chore(merge): 문서 체계 PR #15가 들어간 main을 받는다

This commit is contained in:
DongHyeonka
2026-11-12 07:02:05 +09:00
139 changed files with 5416 additions and 3948 deletions
+8 -3
View File
@@ -33,13 +33,18 @@ const LEDGER_PATH = "docs/operations/adapter-remediation-ledger.md";
* `SW-01` — so rows are matched inside this pass's section rather than anywhere
* in the document.
*/
const SECTION_HEADING = "## Third re-review (2026-08-14)";
const SECTION_HEADING = "## 세 번째 재검토 (2026-08-14)";
const CLOSED_DISPOSITIONS: ReadonlySet<string> = new Set(["FIXED"]);
const RECIPES_PATH = "config/recipes/frontend-capability-recipes.json";
/** The table is `| id | prior verdict | disposition | evidence |`. */
const DISPOSITION_OFFSET_FROM_ID = 2;
/** Sentences that assert everything is done, and therefore need proof. */
const BLANKET_CLOSURE = /All\s+(?:\d+|findings|rows)[^.\n]*\b(?:FIXED|closed)\b/giu;
/**
* Sentences that assert everything is done, and therefore need proof.
* The ledger is written in Korean now, so Korean branches catch the same
* claim ("발견 38건은 … 모두 `FIXED`다"); the English branch still catches quotes.
*/
const BLANKET_CLOSURE =
/All\s+(?:\d+|findings|rows)[^.\n]*\b(?:FIXED|closed)\b|(?:모든|전체)\s*(?:발견|행)[^.\n]*(?:FIXED|닫)|(?:\d+\s*건|발견|(?<![가-힣])행)[^.\n]*(?:모두|전부)[^.\n]*(?:FIXED|닫)/giu;
async function main(): Promise<void> {
const problems: string[] = [];
+2 -2
View File
@@ -414,7 +414,7 @@ const GENERATED = "Generated by `pnpm create:feature`.";
function renderContextModule(contextId: string, appId: string, root: string): string {
return `/**
* Ownership declaration of the ${contextId} bounded context
* (docs/architecture/starter-experience.md, "Ownership declarations"): the
* (docs/architecture/starter-experience.md, "소유 선언"): the
* app that owns it, its route root and its direct-feature budget.
* ${GENERATED}
*/
@@ -1697,7 +1697,7 @@ async function readInstalledFacts(root: string): Promise<InstalledFacts> {
* and the command that writes each. A feature branch commits them with the
* feature; two feature branches change the same lines, and the merge takes
* the command again instead of a hand-merged value. docs/manual/03 (A) and
* the "Adding a feature" table in docs/architecture/starter-experience.md
* the "feature 추가" table in docs/architecture/starter-experience.md
* list them (tests/unit/feature-tracked-files.test.ts).
*/
export const FEATURE_TRACKED_FILE_REWRITES = Object.freeze([
+8
View File
@@ -0,0 +1,8 @@
# scripts/lib/docs-system.ts의 예외 목록. 줄기만 한다(docs/README.md 「5. 문서 검사」).
#
# - 줄마다 scripts/lib/docs-system.ts의 FROZEN에 그 줄의 지문(sha256 앞 16자)이 있어야 한다.
# FROZEN이 비어 있으므로 어떤 줄을 더해도 검사가 실패한다.
# - 고쳐서 더는 걸리지 않는 줄은 지운다. 남겨 두면 검사가 실패한다. 줄을 지우면 같은 변경에서
# FROZEN에서 그 지문도 뺀다.
# - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다.
# - 2026-11-08에 문서 체계를 적용하면서 걸린 문서를 모두 고쳐 목록이 비었다.
+1 -1
View File
@@ -112,7 +112,7 @@ export function renderContextIndex(entries: readonly FeatureIndexEntry[]): strin
/**
* Ownership declarations the generator reads, documented in
* docs/architecture/starter-experience.md ("Ownership declarations"). Each boundary
* docs/architecture/starter-experience.md ("소유 선언"). Each boundary
* declares only its parent:
*
* src/apps/<app>/app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS
+731
View File
@@ -0,0 +1,731 @@
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`);
// 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<string> = 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<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 treeFiles(root).filter((path) => path.endsWith(".md") && !NOT_DOCUMENT.test(path) && checkedForDrift(path));
}
+30 -17
View File
@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts";
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
import { checkDocsSystem, checkedForDrift, deletableHistory, HISTORY_HOLDERS, livingDocuments } from "./lib/docs-system.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts";
import {
REMOVABLE_TEMPLATE_FEATURES,
@@ -161,8 +162,9 @@ const sourceStructureDocumented = sourceStructure.every(
// exist. Documents are read from the working directory; what they name is
// looked up in this repository, as for the src structure above.
const DOCUMENT_INDEX = "docs/README.md";
// Past states are its subject: it names removed scripts and paths on purpose.
const UNCHECKED_DOCUMENTS = new Set(["CHANGELOG.md"]);
// Past states are their subject: they name removed scripts and paths on purpose
// (HISTORY_HOLDERS in scripts/lib/docs-system.ts says which and why).
const UNCHECKED_DOCUMENTS = HISTORY_HOLDERS;
const NOT_CREATED = new Set([
// Reserved by generic-worker-has-no-network-or-credentials. The generic CPU
// worker is NOT_SELECTED; docs/manual/03-outside-feature-folder.md says how
@@ -219,15 +221,9 @@ function generated(file: string): boolean {
}
return ignored;
}
// A copy may delete the history README lists under "Files you can delete
// after copying". A path under an entry that is gone is not drift.
const deletedHistory = [
...(readme.match(/^### Files you can delete after copying\n[\s\S]*?(?=^#)/mu)?.[0] ?? "").matchAll(
/^\| (.+?) \|/gmu,
),
]
.flatMap(([, cell = ""]) => [...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, "")))
.filter((entry) => !exists(entry));
// A copy may delete the history README lists under 「복사한 뒤 지워도 되는
// 것」. A path under an entry that is gone is not drift.
const deletedHistory = deletableHistory(readme).filter((entry) => !exists(entry));
// 1103/12-05, 1105/12-02. The paired templates a document may name
// (`<name>/docs/…`) or link (`../../../<name>/…`) are the ones
@@ -288,7 +284,8 @@ function pairedReferenceExists(reference: string): boolean | null {
// (`../<name>/…`).
function namedPath(token: string, document: string): string | null {
const candidate = token.replace(/#.*$/u, "").replace(/:\d[\d,:-]*$/u, "");
if (!candidate.includes("/") || candidate.startsWith("/") || /[\s*<>{}$()|]|\.\.\./u.test(candidate)) return null;
// An ellipsis, `...` or `…`, stands for any name, as in scripts/lib/docs-system.ts.
if (!candidate.includes("/") || candidate.startsWith("/") || /[\s*<>{}$()|…]|\.\.\./u.test(candidate)) return null;
const first = candidate.split("/")[0] ?? "";
if (topLevelEntries.has(first)) return candidate;
if (pairedPins.has(first)) return `../${candidate}`;
@@ -342,6 +339,12 @@ for (const [, target = ""] of (index.match(/^## 1\.[\s\S]*?(?=^## )/mu)?.[0] ??
entries === null ? [linked] : entries.filter((name) => name.endsWith(".md")).map((name) => join(linked, name));
for (const document of documents) if (!UNCHECKED_DOCUMENTS.has(document)) contractDocuments.add(document);
}
// docs-system.md K3: every living document names only paths, scripts and
// gate IDs that exist, not only the ones the index links. Records keep the
// paths of the time they were written (scripts/lib/docs-system.ts).
for (const document of livingDocuments(process.cwd())) {
if (!UNCHECKED_DOCUMENTS.has(document)) contractDocuments.add(document);
}
const documentReferences = [];
for (const document of contractDocuments) {
const text = await readFile(document, "utf8").catch(() => null);
@@ -417,10 +420,8 @@ const documentReferencesValid = documentReferences.every(
// Helm, Terraform) lives in the infrastructure repository; a current document
// links to it and states the host contract (config/hosting/, FE-GATE-019)
// instead of carrying a copy. The history folders are records and keep what
// they recorded.
// Built from pieces: tests/unit/deletable-history-documents.test.ts fails on
// code that names a history folder, and this names them to skip them.
const HISTORY_DOCUMENT_FOLDERS = ["history", "reviews", "superpowers"].map((folder) => `docs/${folder}/`);
// they recorded: the current documents are the living documents
// scripts/lib/docs-system.ts reads for drift (records and decision records out).
const INFRASTRUCTURE_FENCE = /^\s*```\s*(nginx|hcl|terraform|helm)\b/iu;
const INFRASTRUCTURE_MANIFEST =
/^\s*kind:\s*(Deployment|StatefulSet|DaemonSet|Ingress|Service|ConfigMap|CronJob|HelmRelease|Kustomization)\s*$/u;
@@ -430,7 +431,7 @@ const currentDocuments = [
...((await readdir("docs", { recursive: true }).catch(() => [])) as string[])
.filter((name) => name.endsWith(".md"))
.map((name) => `docs/${name}`)
.filter((name) => !HISTORY_DOCUMENT_FOLDERS.some((folder) => name.startsWith(folder))),
.filter(checkedForDrift),
].sort();
const layoutRuleViolations: { path: string; rule: "R6" | "R7"; detail: string }[] = [];
for (const document of currentDocuments) {
@@ -451,6 +452,10 @@ for (const document of currentDocuments) {
});
}
// docs-system.md K1, K2, K4-K6 and the polite-form rule: language, record
// head blocks, copied numbers, the documents map, README sections, style.
const documentsSystem = checkDocsSystem(process.cwd(), rootDirectory);
// 1101/14-06. Each failed check is named, so the stderr points at the file to
// fix rather than at the diagram review whatever failed. 1101/14-05: the last
// two only compare the two hand-kept copies of the 2026-07-18 diagram review;
@@ -466,6 +471,7 @@ const failedChecks = [
...(results.length === 2 && results.every((result) => result.passed)
? []
: ["2026-07-18 diagram review copies"]),
...(documentsSystem.failures.length === 0 ? [] : ["documents system"]),
];
const passed = failedChecks.length === 0;
await mkdir("artifacts/quality", { recursive: true });
@@ -552,6 +558,12 @@ if (!passed) {
if (results.length !== 2) {
process.stderr.write(`review ledger has ${results.length} diagram reviews; 2 are required\n`);
}
if (documentsSystem.failures.length > 0) {
process.stderr.write(
`Documents system (docs/README.md 「문서 검사」): ${documentsSystem.report.join("; ")}\n` +
documentsSystem.failures.map((failure) => ` ${failure}\n`).join(""),
);
}
process.stderr.write(
`Documentation readiness: FAIL_UNVERIFIED (failed: ${failedChecks.join(", ")})\n`,
);
@@ -573,4 +585,5 @@ if (unverified.length > 0) {
`(${reasons.join("; ")}): ${[...new Set(unverified)].join(", ")}\n`,
);
}
process.stdout.write(`Documents system: ${documentsSystem.report.join("; ")}\n`);
process.stdout.write("Documentation readiness: PASS_SCOPED\n");