5b3618d0d6
Applying last tick's lesson -- grep for the class, not the instance -- found a third surface teaching the old serve command. README-SECTION-3-cli-commands.md transcribes the package.json scripts so a reader need not open the file, and it still showed python3 -m http.server two commits after serve became serve-strict.mjs. An inheritor following the CLI reference would have started the permissive server, the one whose forgiveness hid a URL bug in two gates for a whole flight. Measured before fixing: ten quoted scripts, nine matching, exactly one drifted. I had expected build:unlocked to be stale too and it is not -- the doc truncates it rather than misquoting it, which is the right call for a seven-hundred-character line. Hand-fixing the one line would leave the next script change to rot the same way, so the doc is now checked. The comparison is loose in the three ways a human-facing doc needs: package.json's trailing hash comments are ignored, the doc's own slash-slash annotations are ignored, and truncation passes on a prefix match either way. A quoted script that does not exist in package.json is a hard failure, since that is a command someone would type and get "script not found". Completeness is deliberately not asserted; the doc is a curated subset and demanding otherwise would make it churn on every internal gate. Self-test poisons the doc in memory two ways, a changed body and a nonexistent script name, and requires both to be caught. Both are. Full build passes with the gate in the chain.
114 lines
6.1 KiB
JavaScript
114 lines
6.1 KiB
JavaScript
#!/usr/bin/env node
|
|
/**
|
|
* check-doc-quotes-scripts.mjs — a doc that QUOTES package.json must still match it.
|
|
*
|
|
* THE DEFECT THIS CATCHES, found 2026-09-23. documentation/README-SECTION-3-cli-commands.md
|
|
* transcribes the package.json scripts verbatim so a reader can see them without opening the file.
|
|
* That is a genuinely useful doc and a copy that can never stay true on its own: `bun run serve` was
|
|
* changed from `python3 -m http.server` to `node internal/serve-strict.mjs` two commits earlier, and
|
|
* the doc still taught the old one. An inheritor following the CLI reference would have started the
|
|
* PERMISSIVE server — the one whose forgiveness hid a URL bug in two gates for a whole flight.
|
|
*
|
|
* ★ WHY A GATE AND NOT JUST THE FIX. The repo already carries
|
|
* AP-a-doc-that-QUOTES-a-config-file-silently-stops-matching-it. Hand-fixing this instance leaves
|
|
* the NEXT script change to rot the same way, silently, because nothing reads the doc. It is the
|
|
* same answer the repo reached for capability exemplars: prose that cites a checkable source can be
|
|
* checked; prose that cites memory cannot.
|
|
*
|
|
* WHAT IT ASSERTS. Every `"name": "body"` line in the doc that names a REAL package.json script must
|
|
* agree with it. Comparison is deliberately loose in three ways, because the doc is for humans:
|
|
* - a trailing `# …` comment in package.json is ignored (several scripts carry long explanations);
|
|
* - a trailing `// …` comment in the DOC is ignored (the doc annotates some entries);
|
|
* - the doc may TRUNCATE a long script, so a prefix match in either direction passes. build:unlocked
|
|
* is ~700 characters and no reader wants it in full; what matters is that the part shown is true.
|
|
* A name the doc quotes that does NOT exist in package.json is a hard failure — that is a command an
|
|
* inheritor would type and get "script not found".
|
|
*
|
|
* NOT ASSERTED: that every script is documented. The doc is a curated subset by design, and demanding
|
|
* completeness would make it churn on every internal gate added.
|
|
*
|
|
* NEGATIVE-TESTED via `--self-test`: poisons the doc in memory two ways (a changed body, and a script
|
|
* name that does not exist) and requires both to be caught. In-memory so a crash cannot leave the
|
|
* tree edited.
|
|
*/
|
|
import { readFileSync } from 'node:fs'
|
|
import { resolve, dirname, join } from 'node:path'
|
|
import { fileURLToPath } from 'node:url'
|
|
|
|
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
|
|
const DOC = join(ROOT, 'documentation/README-SECTION-3-cli-commands.md')
|
|
const REL = 'documentation/README-SECTION-3-cli-commands.md'
|
|
|
|
const fail = (m) => { console.error('DOC-QUOTES-SCRIPTS: FAIL — ' + m); process.exit(1) }
|
|
|
|
// Strip what is presentational rather than semantic: package.json's inline `#` notes and the doc's
|
|
// `//` annotations. Both are explanation, not command.
|
|
const norm = (s) => s.split(/\s+#\s/)[0].split(/\s+\/\/\s/)[0].trim().replace(/,$/, '').trim()
|
|
|
|
function audit(docText, scripts) {
|
|
const problems = []
|
|
const quoted = [...docText.matchAll(/^"([a-z0-9:_-]+)":\s*"((?:[^"\\]|\\.)*)"/gm)]
|
|
if (!quoted.length) {
|
|
problems.push('found 0 quoted `"name": "body"` lines in ' + REL + '.\n' +
|
|
' A gate with nothing to assert is not passing; it is not running. If the doc was restructured,\n' +
|
|
' update this gate in the same commit.')
|
|
return { problems, checked: 0 }
|
|
}
|
|
|
|
let checked = 0
|
|
for (const m of quoted) {
|
|
const name = m[1]
|
|
const shown = norm(m[2].replace(/\\"/g, '"'))
|
|
if (!(name in scripts)) {
|
|
problems.push(`${REL} quotes a script that does NOT EXIST: "${name}".\n` +
|
|
' An inheritor typing it gets "script not found". Remove it or add it to package.json.')
|
|
continue
|
|
}
|
|
checked++
|
|
const real = norm(scripts[name])
|
|
// The doc may truncate a long script; a prefix match in either direction is fine.
|
|
const head = Math.min(30, shown.length, real.length)
|
|
if (head > 0 && (real.startsWith(shown.slice(0, head)) || shown.startsWith(real.slice(0, head)))) continue
|
|
problems.push(`${REL} — "${name}" no longer matches package.json.\n` +
|
|
` doc : ${shown.slice(0, 70)}\n` +
|
|
` real: ${real.slice(0, 70)}\n` +
|
|
' The doc transcribes package.json so a reader need not open it, which means it rots on every\n' +
|
|
' script change unless something checks it. Update the doc, not this gate.')
|
|
}
|
|
return { problems, checked }
|
|
}
|
|
|
|
const scripts = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).scripts || {}
|
|
|
|
if (process.argv.includes('--self-test')) {
|
|
const original = readFileSync(DOC, 'utf8')
|
|
if (audit(original, scripts).problems.length) {
|
|
console.error('DOC-QUOTES-SCRIPTS SELF-TEST: FAIL — the tree is already failing; fix that first.')
|
|
process.exit(1)
|
|
}
|
|
const cases = [
|
|
['body-drifted', (s) => s.replace(/^"serve":\s*"[^"]*"/m, '"serve": "python3 -m http.server 4173"')],
|
|
['script-does-not-exist', (s) => s.replace(/^"dev":/m, '"dveloop":')],
|
|
]
|
|
let bad = 0
|
|
for (const [name, poison] of cases) {
|
|
const mutated = poison(original)
|
|
if (mutated === original) { console.error(` ${name}: POISON DID NOT APPLY — the case proves nothing.`); bad++; continue }
|
|
const caught = audit(mutated, scripts).problems.length > 0
|
|
console.log(` ${name}: ${caught ? 'caught' : 'NOT CAUGHT'}`)
|
|
if (!caught) bad++
|
|
}
|
|
if (bad) { console.error(`DOC-QUOTES-SCRIPTS SELF-TEST: FAIL — ${bad} case(s) not caught.`); process.exit(1) }
|
|
console.log('DOC-QUOTES-SCRIPTS SELF-TEST: PASS — both regressions caught; tree untouched (poisoned in memory).')
|
|
process.exit(0)
|
|
}
|
|
|
|
const { problems, checked } = audit(readFileSync(DOC, 'utf8'), scripts)
|
|
if (problems.length) {
|
|
console.error(`DOC-QUOTES-SCRIPTS: FAIL — ${problems.length} problem(s).\n`)
|
|
for (const p of problems) console.error(' ✗ ' + p + '\n')
|
|
process.exit(1)
|
|
}
|
|
console.log(`DOC-QUOTES-SCRIPTS: PASS — ${checked} quoted script(s) match package.json.`)
|
|
console.log(' Truncation is allowed (build:unlocked is ~700 chars); what is SHOWN must be true.')
|
|
console.log(' Completeness is deliberately not asserted — the doc is a curated subset.')
|