feat: add diff-apidocs, an API surface diff tool for the object-reference archive

[irondarrius]

Adds diff-apidocs, a tool that answers "what changed in the public API between version X and Y?" for the 480+ archived .NET version directories, classifying every change as breaking, additive, or cosmetic. Ships as both ports per the dual-port rule. Also includes the 2026 release-chain diffs it produced, and the findings those surfaced.

python diff-apidocs.py -p ironpdf                                  # newest vs previous
node   diff-apidocs.mjs -p ironzip --from 2024.1.1 --to 2026.7.2 --json --markdown
python diff-apidocs.py -p ironword --namespace 'IronWord.Models.*' --fail-on-breaking

Exit codes: 0 success, 1 tool error, 2 breaking changes found with --fail-on-breaking.

How it works

Two committed sources are combined per version, so the tool is entirely offline — no registry calls, no build triggered:

Source	Supplies
xrefmap.yml	member identity — uid, kind, parameter types
api/*.html declarations	modifiers, return types, base classes, default parameter values, accessors
api/*.html Implements section	the interfaces a type implements

Declarations are located by the data-uid DocFX writes on each heading, which is byte-identical to the xrefmap uid. That anchoring is a correctness requirement, not a style choice: Archetype-N injects runnable code samples into the same pages, so a flat lang-csharp scan — the approach in scaffolds/tools/archetype-n/facts.py — reports using IronZip; as a member.

The {PackageName}.xml files inside each nupkg were evaluated and rejected: DocFX takes metadata from the assembly, and the .xml supplies only doc-comment prose with no representation of base types or interfaces. Using it would also have made the tool network-dependent.

Because a uid encodes parameter types, a parameter-type change or a new overload surfaces as a removal plus an addition rather than a modification; the report notes the pairing.

Findings from the 2026 release diffs

Running this across the year turned up four things worth acting on.

1. IronWord 2026.7.1 dropped 21 documented types, including Text, Image, Shape, Style and 13 enums. Verified independently of the tool against the raw archive: 200 → 179 pages, 3865 → 3320 xrefmap entries.

Two of them are a genuine documentation hole rather than a removal — TextAlignment and ShapeType are still used in surviving public signatures (Paragraph.Alignment { get; set; } returns TextAlignment; ShapeContent(ShapeType, RectangleF) takes ShapeType) but no longer have type pages. A consumer cannot look up a type the API requires. Worth raising with the IronWord team.

2. IronQR 2026.1.1 shipped an accidental breaking change. IQrInput and QrImageInput lost IDisposable, restored in 2026.1.2. The cumulative year diff correctly nets to zero — a sum-of-steps tool would have reported 2 breaking for the year. This is the concrete argument for wiring --fail-on-breaking into the release pipeline; it would have caught this pre-release.

3. Iron.Pdf.Extensions publishes obfuscator output to the docs site. The namespace contains only obfuscator-generated types, renamed randomly every build:

2025.12.2	2026.1.3	…	2026.6.1	2026.7.2
auxkyk auxkyl	kjmakb kjmakc	…	bnubqp bnubqq	qdygyt qdygyu

scaffolds/filterConfig.yml gains a uidRegex exclude so future builds stop publishing them, alongside the existing ^IronPdfEngine.Proto$ entries. That only helps builds that pick the change up — the 2026.7 rebuild did not, and every already-archived version still contains them, so the tool carries a matching filter regardless.

4. DocFX's declaration line is not a reliable source for interfaces. Between 2026.6 and 2026.7 it stopped inlining them, while the Implements section stayed byte-identical:

2026.6.2  Implements: System.IDisposable
          decl:       public class IronZipArchive : IronBaseArchive, IDisposable
2026.7.2  Implements: System.IDisposable          <- unchanged
          decl:       public class IronZipArchive : IronBaseArchive

Nothing about the API changed. Read from the declaration this reported 183 breaking changes across 11 products; read from Implements it reports 21, all IronWord's removed types. Interface pages carry no Implements section, so for those an interface-shaped difference is reported as cosmetic with an explicit "unverifiable" note rather than counted as breaking — a deliberate trade against re-reporting a rendering change as ~160 false breakings.

2026 year-to-date, as committed

product	breaking	additive	cosmetic
ironword	189	100	5
ironpdf	25	127	18
ironocr	21	29	6
ironbarcode	0	9	0
irondrawing	0	3	0
ironppt	0	1	0
ironprint	0	1	0
ironqr	0	0	1
ironwebscraper, ironxl, ironzip	0	0	0

85 diffs under docs/api-diffs/<code>/<from>..<to>.{json,md} — one per consecutive 2026 pair plus a cumulative year diff each. docs/ is already excluded from the Jekyll build, so these stay private to the repo.

IronPDF 2026.7.2 is purely additive: 27 new members including PdfDocument.ExtractTextFromLayer(int|string), AddHtmlHeaders/AddHtmlFooters overloads taking ContentOverlapBehavior, and the CssPageRulePolicy / ContentOverlapBehavior enums.

Verification

No test framework or CI exists in this repo, so this follows the documented golden-corpus procedure in docs/api-surface-diff-plan.md. All of it was run and passed.

• 63/63 parity checks — 7 products × 3 version spans × 3 flag combinations, comparing exit codes, stdout, and byte-identical JSON between the two ports.
• Zero unexplained classifications across all 11 products diffed oldest-to-newest; every reported change carries a specific stated reason.
• Determinism — five consecutive identical runs, after fixing a bug where set iteration order let results vary with PYTHONHASHSEED.
• Archetype-N leak guard — asserts no member declaration contains an injected code sample.
• Cross-era parsing back to irondrawing/2022.9.8843 and ironxl/2019.3.2.1.
• Filter completeness — --namespace G and --exclude G summaries sum exactly to the unfiltered summary.
• Performance — ironpdf at 341 pages per version diffs in 0.95 s, which is why there is no cache layer.

Notes for review

• apidiff/ sits at the repo root beside check-apidocs, with both ports in one directory as scaffolds/tools/archetype-n/ does. Nothing was placed under scaffolds/tools/, where .gitattributes would silently make it Git LFS.
• _config.yml excludes apidiff outright, so nothing under it can ever be published.
• apidocs.py / .mjs gain list_archived_versions() and version_sort_key(), shared rather than duplicated. The sorter handles both numbering eras (2019.3.2.1, 2021.9.3650, 2026.7.2) and skips the _archetype-n-samples sibling directory.
• Python is stdlib-only apart from colorama via StatusLogger; Node is dependency-free.
• Known limitation: stdout is compared whitespace-normalised, not byte-for-byte, because statuslogger.py and statuslogger.mjs already differ in spacing — a pre-existing divergence affecting every tool in this repo. It was left alone rather than changing output the devops pipeline may parse. JSON, which this tool fully controls, is byte-identical.
• Unrelated observation, not addressed here: __pycache__/*.pyc files are tracked in the repo despite .gitignore covering them. Worth a standalone cleanup.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EMFBtpbUYSURA6Y911CvFJ