refactor(layout): 남은 루트 경로 목록도 등록부 집합에서 고른다

정리 4단계의 R2 검사는 등록부를 쓰는 7곳만 봤다. 그 밖에 루트 이름을
담은 목록이 코드 15파일에 19개 따로 있어, 루트 항목 하나를 옮기면
여전히 여러 곳을 같이 고쳐야 했다.

- 등록부에 집합 12개를 더했다. 사본 복사에서 건너뛰는 항목 셋
  (checkout·provider·공급망 fixture), fixture 코드 범위, pnpm 매니페스트,
  Playwright 설정, visual 증거, 문서 입력, 에이전트 하네스, tsconfig
  묶음 셋. 각 집합 설명에 읽는 파일을 적었다.
- 사본이 건너뛰는 node_modules·dist·.tmp 같은 추적 안 하는 항목은
  종류 untracked(optional)로 적는다. 추적 파일이 있으면 시험이 실패한다.
- 19개 목록이 모두 집합을 고른다. 집합의 원소는 전과 같아 동작은
  바뀌지 않는다.
- R2 시험이 추적되는 코드 파일 전체를 본다. 루트 항목(이나 그 안
  경로)만 담은 문자열 배열에 추적되는 루트 이름이 둘 이상이면 실패.
  인자 목록은 `--` 뒤만 본다. main의 옛 목록 18개를 이 검사가 잡는
  것을 확인했다.
- 집합마다 selectRepositoryPaths·selectRepositoryEntries로 고르는 코드가
  있는지 본다. 문서를 복사하지 않는 제거 drill(FE-GATE-020)은 문서
  시험(REMOVAL_FIXTURE_DOCUMENT_TESTS)을 지우는데, 집합 셋
  (agent-harness·documentation-inputs·feature-typecheck)은 그 시험만
  읽는다. 시험이 이 셋을 적어 두고, 문서 시험이 지워진 사본에서만 셋이
  비는 것을 허용한다. 셋이 바뀌면 전체 checkout에서 실패한다.
- 파서가 kinds·sets 설명과 코드의 목록이 같은지 본다.
- .gitignore 주석이 a11y 기록을 아직 artifacts/ 아래라고 적던 것을
  고쳤다(정리 3단계에서 docs/로 옮김).

