import { spawnSync } from "node:child_process"; import { existsSync } from "node:fs"; import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; import { describe, expect, it } from "vitest"; import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; import { REMOVABLE_TEMPLATE_FEATURES, removableTemplateFeaturePaths, } from "../../scripts/lib/removable-template-features.ts"; import { REMOVAL_FIXTURE_COPY_TARGETS, REMOVAL_FIXTURE_DOCUMENT_TARGETS, } from "../../scripts/lib/removal-fixture.ts"; import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; /** * 1105/14-01. A copy that deleted a sample listed in * scripts/lib/removable-template-features.ts failed verify:documentation and * the FE-GATE-005 copy of it ("passes the documents as they are") wherever * the documents named the sample's folders. The template lists no sample * since 2026-11-07, so the copy here gets one: the feature `create:feature` * writes, listed and named in a document, then deleted. */ const CHECKER = "scripts/verify-documentation-readiness.ts"; /** What verify:documentation reads besides the code: the documents a drill copies. */ const DOCUMENTS = REMOVAL_FIXTURE_DOCUMENT_TARGETS; const LISTED_SAMPLE = Object.freeze({ featureId: "listed-sample-feature", contextDirectory: "src/contexts/listed-sample-context", extraPaths: Object.freeze([]), scripts: Object.freeze([]), }); const NAMING_DOCUMENT = "docs/architecture/starter-experience.md"; /** * A copy of the repository with LISTED_SAMPLE installed, listed and named in * NAMING_DOCUMENT (its module and a file it does not have). `verify` runs the * copy's verify:documentation; `remove` deletes the sample as a product does * (its paths and route records), then generates the feature index again. */ async function copyWithListedSample() { const parent = await mkdtemp(path.join(tmpdir(), "template-feature-removal-")); const root = path.join(parent, "frontend"); for (const entry of [...REMOVAL_FIXTURE_COPY_TARGETS, ...DOCUMENTS]) { // A drill runs this test in a copy that has already lost some of them. if (!existsSync(entry)) continue; await cp(entry, path.join(root, entry), { recursive: true, filter: (source) => !source.includes(`${path.sep}.generated`), }); } await linkFixtureNodeModules(root); const node = (args: readonly string[]) => spawnSync(process.execPath, args, { cwd: root, encoding: "utf8" }); for (const args of [ ["scripts/generate-product-feature-index.ts"], ["scripts/create-feature.ts", LISTED_SAMPLE.featureId], ]) { const result = node(args); expect(result.status, `${result.stdout}${result.stderr}`).toBe(0); } const list = path.join(root, "scripts/lib/removable-template-features.ts"); const listed = (await readFile(list, "utf8")).replace( "Object.freeze([]);", `Object.freeze([${JSON.stringify(LISTED_SAMPLE)}]);`, ); expect(listed).toContain(LISTED_SAMPLE.featureId); await writeFile(list, listed); const named = [ `src/features/${LISTED_SAMPLE.featureId}/feature-module.ts`, `src/features/${LISTED_SAMPLE.featureId}/no-such-module.ts`, ]; const document = path.join(root, NAMING_DOCUMENT); await writeFile( document, `${await readFile(document, "utf8")}\n${named.map((file) => `- \`${file}\``).join("\n")}\n`, ); return { named, verify: () => node([CHECKER]), async remove() { for (const entry of removableTemplateFeaturePaths(LISTED_SAMPLE)) { await rm(path.join(root, entry), { recursive: true, force: true }); } await rm(path.join(root, "docs/accessibility/route-reviews/LISTED_SAMPLE_LIST.md"), { force: true }); expect(node(["scripts/generate-product-feature-index.ts"]).status).toBe(0); }, cleanUp: () => rm(parent, { recursive: true, force: true }), }; } /** * Runs this repository's verify:documentation on a copy of the documents * with `mutate` applied to `document`; the code facts are this repository's. * `documents` are the ones it checked (docs/README.md ยง1 and what it links). */ async function verifyDocuments(document: string, mutate: (text: string) => string = (text) => text) { const parent = await mkdtemp(path.join(tmpdir(), "template-feature-documents-")); const root = path.join(parent, "frontend"); try { // The pin says which commit of the paired backend the documents describe. for (const entry of selectRepositoryPaths("documentation-inputs")) await cp(entry, path.join(root, entry), { recursive: true }); const target = path.join(root, document); await writeFile(target, mutate(await readFile(target, "utf8"))); const result = spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" }); const report = JSON.parse( await readFile(path.join(root, "artifacts/quality/documentation-review.json"), "utf8"), ) as { documentReferences: { path: string }[] }; return { ...result, documents: report.documentReferences.map((entry) => entry.path) }; } finally { await rm(parent, { recursive: true, force: true }); } } describe("verify:documentation after a listed sample is deleted (1105/14-01)", () => { // Only a deleted sample's paths are let through. While it is installed a // missing path under it fails; once it is deleted, the documents that name // it pass. it("fails on a missing path under an installed sample and passes once it is deleted", async () => { const copy = await copyWithListedSample(); try { const installed = copy.verify(); expect(installed.status).toBe(1); expect(installed.stderr).toContain(`${NAMING_DOCUMENT} names paths that do not exist:`); expect(installed.stderr).toContain(copy.named[1]); expect(installed.stderr).not.toContain(copy.named[0]); await copy.remove(); const deleted = copy.verify(); expect(deleted.status, deleted.stderr).toBe(0); } finally { await copy.cleanUp(); } }, 180_000); it("still fails on a feature folder that is not on the list", async () => { const missing = "src/features/no-such-template-feature/feature-module.ts"; const result = await verifyDocuments(NAMING_DOCUMENT, (text) => `${text}\n- \`${missing}\`\n`); expect(result.status).toBe(1); expect(result.stderr).toContain(`${NAMING_DOCUMENT} names paths that do not exist:`); expect(result.stderr).toContain(missing); }, 60_000); }); /** Fenced blocks whose command lines verify:documentation reads. */ const SHELL_FENCE = /^(?:bash|sh|shell|console|zsh)?$/u; /** * 1105/14-03. The fix for 1103/14-04 wrote the reference sample's paths * without backticks so that a copy without the sample passed, which also took * 26 lines out of the check while the sample is installed: renaming one of * its files left the manual pointing at nothing. Deleted features' paths are * accepted now (above), so a current contract document names a removable * template feature's path or script only where verify:documentation reads * it: in an inline code span, a link target or a shell code block. */ describe("removable template features in the current contract documents (1105/14-03)", () => { it("names their paths and scripts only where verify:documentation checks them", async () => { const { documents } = await verifyDocuments("docs/README.md"); const owned = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => [ ...removableTemplateFeaturePaths(feature), ...feature.scripts, ]); const unchecked: string[] = []; for (const document of documents) { const lines = (await readFile(document, "utf8")).split("\n"); let fence: string | null = null; for (const [index, line] of lines.entries()) { const marker = /^\s*```(\w*)/u.exec(line); if (marker) { fence = fence === null ? (marker[1] ?? "") : null; continue; } if (fence !== null && SHELL_FENCE.test(fence)) continue; const prose = line.replace(/`[^`\n]+`/gu, "").replace(/\]\([^)\s]+\)/gu, "]"); for (const entry of owned) { if (prose.includes(entry)) unchecked.push(`${document}:${index + 1}: ${entry}`); } } } expect(documents).toContain("docs/manual/01-add-a-feature.md"); expect(unchecked).toEqual([]); }, 60_000); });