import { readdir, readFile, stat } from "node:fs/promises"; import path from "node:path"; import { describe, expect, it } from "vitest"; import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; /** * README.md, "Files you can delete after copying", tells a new project that * the build and the gates read none of the history documents except * `docs/reviews/adapters/INVENTORY.md`. The removal fixtures rely on the same * promise: they do not copy `docs/`. A test that opens a review document broke * all three removal checks (fix of 11-04), so the promise is checked here. * The root instruction files left the list on 2026-11-07: they are the * template's contract, which a copy keeps (template-contract-documents.test.ts). */ // The history-free set of config/repository-layout.json (R2). The registry // itself names every root item, history documents included (R1); naming a // root item is not reading it. const CODE_PATHS = selectRepositoryPaths("history-free"); const LAYOUT_REGISTRY = "config/repository-layout.json"; // Built from pieces so that this file does not match itself. const REVIEWS = ["docs", "reviews", ""].join("/"); const KEPT = `${REVIEWS}adapters/INVENTORY.md`; // The 2026-09-25 round's task folder moved into the history folder on // 2026-11-07 (docs/README.md §3), so the history pattern covers it. A pattern // for the old root folder would now only catch a product's own route or // folder of that name. const DELETABLE = [ new RegExp(`${REVIEWS}(?!adapters/INVENTORY\\.md)`, "u"), new RegExp(["docs", "superpowers"].join("/"), "u"), new RegExp(["docs", "history"].join("/"), "u"), new RegExp(`\\b${"SPEC"}\\.md\\b`, "u"), ]; /** * 1101/14-01. A section number without a document name cannot be followed, * and the scale design it meant used to live only in the history bundle a * copy deletes. Cite it as `scale-architecture.md §N` * (docs/architecture/scale-architecture.md, a current contract). */ const UNNAMED_SECTION = new RegExp(`\\b${"spec"} ?§`, "iu"); async function codeFiles(directory: string): Promise { const entries = await readdir(directory, { withFileTypes: true }).catch( () => [], ); const files = await Promise.all( entries.map(async (entry) => { const target = path.join(directory, entry.name); if (entry.isDirectory()) return entry.name === "node_modules" ? [] : codeFiles(target); return /\.(?:[cm]?[jt]sx?|json|ya?ml)$/u.test(entry.name) ? [target] : []; }), ); return files.flat(); } async function linesMatching(patterns: readonly RegExp[]): Promise { const files = ( await Promise.all( CODE_PATHS.map(async (entry) => (await stat(entry).catch(() => null))?.isDirectory() ? codeFiles(entry) : [entry], ), ) ).flat(); const matches: string[] = []; for (const file of files) { if (file === LAYOUT_REGISTRY) continue; const lines = (await readFile(file, "utf8").catch(() => "")).split("\n"); lines.forEach((line, index) => { if (patterns.some((pattern) => pattern.test(line))) matches.push(`${file}:${index + 1}`); }); } return matches; } describe("deletable history documents", () => { it("are read by no code, test, script or configuration", async () => { expect(await linesMatching(DELETABLE), `only ${KEPT} may be read`).toEqual([]); }); it("are not cited as an unnamed design section", async () => { expect( await linesMatching([UNNAMED_SECTION]), "name the document: scale-architecture.md §N", ).toEqual([]); }); });