문제 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
174 lines
5.8 KiB
TypeScript
174 lines
5.8 KiB
TypeScript
import { access, mkdir, readFile } from "node:fs/promises";
|
|
|
|
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
|
|
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
|
|
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
|
|
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
|
|
|
/**
|
|
* Documents that state the review scope. The route registry is the source of
|
|
* truth for what that scope is, so these have to enumerate exactly the
|
|
* installed routes.
|
|
*
|
|
* Both said "six routes" while ten were registered: the four newest — the
|
|
* platform overview and three reference-resource screens — were outside the
|
|
* declared manual accessibility scope without anybody deciding they should be.
|
|
* A hand-typed count drifts silently, so it is derived here instead.
|
|
*/
|
|
const ROUTE_SCOPE_DOCUMENTS = Object.freeze([
|
|
"README.md",
|
|
"docs/accessibility/manual-checklist.md",
|
|
]);
|
|
|
|
type DocumentationReview = Readonly<{
|
|
sourcePath: string;
|
|
sha256: string;
|
|
thresholdSatisfied: boolean;
|
|
verdict: string;
|
|
score: number;
|
|
}>;
|
|
|
|
type ReviewLedger = Readonly<{
|
|
evidenceReport: Readonly<{
|
|
repoPath: string;
|
|
upstreamCanonicalPath: string;
|
|
canonicalSha256: string;
|
|
}>;
|
|
reviews: Record<string, DocumentationReview>;
|
|
reviewer: string;
|
|
standard: string;
|
|
status: string;
|
|
}>;
|
|
|
|
const ledger = JSON.parse(
|
|
await readFile("docs/architecture/review-ledger.json", "utf8"),
|
|
) as ReviewLedger;
|
|
const evidence = await readFile(ledger.evidenceReport.repoPath, "utf8");
|
|
const results = [];
|
|
for (const [diagram, review] of Object.entries(ledger.reviews)) {
|
|
const sourceReferenced = evidence.includes(review.sourcePath);
|
|
const digestReferenced =
|
|
/^[0-9a-f]{64}$/.test(review.sha256) &&
|
|
evidence.includes(review.sha256);
|
|
const scorePass =
|
|
review.thresholdSatisfied === true &&
|
|
review.verdict === "PASS" &&
|
|
typeof review.score === "number" &&
|
|
evidence.includes(`| ${review.score} | PASS |`);
|
|
results.push({
|
|
diagram,
|
|
sourcePath: review.sourcePath,
|
|
sha256: review.sha256,
|
|
sourceReferenced,
|
|
digestReferenced,
|
|
reviewer: ledger.reviewer,
|
|
score: review.score,
|
|
scorePass,
|
|
passed:
|
|
sourceReferenced &&
|
|
digestReferenced &&
|
|
ledger.reviewer === "wiki-diagram-reviewer" &&
|
|
ledger.standard === "rules/diagram-standards.md v2" &&
|
|
scorePass &&
|
|
ledger.status === "PASS_SCOPED",
|
|
});
|
|
}
|
|
const reportDigestValid =
|
|
/^[0-9a-f]{64}$/.test(ledger.evidenceReport.canonicalSha256) &&
|
|
evidence.includes(ledger.evidenceReport.canonicalSha256);
|
|
|
|
const installedRouteIds = Object.values(ROUTE_REGISTRY)
|
|
.map((route) => route.routeId)
|
|
.sort();
|
|
const routeScope = [];
|
|
for (const path of ROUTE_SCOPE_DOCUMENTS) {
|
|
let text: string;
|
|
try {
|
|
await access(path);
|
|
text = await readFile(path, "utf8");
|
|
} catch {
|
|
routeScope.push({ path, missingRouteIds: [...installedRouteIds], documented: false });
|
|
continue;
|
|
}
|
|
const missingRouteIds = installedRouteIds.filter(
|
|
(routeId) => !text.includes(routeId),
|
|
);
|
|
routeScope.push({ path, missingRouteIds, documented: missingRouteIds.length === 0 });
|
|
}
|
|
const routeScopeDocumented = routeScope.every((entry) => entry.documented);
|
|
|
|
// 13-15. README is where a project learns how to build for production. It
|
|
// named none of the variables the build and admission read, so each one is
|
|
// required here, taken from the code that reads it where possible.
|
|
const RUNTIME_VARIABLES = Object.freeze([
|
|
"APP_PROFILE",
|
|
"RELEASE_TARGET",
|
|
"VITE_BUILD_ID",
|
|
"RELEASE_ID",
|
|
...Object.values(RUNTIME_OVERRIDES),
|
|
]);
|
|
const readme = await readFile("README.md", "utf8").catch(() => "");
|
|
const missingRuntimeVariables = RUNTIME_VARIABLES.filter(
|
|
(variable) => !readme.includes(`\`${variable}\``),
|
|
);
|
|
|
|
// 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",
|
|
schema: documentationReviewArtifactSchema,
|
|
value: {
|
|
schemaVersion: 1,
|
|
generatedAt: new Date().toISOString(),
|
|
status: ledger.status,
|
|
reviewer: ledger.reviewer,
|
|
standard: ledger.standard,
|
|
evidenceReport: ledger.evidenceReport,
|
|
reportDigestValid,
|
|
routeScope,
|
|
routeScopeDocumented,
|
|
missingRuntimeVariables,
|
|
results,
|
|
passed,
|
|
},
|
|
});
|
|
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 (failed: ${failedChecks.join(", ")})\n`,
|
|
);
|
|
process.exit(1);
|
|
}
|
|
process.stdout.write("Documentation readiness: PASS_SCOPED\n");
|