Files
clean-architecture-frontend…/scripts/verify-documentation-readiness.ts
DongHyeonka b4e4f98c03 fix(docs): 문서 검사가 명령 안 경로와 짝 저장소 참조를 본다
문제
verify:documentation(FE-GATE-017)은 공백 없는 backtick 경로만 본다. 그래서
`corepack pnpm exec vitest run tests/…` 같은 명령 안의 경로, 셸 코드 블록의
명령, 저장소 밖(`../`) 링크는 확인하지 않았다. 실제로 원장
docs/operations/adapter-remediation-ledger.md의 N-06~N-08 행이 V2와 함께
지운 테스트 세 개를 실행하라고 적고 있었다. 짝 백엔드 정본 링크가 깨져도
알 수 없었다. config/ci/ungated-scripts.json의 check:remediation-ledger
사유는 "It passes at this commit"이라는 시점 문장을 담았다.

고른 방법
- 인라인 코드와 셸 코드 블록(```bash/sh/shell/console/zsh, 언어 없음)에서
  명령(corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash,
  sh)의 인자를 같은 경로 규칙으로 본다. 앞의 NAME=value는 건너뛰고,
  --flag=value는 값만 본다. 자리표시자(<id>, glob, $VAR)는 기존 규칙대로
  경로로 보지 않는다.
- 짝 백엔드 템플릿(clean-architecture-backend-template)을 가리키는 backtick
  경로와 저장소 밖 링크는 문서를 읽는 checkout 옆에서 찾는다. 그 checkout이
  있으면 없는 경로는 실패다. 없으면(CI, 중첩 worktree) 실패 대신 "not
  verified"로 출력하고 보고서 documentReferences[].unverifiedLinks에 남긴다.
  보고서 schema에 그 칸을 더했다.
- 원장 N-06~N-08 행의 명령을 LEG-01 행처럼 "V2와 함께 지움"으로 바꾸고,
  ungated 사유에서 시점 문장을 지웠다. docs/README.md 1절의 검사 범위 설명을
  고쳤다.
- 버린 대안: 지운 심볼 이름 검사. 지운 이름 목록을 따로 관리해야 하고
  오탐이 많다(리뷰 5.2절). 1절 밖 문서로 대상 넓히기. 기록 문서가 일부러 옛
  경로를 적어 예외가 늘어난다.

위험·한계
- 명령 머리 목록에 없는 명령(git, curl 등)의 인자는 여전히 보지 않는다.
- 짝 저장소 참조는 CI에서 늘 "not verified"다. 실제 확인은 옆에 checkout이
  있는 개발 환경에서만 된다.
- 1절 밖 문서(testing strategy :765, VD-23)는 그대로 검사 밖이다.

검증
- RED: 새 테스트 4건(인라인 명령, 셸 블록, 짝 저장소 있음·깨짐, 짝 저장소
  없음 보고) 실패.
- 수정 뒤 documentation-readiness 19건 통과. 저장소에서 수정 전 원장 행 3개가
  "names paths that do not exist"로 잡혔고, 행을 고친 뒤 verify:documentation
  PASS_SCOPED(worktree라 짝 저장소 참조 3건은 not verified).
  check:remediation-ledger PASS, check:ci PASS, check:types 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
2026-11-04 21:15:03 +09:00

447 lines
19 KiB
TypeScript

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<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 (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<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,
]);
// 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 (`<name>/docs/…`) or
// link (`../../../<name>/…`). 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
// (`../<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 (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 (`<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: 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<string>();
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");