diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index 35af29d9..a2b9c247 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -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 diff --git a/.gitignore b/.gitignore index 7347b810..5708900a 100644 --- a/.gitignore +++ b/.gitignore @@ -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. diff --git a/CHANGELOG.md b/CHANGELOG.md index efd60bc1..2c948011 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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/ 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: )`로 실패한다 (`bf485f44`) +9. **수동 a11y 기록을 옮긴다.** `artifacts/tests/a11y-manual/.md` → `docs/accessibility/route-reviews/.md`(자기 라우트 기록도 `git mv`). `.gitignore`가 더는 `artifacts/` 아래 `.md`를 들이지 않는다. 남기면 `tests/unit/tracked-artifacts.test.ts`가 그 파일을 이름으로 실패시키고, 옮기지 않으면 `verify:documentation`이 `docs/accessibility/route-reviews/ has no record for route 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-`에서 `merge-static-`·`merge-test-`·`merge-browser-`으로 바뀌었다 (`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:`). 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)을 잡지 못한다. 옛 골든도 같았다. diff --git a/README.md b/README.md index 42108896..28124130 100644 --- a/README.md +++ b/README.md @@ -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/.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/.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나 진입 압축이 없는 호스트는 실패한다. diff --git a/config/ci/contract-baseline.json b/config/ci/contract-baseline.json deleted file mode 100644 index 439cde3c..00000000 --- a/config/ci/contract-baseline.json +++ /dev/null @@ -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" -} diff --git a/config/ci/gates.json b/config/ci/gates.json index ab728fce..1d8fe31c 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -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": { diff --git a/config/recipes/frontend-capability-recipes.json b/config/recipes/frontend-capability-recipes.json index 39bb5882..c25cfb96 100644 --- a/config/recipes/frontend-capability-recipes.json +++ b/config/recipes/frontend-capability-recipes.json @@ -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", diff --git a/config/repository-layout.json b/config/repository-layout.json new file mode 100644 index 00000000..8ce7b17a --- /dev/null +++ b/config/repository-layout.json @@ -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"] + } + ] +} diff --git a/schemas/artifacts/build-manifest.schema.json b/config/schemas/artifacts/build-manifest.schema.json similarity index 100% rename from schemas/artifacts/build-manifest.schema.json rename to config/schemas/artifacts/build-manifest.schema.json diff --git a/schemas/artifacts/dependency-inventory.schema.json b/config/schemas/artifacts/dependency-inventory.schema.json similarity index 100% rename from schemas/artifacts/dependency-inventory.schema.json rename to config/schemas/artifacts/dependency-inventory.schema.json diff --git a/schemas/artifacts/registry-snapshot.schema.json b/config/schemas/artifacts/registry-snapshot.schema.json similarity index 100% rename from schemas/artifacts/registry-snapshot.schema.json rename to config/schemas/artifacts/registry-snapshot.schema.json diff --git a/schemas/artifacts/supply-chain-verification.schema.json b/config/schemas/artifacts/supply-chain-verification.schema.json similarity index 100% rename from schemas/artifacts/supply-chain-verification.schema.json rename to config/schemas/artifacts/supply-chain-verification.schema.json diff --git a/schemas/config/frontend-capability-recipes.schema.json b/config/schemas/recipes/frontend-capability-recipes.schema.json similarity index 100% rename from schemas/config/frontend-capability-recipes.schema.json rename to config/schemas/recipes/frontend-capability-recipes.schema.json diff --git a/config/security/secret-scan-policy.json b/config/security/secret-scan-policy.json index ab836f0a..a1bd645c 100644 --- a/config/security/secret-scan-policy.json +++ b/config/security/secret-scan-policy.json @@ -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", diff --git a/docs/README.md b/docs/README.md index 54cec9f6..199314e3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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/.md`) | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) | +| 라우트별 수동 접근성 기록(`accessibility/route-reviews/.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. 기록 문서의 머리 블록 diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 5dce5a37..85f320e3 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -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 하나에 기록 하나를 두고, 이름은 `.md`로 한다. template 필드를 diff --git a/artifacts/tests/a11y-manual/APP_HOME.md b/docs/accessibility/route-reviews/APP_HOME.md similarity index 100% rename from artifacts/tests/a11y-manual/APP_HOME.md rename to docs/accessibility/route-reviews/APP_HOME.md diff --git a/artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md b/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md similarity index 100% rename from artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md rename to docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md diff --git a/artifacts/tests/a11y-manual/NOT_FOUND.md b/docs/accessibility/route-reviews/NOT_FOUND.md similarity index 100% rename from artifacts/tests/a11y-manual/NOT_FOUND.md rename to docs/accessibility/route-reviews/NOT_FOUND.md diff --git a/docs/architecture/optional-adapter-recipes.md b/docs/architecture/optional-adapter-recipes.md index da5355de..98803fbd 100644 --- a/docs/architecture/optional-adapter-recipes.md +++ b/docs/architecture/optional-adapter-recipes.md @@ -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 diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 264586ec..a0de081b 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -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-module.ts` | feature에 새 context가 필요할 때 | `generate:feature-index`: `Feature belongs to undeclared context ` | | `src/contexts//context-layout.tsx` | context에 `AppShell` 대신 자기 틀이 필요할 때(아래 "제품 홈과 레이아웃" 참고) | 없음. 파일이 없으면 context는 `AppShell` 안에서 렌더링된다 | -| `artifacts/tests/a11y-manual/.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/.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 '""' 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 needs , which the host did not provide`. 세션 owner가 없으면 `AUTH_MODE: "external"`은 세션이 `integration-failed`인 채로 부팅한다 | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 2f121ec5..d298aeb7 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -369,7 +369,7 @@ projectRequest: (input) => Object.freeze({ - application이 React·어댑터·presentation을 import하면 `check:architecture`가 `feature-application-does-not-know-runtime`으로 막는다. - 보강 키와 조립 기여의 `featureId`가 다르면 조립이 실패한다. - 메시지: `feature adapter contribution installed an input for ` -- 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 needs , which the host did not provide` - operation을 계약에 두고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다. @@ -430,7 +430,7 @@ projectRequest: (input) => Object.freeze({ - `presentation/-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다. - 문구 `route..title`, `route..navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다. - 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다. -- 기능 폴더 밖: `artifacts/tests/a11y-manual/.md`(pending 기록). 생성 명령이 만든다. +- 기능 폴더 밖: `docs/accessibility/route-reviews/.md`(pending 기록). 생성 명령이 만든다. ① **정할 것** @@ -506,7 +506,7 @@ export function useInvoiceListFilters(): InvoiceListSearch { - `context-routes.ts`의 handle이 계약에 없는 route ID를 가리키면 context 적재가 거부한다. - 메시지: `Route handle loaded by 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: ` + - `verify:documentation`(FE-GATE-017): `docs/accessibility/route-reviews/ has no record for route 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/.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/.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index 4e7ae418..b07a2a2f 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -24,7 +24,7 @@ - `src/contexts//context-module.ts` - 새 context일 때만 만든다. `--context`를 주면 만들지 않는다. - 왜 밖인가: context는 여러 기능이 함께 쓰는 소속 선언이다. 기능 하나가 갖지 않는다. -- `artifacts/tests/a11y-manual/.md` +- `docs/accessibility/route-reviews/.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/.md`를 채운다. +3. `docs/accessibility/route-reviews/.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=`는 복사본에서 지워 보고 게이트를 돈다. 실제 저장소에서 지울 때는 아래를 함께 지운다. - `src/features//`, `tests/features//` - 그 context의 마지막 기능이면 `src/contexts//` -- `artifacts/tests/a11y-manual/.md` (라우트마다) +- `docs/accessibility/route-reviews/.md` (라우트마다) - 남아도 검사는 실패하지 않는다. 검사는 등록된 라우트의 기록만 읽는다. 그래서 잊기 쉽다. - 기능 전용 `tests/e2e/` spec - `config/runtime/.json`의 `FEATURE_OVERRIDES` 키 diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md index f515d8f7..c57895af 100644 --- a/docs/manual/reference/create-feature.md +++ b/docs/manual/reference/create-feature.md @@ -81,7 +81,7 @@ corepack pnpm create:feature [--context ] [--with-create [--key 기능 폴더 밖: - `src/contexts/-context/context-module.ts`: 새 context일 때만 -- `artifacts/tests/a11y-manual/.md`: 라우트마다 pending 기록 +- `docs/accessibility/route-reviews/.md`: 라우트마다 pending 기록 ## 뼈대 모양 @@ -95,7 +95,7 @@ corepack pnpm create:feature [--context ] [--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/.md`)이 맡는다. +- `--with-create`의 상세 라우트는 자원 하나를 읽는다. 빈 목록으로 답할 수 없어 실패 화면에서만 axe를 돌린다. 그래서 `artifacts/tests/a11y.json`은 이 라우트를 통과(`scope`)로 세지 않고 `notChecked`에 이유와 함께 적는다. 화면 내용의 접근성은 수동 검토 기록(`docs/accessibility/route-reviews/.md`)이 맡는다. 한도·마감 같은 숫자는 `scripts/create-feature.ts`의 템플릿이 정본이다. @@ -119,7 +119,7 @@ create:feature: in (new context), route at created <파일> ... Next: - 1. Before a release, have a person review and sign artifacts/tests/a11y-manual/.md (FE-GATE-028). ... + 1. Before a release, have a person review and sign docs/accessibility/route-reviews/.md (FE-GATE-028). ... 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE- for each gate of the merge stage ... The feature's own tests: node scripts/run-vitest.ts run tests/features/ ... The registry baseline does not change: ... @@ -138,7 +138,7 @@ create:feature warning: no --package was given, so src/features//contracts/< 생성한 기능을 지우려면 만든 것을 지우고 생성기를 다시 돌린다. ```bash -rm -r src/features/ tests/features/ artifacts/tests/a11y-manual/.md +rm -r src/features/ tests/features/ docs/accessibility/route-reviews/.md rm -r src/contexts/-context # 새 context를 만들었을 때만 corepack pnpm generate:feature-index node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의 계약 패키지를 뺀다 diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 13f0823c..6bd93f7f 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -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: ` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 | -| `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 | +| `docs/accessibility/route-reviews/ has no record for route IDs: ` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 | +| `Manual accessibility record format is invalid:` 다음 `docs/accessibility/route-reviews/.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 | | `a11y.json not written:` 다음 `a11y: reads one resource () 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/-schema-metadata.ts`를 고친다 | | `Manual accessibility evidence is incomplete:` 다음 `: ` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) | | `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 | diff --git a/docs/manual/reference/global-ids.md b/docs/manual/reference/global-ids.md index 522b6249..c1364732 100644 --- a/docs/manual/reference/global-ids.md +++ b/docs/manual/reference/global-ids.md @@ -50,7 +50,7 @@ - 형식: `qinv.` + 소문자·숫자 26자. - `scripts/create-feature.ts`의 `randomTopicSuffix`가 같은 형식으로 만든다. - 다른 기능의 값을 복사하지 않는다. -- route ID는 `_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`artifacts/tests/a11y-manual/.md`). +- route ID는 `_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`docs/accessibility/route-reviews/.md`). - 문구 키는 ko-KR과 en-US에 같은 키를 넣는다. `check:i18n`이 비교한다. ## 정본 위치 diff --git a/docs/operations/adapter-remediation-ledger.md b/docs/operations/adapter-remediation-ledger.md index 64fd1d40..ca3aa55e 100644 --- a/docs/operations/adapter-remediation-ledger.md +++ b/docs/operations/adapter-remediation-ledger.md @@ -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`에서 멈춘다. 그래서 위의 나머지 테스트는 직접 돌렸다. diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 634c21a5..2dcc4a8a 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -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의 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/.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES. … 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/.md`가 +- 설치된 라우트마다 수동 접근성 기록 `docs/accessibility/route-reviews/.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