Project Goals¶

The product direction is owned by the repository-root vision.md (rendered here verbatim): abicheck helps library and package maintainers understand and validate API/ABI evolution, grounded in compatibility analysis. This page has two jobs that the vision deliberately does not take on: it names the enduring goals that direction implies, and it keeps the historical milestones — the ABICC-parity programme this project started from — as history. Concrete, in-progress work lives in the implementation plans and the use-case registry, never here.

Enduring goals¶

Goal	What it means in practice	Where the work is tracked
Trusted compatibility verdicts	Binary breaks, source-only breaks, and deployment risks stay separate, with evidence coverage stated and no manufactured findings	Verdicts, Evidence & Detectability, ADR-009/042/064
Visible surface evolution	Additions, removals, and modifications are all first-class, and what policy hid stays auditable	ADR-067, vision workstream plan
Scope-sensitive analysis	One model for one or many components; package and release contracts apply only when selected; partial matrices are never read as removals	ADR-065
Honest evidence	Missing, failed, unsupported, not applicable, and not requested are distinct; weaker evidence narrows conclusions	ADR-028/049/050/063, plan
Project-defined versioning and history	Versioning policy and strictness decide acceptance, never facts; longitudinal tracking over immutable snapshots	ADR-066
CI-first delivery	GitHub Action first, identical semantics through the CLI and typed Python API	ADR-017/047/055, GitHub Action
Honest platform and domain scope	Linux/C/C++ first with SYCL inside C++; Windows/macOS with stated capability; CPython/scientific Python as the next optional provider domain; header-only as intended scope	Platforms, SciPy roadmap, G4/G45

Historical milestones¶

Context, as it stood when the project started: abi-compliance-checker (ABICC) is no longer actively maintained. libabigail is maintained by Red Hat but focuses on DWARF-only binary analysis. abicheck began as a modern Python alternative — drop-in compatible with ABICC first, then better. The six goals below were that programme; their "Done" notes are kept as history and are not the whole vision.

Goal 1 — Drop-In Replacement for ABICC¶

Support everything ABICC currently does so existing users and pipelines can migrate without changes:

Same detection coverage (C/C++ ABI breaks: symbols, types, vtables, enums, layout)
CLI compatible with ABICC inputs (XML descriptors, headers + libs)
JSON/HTML/Markdown reports with equivalent verdict semantics
Support for suppression files

Done: 408 ChangeKinds implemented; YAML suppression files fully supported; ABICC compat CLI supports -symbols-list and -types-list whitelist flags (plain-text, one name per line); XML report generation for ABICC-compatible output; ABICC compat CLI with all major flags; auto-forwarding abicheck compat <flags> to compat check; test parity for ABICC 2.3. Superseded (2026-10): the compat CLI, descriptors and XML reports were removed before 0.6 (ADR-012, retired); detection parity with ABICC is still measured (tests/test_abicc_parity.py).

Goal 2 — Close Known Gaps + Extend¶

Fix known ABICC / libabigail limitations and add new detection capability:

Toolchain/flag drift detection (DW_AT_producer, -fshort-enums, -fpack-struct)
DWARF-aware layout analysis (calling convention, packing, RTTI/visibility boundaries)
Header/API surface diff (AST-based, macro contracts, inline/template changes)
Confidence/evidence tiers in output (ELF_ONLY / DWARF_AWARE / HEADER_AWARE)

Done: DWARF-aware struct/enum layout; calling convention, packing, toolchain flags detection; AST-DWARF deduplication; field qualifiers (const/volatile/mutable); enum/parameter rename heuristics; ELF_ONLY visibility tier used throughout detection; Confidence enum (high/medium/low) on DiffResult with coverage_warnings for disabled detectors (v0.2.0).

Done: Formalized the canonical evidence_tier scalar (ELF_ONLY / DWARF_AWARE / HEADER_AWARE, ordered by analysis depth) in the JSON output schema, alongside the existing raw evidence_tiers list. HEADER_AWARE is now distinct from DWARF_AWARE: the presence of a header/AST surface promotes the tier above DWARF-only debug info. See EvidenceTier in checker_policy.py.

Backlog (MSVC end-to-end hardening): Windows CI includes a non-blocking MSVC + PDB lane, while MinGW/native cross-platform coverage is part of the regular validation story. Promoting the MSVC lane to blocking and broadening its fixture matrix are tracked in docs/contribute/backlog.md.

In progress (scientific-Python direction): the CPython-extension-adjacent gap work (G14 abi3, G23 Python-level API) generalizes toward scientific-Python distributions specifically — compiled Python wheels have compatibility surfaces (Cython capsule APIs, the NumPy C-API, multi-platform wheel deployment claims) that plain native-symbol analysis doesn't see. Scoped as three new planned gaps: G25 (Cython API/ABI frontend), G26 (NumPy C-API compatibility envelope), G27 (wheel tag/deployment-claim verification across Linux/macOS/Windows). See the SciPy / Scientific-Python Roadmap for the full ten-item vision this scoping was drawn from.

Goal 3 — Pass libabigail Test Suite¶

Run abicheck against libabigail's own regression test cases and reach 100% pass rate:

Mirror libabigail's tests/ corpus as integration examples
Add per-case expected verdicts to CI
Use as the compatibility regression gate before each release

