Found while implementing #1344 (PR #1532). Out of scope there — that PR does not touch scripts/check-source-token-ratchet.mjs at all, by design — so it is filed rather than fixed as a rider.
The claim, and why it is now false
scripts/check-source-token-ratchet.mjs ends with a comment enumerating its own consumers:
// Run only when invoked directly. `anchor`, `fmt`, `BUFFER` and the ceilings
// are importable so that every figure derived from a ceiling is DERIVED by
// the test quoting it rather than transcribed beside it:
// `test/source-token-ratchet.test.ts` sizes its fixtures from
// `CEILINGS`/`BUFFER` and pins the worked table in the header above against
// `anchor()`, and `test/docs-readme-token-figures.test.ts` reads the same two
// constants to check the README banner — so a re-anchoring moves the constant
// and the copies follow.
//
// Those two suites import nothing else from here, and need nothing else: the
// stripping rule and the verdict are exercised by RUNNING this file, not by
// importing it.
Measured on main at d9fad90, there are three ES importers of this module, not two:
| Importer |
Imports |
test/source-token-ratchet.test.ts:7 |
anchor, fmt, BUFFER, CEILINGS |
test/docs-readme-token-figures.test.ts:7 |
BUFFER, CEILINGS |
test/docs-object-term-consistency.test.ts:8 |
stripComments |
(test/script-main-guard.test.ts names the script by path only — it spawns it, it does not import it, so it is correctly outside this list.)
The third one landed with #802 as PR #1529. So both halves of the closing paragraph are now wrong: it is not two suites, and the stripping rule is exercised by importing it.
Why this is worth a card rather than a shrug
The sentence is not decoration — it is an instruction to the next maintainer about what is safe to change. It currently says stripComments has no importers and is only ever exercised by running the gate. A maintainer who believes that will change stripComments freely, and the thing that silently changes underneath them is the surface the Chinese-term guard scans — the guard standing between this repo and a drift class it has been bitten by repeatedly. A comment that misdescribes a module's consumers is at its most expensive on exactly the module whose consumers are load-bearing.
It is also the same defect class the ratchet suite exists to close, one level up: a fact about the producer, transcribed by hand beside it, with nothing holding the copy to the original.
Suggested shape (not a ruling)
- Correct the paragraph to name all three importers and what each takes, and drop the "not by importing it" claim about the stripping rule.
- Consider whether the list should be pinned rather than transcribed a second time —
test/source-token-ratchet.test.ts already reads the gate's source as text, so an assertion that the importers named in the footer equal the files that actually import the module is available without new machinery. Worth weighing against the cost of a pin on a comment; a maintainer call, not an obvious yes.
⛔ Scope note: scripts/check-source-hygiene.mjs (#1314 / #1339) is a different gate in a different file and is not involved here.
Generated by Claude Code
Found while implementing #1344 (PR #1532). Out of scope there — that PR does not touch
scripts/check-source-token-ratchet.mjsat all, by design — so it is filed rather than fixed as a rider.The claim, and why it is now false
scripts/check-source-token-ratchet.mjsends with a comment enumerating its own consumers:Measured on
mainatd9fad90, there are three ES importers of this module, not two:test/source-token-ratchet.test.ts:7anchor, fmt, BUFFER, CEILINGStest/docs-readme-token-figures.test.ts:7BUFFER, CEILINGStest/docs-object-term-consistency.test.ts:8stripComments(
test/script-main-guard.test.tsnames the script by path only — it spawns it, it does not import it, so it is correctly outside this list.)The third one landed with #802 as PR #1529. So both halves of the closing paragraph are now wrong: it is not two suites, and the stripping rule is exercised by importing it.
Why this is worth a card rather than a shrug
The sentence is not decoration — it is an instruction to the next maintainer about what is safe to change. It currently says
stripCommentshas no importers and is only ever exercised by running the gate. A maintainer who believes that will changestripCommentsfreely, and the thing that silently changes underneath them is the surface the Chinese-term guard scans — the guard standing between this repo and a drift class it has been bitten by repeatedly. A comment that misdescribes a module's consumers is at its most expensive on exactly the module whose consumers are load-bearing.It is also the same defect class the ratchet suite exists to close, one level up: a fact about the producer, transcribed by hand beside it, with nothing holding the copy to the original.
Suggested shape (not a ruling)
test/source-token-ratchet.test.tsalready reads the gate's source as text, so an assertion that the importers named in the footer equal the files that actually import the module is available without new machinery. Worth weighing against the cost of a pin on a comment; a maintainer call, not an obvious yes.⛔ Scope note:
scripts/check-source-hygiene.mjs(#1314 / #1339) is a different gate in a different file and is not involved here.Generated by Claude Code