문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
(failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
241 lines
8.9 KiB
TypeScript
241 lines
8.9 KiB
TypeScript
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<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}\``),
|
|
);
|
|
|
|
// 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-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");
|