import { access, mkdir, readdir, 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; 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-03. The entry documents drew a `src/domain` layer that does not // exist and left out `src/platform`, `src/apps` and `src/contexts`; layers.md // said its table "cannot drift" from the rules while most rule names were // missing. The folder and rule lists come from the code. layers.md describes // each folder in one table row, and the other entry documents repeat that // description verbatim as "`src/` — ", so a new folder or // rule must be documented, the descriptions cannot diverge, and no document // may name a top-level folder that is gone. const RULES_DOCUMENT = "docs/architecture/layers.md"; const STRUCTURE_DOCUMENTS = Object.freeze([ RULES_DOCUMENT, "README.md", "docs/architecture/overview.md", "docs/architecture/frontend-application-foundation.md", ]); const repositoryRoot = new URL("../", import.meta.url); const sourceFolders = (await readdir(new URL("src/", repositoryRoot), { withFileTypes: true })) .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")) .map((entry) => entry.name) .sort(); const architectureRules = ( JSON.parse(await readFile(new URL(".dependency-cruiser.json", repositoryRoot), "utf8")) as { forbidden: readonly { name: string }[]; } ).forbidden.map((rule) => rule.name); const rulesText = await readFile(RULES_DOCUMENT, "utf8").catch(() => ""); const folderDescriptions = new Map( [...rulesText.matchAll(/^\| `src\/([\w-]+)` \| (.+) \|$/gmu)].map((match) => [match[1], match[2]]), ); const sourceStructure = []; for (const path of STRUCTURE_DOCUMENTS) { const text = path === RULES_DOCUMENT ? rulesText : await readFile(path, "utf8").catch(() => ""); const namedFolders = new Set([...text.matchAll(/\bsrc\/([\w-]+)/gu)].map((match) => match[1] ?? "")); sourceStructure.push({ path, missingFolders: sourceFolders.filter((folder) => { const description = folderDescriptions.get(folder); if (description === undefined) return true; return path !== RULES_DOCUMENT && !text.includes(`\`src/${folder}\` — ${description}`); }), unknownFolders: [...namedFolders].filter((folder) => !sourceFolders.includes(folder)).sort(), missingRules: path === RULES_DOCUMENT ? architectureRules.filter((rule) => !text.includes(`\`${rule}\``)) : [], }); } const sourceStructureDocumented = sourceStructure.every( (entry) => entry.missingFolders.length === 0 && entry.unknownFolders.length === 0 && entry.missingRules.length === 0, ); // 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"]), ...(sourceStructureDocumented ? [] : ["source structure"]), ...(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, sourceStructure, 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`); } for (const entry of sourceStructure) { if (entry.missingFolders.length > 0) { process.stderr.write(`${entry.path} does not describe src folders as the layers.md table does: ${entry.missingFolders.join(", ")}\n`); } if (entry.unknownFolders.length > 0) { process.stderr.write(`${entry.path} names src folders that do not exist: ${entry.unknownFolders.join(", ")}\n`); } if (entry.missingRules.length > 0) { process.stderr.write( `${entry.path} does not name .dependency-cruiser.json rules: ${entry.missingRules.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");