Files
clean-architecture-frontend…/tests/unit/documentation-readiness.test.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

368 lines
17 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { mkdirSync, rmSync, writeFileSync } from "node:fs";
import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { devNull, tmpdir } from "node:os";
import path from "node:path";
import { describe, expect, it } from "vitest";
// The pin says which commit of the paired backend the documents describe.
const INPUTS = ["README.md", "docs", "config/contracts/backend-contract-pin.json"];
const PAIRED_BACKEND = "clean-architecture-backend-template";
type Changes = Readonly<Record<string, (text: string) => string>>;
/**
* 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. The
* copy is a `frontend` folder; `paired` builds what sits beside it, where a
* checkout of the paired repositories would be, and returns more changes (a
* pin to its commit).
*/
async function verify(
changes: Changes,
removed: readonly string[] = [],
paired: (parent: string) => Changes = () => ({}),
) {
const parent = await mkdtemp(path.join(tmpdir(), "documentation-readiness-"));
const root = path.join(parent, "frontend");
try {
const pairedChanges = paired(parent);
for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true });
for (const [document, mutate] of Object.entries({ ...changes, ...pairedChanges })) {
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));
const result = spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], {
cwd: root,
encoding: "utf8",
});
const report = await readFile(path.join(root, "artifacts/quality/documentation-review.json"), "utf8")
.then((json) => JSON.parse(json) as {
documentReferences: { path: string; missingPaths?: string[]; unverifiedLinks?: string[] }[];
})
.catch(() => null);
return { ...result, report };
} finally {
await rm(parent, { recursive: true, force: true });
}
}
function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
return verify({ [document]: mutate });
}
const gitEnvironment = {
...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_"))),
GIT_CONFIG_GLOBAL: devNull,
GIT_CONFIG_NOSYSTEM: "1",
};
function git(cwd: string, ...args: string[]): string {
const result = spawnSync(
"git",
["-c", "user.name=fixture", "-c", "user.email=fixture@example.invalid", "-c", "commit.gpgsign=false", ...args],
{ cwd, encoding: "utf8", env: gitEnvironment },
);
if (result.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${result.stderr}`);
return result.stdout.trim();
}
/**
* A git checkout of the paired backend beside the copy: one commit per
* `history` entry (a file set to null is deleted), then `uncommitted` written
* to its working tree. Returns the commit ids.
*/
function pairedCheckout(
parent: string,
history: readonly Readonly<Record<string, string | null>>[],
uncommitted: Readonly<Record<string, string>> = {},
): string[] {
const root = path.join(parent, PAIRED_BACKEND);
const write = (files: Readonly<Record<string, string | null>>) => {
for (const [file, content] of Object.entries(files)) {
const target = path.join(root, file);
if (content === null) {
rmSync(target);
} else {
mkdirSync(path.dirname(target), { recursive: true });
writeFileSync(target, content);
}
}
};
mkdirSync(root, { recursive: true });
git(root, "init", "-q");
const commits: string[] = [];
for (const files of history) {
write(files);
git(root, "add", "-A");
git(root, "commit", "-q", "--allow-empty", "-m", `fixture ${commits.length}`);
commits.push(git(root, "rev-parse", "HEAD"));
}
write(uncommitted);
return commits;
}
function pinnedTo(commit: string): Changes {
return {
"config/contracts/backend-contract-pin.json": (pin) =>
pin.replace(/"commit": "[0-9a-f]+"/u, `"commit": "${commit}"`),
};
}
// 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({}, ["docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md"]);
expect(result.status).toBe(1);
expect(result.stderr).toContain("docs/accessibility/route-reviews/ 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`", "") },
["docs/accessibility/route-reviews/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)", () => {
// Written without the sample's route prefix: the sample removal drill runs
// this file and refuses any file that still names the removed sample.
const ROUTE_IDS = /`(?:APP_HOME|EXAMPLES_[A-Z]+|NOT_FOUND|[A-Z]+_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");
});
});
// 1103/12-05. Paths inside a command and links into the paired repositories
// were never looked up: a deleted V2 test stayed in a `vitest run` command,
// and a broken link to the backend template's contract passed.
describe("verify:documentation commands and sibling links (1103/12-05)", () => {
const CI_DOC = "docs/operations/ci-quality-gates.md";
const BACKEND = "clean-architecture-backend-template/docs/web/http-contract.md";
it.each([
["an inline command", "`corepack pnpm exec vitest run tests/integration/no-such-client.test.ts`"],
["a shell block", "```bash\nnode tests/integration/no-such-client.test.ts --flag\n```"],
])("fails when %s names a path that does not exist", async (_shape, line) => {
const result = await verify({ [CI_DOC]: (text) => `${text}\n${line}\n` });
expect(result.status).toBe(1);
expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: tests/integration/no-such-client.test.ts`);
});
it("looks up a command's existing arguments and leaves placeholders alone", async () => {
const result = await verify({
[CI_DOC]: (text) => `${text}\n\`corepack pnpm exec vitest run tests/unit/documentation-readiness.test.ts -t "x"\`\n` +
"```bash\ncorepack pnpm drill:runbook -- FE-RB-005 --release-root <release dir>\n```\n",
});
expect(result.status, result.stderr).toBe(0);
});
it("checks a link or a path into a paired repository checked out beside this one", async () => {
const naming = (target: string) => (text: string) =>
`${text}\n[contract](../../../${target}) and \`${target}\`\n`;
// 1105/12-02. The checkout is looked up at the pinned commit.
const pinnedBackend = (parent: string) =>
pinnedTo(pairedCheckout(parent, [{ "docs/web/http-contract.md": "# contract\n" }])[0]!);
const present = await verify({ [CI_DOC]: naming(BACKEND) }, [], pinnedBackend);
// Only this document is under test: other documents name paired-backend
// paths the stub checkout does not have.
expect(present.stderr).not.toContain(`${CI_DOC} names paths that do not exist`);
expect(
present.report?.documentReferences.find((entry) => entry.path === CI_DOC)?.missingPaths,
).toEqual([]);
const broken = await verify(
{ [CI_DOC]: naming("clean-architecture-backend-template/docs/web/no-such.md") },
[],
pinnedBackend,
);
expect(broken.status).toBe(1);
expect(broken.stderr).toContain(
`${CI_DOC} names paths that do not exist: ../clean-architecture-backend-template/docs/web/no-such.md`,
);
});
it("reports a link into a paired repository that is not checked out as unverified", async () => {
const result = await verify({
[CI_DOC]: (text) => `${text}\n[contract](../../../clean-architecture-backend-template/docs/web/no-such.md)\n`,
});
expect(result.status, result.stderr).toBe(0);
expect(result.stdout).toContain("not verified");
expect(result.report?.documentReferences.find((entry) => entry.path === CI_DOC)?.unverifiedLinks)
.toEqual(["../clean-architecture-backend-template/docs/web/no-such.md"]);
});
});
// 1105/12-02. Paired references were looked up in the working tree of the
// checkout beside this one, so the same commit failed on the desktop (a
// sibling months behind with uncommitted changes), passed with 17 references
// unverified where no sibling was, and a misspelled repository passed as
// unverified. They are looked up at the commit the pin names.
describe("verify:documentation paired references at the pinned commit (1105/12-02)", () => {
const CI_DOC = "docs/operations/ci-quality-gates.md";
const naming = (...targets: string[]) => (text: string) =>
`${text}\n${targets.map((target) => `[link](../../../${target}) and \`${target}\``).join("\n")}\n`;
const entryOf = (result: Awaited<ReturnType<typeof verify>>) =>
result.report?.documentReferences.find((entry) => entry.path === CI_DOC);
it("looks a reference up in the pinned commit, not in a later HEAD or the working tree", async () => {
const result = await verify(
{
[CI_DOC]: naming(
`${PAIRED_BACKEND}/docs/web/http-contract.md`,
`${PAIRED_BACKEND}/docs/web/after-pin.md`,
`${PAIRED_BACKEND}/docs/web/uncommitted.md`,
),
},
[],
(parent) => {
const [pinned] = pairedCheckout(
parent,
[
{ "docs/web/http-contract.md": "# contract\n" },
{ "docs/web/http-contract.md": null, "docs/web/after-pin.md": "# later\n" },
],
{ "docs/web/uncommitted.md": "# draft\n" },
);
return pinnedTo(pinned!);
},
);
// Other documents name paired paths the stub does not have, so only this
// document's entry is compared.
expect(entryOf(result)?.missingPaths).toEqual([
`../${PAIRED_BACKEND}/docs/web/after-pin.md`,
`../${PAIRED_BACKEND}/docs/web/uncommitted.md`,
]);
expect(entryOf(result)?.unverifiedLinks).toEqual([]);
expect(result.stderr).toContain("at the pinned commit (looked up in clean-architecture-backend-template ");
});
it("reports the references as not verified when the checkout does not have the pinned commit", async () => {
// The desktop case: a sibling whose history stops before the pin, with
// none of the files the documents name.
const result = await verify({ [CI_DOC]: naming(`${PAIRED_BACKEND}/docs/web/no-such.md`) }, [], (parent) => {
pairedCheckout(parent, [{ "README.md": "# an older backend\n" }]);
return {};
});
expect(result.status, result.stderr).toBe(0);
expect(entryOf(result)?.missingPaths).toEqual([]);
expect(entryOf(result)?.unverifiedLinks).toEqual([`../${PAIRED_BACKEND}/docs/web/no-such.md`]);
expect(result.stdout).toContain("not verified");
expect(result.stdout).toContain("does not have the pinned commit");
});
it("fails a link out of the repository into a repository that is not paired", async () => {
const misspelled = "clean-architecture-backend-templat/docs/web/http-contract.md";
const result = await verify({ [CI_DOC]: (text) => `${text}\n[contract](../../../${misspelled})\n` });
expect(result.status).toBe(1);
expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: ../${misspelled}`);
});
});
// 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",
);
});
});