fix(docs): verify:documentation이 실패한 검사와 고칠 파일을 적는다 (1101/14-06)

문제
verify-documentation-readiness.ts는 실패 원인과 상관없이 마지막에
"FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)"를
적는다. stderr에 따로 적는 것은 README 빌드 변수 누락뿐이다. 기능을
더해 route가 늘었는데 README나 접근성 체크리스트에 route ID를 안 적으면,
개발자는 diagram 리뷰 기록을 먼저 의심하고 산출물 JSON을 열어야 원인을
안다.

고른 방법
- 검사 네 개(route scope, runtime variables, review report digest,
  diagram reviews)의 실패를 failedChecks로 모으고 passed는 그것이 비었는지로
  정한다. 판정 조건은 그대로다.
- 실패하면 검사마다 고칠 곳을 stderr에 적는다. route scope는 문서별로
  빠진 route ID, diagram review는 어느 diagram이 증거 문서에 PASS로 없는지.
- 마지막 줄은 "FAIL_UNVERIFIED (failed: <검사 이름들>)"이다. 판정 토큰은
  그대로 둬서 이 줄을 읽는 쪽이 바뀌지 않는다.

버린 대안
- route ID 누락만 따로 적기(리뷰의 최소 방향): 다음에 다른 검사가 실패해도
  같은 엉뚱한 문구가 나온다. 검사 네 개 모두 같은 방식으로 적어도 몇 줄이다.

위험·한계
- diagram review 실패는 어느 하위 조건(경로·digest·점수)인지까지는 적지
  않는다. 산출물 JSON의 results에 그대로 있다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
  2 failed. README에서 `EXAMPLES_PLATFORM`을 지운 사본에서 stderr가
  "Documentation readiness: FAIL_UNVERIF…"뿐이라 "README.md does not name
  route IDs: EXAMPLES_PLATFORM"이 없다. 두 검사 실패 때도 실패 이름이 없다
- GREEN: 같은 파일 3 passed(원본 사본 PASS, route 하나 누락,
  route+변수 누락)
- 실제 repo에서 verify-documentation-readiness PASS_SCOPED
- eslint, tsc(node, test), check-ci-contract PASS

Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-06
This commit is contained in:
DongHyeonka
2026-11-01 22:49:13 +09:00
parent 003832b694
commit f13ed7bea7
2 changed files with 86 additions and 7 deletions
+31 -7
View File
@@ -112,12 +112,17 @@ const missingRuntimeVariables = RUNTIME_VARIABLES.filter(
(variable) => !readme.includes(`\`${variable}\``),
);
const passed =
reportDigestValid &&
routeScopeDocumented &&
missingRuntimeVariables.length === 0 &&
results.length === 2 &&
results.every((result) => result.passed);
// 1101/14-06. Each failed check is named, so the stderr points at the file to
// fix rather than at the diagram review whatever failed.
const failedChecks = [
...(routeScopeDocumented ? [] : ["route scope"]),
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
...(reportDigestValid ? [] : ["review report digest"]),
...(results.length === 2 && results.every((result) => result.passed)
? []
: ["diagram reviews"]),
];
const passed = failedChecks.length === 0;
await mkdir("artifacts/quality", { recursive: true });
await writeValidatedJsonArtifact({
path: "artifacts/quality/documentation-review.json",
@@ -138,11 +143,30 @@ await writeValidatedJsonArtifact({
},
});
if (!passed) {
for (const entry of routeScope) {
if (entry.documented) continue;
process.stderr.write(`${entry.path} does not name route IDs: ${entry.missingRouteIds.join(", ")}\n`);
}
if (missingRuntimeVariables.length > 0) {
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
}
if (!reportDigestValid) {
process.stderr.write(
`${ledger.evidenceReport.repoPath} does not contain the ledger's canonicalSha256\n`,
);
}
for (const result of results) {
if (result.passed) continue;
process.stderr.write(
`diagram review ${result.diagram} (${result.sourcePath}) is not a recorded PASS in ` +
`${ledger.evidenceReport.repoPath} (docs/architecture/review-ledger.json)\n`,
);
}
if (results.length !== 2) {
process.stderr.write(`review ledger has ${results.length} diagram reviews; 2 are required\n`);
}
process.stderr.write(
"Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n",
`Documentation readiness: FAIL_UNVERIFIED (failed: ${failedChecks.join(", ")})\n`,
);
process.exit(1);
}
@@ -0,0 +1,55 @@
import { spawnSync } from "node:child_process";
import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { describe, expect, it } from "vitest";
const INPUTS = [
"README.md",
"docs/accessibility/manual-checklist.md",
"docs/architecture/review-ledger.json",
"docs/architecture/review-evidence.md",
];
/** Runs verify:documentation on a copy of its inputs, `mutate` applied to README.md. */
async function verifyWithReadme(mutate: (readme: string) => string) {
const root = await mkdtemp(path.join(tmpdir(), "documentation-readiness-"));
try {
for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true });
const readme = path.join(root, "README.md");
await writeFile(readme, mutate(await readFile(readme, "utf8")));
return spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], {
cwd: root,
encoding: "utf8",
});
} finally {
await rm(root, { recursive: true, force: true });
}
}
// 1101/14-06. A route missing from a scope document used to fail with only
// "canonical scoped-review evidence is incomplete", which points at the
// diagram review instead of the document to fix.
describe("verify:documentation failure output (1101/14-06)", () => {
it("passes the documents as they are", async () => {
const result = await verifyWithReadme((readme) => readme);
expect(result.status, result.stderr).toBe(0);
});
it("names the document and the route ID it is missing", async () => {
const result = await verifyWithReadme((readme) => readme.replaceAll("`EXAMPLES_PLATFORM`", ""));
expect(result.status).toBe(1);
expect(result.stderr).toContain("README.md does not name route IDs: EXAMPLES_PLATFORM");
expect(result.stderr).toMatch(/FAIL_UNVERIFIED \(failed: route scope\)/u);
expect(result.stderr).not.toContain("scoped-review evidence");
});
it("names every failed check", async () => {
const result = await verifyWithReadme((readme) =>
readme.replaceAll("`EXAMPLES_PLATFORM`", "").replaceAll("`RELEASE_TARGET`", ""),
);
expect(result.stderr).toContain("README.md does not name: RELEASE_TARGET");
expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u);
});
});