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>
150 lines
4.8 KiB
TypeScript
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");
|