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); 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([ "fixture-copy", "fixture-documents", "secret-scan", "history-free", "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]; export const REPOSITORY_LAYOUT_KINDS = Object.freeze([ "source", "tool-convention", "gate-input", "document", "history", "output", "untracked", ] as const); export type RepositoryLayoutKind = (typeof REPOSITORY_LAYOUT_KINDS)[number]; export type RepositoryLayoutEntry = Readonly<{ /** A root item name: one path segment, no slash. */ path: string; kind: RepositoryLayoutKind; role: string; readBy: string; /** A removal drill or a product copy may not have it; a selection skips it when absent. */ optional: boolean; /** The sets that select the whole item. */ sets: readonly RepositoryLayoutSet[]; /** The sets that select only these paths inside the item. */ setPaths: Readonly>>; }>; export const REPOSITORY_LAYOUT_FILE = "config/repository-layout.json"; export function parseRepositoryLayout(value: unknown): readonly RepositoryLayoutEntry[] { const document = record(value, "layout"); if (document["schemaVersion"] !== 1) throw new Error("layout: schemaVersion must be 1"); // 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"); } const seen = new Set(); return Object.freeze( entries.map((raw, index) => { const entry = record(raw, `entries[${index}]`); const at = `entries[${index}]`; const itemPath = text(entry["path"], `${at}.path`); if (itemPath.includes("/")) throw new Error(`${at}.path: a root item has no slash: ${itemPath}`); if (seen.has(itemPath)) throw new Error(`${at}.path: duplicate root item ${itemPath}`); seen.add(itemPath); const kind = text(entry["kind"], `${at}.kind`); if (!(REPOSITORY_LAYOUT_KINDS as readonly string[]).includes(kind)) { throw new Error(`${at}.kind: unknown kind ${kind}`); } 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`); for (const set of [...sets, ...Object.keys(setPaths)]) { if (!(REPOSITORY_LAYOUT_SETS as readonly string[]).includes(set as string)) { throw new Error(`${at}: unknown set ${String(set)}`); } } for (const [set, paths] of Object.entries(setPaths)) { if (!Array.isArray(paths) || paths.length === 0) { throw new Error(`${at}.setPaths.${set} must be a non-empty array`); } for (const inner of paths) { if (typeof inner !== "string" || !inner.startsWith(`${itemPath}/`)) { throw new Error(`${at}.setPaths.${set}: ${String(inner)} is not inside ${itemPath}`); } } if (sets.includes(set)) throw new Error(`${at}: ${set} selects the whole item and paths in it`); } return Object.freeze({ path: itemPath, kind: kind as RepositoryLayoutKind, role: text(entry["role"], `${at}.role`), readBy: text(entry["readBy"], `${at}.readBy`), optional: entry["optional"] === true, sets: Object.freeze([...sets] as RepositoryLayoutSet[]), setPaths: Object.freeze(setPaths as Partial>), }); }), ); } export const REPOSITORY_LAYOUT: readonly RepositoryLayoutEntry[] = parseRepositoryLayout( JSON.parse(readFileSync(new URL(`../../${REPOSITORY_LAYOUT_FILE}`, import.meta.url), "utf8")), ); /** The paths a set selects, in registry order. */ export function selectRepositoryPaths( set: RepositoryLayoutSet, layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT, ): readonly string[] { return Object.freeze( layout.flatMap((entry) => entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])], ), ); } /** Like selectRepositoryPaths, with whether a drill or a copy may lack each path. */ export function selectRepositoryEntries( set: RepositoryLayoutSet, layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT, ): readonly Readonly<{ path: string; optional: boolean }>[] { return Object.freeze( layout.flatMap((entry) => (entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])]).map( (selected) => Object.freeze({ path: selected, optional: entry.optional }), ), ), ); } function record(value: unknown, at: string): Record { if (typeof value !== "object" || value === null || Array.isArray(value)) { throw new Error(`${at} must be an object`); } return value as Record; } function text(value: unknown, at: string): string { if (typeof value !== "string" || value.trim() === "") throw new Error(`${at} must be a non-empty string`); return value; }