From fd2ea143f6b47564bfc2dac44ab9438a54b79790 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 11:03:12 +0000 Subject: [PATCH] fix(check-doc-anchors): spell the heading-ids remedy so it cannot be read as a watch-hint declaration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The remedy line printed for a broken anchor is a command for a human to paste at the repo root, and it carried the module specifier as a quoted relative literal `'./scripts/check-doc-anchors.mjs'`. The dispatch watch-hint extractor reads quoted path-shaped literals in a gate's module body and resolves the relative ones against the writer's own directory, so this gate — which lives in scripts/ — declared a path that has never existed on this tree, and that lead was pasted into every dispatch prompt the family matched. Neither half was wrong on its own; the fabrication came from prose being read as a declaration. Tightening the reader was measured and refused upstream, so the producer spells the path absolutely instead: process.cwd() + a leading-slash literal, which the extractor's admission test refuses outright while the command stays runnable verbatim from the repo root. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC --- scripts/check-doc-anchors.mjs | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/scripts/check-doc-anchors.mjs b/scripts/check-doc-anchors.mjs index 9f85825e42..cb30a9f975 100644 --- a/scripts/check-doc-anchors.mjs +++ b/scripts/check-doc-anchors.mjs @@ -456,7 +456,30 @@ function runCheck() { '\n\n The heading id is computed with `github-slugger`, the same package\n' + ' fumadocs-core uses to render the page, so what this gate says the anchor is\n' + ' is what the site says it is. Print a page\'s real ids with:\n' + - " node -e \"import('./scripts/check-doc-anchors.mjs').then(m=>console.log(m.headingIds(require('node:fs').readFileSync('','utf8')).join('\\n')))\"\n" + + // ⚠️ The specifier below is spelled ABSOLUTE — `process.cwd()+'/scripts/…'` — and that is + // load-bearing rather than style. This line is a REMEDY: prose for a human, to be pasted + // into a shell already sitting at the repo root. Spelled the natural way, as a quoted + // `./scripts/…` literal, it is ALSO a well-formed watch-hint DECLARATION to the dispatch + // derivation, which scans a gate's module body for quoted path-shaped literals and + // resolves the relative ones against the directory of the file that WROTE them. This gate + // lives in `scripts/`, so a literal written in the ROOT frame came back with its own + // directory prepended — a lead naming a path that has never existed on this tree, pasted + // into every dispatch prompt whose file surface brushes this family, and indistinguishable + // there from a real one. + // + // Neither half was wrong on its own: the remedy is correct for its reader and the extractor + // is correct about a declaration — the fabrication came from one being read as the other. + // Tightening the reader was measured and REFUSED (#13312: the sanctioned declaration idiom + // is structurally indistinguishable from an incidental module-scope constant, priced at 8.6 + // real populations deleted per fabrication removed), so the repair belongs to the PRODUCER: + // spell the path so it cannot be read as a declaration. The leading `/` inside the quotes is + // the whole mechanism — the extractor's admission test requires a literal to begin with a + // word character, `.` or `@`, so an absolute path is refused outright — and `process.cwd()` + // is what keeps the command runnable verbatim from the repo root, which is the only reason a + // remedy line exists. ⛔ Do not "tidy" it back to a quoted relative specifier. What this gate + // really reads is declared above and deliberately, in `CONTENT_GLOB` and + // `ROOT_FILE_WATCH_HINTS` (#13449). + " node -e \"import(process.cwd()+'/scripts/check-doc-anchors.mjs').then(m=>console.log(m.headingIds(require('node:fs').readFileSync('','utf8')).join('\\n')))\"\n" + ' Fix the link, or fix the heading. Do not add an exemption — an anchor that\n' + ' nobody may check is the defect this gate exists to remove (#7484).', );