Skip to content

Commit 3f3c906

Browse files
authored
test(docs): fail when a subsystem doc names a repo path that does not exist (#2910)
Fixes #2906 `core/test/check-doc-paths.test.js` judged inline-code repo paths on the two root READMEs only, so `docs/**` was never read: on 2026-11-11 ten backticked paths across four subsystem docs still named files #2830 had moved into `plugins/project/` (#2895), and a reader who followed one landed on a missing file while the suite stayed green. #2897 repointed those ten but added no guard, so the same rot can land again silently. This adds `docTreeMisses()`, which scans `docs/**/*.md` and reports a backticked token as a miss only when it opens with `core/`, `plugins/` or `patches/` and ends in a code or document extension — the narrow rule that found exactly those ten misses on the tree and nothing else, so no allowlist is needed (#1403). A second, constructed case pins the four shapes that are *not* repo-path claims (package-relative `scripts/check-arch-docs.mjs`, tool/branch names `plugins/list` and `dev/bench.sh`, another repository's `docs/FACE_ROOMS.md`, an example traversal `decisions/../outside.md`), keeps fenced blocks out, and requires one genuine miss (`plugins/project/src/project-board.js` in the synthetic tree) to be reported. ### Red first The tree is green once #2897 landed, so the red is a mutation: with `docs/subsystems/core-host.md:241` put back to the old `core/src/host/project-board.js`, the real-tree case fails on exactly that line — ``` docs/subsystems/core-host.md:241: core/src/host/project-board.js ``` Restored, 4/4 pass twice. ### What I ran - `core/test/check-doc-paths.test.js` alone: 4/4 green twice; once with the mutation above, red on `core-host.md:241`. - The same scan over the tree at this tip: 42 documents, 0 misses. - `node scripts/ds-bot-patches.mjs generate` then `check` — `ok 10 patches apply cleanly in order`, `ok core/ equals ds-bot/ + patches/ds-bot/`; the mirror `patches/ds-bot/files/test/check-doc-paths.test.js` is the only generated entry. - `TZ=UTC npm run verify` — green (`EXIT=0`). - `node core/scripts/check-arch-docs.mjs` with `ARCH_DOCS_BASE=f9ce2a48141fbf5ae0e49e6f9f9feb37eba65fa6` — `arch-docs: OK (3 changed file(s))` on the committed tree. - `node .github/scripts/changelog.mjs check` — `27 fragment(s) in changelog.d/ are well formed`. Not run: `smoke` — it cannot start in this checkout (`EROFS` symlinking the pnpm store into `.dsh-test-smoke`), so it is skipped rather than counted green. No `core/client.js` and no `*.patch` file is touched: the only generated entry is the updated test mirror, which the `core/ equals ds-bot/ + patches/` check requires. Owner: Dev-1 Reviewer: Birfy Written-by: Dev-1 Bot: Dev-1 Claim-Id: e010e841df044e14ad628dd863fd9b8d Risk tier: T1 (`core/test/**`, `patches/**`, `changelog.d/**`) Base: `f9ce2a48141fbf5ae0e49e6f9f9feb37eba65fa6` (live `main` at push time) Verified commit: `85598ef21a4771ac98ef79861e4390664b69cf01` (tree `ff244f11fd06e5d542ffbd5b03be89d5dc06d3c5`), pushed head is generated from that tree by the push path ## Checkpoint <!-- flybot:checkpoint --> ```json { "pr": 2910, "claim": "Dev-1", "issue": 2906, "summary": "The repo-path guard now reads docs/**/*.md: a backticked core/, plugins/ or patches/ path ending in a code or document extension that does not exist fails the suite, so a subsystem doc that keeps naming a moved file is caught. The narrow rule finds zero misses on today's tree and exactly the ten #2897 fixed; a constructed case keeps package-relative, tool/branch, cross-repository and example tokens out and reports one real miss. Mutation of one doc path back to its old value is the red.", "files": [ "core/test/check-doc-paths.test.js", "changelog.d/2906-doc-tree-paths.changed.md", "patches/ds-bot/files/test/check-doc-paths.test.js" ], "checks": { "ran": "the test file alone twice green, once with the mutation red; docs scan over the tree; ds-bot-patches generate+check; TZ=UTC npm run verify; arch-docs; changelog check", "result": "green", "at": "85598ef21a4771ac98ef79861e4390664b69cf01" }, "next": "none — ready for review" } ``` <!-- /flybot:checkpoint -->
1 parent 84a7868 commit 3f3c906

3 files changed

Lines changed: 141 additions & 2 deletions

File tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
The repo-path guard now reads the docs tree: a backticked `core/`, `plugins/` or `patches/` path with a code or document extension that does not exist on disk fails the suite, so a subsystem doc that keeps pointing at a moved file is caught instead of read.

‎core/test/check-doc-paths.test.js‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
// inline paths relative to their own package or to the runtime home, so judging them against the repo
55
// root reports paths that are not broken. #1403 allows narrowing the file list; it forbids an allowlist.
66
import assert from 'node:assert/strict'
7-
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
7+
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
88
import { tmpdir } from 'node:os'
99
import { join } from 'node:path'
1010
import { test } from 'node:test'
@@ -48,6 +48,49 @@ export function docPathMisses(root = ROOT, documents = DOCUMENTS) {
4848
return misses
4949
}
5050

51+
// Subsystem docs name repo files too, and those rot the same way: on 2026-11-11 ten backticked paths
52+
// across four docs still named files #2830 had moved into `plugins/project/`, and nothing read them
53+
// (#2895). Judging every backticked token against the repo root is not the answer — `docs/**` also
54+
// writes paths relative to its own package, to the runtime home, to another repository and as
55+
// examples, and #1403 forbids an allowlist. So a token claims a repo path only when it opens with one
56+
// of the top-level code directories and ends in a code or document extension; that rule found exactly
57+
// those ten misses when it was written and nothing else on the tree.
58+
const CODE_ROOTS = ['core', 'plugins', 'patches']
59+
const FILE_ENDING = /\.(?:js|mjs|cjs|json|md|ts|yml|yaml|sh|css|html|patch|txt)$/
60+
61+
export function isDocRepoPath(token) {
62+
if (!token.includes('/') || /\s/.test(token)) return false
63+
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(token)) return false // URL
64+
if (/[*<>{}[\]`]/.test(token)) return false // glob or placeholder
65+
const [first] = token.split('/')
66+
return CODE_ROOTS.includes(first) && FILE_ENDING.test(token)
67+
}
68+
69+
export function docTreeDocuments(root = ROOT) {
70+
return readdirSync(join(root, 'docs'), { recursive: true })
71+
.filter(name => String(name).endsWith('.md'))
72+
.map(name => `docs/${String(name).split('\\').join('/')}`)
73+
.sort()
74+
}
75+
76+
// Every backticked token outside a fenced block that claims a repo path but misses on disk.
77+
export function docTreeMisses(root = ROOT, documents = docTreeDocuments(root)) {
78+
const misses = []
79+
for (const file of documents) {
80+
let fenced = false
81+
readFileSync(join(root, file), 'utf8').split('\n').forEach((line, index) => {
82+
if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; return }
83+
if (fenced) return
84+
for (const [, token] of line.matchAll(/`([^`]+)`/g)) {
85+
const path = token.trim().replace(/\/+$/, '')
86+
if (!isDocRepoPath(path) || existsSync(join(root, path))) continue
87+
misses.push(`${file}:${index + 1}: ${token.trim()}`)
88+
}
89+
})
90+
}
91+
return misses
92+
}
93+
5194
test('every repo path named in inline code on the root READMEs exists on disk', () => {
5295
assert.deepEqual(docPathMisses(), [])
5396
})
@@ -71,3 +114,29 @@ test('the tokenizer skips refs, URLs, globs, placeholders, npm scopes and absolu
71114
].join('\n'))
72115
assert.deepEqual(docPathMisses(root, ['README.md']), ['README.md:9: dev/nope'])
73116
})
117+
118+
test('every repo path a subsystem doc names under core/, plugins/ or patches/ exists on disk', () => {
119+
assert.deepEqual(docTreeMisses(), [])
120+
})
121+
122+
test('the doc scan keeps the four shapes that are not repo paths, and names a real miss', (t) => {
123+
const root = mkdtempSync(join(tmpdir(), 'doc-tree-paths-'))
124+
t.after(() => rmSync(root, { recursive: true, force: true }))
125+
mkdirSync(join(root, 'core', 'test'), { recursive: true })
126+
mkdirSync(join(root, 'docs', 'subsystems'), { recursive: true })
127+
writeFileSync(join(root, 'core', 'test', 'here.test.js'), '// here\n')
128+
writeFileSync(join(root, 'docs', 'subsystems', 'core.md'), [
129+
'A fenced block is prose, not a claim:',
130+
'```',
131+
'core/test/gone-in-a-fence.test.js',
132+
'```',
133+
'Real: `core/test/here.test.js`, `plugins/project/src/project-board.js` (missing).',
134+
'Package-relative, so not a repo path: `scripts/check-arch-docs.mjs`.',
135+
'Tool names and branch names: `plugins/list`, `dev/bench.sh`.',
136+
'Another repository: `docs/FACE_ROOMS.md`.',
137+
'An example of a traversal: `decisions/../outside.md`.',
138+
].join('\n'))
139+
assert.deepEqual(docTreeMisses(root, ['docs/subsystems/core.md']), [
140+
'docs/subsystems/core.md:5: plugins/project/src/project-board.js',
141+
])
142+
})

