Files
clean-architecture-frontend…/scripts/verify-documentation-readiness.ts
T
donghyeon.kang 79dc945a67 refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
  들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
  `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
  집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
  같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
  공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
  추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
  문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
  스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
  `config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
  `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
  복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
  `tests/fixtures/hosting/response-headers.json`.

버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.

위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).

검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
2026-11-08 17:41:07 +09:00

528 lines
23 KiB
TypeScript

import { spawnSync } from "node:child_process";
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 {
REMOVABLE_TEMPLATE_FEATURES,
removableTemplateFeaturePaths,
} from "./lib/removable-template-features.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 = "docs/accessibility/route-reviews/";
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 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/<folder>` — <description>", 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; docs/manual/03-outside-feature-folder.md says how
// to add it with its own tsconfig.
"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<string, string> })
.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,
]);
// 1105/14-01. A copy may delete the sample features listed in
// scripts/lib/removable-template-features.ts (the template lists none since
// 2026-11-07). The documents may name a sample's paths: while it is installed
// (its feature-module.ts exists), its paths and scripts are checked like any
// other; once it is not, they are not drift. A misspelt feature folder is not
// on the list and still fails.
const removedTemplateFeatures = REMOVABLE_TEMPLATE_FEATURES.filter(
(feature) => !exists(`src/features/${feature.featureId}/feature-module.ts`),
);
const removedTemplateFeaturePaths = removedTemplateFeatures.flatMap((feature) =>
removableTemplateFeaturePaths(feature),
);
const removedTemplateFeatureScripts = new Set(removedTemplateFeatures.flatMap((feature) => feature.scripts));
function missingScript(name: string): boolean {
return !scripts.has(name) && !removedTemplateFeatureScripts.has(name);
}
// 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, 1105/12-02. The paired templates a document may name
// (`<name>/docs/…`) or link (`../../../<name>/…`) are the ones
// config/contracts/backend-contract-pin.json pins. It is read with the
// documents, since it says which commit they describe. A reference is looked
// up in the tree of the pinned commit, read from the object store of the
// checkout beside the documents, never from that checkout's working tree or
// HEAD: those differ per machine, and the same commit failed on one whose
// sibling was months behind with uncommitted changes and passed elsewhere.
// Where the checkout or the pinned commit is missing (CI, a nested worktree, a
// stale clone) the reference is reported as not verified. A link that leaves
// the repository for anything else is broken (a misspelled repository too).
const PAIRED_PIN = "config/contracts/backend-contract-pin.json";
const pairedPins = new Map<string, string>();
const pairedPin = await readFile(PAIRED_PIN, "utf8").catch(() => null);
if (pairedPin !== null) {
const { backend } = JSON.parse(pairedPin) as { backend: { repository: string; commit: string } };
pairedPins.set(backend.repository, backend.commit);
}
const siblingsRoot = resolve(process.cwd(), "..");
type PairedTree = Readonly<{ paths: ReadonlySet<string> }> | Readonly<{ unverified: string }>;
const pairedTrees = new Map<string, PairedTree>();
function readPairedTree(repository: string, commit: string): PairedTree {
const checkout = resolve(siblingsRoot, repository);
if (!existsSync(join(checkout, ".git"))) return { unverified: `no checkout at ${checkout}` };
// The checkout's own repository only: a GIT_DIR set by a hook would point
// git at another one.
const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
const git = (...args: string[]) =>
spawnSync("git", ["-C", checkout, ...args], { encoding: "utf8", env, maxBuffer: 64 * 1024 * 1024 });
if (git("cat-file", "-e", `${commit}^{commit}`).status !== 0) {
const head = git("rev-parse", "--short=12", "HEAD");
return {
unverified: `${checkout} at HEAD ${head.status === 0 ? head.stdout.trim() : "(unreadable)"} does not have the pinned commit; fetch it to check these`,
};
}
const listing = git("ls-tree", "-r", "-t", "-z", "--name-only", commit);
if (listing.status !== 0) return { unverified: `git ls-tree failed in ${checkout}: ${listing.stderr.trim()}` };
return { paths: new Set(listing.stdout.split("\0").filter((entry) => entry !== "")) };
}
/** Whether `reference` (`../<name>/<path>`) is in the pinned tree, or null when it cannot be checked here. */
function pairedReferenceExists(reference: string): boolean | null {
const [, repository = "", ...inside] = reference.split("/");
const commit = pairedPins.get(repository);
if (commit === undefined) return false;
let tree = pairedTrees.get(repository);
if (tree === undefined) {
tree = readPairedTree(repository, commit);
pairedTrees.set(repository, tree);
}
if ("unverified" in tree) return null;
return inside.length === 0 || tree.paths.has(inside.join("/"));
}
// 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
// (`../<name>/…`).
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 (pairedPins.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
// in the paired repositories.
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 (`<id>`,
// 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<string>();
const unverifiedLinks = new Set<string>();
for (const file of named) {
if (file === null) continue;
const trimmed = file.replace(/\/$/u, "");
if (trimmed.startsWith("../")) {
// Outside this repository: `../<paired repository>/<path at its pin>`.
const found = pairedReferenceExists(trimmed);
if (found === null) unverifiedLinks.add(trimmed);
else if (!found) missingPaths.add(trimmed);
continue;
}
if (
!exists(trimmed) &&
!NOT_CREATED.has(trimmed) &&
!generated(trimmed) &&
!deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) &&
!removedTemplateFeaturePaths.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`))
) {
missingPaths.add(trimmed);
}
}
const missingScripts = new Set<string>();
for (const [, name = ""] of text.matchAll(/(?:corepack pnpm|`pnpm) (?:run )?([a-z](?:[\w:-]*\w)?)/gu)) {
if (!PNPM_COMMANDS.has(name) && missingScript(name)) missingScripts.add(name);
}
for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) {
if (scriptPrefixes.has(name.split(":")[0]) && missingScript(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 (documentReferences.some((entry) => entry.missingPaths.some((file) => file.startsWith("../")))) {
const checked = [...pairedTrees]
.filter(([, tree]) => "paths" in tree)
.map(([repository]) => `${repository} ${pairedPins.get(repository)?.slice(0, 12)}`);
process.stderr.write(
`A path outside this repository must be in a repository ${PAIRED_PIN} pins, at the pinned commit` +
`${checked.length > 0 ? ` (looked up in ${checked.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);
}
if (removedTemplateFeatures.length > 0) {
process.stdout.write(
`Documentation readiness: paths and scripts of removed template features not required: ` +
`${removedTemplateFeatures.map((feature) => feature.featureId).join(", ")}\n`,
);
}
const unverified = documentReferences.flatMap((entry) => entry.unverifiedLinks);
if (unverified.length > 0) {
const reasons = [...pairedTrees].flatMap(([repository, tree]) =>
"unverified" in tree ? [`${repository} pinned at ${pairedPins.get(repository)?.slice(0, 12)}: ${tree.unverified}`] : [],
);
process.stdout.write(
`Documentation readiness: ${unverified.length} reference(s) into paired repositories not verified ` +
`(${reasons.join("; ")}): ${[...new Set(unverified)].join(", ")}\n`,
);
}
process.stdout.write("Documentation readiness: PASS_SCOPED\n");