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; 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([]); }); });