검증(desktop): test:unit, check:types, check:ci, lint, verify:documentation.
repository-layout 시험을 문서 없는 제거 사본과 feature-scaffold 사본에서도
돌렸고, 집합 하나의 읽는 곳을 지우면 두 곳 모두 실패한다.
This commit is contained in:
DongHyeonka
2026-11-12 01:17:55 +09:00
parent 38c0dc7dbf
commit 3f64c68991
19 changed files with 275 additions and 129 deletions
+2 -2
View File
@@ -11,8 +11,8 @@ coverage/
# artifacts/ is run output and is ignored as a whole. Ignoring it by extension
# let screenshots and a coverage report in (0929/14-01) and step logs until
# they got their own rule (1103/12-08).
# Only the folder markers and the manual a11y reviews, which people write and
# the a11y gates read (config/ci/gates.json), are tracked;
# Only the folder markers are tracked (R3); the manual a11y reviews people
# write are in docs/accessibility/route-reviews/.
# tests/unit/tracked-artifacts.test.ts keeps it so. Git cannot re-include a
# file under an ignored folder, so each folder on the way is re-included and
# its contents ignored again.
+110 -23
View File
@@ -6,7 +6,8 @@
"gate-input": "게이트와 런타임이 읽는 기준 데이터",
"document": "사람이 읽는 문서",
"history": "끝난 라운드의 기록. 이력 폴더로 옮길 대상이다(R10)",
"output": "실행 출력. 추적하는 것은 `.gitkeep`뿐이다(R3)"
"output": "실행 출력. 추적하는 것은 `.gitkeep`뿐이다(R3)",
"untracked": "추적하지 않는 로컬 항목(의존성·VCS·생성물·실행 출력·다른 worktree). 집합이 이름으로 고를 때만 적는다. 추적 파일이 없어야 한다"
},
"sets": {
"fixture-copy": "제거·생성 drill과 사본 시험이 복사하는 것(scripts/lib/removal-fixture.ts)",
@@ -15,14 +16,27 @@
"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)"
"typescript-only": "JS 파일을 두면 안 되는 곳(scripts/check-architecture.ts)",
"checkout-copy-skip": "저장소 전체를 임시 폴더로 복사하는 시험이 건너뛰는 항목(tests/e2e/support/fixture-builds.ts, tests/e2e/support/service-worker-builds.ts, tests/unit/run-output-root-build.test.ts)",
"provider-fixture-skip": "provider 업로드 시험의 기준 fixture가 복사하지 않는 항목(tests/system/ci-runner/ci-artifact-contract.test.ts)",
"supply-chain-fixture-skip": "공급망 provider fixture가 복사하지 않는 항목. artifacts는 따로 복사한다(scripts/check-supply-chain-provider-fixtures.ts, tests/integration/security-followup-archive.test.ts)",
"fixture-code": "사본을 만들고 node_modules를 잇는 코드가 있는 곳. linkFixtureNodeModules 규칙을 보는 범위(scripts/check-adapter-inventory.ts, tests/unit/fixture-node-modules.test.ts)",
"package-manifest": "pnpm 설치를 정하는 매니페스트(tests/unit/fixture-node-modules.test.ts)",
"playwright-configs": "자기 forbidOnly를 가져야 하는 Playwright 설정. dev 설정은 기본 설정을 펼친다(scripts/check-test-evidence.ts)",
"visual-evidence": "시험 증거 검사가 있어야 한다고 보는 visual·workshop 입력(scripts/check-test-evidence.ts)",
"documentation-inputs": "verify:documentation이 읽는 문서 입력. 문서 시험이 사본으로 복사한다(tests/unit/documentation-readiness.test.ts, tests/unit/template-feature-removal-documents.test.ts)",
"agent-harness": "에이전트 하네스 파일(tests/unit/template-contract-documents.test.ts)",
"feature-typecheck": "기능 코드와 기능 시험을 타입 검사하는 tsconfig(tests/unit/manual-code-blocks.test.ts)",
"product-typecheck": "제품 사본을 타입 검사하는 tsconfig(tests/unit/product-extension-typecheck.test.ts)",
"app-typecheck": "앱 프로그램 tsconfig와 그 기반 설정(tests/unit/two-feature-install-typecheck.test.ts)"
},
"entries": [
{
"path": ".claude",
"kind": "tool-convention",
"role": "Claude Code 설정·규칙·스킬·서브에이전트",
"readBy": "Claude Code"
"readBy": "Claude Code",
"sets": ["checkout-copy-skip", "provider-fixture-skip", "agent-harness"]
},
{
"path": ".dependency-cruiser.json",
@@ -37,6 +51,22 @@
"role": "빌드 시점 공개 변수의 견본",
"readBy": "Vite(VITE_*), 사람"
},
{
"path": ".generated",
"kind": "untracked",
"role": "빌드가 쓰는 런타임 생성물(.generated/frontend-runtime)",
"readBy": "scripts/build-frontend.ts, scripts/generate-contract-set.ts",
"optional": true,
"sets": ["checkout-copy-skip"]
},
{
"path": ".git",
"kind": "untracked",
"role": "git 저장소. worktree에서는 파일이다",
"readBy": "git",
"optional": true,
"sets": ["checkout-copy-skip"]
},
{
"path": ".gitattributes",
"kind": "tool-convention",
@@ -74,6 +104,14 @@
"readBy": "nvm, CI",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": ".release",
"kind": "untracked",
"role": "CI가 만드는 릴리스 후보 묶음",
"readBy": "release 단계 job(config/ci/gates.json)",
"optional": true,
"sets": ["provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": ".storybook",
"kind": "tool-convention",
@@ -81,12 +119,28 @@
"readBy": "storybook, build:storybook (FE-GATE-011)",
"sets": ["fixture-copy", "secret-scan", "scale-source", "typescript-only"]
},
{
"path": ".tmp",
"kind": "untracked",
"role": "drill 사본과 실행별 빌드·결과(.tmp/runs/<id>)",
"readBy": "scripts/lib/run-isolation.ts, 제거 drill",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip"]
},
{
"path": ".worktrees",
"kind": "untracked",
"role": "이 저장소의 다른 worktree를 두는 자리",
"readBy": "git worktree",
"optional": true,
"sets": ["provider-fixture-skip"]
},
{
"path": "AGENTS.md",
"kind": "tool-convention",
"role": "에이전트 진입 문서(꼭 지킬 것·지도·검증). docs/README.md 1절이 가리키는 현재 계약 문서",
"readBy": "코딩 에이전트, verify:documentation (FE-GATE-017)",
"sets": ["fixture-documents"]
"sets": ["fixture-documents", "agent-harness"]
},
{
"path": "CHANGELOG.md",
@@ -99,7 +153,8 @@
"path": "CLAUDE.md",
"kind": "tool-convention",
"role": "Claude Code 진입 문서",
"readBy": "Claude Code"
"readBy": "Claude Code",
"sets": ["agent-harness"]
},
{
"path": "PRODUCT.md",
@@ -112,7 +167,7 @@
"kind": "document",
"role": "시작·설정·검증",
"readBy": "verify:documentation (FE-GATE-017), 사람",
"sets": ["fixture-documents"]
"sets": ["fixture-documents", "documentation-inputs"]
},
{
"path": "SPEC.md",
@@ -124,23 +179,36 @@
"path": "artifacts",
"kind": "output",
"role": "게이트와 시험의 실행 출력",
"readBy": "scripts/run-ci-gate.ts, CI 업로드"
"readBy": "scripts/run-ci-gate.ts, CI 업로드",
"sets": ["checkout-copy-skip", "provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": "config",
"kind": "gate-input",
"role": "게이트·런타임·보안·성능의 기준 데이터와 JSON Schema(config/schemas)",
"readBy": "scripts/, tests/, src/",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"],
"setPaths": {
"documentation-inputs": ["config/contracts/backend-contract-pin.json"]
}
},
{
"path": "dist",
"kind": "untracked",
"role": "vite build 출력",
"readBy": "vite build, preview 서버",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": "docs",
"kind": "document",
"role": "매뉴얼·설계·운영 문서와 수동 접근성 검토 기록",
"readBy": "verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009·028)",
"sets": ["fixture-documents"],
"sets": ["fixture-documents", "documentation-inputs"],
"setPaths": {
"fixture-copy": ["docs/accessibility/route-reviews"]
"fixture-copy": ["docs/accessibility/route-reviews"],
"agent-harness": ["docs/work"]
}
},
{
@@ -150,6 +218,14 @@
"readBy": "eslint (FE-GATE-002)",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
},
{
"path": "graphify-out",
"kind": "untracked",
"role": "graphify 지식 그래프 출력(로컬 분석)",
"readBy": "graphify",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip"]
},
{
"path": "index.html",
"kind": "tool-convention",
@@ -157,26 +233,34 @@
"readBy": "Vite",
"sets": ["fixture-copy", "secret-scan", "vite-build"]
},
{
"path": "node_modules",
"kind": "untracked",
"role": "설치된 의존성",
"readBy": "pnpm, Node",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": "package.json",
"kind": "tool-convention",
"role": "의존성과 package script",
"readBy": "pnpm, 모든 게이트",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build"]
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build", "package-manifest"]
},
{
"path": "playwright.capabilities.config.ts",
"kind": "tool-convention",
"role": "브라우저 capability 시험 설정",
"readBy": "test:browser-capabilities (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan"]
"sets": ["fixture-copy", "secret-scan", "playwright-configs"]
},
{
"path": "playwright.config.ts",
"kind": "tool-convention",
"role": "e2e 설정(빌드 미리보기)",
"readBy": "test:e2e (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan", "history-free"]
"sets": ["fixture-copy", "secret-scan", "history-free", "playwright-configs"]
},
{
"path": "playwright.dev.config.ts",
@@ -190,28 +274,28 @@
"kind": "tool-convention",
"role": "Storybook 정적 빌드 시험 설정",
"readBy": "test:storybook (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan"]
"sets": ["fixture-copy", "secret-scan", "playwright-configs", "visual-evidence"]
},
{
"path": "playwright.visual.config.ts",
"kind": "tool-convention",
"role": "visual 골든 설정",
"readBy": "test:visual (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan"]
"sets": ["fixture-copy", "secret-scan", "playwright-configs", "visual-evidence"]
},
{
"path": "pnpm-lock.yaml",
"kind": "tool-convention",
"role": "잠금 파일",
"readBy": "pnpm, 공급망 생성",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
"sets": ["fixture-copy", "secret-scan", "scale-source", "package-manifest"]
},
{
"path": "pnpm-workspace.yaml",
"kind": "tool-convention",
"role": "pnpm 11 설정",
"readBy": "pnpm, scripts/lib/package-script-graph.ts",
"sets": ["fixture-copy", "secret-scan"]
"sets": ["fixture-copy", "secret-scan", "package-manifest"]
},
{
"path": "public",
@@ -239,7 +323,7 @@
"kind": "source",
"role": "게이트·생성기·drill 스크립트",
"readBy": "package.json scripts",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only"],
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only", "fixture-code"],
"setPaths": {
"vite-build": ["scripts/lib/run-isolation.ts", "scripts/lib/vite-module-inventory.ts"]
}
@@ -256,21 +340,24 @@
"kind": "source",
"role": "시험과 fixture",
"readBy": "test:* scripts, playwright 설정",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only"]
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only", "fixture-code"],
"setPaths": {
"visual-evidence": ["tests/storybook/workshop.spec.ts"]
}
},
{
"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"]
"sets": ["fixture-copy", "secret-scan", "scale-source", "vite-build", "feature-typecheck", "product-typecheck", "app-typecheck"]
},
{
"path": "tsconfig.base.json",
"kind": "tool-convention",
"role": "공통 컴파일 옵션",
"readBy": "다른 tsconfig의 extends",
"sets": ["fixture-copy", "secret-scan", "vite-build"]
"sets": ["fixture-copy", "secret-scan", "vite-build", "app-typecheck"]
},
{
"path": "tsconfig.json",
@@ -284,7 +371,7 @@
"kind": "tool-convention",
"role": "scripts·설정 파일 타입 검사(NodeNext)",
"readBy": "check:types:node (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
"sets": ["fixture-copy", "secret-scan", "scale-source", "product-typecheck"]
},
{
"path": "tsconfig.service-worker.json",
@@ -298,7 +385,7 @@
"kind": "tool-convention",
"role": "tests·recipes·시험 설정 파일 타입 검사",
"readBy": "check:types:test (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
"sets": ["fixture-copy", "secret-scan", "scale-source", "feature-typecheck", "product-typecheck"]
},
{
"path": "vite.config.ts",
+3 -2
View File
@@ -4,6 +4,7 @@ import path from "node:path";
import { spawnSync } from "node:child_process";
import { CACHEABLE_ASSET_CONTENT_TYPES } from "../src/contracts/service-worker-static-manifest.ts";
import { selectRepositoryPaths } from "./lib/repository-layout.ts";
/**
* GOV-01 / SW-RR-03. Structural gates for facts that a hand-maintained document
@@ -99,7 +100,7 @@ async function main(): Promise<void> {
// dependencies mid-run. `linkFixtureNodeModules` is the only sanctioned form.
const sources = spawnSync(
"git",
["grep", "-n", "-e", 'symlink(', "--", "scripts", "tests"],
["grep", "-n", "-e", 'symlink(', "--", ...selectRepositoryPaths("fixture-code")],
{ encoding: "utf8" },
);
if (sources.status === 0) {
@@ -113,7 +114,7 @@ async function main(): Promise<void> {
}
const linkedFixtures = spawnSync(
"git",
["grep", "-l", "linkFixtureNodeModules", "--", "scripts", "tests"],
["grep", "-l", "linkFixtureNodeModules", "--", ...selectRepositoryPaths("fixture-code")],
{ encoding: "utf8" },
);
if (
@@ -45,8 +45,10 @@ import {
FIXTURE_PNPM_ENVIRONMENT,
linkFixtureNodeModules,
} from "./lib/fixture-node-modules.ts";
import { selectRepositoryPaths } from "./lib/repository-layout.ts";
const repositoryRoot = process.cwd();
const UNCOPIED_ROOTS = selectRepositoryPaths("supply-chain-fixture-skip");
const fixtureRoot = await mkdtemp(path.join(tmpdir(), "provider-exact-five-fixture-"));
try {
await cp(repositoryRoot, fixtureRoot, {
@@ -55,7 +57,7 @@ try {
const relative = path.relative(repositoryRoot, source);
if (!relative) return true;
const first = relative.split(path.sep)[0];
return ![".release", "artifacts", "dist", "node_modules"].includes(first ?? "");
return !UNCOPIED_ROOTS.includes(first ?? "");
},
});
await cp(path.join(repositoryRoot, "artifacts"), path.join(fixtureRoot, "artifacts"), {
+3 -11
View File
@@ -12,6 +12,7 @@ import {
type HttpScenarioExpectation,
type HttpScenarioReceipt,
} from "./lib/http-scenario-evidence.ts";
import { selectRepositoryPaths } from "./lib/repository-layout.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
import { testEvidenceReportSchema } from "./lib/test-evidence-artifact.ts";
@@ -381,12 +382,7 @@ if (!fixtureMode && !scenarioOnly) {
}
}
// playwright.dev.config.ts spreads playwright.config.ts.
for (const config of [
"playwright.config.ts",
"playwright.visual.config.ts",
"playwright.storybook.config.ts",
"playwright.capabilities.config.ts",
]) {
for (const config of selectRepositoryPaths("playwright-configs")) {
if (!(await readFile(config, "utf8")).includes("forbidOnly: true")) {
failures.push(`${config}: missing forbidOnly: true, so a committed test.only passes the gate`);
}
@@ -409,11 +405,7 @@ if (!fixtureMode && !scenarioOnly) {
if (facts.visualBaselines < 4) {
failures.push("visual baseline requires at least four risk surfaces");
}
for (const required of [
"playwright.storybook.config.ts",
"playwright.visual.config.ts",
"tests/storybook/workshop.spec.ts",
]) {
for (const required of selectRepositoryPaths("visual-evidence")) {
if ((await filesBelow(required)).length === 0) {
failures.push(`test evidence missing ${required}`);
}
+32 -1
View File
@@ -6,7 +6,10 @@ import { readFileSync } from "node:fs";
* 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).
* (design-docs repo-structure/04-frontend-layout.md §2.4); about twenty more
* lists followed on 2026-11-11. An untracked item (node_modules, dist, other
* worktrees) has an entry only when a set names it, such as the items a copy
* of the checkout skips.
*/
export const REPOSITORY_LAYOUT_SETS = Object.freeze([
@@ -17,6 +20,18 @@ export const REPOSITORY_LAYOUT_SETS = Object.freeze([
"scale-source",
"vite-build",
"typescript-only",
"checkout-copy-skip",
"provider-fixture-skip",
"supply-chain-fixture-skip",
"fixture-code",
"package-manifest",
"playwright-configs",
"visual-evidence",
"documentation-inputs",
"agent-harness",
"feature-typecheck",
"product-typecheck",
"app-typecheck",
] as const);
export type RepositoryLayoutSet = (typeof REPOSITORY_LAYOUT_SETS)[number];
@@ -27,6 +42,7 @@ export const REPOSITORY_LAYOUT_KINDS = Object.freeze([
"document",
"history",
"output",
"untracked",
] as const);
export type RepositoryLayoutKind = (typeof REPOSITORY_LAYOUT_KINDS)[number];
@@ -49,6 +65,18 @@ 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");
// Each kind and set the code knows is described once in the file, and the file names no other.
for (const [field, known] of [
["kinds", REPOSITORY_LAYOUT_KINDS],
["sets", REPOSITORY_LAYOUT_SETS],
] as const) {
if (!(field in document)) continue;
const described = Object.keys(record(document[field], `layout.${field}`)).sort();
const expected = [...known].sort();
if (described.join() !== expected.join()) {
throw new Error(`layout.${field} must describe exactly ${expected.join(", ")}; it has ${described.join(", ")}`);
}
}
const entries = document["entries"];
if (!Array.isArray(entries) || entries.length === 0) {
throw new Error("layout: entries must be a non-empty array");
@@ -66,6 +94,9 @@ export function parseRepositoryLayout(value: unknown): readonly RepositoryLayout
if (!(REPOSITORY_LAYOUT_KINDS as readonly string[]).includes(kind)) {
throw new Error(`${at}.kind: unknown kind ${kind}`);
}
if (kind === "untracked" && entry["optional"] !== true) {
throw new Error(`${at}: an untracked item may be absent, so it is optional`);
}
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`);
+2 -10
View File
@@ -5,6 +5,7 @@ import path from "node:path";
import { localBuildEnvironment } from "../../../scripts/lib/build-environment.ts";
import { linkFixtureNodeModules } from "../../../scripts/lib/fixture-node-modules.ts";
import { selectRepositoryPaths } from "../../../scripts/lib/repository-layout.ts";
/**
* Real production builds of an edited temp copy of the repository, in the
@@ -16,16 +17,7 @@ import { linkFixtureNodeModules } from "../../../scripts/lib/fixture-node-module
*/
const repoRoot = path.resolve(import.meta.dirname, "../../..");
const skipped = new Set([
"node_modules",
".git",
".claude",
".generated",
".tmp",
"dist",
"artifacts",
"graphify-out",
]);
const skipped = new Set(selectRepositoryPaths("checkout-copy-skip"));
export type FixtureBuild<Name extends string> = Readonly<{
name: Name;
+2 -10
View File
@@ -18,6 +18,7 @@ import { gzipSync } from "node:zlib";
import { SERVICE_WORKER_ASSETS_OUTPUT } from "../../../scripts/generate-service-worker-assets.ts";
import { localBuildEnvironment } from "../../../scripts/lib/build-environment.ts";
import { linkFixtureNodeModules } from "../../../scripts/lib/fixture-node-modules.ts";
import { selectRepositoryPaths } from "../../../scripts/lib/repository-layout.ts";
import type { StaticAssetManifestV1 } from "../../../src/contracts/service-worker.ts";
/**
@@ -57,16 +58,7 @@ import type { StaticAssetManifestV1 } from "../../../src/contracts/service-worke
const repoRoot = path.resolve(import.meta.dirname, "../../..");
// 1105/12-04. `.tmp` holds other runs' builds and results (.tmp/runs/<id>),
// which change while this copy is made; fixture-builds.ts skips it too.
const skipped = new Set([
"node_modules",
".git",
".claude",
".generated",
".tmp",
"dist",
"artifacts",
"graphify-out",
]);
const skipped = new Set(selectRepositoryPaths("checkout-copy-skip"));
export type BuildName = "a" | "b";
export type ServiceWorkerBuilds = Readonly<{
@@ -19,6 +19,7 @@ import {
FIXTURE_PNPM_ENVIRONMENT,
linkFixtureNodeModules,
} from "../../scripts/lib/fixture-node-modules.ts";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
it(
"builds a real candidate assessment and passes the default archived verifier from the captured archive",
@@ -32,12 +33,7 @@ it(
const relative = path.relative(sourceRoot, source);
if (!relative) return true;
const first = relative.split(path.sep)[0];
return ![
".release",
"artifacts",
"dist",
"node_modules",
].includes(first ?? "");
return !selectRepositoryPaths("supply-chain-fixture-skip").includes(first ?? "");
},
});
await cp(path.join(sourceRoot, "artifacts"), path.join(fixtureRoot, "artifacts"), {
@@ -24,6 +24,7 @@ import {
linkFixtureNodeModules,
} from "../../../scripts/lib/fixture-node-modules.ts";
import { copyReleaseEvidenceTree } from "../../../scripts/lib/removal-fixture.ts";
import { selectRepositoryPaths } from "../../../scripts/lib/repository-layout.ts";
import { captureCiCandidateArchive, verifyCiCandidateArchive } from "../../../scripts/lib/ci-candidate-archive.ts";
import {
CANDIDATE_ARCHIVE_USAGE,
@@ -2232,16 +2233,7 @@ async function createProviderFixture() {
* with timeouts and ENOTEMPTY clean-ups (1103/11-04). None of them is tracked,
* so the candidate's tracked-file inventory does not miss them.
*/
const PROVIDER_BASE_FIXTURE_UNCOPIED_ENTRIES: readonly string[] = Object.freeze([
".release",
"artifacts",
"dist",
"node_modules",
".claude",
".worktrees",
".tmp",
"graphify-out",
]);
const PROVIDER_BASE_FIXTURE_UNCOPIED_ENTRIES: readonly string[] = selectRepositoryPaths("provider-fixture-skip");
async function ensureProviderBaseFixture(): Promise<string> {
if (providerBaseRoot) return providerBaseRoot;
+3 -1
View File
@@ -6,8 +6,10 @@ import path from "node:path";
import { describe, expect, it } from "vitest";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
// The pin says which commit of the paired backend the documents describe.
const INPUTS = ["README.md", "docs", "config/contracts/backend-contract-pin.json"];
const INPUTS = selectRepositoryPaths("documentation-inputs");
const PAIRED_BACKEND = "clean-architecture-backend-template";
type Changes = Readonly<Record<string, (text: string) => string>>;
+3 -2
View File
@@ -19,6 +19,7 @@ import {
FIXTURE_PNPM_ENVIRONMENT,
linkFixtureNodeModules,
} from "../../scripts/lib/fixture-node-modules.ts";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
/**
* A removal or provider fixture runs `pnpm` inside a throwaway copy of the
@@ -239,7 +240,7 @@ describe("pnpm inside a linked fixture (F-4)", () => {
) {
const fixture = path.join(root, `fixture-${scratch.length}-${Date.now()}`);
await mkdir(fixture);
for (const file of ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"]) {
for (const file of selectRepositoryPaths("package-manifest")) {
await copyFile(path.join(source, file), path.join(fixture, file));
}
await linkFixtureNodeModules(fixture, source);
@@ -270,7 +271,7 @@ describe("pnpm inside a linked fixture (F-4)", () => {
it("is used by every fixture that links node_modules and runs pnpm", async () => {
const listed = spawnSync(
"git",
["grep", "-l", "linkFixtureNodeModules(", "--", "scripts", "tests"],
["grep", "-l", "linkFixtureNodeModules(", "--", ...selectRepositoryPaths("fixture-code")],
{ encoding: "utf8" },
);
expect(listed.status, listed.stderr).toBe(0);
+2 -1
View File
@@ -8,6 +8,7 @@ import { afterAll, describe, expect, it } from "vitest";
import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts";
import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
/**
* 2026-11-07. The template ships no sample feature: what the generated
@@ -114,7 +115,7 @@ describe("docs/manual code blocks, pasted into a generated feature", () => {
);
}
for (const program of ["tsconfig.app.json", "tsconfig.test.json"]) {
for (const program of selectRepositoryPaths("feature-typecheck")) {
const typecheck = run(root, path.resolve("node_modules/.bin/tsc"), ["--project", program]);
expect(typecheck.output, program).toBe("");
expect(typecheck.status, program).toBe(0);
@@ -8,6 +8,7 @@ import { afterAll, describe, expect, it } from "vitest";
import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts";
import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
/**
* 1103/09-02. The product extension point has to hold on the typecheck path,
@@ -291,7 +292,7 @@ function expectTypecheckPasses(root: string): void {
expect(generated.stderr).toBe("");
expect(generated.status).toBe(0);
for (const project of ["tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json"]) {
for (const project of selectRepositoryPaths("product-typecheck")) {
const typecheck = spawnSync(
path.resolve("node_modules/.bin/tsc"),
["--project", path.join(root, project)],
+89 -31
View File
@@ -8,9 +8,11 @@ import {
parseRepositoryLayout,
REPOSITORY_LAYOUT,
REPOSITORY_LAYOUT_FILE,
REPOSITORY_LAYOUT_SETS,
selectRepositoryEntries,
selectRepositoryPaths,
} from "../../scripts/lib/repository-layout.ts";
import { REMOVAL_FIXTURE_DOCUMENT_TESTS } from "../../scripts/lib/removal-fixture.ts";
/**
* The repository layout rules of docs/manual/03-outside-feature-folder.md
@@ -29,6 +31,10 @@ function trackedFiles(): string[] {
}
const rootItemNames = new Set(REPOSITORY_LAYOUT.map((entry) => entry.path));
/** Tracked items: the ones a list in code can go stale on when one moves. */
const trackedRootNames = new Set(
REPOSITORY_LAYOUT.filter(({ kind }) => kind !== "untracked").map((entry) => entry.path),
);
describe("repository layout registry (R1)", () => {
// A removal fixture copies part of the repository, so the claim is one way:
@@ -42,6 +48,13 @@ describe("repository layout registry (R1)", () => {
).toEqual([]);
});
it("lists untracked items that have no tracked file", () => {
const tracked = new Set(trackedFiles().map((file) => file.split("/")[0]!));
const untracked = REPOSITORY_LAYOUT.filter(({ kind }) => kind === "untracked");
expect(untracked.length).toBeGreaterThan(0);
expect(untracked.filter(({ path: item }) => tracked.has(item)).map(({ path: item }) => item)).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(
@@ -60,67 +73,112 @@ describe("repository layout registry (R1)", () => {
expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, sets: ["everything"] }] })).toThrow(
/unknown set/u,
);
expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, kind: "untracked" }] })).toThrow(
/optional/u,
);
expect(() =>
parseRepositoryLayout({ schemaVersion: 1, sets: { "fixture-copy": "copied" }, entries: [entry] }),
).toThrow(/must describe exactly/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"] },
{ path: ".ci", kind: "tool-convention", role: "ci", readBy: "ci", setPaths: { "secret-scan": [".ci/workflows/a.yml"] } },
{ path: "extras", kind: "source", role: "extras", readBy: "tsc", optional: true, sets: ["secret-scan"] },
{ path: "app", 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(selectRepositoryPaths("secret-scan", layout)).toEqual([".ci/workflows/a.yml", "extras", "app"]);
expect(selectRepositoryPaths("vite-build", layout)).toEqual(["app"]);
expect(selectRepositoryEntries("secret-scan", layout).filter(({ optional }) => optional)).toEqual([
{ path: "recipes", optional: true },
{ path: "extras", 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.
* their own literal lists of root paths, each a different subset; about
* twenty more were found on 2026-11-11. Every tracked code file is checked, so
* a new list fails here instead of waiting for a review to find it.
*/
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 CODE_FILE = /\.(?:[cm]?ts|tsx|[cm]?js)$/u;
/** The sets that only tests in REMOVAL_FIXTURE_DOCUMENT_TESTS read, sorted. */
const DOCUMENT_TEST_SETS = ["agent-harness", "documentation-inputs", "feature-typecheck"];
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, "");
/**
* Array literals of string literals that are all root items or paths inside
* one, two or more of them tracked. In an argument vector only the paths after
* `--` count, so `git grep … -- <paths>` is a list and a list of subcommand
* names that happen to include `docs` is not.
*/
function literalRootLists(
source: string,
tracked: ReadonlySet<string> = trackedRootNames,
roots: ReadonlySet<string> = rootItemNames,
): string[] {
const code = source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/^\s*\/\/.*$/gmu, "");
const isRootPath = (value: string) => roots.has(value) || (value.includes("/") && roots.has(value.split("/")[0]!));
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.includes("--") ? values.slice(values.lastIndexOf("--") + 1) : values))
.filter((values) => values.every(isRootPath) && new Set(values.filter((value) => tracked.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("are chosen from the registry everywhere in the code", () => {
const files = trackedFiles().filter((file) => CODE_FILE.test(file) && existsSync(file));
expect(files.length).toBeGreaterThan(100);
expect(
files.flatMap((file) => literalRootLists(readFileSync(file, "utf8")).map((list) => `${file}: [${list}]`)),
`choose a set from ${REPOSITORY_LAYOUT_FILE} with selectRepositoryPaths`,
).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, also after -- in an argument vector, and nothing else", () => {
const tracked = new Set(["alpha", "beta"]);
const roots = new Set(["alpha", "beta", "gamma"]);
expect(literalRootLists(`const ROOTS = ["alpha", "beta/x.ts", "gamma"];`, tracked, roots)).toEqual([]);
expect(literalRootLists(`const ROOTS = ["alpha", "beta", "gamma"];`, tracked, roots)).toEqual([
"alpha, beta, gamma",
]);
expect(literalRootLists(`spawn("git", ["grep", "-l", "x", "--", "alpha", "beta"]);`, tracked, roots)).toEqual([
"alpha, beta",
]);
// A command list that names two items among other words is not a list of paths.
expect(literalRootLists(`const COMMANDS = ["alpha", "beta", "help"];`, tracked, roots)).toEqual([]);
// Untracked items alone never move with the code, as in a list of build output folders.
expect(literalRootLists(`const SKIP = ["alpha", "gamma"];`, tracked, roots)).toEqual([]);
expect(literalRootLists(`/** ["alpha", "beta"] */\n// ["alpha", "beta"]`, tracked, roots)).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([]);
it("has a reader for every set", () => {
// A reader calls the registry with the set's name; naming it is not enough.
// This file reads secret-scan, which its policy test keeps equal.
const readers = trackedFiles()
.filter((file) => CODE_FILE.test(file) && existsSync(file) && file !== "scripts/lib/repository-layout.ts")
.map((file) => ({ file, source: readFileSync(file, "utf8") }));
const reads = (source: string, set: string) =>
new RegExp(String.raw`selectRepository(?:Paths|Entries)\(\s*"${set}"`, "u").test(source);
const unreadBy = (files: readonly { source: string }[]) =>
REPOSITORY_LAYOUT_SETS.filter((set) => !files.some(({ source }) => reads(source, set))).sort();
// A removal drill that copies no documents deletes the tests that read them
// (removalFixtureExcludedTests in scripts/lib/removal-fixture.ts), and with
// them the only readers of DOCUMENT_TEST_SETS; FE-GATE-020 failed on that.
const documentTestsDeleted = REMOVAL_FIXTURE_DOCUMENT_TESTS.some((file) => !existsSync(file));
expect(unreadBy(readers), "sets no code selects").toEqual(documentTestsDeleted ? DOCUMENT_TEST_SETS : []);
const documentTests = new Set<string>(REMOVAL_FIXTURE_DOCUMENT_TESTS);
expect(
unreadBy(readers.filter(({ file }) => !documentTests.has(file))),
"sets only REMOVAL_FIXTURE_DOCUMENT_TESTS select (DOCUMENT_TEST_SETS)",
).toEqual(DOCUMENT_TEST_SETS);
});
// A removal fixture deletes some of these inputs on purpose — removing the
+2 -10
View File
@@ -8,6 +8,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { localBuildEnvironment } from "../../scripts/lib/build-environment.ts";
import { verifyBuildManifestOutputs } from "../../scripts/lib/build-manifest-outputs.ts";
import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
import { buildManifestArtifactSchema } from "../../src/contracts/release-artifacts.ts";
import { turnOnServiceWorker } from "../e2e/support/service-worker-builds.ts";
@@ -24,16 +25,7 @@ import { turnOnServiceWorker } from "../e2e/support/service-worker-builds.ts";
*/
const ROOT = ".tmp/runs/build-probe";
const repoRoot = process.cwd();
const skipped = new Set([
"node_modules",
".git",
".claude",
".generated",
".tmp",
"dist",
"artifacts",
"graphify-out",
]);
const skipped = new Set(selectRepositoryPaths("checkout-copy-skip"));
let copy: string | undefined;
let failed: SpawnSyncReturns<string> | undefined;
@@ -2,6 +2,8 @@ import { readFile } from "node:fs/promises";
import { describe, expect, it } from "vitest";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
/**
* Owner decision 2026-11-07 (docs/work/reference/decisions.md): the root
* AGENTS.md and CLAUDE.md, `.claude/` and `docs/work/` are the template's
@@ -10,7 +12,7 @@ import { describe, expect, it } from "vitest";
* work manual, which makes verify:documentation check the paths, scripts and
* gate IDs they name.
*/
const CONTRACT = Object.freeze(["AGENTS.md", "CLAUDE.md", ".claude", "docs/work"]);
const CONTRACT = selectRepositoryPaths("agent-harness");
// Built from pieces: deletable-history-documents.test.ts fails on code that
// names a folder a copy may delete.
const PAST_PLANS = ["docs", "superpowers"].join("/");
@@ -11,7 +11,11 @@ import {
REMOVABLE_TEMPLATE_FEATURES,
removableTemplateFeaturePaths,
} from "../../scripts/lib/removable-template-features.ts";
import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts";
import {
REMOVAL_FIXTURE_COPY_TARGETS,
REMOVAL_FIXTURE_DOCUMENT_TARGETS,
} from "../../scripts/lib/removal-fixture.ts";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
/**
* 1105/14-01. A copy that deleted a sample listed in
@@ -22,8 +26,8 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.
* writes, listed and named in a document, then deleted.
*/
const CHECKER = "scripts/verify-documentation-readiness.ts";
/** What verify:documentation reads besides the code. */
const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "AGENTS.md"]);
/** What verify:documentation reads besides the code: the documents a drill copies. */
const DOCUMENTS = REMOVAL_FIXTURE_DOCUMENT_TARGETS;
const LISTED_SAMPLE = Object.freeze({
featureId: "listed-sample-feature",
@@ -100,8 +104,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", "config/contracts/backend-contract-pin.json"];
for (const entry of inputs) await cp(entry, path.join(root, entry), { recursive: true });
for (const entry of selectRepositoryPaths("documentation-inputs")) await cp(entry, path.join(root, entry), { recursive: true });
const target = path.join(root, document);
await writeFile(target, mutate(await readFile(target, "utf8")));
const result = spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" });
@@ -6,6 +6,7 @@ import path from "node:path";
import { afterAll, describe, expect, it } from "vitest";
import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts";
import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
/**
* 09-01. The central composers (`src/features/installed-*`) are typed from the
@@ -150,7 +151,7 @@ describe("installing a second feature (09-01)", () => {
const root = await mkdtemp(path.join(tmpdir(), "two-feature-install-"));
roots.push(root);
await cp(path.resolve("src"), path.join(root, "src"), { recursive: true });
for (const config of ["tsconfig.base.json", "tsconfig.app.json"]) {
for (const config of selectRepositoryPaths("app-typecheck")) {
await cp(path.resolve(config), path.join(root, config));
}
await linkFixtureNodeModules(root);