enhance(#2778): make the size-ratchet failure name its own remedy (#2780)

* fix(#2778): exempt intentionally-absent paths from the glossary gate

check-glossary-refs asserts that every backticked tests/ token in
CONTEXT.md resolves on disk. tests/emitted-drift-ack.json (ADR-2719
section 3) is absent on a healthy next BY DESIGN — it appears only
inside a PR that needs it, which is what makes touching it the alarm.

It passed before only by accident of backtick pairing: CONTEXT.md's
RULESET entries are themselves backtick-wrapped and contain backticks,
so the token happened to fall outside a code span. Any edit that
shifted the parity exposed it. A gate that passes by luck is not
passing.

The exemption is exact, not a prefix hole: a sibling missing tests/
path still fails, and a test locks that.

* feat(#2778): make the size-ratchet failure name its own remedy

The growth branch stated a requirement and withheld the means of
satisfying it: no ack file named, no schema, no key format, and no
do-not-regenerate line — so the likeliest guess was to hunt for a
baseline that #2724 deleted. Observed live on #2543.

All remediation now comes from one frozen REMEDIATION export whose
example document is rendered from ACK_VERSION, so the taught schema
cannot drift from the schema parseAck accepts. A round-trip test feeds
the printed document back through parseAck.

The report is now built as a typed IR (buildReport) that formatReport
renders, so tests assert on structure rather than prose, per
CONTRIBUTING.md's raw-text-matching rule.

Two defects found and fixed inline while building:
- diffEmitted's validation early-return omitted newFileCapExceeded
  while formatReport reads its length, so the branch that reports a
  failed git diff threw a TypeError instead of naming the problem.
- Printing one complete ack document per failing branch made each read
  as the whole file, so pasting the second over the first silently lost
  an acknowledgment. One document now covers the whole report.

Closes #2778

* chore(#2778): backfill changeset pr number to 2780
This commit is contained in:
Tom Boucher
2026-07-28 18:26:55 -04:00
committed by GitHub
parent 0997d4f443
commit e276cc7f00
8 changed files with 546 additions and 8 deletions

View File

@@ -64,6 +64,29 @@ const TRACKED_PREFIXES = [
/** The only bare (no-prefix-match) tokens this gate checks by exact name. */
const TRACKED_EXACT = new Set(['bin/install.js', 'package.json']);
/**
* Paths CONTEXT.md documents whose ABSENCE is the healthy steady state (#2778).
*
* `TRACKED_PREFIXES` skips claims this gate *cannot* check. This is the narrower
* third case: a claim it must not check, because "does not exist" is the correct
* state rather than drift.
*
* `tests/emitted-drift-ack.json` is the acknowledgment file from ADR-2719 §3. Its
* whole design property is that it appears in the changed-files list ONLY when
* something rippled unexpectedly — "touching it IS the alarm". A permanently
* committed copy would signal nothing, which is exactly why the ADR rejected
* shipping an empty stub. So the file is absent on a healthy `next` and present
* only inside a PR that needs it, and asserting either way is wrong.
*
* Until #2778 this passed only by accident: CONTEXT.md's `RULESET.` entries are
* themselves backtick-wrapped and contain backticks, so the sequential pairing in
* `extractTrackedRefs` happened to leave this token outside a code span. Any edit
* that shifted the parity — such as #2778's own — exposed it. A gate that passes
* by luck is not passing; naming the exemption makes the intent explicit and
* survives the next edit.
*/
const INTENTIONALLY_ABSENT = new Set(['tests/emitted-drift-ack.json']);
/**
* Shape a backticked token must have to even be considered a path candidate:
* one or more `/`-separated segments of word/dot/dash characters, with an
@@ -75,6 +98,7 @@ const PATH_TOKEN_RE = /^[\w.-]+(?:\/[\w.-]+)*(?::\d+)?$/;
/** Whether `token` (line-suffix already stripped) is one this gate checks. */
function isTracked(token) {
if (INTENTIONALLY_ABSENT.has(token)) return false;
return TRACKED_EXACT.has(token) || TRACKED_PREFIXES.some((prefix) => token.startsWith(prefix));
}