import { spawnSync } from "node:child_process"; import { existsSync, readFileSync } from "node:fs"; import path from "node:path"; import { describe, expect, it } from "vitest"; 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 * that a file listing can check: R1 (every root item is registered), R2 (root * path lists are chosen from the registry), R7 for files (no infrastructure * configuration in this repository) and R9 (a tsconfig differs in its * options, not only in its files). R3 is tests/unit/tracked-artifacts.test.ts. */ function trackedFiles(): string[] { const listed = spawnSync("git", ["ls-files", "-z"], { encoding: "utf8" }); if (listed.error || listed.status !== 0) { throw new Error(`git ls-files failed: ${listed.error?.message ?? listed.stderr}`); } return listed.stdout.split("\0").filter((file) => file !== ""); } const rootItemNames = new Set(REPOSITORY_LAYOUT.map((entry) => entry.path)); /** 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: // whatever is tracked at the root is registered. A registered path that is // gone fails where a set uses it (a copy or the secret scan cannot find it). it("has an entry for every tracked root item", () => { const roots = new Set(trackedFiles().map((file) => file.split("/")[0]!)); expect( [...roots].filter((root) => !rootItemNames.has(root)).sort(), `add an entry with its role to ${REPOSITORY_LAYOUT_FILE}`, ).toEqual([]); }); it("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( /no slash/u, ); expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [entry, entry] })).toThrow(/duplicate/u); expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, setPaths: { "vite-build": ["scripts/lib/run-isolation.ts"] } }], }), ).toThrow(/not inside src/u); expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, kind: "misc" }] })).toThrow( /unknown kind/u, ); expect(() => parseRepositoryLayout({ schemaVersion: 1, entries: [{ ...entry, sets: ["everything"] }] })).toThrow( /unknown set/u, ); 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: ".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([".ci/workflows/a.yml", "extras", "app"]); expect(selectRepositoryPaths("vite-build", layout)).toEqual(["app"]); expect(selectRepositoryEntries("secret-scan", layout).filter(({ optional }) => optional)).toEqual([ { 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; 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 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"]; /** * Lists that look like root path lists but describe a made-up repository a * test builds in memory: moving a root item never changes them. Only the exact * list in that file is excused, and an entry that no longer matches fails, so * it cannot hide a later list. */ const MADE_UP_REPOSITORY_LISTS: readonly Readonly<{ file: string; list: string; reason: string }>[] = [ { file: "tests/unit/docs-system.test.ts", list: "docs, docs/architecture, docs/architecture/layers.md, src, src/platform", reason: "knownPaths of the in-memory repository the docs-system checker test builds", }, ]; 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 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))) .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("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); const found = files.flatMap((file) => literalRootLists(readFileSync(file, "utf8")).map((list) => ({ file, list }))); const excused = (file: string, list: string) => MADE_UP_REPOSITORY_LISTS.some((entry) => entry.file === file && entry.list === list); expect( found.filter(({ file, list }) => !excused(file, list)).map(({ file, list }) => `${file}: [${list}]`), `choose a set from ${REPOSITORY_LAYOUT_FILE} with selectRepositoryPaths`, ).toEqual([]); // A removal drill copy may lack the excused file; an excuse is stale only where the file is checked. expect( MADE_UP_REPOSITORY_LISTS.filter( (entry) => files.includes(entry.file) && !found.some(({ file, list }) => entry.file === file && entry.list === list), ), "MADE_UP_REPOSITORY_LISTS entries that match no list any more", ).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("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 // browser file/storage capability takes the whole browser-capability harness // with it — and prunes the policy to match. The claim is about the inputs // this checkout has. it("keeps the secret scan policy's roots equal to the secret-scan set", () => { const policy = JSON.parse(readFileSync("config/security/secret-scan-policy.json", "utf8")) as { trackedRoots: string[]; }; expect([...policy.trackedRoots].sort()).toEqual( [...selectRepositoryPaths("secret-scan").filter((input) => existsSync(input))].sort(), ); }); }); /** R7. Development compose files and Dockerfiles may live here; host and cluster configuration may not. */ const INFRASTRUCTURE_FILE = /(?:^|\/)(?:nginx[^/]*|[^/]+\.tf|[^/]+\.tfvars|Chart\.ya?ml|kustomization\.ya?ml|helmfile\.ya?ml)$/iu; const KUBERNETES_MANIFEST = /^apiVersion:\s*\S+\s*$[\s\S]*^kind:\s*\S+\s*$/mu; describe("infrastructure configuration (R7)", () => { it("is not tracked in this repository", () => { const files = trackedFiles(); const manifests = files .filter((file) => /\.ya?ml$/u.test(file) && existsSync(file)) .filter((file) => KUBERNETES_MANIFEST.test(readFileSync(file, "utf8"))); expect([...files.filter((file) => INFRASTRUCTURE_FILE.test(file)), ...manifests]).toEqual([]); }); it("recognises the file kinds the rule names", () => { expect(["deploy/nginx.conf", "infra/main.tf", "chart/Chart.yaml", "kustomization.yml"].filter((file) => INFRASTRUCTURE_FILE.test(file), )).toHaveLength(4); expect(KUBERNETES_MANIFEST.test("apiVersion: apps/v1\nkind: Deployment\n")).toBe(true); expect(INFRASTRUCTURE_FILE.test("compose.yaml")).toBe(false); }); }); type TsconfigDocument = Readonly<{ extends?: string; compilerOptions?: Record; files?: readonly string[]; references?: readonly unknown[]; }>; function effectiveCompilerOptions(file: string): Record { const document = JSON.parse(readFileSync(file, "utf8")) as TsconfigDocument; const inherited = document.extends?.startsWith(".") ? effectiveCompilerOptions(path.join(path.dirname(file), document.extends)) : {}; return { ...inherited, ...document.compilerOptions }; } /** Pairs of tsconfig files whose options are the same; a solution tsconfig (references only) has none. */ function sameOptionTsconfigs(files: readonly string[]): string[] { const options = files .filter((file) => { const document = JSON.parse(readFileSync(file, "utf8")) as TsconfigDocument; return !(document.references && document.files?.length === 0); }) .map((file) => ({ file, options: JSON.stringify(Object.entries(effectiveCompilerOptions(file)).sort(([a], [b]) => a.localeCompare(b))), })); return options.flatMap((left, index) => options.slice(index + 1).filter((right) => right.options === left.options).map((right) => `${left.file} = ${right.file}`), ); } describe("tsconfig files (R9)", () => { // tests/fixtures/typecheck had 23 one-file tsconfigs with one set of // options until 2026-11-08; scripts/check-type-fixtures.ts runs them now. it("differ in lib, types or module resolution, not only in their files", () => { const tsconfigs = trackedFiles().filter((file) => /(?:^|\/)tsconfig[^/]*\.json$/u.test(file) && existsSync(file)); expect(tsconfigs.length).toBeGreaterThan(1); expect(sameOptionTsconfigs(tsconfigs)).toEqual([]); }); });