import { existsSync } from "node:fs"; import { mkdir, readdir, readFile } from "node:fs/promises"; import { dirname, join, matchesGlob, normalize, resolve } from "node:path/posix"; import { fileURLToPath } from "node:url"; import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts"; import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts"; import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts"; import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; /** * The manual accessibility review scope is one record per installed route. * README and the checklist used to list the route IDs and this script checked * the lists (they had said six routes while ten were registered). That made * every new feature edit two template-owned documents (1101/14-05), so the * documents now name this folder and the record files are what is checked. */ const MANUAL_A11Y_RECORDS = "artifacts/tests/a11y-manual/"; 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 missingRouteIds = MANUAL_A11Y_ROUTE_IDS.filter( (routeId) => !existsSync(`${MANUAL_A11Y_RECORDS}${routeId}.md`), ).sort(); const routeScope = [ { path: MANUAL_A11Y_RECORDS, missingRouteIds, documented: missingRouteIds.length === 0 }, ]; const routeScopeDocumented = missingRouteIds.length === 0; // 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-05. docs/README.md §1 says the gates check the current contract // documents, while only the checks above did. Every repo path, package script // and FE-GATE ID that the index and the documents its §1 links name must // exist. Documents are read from the working directory; what they name is // looked up in this repository, as for the src structure above. const DOCUMENT_INDEX = "docs/README.md"; // Past states are its subject: it names removed scripts and paths on purpose. const UNCHECKED_DOCUMENTS = new Set(["CHANGELOG.md"]); const NOT_CREATED = new Set([ // Reserved by generic-worker-has-no-network-or-credentials. The generic CPU // worker is NOT_SELECTED (tsconfig.web-worker.json). "src/adapters/web-worker", ]); // pnpm's own commands, which are not package scripts. const PNPM_COMMANDS = new Set(["add", "dlx", "exec", "install", "list", "why"]); const rootDirectory = fileURLToPath(repositoryRoot); const exists = (file: string) => existsSync(join(rootDirectory, file)); const topLevelEntries = new Set(await readdir(rootDirectory)); const scripts = new Set( Object.keys( (JSON.parse(await readFile(join(rootDirectory, "package.json"), "utf8")) as { scripts: Record }) .scripts, ), ); const scriptPrefixes = new Set([...scripts].map((name) => name.split(":")[0])); const gateIds = new Set([ ...( JSON.parse(await readFile(join(rootDirectory, "config/ci/gates.json"), "utf8")) as { gates: { id: string }[] } ).gates.map((gate) => gate.id), ...RETIRED_GATE_IDS, ]); // Generated output is what git ignores, so a document may name it before a // run has written it. const ignorePatterns = (await readFile(join(rootDirectory, ".gitignore"), "utf8").catch(() => "")) .split("\n") .map((line) => line.trim()) .filter((line) => line !== "" && !line.startsWith("#")); function generated(file: string): boolean { let ignored = false; for (const line of ignorePatterns) { const pattern = line.replace(/^!/u, "").replace(/^\/|\/$/gu, ""); const glob = pattern.includes("/") ? pattern : `**/${pattern}`; if (matchesGlob(file, glob) || matchesGlob(file, `${glob}/**`)) ignored = !line.startsWith("!"); } return ignored; } // A copy may delete the history README lists under "Files you can delete // after copying". A path under an entry that is gone is not drift. const deletedHistory = [ ...(readme.match(/^### Files you can delete after copying\n[\s\S]*?(?=^#)/mu)?.[0] ?? "").matchAll( /^\| (.+?) \|/gmu, ), ] .flatMap(([, cell = ""]) => [...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, ""))) .filter((entry) => !exists(entry)); // 1103/12-05. The paired templates a document may name (`/docs/…`) or // link (`../../..//…`). They are looked up beside the checkout the // documents are read from; where none is checked out (CI, a nested worktree) // the reference is reported as not verified instead of passing silently. const SIBLING_REPOSITORIES = new Set(["clean-architecture-backend-template"]); const siblingsRoot = resolve(process.cwd(), ".."); // A backtick span is a path when it starts at a top-level entry, at an entry // beside the document or at a paired repository; line numbers and anchors are // dropped. A path into a paired repository is returned relative to this one // (`..//…`). function namedPath(token: string, document: string): string | null { const candidate = token.replace(/#.*$/u, "").replace(/:\d[\d,:-]*$/u, ""); if (!candidate.includes("/") || candidate.startsWith("/") || /[\s*<>{}$()|]|\.\.\./u.test(candidate)) return null; const first = candidate.split("/")[0] ?? ""; if (topLevelEntries.has(first)) return candidate; if (SIBLING_REPOSITORIES.has(first)) return `../${candidate}`; return first !== "." && first !== ".." && exists(join(dirname(document), first)) ? join(dirname(document), candidate) : null; } // A link that leaves the repository is kept (`../…`); the caller looks it up // beside the checkout. function linkedPath(target: string, document: string): string | null { if (/^(?:[a-z][a-z+.-]*:|#)/iu.test(target)) return null; return normalize(join(dirname(document), target.replace(/#.*$/u, ""))); } // 1103/12-05. A command span is not a path, so the paths it takes as // arguments (`corepack pnpm exec vitest run tests/…`, `node scripts/…`) were // never looked up. Leading `NAME=value` assignments are skipped, a // `--flag=value` argument is read as its value, and placeholders (``, // globs, `$VAR`) are left alone by namedPath. const COMMAND_HEADS = new Set(["corepack", "pnpm", "npx", "node", "vitest", "playwright", "tsc", "eslint", "bash", "sh"]); function commandPaths(command: string, document: string): (string | null)[] { const words = command.trim().replace(/^\$\s+/u, "").split(/\s+/u); let head = 0; while (/^[A-Z_][A-Z0-9_]*=/u.test(words[head] ?? "")) head += 1; if (!COMMAND_HEADS.has(words[head] ?? "")) return []; return words .slice(head + 1) .map((word) => namedPath(word.replace(/^--?[\w.-]+=/u, "").replace(/^["']|["']$/gu, ""), document)); } // Lines of fenced shell blocks (```bash, ```sh, ```shell, ```console or no // language), which is where most documented commands are. function fencedCommands(text: string): string[] { const commands: string[] = []; let fence: string | null = null; for (const line of text.split("\n")) { const marker = /^\s*```(\w*)/u.exec(line); if (marker) { fence = fence === null ? (marker[1] ?? "") : null; continue; } if (fence !== null && /^(?:bash|sh|shell|console|zsh)?$/u.test(fence)) commands.push(line); } return commands; } const index = await readFile(DOCUMENT_INDEX, "utf8").catch(() => ""); const contractDocuments = new Set([DOCUMENT_INDEX]); for (const [, target = ""] of (index.match(/^## 1\.[\s\S]*?(?=^## )/mu)?.[0] ?? "").matchAll(/\]\(([^)#\s]+)\)/gu)) { const linked = normalize(join(dirname(DOCUMENT_INDEX), target)); const entries = await readdir(linked).catch(() => null); const documents = entries === null ? [linked] : entries.filter((name) => name.endsWith(".md")).map((name) => join(linked, name)); for (const document of documents) if (!UNCHECKED_DOCUMENTS.has(document)) contractDocuments.add(document); } const documentReferences = []; for (const document of contractDocuments) { const text = await readFile(document, "utf8").catch(() => null); if (text === null) { // A linked document that is gone is reported as the index's broken link. if (document === DOCUMENT_INDEX) { documentReferences.push({ path: document, missingPaths: [document], unverifiedLinks: [], missingScripts: [], unknownGateIds: [], }); } continue; } const named = [ ...[...text.matchAll(/`([^`\n]+)`/gu)].flatMap(([, token = ""]) => [ namedPath(token, document), ...commandPaths(token, document), ]), ...fencedCommands(text).flatMap((command) => commandPaths(command, document)), ...[...text.matchAll(/\]\(([^)\s]+)\)/gu)].map(([, target = ""]) => linkedPath(target, document)), ]; const missingPaths = new Set(); const unverifiedLinks = new Set(); for (const file of named) { if (file === null) continue; const trimmed = file.replace(/\/$/u, ""); if (trimmed.startsWith("../")) { // Outside this repository: the first folder past the `..` steps is the // paired checkout. Without it the reference cannot be checked here. const segments = trimmed.split("/"); const checkout = segments.slice(0, segments.findIndex((segment) => segment !== "..") + 1).join("/"); const relativeToSiblings = trimmed.replace(/^\.\.\//u, ""); if (!existsSync(resolve(siblingsRoot, checkout.replace(/^\.\.\//u, "")))) { unverifiedLinks.add(trimmed); } else if (!existsSync(resolve(siblingsRoot, relativeToSiblings))) { missingPaths.add(trimmed); } continue; } if ( !exists(trimmed) && !NOT_CREATED.has(trimmed) && !generated(trimmed) && !deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) ) { missingPaths.add(trimmed); } } const missingScripts = new Set(); for (const [, name = ""] of text.matchAll(/(?:corepack pnpm|`pnpm) (?:run )?([a-z](?:[\w:-]*\w)?)/gu)) { if (!PNPM_COMMANDS.has(name) && !scripts.has(name)) missingScripts.add(name); } for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) { if (scriptPrefixes.has(name.split(":")[0]) && !scripts.has(name)) missingScripts.add(name); } documentReferences.push({ path: document, missingPaths: [...missingPaths].sort(), unverifiedLinks: [...unverifiedLinks].sort(), missingScripts: [...missingScripts].sort(), unknownGateIds: [...new Set([...text.matchAll(/\bFE-GATE-\d+\b/gu)].map(([id]) => id))] .filter((id) => !gateIds.has(id)) .sort(), }); } const documentReferencesValid = documentReferences.every( (entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.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. 1101/14-05: the last // two only compare the two hand-kept copies of the 2026-07-18 diagram review; // the diagrams are outside this repository, so they pass whatever the // structure becomes, and their names say so. const failedChecks = [ ...(routeScopeDocumented ? [] : ["route scope"]), ...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]), ...(sourceStructureDocumented ? [] : ["source structure"]), ...(documentReferencesValid ? [] : ["document references"]), ...(reportDigestValid ? [] : ["2026-07-18 diagram review copy digest"]), ...(results.length === 2 && results.every((result) => result.passed) ? [] : ["2026-07-18 diagram review copies"]), ]; 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, documentReferences, results, passed, }, }); if (!passed) { if (!routeScopeDocumented) { process.stderr.write(`${MANUAL_A11Y_RECORDS} has no record for route IDs: ${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`, ); } } for (const entry of documentReferences) { if (entry.missingPaths.length > 0) { process.stderr.write(`${entry.path} names paths that do not exist: ${entry.missingPaths.join(", ")}\n`); } if (entry.missingScripts.length > 0) { process.stderr.write(`${entry.path} names package scripts that do not exist: ${entry.missingScripts.join(", ")}\n`); } if (entry.unknownGateIds.length > 0) { process.stderr.write( `${entry.path} names gate IDs that config/ci/gates.json does not define: ${entry.unknownGateIds.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); } const unverified = documentReferences.flatMap((entry) => entry.unverifiedLinks); if (unverified.length > 0) { process.stdout.write( `Documentation readiness: ${unverified.length} reference(s) into paired repositories not verified ` + `(no checkout beside ${process.cwd()}): ${[...new Set(unverified)].join(", ")}\n`, ); } process.stdout.write("Documentation readiness: PASS_SCOPED\n");