Files
clean-architecture-frontend…/scripts/verify-documentation-readiness.ts
DongHyeonkaandClaude Opus 5.5 5810461256 fix(docs): check README runtime variables in verify:documentation (13-15)
The unit test read README.md, which removal fixtures do not copy, so
test:sample-removal failed. verify:documentation now requires README to name
every build and deploy variable the generator and admission read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:35:11 +09:00

150 lines
4.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}\``),
);
const passed =
reportDigestValid &&
routeScopeDocumented &&
missingRuntimeVariables.length === 0 &&
results.length === 2 &&
results.every((result) => result.passed);
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) {
if (missingRuntimeVariables.length > 0) {
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
}
process.stderr.write(
"Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n",
);
process.exit(1);
}
process.stdout.write("Documentation readiness: PASS_SCOPED\n");