mirror of
https://github.com/nlohmann/json.git
synced 2026-07-12 05:25:09 +00:00
Add AST-based public API checker and fix documentation gaps it found (#3691)
Adds tools/api_checker/: extract_api.py derives the public API surface directly from the libclang AST (independent of documentation status), check_docs.py flags public entries missing @sa links (and @sa on non-public ones), diff_api.py does an overload-aware breaking/feature diff between two refs, check_macros.py cross- checks documented macros against #define sites, and snapshot_release.py backfills immutable per-release surface snapshots into tools/api_checker/history/ (v3.1.0 through v3.12.0) so diff_api.py can compare releases without live extraction. POLICY.md documents what counts as public API and what stability is guaranteed. Running this tooling against the current tree found and fixed a real documentation backlog: ~25 new API doc pages (ordered_map's methods, json_sax's ctor/dtor/ operator=, byte_container_with_subtype's comparison operators, several orphaned type aliases), each with a compiled and output-verified example, plus missing @sa comments and stale/incorrect Version History entries on several existing pages (found by diffing consecutive release pairs and checking whether the resulting change was actually reflected in the target page's history section). Also adds docs/home/api_changes.md, a per-release, per-function reference of public API changes (v3.1.0 through v3.12.0) generated from the history/ snapshots, complementing (not replacing) the existing release notes. Along the way, found and fixed several extractor bugs by testing against real release tags rather than trusting the algorithm in isolation -- most notably an identity-key scheme based on libclang's USR that encoded the enclosing class template's own arity, and a since-renamed ABI inline-namespace pattern (json_v3_11_0 vs. today's json_abi_v3_11_2) that neither of two earlier regex attempts stripped correctly. Both are documented in extract_api.py's docstrings and tools/api_checker/history/README.md so the failure mode doesn't recur silently. .github/workflows/check_api_docs.yml runs extract_api.py + check_docs.py in CI, advisory-only for now (documented backlog may not be at zero for entities this PR didn't touch), plus a blocking drift check on the committed tools/api_checker/api_surface.json. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
@@ -0,0 +1,127 @@
|
||||
# Public API Policy
|
||||
|
||||
This document defines what counts as the **public API** of nlohmann/json for the purposes of the
|
||||
`tools/api_checker/` tooling, what stability is (and is not) guaranteed, and how API changes are
|
||||
classified as breaking or feature additions. It exists so that "public API" is a checkable, mechanical
|
||||
property of the source, not a matter of convention or memory — see
|
||||
[Discussion #3691](https://github.com/nlohmann/json/discussions/3691) for the original motivation.
|
||||
|
||||
## What counts as public API
|
||||
|
||||
The public API surface is derived from C++ semantics (class templates, access specifiers, namespace
|
||||
scoping) by `extract_api.py`, not from the presence of documentation. It consists of:
|
||||
|
||||
1. **Public members of six class templates**: `basic_json`, `adl_serializer`,
|
||||
`byte_container_with_subtype`, `json_pointer`, `json_sax`, `ordered_map`. Specifically, the *primary
|
||||
template definition* (`CLASS_TEMPLATE` cursor with `is_definition() == True`) — never an implicit
|
||||
instantiation, which silently drops SFINAE-guarded overloads. Two tiers apply:
|
||||
- **Callable tier** (methods, constructors, destructors, conversion operators, function templates):
|
||||
every public callable requires its own `@sa` documentation link, without exception.
|
||||
- **Type tier** (public type aliases): requires `@sa`, except for a fixed exemption list of
|
||||
STL-container named-requirement aliases that mirror standard-library conventions rather than being
|
||||
independently documented: `value_type`, `reference`, `const_reference`, `pointer`, `const_pointer`,
|
||||
`iterator`, `const_iterator`, `reverse_iterator`, `const_reverse_iterator`, `difference_type`,
|
||||
`size_type`, `allocator_type`, `key_type`, `mapped_type`. This list is defined once, in
|
||||
`extract_api.py`'s `stl_exempt` set, and referenced here rather than duplicated.
|
||||
2. **Free functions and operators in `nlohmann::`**, including `nlohmann::literals::json_literals`
|
||||
(the `operator""_json` / `operator""_json_pointer` user-defined literals). Comparison and stream
|
||||
operators on `basic_json` and `json_pointer`, `operator/`, `swap`.
|
||||
3. **The six alias-exposed exception types**: `basic_json::exception`, `parse_error`,
|
||||
`invalid_iterator`, `type_error`, `out_of_range`, `other_error`. These are public `TYPE_ALIAS_DECL`s
|
||||
in `basic_json` (e.g. `using exception = detail::exception;`) whose underlying class is physically
|
||||
defined in `nlohmann::detail::exceptions.hpp`. `extract_api.py` follows the alias to find the `@sa` on
|
||||
the underlying `detail::` class definition, since that's where the existing documentation convention
|
||||
places it. Each exception class is documented as *one page* — its individual members (`what()`, `id`)
|
||||
are not separately tracked, matching the existing one-page-per-class convention.
|
||||
4. **Macros**, governed separately by `docs/mkdocs/docs/api/macros/` (the curated list of ~30 pages is
|
||||
authoritative) and cross-checked, advisory-only, by `check_macros.py`. See "Known limitations" below
|
||||
for why macros can't be checked the same way as everything else.
|
||||
|
||||
## What's excluded
|
||||
|
||||
- **Everything in `nlohmann::detail::`**, with the one narrow exception above (exception-type aliases).
|
||||
**No stability is guaranteed for any symbol in the `detail::` namespace — clients must not rely on it**,
|
||||
regardless of whether a given `detail::` symbol happens to be reachable from user code today. This is
|
||||
an explicit, deliberate policy, not an oversight.
|
||||
- **Private and protected members**, even of the six tracked classes. `extract_api.py` walks non-public
|
||||
members only to check they don't carry a stray `@sa` (a documentation leak) — never to add them to the
|
||||
public surface.
|
||||
- **The ABI inline-namespace segment** (`json_abi_v3_12_0`, `json_abi_diag_v3_12_0`, etc. — see
|
||||
[docs/mkdocs/docs/features/namespace.md](../../docs/mkdocs/docs/features/namespace.md)). This is a
|
||||
version-tag identity concern for `diff_api.py` (it must not make every release look like the entire API
|
||||
was removed and re-added), not a scoping or visibility concern — the symbols inside it are public or
|
||||
not independent of the tag.
|
||||
|
||||
## Breaking vs. feature classification
|
||||
|
||||
`diff_api.py` compares the `public_api` surface of two snapshots using an overload-disambiguating
|
||||
identity — `(scope, identity_name, kind, signature)`, where `signature` is the declaration's own
|
||||
source text (return type, name, parameter list, trailing qualifiers; comments and constructors'
|
||||
member-initializer-lists stripped). This is the third identity scheme this tooling has used; the
|
||||
first two were each found broken by testing against real release tags, not by inspection — see
|
||||
`extract_api.py`'s `identity_key()` docstring for the full history (a naive params-only key silently
|
||||
collided on overloads differing only by constness/SFINAE; libclang's USR fixed that but encoded the
|
||||
*enclosing class template's own arity*, so a single backward-compatible template-parameter addition
|
||||
made ~228 of 330 `basic_json` entries look "changed" between two real releases with zero actual
|
||||
breaking changes among them).
|
||||
|
||||
- An identity present only in the **new** snapshot → **feature** (addition).
|
||||
- An identity present only in the **old** snapshot → **breaking** (removal).
|
||||
- The same `(scope, name)` with one identity removed and a different one added → reported as a
|
||||
**changed overload**, classified breaking by default. No automatic overload-compatibility reasoning
|
||||
is attempted — whether a signature change is source-compatible is a judgment call for a human
|
||||
reviewer, not a sound problem for a CI tool to solve unsupervised.
|
||||
|
||||
## Stable per-release API history
|
||||
|
||||
`tools/api_checker/history/<tag>.json` holds one immutable, committed API-surface record per
|
||||
released `v3.*` tag (captured via `snapshot_release.py`; see `tools/api_checker/README.md` and
|
||||
`tools/api_checker/history/README.md`). `diff_api.py` reads from here automatically when a ref
|
||||
matches a stored file, instead of live-extracting via `git archive` every time.
|
||||
|
||||
Every surface file (the live `api_surface.json` and every `history/*.json` record) carries a
|
||||
`format_version` integer. **Bump it whenever a change to the schema, or to the identity-computing
|
||||
algorithm (`get_signature_text()`/`get_identity_name()`/`identity_key()` in `extract_api.py`), could
|
||||
alter the `signature` or `identity_name` text for otherwise-unchanged source.** `diff_api.py` refuses
|
||||
by default to compare two surfaces with different `format_version` values — this is a direct,
|
||||
mechanical safeguard against the exact class of bug that motivated the current identity scheme (see
|
||||
above): a silent algorithm change corrupting every historical comparison with no way to detect it.
|
||||
An explicit `--allow-format-mismatch` flag exists for a deliberate, informed comparison anyway.
|
||||
|
||||
Practical implication for anyone changing `extract_api.py`'s identity logic: bump
|
||||
`SURFACE_FORMAT_VERSION`, and treat every already-committed `history/*.json` file as needing a
|
||||
`--force` regeneration (reviewed, not blind) before it can be meaningfully compared against surfaces
|
||||
produced by the new algorithm version.
|
||||
|
||||
## Stability guarantees
|
||||
|
||||
This tooling makes the project's existing commitments *mechanically checkable* — it does not introduce a
|
||||
new promise:
|
||||
|
||||
- `ChangeLog.md` states the project "adheres to [Semantic Versioning](http://semver.org/)."
|
||||
- [docs/mkdocs/docs/home/releases.md](../../docs/mkdocs/docs/home/releases.md) marks every 3.x release "All
|
||||
changes are backward-compatible" (except 3.0.0 itself, a major bump with a migration guide).
|
||||
- `tests/abi/` provides a complementary, narrower guarantee: ABI/link compatibility *within one ABI tag*.
|
||||
That is a binary-compatibility concern; this tooling's concern is source/API-level — a symbol can be
|
||||
ABI-stable and still be a source-breaking change (e.g. a removed overload), or vice versa.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- **Macros have no C++ access-specifier concept**, so the public/private test that works for classes
|
||||
doesn't transfer. Only a minority of documented macro `#define`s have an attached `@sa`-style comment
|
||||
(the `#ifndef X / #define X value #endif` idiom has no natural comment-attachment point), and internal
|
||||
helper macros live in the same files as public configuration macros, so no path-based exclusion works
|
||||
either. `check_macros.py` therefore only checks one direction: that every documented macro still has a
|
||||
matching `#define` somewhere under `include/nlohmann/` (catches stale/renamed doc pages). It does
|
||||
**not** attempt to detect undocumented macros — no reliable signal exists for that direction with the
|
||||
current codebase conventions, and this tool doesn't pretend otherwise.
|
||||
- **`diff_api.py` does not track exception specifications or template-parameter-only changes.** A
|
||||
function whose `noexcept` status changes, or whose template parameter list changes without altering
|
||||
its externally-visible identity, will not be flagged.
|
||||
- **Known API-hygiene gap, surfaced by this tooling rather than fixed**:
|
||||
`basic_json::insert_iterator` (a `public` member per C++ access rules) is a helper used internally by
|
||||
`insert()`; its own source comment calls it "Helper for insertion of an iterator." It has no
|
||||
documentation page and is deliberately left undocumented rather than either speculatively documented or
|
||||
silently exempted — this is exactly the class of undocumented-and-probably-shouldn't-be-public symbol
|
||||
this tooling exists to surface, per the motivating discussion. A future PR may reclassify it as private
|
||||
as a (breaking, ABI-relevant) cleanup; that is out of scope here.
|
||||
@@ -0,0 +1,392 @@
|
||||
# API Checker Tools
|
||||
|
||||
Tooling to extract, validate, and track changes to the public API surface of nlohmann/json.
|
||||
|
||||
## Overview
|
||||
|
||||
These tools use libclang AST parsing to programmatically derive "the public API" from C++ semantics
|
||||
(class templates, access specifiers, namespace scoping) — independently of documentation status. The
|
||||
extracted surface is the source of truth for what is considered "public API." On top of this, the tools
|
||||
verify that every public entity carries a documentation link and detect API changes between releases.
|
||||
A per-release historical record lives in [`history/`](history/README.md), one file per tagged `v3.*`
|
||||
release, so past API changes can be derived without re-running libclang against old git refs.
|
||||
|
||||
See [POLICY.md](POLICY.md) for the full definition of what counts as public API, what's excluded, how
|
||||
breaking vs. feature changes are classified, and known limitations.
|
||||
|
||||
## Installation
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
pip install -r tools/api_checker/requirements.txt
|
||||
```
|
||||
|
||||
Requires:
|
||||
- Python 3.7+
|
||||
- libclang 18.1.1 (installed via pip)
|
||||
- clang++ or clang (system package, for include-path discovery only — does not need to
|
||||
version-match the pinned libclang wheel)
|
||||
|
||||
## Tools
|
||||
|
||||
### extract_api.py
|
||||
|
||||
Extract the public API surface by parsing C++ AST using libclang. Produces two different outputs for
|
||||
two different consumers — see "Two outputs, one extraction pass" below for why.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python3 tools/api_checker/extract_api.py \
|
||||
--header include/nlohmann/json.hpp \
|
||||
--include include \
|
||||
--output api_snapshot.json \
|
||||
--surface-output api_surface.json
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--header PATH` — Header file to analyze (default: `include/nlohmann/json.hpp`)
|
||||
- `--include PATH` — Include directory for parsing (default: `include`)
|
||||
- `--output PATH` — Full snapshot output (location + doc status; default: `api_snapshot.json`)
|
||||
- `--surface-output PATH` — Minimal surface output (identity only; omit to skip)
|
||||
- `--extra-isystem PATH` — Extra `-isystem` include path (repeatable), in case system-include
|
||||
discovery via `clang++ -E -v` ever fails on a given runner image
|
||||
- `--self-test` — Run self-tests and exit (validates ABI-tag stripping)
|
||||
|
||||
**How it works:**
|
||||
Parses the header file using libclang with `PARSE_DETAILED_PROCESSING_RECORD`, discovers system
|
||||
includes via `clang++ -E -x c++ -v /dev/null`, and walks the AST:
|
||||
|
||||
1. For each of the 6 public class templates (`basic_json`, `adl_serializer`, `byte_container_with_subtype`,
|
||||
`json_pointer`, `json_sax`, `ordered_map`): locate the `CLASS_TEMPLATE` cursor with `is_definition() == True`
|
||||
— never a `CLASS_DECL` implicit instantiation, which silently drops SFINAE-guarded overloads
|
||||
2. Extract public members: `CXX_METHOD`, `CONSTRUCTOR`, `DESTRUCTOR`, `CONVERSION_FUNCTION`, `FUNCTION_TEMPLATE`
|
||||
(callable tier — strict `@sa` requirement), and `TYPE_ALIAS_DECL` (type tier — with STL-container exemptions)
|
||||
3. Extract free functions in `nlohmann::` namespace (excluding `detail::` and `std::`)
|
||||
4. Normalize away ABI inline-namespace (regex `::json_abi[a-z_]*_v\d+_\d+_\d+` → `::`)
|
||||
5. Use overload-disambiguating identity keys built from raw source-text signature capture,
|
||||
ABI-tag-stripped — see "Identity keys" below
|
||||
|
||||
**Two outputs, one extraction pass:**
|
||||
- `--output` (full snapshot): each entry carries `location` (file:line) and documentation status
|
||||
(`doc_url`, `has_sa`). Consumed by `check_docs.py`. **Not meant to be committed** — `location` shifts
|
||||
on any unrelated code edit and `doc_url` changes when doc pages move, so a diff of this file mixes real
|
||||
API changes with pure noise.
|
||||
- `--surface-output` (minimal surface): each entry has only `scope`, `kind`, `name`, `identity_name`,
|
||||
`tier`, `signature`, and `pretty_signature` — nothing that can change without the API itself changing.
|
||||
**This is the file that gets committed** (`tools/api_checker/api_surface.json` for the current
|
||||
working tree, `tools/api_checker/history/<tag>.json` per released tag) and diffed by `diff_api.py`.
|
||||
|
||||
**Identity keys — three approaches were tried and rejected before arriving at the current one:**
|
||||
1. `{scope, name, kind, params}` from `cursor.get_arguments()`: silently collided for any overload set
|
||||
differentiated only by constness, ref-qualifiers, or SFINAE constraints rather than parameter types —
|
||||
confirmed empirically: `basic_json`'s two zero-argument `get()` overloads (one `const`, one not) both
|
||||
produced `params=[]` and silently overwrote each other. A full scan found **59 such silent overwrites
|
||||
across 27 colliding names**.
|
||||
2. libclang's USR: correctly disambiguates every overload (it encodes the full mangled signature) — but
|
||||
*also* encodes the enclosing class template's own arity into every member's USR. Confirmed
|
||||
empirically against real release tags: `basic_json` gaining one new defaulted template parameter
|
||||
between v3.11.2 and v3.11.3 (a backward-compatible change) changed literally every member's USR,
|
||||
which made `diff_api.py` report **228 of 330 entries as "changed"** for a release with zero real
|
||||
breaking changes among them.
|
||||
3. **Current approach**: raw source-text signature capture — `identity = (scope, identity_name, kind,
|
||||
signature)`, where `signature` is the declaration's own text (return type, name, parameter list,
|
||||
trailing cv/ref/noexcept qualifiers; comments and constructors' member-initializer-lists stripped;
|
||||
stops before the function body) read directly via the cursor's byte-offset extent. This is what's
|
||||
actually written in source — declared names like `ValueType`, never a resolved
|
||||
`basic_json<T0,...,T10>` — so it's immune to the class-arity problem above. Verified by manually
|
||||
cross-referencing every "added"/"removed"/"changed" entry in three real release-to-release diffs
|
||||
(v3.11.2→v3.11.3, v3.11.3→v3.12.0, v3.12.0→HEAD) against the actual `git diff` of the source — every
|
||||
one confirmed genuine. Full details, including several further edge-case fixes found the same way
|
||||
(a libclang tokenizer gap, comment-stripping, constructor-name arity-poisoning), are in
|
||||
`extract_api.py`'s `identity_key()`/`get_signature_text()` docstrings.
|
||||
|
||||
**Output (full snapshot, from `--output`):**
|
||||
```json
|
||||
{
|
||||
"meta": {
|
||||
"extracted_from": "include/nlohmann/json.hpp"
|
||||
},
|
||||
"public_api": {
|
||||
"<opaque internal key, not meant to be read>": {
|
||||
"scope": "nlohmann::basic_json",
|
||||
"name": "parse",
|
||||
"identity_name": "parse",
|
||||
"kind": "CXX_METHOD",
|
||||
"tier": "callable",
|
||||
"signature": "static basic_json parse ( InputType && i , ... )",
|
||||
"location": "include/nlohmann/json.hpp:4104",
|
||||
"doc_url": "https://json.nlohmann.me/api/basic_json/parse/",
|
||||
"has_sa": true,
|
||||
"pretty_signature": "nlohmann::basic_json::parse"
|
||||
}
|
||||
},
|
||||
"documented_non_public": []
|
||||
}
|
||||
```
|
||||
|
||||
`documented_non_public` lists entities **not** part of the public surface (private/protected members of
|
||||
the six tracked classes) that surprisingly carry a real `@sa` URL — a genuine documentation leak. It does
|
||||
not list public entries that merely lack `@sa`; that's `check_docs.py`'s job.
|
||||
|
||||
**Output (surface, from `--surface-output`):**
|
||||
```json
|
||||
{
|
||||
"format_version": 1,
|
||||
"meta": {
|
||||
"extracted_from": "include/nlohmann/json.hpp"
|
||||
},
|
||||
"public_api": [
|
||||
{
|
||||
"scope": "nlohmann::basic_json",
|
||||
"kind": "CXX_METHOD",
|
||||
"name": "parse",
|
||||
"identity_name": "parse",
|
||||
"tier": "callable",
|
||||
"signature": "static basic_json parse ( InputType && i , parser_callback_t cb = nullptr , const bool allow_exceptions = true , const bool ignore_comments = false )",
|
||||
"pretty_signature": "nlohmann::basic_json::parse"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
A flat, sorted list of self-describing records — `signature`/`identity_name` are the same values
|
||||
`identity_key()` joins into one opaque internal string, exposed here as explicit fields so the file is
|
||||
readable and diffable by inspection, not just by tooling. `identity_name` differs from `name` only for
|
||||
constructors/destructors (a canonical `"(constructor)"`/`"(destructor)"` placeholder — see
|
||||
`get_identity_name()`'s docstring for why `cursor.spelling` isn't used directly there).
|
||||
|
||||
`format_version` guards against a future change to this schema or to the identity-computing algorithm
|
||||
silently corrupting a comparison against an older stored surface — bump it whenever such a change could
|
||||
alter `signature`/`identity_name` text for otherwise-unchanged source (see `diff_api.py`).
|
||||
|
||||
### check_docs.py
|
||||
|
||||
Verify that all public API entries have valid documentation links and that no non-public entities
|
||||
carry `@sa` comments.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python3 tools/api_checker/check_docs.py --snapshot api_snapshot.json
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--snapshot PATH` — Full API snapshot JSON file from `extract_api.py --output` (default: `api_snapshot.json`)
|
||||
|
||||
**How it works:**
|
||||
Two-pass validation over the extracted snapshot:
|
||||
|
||||
1. For every `public_api` entry (callable tier, and type tier minus STL exemptions): flag if missing `@sa`,
|
||||
flag if `@sa` URL doesn't resolve to an existing documentation file (following `docs/mkdocs/mkdocs.yml`'s
|
||||
`redirect_maps` when a page has moved, and trying the class-overview conventions used by different
|
||||
classes — flat `<class>.md`, nested `<class>/<class>.md`, nested `<class>/index.md`)
|
||||
2. For every `documented_non_public` entry: flag as unexpected `@sa` on a non-public entity
|
||||
|
||||
**Output:**
|
||||
Prints warnings for each issue, categorized by rule:
|
||||
- `docs/missing_sa_comment` — public API without `@sa` documentation link
|
||||
- `docs/missing_doc_file` — `@sa` URL points to non-existent `.md` file
|
||||
- `docs/invalid_sa_url` — malformed `@sa` URL
|
||||
- `docs/sa_on_non_public` — unexpected `@sa` on a non-public entity
|
||||
|
||||
Exits with status 0 if all checks pass, 1 if issues found.
|
||||
|
||||
### diff_api.py
|
||||
|
||||
Compare the public API surface between two refs and classify changes as feature (added) or
|
||||
breaking (removed / changed overload).
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python3 tools/api_checker/diff_api.py --old v3.12.0 --new HEAD
|
||||
python3 tools/api_checker/diff_api.py --old v3.11.2 --new v3.11.3 # both resolved from history/
|
||||
python3 tools/api_checker/diff_api.py --old v3.12.0 --new HEAD --fail-on-breaking
|
||||
python3 tools/api_checker/diff_api.py --old-file a.json --new-file b.json # compare two files directly
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--old REF` / `--new REF` — Refs to compare (tags, branches, commits). `--new` defaults to `HEAD`.
|
||||
Each is resolved by checking `tools/api_checker/history/<ref>.json` first (fast — no libclang or
|
||||
git-archive needed), falling back to live extraction if no matching file exists there.
|
||||
- `--old-file PATH` / `--new-file PATH` — Load an arbitrary surface JSON file directly, bypassing
|
||||
both git and `tools/api_checker/history/`. Mutually exclusive with `--old`/`--new` respectively.
|
||||
- `--no-history` — Force live extraction even when a matching `tools/api_checker/history/<ref>.json`
|
||||
exists. Useful to check that a stored record is still faithful to a fresh run of the current tool.
|
||||
- `--allow-format-mismatch` — Proceed even if the two surfaces have different `format_version`
|
||||
(otherwise `diff_api.py` refuses — see below).
|
||||
- `--header PATH` / `--include PATH` — For live extraction only (default:
|
||||
`include/nlohmann/json.hpp` / `include`)
|
||||
- `--fail-on-breaking` — Exit with status 1 if breaking changes are detected
|
||||
|
||||
**How it works:**
|
||||
For a ref not found in `tools/api_checker/history/`, checks out the **full `include/` tree** at
|
||||
that ref into a temp directory via `git archive` (a single-file checkout of `json.hpp` is not
|
||||
enough — it `#include`s dozens of other headers that must exist at the same ref), then runs the
|
||||
*current* `extract_api.py --surface-output` against it. Diffs the two surfaces by identity
|
||||
(`scope`, `identity_name`, `kind`, `signature`):
|
||||
- Identity only in the new surface → **feature**.
|
||||
- Identity only in the old surface → **breaking** (removed).
|
||||
- Same `(scope, name)` with a removed identity and an added identity → grouped as a **changed
|
||||
overload**, breaking by default. No automatic overload-compatibility reasoning is attempted — a
|
||||
human judges whether the change is actually source-compatible.
|
||||
|
||||
Before diffing, the two surfaces' `format_version` fields are compared; a mismatch aborts with an
|
||||
error (override with `--allow-format-mismatch`) rather than silently producing an unsound diff — see
|
||||
`extract_api.py`'s `SURFACE_FORMAT_VERSION` docstring for the incident that motivated this guard.
|
||||
|
||||
ABI-tag stripping is inherited automatically since both extractions go through the same
|
||||
`extract_api.py`.
|
||||
|
||||
**Use case:** Run before cutting a release to verify the changelog correctly categorizes changes as
|
||||
breaking vs. features.
|
||||
|
||||
### snapshot_release.py
|
||||
|
||||
Capture an immutable, per-release API surface record into `tools/api_checker/history/<tag>.json`.
|
||||
This is what makes `diff_api.py` fast for released tags — see "How it works" above.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python3 tools/api_checker/snapshot_release.py --ref v3.12.0
|
||||
python3 tools/api_checker/snapshot_release.py --ref v3.11.0 --ref v3.12.0 # repeatable
|
||||
python3 tools/api_checker/snapshot_release.py --all-tags # every v3.* tag
|
||||
python3 tools/api_checker/snapshot_release.py --ref v3.12.0 --force # overwrite an existing record
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--ref REF` — Git tag to snapshot; repeatable
|
||||
- `--all-tags` — Snapshot every `v3.*` tag (existing files are skipped unless `--force`)
|
||||
- `--output-dir PATH` — Where to write (default: `tools/api_checker/history/`)
|
||||
- `--force` — Overwrite an existing history file. History files are immutable by convention —
|
||||
only pass this for a deliberate, reviewed regeneration; review the resulting diff before
|
||||
committing
|
||||
- `--header PATH` / `--include PATH` — Same as `diff_api.py`'s live-extraction options
|
||||
|
||||
**How it works:** Reuses `diff_api.py`'s `extract_surface_for_ref()` for the git-archive-and-extract
|
||||
work, then adds `generated_at`/`generator` provenance and writes the result to
|
||||
`tools/api_checker/history/<ref>.json`. Given multiple refs (or `--all-tags`), does **not** abort
|
||||
the batch on one failing ref — collects failures and prints a summary at the end, so one
|
||||
unparseable old tag doesn't block backfilling the releases that do work. See
|
||||
`tools/api_checker/history/README.md` for the currently-known gaps (pre-restructuring tags that
|
||||
predate the `include/nlohmann/` layout entirely).
|
||||
|
||||
**Not CI-automated** — this is a manual step in the release checklist (see below), by design.
|
||||
|
||||
### check_macros.py
|
||||
|
||||
Advisory-only cross-check between documented macros and their `#define`/reference sites. **Never blocks
|
||||
CI**, regardless of findings.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python3 tools/api_checker/check_macros.py
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--macros-dir PATH` — Directory of macro doc pages (default: `docs/mkdocs/docs/api/macros`)
|
||||
- `--include-dir PATH` — Directory to search for `#define`/reference sites (default: `include/nlohmann`)
|
||||
|
||||
**How it works:**
|
||||
For each `.md` page under `docs/mkdocs/docs/api/macros/` (excluding `index.md`), extracts the macro
|
||||
name(s) from the H1 heading — handling both plain single-macro headings and multi-line HTML headings
|
||||
that list a family of related macros (e.g. the `NLOHMANN_DEFINE_DERIVED_TYPE_*` family) — then checks
|
||||
whether each name is defined **or referenced** (`#define`, `#ifdef`, `#ifndef`, `defined(...)`) anywhere
|
||||
under `include/nlohmann/`. Referenced-but-not-defined is deliberately accepted: macros like
|
||||
`JSON_NOEXCEPTION` or `JSON_THROW_USER` are user-supplied overrides that the library only checks for,
|
||||
never defines itself.
|
||||
|
||||
Only checks the documented-macro-still-exists direction (catches stale/renamed doc pages). Does **not**
|
||||
check the converse (undocumented macros) — see [POLICY.md](POLICY.md)'s "Known limitations" for why.
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
A GitHub Actions workflow (`.github/workflows/check_api_docs.yml`) runs on every pull request:
|
||||
|
||||
1. Installs `clang` (system package, for include discovery) and Python dependencies
|
||||
2. Runs `extract_api.py`, regenerating both the ephemeral full snapshot and the tracked
|
||||
`tools/api_checker/api_surface.json`
|
||||
3. Runs `check_docs.py` — **Phase 1: advisory** (`continue-on-error: true`), surfacing the doc backlog
|
||||
without failing the job while it's burned down. Will flip to blocking once the backlog is cleared.
|
||||
4. Runs `check_macros.py` — always advisory
|
||||
5. Diffs `tools/api_checker/api_surface.json` against the regenerated copy — **blocking from the start**
|
||||
(unlike the doc-backlog check, this is purely mechanical regeneration with no backlog to phase in,
|
||||
matching the precedent set by `check_amalgamation.yml`). Uploads a patch artifact if it differs, so
|
||||
contributors can `git apply` it instead of installing libclang locally.
|
||||
|
||||
## Workflow: Adding New Public API
|
||||
|
||||
1. Add the new public method/function to the header
|
||||
2. Add a `/// @sa https://json.nlohmann.me/api/<class>/<member>/` comment above it
|
||||
3. Create the corresponding documentation page at `docs/mkdocs/docs/api/<class>/<member>.md` and a
|
||||
`mkdocs.yml` nav entry
|
||||
4. Regenerate and commit the tracked surface file:
|
||||
```bash
|
||||
python3 tools/api_checker/extract_api.py --surface-output tools/api_checker/api_surface.json
|
||||
git add tools/api_checker/api_surface.json
|
||||
```
|
||||
5. Push your PR — CI verifies both the doc link and that the surface file is up to date
|
||||
|
||||
## Workflow: Release Checklist
|
||||
|
||||
Before cutting a release:
|
||||
|
||||
```bash
|
||||
# Diff current API against the previous release
|
||||
python3 tools/api_checker/diff_api.py --old v3.12.0 --new HEAD
|
||||
|
||||
# Review the output to verify the changelog correctly categorizes breaking vs. feature changes
|
||||
```
|
||||
|
||||
After tagging the release:
|
||||
|
||||
```bash
|
||||
# Capture and commit the new tag's API surface, so future diffs against it hit the fast,
|
||||
# stored-file path instead of live-extracting every time. A manual step, not CI-automated.
|
||||
python3 tools/api_checker/snapshot_release.py --ref v3.13.0
|
||||
git add tools/api_checker/history/v3.13.0.json
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**libclang not found:**
|
||||
```
|
||||
Error: Could not locate libclang library
|
||||
```
|
||||
→ Ensure libclang is installed: `python3 -m pip install libclang==18.1.1`
|
||||
|
||||
**Parse errors in header:**
|
||||
```
|
||||
Parse errors encountered:
|
||||
... list of diagnostics ...
|
||||
```
|
||||
→ Check that system includes can be discovered. Run `clang++ -E -x c++ -v /dev/null` and verify
|
||||
the output includes a section titled `#include <...> search starts here:` with system paths.
|
||||
If include discovery fails, use `--extra-isystem PATH` to provide additional paths.
|
||||
|
||||
**No API entries extracted (or very few):**
|
||||
- Check that the header file exists and is valid C++: `ls -la include/nlohmann/json.hpp`
|
||||
- Verify that no parse errors occur above
|
||||
- Confirm that you're targeting a `CLASS_TEMPLATE` definition, not an implicit instantiation
|
||||
(the tool logs `Found N public API entries` — a zero or very small count suggests the wrong cursor kind)
|
||||
|
||||
**Doc link returns 404:**
|
||||
- Verify the file exists at the expected path: `docs/mkdocs/docs/api/<class>/<member>.md`
|
||||
- Check for URL encoding issues (e.g., `operator[]` → `operator%5B%5D`)
|
||||
- Verify the URL structure in the `@sa` comment: should be `https://json.nlohmann.me/api/<path>/`
|
||||
- Check `docs/mkdocs/mkdocs.yml`'s `redirect_maps` if the page has moved
|
||||
|
||||
**`tools/api_checker/api_surface.json` is out of date in CI:**
|
||||
→ Regenerate and commit it: `python3 tools/api_checker/extract_api.py --surface-output tools/api_checker/api_surface.json`
|
||||
|
||||
**`diff_api.py` refuses with "format_version mismatch":**
|
||||
→ One side is a stored surface (live `api_surface.json` or a `tools/api_checker/history/*.json`
|
||||
file) captured with an older/newer version of `extract_api.py`'s identity-computing algorithm than
|
||||
the other side. Comparing them directly could produce an unsound diff (this is exactly the failure
|
||||
mode that motivated adding the check — see `extract_api.py`'s `SURFACE_FORMAT_VERSION` docstring).
|
||||
Either regenerate the older side with the current tool, or pass `--allow-format-mismatch` if you
|
||||
understand the risk and want to proceed anyway.
|
||||
|
||||
## Contributing
|
||||
|
||||
Report bugs or suggest improvements to [Discussion #3691](https://github.com/nlohmann/json/discussions/3691).
|
||||
Read [POLICY.md](POLICY.md) first for the definition of public API this tooling enforces.
|
||||
File diff suppressed because it is too large
Load Diff
Executable
+183
@@ -0,0 +1,183 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Verify that public API entries have documentation links.
|
||||
|
||||
Consumes an API snapshot from extract_api.py and checks:
|
||||
1. Every public callable/type-tier entry has an @sa comment (with exceptions)
|
||||
2. Every @sa URL resolves to an existing documentation file
|
||||
3. No @sa comments appear on non-public entities
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from urllib.parse import unquote
|
||||
|
||||
warnings = 0
|
||||
|
||||
# STL-container-named-requirement aliases that are exempt from @sa requirement
|
||||
STL_EXEMPT = {'value_type', 'reference', 'const_reference', 'pointer', 'const_pointer',
|
||||
'iterator', 'const_iterator', 'reverse_iterator', 'const_reverse_iterator',
|
||||
'difference_type', 'size_type', 'allocator_type', 'key_type', 'mapped_type'}
|
||||
|
||||
|
||||
def get_repo_root():
|
||||
"""Find the repository root via git, so this script works regardless of invoking CWD."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
['git', 'rev-parse', '--show-toplevel'],
|
||||
capture_output=True, text=True, check=True, timeout=10
|
||||
)
|
||||
return result.stdout.strip()
|
||||
except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
|
||||
return os.getcwd()
|
||||
|
||||
|
||||
REPO_ROOT = get_repo_root()
|
||||
MKDOCS_YML = os.path.join(REPO_ROOT, 'docs', 'mkdocs', 'mkdocs.yml')
|
||||
|
||||
|
||||
def load_redirect_map() -> dict:
|
||||
"""Parse the redirect_maps block of docs/mkdocs/mkdocs.yml: {old_relative_path: new_relative_path}.
|
||||
|
||||
mkdocs' redirect plugin lets a doc page move without breaking existing @sa URLs -- e.g.
|
||||
'api/basic_json/operator_ltlt.md' redirects to the real file at 'api/operator_ltlt.md'.
|
||||
Without consulting this map, url_to_docfile() would flag every redirected URL as a broken link.
|
||||
"""
|
||||
if not os.path.exists(MKDOCS_YML):
|
||||
return {}
|
||||
with open(MKDOCS_YML) as f:
|
||||
content = f.read()
|
||||
redirect_map = {}
|
||||
for m in re.finditer(r"^\s*'([^']+\.md)':\s*(\S+\.md)\s*$", content, re.MULTILINE):
|
||||
redirect_map[m.group(1)] = m.group(2)
|
||||
return redirect_map
|
||||
|
||||
|
||||
REDIRECT_MAP = load_redirect_map()
|
||||
|
||||
|
||||
def report(rule: str, location: str, description: str):
|
||||
"""Report a documentation issue."""
|
||||
global warnings
|
||||
warnings += 1
|
||||
print(f'{warnings:3}. {location}: {description} [{rule}]')
|
||||
|
||||
|
||||
def url_to_docfile(url: str) -> str | None:
|
||||
"""Convert @sa URL to the documentation file it resolves to, following mkdocs redirects."""
|
||||
if not url:
|
||||
return None
|
||||
|
||||
# Extract path after /api/
|
||||
match = re.search(r'/api/(.+?)/?$', url)
|
||||
if not match:
|
||||
return None
|
||||
|
||||
# URL-decode each path component
|
||||
path_parts = [unquote(part) for part in match.group(1).split('/')]
|
||||
relative_path = 'api/' + '/'.join(path_parts) + '.md'
|
||||
|
||||
docs_root = os.path.join(REPO_ROOT, 'docs', 'mkdocs', 'docs')
|
||||
direct_path = os.path.join(docs_root, relative_path)
|
||||
|
||||
# Class-overview URLs (a single path segment after /api/, e.g. ".../api/json_pointer/")
|
||||
# use inconsistent on-disk conventions across classes: ordered_map.md is a flat file,
|
||||
# byte_container_with_subtype/byte_container_with_subtype.md nests under a same-named
|
||||
# file, json_pointer/index.md nests under index.md. Try all observed conventions.
|
||||
candidates = [direct_path]
|
||||
if len(path_parts) == 1:
|
||||
stem = path_parts[0]
|
||||
candidates.append(os.path.join(docs_root, 'api', stem, 'index.md'))
|
||||
candidates.append(os.path.join(docs_root, 'api', stem, stem + '.md'))
|
||||
|
||||
redirected = REDIRECT_MAP.get(relative_path)
|
||||
if redirected:
|
||||
candidates.append(os.path.join(docs_root, redirected))
|
||||
|
||||
for candidate in candidates:
|
||||
if os.path.exists(candidate):
|
||||
return candidate
|
||||
|
||||
# Nothing resolved -- return the direct path so the caller reports a meaningful "missing" location.
|
||||
return direct_path
|
||||
|
||||
|
||||
def check_docs(snapshot_path: str):
|
||||
"""Check documentation for all API entries."""
|
||||
if not os.path.exists(snapshot_path):
|
||||
print(f"Error: Snapshot file not found: {snapshot_path}")
|
||||
sys.exit(1)
|
||||
|
||||
with open(snapshot_path, 'r') as f:
|
||||
data = json.load(f)
|
||||
|
||||
api = data.get('public_api', {})
|
||||
documented_non_public = data.get('documented_non_public', [])
|
||||
|
||||
print(f"Checking documentation for {len(api)} API entries...")
|
||||
print(120 * "-")
|
||||
|
||||
# Check public API entries
|
||||
for identity_key, entry in sorted(api.items()):
|
||||
location = entry.get('location', 'unknown')
|
||||
name = entry.get('name', '?')
|
||||
tier = entry.get('tier', '?')
|
||||
doc_url = entry.get('doc_url')
|
||||
has_sa = entry.get('has_sa', False)
|
||||
|
||||
# Skip type_exempt tier entries
|
||||
if tier == 'type_exempt':
|
||||
continue
|
||||
|
||||
# Check for missing @sa
|
||||
if not has_sa:
|
||||
report('docs/missing_sa_comment', location,
|
||||
f'public API "{name}" (tier: {tier}) has no @sa documentation link')
|
||||
continue
|
||||
|
||||
# Verify URL resolves to an existing file
|
||||
doc_file = url_to_docfile(doc_url)
|
||||
if not doc_file:
|
||||
report('docs/invalid_sa_url', location,
|
||||
f'public API "{name}" has invalid @sa URL: {doc_url}')
|
||||
continue
|
||||
|
||||
if not os.path.exists(doc_file):
|
||||
display_path = os.path.relpath(doc_file, REPO_ROOT)
|
||||
report('docs/missing_doc_file', location,
|
||||
f'public API "{name}" @sa URL points to non-existent file: {display_path}')
|
||||
|
||||
# Check documented_non_public entries
|
||||
for entry in documented_non_public:
|
||||
location = entry.get('location', 'unknown')
|
||||
reason = entry.get('reason', '?')
|
||||
report('docs/sa_on_non_public', location,
|
||||
f'@sa comment found on non-public entity: {reason}')
|
||||
|
||||
print(120 * "-")
|
||||
|
||||
if warnings > 0:
|
||||
print(f"\nFound {warnings} documentation issues")
|
||||
return False
|
||||
else:
|
||||
print("\nAll public API entries are properly documented ✓")
|
||||
return True
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description='Check documentation for public API')
|
||||
parser.add_argument('--snapshot', default='api_snapshot.json',
|
||||
help='Path to API snapshot JSON file')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if not check_docs(args.snapshot):
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Executable
+131
@@ -0,0 +1,131 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Advisory-only cross-check between documented macros and their #define sites.
|
||||
|
||||
Macros have no C++ access-specifier concept, so the AST-based public/private test that
|
||||
extract_api.py uses for classes doesn't transfer -- see tools/api_checker/POLICY.md's "Known
|
||||
limitations" section. This script only checks one direction: that every macro documented under
|
||||
docs/mkdocs/docs/api/macros/ still has a matching #define somewhere under include/nlohmann/,
|
||||
catching stale or renamed doc pages. It does NOT check the converse (undocumented macros) --
|
||||
no reliable signal exists for that direction given this codebase's conventions.
|
||||
|
||||
Never blocks CI -- always exits 0, even when it reports findings.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import glob
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
|
||||
MACRO_TOKEN_RE = re.compile(r'\b([A-Z][A-Z0-9_]*)\b')
|
||||
|
||||
warnings = 0
|
||||
|
||||
|
||||
def report(location: str, description: str):
|
||||
global warnings
|
||||
warnings += 1
|
||||
print(f'{warnings:3}. {location}: {description}')
|
||||
|
||||
|
||||
def extract_macro_names(md_path: str) -> list:
|
||||
"""Extract macro name(s) from a doc page's H1 heading.
|
||||
|
||||
Most pages use a single-line markdown heading ('# JSON_ASSERT'). A few document a family of
|
||||
related macros under one page using a multi-line HTML heading listing comma-separated names
|
||||
(e.g. NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, ..._WITH_DEFAULT, ..._ONLY_SERIALIZE). Handle
|
||||
both: collect the heading text (markdown '# ...' line, or everything between <h1> and </h1>,
|
||||
which may span multiple lines), then split on commas.
|
||||
"""
|
||||
with open(md_path) as f:
|
||||
content = f.read()
|
||||
|
||||
heading_text = None
|
||||
html_match = re.search(r'<h1>(.*?)</h1>', content, re.DOTALL)
|
||||
if html_match:
|
||||
heading_text = html_match.group(1)
|
||||
else:
|
||||
for line in content.splitlines():
|
||||
if line.startswith('# '):
|
||||
heading_text = line[2:]
|
||||
break
|
||||
|
||||
if not heading_text:
|
||||
return []
|
||||
|
||||
names = []
|
||||
for part in heading_text.split(','):
|
||||
match = MACRO_TOKEN_RE.search(part)
|
||||
if match:
|
||||
names.append(match.group(1))
|
||||
return names
|
||||
|
||||
|
||||
def macro_is_referenced(macro_name: str, include_dir: str) -> bool:
|
||||
"""Check whether macro_name is defined OR referenced (#ifdef/#ifndef/defined()) anywhere
|
||||
under include_dir.
|
||||
|
||||
Some documented macros (e.g. JSON_NOEXCEPTION, JSON_THROW_USER) are user-supplied overrides:
|
||||
the library only checks whether they're defined, it never #defines them itself. Requiring a
|
||||
literal #define would make this advisory check permanently noisy for that whole category, so
|
||||
presence of any reference is treated as "this macro still exists in the codebase."
|
||||
"""
|
||||
pattern = re.compile(
|
||||
r'#\s*define\s+' + re.escape(macro_name) + r'\b'
|
||||
r'|#\s*ifn?def\s+' + re.escape(macro_name) + r'\b'
|
||||
r'|defined\s*\(\s*' + re.escape(macro_name) + r'\s*\)'
|
||||
r'|defined\s+' + re.escape(macro_name) + r'\b'
|
||||
)
|
||||
for root, _dirs, files in os.walk(include_dir):
|
||||
for fname in files:
|
||||
if not fname.endswith('.hpp'):
|
||||
continue
|
||||
path = os.path.join(root, fname)
|
||||
with open(path, encoding='utf-8', errors='ignore') as f:
|
||||
if pattern.search(f.read()):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def check_macros(macros_dir: str, include_dir: str) -> bool:
|
||||
md_files = sorted(glob.glob(os.path.join(macros_dir, '*.md')))
|
||||
md_files = [f for f in md_files if os.path.basename(f) != 'index.md']
|
||||
|
||||
print(f"Checking {len(md_files)} documented macros against #define sites in {include_dir}...")
|
||||
print(120 * "-")
|
||||
|
||||
for md_path in md_files:
|
||||
macro_names = extract_macro_names(md_path)
|
||||
if not macro_names:
|
||||
report(md_path, "could not extract macro name(s) from H1 heading")
|
||||
continue
|
||||
|
||||
for macro_name in macro_names:
|
||||
if not macro_is_referenced(macro_name, include_dir):
|
||||
report(md_path, f'documented macro "{macro_name}" is not defined or referenced under {include_dir}')
|
||||
|
||||
print(120 * "-")
|
||||
|
||||
if warnings > 0:
|
||||
print(f"\nFound {warnings} stale/renamed macro doc pages (advisory only, not blocking)")
|
||||
else:
|
||||
print("\nAll documented macros have a matching #define ✓")
|
||||
|
||||
return warnings == 0
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description='Advisory cross-check of documented macros vs. #define sites')
|
||||
parser.add_argument('--macros-dir', default='docs/mkdocs/docs/api/macros',
|
||||
help='Directory containing macro documentation pages')
|
||||
parser.add_argument('--include-dir', default='include/nlohmann',
|
||||
help='Directory to search for #define sites')
|
||||
|
||||
args = parser.parse_args()
|
||||
check_macros(args.macros_dir, args.include_dir)
|
||||
# Advisory only -- never fail CI regardless of findings.
|
||||
sys.exit(0)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Executable
+288
@@ -0,0 +1,288 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Diff the public API surface between two refs to flag breaking vs. feature changes.
|
||||
|
||||
A "ref" for --old/--new is resolved in this order:
|
||||
1. A stored, committed historical record at tools/api_checker/history/<ref>.json, if one exists
|
||||
and --no-history wasn't passed (fast path -- no libclang/git-archive needed).
|
||||
2. Live extraction: check the ref out via `git archive` into a temp dir and run extract_api.py
|
||||
against it (needed for HEAD, branches, or any tag not yet backfilled into history/).
|
||||
--old-file/--new-file bypass both and load an arbitrary surface JSON file directly.
|
||||
|
||||
Uses extract_api.py's --surface-output (identity-only: scope, kind, name, identity_name, tier,
|
||||
signature, pretty_signature -- no location, no doc_url) for both sides, so the diff reflects only
|
||||
genuine API changes, never unrelated code motion or documentation-site restructuring. Identity is
|
||||
(scope, identity_name, kind, signature) -- see extract_api.py's identity_key()/get_signature_text()
|
||||
docstrings for the full history of why this is what it is: a naive {scope,name,kind,params} key
|
||||
silently collided on overloads differing only by constness/SFINAE; switching to libclang's USR
|
||||
fixed that but encoded the *enclosing class template's own arity* into every member's identity, so
|
||||
a single backward-compatible template-parameter addition (confirmed via real release tags
|
||||
v3.11.2->v3.11.3) made ~228 of 330 entries look "changed" for a release with no real breaking
|
||||
changes. The current raw-source-text-signature approach was arrived at, and each of several further
|
||||
refinements verified, by testing against real historical releases -- not by inspecting code alone.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
from collections import defaultdict
|
||||
|
||||
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
||||
HISTORY_DIR = os.path.join(SCRIPT_DIR, 'history')
|
||||
|
||||
# The format_version this build of diff_api.py understands. Kept in sync with
|
||||
# extract_api.py's SURFACE_FORMAT_VERSION by convention (both bump together whenever the
|
||||
# identity-computing algorithm changes) -- imported directly so there's exactly one source of
|
||||
# truth, not two constants that can drift apart.
|
||||
sys.path.insert(0, SCRIPT_DIR)
|
||||
from extract_api import SURFACE_FORMAT_VERSION # noqa: E402
|
||||
|
||||
|
||||
def resolve_commit_sha(ref: str) -> str | None:
|
||||
"""Resolve a ref to its full commit sha, or None if that fails."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
['git', 'rev-parse', ref],
|
||||
capture_output=True, text=True, check=True, timeout=10
|
||||
)
|
||||
return result.stdout.strip()
|
||||
except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
|
||||
return None
|
||||
|
||||
|
||||
def extract_surface_for_ref(ref: str, header: str = 'include/nlohmann/json.hpp',
|
||||
include: str = 'include') -> dict:
|
||||
"""Check out the full include/ tree at `ref` into a temp dir and extract its API surface.
|
||||
|
||||
A single-file checkout of json.hpp is not enough: json.hpp #includes dozens of other
|
||||
headers under nlohmann/detail/ that must exist at the same ref for parsing to succeed.
|
||||
|
||||
Returns the full loaded surface JSON (format_version, meta, public_api list), with `ref` and
|
||||
the resolved commit sha recorded in meta -- callers that only care about the diff can ignore
|
||||
these; snapshot_release.py uses them as a historical record's provenance.
|
||||
"""
|
||||
with tempfile.TemporaryDirectory(prefix='api_checker_') as tmpdir:
|
||||
archive = subprocess.run(
|
||||
['git', 'archive', ref, '--', 'include'],
|
||||
capture_output=True, check=True
|
||||
)
|
||||
subprocess.run(['tar', '-x', '-C', tmpdir], input=archive.stdout, check=True)
|
||||
|
||||
ref_include = os.path.join(tmpdir, include)
|
||||
ref_header = os.path.join(tmpdir, header)
|
||||
if not os.path.exists(ref_header):
|
||||
print(f"Error: {header} does not exist at ref {ref}")
|
||||
sys.exit(1)
|
||||
|
||||
surface_output = os.path.join(tmpdir, 'surface.json')
|
||||
result = subprocess.run(
|
||||
[sys.executable, os.path.join(SCRIPT_DIR, 'extract_api.py'),
|
||||
'--header', ref_header,
|
||||
'--include', ref_include,
|
||||
'--output', os.path.join(tmpdir, 'snapshot.json'),
|
||||
'--surface-output', surface_output],
|
||||
capture_output=True, text=True
|
||||
)
|
||||
if result.returncode != 0:
|
||||
print(f"Error extracting API at ref {ref}:")
|
||||
print(result.stdout)
|
||||
print(result.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
with open(surface_output) as f:
|
||||
surface = json.load(f)
|
||||
|
||||
# extract_api.py resolved 'extracted_from' relative to *its own* invocation cwd/repo-root
|
||||
# detection, which inside this temp checkout is meaningless (a path like
|
||||
# "../../../../var/folders/.../tmp.XXXX/include/nlohmann/json.hpp") -- overwrite with the
|
||||
# stable, repo-relative header path actually passed in, so a stored history file's metadata
|
||||
# doesn't embed a throwaway temp directory name.
|
||||
surface.setdefault('meta', {})['extracted_from'] = header
|
||||
surface['meta']['ref'] = ref
|
||||
commit_sha = resolve_commit_sha(ref)
|
||||
if commit_sha:
|
||||
surface['meta']['commit'] = commit_sha
|
||||
return surface
|
||||
|
||||
|
||||
def load_surface_file(path: str) -> dict:
|
||||
"""Load a surface JSON file from disk (a stored history/ record or an explicit --old-file/--new-file)."""
|
||||
with open(path) as f:
|
||||
return json.load(f)
|
||||
|
||||
|
||||
def resolve_surface(ref: str | None, explicit_file: str | None, header: str, include: str,
|
||||
no_history: bool) -> tuple:
|
||||
"""Resolve one side of a diff. Returns (surface_dict, description_string_for_display)."""
|
||||
if explicit_file:
|
||||
return load_surface_file(explicit_file), f"file:{explicit_file}"
|
||||
|
||||
history_path = os.path.join(HISTORY_DIR, f"{ref}.json")
|
||||
if not no_history and os.path.exists(history_path):
|
||||
return load_surface_file(history_path), f"history:{ref}"
|
||||
|
||||
return extract_surface_for_ref(ref, header, include), f"live:{ref}"
|
||||
|
||||
|
||||
def build_identity_dict(public_api: list) -> dict:
|
||||
"""Group a surface's public_api list by identity for diffing.
|
||||
|
||||
Identity is (scope, identity_name, kind, signature) -- the same four components
|
||||
extract_api.py's identity_key() joins into one opaque string internally, exposed here as
|
||||
explicit fields on each record (see extract_api.py's write_surface()) so this reconstruction
|
||||
is a plain, visible tuple lookup rather than decoding anything.
|
||||
"""
|
||||
return {
|
||||
(entry['scope'], entry['identity_name'], entry['kind'], entry['signature']): entry
|
||||
for entry in public_api
|
||||
}
|
||||
|
||||
|
||||
def diff_surfaces(old_api: dict, new_api: dict) -> dict:
|
||||
"""Compare two API surfaces by identity key, grouping same-(scope,name) changes."""
|
||||
old_keys = set(old_api.keys())
|
||||
new_keys = set(new_api.keys())
|
||||
|
||||
added_keys = new_keys - old_keys
|
||||
removed_keys = old_keys - new_keys
|
||||
|
||||
# Group removed/added entries by (scope, name) to detect "changed overload" pairs,
|
||||
# rather than reporting a same-named removal+addition as two unrelated changes.
|
||||
removed_by_name = defaultdict(list)
|
||||
for key in removed_keys:
|
||||
entry = old_api[key]
|
||||
removed_by_name[(entry['scope'], entry['name'])].append(key)
|
||||
|
||||
added_by_name = defaultdict(list)
|
||||
for key in added_keys:
|
||||
entry = new_api[key]
|
||||
added_by_name[(entry['scope'], entry['name'])].append(key)
|
||||
|
||||
changed = []
|
||||
pure_added = []
|
||||
pure_removed = []
|
||||
|
||||
for name, removed_list in removed_by_name.items():
|
||||
if name in added_by_name:
|
||||
added_list = added_by_name.pop(name)
|
||||
for key in removed_list:
|
||||
changed.append({'scope': name[0], 'name': name[1],
|
||||
'old': old_api[key]['pretty_signature'],
|
||||
'new': new_api[added_list[0]]['pretty_signature']})
|
||||
else:
|
||||
for key in removed_list:
|
||||
pure_removed.append(old_api[key])
|
||||
|
||||
for name, added_list in added_by_name.items():
|
||||
for key in added_list:
|
||||
pure_added.append(new_api[key])
|
||||
|
||||
return {
|
||||
'added': sorted(pure_added, key=lambda e: e['pretty_signature']),
|
||||
'removed': sorted(pure_removed, key=lambda e: e['pretty_signature']),
|
||||
'changed': sorted(changed, key=lambda e: (e['scope'], e['name'])),
|
||||
}
|
||||
|
||||
|
||||
def print_diff(diff: dict, old_desc: str, new_desc: str) -> bool:
|
||||
"""Print a human-readable diff report. Returns True if breaking changes were found."""
|
||||
print(120 * "-")
|
||||
print(f"API Diff: {old_desc} -> {new_desc}")
|
||||
print(120 * "-")
|
||||
|
||||
if diff['added']:
|
||||
print(f"\nAdded ({len(diff['added'])} entries) -- feature:")
|
||||
for entry in diff['added']:
|
||||
print(f" + {entry['pretty_signature']}")
|
||||
|
||||
if diff['removed']:
|
||||
print(f"\nRemoved ({len(diff['removed'])} entries) -- BREAKING:")
|
||||
for entry in diff['removed']:
|
||||
print(f" - {entry['pretty_signature']}")
|
||||
|
||||
if diff['changed']:
|
||||
print(f"\nChanged overloads ({len(diff['changed'])} entries) -- BREAKING by default:")
|
||||
for entry in diff['changed']:
|
||||
print(f" ~ {entry['old']} -> {entry['new']}")
|
||||
|
||||
if not any([diff['added'], diff['removed'], diff['changed']]):
|
||||
print("\nNo API changes detected")
|
||||
|
||||
print(120 * "-")
|
||||
|
||||
breaking = bool(diff['removed'] or diff['changed'])
|
||||
if breaking:
|
||||
print(f"\nWARNING: Potential BREAKING CHANGES detected:")
|
||||
print(f" - {len(diff['removed'])} removed entries")
|
||||
print(f" - {len(diff['changed'])} changed overloads")
|
||||
if diff['added']:
|
||||
print(f"\nNew features: {len(diff['added'])} added entries")
|
||||
|
||||
return breaking
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description='Diff public API surface between two refs')
|
||||
parser.add_argument('--old', help='Old git ref (tag/commit) -- checks tools/api_checker/history/ first, '
|
||||
'then falls back to live extraction')
|
||||
parser.add_argument('--new', help='New git ref (default: HEAD unless --new-file is given)')
|
||||
parser.add_argument('--old-file', help='Path to a stored surface JSON file for the "old" side '
|
||||
'(bypasses git and tools/api_checker/history/ entirely)')
|
||||
parser.add_argument('--new-file', help='Path to a stored surface JSON file for the "new" side '
|
||||
'(bypasses git and tools/api_checker/history/ entirely)')
|
||||
parser.add_argument('--no-history', action='store_true',
|
||||
help='Force live extraction even if a matching tools/api_checker/history/<ref>.json '
|
||||
'exists -- useful to check a stored record is still faithful to a fresh run')
|
||||
parser.add_argument('--allow-format-mismatch', action='store_true',
|
||||
help='Proceed even if the two surfaces have different format_version (results may '
|
||||
'be unsound -- the identity algorithm may differ between versions)')
|
||||
parser.add_argument('--header', default='include/nlohmann/json.hpp',
|
||||
help='Header file to analyze (relative to repo root, live-extraction only)')
|
||||
parser.add_argument('--include', default='include',
|
||||
help='Include directory (relative to repo root, live-extraction only)')
|
||||
parser.add_argument('--fail-on-breaking', action='store_true',
|
||||
help='Exit with status 1 if breaking changes are detected')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.old and args.old_file:
|
||||
parser.error('--old and --old-file are mutually exclusive')
|
||||
if not args.old and not args.old_file:
|
||||
parser.error('one of --old or --old-file is required')
|
||||
if args.new and args.new_file:
|
||||
parser.error('--new and --new-file are mutually exclusive')
|
||||
|
||||
new_ref = args.new or ('HEAD' if not args.new_file else None)
|
||||
|
||||
print(f"Resolving old surface ({args.old_file or args.old})...")
|
||||
old_surface, old_desc = resolve_surface(args.old, args.old_file, args.header, args.include, args.no_history)
|
||||
|
||||
print(f"Resolving new surface ({args.new_file or new_ref})...")
|
||||
new_surface, new_desc = resolve_surface(new_ref, args.new_file, args.header, args.include, args.no_history)
|
||||
|
||||
old_fmt = old_surface.get('format_version')
|
||||
new_fmt = new_surface.get('format_version')
|
||||
if old_fmt != new_fmt and not args.allow_format_mismatch:
|
||||
print(f"Error: format_version mismatch ({old_desc}: {old_fmt!r} vs {new_desc}: {new_fmt!r}).")
|
||||
print("The identity/signature algorithm may differ between these two surfaces, making a diff unsound.")
|
||||
print("Re-run with --allow-format-mismatch to proceed anyway.")
|
||||
sys.exit(1)
|
||||
elif old_fmt != new_fmt:
|
||||
print(f"WARNING: proceeding with mismatched format_version ({old_fmt!r} vs {new_fmt!r}) as requested.")
|
||||
|
||||
old_api = build_identity_dict(old_surface['public_api'])
|
||||
new_api = build_identity_dict(new_surface['public_api'])
|
||||
|
||||
print(f"\nComparing {len(old_api)} old entries with {len(new_api)} new entries...")
|
||||
diff = diff_surfaces(old_api, new_api)
|
||||
|
||||
breaking = print_diff(diff, old_desc, new_desc)
|
||||
|
||||
if args.fail_on_breaking and breaking:
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Executable
+630
@@ -0,0 +1,630 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Extract the public API surface of nlohmann/json using libclang AST.
|
||||
|
||||
This tool derives the public API from C++ semantics (class templates, access specifiers,
|
||||
namespace scoping) independently of documentation status. The extracted surface is the
|
||||
source of truth for what is considered "public API" — doc-checking and API diffing are
|
||||
downstream consumers of this snapshot.
|
||||
|
||||
Strategy:
|
||||
1. Parse include/nlohmann/json.hpp with libclang (with proper system includes)
|
||||
2. Walk the primary class-template definitions of the 6 known public classes
|
||||
3. Extract callable members (methods, constructors, destructors, conversion ops) and type aliases
|
||||
4. Extract free functions/operators in nlohmann:: (excluding detail::)
|
||||
5. Handle alias-exposed exception types by following the alias to the detail:: definition
|
||||
6. Normalize away the ABI inline-namespace (json_abi_v3_12_0, json_abi_diag_v3_12_0, etc.)
|
||||
7. Emit a snapshot with an overload-disambiguating identity key and documentation status
|
||||
|
||||
Output includes both public_api (all tracked public entities) and documented_non_public
|
||||
(entities with @sa comments that are NOT in the public surface — used for validation).
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
from clang import cindex
|
||||
except ImportError:
|
||||
print("Error: libclang not installed. Run: pip install -r tools/api_checker/requirements.txt")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
ABI_TAG_PATTERN = re.compile(r'::json(?:_abi)?[a-z_]*_v\d+_\d+_\d+(?=::|$)')
|
||||
|
||||
# Bump whenever a change to this schema, or to the identity-computing algorithm
|
||||
# (get_signature_text()/get_identity_name()/identity_key()), could alter the 'signature' or
|
||||
# 'identity_name' text for otherwise-unchanged source. diff_api.py refuses by default to compare
|
||||
# two surface files with different SURFACE_FORMAT_VERSION -- see diff_api.py and
|
||||
# tools/api_checker/POLICY.md for why: an earlier, unversioned identity scheme (based on
|
||||
# libclang's USR) silently corrupted every historical comparison whenever the *unrelated*
|
||||
# enclosing class template gained a new template parameter, and nothing caught it because there
|
||||
# was no version to check.
|
||||
SURFACE_FORMAT_VERSION = 2
|
||||
|
||||
|
||||
def strip_abi_tag(text: str) -> str:
|
||||
"""Remove ABI inline-namespace from a qualified name or type string."""
|
||||
return ABI_TAG_PATTERN.sub('', text)
|
||||
|
||||
|
||||
_FILE_CONTENT_CACHE = {}
|
||||
|
||||
|
||||
def _read_file_cached(path: str) -> str:
|
||||
if path not in _FILE_CONTENT_CACHE:
|
||||
try:
|
||||
with open(path, 'r', encoding='utf-8', errors='ignore') as f:
|
||||
_FILE_CONTENT_CACHE[path] = f.read()
|
||||
except OSError:
|
||||
_FILE_CONTENT_CACHE[path] = ''
|
||||
return _FILE_CONTENT_CACHE[path]
|
||||
|
||||
|
||||
def get_signature_text(cursor) -> str:
|
||||
"""The normalized source text of a declaration's own signature -- template header, return
|
||||
type, name, full parameter list, and trailing cv/ref/noexcept qualifiers -- stopping before
|
||||
the function body ('{') or at the terminating ';'/'= default;'/'= 0;'. Never includes the
|
||||
body, so implementation-only changes don't affect identity.
|
||||
|
||||
Reads raw source text via cursor.extent's byte offsets rather than cursor.get_tokens():
|
||||
the latter was found to silently return zero tokens whenever a cursor's extent starts
|
||||
exactly at an unexpanded macro invocation (confirmed empirically for basic_json's four
|
||||
binary() overloads and iterator_wrapper(), both preceded by JSON_HEDLEY_WARN_UNUSED_RESULT
|
||||
-- a known class of libclang tokenizer edge case, not specific to this codebase). Raw text
|
||||
also avoids cursor.get_arguments()/cursor.type.spelling, which were separately found
|
||||
empty/unreliable for some FUNCTION_TEMPLATE cursors with complex trailing
|
||||
noexcept(noexcept(...))/decltype(...) clauses (adl_serializer::from_json). Source text is
|
||||
what's actually written (declared names like "ValueType", never a resolved
|
||||
"basic_json<T0,...,T10>"), so it's immune to the enclosing class's template arity too --
|
||||
see identity_key()'s docstring for why that matters.
|
||||
|
||||
Comments are stripped while scanning. Without this, a purely cosmetic NOLINT annotation
|
||||
added mid-signature (e.g. `KeyType&& key) // NOLINT(...)` before the body's '{') would
|
||||
change the captured text -- confirmed empirically via a real nlohmann/json release
|
||||
(v3.11.2 -> v3.11.3 added such NOLINT comments to several ordered_map methods and to
|
||||
basic_json's swap(), with no other change, and diff_api.py reported all of them as
|
||||
"changed overloads").
|
||||
"""
|
||||
start = cursor.extent.start
|
||||
end = cursor.extent.end
|
||||
if not start.file:
|
||||
return ''
|
||||
content = _read_file_cached(start.file.name)
|
||||
if not content:
|
||||
return ''
|
||||
raw = content[start.offset:end.offset]
|
||||
|
||||
paren_depth = 0
|
||||
angle_depth = 0
|
||||
seen_param_list_close = False
|
||||
out = []
|
||||
i = 0
|
||||
n = len(raw)
|
||||
while i < n:
|
||||
ch = raw[i]
|
||||
if ch == '/' and i + 1 < n and raw[i + 1] == '/':
|
||||
i = raw.find('\n', i)
|
||||
if i == -1:
|
||||
break
|
||||
continue
|
||||
if ch == '/' and i + 1 < n and raw[i + 1] == '*':
|
||||
end_comment = raw.find('*/', i + 2)
|
||||
i = n if end_comment == -1 else end_comment + 2
|
||||
continue
|
||||
if ch == '{' and paren_depth == 0 and angle_depth == 0:
|
||||
break
|
||||
if ch == ';' and paren_depth == 0 and angle_depth == 0:
|
||||
out.append(ch)
|
||||
break
|
||||
# A bare ':' after the parameter list has closed starts a constructor's
|
||||
# member-initializer-list ("basic_json(...) : m_data(v) { ... }") -- that's
|
||||
# implementation (which members get initialized how), not public signature, so stop
|
||||
# before it. Guarded by seen_param_list_close so this doesn't misfire on a ':' that's
|
||||
# actually part of a preceding "::" scope-resolution token in the return type/params.
|
||||
if (ch == ':' and seen_param_list_close and paren_depth == 0 and angle_depth == 0
|
||||
and (i == 0 or raw[i - 1] != ':') and (i + 1 >= n or raw[i + 1] != ':')):
|
||||
break
|
||||
if ch == '(':
|
||||
paren_depth += 1
|
||||
elif ch == ')':
|
||||
paren_depth = max(0, paren_depth - 1)
|
||||
if paren_depth == 0:
|
||||
seen_param_list_close = True
|
||||
elif ch == '<':
|
||||
angle_depth += 1
|
||||
elif ch == '>' and angle_depth > 0:
|
||||
angle_depth -= 1
|
||||
out.append(ch)
|
||||
i += 1
|
||||
|
||||
sig = re.sub(r'\s+', ' ', ''.join(out)).strip()
|
||||
return strip_abi_tag(sig)
|
||||
|
||||
|
||||
def get_identity_name(cursor, scope: str) -> str:
|
||||
"""The name component of a cursor's identity -- usually cursor.spelling, but not for
|
||||
CONSTRUCTOR/DESTRUCTOR cursors, or FUNCTION_TEMPLATE cursors that are themselves templated
|
||||
constructors (e.g. `template<typename CompatibleType> basic_json(CompatibleType&& val)`,
|
||||
which libclang represents as FUNCTION_TEMPLATE, not CONSTRUCTOR).
|
||||
|
||||
libclang's cursor.spelling for those renders the *enclosing class's full template argument
|
||||
list* (e.g. "basic_json<ObjectType, ..., CustomBaseClass>"), not just "basic_json". Using it
|
||||
as-is for identity would reintroduce class-arity sensitivity (see identity_key()'s docstring
|
||||
for why that's a problem) just for constructors specifically. Detected by checking whether
|
||||
cursor.spelling equals or starts with "<ClassName><" -- the class's own bare name, the last
|
||||
segment of scope. A canonical placeholder ("(constructor)"/"(destructor)") is substituted for
|
||||
identity purposes; callers still use cursor.spelling as-is for human-readable display fields
|
||||
(name/pretty_signature), where the full templated name is informative rather than noisy.
|
||||
"""
|
||||
class_bare_name = scope.rsplit('::', 1)[-1]
|
||||
is_constructor_like = (
|
||||
cursor.kind == cindex.CursorKind.CONSTRUCTOR
|
||||
or (cursor.kind == cindex.CursorKind.FUNCTION_TEMPLATE
|
||||
and (cursor.spelling == class_bare_name or cursor.spelling.startswith(class_bare_name + '<')))
|
||||
)
|
||||
if is_constructor_like:
|
||||
return '(constructor)'
|
||||
if cursor.kind == cindex.CursorKind.DESTRUCTOR:
|
||||
return '(destructor)'
|
||||
return cursor.spelling
|
||||
|
||||
|
||||
def identity_key(cursor, scope: str) -> str:
|
||||
"""A stable, overload-disambiguating key, used internally during extraction to prevent two
|
||||
distinct entries from silently colliding in the in-memory api_dict. Two prior approaches were
|
||||
tried and found broken:
|
||||
|
||||
1. {scope, name, kind, params} from cursor.get_arguments() alone: silently collided for
|
||||
overload sets differentiated only by constness, ref-qualifiers, or SFINAE constraints
|
||||
rather than parameter types -- e.g. basic_json's two zero-argument get() overloads (one
|
||||
const, one not) both produced params=[] and overwrote each other in the output dict. A
|
||||
full scan found 59 such silent overwrites across 27 colliding names. Extending this
|
||||
approach with is_const/is_static/ref-qualifier flags fixed most of these but not all --
|
||||
adl_serializer::from_json's two overloads and basic_json's two erase(iterator) overloads
|
||||
still collided, because get_arguments() returns [] for them (see get_signature_text()'s
|
||||
docstring) and their template-parameter lists happen to read identically too.
|
||||
2. libclang's USR: correctly disambiguates every overload (it encodes the full mangled
|
||||
signature) but also encodes the *enclosing class template's own arity* into every
|
||||
member's USR. Confirmed empirically: basic_json gaining a defaulted CustomBaseClass
|
||||
template parameter between v3.11.2 and v3.11.3 (a backward-compatible change) changed
|
||||
literally every basic_json member's USR, which made diff_api.py report ~228/330 entries
|
||||
as "changed" for a release with zero real breaking changes among them. Reconstructing
|
||||
"the member's own identity" by string-surgery on USR text was rejected: clang's USR
|
||||
grammar is undocumented and not a stable contract for this kind of manipulation.
|
||||
|
||||
This key avoids both failure modes: scope is passed in (derived from get_qualified_name(),
|
||||
never from USR), and get_signature_text() reads the declaration as literally written in
|
||||
source, which never encodes the enclosing class's resolved template arguments and reliably
|
||||
disambiguates every case found so far (SFINAE-only overloads, overloads get_arguments()
|
||||
can't see, and simple parameter-type differences alike).
|
||||
|
||||
Known limitation: because the signature text includes parameter *names*, not just types, a
|
||||
pure parameter rename (no type/constraint change) would look like a "changed" entry to
|
||||
diff_api.py. Accepted as a much smaller and rarer source of noise than either bug above --
|
||||
see POLICY.md.
|
||||
|
||||
NOTE: this opaque joined string is only used as a dict key during extraction. The persisted
|
||||
--surface-output format (see main()) stores scope/identity_name/kind/signature as separate,
|
||||
explicit fields instead -- a human or `git diff` should never need to decode this string.
|
||||
"""
|
||||
return '\x1f'.join([scope, get_identity_name(cursor, scope), cursor.kind.name, get_signature_text(cursor)])
|
||||
|
||||
|
||||
def get_repo_root():
|
||||
"""Find the repository root via git, so location paths are deterministic regardless of invoking CWD."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
['git', 'rev-parse', '--show-toplevel'],
|
||||
capture_output=True, text=True, check=True, timeout=10
|
||||
)
|
||||
return result.stdout.strip()
|
||||
except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
|
||||
return None
|
||||
|
||||
|
||||
REPO_ROOT = get_repo_root()
|
||||
|
||||
|
||||
def canonicalize_path(file_path: str) -> str:
|
||||
"""Make a file path deterministic: absolute, then relative to the repo root."""
|
||||
if not file_path:
|
||||
return 'unknown'
|
||||
abs_path = os.path.abspath(file_path)
|
||||
if REPO_ROOT:
|
||||
return os.path.relpath(abs_path, REPO_ROOT)
|
||||
return abs_path
|
||||
|
||||
|
||||
def cursor_location(cursor) -> str:
|
||||
"""Build a canonical 'path:line' string for a cursor, or 'unknown' if it has no file."""
|
||||
if cursor.location and cursor.location.file:
|
||||
return f"{canonicalize_path(cursor.location.file.name)}:{cursor.location.line}"
|
||||
return "unknown"
|
||||
|
||||
|
||||
def get_system_includes(compiler='clang++'):
|
||||
"""Discover system include paths by parsing clang++ -E -x c++ -v /dev/null output."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
[compiler, '-E', '-x', 'c++', '-v', '/dev/null'],
|
||||
capture_output=True, text=True, check=True, timeout=10
|
||||
)
|
||||
except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired) as e:
|
||||
print(f"Warning: Failed to discover system includes via '{compiler}': {e}")
|
||||
return []
|
||||
|
||||
stderr = result.stderr
|
||||
in_block = False
|
||||
paths = []
|
||||
for line in stderr.splitlines():
|
||||
if line.strip() == '#include <...> search starts here:':
|
||||
in_block = True
|
||||
continue
|
||||
if line.strip() == 'End of search list.':
|
||||
in_block = False
|
||||
continue
|
||||
if in_block:
|
||||
# Strip trailing annotations like "(framework directory)"
|
||||
path = line.strip().split()[0] if line.strip() else ''
|
||||
if path:
|
||||
paths.append(path)
|
||||
|
||||
return [f'-isystem{p}' for p in paths]
|
||||
|
||||
|
||||
def setup_libclang():
|
||||
"""Locate and set up libclang library."""
|
||||
possible_paths = [
|
||||
'/opt/homebrew/opt/llvm/lib/libclang.dylib', # macOS
|
||||
'/usr/local/opt/llvm/lib/libclang.dylib', # macOS alt
|
||||
'/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib',
|
||||
'/usr/lib/libclang.so', # Linux
|
||||
'/usr/lib/x86_64-linux-gnu/libclang.so', # Linux
|
||||
]
|
||||
|
||||
for path in possible_paths:
|
||||
if os.path.exists(path):
|
||||
try:
|
||||
cindex.conf.set_library_file(path)
|
||||
return True
|
||||
except Exception:
|
||||
continue
|
||||
|
||||
try:
|
||||
filename = cindex.conf.get_filename()
|
||||
if filename:
|
||||
cindex.conf.set_library_file(filename)
|
||||
return True
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return False
|
||||
|
||||
|
||||
def extract_sa_url(raw_comment: str) -> str | None:
|
||||
"""Extract @sa URL from a Doxygen comment."""
|
||||
if not raw_comment:
|
||||
return None
|
||||
match = re.search(r'@sa\s+(https://[^\s]+)', raw_comment)
|
||||
return match.group(1) if match else None
|
||||
|
||||
|
||||
def get_qualified_name(cursor) -> str:
|
||||
"""Get fully qualified name by walking semantic_parent chain."""
|
||||
parts = []
|
||||
c = cursor
|
||||
while c and c.kind != cindex.CursorKind.TRANSLATION_UNIT:
|
||||
if c.kind == cindex.CursorKind.NAMESPACE:
|
||||
# Skip ABI inline-namespace cursors
|
||||
if not ABI_TAG_PATTERN.search(f'::{c.spelling}'):
|
||||
parts.append(c.spelling)
|
||||
elif c.spelling:
|
||||
parts.append(c.spelling)
|
||||
c = c.semantic_parent
|
||||
return '::'.join(reversed(parts)) if parts else ''
|
||||
|
||||
|
||||
def walk_class_template(cursor, public_classes: set, api_dict: dict, documented_non_public: list):
|
||||
"""Walk a class template's members: extract public callable/type-tier entities, and flag
|
||||
any non-public member that surprisingly carries a real @sa URL (a genuine documentation leak)."""
|
||||
if cursor.kind not in (cindex.CursorKind.CLASS_TEMPLATE, cindex.CursorKind.CLASS_DECL, cindex.CursorKind.STRUCT_DECL):
|
||||
return
|
||||
if cursor.spelling not in public_classes or not cursor.is_definition():
|
||||
return
|
||||
|
||||
scope = strip_abi_tag(get_qualified_name(cursor))
|
||||
location = cursor_location(cursor)
|
||||
|
||||
# Exemption list: STL-container-named-requirement aliases that don't require @sa
|
||||
stl_exempt = {'value_type', 'reference', 'const_reference', 'pointer', 'const_pointer',
|
||||
'iterator', 'const_iterator', 'reverse_iterator', 'const_reverse_iterator',
|
||||
'difference_type', 'size_type', 'allocator_type', 'key_type', 'mapped_type'}
|
||||
|
||||
for child in cursor.get_children():
|
||||
is_public = not hasattr(child, 'access_specifier') or str(child.access_specifier) == 'AccessSpecifier.PUBLIC'
|
||||
|
||||
if not is_public:
|
||||
# documented_non_public tracks entities NOT part of the public surface that
|
||||
# nonetheless carry a real @sa URL -- a genuine documentation leak, not "any
|
||||
# public member missing @sa" (that's what check_docs.py's missing-@sa check is for).
|
||||
leaked_url = extract_sa_url(child.raw_comment)
|
||||
if leaked_url:
|
||||
documented_non_public.append({
|
||||
'location': cursor_location(child),
|
||||
'raw_comment_excerpt': (child.raw_comment or '')[:100],
|
||||
'reason': f'{child.kind.name} "{child.spelling}" is non-public but has @sa: {leaked_url}'
|
||||
})
|
||||
continue
|
||||
|
||||
# Callable tier: methods, constructors, destructors, conversion ops, function templates
|
||||
if child.kind in (cindex.CursorKind.CXX_METHOD, cindex.CursorKind.CONSTRUCTOR,
|
||||
cindex.CursorKind.DESTRUCTOR, cindex.CursorKind.CONVERSION_FUNCTION,
|
||||
cindex.CursorKind.FUNCTION_TEMPLATE):
|
||||
key = identity_key(child, scope)
|
||||
doc_url = extract_sa_url(child.raw_comment)
|
||||
api_dict[key] = {
|
||||
'scope': scope,
|
||||
'name': child.spelling,
|
||||
'identity_name': get_identity_name(child, scope),
|
||||
'kind': child.kind.name,
|
||||
'tier': 'callable',
|
||||
'signature': get_signature_text(child),
|
||||
'location': cursor_location(child),
|
||||
'doc_url': doc_url,
|
||||
'has_sa': doc_url is not None,
|
||||
'pretty_signature': f"{scope}::{child.spelling}",
|
||||
}
|
||||
|
||||
# Type tier: TYPE_ALIAS_DECL
|
||||
elif child.kind == cindex.CursorKind.TYPE_ALIAS_DECL:
|
||||
name = child.spelling
|
||||
tier = 'type_exempt' if name in stl_exempt else 'type'
|
||||
|
||||
# Try to follow the alias to find @sa on the underlying declaration
|
||||
doc_url = extract_sa_url(child.raw_comment)
|
||||
underlying_location = None
|
||||
if not doc_url and hasattr(child, 'underlying_typedef_type'):
|
||||
try:
|
||||
underlying_decl = child.underlying_typedef_type.get_declaration()
|
||||
if underlying_decl and underlying_decl.raw_comment:
|
||||
doc_url = extract_sa_url(underlying_decl.raw_comment)
|
||||
if underlying_decl.location.file:
|
||||
underlying_location = cursor_location(underlying_decl)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
key = identity_key(child, scope)
|
||||
api_dict[key] = {
|
||||
'scope': scope,
|
||||
'name': name,
|
||||
'identity_name': get_identity_name(child, scope),
|
||||
'kind': 'TYPE_ALIAS_DECL',
|
||||
'tier': tier,
|
||||
'signature': get_signature_text(child),
|
||||
'location': location,
|
||||
'doc_url': doc_url,
|
||||
'has_sa': doc_url is not None,
|
||||
'pretty_signature': f"{scope}::{name}",
|
||||
}
|
||||
if underlying_location:
|
||||
api_dict[key]['resolved_via_alias_to'] = underlying_location
|
||||
|
||||
|
||||
def walk_ast(cursor, public_classes: set, api_dict: dict, documented_non_public: list):
|
||||
"""Recursively walk AST."""
|
||||
# Check if this is one of the six public class templates
|
||||
if cursor.kind in (cindex.CursorKind.CLASS_TEMPLATE, cindex.CursorKind.CLASS_DECL, cindex.CursorKind.STRUCT_DECL):
|
||||
if cursor.spelling in public_classes:
|
||||
walk_class_template(cursor, public_classes, api_dict, documented_non_public)
|
||||
|
||||
# Extract free functions (not nested in a class)
|
||||
elif cursor.kind == cindex.CursorKind.FUNCTION_DECL:
|
||||
# Check it's in nlohmann namespace, not detail/std
|
||||
parent = cursor.semantic_parent
|
||||
if parent and parent.kind == cindex.CursorKind.NAMESPACE:
|
||||
ns_name = parent.spelling
|
||||
if ns_name == 'nlohmann' or (parent.semantic_parent and parent.semantic_parent.kind == cindex.CursorKind.NAMESPACE and
|
||||
parent.semantic_parent.spelling == 'nlohmann'):
|
||||
# This is a free function in nlohmann (or a subnamespace like json_literals)
|
||||
if 'detail' not in ns_name and 'std' not in ns_name:
|
||||
# get_qualified_name(parent), not get_qualified_name(cursor) -- the latter
|
||||
# would include the function's own name as the last segment (cursor is the
|
||||
# function itself), producing a bogus scope like "nlohmann::operator==" and
|
||||
# a doubled pretty_signature "nlohmann::operator==::operator==".
|
||||
scope = strip_abi_tag(get_qualified_name(parent))
|
||||
key = identity_key(cursor, scope)
|
||||
doc_url = extract_sa_url(cursor.raw_comment)
|
||||
api_dict[key] = {
|
||||
'scope': scope,
|
||||
'name': cursor.spelling,
|
||||
'identity_name': get_identity_name(cursor, scope),
|
||||
'kind': 'FUNCTION_DECL',
|
||||
'tier': 'callable',
|
||||
'signature': get_signature_text(cursor),
|
||||
'location': cursor_location(cursor),
|
||||
'doc_url': doc_url,
|
||||
'has_sa': doc_url is not None,
|
||||
'pretty_signature': f"{scope}::{cursor.spelling}",
|
||||
}
|
||||
|
||||
# Recurse into container types
|
||||
for child in cursor.get_children():
|
||||
walk_ast(child, public_classes, api_dict, documented_non_public)
|
||||
|
||||
|
||||
def write_surface(api_dict: dict, output_path: str, extracted_from: str, extra_meta: dict | None = None):
|
||||
"""Write the minimal, location/doc-independent API surface: a format_version-tagged, sorted
|
||||
list of self-describing records (scope, kind, name, identity_name, tier, signature,
|
||||
pretty_signature) -- no opaque joined key, no location, no doc_url.
|
||||
|
||||
This is the file meant to be committed and diffed release-to-release (see
|
||||
tools/api_checker/README.md and POLICY.md): 'signature'/'identity_name' are the same values
|
||||
identity_key() joins into one opaque string for internal use during extraction, but exposed
|
||||
here as separate fields so the file is self-describing -- a human or `git diff` can see
|
||||
exactly what changed without decoding anything (see identity_key()'s docstring).
|
||||
|
||||
extra_meta lets callers (e.g. snapshot_release.py, writing a per-release historical record)
|
||||
add richer, immutable provenance (ref/commit/generated_at) beyond what a live, repeatedly-
|
||||
regenerated snapshot should carry -- see SURFACE_FORMAT_VERSION's docstring for why the live
|
||||
file deliberately omits a timestamp.
|
||||
"""
|
||||
records = [
|
||||
{
|
||||
'scope': entry['scope'],
|
||||
'kind': entry['kind'],
|
||||
'name': entry['name'],
|
||||
'identity_name': entry['identity_name'],
|
||||
'tier': entry['tier'],
|
||||
'signature': entry['signature'],
|
||||
'pretty_signature': entry['pretty_signature'],
|
||||
}
|
||||
for entry in api_dict.values()
|
||||
]
|
||||
records.sort(key=lambda r: (r['scope'], r['name'], r['kind'], r['signature']))
|
||||
|
||||
meta = {'extracted_from': extracted_from}
|
||||
if extra_meta:
|
||||
meta.update(extra_meta)
|
||||
|
||||
output = {
|
||||
'format_version': SURFACE_FORMAT_VERSION,
|
||||
'meta': meta,
|
||||
'public_api': records,
|
||||
}
|
||||
with open(output_path, 'w') as f:
|
||||
json.dump(output, f, indent=2, sort_keys=True)
|
||||
f.write('\n')
|
||||
|
||||
|
||||
def run_self_test():
|
||||
"""Test ABI-tag stripping."""
|
||||
tests = [
|
||||
('nlohmann::json_abi_v3_12_0::basic_json::parse', 'nlohmann::basic_json::parse'),
|
||||
('nlohmann::json_abi_diag_v3_12_0::basic_json::dump', 'nlohmann::basic_json::dump'),
|
||||
('nlohmann::json_abi_diag_ldvcmp_v3_11_2::basic_json::get', 'nlohmann::basic_json::get'),
|
||||
# The ABI tag as the *last* segment (no following '::') -- the scope of a free function
|
||||
# whose direct parent is the ABI-tagged namespace itself, e.g. nlohmann::operator==.
|
||||
# A regression: an earlier version of this pattern required a trailing '::' via a
|
||||
# lookahead, so it silently failed to strip exactly this case, and diff_api.py reported
|
||||
# every free comparison operator as removed-and-readded on every ABI-tag version bump.
|
||||
('nlohmann::json_abi_v3_11_3', 'nlohmann'),
|
||||
# v3.11.0/v3.11.1 used "json_vMAJOR_MINOR_PATCH" (no "_abi" segment) before the tag was
|
||||
# renamed to "json_abi_v..." in v3.11.2. A regression: an earlier version of this pattern
|
||||
# hard-required the literal "_abi" segment, so it silently failed to strip this older
|
||||
# form, making diff_api.py report ~100% of the API as removed-and-readded across
|
||||
# v3.10.5->v3.11.0->v3.11.1->v3.11.2 (confirmed against the real backfilled history).
|
||||
('nlohmann::json_v3_11_0::basic_json::parse', 'nlohmann::basic_json::parse'),
|
||||
]
|
||||
for input_str, expected in tests:
|
||||
result = strip_abi_tag(input_str)
|
||||
if result != expected:
|
||||
print(f"FAIL: strip_abi_tag('{input_str}') = '{result}', expected '{expected}'")
|
||||
return False
|
||||
print("Self-test passed: ABI-tag stripping works correctly")
|
||||
return True
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description='Extract public API surface from nlohmann/json')
|
||||
parser.add_argument('--header', default='include/nlohmann/json.hpp',
|
||||
help='Path to header file to analyze')
|
||||
parser.add_argument('--include', default='include',
|
||||
help='Include path for parsing')
|
||||
parser.add_argument('--output', default='api_snapshot.json',
|
||||
help='Output file for the full API snapshot (includes source location and '
|
||||
'documentation status -- for check_docs.py; not meant to be committed, '
|
||||
'since location/doc-link churn would make every regeneration look like '
|
||||
'an API change)')
|
||||
parser.add_argument('--surface-output', default=None,
|
||||
help='Output file for the minimal API surface (identity only: scope, name, '
|
||||
'kind, tier, pretty_signature -- no location or doc_url). This is the '
|
||||
'file meant to be committed and diffed release-to-release, since it is '
|
||||
'unaffected by unrelated code motion or documentation-site restructuring.')
|
||||
parser.add_argument('--self-test', action='store_true',
|
||||
help='Run self-tests and exit')
|
||||
parser.add_argument('--extra-isystem', action='append', default=[],
|
||||
help='Extra -isystem include path (repeatable)')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.self_test:
|
||||
sys.exit(0 if run_self_test() else 1)
|
||||
|
||||
if not setup_libclang():
|
||||
print("Error: Could not locate libclang library")
|
||||
sys.exit(1)
|
||||
|
||||
if not os.path.exists(args.header):
|
||||
print(f"Error: Header file not found: {args.header}")
|
||||
sys.exit(1)
|
||||
|
||||
print(f"Extracting API from {args.header}...")
|
||||
|
||||
# Discover system includes
|
||||
sys_includes = get_system_includes()
|
||||
if not sys_includes:
|
||||
print("Warning: Could not discover system includes via clang++")
|
||||
|
||||
# Build parse arguments
|
||||
parse_args = [
|
||||
f'-I{args.include}',
|
||||
'-std=c++17',
|
||||
'-x', 'c++',
|
||||
'-fparse-all-comments',
|
||||
] + sys_includes + [f'-isystem{path}' for path in args.extra_isystem]
|
||||
|
||||
# Parse
|
||||
index = cindex.Index.create()
|
||||
tu = index.parse(args.header, parse_args,
|
||||
options=cindex.TranslationUnit.PARSE_DETAILED_PROCESSING_RECORD)
|
||||
|
||||
# Check for errors
|
||||
errors = [d for d in tu.diagnostics if d.severity >= cindex.Diagnostic.Error]
|
||||
if errors:
|
||||
print("Parse errors encountered:")
|
||||
for diag in errors[:10]:
|
||||
print(f" {diag}")
|
||||
if len(errors) > 10:
|
||||
print(f" ... and {len(errors) - 10} more")
|
||||
sys.exit(1)
|
||||
|
||||
# Extract API
|
||||
public_classes = {'basic_json', 'adl_serializer', 'byte_container_with_subtype',
|
||||
'json_pointer', 'json_sax', 'ordered_map'}
|
||||
api_dict = {}
|
||||
documented_non_public = []
|
||||
|
||||
walk_ast(tu.cursor, public_classes, api_dict, documented_non_public)
|
||||
|
||||
# Output. Deliberately no timestamp here: this file is meant to be committed and diffed
|
||||
# (see tools/api_checker/README.md), so its content must be a pure function of the source
|
||||
# tree -- a generated-at timestamp would make every regeneration look like a diff.
|
||||
output = {
|
||||
'meta': {
|
||||
'extracted_from': canonicalize_path(os.path.abspath(args.header)),
|
||||
},
|
||||
'public_api': api_dict,
|
||||
'documented_non_public': documented_non_public,
|
||||
}
|
||||
|
||||
with open(args.output, 'w') as f:
|
||||
json.dump(output, f, indent=2, sort_keys=True)
|
||||
f.write('\n')
|
||||
|
||||
print(f"Found {len(api_dict)} public API entries")
|
||||
if documented_non_public:
|
||||
print(f"Found {len(documented_non_public)} entities with @sa outside the public surface")
|
||||
print(f"Wrote API snapshot to {args.output}")
|
||||
|
||||
if args.surface_output:
|
||||
write_surface(api_dict, args.surface_output, canonicalize_path(os.path.abspath(args.header)))
|
||||
print(f"Wrote API surface (location/doc-independent) to {args.surface_output}")
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
@@ -0,0 +1,50 @@
|
||||
# API surface history
|
||||
|
||||
One file per released `v3.*` tag: `<tag>.json`, e.g. `v3.12.0.json`. Each is the output of
|
||||
`extract_api.py --surface-output` at that tag (see `tools/api_checker/README.md` for the schema),
|
||||
with additional immutable provenance in `meta`: `ref`, `commit` (the tag's resolved commit sha),
|
||||
`generated_at`, and `generator`.
|
||||
|
||||
## Conventions
|
||||
|
||||
- **Immutable once committed.** Files here are never hand-edited or silently regenerated.
|
||||
`snapshot_release.py` refuses to overwrite an existing file unless `--force` is passed, and that
|
||||
should only happen for a deliberate, reviewed fix — the resulting diff should be inspected before
|
||||
committing, same as any other source change.
|
||||
- **Generated by `tools/api_checker/snapshot_release.py`**, run manually as part of cutting a
|
||||
release (see `tools/api_checker/README.md`'s "Workflow: Release Checklist"). Not CI-automated.
|
||||
- **`diff_api.py` uses these automatically.** `--old`/`--new` check here first (matching the ref
|
||||
string to `<ref>.json`) before falling back to live `git archive` extraction — see
|
||||
`tools/api_checker/README.md`'s `diff_api.py` section.
|
||||
|
||||
## Coverage
|
||||
|
||||
Backfilled: every `v3.*` tag from `v3.1.0` through the latest release at backfill time
|
||||
(`v3.12.0`), covering the full public API history of the `include/nlohmann/` header layout.
|
||||
|
||||
## Format history
|
||||
|
||||
- **`format_version: 2`** (current). Fixed `extract_api.py`'s `ABI_TAG_PATTERN` to also strip the
|
||||
pre-rename ABI inline-namespace form used by `v3.11.0`/`v3.11.1`: `json_v3_11_0` (no `_abi`
|
||||
segment), renamed to today's `json_abi_v3_11_2`-style tag starting with `v3.11.2`. Under
|
||||
`format_version: 1`, that older form wasn't recognized, so every `scope`/`signature` at
|
||||
`v3.11.0`/`v3.11.1` retained the raw un-stripped namespace segment, making `diff_api.py` report
|
||||
essentially the entire API (~330 of ~332 entries) as removed-and-readded across
|
||||
`v3.10.5`->`v3.11.0`->`v3.11.1`->`v3.11.2` — a bug of the same shape as the earlier USR-arity
|
||||
issue documented in `extract_api.py`'s `identity_key()` docstring, caught the same way: by
|
||||
actually diffing real consecutive release pairs instead of trusting the extractor in isolation.
|
||||
All 27 files were regenerated under `format_version: 2`; only `v3.11.0.json` and `v3.11.1.json`
|
||||
actually changed content (every other tag's scopes never contained the old-style tag).
|
||||
|
||||
## Known gaps
|
||||
|
||||
- **`v3.0.0`, `v3.0.1`**: not backfilled. These predate the `include/nlohmann/` directory
|
||||
structure entirely — headers lived under `src/` at that point (a single `src/json.hpp`). Since
|
||||
`extract_api.py` hardcodes `include/nlohmann/json.hpp` as the entry point,
|
||||
`snapshot_release.py --all-tags` fails cleanly on these two refs (`git archive ... -- include`
|
||||
finds nothing) rather than silently producing a wrong/empty result. Not pursued: two tags,
|
||||
immediately superseded by `v3.1.0`, and supporting the pre-restructuring layout would need a
|
||||
separate header/include-path convention with no other benefit. If full pre-3.1 coverage is ever
|
||||
wanted, `extract_api.py` would need a `src/json.hpp`-aware mode first.
|
||||
- Pre-`v3.0.0` tags (`v1.x`, `v2.x`, `v3.0.0-rc*`, etc.) were never attempted — out of scope for
|
||||
this backfill; see `tools/api_checker/POLICY.md` for the stated boundary.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1 @@
|
||||
libclang==18.1.1
|
||||
Executable
+106
@@ -0,0 +1,106 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Capture immutable, per-release API surface records into tools/api_checker/history/.
|
||||
|
||||
These are the durable, committed counterpart to diff_api.py's live git-archive-and-extract path:
|
||||
once a release is tagged, run this once to capture tools/api_checker/history/<tag>.json, commit
|
||||
it, and future diffs against that tag hit the fast, no-libclang-needed stored-file path in
|
||||
diff_api.py automatically. See tools/api_checker/README.md's "Workflow: Release Checklist" and
|
||||
POLICY.md for the full policy (manual step, not CI-automated; files are immutable once committed
|
||||
-- regenerate only via --force, and only as a deliberate, reviewed choice).
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import datetime
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
||||
HISTORY_DIR = os.path.join(SCRIPT_DIR, 'history')
|
||||
|
||||
sys.path.insert(0, SCRIPT_DIR)
|
||||
from diff_api import extract_surface_for_ref # noqa: E402
|
||||
|
||||
|
||||
def discover_v3_tags() -> list:
|
||||
"""List every v3.* git tag, sorted by dotted version (not lexicographically -- v3.9.0 must
|
||||
sort before v3.10.0)."""
|
||||
result = subprocess.run(['git', 'tag', '--list', 'v3.*'], capture_output=True, text=True, check=True)
|
||||
tags = [t for t in result.stdout.splitlines() if t.strip()]
|
||||
|
||||
def version_key(tag):
|
||||
parts = tag.lstrip('v').replace('-', '.').split('.')
|
||||
return tuple(int(p) if p.isdigit() else p for p in parts)
|
||||
|
||||
return sorted(tags, key=version_key)
|
||||
|
||||
|
||||
def snapshot_one(ref: str, output_dir: str, force: bool, header: str, include: str) -> tuple:
|
||||
"""Capture one ref's surface. Returns (ref, success, message)."""
|
||||
output_path = os.path.join(output_dir, f"{ref}.json")
|
||||
if os.path.exists(output_path) and not force:
|
||||
return ref, True, f"skipped (already exists at {output_path}; use --force to overwrite)"
|
||||
|
||||
try:
|
||||
surface = extract_surface_for_ref(ref, header, include)
|
||||
except SystemExit:
|
||||
return ref, False, "extraction failed (see output above)"
|
||||
except Exception as e: # noqa: BLE001 -- a batch backfill must not die on one bad tag
|
||||
return ref, False, f"unexpected error: {e}"
|
||||
|
||||
surface['meta']['generated_at'] = datetime.datetime.now(datetime.timezone.utc).isoformat()
|
||||
surface['meta']['generator'] = 'tools/api_checker/extract_api.py'
|
||||
|
||||
os.makedirs(output_dir, exist_ok=True)
|
||||
with open(output_path, 'w') as f:
|
||||
json.dump(surface, f, indent=2, sort_keys=True)
|
||||
f.write('\n')
|
||||
|
||||
return ref, True, f"{len(surface['public_api'])} entries -> {output_path}"
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description='Capture per-release API surface snapshots into tools/api_checker/history/')
|
||||
parser.add_argument('--ref', action='append', default=[],
|
||||
help='Git ref (tag) to snapshot; repeatable')
|
||||
parser.add_argument('--all-tags', action='store_true',
|
||||
help='Snapshot every v3.* tag (existing history files are skipped unless --force)')
|
||||
parser.add_argument('--output-dir', default=HISTORY_DIR,
|
||||
help='Directory to write history files into (default: tools/api_checker/history/)')
|
||||
parser.add_argument('--force', action='store_true',
|
||||
help='Overwrite an existing history file (history files are immutable by '
|
||||
'convention -- only pass this for a deliberate, reviewed regeneration)')
|
||||
parser.add_argument('--header', default='include/nlohmann/json.hpp')
|
||||
parser.add_argument('--include', default='include')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
refs = list(args.ref)
|
||||
if args.all_tags:
|
||||
refs = discover_v3_tags()
|
||||
|
||||
if not refs:
|
||||
parser.error('specify at least one --ref, or --all-tags')
|
||||
|
||||
print(f"Snapshotting {len(refs)} ref(s)...")
|
||||
results = []
|
||||
for ref in refs:
|
||||
print(f"\n=== {ref} ===")
|
||||
result = snapshot_one(ref, args.output_dir, args.force, args.header, args.include)
|
||||
print(result[2])
|
||||
results.append(result)
|
||||
|
||||
failures = [(ref, msg) for ref, ok, msg in results if not ok]
|
||||
print("\n" + "=" * 70)
|
||||
print(f"Done: {len(results) - len(failures)} succeeded, {len(failures)} failed")
|
||||
if failures:
|
||||
print("\nFailures (review and record accepted gaps in tools/api_checker/history/README.md):")
|
||||
for ref, msg in failures:
|
||||
print(f" {ref}: {msg}")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Reference in New Issue
Block a user