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