test: hold README and CONTRIBUTING to the repository they describe - #72
Merged
Merged
Conversation
Extract every npm script, backtick path, coverage percentage and Node version the two documents name, and check each against package.json, the tree, vitest.config.ts and .nvmrc. The link lint already resolves Markdown links and anchors; this covers the claims that never sit inside one. README's Node and coverage lines were vague enough to dodge drift by never stating a number. Made them concrete so there is something to hold, and corrected the coverage sentence to say verify enforces the ratchet rather than test.
The gate landed in #69 but was left unwired while #23 split CI into one job per gate; per ADR 0102, a gate's script and its CI job belong in the same pull request, and test/pipeline-wiring.test.ts now proves it. lint:docs runs in the Contracts job beside the other document checks and in npm run verify. Refreshes README's coverage line, stale since the ratchet moved under it, and adds REQ-011 to the behaviour ledger. Coverage moved with lint-docs.ts entering the measured set: its three unreachable regex-capture fallbacks became one cast instead of dead branches, its one real fallback (a package.json with no scripts field) is now tested, and every threshold rose with what the suite reaches.
ExtraToast
added
type: test
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
1 participant
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.
Closes #69 (parent #21)
What this branch does
A gate holds
README.mdandCONTRIBUTING.mdto the repository, so the first documents a reader opens cannot drift from it in silence. Prose goes stale without a symptom: a renamed script, a coverage threshold that moved, a pinned Node version that changed. Each reads exactly as well wrong as right.scripts/lint-docs.tsextracts four kinds of claim and checks each against the thing it describes:npm run <name>and barenpm testagainst the scripts inpackage.json.vitest.config.ts..nvmrc.31 claims on the tree today: 5 scripts, 4 numbers, 1 version, 21 paths. The link gate already proves that relative links and anchors resolve, so this covers what it cannot see: names, numbers and versions.
The README's Node and coverage lines previously side-stepped the numbers ("the exact Node version in .nvmrc"). They now state them, which is what makes them checkable, and one claim was wrong and is corrected:
npm testdoes not enforce coverage,npm run test:coveragedoes.CONTRIBUTING.mdquotes no numbers or versions, and its scripts and paths already resolve.The gate runs in the
Contractsjob beside the ADR, link, manifest and requirements contracts, and innpm run verify. It carriesREQ-011in the behaviour ledger.One defect found on the way
The path extractor first paired backticks across fenced code blocks, which silently dropped five path claims and let a broken one pass. Fenced blocks are now stripped before pairing, the way
lint-links.tsdoes it, with a regression test.docs/architecture.mdsaid "Nine gates hold the structure" above a table listing thirteen. The prose now counts what the table holds.Ratchet
Statements 97.5 to 97.71, branches 88.79 to 89.78, functions 100, lines 97.26 to 97.51. Nothing moved down.
Three
match[1] ?? ""fallbacks came out rather than being covered by contrived tests. TypeScript types every capture group as optional, but a+quantified group in a successful match cannot be undefined, so the branch could not fire. They are onerequiredGroup()helper now. The fourth uncovered branch, apackage.jsonwith noscriptsfield, is genuinely reachable and got a test instead.Verification
Each acceptance criterion was broken on the rebased tree and restored:
verifyscript:README.md: names \npm run verify`, which is not a script in package.json`README.md: quotes statements coverage as 97.71%, but vitest.config.ts sets it to 90%.nvmrc:README.md: names Node 24.21.0, but .nvmrc pins 22.10.0CONTRIBUTING.md: names \docs/nonexistent-file.md`, which does not exist`npm run verifyclean, 219 tests.actionlint1.7.7, the version CI pins, clean.