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 = new Set(); 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 = 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`); // docs/work/evidence.md is the record of why the work manual says what it says // (as in the backend template). // The number check and the reference check of verify:documentation skip them. export const HISTORY_HOLDERS: ReadonlySet = new Set([ "CHANGELOG.md", "docs/architecture/review-evidence.md", "docs/work/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 = /^docs\/accessibility\/route-reviews\//u; const IGNORED_FOLDERS: ReadonlySet = new Set(["node_modules", ".git"]); const STATUS: Readonly> = Object.freeze({ 설계서: ["제안", "채택", "구현됨", "보류", "폐기", "대체됨", "확인 안 함"], "결정 기록": ["제안", "채택", "채택(보완)", "폐기", "대체됨"], 계획서: ["실행 중", "끝남", "중단", "대체됨", "확인 안 함"], "납품 패키지": ["보관"], 증거: ["보관"], "학습 문서": ["보관"], }); export const HEAD_START = ""; 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; /** Every file under docs/ in the documents root, any extension. */ docsFiles: readonly string[]; /** Framework name → exact version, from package.json and .nvmrc. */ frameworkVersions: ReadonlyMap; /** 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(); 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(`(?(); 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 { const children = (entries: readonly string[]) => { const found = new Map(); 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(); 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(); 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 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; 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 { const paths = new Set(); 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 { const versions = new Map(); const manifest = JSON.parse(readFileSync(join(repositoryRoot, "package.json"), "utf8")) as { dependencies?: Record; devDependencies?: Record; }; 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 treeFiles(root).filter((path) => path.endsWith(".md") && !NOT_DOCUMENT.test(path) && checkedForDrift(path)); }