diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index 35af29d9..20d19234 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -170,6 +170,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 +180,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 \ diff --git a/.gitignore b/.gitignore index 34cdbac7..fd872656 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/README.md b/README.md index 8b0d536b..f2c7a518 100644 --- a/README.md +++ b/README.md @@ -301,7 +301,7 @@ Two gates intentionally need external evidence: - `review:a11y-manual` (release gate FE-GATE-028) needs a signed human keyboard/focus/screen-reader review of every registered route, one record - per route at `artifacts/tests/a11y-manual/.md`. The routes are + per route at `docs/accessibility/route-reviews/.md`. The routes are `ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a registered route has no record. The merge gate FE-GATE-009 runs only `review:a11y-manual -- --format-only`, which checks that every route record diff --git a/config/ci/contract-baseline.json b/config/ci/contract-baseline.json index 220ad79e..7426f344 100644 --- a/config/ci/contract-baseline.json +++ b/config/ci/contract-baseline.json @@ -1,11 +1,11 @@ { "schemaVersion": 1, "owner": "DongHyeonka", - "reason": "2026-11-07 소유자 결정: 정리 3단계(design-docs repo-structure/README.md 3.4절). 음성 타입 fixture 명령 23개를 실행기 하나(check-types-fixtures)로 합치고 check-types-recipes를 check:types:test에 넣는다", + "reason": "2026-11-07 소유자 결정: 정리 3단계(design-docs repo-structure/README.md 3.4절). 음성 타입 fixture 명령 23개를 실행기 하나로 합치고, 수동 a11y 기록을 docs/accessibility/route-reviews로, JSON Schema를 config/schemas로 옮긴다", "gates": 27, "commands": 76, "commandReferences": 80, "artifacts": 105, "stages": 5, - "gateShapeSha256": "963249d0ce7771677705f8f81e82fa5524dac2e57349063f96d8136ef252881d" + "gateShapeSha256": "5b2ded190e5c1cbfc31f0d8c90fa358defe87850d99dc4db5439426b9ed72a90" } diff --git a/config/ci/gates.json b/config/ci/gates.json index 2ff619ca..5877462a 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -985,14 +985,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" }, @@ -2004,8 +2004,8 @@ ], "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" @@ -2241,6 +2241,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", @@ -2248,9 +2251,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", diff --git a/config/recipes/frontend-capability-recipes.json b/config/recipes/frontend-capability-recipes.json index 386e792f..06a8329e 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..a118a672 --- /dev/null +++ b/config/repository-layout.json @@ -0,0 +1,320 @@ +{ + "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 설정·규칙·스킬. 하네스 작업(fe-c)이 더한다", + "readBy": "Claude Code", + "optional": true + }, + { + "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": ".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": "에이전트 진입 문서. 하네스 작업(fe-c)이 더한다", + "readBy": "코딩 에이전트", + "optional": true + }, + { + "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": "SPEC.md", + "kind": "history", + "role": "2026-09-25 라운드 요구사항. 문서 체계 작업(fe-b)이 이력 폴더로 옮기고 이 항목을 뺀다", + "readBy": "사람" + }, + { + "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 619d13e2..47c00289 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", diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 313cd9b8..7efc1122 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -1,7 +1,7 @@ # Manual accessibility review checklist Automated axe checks do not establish WCAG conformance. A human reviewer must -review every route record in `artifacts/tests/a11y-manual/` against one +review every route record in `docs/accessibility/route-reviews/` against one release candidate and sign them. The required scope is the route registry (`ROUTE_REGISTRY` in `src/features/installed-feature-contracts.ts`): one record per route, named `.md`. Copy the template fields exactly; the 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 c1722693..bde220aa 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` | 아니오 | diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index ef39a92c..2c2e8dec 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -222,7 +222,7 @@ Files outside the feature directory. Everything else a feature needs is in | `config/scale/feature-shape-ceilings.json` `initialJavascript` (tracked) | every added or removed feature, and every template change that moves the initial JavaScript: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. Commit it with the change; on a merge conflict run the command again | `test:unit` (the feature-shape growth test compares it with a build) | | `src/contexts//context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature belongs to undeclared context ` | | `src/contexts//context-layout.tsx` | the context needs its own frame instead of `AppShell` (see "Product home and layouts" below) | nothing: without it the context renders in `AppShell` | -| `artifacts/tests/a11y-manual/.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release | +| `docs/accessibility/route-reviews/.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release | | `tests/e2e/accessibility.spec.ts` | never per feature (1103/16-03): it fills every path parameter with one value and answers each API request from the installed descriptor, a list read with an empty list in its `responseEnvelope` frame. Edit it only for a protected page that sends something other than an installed GET before it renders | `test:a11y` (FE-GATE-009): a request no installed GET declares fails the route; so does an alert box (`role="alert"`) on a page that read only lists | | `src/features/product-capabilities.ts` (product-owned) | `needs` names a capability the template does not build: type it in `ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities` extends it, so the app, scripts and tests typecheck programs all see the key (an augmentation inside `product-composition.ts` is not seen by the scripts' program) | `check:types`: `Type '""' is not assignable to type 'keyof FeaturePlatformCapabilities'` in the feature | | `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: return the capability here, typed in `product-capabilities.ts`. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too. A product that owns the session (a BFF's httpOnly cookie) returns its session owner from `composeProductSessionOwner` instead of installing it on the host global before boot | `check:types`; at runtime `feature needs , which the host did not provide`. Without the session owner, `AUTH_MODE: "external"` boots with the session `integration-failed` | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 54b51178..1597c2c7 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -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 d96aeef6..ecdb4cd9 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`가 같아야 한다. @@ -205,7 +205,7 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE) - `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/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index e65b6c49..1f6a349a 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -126,7 +126,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` 규칙 이름을 diff --git a/scripts/check-architecture.ts b/scripts/check-architecture.ts index fbb07a33..250bc142 100644 --- a/scripts/check-architecture.ts +++ b/scripts/check-architecture.ts @@ -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 { } async function inspectTypeScriptOnlyPolicy(): Promise { - 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( diff --git a/scripts/check-optional-recipes.ts b/scripts/check-optional-recipes.ts index 535e9c87..8a7206f4 100644 --- a/scripts/check-optional-recipes.ts +++ b/scripts/check-optional-recipes.ts @@ -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", ), ), diff --git a/scripts/check-registries.ts b/scripts/check-registries.ts index 313ababb..d2129d9c 100644 --- a/scripts/check-registries.ts +++ b/scripts/check-registries.ts @@ -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", ), ), diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index 40a7a21c..180234d7 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -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( diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index 576ce866..7889dc6b 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -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- 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)`, diff --git a/scripts/generate-artifact-schemas.ts b/scripts/generate-artifact-schemas.ts index af9187ec..333f25e1 100644 --- a/scripts/generate-artifact-schemas.ts +++ b/scripts/generate-artifact-schemas.ts @@ -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, }, diff --git a/scripts/lib/local-release-evidence.ts b/scripts/lib/local-release-evidence.ts index 34051e35..9149872e 100644 --- a/scripts/lib/local-release-evidence.ts +++ b/scripts/lib/local-release-evidence.ts @@ -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", diff --git a/scripts/lib/release-candidate.ts b/scripts/lib/release-candidate.ts index 33403792..6ddb3cf5 100644 --- a/scripts/lib/release-candidate.ts +++ b/scripts/lib/release-candidate.ts @@ -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); diff --git a/scripts/lib/removal-fixture.ts b/scripts/lib/removal-fixture.ts index 0ca323c7..ce3469cd 100644 --- a/scripts/lib/removal-fixture.ts +++ b/scripts/lib/removal-fixture.ts @@ -20,23 +20,20 @@ import { linkFixtureNodeModules, } from "./fixture-node-modules.ts"; import { generateCiWorkflow } from "../generate-ci-workflow.ts"; +import { selectRepositoryPaths } from "./repository-layout.ts"; import { updateCiContractBaseline } from "../update-ci-contract-baseline.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.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,11 +50,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", -] as const); +export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = selectRepositoryPaths("fixture-documents"); /** * 1103/02-06. Tests that read REMOVAL_FIXTURE_DOCUMENT_TARGETS. A fixture diff --git a/scripts/lib/repository-layout.ts b/scripts/lib/repository-layout.ts new file mode 100644 index 00000000..0d05ab01 --- /dev/null +++ b/scripts/lib/repository-layout.ts @@ -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>>; +}>; + +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(); + 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>), + }); + }), + ); +} + +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 { + if (typeof value !== "object" || value === null || Array.isArray(value)) { + throw new Error(`${at} must be an object`); + } + return value as Record; +} + +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; +} diff --git a/scripts/lib/vite-build-inputs.ts b/scripts/lib/vite-build-inputs.ts index cc94af25..7db5777b 100644 --- a/scripts/lib/vite-build-inputs.ts +++ b/scripts/lib/vite-build-inputs.ts @@ -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"); diff --git a/scripts/verify-a11y-manual.ts b/scripts/verify-a11y-manual.ts index 5c562943..ef205fd8 100644 --- a/scripts/verify-a11y-manual.ts +++ b/scripts/verify-a11y-manual.ts @@ -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 = diff --git a/scripts/verify-documentation-readiness.ts b/scripts/verify-documentation-readiness.ts index 56fa1587..9bbf0648 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -21,7 +21,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; diff --git a/scripts/verify-extreme-scale.ts b/scripts/verify-extreme-scale.ts index 8bffa3bb..ae97e6c9 100644 --- a/scripts/verify-extreme-scale.ts +++ b/scripts/verify-extreme-scale.ts @@ -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 { const found: string[] = []; @@ -80,8 +70,17 @@ async function listFiles(directory: string): Promise { /** sha256 over every source input (path + content), in a stable order. */ export async function sourceDigest(root: string): Promise> { 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(); diff --git a/scripts/verify-hosting-headers.ts b/scripts/verify-hosting-headers.ts index f77db9f2..d46073d5 100644 --- a/scripts/verify-hosting-headers.ts +++ b/scripts/verify-hosting-headers.ts @@ -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); } diff --git a/scripts/verify-release.ts b/scripts/verify-release.ts index a5a718c7..c4eb5a9f 100644 --- a/scripts/verify-release.ts +++ b/scripts/verify-release.ts @@ -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", diff --git a/config/hosting/response-headers.fixture.json b/tests/fixtures/hosting/response-headers.json similarity index 100% rename from config/hosting/response-headers.fixture.json rename to tests/fixtures/hosting/response-headers.json diff --git a/tests/platform/release/cache-policy.test.ts b/tests/platform/release/cache-policy.test.ts index 8e23764b..4914f769 100644 --- a/tests/platform/release/cache-policy.test.ts +++ b/tests/platform/release/cache-policy.test.ts @@ -15,7 +15,7 @@ async function json(relative: string): Promise { const policy = (await json<{ surfaces: Surfaces }>("config/hosting/cache-policy.json")).surfaces; const fixtureHeaders = ( await json<{ responses: Record> }>( - "config/hosting/response-headers.fixture.json", + "tests/fixtures/hosting/response-headers.json", ) ).responses; diff --git a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap index a64963d1..0cbd5db1 100644 --- a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap +++ b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap @@ -173,6 +173,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 \\ @@ -180,9 +183,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 \\ diff --git a/tests/unit/create-feature.test.ts b/tests/unit/create-feature.test.ts index b85d6221..addc1b40 100644 --- a/tests/unit/create-feature.test.ts +++ b/tests/unit/create-feature.test.ts @@ -88,14 +88,14 @@ describe("create:feature rendering", () => { "src/features/invoice-feature/feature-module.ts", "tests/features/invoice-feature/invoice-feature-input.test.ts", "tests/features/invoice-feature/invoice-list-page.test.tsx", - "artifacts/tests/a11y-manual/INVOICE_LIST.md", + "docs/accessibility/route-reviews/INVOICE_LIST.md", ]), ); expect([...created.files.keys()].some((file) => file.includes("/domain/"))).toBe(false); expect(created.files.get("src/contexts/invoice-context/context-module.ts")).toContain( 'CONTEXT_ROUTE_PATH = "invoice/*"', ); - expect(created.files.get("artifacts/tests/a11y-manual/INVOICE_LIST.md")).toMatch( + expect(created.files.get("docs/accessibility/route-reviews/INVOICE_LIST.md")).toMatch( /^Status: pending-manual-review$/mu, ); }); @@ -232,8 +232,8 @@ describe("create:feature --with-create", () => { "src/features/invoice-feature/presentation/use-invoice-item.ts", "src/features/invoice-feature/presentation/use-invoice-create.ts", "tests/features/invoice-feature/invoice-create-page.test.tsx", - "artifacts/tests/a11y-manual/INVOICE_DETAIL.md", - "artifacts/tests/a11y-manual/INVOICE_CREATE.md", + "docs/accessibility/route-reviews/INVOICE_DETAIL.md", + "docs/accessibility/route-reviews/INVOICE_CREATE.md", ]), ); expect(created.routes).toEqual([ @@ -522,13 +522,13 @@ describe("create:feature writing", () => { it("refuses to overwrite and writes nothing when one target exists", async () => { const root = await emptyRoot(); const files = plan({ id: "invoice-feature" }).files; - await mkdir(path.join(root, "artifacts/tests/a11y-manual"), { recursive: true }); - await writeFile(path.join(root, "artifacts/tests/a11y-manual/INVOICE_LIST.md"), "kept\n"); + await mkdir(path.join(root, "docs/accessibility/route-reviews"), { recursive: true }); + await writeFile(path.join(root, "docs/accessibility/route-reviews/INVOICE_LIST.md"), "kept\n"); await expect(writeFeatureFiles(root, files)).rejects.toThrow( - /refusing to overwrite: artifacts\/tests\/a11y-manual\/INVOICE_LIST\.md/u, + /refusing to overwrite: docs\/accessibility\/route-reviews\/INVOICE_LIST\.md/u, ); - expect(await readdir(root)).toEqual(["artifacts"]); + expect(await readdir(root)).toEqual(["docs"]); }); it("refuses an existing feature directory", async () => { diff --git a/tests/unit/deletable-history-documents.test.ts b/tests/unit/deletable-history-documents.test.ts index 77dcdf98..5e32cfe8 100644 --- a/tests/unit/deletable-history-documents.test.ts +++ b/tests/unit/deletable-history-documents.test.ts @@ -1,8 +1,10 @@ -import { readdir, readFile } from "node:fs/promises"; +import { readdir, readFile, stat } from "node:fs/promises"; import path from "node:path"; import { describe, expect, it } from "vitest"; +import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; + /** * README.md, "Files you can delete after copying", tells a new project that * the build and the gates read none of the history documents except @@ -10,15 +12,11 @@ import { describe, expect, it } from "vitest"; * promise: they do not copy `docs/`. A test that opens a review document broke * all three removal checks (fix of 11-04), so the promise is checked here. */ -const CODE_ROOTS = ["src", "tests", "scripts", "config", "recipes", "schemas", ".gitea"]; -const ROOT_FILES = [ - "package.json", - "vite.config.ts", - "vitest.config.ts", - "eslint.config.ts", - "playwright.config.ts", - ".dependency-cruiser.json", -]; +// The history-free set of config/repository-layout.json (R2). The registry +// itself names every root item, history documents included (R1); naming a +// root item is not reading it. +const CODE_PATHS = selectRepositoryPaths("history-free"); +const LAYOUT_REGISTRY = "config/repository-layout.json"; // Built from pieces so that this file does not match itself. const REVIEWS = ["docs", "reviews", ""].join("/"); @@ -58,12 +56,16 @@ async function codeFiles(directory: string): Promise { } async function linesMatching(patterns: readonly RegExp[]): Promise { - const files = [ - ...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat(), - ...ROOT_FILES, - ]; + const files = ( + await Promise.all( + CODE_PATHS.map(async (entry) => + (await stat(entry).catch(() => null))?.isDirectory() ? codeFiles(entry) : [entry], + ), + ) + ).flat(); const matches: string[] = []; for (const file of files) { + if (file === LAYOUT_REGISTRY) continue; const lines = (await readFile(file, "utf8").catch(() => "")).split("\n"); lines.forEach((line, index) => { if (patterns.some((pattern) => pattern.test(line))) diff --git a/tests/unit/documentation-readiness.test.ts b/tests/unit/documentation-readiness.test.ts index ea9a5dd2..1cd46162 100644 --- a/tests/unit/documentation-readiness.test.ts +++ b/tests/unit/documentation-readiness.test.ts @@ -7,7 +7,7 @@ import path from "node:path"; import { describe, expect, it } from "vitest"; // The pin says which commit of the paired backend the documents describe. -const INPUTS = ["README.md", "docs", "artifacts/tests/a11y-manual", "config/contracts/backend-contract-pin.json"]; +const INPUTS = ["README.md", "docs", "config/contracts/backend-contract-pin.json"]; const PAIRED_BACKEND = "clean-architecture-backend-template"; type Changes = Readonly string>>; @@ -121,9 +121,9 @@ describe("verify:documentation failure output (1101/14-06)", () => { }); it("names the route ID that has no manual review record", async () => { - const result = await verify({}, ["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"]); + const result = await verify({}, ["docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md"]); expect(result.status).toBe(1); - expect(result.stderr).toContain("artifacts/tests/a11y-manual/ has no record for route IDs: EXAMPLES_PLATFORM"); + expect(result.stderr).toContain("docs/accessibility/route-reviews/ has no record for route IDs: EXAMPLES_PLATFORM"); expect(result.stderr).toMatch(/FAIL_UNVERIFIED \(failed: route scope\)/u); expect(result.stderr).not.toContain("scoped-review evidence"); }); @@ -131,7 +131,7 @@ describe("verify:documentation failure output (1101/14-06)", () => { it("names every failed check", async () => { const result = await verify( { "README.md": (readme) => readme.replaceAll("`RELEASE_TARGET`", "") }, - ["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"], + ["docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md"], ); expect(result.stderr).toContain("README.md does not name: RELEASE_TARGET"); expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u); diff --git a/tests/unit/hosting-probe.test.ts b/tests/unit/hosting-probe.test.ts index 0d980b33..1e221633 100644 --- a/tests/unit/hosting-probe.test.ts +++ b/tests/unit/hosting-probe.test.ts @@ -133,7 +133,7 @@ describe("SPA fallback and worker script surfaces (1101/13-04)", () => { }); expect(appRoute?.path).toMatch(/^\/[^.]+$/u); const { responses } = JSON.parse( - await readFile("config/hosting/response-headers.fixture.json", "utf8"), + await readFile("tests/fixtures/hosting/response-headers.json", "utf8"), ) as { responses: Record }; expect(responses["appRoute"]).toEqual(responses["index"]); }); @@ -510,11 +510,16 @@ describe("verify-hosting-headers on a promoted release root (1101/13-01)", () => const root = await mkdtemp(path.join(tmpdir(), "hosting-release-root-")); try { await mkdir(path.join(root, "config/hosting"), { recursive: true }); - for (const file of ["cache-policy.json", "security-headers.json", "response-headers.fixture.json"]) { + for (const file of ["cache-policy.json", "security-headers.json"]) { await copyFile(`config/hosting/${file}`, path.join(root, "config/hosting", file)); } + await mkdir(path.join(root, "tests/fixtures/hosting"), { recursive: true }); + await copyFile( + "tests/fixtures/hosting/response-headers.json", + path.join(root, "tests/fixtures/hosting/response-headers.json"), + ); if (editFixture) { - const fixturePath = path.join(root, "config/hosting/response-headers.fixture.json"); + const fixturePath = path.join(root, "tests/fixtures/hosting/response-headers.json"); const fixture = JSON.parse(await readFile(fixturePath, "utf8")) as { responses: Record>; }; diff --git a/tests/unit/json-schema.test.ts b/tests/unit/json-schema.test.ts index ad6c0430..fb5bfd0a 100644 --- a/tests/unit/json-schema.test.ts +++ b/tests/unit/json-schema.test.ts @@ -29,7 +29,7 @@ async function json(path: string): Promise { describe("checked-in JSON Schema execution", () => { it("accepts a build manifest and rejects undeclared output fields", async () => { - const schema = await json("schemas/artifacts/build-manifest.schema.json"); + const schema = await json("config/schemas/artifacts/build-manifest.schema.json"); const manifest = { schemaVersion: 1, buildId: "build-1", @@ -66,7 +66,7 @@ describe("checked-in JSON Schema execution", () => { it("resolves local schema definitions in the recipe catalog", async () => { const [schema, catalog] = await Promise.all([ - json("schemas/config/frontend-capability-recipes.schema.json"), + json("config/schemas/recipes/frontend-capability-recipes.schema.json"), json("config/recipes/frontend-capability-recipes.json"), ]); @@ -80,7 +80,7 @@ describe("checked-in JSON Schema execution", () => { await generateArtifactSchemas({ root }); const generatedPath = path.join( root, - "schemas/artifacts/dependency-inventory.schema.json", + "config/schemas/artifacts/dependency-inventory.schema.json", ); const generated = await readFile(generatedPath, "utf8"); expect(generated.endsWith("\n")).toBe(true); @@ -101,7 +101,7 @@ describe("checked-in JSON Schema execution", () => { it.each([ { name: "dependency inventory", - path: "schemas/artifacts/dependency-inventory.schema.json", + path: "config/schemas/artifacts/dependency-inventory.schema.json", value: { schemaVersion: 2, packageManager: "pnpm@11.17.0", @@ -124,7 +124,7 @@ describe("checked-in JSON Schema execution", () => { }, { name: "registry snapshot", - path: "schemas/artifacts/registry-snapshot.schema.json", + path: "config/schemas/artifacts/registry-snapshot.schema.json", value: { schemaVersion: 2, generatedAt: "2026-08-01T00:00:00.000Z", @@ -144,7 +144,7 @@ describe("checked-in JSON Schema execution", () => { }, { name: "supply-chain verification", - path: "schemas/artifacts/supply-chain-verification.schema.json", + path: "config/schemas/artifacts/supply-chain-verification.schema.json", value: { schemaVersion: 1, localStatus: "PASS", diff --git a/tests/unit/manual-a11y-evidence.test.ts b/tests/unit/manual-a11y-evidence.test.ts index dbd5672d..1bb99468 100644 --- a/tests/unit/manual-a11y-evidence.test.ts +++ b/tests/unit/manual-a11y-evidence.test.ts @@ -87,7 +87,7 @@ describe("manual accessibility evidence", () => { it("accepts every checked-in route record", () => { for (const routeId of MANUAL_A11Y_ROUTE_IDS) { - const record = readFileSync(`artifacts/tests/a11y-manual/${routeId}.md`, "utf8"); + const record = readFileSync(`docs/accessibility/route-reviews/${routeId}.md`, "utf8"); expect(validateManualA11yRecordFormat(record, routeId), routeId).toEqual([]); } }); diff --git a/tests/unit/release-artifacts.test.ts b/tests/unit/release-artifacts.test.ts index 760cfdff..83067e57 100644 --- a/tests/unit/release-artifacts.test.ts +++ b/tests/unit/release-artifacts.test.ts @@ -216,7 +216,7 @@ describe("release artifact contracts", () => { it.each([ ["viteManifest", "package.json"], - ["runtimeConfigSchema", "schemas/artifacts/build-manifest.schema.json"], + ["runtimeConfigSchema", "config/schemas/artifacts/build-manifest.schema.json"], ["moduleInventory", "package.json"], ] as const)("rejects %s outside its approved output root", async (field, value) => { const mismatches = await verifyBuildManifestOutputs( diff --git a/tests/unit/repository-layout.test.ts b/tests/unit/repository-layout.test.ts new file mode 100644 index 00000000..769dfc31 --- /dev/null +++ b/tests/unit/repository-layout.test.ts @@ -0,0 +1,135 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; + +import { describe, expect, it } from "vitest"; + +import { + parseRepositoryLayout, + REPOSITORY_LAYOUT, + REPOSITORY_LAYOUT_FILE, + selectRepositoryEntries, + selectRepositoryPaths, +} from "../../scripts/lib/repository-layout.ts"; + +/** + * The repository root registry: R1 (every root item is registered) and R2 + * (root path lists are chosen from the registry) of + * design-docs repo-structure/04-frontend-layout.md §11. + */ + +function trackedFiles(): string[] { + const listed = spawnSync("git", ["ls-files", "-z"], { encoding: "utf8" }); + if (listed.error || listed.status !== 0) { + throw new Error(`git ls-files failed: ${listed.error?.message ?? listed.stderr}`); + } + return listed.stdout.split("\0").filter((file) => file !== ""); +} + +const rootItemNames = new Set(REPOSITORY_LAYOUT.map((entry) => entry.path)); + +describe("repository layout registry (R1)", () => { + // A removal fixture copies part of the repository, so the claim is one way: + // whatever is tracked at the root is registered. A registered path that is + // gone fails where a set uses it (a copy or the secret scan cannot find it). + it("has an entry for every tracked root item", () => { + const roots = new Set(trackedFiles().map((file) => file.split("/")[0]!)); + expect( + [...roots].filter((root) => !rootItemNames.has(root)).sort(), + `add an entry with its role to ${REPOSITORY_LAYOUT_FILE}`, + ).toEqual([]); + }); + + it("rejects an entry that is not a root item, a duplicate and a path outside its item", () => { + const entry = { path: "src", kind: "source", role: "app", readBy: "build" }; + expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, path: "src/app" }] })).toThrow( + /no slash/u, + ); + expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [entry, entry] })).toThrow(/duplicate/u); + expect(() => + parseRepositoryLayout({ + schemaVersion: 1, + entries: [{ ...entry, setPaths: { "vite-build": ["scripts/lib/run-isolation.ts"] } }], + }), + ).toThrow(/not inside src/u); + expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, kind: "misc" }] })).toThrow( + /unknown kind/u, + ); + expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, sets: ["everything"] }] })).toThrow( + /unknown set/u, + ); + }); + + it("selects whole items and paths inside items in registry order", () => { + const layout = parseRepositoryLayout({ + schemaVersion: 1, + entries: [ + { path: ".gitea", kind: "tool-convention", role: "ci", readBy: "gitea", setPaths: { "secret-scan": [".gitea/workflows/a.yml"] } }, + { path: "recipes", kind: "source", role: "recipes", readBy: "tsc", optional: true, sets: ["secret-scan"] }, + { path: "src", kind: "source", role: "app", readBy: "build", sets: ["secret-scan", "vite-build"] }, + ], + }); + expect(selectRepositoryPaths("secret-scan", layout)).toEqual([".gitea/workflows/a.yml", "recipes", "src"]); + expect(selectRepositoryPaths("vite-build", layout)).toEqual(["src"]); + expect(selectRepositoryEntries("secret-scan", layout).filter(({ optional }) => optional)).toEqual([ + { path: "recipes", optional: true }, + ]); + }); +}); + +/** + * design-docs repo-structure/04-frontend-layout.md §2.4: seven places kept + * their own literal lists of root paths, each a different subset. Six are + * code; the seventh is the secret scan policy, a JSON document the release + * candidate carries, which keeps a copy of its set held equal here. + */ +const LAYOUT_CONSUMERS = Object.freeze([ + "scripts/lib/removal-fixture.ts", + "scripts/lib/vite-build-inputs.ts", + "scripts/verify-extreme-scale.ts", + "scripts/check-architecture.ts", + "tests/unit/deletable-history-documents.test.ts", +]); +/** It checked the policy against a list of its own; the copy check below replaces it. */ +const FORMER_CONSUMERS = Object.freeze(["tests/unit/supply-chain.test.ts"]); + +const STRING = String.raw`(?:"[^"\n]*"|'[^'\n]*'|` + "`[^`\\n]*`)"; +const STRING_ARRAY = new RegExp(String.raw`\[\s*${STRING}(?:\s*,\s*${STRING})+\s*,?\s*\]`, "gu"); + +/** Array literals of two or more string literals that are root item names. */ +function literalRootLists(source: string, roots: ReadonlySet): string[] { + const code = source.replace(/^\s*\/\/.*$/gmu, ""); + return [...code.matchAll(STRING_ARRAY)] + .map(([literal]) => [...literal.matchAll(new RegExp(STRING, "gu"))].map(([value]) => value.slice(1, -1))) + .filter((values) => new Set(values.filter((value) => roots.has(value))).size >= 2) + .map((values) => values.join(", ")); +} + +describe("root path lists (R2)", () => { + it.each(LAYOUT_CONSUMERS)("%s chooses a set from the registry", (consumer) => { + const source = readFileSync(consumer, "utf8"); + expect(source).toMatch(/repository-layout\.ts/u); + expect(literalRootLists(source, rootItemNames)).toEqual([]); + }); + + it.each(FORMER_CONSUMERS)("%s keeps no list of root paths", (consumer) => { + expect(literalRootLists(readFileSync(consumer, "utf8"), rootItemNames)).toEqual([]); + }); + + it("finds a literal root list", () => { + expect(literalRootLists(`const ROOTS = ["src", "tests", "other"];`, rootItemNames)).toEqual(["src, tests, other"]); + expect(literalRootLists(`const ROOTS = ["src"];\nconst X = ["a", "b"];`, rootItemNames)).toEqual([]); + }); + + // A removal fixture deletes some of these inputs on purpose — removing the + // browser file/storage capability takes the whole browser-capability harness + // with it — and prunes the policy to match. The claim is about the inputs + // this checkout has. + it("keeps the secret scan policy's roots equal to the secret-scan set", () => { + const policy = JSON.parse(readFileSync("config/security/secret-scan-policy.json", "utf8")) as { + trackedRoots: string[]; + }; + expect([...policy.trackedRoots].sort()).toEqual( + [...selectRepositoryPaths("secret-scan").filter((input) => existsSync(input))].sort(), + ); + }); +}); diff --git a/tests/unit/second-api-feature-registries.test.ts b/tests/unit/second-api-feature-registries.test.ts index 2dc6ba0d..37090de0 100644 --- a/tests/unit/second-api-feature-registries.test.ts +++ b/tests/unit/second-api-feature-registries.test.ts @@ -205,7 +205,7 @@ async function repositoryWithSecondFeature(featureContract = FEATURE_CONTRACT) { for (const entry of [ "src", "config/contracts", - "schemas/artifacts", + "config/schemas/artifacts", "scripts/check-diagnostics.ts", ]) { await cp(path.resolve(entry), path.join(root, entry), { recursive: true }); diff --git a/tests/unit/security-followup-fixture.ts b/tests/unit/security-followup-fixture.ts index 7ec9770e..abd55b60 100644 --- a/tests/unit/security-followup-fixture.ts +++ b/tests/unit/security-followup-fixture.ts @@ -436,6 +436,9 @@ export async function createArchivedAssessmentFixture(): Promise<{ })) .sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0)); const policyPaths = [ + "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", @@ -443,9 +446,6 @@ export async function createArchivedAssessmentFixture(): Promise<{ "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", diff --git a/tests/unit/service-worker-build-output.test.ts b/tests/unit/service-worker-build-output.test.ts index 0ec124e3..813e3936 100644 --- a/tests/unit/service-worker-build-output.test.ts +++ b/tests/unit/service-worker-build-output.test.ts @@ -113,11 +113,11 @@ describe("worker script hosting headers (0929/06-05)", () => { await rm(path.join(root, "dist"), { recursive: true, force: true }); await symlink(builds!.dist.active, path.join(root, "dist")); const fixture = JSON.parse( - await readFile("config/hosting/response-headers.fixture.json", "utf8"), + await readFile("tests/fixtures/hosting/response-headers.json", "utf8"), ) as { responses: Record> }; fixture.responses["serviceWorker"]!["cache-control"] = workerCacheControl; await writeFile( - path.join(root, "config/hosting/response-headers.fixture.json"), + path.join(root, "tests/fixtures/hosting/response-headers.json"), JSON.stringify(fixture), ); const env: NodeJS.ProcessEnv = { ...process.env }; diff --git a/tests/unit/supply-chain.test.ts b/tests/unit/supply-chain.test.ts index 2f8e05c7..1a247063 100644 --- a/tests/unit/supply-chain.test.ts +++ b/tests/unit/supply-chain.test.ts @@ -1,5 +1,4 @@ import { createHash, generateKeyPairSync, sign } from "node:crypto"; -import { existsSync } from "node:fs"; import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; @@ -532,46 +531,6 @@ describe("supply-chain policy", () => { ]); }); - // A removal fixture deletes some of these inputs on purpose — removing the - // browser file/storage capability takes the whole browser-capability harness - // with it. The claim is about the inputs this checkout has. - it("covers every mandatory release input in the secret scan policy", async () => { - const policy = JSON.parse( - await readFile("config/security/secret-scan-policy.json", "utf8"), - ) as { trackedRoots: string[] }; - const mandatory = [ - "index.html", - ".dependency-cruiser.json", - ".nvmrc", - ".npmrc", - "eslint.config.ts", - "package.json", - "pnpm-lock.yaml", - "pnpm-workspace.yaml", - "scripts", - "schemas", - "config", - ".gitea/workflows/quality-gates.yml", - "vite.config.ts", - "vite.service-worker.config.ts", - "vitest.config.ts", - "playwright.config.ts", - "playwright.capabilities.config.ts", - "playwright.dev.config.ts", - "playwright.storybook.config.ts", - "playwright.visual.config.ts", - "tsconfig.json", - "tsconfig.app.json", - "tsconfig.base.json", - "tsconfig.node.json", - "tsconfig.service-worker.json", - "tsconfig.test.json", - ]; - expect(policy.trackedRoots).toEqual( - expect.arrayContaining(mandatory.filter((input) => existsSync(input))), - ); - }); - it("parses every top-level lockfile package and validates SRI", () => { const parsed = parsePnpmLockfilePackages(` packages: diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts index f0ba8b96..67a5e6e1 100644 --- a/tests/unit/template-feature-removal-documents.test.ts +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -23,7 +23,7 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture. */ const CHECKER = "scripts/verify-documentation-readiness.ts"; /** What verify:documentation reads besides the code. */ -const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "artifacts/tests/a11y-manual"]); +const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs"]); const LISTED_SAMPLE = Object.freeze({ featureId: "listed-sample-feature", @@ -83,7 +83,7 @@ async function copyWithListedSample() { for (const entry of removableTemplateFeaturePaths(LISTED_SAMPLE)) { await rm(path.join(root, entry), { recursive: true, force: true }); } - await rm(path.join(root, "artifacts/tests/a11y-manual/LISTED_SAMPLE_LIST.md"), { force: true }); + await rm(path.join(root, "docs/accessibility/route-reviews/LISTED_SAMPLE_LIST.md"), { force: true }); expect(node(["scripts/generate-product-feature-index.ts"]).status).toBe(0); }, cleanUp: () => rm(parent, { recursive: true, force: true }), @@ -100,7 +100,7 @@ async function verifyDocuments(document: string, mutate: (text: string) => strin const root = path.join(parent, "frontend"); try { // The pin says which commit of the paired backend the documents describe. - const inputs = ["README.md", "docs", "artifacts/tests/a11y-manual", "config/contracts/backend-contract-pin.json"]; + const inputs = ["README.md", "docs", "config/contracts/backend-contract-pin.json"]; for (const entry of inputs) await cp(entry, path.join(root, entry), { recursive: true }); const target = path.join(root, document); await writeFile(target, mutate(await readFile(target, "utf8"))); diff --git a/tests/unit/tracked-artifacts.test.ts b/tests/unit/tracked-artifacts.test.ts index 856600b1..b4639ea1 100644 --- a/tests/unit/tracked-artifacts.test.ts +++ b/tests/unit/tracked-artifacts.test.ts @@ -5,15 +5,15 @@ import { describe, expect, it } from "vitest"; /** * 0929/14-01. `artifacts/` is run output, but screenshots and a coverage * report were committed there and stayed tracked with nothing reading them. - * `.gitignore` ignores the folder as a whole and re-includes only what people - * write or keep: the folder markers and the manual a11y reviews, which the - * a11y gates read (`config/ci/gates.json`). A file `git add -f` puts outside - * that list fails here. + * `.gitignore` ignores the folder as a whole and re-includes only the folder + * markers. The manual a11y reviews, which people write and the a11y gates + * read, moved to docs/accessibility/route-reviews/ on 2026-11-08, so the + * folder is output only (docs/manual/03-outside-feature-folder.md, R3). A + * file `git add -f` puts outside that list fails here. */ const ALLOWED = [ /^artifacts\/runbooks\/\.gitkeep$/u, /^artifacts\/tests\/\.gitkeep$/u, - /^artifacts\/tests\/a11y-manual\/[^/]+\.md$/u, ]; function trackedArtifacts(): string[] { @@ -27,7 +27,7 @@ function trackedArtifacts(): string[] { } describe("tracked artifacts", () => { - it("are only the folder markers and the manual a11y reviews", () => { + it("are only the folder markers", () => { expect( trackedArtifacts().filter((file) => !ALLOWED.some((pattern) => pattern.test(file))), ).toEqual([]);