Merge branch 'main' into claude/fe-b-docs-korean-645f55

정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
  README, docs/README.md, manual-checklist, starter-experience,
  ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
  키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
  FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
  `.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
  문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
  `docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
  검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
  옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
  이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
This commit is contained in:
DongHyeonka
2026-11-12 04:53:06 +09:00
141 changed files with 2113 additions and 1169 deletions
+127 -30
View File
@@ -15,6 +15,7 @@ on:
type: choice
options:
- merge
- main
- release
- production
- field
@@ -31,31 +32,97 @@ env:
CI_RUNNER_IMAGE: "${{ vars.RUNNER_IMAGE_DIGEST }}"
jobs:
merge_gate:
name: "${{ matrix.gate }} / ${{ matrix.name }}"
if: ${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}
merge_static:
name: "merge / static checks"
if: ${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }}
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
persist-credentials: false
- uses: https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with:
node-version-file: .nvmrc
- name: Frozen install
run: |
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: "FE-GATE-001 / manifest-lockfile"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-001
- name: "FE-GATE-002 / lint"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-002
- name: "FE-GATE-003 / typecheck"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-003
- name: "FE-GATE-010 / architecture"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-010
- name: "FE-GATE-011 / build"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-011
- name: "FE-GATE-012 / bundle"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-012
- name: Upload merge static evidence
if: always()
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: "merge-static-${{ gitea.run_id }}"
path: artifacts/
if-no-files-found: error
merge_test:
name: "merge / tests"
if: ${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }}
# FE-GATE-013 runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers
# FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs
runs-on: ubuntu-latest
timeout-minutes: 45
strategy:
fail-fast: false
matrix:
include:
- { gate: FE-GATE-001, name: manifest-lockfile, browser: false }
- { gate: FE-GATE-002, name: lint, browser: false }
- { gate: FE-GATE-003, name: typecheck, browser: false }
- { gate: FE-GATE-004, name: runtime-schema, browser: false }
- { gate: FE-GATE-005, name: unit, browser: false }
- { gate: FE-GATE-006, name: component, browser: false }
- { gate: FE-GATE-007, name: integration, browser: false }
- { gate: FE-GATE-008, name: e2e, browser: true }
- { gate: FE-GATE-009, name: accessibility, browser: true }
- { gate: FE-GATE-010, name: architecture, browser: false }
- { gate: FE-GATE-011, name: build, browser: false }
- { gate: FE-GATE-012, name: bundle, browser: false }
- { gate: FE-GATE-013, name: security, browser: false }
- { gate: FE-GATE-020, name: removability, browser: false }
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
persist-credentials: false
- uses: https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with:
node-version-file: .nvmrc
- name: Frozen install
run: |
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: "FE-GATE-004 / runtime-schema"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-004
- name: "FE-GATE-005 / unit"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-005
- name: "FE-GATE-006 / component"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-006
- name: "FE-GATE-007 / integration"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-007
- name: "FE-GATE-013 / security"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-013
- name: "FE-GATE-020 / removability"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-020
- name: Upload merge test evidence
if: always()
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: "merge-test-${{ gitea.run_id }}"
path: artifacts/
if-no-files-found: error
merge_browser:
name: "merge / browser tests"
if: ${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }}
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
@@ -68,23 +135,26 @@ jobs:
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Install Playwright browsers
if: ${{ matrix.browser }}
run: |
corepack pnpm exec playwright install --with-deps chromium firefox webkit
$(command -v sudo || true) apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation
- name: Run blocking gate
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
- name: Upload merge gate evidence
- name: "FE-GATE-008 / e2e"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-008
- name: "FE-GATE-009 / accessibility"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-009
- name: Upload merge browser evidence
if: always()
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: "${{ matrix.gate }}-${{ gitea.run_id }}"
name: "merge-browser-${{ gitea.run_id }}"
path: artifacts/
if-no-files-found: error
release_gate:
name: "${{ matrix.gate }} / ${{ matrix.name }}"
needs: merge_gate
needs: [merge_static, merge_test, merge_browser]
if: ${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}
runs-on: ubuntu-latest
timeout-minutes: 45
@@ -170,6 +240,9 @@ jobs:
artifacts/security/supply-chain-coherence.json \
artifacts/security/supply-chain-verification.json \
artifacts/security/vulnerability-report.json \
config/schemas/artifacts/build-manifest.schema.json \
config/schemas/artifacts/dependency-inventory.schema.json \
config/schemas/artifacts/supply-chain-verification.schema.json \
config/security/dependency-baseline.approval.json \
config/security/dependency-baseline.json \
config/security/dependency-change-evidence.json \
@@ -177,9 +250,6 @@ jobs:
config/security/secret-scan-policy.json \
config/security/vulnerability-exceptions.json \
config/security/vulnerability-policy.json \
schemas/artifacts/build-manifest.schema.json \
schemas/artifacts/dependency-inventory.schema.json \
schemas/artifacts/supply-chain-verification.schema.json \
scripts/contracts/release-artifacts.ts \
scripts/create-release-candidate.ts \
scripts/generate-supply-chain.ts \
@@ -502,3 +572,30 @@ jobs:
name: "FE-GATE-017-${{ gitea.run_id }}"
path: artifacts/
if-no-files-found: error
main_gate:
name: "main / checker self-tests"
if: ${{ (gitea.event_name == 'push' && startsWith(gitea.ref, 'refs/heads/')) || (gitea.event_name == 'workflow_dispatch' && inputs.stage == 'main') }}
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
persist-credentials: false
- uses: https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with:
node-version-file: .nvmrc
- name: Frozen install
run: |
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: "FE-GATE-029 / checker-self-tests"
if: ${{ !cancelled() }}
run: corepack pnpm ci:gate -- FE-GATE-029
- name: Upload main gate evidence
if: always()
uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: "main-gate-${{ gitea.run_id }}"
path: artifacts/
if-no-files-found: error
-3
View File
@@ -23,9 +23,6 @@ artifacts/runbooks/*
!artifacts/tests/
artifacts/tests/*
!artifacts/tests/.gitkeep
!artifacts/tests/a11y-manual/
artifacts/tests/a11y-manual/*
!artifacts/tests/a11y-manual/*.md
# Local environment overrides. `.env.example` is the tracked template; every
# other `.env*` file is a developer's own machine and never enters the repo.
+21 -2
View File
@@ -43,7 +43,7 @@
## 미출시 — `48c7695b` → 정리 단계
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`부터 브랜치 끝까지, `main` `8327e221`에 합침)와 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`)를 담는다. 3단계(합치기)는 아직 없다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`)를 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
### 먼저 할 일 (BREAKING)
@@ -63,13 +63,22 @@
4. **CI 계약 기준선과 workflow를 자기 값으로 다시 기록한 프로젝트는 다시 기록한다.** FE-GATE-007에서 `test:reference-feature` 명령과 그 산출물이, FE-GATE-009·028에서 지운 라우트의 수동 접근성 기록 산출물 4개가 빠졌다. `CI_CONTRACT_BASELINE_OWNER=<팀> CI_CONTRACT_BASELINE_REASON=<이유> corepack pnpm update:ci-contract-baseline`, 그다음 `corepack pnpm generate:ci-workflow` (`e3c8db48`)
5. **초기 JS 기록을 다시 쓴다.** `config/scale/feature-shape-ceilings.json`의 `initialJavascript`에 `firstFeatureGzipBytes`가 더해졌고, 측정은 참조 기능 대신 생성 기능을 복사해 잰다. `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. 다시 쓰지 않으면 `test:unit`이 기록과 빌드가 다르다며 실패한다 (`b2042de9`)
6. **`src/features/` 아래에 기능이 아닌 폴더를 두었으면 밖으로 옮긴다.** 생성기는 `NOT_A_FEATURE` 표식을 더 읽지 않는다. 선언 없는 폴더는 `src/features/<dir> has no feature-module.ts; add one, or keep code that is no feature outside src/features`로 실패한다. 템플릿의 local-draft 샘플은 `tests/fixtures/indexeddb-consumer/`로 옮겼다 (`b72cd7d4`)
7. **음성 타입 fixture를 더한 프로젝트는 첫 줄에 기대를 쓰고 fixture별 tsconfig·script를 지운다.** 템플릿은 `tests/fixtures/typecheck/tsconfig.<이름>.json` 23개와 `check:types:fixture*` script 23개를 `check:types:fixtures` 하나(`scripts/check-type-fixtures.ts`)로 합쳤다. `invalid-*.ts(x)` fixture마다 첫 줄에 `// expect: TS2322`(실패와 그 진단) 또는 `// expect: pass`를 쓴다. 없으면 `check:types:fixtures`가 `` missing `// expect:` first line ``으로 실패한다. 자기 `config/ci/product-gates.json`이 옛 명령 id(`check-types-fixture-*`)를 참조했으면 `check-types-fixtures`로 바꾼다 (`bf485f44`)
8. **`tsconfig.recipes.json`·`tsconfig.web-worker.json`과 그 script(`check:types:recipes`, `check:types:web-worker`)가 없어졌다.** recipe는 `check:types:test`가 검사한다. 자기 recipe tsconfig를 고쳤으면 그 옵션을 `tsconfig.test.json`에 옮긴다. Web Worker 코드를 들인 프로젝트는 매뉴얼 03 C절 「Web Worker를 들일 때 tsconfig 더하기」대로 tsconfig와 script를 되살린다. `check:types` 끝의 `check-typecheck-inputs.ts`는 tsc에 넘기는 tsconfig의 입력이 0개면 `Typecheck inputs: FAIL (no input files: <tsconfig>)`로 실패한다 (`bf485f44`)
9. **수동 a11y 기록을 옮긴다.** `artifacts/tests/a11y-manual/<ROUTE_ID>.md` → `docs/accessibility/route-reviews/<ROUTE_ID>.md`(자기 라우트 기록도 `git mv`). `.gitignore`가 더는 `artifacts/` 아래 `.md`를 들이지 않는다. 남기면 `tests/unit/tracked-artifacts.test.ts`가 그 파일을 이름으로 실패시키고, 옮기지 않으면 `verify:documentation`이 `docs/accessibility/route-reviews/ has no record for route IDs: <ids>`로 실패한다 (`79dc945a`)
10. **루트 `schemas/`를 `config/schemas/`로 옮긴다.** 산출물 스키마는 `config/schemas/artifacts/`, recipe 카탈로그 스키마는 `config/schemas/recipes/`다. 자기 스키마를 `schemas/`에 두었으면 같은 곳으로 옮기고 `$schema` 상대 경로를 고친다. hosting 응답 fixture는 `config/hosting/response-headers.fixture.json` → `tests/fixtures/hosting/response-headers.json` (`79dc945a`)
11. **자기 루트 항목을 등록부에 더한다.** 루트 항목마다 `config/repository-layout.json`에 종류·역할·읽는 곳을 적는다. 제품이 더한 루트 항목(예: `Dockerfile`, `compose.yaml`, `deploy/`)이 없으면 `tests/unit/repository-layout.test.ts`가 `add an entry with its role to config/repository-layout.json`으로 실패한다. 비밀값 검사 범위에 넣을 항목은 `sets`에 `secret-scan`을 적고 `config/security/secret-scan-policy.json`의 `trackedRoots`에도 같은 이름을 더한다. 둘이 다르면 같은 시험이 실패한다. 루트 경로 목록을 코드에 새로 적지 말고 `selectRepositoryPaths(<집합>)`으로 고른다(매뉴얼 03 E절 R2) (`79dc945a`)
12. **CI 계약 기준선을 자기 값으로 다시 기록한 프로젝트는 다시 기록한다.** FE-GATE-003 명령이 25개에서 2개로, FE-GATE-009·028의 수동 a11y 기록 산출물 경로와 id가 바뀌었다. 4단계와 같은 명령이다 (`bf485f44`, `79dc945a`)
13. **CI 계약 기준선 파일이 없어졌다.** `config/ci/contract-baseline.json`, `scripts/update-ci-contract-baseline.ts`, `update:ci-contract-baseline` script를 지웠다(소유자 결정). 위 12단계와 이 절 4단계, 아래 절들의 "기준선을 다시 기록한다"는 이 절까지 받으면 할 일이 없다. 병합에서 자기 기준선 파일이 수정/삭제 충돌이 되면 삭제 쪽을 고른다. 자기 script나 문서가 `update:ci-contract-baseline`을 부르면 지운다 (`f6b2b96c`)
14. **merge 단계 job 이름이 바뀌었다.** 게이트마다 하나이던 행렬 job(`FE-GATE-NNN / <이름>`)이 `merge / static checks`(`merge_static`), `merge / tests`(`merge_test`), `merge / browser tests`(`merge_browser`) 셋이 됐다. 게이트는 job 안의 단계 이름(`FE-GATE-NNN / <이름>`)으로 남는다. Gitea 브랜치 보호의 필수 검사를 옛 job 이름으로 걸었으면 새 job 셋으로 바꾼다. 증거 업로드 이름도 `FE-GATE-NNN-<run>`에서 `merge-static-<run>`·`merge-test-<run>`·`merge-browser-<run>`으로 바뀌었다 (`0739f26b`)
7. **자기 문서를 새 문서 검사에 맞춘다.** `verify:documentation`(FE-GATE-017)이 살아 있는 문서 전부(루트 `README.md`, `docs/` 아래 기록 밖 문서, 모듈 README)를 본다: 본문이 한국어인지, 「~한다」 체인지, 버전·개수를 복사하지 않았는지, 적은 경로·script·게이트 ID가 있는지. 루트 README는 `## 프로젝트 구조`부터 `## 규칙과 기여`까지 정해진 절을 순서대로 가져야 하고, `docs/README.md`는 `docs/` 아래 모든 폴더를 표 첫 칸 `폴더/`로 덮어야 한다. 자기 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 맨 위에 머리 블록을 단다(형식은 템플릿 `docs/README.md` 3절). 한 번에 다 고칠 수 없으면 걸린 줄을 `scripts/docs-system-exceptions.txt`에 기준선으로 적고 그 지문을 `scripts/lib/docs-system.ts`의 `FROZEN`에 넣는다. 그 목록은 줄기만 한다 (`7a9aefdf`)
8. **README의 바뀐 절 이름을 따른다.** 「Files you can delete after copying」은 「복사한 뒤 지워도 되는 것」이다. `verify:documentation`이 이 제목 아래 표의 첫 칸으로 지워도 되는 경로를 읽는다. 자기 README를 템플릿 README로 받았으면 이 제목을 지킨다 (`7a9aefdf`)
#### 옮긴 뒤 확인
1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4단계), `test:unit`(5단계), `generate:feature-index`(6단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다).
1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4·12단계), `test:unit`(5·9·11단계), `generate:feature-index`(6단계), `check:types`·`check:types:fixtures`(7·8단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서, 9단계, 매뉴얼 03 E절 R6·R7), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다).
- 검사기의 음성 fixture 명령 15개와 ungated 검사(`check:ci:gating`)는 PR이 아니라 브랜치 push의 FE-GATE-029(`main_gate`)에서 돈다. 새 시험 파일이나 검증 script를 게이트에 걸지 않으면 PR은 통과하고 main push가 실패한다. 로컬에서는 `corepack pnpm ci:gate FE-GATE-029`로 미리 본다 (`f6b2b96c`).
2. 시각 골든: 갤러리 두 장(`design-system-gallery-dark`, `state-surfaces-light`)은 이제 Storybook 정적 빌드의 story를 찍는다. 자기 골든을 다시 찍은 프로젝트는 `corepack pnpm test:visual:update`로 그 둘을 다시 찍는다.
3. `/examples/ui`·`/examples/states`·`/examples/auth`를 열던 자기 e2e는 플랫폼 라우트나 자기 화면으로 옮긴다. 템플릿의 그런 spec은 옮겼다(아래 표).
@@ -84,12 +93,19 @@
| [계약] | 규모 측정이 참조 기능 대신 생성 기능을 복사해 잰다(`planShapeFeatures`). `initialJavascript`에 `firstFeatureGzipBytes`(기능이 없는 템플릿에 첫 기능을 더할 때의 비용)가 생겼고, context 비용은 둘째 기능을 새 context에 둘 때와 같은 context에 둘 때의 차이다. 기록: 템플릿 194,354 B·17파일, 첫 기능 6,327 B, 기능 하나 539 B, context 하나 4 B. 성장 기준선(0·25·100개)도 다시 쟀다. 위 "먼저 할 일" 5 | `scripts/scale/measure-feature-shape-growth.ts`, `config/scale/` | `b2042de9`, `9c87cc4d` |
| [계약] | 생성기가 `NOT_A_FEATURE` 표식을 읽지 않는다. local-draft 샘플은 IndexedDB 소비자 시험 fixture(`tests/fixtures/indexeddb-consumer/`)가 됐다. 위 "먼저 할 일" 6 | `scripts/generate-product-feature-index.ts`, `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | `b72cd7d4` |
| [계약] | 브라우저 soak(`scripts/scale/browser-soak.ts`, nightly 밖)이 기본으로 생성 기능을 넣은 빌드를 만들어 그 목록 라우트에서 실패하는 백엔드를 관찰한다. `--dist`를 주면 `--feature-route`도 준다. 결과 칸 이름이 `featureVisits`·`settledFeatureVisits`·`apiRequestsPerFeatureVisit`으로 바뀌었다 | `scripts/scale/browser-soak.ts` | `e3c8db48` |
| [계약] **BREAKING** | 음성 타입 fixture 23개를 실행기 하나로 돈다. fixture 첫 줄의 `// expect:`가 기대이고, 판정은 전과 같다(tsc exit 1과 `error TS<code>:`). fixture별 결과와 맞은 진단 줄을 출력한다. `TelemetryPort.emit` 인자를 넓히는 변이(0925/07-05)에서 실패하는 것을 확인했다. recipes tsconfig는 test에 합쳤고 web-worker tsconfig(0파일 검사)는 지웠다(결정 D4). 위 "먼저 할 일" 7·8 | `scripts/check-type-fixtures.ts`, `scripts/check-typecheck-inputs.ts`, `tests/fixtures/typecheck/`, `package.json`, `config/ci/gates.json` | `bf485f44` |
| [계약] **BREAKING** | 루트 등록부 `config/repository-layout.json`이 생겼다. 루트 경로 목록을 쓰던 7곳(복사 대상, 비밀값 검사 범위, 공급망 시험, 이력 문서 검사, 규모 입력, vite 입력, TS 전용 규칙)이 등록부의 집합을 고른다. `schemas/`·수동 a11y 기록·hosting 응답 fixture를 옮겼다. 위 "먼저 할 일" 9~11 | `config/repository-layout.json`, `scripts/lib/repository-layout.ts`, `config/schemas/`, `docs/accessibility/route-reviews/`, `tests/fixtures/hosting/` | `79dc945a` |
| [계약] | 저장소 배치 규칙 R1~R10을 매뉴얼 03 E절에 적고, 기계로 볼 수 있는 것을 게이트에 넣었다: R1·R2·R7(파일)·R9 `tests/unit/repository-layout.test.ts`, R3 `tests/unit/tracked-artifacts.test.ts`, R4·R5 `tests/unit/example-feature-rules.test.ts`(이상 FE-GATE-005), R6·R7(문서) `verify:documentation`(FE-GATE-017, 산출물에 `layoutRuleViolations`), R8 FE-GATE-003 | `docs/manual/03-outside-feature-folder.md`, `scripts/verify-documentation-readiness.ts`, `scripts/contracts/release-artifacts.ts` | `e902e657` |
| [계약] **BREAKING** | merge 단계 job 14개(게이트마다 행렬 하나)를 셋으로 합쳤다. job마다 설치를 한 번 하고 게이트를 차례로 돈다. 앞 게이트가 실패해도 다음 게이트가 돈다(`if: ${{ !cancelled() }}`). release 단계는 세 job을 모두 기다린다. 위 "먼저 할 일" 14 | `config/ci/gates.json` `jobs`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `.gitea/workflows/quality-gates.yml` | `0739f26b` |
| [계약] **BREAKING** | 새 단계 `main`(`MAIN_READY`, 승격을 막지 않음)과 게이트 FE-GATE-029 `checker-self-tests`. FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거, `check:ci`의 ungated 검사(`check:ci:gating`으로 뗌)를 옮겼다. merge 단계 명령 참조 64 → 49. 음성 타입 fixture(`check:types:fixtures`)는 src 타입 계약 시험이라 merge에 남겼다. CI 계약 기준선 파일은 지웠다. 위 "먼저 할 일" 13 | `config/ci/gates.json`, `scripts/check-ci-gating.ts`, `scripts/lib/promotion-readiness.ts` | `f6b2b96c` |
| [계약] **BREAKING** | 문서 체계 검사가 생겼다. `verify:documentation`이 백엔드 `check-docs.py`와 같은 규칙 여섯(language, head, number, map, readme, style)을 `scripts/lib/docs-system.ts`로 돌리고, 참조 검사의 대상이 `docs/README.md` 1절이 링크한 문서에서 살아 있는 문서 전부로 넓어졌다. pull request에서는 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts`가 이 repo로 `verify:documentation`을 돌리므로 문서가 걸리면 merge 단계가 실패한다. 예외 목록(`scripts/docs-system-exceptions.txt`)은 비어 있고 줄기만 한다. 위 "먼저 할 일" 7 | `scripts/lib/docs-system.ts`, `scripts/verify-documentation-readiness.ts`, `scripts/docs-system-exceptions.txt`, `docs/README.md` | `7a9aefdf` |
| [계약] | 문서를 수명으로 나눠 옮겼다. 설계서는 `docs/design/`(옛 `docs/superpowers/specs/`와 `docs/architecture/`의 목표 설계 16개는 `<작성일>-<이름>-design.md`로), 계획서는 `docs/history/plans/`(옛 `docs/superpowers/plans/`, 루트 `SPEC.md`는 `docs/history/plans/2026-09-25-review-fix-round/`), 결정 기록 VD는 `docs/adr/`(번호 그대로)다. 기록 67개에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 코드 주석의 문서 경로도 고쳤다. 위 "먼저 할 일" 옮기기 전 | `docs/design/`, `docs/history/`, `docs/adr/`, `.dependency-cruiser.json`, `tests/component/router.test.tsx` | `99e76e87`, `e632b230`, `9540bf81`, `75fad73a`, `2b8a348c` |
| [계약] | 루트 README를 한국어로 다시 썼다. 절은 프로젝트 구조 → 시작하기 → (런타임 설정과 배포 변수) → 기능 켜고 끄기 → 문서 지도 → 검증 → 새 서비스로 시작하기 → 규칙과 기여다. 옛 「Support scope」는 「기능 켜고 끄기」의 「지원 범위」, 「Updating a copied project」는 「새 서비스로 시작하기」의 「원본 업데이트 반영」, 「CI and evidence」는 「검증」의 「게이트와 CI」다. 위 "먼저 할 일" 8 | `README.md`, `tests/unit/documentation-readiness.test.ts` | `7a9aefdf` |
### 그 밖의 수정
- `scripts/check-*.ts` 30개를 ESLint 규칙·의존 규칙·시험으로 옮길 수 있는지 판정한 표를 `docs/operations/ci-script-assessment.md`에 남겼다. 코드는 바꾸지 않았다 (`3ce77d9e`).
- 정리 3단계에서 문서가 가리키던 옛 명령·경로(`check:types:fixture:*`, `check:types:recipes`, a11y 기록과 스키마 경로)를 새 이름으로 바꿨다 (`bf485f44`, `79dc945a`).
- 정리 1단계: 읽는 곳 없는 산출물 13개를 지우고 `artifacts/`를 폴더째 무시한다(`85f941c4`). 아무도 읽지 않는 `config/schemas/` JSON Schema 4개를 지웠다(`0805910c`). 루트 `tasks/`와 `.superpowers/` 기록을 `docs/history/`로 옮겼다(`429b8d88`). nginx 설정 예시를 지우고 호스트가 지킬 조건만 남겼다(`121e1125`).
- `/examples/ui`·`/examples/states`를 열던 e2e(반응형, 스크롤 복원, 타이포그래피, 건너뛰기 링크)는 홈과 `/examples/platform`으로 옮겼다 (`e7210c71`).
- 매뉴얼(`docs/manual/`)의 예제 칸은 생성기 출력 경로와 매뉴얼 안 코드 조각을 가리킨다. 코드 조각 일곱 개(problem details 백엔드의 분류와 매핑, 도메인 모델, 검색값 읽기, 실패 행동, 403 페이지 시험)는 `tests/unit/manual-code-blocks.test.ts`가 생성 기능 위에서 타입 검사·lint·아키텍처 검사·동작 시험을 돌린다. problem details 예는 소유자 결정대로 02 결정표 4절에 있다 (`01cac930`).
@@ -104,6 +120,9 @@
### 알려진 제한
- 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다(S4 가정 F4).
- R2 검사는 등록부를 쓰는 7곳만 본다. 그 밖에 루트 이름 둘 이상을 담은 문자열 배열이 약 20곳 남았다(예: `tests/e2e/support/fixture-builds.ts`의 복사 제외 목록, `scripts/check-test-evidence.ts`의 playwright 설정 목록). 뜻이 다른 목록이라 이번에 옮기지 않았다.
- R5는 문자열 검색이라 샘플 ID나 라우트 경로를 조립해 쓰는 시험은 놓친다.
- CI 재편(merge job 셋, main 단계)은 desktop에서 게이트 명령으로 확인했다. Gitea runner에서 새 workflow가 도는지는 Actions를 켠 뒤 확인한다.
- 성능 lab(FE-GATE-026)의 기능 라우트 측정(`featureRouteInteractionMs`)은 템플릿에 공개 기능 라우트가 없어 `measured: false`다. 제품 기능이 생기면 잰다.
- `TEMPLATE_FIXTURE` 출처와 `REFERENCE_EXTERNAL_BEARER` 별칭이 플랫폼 코드에 남았다. 쓰는 기능이 없다.
- visual 골든의 픽셀 비교는 색 허용치(`threshold` 0.2)를 넘지 않는 미세한 토큰 변경(예: 어두운 테마 `--color-danger` red-500 → red-600)을 잡지 못한다. 옛 골든도 같았다.
+3 -4
View File
@@ -12,11 +12,10 @@ React와 Vite로 만든 프론트엔드 참조 구현(reference implementation)
| `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/` |
| `config/` | 게이트 목록(`config/ci/`), 런타임 프로필(`config/runtime/`), recipe 카탈로그(`config/recipes/`), JSON Schema(`config/schemas/`), 보안·성능·규모 기준선, 최상위 항목 등록부(`config/repository-layout.json`) | `docs/operations/ci-quality-gates.md` |
| `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` |
| `artifacts/` | 게이트와 시험의 실행 출력. git은 무시하고 `.gitkeep`만 추적한다 | `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` |
@@ -223,7 +222,7 @@ export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1
외부 증거가 필요한 게이트:
- `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`만 돌린다. 모든 라우트 기록이 템플릿의 칸을 지키는지(검토했든 아직이든) 본다.
- `review:a11y-manual`(release 게이트 FE-GATE-028)은 등록된 모든 라우트에 대해 사람이 서명한 키보드·포커스·스크린 리더 검토가 필요하다. 라우트마다 기록 하나를 `docs/accessibility/route-reviews/<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나 진입 압축이 없는 호스트는 실패한다.
-11
View File
@@ -1,11 +0,0 @@
{
"schemaVersion": 1,
"owner": "DongHyeonka",
"reason": "2026-11-07 소유자 결정: 템플릿 샘플 삭제. 참조 기능 시험 명령과 그 산출물, 지운 라우트의 수동 a11y 기록 산출물 4개를 뺀다",
"gates": 27,
"commands": 99,
"commandReferences": 103,
"artifacts": 105,
"stages": 5,
"gateShapeSha256": "df584fba26f8448c6a77638351c6906ed91869da82e20f12ac71ea7b2037c989"
}
+193 -237
View File
@@ -23,169 +23,10 @@
"expect": "pass"
},
{
"id": "check-types-recipes",
"script": "check:types:recipes",
"id": "check-types-fixtures",
"script": "check:types:fixtures",
"expect": "pass"
},
{
"id": "check-types-fixture",
"script": "check:types:fixture",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-ts-port",
"script": "check:types:fixture:ts-port",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-ts-result",
"script": "check:types:fixture:ts-result",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2339:"
},
{
"id": "check-types-fixture-application-output",
"script": "check:types:fixture:application-output",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-application-input",
"script": "check:types:fixture:application-input",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2739:"
},
{
"id": "check-types-fixture-feature-input",
"script": "check:types:fixture:feature-input",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2345:"
},
{
"id": "check-types-fixture-failure-kind",
"script": "check:types:fixture:failure-kind",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-reference-operation",
"script": "check:types:fixture:reference-operation",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2741:"
},
{
"id": "check-types-fixture-http-operation-input",
"script": "check:types:fixture:http-operation-input",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2353:"
},
{
"id": "check-types-fixture-http-wire-mapper",
"script": "check:types:fixture:http-wire-mapper",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-http-operation-id",
"script": "check:types:fixture:http-operation-id",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2345:"
},
{
"id": "check-types-fixture-http-route-id",
"script": "check:types:fixture:http-route-id",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-feature-contribution-input",
"script": "check:types:fixture:feature-contribution-input",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-feature-capability-selection",
"script": "check:types:fixture:feature-capability-selection",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2339:"
},
{
"id": "check-types-fixture-direct-feature-composition",
"script": "check:types:fixture:direct-feature-composition",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2345:"
},
{
"id": "check-types-fixture-async-overlay",
"script": "check:types:fixture:async-overlay",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2322:"
},
{
"id": "check-types-fixture-route-runtime",
"script": "check:types:fixture:route-runtime",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2741:"
},
{
"id": "check-types-fixture-page-action",
"script": "check:types:fixture:page-action",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS1360:"
},
{
"id": "check-types-fixture-icon-button",
"script": "check:types:fixture:icon-button",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2741:"
},
{
"id": "check-types-fixture-i18n-key",
"script": "check:types:fixture:i18n-key",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2345:"
},
{
"id": "check-types-fixture-i18n-params",
"script": "check:types:fixture:i18n-params",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2554:"
},
{
"id": "check-types-fixture-diagnostics",
"script": "check:types:fixture:diagnostics",
"expect": "pass"
},
{
"id": "check-types-fixture-image-resolve-signal",
"script": "check:types:fixture:image-resolve-signal",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "error TS2741:"
},
{
"id": "test-runtime-schema",
"script": "test:runtime-schema",
@@ -586,6 +427,11 @@
"script": "check:ci",
"expect": "pass"
},
{
"id": "check-ci-gating",
"script": "check:ci:gating",
"expect": "pass"
},
{
"id": "check-release-admission",
"script": "check:release-admission",
@@ -1144,14 +990,14 @@
]
},
{
"id": "artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"path": "artifacts/tests/a11y-manual/APP_HOME.md",
"id": "artifact-docs-accessibility-route-reviews-APP-HOME-md",
"path": "docs/accessibility/route-reviews/APP_HOME.md",
"schemaId": "markdown",
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"path": "artifacts/tests/a11y-manual/NOT_FOUND.md",
"id": "artifact-docs-accessibility-route-reviews-NOT-FOUND-md",
"path": "docs/accessibility/route-reviews/NOT_FOUND.md",
"schemaId": "markdown",
"production": "source-controlled"
},
@@ -1722,6 +1568,12 @@
"path": "artifacts/quality/gates/FE-GATE-028.txt",
"schemaId": "text",
"production": "runner-generated"
},
{
"id": "artifact-artifacts-quality-gates-FE-GATE-029-txt",
"path": "artifacts/quality/gates/FE-GATE-029.txt",
"schemaId": "text",
"production": "runner-generated"
}
],
"gates": [
@@ -1729,8 +1581,7 @@
"id": "FE-GATE-001",
"name": "manifest-lockfile",
"commandIds": [
"verify-lockfile",
"check-frozen-lockfile-fixture"
"verify-lockfile"
],
"logArtifactId": "artifact-artifacts-quality-install-txt",
"evidenceArtifactIds": [
@@ -1755,30 +1606,7 @@
"name": "typecheck",
"commandIds": [
"check-types",
"check-types-recipes",
"check-types-fixture",
"check-types-fixture-ts-port",
"check-types-fixture-ts-result",
"check-types-fixture-application-output",
"check-types-fixture-application-input",
"check-types-fixture-feature-input",
"check-types-fixture-failure-kind",
"check-types-fixture-reference-operation",
"check-types-fixture-http-operation-input",
"check-types-fixture-http-wire-mapper",
"check-types-fixture-http-operation-id",
"check-types-fixture-http-route-id",
"check-types-fixture-feature-contribution-input",
"check-types-fixture-feature-capability-selection",
"check-types-fixture-direct-feature-composition",
"check-types-fixture-async-overlay",
"check-types-fixture-route-runtime",
"check-types-fixture-page-action",
"check-types-fixture-icon-button",
"check-types-fixture-i18n-key",
"check-types-fixture-i18n-params",
"check-types-fixture-diagnostics",
"check-types-fixture-image-resolve-signal"
"check-types-fixtures"
],
"logArtifactId": "artifact-artifacts-quality-check-types-txt",
"evidenceArtifactIds": [
@@ -1805,7 +1633,6 @@
"test-unit",
"test-contract",
"test-coverage",
"check-coverage-fixture",
"check-scale-pr"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-005-txt",
@@ -1814,8 +1641,7 @@
"artifact-artifacts-tests-contract-xml",
"artifact-artifacts-tests-coverage-xml",
"artifact-artifacts-tests-coverage-coverage-summary-json",
"artifact-artifacts-quality-risk-coverage-json",
"artifact-artifacts-quality-risk-coverage-fixture-json"
"artifact-artifacts-quality-risk-coverage-json"
],
"retentionClassId": "merge-cycle"
},
@@ -1858,8 +1684,7 @@
"verify-browser-capability-evidence",
"test-storybook",
"test-visual",
"check-test-evidence-browser",
"check-test-evidence-fixture"
"check-test-evidence-browser"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-008-txt",
"evidenceArtifactIds": [
@@ -1871,8 +1696,7 @@
"artifact-artifacts-tests-storybook-results-xml",
"artifact-artifacts-tests-visual-report-index-html",
"artifact-artifacts-tests-visual-results-xml",
"artifact-artifacts-quality-test-evidence-json",
"artifact-artifacts-quality-test-evidence-fixture-json"
"artifact-artifacts-quality-test-evidence-json"
],
"retentionClassId": "merge-cycle"
},
@@ -1897,21 +1721,12 @@
"check-request-fanout",
"check-app-build-input",
"check-design-system",
"check-design-system-fixture",
"check-i18n",
"check-i18n-fixture",
"check-diagnostics",
"check-diagnostics-fixture",
"check-browser-file-storage-boundaries",
"check-realtime-boundaries",
"check-realtime-boundaries-fixture",
"check-optional-recipes-source",
"check-optional-recipe-fixtures",
"check-registries",
"check-registries-compatibility-fixtures",
"check-registries-baseline-fixture",
"check-registries-fixture",
"check-routes-fixture",
"check-adapter-inventory",
"check-ci"
],
@@ -1919,19 +1734,11 @@
"evidenceArtifactIds": [
"artifact-artifacts-quality-dependency-report-json",
"artifact-artifacts-quality-design-system-json",
"artifact-artifacts-quality-design-system-fixture-json",
"artifact-artifacts-quality-i18n-json",
"artifact-artifacts-quality-i18n-fixture-json",
"artifact-artifacts-quality-diagnostics-json",
"artifact-artifacts-quality-diagnostics-fixture-json",
"artifact-artifacts-quality-realtime-boundaries-json",
"artifact-artifacts-quality-optional-recipes-json",
"artifact-artifacts-quality-optional-recipe-fixtures-json",
"artifact-artifacts-quality-registries-json",
"artifact-artifacts-quality-registry-compatibility-fixtures-json",
"artifact-artifacts-quality-registry-baseline-fixture-json",
"artifact-artifacts-quality-registry-fixture-json",
"artifact-artifacts-quality-route-registry-fixture-json",
"artifact-artifacts-quality-ci-contract-json"
],
"retentionClassId": "merge-cycle"
@@ -1975,9 +1782,6 @@
"verify-reproducible-build",
"build-release-candidate",
"verify-local-evidence",
"check-supply-chain-fixtures",
"check-supply-chain-provider-fixtures",
"check-security-fixtures",
"check-browser-security"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-013-txt",
@@ -1992,9 +1796,7 @@
"artifact-artifacts-security-license-report-json",
"artifact-artifacts-security-vulnerability-report-json",
"artifact-artifacts-security-supply-chain-verification-json",
"artifact-artifacts-security-supply-chain-coherence-json",
"artifact-artifacts-security-supply-chain-fixtures-json",
"artifact-artifacts-security-supply-chain-provider-fixtures-json"
"artifact-artifacts-security-supply-chain-coherence-json"
],
"retentionClassId": "release-coherence",
"hostRequirements": [
@@ -2186,11 +1988,49 @@
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
"evidenceArtifactIds": [
"artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"artifact-docs-accessibility-route-reviews-APP-HOME-md",
"artifact-docs-accessibility-route-reviews-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-report-json"
],
"retentionClassId": "release-coherence"
},
{
"id": "FE-GATE-029",
"name": "checker-self-tests",
"commandIds": [
"check-frozen-lockfile-fixture",
"check-coverage-fixture",
"check-test-evidence-fixture",
"check-design-system-fixture",
"check-i18n-fixture",
"check-diagnostics-fixture",
"check-realtime-boundaries-fixture",
"check-optional-recipe-fixtures",
"check-registries-compatibility-fixtures",
"check-registries-baseline-fixture",
"check-registries-fixture",
"check-routes-fixture",
"check-supply-chain-fixtures",
"check-supply-chain-provider-fixtures",
"check-security-fixtures",
"check-ci-gating"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-029-txt",
"evidenceArtifactIds": [
"artifact-artifacts-quality-risk-coverage-fixture-json",
"artifact-artifacts-quality-test-evidence-fixture-json",
"artifact-artifacts-quality-design-system-fixture-json",
"artifact-artifacts-quality-i18n-fixture-json",
"artifact-artifacts-quality-diagnostics-fixture-json",
"artifact-artifacts-quality-optional-recipe-fixtures-json",
"artifact-artifacts-quality-registry-compatibility-fixtures-json",
"artifact-artifacts-quality-registry-baseline-fixture-json",
"artifact-artifacts-quality-registry-fixture-json",
"artifact-artifacts-quality-route-registry-fixture-json",
"artifact-artifacts-security-supply-chain-fixtures-json",
"artifact-artifacts-security-supply-chain-provider-fixtures-json"
],
"retentionClassId": "merge-cycle"
}
],
"stages": [
@@ -2261,13 +2101,21 @@
"gateIds": [
"FE-GATE-017"
]
},
{
"id": "main",
"readiness": "MAIN_READY",
"needs": [],
"gateIds": [
"FE-GATE-029"
]
}
],
"jobs": [
{
"id": "merge_gate",
"displayName": "${{ matrix.gate }} / ${{ matrix.name }}",
"kind": "gate-matrix",
"id": "merge_static",
"displayName": "merge / static checks",
"kind": "gate-sequence",
"needs": [],
"condition": "merge",
"timeoutMinutes": 45,
@@ -2275,18 +2123,88 @@
"FE-GATE-001",
"FE-GATE-002",
"FE-GATE-003",
"FE-GATE-010",
"FE-GATE-011",
"FE-GATE-012"
],
"browserGateIds": [],
"environment": [],
"steps": [
{
"kind": "checkout"
},
{
"kind": "setup-node"
},
{
"kind": "frozen-install"
},
{
"kind": "run-gate"
},
{
"kind": "upload",
"transferId": "merge-static-evidence",
"name": "merge-static-${{ gitea.run_id }}",
"paths": [
"artifacts/"
],
"always": true
}
]
},
{
"id": "merge_test",
"displayName": "merge / tests",
"kind": "gate-sequence",
"needs": [],
"condition": "merge",
"timeoutMinutes": 45,
"gateIds": [
"FE-GATE-004",
"FE-GATE-005",
"FE-GATE-006",
"FE-GATE-007",
"FE-GATE-008",
"FE-GATE-009",
"FE-GATE-010",
"FE-GATE-011",
"FE-GATE-012",
"FE-GATE-013",
"FE-GATE-020"
],
"browserGateIds": [],
"environment": [],
"steps": [
{
"kind": "checkout"
},
{
"kind": "setup-node"
},
{
"kind": "frozen-install"
},
{
"kind": "run-gate"
},
{
"kind": "upload",
"transferId": "merge-test-evidence",
"name": "merge-test-${{ gitea.run_id }}",
"paths": [
"artifacts/"
],
"always": true
}
]
},
{
"id": "merge_browser",
"displayName": "merge / browser tests",
"kind": "gate-sequence",
"needs": [],
"condition": "merge",
"timeoutMinutes": 45,
"gateIds": [
"FE-GATE-008",
"FE-GATE-009"
],
"browserGateIds": [
"FE-GATE-008",
"FE-GATE-009"
@@ -2310,8 +2228,8 @@
},
{
"kind": "upload",
"transferId": "merge-gate-evidence",
"name": "${{ matrix.gate }}-${{ gitea.run_id }}",
"transferId": "merge-browser-evidence",
"name": "merge-browser-${{ gitea.run_id }}",
"paths": [
"artifacts/"
],
@@ -2324,7 +2242,9 @@
"displayName": "${{ matrix.gate }} / ${{ matrix.name }}",
"kind": "gate-matrix",
"needs": [
"merge_gate"
"merge_static",
"merge_test",
"merge_browser"
],
"condition": "release",
"timeoutMinutes": 45,
@@ -2423,6 +2343,9 @@
"artifacts/security/supply-chain-coherence.json",
"artifacts/security/supply-chain-verification.json",
"artifacts/security/vulnerability-report.json",
"config/schemas/artifacts/build-manifest.schema.json",
"config/schemas/artifacts/dependency-inventory.schema.json",
"config/schemas/artifacts/supply-chain-verification.schema.json",
"config/security/dependency-baseline.approval.json",
"config/security/dependency-baseline.json",
"config/security/dependency-change-evidence.json",
@@ -2430,9 +2353,6 @@
"config/security/secret-scan-policy.json",
"config/security/vulnerability-exceptions.json",
"config/security/vulnerability-policy.json",
"schemas/artifacts/build-manifest.schema.json",
"schemas/artifacts/dependency-inventory.schema.json",
"schemas/artifacts/supply-chain-verification.schema.json",
"scripts/contracts/release-artifacts.ts",
"scripts/create-release-candidate.ts",
"scripts/generate-supply-chain.ts",
@@ -2935,6 +2855,42 @@
"always": true
}
]
},
{
"id": "main_gate",
"displayName": "main / checker self-tests",
"kind": "gate-sequence",
"needs": [],
"condition": "main",
"timeoutMinutes": 45,
"gateIds": [
"FE-GATE-029"
],
"browserGateIds": [],
"environment": [],
"steps": [
{
"kind": "checkout"
},
{
"kind": "setup-node"
},
{
"kind": "frozen-install"
},
{
"kind": "run-gate"
},
{
"kind": "upload",
"transferId": "main-gate-evidence",
"name": "main-gate-${{ gitea.run_id }}",
"paths": [
"artifacts/"
],
"always": true
}
]
}
],
"retention": {
@@ -1,5 +1,5 @@
{
"$schema": "../../schemas/config/frontend-capability-recipes.schema.json",
"$schema": "../schemas/recipes/frontend-capability-recipes.schema.json",
"schemaVersion": 1,
"decisionId": "VD-10",
"defaultStatus": "NOT_INSTALLED",
+319
View File
@@ -0,0 +1,319 @@
{
"schemaVersion": 1,
"kinds": {
"source": "코드와 시험. 계층과 도구가 읽는다",
"tool-convention": "도구가 루트에서 이 이름으로 찾는 설정 파일·폴더",
"gate-input": "게이트와 런타임이 읽는 기준 데이터",
"document": "사람이 읽는 문서",
"history": "끝난 라운드의 기록. 이력 폴더로 옮길 대상이다(R10)",
"output": "실행 출력. 추적하는 것은 `.gitkeep`뿐이다(R3)"
},
"sets": {
"fixture-copy": "제거·생성 drill과 사본 시험이 복사하는 것(scripts/lib/removal-fixture.ts)",
"fixture-documents": "기능을 더하거나 지우는 drill이 문서까지 맞는지 보려고 더 복사하는 문서(scripts/lib/removal-fixture.ts)",
"secret-scan": "비밀값 검사와 공급망 목록의 범위. config/security/secret-scan-policy.json의 trackedRoots가 이 집합과 같아야 한다",
"history-free": "이력 문서를 읽으면 안 되는 코드(tests/unit/deletable-history-documents.test.ts)",
"scale-source": "규모 증거에서 '지금 코드'를 정하는 입력(scripts/verify-extreme-scale.ts)",
"vite-build": "vite build가 읽는 입력(scripts/lib/vite-build-inputs.ts)",
"typescript-only": "JS 파일을 두면 안 되는 곳(scripts/check-architecture.ts)"
},
"entries": [
{
"path": ".claude",
"kind": "tool-convention",
"role": "Claude Code 설정·규칙·스킬·서브에이전트",
"readBy": "Claude Code"
},
{
"path": ".dependency-cruiser.json",
"kind": "tool-convention",
"role": "import 규칙과 kernel 예외의 정본",
"readBy": "scripts/check-architecture.ts (FE-GATE-010)",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
},
{
"path": ".env.example",
"kind": "tool-convention",
"role": "빌드 시점 공개 변수의 견본",
"readBy": "Vite(VITE_*), 사람"
},
{
"path": ".gitattributes",
"kind": "tool-convention",
"role": "git 병합 규칙(작업 장부 docs/ledger/estimates.jsonl을 union으로 합친다)",
"readBy": "git"
},
{
"path": ".gitea",
"kind": "tool-convention",
"role": "Gitea Actions workflow. config/ci/gates.json에서 생성한다",
"readBy": "Gitea Actions, scripts/generate-ci-workflow.ts, check:ci (FE-GATE-010)",
"sets": ["fixture-copy", "history-free"],
"setPaths": {
"secret-scan": [".gitea/workflows/quality-gates.yml"]
}
},
{
"path": ".gitignore",
"kind": "tool-convention",
"role": "추적하지 않을 파일",
"readBy": "git",
"sets": ["fixture-copy"]
},
{
"path": ".npmrc",
"kind": "tool-convention",
"role": "pnpm 설정",
"readBy": "pnpm",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": ".nvmrc",
"kind": "tool-convention",
"role": "Node 버전",
"readBy": "nvm, CI",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": ".storybook",
"kind": "tool-convention",
"role": "Storybook 설정. 갤러리와 visual 골든의 대상",
"readBy": "storybook, build:storybook (FE-GATE-011)",
"sets": ["fixture-copy", "secret-scan", "scale-source", "typescript-only"]
},
{
"path": "AGENTS.md",
"kind": "tool-convention",
"role": "에이전트 진입 문서(꼭 지킬 것·지도·검증). docs/README.md 1절이 가리키는 현재 계약 문서",
"readBy": "코딩 에이전트, verify:documentation (FE-GATE-017)",
"sets": ["fixture-documents"]
},
{
"path": "CHANGELOG.md",
"kind": "document",
"role": "버전별 변경과 다운스트림이 할 일",
"readBy": "tests/unit/changelog-review-ids.test.ts, 사람",
"sets": ["fixture-documents"]
},
{
"path": "CLAUDE.md",
"kind": "tool-convention",
"role": "Claude Code 진입 문서",
"readBy": "Claude Code"
},
{
"path": "PRODUCT.md",
"kind": "tool-convention",
"role": "제품 맥락. 디자인 도구가 루트에서 찾는다",
"readBy": "디자인 스킬"
},
{
"path": "README.md",
"kind": "document",
"role": "시작·설정·검증",
"readBy": "verify:documentation (FE-GATE-017), 사람",
"sets": ["fixture-documents"]
},
{
"path": "artifacts",
"kind": "output",
"role": "게이트와 시험의 실행 출력",
"readBy": "scripts/run-ci-gate.ts, CI 업로드"
},
{
"path": "config",
"kind": "gate-input",
"role": "게이트·런타임·보안·성능의 기준 데이터와 JSON Schema(config/schemas)",
"readBy": "scripts/, tests/, src/",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
},
{
"path": "docs",
"kind": "document",
"role": "매뉴얼·설계·운영 문서와 수동 접근성 검토 기록",
"readBy": "verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009·028)",
"sets": ["fixture-documents"],
"setPaths": {
"fixture-copy": ["docs/accessibility/route-reviews"]
}
},
{
"path": "eslint.config.ts",
"kind": "tool-convention",
"role": "lint 규칙",
"readBy": "eslint (FE-GATE-002)",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
},
{
"path": "index.html",
"kind": "tool-convention",
"role": "Vite 진입 HTML",
"readBy": "Vite",
"sets": ["fixture-copy", "secret-scan", "vite-build"]
},
{
"path": "package.json",
"kind": "tool-convention",
"role": "의존성과 package script",
"readBy": "pnpm, 모든 게이트",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build"]
},
{
"path": "playwright.capabilities.config.ts",
"kind": "tool-convention",
"role": "브라우저 capability 시험 설정",
"readBy": "test:browser-capabilities (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "playwright.config.ts",
"kind": "tool-convention",
"role": "e2e 설정(빌드 미리보기)",
"readBy": "test:e2e (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan", "history-free"]
},
{
"path": "playwright.dev.config.ts",
"kind": "tool-convention",
"role": "dev 서버 대상 e2e 설정",
"readBy": "test:e2e:dev",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "playwright.storybook.config.ts",
"kind": "tool-convention",
"role": "Storybook 정적 빌드 시험 설정",
"readBy": "test:storybook (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "playwright.visual.config.ts",
"kind": "tool-convention",
"role": "visual 골든 설정",
"readBy": "test:visual (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "pnpm-lock.yaml",
"kind": "tool-convention",
"role": "잠금 파일",
"readBy": "pnpm, 공급망 생성",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
},
{
"path": "pnpm-workspace.yaml",
"kind": "tool-convention",
"role": "pnpm 11 설정",
"readBy": "pnpm, scripts/lib/package-script-graph.ts",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "public",
"kind": "tool-convention",
"role": "개발 서버가 서빙하는 런타임 문서",
"readBy": "Vite",
"sets": ["fixture-copy", "secret-scan", "vite-build"]
},
{
"path": "recipes",
"kind": "source",
"role": "선택 기능 설치 원본. 기본 빌드에 들어가지 않는다",
"readBy": "tsconfig.test.json, test:recipes (FE-GATE-007), check:optional-recipes (FE-GATE-012)",
"optional": true,
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only"]
},
{
"path": "renovate.json",
"kind": "tool-convention",
"role": "보안 업데이트 봇 설정",
"readBy": "Renovate"
},
{
"path": "scripts",
"kind": "source",
"role": "게이트·생성기·drill 스크립트",
"readBy": "package.json scripts",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only"],
"setPaths": {
"vite-build": ["scripts/lib/run-isolation.ts", "scripts/lib/vite-module-inventory.ts"]
}
},
{
"path": "src",
"kind": "source",
"role": "앱 계층",
"readBy": "빌드와 모든 게이트",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build", "typescript-only"]
},
{
"path": "tests",
"kind": "source",
"role": "시험과 fixture",
"readBy": "test:* scripts, playwright 설정",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only"]
},
{
"path": "tsconfig.app.json",
"kind": "tool-convention",
"role": "src 타입 검사(DOM, Node 타입 없음)",
"readBy": "check:types:app (FE-GATE-003), Vite",
"sets": ["fixture-copy", "secret-scan", "scale-source", "vite-build"]
},
{
"path": "tsconfig.base.json",
"kind": "tool-convention",
"role": "공통 컴파일 옵션",
"readBy": "다른 tsconfig의 extends",
"sets": ["fixture-copy", "secret-scan", "vite-build"]
},
{
"path": "tsconfig.json",
"kind": "tool-convention",
"role": "편집기용 solution tsconfig(files 없음, references만)",
"readBy": "편집기",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
},
{
"path": "tsconfig.node.json",
"kind": "tool-convention",
"role": "scripts·설정 파일 타입 검사(NodeNext)",
"readBy": "check:types:node (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
},
{
"path": "tsconfig.service-worker.json",
"kind": "tool-convention",
"role": "Service Worker 타입 검사(WebWorker, DOM 없음)",
"readBy": "check:types:service-worker (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "tsconfig.test.json",
"kind": "tool-convention",
"role": "tests·recipes·시험 설정 파일 타입 검사",
"readBy": "check:types:test (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
},
{
"path": "vite.config.ts",
"kind": "tool-convention",
"role": "앱 빌드",
"readBy": "Vite",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build"]
},
{
"path": "vite.service-worker.config.ts",
"kind": "tool-convention",
"role": "Service Worker 빌드",
"readBy": "scripts/build-frontend.ts",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "vitest.config.ts",
"kind": "tool-convention",
"role": "단위·컴포넌트 시험 설정",
"readBy": "scripts/run-vitest.ts",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
}
]
}
-3
View File
@@ -7,7 +7,6 @@
"tests",
"config",
"public",
"schemas",
".storybook",
".gitea/workflows/quality-gates.yml",
".dependency-cruiser.json",
@@ -22,10 +21,8 @@
"tsconfig.app.json",
"tsconfig.base.json",
"tsconfig.node.json",
"tsconfig.recipes.json",
"tsconfig.service-worker.json",
"tsconfig.test.json",
"tsconfig.web-worker.json",
"vite.config.ts",
"vite.service-worker.config.ts",
"vitest.config.ts",
+3 -3
View File
@@ -49,7 +49,7 @@
| `contracts/` | 계약 호환 규칙(읽는 쪽을 먼저 배포한다) |
| `security/` | 브라우저 보안 경계와 공급망 |
| `styling/` | 디자인 토큰 |
| `accessibility/` | 수동 접근성 검토 체크리스트. 라우트별 기록은 repo 루트의 `artifacts/tests/a11y-manual/`에 있다 |
| `accessibility/` | 수동 접근성 검토 체크리스트와 라우트별 검토 기록(`accessibility/route-reviews/`) |
| `testing/` | 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선 |
### 운영
@@ -99,7 +99,7 @@
| 파일 | 읽는 명령 |
| --- | --- |
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
| repo 루트의 라우트별 수동 접근성 기록(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`) | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
| 라우트별 수동 접근성 기록(`accessibility/route-reviews/<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) |
@@ -119,7 +119,7 @@
- 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
- 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
- `artifacts/tests/a11y-manual/`의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(`scripts/lib/manual-a11y-evidence.ts`). 문서 검사가 보지 않는다.
- `accessibility/route-reviews/`의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(`scripts/lib/manual-a11y-evidence.ts`). 문서 검사가 보지 않는다.
## 3. 기록 문서의 머리 블록
+1 -1
View File
@@ -1,7 +1,7 @@
# 수동 접근성 리뷰 체크리스트
자동 axe 검사만으로는 WCAG 준수를 증명하지 못한다. 사람 리뷰어가
`artifacts/tests/a11y-manual/`의 route 기록을 모두 한 release 후보에 대해
`docs/accessibility/route-reviews/`의 route 기록을 모두 한 release 후보에 대해
리뷰하고 서명해야 한다. 필요한 범위는 route
registry(`src/features/installed-feature-contracts.ts`의 `ROUTE_REGISTRY`)다.
route 하나에 기록 하나를 두고, 이름은 `<ROUTE_ID>.md`로 한다. template 필드를
@@ -15,7 +15,7 @@ production readiness를 뜻하지 않는다.
| 항목 | 경로 | production 포함 |
| --- | --- | --- |
| 선택/금지/예산 SSOT | `config/recipes/frontend-capability-recipes.json` | 정책만 |
| catalog JSON schema | `schemas/config/frontend-capability-recipes.schema.json` | 아니오 |
| catalog JSON schema | `config/schemas/recipes/frontend-capability-recipes.schema.json` | 아니오 |
| TypeScript port | `recipes/frontend-capabilities/contracts.ts` | 아니오 |
| fake/unavailable | `recipes/frontend-capabilities/fake-adapters.ts` | 아니오 |
| contract test | `tests/recipes/optional-capability-contracts.test.ts` | 아니오 |
@@ -330,7 +330,7 @@ Web Push를 함께 설치하지 않는다.
## 6. 검증 명령
```bash
corepack pnpm check:types:recipes
corepack pnpm check:types:test
corepack pnpm test:recipes
corepack pnpm test:browser-capabilities
corepack pnpm build
+1 -1
View File
@@ -199,7 +199,7 @@ feature 디렉터리 밖 파일은 아래 표에 있다. feature에 필요한
| `config/scale/feature-shape-ceilings.json` `initialJavascript` (추적 파일) | feature를 더하거나 뺄 때마다, 그리고 초기 JavaScript를 바꾸는 템플릿 변경마다: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. 그 변경과 같은 커밋에 넣는다. 병합 충돌이 나면 명령을 다시 돌린다 | `test:unit`(feature-shape growth 테스트가 이 값을 빌드 결과와 비교한다) |
| `src/contexts/<context>/context-module.ts` | feature에 새 context가 필요할 때 | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
| `src/contexts/<context>/context-layout.tsx` | context에 `AppShell` 대신 자기 틀이 필요할 때(아래 "제품 홈과 레이아웃" 참고) | 없음. 파일이 없으면 context는 `AppShell` 안에서 렌더링된다 |
| `artifacts/tests/a11y-manual/<ROUTE_ID>.md` | feature가 더하는 라우트마다. 기록 하나를 복사해 `Status: pending-manual-review`로 되돌린다 | `test:unit`(`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation`(route ID를 댄다), FE-GATE-009(`review:a11y-manual -- --format-only`). release 때는 FE-GATE-028이 서명된 검토를 요구한다 |
| `docs/accessibility/route-reviews/<ROUTE_ID>.md` | feature가 더하는 라우트마다. 기록 하나를 복사해 `Status: pending-manual-review`로 되돌린다 | `test:unit`(`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation`(route ID를 댄다), FE-GATE-009(`review:a11y-manual -- --format-only`). release 때는 FE-GATE-028이 서명된 검토를 요구한다 |
| `tests/e2e/accessibility.spec.ts` | feature마다 고치지 않는다(1103/16-03). 이 파일은 모든 경로 파라미터를 한 값으로 채우고, 각 API 요청에 설치된 descriptor로 응답한다. 목록 읽기에는 `responseEnvelope` 틀에 담은 빈 목록으로 응답한다. 보호된 페이지가 렌더링 전에 설치된 GET이 아닌 요청을 보낼 때만 고친다 | `test:a11y`(FE-GATE-009): 설치된 GET 어디에도 선언되지 않은 요청이 오면 그 라우트가 실패한다. 목록만 읽은 페이지에 경고 상자(`role="alert"`)가 떠도 실패한다 |
| `src/features/product-capabilities.ts` (제품 소유) | `needs`가 템플릿이 만들지 않는 capability를 가리킬 때: `ProductFeaturePlatformCapabilities`에 그 타입을 적는다. `FeaturePlatformCapabilities`가 이를 확장하므로 app, scripts, tests의 타입 검사 프로그램이 모두 그 키를 본다(`product-composition.ts` 안에 둔 augmentation은 scripts의 프로그램이 보지 못한다) | `check:types`: feature에서 `Type '"<capability>"' is not assignable to type 'keyof FeaturePlatformCapabilities'` |
| `src/bootstrap/product-composition.ts` (제품 소유) | `needs`가 템플릿이 만들지 않는 capability를 가리킬 때: 여기서 그 capability를 돌려준다. 타입은 `product-capabilities.ts`에 적는다. `indexedDb`는 `recipes/frontend-capabilities/indexeddb-feature-capability.ts`처럼 만든다. 제품 인증 프로필의 자격 증명도 여기서 돌려준다. 세션을 직접 소유하는 제품(BFF의 httpOnly 쿠키)은 부팅 전에 host 전역에 세션 owner를 설치하지 않는다. 대신 `composeProductSessionOwner`에서 돌려준다 | `check:types`. 실행 중에는 `feature <id> needs <capability>, which the host did not provide`. 세션 owner가 없으면 `AUTH_MODE: "external"`은 세션이 `integration-failed`인 채로 부팅한다 |
+5 -5
View File
@@ -369,7 +369,7 @@ projectRequest: (input) => Object.freeze({
- application이 React·어댑터·presentation을 import하면 `check:architecture`가 `feature-application-does-not-know-runtime`으로 막는다.
- 보강 키와 조립 기여의 `featureId`가 다르면 조립이 실패한다.
- 메시지: `feature adapter contribution <id> installed an input for <other>`
- input 모양이 보강 타입과 다르면 `check:types`(FE-GATE-003)가 막는다. 음성 fixture `check:types:fixture:feature-input`도 같은 게이트에서 돈다.
- input 모양이 보강 타입과 다르면 `check:types`(FE-GATE-003)가 막는다. 음성 fixture `tests/fixtures/typecheck/invalid-feature-input.ts`도 같은 게이트의 `check:types:fixtures`에서 돈다.
- **못 잡음**: telemetry `kind` 중복. 유일성 검사가 없다. 접두어로 피한다.
④ **쓸 스킬**: `clean-architecture`, `codebase-design`
@@ -408,7 +408,7 @@ projectRequest: (input) => Object.freeze({
- presentation이 기능 `adapters/`를 import하면 `feature-presentation-does-not-know-outbound-adapters`로 막는다.
- adapters가 presentation을 import하면 `feature-adapters-do-not-know-presentation`으로 막는다.
- 기능 루트 파일(`feature-module.ts` 등)이나 계층이 아닌 폴더(`support/` 등)의 파일이 `src/adapters`에 닿으면 `feature-and-app-roots-do-not-reach-adapters`로 막는다. 기능 안에서 `src/adapters`에 닿을 수 있는 곳은 `adapters/` 폴더뿐이다.
- operation ID·route ID·입력 타입을 틀리면 `check:types`가 막는다. 음성 fixture: `check:types:fixture:http-operation-id`, `check:types:fixture:http-route-id`, `check:types:fixture:http-operation-input`.
- operation ID·route ID·입력 타입을 틀리면 `check:types`가 막는다. 음성 fixture: `tests/fixtures/typecheck/invalid-http-operation-id.ts`, `tests/fixtures/typecheck/invalid-http-route-id.ts`, `tests/fixtures/typecheck/invalid-http-operation-input.ts`(`check:types:fixtures`).
- 호스트가 주지 않는 capability를 `needs`에 적으면 조립이 실패한다.
- 메시지: `feature <id> needs <capability>, which the host did not provide`
- operation을 계약에 두고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다.
@@ -430,7 +430,7 @@ projectRequest: (input) => Object.freeze({
- `presentation/<base>-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다.
- 문구 `route.<ROUTE_ID>.title`, `route.<ROUTE_ID>.navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다.
- 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다.
- 기능 폴더 밖: `artifacts/tests/a11y-manual/<ROUTE_ID>.md`(pending 기록). 생성 명령이 만든다.
- 기능 폴더 밖: `docs/accessibility/route-reviews/<ROUTE_ID>.md`(pending 기록). 생성 명령이 만든다.
① **정할 것**
@@ -506,7 +506,7 @@ export function useInvoiceListFilters(): InvoiceListSearch {
- `context-routes.ts`의 handle이 계약에 없는 route ID를 가리키면 context 적재가 거부한다.
- 메시지: `Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (...)`
- 라우트별 a11y 기록이 없으면 세 곳이 잡는다.
- `verify:documentation`(FE-GATE-017): `artifacts/tests/a11y-manual/ has no record for route IDs: <ids>`
- `verify:documentation`(FE-GATE-017): `docs/accessibility/route-reviews/ has no record for route IDs: <ids>`
- `review:a11y-manual -- --format-only`(FE-GATE-009): `missing record`
- `test:unit`의 `tests/unit/manual-a11y-evidence.test.ts`
- en-US 문구 키가 ko-KR과 다르면 `check:i18n`(FE-GATE-010)이 `en-US catalog keys do not match ko-KR`로 실패한다.
@@ -790,7 +790,7 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature
- 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다.
- spec 본문은 이름 단위로 찾는다(1106/16-01). 적힌 그대로(대소문자 구분) 찾고, 앞뒤에 `[A-Za-z0-9_-]`가 붙으면 다른 이름이다. `test.describe("invoice-feature", …)`는 잔여이고, `product-feature`를 지울 때 `generate-product-feature-index.ts`처럼 더 긴 이름 안에 든 것은 잔여가 아니다. spec은 `test:all`(vitest)도 드릴의 다른 단계도 돌리지 않으므로 이 검사가 아니면 다음 CI의 브라우저 게이트에서야 실패한다.
- `-`가 없는 한 단어 ID·폴더 이름(`messages`, `status`)은 spec 본문에서 찾지 않는다. 템플릿 spec이 그 단어를 평범하게 쓰므로(`status: 200`, `getByRole("status")`) 찾으면 템플릿 spec이 잔여로 나온다.
- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec, `artifacts/tests/a11y-manual/<ROUTE_ID>.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec, `docs/accessibility/route-reviews/<ROUTE_ID>.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration`
+49 -3
View File
@@ -24,7 +24,7 @@
- `src/contexts/<context>/context-module.ts`
- 새 context일 때만 만든다. `--context`를 주면 만들지 않는다.
- 왜 밖인가: context는 여러 기능이 함께 쓰는 소속 선언이다. 기능 하나가 갖지 않는다.
- `artifacts/tests/a11y-manual/<ROUTE_ID>.md`
- `docs/accessibility/route-reviews/<ROUTE_ID>.md`
- 라우트마다 하나. `Status: pending-manual-review`로 만든다.
- 왜 밖인가: 수동 접근성 검토 기록은 라우트 단위로 한 폴더에 모은다. 릴리스 검토자가 한 곳에서 서명한다.
- pending 기록은 merge 게이트를 통과하고 릴리스 게이트를 넘지 못한다(원칙 7).
@@ -62,7 +62,7 @@ create:feature가 pending 기록을 만든다
1. 릴리스 후보 하나를 띄운다.
2. `docs/accessibility/manual-checklist.md`의 M1~M7과 스크린 리더 항목을 그 라우트에서 확인한다.
3. `artifacts/tests/a11y-manual/<ROUTE_ID>.md`를 채운다.
3. `docs/accessibility/route-reviews/<ROUTE_ID>.md`를 채운다.
- `Status: reviewed`, `Release ID`, `Reviewer`, `Reviewed at`, `Signature`, `Attestation: accepted`
- 항목마다 `pass` 또는 `not-applicable (<구체적 이유>)`
4. 모든 라우트 기록의 `Release ID`가 같아야 한다.
@@ -184,6 +184,28 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
- 템플릿이 아직 연결하지 않은 것: 활성화 화면(`onUpdateWaiting`·`requestActivation()`). 확인할 것 목록은 `docs/architecture/optional-adapter-recipes.md`의 "Service Worker를 켤 때 확인할 것"에 있다.
- realtime·Web Worker·오프라인 명령을 고르면 조립이 `Selected optional capabilities have no runtime to start them`로 거절한다. 템플릿 조립에 아직 그 런타임이 없다.
### Web Worker를 들일 때 tsconfig 더하기
템플릿에는 Web Worker 코드가 없다. 그래서 Worker용 tsconfig도 없다. 빈 tsconfig는 0파일을 검사하고 통과한다(아래 E절 R8). 2026-11-08에 지웠다. Worker 코드를 처음 넣는 변경에서 아래를 함께 한다.
1. Worker 코드를 `src/adapters/web-worker/`에 둔다. 그 폴더의 `index.ts`가 배럴이다.
2. 루트에 `tsconfig.web-worker.json`을 만든다. lib가 `WebWorker`이고 DOM이 없어서, Worker 코드가 `document`·`window`를 쓰면 실패한다. `tsconfig.service-worker.json`과 같은 이유다.
```json
{
"extends": "./tsconfig.base.json",
"compilerOptions": { "lib": ["ES2022", "WebWorker"], "types": [], "skipLibCheck": false },
"include": ["src/adapters/web-worker"],
"exclude": ["src/adapters/web-worker/index.ts"]
}
```
3. Worker 진입 파일을 `tsconfig.app.json`의 `exclude`에 더한다. 배럴처럼 페이지가 import하는 파일은 app 프로그램에 남긴다.
4. `tsconfig.json`의 `references`에 `{ "path": "./tsconfig.web-worker.json" }`을 더한다. 편집기가 Worker 파일에 이 설정을 쓴다.
5. `package.json`에 `"check:types:web-worker": "tsc --project tsconfig.web-worker.json"`을 더하고 `check:types` 사슬에 잇는다. 사슬 끝의 `node scripts/check-typecheck-inputs.ts`가 이 tsconfig의 입력이 0개면 실패시킨다.
6. `config/repository-layout.json`에 `tsconfig.web-worker.json` 항목을 더한다(E절 R1). `sets`는 `tsconfig.service-worker.json`과 같게 `fixture-copy`·`secret-scan`이다. `config/security/secret-scan-policy.json`의 `trackedRoots`에도 같은 이름을 더한다(R2).
7. `scripts/verify-documentation-readiness.ts`의 `NOT_CREATED`에서 `src/adapters/web-worker`를 뺀다.
---
## D. 고치지 않는다
@@ -199,13 +221,37 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
---
## E. 저장소 배치 규칙 (R1~R10)
기능 밖의 루트 폴더·설정·검사를 더하거나 옮길 때 지킨다. 2026-11-07 소유자 지적(샘플이 남아 있음, 역할이 겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)이 다시 나오지 않게 하는 규칙이다. 설계와 근거는 design-docs `repo-structure/04-frontend-layout.md` 11절이다.
| ID | 규칙 | 검사 |
| --- | --- | --- |
| R1 | 루트 항목은 모두 `config/repository-layout.json`에 있다. 항목마다 종류(source·tool-convention·gate-input·document·history·output), 역할, 읽는 곳을 적는다 | `tests/unit/repository-layout.test.ts`(FE-GATE-005). 등록부에 없는 루트 항목이 추적되면 실패 |
| R2 | 루트 경로 목록은 등록부의 이름 붙은 집합(`sets`, 하위 경로는 `setPaths`)에서만 고른다. 목록을 코드에 새로 적지 않는다. JSON 정책 파일(`config/security/secret-scan-policy.json`)은 그 집합의 사본을 갖고 시험이 같은지 본다 | 같은 시험. 목록을 쓰던 곳이 `scripts/lib/repository-layout.ts`를 import하는지, 루트 이름 두 개 이상의 문자열 배열이 없는지 |
| R3 | 추적 파일은 읽는 곳이 있다. `artifacts/`는 출력 전용이라 `.gitkeep`만 추적한다. 사람이 쓴 기록은 `docs/` 아래에 둔다(수동 a11y 기록은 `docs/accessibility/route-reviews/`) | `tests/unit/tracked-artifacts.test.ts`(FE-GATE-005). `config/` 아래 고아 JSON은 리뷰가 본다 |
| R4 | 템플릿이나 제품이 넣은 샘플 기능은 `scripts/lib/removable-template-features.ts` 목록에 있고, 복사본에서 지우고 빌드·시험하는 drill로 증명한다. 문서 검사만으로는 안 된다 | `tests/unit/example-feature-rules.test.ts`(FE-GATE-005). FE-GATE-020이 `test:sample-removal`을 목록 전체로 도는지 |
| R5 | 게이트의 검사 대상(visual 골든, e2e 라우트, 게이트 증거 목록, 규모 측정)은 플랫폼 화면·시험 fixture·생성기 출력이다. 지울 샘플 기능이 아니다 | 같은 시험. 샘플의 기능 ID·라우트가 visual·e2e의 `goto`, `config/ci/gates.json` 산출물 경로, `config/scale/`에 나오면 실패 |
| R6 | 매뉴얼의 예제 위치는 `create:feature` 출력이나 매뉴얼 안 코드 조각을 가리킨다. 지울 샘플 기능의 경로를 가리키지 않는다 | `verify:documentation`(FE-GATE-017). `docs/manual/`에 목록 샘플의 경로가 나오면 실패 |
| R7 | 이 repo에 둘 수 있는 실행 환경 파일은 개발 의존 서비스용 compose와 개발 Dockerfile뿐이다. nginx·Kubernetes·Helm·Terraform 설정은 인프라 repo에 두고 링크한다. 호스트에 요구하는 것은 계약(`config/hosting/`)과 검사(FE-GATE-019)로 둔다 | 파일: `tests/unit/repository-layout.test.ts`(FE-GATE-005). 문서: `verify:documentation`(FE-GATE-017)이 현재 문서의 ```` ```nginx ````·```` ```hcl ```` 블록과 `kind: Deployment` 같은 매니페스트 줄을 막는다. 이력 폴더(`docs/history/`, `docs/reviews/`, `docs/superpowers/`)는 기록이라 보지 않는다 |
| R8 | 검사 대상이 0개인 게이트 명령은 실패하거나 SKIP을 출력한다. 통과로 보이면 안 된다 | FE-GATE-003: `scripts/check-typecheck-inputs.ts`(package script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상), `scripts/check-type-fixtures.ts`(fixture 0개면 실패) |
| R9 | tsconfig는 lib·types·모듈 해석 중 하나가 다를 때만 새로 만든다. 옵션이 같고 파일만 다르면 실행기 하나로 돈다(예: 음성 타입 fixture는 `check:types:fixtures` 하나) | `tests/unit/repository-layout.test.ts`(FE-GATE-005). 옵션이 같은 tsconfig 쌍이 있으면 실패 |
| R10 | 이력 문서(끝난 라운드의 계획·작업 목록·보고)는 루트나 숨김 폴더에 두지 않고 이력 폴더 한 곳에 둔다. 정본으로 쓰이는 부분은 이력에 두지 않는다 | 루트 `*.md`는 R1 등록부에 종류와 함께 있어야 한다. "정본으로 쓰이는가"는 리뷰가 본다 |
루트 항목을 더하거나 옮길 때의 순서:
1. `config/repository-layout.json`에 항목을 더하거나 고친다. 종류·역할·읽는 곳을 적는다(R1).
2. 그 항목이 들어갈 집합을 `sets`(항목 전체)나 `setPaths`(항목 안 경로)에 적는다. 집합의 뜻은 파일 머리의 `sets` 설명에 있다(R2).
3. `secret-scan` 집합을 바꿨으면 `config/security/secret-scan-policy.json`의 `trackedRoots`도 같게 고친다.
4. 새 tsconfig라면 R9를 먼저 본다. 다른 tsconfig와 옵션이 같으면 만들지 않는다.
## 기능을 지울 때
`corepack pnpm test:sample-removal -- --feature=<id>`는 복사본에서 지워 보고 게이트를 돈다. 실제 저장소에서 지울 때는 아래를 함께 지운다.
- `src/features/<id>/`, `tests/features/<id>/`
- 그 context의 마지막 기능이면 `src/contexts/<context>/`
- `artifacts/tests/a11y-manual/<ROUTE_ID>.md` (라우트마다)
- `docs/accessibility/route-reviews/<ROUTE_ID>.md` (라우트마다)
- 남아도 검사는 실패하지 않는다. 검사는 등록된 라우트의 기록만 읽는다. 그래서 잊기 쉽다.
- 기능 전용 `tests/e2e/` spec
- `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` 키
+4 -4
View File
@@ -81,7 +81,7 @@ corepack pnpm create:feature <id> [--context <context id>] [--with-create [--key
기능 폴더 밖:
- `src/contexts/<base>-context/context-module.ts`: 새 context일 때만
- `artifacts/tests/a11y-manual/<ROUTE_ID>.md`: 라우트마다 pending 기록
- `docs/accessibility/route-reviews/<ROUTE_ID>.md`: 라우트마다 pending 기록
## 뼈대 모양
@@ -95,7 +95,7 @@ corepack pnpm create:feature <id> [--context <context id>] [--with-create [--key
- 쿼리 1개: `LIST_STANDARD` profile.
- 무효화 topic 1개, namespace 1개, edge 1개.
- 빈 배열 응답은 공유 빈 상태 화면으로 그린다. `tests/e2e/accessibility.spec.ts`는 이 목록 조회에 빈 목록을 Envelope 모양으로 답하고, 경고 상자가 없는지 본 뒤 axe를 돌린다. 그래서 생성한 목록 라우트는 빈 상태 화면으로 검사된다.
- `--with-create`의 상세 라우트는 자원 하나를 읽는다. 빈 목록으로 답할 수 없어 실패 화면에서만 axe를 돌린다. 그래서 `artifacts/tests/a11y.json`은 이 라우트를 통과(`scope`)로 세지 않고 `notChecked`에 이유와 함께 적는다. 화면 내용의 접근성은 수동 검토 기록(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`)이 맡는다.
- `--with-create`의 상세 라우트는 자원 하나를 읽는다. 빈 목록으로 답할 수 없어 실패 화면에서만 axe를 돌린다. 그래서 `artifacts/tests/a11y.json`은 이 라우트를 통과(`scope`)로 세지 않고 `notChecked`에 이유와 함께 적는다. 화면 내용의 접근성은 수동 검토 기록(`docs/accessibility/route-reviews/<ROUTE_ID>.md`)이 맡는다.
한도·마감 같은 숫자는 `scripts/create-feature.ts`의 템플릿이 정본이다.
@@ -119,7 +119,7 @@ create:feature: <id> in <context> (new context), route <ROUTE_ID> at <path>
created <파일> ...
Next:
1. Before a release, have a person review and sign artifacts/tests/a11y-manual/<ROUTE_ID>.md (FE-GATE-028). ...
1. Before a release, have a person review and sign docs/accessibility/route-reviews/<ROUTE_ID>.md (FE-GATE-028). ...
2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage ...
The feature's own tests: node scripts/run-vitest.ts run tests/features/<id> ...
The registry baseline does not change: ...
@@ -138,7 +138,7 @@ create:feature warning: no --package was given, so src/features/<id>/contracts/<
생성한 기능을 지우려면 만든 것을 지우고 생성기를 다시 돌린다.
```bash
rm -r src/features/<id> tests/features/<id> artifacts/tests/a11y-manual/<ROUTE_ID>.md
rm -r src/features/<id> tests/features/<id> docs/accessibility/route-reviews/<ROUTE_ID>.md
rm -r src/contexts/<base>-context # 새 context를 만들었을 때만
corepack pnpm generate:feature-index
node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의 계약 패키지를 뺀다
+2 -2
View File
@@ -175,8 +175,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `artifacts/tests/a11y-manual/ has no record for route IDs: <ids>` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 |
| `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/<ROUTE_ID>.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 |
| `docs/accessibility/route-reviews/ has no record for route IDs: <ids>` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 |
| `Manual accessibility record format is invalid:` 다음 `docs/accessibility/route-reviews/<ROUTE_ID>.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 |
| `a11y.json not written:` 다음 `a11y: <ROUTE_ID> reads one resource (<operationId>) but has no failure-state record in artifacts/tests/a11y-data-state` (`test:a11y`, FE-GATE-009) | 라우트의 `paramsSchema`가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록이 없다(1106/11-01). spec이 기록 호출을 놓쳤거나, 그 라우트의 페이지가 그 GET을 부르지 않아 spec이 실패 화면을 보지 않았다. 앞의 경우 그대로면 `a11y.json`이 그 라우트를 통과로 센다 | 페이지가 그 GET을 부르면 `tests/e2e/accessibility.spec.ts`의 기록 호출(`recordA11yDataState`)을 본다. 이때 기능 파일은 고치지 않는다. 페이지가 그 GET을 부르지 않으면(예: `/things/:thingId/parts/new` 같은 하위 항목 작성 폼이 상세 GET과 같은 `ThingParams`를 쓴다) 그 라우트에 자기 `paramsSchema`를 따로 둔다. 기능의 라우트 계약과 `contracts/<base>-schema-metadata.ts`를 고친다 |
| `Manual accessibility evidence is incomplete:` 다음 `<ROUTE_ID>: <failures>` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) |
| `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 |
+1 -1
View File
@@ -50,7 +50,7 @@
- 형식: `qinv.` + 소문자·숫자 26자.
- `scripts/create-feature.ts`의 `randomTopicSuffix`가 같은 형식으로 만든다.
- 다른 기능의 값을 복사하지 않는다.
- route ID는 `<BASE>_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`).
- route ID는 `<BASE>_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`docs/accessibility/route-reviews/<ROUTE_ID>.md`).
- 문구 키는 ko-KR과 en-US에 같은 키를 넣는다. `check:i18n`이 비교한다.
## 정본 위치
@@ -126,7 +126,7 @@ AssertionError: expected [] to deeply equal ArrayContaining{…}
| BT-UP-05 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | — | `NOT_PERFORMED` | 동작 기록(characterization) drift | **시도했다가 되돌렸다.** 내부 owner 다섯 개는 기계적으로 뽑아냈다. 그러나 import 순환을 피하려면 `RuntimeDependencies`, `ActiveResolution`, `ReconciliationResolution`, `FAILURE_CODES`, `RECOVERIES`, `reportProgress`, `observeTerminal`과 바인딩 약 40개를 더 담은 공유 내부 모듈이 필요했다. 이 파일에서 검증한 정확성 작업을 위험에 빠뜨리지 않으려고, 반만 반영하지 않고 추출을 되돌렸다. 동작과 공개 facade는 그대로다. 파일은 여전히 2,239줄이다. |
| BT-UP-06 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | `fix: drain resumable upload teardown` | `FIXED_NOT_RELEASED` | drain 뒤에도 작업이 남음 | 실패: single-flight dispose 사례 → 통과 18/18. `close()`는 새 작업 받기를 닫고 같은 drain을 시작한다. `dispose()`는 active-operation registry를 중단하고, 실제로 끝나기를 기다린 뒤 checkpoint store를 닫는다 |
| BT-UP-07 | 문서에 적힌 빈틈(Web Locks 매트릭스) | promotion 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
| BT-IMG-01 | 타입 계약 변경 | `corepack pnpm check:types:test` fixture | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | 호출부 컴파일 깨짐 | `resolve()`는 이제 lifetime signal을 요구한다. `tests/fixtures/typecheck/invalid-image-cdn-resolve-signal.ts` + `check:types:fixture:image-resolve-signal`은 설계대로 실패하고(오류 2개), 모든 호출부가 signal을 넘긴다 |
| BT-IMG-01 | 타입 계약 변경 | `corepack pnpm check:types:test` fixture | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | 호출부 컴파일 깨짐 | `resolve()`는 이제 lifetime signal을 요구한다. `tests/fixtures/typecheck/invalid-image-cdn-resolve-signal.ts`(그때는 전용 script였고, 2026-11-08 `check:types:fixtures`로 합쳤다)는 설계대로 실패하고(오류 2개), 모든 호출부가 signal을 넘긴다 |
| BT-IMG-02 | Image probe | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | `fix: parse Cache-Control with quote awareness` | `FIXED_NOT_RELEASED` | Cache-Control 파싱 거부 | 실패: 짝 없는 따옴표 사례 → 통과 25/25 |
| BT-IMG-03 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | — | `NOT_PERFORMED` | 동작 기록(characterization) drift | **하지 않았다.** BT-UP-05와 같은 이유다. `image-cdn-runtime.ts`(1,340줄)의 순수 응집도 리팩터링이고, 이것으로 닫히는 발견이 없다. `image-header-metadata.ts`는 리뷰에 따라 일부러 그대로 뒀다. |
| BT-IMG-04 | 문서에 적힌 빈틈(descriptor provider) | promotion 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
@@ -186,7 +186,7 @@ AssertionError: expected [] to deeply equal ArrayContaining{…}
| `corepack pnpm test:unit` | 1 | 테스트 1585개 통과 / 19개 실패. 19개는 원래 있던 그대로인 `ci-artifact-contract` sandbox 실패다 |
| `corepack pnpm check:registries` | 0 | registry 11개 PASS |
| `corepack pnpm verify:documentation` | 0 | PASS_SCOPED |
| `corepack pnpm check:types:fixture:image-resolve-signal` | 1 | **0이 아닌 것이 정상이다.** `resolve()`가 이제 lifetime signal 없는 호출을 거부함을 보이는 음성 fixture다(BT-IMG-01). |
| 음성 fixture `invalid-image-cdn-resolve-signal.ts` 단독 tsc(그 script는 2026-11-08 `check:types:fixtures`로 합쳤다) | 1 | **0이 아닌 것이 정상이다.** `resolve()`가 이제 lifetime signal 없는 호출을 거부함을 보이는 음성 fixture다(BT-IMG-01). |
`test:all`은 `test:unit`에서 멈춘다. 그래서 위의 나머지 테스트는 직접 돌렸다.
+17 -27
View File
@@ -6,33 +6,24 @@
`corepack pnpm generate:ci-workflow`를 돌린 뒤, 생성된 바이트를 함께 커밋한다.
`corepack pnpm check:ci-workflow`는 빠졌거나, 낡았거나, CRLF이거나, 그 밖에 바이트가 다른
출력을 거절한다. `corepack pnpm check:ci`는 산출물 schema 검사, 타입이 있는 계약 검사기,
이 workflow drift 검사를 돈다. Gitea adapter는 게이트마다 독립된 matrix check로 돌린다.
모두 펼쳐서(full fan-out) 돌리고, 실패를 무시하는(soft-fail) 연결은 없다.
이 workflow drift 검사를 돈다. merge 단계는 job 셋(`merge_static`, `merge_test`,
`merge_browser`)으로 돌고 job마다 설치를 한 번 한다. 게이트마다 ID 이름의 step이 하나씩
있고, 실패한 게이트가 다음 게이트를 건너뛰게 하지 않는다. 검사기 자신의 음성 fixture와
gating 검사는 branch에 push한 뒤 main 단계(`main_gate`, FE-GATE-029)에서 돈다. release와
production 게이트는 matrix check로 남는다. 실패를 무시하는(soft-fail) 연결은 없다.
## 기준선 갱신과 새 프로젝트 시작 시 초기화할 기준선
게이트 계약의 크기와 모양은 코드 상수가 아니라 `config/ci/contract-baseline.json`에
있다. 이 파일에는 게이트 수, 명령 정의 수, 명령 참조 수, 산출물 수, stage 수,
게이트 모양 SHA-256과 함께 `owner`·`reason`이 들어 있다. 계약을 불러올 때 현재
`gates.json`과 이 파일이 다르면 실패한다(`scripts/contracts/ci-gates.ts`의
`assertCiContractBaseline`). 그래서 게이트·명령·산출물을 추가하거나 지운 뒤에는
다음 순서로 커밋한다.
게이트·명령·산출물 수와 게이트 모양 해시를 따로 기록하던 기준선 파일은 2026-11-08에
지웠다(소유자 결정, design-docs `repo-structure/README.md` 3.3절). 계약의 모양은
`scripts/contracts/ci-gates.ts`의 의미 검사(게이트·job·stage 소유와 순서)가 지킨다.
게이트·명령·산출물을 바꾼 뒤에는 `corepack pnpm generate:ci-workflow`와
`corepack pnpm check:ci`를 돌리고 생성된 workflow를 함께 커밋한다. 제거 검증
(`test:*-removal`)은 줄인 계약을 그대로 불러 canonical `check:ci`를 돌린다
(`scripts/lib/removal-fixture.ts`의 `pruneRemovalFixtureCiContract`).
```
# 1. config/ci/gates.json 수정
CI_CONTRACT_BASELINE_OWNER=<팀> CI_CONTRACT_BASELINE_REASON=<이유> corepack pnpm update:ci-contract-baseline
corepack pnpm generate:ci-workflow
corepack pnpm check:ci
```
`update:ci-contract-baseline`은 `scripts/update-ci-contract-baseline.ts`를 실행한다.
리뷰는 `contract-baseline.json`의 diff로 변경을 승인한다. 샘플·recipe·런타임 제거
검증(`test:*-removal`)도 같은 절차를 쓴다. 줄인 계약을 기준선으로 기록한 뒤
canonical `check:ci`를 돌린다(`scripts/lib/removal-fixture.ts`의
`pruneRemovalFixtureCiContract`). 완화 모드는 없다.
`check:ci`는 `tests/` 아래 테스트 파일(`tests/fixtures` 제외)이 모두 CI 게이트
명령에서 실행되는지도 확인한다. 게이트 명령이 닿는 package script의 Vitest 경로와
`check:ci:gating`(main 단계 FE-GATE-029)은 `tests/` 아래 테스트 파일(`tests/fixtures` 제외)이 모두 CI 게이트
명령에서 실행되는지 확인한다. 게이트 명령이 닿는 package script의 Vitest 경로와
Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests.ts`).
`run-scale-profile.ts <tier>`를 부르는 명령은 그 tier의 Vitest 경로로 센다.
게이트가 돌리지 않는 테스트는 `config/ci/ungated-tests.json`에 이유와 함께 적어야
@@ -62,7 +53,6 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경
| 기준선 | 파일 | 갱신 방법 | 검사 위치 |
|---|---|---|---|
| CI 계약 크기·게이트 모양 | `config/ci/contract-baseline.json` | `update:ci-contract-baseline` (`CI_CONTRACT_BASELINE_OWNER`·`_REASON` 필수) | `scripts/contracts/ci-gates.ts` `assertCiContractBaseline` |
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다. 지금 diff의 breaking 변경과 changeId가 맞지 않는 항목이 있으면 게이트가 그 항목을 나열하며 실패한다. `update:registry-baseline`은 새 기준선이 설명하는 항목을 모두 지운다(지운 항목은 git 이력에 남는다) | `scripts/check-registries.ts`의 baseline 비교 |
| 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" |
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 09-09) |
@@ -121,7 +111,7 @@ DOCUMENTATION_READY (off-chain)
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
(`scripts/verify-documentation-readiness.ts`).
- 설치된 라우트마다 수동 접근성 기록 `artifacts/tests/a11y-manual/<ROUTE_ID>.md`가
- 설치된 라우트마다 수동 접근성 기록 `docs/accessibility/route-reviews/<ROUTE_ID>.md`가
있는지. 없으면 route ID를 적고 실패한다
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
- 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을
@@ -396,8 +386,8 @@ hosting 게이트 FE-GATE-019도 `.release/promoted-release`를 읽는다. 그 a
`{ "id": "PRODUCT-GATE-001", "name": "backend-contract", "script": "check:backend-contract" }`이다.
ID는 `PRODUCT-GATE-NNN`이다. `FE-GATE-NNN` ID와 그 명령, 산출물, 준비 상태 공식은
템플릿의 것으로 남는다. 각 검사는 `product_merge_gate` job에서 `corepack pnpm <script>`로
돈다. 조건은 `merge_gate`와 같다. 브라우저 없이, `ci:gate`의 게이트 log와 evidence
산출물 없이 돈다. `release_gate`는 `merge_gate`를 기다리듯 그 job도 기다린다. 그래서
돈다. 조건은 merge job들과 같다. 브라우저 없이, `ci:gate`의 게이트 log와 evidence
산출물 없이 돈다. `release_gate`는 merge job들을 기다리듯 그 job도 기다린다. 그래서
제품 게이트가 실패하면 같은 run의 release 빌드, 승격, 배포도 멈춘다(1105/13-02). 제품
게이트가 없으면 workflow는 템플릿의 것 그대로다. pull request merge를 막는 것은 branch의
required check다. 그러니 merge를 막아야 하는 곳에서는 이 job을 required check로 만든다.
+92
View File
@@ -0,0 +1,92 @@
# check-*.ts 이전 판정 (F3)
- 작성일: 2026-11-08, 기준 커밋 `ad3a071f`(정리 2단계 끝)
- 정본 설계: design-docs `repo-structure/03-ci.md` 7.3절 F3. 이 문서는 판정만 남긴다. 코드는 바꾸지 않았다.
- 상태: 판정 표. 옮기는 작업은 이 표를 근거로 따로 한다.
- 판정 뒤 바뀐 것(2026-11-08): check-optional-recipe-types.ts는 정리 3단계에서 지웠다. `*:fixture` 자기 시험 명령은 merge 게이트에서 main 단계 FE-GATE-029로 옮겼고, CI 계약 기준선 파일은 지웠다. 아래 표의 게이트 칸은 판정 시점(`ad3a071f`) 값이다.
대상: `scripts/check-*.ts` 30개, 6,351줄. 코드를 읽고 판정했다. pnpm·tsc·테스트는 돌리지 않았다.
줄 번호는 모두 `git show ad3a071f:<파일>` 기준이다.
## 요약
**판정별 개수**
- ESLint 규칙: 1개 (check-realtime-boundaries)
- dependency-cruiser 규칙: 단독으로 옮길 스크립트 0개. 다만 다른 스크립트 안의 import 검사 일부를 옮길 수 있다(design-system, optional-recipes).
- 테스트: 8개 (adapter-inventory, browser-file-storage-boundaries, optional-recipe-fixtures, realtime-boundary-fixtures, registry-compatibility-fixtures, request-fanout, security-fixtures, supply-chain-fixtures). 합계 1,135줄.
- 일부 이전: 9개 (app-build-input, architecture, browser-security, design-system, diagnostics, i18n, optional-recipes, registries, test-evidence). 이 중 diagnostics와 i18n은 나눠서 전부 옮길 수 있어 스크립트를 지울 수 있다.
- 스크립트 유지: 11개 (backend-contract-drift, bundle, ci-contract, compatibility, frozen-lockfile-fixture, release-admission, remediation-ledger, risk-coverage, supply-chain-provider-fixtures, system-test-prerequisites, v8-coverage-counter-semantics)
- 삭제함(정리 3단계): 1개 (optional-recipe-types)
**위험이 낮고 효과가 큰 후보 5개**
1. **check-request-fanout**: 같은 검사가 `tests/architecture/request-fanout.test.ts:11-24`에 이미 있고, fixture 확인은 테스트 쪽이 더 엄격하다. CLI(`:157-185`), package script, gate 명령 1개만 지우면 된다. 증거 artifact가 없다.
2. **check-app-build-input 기본 모드**: 더 강한 같은 검사가 `tests/architecture/app-build-input.test.ts:87-92`에 이미 있다. FE-GATE-010의 `check-app-build-input` 명령만 지우고 `:bundle`은 남긴다.
3. **check-browser-file-storage-boundaries**: 이미 있는 ESLint 규칙을 검증하는 207줄짜리 메타 테스트다. `pnpm exec eslint`를 약 19번 띄우는데, vitest에서 ESLint API로 옮기면 프로세스 하나로 끝난다. 증거 artifact가 없다.
4. **check-realtime-boundaries + check-realtime-boundary-fixtures + lib**(합계 219줄): 소스 정규식 검사라 ESLint 로컬 규칙과 fixture 테스트로 옮기기 좋다. 대신 증거 1개(FE-GATE-010)와 실시간 삭제 드릴(FE-GATE-020)을 함께 고쳐야 한다.
5. **check-supply-chain-fixtures, check-registry-compatibility-fixtures**(217줄): 메모리 안의 값으로 lib 함수만 부르므로 unit test로 그대로 옮길 수 있다. 코드 쪽 위험은 거의 없다. 대신 증거 2개(FE-GATE-013·010)의 계약이 바뀌므로 contract-baseline 재승인이 필요하다.
덤으로 할 수 있는 작은 정리가 둘 있다. check-i18n의 카탈로그 비교는 이미 `tests/unit/i18n-contract.test.ts:27-38`과 겹친다. check-diagnostics의 `console.` 검사는 ESLint 기본 규칙 `no-console`로 바로 바꿀 수 있다(지금 src에 console 사용 0건).
**옮기기 전에 알아둘 공통 제약**
- **"dependency-cruiser 규칙"의 실제 범위**: 이 말은 `.dependency-cruiser.json`에 forbidden 규칙을 추가한다는 뜻이다. 실제 dependency-cruiser는 돌지 않는다. `check-architecture.ts`의 자체 Babel 그래프가 이 파일을 규칙 파일로 읽는다(`check-architecture.ts:103-106`). 지원하는 것은 forbidden(from/to path, circular)뿐이다. `allowed`·`required`를 넣으면 바로 throw한다(`:93-99`). 그래서 "이 파일은 반드시 X를 import해야 한다" 같은 검사는 이 경로로 옮길 수 없다.
- **이미 막히는 import**: 설치되지 않은 패키지 import와 src 밖으로 나가는 상대 import는 check:architecture가 이미 unresolved로 실패시킨다(`check-architecture.ts:250,310,508`).
- **증거 artifact 계약**: gates.json에 `command-generated` 증거로 등록된 파일을 만드는 스크립트를 지우면, `run-ci-gate.ts:198-205`가 "freshly produced 아님"으로 게이트를 실패시킨다. 그래서 다음을 같이 고쳐야 한다.
- gates.json의 `artifacts`·`artifactSchemas`·`evidenceArtifactIds`
- `scripts/contracts/ci-gates.ts:209-240`의 스키마 id 목록
- `scripts/contracts/release-artifacts.ts`의 스키마
- 생성 workflow와 ci-workflow-generation 스냅샷
- CI 계약 기준선(승인자·사유). 2026-11-08에 지웠다
- **실패를 보고하는 게이트가 바뀐다**: `tests/unit`은 test:unit과 test:coverage(FE-GATE-005)에서 돈다. `tests/architecture`는 test:coverage에서만 돈다(package.json:51,82). 따라서 FE-GATE-010·013에 있던 확인을 테스트로 옮기면 그 게이트 로그에서 빠지고 FE-GATE-005로 간다.
- **ESLint 설정**: flat config는 같은 규칙 이름의 옵션을 합치지 않고 덮어쓴다(`eslint.config.ts:909-910` 주석). 새 금지 규칙을 레이어별 `no-restricted-*` 옵션에 끼워 넣으면 서로 덮어쓴다. `build-env/*`, `browser-data-boundary/*`처럼 로컬 규칙 이름으로 따로 둔다. 또 금지 fixture는 ignores(`:500-511`)에 걸린다. 테스트에서는 `new ESLint({ ignore: false })`를 쓰거나 `lintText(source, { filePath })`에 가상 경로를 줘서 돌린다.
- **script 이름을 부르는 곳**: 삭제 드릴과 스케일 검증이 package script를 이름으로 부른다. 옮길 때 이 목록도 같이 고친다.
- `test-sample-removal.ts:475-482`
- `test-realtime-runtime-removal.ts:39-40,95-97`
- `test-browser-file-storage-runtime-removal.ts:55,145`
- `test-optional-recipe-removal.ts:47-48`
- `verify-extreme-scale.ts:28-31`
## 판정표
| 스크립트 | 줄 | 게이트·script | 검사 내용 | 판정 | 근거 | 위치 | 크기 |
|---|---|---|---|---|---|---|---|
| check-adapter-inventory.ts | 259 | `check:adapter-inventory` → FE-GATE-010 | 다섯 가지를 확인한다: ① `git ls-files src/adapters`와 INVENTORY.md 표·합계가 같은지 ② SW 에셋 생성기가 공용 확장자 표를 쓰는지 ③ node_modules를 symlink로 직접 잇지 않는지 ④ 지정한 4개 파일이 `platform/abortable-operation.ts`를 import하는지 ⑤ 손으로 짠 abort 리스너 파일이 13개 이하인지 | 테스트 | git ls-files·git grep과 저장소 파일만 읽는다. 빌드와 증거 artifact가 없어 vitest로 그대로 옮길 수 있다. ④는 required 규칙이어서 `.dependency-cruiser.json`으로는 못 옮긴다(엔진이 거부). 잃는 것: 실패 위치가 FE-GATE-010에서 FE-GATE-005로 바뀐다. 주석 두 곳이 이 스크립트 이름을 가리키므로 같이 고친다. | check-adapter-inventory.ts:24,58-74,77-94,100-126,139-189,215-237; check-architecture.ts:93-99; src/adapters/platform/index.ts:5; .dependency-cruiser.json:266; gates.json:410 | 작음 |
| check-app-build-input.ts | 143 | `check:app-build-input` → FE-GATE-010<br>`check:app-build-input:bundle`(`--require-bundle`) → FE-GATE-012 | 생성된 feature·context 인덱스가 현재 앱이 소유한 feature·context만 가져오는지 본다. `--require-bundle`이면 빌드 모듈 목록에 다른 앱의 feature가 섞였는지도 본다 | 일부 이전 | 기본 모드: `tests/architecture/app-build-input.test.ts:87-92`가 같은 함수로 이미 검사한다. 생성된 import가 소유 목록과 같은지까지 보므로 더 강하다. FE-GATE-010 명령만 지우면 된다. `--require-bundle`: 빌드 산출물(`artifacts/quality/vite-module-inventory.json`)이 필요해 스크립트로 남긴다. 증거 artifact 없음. 고칠 곳: ungated-scripts.test.ts:57, verify-extreme-scale.ts:28 | check-app-build-input.ts:85-108,121-130; tests/architecture/app-build-input.test.ts:87-92; package.json:149-150; gates.json:313,430 | 작음 |
| check-architecture.ts | 1188 | `check:architecture` → FE-GATE-010 | src import 그래프를 직접 만들어 `.dependency-cruiser.json`의 forbidden 규칙, 순환, 해석 안 되는 import를 검사한다. 이 밖에 그래프 엔진 자기검사(fixture 그래프 7개), JS 파일 금지, 레이어별 ESLint fixture 검사를 한다 | 일부 이전 (우선순위 낮음) | 그래프와 규칙 판정은 남긴다. 이 파일이 곧 이 repo의 "dependency-cruiser"다. 진짜 dependency-cruiser는 TS 7을 못 읽어서 쓰지 않는다. 엔진 자기검사(runGraphFixtureChecks 약 290줄), JS 금지 정책, lint fixture는 결정적이라 테스트로 옮길 수는 있다. 걸리는 점 두 가지: 그래프 함수가 export되지 않아 lib로 먼저 빼야 한다. 그리고 `dependency-report.json`(FE-GATE-010 증거)의 `fixtureChecks`·`typeScriptOnlySourcePolicy` 필드가 빠져 스키마가 바뀐다. 줄어드는 양에 비해 손이 많이 간다 | check-architecture.ts:93-99,103-106,135-136,205-218,754,1046; gates.json:303,1175 | 큼 |
| check-backend-contract-drift.ts | 198 | `check:backend-contract-drift` (게이트 없음, 일부러 제외) | 옆에 있는 백엔드 checkout을 본다. 고정 커밋 문서와 발췌표·답변표가 같은지, 고정 커밋 이후 문서와 scaffold 파일이 바뀌었는지 확인한다 | 스크립트 유지 | 다른 저장소 checkout과 git(rev-parse, show, diff)이 필요하다. 비교하지 못하면 exit 2를 낸다. CI는 이 저장소만 checkout하므로 게이트에서 돌 수 없다. 답변표와 발췌표 비교는 이미 test:unit(backend-contract-pin.test.ts)에 있다 | check-backend-contract-drift.ts:72-90,106-123,152-180; config/ci/ungated-scripts.json:5-6 | — |
| check-browser-file-storage-boundaries.ts | 207 | `check:browser-file-storage-boundaries` → FE-GATE-010 | 브라우저 저장소·파일 API ESLint 규칙이 허용 fixture는 통과시키는지 본다. 금지 fixture와 다른 어댑터 경로에 놓인 코드(가상 경로 14개)는 막는지도 본다 | 테스트 | 규칙 자체는 이미 eslint.config.ts에 있다. 이 파일은 그 규칙의 메타 테스트다. 지금은 `pnpm exec eslint`를 약 19번 따로 띄운다. vitest에서 ESLint API(`lintFiles`, `lintText({ filePath })`)를 쓰면 같은 판정을 프로세스 하나로 할 수 있다. 증거 artifact가 없고 `npm_execpath` 의존도 사라진다. 고칠 곳: 삭제 드릴이 이 스크립트 대신 테스트 파일을 지우도록 바꾼다 | check-browser-file-storage-boundaries.ts:15-45,47-60,102-171; eslint.config.ts:416-418,940-962; test-browser-file-storage-runtime-removal.ts:55,145; gates.json:354 | 작음 |
| check-browser-security.ts | 49 | `check:browser-security` → FE-GATE-013 | 보안 ESLint 규칙(eval, dangerouslySetInnerHTML, script 생성)이 허용 fixture는 통과시키고 금지 fixture는 실패시키는지 본다. dist에 `.map` 파일이 없는지도 본다 | 일부 이전 | ESLint fixture 부분은 vitest(ESLint API)로 옮긴다. 지금은 금지 폴더 전체를 한 번 lint해서 실패하는지만 본다. 그래서 4개 파일 중 하나만 걸려도 통과한다. 테스트로 옮기면서 파일별로 확인하면 더 단단해진다. dist `.map` 검사는 빌드 결과가 필요해 남는다. 다만 같은 검사가 check-test-evidence(FE-GATE-008)와 verify-hosting-headers에 이미 있으므로 여기서는 지우거나 한 곳으로 모은다. 증거 artifact 없음 | check-browser-security.ts:20-38; check-test-evidence.ts:442-447; verify-hosting-headers.ts:82; gates.json:470 | 작음 |
| check-bundle.ts | 159 | `check:bundle` → FE-GATE-012 | 빌드된 dist의 초기 JS·지연 chunk gzip 크기와 파일 수가 예산 안인지 본다. manifest와 산출물 목록이 맞는지, 예산 검사 자체가 초과 값을 실패시키는지도 본다 | 스크립트 유지 | `dist/.vite/manifest.json`과 `artifacts/performance/bundle.json`(빌드 산출물)을 읽는다. bundle.json은 FE-GATE-012 증거다. release-candidate·local-release-evidence·workflow도 이 파일을 읽는다. 안에 있는 예산 자기검사 3개는 unit test로 뺄 수 있다. 그러면 bundle.json의 `fixtures` 필드가 빠져 스키마가 바뀐다 | check-bundle.ts:29-43,67-109,126-130; gates.json:425,1350 | — |
| check-ci-contract.ts | 199 | `check:ci`(check:artifact-schemas·check:ci-workflow와 함께) → FE-GATE-010 | gates.json·package.json·workflow가 서로 맞는지 본다. 모든 테스트 파일과 검증 script가 게이트에 걸렸는지, 승격 공식이 한 게이트만 실패해도 막는지, 생성 workflow가 커밋본과 같은지도 본다 | 스크립트 유지 | 저장소 파일만 읽으므로 기술적으로는 테스트가 가능하다. 하지만 CI 계약의 뿌리다. 자기가 쓰는 ci-contract.json을 FE-GATE-010이 반드시 게시해야 한다고 스스로 검사한다. ci-workflow-generation.test.ts:1607이 이 스크립트를 직접 실행하고, 삭제 드릴도 check:ci를 부른다. 옮기면 증거 계약을 다시 짜야 해서 얻는 것이 없다 | check-ci-contract.ts:85-120,127-133,190-194; gates.json:585,1698; test-sample-removal.ts:482 | — |
| check-compatibility.ts | 87 | `verify:compatibility`(`--update-baseline` 갱신 모드 있음) → FE-GATE-014 | runtime config 스키마 변경 분류 fixture가 기대값과 같은지 본다. 현재 스키마가 커밋된 baseline보다 breaking이 아닌지도 본다 | 스크립트 유지 | 계산은 결정적이다. 하지만 FE-GATE-014의 유일한 명령이고 compatibility.json이 유일한 증거다(release_gate, 승격 공식에 포함). 옮기면 게이트가 빈다. baseline 비교는 이미 compatibility.test.ts:94-109가 "none"으로 더 엄격하게 한다. `--update-baseline` 갱신 도구 역할도 한다 | check-compatibility.ts:29-33,38-51,53-71; tests/unit/compatibility.test.ts:94-109; gates.json:475,1479,2006-2016 | — |
| check-design-system.ts | 183 | `check:design-system` → FE-GATE-010<br>`check:design-system:fixture`(`--fixture`, 실패 기대) → FE-GATE-010 | 토큰 CSS를 본다: 필수·다크 토큰, 정의 안 된 `var()`, hue 혼합, 포커스 대비, 읽히지 않는 토큰, 폰트, forced-colors. src TS에서는 react-aria·radix 직접 import와 원시 색값(#hex, `oklch(`, `rgb(`)을 찾는다 | 일부 이전 | 부분별로 나눈다: ① headless vendor import → `.dependency-cruiser.json` forbidden 규칙(외부 패키지 규칙 선례 `:326`). 지금은 설치도 안 된 패키지라 import하면 check:architecture가 이미 막는다 ② 원시 색값 → ESLint 로컬 규칙. 문자열 리터럴을 검사하고 `tokens/`는 뺀다. 주석에서 생기던 오탐이 사라진다 ③ CSS 검사 → vitest. ESLint는 CSS를 못 본다. design-system-rules.test.ts가 이미 규칙 함수와 이 스크립트 실행을 테스트한다 ④ 툴팁 검사 → 버린다. fixture에만 있는 표식 문자열을 찾는 가짜 검사라 잃는 게 없다. 잃는 것: design-system.json·-fixture.json 증거, 실패 기대 명령. 삭제 드릴 test-sample-removal.ts:476 | check-design-system.ts:34-119,139-149,150-155,168-175; .dependency-cruiser.json:326; gates.json:318,323,1184,1193 | 중간 |
| check-diagnostics.ts | 142 | `check:diagnostics` → FE-GATE-010<br>`check:diagnostics:fixture`(`--fixture`, 실패 기대) → FE-GATE-010 | 진단 context 키마다 카디널리티가 있는지, telemetry 속성에 request 카디널리티가 없는지 본다. 이벤트마다 생산자 파일에 이벤트 이름이 있는지, src에 `console.`이 없는지, `record()`·`emit()` 호출에 민감한 키가 없는지도 본다 | 일부 이전 (나누면 스크립트 삭제 가능) | 부분별로 나눈다: ① `console.` → ESLint 기본 `no-console`(src 전체). 지금 src의 console 사용은 0건 ② 민감 키 → ESLint 로컬 규칙(호출 인자 객체의 키와 문자열 검사). 지금 정규식은 호출 텍스트 700자 안에 그 단어가 어디든 있으면 걸리므로 판정이 조금 달라진다 ③ 레지스트리·생산자 검사 → unit test. src/contracts 상수 import와 고정 파일 읽기뿐이다 ④ `UNKNOWN_DIAGNOSTIC_EVENT` 검사 → 버린다. fixture 표식만 찾는 가짜 검사다. 고칠 곳: registry-governance.json:522(이 파일을 TELEMETRY_REGISTRY 소비자로 등록), second-api-feature-registries.test.ts:204-209(이 파일을 복사), verify-extreme-scale.ts:31. 잃는 것: diagnostics.json·-fixture.json 증거 | check-diagnostics.ts:54-90,95-108,109-114,126-133; config/contracts/registry-governance.json:522; gates.json:342,347,1220,1229 | 중간 |
| check-frozen-lockfile-fixture.ts | 39 | `check:frozen-lockfile:fixture` → FE-GATE-001 | package.json을 바꾼 임시 폴더에서 `pnpm install --frozen-lockfile`이 실제로 실패하는지 본다 | 스크립트 유지 | pnpm 자식 프로세스와 임시 폴더로 도구 동작을 확인하는 검사다. vitest에 넣어도 같은 spawn이라 줄어드는 게 없다. 오히려 lockfile 게이트(FE-GATE-001)에서 빠진다. 증거는 runner 로그뿐이다 | check-frozen-lockfile-fixture.ts:6-30; gates.json:11 | — |
| check-i18n.ts | 180 | `check:i18n` → FE-GATE-010<br>`check:i18n:fixture`(`--fixture`, 실패 기대) → FE-GATE-010 | 언어별 메시지 카탈로그의 키와 자리표시자가 ko-KR과 같은지 본다. 화면 코드가 `{error.message}`처럼 백엔드 메시지를 그대로 그리는지도 본다. fixture 모드는 ESLint 화면 문구 규칙도 fixture에 돌려 금지 파일마다 걸리는지 확인한다 | 일부 이전 (나누면 스크립트 삭제 가능) | 부분별로 나눈다: ① 카탈로그 비교 → 지운다. i18n-contract.test.ts:27-38에 이미 있다 ② 백엔드 메시지 출력 → ESLint `no-restricted-syntax`. 화면 문구 블록(eslint.config.ts:911)에 넣고 `.ts`도 포함하게 한다. 스크립트 주석(`:54-61`)은 selector로 못 가린다고 하지만, 지금 정규식도 변수 이름(failure·error·response·backend)과 `.message`만 본다(`:12-13`). selector로 같은 판정이 된다 ③ fixture 검사 → vitest에서 ESLint API(`ignore: false`). 잃는 것: i18n.json·-fixture.json 증거, 실패 기대 명령. 삭제 드릴 test-sample-removal.ts:475 | check-i18n.ts:12-13,31-52,54-61,103-111,113-172; tests/unit/i18n-contract.test.ts:27-38; eslint.config.ts:464-474,909-925; gates.json:330,335,1202,1211 | 중간 |
| check-optional-recipe-fixtures.ts | 211 | `check:optional-recipe-fixtures` → FE-GATE-010 | 선택 레시피 검사기 자체가 금지 사례 11개를 잡는지 본다: 카탈로그 변조, vendor import, 자격증명 누출, 서버 상태 복제, 레시피 import, 런타임 조합, 번들 표식, 모듈 목록, 예산 1바이트 초과 등 | 테스트 | 전부 lib 함수(validateRecipeCatalog, scanOptionalRecipeSources, scanProductionBundle, measureOptionalRecipeBundle)를 fixture에 돌리는 자기검사다. unit test 모양 그대로다. 지금 이 lib 전용 unit test는 없다. 예산 사례는 레시피마다 vite build를 돌려 느리다. 그 사례만 느린 테스트로 나누거나 스크립트에 남긴다. 잃는 것: optional-recipe-fixtures.json 증거 | check-optional-recipe-fixtures.ts:43-57,59-113,118-187,194-199; gates.json:374,1257 | 중간 |
| check-optional-recipe-types.ts | 62 | check:types:recipes(지움) → FE-GATE-003(check:types 안에서도 실행) | recipes/에 TS 파일이 있으면 `tsconfig.recipes.json`으로 tsc를 돌린다 | 삭제 예정(PR A) | tsconfig.test.json으로 합쳐지면서 지워진다. 판정 대상이 아니다 | check-optional-recipe-types.ts:8-21; package.json:29,33; gates.json:26 | — |
| check-optional-recipes.ts | 271 | `check:optional-recipes:source` → FE-GATE-010<br>`check:optional-recipes`(`--require-dist`) → FE-GATE-012 | 다섯 가지를 본다: ① 레시피 카탈로그의 JSON Schema와 규칙 ② 참조 런타임 소스가 있는지 ③ 레시피별 번들 예산(vite build) ④ src 소스 규칙 5개(레시피 import, 선택 안 된 런타임 조합, vendor 직접 import, 자격증명 누출, 서버 상태 복제) ⑤ dist에 선택 안 된 레시피 코드가 없는지 | 일부 이전 | import 규칙만 `.dependency-cruiser.json` forbidden 규칙으로 옮긴다: vendor 직접 import는 관측 vendor 규칙(`:326`)처럼 to 경로로 막고, bootstrap·installed-feature-*에서 참조 런타임 어댑터를 import하는 것도 막는다. src에서 recipes/로 가는 import는 check:architecture가 "src 밖" unresolved로 이미 막는다. 정규식 일부는 남는다: `new URL` 같은 문자열 경로는 그래프가 못 보기 때문이다. 자격증명·서버 상태 정규식은 의미가 느슨해 ESLint로 옮기면 판정이 바뀐다 → 유지를 권한다. 카탈로그, vite build 예산, dist 검사는 빌드가 필요해 유지한다. optional-recipes.json은 FE-GATE-010·012 증거로 그대로 남는다. 삭제 드릴 test-optional-recipe-removal.ts:47-48 | scripts/lib/optional-recipes.ts:241-338,341; check-optional-recipes.ts:53-70,100-128; check-architecture.ts:508; gates.json:369,435,1247 | 중간 |
| check-realtime-boundaries.ts | 43 (+lib 130) | `check:realtime-boundaries` → FE-GATE-010 (`--source-root`·`--artifact`로 fixture에도 쓴다) | realtime·web-push 어댑터 밖에서 다음이 없는지 본다: WebSocket·EventSource·Notification 생성, `requestPermission`, `showNotification`, `pushManager` 호출, `Reflect.get` 우회. presentation에 `setInterval`이 없는지도 본다 | ESLint 규칙 | lib는 소스 텍스트 정규식 검사뿐이라 AST 규칙에 잘 맞는다. lib 주석(`:4-6`)도 "그래프가 못 보는 네이티브 호출"을 맡는다고 하는데, ESLint는 이것을 본다. 로컬 규칙 하나로 만든다: files는 `src/**`, ignores는 두 어댑터 폴더, presentation에는 `setInterval` 금지. 주석과 문자열에서 생기던 오탐도 사라진다. 잃는 것: realtime-boundaries.json 증거(FE-GATE-010). 실시간 삭제 드릴(FE-GATE-020)은 이 스크립트 2개와 lib를 지우는 방식이라, ESLint 블록을 지우는 방식으로 바꿔야 한다 | scripts/lib/realtime-boundaries.ts:4-6,17-29,54-92; check-realtime-boundaries.ts:12-25; test-realtime-runtime-removal.ts:39-40,95-97; gates.json:359,1238 | 중간 |
| check-realtime-boundary-fixtures.ts | 46 | `check:realtime-boundaries:fixture` → FE-GATE-010 | 위 검사를 자식 프로세스로 돌려, 허용 fixture는 통과하고 금지 fixture는 규칙 2개로 실패하는지 본다 | 테스트 | 위 스크립트가 ESLint로 가면 이 파일은 vitest에서 ESLint API(또는 RuleTester)로 fixture를 lint하는 테스트가 된다. 위 스크립트를 그대로 두더라도 `scanRealtimeBoundaries`를 직접 부르는 unit test로 바로 옮길 수 있다. 증거 artifact 없음(`.tmp`에 쓴다) | check-realtime-boundary-fixtures.ts:3-11,18-28,34-46; gates.json:364 | 작음 |
| check-registries.ts | 777 | `check:registries` → FE-GATE-010<br>`--governance`·`--approval` fixture 3개(baseline·registry·routes, 실패 기대) → FE-GATE-010<br>`update:registry-baseline`(`--no-baseline`) | 레지스트리 모듈을 import해 필수 필드, 타입, 유일성, 참조, 소비자 토큰, 고아 행을 본다. baseline 승인 digest와 breaking 증거를 확인하고 스냅샷을 기록한다. application·presentation·domain에서 fetch·localStorage·`import.meta.env`·`"/api/"`를 직접 쓰는지도 본다 | 일부 이전 | 직접 사용 검사(`:666-690`)만 ESLint로 옮긴다. fetch·localStorage는 이미 레이어별 `no-restricted-globals`와 겹친다. `import.meta.env` 읽기와 `"/api/"` 문자열은 로컬 규칙으로 추가한다. governance fixture는 sourceDirectories가 비어 있어 이 변경의 영향을 받지 않는다. 나머지는 유지한다: registries.json 스냅샷은 update:registry-baseline의 입력이자 FE-GATE-010 증거이고, 실패 기대 fixture 명령 3개가 진단 문구로 걸려 있다 | check-registries.ts:666-690,700-735,763-770; eslint.config.ts:629-697; package.json:105-110; gates.json:379,389,396,403,1266 | 작음 (ESLint 부분) |
| check-registry-compatibility-fixtures.ts | 66 | `check:registries:compatibility-fixtures` → FE-GATE-010 | 레지스트리 스냅샷 diff 분류 fixture가 맞는지 본다. breaking 변경에 증거가 없으면 실패하는지, 변조된 baseline digest를 거부하는지도 본다 | 테스트 | JSON fixture 하나를 읽어 lib 함수만 부른다. 파일 시스템 작업이나 빌드가 없다. registry-compatibility.test.ts가 lib는 이미 테스트하지만 이 fixture 파일은 읽지 않는다 → 그 테스트에 케이스를 추가한다. package script는 쓰지도 않는 인덱스 생성기를 먼저 돈다. 잃는 것: registry-compatibility-fixtures.json 증거(FE-GATE-010, 다른 소비자 없음) | check-registry-compatibility-fixtures.ts:11-52,54-59; package.json:107; gates.json:384,1275 | 작음 |
| check-release-admission.ts | 199 | `check:release-admission` → FE-GATE-027<br>운영자용 `--config`·`--original` 모드 | 빌드된 `dist/config.json`이 RELEASE_TARGET(과 APP_PROFILE) 환경에 맞는지 본다. 수정본은 비상 스위치 말고 빌드 필드를 바꾸지 않았는지 본다 | 스크립트 유지 | 입력이 빌드 산출물과 환경 변수이고, 운영자가 직접 쓰는 CLI다. deployment-admission.json은 FE-GATE-027 증거이고 workflow도 읽는다. 판정 로직은 이미 src/contracts/deployment-admission.ts와 그 unit test에 있다 | check-release-admission.ts:35-37,72-94,98-120,161-181; gates.json:590,1707 | — |
| check-remediation-ledger.ts | 165 | `check:remediation-ledger` (게이트 없음, 일부러 제외) | 재검토 처분 JSON과 원장 문서의 판정 칸이 같은지 본다. 증거 파일이 있고 finding id를 언급하는지, 열린 항목이 있을 때 "모두 FIXED" 문장이 없는지, file-transfer 예산 숫자가 같은지도 본다 | 스크립트 유지 | 저장소 파일만 읽어 테스트로 옮기기는 쉽다. 그러나 ungated-scripts.json:21-22가 "손으로 돌리는 이력 기록이고 merge를 막으면 안 된다"며 일부러 게이트에서 뺐다. tests/unit에 넣으면 그 결정과 반대로 merge를 막게 된다. 더 필요 없다면 삭제는 따로 판단한다 | check-remediation-ledger.ts:29-42,66-120,139-152; config/ci/ungated-scripts.json:21-22 | — |
| check-request-fanout.ts | 185 | `check:request-fanout`(같은 명령에서 `--fixture`도 실행) → FE-GATE-010 | src/features·src/application에서 루프나 map·forEach 콜백 안에서 fetch나 transport를 호출하는지(N+1) 본다. `// fanout-reviewed:` 주석은 예외로 허용한다 | 테스트 (이미 있음) | `tests/architecture/request-fanout.test.ts:11-24`가 같은 전체 검사를 이미 한다. fixture 검사는 테스트 쪽이 더 엄격하다(금지 파일마다 걸리는지, 정확히 3개인지). CLI(`:157-185`), package script, gate 명령만 지우고 스캐너는 lib로 옮기면 된다. 증거 artifact 없음. Babel AST 순회라 ESLint 로컬 규칙으로도 옮길 수 있다(에디터 경고가 생기지만 크기 중간). 주의: tests/architecture는 test:coverage(FE-GATE-005)에서만 돈다. 고칠 곳: ungated-scripts.test.ts:57, feature-scaffold-drill.test.ts:32, verify-extreme-scale.ts:29 | check-request-fanout.ts:80-125,157-185; tests/architecture/request-fanout.test.ts:11-24; package.json:82,148; gates.json:308 | 작음 |
| check-risk-coverage.ts | 78 | `test:coverage` 마지막 단계 → FE-GATE-005<br>`check:coverage:fixture`(`--summary` fixture, 실패 기대) → FE-GATE-005 | 커버리지 결과가 위험 정책(config/testing/risk-coverage.json)의 모듈별 기준을 넘는지 본다 | 스크립트 유지 | 입력이 coverage 실행 결과(`artifacts/tests/coverage/coverage-summary.json`)라 테스트 실행 뒤에만 돌 수 있다. risk-coverage.json·-fixture.json이 FE-GATE-005 증거다. 판정 로직은 lib와 unit test에 이미 있다 | check-risk-coverage.ts:35-46,60-70; package.json:82-83; gates.json:205,210,944,953 | — |
| check-security-fixtures.ts | 10 (+lib 170) | `check:security:fixtures` → FE-GATE-013 | 비밀값 스캐너 CLI가 금지 fixture에서 정확히 3건으로 실패하는지 본다. include 경로가 맞지 않으면 artifact 없이 실패하는지도 본다 | 테스트 | lib가 이미 의존성 주입을 받고, 실패 경로 unit test도 있다. 실제 CLI 실행도 vitest에서 같은 spawn으로 하면 된다. 증거 artifact 없음(임시 폴더에 쓴다). 잃는 것: 이 확인이 보안 게이트(FE-GATE-013) 로그에서 빠지고 FE-GATE-005로 간다. supply-chain.test.ts:458-483이 "FE-GATE-013이 이 script를 돈다"를 검사하므로 같이 고친다 | scripts/lib/security-fixture-check.ts:30-49,85-118,120-170; tests/unit/supply-chain.test.ts:417,458-483; gates.json:465 | 작음 |
| check-supply-chain-fixtures.ts | 151 | `check:supply-chain:fixtures` → FE-GATE-013 | 공급망 lib가 다음 9가지를 거부하는지 본다: 의존성 diff, 무결성 값, 자기 승인, 금지 라이선스, 만료된 예외, SBOM·provenance 불일치, 정렬, baseline 변조, 스캐너 증거 오류 | 테스트 | 메모리 안의 값으로 lib 함수만 부른다. 파일 읽기와 빌드가 없어 unit test로 그대로 옮길 수 있다. package script는 쓰지도 않는 인덱스 생성기를 먼저 돈다. 잃는 것: supply-chain-fixtures.json(FE-GATE-013 증거, 다른 소비자 없음) → 증거 계약이 바뀐다 | check-supply-chain-fixtures.ts:15-140,141-146; package.json:93; gates.json:455,1455 | 작음 |
| check-supply-chain-provider-fixtures.ts | 417 | `check:supply-chain:provider-fixtures` → FE-GATE-013 | 저장소를 임시 폴더로 복사해 release candidate를 실제로 빌드하고, 묶고, 서명한다. 그 뒤 정확한 5개 파일 승격 검증과 서명 검증이 제대로 동작하는지 본다 | 스크립트 유지 | 저장소 복사, `pnpm build:release-candidate`, tar, git, 키 생성이 모두 필요한 끝단 검사다. supply-chain-provider-fixtures.json이 FE-GATE-013 증거다 | check-supply-chain-provider-fixtures.ts:50-64,66-80,101; gates.json:460,1464 | — |
| check-system-test-prerequisites.ts | 154 | `test:system` 첫 단계 → FE-GATE-013 | 호스트에 bwrap·systemctl·tar가 있는지, cgroup v2와 systemd 버스가 동작하는지, 비특권 user namespace가 허용되는지 본다 | 스크립트 유지 | 실제 호스트를 확인하는 사전 점검이다. 판정 로직은 이미 의존성 주입 방식으로 unit test(system-test-prerequisites.test.ts)가 있다. workflow와 gates.json도 이 파일을 이름으로 참조한다 | check-system-test-prerequisites.ts:55-97,146-154; package.json:53; gates.json:232 | — |
| check-test-evidence.ts | 471 | `check:test-evidence:browser`(`--skip-scenario-executions`) → FE-GATE-008<br>`check:test-evidence:fixture`(`--source-root`, 실패 기대) → FE-GATE-008<br>`check:http-scenario-evidence`(+`:fixture`) → run-http-scenario-evidence.ts를 거쳐 FE-GATE-007<br>`check:test-evidence`·`:source`는 로컬용 | 소스 쪽: tests/의 `.only`, 기한 없는 `.skip`, 화면 전체 mask, 정책의 필수 토큰, playwright 설정 토큰과 forbidOnly, e2e가 strict fixture를 쓰는지, visual baseline 4개 이상. 실행 결과 쪽: HTTP 시나리오 실행 영수증이 카탈로그와 같은지, results.xml과 dist 산출물이 있는지, dist에 `.map`이 없는지 | 일부 이전 | 소스만 보는 부분(`:280-311`, `:326-340`, `:366-418`)은 unit test로 옮긴다. `.only`와 mask는 ESLint로도 되지만, fixture 트리에 `.fixture`·`.txt` 파일이 있어 ESLint가 읽지 못한다 → 테스트가 맞다. 영수증, results.xml, dist 검사(`:420-447`)는 실행·빌드 산출물이 필요해 남는다. 잃는 것: test-evidence.json의 일부 사실과 실패 항목(스키마·증거 변경). 삭제 드릴의 check:test-evidence:source 호출(test-sample-removal.ts:481)도 고쳐야 한다. 모드가 많아 손이 많이 간다 | check-test-evidence.ts:130-278,280-311,326-340,345-360,366-418,420-447; gates.json:272,277,1115,1124 | 큼 |
| check-v8-coverage-counter-semantics.ts | 12 (+lib 294) | `check:v8-coverage-counter-semantics` → `test:coverage` 첫 단계, FE-GATE-005 | 임시 폴더에서 vitest coverage를 돌려, import만 있는 모듈의 V8 카운터가 0/0으로 나오는지 본다(위험 커버리지 판정의 전제) | 스크립트 유지 | vitest를 자식 프로세스로 돌려 도구 동작을 확인하는 점검이다. coverage 실행 직전에 돌아야 의미가 있다. lib에는 unit test가 이미 있다 | scripts/lib/v8-coverage-counter-semantics.ts:186-205; package.json:81-82; gates.json:205 | — |
## 조사 중 확인한 것 (판정과 별개)
- **가짜 검사 2개**: `check-design-system.ts:150-155`와 `check-diagnostics.ts:109-114`는 fixture 파일에만 들어 있는 표식 문자열(`TOOLTIP_ONLY_REQUIRED_INFORMATION`, `UNKNOWN_DIAGNOSTIC_EVENT`)을 찾아 실패를 만든다. 실제 규칙은 검사하지 않는다.
- **dist `.map` 검사 중복**: 같은 검사가 세 곳에 있다(`check-browser-security.ts:35-36`, `check-test-evidence.ts:442-447`, `verify-hosting-headers.ts:82`).
- **약한 fixture 확인**: `check-browser-security.ts:27-38`은 금지 fixture 폴더 전체가 한 번 실패하는지만 본다. 그래서 4개 파일 중 하나만 걸려도 통과한다.
- **불필요한 생성기 실행**: `check:supply-chain:fixtures`와 `check:registries:compatibility-fixtures`는 쓰지도 않는 인덱스 생성기를 먼저 돈다(package.json:93,107).
- **생성기 없이 읽는 스크립트**: 반대로 `check:app-build-input`은 생성기를 돌리지 않고 `src/.generated`를 읽는다(package.json:149). 그래서 앞 단계가 남긴 인덱스에 기대고, 혼자 돌리면 오래된 인덱스를 볼 수 있다. CI에서는 FE-GATE-010의 check:architecture가 먼저 생성해 줘서 문제가 드러나지 않는다.
+1 -1
View File
@@ -110,4 +110,4 @@ release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회
- 새 게이트·명령은 `config/ci/gates.json`에 더하고 workflow는 생성기로 다시 만든다(`check:ci`가 대조한다). 손으로 workflow만 고치지 않는다.
- 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다.
- 새 package script가 어느 게이트에서도 돌지 않으면 `check:ci`가 실패한다. 예외는 이유와 함께 `config/ci/ungated-scripts.json`·`config/ci/ungated-tests.json`에 둔다. 이 목록을 늘리는 것은 게이트 기준을 낮추는 일이다(꼭 지킬 것 4).
- 새 package script가 어느 게이트에서도 돌지 않으면 `check:ci:gating`(main 단계 FE-GATE-029)이 실패한다. PR에서는 돌지 않고 main에 push한 뒤 돈다. 예외는 이유와 함께 `config/ci/ungated-scripts.json`·`config/ci/ungated-tests.json`에 둔다. 이 목록을 늘리는 것은 게이트 기준을 낮추는 일이다(꼭 지킬 것 4).
+1 -1
View File
@@ -19,7 +19,7 @@
| Vitest 실행 runner(Node 버전, `NODE_ENV`, 생성물) | `scripts/run-vitest.ts` |
| Playwright skip·fixme의 quarantine 조건, `forbidOnly` | `scripts/check-test-evidence.ts` |
| 테스트 공통 대기 기한 | `tests/setup.ts` |
| 모든 테스트 파일이 어떤 게이트에서 도는가 | `check:ci`, 예외 목록 `config/ci/ungated-tests.json` |
| 모든 테스트 파일이 어떤 게이트에서 도는가 | `check:ci:gating`(main 단계 FE-GATE-029), 예외 목록 `config/ci/ungated-tests.json` |
| 지워도 되는 문서를 테스트가 읽지 않는다 | `tests/unit/deletable-history-documents.test.ts` |
## 2. 테스트를 어디에 둘까
+3 -27
View File
@@ -26,27 +26,11 @@
"scan:dependency-advisories": "node scripts/scan-dependency-advisories.ts",
"check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts --fixture",
"check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:recipes && corepack pnpm check:types:web-worker && corepack pnpm check:types:service-worker",
"check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:service-worker && node scripts/check-typecheck-inputs.ts",
"check:types:app": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.app.json",
"check:types:node": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.node.json",
"check:types:test": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.test.json",
"check:types:recipes": "node scripts/check-optional-recipe-types.ts",
"check:types:fixture": "tsc -p tests/fixtures/typecheck/tsconfig.port-call.json",
"check:types:fixture:ts-port": "tsc -p tests/fixtures/typecheck/tsconfig.port-implementation.json",
"check:types:fixture:ts-result": "tsc -p tests/fixtures/typecheck/tsconfig.result-narrowing.json",
"check:types:fixture:application-output": "tsc -p tests/fixtures/typecheck/tsconfig.application-output.json",
"check:types:fixture:application-input": "tsc -p tests/fixtures/typecheck/tsconfig.application-input.json",
"check:types:fixture:feature-input": "tsc -p tests/fixtures/typecheck/tsconfig.feature-input.json",
"check:types:fixture:failure-kind": "tsc -p tests/fixtures/typecheck/tsconfig.failure-kind.json",
"check:types:fixture:reference-operation": "tsc -p tests/fixtures/typecheck/tsconfig.reference-operation.json",
"check:types:fixture:async-overlay": "tsc -p tests/fixtures/typecheck/tsconfig.async-overlay.json",
"check:types:fixture:route-runtime": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.route-runtime.json",
"check:types:fixture:page-action": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.page-action.json",
"check:types:fixture:icon-button": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.icon-button.json",
"check:types:fixture:i18n-key": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-key.json",
"check:types:fixture:i18n-params": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-params.json",
"check:types:fixture:diagnostics": "tsc -p tests/fixtures/typecheck/tsconfig.diagnostics-port.json",
"check:types:fixture:image-resolve-signal": "tsc -p tests/fixtures/typecheck/tsconfig.image-cdn-resolve-signal.json",
"check:types:fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-type-fixtures.ts",
"test:runtime-schema": "node scripts/run-vitest.ts run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
"test:unit": "node scripts/run-vitest.ts run tests/unit --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/unit.xml",
"test:contract": "node scripts/run-vitest.ts run tests/contract --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/contract.xml",
@@ -120,17 +104,9 @@
"generate:ci-workflow": "node scripts/generate-ci-workflow.ts",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
"check:ci": "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow",
"update:ci-contract-baseline": "node scripts/update-ci-contract-baseline.ts",
"check:ci:gating": "node scripts/check-ci-gating.ts",
"verify:documentation": "node scripts/generate-product-feature-index.ts && node scripts/verify-documentation-readiness.ts",
"check:types:web-worker": "tsc --project tsconfig.web-worker.json",
"check:types:service-worker": "tsc --project tsconfig.service-worker.json",
"check:types:fixture:http-operation-input": "tsc -p tests/fixtures/typecheck/tsconfig.http-operation-input.json",
"check:types:fixture:http-wire-mapper": "tsc -p tests/fixtures/typecheck/tsconfig.http-wire-mapper.json",
"check:types:fixture:http-operation-id": "tsc -p tests/fixtures/typecheck/tsconfig.http-operation-id.json",
"check:types:fixture:http-route-id": "tsc -p tests/fixtures/typecheck/tsconfig.http-route-id.json",
"check:types:fixture:feature-contribution-input": "tsc -p tests/fixtures/typecheck/tsconfig.feature-contribution-input.json",
"check:types:fixture:feature-capability-selection": "tsc -p tests/fixtures/typecheck/tsconfig.feature-capability-selection.json",
"check:types:fixture:direct-feature-composition": "tsc -p tests/fixtures/typecheck/tsconfig.direct-feature-composition.json",
"generate:feature-index": "node scripts/generate-product-feature-index.ts",
"create:feature": "node scripts/generate-product-feature-index.ts && node scripts/create-feature.ts",
"check:feature-index": "node scripts/generate-product-feature-index.ts --check",
+6 -2
View File
@@ -9,6 +9,7 @@ import { ESLint } from "eslint";
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
import { checkArchitectureLintFixtures } from "./lib/architecture-lint-fixtures.ts";
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
import { selectRepositoryEntries } from "./lib/repository-layout.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type PathRule = Readonly<{ path?: string; pathNot?: string }>;
@@ -1044,8 +1045,11 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
}
async function inspectTypeScriptOnlyPolicy(): Promise<TypeScriptOnlyPolicy> {
const requiredRoots = ["src", "scripts", "tests", ".storybook"] as const;
const optionalRoots = ["recipes"] as const;
// The typescript-only set of config/repository-layout.json (R2). An optional
// root (recipes/) may be gone after a removal drill.
const selected = selectRepositoryEntries("typescript-only");
const requiredRoots = selected.filter(({ optional }) => !optional).map(({ path }) => path);
const optionalRoots = selected.filter(({ optional }) => optional).map(({ path }) => path);
const checkedRoots = [...requiredRoots, ...optionalRoots];
const files = (
await Promise.all(
+5 -51
View File
@@ -1,5 +1,4 @@
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import {
@@ -25,25 +24,12 @@ import {
validateInstallScriptPolicy,
validatePackageScriptGraph,
} from "./lib/package-script-graph.ts";
import {
gatedTestPaths,
listTestFiles,
parseUngatedTestExclusions,
ungatedTestFailures,
UNGATED_TESTS_PATH,
} from "./lib/ungated-tests.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "./lib/ungated-scripts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
// 1103/12-07. The product's merge gates are entry scripts of CI as well.
// 1103/12-07. The product's merge gates run in the generated workflow too.
const { mergeGates: productGates } = await loadProductCiOverlay(process.cwd());
const productGateScripts = productGates.map(({ script }) => script);
const [packageDocument, nodeVersion] = await Promise.all([
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
readFile(".nvmrc", "utf8").then((value) => value.trim()),
@@ -82,42 +68,10 @@ failures.push(
),
);
// 12-04: every test file runs in a gate, or config/ci/ungated-tests.json says why not.
try {
failures.push(
...ungatedTestFailures({
testFiles: await listTestFiles(process.cwd()),
gatedPaths: gatedTestPaths(
packageScripts,
[...contract.commands.map(({ script }) => script), ...productGateScripts],
(file) => readFileSync(file, "utf8"),
),
exclusions: parseUngatedTestExclusions(
JSON.parse(await readFile(UNGATED_TESTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04: every verification package script is reached by a gate, or
// config/ci/ungated-scripts.json says why not.
try {
const entryScripts = [...contract.commands.map(({ script }) => script), ...productGateScripts];
failures.push(
...ungatedScriptFailures({
scripts: packageScripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04. Whether every test file and verification script is reached by a
// gate is checked by check:ci:gating (scripts/check-ci-gating.ts) in the main
// stage (FE-GATE-029), not on every pull request (design-docs
// repo-structure/03-ci.md F2).
const immutable = index.gates.get("FE-GATE-015");
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
+77
View File
@@ -0,0 +1,77 @@
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import { loadCiGateContract } from "./contracts/ci-gates.ts";
import { loadProductCiOverlay } from "./contracts/product-ci-overlay.ts";
import {
gatedTestPaths,
listTestFiles,
parseUngatedTestExclusions,
ungatedTestFailures,
UNGATED_TESTS_PATH,
} from "./lib/ungated-tests.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "./lib/ungated-scripts.ts";
/**
* 12-04. Every test file and every verification package script is reached by
* a gate command of any stage, or config/ci/ungated-tests.json and
* config/ci/ungated-scripts.json say why not. It checks how the gates are
* wired, not the change, so it runs in the main stage (FE-GATE-029) after a
* merge (design-docs repo-structure/03-ci.md F2); check:ci keeps the contract
* and workflow checks on every pull request.
*/
const contract = await loadCiGateContract(process.cwd());
// 1103/12-07. The product's merge gates are entry scripts of CI as well.
const { mergeGates: productGates } = await loadProductCiOverlay(process.cwd());
const productGateScripts = productGates.map(({ script }) => script);
const packageScripts =
(JSON.parse(await readFile("package.json", "utf8")) as { scripts?: Record<string, string> }).scripts ?? {};
const failures: string[] = [];
// 12-04: every test file runs in a gate, or config/ci/ungated-tests.json says why not.
try {
failures.push(
...ungatedTestFailures({
testFiles: await listTestFiles(process.cwd()),
gatedPaths: gatedTestPaths(
packageScripts,
[...contract.commands.map(({ script }) => script), ...productGateScripts],
(file) => readFileSync(file, "utf8"),
),
exclusions: parseUngatedTestExclusions(
JSON.parse(await readFile(UNGATED_TESTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04: every verification package script is reached by a gate, or
// config/ci/ungated-scripts.json says why not.
try {
const entryScripts = [...contract.commands.map(({ script }) => script), ...productGateScripts];
failures.push(
...ungatedScriptFailures({
scripts: packageScripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
if (failures.length > 0) {
process.stderr.write(`CI gating failed:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write("CI gating: every test file and verification script is gated or excluded with a reason PASS\n");
-62
View File
@@ -1,62 +0,0 @@
import { spawnSync } from "node:child_process";
import { readdir } from "node:fs/promises";
import { extname, resolve } from "node:path";
const recipeRoot = resolve("recipes");
const pnpmCli = requireEnvironment("npm_execpath");
if (!(await containsTypeScriptSource(recipeRoot))) {
process.stdout.write(
"Optional recipe typecheck: SKIP (no recipe TypeScript sources installed)\n",
);
} else {
const result = spawnSync(
process.execPath,
[pnpmCli, "exec", "tsc", "--project", "tsconfig.recipes.json"],
{ stdio: "inherit" },
);
if (result.error) {
throw result.error;
}
process.exitCode = result.status ?? 1;
}
function requireEnvironment(name: string): string {
const value = process.env[name];
if (!value) {
throw new Error(`${name} is required to typecheck optional recipes`);
}
return value;
}
async function containsTypeScriptSource(directory: string): Promise<boolean> {
let entries;
try {
entries = await readdir(directory, { withFileTypes: true });
} catch (error) {
if (hasErrorCode(error, "ENOENT")) {
return false;
}
throw error;
}
for (const entry of entries) {
const target = resolve(directory, entry.name);
if (entry.isDirectory() && (await containsTypeScriptSource(target))) {
return true;
}
if (entry.isFile() && [".ts", ".tsx", ".mts", ".cts"].includes(extname(entry.name))) {
return true;
}
}
return false;
}
function hasErrorCode(error: unknown, code: string): boolean {
return (
typeof error === "object" &&
error !== null &&
"code" in error &&
error.code === code
);
}
+1 -1
View File
@@ -54,7 +54,7 @@ try {
assertMatchesJsonSchema(
JSON.parse(
await readFile(
"schemas/config/frontend-capability-recipes.schema.json",
"config/schemas/recipes/frontend-capability-recipes.schema.json",
"utf8",
),
),
+1 -1
View File
@@ -748,7 +748,7 @@ if (usesRepositoryBaseline && failures.length === 0) {
assertMatchesJsonSchema(
JSON.parse(
await readFile(
"schemas/artifacts/registry-snapshot.schema.json",
"config/schemas/artifacts/registry-snapshot.schema.json",
"utf8",
),
),
+141
View File
@@ -0,0 +1,141 @@
import { spawn } from "node:child_process";
import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
/**
* The negative type fixtures (FE-GATE-003). Each fixture under
* tests/fixtures/typecheck states on its first line what tsc must say about
* it: `// expect: TS2322` (compilation fails and reports TS2322) or
* `// expect: pass` (it compiles; tests/fixtures/typecheck/invalid-diagnostics-port.ts
* holds one `@ts-expect-error` per violation). Every fixture compiles alone
* with tests/fixtures/typecheck/tsconfig.base.json, as the 23 one-file
* tsconfigs and package scripts this runner replaces did (design-docs
* repo-structure/04-frontend-layout.md §5.3 (가)).
*
* The check is the one run-ci-gate.ts applied to each of those commands:
* tsc exits 1 and its output contains `error TS<code>:`. A fixture without an
* expectation line fails, and so does a directory with no fixtures, so a new
* fixture cannot be skipped and an empty run cannot pass (R8).
*/
export const TYPE_FIXTURE_ROOT = "tests/fixtures/typecheck";
const BASE_CONFIG = `${TYPE_FIXTURE_ROOT}/tsconfig.base.json`;
/**
* tsc resolves `types` from the tsconfig's directory upwards, so the one-file
* tsconfigs are written inside the repository, in the ignored `.tmp/`.
*/
const CONFIG_ROOT = ".tmp/type-fixtures";
const EXPECTATION = /^\/\/ expect: (pass|TS\d{4,5})$/u;
/** Helpers that fixtures import are not fixtures. */
const FIXTURE_FILE = /^invalid-[\w-]+\.tsx?$/u;
const CONCURRENCY = 4;
export type TypeFixtureExpectation = { kind: "pass" } | { kind: "fail"; code: string };
export interface TypeFixtureResult {
file: string;
expectation: TypeFixtureExpectation | undefined;
passed: boolean;
/** The diagnostic lines that met the expectation, or all output on failure. */
evidence: string[];
}
export function parseTypeFixtureExpectation(source: string): TypeFixtureExpectation | undefined {
const match = EXPECTATION.exec(source.split("\n", 1)[0]?.trimEnd() ?? "");
if (!match?.[1]) return undefined;
return match[1] === "pass" ? { kind: "pass" } : { kind: "fail", code: match[1] };
}
export async function listTypeFixtures(root: string): Promise<string[]> {
return (await readdir(path.join(root, TYPE_FIXTURE_ROOT)))
.filter((name) => FIXTURE_FILE.test(name))
.sort()
.map((name) => `${TYPE_FIXTURE_ROOT}/${name}`);
}
export function judgeTypeFixture(
expectation: TypeFixtureExpectation,
exitCode: number | null,
output: string,
): Pick<TypeFixtureResult, "passed" | "evidence"> {
const lines = output.split("\n").filter((line) => line.trim().length > 0);
if (expectation.kind === "pass") {
return { passed: exitCode === 0, evidence: lines };
}
const matching = lines.filter((line) => line.includes(`error ${expectation.code}:`));
return exitCode === 1 && matching.length > 0
? { passed: true, evidence: matching }
: { passed: false, evidence: [`tsc exit ${exitCode}`, ...lines] };
}
function runTsc(root: string, config: string): Promise<{ exitCode: number | null; output: string }> {
return new Promise((resolve, reject) => {
const child = spawn(path.join(root, "node_modules/.bin/tsc"), ["--project", config, "--pretty", "false"], {
cwd: root,
stdio: ["ignore", "pipe", "pipe"],
});
let output = "";
child.stdout.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
child.stderr.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
child.on("error", reject);
child.on("close", (exitCode) => resolve({ exitCode, output }));
});
}
async function checkTypeFixture(root: string, file: string): Promise<TypeFixtureResult> {
const expectation = parseTypeFixtureExpectation(await readFile(path.join(root, file), "utf8"));
if (!expectation) {
return { file, expectation, passed: false, evidence: ["missing `// expect:` first line"] };
}
const config = path.join(CONFIG_ROOT, `tsconfig.${path.basename(file).replace(/\.tsx?$/u, "")}.json`);
const fromConfig = (target: string) => path.relative(path.dirname(config), target);
await writeFile(
path.join(root, config),
`${JSON.stringify({ extends: fromConfig(BASE_CONFIG), files: [fromConfig(file)] }, null, 2)}\n`,
);
const { exitCode, output } = await runTsc(root, config);
return { file, expectation, ...judgeTypeFixture(expectation, exitCode, output) };
}
export async function checkTypeFixtures(root: string): Promise<TypeFixtureResult[]> {
const fixtures = await listTypeFixtures(root);
await rm(path.join(root, CONFIG_ROOT), { recursive: true, force: true });
await mkdir(path.join(root, CONFIG_ROOT), { recursive: true });
const results: TypeFixtureResult[] = new Array(fixtures.length);
let next = 0;
await Promise.all(
Array.from({ length: Math.min(CONCURRENCY, fixtures.length) }, async () => {
while (next < fixtures.length) {
const index = next++;
results[index] = await checkTypeFixture(root, fixtures[index]!);
}
}),
);
return results;
}
function describeExpectation(expectation: TypeFixtureExpectation | undefined): string {
if (!expectation) return "no expectation";
return expectation.kind === "pass" ? "expect pass" : `expect ${expectation.code}`;
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const results = await checkTypeFixtures(process.cwd());
for (const result of results) {
process.stdout.write(
`${result.passed ? "PASS" : "FAIL"} ${result.file} (${describeExpectation(result.expectation)})\n`,
);
for (const line of result.evidence) process.stdout.write(` ${line}\n`);
}
const failed = results.filter(({ passed }) => !passed);
if (results.length === 0) {
process.stderr.write(`Type fixtures: FAIL (no fixtures under ${TYPE_FIXTURE_ROOT})\n`);
process.exitCode = 1;
} else if (failed.length > 0) {
process.stderr.write(`Type fixtures: FAIL (${failed.length} of ${results.length})\n`);
process.exitCode = 1;
} else {
process.stdout.write(`Type fixtures: PASS (${results.length} fixtures)\n`);
}
}
+55
View File
@@ -0,0 +1,55 @@
import { spawnSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
/**
* R8 of docs/manual/03-outside-feature-folder.md: a check with nothing to
* check fails. tsc passes a tsconfig whose `files` is empty when it extends
* another one, so `check:types:web-worker` compiled zero files and passed
* FE-GATE-003 from 2026-09-25 until it was deleted on 2026-11-08. Every
* tsconfig a package script hands to tsc must list at least one file of this
* repository (lib and node_modules declarations do not count).
*/
const TSC_PROJECT = /\btsc\s+(?:--project|-p)\s+(\S+)/gu;
export function typecheckProjects(scripts: Readonly<Record<string, string>>): string[] {
const projects = new Set<string>();
for (const command of Object.values(scripts)) {
for (const match of command.matchAll(TSC_PROJECT)) projects.add(match[1]!);
}
return [...projects].sort();
}
export function ownInputFiles(listed: string): string[] {
return listed
.split("\n")
.map((line) => line.trim())
.filter((line) => line.length > 0 && !line.split(path.sep).includes("node_modules"));
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const scripts = (JSON.parse(readFileSync("package.json", "utf8")) as { scripts: Record<string, string> }).scripts;
const projects = typecheckProjects(scripts);
const counts = projects.map((project) => {
const result = spawnSync(path.resolve("node_modules/.bin/tsc"), ["--project", project, "--listFilesOnly"], {
encoding: "utf8",
});
if (result.error) throw result.error;
return { project, files: ownInputFiles(result.stdout).length };
});
const empty = counts.filter(({ files }) => files === 0);
if (projects.length === 0 || empty.length > 0) {
process.stderr.write(
projects.length === 0
? "Typecheck inputs: FAIL (no package script runs tsc --project)\n"
: `Typecheck inputs: FAIL (no input files: ${empty.map(({ project }) => project).join(", ")})\n`,
);
process.exitCode = 1;
} else {
process.stdout.write(
`Typecheck inputs: PASS (${counts.map(({ project, files }) => `${project} ${files}`).join(", ")})\n`,
);
}
}
+31 -109
View File
@@ -1,5 +1,4 @@
import { readFile } from "node:fs/promises";
import { createHash } from "node:crypto";
import path from "node:path";
import { z } from "zod";
@@ -312,6 +311,7 @@ const stageSchema = z
"PROD_PROMOTION_READY",
"FIELD_SLO_READY",
"DOCUMENTATION_READY",
"MAIN_READY",
]),
needs: z.array(id).max(16),
gateIds: z.array(id).min(1).max(64),
@@ -405,9 +405,9 @@ const jobSchema = z
.object({
id,
displayName: workflowValue,
kind: z.enum(["gate-matrix", "gate-single", "immutable", "provider", "promotion", "deployment"]),
kind: z.enum(["gate-matrix", "gate-sequence", "gate-single", "immutable", "provider", "promotion", "deployment"]),
needs: z.array(id).max(32),
condition: z.enum(["always", "needs-success", "merge", "release", "production", "field", "documentation"]),
condition: z.enum(["always", "needs-success", "merge", "main", "release", "production", "field", "documentation"]),
timeoutMinutes: z.number().int().positive(),
gateIds: z.array(id).max(64),
browserGateIds: z.array(id).max(64),
@@ -467,106 +467,10 @@ export type CiGateContractIndex = Readonly<{
export const RETIRED_GATE_IDS: readonly string[] = Object.freeze(["FE-GATE-016"]);
export const CANONICAL_GATE_IDS: readonly string[] = Object.freeze(
Array.from({ length: 28 }, (_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`)
Array.from({ length: 29 }, (_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`)
.filter((gateId) => !RETIRED_GATE_IDS.includes(gateId)),
);
/**
* D-13. The contract's size and gate shape are a reviewed baseline, not code
* constants: a project that removes a sample or adds a gate records the new
* shape with `update:ci-contract-baseline` (owner and reason required) and the
* diff of this file is what review sees.
*/
export const CI_CONTRACT_BASELINE_PATH = "config/ci/contract-baseline.json";
const ciContractBaselineSchema = z
.object({
schemaVersion: z.literal(1),
owner: nonEmpty,
reason: nonEmpty,
gates: z.number().int().nonnegative(),
commands: z.number().int().nonnegative(),
commandReferences: z.number().int().nonnegative(),
artifacts: z.number().int().nonnegative(),
stages: z.number().int().nonnegative(),
gateShapeSha256: z.string().regex(/^[0-9a-f]{64}$/u),
})
.strict();
export type CiContractBaseline = z.infer<typeof ciContractBaselineSchema>;
function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
const normalized = gates.map(
({
id,
name,
commandIds,
logArtifactId,
evidenceArtifactIds,
retentionClassId,
requiresEnvironment,
hostRequirements,
}) => ({
id,
name,
commandIds,
logArtifactId,
evidenceArtifactIds,
retentionClassId,
requiresEnvironment: requiresEnvironment ?? [],
// Only gates that declare runner requirements carry the key, so the
// digest of every other gate stays what it was.
...(hostRequirements === undefined ? {} : { hostRequirements }),
}),
);
return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
}
export function measureCiContractBaseline(
contract: CiGateContract,
): Omit<CiContractBaseline, "schemaVersion" | "owner" | "reason"> {
return {
gates: contract.gates.length,
commands: contract.commands.length,
commandReferences: contract.gates.reduce(
(total, gate) => total + gate.commandIds.length,
0,
),
artifacts: contract.artifacts.length,
stages: contract.stages.length,
gateShapeSha256: canonicalGateShapeSha256(contract.gates),
};
}
async function assertCiContractBaseline(
root: string,
contract: CiGateContract,
): Promise<void> {
const parsed = ciContractBaselineSchema.safeParse(
JSON.parse(await readFile(path.join(root, CI_CONTRACT_BASELINE_PATH), "utf8")),
);
if (!parsed.success) {
throw new TypeError(
`${CI_CONTRACT_BASELINE_PATH} invalid:\n${parsed.error.issues
.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
.join("\n")}`,
);
}
const baseline = parsed.data;
const drift = Object.entries(measureCiContractBaseline(contract))
.filter(([key, value]) => baseline[key as keyof CiContractBaseline] !== value)
.map(([key, value]) =>
`${key}: baseline ${String(baseline[key as keyof CiContractBaseline])}, contract ${String(value)}`
);
if (drift.length > 0) {
throw new TypeError(
`CI gate contract does not match ${CI_CONTRACT_BASELINE_PATH}:\n${drift.join("\n")}\n` +
"If the change is intended, review it and run " +
"CI_CONTRACT_BASELINE_OWNER=<team> CI_CONTRACT_BASELINE_REASON=<why> corepack pnpm update:ci-contract-baseline",
);
}
}
function retentionRegistryFailures(contract: CiGateContract): string[] {
const expectedRetentionClasses = [
{ id: "merge-cycle", policy: "at least through pull-request readiness decision" },
@@ -668,8 +572,6 @@ export async function loadCiGateContract(
`CI package script install policy invalid:\n${installPolicyFailures.join("\n")}`,
);
}
// The baseline describes the template contract; the overlay is the product's.
await assertCiContractBaseline(root, template);
return contract;
}
@@ -843,7 +745,7 @@ function validateContractSemantics(
const expectedGateIds = CANONICAL_GATE_IDS;
if (JSON.stringify(contract.gates.map(({ id }) => id)) !== JSON.stringify(expectedGateIds)) {
issue(`gate registry must contain FE-GATE-001..028 without retired ${RETIRED_GATE_IDS.join(", ")} in canonical order`);
issue(`gate registry must contain FE-GATE-001..029 without retired ${RETIRED_GATE_IDS.join(", ")} in canonical order`);
}
const expectedStages: ReadonlyArray<readonly [string, string, readonly string[], readonly string[]]> = [
["merge", "MERGE_READY", [], PROMOTION_FORMULA.MERGE_READY],
@@ -851,6 +753,7 @@ function validateContractSemantics(
["production", "PROD_PROMOTION_READY", ["release"], PROMOTION_FORMULA.PROD_PROMOTION_READY],
["field", "FIELD_SLO_READY", ["production"], PROMOTION_FORMULA.FIELD_SLO_READY],
["documentation", "DOCUMENTATION_READY", [], PROMOTION_FORMULA.DOCUMENTATION_READY],
["main", "MAIN_READY", [], PROMOTION_FORMULA.MAIN_READY],
];
const stageShape = contract.stages.map(({ id, readiness, needs, gateIds }) => [id, readiness, needs, gateIds]);
if (JSON.stringify(stageShape) !== JSON.stringify(expectedStages)) {
@@ -912,10 +815,16 @@ function validateContractSemantics(
if (gateOwners.length > 1) issue(`multiply owned gate: ${gate.id} by ${gateOwners.join(", ")}`);
}
const expectedJobOwnership: Readonly<Record<string, readonly string[]>> = {
// The merge stage runs as three jobs, one install each (design-docs
// repo-structure/03-ci.md F1): checks that read the source and build it,
// tests, and the gates that need browsers. Each runs its gates one after
// another in this order; a failed gate does not skip the next.
// 15-01. The bundle budget (FE-GATE-012) runs on every PR: a feature that
// pushes initial JavaScript over budget fails before it merges, not at the
// next tagged release.
merge_gate: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-008", "FE-GATE-009", "FE-GATE-010", "FE-GATE-011", "FE-GATE-012", "FE-GATE-013", "FE-GATE-020"],
merge_static: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-010", "FE-GATE-011", "FE-GATE-012"],
merge_test: ["FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-013", "FE-GATE-020"],
merge_browser: ["FE-GATE-008", "FE-GATE-009"],
release_gate: ["FE-GATE-014", "FE-GATE-026", "FE-GATE-028"],
immutable_build: ["FE-GATE-015", "FE-GATE-027"],
vulnerability_provider: [],
@@ -927,9 +836,12 @@ function validateContractSemantics(
production_gate: ["FE-GATE-019", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"],
field_gate: ["FE-GATE-018"],
documentation_gate: ["FE-GATE-017"],
// F2. The checkers' own negative fixtures and the gating coverage check
// run after a merge to main, not on every pull request.
main_gate: ["FE-GATE-029"],
};
if (JSON.stringify(contract.jobs.map(({ id }) => id)) !== JSON.stringify(Object.keys(expectedJobOwnership))) {
issue("job registry must contain the exact ten canonical jobs in semantic order");
issue("job registry must contain the exact thirteen canonical jobs in semantic order");
}
for (const [jobId, gateIds] of Object.entries(expectedJobOwnership)) {
const job = contract.jobs.find(({ id }) => id === jobId);
@@ -938,8 +850,10 @@ function validateContractSemantics(
}
}
const expectedJobGraph: Readonly<Record<string, readonly [CiWorkflowJob["kind"], readonly string[], CiWorkflowJob["condition"]]>> = {
merge_gate: ["gate-matrix", [], "merge"],
release_gate: ["gate-matrix", ["merge_gate"], "release"],
merge_static: ["gate-sequence", [], "merge"],
merge_test: ["gate-sequence", [], "merge"],
merge_browser: ["gate-sequence", [], "merge"],
release_gate: ["gate-matrix", ["merge_static", "merge_test", "merge_browser"], "release"],
immutable_build: ["immutable", ["release_gate"], "release"],
vulnerability_provider: ["provider", ["immutable_build"], "always"],
provenance_provider: ["provider", ["immutable_build"], "always"],
@@ -948,6 +862,7 @@ function validateContractSemantics(
production_gate: ["gate-matrix", ["immutable_build", "promotion", "deployment"], "production"],
field_gate: ["gate-single", ["production_gate"], "field"],
documentation_gate: ["gate-single", [], "documentation"],
main_gate: ["gate-sequence", [], "main"],
};
for (const [jobId, [kind, needs, condition]] of Object.entries(expectedJobGraph)) {
const job = contract.jobs.find(({ id }) => id === jobId);
@@ -956,7 +871,9 @@ function validateContractSemantics(
}
}
const expectedStepKinds: Readonly<Record<string, readonly CiWorkflowStep["kind"][]>> = {
merge_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
merge_static: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
merge_test: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
merge_browser: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
release_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"],
immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload", "upload"],
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
@@ -966,6 +883,7 @@ function validateContractSemantics(
production_gate: ["checkout", "setup-node", "frozen-install", "download", "extract", "run-gate", "upload"],
field_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
documentation_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
main_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
};
for (const [jobId, expected] of Object.entries(expectedStepKinds)) {
const actual = contract.jobs.find(({ id }) => id === jobId)?.steps.map(({ kind }) => kind);
@@ -974,7 +892,9 @@ function validateContractSemantics(
}
}
const expectedEnvironmentBindings: Readonly<Record<string, readonly Readonly<{ name: string; value: string }> []>> = {
merge_gate: [],
merge_static: [],
merge_test: [],
merge_browser: [],
release_gate: [],
immutable_build: [
// FE-GATE-027 admits the built artifact to a named environment, so both
@@ -1037,6 +957,7 @@ function validateContractSemantics(
{ name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" },
],
documentation_gate: [],
main_gate: [],
};
for (const job of contract.jobs) {
const environmentNames = job.environment.map(({ name }) => name);
@@ -1361,6 +1282,7 @@ function validateJobStepKinds(
): void {
const allowed: Readonly<Record<z.infer<typeof jobSchema>["kind"], ReadonlySet<string>>> = {
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "download", "extract", "run-gate", "upload"]),
"gate-sequence": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]),
"gate-single": new Set(["checkout", "setup-node", "frozen-install", "run-gate", "upload"]),
immutable: new Set(["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"]),
provider: new Set(["checkout", "setup-node", "frozen-install", "download", "extract", "run-provider", "validate-provider-evidence", "upload"]),
+16 -3
View File
@@ -880,7 +880,7 @@ const manualA11yResultSchema = z
})
.strict()
.superRefine((result, context) => {
if (result.path !== `artifacts/tests/a11y-manual/${result.routeId}.md`) {
if (result.path !== `docs/accessibility/route-reviews/${result.routeId}.md`) {
context.addIssue({ code: "custom", path: ["path"], message: "path must match routeId" });
}
const hasIdentity = Boolean(
@@ -1429,7 +1429,7 @@ export const documentationReviewArtifactSchema = z
reportDigestValid: z.boolean(),
/**
* The manual accessibility review scope: the installed routes that have no
* record file under artifacts/tests/a11y-manual/. It is derived from the
* record file under docs/accessibility/route-reviews/. It is derived from the
* route registry, not read off a document (1101/14-05).
*/
routeScope: z.array(
@@ -1472,6 +1472,18 @@ export const documentationReviewArtifactSchema = z
})
.strict(),
).min(1),
// R6·R7 of docs/manual/03-outside-feature-folder.md: a manual example that
// points at a deletable sample feature, or infrastructure configuration
// copied into a current document.
layoutRuleViolations: z.array(
z
.object({
path: nonEmptyString,
rule: z.enum(["R6", "R7"]),
detail: nonEmptyString,
})
.strict(),
),
results: z.array(
z
.object({
@@ -1523,9 +1535,10 @@ export const documentationReviewArtifactSchema = z
entry.missingScripts.length === 0 &&
entry.unknownGateIds.length === 0,
) &&
artifact.layoutRuleViolations.length === 0 &&
artifact.results.every(({ passed }) => passed))
) {
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references and review results" });
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references, layout rules and review results" });
}
});
+2 -2
View File
@@ -375,7 +375,7 @@ export function planFeature(
: []),
...planned.map(
(route) =>
[`artifacts/tests/a11y-manual/${route.routeId}.md`, renderA11yRecord(route.routeId)] as const,
[`docs/accessibility/route-reviews/${route.routeId}.md`, renderA11yRecord(route.routeId)] as const,
),
]);
return Object.freeze({
@@ -1767,7 +1767,7 @@ function report(plan: FeaturePlan): string {
"",
"Next:",
` 1. Before a release, have a person review and sign ${plan.routes
.map((route) => `artifacts/tests/a11y-manual/${route.routeId}.md`)
.map((route) => `docs/accessibility/route-reviews/${route.routeId}.md`)
.join(", ")} (FE-GATE-028). The merge gates check only their format.`,
" 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage in config/ci/gates.json (README lists the loop). test:feature-scaffold runs them on a generated feature except the browser gates FE-GATE-008/009 and test:system.",
` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`,
+4 -4
View File
@@ -15,22 +15,22 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const ARTIFACT_SCHEMA_DEFINITIONS = Object.freeze([
{
relativePath: "schemas/artifacts/build-manifest.schema.json",
relativePath: "config/schemas/artifacts/build-manifest.schema.json",
id: undefined,
schema: buildManifestArtifactSchema,
},
{
relativePath: "schemas/artifacts/dependency-inventory.schema.json",
relativePath: "config/schemas/artifacts/dependency-inventory.schema.json",
id: "https://clean-architecture-frontend.local/schemas/dependency-inventory.schema.json",
schema: dependencyInventoryArtifactSchema,
},
{
relativePath: "schemas/artifacts/registry-snapshot.schema.json",
relativePath: "config/schemas/artifacts/registry-snapshot.schema.json",
id: undefined,
schema: registrySnapshotArtifactSchema,
},
{
relativePath: "schemas/artifacts/supply-chain-verification.schema.json",
relativePath: "config/schemas/artifacts/supply-chain-verification.schema.json",
id: "https://clean-architecture-frontend.local/schemas/supply-chain-verification.schema.json",
schema: supplyChainVerificationArtifactSchema,
},
+18 -3
View File
@@ -71,7 +71,7 @@ const PRODUCT_GATE_JOB = "product_merge_gate";
* gate stopped nothing but a PR merge: the same run went on to release, build,
* promote and deploy, and the fixed job graph left a product no way to link
* them. release_gate is the first release-stage job, and every later one
* depends on it as it depends on merge_gate. The link is rendered from the
* depends on it as it depends on the merge jobs. The link is rendered from the
* overlay, so the template contract's job graph (and its check) stays the
* template's, and without product gates the workflow bytes do not change.
*/
@@ -108,6 +108,7 @@ export function renderCiWorkflow(
" type: choice",
" options:",
" - merge",
" - main",
" - release",
" - production",
" - field",
@@ -231,7 +232,7 @@ function renderJob(
}
}
lines.push(" steps:");
for (const step of job.steps) lines.push(...renderStep(job, step, transfers));
for (const step of job.steps) lines.push(...renderStep(job, step, transfers, index));
return lines;
}
@@ -257,6 +258,7 @@ function renderStep(
job: CiWorkflowJob,
step: CiWorkflowStep,
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
index: ReturnType<typeof indexCiGateContract>,
): string[] {
switch (step.kind) {
case "checkout":
@@ -294,6 +296,16 @@ function renderStep(
return [" - name: Run blocking gate", " run: corepack pnpm ci:gate -- ${{ matrix.gate }}"];
}
if (job.gateIds.length === 0) throw new TypeError(`run-gate step lacks ownership: ${job.id}`);
// F2·F1 (design-docs repo-structure/03-ci.md). A job of several gates
// shares one install; each gate is a step named by its id, and a failed
// gate does not skip the ones after it, as the matrix entries did not.
if (job.kind === "gate-sequence") {
return job.gateIds.flatMap((gateId) => [
` - name: ${yamlScalar(`${gateId} / ${index.gates.get(gateId)?.name ?? ""}`)}`,
" if: ${{ !cancelled() }}",
` run: corepack pnpm ci:gate -- ${gateId}`,
]);
}
// 12-02: every gate the job owns runs, in order. Rendering only the first
// left FE-GATE-027 (release admission) out of the workflow.
return job.gateIds.flatMap((gateId) => [
@@ -426,7 +438,10 @@ function renderCondition(condition: CiWorkflowJob["condition"]): string | null {
const expressions: Record<CiWorkflowJob["condition"], string | null> = {
always: null,
"needs-success": null,
merge: "${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}",
merge: "${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }}",
// A push to a branch (main, develop) or a dispatch that asks for it; never
// a pull request or a tag.
main: "${{ (gitea.event_name == 'push' && startsWith(gitea.ref, 'refs/heads/')) || (gitea.event_name == 'workflow_dispatch' && inputs.stage == 'main') }}",
release: "${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}",
production: "${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}",
field: "${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'field' }}",
+4 -3
View File
@@ -4,11 +4,11 @@ export const ciContractReportSchema = z
.object({
schemaVersion: z.literal(2),
nodeVersion: z.string().regex(/^\d+\.\d+\.\d+$/u),
gateCount: z.literal(27),
gateCount: z.literal(28),
commandDefinitionCount: z.number().int().positive(),
commandReferenceCount: z.number().int().positive(),
artifactCount: z.number().int().positive(),
jobCount: z.literal(10),
jobCount: z.literal(13),
workflowSha256: z.string().regex(/^[a-f0-9]{64}$/u),
durationStatus: z.string().min(1),
negativeFixtures: z.array(
@@ -20,6 +20,7 @@ export const ciContractReportSchema = z
"PROD_PROMOTION_READY",
"FIELD_SLO_READY",
"DOCUMENTATION_READY",
"MAIN_READY",
]),
failedGate: z.string().regex(/^FE-GATE-\d{3}$/u),
passed: z.boolean(),
@@ -37,7 +38,7 @@ export const ciContractReportSchema = z
fail(["passed"], "passed must agree with failures");
}
if (
report.negativeFixtures.length !== 5 ||
report.negativeFixtures.length !== 6 ||
report.negativeFixtures.some((fixture) => !fixture.passed)
) {
fail(["negativeFixtures"], "every readiness negative fixture must pass");
+1 -1
View File
@@ -93,7 +93,7 @@ export const HISTORY_HOLDERS: ReadonlySet<string> = new Set([
// 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 NOT_DOCUMENT = /^docs\/accessibility\/route-reviews\//u;
const IGNORED_FOLDERS: ReadonlySet<string> = new Set(["node_modules", ".git"]);
const STATUS: Readonly<Record<RecordKind, readonly string[]>> = Object.freeze({
+1 -1
View File
@@ -17,7 +17,7 @@ import type { RemovalCheck } from "./removal-fixture.ts";
*/
const BROWSER =
"needs Playwright browsers. FE-GATE-020 runs in a merge job without them " +
"(merge_gate matrix browser: false). The generated routes in the browser " +
"(merge_test installs none). The generated routes in the browser " +
"gates are reviewed as 1103/12-01 and 12-03.";
const DRILL =
"a removal drill copies the repository again. The drill runs the generated " +
+3 -3
View File
@@ -122,12 +122,12 @@ export async function verifyLocalSupplyChainEvidence(
for (const [schemaPath, artifact, label] of [
[
"schemas/artifacts/dependency-inventory.schema.json",
"config/schemas/artifacts/dependency-inventory.schema.json",
inventory,
"dependency inventory",
],
[
"schemas/artifacts/supply-chain-verification.schema.json",
"config/schemas/artifacts/supply-chain-verification.schema.json",
verification,
"supply-chain verification",
],
@@ -1020,7 +1020,7 @@ export async function assessLocalEvidenceForProducer(input: Readonly<{
assertMatchesJsonSchema(
await readJson(
repositoryRoot,
"schemas/artifacts/build-manifest.schema.json",
"config/schemas/artifacts/build-manifest.schema.json",
),
buildManifest,
"build manifest",
+6
View File
@@ -40,6 +40,10 @@ export const PROMOTION_FORMULA = Object.freeze({
]),
FIELD_SLO_READY: Object.freeze(["FE-GATE-018"]),
DOCUMENTATION_READY: Object.freeze(["FE-GATE-017"]),
// F2 (design-docs repo-structure/03-ci.md 7.3). The checkers' negative
// fixtures and the gating coverage check run after a merge to main. They
// test the checkers, not the change, so they hold no promotion.
MAIN_READY: Object.freeze(["FE-GATE-029"]),
});
export type GateResult = "PASS" | "FAIL" | "UNVERIFIED";
@@ -58,6 +62,7 @@ export function evaluatePromotionReadiness(
const fieldReady =
productionReady && allPass(PROMOTION_FORMULA.FIELD_SLO_READY);
const documentationReady = allPass(PROMOTION_FORMULA.DOCUMENTATION_READY);
const mainReady = allPass(PROMOTION_FORMULA.MAIN_READY);
return Object.freeze({
MERGE_READY: mergeReady,
@@ -65,5 +70,6 @@ export function evaluatePromotionReadiness(
PROD_PROMOTION_READY: productionReady,
FIELD_SLO_READY: fieldReady,
DOCUMENTATION_READY: documentationReady,
MAIN_READY: mainReady,
});
}
+3 -3
View File
@@ -58,6 +58,9 @@ export const LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS = Object.freeze([
] as const);
export const LOCAL_EVIDENCE_POLICY_INPUT_PATHS = Object.freeze([
"config/schemas/artifacts/build-manifest.schema.json",
"config/schemas/artifacts/dependency-inventory.schema.json",
"config/schemas/artifacts/supply-chain-verification.schema.json",
"config/security/dependency-baseline.approval.json",
"config/security/dependency-baseline.json",
"config/security/dependency-change-evidence.json",
@@ -65,9 +68,6 @@ export const LOCAL_EVIDENCE_POLICY_INPUT_PATHS = Object.freeze([
"config/security/secret-scan-policy.json",
"config/security/vulnerability-exceptions.json",
"config/security/vulnerability-policy.json",
"schemas/artifacts/build-manifest.schema.json",
"schemas/artifacts/dependency-inventory.schema.json",
"schemas/artifacts/supply-chain-verification.schema.json",
...LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS,
] as const);
+13 -36
View File
@@ -20,23 +20,19 @@ import {
linkFixtureNodeModules,
} from "./fixture-node-modules.ts";
import { generateCiWorkflow } from "../generate-ci-workflow.ts";
import { updateCiContractBaseline } from "../update-ci-contract-baseline.ts";
import { selectRepositoryPaths } from "./repository-layout.ts";
export const REMOVAL_FIXTURE_COPY_TARGETS = Object.freeze([
"src", "tests", "recipes", "scripts", "schemas", "config", "public",
".gitea", ".storybook", "index.html", "package.json", "tsconfig.base.json",
"tsconfig.json", "tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json",
"tsconfig.recipes.json", "tsconfig.web-worker.json", "tsconfig.service-worker.json",
"vite.service-worker.config.ts", "vite.config.ts", "vitest.config.ts",
"playwright.config.ts", "playwright.capabilities.config.ts", "playwright.dev.config.ts",
"playwright.storybook.config.ts", "playwright.visual.config.ts", "eslint.config.ts",
".dependency-cruiser.json", ".nvmrc", ".gitignore",
// Install and workspace identity. Without these the fixture is not the same
// project: `corepack pnpm` resolves a different store, and the provider
// suites — which build a release candidate containing `pnpm-lock.yaml` —
// cannot assemble their fixture at all.
".npmrc", "pnpm-lock.yaml", "pnpm-workspace.yaml",
] as const);
/**
* The fixture-copy set of config/repository-layout.json (R2). It includes the
* install and workspace identity (`.npmrc`, `pnpm-lock.yaml`,
* `pnpm-workspace.yaml`): without them the fixture is not the same project,
* `corepack pnpm` resolves a different store, and the provider suites — which
* build a release candidate containing `pnpm-lock.yaml` — cannot assemble
* their fixture at all. It also carries the manual a11y review records
* (docs/accessibility/route-reviews), which unit tests read, without the rest
* of `docs/`.
*/
export const REMOVAL_FIXTURE_COPY_TARGETS = selectRepositoryPaths("fixture-copy");
/**
* This is the only copy-target list. Each removal script used to keep its own,
@@ -53,14 +49,7 @@ export const REMOVAL_FIXTURE_COPY_TARGETS = Object.freeze([
* the documents describe the capability they delete, and what those drills
* prove is that the code still builds and tests without it.
*/
export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([
"README.md",
"CHANGELOG.md",
"docs",
// The root rule book. docs/README.md section 1 links it, so verify:documentation
// in the fixture reads it as a current contract document.
"AGENTS.md",
] as const);
export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = selectRepositoryPaths("fixture-documents");
/**
* 1103/02-06. Tests that read REMOVAL_FIXTURE_DOCUMENT_TARGETS. A fixture
@@ -522,16 +511,4 @@ export async function pruneRemovalFixtureCiContract(options: Readonly<{
writeFile(packagePath, `${JSON.stringify(packageDocument, null, 2)}\n`),
writeFile(gatesPath, `${JSON.stringify(validated, null, 2)}\n`),
]);
// D-13: the reduced contract is a new baseline, recorded the way a project
// that removes the capability records it; canonical check:ci then applies.
// 1103/16-02. A product feature owns no CI script; an empty list used to
// leave a trailing blank that the baseline schema refuses.
await updateCiContractBaseline(options.root, {
owner: "removal-fixture",
reason: `removal fixture pruned ${
options.removedScripts.size === 0
? "no CI scripts"
: [...options.removedScripts].join(", ")
}`,
});
}
+141
View File
@@ -0,0 +1,141 @@
import { readFileSync } from "node:fs";
/**
* The repository root registry, config/repository-layout.json (R1 in
* docs/manual/03-outside-feature-folder.md). Every tracked root item has an
* entry, and every list of root paths is a named set chosen from it (R2).
* Seven places used to keep their own literal lists of root paths, each a
* different subset, so moving one root item meant editing all seven
* (design-docs repo-structure/04-frontend-layout.md §2.4).
*/
export const REPOSITORY_LAYOUT_SETS = Object.freeze([
"fixture-copy",
"fixture-documents",
"secret-scan",
"history-free",
"scale-source",
"vite-build",
"typescript-only",
] as const);
export type RepositoryLayoutSet = (typeof REPOSITORY_LAYOUT_SETS)[number];
export const REPOSITORY_LAYOUT_KINDS = Object.freeze([
"source",
"tool-convention",
"gate-input",
"document",
"history",
"output",
] as const);
export type RepositoryLayoutKind = (typeof REPOSITORY_LAYOUT_KINDS)[number];
export type RepositoryLayoutEntry = Readonly<{
/** A root item name: one path segment, no slash. */
path: string;
kind: RepositoryLayoutKind;
role: string;
readBy: string;
/** A removal drill or a product copy may not have it; a selection skips it when absent. */
optional: boolean;
/** The sets that select the whole item. */
sets: readonly RepositoryLayoutSet[];
/** The sets that select only these paths inside the item. */
setPaths: Readonly<Partial<Record<RepositoryLayoutSet, readonly string[]>>>;
}>;
export const REPOSITORY_LAYOUT_FILE = "config/repository-layout.json";
export function parseRepositoryLayout(value: unknown): readonly RepositoryLayoutEntry[] {
const document = record(value, "layout");
if (document["schemaVersion"] !== 1) throw new Error("layout: schemaVersion must be 1");
const entries = document["entries"];
if (!Array.isArray(entries) || entries.length === 0) {
throw new Error("layout: entries must be a non-empty array");
}
const seen = new Set<string>();
return Object.freeze(
entries.map((raw, index) => {
const entry = record(raw, `entries[${index}]`);
const at = `entries[${index}]`;
const itemPath = text(entry["path"], `${at}.path`);
if (itemPath.includes("/")) throw new Error(`${at}.path: a root item has no slash: ${itemPath}`);
if (seen.has(itemPath)) throw new Error(`${at}.path: duplicate root item ${itemPath}`);
seen.add(itemPath);
const kind = text(entry["kind"], `${at}.kind`);
if (!(REPOSITORY_LAYOUT_KINDS as readonly string[]).includes(kind)) {
throw new Error(`${at}.kind: unknown kind ${kind}`);
}
const sets = (entry["sets"] ?? []) as unknown;
if (!Array.isArray(sets)) throw new Error(`${at}.sets must be an array`);
const setPaths = record(entry["setPaths"] ?? {}, `${at}.setPaths`);
for (const set of [...sets, ...Object.keys(setPaths)]) {
if (!(REPOSITORY_LAYOUT_SETS as readonly string[]).includes(set as string)) {
throw new Error(`${at}: unknown set ${String(set)}`);
}
}
for (const [set, paths] of Object.entries(setPaths)) {
if (!Array.isArray(paths) || paths.length === 0) {
throw new Error(`${at}.setPaths.${set} must be a non-empty array`);
}
for (const inner of paths) {
if (typeof inner !== "string" || !inner.startsWith(`${itemPath}/`)) {
throw new Error(`${at}.setPaths.${set}: ${String(inner)} is not inside ${itemPath}`);
}
}
if (sets.includes(set)) throw new Error(`${at}: ${set} selects the whole item and paths in it`);
}
return Object.freeze({
path: itemPath,
kind: kind as RepositoryLayoutKind,
role: text(entry["role"], `${at}.role`),
readBy: text(entry["readBy"], `${at}.readBy`),
optional: entry["optional"] === true,
sets: Object.freeze([...sets] as RepositoryLayoutSet[]),
setPaths: Object.freeze(setPaths as Partial<Record<RepositoryLayoutSet, readonly string[]>>),
});
}),
);
}
export const REPOSITORY_LAYOUT: readonly RepositoryLayoutEntry[] = parseRepositoryLayout(
JSON.parse(readFileSync(new URL(`../../${REPOSITORY_LAYOUT_FILE}`, import.meta.url), "utf8")),
);
/** The paths a set selects, in registry order. */
export function selectRepositoryPaths(
set: RepositoryLayoutSet,
layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT,
): readonly string[] {
return Object.freeze(
layout.flatMap((entry) =>
entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])],
),
);
}
/** Like selectRepositoryPaths, with whether a drill or a copy may lack each path. */
export function selectRepositoryEntries(
set: RepositoryLayoutSet,
layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT,
): readonly Readonly<{ path: string; optional: boolean }>[] {
return Object.freeze(
layout.flatMap((entry) =>
(entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])]).map(
(selected) => Object.freeze({ path: selected, optional: entry.optional }),
),
),
);
}
function record(value: unknown, at: string): Record<string, unknown> {
if (typeof value !== "object" || value === null || Array.isArray(value)) {
throw new Error(`${at} must be an object`);
}
return value as Record<string, unknown>;
}
function text(value: unknown, at: string): string {
if (typeof value !== "string" || value.trim() === "") throw new Error(`${at} must be a non-empty string`);
return value;
}
+4 -11
View File
@@ -1,3 +1,5 @@
import { selectRepositoryPaths } from "./repository-layout.ts";
/**
* 1105/15-03. The files `vite build` reads from the repository root, for the
* measurements and tests that copy them into a temporary root and build
@@ -7,15 +9,6 @@
* a new local import in vite.config.ts broke both, and both had to be edited
* (7f9a515, 799ab7f). tests/unit/vite-build-inputs.test.ts fails, naming the
* file, when vite.config.ts imports a local file this list does not cover.
* The list is the vite-build set of config/repository-layout.json (R2).
*/
export const VITE_BUILD_INPUTS = Object.freeze([
"src",
"public",
"index.html",
"package.json",
"vite.config.ts",
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/run-isolation.ts",
"scripts/lib/vite-module-inventory.ts",
] as const);
export const VITE_BUILD_INPUTS = selectRepositoryPaths("vite-build");
-1
View File
@@ -42,7 +42,6 @@ try {
});
const removedCiScripts = new Set([
"check:types:recipes",
"test:recipes",
"check:optional-recipes",
"check:optional-recipes:source",
-52
View File
@@ -1,52 +0,0 @@
import { readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import {
CI_CONTRACT_BASELINE_PATH,
measureCiContractBaseline,
parseCiGateContract,
type CiContractBaseline,
} from "./contracts/ci-gates.ts";
/**
* D-13. Records the current `config/ci/gates.json` size and gate shape as the
* reviewed baseline. Run it after an intended contract change; the diff of
* `config/ci/contract-baseline.json` is what review approves.
*/
export async function updateCiContractBaseline(
root: string,
approval: Readonly<{ owner: string; reason: string }>,
): Promise<CiContractBaseline> {
const contract = parseCiGateContract(
JSON.parse(await readFile(path.join(root, "config/ci/gates.json"), "utf8")),
);
const baseline: CiContractBaseline = {
schemaVersion: 1,
owner: approval.owner,
reason: approval.reason,
...measureCiContractBaseline(contract),
};
await writeFile(
path.join(root, CI_CONTRACT_BASELINE_PATH),
`${JSON.stringify(baseline, null, 2)}\n`,
);
return baseline;
}
const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isCli) {
const owner = process.env.CI_CONTRACT_BASELINE_OWNER;
const reason = process.env.CI_CONTRACT_BASELINE_REASON;
if (!owner || !reason) {
process.stderr.write(
"CI_CONTRACT_BASELINE_OWNER and CI_CONTRACT_BASELINE_REASON are required.\n",
);
process.exit(1);
}
const baseline = await updateCiContractBaseline(process.cwd(), { owner, reason });
process.stdout.write(
`CI contract baseline updated: ${baseline.gates} gates, ${baseline.commands} commands, ` +
`${baseline.commandReferences} command references, ${baseline.artifacts} artifacts\n`,
);
}
+2 -2
View File
@@ -24,7 +24,7 @@ type ManualA11yResult = Readonly<{
if (process.argv.includes("--format-only")) {
const failures: string[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const path = `docs/accessibility/route-reviews/${routeId}.md`;
const record = await readFile(path, "utf8").catch(() => null);
const invalid = record === null ? ["missing record"] : validateManualA11yRecordFormat(record, routeId);
if (invalid.length > 0) failures.push(`${path}: ${invalid.join(", ")}`);
@@ -41,7 +41,7 @@ if (process.argv.includes("--format-only")) {
const results: ManualA11yResult[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const path = `docs/accessibility/route-reviews/${routeId}.md`;
const evidence = await readFile(path, "utf8");
const validation = validateManualA11yEvidence(evidence);
const failures =
+51 -3
View File
@@ -7,7 +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 { checkDocsSystem, checkedForDrift, deletableHistory, HISTORY_HOLDERS, livingDocuments } from "./lib/docs-system.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts";
import {
REMOVABLE_TEMPLATE_FEATURES,
@@ -22,7 +22,7 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
* every new feature edit two template-owned documents (1101/14-05), so the
* documents now name this folder and the record files are what is checked.
*/
const MANUAL_A11Y_RECORDS = "artifacts/tests/a11y-manual/";
const MANUAL_A11Y_RECORDS = "docs/accessibility/route-reviews/";
type DocumentationReview = Readonly<{
sourcePath: string;
@@ -167,7 +167,8 @@ const DOCUMENT_INDEX = "docs/README.md";
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).
// worker is NOT_SELECTED; docs/manual/03-outside-feature-folder.md says how
// to add it with its own tsconfig.
"src/adapters/web-worker",
]);
// pnpm's own commands, which are not package scripts.
@@ -411,6 +412,46 @@ const documentReferencesValid = documentReferences.every(
(entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.length === 0,
);
// Repository layout rules of docs/manual/03-outside-feature-folder.md.
// R6: the manual's examples point at generator output or at code blocks in
// the manual, never at a sample feature a copy is meant to delete (the
// template's own sample took the manual's examples with it on 2026-11-07).
// R7: host, cluster and infrastructure configuration (nginx, Kubernetes,
// Helm, Terraform) lives in the infrastructure repository; a current document
// links to it and states the host contract (config/hosting/, FE-GATE-019)
// instead of carrying a copy. The history folders are records and keep what
// they recorded: the current documents are the living documents
// scripts/lib/docs-system.ts reads for drift (records and decision records out).
const INFRASTRUCTURE_FENCE = /^\s*```\s*(nginx|hcl|terraform|helm)\b/iu;
const INFRASTRUCTURE_MANIFEST =
/^\s*kind:\s*(Deployment|StatefulSet|DaemonSet|Ingress|Service|ConfigMap|CronJob|HelmRelease|Kustomization)\s*$/u;
const sampleFeaturePaths = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => removableTemplateFeaturePaths(feature));
const currentDocuments = [
"README.md",
...((await readdir("docs", { recursive: true }).catch(() => [])) as string[])
.filter((name) => name.endsWith(".md"))
.map((name) => `docs/${name}`)
.filter(checkedForDrift),
].sort();
const layoutRuleViolations: { path: string; rule: "R6" | "R7"; detail: string }[] = [];
for (const document of currentDocuments) {
const text = await readFile(document, "utf8").catch(() => null);
if (text === null) continue;
let fenced = false;
text.split("\n").forEach((line, index) => {
if (/^\s*```/u.test(line)) fenced = !fenced;
if (INFRASTRUCTURE_FENCE.test(line) || (fenced && INFRASTRUCTURE_MANIFEST.test(line))) {
layoutRuleViolations.push({ path: document, rule: "R7", detail: `line ${index + 1}: ${line.trim()}` });
}
if (!document.startsWith("docs/manual/")) return;
for (const samplePath of sampleFeaturePaths) {
if (line.includes(samplePath)) {
layoutRuleViolations.push({ path: document, rule: "R6", detail: `line ${index + 1}: ${samplePath}` });
}
}
});
}
// 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);
@@ -425,6 +466,7 @@ const failedChecks = [
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
...(sourceStructureDocumented ? [] : ["source structure"]),
...(documentReferencesValid ? [] : ["document references"]),
...(layoutRuleViolations.length === 0 ? [] : ["repository layout rules"]),
...(reportDigestValid ? [] : ["2026-07-18 diagram review copy digest"]),
...(results.length === 2 && results.every((result) => result.passed)
? []
@@ -449,6 +491,7 @@ await writeValidatedJsonArtifact({
missingRuntimeVariables,
sourceStructure,
documentReferences,
layoutRuleViolations,
results,
passed,
},
@@ -486,6 +529,11 @@ if (!passed) {
);
}
}
for (const violation of layoutRuleViolations) {
process.stderr.write(
`${violation.path} breaks ${violation.rule} of docs/manual/03-outside-feature-folder.md: ${violation.detail}\n`,
);
}
if (documentReferences.some((entry) => entry.missingPaths.some((file) => file.startsWith("../")))) {
const checked = [...pairedTrees]
.filter(([, tree]) => "paths" in tree)
+15 -16
View File
@@ -5,6 +5,8 @@ import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
import { arch, platform, userInfo } from "node:os";
import path from "node:path";
import { selectRepositoryPaths } from "./lib/repository-layout.ts";
/**
* Executable evidence for the extreme-scale acceptance matrix.
*
@@ -46,20 +48,8 @@ export const EXTREME_SCALE_GATES = Object.freeze([
"check:scale:release",
] as const);
/** Inputs whose content defines "the current code" for this evidence. */
const SOURCE_ROOTS = Object.freeze(["src", "scripts", "tests", "config", ".storybook", "recipes"]);
const SOURCE_FILES = Object.freeze([
"package.json",
"pnpm-lock.yaml",
".dependency-cruiser.json",
"eslint.config.ts",
"vite.config.ts",
"vitest.config.ts",
"tsconfig.json",
"tsconfig.app.json",
"tsconfig.test.json",
"tsconfig.node.json",
]);
/** Inputs whose content defines "the current code": the scale-source set of config/repository-layout.json (R2). */
const SOURCE_PATHS = selectRepositoryPaths("scale-source");
async function listFiles(directory: string): Promise<string[]> {
const found: string[] = [];
@@ -80,8 +70,17 @@ async function listFiles(directory: string): Promise<string[]> {
/** sha256 over every source input (path + content), in a stable order. */
export async function sourceDigest(root: string): Promise<Readonly<{ digest: string; files: number }>> {
const files = [
...(await Promise.all(SOURCE_ROOTS.map((entry) => listFiles(path.join(root, entry))))).flat(),
...SOURCE_FILES.map((file) => path.join(root, file)).filter((file) => existsSync(file)),
...(
await Promise.all(
SOURCE_PATHS.map((entry) => path.join(root, entry)).map(async (target) =>
(await stat(target).catch(() => null))?.isDirectory()
? listFiles(target)
: existsSync(target)
? [target]
: [],
),
)
).flat(),
]
.map((file) => path.relative(root, file))
.sort();
+1 -1
View File
@@ -129,7 +129,7 @@ if (liveTarget?.passed && !slotEmpty) {
} else {
mode = "fixture";
const fixture = await readDocument(
"config/hosting/response-headers.fixture.json",
"tests/fixtures/hosting/response-headers.json",
);
responses = responseHeaders(fixture.responses);
}
+1 -1
View File
@@ -95,7 +95,7 @@ const buildManifestDocument: unknown = JSON.parse(
);
assertMatchesJsonSchema(
JSON.parse(
await readFile("schemas/artifacts/build-manifest.schema.json", "utf8"),
await readFile("config/schemas/artifacts/build-manifest.schema.json", "utf8"),
),
buildManifestDocument,
"build manifest",
+1 -1
View File
@@ -1,4 +1,4 @@
{
"jobId": "merge_gate",
"jobId": "merge_static",
"needs": ["release_gate"]
}
+1 -1
View File
@@ -1,4 +1,4 @@
{
"jobId": "merge_gate",
"jobId": "merge_static",
"needs": ["missing"]
}
+1 -1
View File
@@ -1,4 +1,4 @@
{
"jobId": "merge_gate",
"jobId": "merge_static",
"removeGateId": "FE-GATE-001"
}
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2739
import type { ApplicationApi } from "../../../src/application/create-application.ts";
export const incompleteApplication: ApplicationApi = {
@@ -1,3 +1,4 @@
// expect: TS2322
import type { ApplicationOutputPorts } from "../../../src/application/create-application.ts";
export const invalidOutputPorts: ApplicationOutputPorts = {
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2322
import type { AsyncOverlay } from "../../../src/application/view-models/async-state.ts";
export const invalidPendingConflict: AsyncOverlay = {
+1
View File
@@ -1,3 +1,4 @@
// expect: pass
import type { DiagnosticsPort } from "../../../src/application/ports/diagnostics-port.ts";
import type { TelemetryPort } from "../../../src/application/ports/telemetry-port.ts";
@@ -1,3 +1,4 @@
// expect: TS2345
import type { InstalledHttpOperationExecutor } from "../../../src/adapters/http/index.ts";
import { composeFeatureAdapterInputs } from "../../../src/features/feature-adapter-contribution.ts";
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2322
import type { AppFailure } from "../../../src/contracts/errors.ts";
export const invalidFailure: AppFailure = {
@@ -1,3 +1,4 @@
// expect: TS2339
import { defineFeatureAdapterContribution } from "../../../src/features/feature-adapter-contribution.ts";
import { createFixtureFeatureInstalledInput } from "./fixture-feature-contract.ts";
@@ -1,3 +1,4 @@
// expect: TS2322
import { defineFeatureAdapterContribution } from "../../../src/features/feature-adapter-contribution.ts";
import type {} from "./fixture-feature-contract.ts";
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2345
import type { ApplicationApi } from "../../../src/application/ports/in/application-api.ts";
import type { FixtureFeatureInput } from "./fixture-feature-contract.ts";
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2345
import {
createFeatureHttpBinding,
defineFeatureHttpOperation,
@@ -1,3 +1,4 @@
// expect: TS2353
import type { FixtureHttpBinding } from "./fixture-feature-contract.ts";
declare const http: FixtureHttpBinding;
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2322
import { defineFeatureHttpOperationForRoutes } from "../../../src/adapters/http/index.ts";
import {
mapEntityPayload,
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2322
import { defineFeatureHttpOperation } from "../../../src/adapters/http/index.ts";
import { TEST_GET_ENTITY_CONTRACT } from "./fixture-feature-contract.ts";
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2741
import { IconButton, MenuIcon } from "../../../src/presentation/design-system/index.ts";
export const InvalidIconButton = <IconButton><MenuIcon /></IconButton>;
@@ -1,3 +1,4 @@
// expect: TS2741
import type {
ImageAssetReference,
ImageCdnPresentationPort,
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2345
import { formatMessage } from "../../../src/presentation/i18n/index.ts";
formatMessage("ko-KR", "unknown.translation.key");
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2554
import { formatMessage } from "../../../src/presentation/i18n/index.ts";
formatMessage("en-US", "route.documentTitle");
+1
View File
@@ -1,3 +1,4 @@
// expect: TS1360
import type { PageActionDefinition } from "../../../src/presentation/templates/index.ts";
export const activeButtonWithoutCallback = {
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2322
// This deliberately failing fixture proves that TypeScript rejects a wrong shape.
function execute(request: { operationId: string }) {
@@ -1,3 +1,4 @@
// expect: TS2322
interface ClockPort {
now(): number;
}
@@ -1,3 +1,4 @@
// expect: TS2741
import type { FixtureHttpBinding } from "./fixture-feature-contract.ts";
declare const http: FixtureHttpBinding;
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2339
import type { Result } from "../../../src/contracts/result.ts";
export function invalidUnwrap(result: Result<number, string>): number {
+1
View File
@@ -1,3 +1,4 @@
// expect: TS2741
import { ROUTE_RUNTIME_CONTRACT } from "../../../src/features/installed-feature-contracts.ts";
type RouteId = keyof typeof ROUTE_RUNTIME_CONTRACT;
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-application-input.ts"
]
}
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-application-output.ts"
]
}
-6
View File
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-async-overlay.ts"
]
}
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-diagnostics-port.ts"
]
}
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-direct-feature-composition.ts"
]
}
-6
View File
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-failure-kind.ts"
]
}
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-feature-capability-selection.ts"
]
}
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-feature-contribution-input.ts"
]
}
-6
View File
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-feature-input.ts"
]
}
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-http-operation-id.ts"
]
}
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-http-operation-input.ts"
]
}
-6
View File
@@ -1,6 +0,0 @@
{
"extends": "./tsconfig.base.json",
"files": [
"./invalid-http-route-id.ts"
]
}

Some files were not shown because too many files have changed in this diff Show More