@@ -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 = / ^ d o c s \ / a c c e s s i b i l i t y \ / r o u t e - r e v i e w s \ / / 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 = / [ 가 - 힣 ] + / g u ;
const FENCE = / ^ [ \ t ] * ( ` { 3 , } | ~ { 3 , } ) / u ;
const INLINE = / ( ` + ) ( ? : ( ? ! \ 1 ) [ \ s \ S ] ) + ? \ 1 / g u ;
const MDLINK = / \ [ [ ^ \ ] \ n ] * \ ] \ ( [ ^ ) \ s ] * \ ) / g u ;
const URL = / ( ? : \ b [ a - z ] [ a - z 0 - 9 + . - ] * : \ / \ / | \ b w w w \ . ) \ S + / g i u ;
const PATHLIKE = / [ ^ \ s 가 - 힣 ] * [ / \ \ ] [ ^ \ s 가 - 힣 ] * / g u ;
const FILELIKE = / [ ^ \ s 가 - 힣 ] + \ . [ A - Z a - z ] { 1 , 1 0 } ( ? : : \ d + ) * ( ? ! [ A - Z a - z ] ) / g u ;
const QUOTED = / " [ ^ " \ n ] * " | “ [ ^ ” \ n ] * ” / g u ;
const TOKEN = / [ ^ \ s 가 - 힣 ] + / g u ;
const WORD = / ^ [ ( [ " ' “ ‘ * _ ] * [ A - Z a - z ] [ a - z ] * ( ? : [ ' ’ ] [ a - z ] + ) ? ( ? : - [ a - z ] + ) * [ ) \ ] " ' ” ’ * _ . , ; : ! ? … ] * $ / u ;
const HISTORY_QUOTE = / ^ \ s * > \ s * ( ? : \ * \ * ) ? 이 력 / u ;
const CORNER_QUOTED = / 「 [ ^ 」 \ n ] * 」 / g u ;
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 ( ? : R e a c t ( ? : D O M | R o u t e r ) ? | V i t e | T y p e S c r i p t | V i t e s t | P l a y w r i g h t | T a n S t a c k Q u e r y | Z o d | S t o r y b o o k | N o d e ( ? : \ . j s ) ? ) \ s + v ? \ d + \ . \ d + ( ? : \ . \ d + ) ? \ b / g u ;
const COPIED_COUNTS = Object . freeze ( [
[
"gate count (config/ci/gates.json)" ,
/ \ b \ d + \ s * 개 의 ? \ s * ( ? : m e r g e \ s * ) ? ( ? : 게 이 트 | g a t e ) | ( ? : 게 이 트 | g a t e ) \ s * \ d + \ s * 개 | \ b \ d + \ s + ( ? : m e r g e \ s + ) ? g a t e s \ b / g i u ,
] ,
[ "recipe count (config/recipes/frontend-capability-recipes.json)" , / \ b \ d + \ s * 개 의 ? \ s * r e c i p e | r e c i p e \ s * \ d + \ s * 개 | \ b \ d + \ s + r e c i p e s \ b / g i u ] ,
[ "adapter count (docs/reviews/adapters/INVENTORY.md)" , / \ b \ d + \ s * 개 의 ? \ s * a d a p t e r | a d a p t e r \ s * \ d + \ s * 개 | \ b \ d + \ s + a d a p t e r s \ b / g i u ] ,
] 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 . t e s t ( v a l u e ) ) r e t u r n f a l s e ;
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 ( / ` ( [ ^ ` ] + ) ` / g u ) ] . m a p ( ( [ , p a t h = " " ] ) = > p a t h ) ;
}
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 . e x e c ( l i n e ) ;
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 . t e s t ( s u m m a r y [ 0 ] ) | | i s E n g l i s h ( s u m m a r y [ 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 ( / ^ ` + | ` + $ / g u , " " ) . t r i m ( ) ;
if ( token . startsWith ( DOCS_ROOT ) ) token = token . slice ( DOCS_ROOT . length ) ;
if ( token . endsWith ( "/" ) && ! / [ * ? < > { } [ \ ] $ … ] | \ . \ . \ . / u . t e s t ( t o k e n ) ) e n t r i e s . p u s h ( [ n u m b e r , t o k e n ] ) ;
}
}
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 . e x e c ( l i n e ) ;
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 . t e s t ( l i n e ) ) ) {
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 ] * ? ( ? = ^ # ) / m u . e x e c ( r e a d m e ) ? . [ 0 ] ? ? " " ;
return [ . . . section . matchAll ( / ^ \ | ( . + ? ) \ | / g m u ) ] . f l a t M a p ( ( [ , c e l l = " " ] ) = >
[ . . . cell . matchAll ( / ` ( [ ^ ` ] + ) ` / g u ) ] . m a p ( ( [ , e n t r y = " " ] ) = > e n t r y . r e p l a c e ( / \ / $ / 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 . e x e c ( d e c l a r e d [ p a c k a g e N a m e ] ? ? " " ) ? . [ 0 ] ;
if ( version ) versions . set ( name , version ) ;
}
const node = existsSync ( join ( repositoryRoot , ".nvmrc" ) )
? / \ d + \ . \ d + \ . \ d + / u . e x e c ( r e a d F i l e S y n c ( j o i n ( r e p o s i t o r y R o o t , " . n v m r c " ) , " u t f 8 " ) ) ? . [ 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 ) ) ;
}