fix(docs-check): verify.sh와 python3 명령 안의 경로·script도 대조한다

문제: `verify:documentation`은 명령 머리가 corepack·pnpm·node 같은 낱말일
때만 인자 경로를 보았다. 이 repo 문서의 명령 대부분은
`scripts/verify.sh exec -- node <경로>`, `scripts/verify.sh script <이름>`,
`python3 scripts/…` 꼴이라, 그 안의 낡은 경로·없는 script 이름이 검사를
통과했다.

고친 것: `python3`를 명령 머리에 더하고, `scripts/verify.sh`는 그 자신을
경로로 보며 `exec --` 뒤를 다시 명령으로 읽고 `script` 뒤 낱말을 package
script 이름으로 대조한다. 자리표시자(`<이름>`)와 `--` 뒤 인자는 보지
않는다.

위험·한계: 살아 있는 문서 전부가 지금 이 검사를 통과하는지는 desktop
`verify:documentation`으로 확인한다.

검증: desktop `node scripts/run-vitest.ts run
tests/unit/documentation-readiness.test.ts` 24건 통과(새 시험 포함). 검사기를
기준 커밋으로 되돌리면 새 시험이 실패한다.

Refs: 1112/08-06
This commit is contained in:
DongHyeonka
2026-11-13 21:49:58 +09:00
parent eb7d89c742
commit aebb7c8c55
2 changed files with 54 additions and 4 deletions
+35 -3
View File
@@ -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 (`<id>`,
// 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 <name>… [-- 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(),
+19 -1
View File
@@ -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 <release dir>\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`;