Files
clean-architecture-frontend…/scripts/lib/docs-system.ts
T
DongHyeonka 11530b1adf docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.

위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.

검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
2026-11-08 21:57:47 +09:00

731 lines
32 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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>();
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);
}