feat(docs): 문서 체계 검사를 verify:documentation에 더하고 입구 문서를 고친다

문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.

고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
  3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
  도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
  이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
  FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
  번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
  검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
  절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
  글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
  테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
  폴더 이름을 적지만 지운 사본에서도 통과하므로
  deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
  테스트와 검사기 시험에 적었다).

위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).

검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
This commit is contained in:
DongHyeonka
2026-11-08 21:57:39 +09:00
parent 2b8a348c1f
commit 7a9aefdf25
13 changed files with 1916 additions and 798 deletions
+51
View File
@@ -0,0 +1,51 @@
# scripts/lib/docs-system.ts의 예외 목록. 줄기만 한다(docs/README.md 「5. 문서 검사」).
#
# - 줄마다 scripts/lib/docs-system.ts의 FROZEN에 그 줄의 지문(sha256 앞 16자)이 있어야 한다.
# FROZEN이 비어 있으므로 어떤 줄을 더해도 검사가 실패한다.
# - 고쳐서 더는 걸리지 않는 줄은 지운다. 남겨 두면 검사가 실패한다. 줄을 지우면 같은 변경에서
# FROZEN에서 그 지문도 뺀다.
# - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다.
# - 2026-11-08 문서 체계를 켤 때의 기준선이다. 문서를 고쳐 더는 걸리지 않으면 그 줄을 지운다.
language docs/accessibility/manual-checklist.md
language docs/architecture/capability-consumer-experience.md
language docs/architecture/contract-ownership.md
language docs/architecture/review-evidence.md
language docs/architecture/scale-architecture.md
language docs/architecture/starter-experience.md
language docs/architecture/static-delivery.md
language docs/contracts/compatibility.md
language docs/operations/adapter-remediation-ledger.md
language docs/operations/release-cache-rollback.md
language docs/runbooks/FE-RB-001.md
language docs/runbooks/FE-RB-002.md
language docs/runbooks/FE-RB-003.md
language docs/runbooks/FE-RB-004.md
language docs/runbooks/FE-RB-005.md
language docs/security/browser-boundary.md
language docs/security/supply-chain.md
language docs/styling/design-tokens.md
language docs/testing/taxonomy.md
language src/adapters/browser-transfer/image-cdn/README.md
number docs/architecture/optional-adapter-recipes.md 12개 recipe
number docs/operations/ci-quality-gates.md 4.4.3
style PRODUCT.md - **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 기본 화면(홈, 플랫폼 구성)과 Storyboo
style PRODUCT.md - **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로
style PRODUCT.md - 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → c
style PRODUCT.md - 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다.
style PRODUCT.md - 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없습니다. 지어내지 않습니다.
style PRODUCT.md - 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker입니다. SSR은 없습니다.
style PRODUCT.md - 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다.
style PRODUCT.md - 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있습니다.
style PRODUCT.md - 템플릿에는 샘플 기능이 없습니다(참조 기능과 예제 화면은 2026-11-07에 지웠습니다). 기능은 `create:feature`로 만듭니다
style PRODUCT.md - 파생 서비스는 운영 중인 desktop 서버에 배포됩니다.
style PRODUCT.md - 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩
style PRODUCT.md 1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것입니다. 둘을 섞지 않습니다.
style PRODUCT.md 2. 브랜드는 토큰으로만 바꿉니다. 컴포넌트에 브랜드 값을 직접 넣지 않습니다.
style PRODUCT.md 3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절합니다. 컴포넌트를 서비스 종류별로 복
style PRODUCT.md 4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값입니다.
style PRODUCT.md 5. 한국어가 기본이고 영어를 함께 지원합니다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 합니다.
style PRODUCT.md WCAG 2.2 AA를 기준으로 합니다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를
style PRODUCT.md 도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점입니다. 아키텍처 경계, 연동 동작, 릴리스 정합성,
style PRODUCT.md 브랜드는 중립으로 유지합니다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힙니다. 현재 표시 이름 "
style PRODUCT.md 화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트
+773
View File
@@ -0,0 +1,773 @@
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { existsSync, readdirSync, readFileSync } from "node:fs";
import { join, normalize } from "node:path/posix";
/**
* The document rules of design-docs `conventions/docs-system.md` that a
* machine can check, applied as docs/README.md 「문서 수명과 언어」 says.
* verify:documentation (FE-GATE-017) runs them on every pull request; the
* paths, links, package scripts and gate IDs a living document names are its
* own `document references` check, which reads every living document listed
* here.
*
* This is the backend template's `scripts/check-docs.py` ported rule by rule
* (same names, same thresholds, same exception list semantics), so the two
* templates fail on the same documents:
*
* language a living document or decision record body is Korean. The
* verdict is the report-language hook's H11: code, commands,
* quotes, links, URLs, paths and file names are left out; three
* or more English words with a Hangul share under 0.3 is English.
* head a record (docs/design, docs/history, docs/adr) starts with the
* head block: status from its kind's vocabulary, a date, a Korean
* summary, and current-canonical and superseded-by paths that exist.
* number a living document does not copy a number its source of truth
* owns: a framework version (package.json, .nvmrc) or a count of
* gates, recipes or adapters (config/ci/gates.json, the recipe
* catalog, docs/reviews/adapters/INVENTORY.md).
* map docs/README.md's map covers every documents folder, and every
* folder it lists exists.
* readme README.md has its title, an intro paragraph and the required
* `##` sections in order.
* style a living document does not end sentences in the polite form
* (「~합니다」). It is written in 「~한다」.
*
* The exception list (scripts/docs-system-exceptions.txt) only shrinks: each
* line needs its fingerprint in FROZEN, each FROZEN fingerprint needs its
* line, and a line that no longer matches a problem fails until it is deleted.
* Growing FROZEN changes the rule and needs the owner's decision.
*/
export const DOCS_SYSTEM_CHECKS = Object.freeze(["language", "head", "number", "map", "readme", "style"] as const);
export type DocsSystemCheck = (typeof DOCS_SYSTEM_CHECKS)[number];
export type DocsProblem = Readonly<{
check: DocsSystemCheck;
path: string;
key: string;
message: string;
line: number;
}>;
/** A document is its path (from the documents root) and its text. */
export type DocsDocument = Readonly<{ path: string; text: string }>;
export const EXCEPTIONS_FILE = "scripts/docs-system-exceptions.txt";
/**
* Fingerprints (sha256, first 16 hex) of the exception list lines: the
* 2026-11-08 baseline, which only shrinks. When it is empty no document is
* excused, and any line added to the list fails.
*/
export const FROZEN: ReadonlySet<string> = new Set<string>([
"cd62292c1faf9312",
"9ebf8141a4434f32",
"64bb8316aafc4fcc",
"80ca3b198759492f",
"89616e7ca7b409d5",
"021ee3958bdd58af",
"1f94ecba91dcd1df",
"0ea431405727b1ba",
"29d6b489d280d464",
"f0eed09117035063",
"f6c533a3450c74be",
"b76f8449ca6ad18b",
"61a22114f0f80622",
"ee082cac5fe9f20e",
"2fcb1b008276a6f0",
"d1b5e5cfbd8887fc",
"67fcfa6470a125a0",
"07db060102714081",
"a42bc30fb525d6c9",
"59569b9b066cffcc",
"cac81d51afa3db95",
"33ba6f03c95bd8e7",
"dce0f0c48d3876a4",
"e1e286fae81074d4",
"4495c81b34b2ccc9",
"9b5a07b82e98f153",
"24298b522fdc5404",
"d21b67aefa16fe30",
"c93a4077c595bfd6",
"e23d9d9bf15712e4",
"09f0dfe98de3c278",
"e7f28af3b9e31580",
"7d97ca40a8ec73f8",
"399a89014bf0dda7",
"4360f2d0bd948db2",
"6fd03906dc2c2f23",
"1e550a75f934225e",
"ec854cee6e8ca7dd",
"bf813a1c94ef9800",
"e3b8f5f5b45d54c2",
"9b512220105c506a",
"c38dda017bafd925",
]);
type RecordKind = "설계서" | "계획서" | "증거" | "납품 패키지" | "학습 문서" | "결정 기록";
// The folder decides the kind of a record (docs-system.md 4.1).
const RECORD_KINDS: readonly (readonly [string, RecordKind])[] = Object.freeze([
["docs/design/", "설계서"],
["docs/history/plans/", "계획서"],
["docs/history/evidence/", "증거"],
["docs/history/packages/", "납품 패키지"],
["docs/history/study/", "학습 문서"],
["docs/adr/", "결정 기록"],
]);
// Reviews are records as well; they do not need a head block yet.
const RECORD_FOLDERS = Object.freeze(["docs/design/", "docs/history/", "docs/reviews/"]);
const DECISION_FOLDER = "docs/adr/";
// The one file under docs/reviews/ that is kept current: check:adapter-inventory
// compares it with src/adapters on every change.
const LIVING_IN_RECORDS: ReadonlySet<string> = new Set(["docs/reviews/adapters/INVENTORY.md"]);
// Living documents that name past states on purpose. CHANGELOG.md names
// removed scripts, old paths and the versions a release shipped;
// review-evidence.md is the copy of the 2026-07-18 diagram review, whose paths
// are in the reviewing workspace (docs/architecture/review-ledger.json `note`).
// The number check and the reference check of verify:documentation skip them.
export const HISTORY_HOLDERS: ReadonlySet<string> = new Set([
"CHANGELOG.md",
"docs/architecture/review-evidence.md",
]);
// Not documents: the manual accessibility records are gate input in a fixed
// English key format (scripts/lib/manual-a11y-evidence.ts), like the backend's
// test resources.
const NOT_DOCUMENT = /^artifacts\/tests\/a11y-manual\//u;
const IGNORED_FOLDERS: ReadonlySet<string> = new Set(["node_modules", ".git"]);
const STATUS: Readonly<Record<RecordKind, readonly string[]>> = Object.freeze({
설계서: ["제안", "채택", "구현됨", "보류", "폐기", "대체됨", "확인 안 함"],
"결정 기록": ["제안", "채택", "채택(보완)", "폐기", "대체됨"],
계획서: ["실행 중", "끝남", "중단", "대체됨", "확인 안 함"],
"납품 패키지": ["보관"],
증거: ["보관"],
"학습 문서": ["보관"],
});
export const HEAD_START = "<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->";
export const HEAD_END = "<!-- 머리 블록 끝 -->";
const recordLabel = (kind: RecordKind) =>
`> **기록 · ${kind}** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.`;
// The frontend VD were written in Korean and are not translated, so their
// label is the original-text one; a decision record whose body is translated
// later takes the second (docs-system.md 4.1).
const DECISION_LABELS = Object.freeze([
"> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.",
"> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.",
]);
const HEAD_FIELDS = Object.freeze(["상태", "작성일", "요약", "현재 정본"]);
const HEAD_OPTIONAL = Object.freeze(["대체", "대체됨"]);
const HEAD_SEARCH_LINES = 20;
export const MAP_FILE = "docs/README.md";
const DOCS_ROOT = "docs/";
export const README_FILE = "README.md";
// The list and order are docs-system.md 6.1's.
export const README_SECTIONS = Object.freeze([
"프로젝트 구조",
"시작하기",
"기능 켜고 끄기",
"문서 지도",
"검증",
"새 서비스로 시작하기",
"규칙과 기여",
]);
// --- Language verdict: H11 of the report-language hook, as check-docs.py has it.
const MIN_ENGLISH = 3;
const MIN_KOREAN_SHARE = 0.3;
const HANGUL = /[가-힣]+/gu;
const FENCE = /^[ \t]*(`{3,}|~{3,})/u;
const INLINE = /(`+)(?:(?!\1)[\s\S])+?\1/gu;
const MDLINK = /\[[^\]\n]*\]\([^)\s]*\)/gu;
const URL = /(?:\b[a-z][a-z0-9+.-]*:\/\/|\bwww\.)\S+/giu;
const PATHLIKE = /[^\s가-힣]*[/\\][^\s가-힣]*/gu;
const FILELIKE = /[^\s가-힣]+\.[A-Za-z]{1,10}(?::\d+)*(?![A-Za-z])/gu;
const QUOTED = /"[^"\n]*"|“[^”\n]*”/gu;
const TOKEN = /[^\s가-힣]+/gu;
const WORD = /^[(["'“‘*_]*[A-Za-z][a-z]*(?:['’][a-z]+)?(?:-[a-z]+)*[)\]"'”’*_.,;:!?…]*$/u;
const HISTORY_QUOTE = /^\s*>\s*(?:\*\*)?이력/u;
const CORNER_QUOTED = /「[^」\n]*」/gu;
const POLITE = /(?:습니다|합니다|입니다|됩니다|십시오|하세요|주세요)(?=[.!?)\]」\s]|$)/u;
// --- Copied numbers.
const FRAMEWORKS = Object.freeze([
["React", "react"],
["React DOM", "react-dom"],
["React Router", "react-router"],
["Vite", "vite"],
["TypeScript", "typescript"],
["Vitest", "vitest"],
["Playwright", "@playwright/test"],
["TanStack Query", "@tanstack/react-query"],
["Zod", "zod"],
["Storybook", "storybook"],
] as const);
const NAMED_VERSION =
/\b(?:React(?: DOM| Router)?|Vite|TypeScript|Vitest|Playwright|TanStack Query|Zod|Storybook|Node(?:\.js)?)\s+v?\d+\.\d+(?:\.\d+)?\b/gu;
const COPIED_COUNTS = Object.freeze([
[
"gate count (config/ci/gates.json)",
/\b\d+\s*개의?\s*(?:merge\s*)?(?:게이트|gate)|(?:게이트|gate)\s*\d+\s*개|\b\d+\s+(?:merge\s+)?gates\b/giu,
],
["recipe count (config/recipes/frontend-capability-recipes.json)", /\b\d+\s*개의?\s*recipe|recipe\s*\d+\s*개|\b\d+\s+recipes\b/giu],
["adapter count (docs/reviews/adapters/INVENTORY.md)", /\b\d+\s*개의?\s*adapter|adapter\s*\d+\s*개|\b\d+\s+adapters\b/giu],
] as const);
const sha16 = (line: string) => createHash("sha256").update(line, "utf8").digest("hex").slice(0, 16);
export function exceptionLine(problem: DocsProblem): string {
return [problem.check, problem.path, problem.key].filter((part) => part !== "").join("\t");
}
export function renderProblem(problem: DocsProblem): string {
return `[${problem.check}] ${problem.line > 0 ? `${problem.path}:${problem.line}` : problem.path}: ${problem.message}`;
}
export function recordKind(path: string): RecordKind | null {
return RECORD_KINDS.find(([prefix]) => path.startsWith(prefix))?.[1] ?? null;
}
/** Living documents and decision records: what the language and style checks read. */
export function isLiving(path: string): boolean {
return LIVING_IN_RECORDS.has(path) || !RECORD_FOLDERS.some((folder) => path.startsWith(folder));
}
/** Living documents whose named paths and numbers must be current. */
export function checkedForDrift(path: string): boolean {
return isLiving(path) && !path.startsWith(DECISION_FOLDER) && !HISTORY_HOLDERS.has(path);
}
function stripHeadBlock(lines: readonly string[]): readonly string[] {
const end = lines.slice(0, HEAD_SEARCH_LINES).indexOf(HEAD_END);
return lines[0] === HEAD_START && end > 0 ? lines.slice(end + 1) : lines;
}
function stripFrontMatter(lines: readonly string[]): readonly string[] {
if (lines[0]?.trim() !== "---") return lines;
const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
return end > 0 ? lines.slice(end + 1) : lines;
}
/** The body: the text without its head block and front matter. */
export function bodyLines(text: string): readonly string[] {
return stripFrontMatter(stripHeadBlock(text.split("\n")));
}
type Fence = Readonly<{ marker: string }> | null;
function closesFence(fence: Fence, line: string): boolean {
const match = FENCE.exec(line);
return fence !== null && match !== null && match[1]?.[0] === fence.marker[0] && match[1].length >= fence.marker.length;
}
/** (line number, line) outside fenced code, and outside `> 이력` quotes when asked. */
function outsideCode(lines: readonly string[], skipHistory: boolean): (readonly [number, string])[] {
const kept: (readonly [number, string])[] = [];
let fence: Fence = null;
let history = false;
lines.forEach((line, index) => {
if (fence !== null) {
if (closesFence(fence, line)) fence = null;
return;
}
const open = FENCE.exec(line);
if (open) {
fence = { marker: open[1] ?? "```" };
return;
}
const quoted = line.trimStart().startsWith(">");
if (quoted && HISTORY_QUOTE.test(line)) history = true;
else if (!quoted) history = false;
if (!(skipHistory && history)) kept.push([index + 1, line]);
});
return kept;
}
/** The text the verdict reads: H11's prose(). */
export function prose(text: string): string {
const kept = outsideCode(text.split("\n"), false)
.map(([, line]) => line)
.filter((line) => !line.trimStart().startsWith("$ ") && !line.trimStart().startsWith(">"));
let cleaned = kept.join("\n");
for (const pattern of [INLINE, MDLINK, URL, QUOTED, PATHLIKE, FILELIKE]) cleaned = cleaned.replace(pattern, " ");
return cleaned;
}
export function languageCounts(text: string): Readonly<{ korean: number; english: number }> {
const cleaned = prose(text);
return {
korean: cleaned.match(HANGUL)?.length ?? 0,
english: (cleaned.match(TOKEN) ?? []).filter((token) => WORD.test(token)).length,
};
}
export function isEnglish(text: string): boolean {
const { korean, english } = languageCounts(text);
return english >= MIN_ENGLISH && korean / (korean + english) < MIN_KOREAN_SHARE;
}
/** What a check needs besides the documents: the repository it names paths in, and the sources of truth. */
export type DocsFacts = Readonly<{
/** Files git knows in the repository (tracked and untracked-not-ignored), with every folder above them. */
knownPaths: ReadonlySet<string>;
/** Every file under docs/ in the documents root, any extension. */
docsFiles: readonly string[];
/** Framework name → exact version, from package.json and .nvmrc. */
frameworkVersions: ReadonlyMap<string, string>;
/** Paths a copy may delete (README 「복사한 뒤 지워도 되는 것」), without a trailing slash. */
deletable: readonly string[];
}>;
function checkLanguage(documents: readonly DocsDocument[]): DocsProblem[] {
return documents.flatMap(({ path, text }) => {
if (!isLiving(path) && !path.startsWith(DECISION_FOLDER)) return [];
const body = bodyLines(text).join("\n");
if (!isEnglish(body)) return [];
const { korean, english } = languageCounts(body);
return [
{
check: "language",
path,
key: "",
line: 0,
message: `the body is English (Hangul ${korean}, English words ${english}); write it in Korean`,
} as const,
];
});
}
function isCalendarDate(value: string): boolean {
if (!/^\d{4}-\d{2}-\d{2}$/u.test(value)) return false;
const date = new Date(`${value}T00:00:00Z`);
return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
}
function backtickedPaths(value: string): string[] {
return [...value.matchAll(/`([^`]+)`/gu)].map(([, path = ""]) => path);
}
function knows(facts: DocsFacts, path: string): boolean {
return facts.knownPaths.has(normalize(path).replace(/\/$/u, ""));
}
function checkHead(documents: readonly DocsDocument[], facts: DocsFacts): DocsProblem[] {
const problems: DocsProblem[] = [];
for (const { path, text } of documents) {
const kind = recordKind(path);
if (kind === null) continue;
const fail = (message: string, line = 1) => problems.push({ check: "head", path, key: "", message, line });
const lines = text.split("\n");
const end = lines.slice(0, HEAD_SEARCH_LINES).indexOf(HEAD_END);
if (lines[0] !== HEAD_START || end < 0) {
fail(`no head block at the top: the first line is \`${HEAD_START}\` and the block ends with \`${HEAD_END}\``);
continue;
}
const block = lines.slice(1, end);
const labels = kind === "결정 기록" ? DECISION_LABELS : [recordLabel(kind)];
if (!labels.includes(block[0] ?? "")) fail(`the second line is 「${labels[0]}」`, 2);
const fields = new Map<string, readonly [string, number]>();
block.slice(1).forEach((line, offset) => {
const at = offset + 3;
if (line.trim() === "") return;
const match = /^- ([^:]+): (.+)$/u.exec(line);
if (!match) {
fail(`a head block line is \`- 칸: 값\`: ${JSON.stringify(line)}`, at);
return;
}
const name = (match[1] ?? "").trim();
const value = (match[2] ?? "").trim();
if (![...HEAD_FIELDS, ...HEAD_OPTIONAL].includes(name)) fail(`not a head block field: ${name}`, at);
else if (fields.has(name)) fail(`field given twice: ${name}`, at);
else fields.set(name, [value, at]);
});
for (const name of HEAD_FIELDS) if (!fields.has(name)) fail(`no 「${name}」 field`);
const status = fields.get("상태");
if (status && !STATUS[kind].includes(status[0])) {
fail(`the status of a ${kind} is one of ${STATUS[kind].join(" · ")}: ${JSON.stringify(status[0])}`, status[1]);
}
const written = fields.get("작성일");
if (written && !isCalendarDate(written[0])) {
fail(`the date is YYYY-MM-DD: ${JSON.stringify(written[0])}`, written[1]);
}
const summary = fields.get("요약");
if (summary && (!/[가-힣]/u.test(summary[0]) || isEnglish(summary[0]))) {
fail("the summary is one Korean sentence", summary[1]);
}
const canonical = fields.get("현재 정본");
if (canonical) {
const targets = backtickedPaths(canonical[0]);
if (!canonical[0].startsWith("없음") && targets.length === 0) {
fail("the current canonical is `path` (comma separated) or 「없음 — 이유」", canonical[1]);
}
for (const target of targets) {
if (!knows(facts, target)) fail(`the current canonical path does not exist: ${target}`, canonical[1]);
}
}
if (status?.[0] === "대체됨" && !fields.has("대체됨")) fail("a superseded record names its replacement in 「대체됨」");
for (const name of HEAD_OPTIONAL) {
const field = fields.get(name);
if (!field) continue;
const targets = backtickedPaths(field[0]);
if (targets.length === 0) fail(`the 「${name}」 field names a \`path\``, field[1]);
for (const target of targets) if (!knows(facts, target)) fail(`the 「${name}」 path does not exist: ${target}`, field[1]);
}
}
return problems;
}
function checkNumber(documents: readonly DocsDocument[], facts: DocsFacts): DocsProblem[] {
const exact = [...facts.frameworkVersions].map(
([name, version]) =>
[name, new RegExp(`(?<![\\w.§])v?${version.replaceAll(".", "\\.")}(?![\\w]|\\.\\d)`, "gu")] as const,
);
const problems: DocsProblem[] = [];
for (const { path, text } of documents) {
if (!checkedForDrift(path)) continue;
const seen = new Set<string>();
text.split("\n").forEach((line, index) => {
const found: (readonly [string, string, number])[] = [];
for (const match of line.matchAll(NAMED_VERSION)) found.push(["framework version", match[0], match.index]);
for (const [label, pattern] of COPIED_COUNTS) {
for (const match of line.matchAll(pattern)) found.push([label, match[0], match.index]);
}
const named = found.map(([, value, start]) => [start, start + value.length] as const);
for (const [name, pattern] of exact) {
for (const match of line.matchAll(pattern)) {
// A version next to its name is counted once, by the pattern above.
if (!named.some(([start, end]) => start <= match.index && match.index + match[0].length <= end)) {
found.push([`${name} version`, match[0], match.index]);
}
}
}
for (const [label, value] of found) {
if (seen.has(value)) continue;
seen.add(value);
problems.push({
check: "number",
path,
key: value,
line: index + 1,
message: `copies a ${label}: ${JSON.stringify(value)}. Point at its source of truth instead`,
});
}
});
}
return problems;
}
/**
* The folders the map must list (from docs/): each folder right under docs/,
* or, for a folder that only holds folders (history/), each folder under it.
*/
export function requiredFolders(paths: readonly string[]): Set<string> {
const children = (entries: readonly string[]) => {
const found = new Map<string, string[]>();
for (const entry of entries) {
const slash = entry.indexOf("/");
if (slash < 0) continue;
const name = entry.slice(0, slash);
found.set(name, [...(found.get(name) ?? []), entry.slice(slash + 1)]);
}
return found;
};
const folders = new Set<string>();
for (const [name, inside] of children(paths)) {
if (inside.some((entry) => !entry.includes("/"))) folders.add(`${name}/`);
else for (const child of children(inside).keys()) folders.add(`${name}/${child}/`);
}
return folders;
}
/** (line, folder from docs/) — inline-code `folder/` in the first cell of a table row, outside code blocks. */
function mapEntries(lines: readonly string[]): (readonly [number, string])[] {
const entries: (readonly [number, string])[] = [];
for (const [number, line] of outsideCode(lines, false)) {
const cells = line.trim().split("|");
if (!line.trim().startsWith("|") || cells.length < 3) continue;
for (const [span = ""] of (cells[1] ?? "").matchAll(INLINE)) {
let token = span.replace(/^`+|`+$/gu, "").trim();
if (token.startsWith(DOCS_ROOT)) token = token.slice(DOCS_ROOT.length);
if (token.endsWith("/") && !/[*?<>{}[\]$…]|\.\.\./u.test(token)) entries.push([number, token]);
}
}
return entries;
}
function checkMap(documents: readonly DocsDocument[], facts: DocsFacts): DocsProblem[] {
const map = documents.find(({ path }) => path === MAP_FILE);
if (!map) return [{ check: "map", path: MAP_FILE, key: "", line: 0, message: "there is no documents map" }];
const files = facts.docsFiles.map((path) => path.slice(DOCS_ROOT.length));
const entries = mapEntries(map.text.split("\n"));
const mapped = new Set(entries.map(([, folder]) => folder));
const problems: DocsProblem[] = [...requiredFolders(files)]
.filter((folder) => !mapped.has(folder))
.sort()
.map((folder) => ({
check: "map",
path: MAP_FILE,
key: folder,
line: 0,
message: `a documents folder the map does not list: ${DOCS_ROOT}${folder}. Add a row for it`,
}));
const deletable = (folder: string) =>
facts.deletable.some((entry) => `${DOCS_ROOT}${folder}`.startsWith(`${entry}/`));
for (const [line, folder] of entries) {
// A copy that deleted its history keeps the map rows of the template.
if (!files.some((path) => path.startsWith(folder)) && !deletable(folder)) {
problems.push({ check: "map", path: MAP_FILE, key: folder, line, message: `a mapped folder that does not exist: ${DOCS_ROOT}${folder}` });
}
}
return problems;
}
function checkReadme(documents: readonly DocsDocument[]): DocsProblem[] {
const problems: DocsProblem[] = [];
const fail = (key: string, message: string, line = 0) =>
problems.push({ check: "readme", path: README_FILE, key, message, line });
const readme = documents.find(({ path }) => path === README_FILE);
if (!readme) {
fail("", "there is no root README");
return problems;
}
const lines = readme.text.split("\n");
const headings = outsideCode(lines, false).flatMap(([number, line]) => {
const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/u.exec(line);
return match ? [[number, match[1]?.length ?? 0, match[2] ?? ""] as const] : [];
});
const first = lines.findIndex((line) => line.trim() !== "") + 1;
if (headings[0]?.[0] !== first || headings[0][1] !== 1) {
fail("제목", "the first line is `# 제목`", first);
} else {
const firstSection = headings.find(([, level]) => level === 2)?.[0] ?? lines.length + 1;
const intro = lines.slice(first, firstSection - 1);
if (!intro.some((line) => line.trim() !== "" && !/^\s*(?:#|\||```|~~~)/u.test(line))) {
fail("소개", "put one paragraph (what this is, who uses it) under the title, before the first ## section", first);
}
}
const positions = new Map<string, number>();
for (const [number, level, title] of headings) {
if (level === 2 && README_SECTIONS.includes(title) && !positions.has(title)) positions.set(title, number);
}
for (const title of README_SECTIONS) {
if (!positions.has(title)) fail(title, `no 「## ${title}」 section. The sections are ${README_SECTIONS.join(" → ")}`);
}
const present = README_SECTIONS.filter((title) => positions.has(title));
present.slice(1).forEach((after, index) => {
const before = present[index] ?? "";
if ((positions.get(before) ?? 0) > (positions.get(after) ?? 0)) {
fail(after, `the 「## ${after}」 section comes after 「## ${before}」`, positions.get(after));
}
});
return problems;
}
function checkStyle(documents: readonly DocsDocument[]): DocsProblem[] {
const problems: DocsProblem[] = [];
for (const { path, text } of documents) {
if (!isLiving(path) && !path.startsWith(DECISION_FOLDER)) continue;
const body = bodyLines(text);
const offset = text.split("\n").length - body.length;
for (const [number, line] of outsideCode(body, true)) {
// A polite ending inside 「」 or quotes is a quotation, not this document's sentence.
const found = POLITE.exec(line.replace(INLINE, "").replace(QUOTED, "").replace(CORNER_QUOTED, ""));
if (found) {
problems.push({
check: "style",
path,
key: line.trim().slice(0, 80),
line: number + offset,
message: `polite form (write 「~한다」): …${found[0]}`,
});
}
}
}
return problems;
}
const RUNNERS: Readonly<
Record<DocsSystemCheck, (documents: readonly DocsDocument[], facts: DocsFacts) => DocsProblem[]>
> = Object.freeze({
language: (documents) => checkLanguage(documents),
head: checkHead,
number: checkNumber,
map: checkMap,
readme: (documents) => checkReadme(documents),
style: (documents) => checkStyle(documents),
});
export type DocsSystemResult = Readonly<{
/** Problems the exception list does not excuse, and exception list errors. */
failures: readonly string[];
/** One line per check: found, excused, failed. */
report: readonly string[];
}>;
function readExceptions(text: string): string[] {
return text.split("\n").filter((line) => line.trim() !== "" && !line.startsWith("#"));
}
/** Every problem the checks find, before the exception list is applied. */
export function findDocsProblems(
documents: readonly DocsDocument[],
facts: DocsFacts,
only: readonly DocsSystemCheck[] = DOCS_SYSTEM_CHECKS,
): DocsProblem[] {
return only.flatMap((check) => RUNNERS[check](documents, facts));
}
export function runDocsSystemChecks(
input: Readonly<{
documents: readonly DocsDocument[];
facts: DocsFacts;
exceptions?: string;
frozen?: ReadonlySet<string>;
only?: readonly DocsSystemCheck[];
}>,
): DocsSystemResult {
const allowed = readExceptions(input.exceptions ?? "");
const frozen = input.frozen ?? FROZEN;
const failures: string[] = [];
const report: string[] = [];
for (const entry of allowed) {
if (!frozen.has(sha16(entry))) {
failures.push(`[exceptions] ${EXCEPTIONS_FILE}: not in the baseline; the exception list does not grow: ${JSON.stringify(entry)}`);
}
}
const listed = new Set(allowed.map(sha16));
for (const orphan of [...frozen].filter((fingerprint) => !listed.has(fingerprint)).sort()) {
failures.push(
`[exceptions] scripts/lib/docs-system.ts FROZEN: a fingerprint with no line in the exception list; drop it with its line: ${orphan}`,
);
}
const allowedSet = new Set(allowed);
// A line about a document this tree does not have is not stale here: the
// tests run the checks on a copy of some documents only.
const present = new Set(input.documents.map(({ path }) => path));
for (const check of input.only ?? DOCS_SYSTEM_CHECKS) {
const problems = RUNNERS[check](input.documents, input.facts);
const hit = new Set(problems.map(exceptionLine));
const unexcused = problems.filter((problem) => !allowedSet.has(exceptionLine(problem)));
const stale = allowed.filter((entry) => {
const [entryCheck, entryPath = ""] = entry.split("\t");
return entryCheck === check && present.has(entryPath) && !hit.has(entry);
});
failures.push(...unexcused.map(renderProblem));
failures.push(...stale.map((entry) => `[exceptions] ${EXCEPTIONS_FILE}: no longer matches; delete the line: ${JSON.stringify(entry)}`));
report.push(`${check}: found ${problems.length}, excused ${problems.length - unexcused.length}, failed ${unexcused.length}`);
}
return { failures, report };
}
/**
* The paths README.md lists under 「복사한 뒤 지워도 되는 것」 (first-column
* inline code), without a trailing slash: a copy may delete them, so a path
* under one that is gone is not drift.
*/
export function deletableHistory(readme: string): string[] {
const section = /^### 복사한 뒤 지워도 되는 것\n[\s\S]*?(?=^#)/mu.exec(readme)?.[0] ?? "";
return [...section.matchAll(/^\| (.+?) \|/gmu)].flatMap(([, cell = ""]) =>
[...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, "")),
);
}
// --- Reading a tree.
function walk(root: string, folder = ""): string[] {
const entries = (() => {
try {
return readdirSync(join(root, folder), { withFileTypes: true });
} catch {
return [];
}
})();
return entries.flatMap((entry) => {
const path = folder === "" ? entry.name : `${folder}/${entry.name}`;
if (entry.isDirectory()) return IGNORED_FOLDERS.has(entry.name) ? [] : walk(root, path);
return entry.isFile() ? [path] : [];
});
}
/**
* The files of a tree: what git knows when it is a work tree (tracked plus
* untracked files that are not ignored, so generated output does not count),
* otherwise every file (a copy of the documents, as the tests make).
*/
export function treeFiles(root: string): string[] {
const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
const listing = spawnSync(
"git",
["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--full-name", "--", "."],
{ encoding: "utf8", env, maxBuffer: 64 * 1024 * 1024 },
);
const inside = spawnSync("git", ["-C", root, "rev-parse", "--show-prefix"], { encoding: "utf8", env });
if (listing.status !== 0 || inside.status !== 0 || inside.stdout.trim() !== "") return walk(root).sort();
return listing.stdout
.split("\0")
.filter((name) => name !== "" && existsSync(join(root, name)))
.sort();
}
export function knownPaths(files: readonly string[]): Set<string> {
const paths = new Set<string>();
for (const file of files) {
const parts = file.split("/");
for (let end = 1; end <= parts.length; end += 1) paths.add(parts.slice(0, end).join("/"));
}
return paths;
}
/** The markdown documents of a tree, with their text. */
export function readDocuments(root: string, files: readonly string[] = treeFiles(root)): DocsDocument[] {
return files
.filter((path) => path.endsWith(".md") && !NOT_DOCUMENT.test(path))
.map((path) => ({ path, text: readFileSync(join(root, path), "utf8") }));
}
/** Framework versions from the repository's package.json and .nvmrc. */
export function frameworkVersions(repositoryRoot: string): Map<string, string> {
const versions = new Map<string, string>();
const manifest = JSON.parse(readFileSync(join(repositoryRoot, "package.json"), "utf8")) as {
dependencies?: Record<string, string>;
devDependencies?: Record<string, string>;
};
const declared = { ...manifest.dependencies, ...manifest.devDependencies };
for (const [name, packageName] of FRAMEWORKS) {
const version = /\d+\.\d+\.\d+/u.exec(declared[packageName] ?? "")?.[0];
if (version) versions.set(name, version);
}
const node = existsSync(join(repositoryRoot, ".nvmrc"))
? /\d+\.\d+\.\d+/u.exec(readFileSync(join(repositoryRoot, ".nvmrc"), "utf8"))?.[0]
: undefined;
if (node) versions.set("Node.js", node);
return versions;
}
/**
* Runs the checks on the documents under `documentsRoot`, naming paths in
* `repositoryRoot`. verify:documentation passes its working directory (a copy
* of the documents in the tests) and this repository.
*/
export function checkDocsSystem(documentsRoot: string, repositoryRoot: string): DocsSystemResult {
const documentFiles = treeFiles(documentsRoot);
const exceptionsPath = join(repositoryRoot, EXCEPTIONS_FILE);
return runDocsSystemChecks({
documents: readDocuments(documentsRoot, documentFiles),
facts: {
knownPaths: knownPaths(treeFiles(repositoryRoot)),
docsFiles: documentFiles.filter((path) => path.startsWith(DOCS_ROOT)),
frameworkVersions: frameworkVersions(repositoryRoot),
deletable: deletableHistory(
existsSync(join(documentsRoot, README_FILE)) ? readFileSync(join(documentsRoot, README_FILE), "utf8") : "",
),
},
exceptions: existsSync(exceptionsPath) ? readFileSync(exceptionsPath, "utf8") : "",
});
}
/** Living documents under `root` whose references verify:documentation checks. */
export function livingDocuments(root: string): string[] {
return readDocuments(root)
.map(({ path }) => path)
.filter(checkedForDrift);
}
+25 -11
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, 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 (tsconfig.web-worker.json).
@@ -218,15 +220,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
@@ -341,6 +337,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);
@@ -408,6 +410,10 @@ const documentReferencesValid = documentReferences.every(
(entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.length === 0,
);
// 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;
@@ -422,6 +428,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 });
@@ -502,6 +509,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`,
);
@@ -523,4 +536,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");