chore: pin the counts quoted in prose to the generated figures - #9
Merged
Conversation
Cargo.toml claimed 6,365 public functions across 71 modules. 6,365 is the sum of the map's functions and methods, and 71 is the public top-level count, not the module count -- so both halves named the wrong thing. It is 4,124 functions across 295 modules. That string is what crates.io renders and cannot be edited once a version is published. check_counts.py reads the two files that already derive counts and are already kept current by CI -- docs/MODULE_MAP.md and the generator's COVERAGE.md -- and checks every hand-written figure against whichever of them owns it. The two disagree by design: the map counts a macro-generated item once, the generator counts what it emitted. Also corrects "296 modules" to 295 in the bindings README, and replaces "4,000+ validated functions" in pyproject.toml with the 4,086 the generator actually bound.
There was a problem hiding this comment.
🟢 Approval recommended
The changes correctly align quoted figures with the generated sources and add CI enforcement, with only minor robustness/wording nits noted.
Pull request overview
Adds an automated checker that verifies numeric counts quoted in prose (e.g., Cargo.toml, Python metadata, READMEs) against the two generated “source of truth” documents, and updates the currently incorrect quoted figures so published package descriptions don’t drift.
Changes:
- Introduces
tools/check_counts.pyto validate prose-quoted counts againstdocs/MODULE_MAP.mdandbindings/python/COVERAGE.md. - Updates package metadata prose to the correct generated figures (Rust crate description and Python package description).
- Adds the new count-check step to the main CI workflow.
File summaries
| File | Description |
|---|---|
| tools/check_counts.py | New checker to pin prose-quoted counts to generated figures and fail CI on drift/missing claims. |
| Cargo.toml | Fixes crates.io-rendered description counts to match docs/MODULE_MAP.md. |
| bindings/python/README.md | Corrects the quoted module count in the “What is not bound” prose. |
| bindings/python/pyproject.toml | Pins the Python package description to the bound function count. |
| .github/workflows/ci.yml | Runs the new quoted-count checker in CI. |
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+32
to
+34
| def read(rel: str) -> str: | ||
| with open(os.path.join(ROOT, rel), encoding="utf-8") as fh: | ||
| return fh.read() |
Comment on lines
+93
to
+97
| # The counts quoted in Cargo.toml, pyproject.toml and the READMEs are | ||
| # written by hand from the two generated files above. This pins them | ||
| # to those files, so a library that grows fails the build instead of | ||
| # shipping a stale figure to a registry, where the description of a | ||
| # published version cannot be edited. |
crates-release.yml was 46 comment lines against 48 of YAML. What is left is the two things reading the file cannot tell you: the trusted publisher is keyed to this filename, and the dispatch input exists for tags older than the file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cargo.tomlclaimed 6,365 public functions across 71 modules. Both halves named the wrong thing: 6,365 is functions plus methods, and 71 is the public top-level count, not the module count. It is 4,124 functions across 295 modules. That string is what crates.io renders, and a published version's description cannot be edited — 0.2.0 is stuck with the wrong one, 0.3.0 won't be.Why a checker rather than a generator
Two files already derive counts, and CI already keeps both current:
docs/MODULE_MAP.mdgen_module_map.pybindings/python/COVERAGE.mdgenerate.pyThey disagree, correctly — the map counts a macro-generated item once because it appears once in source; the generator counts what it emitted, so
unit_ctor!shows up as its thirty constructors.check_counts.pytherefore pins each claim to whichever file owns it, instead of forcing one number everywhere.Prose is checked, not rewritten: the sentence around a figure usually has to change with it, and a machine can't write that sentence.
Also corrected
bindings/python/README.md— "296 modules" → 295 (296 is the file count, which includessrc/lib.rs).pyproject.toml— "4,000+ validated functions" → the 4,086 the generator actually bound.Deliberately left alone
README.md:39's "20,200 functions" is llvm-cov's function-coverage denominator, which counts generic instantiations and private functions. Different metric, correctly stated.Verified
19 claims pass. Three negative controls, each confirmed to fail:
The third matters most: a checker that silently passes when its target disappears is worse than no checker.