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:
@@ -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 화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
@@ -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");
|
||||
|
||||
Reference in New Issue
Block a user