문제: 프론트 문서 체계는 백엔드와 다르다. 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에서 돌렸다.
774 lines
33 KiB
TypeScript
774 lines
33 KiB
TypeScript
import { spawnSync } from "node:child_process";
|
||
import { createHash } from "node:crypto";
|
||
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
||
import { join, normalize } from "node:path/posix";
|
||
|
||
/**
|
||
* The document rules of design-docs `conventions/docs-system.md` that a
|
||
* machine can check, applied as docs/README.md 「문서 수명과 언어」 says.
|
||
* verify:documentation (FE-GATE-017) runs them on every pull request; the
|
||
* paths, links, package scripts and gate IDs a living document names are its
|
||
* own `document references` check, which reads every living document listed
|
||
* here.
|
||
*
|
||
* This is the backend template's `scripts/check-docs.py` ported rule by rule
|
||
* (same names, same thresholds, same exception list semantics), so the two
|
||
* templates fail on the same documents:
|
||
*
|
||
* language a living document or decision record body is Korean. The
|
||
* verdict is the report-language hook's H11: code, commands,
|
||
* quotes, links, URLs, paths and file names are left out; three
|
||
* or more English words with a Hangul share under 0.3 is English.
|
||
* head a record (docs/design, docs/history, docs/adr) starts with the
|
||
* head block: status from its kind's vocabulary, a date, a Korean
|
||
* summary, and current-canonical and superseded-by paths that exist.
|
||
* number a living document does not copy a number its source of truth
|
||
* owns: a framework version (package.json, .nvmrc) or a count of
|
||
* gates, recipes or adapters (config/ci/gates.json, the recipe
|
||
* catalog, docs/reviews/adapters/INVENTORY.md).
|
||
* map docs/README.md's map covers every documents folder, and every
|
||
* folder it lists exists.
|
||
* readme README.md has its title, an intro paragraph and the required
|
||
* `##` sections in order.
|
||
* style a living document does not end sentences in the polite form
|
||
* (「~합니다」). It is written in 「~한다」.
|
||
*
|
||
* The exception list (scripts/docs-system-exceptions.txt) only shrinks: each
|
||
* line needs its fingerprint in FROZEN, each FROZEN fingerprint needs its
|
||
* line, and a line that no longer matches a problem fails until it is deleted.
|
||
* Growing FROZEN changes the rule and needs the owner's decision.
|
||
*/
|
||
|
||
export const DOCS_SYSTEM_CHECKS = Object.freeze(["language", "head", "number", "map", "readme", "style"] as const);
|
||
export type DocsSystemCheck = (typeof DOCS_SYSTEM_CHECKS)[number];
|
||
|
||
export type DocsProblem = Readonly<{
|
||
check: DocsSystemCheck;
|
||
path: string;
|
||
key: string;
|
||
message: string;
|
||
line: number;
|
||
}>;
|
||
|
||
/** A document is its path (from the documents root) and its text. */
|
||
export type DocsDocument = Readonly<{ path: string; text: string }>;
|
||
|
||
export const EXCEPTIONS_FILE = "scripts/docs-system-exceptions.txt";
|
||
/**
|
||
* Fingerprints (sha256, first 16 hex) of the exception list lines: the
|
||
* 2026-11-08 baseline, which only shrinks. When it is empty no document is
|
||
* excused, and any line added to the list fails.
|
||
*/
|
||
export const FROZEN: ReadonlySet<string> = new Set<string>([
|
||
"cd62292c1faf9312",
|
||
"9ebf8141a4434f32",
|
||
"64bb8316aafc4fcc",
|
||
"80ca3b198759492f",
|
||
"89616e7ca7b409d5",
|
||
"021ee3958bdd58af",
|
||
"1f94ecba91dcd1df",
|
||
"0ea431405727b1ba",
|
||
"29d6b489d280d464",
|
||
"f0eed09117035063",
|
||
"f6c533a3450c74be",
|
||
"b76f8449ca6ad18b",
|
||
"61a22114f0f80622",
|
||
"ee082cac5fe9f20e",
|
||
"2fcb1b008276a6f0",
|
||
"d1b5e5cfbd8887fc",
|
||
"67fcfa6470a125a0",
|
||
"07db060102714081",
|
||
"a42bc30fb525d6c9",
|
||
"59569b9b066cffcc",
|
||
"cac81d51afa3db95",
|
||
"33ba6f03c95bd8e7",
|
||
"dce0f0c48d3876a4",
|
||
"e1e286fae81074d4",
|
||
"4495c81b34b2ccc9",
|
||
"9b5a07b82e98f153",
|
||
"24298b522fdc5404",
|
||
"d21b67aefa16fe30",
|
||
"c93a4077c595bfd6",
|
||
"e23d9d9bf15712e4",
|
||
"09f0dfe98de3c278",
|
||
"e7f28af3b9e31580",
|
||
"7d97ca40a8ec73f8",
|
||
"399a89014bf0dda7",
|
||
"4360f2d0bd948db2",
|
||
"6fd03906dc2c2f23",
|
||
"1e550a75f934225e",
|
||
"ec854cee6e8ca7dd",
|
||
"bf813a1c94ef9800",
|
||
"e3b8f5f5b45d54c2",
|
||
"9b512220105c506a",
|
||
"c38dda017bafd925",
|
||
]);
|
||
|
||
type RecordKind = "설계서" | "계획서" | "증거" | "납품 패키지" | "학습 문서" | "결정 기록";
|
||
|
||
// The folder decides the kind of a record (docs-system.md 4.1).
|
||
const RECORD_KINDS: readonly (readonly [string, RecordKind])[] = Object.freeze([
|
||
["docs/design/", "설계서"],
|
||
["docs/history/plans/", "계획서"],
|
||
["docs/history/evidence/", "증거"],
|
||
["docs/history/packages/", "납품 패키지"],
|
||
["docs/history/study/", "학습 문서"],
|
||
["docs/adr/", "결정 기록"],
|
||
]);
|
||
// Reviews are records as well; they do not need a head block yet.
|
||
const RECORD_FOLDERS = Object.freeze(["docs/design/", "docs/history/", "docs/reviews/"]);
|
||
const DECISION_FOLDER = "docs/adr/";
|
||
// The one file under docs/reviews/ that is kept current: check:adapter-inventory
|
||
// compares it with src/adapters on every change.
|
||
const LIVING_IN_RECORDS: ReadonlySet<string> = new Set(["docs/reviews/adapters/INVENTORY.md"]);
|
||
// Living documents that name past states on purpose. CHANGELOG.md names
|
||
// removed scripts, old paths and the versions a release shipped;
|
||
// review-evidence.md is the copy of the 2026-07-18 diagram review, whose paths
|
||
// are in the reviewing workspace (docs/architecture/review-ledger.json `note`).
|
||
// The number check and the reference check of verify:documentation skip them.
|
||
export const HISTORY_HOLDERS: ReadonlySet<string> = new Set([
|
||
"CHANGELOG.md",
|
||
"docs/architecture/review-evidence.md",
|
||
]);
|
||
// Not documents: the manual accessibility records are gate input in a fixed
|
||
// English key format (scripts/lib/manual-a11y-evidence.ts), like the backend's
|
||
// test resources.
|
||
const NOT_DOCUMENT = /^artifacts\/tests\/a11y-manual\//u;
|
||
const IGNORED_FOLDERS: ReadonlySet<string> = new Set(["node_modules", ".git"]);
|
||
|
||
const STATUS: Readonly<Record<RecordKind, readonly string[]>> = Object.freeze({
|
||
설계서: ["제안", "채택", "구현됨", "보류", "폐기", "대체됨", "확인 안 함"],
|
||
"결정 기록": ["제안", "채택", "채택(보완)", "폐기", "대체됨"],
|
||
계획서: ["실행 중", "끝남", "중단", "대체됨", "확인 안 함"],
|
||
"납품 패키지": ["보관"],
|
||
증거: ["보관"],
|
||
"학습 문서": ["보관"],
|
||
});
|
||
export const HEAD_START = "<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->";
|
||
export const HEAD_END = "<!-- 머리 블록 끝 -->";
|
||
const recordLabel = (kind: RecordKind) =>
|
||
`> **기록 · ${kind}** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.`;
|
||
// The frontend VD were written in Korean and are not translated, so their
|
||
// label is the original-text one; a decision record whose body is translated
|
||
// later takes the second (docs-system.md 4.1).
|
||
const DECISION_LABELS = Object.freeze([
|
||
"> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.",
|
||
"> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.",
|
||
]);
|
||
const HEAD_FIELDS = Object.freeze(["상태", "작성일", "요약", "현재 정본"]);
|
||
const HEAD_OPTIONAL = Object.freeze(["대체", "대체됨"]);
|
||
const HEAD_SEARCH_LINES = 20;
|
||
|
||
export const MAP_FILE = "docs/README.md";
|
||
const DOCS_ROOT = "docs/";
|
||
export const README_FILE = "README.md";
|
||
// The list and order are docs-system.md 6.1's.
|
||
export const README_SECTIONS = Object.freeze([
|
||
"프로젝트 구조",
|
||
"시작하기",
|
||
"기능 켜고 끄기",
|
||
"문서 지도",
|
||
"검증",
|
||
"새 서비스로 시작하기",
|
||
"규칙과 기여",
|
||
]);
|
||
|
||
// --- Language verdict: H11 of the report-language hook, as check-docs.py has it.
|
||
const MIN_ENGLISH = 3;
|
||
const MIN_KOREAN_SHARE = 0.3;
|
||
const HANGUL = /[가-힣]+/gu;
|
||
const FENCE = /^[ \t]*(`{3,}|~{3,})/u;
|
||
const INLINE = /(`+)(?:(?!\1)[\s\S])+?\1/gu;
|
||
const MDLINK = /\[[^\]\n]*\]\([^)\s]*\)/gu;
|
||
const URL = /(?:\b[a-z][a-z0-9+.-]*:\/\/|\bwww\.)\S+/giu;
|
||
const PATHLIKE = /[^\s가-힣]*[/\\][^\s가-힣]*/gu;
|
||
const FILELIKE = /[^\s가-힣]+\.[A-Za-z]{1,10}(?::\d+)*(?![A-Za-z])/gu;
|
||
const QUOTED = /"[^"\n]*"|“[^”\n]*”/gu;
|
||
const TOKEN = /[^\s가-힣]+/gu;
|
||
const WORD = /^[(["'“‘*_]*[A-Za-z][a-z]*(?:['’][a-z]+)?(?:-[a-z]+)*[)\]"'”’*_.,;:!?…]*$/u;
|
||
const HISTORY_QUOTE = /^\s*>\s*(?:\*\*)?이력/u;
|
||
const CORNER_QUOTED = /「[^」\n]*」/gu;
|
||
const POLITE = /(?:습니다|합니다|입니다|됩니다|십시오|하세요|주세요)(?=[.!?)\]」\s]|$)/u;
|
||
|
||
// --- Copied numbers.
|
||
const FRAMEWORKS = Object.freeze([
|
||
["React", "react"],
|
||
["React DOM", "react-dom"],
|
||
["React Router", "react-router"],
|
||
["Vite", "vite"],
|
||
["TypeScript", "typescript"],
|
||
["Vitest", "vitest"],
|
||
["Playwright", "@playwright/test"],
|
||
["TanStack Query", "@tanstack/react-query"],
|
||
["Zod", "zod"],
|
||
["Storybook", "storybook"],
|
||
] as const);
|
||
const NAMED_VERSION =
|
||
/\b(?:React(?: DOM| Router)?|Vite|TypeScript|Vitest|Playwright|TanStack Query|Zod|Storybook|Node(?:\.js)?)\s+v?\d+\.\d+(?:\.\d+)?\b/gu;
|
||
const COPIED_COUNTS = Object.freeze([
|
||
[
|
||
"gate count (config/ci/gates.json)",
|
||
/\b\d+\s*개의?\s*(?:merge\s*)?(?:게이트|gate)|(?:게이트|gate)\s*\d+\s*개|\b\d+\s+(?:merge\s+)?gates\b/giu,
|
||
],
|
||
["recipe count (config/recipes/frontend-capability-recipes.json)", /\b\d+\s*개의?\s*recipe|recipe\s*\d+\s*개|\b\d+\s+recipes\b/giu],
|
||
["adapter count (docs/reviews/adapters/INVENTORY.md)", /\b\d+\s*개의?\s*adapter|adapter\s*\d+\s*개|\b\d+\s+adapters\b/giu],
|
||
] as const);
|
||
|
||
const sha16 = (line: string) => createHash("sha256").update(line, "utf8").digest("hex").slice(0, 16);
|
||
|
||
export function exceptionLine(problem: DocsProblem): string {
|
||
return [problem.check, problem.path, problem.key].filter((part) => part !== "").join("\t");
|
||
}
|
||
|
||
export function renderProblem(problem: DocsProblem): string {
|
||
return `[${problem.check}] ${problem.line > 0 ? `${problem.path}:${problem.line}` : problem.path}: ${problem.message}`;
|
||
}
|
||
|
||
export function recordKind(path: string): RecordKind | null {
|
||
return RECORD_KINDS.find(([prefix]) => path.startsWith(prefix))?.[1] ?? null;
|
||
}
|
||
|
||
/** Living documents and decision records: what the language and style checks read. */
|
||
export function isLiving(path: string): boolean {
|
||
return LIVING_IN_RECORDS.has(path) || !RECORD_FOLDERS.some((folder) => path.startsWith(folder));
|
||
}
|
||
|
||
/** Living documents whose named paths and numbers must be current. */
|
||
export function checkedForDrift(path: string): boolean {
|
||
return isLiving(path) && !path.startsWith(DECISION_FOLDER) && !HISTORY_HOLDERS.has(path);
|
||
}
|
||
|
||
function stripHeadBlock(lines: readonly string[]): readonly string[] {
|
||
const end = lines.slice(0, HEAD_SEARCH_LINES).indexOf(HEAD_END);
|
||
return lines[0] === HEAD_START && end > 0 ? lines.slice(end + 1) : lines;
|
||
}
|
||
|
||
function stripFrontMatter(lines: readonly string[]): readonly string[] {
|
||
if (lines[0]?.trim() !== "---") return lines;
|
||
const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
|
||
return end > 0 ? lines.slice(end + 1) : lines;
|
||
}
|
||
|
||
/** The body: the text without its head block and front matter. */
|
||
export function bodyLines(text: string): readonly string[] {
|
||
return stripFrontMatter(stripHeadBlock(text.split("\n")));
|
||
}
|
||
|
||
type Fence = Readonly<{ marker: string }> | null;
|
||
function closesFence(fence: Fence, line: string): boolean {
|
||
const match = FENCE.exec(line);
|
||
return fence !== null && match !== null && match[1]?.[0] === fence.marker[0] && match[1].length >= fence.marker.length;
|
||
}
|
||
|
||
/** (line number, line) outside fenced code, and outside `> 이력` quotes when asked. */
|
||
function outsideCode(lines: readonly string[], skipHistory: boolean): (readonly [number, string])[] {
|
||
const kept: (readonly [number, string])[] = [];
|
||
let fence: Fence = null;
|
||
let history = false;
|
||
lines.forEach((line, index) => {
|
||
if (fence !== null) {
|
||
if (closesFence(fence, line)) fence = null;
|
||
return;
|
||
}
|
||
const open = FENCE.exec(line);
|
||
if (open) {
|
||
fence = { marker: open[1] ?? "```" };
|
||
return;
|
||
}
|
||
const quoted = line.trimStart().startsWith(">");
|
||
if (quoted && HISTORY_QUOTE.test(line)) history = true;
|
||
else if (!quoted) history = false;
|
||
if (!(skipHistory && history)) kept.push([index + 1, line]);
|
||
});
|
||
return kept;
|
||
}
|
||
|
||
/** The text the verdict reads: H11's prose(). */
|
||
export function prose(text: string): string {
|
||
const kept = outsideCode(text.split("\n"), false)
|
||
.map(([, line]) => line)
|
||
.filter((line) => !line.trimStart().startsWith("$ ") && !line.trimStart().startsWith(">"));
|
||
let cleaned = kept.join("\n");
|
||
for (const pattern of [INLINE, MDLINK, URL, QUOTED, PATHLIKE, FILELIKE]) cleaned = cleaned.replace(pattern, " ");
|
||
return cleaned;
|
||
}
|
||
|
||
export function languageCounts(text: string): Readonly<{ korean: number; english: number }> {
|
||
const cleaned = prose(text);
|
||
return {
|
||
korean: cleaned.match(HANGUL)?.length ?? 0,
|
||
english: (cleaned.match(TOKEN) ?? []).filter((token) => WORD.test(token)).length,
|
||
};
|
||
}
|
||
|
||
export function isEnglish(text: string): boolean {
|
||
const { korean, english } = languageCounts(text);
|
||
return english >= MIN_ENGLISH && korean / (korean + english) < MIN_KOREAN_SHARE;
|
||
}
|
||
|
||
/** What a check needs besides the documents: the repository it names paths in, and the sources of truth. */
|
||
export type DocsFacts = Readonly<{
|
||
/** Files git knows in the repository (tracked and untracked-not-ignored), with every folder above them. */
|
||
knownPaths: ReadonlySet<string>;
|
||
/** Every file under docs/ in the documents root, any extension. */
|
||
docsFiles: readonly string[];
|
||
/** Framework name → exact version, from package.json and .nvmrc. */
|
||
frameworkVersions: ReadonlyMap<string, string>;
|
||
/** Paths a copy may delete (README 「복사한 뒤 지워도 되는 것」), without a trailing slash. */
|
||
deletable: readonly string[];
|
||
}>;
|
||
|
||
function checkLanguage(documents: readonly DocsDocument[]): DocsProblem[] {
|
||
return documents.flatMap(({ path, text }) => {
|
||
if (!isLiving(path) && !path.startsWith(DECISION_FOLDER)) return [];
|
||
const body = bodyLines(text).join("\n");
|
||
if (!isEnglish(body)) return [];
|
||
const { korean, english } = languageCounts(body);
|
||
return [
|
||
{
|
||
check: "language",
|
||
path,
|
||
key: "",
|
||
line: 0,
|
||
message: `the body is English (Hangul ${korean}, English words ${english}); write it in Korean`,
|
||
} as const,
|
||
];
|
||
});
|
||
}
|
||
|
||
function isCalendarDate(value: string): boolean {
|
||
if (!/^\d{4}-\d{2}-\d{2}$/u.test(value)) return false;
|
||
const date = new Date(`${value}T00:00:00Z`);
|
||
return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
|
||
}
|
||
|
||
function backtickedPaths(value: string): string[] {
|
||
return [...value.matchAll(/`([^`]+)`/gu)].map(([, path = ""]) => path);
|
||
}
|
||
|
||
function knows(facts: DocsFacts, path: string): boolean {
|
||
return facts.knownPaths.has(normalize(path).replace(/\/$/u, ""));
|
||
}
|
||
|
||
function checkHead(documents: readonly DocsDocument[], facts: DocsFacts): DocsProblem[] {
|
||
const problems: DocsProblem[] = [];
|
||
for (const { path, text } of documents) {
|
||
const kind = recordKind(path);
|
||
if (kind === null) continue;
|
||
const fail = (message: string, line = 1) => problems.push({ check: "head", path, key: "", message, line });
|
||
const lines = text.split("\n");
|
||
const end = lines.slice(0, HEAD_SEARCH_LINES).indexOf(HEAD_END);
|
||
if (lines[0] !== HEAD_START || end < 0) {
|
||
fail(`no head block at the top: the first line is \`${HEAD_START}\` and the block ends with \`${HEAD_END}\``);
|
||
continue;
|
||
}
|
||
const block = lines.slice(1, end);
|
||
const labels = kind === "결정 기록" ? DECISION_LABELS : [recordLabel(kind)];
|
||
if (!labels.includes(block[0] ?? "")) fail(`the second line is 「${labels[0]}」`, 2);
|
||
const fields = new Map<string, readonly [string, number]>();
|
||
block.slice(1).forEach((line, offset) => {
|
||
const at = offset + 3;
|
||
if (line.trim() === "") return;
|
||
const match = /^- ([^:]+): (.+)$/u.exec(line);
|
||
if (!match) {
|
||
fail(`a head block line is \`- 칸: 값\`: ${JSON.stringify(line)}`, at);
|
||
return;
|
||
}
|
||
const name = (match[1] ?? "").trim();
|
||
const value = (match[2] ?? "").trim();
|
||
if (![...HEAD_FIELDS, ...HEAD_OPTIONAL].includes(name)) fail(`not a head block field: ${name}`, at);
|
||
else if (fields.has(name)) fail(`field given twice: ${name}`, at);
|
||
else fields.set(name, [value, at]);
|
||
});
|
||
for (const name of HEAD_FIELDS) if (!fields.has(name)) fail(`no 「${name}」 field`);
|
||
const status = fields.get("상태");
|
||
if (status && !STATUS[kind].includes(status[0])) {
|
||
fail(`the status of a ${kind} is one of ${STATUS[kind].join(" · ")}: ${JSON.stringify(status[0])}`, status[1]);
|
||
}
|
||
const written = fields.get("작성일");
|
||
if (written && !isCalendarDate(written[0])) {
|
||
fail(`the date is YYYY-MM-DD: ${JSON.stringify(written[0])}`, written[1]);
|
||
}
|
||
const summary = fields.get("요약");
|
||
if (summary && (!/[가-힣]/u.test(summary[0]) || isEnglish(summary[0]))) {
|
||
fail("the summary is one Korean sentence", summary[1]);
|
||
}
|
||
const canonical = fields.get("현재 정본");
|
||
if (canonical) {
|
||
const targets = backtickedPaths(canonical[0]);
|
||
if (!canonical[0].startsWith("없음") && targets.length === 0) {
|
||
fail("the current canonical is `path` (comma separated) or 「없음 — 이유」", canonical[1]);
|
||
}
|
||
for (const target of targets) {
|
||
if (!knows(facts, target)) fail(`the current canonical path does not exist: ${target}`, canonical[1]);
|
||
}
|
||
}
|
||
if (status?.[0] === "대체됨" && !fields.has("대체됨")) fail("a superseded record names its replacement in 「대체됨」");
|
||
for (const name of HEAD_OPTIONAL) {
|
||
const field = fields.get(name);
|
||
if (!field) continue;
|
||
const targets = backtickedPaths(field[0]);
|
||
if (targets.length === 0) fail(`the 「${name}」 field names a \`path\``, field[1]);
|
||
for (const target of targets) if (!knows(facts, target)) fail(`the 「${name}」 path does not exist: ${target}`, field[1]);
|
||
}
|
||
}
|
||
return problems;
|
||
}
|
||
|
||
function checkNumber(documents: readonly DocsDocument[], facts: DocsFacts): DocsProblem[] {
|
||
const exact = [...facts.frameworkVersions].map(
|
||
([name, version]) =>
|
||
[name, new RegExp(`(?<![\\w.§])v?${version.replaceAll(".", "\\.")}(?![\\w]|\\.\\d)`, "gu")] as const,
|
||
);
|
||
const problems: DocsProblem[] = [];
|
||
for (const { path, text } of documents) {
|
||
if (!checkedForDrift(path)) continue;
|
||
const seen = new Set<string>();
|
||
text.split("\n").forEach((line, index) => {
|
||
const found: (readonly [string, string, number])[] = [];
|
||
for (const match of line.matchAll(NAMED_VERSION)) found.push(["framework version", match[0], match.index]);
|
||
for (const [label, pattern] of COPIED_COUNTS) {
|
||
for (const match of line.matchAll(pattern)) found.push([label, match[0], match.index]);
|
||
}
|
||
const named = found.map(([, value, start]) => [start, start + value.length] as const);
|
||
for (const [name, pattern] of exact) {
|
||
for (const match of line.matchAll(pattern)) {
|
||
// A version next to its name is counted once, by the pattern above.
|
||
if (!named.some(([start, end]) => start <= match.index && match.index + match[0].length <= end)) {
|
||
found.push([`${name} version`, match[0], match.index]);
|
||
}
|
||
}
|
||
}
|
||
for (const [label, value] of found) {
|
||
if (seen.has(value)) continue;
|
||
seen.add(value);
|
||
problems.push({
|
||
check: "number",
|
||
path,
|
||
key: value,
|
||
line: index + 1,
|
||
message: `copies a ${label}: ${JSON.stringify(value)}. Point at its source of truth instead`,
|
||
});
|
||
}
|
||
});
|
||
}
|
||
return problems;
|
||
}
|
||
|
||
/**
|
||
* The folders the map must list (from docs/): each folder right under docs/,
|
||
* or, for a folder that only holds folders (history/), each folder under it.
|
||
*/
|
||
export function requiredFolders(paths: readonly string[]): Set<string> {
|
||
const children = (entries: readonly string[]) => {
|
||
const found = new Map<string, string[]>();
|
||
for (const entry of entries) {
|
||
const slash = entry.indexOf("/");
|
||
if (slash < 0) continue;
|
||
const name = entry.slice(0, slash);
|
||
found.set(name, [...(found.get(name) ?? []), entry.slice(slash + 1)]);
|
||
}
|
||
return found;
|
||
};
|
||
const folders = new Set<string>();
|
||
for (const [name, inside] of children(paths)) {
|
||
if (inside.some((entry) => !entry.includes("/"))) folders.add(`${name}/`);
|
||
else for (const child of children(inside).keys()) folders.add(`${name}/${child}/`);
|
||
}
|
||
return folders;
|
||
}
|
||
|
||
/** (line, folder from docs/) — inline-code `folder/` in the first cell of a table row, outside code blocks. */
|
||
function mapEntries(lines: readonly string[]): (readonly [number, string])[] {
|
||
const entries: (readonly [number, string])[] = [];
|
||
for (const [number, line] of outsideCode(lines, false)) {
|
||
const cells = line.trim().split("|");
|
||
if (!line.trim().startsWith("|") || cells.length < 3) continue;
|
||
for (const [span = ""] of (cells[1] ?? "").matchAll(INLINE)) {
|
||
let token = span.replace(/^`+|`+$/gu, "").trim();
|
||
if (token.startsWith(DOCS_ROOT)) token = token.slice(DOCS_ROOT.length);
|
||
if (token.endsWith("/") && !/[*?<>{}[\]$…]|\.\.\./u.test(token)) entries.push([number, token]);
|
||
}
|
||
}
|
||
return entries;
|
||
}
|
||
|
||
function checkMap(documents: readonly DocsDocument[], facts: DocsFacts): DocsProblem[] {
|
||
const map = documents.find(({ path }) => path === MAP_FILE);
|
||
if (!map) return [{ check: "map", path: MAP_FILE, key: "", line: 0, message: "there is no documents map" }];
|
||
const files = facts.docsFiles.map((path) => path.slice(DOCS_ROOT.length));
|
||
const entries = mapEntries(map.text.split("\n"));
|
||
const mapped = new Set(entries.map(([, folder]) => folder));
|
||
const problems: DocsProblem[] = [...requiredFolders(files)]
|
||
.filter((folder) => !mapped.has(folder))
|
||
.sort()
|
||
.map((folder) => ({
|
||
check: "map",
|
||
path: MAP_FILE,
|
||
key: folder,
|
||
line: 0,
|
||
message: `a documents folder the map does not list: ${DOCS_ROOT}${folder}. Add a row for it`,
|
||
}));
|
||
const deletable = (folder: string) =>
|
||
facts.deletable.some((entry) => `${DOCS_ROOT}${folder}`.startsWith(`${entry}/`));
|
||
for (const [line, folder] of entries) {
|
||
// A copy that deleted its history keeps the map rows of the template.
|
||
if (!files.some((path) => path.startsWith(folder)) && !deletable(folder)) {
|
||
problems.push({ check: "map", path: MAP_FILE, key: folder, line, message: `a mapped folder that does not exist: ${DOCS_ROOT}${folder}` });
|
||
}
|
||
}
|
||
return problems;
|
||
}
|
||
|
||
function checkReadme(documents: readonly DocsDocument[]): DocsProblem[] {
|
||
const problems: DocsProblem[] = [];
|
||
const fail = (key: string, message: string, line = 0) =>
|
||
problems.push({ check: "readme", path: README_FILE, key, message, line });
|
||
const readme = documents.find(({ path }) => path === README_FILE);
|
||
if (!readme) {
|
||
fail("", "there is no root README");
|
||
return problems;
|
||
}
|
||
const lines = readme.text.split("\n");
|
||
const headings = outsideCode(lines, false).flatMap(([number, line]) => {
|
||
const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/u.exec(line);
|
||
return match ? [[number, match[1]?.length ?? 0, match[2] ?? ""] as const] : [];
|
||
});
|
||
const first = lines.findIndex((line) => line.trim() !== "") + 1;
|
||
if (headings[0]?.[0] !== first || headings[0][1] !== 1) {
|
||
fail("제목", "the first line is `# 제목`", first);
|
||
} else {
|
||
const firstSection = headings.find(([, level]) => level === 2)?.[0] ?? lines.length + 1;
|
||
const intro = lines.slice(first, firstSection - 1);
|
||
if (!intro.some((line) => line.trim() !== "" && !/^\s*(?:#|\||```|~~~)/u.test(line))) {
|
||
fail("소개", "put one paragraph (what this is, who uses it) under the title, before the first ## section", first);
|
||
}
|
||
}
|
||
const positions = new Map<string, number>();
|
||
for (const [number, level, title] of headings) {
|
||
if (level === 2 && README_SECTIONS.includes(title) && !positions.has(title)) positions.set(title, number);
|
||
}
|
||
for (const title of README_SECTIONS) {
|
||
if (!positions.has(title)) fail(title, `no 「## ${title}」 section. The sections are ${README_SECTIONS.join(" → ")}`);
|
||
}
|
||
const present = README_SECTIONS.filter((title) => positions.has(title));
|
||
present.slice(1).forEach((after, index) => {
|
||
const before = present[index] ?? "";
|
||
if ((positions.get(before) ?? 0) > (positions.get(after) ?? 0)) {
|
||
fail(after, `the 「## ${after}」 section comes after 「## ${before}」`, positions.get(after));
|
||
}
|
||
});
|
||
return problems;
|
||
}
|
||
|
||
function checkStyle(documents: readonly DocsDocument[]): DocsProblem[] {
|
||
const problems: DocsProblem[] = [];
|
||
for (const { path, text } of documents) {
|
||
if (!isLiving(path) && !path.startsWith(DECISION_FOLDER)) continue;
|
||
const body = bodyLines(text);
|
||
const offset = text.split("\n").length - body.length;
|
||
for (const [number, line] of outsideCode(body, true)) {
|
||
// A polite ending inside 「」 or quotes is a quotation, not this document's sentence.
|
||
const found = POLITE.exec(line.replace(INLINE, "").replace(QUOTED, "").replace(CORNER_QUOTED, ""));
|
||
if (found) {
|
||
problems.push({
|
||
check: "style",
|
||
path,
|
||
key: line.trim().slice(0, 80),
|
||
line: number + offset,
|
||
message: `polite form (write 「~한다」): …${found[0]}`,
|
||
});
|
||
}
|
||
}
|
||
}
|
||
return problems;
|
||
}
|
||
|
||
const RUNNERS: Readonly<
|
||
Record<DocsSystemCheck, (documents: readonly DocsDocument[], facts: DocsFacts) => DocsProblem[]>
|
||
> = Object.freeze({
|
||
language: (documents) => checkLanguage(documents),
|
||
head: checkHead,
|
||
number: checkNumber,
|
||
map: checkMap,
|
||
readme: (documents) => checkReadme(documents),
|
||
style: (documents) => checkStyle(documents),
|
||
});
|
||
|
||
export type DocsSystemResult = Readonly<{
|
||
/** Problems the exception list does not excuse, and exception list errors. */
|
||
failures: readonly string[];
|
||
/** One line per check: found, excused, failed. */
|
||
report: readonly string[];
|
||
}>;
|
||
|
||
function readExceptions(text: string): string[] {
|
||
return text.split("\n").filter((line) => line.trim() !== "" && !line.startsWith("#"));
|
||
}
|
||
|
||
/** Every problem the checks find, before the exception list is applied. */
|
||
export function findDocsProblems(
|
||
documents: readonly DocsDocument[],
|
||
facts: DocsFacts,
|
||
only: readonly DocsSystemCheck[] = DOCS_SYSTEM_CHECKS,
|
||
): DocsProblem[] {
|
||
return only.flatMap((check) => RUNNERS[check](documents, facts));
|
||
}
|
||
|
||
export function runDocsSystemChecks(
|
||
input: Readonly<{
|
||
documents: readonly DocsDocument[];
|
||
facts: DocsFacts;
|
||
exceptions?: string;
|
||
frozen?: ReadonlySet<string>;
|
||
only?: readonly DocsSystemCheck[];
|
||
}>,
|
||
): DocsSystemResult {
|
||
const allowed = readExceptions(input.exceptions ?? "");
|
||
const frozen = input.frozen ?? FROZEN;
|
||
const failures: string[] = [];
|
||
const report: string[] = [];
|
||
for (const entry of allowed) {
|
||
if (!frozen.has(sha16(entry))) {
|
||
failures.push(`[exceptions] ${EXCEPTIONS_FILE}: not in the baseline; the exception list does not grow: ${JSON.stringify(entry)}`);
|
||
}
|
||
}
|
||
const listed = new Set(allowed.map(sha16));
|
||
for (const orphan of [...frozen].filter((fingerprint) => !listed.has(fingerprint)).sort()) {
|
||
failures.push(
|
||
`[exceptions] scripts/lib/docs-system.ts FROZEN: a fingerprint with no line in the exception list; drop it with its line: ${orphan}`,
|
||
);
|
||
}
|
||
const allowedSet = new Set(allowed);
|
||
// A line about a document this tree does not have is not stale here: the
|
||
// tests run the checks on a copy of some documents only.
|
||
const present = new Set(input.documents.map(({ path }) => path));
|
||
for (const check of input.only ?? DOCS_SYSTEM_CHECKS) {
|
||
const problems = RUNNERS[check](input.documents, input.facts);
|
||
const hit = new Set(problems.map(exceptionLine));
|
||
const unexcused = problems.filter((problem) => !allowedSet.has(exceptionLine(problem)));
|
||
const stale = allowed.filter((entry) => {
|
||
const [entryCheck, entryPath = ""] = entry.split("\t");
|
||
return entryCheck === check && present.has(entryPath) && !hit.has(entry);
|
||
});
|
||
failures.push(...unexcused.map(renderProblem));
|
||
failures.push(...stale.map((entry) => `[exceptions] ${EXCEPTIONS_FILE}: no longer matches; delete the line: ${JSON.stringify(entry)}`));
|
||
report.push(`${check}: found ${problems.length}, excused ${problems.length - unexcused.length}, failed ${unexcused.length}`);
|
||
}
|
||
return { failures, report };
|
||
}
|
||
|
||
/**
|
||
* The paths README.md lists under 「복사한 뒤 지워도 되는 것」 (first-column
|
||
* inline code), without a trailing slash: a copy may delete them, so a path
|
||
* under one that is gone is not drift.
|
||
*/
|
||
export function deletableHistory(readme: string): string[] {
|
||
const section = /^### 복사한 뒤 지워도 되는 것\n[\s\S]*?(?=^#)/mu.exec(readme)?.[0] ?? "";
|
||
return [...section.matchAll(/^\| (.+?) \|/gmu)].flatMap(([, cell = ""]) =>
|
||
[...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, "")),
|
||
);
|
||
}
|
||
|
||
// --- Reading a tree.
|
||
|
||
function walk(root: string, folder = ""): string[] {
|
||
const entries = (() => {
|
||
try {
|
||
return readdirSync(join(root, folder), { withFileTypes: true });
|
||
} catch {
|
||
return [];
|
||
}
|
||
})();
|
||
return entries.flatMap((entry) => {
|
||
const path = folder === "" ? entry.name : `${folder}/${entry.name}`;
|
||
if (entry.isDirectory()) return IGNORED_FOLDERS.has(entry.name) ? [] : walk(root, path);
|
||
return entry.isFile() ? [path] : [];
|
||
});
|
||
}
|
||
|
||
/**
|
||
* The files of a tree: what git knows when it is a work tree (tracked plus
|
||
* untracked files that are not ignored, so generated output does not count),
|
||
* otherwise every file (a copy of the documents, as the tests make).
|
||
*/
|
||
export function treeFiles(root: string): string[] {
|
||
const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
|
||
const listing = spawnSync(
|
||
"git",
|
||
["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--full-name", "--", "."],
|
||
{ encoding: "utf8", env, maxBuffer: 64 * 1024 * 1024 },
|
||
);
|
||
const inside = spawnSync("git", ["-C", root, "rev-parse", "--show-prefix"], { encoding: "utf8", env });
|
||
if (listing.status !== 0 || inside.status !== 0 || inside.stdout.trim() !== "") return walk(root).sort();
|
||
return listing.stdout
|
||
.split("\0")
|
||
.filter((name) => name !== "" && existsSync(join(root, name)))
|
||
.sort();
|
||
}
|
||
|
||
export function knownPaths(files: readonly string[]): Set<string> {
|
||
const paths = new Set<string>();
|
||
for (const file of files) {
|
||
const parts = file.split("/");
|
||
for (let end = 1; end <= parts.length; end += 1) paths.add(parts.slice(0, end).join("/"));
|
||
}
|
||
return paths;
|
||
}
|
||
|
||
/** The markdown documents of a tree, with their text. */
|
||
export function readDocuments(root: string, files: readonly string[] = treeFiles(root)): DocsDocument[] {
|
||
return files
|
||
.filter((path) => path.endsWith(".md") && !NOT_DOCUMENT.test(path))
|
||
.map((path) => ({ path, text: readFileSync(join(root, path), "utf8") }));
|
||
}
|
||
|
||
/** Framework versions from the repository's package.json and .nvmrc. */
|
||
export function frameworkVersions(repositoryRoot: string): Map<string, string> {
|
||
const versions = new Map<string, string>();
|
||
const manifest = JSON.parse(readFileSync(join(repositoryRoot, "package.json"), "utf8")) as {
|
||
dependencies?: Record<string, string>;
|
||
devDependencies?: Record<string, string>;
|
||
};
|
||
const declared = { ...manifest.dependencies, ...manifest.devDependencies };
|
||
for (const [name, packageName] of FRAMEWORKS) {
|
||
const version = /\d+\.\d+\.\d+/u.exec(declared[packageName] ?? "")?.[0];
|
||
if (version) versions.set(name, version);
|
||
}
|
||
const node = existsSync(join(repositoryRoot, ".nvmrc"))
|
||
? /\d+\.\d+\.\d+/u.exec(readFileSync(join(repositoryRoot, ".nvmrc"), "utf8"))?.[0]
|
||
: undefined;
|
||
if (node) versions.set("Node.js", node);
|
||
return versions;
|
||
}
|
||
|
||
/**
|
||
* Runs the checks on the documents under `documentsRoot`, naming paths in
|
||
* `repositoryRoot`. verify:documentation passes its working directory (a copy
|
||
* of the documents in the tests) and this repository.
|
||
*/
|
||
export function checkDocsSystem(documentsRoot: string, repositoryRoot: string): DocsSystemResult {
|
||
const documentFiles = treeFiles(documentsRoot);
|
||
const exceptionsPath = join(repositoryRoot, EXCEPTIONS_FILE);
|
||
return runDocsSystemChecks({
|
||
documents: readDocuments(documentsRoot, documentFiles),
|
||
facts: {
|
||
knownPaths: knownPaths(treeFiles(repositoryRoot)),
|
||
docsFiles: documentFiles.filter((path) => path.startsWith(DOCS_ROOT)),
|
||
frameworkVersions: frameworkVersions(repositoryRoot),
|
||
deletable: deletableHistory(
|
||
existsSync(join(documentsRoot, README_FILE)) ? readFileSync(join(documentsRoot, README_FILE), "utf8") : "",
|
||
),
|
||
},
|
||
exceptions: existsSync(exceptionsPath) ? readFileSync(exceptionsPath, "utf8") : "",
|
||
});
|
||
}
|
||
|
||
/** Living documents under `root` whose references verify:documentation checks. */
|
||
export function livingDocuments(root: string): string[] {
|
||
return readDocuments(root)
|
||
.map(({ path }) => path)
|
||
.filter(checkedForDrift);
|
||
}
|
||
|