fix(features): make feature add and removal work from the feature directory (09-07, 14-03)

A feature directory without feature-module.ts vanished silently, registry
consumers listed only the sample's directories, and the removal gate only knew
the sample. The generator now fails unless a NOT_INSTALLED marker says so
(D-10), consumer directories are globs over every feature, and the removal
script takes --feature=<id>. starter-experience.md documents the current
ownership declarations and the files a new feature touches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 23:10:19 +09:00
co-authored by Claude Opus 5.5
parent 790f62ebb5
commit ad0e83c867
12 changed files with 327 additions and 99 deletions
+26 -1
View File
@@ -330,6 +330,27 @@ function projectSnapshotRows(
});
}
/**
* 09-07. `src/features/*\/adapters` names that directory in every feature, so
* adding a feature does not mean adding it to this governance file.
*/
async function expandDirectoryPattern(pattern: string): Promise<string[]> {
const star = pattern.split("/").indexOf("*");
if (star === -1) return [pattern];
const segments = pattern.split("/");
const parent = segments.slice(0, star).join("/");
const rest = segments.slice(star + 1).join("/");
const entries = await readdir(parent, { withFileTypes: true }).catch(() => []);
const expanded = await Promise.all(
entries
.filter((entry) => entry.isDirectory())
.map((entry) =>
expandDirectoryPattern(path.join(parent, entry.name, rest)),
),
);
return expanded.flat();
}
async function filesBelow(directory: string): Promise<string[]> {
try {
const entries = await readdir(directory, { withFileTypes: true });
@@ -548,7 +569,11 @@ for (const specification of governance.registries) {
if (specification.consumerIdentityField) {
const consumerFiles = (
await Promise.all(
(specification.consumerDirectories ?? []).map(filesBelow),
(await Promise.all(
(specification.consumerDirectories ?? []).map(expandDirectoryPattern),
))
.flat()
.map(filesBelow),
)
).flat();
const sourcePath = sourcesByRegistry.get(specification.registryId);
+22 -3
View File
@@ -105,7 +105,8 @@ export function renderContextIndex(entries: readonly FeatureIndexEntry[]): strin
}
/**
* Spec §3.2 / §5. Ownership declarations the generator reads. Each boundary
* Ownership declarations the generator reads, documented in
* docs/architecture/starter-experience.md ("Ownership declarations"). Each boundary
* declares only its parent:
*
* src/apps/<app>/app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS
@@ -258,9 +259,17 @@ function requiredInteger(source: string, name: string, file: string): number {
return parsed;
}
/**
* 09-07 (D-10). A feature directory must declare itself or say it is not
* installed. A missing or misspelt `feature-module.ts` used to drop the
* feature from the product without a word.
*/
export const NOT_INSTALLED_MARKER = "NOT_INSTALLED";
async function readDeclarations(
directory: string,
fileName: string,
requiredUnless?: string,
): Promise<readonly Readonly<{ directory: string; file: string; source: string }>[]> {
const found: { directory: string; file: string; source: string }[] = [];
let items;
@@ -275,7 +284,13 @@ async function readDeclarations(
try {
found.push({ directory: item.name, file, source: await readFile(file, "utf8") });
} catch {
continue;
if (requiredUnless === undefined) continue;
const marker = await readFile(resolve(directory, item.name, requiredUnless))
.then(() => true, () => false);
if (marker) continue;
throw new Error(
`src/features/${item.name} has no ${fileName}; add one or mark the directory with ${requiredUnless}`,
);
}
}
return found;
@@ -318,7 +333,11 @@ export async function createFileSystemDeclarationSource(
}
const featuresByContext = new Map<string, FeatureDeclaration[]>();
const featureIds = new Set<string>();
for (const declaration of await readDeclarations(resolve(root, "src/features"), "feature-module.ts")) {
for (const declaration of await readDeclarations(
resolve(root, "src/features"),
"feature-module.ts",
NOT_INSTALLED_MARKER,
)) {
const feature: FeatureDeclaration = {
id: requiredLiteral(declaration.source, "FEATURE_MODULE_ID", declaration.file),
contextId: requiredLiteral(declaration.source, "FEATURE_CONTEXT_ID", declaration.file),
+149 -65
View File
@@ -2,12 +2,15 @@ import {
access,
mkdir,
mkdtemp,
readdir,
readFile,
rm,
writeFile,
} from "node:fs/promises";
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 {
filesBelow,
@@ -19,14 +22,130 @@ import {
runRemovalFixturePnpm,
} from "./lib/removal-fixture.ts";
/**
* 09-07 (D-10). Removes one installed feature, `--feature=<id>` (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<Record<string, FeatureExtras>> = Object.freeze({
"reference-feature": Object.freeze({
paths: [
"tests/integration/http-scenario-catalog.test.ts",
"tests/component/product-feature-switch.test.tsx",
"tests/e2e/reference-form.spec.ts",
"tests/e2e/reference-route.spec.ts",
"tests/mocks",
"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",
"tests/fixtures/typecheck/tsconfig.feature-input.json",
"tests/fixtures/typecheck/tsconfig.reference-operation.json",
"tests/fixtures/typecheck/tsconfig.http-operation-input.json",
"tests/fixtures/typecheck/tsconfig.http-wire-mapper.json",
"tests/fixtures/typecheck/tsconfig.http-operation-id.json",
"tests/fixtures/typecheck/tsconfig.http-route-id.json",
"tests/fixtures/typecheck/tsconfig.feature-contribution-input.json",
"tests/fixtures/typecheck/tsconfig.feature-capability-selection.json",
],
ciScripts: [
"check:types:fixture:feature-input",
"check:types:fixture:reference-operation",
"check:types:fixture:http-operation-input",
"check:types:fixture:http-wire-mapper",
"check:types:fixture:http-operation-id",
"check:types:fixture:http-route-id",
"check:types:fixture:feature-contribution-input",
"check:types:fixture:feature-capability-selection",
"test:http-scenario-evidence",
"test:reference-feature",
],
evidencePathFragments: [
"reference-feature.xml",
"http-scenario-executions",
"http-scenario-evidence",
],
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 fixtureParent = path.resolve(".tmp");
await mkdir(fixtureParent, { recursive: true });
const fixtureRoot = await mkdtemp(
path.join(fixtureParent, "reference-feature-removal-"),
path.join(fixtureParent, `${featureId}-removal-`),
);
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
const featureSource = "src/features/reference-feature";
const featureTests = "tests/features/reference-feature";
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
@@ -41,29 +160,10 @@ const commonTestPaths = [
const featureOwnedPaths = [
featureSource,
featureTests,
// The sample's bounded-context declaration; the template app stays.
"src/contexts/reference-context",
"tests/integration/http-scenario-catalog.test.ts",
"tests/component/product-feature-switch.test.tsx",
"tests/e2e/reference-form.spec.ts",
"tests/e2e/reference-route.spec.ts",
"tests/mocks",
"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",
"tests/fixtures/typecheck/tsconfig.feature-input.json",
"tests/fixtures/typecheck/tsconfig.reference-operation.json",
"tests/fixtures/typecheck/tsconfig.http-operation-input.json",
"tests/fixtures/typecheck/tsconfig.http-wire-mapper.json",
"tests/fixtures/typecheck/tsconfig.http-operation-id.json",
"tests/fixtures/typecheck/tsconfig.http-route-id.json",
"tests/fixtures/typecheck/tsconfig.feature-contribution-input.json",
"tests/fixtures/typecheck/tsconfig.feature-capability-selection.json",
// 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 = {
@@ -152,7 +252,7 @@ try {
FEATURE_OVERRIDES?: Record<string, string>;
};
if (runtimeConfig.FEATURE_OVERRIDES) {
delete runtimeConfig.FEATURE_OVERRIDES["reference-feature"];
delete runtimeConfig.FEATURE_OVERRIDES[featureId];
}
await writeFile(
profilePath,
@@ -164,6 +264,7 @@ try {
(modulePolicy) => !modulePolicy.path?.startsWith(`${featureSource}/`),
);
if (
isSample &&
retainedCriticalModules.length === coveragePolicy.criticalModules.length
) {
throw new Error("Reference feature coverage policy is not registered");
@@ -202,12 +303,12 @@ try {
}
evidencePolicy[policyKey] = contributions.filter((candidate: unknown) => {
const contribution = candidate as EvidenceContribution;
const retained = contribution.owner !== "reference-feature";
const retained = contribution.owner !== featureId;
if (!retained) removedEvidenceContributions += 1;
return retained;
});
}
if (removedEvidenceContributions === 0) {
if (isSample && removedEvidenceContributions === 0) {
throw new Error("Reference feature test evidence policy is not registered");
}
await writeFile(
@@ -230,7 +331,7 @@ try {
consumers: registry.consumers.filter(
(candidate: unknown) => {
const consumer = candidate as GovernanceConsumer;
return !consumer.path?.includes("features/reference-feature");
return !consumer.path?.includes(featureSource);
},
),
}
@@ -240,7 +341,7 @@ try {
consumerDirectories: registry.consumerDirectories.filter(
(directory: unknown) =>
typeof directory !== "string" ||
!directory.includes("features/reference-feature"),
!directory.includes(featureSource),
),
}
: {}),
@@ -251,41 +352,28 @@ try {
`${JSON.stringify(removalGovernance, null, 2)}\n`,
);
const removedCiScripts = new Set([
"check:types:fixture:feature-input",
"check:types:fixture:reference-operation",
"check:types:fixture:http-operation-input",
"check:types:fixture:http-wire-mapper",
"check:types:fixture:http-operation-id",
"check:types:fixture:http-route-id",
"check:types:fixture:feature-contribution-input",
"check:types:fixture:feature-capability-selection",
"test:http-scenario-evidence",
"test:reference-feature",
]);
const removedCiScripts = new Set(extras.ciScripts);
const fixturePackagePath = path.join(fixtureRoot, "package.json");
const fixturePackage = JSON.parse(await readFile(fixturePackagePath, "utf8")) as {
scripts: Record<string, string>;
};
pruneScriptOrchestration(fixturePackage.scripts, "test:all", removedCiScripts);
delete fixturePackage.scripts["check:http-scenario-evidence"];
delete fixturePackage.scripts["check:http-scenario-evidence:fixture"];
if (isSample) {
delete fixturePackage.scripts["check:http-scenario-evidence"];
delete fixturePackage.scripts["check:http-scenario-evidence:fixture"];
}
await writeFile(fixturePackagePath, `${JSON.stringify(fixturePackage, null, 2)}\n`);
await pruneRemovalFixtureCiContract({
root: fixtureRoot,
removedScripts: removedCiScripts,
removedEvidencePathFragments: [
"reference-feature.xml",
"http-scenario-executions",
"http-scenario-evidence",
],
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: "reference feature removed",
REGISTRY_BASELINE_REASON: `${featureId} removed`,
})) {
throw new Error("Registry baseline failed to update after sample removal");
}
@@ -296,11 +384,7 @@ try {
for (const file of await filesBelow(path.join(fixtureRoot, root))) {
const relative = path.relative(fixtureRoot, file);
const content = await readFile(file, "utf8");
if (
/REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(
`${relative}\n${content}`,
)
) {
if (extras.residue.test(`${relative}\n${content}`)) {
residue.push(relative);
}
}
@@ -347,9 +431,7 @@ try {
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 (
/REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(content)
) {
if (extras.residue.test(content)) {
builtResidue.push(path.relative(fixtureRoot, file));
}
}
@@ -360,8 +442,8 @@ try {
`file://${fixtureRoot}/scripts/`,
).href}?removed=${Date.now()}`
) as { ROUTE_REGISTRY: Readonly<Record<string, unknown>> };
const routeIds = Object.keys(routeCatalog.ROUTE_REGISTRY);
const routeAbsent = routeIds.every((routeId) => !routeId.startsWith("REFERENCE_"));
const routeIds = new Set(Object.keys(routeCatalog.ROUTE_REGISTRY));
const routeAbsent = featureRouteIds.every((routeId) => !routeIds.has(routeId));
checks.push(["route-absent", routeAbsent]);
checks.push(["fixture-id-residue", residue.length === 0]);
checks.push(["built-fixture-id-residue", builtResidue.length === 0]);
@@ -369,9 +451,11 @@ try {
const passed = checks.every(([, result]) => result);
await mkdir("artifacts/tests", { recursive: true });
await writeFile(
"artifacts/tests/sample-removal.xml",
isSample
? "artifacts/tests/sample-removal.xml"
: `artifacts/tests/feature-removal-${featureId}.xml`,
`<?xml version="1.0" encoding="UTF-8"?>\n` +
`<testsuite name="reference-feature-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
`<testsuite name="${featureId}-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
checks
.map(
([name, result]) =>
@@ -385,12 +469,12 @@ try {
.filter(([, result]) => !result)
.map(([name]) => name);
process.stderr.write(
`Reference feature removal failed: ${failures.join(", ")}; residue: ${[...residue, ...builtResidue].join(", ")}\n`,
`${featureId} removal failed: ${failures.join(", ")}; residue: ${[...residue, ...builtResidue].join(", ")}\n`,
);
process.exitCode = 1;
} else {
process.stdout.write(
`Reference feature removal: PASS (${checks.length} checks, no fixture IDs)\n`,
`${featureId} removal: PASS (${checks.length} checks, no fixture IDs)\n`,
);
}
} finally {