diff --git a/.gitignore b/.gitignore index 5708900a..244094ae 100644 --- a/.gitignore +++ b/.gitignore @@ -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. diff --git a/config/repository-layout.json b/config/repository-layout.json index 4bb4125a..b55a7431 100644 --- a/config/repository-layout.json +++ b/config/repository-layout.json @@ -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/)", + "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", diff --git a/scripts/check-adapter-inventory.ts b/scripts/check-adapter-inventory.ts index 0d477dbc..e39e82f7 100644 --- a/scripts/check-adapter-inventory.ts +++ b/scripts/check-adapter-inventory.ts @@ -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 { // 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 { } const linkedFixtures = spawnSync( "git", - ["grep", "-l", "linkFixtureNodeModules", "--", "scripts", "tests"], + ["grep", "-l", "linkFixtureNodeModules", "--", ...selectRepositoryPaths("fixture-code")], { encoding: "utf8" }, ); if ( diff --git a/scripts/check-supply-chain-provider-fixtures.ts b/scripts/check-supply-chain-provider-fixtures.ts index 80f702d9..67b5d303 100644 --- a/scripts/check-supply-chain-provider-fixtures.ts +++ b/scripts/check-supply-chain-provider-fixtures.ts @@ -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"), { diff --git a/scripts/check-test-evidence.ts b/scripts/check-test-evidence.ts index ab3e0dc6..6b16b483 100644 --- a/scripts/check-test-evidence.ts +++ b/scripts/check-test-evidence.ts @@ -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}`); } diff --git a/scripts/lib/repository-layout.ts b/scripts/lib/repository-layout.ts index 0d05ab01..a3e0bb60 100644 --- a/scripts/lib/repository-layout.ts +++ b/scripts/lib/repository-layout.ts @@ -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`); diff --git a/tests/e2e/support/fixture-builds.ts b/tests/e2e/support/fixture-builds.ts index 405b44ff..0a70a059 100644 --- a/tests/e2e/support/fixture-builds.ts +++ b/tests/e2e/support/fixture-builds.ts @@ -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 = Readonly<{ name: Name; diff --git a/tests/e2e/support/service-worker-builds.ts b/tests/e2e/support/service-worker-builds.ts index df6b39a8..156a23fd 100644 --- a/tests/e2e/support/service-worker-builds.ts +++ b/tests/e2e/support/service-worker-builds.ts @@ -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/), // 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<{ diff --git a/tests/integration/security-followup-archive.test.ts b/tests/integration/security-followup-archive.test.ts index 06845203..837863c6 100644 --- a/tests/integration/security-followup-archive.test.ts +++ b/tests/integration/security-followup-archive.test.ts @@ -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"), { diff --git a/tests/system/ci-runner/ci-artifact-contract.test.ts b/tests/system/ci-runner/ci-artifact-contract.test.ts index 3aa99b33..c7f91a52 100644 --- a/tests/system/ci-runner/ci-artifact-contract.test.ts +++ b/tests/system/ci-runner/ci-artifact-contract.test.ts @@ -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 { if (providerBaseRoot) return providerBaseRoot; diff --git a/tests/unit/documentation-readiness.test.ts b/tests/unit/documentation-readiness.test.ts index 1cd46162..c5ba4168 100644 --- a/tests/unit/documentation-readiness.test.ts +++ b/tests/unit/documentation-readiness.test.ts @@ -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 string>>; diff --git a/tests/unit/fixture-node-modules.test.ts b/tests/unit/fixture-node-modules.test.ts index 720f76f7..3e0a0d71 100644 --- a/tests/unit/fixture-node-modules.test.ts +++ b/tests/unit/fixture-node-modules.test.ts @@ -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); diff --git a/tests/unit/manual-code-blocks.test.ts b/tests/unit/manual-code-blocks.test.ts index 10ddabc9..43cf272e 100644 --- a/tests/unit/manual-code-blocks.test.ts +++ b/tests/unit/manual-code-blocks.test.ts @@ -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); diff --git a/tests/unit/product-extension-typecheck.test.ts b/tests/unit/product-extension-typecheck.test.ts index 1d1319f9..9ebc5db5 100644 --- a/tests/unit/product-extension-typecheck.test.ts +++ b/tests/unit/product-extension-typecheck.test.ts @@ -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)], diff --git a/tests/unit/repository-layout.test.ts b/tests/unit/repository-layout.test.ts index b6ae701d..8adfb908 100644 --- a/tests/unit/repository-layout.test.ts +++ b/tests/unit/repository-layout.test.ts @@ -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[] { - 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 … -- ` is a list and a list of subcommand + * names that happen to include `docs` is not. + */ +function literalRootLists( + source: string, + tracked: ReadonlySet = trackedRootNames, + roots: ReadonlySet = 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(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 diff --git a/tests/unit/run-output-root-build.test.ts b/tests/unit/run-output-root-build.test.ts index 0104f7b3..2fab1b75 100644 --- a/tests/unit/run-output-root-build.test.ts +++ b/tests/unit/run-output-root-build.test.ts @@ -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 | undefined; diff --git a/tests/unit/template-contract-documents.test.ts b/tests/unit/template-contract-documents.test.ts index 71c9ef44..b4e8da2c 100644 --- a/tests/unit/template-contract-documents.test.ts +++ b/tests/unit/template-contract-documents.test.ts @@ -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("/"); diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts index 32239b8a..97871646 100644 --- a/tests/unit/template-feature-removal-documents.test.ts +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -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" }); diff --git a/tests/unit/two-feature-install-typecheck.test.ts b/tests/unit/two-feature-install-typecheck.test.ts index b19df20a..ef11bb34 100644 --- a/tests/unit/two-feature-install-typecheck.test.ts +++ b/tests/unit/two-feature-install-typecheck.test.ts @@ -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);