원문: https://github.com/facebook/astryx/wiki/Night-Watch-Doc-Reviewer · 번역 기준: 2026-09-03

담당: Joey's Navi (josephfarina)

목표: 컴포넌트 문서를 Storybook autodocs와 호환되게 유지하고, block/page 템플릿 메타데이터를 검증하고, 컴포넌트와 hook 양쪽의 번역 오버레이(docsZh/docsDense)를 완전하고 충실하게 유지하고, CLI 자체의 colocated 문서(FunctionDoc/CommandDoc/SchemaDoc/EnumDoc)가 존재하고 라이브 CLI와 동기화되도록 유지하고, 타입 체커가 볼 수 없는 콘텐츠 수준 이슈를 잡아냅니다.

채점(grading) vs 집행(enforcement). 채점되는 문서 기준 — 무엇이 존재해야 하는지, 어떤 심각도로, 어떻게 점수화되는지 — 는 Component Audit Rubric §8에 있습니다. 이 페이지는 rubric이 이름으로 인용하는 집행 레이어입니다: 체크별 세부 사항과 발견을 산출하는 스크립트들. 둘을 발맞춰 유지하십시오. 둘이 어긋나면, rubric이 기준을 말하고 이 페이지는 그것이 어떻게 측정되는지를 말합니다.

빈도: 하룻밤에 한 번.

이 역할이 존재하는 이유

Astryx 문서는 세 청중을 동시에 상대합니다:

  1. Storybook을 탐색하거나 API 레퍼런스로 .doc.mjs 파일을 읽는 사람
  2. 코드 생성을 위해 CLI 출력(astryx component --brief, --compact, --lang zh, --lang dense, astryx hook)을 소비하는 LLM
  3. 라이브 프리뷰를 위해 JSDoc @example 블록을 파싱하는 Storybook autodocs

.doc.mjs 파일은 CI에서 tsc --checkJs로 타입 체크됩니다 — 구조적 이슈(잘못된 필드, 누락된 필수 프로퍼티, 잘못된 타입)는 자동으로 잡힙니다. 이 역할은 타입 체커가 잡을 수 없는 것에 집중합니다: Storybook docblock 포맷팅, 소스 코드 대비 prop 문서 drift, 템플릿 메타데이터 정확성, showcase/block 완결성.

배경: 문서 포맷

컴포넌트 문서는 타입이 지정된 .doc.mjs 파일에 삽니다. 각 컴포넌트 디렉토리에는 ComponentDoc 타입(@astryxdesign/cli/authoring에서 export)의 docs 상수를 export하는 {Name}.doc.mjs가 있습니다.

CLI는 이것들을 import()로 직접 임포트합니다 — 마크다운 파싱은 없습니다. 타입 체크는 CI에서 tsc --checkJs로 실행되므로(pnpm --filter @astryxdesign/core typecheck:docs), 구조적 유효성은 머지 전에 이미 집행됩니다.

템플릿 시스템 (PR #1393+)

템플릿은 두 카테고리로 나뉩니다: