docs: audit-overhaul — fix factual drift + version-string lifecycle#1015
Merged
Conversation
…book links Rebuild the README as the project's front door: a concrete pitch (metrics, languages, tree-sitter, fork lineage), a headline section on wiring bca check into Claude Code / opencode after-edit feedback loops, a quick start with the real install channels (signed release binaries, cargo install, pip install), CI gates with the live report links, and a condensed library section that links the book instead of replicating it. Fixes carried along: the wrong "1.x line" claim, the deprecated `bca report markdown` positional form, a dependency example pinning the unpublished 2.0.1 (now the major-line form `"2"`), the missing big-code-analysis-py entry in the license list, and the vague "Mozilla-defined grammars" phrase (the five vendored crates are now named). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Corrections from a three-agent audit of every prose doc, each finding verified against the code before fixing: - Versions: stale "1.x line" claims (RELEASING-adjacent docs, documentation.md); CI-recipe and dependency examples pinned the unpublished 2.0.1 whose download 404s, now pinned to the published 2.0.0 with the real SHA256SUMS digest; "Ast added in 0.0.26" was an upstream version leak (landed in 1.1.0). - Dead or wrong references: src/macros.rs links (now src/macros/mod.rs), commands/count.md and dump.md links (pages never existed), the nonexistent `bca nodes` subcommand, the dangling archive branch in the output-name-normalization postmortem. - Behaviour drift: file-detection.md BOM/UTF-8 validation and the 5-line mode-line window; retired Objective-C override contradiction; bus factor covers immediate subdirectories; report advisory cutoffs are manifest-overridable defaults; `--output` vs `--output-dir` on metrics/ops; tiered exit-code labels; "every subcommand takes positional paths" overclaim; stale variadic --include/--exclude warnings; `bca diff` --exit-code omission; retired vcs_metrics / vcs_trend / vcs_jit names (now vcs.rank/trend/commit/score_diff); pre-#958 SARIF description in the Python README and _native.pyi; "not yet published on PyPI" claim; CI-consumes-uv.lock passage. - Non-compiling book examples: u64/f64 type errors in in-memory.md and walking-funcspace.md, missing Result unwrap in reuse-tree.md (all now compile-verified). - Deprecated forms: recipes and migration examples moved off the positional `bca report markdown` to `-O`/`--format`; "removed in 2.0" promises reworded now that 2.0 shipped. - Indexes: Baselines recipe added to the recipes index; AST traversal and VCS chapters added to the Python chapter list; tree-sitter-tcl's no-regen-script status documented. - Style: em dashes removed from STABILITY.md, CONTRIBUTING.md, file-detection.md, and the normalization postmortem per the documentation convention; AGENTS.md no longer claims the project is Mozilla-maintained. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add a "Version strings in documentation" section defining when each
doc-borne version string moves, organized around the reader test ("if
someone copies this line today, does it resolve?"):
- Release-prep (before tagging vX.Y.Z): registry-resolvable pins
(STABILITY "(currently ...)" and exact-pin examples, the book's
dependency examples, the CHANGELOG section move), plus a scoped rg
sweep for stragglers and a warning against blind sed.
- Post-publish follow-up: every pin in recipes/ci.md, because the
BCA_SHA256 values cannot exist before sign-attest emits SHA256SUMS;
version and sha bump together.
- Post-tag next-version bump: manifests and man pages only; every
reader-facing pin stays at the published release.
- Never (outside a major bump): 2.x major-line strings, historical
records, illustrative placeholders, and the look-alike SemVer /
Keep-a-Changelog spec URLs.
Wired into the pre-release checklist and post-release verification.
Also carried in this file: the stale "pipeline is being built" status
block removed (three releases have shipped), "1.x line" corrected to
2.x, the known-issues section refreshed for its closed tracking issue,
and prose em dashes replaced per the documentation convention.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The deprecated aliases (--output-format, --ls/--le, the report positional FORMAT, the old --format/-O spellings on check) promised removal "in 2.0", but 2.0 shipped with the aliases still present. Say "the next major" instead so the help text cannot go stale the same way again. Man pages regenerated via cargo xtask in the same commit to keep the drift gate green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
in-memory.md, walking-funcspace.md, and reuse-tree.md shipped examples that did not compile (u64/f64 type errors, a missing Result unwrap). Mirror the fixed snippets into a cargo-tested module with exact-value anchors, following the book_ast_traversal_examples.rs pattern, so the next drift fails `cargo test` instead of a reader's copy-paste. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…atisfy fmt and clippy Three CI failures on this branch, one root cause each: - rustfmt: the new tests/book_library_examples.rs was committed unformatted (import ordering, line joins). Formatted. - clippy: collapsible_if on the mirrored hotspots example. Collapsed into an edition-2024 let-chain in both the test and the book's walking-funcspace.md so the mirror stays exact. - make lint (check-versions): the gate enforced the old convention, requiring doc snippets to cite the workspace version, which is exactly the convention this branch retires. Doc pins are now checked against the latest released `## [X.Y.Z]` section of CHANGELOG.md (readers deploy the published release; release-prep moves the changelog and the pins in one commit), and the recipes/ci.md install pins may lag one release because their paired BCA_SHA256 values only exist once the release publishes SHA256SUMS. Self-tests updated and extended (changelog parsing, lag-of-one allowance, prefix normalization); RELEASING.md's lockstep item 6 and the version-string policy section now name the gate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
dekobon
force-pushed
the
docs/audit-overhaul
branch
from
30cc454 to
2e8dfc4
Compare
CI's stable toolchain moved to 1.97, which flags two pre-existing spots under -D warnings: clippy::question_mark on the manual if-let/else parent walk in Node::get_parent (src/node.rs), and a redundant reference on a format! argument in the enums generator (enums/src/rust.rs). Behaviour unchanged; verified clean under both 1.97 and the 1.94 MSRV toolchain. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1015 +/- ##
=======================================
Coverage 98.03% 98.03%
=======================================
Files 267 267
Lines 65971 65968 -3
Branches 65541 65538 -3
=======================================
Hits 64673 64673
+ Misses 857 854 -3
Partials 441 441
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
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
2 participants
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.
Summary
Documentation-focused overhaul correcting factual drift across the root docs, the mdBook, and the Python bindings docs, plus a couple of small code/help-text fixes the doc audit surfaced. Every correction was verified against the code before being made.
Commits
bca checkinto Claude Code / opencode after-edit feedback loops, a real quick start (signed release binaries,cargo install,pip install), CI gates with live report links, and a condensed library section that links the book instead of duplicating it.1.x lineclaims, CI/dependency examples pinned to the unpublished 2.0.1 (404) now pinned to published 2.0.0 with the real SHA256SUMS digest, dead/wrong links and the nonexistentbca nodessubcommand, behaviour drift (BOM/UTF-8 detection, bus factor scope,--outputvs--output-dir, retiredvcs_*names →vcs.rank/trend/commit/score_diff, pre-output(sarif): py binding under-emits interior-space own-value breaches (wire shape lacks per-space own value) #958 SARIF text), non-compiling book examples now compile-verified, and em-dash style cleanup per the documentation convention.cargo xtaskin the same commit to keep the drift gate green.in-memory.md,walking-funcspace.md, andreuse-tree.mdshipped examples that did not compile; mirror the fixed snippets into a cargo-tested module with exact-value anchors so the next drift failscargo testinstead of a reader's copy-paste.Test plan
make pre-commit(fmt, clippy, tests, doc, man-page drift gate, self-scan, markdown lint)cargo test --workspace --all-features— exercises the newtests/book_library_examples.rs🤖 Generated with Claude Code