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
+1 -1
View File
@@ -8,7 +8,7 @@
# materialized into `dist/config.json` at build time. Only the emergency
# switches (CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) may be changed in a
# deployed config.json without rebuilding, by the checked procedure in
# docs/runbooks/FE-RB-001.md. See the "Runtime configuration" section of
# docs/runbooks/FE-RB-001.md. See the 「런타임 설정과 배포 변수」 section of
# README.md.
#
# Copy to `.env.local` (git-ignored) to override locally.
+1 -1
View File
@@ -1,7 +1,7 @@
# 변경 이력
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다.
가져오는 방법은 `README.md`의 「원본 업데이트 반영」 절에 있다.
- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다.
- 미출시 절은 한 번의 동기화 단위(기준 커밋 → 브랜치 끝)에서 받는 변경의 순 요약이다. 최종 상태만 적고, 같은 범위 안에서 뒤 커밋이 바꾼 중간 상태는 지운다. 호환을 깨는 변경은 절 첫머리 "먼저 할 일"에 옮기기 전·옮기는 법·옮긴 뒤 확인 순서로 적는다.
+184 -327
View File
@@ -1,69 +1,101 @@
# Clean Architecture Frontend Template
A React/Vite reference implementation where architecture boundaries,
integration behavior, release coherence, accessibility, performance, and
operations are executable contracts rather than conventions.
React와 Vite로 만든 프론트엔드 참조 구현(reference implementation)이다. 이 템플릿을 복사한 제품 팀이 도메인 기능을 채워 서비스를 만든다.
아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약(게이트와 테스트)으로 지킨다.
## Start locally
## 프로젝트 구조
Requirements: the exact Node.js version in `.nvmrc` (currently 24.14.0) and
Corepack. The repository pins pnpm in `package.json`.
최상위 폴더와 파일:
Product source, tests, build/quality scripts, and supported tool configuration
are TypeScript/TSX. `allowJs` is disabled. Node-side `.ts` scripts run directly
on the pinned Node 24 runtime and are checked with NodeNext resolution plus
erasable-syntax enforcement. Project-owned executable source contains no
JavaScript-family files; negative architecture, security, and type-compatibility
fixtures are TypeScript/TSX as well.
| 경로 | 하는 일 | 먼저 읽을 곳 |
| --- | --- | --- |
| `src/` | 앱 코드. 아래 표의 폴더로 나뉜다 | `docs/architecture/layers.md` |
| `tests/` | 테스트. 계층별 폴더(`tests/unit/`, `tests/component/`, `tests/integration/`, `tests/e2e/` 등) | `docs/testing/taxonomy.md` |
| `scripts/` | 빌드·검사·생성 명령의 TypeScript 스크립트. `package.json`의 script가 부른다 | `package.json` |
| `config/` | 게이트 목록(`config/ci/`), 런타임 프로필(`config/runtime/`), recipe 카탈로그(`config/recipes/`), 보안·성능·규모 기준선 | `docs/operations/ci-quality-gates.md` |
| `schemas/` | 설정 파일과 산출물의 JSON Schema | `config/` |
| `recipes/` | 선택 기능(recipe)의 원본 코드. 제품이 앱으로 복사해 쓴다. 기본 빌드에 들어가지 않는다 | `docs/architecture/optional-adapter-recipes.md` |
| `docs/` | 문서. 지도는 `docs/README.md` | `docs/README.md` |
| `artifacts/` | 게이트가 쓰는 증거 산출물. git은 무시하고, 수동 접근성 검토 기록(`artifacts/tests/a11y-manual/`)만 추적한다 | `docs/operations/ci-quality-gates.md` |
| `public/`, `index.html` | 정적 자원과 앱 진입 HTML | `docs/architecture/static-delivery.md` |
| `.gitea/` | CI workflow(`.gitea/workflows/quality-gates.yml`, 생성 파일) | `docs/operations/ci-quality-gates.md` |
| `.storybook/` | Storybook 설정 | `docs/styling/design-tokens.md` |
| `.dependency-cruiser.json` | import 규칙. `check:architecture`가 읽는다 | `docs/architecture/layers.md` |
| `CLAUDE.md` | 이 repo를 리뷰할 때의 기준 | `CLAUDE.md` |
| `PRODUCT.md` | 디자인 도구가 읽는 제품 맥락 | `PRODUCT.md` |
| `CHANGELOG.md` | 템플릿 버전 사이의 변경과 복사한 프로젝트가 할 일 | `CHANGELOG.md` |
`src/` 폴더 (설명은 `docs/architecture/layers.md` 표와 같다. 그 문서가 import 규칙도 모두 적는다):
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
- `src/application` — 범용 use case, 포트, 정책, view-model
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
의존은 안쪽으로 향한다. 어느 폴더든 `contracts`와 `platform`은 가져와도 된다:
```text
presentation -> application -> contracts -> platform
adapters -----^
bootstrap composes concrete adapters
apps -> contexts -> features (an app deploys contexts; a context owns features)
feature use case -> feature port <- feature-owned capability binding
```
- 도메인 코드는 각 기능 안에 있다. 최상위 domain 폴더는 없다.
- 기능은 `src/features/<id>` 아래 수직 slice다. 도메인, application 입력, HTTP 연결, 계약, 라우트 런타임, 화면을 그 기능이 소유한다. 중앙 목록은 고른 기능의 기여를 모으기만 한다.
- 템플릿은 기능을 하나도 싣지 않는다(참조 샘플과 예제 화면은 2026-11-07에 지웠다). `corepack pnpm create:feature <id>`가 기능을 만든다. 기능이 없어도 범용 스타터 라우트는 타입 검사·테스트·빌드를 통과한다.
- 불변식: 규칙은 `.dependency-cruiser.json`이 정하고 `check:architecture`가 모든 import를 풀어 검사한다. 해석되지 않은 import, 파싱 실패, 금지된 계층 간선, 순환 의존은 모두 실패로 닫힌다(fail-closed).
플랫폼 계층의 역할과 경계는 `docs/architecture/frontend-application-foundation.md`, `docs/architecture/overview.md`, `docs/architecture/starter-experience.md`에 있다.
## 시작하기
전제: `.nvmrc`에 적힌 Node.js 버전과 Corepack. pnpm 버전은 `package.json`이 고정한다.
```bash
corepack pnpm install --frozen-lockfile
corepack pnpm dev
```
## Runtime configuration
- 성공하면 터미널에 Vite가 알려 준 로컬 주소에서 헤더와 사이드바가 있는 앱 셸이 뜬다.
- 내리려면 그 터미널에서 Ctrl+C를 누른다.
Runtime-public settings are validated against one schema before the product
tree mounts (`runtimeConfigV2ArtifactSchema` in
`src/contracts/release-artifacts.ts`). Client secrets are forbidden.
앱 코드, 테스트, 빌드·품질 스크립트, 도구 설정은 모두 TypeScript/TSX다. `allowJs`는 꺼져 있다. Node 쪽 `.ts` 스크립트는 고정한 Node 런타임에서 바로 돈다. NodeNext 해석과 지울 수 있는 문법(erasable syntax)만 쓰는지로 검사한다. 아키텍처·보안·타입 호환의 음성 fixture도 TypeScript/TSX다.
The source of truth is `config/runtime/<profile>.json`, one file per
environment: `local`, `development`, `staging`, `production`. `corepack pnpm
build` writes `dist/config.json` from the selected profile
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
profile for `corepack pnpm dev`; the build replaces it, so settings put there
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
`BUILD_ID: local-build` and `RELEASE_ID: local-release`;
`tests/unit/deployment-admission.test.ts` fails when the two differ.
## 런타임 설정과 배포 변수
Build and deploy variables, lowest precedence first:
런타임에 공개되는 설정은 제품 트리를 마운트하기 전에 스키마 하나로 검증한다(`src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema`). 클라이언트 비밀값은 금지다.
| Variable | Sets | Default |
정본은 환경마다 하나인 `config/runtime/<profile>.json`이다: `local`, `development`, `staging`, `production`.
- `corepack pnpm build`는 고른 프로필로 `dist/config.json`을 쓴다(`scripts/generate-runtime-config.ts`).
- `public/config.json`은 `corepack pnpm dev`용 로컬 프로필일 뿐이다. 빌드가 덮어쓰므로 거기 넣은 설정은 배포에 닿지 않는다.
- `public/config.json`은 `config/runtime/local.json`에 `BUILD_ID: local-build`, `RELEASE_ID: local-release`를 더한 것과 같아야 한다. 다르면 `tests/unit/deployment-admission.test.ts`가 실패한다.
빌드·배포 변수 (위가 우선순위가 가장 낮다):
| 변수 | 정하는 것 | 기본값 |
| --- | --- | --- |
| `APP_PROFILE` | which `config/runtime/<profile>.json` is used | `local`; an empty value fails the build |
| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile; the CI workflow cannot pass it (see below) | the profile value |
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile; the CI workflow cannot pass it (see below) | the profile value |
| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` for `local` and `development`; a `staging` or `production` build fails without it |
| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` |
| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it |
| `APP_PROFILE` | 어느 `config/runtime/<profile>.json`을 쓰나 | `local`. 빈 값이면 빌드가 실패한다 |
| `RUNTIME_API_BASE_URL` | 프로필을 덮어쓰는 `API_BASE_URL`. CI workflow는 넘길 수 없다(아래) | 프로필 값 |
| `RUNTIME_TELEMETRY_ENDPOINT` | 프로필을 덮어쓰는 `TELEMETRY_ENDPOINT`. CI workflow는 넘길 수 없다(아래) | 프로필 값 |
| `VITE_BUILD_ID` | 런타임 설정과 릴리스 manifest의 `BUILD_ID` | `local`·`development`는 `local-build`. `staging`·`production` 빌드는 없으면 실패한다 |
| `RELEASE_ID` | 런타임 설정과 릴리스 manifest의 `RELEASE_ID` | `local-release` |
| `RELEASE_TARGET` | FE-GATE-027이 빌드를 받아들일 환경. `APP_PROFILE`과 같아야 한다 | 없음. 없으면 승인(admission)이 거절한다 |
`verify:documentation` fails if this table stops naming a variable the build or
admission reads (`scripts/verify-documentation-readiness.ts`).
빌드나 승인이 읽는 변수를 이 표가 빠뜨리면 `verify:documentation`이 실패한다(`scripts/verify-documentation-readiness.ts`).
Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything
else changes by editing the profile file. Staging and production reject demo
auth, non-HTTPS endpoints and the names reserved for examples and tests
(`example.com`, `example.net`, `example.org` and their subdomains, `.example`,
`.invalid`, `.test`). The shipped `staging` and `production` profiles use
`*.example.com`, so admission refuses them until a project sets its own
endpoints.
- 검토한 프로필과 달라질 수 있는 값은 두 `RUNTIME_*`뿐이다. 나머지는 프로필 파일을 고쳐서 바꾼다.
- staging과 production은 demo 인증, HTTPS가 아닌 endpoint, 예시·시험용으로 예약된 이름(`example.com`, `example.net`, `example.org`와 그 하위 도메인, `.example`, `.invalid`, `.test`)을 거절한다. 템플릿의 `staging`·`production` 프로필은 `*.example.com`을 쓰므로 프로젝트가 자기 endpoint를 넣기 전까지 승인이 거절한다.
- CI에서 endpoint를 정하는 길은 `config/runtime/<profile>.json`에 커밋하는 것뿐이다. CI 계약은 build job에 `APP_PROFILE`과 `RELEASE_TARGET`만 넘긴다(`scripts/contracts/ci-gates.ts`). 그래서 `RUNTIME_*` repository 변수는 빌드에 닿지 않는다.
In CI the only way to set the endpoints is to commit them to
`config/runtime/<profile>.json`. The CI contract binds just `APP_PROFILE` and
`RELEASE_TARGET` to the build job (`scripts/contracts/ci-gates.ts`), so a
`RUNTIME_*` repository variable never reaches the build.
A local production build and its admission check:
로컬 production 빌드와 그 승인 검사:
```bash
APP_PROFILE=production \
@@ -74,318 +106,156 @@ corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
```
With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires
`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a
gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable
list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
`CI=true`이면 게이트 실행기(`corepack pnpm ci:gate`)가 게이트를 돌리기 전에 `VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH`, `CI_RUNNER_IMAGE`도 요구한다(`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). CI 변수 목록은 [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)에 있다.
## Included starter experience
## 기능 켜고 끄기
The default build mounts a domain-neutral application shell with a header,
responsive sidebar, route focus management, session integration status, a
persistent `system` / `light` / `dark` theme selector, and a language selector.
- **제품 기능**은 `corepack pnpm create:feature <id>`로 만들고 지운다. 절차는 [`docs/manual/`](docs/manual/README.md)에 있다. 기능 폴더만 지우면 테스트·정책 항목·CI 스크립트가 남아 게이트가 실패한다. 지우는 법은 아래 「새 서비스로 시작하기」에 있다.
- **선택 capability**(recipe)는 기본 빌드에 없다. 프로젝트가 `config/recipes/frontend-capability-recipes.json`의 recipe 하나를 복사하고 좁혀서 넣는다. 원칙과 절차는 [`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)에 있다.
- **인증**: `AUTH_MODE=demo`는 자격 증명이 없고 local·development에서만 받는다. 배포는 `AUTH_MODE=external`을 쓰고 [`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md)가 설명하는 불투명 인증 owner를 준다. 클라이언트 라우트 정책은 사용자 경험일 뿐이다. 권한의 정본은 서버다.
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
the platform routes of `src/contracts/routes.ts` plus the routes of every
installed feature. The template installs none: `corepack pnpm create:feature`
adds one (`docs/manual/`). The platform overview page (`/examples/platform`) shows the composed list at runtime, so
this README keeps no copy of it and adding a feature does not edit it.
### 기본 화면
`AUTH_MODE=demo` is credential-free and accepted only in local/development
environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
owner described in
[`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md).
The client route policy is user experience only; server authorization remains
authoritative.
기본 빌드는 도메인 중립 앱 셸을 마운트한다. 헤더, 반응형 사이드바, 라우트 포커스 관리, 세션 연동 상태, 저장되는 `system` / `light` / `dark` 테마 선택, 언어 선택이 있다.
## Support scope
라우트 목록은 `ROUTE_REGISTRY`(`src/features/installed-feature-contracts.ts`)다. `src/contracts/routes.ts`의 플랫폼 라우트와 설치된 모든 기능의 라우트를 합친다. 템플릿은 기능을 설치하지 않는다. 플랫폼 개요 화면(`/examples/platform`)이 런타임에 합친 목록을 보여 준다. 그래서 이 README는 목록 사본을 두지 않고, 기능을 더해도 고치지 않는다.
Four tiers. The status words on the right are the ones the catalogs and
design documents use; the next table maps them.
### 지원 범위
| Tier | What it covers | Status words |
네 단계다. 오른쪽 상태 값은 카탈로그와 설계 문서가 쓰는 말이다. 뜻은 다음 표에 있다.
| 단계 | 무엇이 들어가나 | 상태 값 |
| --- | --- | --- |
| Default | In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), the typed message catalog, and `create:feature`, which writes a feature that passes the merge gates. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe | `DESIGNED_NOT_IMPLEMENTED` |
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` |
| 기본 | 기본 빌드에 들어가고 merge 게이트가 덮는다: 앱 셸과 예제 라우트, REST HTTP 실행기, TanStack Query 서버 상태, Local/Session Storage registry, 탭 간 무효화, 런타임 설정 프로필과 릴리스 manifest 검사, `AUTH_MODE=external`(`demo`는 local·development만), 타입이 있는 문구 카탈로그, merge 게이트를 통과하는 기능을 만드는 `create:feature`. `dist/`는 정적 호스트가 서빙한다([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
| 선택(recipe) | 설치되지 않는다. 프로젝트가 `config/recipes/frontend-capability-recipes.json`의 recipe를 복사하고 좁힌다([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa`, `file-transfer`는 시험한 참조 런타임도 싣지만 기본 빌드는 뺀다 | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
| 실험 | 설계와 결정은 했지만 런타임이 없거나 덜 됐다. 그 위에 짓기 전에 마저 만든다. GraphQL, gRPC-Web, Connect-Web, Protobuf adapter, Range 이어받기 다운로드, IndexedDB query 영속화, 로컬 미리보기 디코드 안전 탐침 | `DESIGNED_NOT_IMPLEMENTED` |
| 지원 안 함 | 일부러 고르지 않았거나 브라우저가 보장하지 못한다: SSR, 앱이 관리하는 백그라운드 업로드·다운로드, 디렉터리 선택, 영속 파일 핸들, 제품 query 영속화, 탭 사이의 정확히 한 번 전달 | `NOT_SELECTED`, `PLATFORM_LIMITED` |
The rows come from
[`docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md`](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md),
[`docs/design/2026-07-28-client-cache-and-storage-design.md`](docs/design/2026-07-28-client-cache-and-storage-design.md)
and
[`docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md).
행의 출처는 설계서 [`docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md`](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md), [`docs/design/2026-07-28-client-cache-and-storage-design.md`](docs/design/2026-07-28-client-cache-and-storage-design.md), [`docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)다.
| Status word | Where it appears | Meaning | Tier |
| 상태 값 | 나오는 곳 | 뜻 | 단계 |
| --- | --- | --- | --- |
| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default |
| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional |
| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a declared feature the build or `FEATURE_OVERRIDES` left out | not part of the build | Optional (recipe) or Experimental (feature) |
| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional |
| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental |
| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported |
| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
| `COMPOSED` | capability 원장, 설계 문서 | 기본 production 경로에 조립됐다 | 기본 |
| `INSTALLED` | 프로젝트 자신의 recipe 카탈로그(recipe 절차 10단계) | 프로젝트가 recipe를 더했다 | 그 프로젝트에서 기본 |
| `RECIPE_AVAILABLE` | recipe 카탈로그 `status` | 복사할 recipe가 있다. 설치된 것은 없다 | 선택 |
| `NOT_INSTALLED` | recipe 카탈로그 `defaultStatus`. 빌드나 `FEATURE_OVERRIDES`가 뺀 선언된 기능 | 빌드에 없다 | 선택(recipe) 또는 실험(기능) |
| `AVAILABLE_NOT_COMPOSED` | capability 원장, recipe `referenceRuntime.status` | 코드와 테스트가 있지만 기본 빌드가 뺀다 | 선택 |
| `DESIGNED_NOT_IMPLEMENTED` | capability 원장, 설계 문서 | 설계는 승인됐고 런타임이 없다 | 실험 |
| `NOT_SELECTED` | capability 원장, 설계 문서 | 일부러 고르지 않았다 | 지원 안 함 |
| `PLATFORM_LIMITED` | capability 원장 | 브라우저가 보장하지 못한다. 준다면 탐침과 대체 경로 뒤에서만 준다 | 보장으로는 지원 안 함 |
Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are
verdicts on evidence, not support tiers.
게이트 결과(`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`)는 증거에 대한 판정이지 지원 단계가 아니다.
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
iOS 16.4. That is the higher of Vite 8's default JavaScript target
(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older
versions inside the target range and real mobile browsers are not tested.
브라우저: 빌드 대상은 Chrome·Edge 111, Firefox 128, Safari·iOS 16.4다.
## Architecture
- Vite 기본 JavaScript 대상(`baseline-widely-available`. `vite.config.ts`는 `build.target`을 정하지 않는다)과 Tailwind CSS의 CSS 대상 중 높은 쪽이다. browserslist는 없다.
- end-to-end 시험은 Playwright가 고정한(`package.json`의 `@playwright/test`) 데스크톱 Chromium·Firefox·WebKit과, Chromium 휴대폰 크기 smoke 하나로 돈다(`playwright.config.ts`).
- 대상 범위 안의 더 오래된 버전과 실제 모바일 브라우저는 시험하지 않는다.
This repository is a **Frontend Application Foundation**: a starter/composition
skeleton plus a reusable capability platform. Platform capabilities stay
horizontal while product business features use vertical slices.
## 문서 지도
`src/` has nine top-level folders. The descriptions match the table in
`docs/architecture/layers.md`, which also names every import rule:
모든 문서 폴더의 지도는 [`docs/README.md`](docs/README.md)다. 거기에 문서의 수명(살아 있는 문서·결정 기록·기록)과 언어 규칙, 기록 문서의 머리 블록 형식도 있다.
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
- `src/application` — generic use cases, ports, policies and view-models
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
Dependencies point inward. Every folder may also import `contracts` and
`platform`:
```text
presentation -> application -> contracts -> platform
adapters -----^
bootstrap composes concrete adapters
apps -> contexts -> features (an app deploys contexts; a context owns features)
feature use case -> feature port <- feature-owned capability binding
```
Domain code lives inside each feature; there is no top-level domain folder.
See
`docs/architecture/frontend-application-foundation.md`,
`docs/architecture/overview.md`, `docs/architecture/layers.md`, and
`docs/architecture/starter-experience.md`. A feature is a vertical slice under
`src/features/<id>`; its domain, application input, HTTP binding, contracts,
route runtime, and presentation own their contributions. The central installed
catalogs only aggregate selected contributions. The template ships no feature
(its reference sample and example screens were deleted on 2026-11-07):
`corepack pnpm create:feature <id>` writes one, and the generic starter routes
typecheck, test, and build without any.
### Platform capability review
The starter shell is implemented, but the repository review also records the
remaining work required before feature teams can use every declared contract
through one end-to-end application path:
- [platform capability review](docs/design/2026-07-26-frontend-platform-capability-review-design.md)
- [ports, adapters, and feature boundaries](docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
- [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
- [Protobuf browser transports and REST Gateway](docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
- [backend API and Server State handoff contract](docs/architecture/backend-api-and-server-state-contract.md)
- [TypeScript, state ownership, and data flow](docs/design/2026-07-26-typescript-state-and-data-flow-design.md)
- [routing, page templates, and reusable patterns](docs/design/2026-07-26-routing-pages-and-patterns-design.md)
- [browser data capability completion ledger](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md)
- [browser file and origin-storage platform](docs/design/2026-07-27-browser-file-and-origin-storage-design.md)
- [client cache and storage](docs/design/2026-07-28-client-cache-and-storage-design.md)
- [realtime events, Web Push, and bounded polling](docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
- [presigned transfer, resumable upload, streaming download, and Image CDN](docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
- [server file capability infrastructure](docs/design/2026-07-28-server-file-capability-infrastructure-design.md)
- [design-system platform](docs/design/2026-07-26-design-system-platform-design.md)
- [frontend platform testing strategy](docs/design/2026-07-26-frontend-platform-testing-strategy-design.md)
- [implementation roadmap](docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
These documents distinguish repository defaults from opt-in adapters and
project-owned integrations. They are target designs and review findings; a
capability is not treated as implemented until its branch acceptance criteria
and executable gates pass.
## Documentation
[`docs/README.md`](docs/README.md) sorts the documents into current contracts,
target designs and work history.
[`docs/manual/`](docs/manual/README.md) is the step-by-step guide (Korean) for
adding a feature, starting from `corepack pnpm create:feature <id>`.
### Files you can delete after copying
These record how the template was built. Nothing in the build or the gates
reads them, except the one file noted below
(`tests/unit/deletable-history-documents.test.ts` checks this).
| Path | Contents |
| 무엇 | 어디 |
| --- | --- |
| `docs/superpowers/` | past plans and specs |
| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/`: `check:adapter-inventory` (FE-GATE-010) reads its `INVENTORY.md`, whose rows link to the adapter reviews beside it, and `docs/operations/adapter-remediation-ledger.md` cites those reviews |
| `SPEC.md`, `docs/history/` | requirements of the 2026-09-25 review fix round (`SPEC.md`), and the plans and evidence of finished work, that round's task list included |
| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own |
| `PRODUCT.md` | product context of the template itself (users, purpose, principles) for design tools; replace it with your product's |
| 개발 매뉴얼: 새 기능을 더하는 순서와 판단 기준, `create:feature`, 완료 기준 | [`docs/manual/`](docs/manual/README.md) |
| 현재 계약: 계층과 import 규칙, 스타터, recipe, 정적 배포, 규모 설계, 짝 백엔드 계약 | [`docs/architecture/`](docs/architecture/), [`docs/contracts/`](docs/contracts/), [`docs/security/`](docs/security/), [`docs/styling/`](docs/styling/), [`docs/accessibility/`](docs/accessibility/), [`docs/testing/`](docs/testing/) |
| 운영과 복구: 게이트, 복구 절차, 성능 증거, 오류 code별 runbook | [`docs/operations/`](docs/operations/), [`docs/runbooks/`](docs/runbooks/) |
| 결정 기록(VD) | [`docs/adr/`](docs/adr/) |
| 설계서(쓴 때의 목표 설계) | [`docs/design/`](docs/design/) |
| 기록: 계획서·증거, 리뷰 | [`docs/history/`](docs/history/), [`docs/reviews/`](docs/reviews/) |
| 버전별 변경 | [`CHANGELOG.md`](CHANGELOG.md) |
A feature is not in this list: deleting its directory alone leaves tests,
policy entries and CI scripts behind that fail the gates.
`corepack pnpm test:sample-removal -- --feature=<id>` removes it from a copy of
the repository and lists everything that has to go with it (the header comment
of `scripts/test-sample-removal.ts`); do the same in your project and run the
gates. A sample your project keeps for a while can be listed in
`scripts/lib/removable-template-features.ts`: the drill then removes it without
`--feature`, and the documentation check accepts its paths once its
`feature-module.ts` is gone.
설계서와 기록은 쓴 때의 글이다. 지금 동작은 각 문서 맨 위 머리 블록의 「현재 정본」을 읽는다.
## Verification
## 검증
Common local checks:
일상 명령:
```bash
corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:types:app
corepack pnpm check:types:node
corepack pnpm check:types:test
corepack pnpm check:architecture
corepack pnpm test:all
corepack pnpm test:contract
corepack pnpm test:e2e
corepack pnpm test:a11y
corepack pnpm build
corepack pnpm check:bundle
corepack pnpm test:performance
corepack pnpm verify:compatibility
corepack pnpm verify:release
corepack pnpm check:registries
corepack pnpm drill:runbooks
corepack pnpm check:ci
```
`drill:runbooks` stops at the first drill that is not `PASS`. Without provider
evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports
a check it could not run locally as `PASS`; see "Runbook jobs" in
[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
- `check:types`는 앱 코드, Node 스크립트·설정, 테스트를 따로 나눈 TypeScript project로 모두 검사한다(`check:types:app`, `check:types:node`, `check:types:test`). 타입·아키텍처·보안·registry의 잘못된 fixture는 `config/ci/gates.json`에서 "실패해야 통과"하는 음성 게이트로 돈다. 도구 호환 결정은 [VD-01](docs/adr/VD-01-typescript-lint-tooling.md)에 있다.
- `test:all`은 평소 제품 개발 루프이고 호스트 수준의 CI runner 검증은 일부러 뺀다. `corepack pnpm test:system`은 [`docs/testing/taxonomy.md`](docs/testing/taxonomy.md)가 말하는 호환 Linux 검증 호스트에서만 돌린다.
- 브라우저 시험 전에 고정한 Playwright 브라우저 엔진을 설치한다: `corepack pnpm exec playwright install --with-deps chromium firefox webkit`.
- 그 밖의 검사(`test:contract`, `test:e2e`, `test:a11y`, `check:bundle`, `test:performance`, `verify:compatibility`, `verify:release`, `check:registries`, `drill:runbooks`, `check:ci`)는 `package.json`과 [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)에 있다. `drill:runbooks`는 `PASS`가 아닌 첫 드릴에서 멈춘다. provider 증거가 없으면 모든 드릴이 `UNVERIFIED`(exit 3)로 끝난다. 로컬에서 돌리지 못한 검사를 `PASS`로 적지 않기 때문이다.
`test:all` is the ordinary product-development loop and intentionally excludes
host-level CI-runner assurance. Run `corepack pnpm test:system` only on the
compatible Linux assurance host described in
[`docs/testing/taxonomy.md`](docs/testing/taxonomy.md).
### 게이트와 CI
`check:types`는 source, Node scripts/config와 tests를 분리된 TypeScript
project로 모두 검사한다. type/architecture/security/registry의 invalid
fixture는 `config/ci/gates.json`에서 “실패해야 통과”하는 negative gate로
실행된다. 도구 호환성 결정은
[VD-01](docs/adr/VD-01-typescript-lint-tooling.md)에 기록돼
있다.
Application feature input은 module augmentation으로 닫힌 ID와 정확한 input
shape를 제공하며, 공통 `Result<Value, Failure = AppFailure>`는 error registry의
failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는
TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고
runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import,
parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용
TypeScript/TSX negative fixture로도 검증된다.
Install the pinned Playwright browser engines before the first cross-browser
run:
```bash
corepack pnpm exec playwright install --with-deps chromium firefox webkit
```
Two gates intentionally need external evidence:
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
keyboard/focus/screen-reader review of every registered route, one record
per route at `artifacts/tests/a11y-manual/<ROUTE_ID>.md`. The routes are
`ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a
registered route has no record. The merge gate FE-GATE-009 runs only
`review:a11y-manual -- --format-only`, which checks that every route record
keeps the template's fields, reviewed or still pending.
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
eligible-sample threshold and 28 days of production data exist.
Live hosting verification (FE-GATE-019, production stage) requires
`HOSTING_BASE_URL` and the promoted release deployed by the workflow's
`deployment` job. That job is an empty slot until the project fills it in
`config/ci/product-gates.json`
([`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md));
until then the result is `UNVERIFIED`, not `PASS`. A host serving another
release fails, and so does one without HTTP/2 or entry compression.
## CI and evidence
The gate registry is `config/ci/gates.json`; the Gitea workflow is
`.gitea/workflows/quality-gates.yml`. It follows:
게이트 목록은 `config/ci/gates.json`이고 Gitea workflow는 `.gitea/workflows/quality-gates.yml`이다. 단계 순서:
```text
MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
```
`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning.
`DOCUMENTATION_READY`는 따로 선다. 경고로 낮춘 게이트는 없다.
The workflow runs on pull requests, pushes to `main` and `develop`, and `v*`
tags. The Git host of this repository may not have Actions enabled, so a pull
request can show no gate status at all; no status is not a pass. Until the
host runs the workflow and marks the merge gates as required checks, run the 14
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
browsers; FE-GATE-012 builds the app first; FE-GATE-013 needs a Linux host where
bubblewrap may create unprivileged user and network namespaces, which Ubuntu
23.10 and later refuse by default — its first step says so, and
`docs/operations/ci-quality-gates.md` lists the fixes). Product checks listed in
`config/ci/product-gates.json` (`PRODUCT-GATE-NNN`) run in the workflow's own
`product_merge_gate` job, which the release stage waits for:
workflow는 pull request, `main`·`develop` push, `v*` 태그에서 돈다. 이 repo의 Git 호스트는 Actions가 꺼져 있을 수 있다. 그러면 pull request에 게이트 상태가 아예 안 보인다. 상태가 없는 것은 통과가 아니다. 호스트가 workflow를 돌리고 merge 게이트를 필수 검사로 지정하기 전까지는 병합 전에 merge 단계 게이트를 로컬에서 모두 돌린다:
```bash
for gate in 001 002 003 004 005 006 007 008 009 010 011 012 013 020; do
corepack pnpm ci:gate -- "FE-GATE-$gate" || break
for gate in $(node -p 'require("./config/ci/gates.json").stages.find((s) => s.id === "merge").gateIds.join(" ")'); do
corepack pnpm ci:gate -- "$gate" || break
done
```
To run them as the workflow does, give the workflow's environment first.
`CI=true` makes the runner and the release build require the CI build
identity; builds a test makes of a copy (fixture builds, the visual goldens'
build, the dev servers of the browser tests) run as local builds whatever this
says (`localBuildEnvironment` in `scripts/lib/build-environment.ts`). Run it in
a clean clone: `ci:gate` stops a gate at its first failing command.
- FE-GATE-008과 FE-GATE-009는 Playwright 브라우저가 필요하다. FE-GATE-012는 먼저 앱을 빌드한다.
- FE-GATE-013은 bubblewrap이 비특권 user·network namespace를 만들 수 있는 Linux 호스트가 필요하다. Ubuntu 23.10 이후는 기본으로 거절한다. 첫 단계가 그렇게 알려 주고, 고치는 법은 `docs/operations/ci-quality-gates.md`에 있다.
- `config/ci/product-gates.json`에 적은 제품 검사(`PRODUCT-GATE-NNN`)는 workflow의 `product_merge_gate` job에서 돌고, release 단계가 그 job을 기다린다.
workflow처럼 돌리려면 workflow의 환경을 먼저 준다. `CI=true`이면 실행기와 release 빌드가 CI 빌드 식별값을 요구한다. 테스트가 사본으로 만드는 빌드(fixture 빌드, 시각 골든 빌드, 브라우저 시험의 dev 서버)는 이 값과 상관없이 로컬 빌드로 돈다(`scripts/lib/build-environment.ts`의 `localBuildEnvironment`). 깨끗한 clone에서 돌린다. `ci:gate`는 게이트의 첫 실패 명령에서 멈춘다.
```bash
export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1 \
RELEASE_ID=local-ci-1 CI_RUNNER_IMAGE="local/runner@sha256:$(printf 'a%.0s' $(seq 64))"
```
Machine-readable evidence is written below `artifacts/`; generated evidence is
ignored by Git while `.gitkeep` files preserve the taxonomy.
Run the gates one at a time in a checkout: they and the evidence checks read
the fixed `dist/` and `artifacts/` paths. Two Playwright runs can share a
checkout when each has its own `TEST_RUN_ID`; its build, results and report go
below `.tmp/runs/<id>/`. The test servers always pick a free port. The
variables are listed in `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md`
(13.6).
- 기계가 읽는 증거는 `artifacts/` 아래에 쓴다. 생성된 증거는 git이 무시하고, `.gitkeep` 파일이 폴더 구조를 지킨다.
- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs/<id>/` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록은 설계서 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절에 있다.
Operational details are in `docs/operations/`, with incident procedures in
`docs/runbooks/`.
외부 증거가 필요한 게이트:
## Updating a copied project
- `review:a11y-manual`(release 게이트 FE-GATE-028)은 등록된 모든 라우트에 대해 사람이 서명한 키보드·포커스·스크린 리더 검토가 필요하다. 라우트마다 기록 하나를 `artifacts/tests/a11y-manual/<ROUTE_ID>.md`에 둔다. 라우트는 `ROUTE_REGISTRY`다. 등록된 라우트에 기록이 없으면 `verify:documentation`이 라우트 ID를 적고 실패한다. merge 게이트 FE-GATE-009는 `review:a11y-manual -- --format-only`만 돌린다. 모든 라우트 기록이 템플릿의 칸을 지키는지(검토했든 아직이든) 본다.
- `collect:web-vitals-evidence`는 검토한 최소 표본 기준과 28일치 production 데이터가 있기 전까지 `FAIL_UNVERIFIED`다.
- 운영 호스팅 확인(FE-GATE-019, production 단계)은 `HOSTING_BASE_URL`과 workflow의 `deployment` job이 배포한 승격 릴리스가 필요하다. 그 job은 프로젝트가 `config/ci/product-gates.json`에서 채우기 전까지 빈 자리다([`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)). 그때까지 결과는 `PASS`가 아니라 `UNVERIFIED`다. 다른 릴리스를 서빙하는 호스트, HTTP/2나 진입 압축이 없는 호스트는 실패한다.
Template versions are Git tags `vX.Y.Z`. [`CHANGELOG.md`](CHANGELOG.md) lists
the changes between tags, marks security fixes **[보안]** and contract changes
**[계약]** (backend, deployment, CI or feature code must change too), and names
the affected paths. Its unreleased section summarizes one sync range (the
section head names the base commit and the branch); take that range as a whole
and do its "먼저 할 일" (BREAKING) steps in order before running the gates.
운영 세부는 `docs/operations/`, 장애 절차는 `docs/runbooks/`에 있다.
Record where you started. Right after copying, commit a one-line
`.template-origin` file at the root of your project with the template tag (or
commit) you copied and the date, for example `v0.2.0 2026-09-26`.
## 새 서비스로 시작하기
Take a template fix with Git. `cherry-pick` works even when your repository
does not share the template's history, because it merges against the picked
commit's parent:
1. 복사한 바로 뒤에 프로젝트 루트에 한 줄짜리 `.template-origin` 파일을 커밋한다. 복사한 템플릿 태그(또는 커밋)와 날짜를 적는다. 예: `v0.2.0 2026-09-26`.
2. `package.json`의 `name`과 `PRODUCT.md`를 제품 것으로 바꾼다. `CLAUDE.md`는 자기 리뷰 기준으로 바꾼다.
3. 첫 기능은 `corepack pnpm create:feature <id>`로 만든다([`docs/manual/`](docs/manual/README.md)).
4. 아래 표의 파일을 지웠으면 merge 게이트를 돌린다(「검증」 절).
### 복사한 뒤 지워도 되는 것
템플릿을 만든 과정의 기록이다. 빌드와 게이트는 아래에 적은 파일 하나 말고는 이것들을 읽지 않는다(`tests/unit/deletable-history-documents.test.ts`가 확인한다).
| 경로 | 내용 |
| --- | --- |
| `docs/history/` | 끝난 작업의 계획서와 증거. 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록도 여기 있다 |
| `docs/reviews/` | 리뷰와 리뷰 가이드 포인터. `docs/reviews/adapters/`는 남긴다: `check:adapter-inventory`(FE-GATE-010)가 그 안의 `INVENTORY.md`를 읽고, 그 행이 옆의 adapter 리뷰로 링크하며, `docs/operations/adapter-remediation-ledger.md`가 그 리뷰를 인용한다 |
| `CLAUDE.md` | 템플릿 repo 자체의 리뷰 지침. 자기 것으로 바꾼다 |
| `PRODUCT.md` | 디자인 도구가 읽는 템플릿 자체의 제품 맥락(사용자, 목적, 원칙). 제품 것으로 바꾼다 |
기능은 이 목록에 없다. 기능 폴더만 지우면 테스트, 정책 항목, CI 스크립트가 남아 게이트가 실패한다.
- `corepack pnpm test:sample-removal -- --feature=<id>`가 repo 사본에서 그 기능을 지우고, 같이 지워야 하는 것을 모두 적는다(`scripts/test-sample-removal.ts` 머리 주석). 프로젝트에서 같은 것을 지우고 게이트를 돌린다.
- 프로젝트가 한동안 두는 샘플은 `scripts/lib/removable-template-features.ts`에 적을 수 있다. 그러면 드릴이 `--feature` 없이 지우고, 문서 검사는 그 기능의 `feature-module.ts`가 없어진 뒤 그 경로를 받아들인다.
### 원본 업데이트 반영
템플릿 버전은 Git 태그 `vX.Y.Z`다. [`CHANGELOG.md`](CHANGELOG.md)가 태그 사이의 변경을 적는다.
- 보안 수정은 **[보안]**, 계약 변경(백엔드·배포·CI·기능 코드도 바꿔야 함)은 **[계약]**으로 표시하고, 영향받는 경로를 적는다.
- 미출시 절은 동기화 범위 하나를 요약한다(절 머리에 기준 커밋과 브랜치가 있다). 그 범위를 통째로 받고, 게이트를 돌리기 전에 그 절의 "먼저 할 일"(BREAKING) 단계를 순서대로 한다.
템플릿 수정 하나는 Git으로 받는다. `cherry-pick`은 고른 커밋의 부모와 병합하므로 템플릿과 이력을 공유하지 않는 repo에서도 된다:
```bash
git remote add template <template repository URL>
@@ -394,34 +264,21 @@ git log --oneline <your origin>..template/main # what changed since you copied
git cherry-pick -x <commit> # one fix; -x records its origin
```
Take an unreleased range as a whole. A repository that shares the template's
history merges the range's branch. One that does not (it started from a copy
of the files) merges three-way against the range base, which leaves the files
both sides changed as conflicts; resolve them and commit:
미출시 범위는 통째로 받는다. 템플릿과 이력을 공유하는 repo는 그 범위의 브랜치를 병합한다. 공유하지 않는 repo(파일 사본에서 시작함)는 범위 기준점과 3-way 병합한다. 양쪽이 바꾼 파일은 충돌로 남으니 풀고 커밋한다:
```bash
git merge --no-ff template/<range branch> # shared history
git merge-recursive <range base> -- HEAD template/<range branch> # no shared history
```
Keep the base you synced from where your project records it: `.template-origin`
(below), or your own lock file (tech-log keeps it as `sourceRevision` in
`template.lock.json`). Move it to the range end once the range is in.
- 동기화한 기준점은 프로젝트가 적어 두는 곳에 둔다: `.template-origin`, 또는 자기 잠금 파일(tech-log는 `template.lock.json`의 `sourceRevision`). 범위를 다 받으면 그 끝으로 옮긴다.
- 파일이 너무 옮겨졌거나 갈라져서 깨끗하게 고를 수 없으면 diff로 읽고 손으로 적용한다: `git diff <commit>^ <commit> -- <paths from CHANGELOG>`.
- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 태그까지 따라잡았으면 `.template-origin`을 고친다. 받은 수정은 `git revert`로 되돌린다.
When the files have moved or diverged too far for a clean pick, read the
change as a diff and apply it by hand:
결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 그 커밋과 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다.
```bash
git diff <commit>^ <commit> -- <paths from CHANGELOG>
```
## 규칙과 기여
Afterwards run the local merge gates from "CI and evidence", apply the
backend or deployment change a **[계약]** row names, and update
`.template-origin` once you have caught up to a tag. `git revert` undoes a pick.
Defects: if a problem reproduces on an unmodified checkout of your
`.template-origin` commit, it is a template defect. Report it on the template
repository with that commit and the reproduction; the template maintainer
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
your changes to reproduce belongs to your project, and applying a template fix
to your copy is your project's job.
- 리뷰 기준과 이 repo의 리뷰 전제는 `CLAUDE.md`에 있다.
- 커밋 메시지와 PR 본문은 design-docs 저장소의 `conventions/commit-and-pr.md`를 따른다. 문서 규칙의 정본은 같은 저장소의 `conventions/docs-system.md`이고, 이 repo의 적용은 [`docs/README.md`](docs/README.md)에 있다.
- 코드나 규칙을 바꾸는 변경은 그것을 설명하는 살아 있는 문서를 같은 변경에서 고친다. 공개 계약을 바꾸면 `CHANGELOG.md`의 미출시 절에 적는다.
+144 -78
View File
@@ -1,113 +1,179 @@
# 문서 색인
# docs
`docs/`의 문서를 세 묶음으로 나눈다.
저장소의 문서는 이 폴더 아래에 있다(루트 `README.md`, `CHANGELOG.md` 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.
```text
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
```
- 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
- 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
규칙의 정본은 design-docs 저장소의 `conventions/docs-system.md`다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다.
파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
문서와 코드가 다르면 코드가 맞다.
## 1. 현재 계약
## 1. 문서 지도
처음 읽을 입구 문서 6개다.
- 표의 첫 칸이 폴더다(`docs/` 기준 경로).
- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
- 문서 검사의 `map`이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).
### 처음 읽을 문서
| 문서 | 정하는 것 |
|---|---|
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
| --- | --- |
| [`README.md`](../README.md) | 프로젝트 구조, 시작하기, 런타임 설정과 배포 변수, 기능 켜고 끄기와 지원 범위, 검증과 CI, 새 서비스로 시작하기, 원본 업데이트 반영 |
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
| [`manual/`](manual/README.md) | 새 기능을 더하는 순서와 판단 기준, `create:feature`, 완료 기준([`manual/reference/`](manual/reference/)) |
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
### 매뉴얼
- 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다
- 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
- 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와
셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의
경로와 링크는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다.
이 checkout 옆에 있는 짝 checkout의 git 기록을 읽고, 그 작업 트리와 HEAD는 보지 않는다. 짝
checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 것으로 출력과
`artifacts/quality/documentation-review.json`에 남긴다. repo 밖으로 나가는 링크가 짝 저장소를
가리키지 않으면(저장소 이름 오타 포함) 실패한다. `CHANGELOG.md`는
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
`scripts/verify-documentation-readiness.ts`다.
프로젝트가 지울 예정인 샘플 기능(목록은 `scripts/lib/removable-template-features.ts`, 템플릿은
비어 있다)의 경로와 script는 그 기능이 설치돼 있을 때(`src/features/<id>/feature-module.ts`가
있을 때) 검사하고, 지운 뒤에는 없어도 된다.
| 폴더 | 무엇 |
| --- | --- |
| `manual/` | 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. `manual/reference/`에 명령 인자, 전역 ID, 패턴, 오류 메시지, 완료 기준 |
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
### 현재 계약
지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.
| 폴더 | 무엇 |
| --- | --- |
| `architecture/` | 계층과 import 규칙(`architecture/layers.md`), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(`architecture/scale-architecture.md`, 코드 주석의 `scale-architecture.md §N`이 가리킨다), 짝 백엔드 계약(`architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절이 실행 규칙. 기준 커밋은 `config/contracts/backend-contract-pin.json`), 2026-07-18 도식 리뷰 기록의 사본(`architecture/review-evidence.md`, `architecture/review-ledger.json`) |
| `contracts/` | 계약 호환 규칙(읽는 쪽을 먼저 배포한다) |
| `security/` | 브라우저 보안 경계와 공급망 |
| `styling/` | 디자인 토큰 |
| `accessibility/` | 수동 접근성 검토 체크리스트. 라우트별 기록은 repo 루트의 `artifacts/tests/a11y-manual/`에 있다 |
| `testing/` | 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선 |
### 운영
| 폴더 | 무엇 |
| --- | --- |
| `operations/` | CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(`operations/adapter-remediation-ledger.md`) |
| `runbooks/` | 오류 code별 장애 대응 runbook(`FE-RB-00N`). 등록은 `config/runbooks/runbooks.json` |
### 결정 기록
| 폴더 | 무엇 |
| --- | --- |
| `adr/` | 결정 기록(VD). 번호는 옮기기 전과 같다(`VD-NN-<주제>.md`). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다 |
### 설계와 기록
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
| 폴더 | 무엇 |
| --- | --- |
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md`. 2026-11-08에 옛 superpowers 폴더의 specs와 `architecture/`의 목표 설계를 옮겼다 |
| `history/plans/` | 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(`SPEC.md`)과 작업 목록도 여기 있다 |
| `history/evidence/` | 작업 단계의 증거·체크포인트 |
| `reviews/` | 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다 |
- 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
- `history/`와 `reviews/`는 복사한 프로젝트가 지워도 된다(루트 `README.md` 「복사한 뒤 지워도 되는 것」). 예외는 `reviews/adapters/`다: `reviews/adapters/INVENTORY.md`는 `check:adapter-inventory`(FE-GATE-010)가 `src/adapters`와 대조하는 살아 있는 목록이다.
- `design/`과 `adr/`은 코드 주석이 근거로 가리키므로 지우지 않는다.
### 폴더 밖 문서
| 문서 | 무엇 |
| --- | --- |
| [`../README.md`](../README.md) | 루트 README. 6절의 필수 절을 가진다 |
| [`../CHANGELOG.md`](../CHANGELOG.md) | 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다 |
| [`../CLAUDE.md`](../CLAUDE.md) | 이 repo를 리뷰할 때의 기준 |
| [`../PRODUCT.md`](../PRODUCT.md) | 디자인 도구가 읽는 제품 맥락 |
| [`../src/adapters/browser-transfer/image-cdn/README.md`](../src/adapters/browser-transfer/image-cdn/README.md) | Image CDN adapter의 모듈 README |
### 게이트가 읽는 파일
지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
| --- | --- |
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
| repo 루트의 `artifacts/tests/a11y-manual/` 라우트별 기록 | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
| repo 루트의 라우트별 수동 접근성 기록(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`) | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
| `architecture/backend-api-and-server-state-contract.md` 6.1절 표 | `tests/unit/backend-contract-pin-document.test.ts` (FE-GATE-005) |
| `architecture/starter-experience.md`의 기능 폴더 밖 파일 표, `manual/03-outside-feature-folder.md` A절 | `tests/unit/feature-tracked-files.test.ts` (FE-GATE-005) |
| `manual/`의 표시한 코드 블록과 `manual/04-paired-backend-session.md` 3.2절 | `tests/unit/manual-code-blocks.test.ts`, `tests/unit/manual-paired-backend-settings.test.ts` (FE-GATE-005) |
## 2. 목표 설계
## 2. 문서 수명과 언어
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
| --- | --- | --- | --- | --- |
| 살아 있음 | README, `CLAUDE.md`, 매뉴얼(`manual/`), 현재 계약(`architecture/`, `contracts/`, `security/`, `styling/`, `accessibility/`, `testing/`), 운영(`operations/`, `runbooks/`), `reviews/adapters/INVENTORY.md`, 모듈 README, `CHANGELOG.md` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다(4절) |
| 결정 | 결정 기록(VD) | `adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다 |
| 기록 | 설계서, 계획서, 증거, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](design/2026-07-30-browser-data-capability-completion-ledger-design.md)
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](design/2026-07-26-frontend-platform-capability-review-design.md), [`architecture/frontend-platform-implementation-roadmap.md`](design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md), [`architecture/typescript-state-and-data-flow.md`](design/2026-07-26-typescript-state-and-data-flow-design.md), [`architecture/routing-pages-and-patterns.md`](design/2026-07-26-routing-pages-and-patterns-design.md)
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](design/2026-07-28-client-cache-and-storage-design.md), [`architecture/browser-file-and-origin-storage.md`](design/2026-07-27-browser-file-and-origin-storage-design.md), [`architecture/presigned-transfer-and-image-cdn.md`](design/2026-07-30-presigned-transfer-and-image-cdn-design.md), [`architecture/server-file-capability-infrastructure.md`](design/2026-07-28-server-file-capability-infrastructure-design.md)
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](design/2026-07-26-design-system-platform-design.md), [`testing/frontend-platform-testing-strategy.md`](design/2026-07-26-frontend-platform-testing-strategy-design.md)
- 결정 기록(ADR): [`architecture/decisions/`](adr/) `VD-*.md`
- 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
- 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
- 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
- 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
- `artifacts/tests/a11y-manual/`의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(`scripts/lib/manual-a11y-evidence.ts`). 문서 검사가 보지 않는다.
## 3. 작업 이력·리뷰
## 3. 기록 문서의 머리 블록
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
| [`reviews/`](reviews/) | 리뷰 결과. 리뷰 가이드와 실행 체크리스트는 2026-11-06에 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 두 개만 있다. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 |
| [`history/`](history/) | 끝난 작업의 계획서(`history/plans/`)와 증거(`history/evidence/`). 파일마다 맨 위에 머리 블록이 있다(아래 4절). 2026-11-07에 루트에서 옮겼다: `tasks/` → `history/plans/2026-09-25-review-fix-round/`, `.superpowers/sdd/2026-08-01-runtime-correctness-remediation/` → `history/evidence/2026-08-01-runtime-correctness-remediation/`. 그때의 기록 문서(`superpowers/plans/`, `reviews/2026-09-25-maturity-review/`, 루트 `SPEC.md`)는 옛 경로로 가리킨다. 기록이라 고치지 않는다 |
| [`../SPEC.md`](../SPEC.md) | 2026-09-25 리뷰 수정 라운드의 요구사항. 그 라운드는 0.2.0(`CHANGELOG.md`)으로 끝났다. 27~37줄 「공통 완료 기준」을 작업 매뉴얼로 옮긴 뒤 같은 라운드의 계획서 옆(`history/plans/2026-09-25-review-fix-round/`)으로 옮긴다 |
## 4. 기록 문서의 머리 블록
`history/` 아래 `.md` 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 쓴 때의 원문이다. 본문은
고치지 않고 블록의 칸만 고친다. 형식의 정본은 design-docs 저장소의
`conventions/docs-system.md` 4절이다.
`design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
```text
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 끝남
- 작성일: 2026-09-25
- 상태: 구현됨
- 작성일: 2026-08-01
- 요약: 한국어 한 문장
- 현재 정본: 지금 동작을 설명하는 문서나 코드의 경로. 없으면 「없음 — 이유」
- 현재 정본: `docs/architecture/layers.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
```
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `history/plans/` 계획서, `history/evidence/` 증거.
- 상태: 계획서는 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함, 증거는 보관.
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서, `history/evidence/` 증거. 결정 기록(`adr/`)의 둘째 줄은 `> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.
- 상태는 종류마다 고정 어휘다.
| 종류 | 상태 |
| --- | --- |
| 설계서 | 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 |
| 결정 기록 | 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 |
| 계획서 | 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 |
| 증거 | 보관 |
- 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
- 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
- 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).
- 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
- `.md`가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
## 4. 문서와 코드를 같은 변경에서 고친다
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: `git grep -n '<바꾼 이름>' -- '*.md'`.
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 `CHANGELOG.md`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
- 숫자·버전을 복사하지 않는다. 프레임워크 버전은 `package.json`과 `.nvmrc`, 게이트 목록은 `config/ci/gates.json`, recipe 목록은 `config/recipes/frontend-capability-recipes.json`, adapter 파일 목록은 `reviews/adapters/INVENTORY.md`를 가리킨다.
- 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고, 문서 검사의 `readme`가 그 목록(`scripts/lib/docs-system.ts`의 `README_SECTIONS`)을 본다.
## 5. 문서 검사
`verify:documentation`(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.
- pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 `tests/unit/documentation-readiness.test.ts`가 이 repo를 그대로 두고 `verify:documentation`을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(`config/ci/gates.json`의 `documentation_gate`).
| 검사 | 보는 것 |
| --- | --- |
| `language` | 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정) |
| `head` | 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지 |
| `document references` | 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다 |
| `number` | 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, `CHANGELOG.md`는 보지 않는다 |
| `map` | 이 README의 1절 지도가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
| `style` | 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, `> 이력` 블록은 보지 않는다 |
- 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 `src/` 폴더 설명(`architecture/layers.md` 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
- 규칙과 판정의 정본은 `scripts/lib/docs-system.ts`(검사 여섯)와 `scripts/verify-documentation-readiness.ts`(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 `check-docs.py`)를 같은 이름·문턱으로 옮긴 것이다.
- 검사 자신의 시험: `tests/unit/docs-system.test.ts`, `tests/unit/documentation-readiness.test.ts`.
- 예외 목록 `scripts/docs-system-exceptions.txt`는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 `scripts/lib/docs-system.ts`의 `FROZEN`에 지문이 있어야 하는데, `FROZEN`이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
- 복사한 프로젝트가 지운 기록(`history/`, `reviews/`)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
- 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.
@@ -1,42 +1,44 @@
# Frontend Application Foundation
# 프론트엔드 애플리케이션 기반(Frontend Application Foundation)
This repository is not treated as a minimal React project template and it is not
an independent general-purpose SDK. Its architectural role is:
이 repo를 최소한의 React 프로젝트 템플릿으로 보지 않는다. 독립된 범용 SDK도
아니다.
아키텍처에서 맡는 역할은 다음과 같다:
> Frontend Application Foundation = Starter / Composition Skeleton + Reusable Capability Platform
> Frontend Application Foundation = 시작 골격(Starter / Composition Skeleton) + 재사용 capability 플랫폼(Reusable Capability Platform)
The starter side owns bootstrap, routing, providers, project conventions and
the `create:feature` command that writes a feature; it ships no sample feature. The capability side owns reusable technical
problems such as HTTP execution, Server State, authentication boundaries,
IndexedDB/OPFS, Cache Storage, realtime, browser RPC, transfer and diagnostics.
시작 골격 쪽은 bootstrap, 라우팅, provider, 프로젝트 규약, feature를 만들어
주는 `create:feature` 명령을 맡는다. 예시 feature는 싣지 않는다. capability
쪽은 재사용할 기술 문제를 맡는다. HTTP 실행, Server State, 인증 경계,
IndexedDB/OPFS, Cache Storage, realtime, 브라우저 RPC, 전송(transfer), 진단
같은 것이다.
The cost of a sophisticated capability is acceptable only when product features
do not have to understand that internal sophistication.
정교한 capability의 비용은 제품 feature가 그 내부의 정교함을 몰라도 될 때만
받아들일 수 있다.
## Hybrid architecture
## 하이브리드 아키텍처
`src/` has nine top-level folders. The descriptions match the table in
[the layer contract](./layers.md), which also names every import rule.
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
표와 같다. 그 문서는 모든 import 규칙도 적는다.
Platform code is horizontal:
platform 코드는 가로(수평)로 놓인다:
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
- `src/application` — generic use cases, ports, policies and view-models
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
- `src/application` — 범용 use case, 포트, 정책, view-model
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
Ownership declarations group features into deployable units:
소유 선언이 feature를 배포 단위로 묶는다:
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
Product business code is vertical:
제품 비즈니스 코드는 세로(수직)로 놓인다:
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
Inside one feature:
feature 하나 안에는 다음이 있다:
- `features/<feature>/domain`
- `features/<feature>/application`
@@ -44,7 +46,7 @@ Inside one feature:
- `features/<feature>/adapters`
- `features/<feature>/presentation`
The dependency model is:
의존성 모델은 다음과 같다:
Domain / Use case
|
@@ -63,143 +65,144 @@ The dependency model is:
v
Browser / network / native API
A use case never imports a platform adapter. Generic binding happens in the
feature adapter/composition seam.
use case는 platform adapter를 절대 import하지 않는다. 범용 바인딩은 feature의
adapter·조립 이음매(seam)에서 일어난다.
## Capability-specific typed bindings
## capability별 타입 바인딩
Do not introduce one universal `Repository<TKey, TValue>` abstraction for HTTP,
storage, realtime and transfer. Their lifecycle and failure semantics differ.
HTTP, storage, realtime, transfer를 하나의 범용 `Repository<TKey, TValue>`
추상화로 묶지 않는다. 넷은 lifecycle과 실패의 의미가 서로 다르다.
A reusable capability boundary is composed from:
재사용 capability 경계는 다음으로 조립한다:
- generic input/output types,
- feature-owned mapper or codec,
- feature-selected policy,
- one capability-specific runtime.
- 범용 입력·출력 타입,
- feature가 소유한 mapper 또는 codec,
- feature가 고른 정책,
- capability 전용 runtime 하나.
The HTTP path is the first concrete example.
`src/adapters/http/feature-http-binding.ts` owns transport/outcome
normalization. A feature `create:feature` writes contributes only:
HTTP 경로가 첫 구체 예다.
`src/adapters/http/feature-http-binding.ts`가 전송과 결과의 정규화를 맡는다.
`create:feature`가 만든 feature가 내놓는 것은 다음뿐이다:
- operation ID,
- route ID,
- exact request input type,
- exact success value type,
- wire-to-domain mapper.
- 정확한 요청 입력 타입,
- 정확한 성공 값 타입,
- wire 형식을 domain으로 바꾸는 mapper.
The feature gateway therefore does not reimplement timeout, cancellation,
transport failure, authentication failure or contract-violation projection.
그래서 feature gateway는 timeout, 취소, 전송 실패, 인증 실패, contract 위반
투영을 다시 구현하지 않는다.
Storage, realtime and transfer may gain their own typed binders only after
actual feature repetition demonstrates the need. They must not be forced
through the HTTP abstraction.
storage, realtime, transfer는 실제 feature에서 반복이 생겨 필요가 드러난
뒤에야 자기 타입 바인더를 가질 수 있다. 이 셋을 HTTP 추상화에 억지로
끼우면 안 된다.
## Custom adapter escape hatch
## 직접 만드는 adapter라는 탈출구
A product feature uses a reusable capability when the capability preserves the
business requirement.
제품 feature는 재사용 capability가 비즈니스 요구를 지켜 줄 때 그 capability를
쓴다.
If a platform contract would require changing or weakening the business model,
the feature implements a custom outbound adapter behind the same application
port. The architecture boundary remains stable; platform reuse is optional.
platform contract 때문에 비즈니스 모델을 바꾸거나 약하게 해야 한다면, feature는
같은 application port 뒤에 직접 만든 outbound adapter를 구현한다. 아키텍처
경계는 그대로다. platform 재사용은 선택이다.
## Feature installation
## feature 설치
A feature owns its contract, runtime and adapter contributions.
feature는 자기 contract, runtime, adapter contribution을 소유한다.
Central installed catalogs are aggregation points only:
중앙의 설치 목록(catalog)은 모으는 지점일 뿐이다:
- `installed-product-manifest.ts`: which product features are compiled/selected
- `installed-feature-contracts.ts`: boot-time contract aggregation (routes,
route runtime contracts, invalidation) from the feature declarations
- `installed-feature-adapters.ts`: application-input loaders, one per active
feature, run when the router enters the feature's routes (15-01)
- `installed-contract-contributions.ts`: declared contract packages and the
registry the HTTP executor resolves against, filled as features load
- `installed-feature-runtime-registries.ts`: loads every runtime half and
composes the contract contributions, the FE-REG-API rows projected from
them and the FE-REG-SCHEMA registry; the platform overview page calls it
after it draws its title (1103/15-01), the boot never does
- `loaded-feature-runtimes.ts`: the same registries as module constants (top-
level await) for Node scripts, tests and registry governance; nothing under
`src` may import it (`boot-does-not-load-every-feature-runtime`)
- `installed-product-manifest.ts`: 어떤 제품 feature를 컴파일하고 고르는지
- `installed-feature-contracts.ts`: feature 선언에서 boot 시점 contract(라우트,
라우트 runtime contract, 무효화)를 모은다
- `installed-feature-adapters.ts`: 활성 feature마다 하나씩 있는
application-input loader. router가 그 feature의 라우트에 들어갈 때
실행된다(15-01)
- `installed-contract-contributions.ts`: 선언된 contract 패키지와, HTTP
executor가 해석할 때 쓰는 registry. feature가 로드될 때 채워진다
- `installed-feature-runtime-registries.ts`: 모든 runtime 쪽 절반을 불러와
contract contribution, 거기서 투영한 FE-REG-API 행, FE-REG-SCHEMA registry를
조립한다. platform 개요 페이지가 제목을 그린 뒤 이 파일을 부른다
(1103/15-01). boot는 절대 부르지 않는다
- `loaded-feature-runtimes.ts`: 같은 registry를 모듈 상수(top-level await)로
둔 것. Node 스크립트, 테스트, registry 관리(governance)가 쓴다. `src` 아래
어떤 코드도 이 파일을 import하면 안 된다
(`boot-does-not-load-every-feature-runtime`)
Feature-specific composition belongs under the feature itself. Central
catalogs must not grow feature-specific branching logic.
feature 전용 조립은 그 feature 아래에 둔다. 중앙 목록에 feature별 분기 로직을
늘리면 안 된다.
Adapter contributions declare the platform capabilities they consume through
`needs`. The generic contribution seam in
`src/features/feature-adapter-contribution.ts` derives the context from that
list, so an HTTP-only feature cannot reach IndexedDB and an IndexedDB-only
feature does not receive the HTTP executor. It also binds
`featureId -> ApplicationFeatureInputs[featureId]` at the contribution
definition site instead of recovering that relationship with a final catalog
cast.
adapter contribution은 자기가 쓰는 platform capability를 `needs`로 선언한다.
`src/features/feature-adapter-contribution.ts`의 범용 contribution 이음매가 그
목록에서 context를 만든다. 그래서 HTTP만 쓰는 feature는 IndexedDB에 닿지
못한다. IndexedDB만 쓰는 feature는 HTTP executor를 받지 않는다. 이 이음매는
`featureId -> ApplicationFeatureInputs[featureId]` 관계도 contribution을
정의하는 자리에서 묶는다. 마지막에 목록을 타입 캐스트해서 그 관계를 되찾지
않는다.
A contribution becomes composable only through
`defineFeatureAdapterContribution()`. That factory adds the private
contribution brand required by `composeFeatureAdapterInputs()`; a raw object
with the same visible fields is rejected by TypeScript and checked again at
runtime. The negative type fixture
`invalid-direct-feature-composition.ts` is part of FE-GATE-003 so this
authority cannot be bypassed by calling the composer directly.
contribution은 `defineFeatureAdapterContribution()`을 거쳐야만 조립할 수
있다. 이 factory는 `composeFeatureAdapterInputs()`가 요구하는 비공개
contribution brand를 붙인다. 겉으로 보이는 필드가 같은 날 객체는 TypeScript가
거부하고, runtime에서도 다시 검사한다. 음성 타입 fixture
`invalid-direct-feature-composition.ts`가 FE-GATE-003에 들어 있다. 그래서
composer를 직접 불러 이 권한을 우회할 수 없다.
For IndexedDB-backed features, `createIndexedDbRepositoryProvider()` is the
composition helper that maps feature-owned repository identities to typed
`IndexedDbRepositoryPort` instances. It does not create a universal storage
repository or move dataset/migration/lifecycle policy into the feature.
IndexedDB를 쓰는 feature에서는 `createIndexedDbRepositoryProvider()`가 조립
헬퍼다. 이 헬퍼는 feature가 소유한 repository 식별자를 타입이 붙은
`IndexedDbRepositoryPort` 인스턴스에 연결한다. 범용 storage repository를
만들지 않는다. dataset·migration·lifecycle 정책을 feature로 옮기지도 않는다.
The repository now has two executable contribution shapes:
지금 repo에는 실행 가능한 contribution 모양이 둘 있다:
- A feature `create:feature` writes: `needs: ["http", "telemetry"]`
- The Local Draft consumer: `needs: ["indexedDb"]`
- `create:feature`가 만드는 feature: `needs: ["http", "telemetry"]`
- Local Draft consumer: `needs: ["indexedDb"]`
Local Draft is a test fixture (`tests/fixtures/indexeddb-consumer`) used to
prove the second capability shape; it is not a feature of the product. Its
browser-capability test composes the feature over the real
`createIndexedDbRuntime` and native IndexedDB, proving that this seam is not
limited to an in-memory contract fixture.
Local Draft는 두 번째 capability 모양을 증명하는 테스트
fixture(`tests/fixtures/indexeddb-consumer`)다. 제품의 feature가 아니다. 그
browser-capability 테스트는 실제 `createIndexedDbRuntime`과 브라우저 자체
IndexedDB 위에서 feature를 조립한다. 이 이음매가 메모리 안 contract fixture에만
묶이지 않는다는 것을 이 테스트가 증명한다.
The bootstrap does not build `indexedDb`: IndexedDB is an opt-in reference
runtime (`productionComposition: false` in
`config/recipes/frontend-capability-recipes.json`). The composition example is
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`
(`createLocalDraftIndexedDbCapability`, exercised by
`tests/recipes/indexeddb-feature-capability.test.ts`). A product that installs a
feature with `needs: ["indexedDb"]` copies it and returns `indexedDb` from the
product-owned `src/bootstrap/product-composition.ts`. Until it does, the feature
capabilities in `src/bootstrap/runtime-adapters.ts` fail the app typecheck, and
`composeFeatureAdapterInputs()` rejects the composition with
`feature <id> needs indexedDb, which the host did not provide`.
bootstrap은 `indexedDb`를 만들지 않는다. IndexedDB는 골라야 켜지는(opt-in)
참조 runtime이다(`config/recipes/frontend-capability-recipes.json`의
`productionComposition: false`). 조립 예시는
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`다
(`createLocalDraftIndexedDbCapability`. 이 함수는
`tests/recipes/indexeddb-feature-capability.test.ts`가 실행해 본다).
`needs: ["indexedDb"]`인 feature를 설치하는 제품은 이 예시를 복사한다. 그리고
제품이 소유한 `src/bootstrap/product-composition.ts`에서 `indexedDb`를
돌려준다. 그 전까지는 `src/bootstrap/runtime-adapters.ts`의 feature
capability가 앱 타입체크에서 실패한다. 그리고 `composeFeatureAdapterInputs()`가
`feature <id> needs indexedDb, which the host did not provide`로 조립을
거부한다.
The same file is where a product adds any other capability and the
credential provider for a product auth profile. The capability's type goes in
the product-owned `src/features/product-capabilities.ts`
(`ProductFeaturePlatformCapabilities`, which `FeaturePlatformCapabilities`
extends), so every typecheck program that sees a feature sees it
(`tests/unit/product-extension-typecheck.test.ts`). The composition root keeps the order: scope fence, `ANONYMOUS`
profile, product provider, session, scope fence again
(`tests/unit/runtime-adapters-credential-order.test.ts`). A product that owns
the session itself (a BFF whose session is an httpOnly cookie) returns its
session owner from `composeProductSessionOwner` in the same file. It is asked
first, before `http` exists, only when `AUTH_MODE` is `external`, and it comes
before the host's `__CA_FRONTEND_AUTH_OWNER__`; `null` leaves the session to
that global. Its context (`src/bootstrap/product-session-owner-context.ts`)
carries a `fetch` with one deadline over the whole exchange, the page for a
sign-in redirect, the page's session storage for that redirect only, and
`readCookie`. Product auth profiles, runtime-config keys and the keys'
FE-REG-ENV rows go in `src/contracts/product-contracts.ts`; each joins the
template's registry under the same checks
제품이 다른 capability를 더하는 곳도 같은 파일이다. 제품 인증 profile의
credential provider를 더하는 곳도 이 파일이다. capability의 타입은 제품이
소유한 `src/features/product-capabilities.ts`에 둔다
(`ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities`가 이
타입을 확장한다). 그래서 feature를 보는 모든 타입체크 프로그램이 이 타입도
본다(`tests/unit/product-extension-typecheck.test.ts`). composition root는 다음
순서를 지킨다: scope fence, `ANONYMOUS` profile, 제품 provider, session, 다시
scope fence(`tests/unit/runtime-adapters-credential-order.test.ts`). session을
직접 소유하는 제품(session이 httpOnly 쿠키인 BFF)은 같은 파일의
`composeProductSessionOwner`에서 자기 session owner를 돌려준다. 이 함수는
`AUTH_MODE`가 `external`일 때만 불린다. 불릴 때는 `http`가 생기기 전에 가장
먼저 불리고, host의 `__CA_FRONTEND_AUTH_OWNER__`보다 앞선다. `null`을
돌려주면 session을 그 전역 값에 맡긴다. 이 함수의 context
(`src/bootstrap/product-session-owner-context.ts`)에는 다음이 들어 있다: 교환
전체에 deadline 하나를 거는 `fetch`, 로그인 redirect에 쓸 페이지, 그
redirect에만 쓰는 페이지의 session storage, `readCookie`. 제품 인증 profile,
runtime-config 키, 그 키의 FE-REG-ENV 행은 `src/contracts/product-contracts.ts`에
둔다. 각각 같은 검사를 거쳐 템플릿의 registry에 합류한다
(`tests/unit/product-composition-fixture.test.ts`).
## Presentation consumer surface
## presentation 소비 표면
`ApplicationProvider` remains the composition root for presentation, but new
consumers should not navigate a root `ApplicationApi` service locator.
`ApplicationProvider`는 계속 presentation의 composition root다. 하지만 새
소비 코드는 루트 `ApplicationApi` service locator를 뒤져서 기능을 찾아가면
안 된다.
Use the narrow hooks in
`src/presentation/providers/application-provider.tsx`:
`src/presentation/providers/application-provider.tsx`의 좁은 hook을 쓴다:
- `useApplicationSession`
- `useApplicationPreferences`
@@ -208,100 +211,96 @@ Use the narrow hooks in
- `useApplicationRecovery`
- `useApplicationFeature`
`useApplication` exists only as a deprecated compatibility escape hatch.
`useApplication`은 deprecated된 호환용 탈출구로만 남아 있다.
## Canonical imports
## 정식 import 경로
New feature code should use capability public entry points rather than deep
runtime modules. For HTTP the canonical path is
`src/adapters/http/index.ts`.
새 feature 코드는 깊은 runtime 모듈 대신 capability의 공개 진입점을 쓴다.
HTTP의 정식 경로는 `src/adapters/http/index.ts`다.
Compatibility re-exports may exist during a migration window, but they must be
marked as compatibility/deprecated paths and should not expand into an
unbounded public barrel.
옮기는 기간에는 호환용 재수출이 있을 수 있다. 하지만 그 경로에는 호환용·
deprecated 경로라는 표시를 해야 한다. 그리고 끝없이 커지는 공개 barrel로
늘어나면 안 된다.
## Policy ownership
## 정책 소유
Duplication is judged by ownership, not by syntax percentage.
중복은 문법이 겹치는 비율이 아니라 소유로 판단한다.
Small local validators can remain duplicated when locality improves auditing.
Business or concurrency policy must have one owner. For example the reference
create mutation keeps definition ID, idempotency requirement, duplicate policy
and invalidation policy in one feature-owned definition and binds only
`scope` and `execute` per usage site.
가까이 두는 편이 감사하기 쉬우면 작은 로컬 검증기는 중복으로 남겨도 된다.
비즈니스 정책이나 동시성 정책은 owner가 하나여야 한다. 예를 들어 참조 create
mutation은 정의 ID, 멱등성 요구, 중복 정책, 무효화 정책을 feature가 소유한
정의 하나에 둔다. 사용하는 자리마다 묶는 것은 `scope`와 `execute`뿐이다.
## Runtime decomposition rule
## runtime 분해 규칙
Large runtime files are not split by line count.
큰 runtime 파일을 줄 수로 나누지 않는다.
Extract a boundary when it has its own state machine, lifecycle owner, failure
model or compensation/recovery responsibility. Candidate seams include:
경계에 자기만의 상태 기계, lifecycle owner, 실패 모델, 보상·복구 책임이
있으면 그 경계를 떼어 낸다. 떼어 낼 후보 이음매는 다음과 같다:
- connection/open/upgrade lifecycle,
- transaction ownership,
- migration state machine,
- reconnect/backoff and heartbeat,
- subscription ownership,
- retry/deadline/cancellation ownership,
- settlement/reconciliation/cleanup.
- 연결·열기·업그레이드 lifecycle,
- 트랜잭션 소유,
- migration 상태 기계,
- 재연결·backoff와 heartbeat,
- 구독 소유,
- 재시도·deadline·취소 소유,
- 정산(settlement)·조정(reconciliation)·정리(cleanup).
A cohesive 2,000-line state machine can remain together. A 300-line file with
multiple lifecycle owners is a better extraction candidate.
응집된 2,000줄짜리 상태 기계는 한데 둬도 된다. lifecycle owner가 여럿인
300줄짜리 파일이 더 나은 분리 후보다.
### Current runtime boundary audit
### 지금 runtime 경계 점검
The current large-runtime inventory was reviewed using that rule.
지금 있는 큰 runtime 목록을 이 규칙으로 점검했다.
- IndexedDB remains large, but connection, transaction, migration, maintenance
and failure translation already have separate owners/modules.
- resumable upload already separates runtime policy, checkpoint persistence,
HTTP control-plane transport, part execution, cancellation and mutation
locking.
- realtime already separates reconnect policy/coordinator, event codec/consumer
and stream coordination.
- OPFS is separated into browser runtime, journal, byte-store, policy and worker
protocol/runtime responsibilities.
- HTTP V3 still owned retry eligibility/backoff inside the execution state
machine, so that responsibility moved to
`src/adapters/http/http-retry-lifecycle.ts`.
- IndexedDB는 여전히 크다. 하지만 연결, 트랜잭션, migration, 유지보수, 실패
변환은 이미 owner·모듈이 따로 있다.
- 이어 올리기(resumable upload)는 이미 runtime 정책, checkpoint 저장, HTTP
제어 평면 전송, 조각(part) 실행, 취소, mutation 잠금을 나눠 두었다.
- realtime은 이미 재연결 정책·조정자, 이벤트 codec·소비자, 스트림 조정을
나눠 두었다.
- OPFS는 브라우저 runtime, journal, byte-store, 정책, worker 프로토콜·runtime
책임으로 나뉘어 있다.
- HTTP V3는 재시도 가능 여부와 backoff를 실행 상태 기계 안에서 여전히 소유하고
있었다. 그래서 그 책임을 `src/adapters/http/http-retry-lifecycle.ts`로
옮겼다.
No other runtime is split merely because of its line count.
다른 runtime은 줄 수만 보고 나누지 않았다.
## Consumer quality metrics
## 소비 품질 지표
Before adding another abstraction, implement or model multiple real feature
uses and measure:
추상화를 하나 더 들이기 전에, 실제 feature 사용 사례 여럿을 구현하거나
모델링하고 다음을 잰다:
- feature-owned adapter LOC,
- repeated platform glue,
- number of platform-internal types exposed to the feature,
- central catalog edits,
- files changed for one normal query/command,
- whether native browser/network APIs leak into the feature.
- feature가 소유한 adapter LOC,
- 반복되는 platform 접착 코드(glue),
- feature에 드러나는 platform 내부 타입 수,
- 중앙 목록 수정 횟수,
- 평범한 query/command 하나에 바뀌는 파일 수,
- 브라우저·네트워크 기본 API가 feature로 새어 나오는지.
The target feature-development path is:
목표로 하는 feature 개발 경로는 다음과 같다:
1. domain type and invariant,
1. domain 타입과 불변식,
2. use case,
3. port,
4. transport/storage schema plus mapper/codec,
5. capability binding,
4. 전송·저장 schema와 mapper/codec,
5. capability 바인딩,
6. presentation controller/page.
A product feature should not need to know the retry scheduler, abort ownership,
effect-certainty machinery, transaction leases, reconnect coordinator, OPFS
journal or provider lifecycle.
제품 feature는 재시도 스케줄러, abort 소유, 효과 확실성(effect-certainty) 장치,
트랜잭션 lease, 재연결 조정자, OPFS journal, provider lifecycle을 몰라도 돼야
한다.
The executable REST and IndexedDB consumer baselines are recorded in
[`capability-consumer-experience.md`](./capability-consumer-experience.md).
Contract placement and the global-vs-owner-local audit are recorded in
[`contract-ownership.md`](./contract-ownership.md).
실행 가능한 REST·IndexedDB 소비 기준선은
[`capability-consumer-experience.md`](./capability-consumer-experience.md)에
적혀 있다. contract를 어디에 둘지와, 전역에 둘지 owner 가까이 둘지 점검한
결과는 [`contract-ownership.md`](./contract-ownership.md)에 적혀 있다.
## Verification paths
## 검증 경로
Product-development verification, capability verification and release assurance
are intentionally separate. See
[`docs/testing/taxonomy.md`](../testing/taxonomy.md).
제품 개발 검증, capability 검증, release 보증은 일부러 나눠 두었다.
[`docs/testing/taxonomy.md`](../testing/taxonomy.md)를 본다.
Host-level CI-runner tests belong to `tests/system`, not `tests/unit`.
Reusable capability consumer contracts belong to `tests/contract`.
host 수준 CI runner 테스트는 `tests/unit`이 아니라 `tests/system`에 둔다.
재사용 capability의 소비 contract는 `tests/contract`에 둔다.
+112 -109
View File
@@ -1,119 +1,120 @@
# Clean Architecture layer contract
# Clean Architecture 계층 계약
Dependencies point inward: `presentation -> application -> contracts ->
platform`. Concrete adapters implement application-owned ports and are
assembled only in `src/bootstrap`.
의존성은 안쪽을 향한다: `presentation -> application -> contracts ->
platform`. 구체 adapter는 application이 소유한 port를 구현한다. 구체
adapter는 `src/bootstrap`에서만 조립된다.
## Top-level folders
## 최상위 폴더
`src/` has these nine folders and no others:
`src/`에는 아래 아홉 폴더만 있다:
| Folder | Owns |
| 폴더 | 맡는 것 |
| --- | --- |
| `src/bootstrap` | the composition root: runtime configuration, concrete adapter construction and the React mount |
| `src/apps` | deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces |
| `src/contexts` | bounded contexts: each `context-module.ts` declares its app, route root and feature budget |
| `src/features` | removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`) |
| `src/presentation` | generic UI and the inbound adapter: routes, layouts, the design system, pages and providers |
| `src/adapters` | reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more |
| `src/application` | generic use cases, ports, policies and view-models |
| `src/contracts` | shared vocabulary and registries read by several layers, the workers and the build and release scripts |
| `src/platform` | product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence |
| `src/bootstrap` | 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트 |
| `src/apps` | 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다 |
| `src/contexts` | bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다 |
| `src/features` | 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`) |
| `src/presentation` | 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider |
| `src/adapters` | application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등 |
| `src/application` | 범용 use case, 포트, 정책, view-model |
| `src/contracts` | 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry |
| `src/platform` | 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성 |
Domain code lives inside a feature (`src/features/<id>/domain`). There is no
top-level domain folder. If a project adds one, `domain-is-framework-neutral`
and `concrete-adapters-compose-only-in-bootstrap` already cover it.
domain 코드는 feature 안(`src/features/<id>/domain`)에 있다. 최상위 domain
폴더는 없다. 프로젝트가 그런 폴더를 더해도 `domain-is-framework-neutral`과
`concrete-adapters-compose-only-in-bootstrap`이 이미 그 폴더를 다룬다.
`src/adapters/platform` is the adapter kernel (below). It is not
`src/platform`.
`src/adapters/platform`은 adapter kernel(아래 절)이다. `src/platform`과는
다른 폴더다.
Where a shared type or primitive goes is decided in
[contract ownership](./contract-ownership.md).
공용 타입이나 기본 요소를 어디에 둘지는
[contract 소유권](./contract-ownership.md)에서 정한다.
## Rules
## 규칙
Each row is one `forbidden` rule in `.dependency-cruiser.json`, by its `name`.
"Forbids" lists what code under "Applies to" must not import.
각 행은 `.dependency-cruiser.json`의 `forbidden` 규칙 하나이고, 그 규칙의
`name`으로 적는다. 「금지」 칸은 「적용 대상」 칸의 코드가 import하면 안 되는
것이다.
| Rule | Applies to | Forbids |
| 규칙 | 적용 대상 | 금지 |
| --- | --- | --- |
| `domain-is-framework-neutral` | a top-level domain folder (none today) | application, presentation, adapters, bootstrap, React, TanStack |
| `domain-is-framework-neutral` | 최상위 domain 폴더(지금은 없다) | application, presentation, adapters, bootstrap, React, TanStack |
| `application-does-not-know-concrete-runtime` | `src/application` | presentation, adapters, bootstrap, React, TanStack |
| `presentation-does-not-know-adapters` | `src/presentation`, except `adapters/query` | adapters, bootstrap, TanStack |
| `page-templates-own-layout-only` | `src/presentation/templates` | application, adapters, bootstrap, the presentation query adapter, TanStack. Templates take data and actions as props |
| `icon-vendor-is-facade-only` | all of `src`, except the lucide vendor facade | `lucide-react` |
| `zod-is-reached-through-contracts-zod` | all of `src`, except `src/contracts/zod.ts` | `zod` and its subpaths (`zod/v4`) |
| `design-system-is-reached-through-its-index` | code outside the design system and its named facades | design-system files other than its `index.ts` |
| `presentation-does-not-know-adapters` | `src/presentation`. 단 `adapters/query`는 제외 | adapters, bootstrap, TanStack |
| `page-templates-own-layout-only` | `src/presentation/templates` | application, adapters, bootstrap, presentation query adapter, TanStack. template은 데이터와 action을 props로 받는다 |
| `icon-vendor-is-facade-only` | `src` 전체. 단 lucide vendor facade는 제외 | `lucide-react` |
| `zod-is-reached-through-contracts-zod` | `src` 전체. 단 `src/contracts/zod.ts`는 제외 | `zod`와 그 하위 경로(`zod/v4`) |
| `design-system-is-reached-through-its-index` | 디자인 시스템과 이름이 정해진 그 facade 밖의 코드 | 디자인 시스템의 `index.ts`가 아닌 디자인 시스템 파일 |
| `adapters-do-not-know-presentation` | `src/adapters` | presentation, bootstrap |
| `feature-domain-is-framework-neutral` | `src/features/<id>/domain` | application, presentation, adapters, bootstrap, any feature's application, adapters and presentation, React, TanStack |
| `feature-application-does-not-know-runtime` | `src/features/<id>/application` | presentation, adapters, bootstrap, any feature's adapters and presentation, React, TanStack |
| `feature-presentation-does-not-know-outbound-adapters` | `src/features/<id>/presentation` | adapters, bootstrap, any feature's adapters, TanStack |
| `feature-adapters-do-not-know-presentation` | `src/features/<id>/adapters` | presentation, bootstrap, any feature's presentation |
| `feature-domain-is-framework-neutral` | `src/features/<id>/domain` | application, presentation, adapters, bootstrap, 모든 feature의 application·adapters·presentation, React, TanStack |
| `feature-application-does-not-know-runtime` | `src/features/<id>/application` | presentation, adapters, bootstrap, 모든 feature의 adapters·presentation, React, TanStack |
| `feature-presentation-does-not-know-outbound-adapters` | `src/features/<id>/presentation` | adapters, bootstrap, 모든 feature의 adapters, TanStack |
| `feature-adapters-do-not-know-presentation` | `src/features/<id>/adapters` | presentation, bootstrap, 모든 feature의 presentation |
| `concrete-adapters-compose-only-in-bootstrap` | `src/application`, `src/presentation`, `src/contracts` | `src/adapters` |
| `external-contract-package-single-import-path` | all of `src`, except `src/features/<id>/contracts/*-contract-contribution.ts` | the generated `@org-contracts/*` service packages |
| `presentation-does-not-fetch-directly` | generic and feature presentation | the HTTP, realtime, service-worker, web-worker and storage adapters |
| `unselected-realtime-runtime-is-not-composed` | `src/bootstrap`, `src/features/installed-feature-*` | the realtime and Web Push adapters, which the template does not select |
| `generic-worker-has-no-network-or-credentials` | `src/adapters/web-worker` | the HTTP, realtime, auth and Web Push adapters |
| `external-contract-package-single-import-path` | `src` 전체. 단 `src/features/<id>/contracts/*-contract-contribution.ts`는 제외 | 생성된 `@org-contracts/*` 서비스 패키지 |
| `presentation-does-not-fetch-directly` | 범용 presentation과 feature presentation | HTTP, realtime, service-worker, web-worker, storage adapter |
| `unselected-realtime-runtime-is-not-composed` | `src/bootstrap`, `src/features/installed-feature-*` | 템플릿이 고르지 않은 realtime adapter와 Web Push adapter |
| `generic-worker-has-no-network-or-credentials` | `src/adapters/web-worker` | HTTP, realtime, auth, Web Push adapter |
| `service-worker-entry-is-not-page-code` | `src/adapters/service-worker` | presentation, bootstrap, React, TanStack |
| `contracts-do-not-know-application` | `src/contracts` | application, features. Contracts is the lower package and owns the vocabulary both read |
| `contracts-do-not-know-application` | `src/contracts` | application, features. contracts가 아래쪽 패키지이고, 둘이 함께 읽는 어휘를 소유한다 |
| `contracts-do-not-know-presentation-or-bootstrap` | `src/contracts` | presentation, bootstrap |
| `generic-presentation-does-not-compose-the-product` | `src/presentation`, except the files the rule lists | the installed-feature registries. Which features exist is a product decision owned by `src/bootstrap` |
| `boot-does-not-load-every-feature-runtime` | all of `src`, except the module itself | `src/features/loaded-feature-runtimes.ts` |
| `adapters-do-not-know-other-concrete-adapters` | each adapter group | another adapter group, except the adapter kernel |
| `adapter-groups-are-reached-through-their-barrel` | code outside `src/adapters` | adapter files other than a group's `index.ts` and the `storage/indexeddb` and `storage/opfs` sub-barrels |
| `features-do-not-import-other-features` | each feature | another feature |
| `contexts-do-not-import-other-contexts` | each context | another context |
| `feature-and-app-roots-do-not-reach-adapters` | every file in `src/features` outside a feature's `adapters/` folder (the root files and any folder that is not a layer, such as `support/`), `src/contexts`, `src/apps`, except the type-only `src/features/feature-adapter-contribution.ts` | `src/adapters` |
| `presentation-does-not-import-apps-or-contexts` | generic and feature presentation, except `src/presentation/routes/app-router.tsx`, which mounts the app's route tree | `src/apps`, `src/contexts` |
| `observability-vendors-live-behind-adapters` | code outside `src/adapters` | vendor telemetry SDKs |
| `platform-kernel-is-product-neutral` | `src/platform`, except `routing/`, which reads app descriptors by type | features, contexts, apps, adapters, bootstrap, presentation, application |
| `no-circular-dependencies` | all of `src` | import cycles |
| `generic-presentation-does-not-compose-the-product` | `src/presentation`. 단 규칙에 적힌 파일은 제외 | 설치된 feature registry. 어떤 feature가 있는지는 제품 결정이고 `src/bootstrap`이 소유한다 |
| `boot-does-not-load-every-feature-runtime` | `src` 전체. 단 그 모듈 자신은 제외 | `src/features/loaded-feature-runtimes.ts` |
| `adapters-do-not-know-other-concrete-adapters` | 각 adapter 그룹 | 다른 adapter 그룹. 단 adapter kernel은 제외 |
| `adapter-groups-are-reached-through-their-barrel` | `src/adapters` 밖의 코드 | 그룹의 `index.ts`와 `storage/indexeddb`·`storage/opfs` 하위 barrel이 아닌 adapter 파일 |
| `features-do-not-import-other-features` | 각 feature | 다른 feature |
| `contexts-do-not-import-other-contexts` | 각 context | 다른 context |
| `feature-and-app-roots-do-not-reach-adapters` | `src/features` 안에서 feature의 `adapters/` 폴더 밖에 있는 모든 파일(루트 파일과, `support/`처럼 계층이 아닌 모든 폴더), `src/contexts`, `src/apps`. 단 타입 전용인 `src/features/feature-adapter-contribution.ts`는 제외 | `src/adapters` |
| `presentation-does-not-import-apps-or-contexts` | 범용 presentation과 feature presentation. 단 앱의 라우트 트리를 마운트하는 `src/presentation/routes/app-router.tsx`는 제외 | `src/apps`, `src/contexts` |
| `observability-vendors-live-behind-adapters` | `src/adapters` 밖의 코드 | vendor telemetry SDK |
| `platform-kernel-is-product-neutral` | `src/platform`. 단 app descriptor를 타입으로 읽는 `routing/`은 제외 | features, contexts, apps, adapters, bootstrap, presentation, application |
| `no-circular-dependencies` | `src` 전체 | import 순환 |
`feature-and-app-roots-do-not-reach-adapters` exists because the graph checks
one edge at a time. Presentation may import those files, so a re-export of an
adapter there would carry the adapter into presentation with every other rule
passing.
`feature-and-app-roots-do-not-reach-adapters`가 있는 이유는 그래프가 간선을
하나씩만 검사하기 때문이다. presentation은 그 파일들을 import할 수 있다.
그래서 그 파일에서 adapter를 재수출하면, 다른 규칙이 모두 통과한 채로
adapter가 presentation까지 들어온다.
## The adapter kernel
## adapter kernel
`adapters-do-not-know-other-concrete-adapters` excludes the adapter kernel,
which is shared on purpose and is the only adapter code an adapter may reach
across a group for:
`adapters-do-not-know-other-concrete-adapters`는 adapter kernel을 예외로
둔다. kernel은 일부러 공유하는 코드다. adapter가 그룹을 넘어 가져다 쓸 수
있는 adapter 코드는 kernel뿐이다:
- `src/adapters/platform/**` — mechanisms more than one adapter group shares:
the system clock, the shared abort primitive, the bounded-capacity guard,
the IndexedDB connection and transaction helpers, `Retry-After` parsing and
the JSON member scanner. Two bootstrap-only platform services live there
too: the browser lifecycle runtime and the mutation intent factory (no
adapter imports them). A kernel file owns mechanics only, never names,
schemas, failure codes or observation shapes; the full list of what it must
never own is at the top of `indexeddb-connection.ts`
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
failure constructors
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
invalidation transport and its types. Any adapter may import it; today
`query-cache` does
- `src/adapters/platform/**` — 여러 adapter 그룹이 함께 쓰는 동작 장치:
시스템 시계, 공용 abort 기본 요소, 용량 상한 가드, IndexedDB 연결·트랜잭션
헬퍼, `Retry-After` 파싱, JSON 멤버 스캐너. bootstrap만 쓰는 platform
서비스 두 개도 여기 있다: 브라우저 lifecycle runtime과 mutation intent
factory다(adapter는 이 둘을 import하지 않는다). kernel 파일은 동작 방식만
소유한다. 이름, schema, 실패 코드, 관측 모양은 절대 소유하지 않는다.
kernel이 절대 소유하면 안 되는 것의 전체 목록은 `indexeddb-connection.ts`
맨 위에 있다
- `src/adapters/browser-file-storage/result.ts` — 브라우저 데이터의 결과 값과
실패 값을 만드는 생성 함수
- `src/adapters/cross-context-invalidation/index.ts` — context 사이 무효화
(invalidation) 전송과 그 타입. 어떤 adapter든 import할 수 있다. 지금은
`query-cache`가 import한다
`check:architecture` enforces every rule above, including the kernel carve-out.
`verify:documentation` fails when a rule name or a top-level `src` folder is
missing from this page, when `README.md`, `overview.md` or
`frontend-application-foundation.md` describe a folder differently from the
folder table, and when any of them names a top-level `src` folder that does not
exist. Neither checks that a row describes its rule correctly.
`check:architecture`는 위 규칙을 모두 강제한다. kernel 예외도 포함한다.
`verify:documentation`은 다음 경우에 실패한다. 규칙 이름이나 최상위 `src`
폴더가 이 문서에서 빠졌을 때다. `README.md`, `overview.md`,
`frontend-application-foundation.md`가 폴더를 폴더 표와 다르게 설명할 때다.
그리고 그중 어느 문서든 없는 최상위 `src` 폴더를 적을 때다. 두 검사 모두 각
행이 규칙을 맞게 설명하는지는 보지 않는다.
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
exempted path in `pathNot`, and the reason, owner and revisit condition in
`comment` (review 12-07). Besides the kernel, the exceptions are:
모든 예외는 규칙 자체(`.dependency-cruiser.json`)에 적는다. 예외 경로는
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 12-07).
kernel 말고 예외는 다음과 같다:
- the generic presentation modules that read the installed registries today
(`generic-presentation-does-not-compose-the-product`). The list names exact
files, so a new module that reads a registry fails the gate
- `src/presentation/adapters/query`, the TanStack Query binding
- 지금 설치된 registry를 읽는 범용 presentation 모듈
(`generic-presentation-does-not-compose-the-product`). 목록은 파일을 정확히
적는다. 그래서 registry를 읽는 새 모듈은 gate에서 실패한다
- TanStack Query 바인딩인 `src/presentation/adapters/query`
(`presentation-does-not-know-adapters`)
- `src/presentation/routes/app-router.tsx` importing the app
- 앱을 import하는 `src/presentation/routes/app-router.tsx`
(`presentation-does-not-import-apps-or-contexts`)
- the design-system facades (`design-system-is-reached-through-its-index`)
- `src/platform/routing` reading deployable-app types
- 디자인 시스템 facade(`design-system-is-reached-through-its-index`)
- 배포 단위 앱 타입을 읽는 `src/platform/routing`
(`platform-kernel-is-product-neutral`)
## 어댑터 그룹의 공개 경계
@@ -151,19 +152,20 @@ realm 파일만 빼는 구조라, 배럴이 그 파일을 다시 끌어들이면
`document`를 찾지 못한다. 배럴의 타입 커버리지는 `tsconfig.app.json`이
담당하고, 워커 진입점은 배럴을 쓰지 않는다.
`bootstrap` contains composition only. Business rules and page-specific
orchestration belong to `src/application` or to a feature's domain and
application.
`bootstrap`에는 조립만 있다. 비즈니스 규칙과 페이지별 흐름 조정
(orchestration)은 `src/application`이나 feature의 domain·application에 둔다.
The [ports, adapters, and feature-boundary contract](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
explains how `presentation` acts as the inbound adapter and how feature
application APIs augment the generic typed input registry. Concrete output
ports are composed in bootstrap and stay hidden behind the application facade.
Project-selected capabilities still implement the same output boundaries.
[port, adapter, feature 경계 계약](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)은
두 가지를 설명한다. 하나는 `presentation`이 inbound adapter로 동작하는
방식이다. 다른 하나는 feature application API가 타입이 붙은 범용 입력
registry를 확장(augment)하는 방식이다. 구체 output port는 bootstrap에서
조립되고 application facade 뒤에 숨는다. 프로젝트가 고른 capability도 같은
output 경계를 구현한다.
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
parse TypeScript 7 and checked zero modules (review 12-05):
`check:architecture`는 TypeScript를 이해하는 아래 그래프를 출력한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser를 돌리지는 않는다.
dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도 검사하지
못했다(리뷰 12-05):
```json
{
@@ -181,11 +183,12 @@ parse TypeScript 7 and checked zero modules (review 12-05):
}
```
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
source imports, and fails closed on JavaScript-family source/specifiers,
unsupported rule shapes, unresolved imports, parse failures, error-severity
layer violations, or cycles. Regression fixtures prove the allowed resolver
path and each rejection class.
그래프는 TypeScript와 TSX를 읽는다. static, dynamic, type, CommonJS, JSDoc
import 참조를 모두 포함한다. `import.meta.glob`은 파싱 실패로 처리한다.
모듈 이름을 적지 않고 모듈을 불러오므로 어떤 간선 규칙도 그 모듈을 볼 수
없기 때문이다(리뷰 12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
적용한다. 로컬 소스 import에는 TypeScript 확장자를 명시하도록 요구한다. 다음
중 하나라도 있으면 통과시키지 않고 실패한다(fail closed): JavaScript 계열
소스·specifier, 지원하지 않는 규칙 모양, 해석되지 않은 import, 파싱 실패,
error 심각도의 계층 위반, 순환. 회귀 fixture가 허용되는 resolver 경로와 거부
종류 하나하나를 증명한다.
+60 -63
View File
@@ -1,24 +1,24 @@
# Architecture overview
# 아키텍처 개요
This Mermaid view is a repository-local implementation projection. The
`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named
in `review-ledger.json`, not automatically to edits in this file.
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
`PASS_SCOPED` 리뷰 증거는 `review-ledger.json`이 가리키는 정본 draw.io
도식에 적용된다. 이 파일을 고친 내용에 저절로 적용되지는 않는다.
`src/` has nine top-level folders. The descriptions match the table in
[the layer contract](./layers.md), which also names every import rule:
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
표와 같다. 그 문서는 모든 import 규칙도 적는다:
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
- `src/application` — generic use cases, ports, policies and view-models
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
- `src/application` — 범용 use case, 포트, 정책, view-model
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
Arrows point from the importing folder to the imported one. Every folder may
also import `contracts` and `platform`; only the main path is drawn.
화살표는 import하는 폴더에서 import되는 폴더로 향한다. 모든 폴더는
`contracts`와 `platform`도 import할 수 있다. 그림에는 주 경로만 그렸다.
```mermaid
flowchart LR
@@ -37,19 +37,18 @@ flowchart LR
Contracts --> Platform[platform]
```
The enforced dependency rule points inward: presentation calls application use
cases, adapters implement application ports, and only the composition root
selects concrete adapters. Domain code lives inside each feature. Contract
registries are the named source for routes,
API operations, environment values, storage keys, errors, queries, telemetry,
and release tokens. Installed feature contributions extend those registries
without making the generic application or router import a concrete feature
implementation.
강제되는 의존성 규칙은 안쪽을 향한다. presentation은 application use case를
부른다. adapter는 application port를 구현한다. 구체 adapter는 composition
root만 고른다. domain 코드는 각 feature 안에 있다. contract registry는
라우트, API operation, 환경 값, 저장소 키, 오류, query, telemetry, release
토큰의 이름을 정하는 출처다. 설치된 feature contribution이 이 registry를
확장한다. 그래도 범용 application이나 router가 구체 feature 구현을
import하게 되지는 않는다.
In ports-and-adapters terms, `presentation` is the current inbound adapter and
`adapters` contains the current outbound implementations. The production
composition exposes an application input API to React while keeping concrete
output ports inside application closures:
ports-and-adapters 용어로 말하면 `presentation`이 지금의 inbound adapter이고,
`adapters`에 지금의 outbound 구현이 있다. 운영 조립(production composition)은
React에 application input API를 내보인다. 구체 output port는 application
closure 안에 둔다:
```mermaid
flowchart LR
@@ -62,39 +61,37 @@ flowchart LR
Bootstrap2 -. selects and injects .-> Outbound
```
The executable route tree is mounted only after runtime configuration and
release-manifest coherence pass. `ApplicationProvider` receives the composed
application API; concrete session, storage, telemetry, diagnostics, and release
ports are not returned to feature pages. TanStack Query is isolated behind the
presentation query adapter, while its provider remains React infrastructure.
The module-augmented feature registry gives each installed feature a closed ID
and exact input type.
실행할 라우트 트리는 runtime 설정 검사와 release manifest 정합성 검사가
통과한 뒤에만 마운트된다. `ApplicationProvider`는 조립된 application API를
받는다. 구체 session·storage·telemetry·진단·release port는 feature 페이지에
돌려주지 않는다. TanStack Query는 presentation query adapter 뒤에 격리된다.
다만 그 provider는 React 인프라로 남는다. module augmentation으로 확장한
feature registry가 설치된 feature마다 닫힌 ID와 정확한 입력 타입을 준다.
Route contracts/codecs, the route-input provider, and lazy runtime modules are
separate modules so feature pages do not import the router that loads them.
Expected application failures use the shared `Result`/`AppFailure` contract.
The architecture gate analyzes TS/TSX imports with its own graph (the rules
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
JavaScript-family files, and fails on unresolved imports, parse failures,
forbidden layer edges, or cycles. The remaining project-owned work includes
selecting and verifying real hosting, identity, telemetry, vulnerability and
signing providers, plus backend/provider/browser/operations evidence for each
selected optional capability; the repository does not fabricate that evidence.
Use the following
documents for implementation details and project integration work:
라우트 contract·codec, route-input provider, lazy runtime 모듈은 서로 다른
모듈이다. 그래서 feature 페이지는 자신을 불러오는 router를 import하지 않는다.
예상된 application 실패는 공용 `Result`/`AppFailure` contract를 쓴다.
architecture gate는 자체 그래프로 TS/TSX import를 분석한다(규칙은
`.dependency-cruiser.json`에 있다. dependency-cruiser 자체는 TypeScript 7을
파싱하지 못해 돌리지 않는다). gate는 로컬 JavaScript 계열 specifier와 실행
가능한 JavaScript 계열 파일을 거부한다. 해석되지 않은 import, 파싱 실패,
금지된 계층 간선, 순환이 있으면 실패한다. 프로젝트가 맡을 일이 남아 있다.
실제 hosting, identity, telemetry, 취약점 점검, 서명 provider를 고르고
검증하는 일이다. 그리고 고른 선택 capability마다 백엔드·provider·브라우저·운영
증거를 갖추는 일이다. 이 repo는 그 증거를 지어내지 않는다. 구현 세부와
프로젝트 통합 작업은 아래 문서를 본다:
- [Frontend platform capability review](../design/2026-07-26-frontend-platform-capability-review-design.md)
- [Frontend ports, adapters, and boundaries](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
- [API contract, Schema, Mapper, and Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
- [Protobuf browser transports and REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
- [Backend API and Server State handoff contract](./backend-api-and-server-state-contract.md)
- [TypeScript, state, and data flow](../design/2026-07-26-typescript-state-and-data-flow-design.md)
- [Routing, pages, and patterns](../design/2026-07-26-routing-pages-and-patterns-design.md)
- [Browser data capability completion ledger](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
- [Browser file and origin storage](../design/2026-07-27-browser-file-and-origin-storage-design.md)
- [Client cache and storage](../design/2026-07-28-client-cache-and-storage-design.md)
- [Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
- [Presigned transfer and Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
- [Server file capability infrastructure](../design/2026-07-28-server-file-capability-infrastructure-design.md)
- [Frontend platform implementation roadmap](../design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
- [프론트엔드 platform capability 리뷰](../design/2026-07-26-frontend-platform-capability-review-design.md)
- [프론트엔드 port, adapter, 경계](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
- [API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
- [Protobuf 브라우저 전송과 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
- [백엔드 API와 Server State 인계 계약](./backend-api-and-server-state-contract.md)
- [TypeScript, 상태, 데이터 흐름](../design/2026-07-26-typescript-state-and-data-flow-design.md)
- [라우팅, 페이지, 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)
- [브라우저 데이터 capability 완료 장부(ledger)](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
- [브라우저 파일과 origin 저장소](../design/2026-07-27-browser-file-and-origin-storage-design.md)
- [클라이언트 캐시와 저장소](../design/2026-07-28-client-cache-and-storage-design.md)
- [Realtime 이벤트, Web Push, 상한을 둔 polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
- [Presigned 전송과 Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
- [서버 파일 capability 인프라](../design/2026-07-28-server-file-capability-infrastructure-design.md)
- [프론트엔드 platform 구현 로드맵](../design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
+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");
+14 -2
View File
@@ -4,7 +4,7 @@ import path from "node:path";
import { describe, expect, it } from "vitest";
/**
* README.md, "Files you can delete after copying", tells a new project that
* README.md, 「복사한 뒤 지워도 되는 것」, tells a new project that
* the build and the gates read none of the history documents except
* `docs/reviews/adapters/INVENTORY.md`. The removal fixtures rely on the same
* promise: they do not copy `docs/`. A test that opens a review document broke
@@ -57,9 +57,21 @@ async function codeFiles(directory: string): Promise<string[]> {
return files.flat();
}
/**
* The document checker (docs/README.md 「5. 문서 검사」) names the record
* folders to read the head block of whatever records are there and nothing
* else of them. A copy that deleted them passes it ("passes a copy that
* deleted its history" in its test), so it is not a reader this promise is
* about.
*/
const RECORD_FOLDER_CHECKERS: ReadonlySet<string> = new Set([
"scripts/lib/docs-system.ts",
"tests/unit/docs-system.test.ts",
]);
async function linesMatching(patterns: readonly RegExp[]): Promise<string[]> {
const files = [
...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat(),
...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat().filter((file) => !RECORD_FOLDER_CHECKERS.has(file)),
...ROOT_FILES,
];
const matches: string[] = [];
+331
View File
@@ -0,0 +1,331 @@
import { createHash } from "node:crypto";
import { describe, expect, it } from "vitest";
import {
type DocsDocument,
type DocsFacts,
type DocsSystemCheck,
HEAD_END,
HEAD_START,
isEnglish,
requiredFolders,
runDocsSystemChecks,
} from "../../scripts/lib/docs-system.ts";
/**
* The checker's own test (docs-system.md 7: a broken input fails, and each
* condition of a verdict has an input that only it catches). Inputs are in
* memory; verify:documentation runs the same checks on this repository.
*/
const KOREAN = "이 문서는 지금 동작을 설명한다. 코드와 같은 변경에서 고친다.\n";
const ENGLISH = "This document describes the current behaviour and is kept with the code that it explains.\n";
const facts: DocsFacts = {
knownPaths: new Set(["docs", "docs/architecture", "docs/architecture/layers.md", "src", "src/platform"]),
docsFiles: ["docs/README.md", "docs/architecture/layers.md", "docs/history/plans/a.md"],
frameworkVersions: new Map([
["React", "19.2.8"],
["Node.js", "24.14.0"],
]),
deletable: ["docs/history", "docs/reviews"],
};
const MAP = [
"# 문서",
"",
"| 폴더 | 무엇 |",
"| --- | --- |",
"| `architecture/` | 현재 계약 |",
"| `history/plans/` | 계획서 |",
"",
].join("\n");
const README = [
"# 템플릿",
"",
"템플릿을 받아 도메인을 채우는 서비스가 쓴다.",
"",
"## 프로젝트 구조",
"## 시작하기",
"## 기능 켜고 끄기",
"## 문서 지도",
"## 검증",
"## 새 서비스로 시작하기",
"## 규칙과 기여",
"",
].join("\n");
function head(label: string, fields: readonly string[]): string {
return [HEAD_START, label, "", ...fields, HEAD_END, "", "# Original title", "", ENGLISH].join("\n");
}
const PLAN_LABEL = "> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.";
const DECISION_LABEL =
"> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.";
const PLAN_FIELDS = Object.freeze([
"- 상태: 끝남",
"- 작성일: 2026-09-25",
"- 요약: 리뷰 발견을 고치는 실행 계획이다.",
"- 현재 정본: `docs/architecture/layers.md`",
]);
/** The fixed documents every case starts from: they pass every check. */
function baseDocuments(): DocsDocument[] {
return [
{ path: "README.md", text: README },
{ path: "docs/README.md", text: MAP },
{ path: "docs/architecture/layers.md", text: KOREAN },
{ path: "docs/history/plans/a.md", text: head(PLAN_LABEL, PLAN_FIELDS) },
];
}
function run(
check: DocsSystemCheck,
documents: readonly DocsDocument[],
options: Readonly<{ exceptions?: string; frozen?: ReadonlySet<string>; facts?: DocsFacts }> = {},
) {
return runDocsSystemChecks({
documents: [...baseDocuments().filter((base) => !documents.some(({ path }) => path === base.path)), ...documents],
facts: options.facts ?? facts,
only: [check],
// The repository's own baseline is not this test's input.
frozen: options.frozen ?? new Set(),
...(options.exceptions === undefined ? {} : { exceptions: options.exceptions }),
}).failures;
}
describe("docs-system checks on documents that follow the rules", () => {
it("pass", () => {
const result = runDocsSystemChecks({ documents: baseDocuments(), facts, frozen: new Set() });
expect(result.failures).toEqual([]);
expect(result.report).toHaveLength(6);
});
});
describe("language (H11)", () => {
it("fails an English living document", () => {
expect(run("language", [{ path: "docs/architecture/layers.md", text: ENGLISH }])).toEqual([
expect.stringContaining("[language] docs/architecture/layers.md: the body is English"),
]);
});
it("fails an English decision record body, below its head block", () => {
const text = head(DECISION_LABEL, ["- 상태: 채택", "- 작성일: 2026-08-01", "- 요약: 결정이다.", "- 현재 정본: 없음 — 예"]);
expect(run("language", [{ path: "docs/adr/VD-99-x.md", text }])).toHaveLength(1);
});
it("does not read record bodies or reviews, which keep the language they were written in", () => {
expect(run("language", [{ path: "docs/reviews/2026-01-01-review.md", text: ENGLISH }])).toEqual([]);
});
it("reads the one living file under reviews", () => {
expect(run("language", [{ path: "docs/reviews/adapters/INVENTORY.md", text: ENGLISH }])).toHaveLength(1);
});
it("does not count code, commands, quotes, links, paths or file names", () => {
const text = [
KOREAN,
"```bash",
"corepack pnpm verify:documentation and many more english words here",
"```",
"`these words are inline code` [and these are a link](https://example.com/a)",
"> quoted lines are left out of the verdict entirely",
'and "a quoted English phrase" src/some/path/here.ts docs/README.md',
].join("\n");
expect(isEnglish(text)).toBe(false);
});
it("needs three English words and a Hangul share under 0.3", () => {
expect(isEnglish("two words")).toBe(false);
expect(isEnglish("three english words")).toBe(true);
expect(isEnglish("한국어 문장 셋이면 three english words")).toBe(false);
});
});
describe("head blocks of records", () => {
const plan = (fields: readonly string[], label = PLAN_LABEL) => [
{ path: "docs/history/plans/a.md", text: head(label, fields) },
];
it("fails a record without one", () => {
expect(run("head", [{ path: "docs/design/2026-01-01-x-design.md", text: ENGLISH }])).toEqual([
expect.stringContaining("no head block at the top"),
]);
});
it("fails the wrong second line for the folder", () => {
expect(run("head", plan(PLAN_FIELDS, PLAN_LABEL.replace("계획서", "설계서")))).toEqual([
expect.stringContaining("the second line is"),
]);
});
it("takes either decision record label", () => {
const fields = ["- 상태: 채택(보완)", "- 작성일: 2026-08-01", "- 요약: 결정이다.", "- 현재 정본: `src/platform`"];
const translated = DECISION_LABEL.replace("원문이다.", "내용이다(번역은 뜻을 바꾸지 않았다).");
expect(run("head", [{ path: "docs/adr/VD-01-x.md", text: head(DECISION_LABEL, fields) }])).toEqual([]);
expect(run("head", [{ path: "docs/adr/VD-01-x.md", text: head(translated, fields) }])).toEqual([]);
});
it.each([
["a status outside the kind's vocabulary", "- 상태: 채택", "the status of a 계획서 is one of"],
["a date that is not YYYY-MM-DD", "- 작성일: 2026-02-30", "the date is YYYY-MM-DD"],
["an English summary", "- 요약: An execution plan for the review findings.", "the summary is one Korean sentence"],
["a canonical path that does not exist", "- 현재 정본: `docs/architecture/gone.md`", "the current canonical path does not exist"],
["a canonical that is neither a path nor 없음", "- 현재 정본: 레이어 문서", "the current canonical is `path`"],
])("fails %s", (_, replacement, message) => {
const name = replacement.slice(2, replacement.indexOf(":"));
const fields = PLAN_FIELDS.map((field) => (field.startsWith(`- ${name}:`) ? replacement : field));
expect(run("head", plan(fields))).toEqual([expect.stringContaining(message)]);
});
it("fails a missing field, an unknown field and a repeated field", () => {
expect(run("head", plan(PLAN_FIELDS.slice(1)))).toEqual([expect.stringContaining("no 「상태」 field")]);
expect(run("head", plan([...PLAN_FIELDS, "- 종류: 계획서"]))).toEqual([
expect.stringContaining("not a head block field: 종류"),
]);
expect(run("head", plan([...PLAN_FIELDS, "- 상태: 끝남"]))).toEqual([
expect.stringContaining("field given twice: 상태"),
]);
});
it("fails a superseded record that does not name its replacement, or names one that is gone", () => {
const superseded = PLAN_FIELDS.map((field) => (field.startsWith("- 상태:") ? "- 상태: 대체됨" : field));
expect(run("head", plan(superseded))).toEqual([expect.stringContaining("names its replacement in 「대체됨」")]);
expect(run("head", plan([...superseded, "- 대체됨: `docs/design/gone.md`"]))).toEqual([
expect.stringContaining("the 「대체됨」 path does not exist"),
]);
expect(run("head", plan([...superseded, "- 대체됨: `docs/architecture/layers.md`"]))).toEqual([]);
});
it("fails a block that does not end within its first 20 lines", () => {
const text = [HEAD_START, PLAN_LABEL, "", ...PLAN_FIELDS, ...Array(15).fill(""), HEAD_END, "", ENGLISH].join("\n");
expect(run("head", [{ path: "docs/history/plans/a.md", text }])).toEqual([
expect.stringContaining("no head block at the top"),
]);
});
});
describe("copied numbers", () => {
const living = (line: string) => [{ path: "docs/architecture/layers.md", text: `${KOREAN}${line}\n` }];
it.each([
["a framework version next to its name", "React 19.1.0을 쓴다.", "framework version"],
["the version package.json pins, wherever it stands", "| 런타임 | 24.14.0 |", "Node.js version"],
["a gate count", "merge 단계 게이트 14개가 돈다.", "gate count"],
["a recipe count", "12개 recipe가 있다.", "recipe count"],
["an adapter count", "adapter 119개를 센다.", "adapter count"],
])("fails %s", (_, line, label) => {
expect(run("number", living(line))).toEqual([expect.stringContaining(label)]);
});
it("counts a version next to its name once", () => {
expect(run("number", living("React 19.2.8을 쓴다."))).toHaveLength(1);
});
it("does not read CHANGELOG.md, decision records or records, which name past states", () => {
expect(run("number", [{ path: "CHANGELOG.md", text: "게이트 14개, React 19.1.0\n" }])).toEqual([]);
expect(run("number", [{ path: "docs/reviews/r.md", text: "게이트 14개\n" }])).toEqual([]);
});
});
describe("documents map", () => {
it("fails a documents folder the map does not list", () => {
const withFolder: DocsFacts = { ...facts, docsFiles: [...facts.docsFiles, "docs/runbooks/FE-RB-001.md"] };
expect(run("map", [], { facts: withFolder })).toEqual([expect.stringContaining("does not list: docs/runbooks/")]);
});
it("fails a listed folder that does not exist", () => {
const map = `${MAP}| \`security/\` | 보안 |\n`;
expect(run("map", [{ path: "docs/README.md", text: map }])).toEqual([
expect.stringContaining("a mapped folder that does not exist: docs/security/"),
]);
});
it("passes a copy that deleted its history, whose map still lists the history folders", () => {
const deleted: DocsFacts = { ...facts, docsFiles: facts.docsFiles.filter((path) => !path.startsWith("docs/history/")) };
const documents = baseDocuments().filter(({ path }) => !path.startsWith("docs/history/"));
expect(runDocsSystemChecks({ documents, facts: deleted, frozen: new Set() }).failures).toEqual([]);
expect(runDocsSystemChecks({ documents, facts: { ...deleted, deletable: [] }, frozen: new Set() }).failures).toEqual([
expect.stringContaining("a mapped folder that does not exist: docs/history/plans/"),
]);
});
it("asks for the folders under a folder that holds only folders", () => {
expect([...requiredFolders(["README.md", "history/plans/a.md", "history/evidence/b/c.md", "manual/x.md"])].sort())
.toEqual(["history/evidence/", "history/plans/", "manual/"]);
});
});
describe("root README sections", () => {
it("fails a missing required section", () => {
expect(run("readme", [{ path: "README.md", text: README.replace("## 문서 지도\n", "") }])).toEqual([
expect.stringContaining("no 「## 문서 지도」 section"),
]);
});
it("fails sections out of order", () => {
const swapped = README.replace("## 프로젝트 구조\n## 시작하기", "## 시작하기\n## 프로젝트 구조");
expect(run("readme", [{ path: "README.md", text: swapped }])).toEqual([
expect.stringContaining("the 「## 시작하기」 section comes after 「## 프로젝트 구조」"),
]);
});
it("fails a README without a title line or an intro paragraph", () => {
expect(run("readme", [{ path: "README.md", text: README.replace("# 템플릿\n", "템플릿\n") }])).toEqual([
expect.stringContaining("the first line is `# 제목`"),
]);
expect(run("readme", [{ path: "README.md", text: README.replace("템플릿을 받아 도메인을 채우는 서비스가 쓴다.\n", "") }]))
.toEqual([expect.stringContaining("put one paragraph")]);
});
});
describe("style", () => {
it("fails a polite sentence ending", () => {
expect(run("style", [{ path: "docs/architecture/layers.md", text: `${KOREAN}이 문서를 설명합니다.\n` }])).toEqual([
expect.stringContaining("[style] docs/architecture/layers.md:2: polite form"),
]);
});
it("does not read quotes, code or `> 이력` blocks", () => {
const text = [KOREAN, "「~합니다」로 쓰지 않는다.", "`설명합니다`", "```", "설명합니다.", "```", "> 이력: 예전에는 설명했습니다."].join("\n");
expect(run("style", [{ path: "docs/architecture/layers.md", text }])).toEqual([]);
});
});
describe("the exception list only shrinks", () => {
const line = "language\tdocs/architecture/layers.md";
const english = [{ path: "docs/architecture/layers.md", text: ENGLISH }];
const frozen = new Set([createHash("sha256").update(line, "utf8").digest("hex").slice(0, 16)]);
it("excuses a frozen line", () => {
expect(run("language", english, { exceptions: `${line}\n`, frozen })).toEqual([]);
});
it("fails a line that is not frozen", () => {
expect(run("language", english, { exceptions: `${line}\n`, frozen: new Set() })).toEqual([
expect.stringContaining("not in the baseline"),
]);
});
it("fails a frozen fingerprint whose line was deleted", () => {
expect(run("language", english, { exceptions: "", frozen })).toEqual(
expect.arrayContaining([expect.stringContaining("a fingerprint with no line")]),
);
});
it("fails a line that no longer matches", () => {
expect(run("language", [], { exceptions: `${line}\n`, frozen })).toEqual([
expect.stringContaining("no longer matches; delete the line"),
]);
});
it("does not call a line stale when its document is not in the tree checked", () => {
const absent = "language\tdocs/runbooks/FE-RB-009.md";
const frozenAbsent = new Set([createHash("sha256").update(absent, "utf8").digest("hex").slice(0, 16)]);
expect(run("language", [], { exceptions: `${absent}\n`, frozen: frozenAbsent })).toEqual([]);
});
it("reads `#` lines and blank lines as comments", () => {
expect(run("language", [], { exceptions: "# 설명\n\n", frozen: new Set() })).toEqual([]);
});
});
+18 -3
View File
@@ -54,6 +54,21 @@ function verifyWithReadme(mutate: (readme: string) => string, document = "README
return verify({ [document]: mutate });
}
/**
* docs-system.md 7: the document checks fail a pull request. The FE-GATE-017
* job runs only when a workflow_dispatch picks the documentation stage, so the
* merge stage (FE-GATE-005, this file) runs verify:documentation once on this
* repository as it is: every document, not the copy the cases below make.
*/
describe("verify:documentation on this repository", () => {
it("passes", () => {
const result = spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], {
encoding: "utf8",
});
expect(result.status, `${result.stderr}${result.stdout}`).toBe(0);
}, 60_000);
});
const gitEnvironment = {
...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_"))),
GIT_CONFIG_GLOBAL: devNull,
@@ -178,7 +193,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => {
it("fails when a document names a package script or a gate ID that does not exist", async () => {
const result = await verify({
"README.md": (readme) => readme.replace("`verify:documentation` fails", "`verify:documentaton` fails"),
"README.md": (readme) => readme.replace("`verify:documentation`", "`verify:documentaton`"),
"docs/README.md": (index) => index.replace("(FE-GATE-017)", "(FE-GATE-099)"),
});
expect(result.status).toBe(1);
@@ -194,7 +209,7 @@ describe("verify:documentation current contract documents (1101/14-05)", () => {
it("accepts a path under history a copy deleted, and only that", async () => {
const naming = (readme: string) => `${readme}\nSee \`docs/retired-notes/plan.md\`.\n`;
const deleted = await verifyWithReadme((readme) =>
naming(readme).replace("| Path | Contents |\n| --- | --- |\n", "$&| `docs/retired-notes/` | deleted |\n"),
naming(readme).replace("| 경로 | 내용 |\n| --- | --- |\n", "$&| `docs/retired-notes/` | 지웠다 |\n"),
);
expect(deleted.status, deleted.stderr).toBe(0);
@@ -356,7 +371,7 @@ describe("verify:documentation source structure (1101/14-03)", () => {
it("fails when a document describes a folder differently from layers.md", async () => {
const result = await verifyWithReadme(
(overview) => overview.replace("- `src/platform` — product-neutral", "- `src/platform` — shared"),
(overview) => overview.replace("- `src/platform` — 어느 폴더든", "- `src/platform` — 공용"),
"docs/architecture/overview.md",
);
expect(result.status).toBe(1);