‎patches/ds-bot/files/test/check-doc-paths.test.js‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
// inline paths relative to their own package or to the runtime home, so judging them against the repo
55
// root reports paths that are not broken. #1403 allows narrowing the file list; it forbids an allowlist.
66
import assert from 'node:assert/strict'
7-
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
7+
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
88
import { tmpdir } from 'node:os'
99
import { join } from 'node:path'
1010
import { test } from 'node:test'
@@ -48,6 +48,49 @@ export function docPathMisses(root = ROOT, documents = DOCUMENTS) {
4848
return misses
4949
}
5050

51+
// Subsystem docs name repo files too, and those rot the same way: on 2026-11-11 ten backticked paths
52+
// across four docs still named files #2830 had moved into `plugins/project/`, and nothing read them
53+
// (#2895). Judging every backticked token against the repo root is not the answer — `docs/**` also
54+
// writes paths relative to its own package, to the runtime home, to another repository and as
55+
// examples, and #1403 forbids an allowlist. So a token claims a repo path only when it opens with one
56+
// of the top-level code directories and ends in a code or document extension; that rule found exactly
57+
// those ten misses when it was written and nothing else on the tree.
58+
const CODE_ROOTS = ['core', 'plugins', 'patches']
59+
const FILE_ENDING = /\.(?:js|mjs|cjs|json|md|ts|yml|yaml|sh|css|html|patch|txt)$/
60+
61+
export function isDocRepoPath(token) {
62+
if (!token.includes('/') || /\s/.test(token)) return false
63+
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(token)) return false // URL
64+
if (/[*<>{}[\]`]/.test(token)) return false // glob or placeholder
65+
const [first] = token.split('/')
66+
return CODE_ROOTS.includes(first) && FILE_ENDING.test(token)
67+
}
68+
69+
export function docTreeDocuments(root = ROOT) {
70+
return readdirSync(join(root, 'docs'), { recursive: true })
71+
.filter(name => String(name).endsWith('.md'))
72+
.map(name => `docs/${String(name).split('\\').join('/')}`)
73+
.sort()
74+
}
75+
76+
// Every backticked token outside a fenced block that claims a repo path but misses on disk.
77+
export function docTreeMisses(root = ROOT, documents = docTreeDocuments(root)) {
78+
const misses = []
79+
for (const file of documents) {
80+
let fenced = false
81+
readFileSync(join(root, file), 'utf8').split('\n').forEach((line, index) => {
82+
if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; return }
83+
if (fenced) return
84+
for (const [, token] of line.matchAll(/`([^`]+)`/g)) {
85+
const path = token.trim().replace(/\/+$/, '')
86+
if (!isDocRepoPath(path) || existsSync(join(root, path))) continue
87+
misses.push(`${file}:${index + 1}: ${token.trim()}`)
88+
}
89+
})
90+
}
91+
return misses
92+
}
93+
5194
test('every repo path named in inline code on the root READMEs exists on disk', () => {
5295
assert.deepEqual(docPathMisses(), [])
5396
})
@@ -71,3 +114,29 @@ test('the tokenizer skips refs, URLs, globs, placeholders, npm scopes and absolu
71114
].join('\n'))
72115
assert.deepEqual(docPathMisses(root, ['README.md']), ['README.md:9: dev/nope'])
73116
})
117+
118+
test('every repo path a subsystem doc names under core/, plugins/ or patches/ exists on disk', () => {
119+
assert.deepEqual(docTreeMisses(), [])
120+
})
121+
122+
test('the doc scan keeps the four shapes that are not repo paths, and names a real miss', (t) => {
123+
const root = mkdtempSync(join(tmpdir(), 'doc-tree-paths-'))
124+
t.after(() => rmSync(root, { recursive: true, force: true }))
125+
mkdirSync(join(root, 'core', 'test'), { recursive: true })
126+
mkdirSync(join(root, 'docs', 'subsystems'), { recursive: true })
127+
writeFileSync(join(root, 'core', 'test', 'here.test.js'), '// here\n')
128+
writeFileSync(join(root, 'docs', 'subsystems', 'core.md'), [
129+
'A fenced block is prose, not a claim:',
130+
'```',
131+
'core/test/gone-in-a-fence.test.js',
132+
'```',
133+
'Real: `core/test/here.test.js`, `plugins/project/src/project-board.js` (missing).',
134+
'Package-relative, so not a repo path: `scripts/check-arch-docs.mjs`.',
135+
'Tool names and branch names: `plugins/list`, `dev/bench.sh`.',
136+
'Another repository: `docs/FACE_ROOMS.md`.',
137+
'An example of a traversal: `decisions/../outside.md`.',
138+
].join('\n'))
139+
assert.deepEqual(docTreeMisses(root, ['docs/subsystems/core.md']), [
140+
'docs/subsystems/core.md:5: plugins/project/src/project-board.js',
141+
])
142+
})

0 commit comments

Comments
 (0)