import { readFileSync } from "node:fs"; /** * The repository root registry, config/repository-layout.json (R1 in * docs/manual/03-outside-feature-folder.md). Every tracked root item has an * entry, and every list of root paths is a named set chosen from it (R2). * Seven places used to keep their own literal lists of root paths, each a * different subset, so moving one root item meant editing all seven * (design-docs repo-structure/04-frontend-layout.md ยง2.4). */ export const REPOSITORY_LAYOUT_SETS = Object.freeze([ "fixture-copy", "fixture-documents", "secret-scan", "history-free", "scale-source", "vite-build", "typescript-only", ] as const); export type RepositoryLayoutSet = (typeof REPOSITORY_LAYOUT_SETS)[number]; export const REPOSITORY_LAYOUT_KINDS = Object.freeze([ "source", "tool-convention", "gate-input", "document", "history", "output", ] as const); export type RepositoryLayoutKind = (typeof REPOSITORY_LAYOUT_KINDS)[number]; export type RepositoryLayoutEntry = Readonly<{ /** A root item name: one path segment, no slash. */ path: string; kind: RepositoryLayoutKind; role: string; readBy: string; /** A removal drill or a product copy may not have it; a selection skips it when absent. */ optional: boolean; /** The sets that select the whole item. */ sets: readonly RepositoryLayoutSet[]; /** The sets that select only these paths inside the item. */ setPaths: Readonly>>; }>; export const REPOSITORY_LAYOUT_FILE = "config/repository-layout.json"; export function parseRepositoryLayout(value: unknown): readonly RepositoryLayoutEntry[] { const document = record(value, "layout"); if (document["schemaVersion"] !== 1) throw new Error("layout: schemaVersion must be 1"); const entries = document["entries"]; if (!Array.isArray(entries) || entries.length === 0) { throw new Error("layout: entries must be a non-empty array"); } const seen = new Set(); return Object.freeze( entries.map((raw, index) => { const entry = record(raw, `entries[${index}]`); const at = `entries[${index}]`; const itemPath = text(entry["path"], `${at}.path`); if (itemPath.includes("/")) throw new Error(`${at}.path: a root item has no slash: ${itemPath}`); if (seen.has(itemPath)) throw new Error(`${at}.path: duplicate root item ${itemPath}`); seen.add(itemPath); const kind = text(entry["kind"], `${at}.kind`); if (!(REPOSITORY_LAYOUT_KINDS as readonly string[]).includes(kind)) { throw new Error(`${at}.kind: unknown kind ${kind}`); } const sets = (entry["sets"] ?? []) as unknown; if (!Array.isArray(sets)) throw new Error(`${at}.sets must be an array`); const setPaths = record(entry["setPaths"] ?? {}, `${at}.setPaths`); for (const set of [...sets, ...Object.keys(setPaths)]) { if (!(REPOSITORY_LAYOUT_SETS as readonly string[]).includes(set as string)) { throw new Error(`${at}: unknown set ${String(set)}`); } } for (const [set, paths] of Object.entries(setPaths)) { if (!Array.isArray(paths) || paths.length === 0) { throw new Error(`${at}.setPaths.${set} must be a non-empty array`); } for (const inner of paths) { if (typeof inner !== "string" || !inner.startsWith(`${itemPath}/`)) { throw new Error(`${at}.setPaths.${set}: ${String(inner)} is not inside ${itemPath}`); } } if (sets.includes(set)) throw new Error(`${at}: ${set} selects the whole item and paths in it`); } return Object.freeze({ path: itemPath, kind: kind as RepositoryLayoutKind, role: text(entry["role"], `${at}.role`), readBy: text(entry["readBy"], `${at}.readBy`), optional: entry["optional"] === true, sets: Object.freeze([...sets] as RepositoryLayoutSet[]), setPaths: Object.freeze(setPaths as Partial>), }); }), ); } export const REPOSITORY_LAYOUT: readonly RepositoryLayoutEntry[] = parseRepositoryLayout( JSON.parse(readFileSync(new URL(`../../${REPOSITORY_LAYOUT_FILE}`, import.meta.url), "utf8")), ); /** The paths a set selects, in registry order. */ export function selectRepositoryPaths( set: RepositoryLayoutSet, layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT, ): readonly string[] { return Object.freeze( layout.flatMap((entry) => entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])], ), ); } /** Like selectRepositoryPaths, with whether a drill or a copy may lack each path. */ export function selectRepositoryEntries( set: RepositoryLayoutSet, layout: readonly RepositoryLayoutEntry[] = REPOSITORY_LAYOUT, ): readonly Readonly<{ path: string; optional: boolean }>[] { return Object.freeze( layout.flatMap((entry) => (entry.sets.includes(set) ? [entry.path] : [...(entry.setPaths[set] ?? [])]).map( (selected) => Object.freeze({ path: selected, optional: entry.optional }), ), ), ); } function record(value: unknown, at: string): Record { if (typeof value !== "object" || value === null || Array.isArray(value)) { throw new Error(`${at} must be an object`); } return value as Record; } function text(value: unknown, at: string): string { if (typeof value !== "string" || value.trim() === "") throw new Error(`${at} must be a non-empty string`); return value; }