문제: 프론트 문서 체계는 백엔드와 다르다. 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에서 돌렸다.
332 lines
15 KiB
TypeScript
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([]);
|
|
});
|
|
});
|