diff --git a/scripts/verify-documentation-readiness.ts b/scripts/verify-documentation-readiness.ts index 1032181d..3abdd9fe 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -304,16 +304,44 @@ function linkedPath(target: string, document: string): string | null { // never looked up. Leading `NAME=value` assignments are skipped, a // `--flag=value` argument is read as its value, and placeholders (``, // globs, `$VAR`) are left alone by namedPath. -const COMMAND_HEADS = new Set(["corepack", "pnpm", "npx", "node", "vitest", "playwright", "tsc", "eslint", "bash", "sh"]); -function commandPaths(command: string, document: string): (string | null)[] { +const COMMAND_HEADS = new Set([ + "corepack", "pnpm", "npx", "node", "vitest", "playwright", "tsc", "eslint", "bash", "sh", "python3", +]); +// 1112/08-06. `scripts/verify.sh` is this repository's main entry and most +// documented commands go through it: the entry is itself a path, `exec --` +// runs a command whose paths are looked up like any other, and `script` +// names package scripts (verifyScripts). +const VERIFY_ENTRY = /^(?:\.\/)?scripts\/verify\.sh$/u; +function commandWords(command: string): Readonly<{ words: string[]; head: number }> { const words = command.trim().replace(/^\$\s+/u, "").split(/\s+/u); let head = 0; while (/^[A-Z_][A-Z0-9_]*=/u.test(words[head] ?? "")) head += 1; - if (!COMMAND_HEADS.has(words[head] ?? "")) return []; + return { words, head }; +} +function commandPaths(command: string, document: string): (string | null)[] { + const { words, head } = commandWords(command); + const first = words[head] ?? ""; + if (VERIFY_ENTRY.test(first)) { + const separator = words.indexOf("--", head + 1); + const executed = words[head + 1] === "exec" && separator > head ? words.slice(separator + 1).join(" ") : ""; + return [namedPath(first, document), ...(executed === "" ? [] : commandPaths(executed, document))]; + } + if (!COMMAND_HEADS.has(first)) return []; return words .slice(head + 1) .map((word) => namedPath(word.replace(/^--?[\w.-]+=/u, "").replace(/^["']|["']$/gu, ""), document)); } +/** The package scripts `scripts/verify.sh script … [-- args]` runs; placeholders are left alone. */ +function verifyScripts(command: string): string[] { + const { words, head } = commandWords(command); + if (!VERIFY_ENTRY.test(words[head] ?? "") || words[head + 1] !== "script") return []; + const names: string[] = []; + for (const word of words.slice(head + 2)) { + if (word.startsWith("-")) break; + names.push(word); + } + return names.filter((name) => /^[a-z](?:[\w:-]*\w)?$/u.test(name)); +} // Lines of fenced shell blocks (```bash, ```sh, ```shell, ```console or no // language), which is where most documented commands are. function fencedCommands(text: string): string[] { @@ -398,6 +426,10 @@ for (const document of contractDocuments) { for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) { if (scriptPrefixes.has(name.split(":")[0]) && missingScript(name)) missingScripts.add(name); } + const commands = [...[...text.matchAll(/`([^`\n]+)`/gu)].map(([, token = ""]) => token), ...fencedCommands(text)]; + for (const name of commands.flatMap(verifyScripts)) { + if (missingScript(name)) missingScripts.add(name); + } documentReferences.push({ path: document, missingPaths: [...missingPaths].sort(), diff --git a/tests/unit/documentation-readiness.test.ts b/tests/unit/documentation-readiness.test.ts index dbc15222..9374e83e 100644 --- a/tests/unit/documentation-readiness.test.ts +++ b/tests/unit/documentation-readiness.test.ts @@ -250,11 +250,29 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { const result = await verify({ [CI_DOC]: (text) => `${text}\n\`corepack pnpm exec vitest run tests/unit/documentation-readiness.test.ts -t "x"\`\n` + "```bash\ncorepack pnpm drill:runbook -- FE-RB-005 --release-root \n```\n" + - "Any script is run as `node scripts/…`.\n", + "Any script is run as `node scripts/…`.\n" + + "`scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts`, " + + "`scripts/verify.sh script verify:documentation lint -- --x`, `scripts/verify.sh script <이름>…`, " + + "`python3 scripts/check-work-docs.py --history <경로>`\n", }); expect(result.status, result.stderr).toBe(0); }, VERIFY_TIMEOUT); + // 1112/08-06. Commands through this repository's entry point, and python3 + // commands, were not read, so a stale path or script name in them passed. + it("reads commands run through scripts/verify.sh and python3", async () => { + const result = await verify({ + [CI_DOC]: (text) => `${text}\n\`scripts/verify.sh exec -- node scripts/no-such.ts\`\n` + + "```bash\nVERIFY_SNAPSHOT=1 scripts/verify.sh exec -- node tests/unit/no-such-shell.test.ts\n```\n" + + "`python3 scripts/no-such.py --history docs`\n`scripts/verify.sh script no:such-script -- --flag`\n", + }); + expect(result.status).toBe(1); + expect(result.stderr).toContain( + `${CI_DOC} names paths that do not exist: scripts/no-such.py, scripts/no-such.ts, tests/unit/no-such-shell.test.ts`, + ); + expect(result.stderr).toContain(`${CI_DOC} names package scripts that do not exist: no:such-script`); + }, VERIFY_TIMEOUT); + it("checks a link or a path into a paired repository checked out beside this one", async () => { const naming = (target: string) => (text: string) => `${text}\n[contract](../../../${target}) and \`${target}\`\n`;