Files
clean-architecture-frontend…/tests/unit/docs-system.test.ts
DongHyeonka 7a9aefdf25 feat(docs): 문서 체계 검사를 verify:documentation에 더하고 입구 문서를 고친다
문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.

고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
  3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
  도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
  이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
  FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
  번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
  검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
  절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
  글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
  테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
  폴더 이름을 적지만 지운 사본에서도 통과하므로
  deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
  테스트와 검사기 시험에 적었다).

위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).

검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
2026-11-08 21:57:39 +09:00

332 lines
15 KiB
TypeScript

import { createHash } from "node:crypto";
import { describe, expect, it } from "vitest";
import {
type DocsDocument,
type DocsFacts,
type DocsSystemCheck,
HEAD_END,
HEAD_START,
isEnglish,
requiredFolders,
runDocsSystemChecks,
} from "../../scripts/lib/docs-system.ts";
/**
* The checker's own test (docs-system.md 7: a broken input fails, and each
* condition of a verdict has an input that only it catches). Inputs are in
* memory; verify:documentation runs the same checks on this repository.
*/
const KOREAN = "이 문서는 지금 동작을 설명한다. 코드와 같은 변경에서 고친다.\n";
const ENGLISH = "This document describes the current behaviour and is kept with the code that it explains.\n";
const facts: DocsFacts = {
knownPaths: new Set(["docs", "docs/architecture", "docs/architecture/layers.md", "src", "src/platform"]),
docsFiles: ["docs/README.md", "docs/architecture/layers.md", "docs/history/plans/a.md"],
frameworkVersions: new Map([
["React", "19.2.8"],
["Node.js", "24.14.0"],
]),
deletable: ["docs/history", "docs/reviews"],
};
const MAP = [
"# 문서",
"",
"| 폴더 | 무엇 |",
"| --- | --- |",
"| `architecture/` | 현재 계약 |",
"| `history/plans/` | 계획서 |",
"",
].join("\n");
const README = [
"# 템플릿",
"",
"템플릿을 받아 도메인을 채우는 서비스가 쓴다.",
"",
"## 프로젝트 구조",
"## 시작하기",
"## 기능 켜고 끄기",
"## 문서 지도",
"## 검증",
"## 새 서비스로 시작하기",
"## 규칙과 기여",
"",
].join("\n");
function head(label: string, fields: readonly string[]): string {
return [HEAD_START, label, "", ...fields, HEAD_END, "", "# Original title", "", ENGLISH].join("\n");
}
const PLAN_LABEL = "> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.";
const DECISION_LABEL =
"> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.";
const PLAN_FIELDS = Object.freeze([
"- 상태: 끝남",
"- 작성일: 2026-09-25",
"- 요약: 리뷰 발견을 고치는 실행 계획이다.",
"- 현재 정본: `docs/architecture/layers.md`",
]);
/** The fixed documents every case starts from: they pass every check. */
function baseDocuments(): DocsDocument[] {
return [
{ path: "README.md", text: README },
{ path: "docs/README.md", text: MAP },
{ path: "docs/architecture/layers.md", text: KOREAN },
{ path: "docs/history/plans/a.md", text: head(PLAN_LABEL, PLAN_FIELDS) },
];
}
function run(
check: DocsSystemCheck,
documents: readonly DocsDocument[],
options: Readonly<{ exceptions?: string; frozen?: ReadonlySet<string>; facts?: DocsFacts }> = {},
) {
return runDocsSystemChecks({
documents: [...baseDocuments().filter((base) => !documents.some(({ path }) => path === base.path)), ...documents],
facts: options.facts ?? facts,
only: [check],
// The repository's own baseline is not this test's input.
frozen: options.frozen ?? new Set(),
...(options.exceptions === undefined ? {} : { exceptions: options.exceptions }),
}).failures;
}
describe("docs-system checks on documents that follow the rules", () => {
it("pass", () => {
const result = runDocsSystemChecks({ documents: baseDocuments(), facts, frozen: new Set() });
expect(result.failures).toEqual([]);
expect(result.report).toHaveLength(6);
});
});
describe("language (H11)", () => {
it("fails an English living document", () => {
expect(run("language", [{ path: "docs/architecture/layers.md", text: ENGLISH }])).toEqual([
expect.stringContaining("[language] docs/architecture/layers.md: the body is English"),
]);
});
it("fails an English decision record body, below its head block", () => {
const text = head(DECISION_LABEL, ["- 상태: 채택", "- 작성일: 2026-08-01", "- 요약: 결정이다.", "- 현재 정본: 없음 — 예"]);
expect(run("language", [{ path: "docs/adr/VD-99-x.md", text }])).toHaveLength(1);
});
it("does not read record bodies or reviews, which keep the language they were written in", () => {
expect(run("language", [{ path: "docs/reviews/2026-01-01-review.md", text: ENGLISH }])).toEqual([]);
});
it("reads the one living file under reviews", () => {
expect(run("language", [{ path: "docs/reviews/adapters/INVENTORY.md", text: ENGLISH }])).toHaveLength(1);
});
it("does not count code, commands, quotes, links, paths or file names", () => {
const text = [
KOREAN,
"```bash",
"corepack pnpm verify:documentation and many more english words here",
"```",
"`these words are inline code` [and these are a link](https://example.com/a)",
"> quoted lines are left out of the verdict entirely",
'and "a quoted English phrase" src/some/path/here.ts docs/README.md',
].join("\n");
expect(isEnglish(text)).toBe(false);
});
it("needs three English words and a Hangul share under 0.3", () => {
expect(isEnglish("two words")).toBe(false);
expect(isEnglish("three english words")).toBe(true);
expect(isEnglish("한국어 문장 셋이면 three english words")).toBe(false);
});
});
describe("head blocks of records", () => {
const plan = (fields: readonly string[], label = PLAN_LABEL) => [
{ path: "docs/history/plans/a.md", text: head(label, fields) },
];
it("fails a record without one", () => {
expect(run("head", [{ path: "docs/design/2026-01-01-x-design.md", text: ENGLISH }])).toEqual([
expect.stringContaining("no head block at the top"),
]);
});
it("fails the wrong second line for the folder", () => {
expect(run("head", plan(PLAN_FIELDS, PLAN_LABEL.replace("계획서", "설계서")))).toEqual([
expect.stringContaining("the second line is"),
]);
});
it("takes either decision record label", () => {
const fields = ["- 상태: 채택(보완)", "- 작성일: 2026-08-01", "- 요약: 결정이다.", "- 현재 정본: `src/platform`"];
const translated = DECISION_LABEL.replace("원문이다.", "내용이다(번역은 뜻을 바꾸지 않았다).");
expect(run("head", [{ path: "docs/adr/VD-01-x.md", text: head(DECISION_LABEL, fields) }])).toEqual([]);
expect(run("head", [{ path: "docs/adr/VD-01-x.md", text: head(translated, fields) }])).toEqual([]);
});
it.each([
["a status outside the kind's vocabulary", "- 상태: 채택", "the status of a 계획서 is one of"],
["a date that is not YYYY-MM-DD", "- 작성일: 2026-02-30", "the date is YYYY-MM-DD"],
["an English summary", "- 요약: An execution plan for the review findings.", "the summary is one Korean sentence"],
["a canonical path that does not exist", "- 현재 정본: `docs/architecture/gone.md`", "the current canonical path does not exist"],
["a canonical that is neither a path nor 없음", "- 현재 정본: 레이어 문서", "the current canonical is `path`"],
])("fails %s", (_, replacement, message) => {
const name = replacement.slice(2, replacement.indexOf(":"));
const fields = PLAN_FIELDS.map((field) => (field.startsWith(`- ${name}:`) ? replacement : field));
expect(run("head", plan(fields))).toEqual([expect.stringContaining(message)]);
});
it("fails a missing field, an unknown field and a repeated field", () => {
expect(run("head", plan(PLAN_FIELDS.slice(1)))).toEqual([expect.stringContaining("no 「상태」 field")]);
expect(run("head", plan([...PLAN_FIELDS, "- 종류: 계획서"]))).toEqual([
expect.stringContaining("not a head block field: 종류"),
]);
expect(run("head", plan([...PLAN_FIELDS, "- 상태: 끝남"]))).toEqual([
expect.stringContaining("field given twice: 상태"),
]);
});
it("fails a superseded record that does not name its replacement, or names one that is gone", () => {
const superseded = PLAN_FIELDS.map((field) => (field.startsWith("- 상태:") ? "- 상태: 대체됨" : field));
expect(run("head", plan(superseded))).toEqual([expect.stringContaining("names its replacement in 「대체됨」")]);
expect(run("head", plan([...superseded, "- 대체됨: `docs/design/gone.md`"]))).toEqual([
expect.stringContaining("the 「대체됨」 path does not exist"),
]);
expect(run("head", plan([...superseded, "- 대체됨: `docs/architecture/layers.md`"]))).toEqual([]);
});
it("fails a block that does not end within its first 20 lines", () => {
const text = [HEAD_START, PLAN_LABEL, "", ...PLAN_FIELDS, ...Array(15).fill(""), HEAD_END, "", ENGLISH].join("\n");
expect(run("head", [{ path: "docs/history/plans/a.md", text }])).toEqual([
expect.stringContaining("no head block at the top"),
]);
});
});
describe("copied numbers", () => {
const living = (line: string) => [{ path: "docs/architecture/layers.md", text: `${KOREAN}${line}\n` }];
it.each([
["a framework version next to its name", "React 19.1.0을 쓴다.", "framework version"],
["the version package.json pins, wherever it stands", "| 런타임 | 24.14.0 |", "Node.js version"],
["a gate count", "merge 단계 게이트 14개가 돈다.", "gate count"],
["a recipe count", "12개 recipe가 있다.", "recipe count"],
["an adapter count", "adapter 119개를 센다.", "adapter count"],
])("fails %s", (_, line, label) => {
expect(run("number", living(line))).toEqual([expect.stringContaining(label)]);
});
it("counts a version next to its name once", () => {
expect(run("number", living("React 19.2.8을 쓴다."))).toHaveLength(1);
});
it("does not read CHANGELOG.md, decision records or records, which name past states", () => {
expect(run("number", [{ path: "CHANGELOG.md", text: "게이트 14개, React 19.1.0\n" }])).toEqual([]);
expect(run("number", [{ path: "docs/reviews/r.md", text: "게이트 14개\n" }])).toEqual([]);
});
});
describe("documents map", () => {
it("fails a documents folder the map does not list", () => {
const withFolder: DocsFacts = { ...facts, docsFiles: [...facts.docsFiles, "docs/runbooks/FE-RB-001.md"] };
expect(run("map", [], { facts: withFolder })).toEqual([expect.stringContaining("does not list: docs/runbooks/")]);
});
it("fails a listed folder that does not exist", () => {
const map = `${MAP}| \`security/\` | 보안 |\n`;
expect(run("map", [{ path: "docs/README.md", text: map }])).toEqual([
expect.stringContaining("a mapped folder that does not exist: docs/security/"),
]);
});
it("passes a copy that deleted its history, whose map still lists the history folders", () => {
const deleted: DocsFacts = { ...facts, docsFiles: facts.docsFiles.filter((path) => !path.startsWith("docs/history/")) };
const documents = baseDocuments().filter(({ path }) => !path.startsWith("docs/history/"));
expect(runDocsSystemChecks({ documents, facts: deleted, frozen: new Set() }).failures).toEqual([]);
expect(runDocsSystemChecks({ documents, facts: { ...deleted, deletable: [] }, frozen: new Set() }).failures).toEqual([
expect.stringContaining("a mapped folder that does not exist: docs/history/plans/"),
]);
});
it("asks for the folders under a folder that holds only folders", () => {
expect([...requiredFolders(["README.md", "history/plans/a.md", "history/evidence/b/c.md", "manual/x.md"])].sort())
.toEqual(["history/evidence/", "history/plans/", "manual/"]);
});
});
describe("root README sections", () => {
it("fails a missing required section", () => {
expect(run("readme", [{ path: "README.md", text: README.replace("## 문서 지도\n", "") }])).toEqual([
expect.stringContaining("no 「## 문서 지도」 section"),
]);
});
it("fails sections out of order", () => {
const swapped = README.replace("## 프로젝트 구조\n## 시작하기", "## 시작하기\n## 프로젝트 구조");
expect(run("readme", [{ path: "README.md", text: swapped }])).toEqual([
expect.stringContaining("the 「## 시작하기」 section comes after 「## 프로젝트 구조」"),
]);
});
it("fails a README without a title line or an intro paragraph", () => {
expect(run("readme", [{ path: "README.md", text: README.replace("# 템플릿\n", "템플릿\n") }])).toEqual([
expect.stringContaining("the first line is `# 제목`"),
]);
expect(run("readme", [{ path: "README.md", text: README.replace("템플릿을 받아 도메인을 채우는 서비스가 쓴다.\n", "") }]))
.toEqual([expect.stringContaining("put one paragraph")]);
});
});
describe("style", () => {
it("fails a polite sentence ending", () => {
expect(run("style", [{ path: "docs/architecture/layers.md", text: `${KOREAN}이 문서를 설명합니다.\n` }])).toEqual([
expect.stringContaining("[style] docs/architecture/layers.md:2: polite form"),
]);
});
it("does not read quotes, code or `> 이력` blocks", () => {
const text = [KOREAN, "「~합니다」로 쓰지 않는다.", "`설명합니다`", "```", "설명합니다.", "```", "> 이력: 예전에는 설명했습니다."].join("\n");
expect(run("style", [{ path: "docs/architecture/layers.md", text }])).toEqual([]);
});
});
describe("the exception list only shrinks", () => {
const line = "language\tdocs/architecture/layers.md";
const english = [{ path: "docs/architecture/layers.md", text: ENGLISH }];
const frozen = new Set([createHash("sha256").update(line, "utf8").digest("hex").slice(0, 16)]);
it("excuses a frozen line", () => {
expect(run("language", english, { exceptions: `${line}\n`, frozen })).toEqual([]);
});
it("fails a line that is not frozen", () => {
expect(run("language", english, { exceptions: `${line}\n`, frozen: new Set() })).toEqual([
expect.stringContaining("not in the baseline"),
]);
});
it("fails a frozen fingerprint whose line was deleted", () => {
expect(run("language", english, { exceptions: "", frozen })).toEqual(
expect.arrayContaining([expect.stringContaining("a fingerprint with no line")]),
);
});
it("fails a line that no longer matches", () => {
expect(run("language", [], { exceptions: `${line}\n`, frozen })).toEqual([
expect.stringContaining("no longer matches; delete the line"),
]);
});
it("does not call a line stale when its document is not in the tree checked", () => {
const absent = "language\tdocs/runbooks/FE-RB-009.md";
const frozenAbsent = new Set([createHash("sha256").update(absent, "utf8").digest("hex").slice(0, 16)]);
expect(run("language", [], { exceptions: `${absent}\n`, frozen: frozenAbsent })).toEqual([]);
});
it("reads `#` lines and blank lines as comments", () => {
expect(run("language", [], { exceptions: "# 설명\n\n", frozen: new Set() })).toEqual([]);
});
});