refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다

루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
  들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
  `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
  집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
  같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
  공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
  추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
  문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
  스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
  `config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
  `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
  복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
  `tests/fixtures/hosting/response-headers.json`.

버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.

위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).

검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
This commit is contained in:
2026-11-08 17:41:07 +09:00
parent bf485f449a
commit 79dc945a67
58 changed files with 751 additions and 204 deletions
+3 -3
View File
@@ -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 \
-3
View File
@@ -23,9 +23,6 @@ artifacts/runbooks/*
!artifacts/tests/
artifacts/tests/*
!artifacts/tests/.gitkeep
!artifacts/tests/a11y-manual/
artifacts/tests/a11y-manual/*
!artifacts/tests/a11y-manual/*.md
# Local environment overrides. `.env.example` is the tracked template; every
# other `.env*` file is a developer's own machine and never enters the repo.
+1 -1
View File
@@ -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/<ROUTE_ID>.md`. The routes are
per route at `docs/accessibility/route-reviews/<ROUTE_ID>.md`. The routes are
`ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a
registered route has no record. The merge gate FE-GATE-009 runs only
`review:a11y-manual -- --format-only`, which checks that every route record
+2 -2
View File
@@ -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"
}
+9 -9
View File
@@ -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",
@@ -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",
+320
View File
@@ -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"]
}
]
}
-1
View File
@@ -7,7 +7,6 @@
"tests",
"config",
"public",
"schemas",
".storybook",
".gitea/workflows/quality-gates.yml",
".dependency-cruiser.json",
+1 -1
View File
@@ -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 `<ROUTE_ID>.md`. Copy the template fields exactly; the
@@ -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` | 아니오 |
+1 -1
View File
@@ -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>/context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
| `src/contexts/<context>/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/<ROUTE_ID>.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/<ROUTE_ID>.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 '"<capability>"' 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 <id> needs <capability>, which the host did not provide`. Without the session owner, `AUTH_MODE: "external"` boots with the session `integration-failed` |
+3 -3
View File
@@ -430,7 +430,7 @@ projectRequest: (input) => Object.freeze({
- `presentation/<base>-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다.
- 문구 `route.<ROUTE_ID>.title`, `route.<ROUTE_ID>.navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다.
- 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다.
- 기능 폴더 밖: `artifacts/tests/a11y-manual/<ROUTE_ID>.md`(pending 기록). 생성 명령이 만든다.
- 기능 폴더 밖: `docs/accessibility/route-reviews/<ROUTE_ID>.md`(pending 기록). 생성 명령이 만든다.
① **정할 것**
@@ -506,7 +506,7 @@ export function useInvoiceListFilters(): InvoiceListSearch {
- `context-routes.ts`의 handle이 계약에 없는 route ID를 가리키면 context 적재가 거부한다.
- 메시지: `Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (...)`
- 라우트별 a11y 기록이 없으면 세 곳이 잡는다.
- `verify:documentation`(FE-GATE-017): `artifacts/tests/a11y-manual/ has no record for route IDs: <ids>`
- `verify:documentation`(FE-GATE-017): `docs/accessibility/route-reviews/ has no record for route IDs: <ids>`
- `review:a11y-manual -- --format-only`(FE-GATE-009): `missing record`
- `test:unit`의 `tests/unit/manual-a11y-evidence.test.ts`
- en-US 문구 키가 ko-KR과 다르면 `check:i18n`(FE-GATE-010)이 `en-US catalog keys do not match ko-KR`로 실패한다.
@@ -790,7 +790,7 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature
- 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다.
- spec 본문은 이름 단위로 찾는다(1106/16-01). 적힌 그대로(대소문자 구분) 찾고, 앞뒤에 `[A-Za-z0-9_-]`가 붙으면 다른 이름이다. `test.describe("invoice-feature", …)`는 잔여이고, `product-feature`를 지울 때 `generate-product-feature-index.ts`처럼 더 긴 이름 안에 든 것은 잔여가 아니다. spec은 `test:all`(vitest)도 드릴의 다른 단계도 돌리지 않으므로 이 검사가 아니면 다음 CI의 브라우저 게이트에서야 실패한다.
- `-`가 없는 한 단어 ID·폴더 이름(`messages`, `status`)은 spec 본문에서 찾지 않는다. 템플릿 spec이 그 단어를 평범하게 쓰므로(`status: 200`, `getByRole("status")`) 찾으면 템플릿 spec이 잔여로 나온다.
- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec, `artifacts/tests/a11y-manual/<ROUTE_ID>.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec, `docs/accessibility/route-reviews/<ROUTE_ID>.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration`
+3 -3
View File
@@ -24,7 +24,7 @@
- `src/contexts/<context>/context-module.ts`
- 새 context일 때만 만든다. `--context`를 주면 만들지 않는다.
- 왜 밖인가: context는 여러 기능이 함께 쓰는 소속 선언이다. 기능 하나가 갖지 않는다.
- `artifacts/tests/a11y-manual/<ROUTE_ID>.md`
- `docs/accessibility/route-reviews/<ROUTE_ID>.md`
- 라우트마다 하나. `Status: pending-manual-review`로 만든다.
- 왜 밖인가: 수동 접근성 검토 기록은 라우트 단위로 한 폴더에 모은다. 릴리스 검토자가 한 곳에서 서명한다.
- pending 기록은 merge 게이트를 통과하고 릴리스 게이트를 넘지 못한다(원칙 7).
@@ -62,7 +62,7 @@ create:feature가 pending 기록을 만든다
1. 릴리스 후보 하나를 띄운다.
2. `docs/accessibility/manual-checklist.md`의 M1~M7과 스크린 리더 항목을 그 라우트에서 확인한다.
3. `artifacts/tests/a11y-manual/<ROUTE_ID>.md`를 채운다.
3. `docs/accessibility/route-reviews/<ROUTE_ID>.md`를 채운다.
- `Status: reviewed`, `Release ID`, `Reviewer`, `Reviewed at`, `Signature`, `Attestation: accepted`
- 항목마다 `pass` 또는 `not-applicable (<구체적 이유>)`
4. 모든 라우트 기록의 `Release ID`가 같아야 한다.
@@ -205,7 +205,7 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
- `src/features/<id>/`, `tests/features/<id>/`
- 그 context의 마지막 기능이면 `src/contexts/<context>/`
- `artifacts/tests/a11y-manual/<ROUTE_ID>.md` (라우트마다)
- `docs/accessibility/route-reviews/<ROUTE_ID>.md` (라우트마다)
- 남아도 검사는 실패하지 않는다. 검사는 등록된 라우트의 기록만 읽는다. 그래서 잊기 쉽다.
- 기능 전용 `tests/e2e/` spec
- `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` 키
+4 -4
View File
@@ -81,7 +81,7 @@ corepack pnpm create:feature <id> [--context <context id>] [--with-create [--key
기능 폴더 밖:
- `src/contexts/<base>-context/context-module.ts`: 새 context일 때만
- `artifacts/tests/a11y-manual/<ROUTE_ID>.md`: 라우트마다 pending 기록
- `docs/accessibility/route-reviews/<ROUTE_ID>.md`: 라우트마다 pending 기록
## 뼈대 모양
@@ -95,7 +95,7 @@ corepack pnpm create:feature <id> [--context <context id>] [--with-create [--key
- 쿼리 1개: `LIST_STANDARD` profile.
- 무효화 topic 1개, namespace 1개, edge 1개.
- 빈 배열 응답은 공유 빈 상태 화면으로 그린다. `tests/e2e/accessibility.spec.ts`는 이 목록 조회에 빈 목록을 Envelope 모양으로 답하고, 경고 상자가 없는지 본 뒤 axe를 돌린다. 그래서 생성한 목록 라우트는 빈 상태 화면으로 검사된다.
- `--with-create`의 상세 라우트는 자원 하나를 읽는다. 빈 목록으로 답할 수 없어 실패 화면에서만 axe를 돌린다. 그래서 `artifacts/tests/a11y.json`은 이 라우트를 통과(`scope`)로 세지 않고 `notChecked`에 이유와 함께 적는다. 화면 내용의 접근성은 수동 검토 기록(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`)이 맡는다.
- `--with-create`의 상세 라우트는 자원 하나를 읽는다. 빈 목록으로 답할 수 없어 실패 화면에서만 axe를 돌린다. 그래서 `artifacts/tests/a11y.json`은 이 라우트를 통과(`scope`)로 세지 않고 `notChecked`에 이유와 함께 적는다. 화면 내용의 접근성은 수동 검토 기록(`docs/accessibility/route-reviews/<ROUTE_ID>.md`)이 맡는다.
한도·마감 같은 숫자는 `scripts/create-feature.ts`의 템플릿이 정본이다.
@@ -119,7 +119,7 @@ create:feature: <id> in <context> (new context), route <ROUTE_ID> at <path>
created <파일> ...
Next:
1. Before a release, have a person review and sign artifacts/tests/a11y-manual/<ROUTE_ID>.md (FE-GATE-028). ...
1. Before a release, have a person review and sign docs/accessibility/route-reviews/<ROUTE_ID>.md (FE-GATE-028). ...
2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage ...
The feature's own tests: node scripts/run-vitest.ts run tests/features/<id> ...
The registry baseline does not change: ...
@@ -138,7 +138,7 @@ create:feature warning: no --package was given, so src/features/<id>/contracts/<
생성한 기능을 지우려면 만든 것을 지우고 생성기를 다시 돌린다.
```bash
rm -r src/features/<id> tests/features/<id> artifacts/tests/a11y-manual/<ROUTE_ID>.md
rm -r src/features/<id> tests/features/<id> docs/accessibility/route-reviews/<ROUTE_ID>.md
rm -r src/contexts/<base>-context # 새 context를 만들었을 때만
corepack pnpm generate:feature-index
node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의 계약 패키지를 뺀다
+2 -2
View File
@@ -175,8 +175,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `artifacts/tests/a11y-manual/ has no record for route IDs: <ids>` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 |
| `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/<ROUTE_ID>.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 |
| `docs/accessibility/route-reviews/ has no record for route IDs: <ids>` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 |
| `Manual accessibility record format is invalid:` 다음 `docs/accessibility/route-reviews/<ROUTE_ID>.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 |
| `a11y.json not written:` 다음 `a11y: <ROUTE_ID> reads one resource (<operationId>) but has no failure-state record in artifacts/tests/a11y-data-state` (`test:a11y`, FE-GATE-009) | 라우트의 `paramsSchema`가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록이 없다(1106/11-01). spec이 기록 호출을 놓쳤거나, 그 라우트의 페이지가 그 GET을 부르지 않아 spec이 실패 화면을 보지 않았다. 앞의 경우 그대로면 `a11y.json`이 그 라우트를 통과로 센다 | 페이지가 그 GET을 부르면 `tests/e2e/accessibility.spec.ts`의 기록 호출(`recordA11yDataState`)을 본다. 이때 기능 파일은 고치지 않는다. 페이지가 그 GET을 부르지 않으면(예: `/things/:thingId/parts/new` 같은 하위 항목 작성 폼이 상세 GET과 같은 `ThingParams`를 쓴다) 그 라우트에 자기 `paramsSchema`를 따로 둔다. 기능의 라우트 계약과 `contracts/<base>-schema-metadata.ts`를 고친다 |
| `Manual accessibility evidence is incomplete:` 다음 `<ROUTE_ID>: <failures>` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) |
| `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 |
+1 -1
View File
@@ -50,7 +50,7 @@
- 형식: `qinv.` + 소문자·숫자 26자.
- `scripts/create-feature.ts`의 `randomTopicSuffix`가 같은 형식으로 만든다.
- 다른 기능의 값을 복사하지 않는다.
- route ID는 `<BASE>_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`).
- route ID는 `<BASE>_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`docs/accessibility/route-reviews/<ROUTE_ID>.md`).
- 문구 키는 ko-KR과 en-US에 같은 키를 넣는다. `check:i18n`이 비교한다.
## 정본 위치
+1 -1
View File
@@ -126,7 +126,7 @@ DOCUMENTATION_READY (off-chain)
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
(`scripts/verify-documentation-readiness.ts`).
- 설치된 라우트마다 수동 접근성 기록 `artifacts/tests/a11y-manual/<ROUTE_ID>.md`가
- 설치된 라우트마다 수동 접근성 기록 `docs/accessibility/route-reviews/<ROUTE_ID>.md`가
있는지. 없으면 route ID를 적고 실패한다
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
- 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을
+6 -2
View File
@@ -9,6 +9,7 @@ import { ESLint } from "eslint";
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
import { checkArchitectureLintFixtures } from "./lib/architecture-lint-fixtures.ts";
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
import { selectRepositoryEntries } from "./lib/repository-layout.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type PathRule = Readonly<{ path?: string; pathNot?: string }>;
@@ -1044,8 +1045,11 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
}
async function inspectTypeScriptOnlyPolicy(): Promise<TypeScriptOnlyPolicy> {
const requiredRoots = ["src", "scripts", "tests", ".storybook"] as const;
const optionalRoots = ["recipes"] as const;
// The typescript-only set of config/repository-layout.json (R2). An optional
// root (recipes/) may be gone after a removal drill.
const selected = selectRepositoryEntries("typescript-only");
const requiredRoots = selected.filter(({ optional }) => !optional).map(({ path }) => path);
const optionalRoots = selected.filter(({ optional }) => optional).map(({ path }) => path);
const checkedRoots = [...requiredRoots, ...optionalRoots];
const files = (
await Promise.all(
+1 -1
View File
@@ -54,7 +54,7 @@ try {
assertMatchesJsonSchema(
JSON.parse(
await readFile(
"schemas/config/frontend-capability-recipes.schema.json",
"config/schemas/recipes/frontend-capability-recipes.schema.json",
"utf8",
),
),
+1 -1
View File
@@ -748,7 +748,7 @@ if (usesRepositoryBaseline && failures.length === 0) {
assertMatchesJsonSchema(
JSON.parse(
await readFile(
"schemas/artifacts/registry-snapshot.schema.json",
"config/schemas/artifacts/registry-snapshot.schema.json",
"utf8",
),
),
+2 -2
View File
@@ -880,7 +880,7 @@ const manualA11yResultSchema = z
})
.strict()
.superRefine((result, context) => {
if (result.path !== `artifacts/tests/a11y-manual/${result.routeId}.md`) {
if (result.path !== `docs/accessibility/route-reviews/${result.routeId}.md`) {
context.addIssue({ code: "custom", path: ["path"], message: "path must match routeId" });
}
const hasIdentity = Boolean(
@@ -1429,7 +1429,7 @@ export const documentationReviewArtifactSchema = z
reportDigestValid: z.boolean(),
/**
* The manual accessibility review scope: the installed routes that have no
* record file under artifacts/tests/a11y-manual/. It is derived from the
* record file under docs/accessibility/route-reviews/. It is derived from the
* route registry, not read off a document (1101/14-05).
*/
routeScope: z.array(
+2 -2
View File
@@ -375,7 +375,7 @@ export function planFeature(
: []),
...planned.map(
(route) =>
[`artifacts/tests/a11y-manual/${route.routeId}.md`, renderA11yRecord(route.routeId)] as const,
[`docs/accessibility/route-reviews/${route.routeId}.md`, renderA11yRecord(route.routeId)] as const,
),
]);
return Object.freeze({
@@ -1767,7 +1767,7 @@ function report(plan: FeaturePlan): string {
"",
"Next:",
` 1. Before a release, have a person review and sign ${plan.routes
.map((route) => `artifacts/tests/a11y-manual/${route.routeId}.md`)
.map((route) => `docs/accessibility/route-reviews/${route.routeId}.md`)
.join(", ")} (FE-GATE-028). The merge gates check only their format.`,
" 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage in config/ci/gates.json (README lists the loop). test:feature-scaffold runs them on a generated feature except the browser gates FE-GATE-008/009 and test:system.",
` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`,
+4 -4
View File
@@ -15,22 +15,22 @@ import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const ARTIFACT_SCHEMA_DEFINITIONS = Object.freeze([
{
relativePath: "schemas/artifacts/build-manifest.schema.json",
relativePath: "config/schemas/artifacts/build-manifest.schema.json",
id: undefined,
schema: buildManifestArtifactSchema,
},
{
relativePath: "schemas/artifacts/dependency-inventory.schema.json",
relativePath: "config/schemas/artifacts/dependency-inventory.schema.json",
id: "https://clean-architecture-frontend.local/schemas/dependency-inventory.schema.json",
schema: dependencyInventoryArtifactSchema,
},
{
relativePath: "schemas/artifacts/registry-snapshot.schema.json",
relativePath: "config/schemas/artifacts/registry-snapshot.schema.json",
id: undefined,
schema: registrySnapshotArtifactSchema,
},
{
relativePath: "schemas/artifacts/supply-chain-verification.schema.json",
relativePath: "config/schemas/artifacts/supply-chain-verification.schema.json",
id: "https://clean-architecture-frontend.local/schemas/supply-chain-verification.schema.json",
schema: supplyChainVerificationArtifactSchema,
},
+3 -3
View File
@@ -122,12 +122,12 @@ export async function verifyLocalSupplyChainEvidence(
for (const [schemaPath, artifact, label] of [
[
"schemas/artifacts/dependency-inventory.schema.json",
"config/schemas/artifacts/dependency-inventory.schema.json",
inventory,
"dependency inventory",
],
[
"schemas/artifacts/supply-chain-verification.schema.json",
"config/schemas/artifacts/supply-chain-verification.schema.json",
verification,
"supply-chain verification",
],
@@ -1020,7 +1020,7 @@ export async function assessLocalEvidenceForProducer(input: Readonly<{
assertMatchesJsonSchema(
await readJson(
repositoryRoot,
"schemas/artifacts/build-manifest.schema.json",
"config/schemas/artifacts/build-manifest.schema.json",
),
buildManifest,
"build manifest",
+3 -3
View File
@@ -58,6 +58,9 @@ export const LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS = Object.freeze([
] as const);
export const LOCAL_EVIDENCE_POLICY_INPUT_PATHS = Object.freeze([
"config/schemas/artifacts/build-manifest.schema.json",
"config/schemas/artifacts/dependency-inventory.schema.json",
"config/schemas/artifacts/supply-chain-verification.schema.json",
"config/security/dependency-baseline.approval.json",
"config/security/dependency-baseline.json",
"config/security/dependency-change-evidence.json",
@@ -65,9 +68,6 @@ export const LOCAL_EVIDENCE_POLICY_INPUT_PATHS = Object.freeze([
"config/security/secret-scan-policy.json",
"config/security/vulnerability-exceptions.json",
"config/security/vulnerability-policy.json",
"schemas/artifacts/build-manifest.schema.json",
"schemas/artifacts/dependency-inventory.schema.json",
"schemas/artifacts/supply-chain-verification.schema.json",
...LOCAL_EVIDENCE_VERIFIER_SOURCE_PATHS,
] as const);
+13 -20
View File
@@ -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
+141
View File
@@ -0,0 +1,141 @@
import { readFileSync } from "node:fs";
/**
* The repository root registry, config/repository-layout.json (R1 in
* docs/manual/03-outside-feature-folder.md). Every tracked root item has an
* entry, and every list of root paths is a named set chosen from it (R2).
* Seven places used to keep their own literal lists of root paths, each a
* different subset, so moving one root item meant editing all seven
* (design-docs repo-structure/04-frontend-layout.md §2.4).
*/
export const REPOSITORY_LAYOUT_SETS = Object.freeze([
"fixture-copy",
"fixture-documents",
"secret-scan",
"history-free",
"scale-source",
"vite-build",
"typescript-only",
] as const);
export type RepositoryLayoutSet = (typeof REPOSITORY_LAYOUT_SETS)[number];
export const REPOSITORY_LAYOUT_KINDS = Object.freeze([
"source",
"tool-convention",
"gate-input",
"document",
"history",
"output",
] as const);
export type RepositoryLayoutKind = (typeof REPOSITORY_LAYOUT_KINDS)[number];
export type RepositoryLayoutEntry = Readonly<{
/** A root item name: one path segment, no slash. */
path: string;
kind: RepositoryLayoutKind;
role: string;
readBy: string;
/** A removal drill or a product copy may not have it; a selection skips it when absent. */
optional: boolean;
/** The sets that select the whole item. */
sets: readonly RepositoryLayoutSet[];
/** The sets that select only these paths inside the item. */
setPaths: Readonly<Partial<Record<RepositoryLayoutSet, readonly string[]>>>;
}>;
export const REPOSITORY_LAYOUT_FILE = "config/repository-layout.json";
export function parseRepositoryLayout(value: unknown): readonly RepositoryLayoutEntry[] {
const document = record(value, "layout");
if (document["schemaVersion"] !== 1) throw new Error("layout: schemaVersion must be 1");
const entries = document["entries"];
if (!Array.isArray(entries) || entries.length === 0) {
throw new Error("layout: entries must be a non-empty array");
}
const seen = new Set<string>();
return Object.freeze(
entries.map((raw, index) => {
const entry = record(raw, `entries[${index}]`);
const at = `entries[${index}]`;
const itemPath = text(entry["path"], `${at}.path`);
if (itemPath.includes("/")) throw new Error(`${at}.path: a root item has no slash: ${itemPath}`);
if (seen.has(itemPath)) throw new Error(`${at}.path: duplicate root item ${itemPath}`);
seen.add(itemPath);
const kind = text(entry["kind"], `${at}.kind`);
if (!(REPOSITORY_LAYOUT_KINDS as readonly string[]).includes(kind)) {
throw new Error(`${at}.kind: unknown kind ${kind}`);
}
const sets = (entry["sets"] ?? []) as unknown;
if (!Array.isArray(sets)) throw new Error(`${at}.sets must be an array`);
const setPaths = record(entry["setPaths"] ?? {}, `${at}.setPaths`);
for (const set of [...sets, ...Object.keys(setPaths)]) {
if (!(REPOSITORY_LAYOUT_SETS as readonly string[]).includes(set as string)) {
throw new Error(`${at}: unknown set ${String(set)}`);
}
}
for (const [set, paths] of Object.entries(setPaths)) {
if (!Array.isArray(paths) || paths.length === 0) {
throw new Error(`${at}.setPaths.${set} must be a non-empty array`);
}
for (const inner of paths) {
if (typeof inner !== "string" || !inner.startsWith(`${itemPath}/`)) {
throw new Error(`${at}.setPaths.${set}: ${String(inner)} is not inside ${itemPath}`);
}
}
if (sets.includes(set)) throw new Error(`${at}: ${set} selects the whole item and paths in it`);
}
return Object.freeze({
path: itemPath,
kind: kind as RepositoryLayoutKind,
role: text(entry["role"], `${at}.role`),
readBy: text(entry["readBy"], `${at}.readBy`),
optional: entry["optional"] === true,
sets: Object.freeze([...sets] as RepositoryLayoutSet[]),
setPaths: Object.freeze(setPaths as Partial<Record<RepositoryLayoutSet, readonly string[]>>),
});
}),
);
}
export const REPOSITORY_LAYOUT: readonly RepositoryLayoutEntry[] = parseRepositoryLayout(
JSON.parse(readFileSync(new URL(`../../${REPOSITORY_LAYOUT_FILE}`, import.meta.url), "utf8")),
);
/** The paths a set selects, in registry order. */
export function selectRepositoryPaths(
set: RepositoryLayoutSet,
layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT,
): readonly string[] {
return Object.freeze(
layout.flatMap((entry) =>
entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])],
),
);
}
/** Like selectRepositoryPaths, with whether a drill or a copy may lack each path. */
export function selectRepositoryEntries(
set: RepositoryLayoutSet,
layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT,
): readonly Readonly<{ path: string; optional: boolean }>[] {
return Object.freeze(
layout.flatMap((entry) =>
(entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])]).map(
(selected) => Object.freeze({ path: selected, optional: entry.optional }),
),
),
);
}
function record(value: unknown, at: string): Record<string, unknown> {
if (typeof value !== "object" || value === null || Array.isArray(value)) {
throw new Error(`${at} must be an object`);
}
return value as Record<string, unknown>;
}
function text(value: unknown, at: string): string {
if (typeof value !== "string" || value.trim() === "") throw new Error(`${at} must be a non-empty string`);
return value;
}
+4 -11
View File
@@ -1,3 +1,5 @@
import { selectRepositoryPaths } from "./repository-layout.ts";
/**
* 1105/15-03. The files `vite build` reads from the repository root, for the
* measurements and tests that copy them into a temporary root and build
@@ -7,15 +9,6 @@
* a new local import in vite.config.ts broke both, and both had to be edited
* (7f9a515, 799ab7f). tests/unit/vite-build-inputs.test.ts fails, naming the
* file, when vite.config.ts imports a local file this list does not cover.
* The list is the vite-build set of config/repository-layout.json (R2).
*/
export const VITE_BUILD_INPUTS = Object.freeze([
"src",
"public",
"index.html",
"package.json",
"vite.config.ts",
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/run-isolation.ts",
"scripts/lib/vite-module-inventory.ts",
] as const);
export const VITE_BUILD_INPUTS = selectRepositoryPaths("vite-build");
+2 -2
View File
@@ -24,7 +24,7 @@ type ManualA11yResult = Readonly<{
if (process.argv.includes("--format-only")) {
const failures: string[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const path = `docs/accessibility/route-reviews/${routeId}.md`;
const record = await readFile(path, "utf8").catch(() => null);
const invalid = record === null ? ["missing record"] : validateManualA11yRecordFormat(record, routeId);
if (invalid.length > 0) failures.push(`${path}: ${invalid.join(", ")}`);
@@ -41,7 +41,7 @@ if (process.argv.includes("--format-only")) {
const results: ManualA11yResult[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const path = `docs/accessibility/route-reviews/${routeId}.md`;
const evidence = await readFile(path, "utf8");
const validation = validateManualA11yEvidence(evidence);
const failures =
+1 -1
View File
@@ -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;
+15 -16
View File
@@ -5,6 +5,8 @@ import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
import { arch, platform, userInfo } from "node:os";
import path from "node:path";
import { selectRepositoryPaths } from "./lib/repository-layout.ts";
/**
* Executable evidence for the extreme-scale acceptance matrix.
*
@@ -46,20 +48,8 @@ export const EXTREME_SCALE_GATES = Object.freeze([
"check:scale:release",
] as const);
/** Inputs whose content defines "the current code" for this evidence. */
const SOURCE_ROOTS = Object.freeze(["src", "scripts", "tests", "config", ".storybook", "recipes"]);
const SOURCE_FILES = Object.freeze([
"package.json",
"pnpm-lock.yaml",
".dependency-cruiser.json",
"eslint.config.ts",
"vite.config.ts",
"vitest.config.ts",
"tsconfig.json",
"tsconfig.app.json",
"tsconfig.test.json",
"tsconfig.node.json",
]);
/** Inputs whose content defines "the current code": the scale-source set of config/repository-layout.json (R2). */
const SOURCE_PATHS = selectRepositoryPaths("scale-source");
async function listFiles(directory: string): Promise<string[]> {
const found: string[] = [];
@@ -80,8 +70,17 @@ async function listFiles(directory: string): Promise<string[]> {
/** sha256 over every source input (path + content), in a stable order. */
export async function sourceDigest(root: string): Promise<Readonly<{ digest: string; files: number }>> {
const files = [
...(await Promise.all(SOURCE_ROOTS.map((entry) => listFiles(path.join(root, entry))))).flat(),
...SOURCE_FILES.map((file) => path.join(root, file)).filter((file) => existsSync(file)),
...(
await Promise.all(
SOURCE_PATHS.map((entry) => path.join(root, entry)).map(async (target) =>
(await stat(target).catch(() => null))?.isDirectory()
? listFiles(target)
: existsSync(target)
? [target]
: [],
),
)
).flat(),
]
.map((file) => path.relative(root, file))
.sort();
+1 -1
View File
@@ -129,7 +129,7 @@ if (liveTarget?.passed && !slotEmpty) {
} else {
mode = "fixture";
const fixture = await readDocument(
"config/hosting/response-headers.fixture.json",
"tests/fixtures/hosting/response-headers.json",
);
responses = responseHeaders(fixture.responses);
}
+1 -1
View File
@@ -95,7 +95,7 @@ const buildManifestDocument: unknown = JSON.parse(
);
assertMatchesJsonSchema(
JSON.parse(
await readFile("schemas/artifacts/build-manifest.schema.json", "utf8"),
await readFile("config/schemas/artifacts/build-manifest.schema.json", "utf8"),
),
buildManifestDocument,
"build manifest",
+1 -1
View File
@@ -15,7 +15,7 @@ async function json<T>(relative: string): Promise<T> {
const policy = (await json<{ surfaces: Surfaces }>("config/hosting/cache-policy.json")).surfaces;
const fixtureHeaders = (
await json<{ responses: Record<string, Record<string, string>> }>(
"config/hosting/response-headers.fixture.json",
"tests/fixtures/hosting/response-headers.json",
)
).responses;
@@ -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 \\
+8 -8
View File
@@ -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 () => {
+16 -14
View File
@@ -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<string[]> {
}
async function linesMatching(patterns: readonly RegExp[]): Promise<string[]> {
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)))
+4 -4
View File
@@ -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<Record<string, (text: string) => 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);
+8 -3
View File
@@ -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<string, unknown> };
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<string, Record<string, string>>;
};
+6 -6
View File
@@ -29,7 +29,7 @@ async function json(path: string): Promise<unknown> {
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",
+1 -1
View File
@@ -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([]);
}
});
+1 -1
View File
@@ -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(
+135
View File
@@ -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>): 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(),
);
});
});
@@ -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 });
+3 -3
View File
@@ -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",
@@ -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<string, Record<string, string>> };
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 };
-41
View File
@@ -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:
@@ -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")));
+6 -6
View File
@@ -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([]);