문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).
고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
(ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
읽는다), README "Files you can delete after copying"의 이력 중 지워진
것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.
위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
계약 문서(README, compatibility.md, starter-experience.md,
manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.
검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
"failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
eslint 통과. check-ci-contract, generate-artifact-schemas --check,
generate-ci-workflow --check, check-adapter-inventory 통과.
check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
166 lines
7.8 KiB
TypeScript
166 lines
7.8 KiB
TypeScript
import { spawnSync } from "node:child_process";
|
|
import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
|
import { tmpdir } from "node:os";
|
|
import path from "node:path";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
const INPUTS = ["README.md", "docs", "artifacts/tests/a11y-manual"];
|
|
|
|
/**
|
|
* Runs verify:documentation on a copy of its inputs, each `changes` entry
|
|
* applied to its document and every `removed` file deleted. Code facts (src,
|
|
* package.json, gates.json) are read from this repository, not the copy.
|
|
*/
|
|
async function verify(
|
|
changes: Readonly<Record<string, (text: string) => string>>,
|
|
removed: readonly string[] = [],
|
|
) {
|
|
const root = await mkdtemp(path.join(tmpdir(), "documentation-readiness-"));
|
|
try {
|
|
for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true });
|
|
for (const [document, mutate] of Object.entries(changes)) {
|
|
const target = path.join(root, document);
|
|
await writeFile(target, mutate(await readFile(target, "utf8")));
|
|
}
|
|
for (const file of removed) await rm(path.join(root, file));
|
|
return spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], {
|
|
cwd: root,
|
|
encoding: "utf8",
|
|
});
|
|
} finally {
|
|
await rm(root, { recursive: true, force: true });
|
|
}
|
|
}
|
|
|
|
function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
|
|
return verify({ [document]: mutate });
|
|
}
|
|
|
|
// 1101/14-06. A route missing from a scope document used to fail with only
|
|
// "canonical scoped-review evidence is incomplete", which points at the
|
|
// diagram review instead of the file to fix.
|
|
describe("verify:documentation failure output (1101/14-06)", () => {
|
|
it("passes the documents as they are", async () => {
|
|
const result = await verifyWithReadme((readme) => readme);
|
|
expect(result.status, result.stderr).toBe(0);
|
|
});
|
|
|
|
it("names the route ID that has no manual review record", async () => {
|
|
const result = await verify({}, ["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"]);
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain("artifacts/tests/a11y-manual/ has no record for route IDs: EXAMPLES_PLATFORM");
|
|
expect(result.stderr).toMatch(/FAIL_UNVERIFIED \(failed: route scope\)/u);
|
|
expect(result.stderr).not.toContain("scoped-review evidence");
|
|
});
|
|
|
|
it("names every failed check", async () => {
|
|
const result = await verify(
|
|
{ "README.md": (readme) => readme.replaceAll("`RELEASE_TARGET`", "") },
|
|
["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"],
|
|
);
|
|
expect(result.stderr).toContain("README.md does not name: RELEASE_TARGET");
|
|
expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u);
|
|
});
|
|
});
|
|
|
|
// 1101/14-05. README and the manual checklist listed every route ID, so each
|
|
// new feature edited two template-owned documents. The scope is the record
|
|
// files now, and the current contract documents (docs/README.md §1) may only
|
|
// name paths, package scripts and gate IDs that exist.
|
|
describe("verify:documentation current contract documents (1101/14-05)", () => {
|
|
const ROUTE_IDS = /`(?:APP_HOME|EXAMPLES_[A-Z]+|NOT_FOUND|REFERENCE_RESOURCE_[A-Z]+)`/gu;
|
|
|
|
it("does not need README or the checklist to list route IDs", async () => {
|
|
const result = await verify({
|
|
"README.md": (readme) => readme.replaceAll(ROUTE_IDS, ""),
|
|
"docs/accessibility/manual-checklist.md": (checklist) => checklist.replaceAll(ROUTE_IDS, ""),
|
|
});
|
|
expect(result.status, result.stderr).toBe(0);
|
|
});
|
|
|
|
it.each([
|
|
["README.md", "scripts/verify-documentation-readiness.ts", "scripts/verify-documentation-readyness.ts"],
|
|
["docs/contracts/compatibility.md", "scripts/check-compatibility.ts", "scripts/check-compatibilty.ts"],
|
|
// reached through the `operations/` directory link
|
|
["docs/operations/release-cache-rollback.md", "scripts/lib/hosting-probe.ts", "scripts/lib/hosting-prob.ts"],
|
|
])("fails when %s names a path that does not exist", async (document, before, after) => {
|
|
const result = await verifyWithReadme((text) => text.replace(`\`${before}\``, `\`${after}\``), document);
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain(`${document} names paths that do not exist: ${after}`);
|
|
expect(result.stderr).toMatch(/\(failed: document references\)/u);
|
|
});
|
|
|
|
it("fails when docs/README.md links a document that does not exist", async () => {
|
|
const result = await verifyWithReadme(
|
|
(index) => index.replace("(architecture/layers.md)", "(architecture/layer.md)"),
|
|
"docs/README.md",
|
|
);
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain("docs/README.md names paths that do not exist: docs/architecture/layer.md");
|
|
});
|
|
|
|
it("fails when a document names a package script or a gate ID that does not exist", async () => {
|
|
const result = await verify({
|
|
"README.md": (readme) => readme.replace("`verify:documentation` fails", "`verify:documentaton` fails"),
|
|
"docs/README.md": (index) => index.replace("(FE-GATE-017)", "(FE-GATE-099)"),
|
|
});
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain("README.md names package scripts that do not exist: verify:documentaton");
|
|
expect(result.stderr).toContain("docs/README.md names gate IDs that config/ci/gates.json does not define: FE-GATE-099");
|
|
});
|
|
|
|
it("does not ask generated output to exist", async () => {
|
|
const result = await verifyWithReadme((readme) => `${readme}\nSee \`artifacts/quality/not-generated-yet.json\`.\n`);
|
|
expect(result.status, result.stderr).toBe(0);
|
|
});
|
|
|
|
it("accepts a path under history a copy deleted, and only that", async () => {
|
|
const naming = (readme: string) => `${readme}\nSee \`docs/retired-notes/plan.md\`.\n`;
|
|
const deleted = await verifyWithReadme((readme) =>
|
|
naming(readme).replace("| Path | Contents |\n| --- | --- |\n", "$&| `docs/retired-notes/` | deleted |\n"),
|
|
);
|
|
expect(deleted.status, deleted.stderr).toBe(0);
|
|
|
|
const missing = await verifyWithReadme(naming);
|
|
expect(missing.status).toBe(1);
|
|
expect(missing.stderr).toContain("README.md names paths that do not exist: docs/retired-notes/plan.md");
|
|
});
|
|
});
|
|
|
|
// 1101/14-03. The entry documents drew a top-level domain layer that does not
|
|
// exist, left out three of the nine src folders, and layers.md named a
|
|
// minority of the architecture rules while claiming it could not drift.
|
|
describe("verify:documentation source structure (1101/14-03)", () => {
|
|
it("fails when layers.md loses a rule name, as renaming a rule does", async () => {
|
|
const result = await verifyWithReadme(
|
|
(layers) => layers.replaceAll("`platform-kernel-is-product-neutral`", "`platform-kernel`"),
|
|
"docs/architecture/layers.md",
|
|
);
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain(
|
|
"docs/architecture/layers.md does not name .dependency-cruiser.json rules: platform-kernel-is-product-neutral",
|
|
);
|
|
expect(result.stderr).toMatch(/\(failed: source structure\)/u);
|
|
});
|
|
|
|
it("fails when a document names a top-level src folder that does not exist", async () => {
|
|
const result = await verifyWithReadme((readme) =>
|
|
readme.replace("presentation -> application -> contracts", "presentation -> application -> `src/domain`"),
|
|
);
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain("README.md names src folders that do not exist: domain");
|
|
});
|
|
|
|
it("fails when a document describes a folder differently from layers.md", async () => {
|
|
const result = await verifyWithReadme(
|
|
(overview) => overview.replace("- `src/platform` — product-neutral", "- `src/platform` — shared"),
|
|
"docs/architecture/overview.md",
|
|
);
|
|
expect(result.status).toBe(1);
|
|
expect(result.stderr).toContain(
|
|
"docs/architecture/overview.md does not describe src folders as the layers.md table does: platform",
|
|
);
|
|
});
|
|
});
|