import { access, mkdir, readdir, readFile, rm, writeFile, } from "node:fs/promises"; import { spawnSync } from "node:child_process"; import path from "node:path"; import { ROUTE_FEATURE_OWNER } from "../src/features/installed-feature-contracts.ts"; import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts"; import { isProductionModulePath } from "./lib/risk-coverage.ts"; import { createRemovalFixtureRoot, filesBelow, prepareRemovalFixture, pruneRemovalFixtureCiContract, pruneScriptOrchestration, regenerateRemovalFixtureWorkflow, REMOVAL_FIXTURE_COPY_TARGETS, REMOVAL_FIXTURE_DOCUMENT_TARGETS, renderRemovalJunit, requireRemovalFixtureEnvironment, runRemovalFixtureCheck, runRemovalFixturePnpm, sealRemovalFixtureRepository, type RemovalCheck, } from "./lib/removal-fixture.ts"; /** * 09-07 (D-10). Removes one installed feature, `--feature=` (default: the * reference sample), from a copy of the repository and proves the rest still * typechecks, tests, covers and builds. Every feature loses its directory, its * tests/features directory, its context when no other feature is left in it, * its runtime-profile override and its central policy rows. The sample also * owns the extra paths and scripts listed in SAMPLE_EXTRAS. */ const featureId = process.argv.find((argument) => argument.startsWith("--feature=")) ?.slice("--feature=".length) ?? "reference-feature"; type FeatureExtras = Readonly<{ paths: readonly string[]; ciScripts: readonly string[]; evidencePathFragments: readonly string[]; residue: RegExp; }>; const SAMPLE_EXTRAS: Readonly> = Object.freeze({ "reference-feature": Object.freeze({ // 0929/10-02. The HTTP scenario catalog (tests/mocks) and the negative // type fixtures of the feature APIs run on the test contracts, so they are // platform checks and stay (commonTestPaths below). paths: [ "tests/component/product-feature-switch.test.tsx", "tests/e2e/reference-form.spec.ts", "tests/e2e/reference-route.spec.ts", "tests/e2e/reference-save.spec.ts", // 11-04: the growth measurement copies this sample feature. "tests/unit/feature-shape-growth.test.ts", "scripts/scale/measure-feature-shape-growth.ts", "config/scale/feature-shape-growth.json", "config/scale/feature-shape-ceilings.json", ], ciScripts: [ "test:reference-feature", ], evidencePathFragments: [ "reference-feature.xml", ], residue: /REFERENCE_RESOURCE|reference-feature|reference-resource/i, }), }); function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"); } async function locateFeature(id: string) { const source = await createFileSystemDeclarationSource(process.cwd()); for (const appId of source.appIds()) { for (const context of source.contextsOf(appId)) { const features = source.featuresOf(context.id); const feature = features.find((candidate) => candidate.id === id); if (!feature) continue; let contextDirectory: string | null = null; for (const entry of await readdir("src/contexts", { withFileTypes: true })) { if (!entry.isDirectory()) continue; const declaration = await readFile( path.join("src/contexts", entry.name, "context-module.ts"), "utf8", ).catch(() => ""); if ( new RegExp(`CONTEXT_MODULE_ID\\s*=\\s*["']${escapeRegExp(context.id)}["']`, "u") .test(declaration) ) { contextDirectory = `src/contexts/${entry.name}`; } } return Object.freeze({ directory: feature.directory, // The context goes with its last feature. contextDirectory: features.length === 1 ? contextDirectory : null, }); } } throw new Error(`No installed feature declares FEATURE_MODULE_ID "${id}"`); } const located = await locateFeature(featureId); const extras: FeatureExtras = SAMPLE_EXTRAS[featureId] ?? Object.freeze({ paths: [], ciScripts: [], evidencePathFragments: [], residue: new RegExp( `${escapeRegExp(featureId)}|${escapeRegExp(located.directory)}`, "i", ), }); // Captured from this repository before the copy loses them. const featureRouteIds = Object.entries(ROUTE_FEATURE_OWNER) .filter(([, owner]) => owner === featureId) .map(([routeId]) => routeId); const fixtureRoot = await createRemovalFixtureRoot(`${featureId}-removal`); const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath"); const featureSource = `src/features/${located.directory}`; const featureTests = `tests/features/${located.directory}`; const isSample = featureId in SAMPLE_EXTRAS; /** * Platform tests that must survive the sample feature's removal. Asserting they * are still present is what stops the removal fixture from "passing" by having * quietly deleted the platform's own coverage along with the feature. */ const commonTestPaths = [ "tests/unit/external-contract-runtime.test.ts", "tests/unit/http-execution-v3.test.ts", "tests/unit/runtime-adapters.test.ts", "tests/integration/http-execution-v3-observability.test.ts", // 0929/10-02. HTTP scenario evidence (FE-GATE-007) and the feature API // negative type fixtures (FE-GATE-003) run on the test contracts. "tests/integration/http-scenario-catalog.test.ts", "tests/mocks/scenarios/catalog.ts", "tests/mocks/handlers/test-entities.ts", // 16-02. Feature tests answer their own operations with it. "tests/mocks/handlers/http-scenarios.ts", "tests/fixtures/typecheck/fixture-feature-contract.ts", "tests/fixtures/typecheck/invalid-feature-input.ts", "tests/fixtures/typecheck/invalid-reference-operation.ts", "tests/fixtures/typecheck/invalid-http-operation-input.ts", "tests/fixtures/typecheck/invalid-http-wire-mapper.ts", "tests/fixtures/typecheck/invalid-http-operation-id.ts", "tests/fixtures/typecheck/invalid-http-route-id.ts", "tests/fixtures/typecheck/invalid-feature-contribution-input.ts", "tests/fixtures/typecheck/invalid-feature-capability-selection.ts", ]; const featureOwnedPaths = [ featureSource, featureTests, // The feature's bounded-context declaration when it was the last feature in // it; the template app stays. ...(located.contextDirectory === null ? [] : [located.contextDirectory]), ...extras.paths, ]; type CoveragePolicy = { repositoryBaseline: number; generatedPaths: string[]; criticalModules: Array<{ path?: string; minimum?: Record; }>; highRiskPaths: string[]; waivers: Array<{ path?: string }>; }; type EvidenceContribution = Readonly<{ owner?: string }>; type EvidencePolicy = Record< "scenarioCatalogs" | "sourceContracts", unknown >; type GovernanceConsumer = Readonly<{ path?: string }>; type GovernanceRegistry = Record & { consumers?: unknown; consumerDirectories?: unknown; }; type RemovalGovernance = { registries: GovernanceRegistry[] }; function runPnpm(script: string, extra: string[] = []): boolean { return runRemovalFixturePnpm(fixtureRoot, pnpmCli, script, extra); } function check(name: string, script: string, extra: string[] = []): RemovalCheck { return runRemovalFixtureCheck(name, fixtureRoot, pnpmCli, script, extra); } /** 14-08. A non-command check fails with its own findings, nothing else's. */ function outcome(name: string, findings: readonly string[], label: string): RemovalCheck { return findings.length === 0 ? { name, passed: true } : { name, passed: false, failure: `${label}: ${findings.join(", ")}` }; } try { // 1103/14-04. The documents come too: removing a feature must leave them // valid, and the fixture used to leave them out with the tests that read // them, so a manual naming the sample's files passed here and then failed // FE-GATE-017 in the product that removed it. await prepareRemovalFixture(fixtureRoot, [ ...REMOVAL_FIXTURE_COPY_TARGETS, ...REMOVAL_FIXTURE_DOCUMENT_TARGETS, ]); // Fixture-only deletions: a project that removes the sample keeps these. // verify:documentation runs in this fixture, so a current contract document // must not name them as backtick paths (docs/manual/reference/patterns.md). for (const excludedFixtureTest of [ "tests/unit/ci-workflow-generation.test.ts", "tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap", "tests/unit/removal-fixture.test.ts", "tests/unit/http-scenario-evidence.test.ts", ]) { await rm(path.join(fixtureRoot, excludedFixtureTest), { force: true }); } const coveragePolicyFile = path.join( fixtureRoot, "config/testing/risk-coverage.json", ); const coveragePolicy = JSON.parse( await readFile(coveragePolicyFile, "utf8"), ) as CoveragePolicy; const generatedProductionModules = new Set(coveragePolicy.generatedPaths); const removedProductionModuleCount = ( await filesBelow(path.join(fixtureRoot, featureSource)) ) .map((file) => path.relative(fixtureRoot, file).split(path.sep).join("/")) .filter( (file) => isProductionModulePath(file) && !generatedProductionModules.has(file), ).length; for (const ownedPath of featureOwnedPaths) { await rm(path.join(fixtureRoot, ownedPath), { recursive: true, force: true, }); } if (!runPnpm("generate:feature-index")) { throw new Error("Feature topology indexes failed to regenerate after sample removal"); } // Runtime profiles are product configuration. Once the feature is physically // removed, its override key must disappear too or the built config still // advertises a source capability that no longer exists. public/config.json // is the local profile `dev` serves and has to stay equal to it (F-5). for (const configPath of [ "config/runtime/local.json", "config/runtime/development.json", "config/runtime/staging.json", "config/runtime/production.json", "public/config.json", ]) { const profilePath = path.join(fixtureRoot, configPath); const runtimeConfig = JSON.parse( await readFile(profilePath, "utf8"), ) as { FEATURE_OVERRIDES?: Record; }; if (runtimeConfig.FEATURE_OVERRIDES) { delete runtimeConfig.FEATURE_OVERRIDES[featureId]; } await writeFile( profilePath, `${JSON.stringify(runtimeConfig, null, 2)}\n`, ); } const retainedCriticalModules = coveragePolicy.criticalModules.filter( (modulePolicy) => !modulePolicy.path?.startsWith(`${featureSource}/`), ); if ( isSample && retainedCriticalModules.length === coveragePolicy.criticalModules.length ) { throw new Error("Reference feature coverage policy is not registered"); } coveragePolicy.criticalModules = retainedCriticalModules; coveragePolicy.highRiskPaths = coveragePolicy.highRiskPaths.filter( (modulePath) => !modulePath.startsWith(`${featureSource}/`), ); coveragePolicy.waivers = coveragePolicy.waivers.filter( (waiver) => !waiver.path?.startsWith(`${featureSource}/`), ); coveragePolicy.generatedPaths = coveragePolicy.generatedPaths.filter( (modulePath) => !modulePath.startsWith(`${featureSource}/`), ); coveragePolicy.repositoryBaseline -= removedProductionModuleCount; if (coveragePolicy.repositoryBaseline <= 0) { throw new Error("Reference feature removal produced an invalid coverage baseline"); } await writeFile( coveragePolicyFile, `${JSON.stringify(coveragePolicy, null, 2)}\n`, ); const evidencePolicyFile = path.join( fixtureRoot, "config/testing/test-evidence.json", ); const evidencePolicy = JSON.parse( await readFile(evidencePolicyFile, "utf8"), ) as EvidencePolicy; for (const policyKey of ["scenarioCatalogs", "sourceContracts"] as const) { const contributions = evidencePolicy[policyKey]; if (!Array.isArray(contributions)) { throw new Error(`Test evidence policy is missing ${policyKey}`); } // A feature's own evidence goes with it. The sample has none since // 0929/10-02: the HTTP scenario catalog is owned by the platform. evidencePolicy[policyKey] = contributions.filter( (candidate: unknown) => (candidate as EvidenceContribution).owner !== featureId, ); } await writeFile( evidencePolicyFile, `${JSON.stringify(evidencePolicy, null, 2)}\n`, ); const governanceFile = path.join( fixtureRoot, "config/contracts/registry-governance.json", ); const removalGovernance = JSON.parse( await readFile(governanceFile, "utf8"), ) as RemovalGovernance; removalGovernance.registries = removalGovernance.registries.map( (registry) => ({ ...registry, ...(Array.isArray(registry.consumers) ? { consumers: registry.consumers.filter( (candidate: unknown) => { const consumer = candidate as GovernanceConsumer; return !consumer.path?.includes(featureSource); }, ), } : {}), ...(Array.isArray(registry.consumerDirectories) ? { consumerDirectories: registry.consumerDirectories.filter( (directory: unknown) => typeof directory !== "string" || !directory.includes(featureSource), ), } : {}), }), ); await writeFile( governanceFile, `${JSON.stringify(removalGovernance, null, 2)}\n`, ); const removedCiScripts = new Set(extras.ciScripts); const fixturePackagePath = path.join(fixtureRoot, "package.json"); const fixturePackage = JSON.parse(await readFile(fixturePackagePath, "utf8")) as { scripts: Record; }; pruneScriptOrchestration(fixturePackage.scripts, "test:all", removedCiScripts); await writeFile(fixturePackagePath, `${JSON.stringify(fixturePackage, null, 2)}\n`); await pruneRemovalFixtureCiContract({ root: fixtureRoot, removedScripts: removedCiScripts, removedEvidencePathFragments: extras.evidencePathFragments, }); // D-13: removing the sample is a breaking registry change. The fixture // records the new registry baseline the way a downstream project does, and // the canonical check:registries then runs against it. if (!runRemovalFixturePnpm(fixtureRoot, pnpmCli, "update:registry-baseline", [], { REGISTRY_BASELINE_OWNER: "removal-fixture", REGISTRY_BASELINE_REASON: `${featureId} removed`, })) { throw new Error("Registry baseline failed to update after sample removal"); } // 1103 X2 #3. The dev server's manifest names the installed contract // packages; the removed feature's is gone. const devManifest = spawnSync(process.execPath, ["scripts/write-dev-release-manifest.ts"], { cwd: fixtureRoot, stdio: "inherit", }); if (devManifest.status !== 0) { throw new Error("public/release-manifest.json failed to update after the removal"); } // 1103 X2 #2. config/scale/feature-shape-ceilings.json records the initial // JavaScript of the features installed now, and test:unit compares a build // with it. A product re-records it when it adds a feature; removing that // feature changes it again, so the fixture re-records it as the product // would. The sample removal deletes the measurement with the sample. const measurement = path.join(fixtureRoot, "scripts/scale/measure-feature-shape-growth.ts"); if (await access(measurement).then(() => true, () => false)) { const measured = spawnSync( process.execPath, [measurement, "--initial-baseline", "--write"], { cwd: fixtureRoot, stdio: "inherit" }, ); if (measured.status !== 0) { throw new Error("Initial JavaScript record failed to update after the removal"); } } await regenerateRemovalFixtureWorkflow(fixtureRoot); const residue: string[] = []; for (const root of ["src", "tests"]) { for (const file of await filesBelow(path.join(fixtureRoot, root))) { const relative = path.relative(fixtureRoot, file); const content = await readFile(file, "utf8"); if (extras.residue.test(`${relative}\n${content}`)) { residue.push(relative); } } } const missingCommonTests: string[] = []; for (const testPath of commonTestPaths) { await access(path.join(fixtureRoot, testPath)).catch(() => { missingCommonTests.push(testPath); }); } const gateChecks = (prefix: string): RemovalCheck[] => [ check(`${prefix}typecheck`, "check:types"), // 1103/14-04 (FOLLOW-UP 09-07). Merge and documentation gates the drill // did not run: the documents, lint, screen text and design tokens can // name or use what the removal deleted. check(`${prefix}lint`, "lint"), check(`${prefix}documentation`, "verify:documentation"), check(`${prefix}i18n`, "check:i18n"), check(`${prefix}design-system`, "check:design-system"), check(`${prefix}architecture`, "check:architecture"), check(`${prefix}registries`, "check:registries"), check(`${prefix}unit-integration`, "test:all"), check(`${prefix}coverage`, "test:coverage"), check(`${prefix}test-evidence-source`, "check:test-evidence:source"), check(`${prefix}ci-contract`, "check:ci"), check(`${prefix}home-smoke`, "exec", [ "vitest", "run", "tests/component/router.test.tsx", "--reporter=default", ]), check(`${prefix}build`, "build"), ]; const checks: RemovalCheck[] = [ outcome("common-test-evidence", missingCommonTests, "platform tests missing"), ...gateChecks(""), ]; const builtResidue: string[] = []; const buildSucceeded = checks.find(({ name }) => name === "build")?.passed === true; if (buildSucceeded) { for (const file of await filesBelow(path.join(fixtureRoot, "dist"))) { if (!/\.(?:js|css|html|json)$/.test(file)) continue; const content = await readFile(file, "utf8"); if (extras.residue.test(content)) { builtResidue.push(path.relative(fixtureRoot, file)); } } } const routeCatalog = await import( `${new URL( "../src/features/installed-feature-contracts.ts", `file://${fixtureRoot}/scripts/`, ).href}?removed=${Date.now()}` ) as { ROUTE_REGISTRY: Readonly> }; const routeIds = new Set(Object.keys(routeCatalog.ROUTE_REGISTRY)); checks.push( outcome( "route-absent", featureRouteIds.filter((routeId) => routeIds.has(routeId)), "routes still registered", ), outcome("fixture-id-residue", residue, "residue"), outcome("built-fixture-id-residue", builtResidue, "built residue"), ); // U7 (decision 4). The same copy, now without the sample, gets one feature // from create:feature and runs the same gates again: the command and the // feature it writes need nothing from the sample. if (isSample) { // 1103/09-06. With the write slice (NEVER), which needs nothing from // the sample either. const created = check("scaffold-create-feature", "create:feature", [ "scaffold-feature", "--with-create", ]); checks.push(created); if (created.passed) { sealRemovalFixtureRepository(fixtureRoot); checks.push(...gateChecks("scaffold-")); } } const failed = checks.filter((entry) => !entry.passed); await mkdir("artifacts/tests", { recursive: true }); await writeFile( isSample ? "artifacts/tests/sample-removal.xml" : `artifacts/tests/feature-removal-${featureId}.xml`, renderRemovalJunit(`${featureId}-removal`, checks), ); if (failed.length > 0) { process.stderr.write( `${featureId} removal failed:\n${failed .map((entry) => ` ${entry.name}: ${entry.failure ?? "failed"}`) .join("\n")}\n`, ); process.exitCode = 1; } else { process.stdout.write( `${featureId} removal: PASS (${checks.length} checks, no fixture IDs)\n`, ); } } finally { await rm(fixtureRoot, { recursive: true, force: true }); }