Done: ~54 parity test functions across multiple suites (test_abicc_parity, test_abicc_full_parity, test_abidiff_parity, test_xml_parity, test_sprint7/10 parity); 13 new ABI compatibility test cases (cases 42, 49–62); sentinel enum detection; function deletion edge-case hardening (abicc #100).

Goal 4 — Agent-Friendly Design¶

Make the tool convenient for AI agents and automation pipelines:

Structured JSON output (machine-readable, no scraping)
Clear exit codes:
- compare command: 0 = compatible/no_change, 2 = source break, 4 = breaking ABI change
Python API (from abicheck.service import run_compare) — not just CLI
-o json=-/markdown output modes
Snapshot files for offline/async workflows (abicheck dump → .abi.json)

Done: JSON output, snapshot format, exit codes (0/2/4), SARIF 2.1.0 output; GitHub Action (abicheck/abicheck@v0.3.0) for CI; report filtering (--show-only, --report-mode leaf|impact) for CI gate pipelines, plus a -o oneline=- one-line summary (originally reached via a built-in --profile quick, removed outright by ADR-068 D5). (An MCP server for AI-agent integration shipped and was later removed; agent integrations now use the CLI's structured JSON/SARIF output or the typed Python API directly.)

Goal 5 — Compatibility Break Encyclopedia¶

For each break type: what it is, how it appears in the real world, and which tool detects it:

examples/caseXX_*/ — minimal compilable C/C++ examples
Per-case README.md with: scenario → what breaks → which tools detect → severity
Comparison table: abicheck vs abicc vs libabigail vs nm-only
Coverage matrix showing evidence tier required (ELF-only / DWARF / Header / Runtime)

Done: 143 example cases with per-case README.md; the original 74-case subset remains the release-pinned cross-tool benchmark; gap report with coverage matrix (abicheck vs ABICC vs libabigail vs nm); the consolidated ABI/API Compatibility guide plus the generated Examples Encyclopedia; cross-platform CMake build support for all single-library example cases.

Goal 6 — Distribution & Documentation¶

conda-forge package¶

Distribute via conda-forge — conda install -c conda-forge abicheck.

castxml declared as a conda run dependency so users get a working install with zero manual setup.
PyPI remains available (pip install abicheck) for users who prefer pip, with castxml as a documented external prerequisite.
conda-forge recipe auto-updates on each PyPI release via conda-forge bot.

GitHub Pages documentation site¶

Public documentation at https://abicheck.github.io/abicheck/:

Getting started / installation
CLI reference
ABI break catalog (rendered from examples/)
Tool comparison table
Architecture overview

Done: MkDocs (Material theme) site with full navigation; GitHub Actions auto-deploy to GitHub Pages on main push; docs include getting-started, CLI reference, case catalog, tool comparison, SARIF guide, ABICC compat guide, troubleshooting; published to PyPI and conda-forge; Trusted Publishing (OIDC) for PyPI; publish workflow with dry-run mode.

Status summary¶

Goal	Status
G1: ABICC drop-in	Done, then retired — 408 ChangeKinds and suppression files remain; the compat CLI and XML reports were removed before 0.6
G2: Known gaps	DWARF layout, toolchain flags, AST-DWARF dedup, confidence tracking, canonical evidence tier (ELF_ONLY/DWARF_AWARE/HEADER_AWARE) done
G3: libabigail tests	Done — ~54 parity test functions + 143 example cases
G4: Agent-friendly	Done — JSON, SARIF, exit codes, snapshots, typed Python API, GitHub Action (an MCP server shipped and was later removed)
G5: Break encyclopedia	Done — 143 example cases + consolidated ABI/API handling guide + coverage matrix
G6: Distribution & docs	Done — PyPI, conda-forge, MkDocs + GitHub Pages

Non-goals¶

Runtime instrumentation or dynamic analysis — abicheck is a static offline tool.
Source-level refactoring suggestions — it reports what broke, not how to fix your code.
General-purpose analysis of non-native source languages (Rust, Go, Java, …) — out of scope. The one exception: CPython extension modules get a narrow, purpose-built frontend (abicheck/python_api.py, diff_python_api.py; gap G23, docs/contribute/plans/g23-python-level-api-diff.md) that recovers the Python-level API surface (.pyi/signatures) a native extension exposes to import — this is a native-ABI-adjacent contract check, not general Rust/Go/ Java source analysis, and ADR-034 (managed-runtime/non-C frontends) remains a proposal for anything broader.
Static / import library archives (.a, .lib) — currently unsupported input, not a permanent exclusion. abicheck compares single linkable images (shared libraries and objects), not ar member archives; a static library has no runtime ABI surface (no SONAME, no dynamic symbol table), and handing one to dump/compare produces a clear error rather than a misleading result (the G8 decision). Extract members (ar x lib.a) and compare the resulting objects, or the shared library built from them, instead. The vision records a bounded, lower-priority investigation into which archive questions can honestly be answered (relinking precompiled objects versus a full rebuild, thin archives, LTO members, import libraries versus static libraries) — tracked in the vision workstream plan; nothing about archive acceptance changes until that investigation reaches a separately scoped decision. See limitations.