import { readdir, readFile } from "node:fs/promises"; import path from "node:path"; import { describe, expect, it } from "vitest"; import { loadCiGateContract } from "../../scripts/contracts/ci-gates.ts"; import { REMOVABLE_TEMPLATE_FEATURES, type RemovableTemplateFeature, } from "../../scripts/lib/removable-template-features.ts"; import { INSTALLED_FEATURE_CONTRACTS } from "../../src/features/installed-feature-contracts.ts"; /** * R4 and R5 of docs/manual/03-outside-feature-folder.md. A sample feature * that the template or a project ships is listed in * scripts/lib/removable-template-features.ts, and the list is proven by a * drill that builds and tests a copy without it (R4). The gates' own targets * (visual goldens, e2e routes, the gate evidence list, scale measurements) * are platform screens, test fixtures and generator output, never a sample a * copy is meant to delete (R5): the template's reference sample was the * target of nine gates when it was deleted on 2026-11-07. */ type ExampleFeature = Readonly<{ featureId: string; routeIds: readonly string[]; routePaths: readonly string[] }>; type GateTargets = Readonly<{ gotoTargets: readonly Readonly<{ file: string; target: string }>[]; artifactPaths: readonly string[]; scaleFiles: readonly Readonly<{ file: string; text: string }>[]; }>; function exampleFeatures(features: readonly RemovableTemplateFeature[]): ExampleFeature[] { return features.map(({ featureId }) => { // The template installs no feature, so the composed list's type is empty. const contracts = INSTALLED_FEATURE_CONTRACTS as readonly Readonly<{ featureId: string; routes: object }>[]; const routes = contracts.filter((contract) => contract.featureId === featureId).flatMap( (contract) => Object.values(contract.routes as Record), ); return { featureId, routeIds: routes.map(({ routeId }) => routeId), routePaths: routes.map(({ path: routePath }) => routePath).filter((routePath) => routePath !== "/"), }; }); } function gateTargetsNamingExamples(examples: readonly ExampleFeature[], targets: GateTargets): string[] { return examples.flatMap(({ featureId, routeIds, routePaths }) => [ ...targets.gotoTargets .filter(({ target }) => target.includes(featureId) || routePaths.some((routePath) => target === routePath || target.startsWith(`${routePath}/`) || target.startsWith(`${routePath}?`))) .map(({ file, target }) => `${file}: goto ${target}`), ...targets.artifactPaths .filter((artifact) => artifact.includes(featureId) || routeIds.some((routeId) => artifact.includes(`/${routeId}.`))) .map((artifact) => `config/ci/gates.json: ${artifact}`), ...targets.scaleFiles.filter(({ text }) => text.includes(featureId)).map(({ file }) => `${file}: ${featureId}`), ]); } async function specFiles(directory: string): Promise { return ((await readdir(directory, { recursive: true })) as string[]) .filter((name) => /\.ts$/u.test(name)) .map((name) => path.join(directory, name)); } async function repositoryGateTargets(): Promise { const gotoTargets: { file: string; target: string }[] = []; for (const file of [...(await specFiles("tests/visual")), ...(await specFiles("tests/e2e"))]) { const source = await readFile(file, "utf8"); for (const [, target = ""] of source.matchAll(/\.goto\(\s*["'`]([^"'`]+)["'`]/gu)) gotoTargets.push({ file, target }); } const contract = await loadCiGateContract(process.cwd()); const scaleFiles = await Promise.all( (await readdir("config/scale")).map(async (name) => ({ file: `config/scale/${name}`, text: await readFile(`config/scale/${name}`, "utf8"), })), ); return { gotoTargets, artifactPaths: contract.artifacts.map(({ path: artifact }) => artifact), scaleFiles }; } describe("sample features (R4)", () => { it("are all proven by the removal drill in FE-GATE-020", async () => { const contract = await loadCiGateContract(process.cwd()); const removability = contract.gates.find(({ id }) => id === "FE-GATE-020"); const scripts = new Set( contract.commands .filter(({ id }) => removability?.commandIds.includes(id)) .map(({ script }) => script), ); expect(scripts).toContain("test:sample-removal"); // Without `--feature` the drill deletes every listed sample. const packageScripts = (JSON.parse(await readFile("package.json", "utf8")) as { scripts: Record }) .scripts; expect(packageScripts["test:sample-removal"]).not.toMatch(/--feature/u); // It builds and tests the copy; a documents-only check does not prove removal. const drill = await readFile("scripts/test-sample-removal.ts", "utf8"); expect(drill).toMatch(/check\(`\$\{prefix\}build`, "build"\)/u); expect(drill).toMatch(/check\(`\$\{prefix\}unit-integration`, "test:all"\)/u); }); }); describe("gate targets (R5)", () => { it("name no sample feature", async () => { expect(gateTargetsNamingExamples(exampleFeatures(REMOVABLE_TEMPLATE_FEATURES), await repositoryGateTargets())).toEqual( [], ); }); it("finds a sample's route in a visual spec, the evidence list and a scale record", () => { const sample = { featureId: "order-feature", routeIds: ["ORDER_LIST"], routePaths: ["/orders"] }; expect( gateTargetsNamingExamples([sample], { gotoTargets: [ { file: "tests/visual/a.visual.spec.ts", target: "/orders?page=2" }, { file: "tests/visual/a.visual.spec.ts", target: "/examples/platform" }, ], artifactPaths: ["docs/accessibility/route-reviews/ORDER_LIST.md", "artifacts/quality/bundle.json"], scaleFiles: [{ file: "config/scale/feature-shape-growth.json", text: '{"sourceFeature":"order-feature"}' }], }), ).toEqual([ "tests/visual/a.visual.spec.ts: goto /orders?page=2", "config/ci/gates.json: docs/accessibility/route-reviews/ORDER_LIST.md", "config/scale/feature-shape-growth.json: order-feature", ]); }); });