import { mkdir, readdir, readFile, writeFile } from "node:fs/promises"; import { dirname, relative, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { selectCompiledProductFeatures } from "../src/contracts/product-features.ts"; export type FeatureImportEntry = Readonly<{ id: string; importPath: string; }>; export type FeatureIndexEntry = FeatureImportEntry & Readonly<{ directory: string; contextId: string; contextRoutePath: string; contextMaxFeatures: number; }>; /** * `declaredIds` is every feature the app declares, selected or not, so a build * that left one out still reports it as `NOT_INSTALLED` without importing it. */ export function renderFeatureIndex( entries: readonly FeatureImportEntry[], declaredIds: readonly string[] = entries.map((entry) => entry.id), ): string { const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id)); const declared = [...declaredIds] .sort((left, right) => left.localeCompare(right)) .map((id) => JSON.stringify(id)) .join(", "); const imports = sorted .map( (entry, index) => `import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`, ) .join("\n"); const modules = sorted.map((_, index) => ` featureModule${index},`).join("\n"); const featureImports = imports.length > 0 ? `${imports}\n` : ""; return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport type { FeatureModule } from "../features/feature-module.ts";\n${featureImports}\nexport const DECLARED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze([${declared}]);\n\nexport const PRODUCT_FEATURE_MODULES = Object.freeze([\n${modules}\n] as const);\n\ntype GeneratedProductFeatureModule = (typeof PRODUCT_FEATURE_MODULES)[number];\nexport type ProductFeatureModule =\n [GeneratedProductFeatureModule] extends [never]\n ? FeatureModule\n : GeneratedProductFeatureModule;\n`; } export function renderContextIndex(entries: readonly FeatureIndexEntry[]): string { if (entries.length === 0) { return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([] as const);\n`; } const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id)); const imports = sorted .map( (entry, index) => `import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`, ) .join("\n"); const indexById = new Map(sorted.map((entry, index) => [entry.id, index] as const)); const grouped = new Map(); for (const entry of sorted) { const group = grouped.get(entry.contextId) ?? []; group.push(entry); grouped.set(entry.contextId, group); } const contexts = [...grouped.entries()] .sort(([left], [right]) => left.localeCompare(right)) .map(([contextId, features]) => { const first = features[0]; if (!first) throw new Error(`Context ${contextId} has no features`); for (const feature of features) { if (feature.contextRoutePath !== first.contextRoutePath) { throw new Error( `Context ${contextId} has conflicting route paths: ${first.contextRoutePath}, ${feature.contextRoutePath}`, ); } if (feature.contextMaxFeatures !== first.contextMaxFeatures) { throw new Error( `Context ${contextId} has conflicting maxFeatures budgets: ${first.contextMaxFeatures}, ${feature.contextMaxFeatures}`, ); } } if (features.length > first.contextMaxFeatures) { throw new Error( `Context ${contextId} feature cardinality ${features.length} exceeds budget ${first.contextMaxFeatures}`, ); } const featureRefs = features .map((feature) => `featureModule${indexById.get(feature.id)}`) .join(", "); const routeImports = features .map( (feature, index) => ` import(${JSON.stringify(`../features/${feature.directory}/context-routes.ts`)})${index < features.length - 1 ? "," : ""}`, ) .join("\n"); const routeSpreads = features .map((_, index) => ` ...routeModule${index}.FEATURE_CONTEXT_ROUTES,`) .join("\n"); const routeBindings = features .map((_, index) => `routeModule${index}`) .join(", "); return ` defineBoundedContextModule({\n id: ${JSON.stringify(contextId)},\n features: Object.freeze([${featureRefs}]),\n budget: Object.freeze({ maxFeatures: ${first.contextMaxFeatures} }),\n route: Object.freeze({\n path: ${JSON.stringify(first.contextRoutePath)},\n async loadRoutes() {\n const [${routeBindings}] = await Promise.all([\n${routeImports}\n ]);\n return Object.freeze([\n${routeSpreads}\n ]);\n },\n }),\n }),`; }) .join("\n"); const featureImports = imports.length > 0 ? `${imports}\n` : ""; return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport { defineBoundedContextModule } from "../contexts/bounded-context-module.ts";\n${featureImports}\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([\n${contexts}\n] as const);\n`; } /** * Ownership declarations the generator reads, documented in * docs/architecture/starter-experience.md ("Ownership declarations"). Each boundary * declares only its parent: * * src/apps//app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS * src/contexts//context-module.ts CONTEXT_MODULE_ID, CONTEXT_APP_ID, * CONTEXT_ROUTE_PATH, CONTEXT_MAX_FEATURES * src/features//feature-module.ts FEATURE_MODULE_ID, FEATURE_CONTEXT_ID * * The generated indexes describe exactly one deployable app: the contexts it * owns and the features those contexts own. Features of other apps are never * imported, so global growth elsewhere cannot enter this app's compile or * boot graph. */ export type AppDeclaration = Readonly<{ id: string; maxContexts: number }>; export type ContextDeclaration = Readonly<{ id: string; appId: string; routePath: string; maxFeatures: number; }>; export type FeatureDeclaration = Readonly<{ id: string; contextId: string; directory: string; }>; /** * Ownership-indexed view of the declarations. The generator only asks for one * app, that app's contexts and those contexts' features, so its work and its * output are local to the selected app. */ export interface TopologyDeclarationSource { appIds(): readonly string[]; app(appId: string): AppDeclaration | undefined; contextsOf(appId: string): readonly ContextDeclaration[]; featuresOf(contextId: string): readonly FeatureDeclaration[]; } export type SelectedAppIndexes = Readonly<{ app: AppDeclaration; entries: readonly FeatureIndexEntry[]; featureIndex: string; contextIndex: string; appIndex: string; }>; export function renderAppIndex(app: AppDeclaration): string { return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand. export const PRODUCT_APP = Object.freeze({ id: ${JSON.stringify(app.id)}, maxContexts: ${app.maxContexts}, } as const); `; } export function resolveSelectedApp( source: TopologyDeclarationSource, requested: string | undefined, ): string { if (requested) { if (!source.app(requested)) throw new Error(`Unknown deployable app: ${requested}`); return requested; } const ids = source.appIds(); if (ids.length !== 1) { throw new Error( `Select a deployable app with --app= or PRODUCT_APP_ID (declared: ${ids.join(", ") || "none"})`, ); } return ids[0] as string; } /** * The production selection: one app -> its direct contexts -> their features, * narrowed by `VITE_PRODUCT_FEATURES` (09-02, D-9). The narrowing happens here * so the bundle, the Node build scripts and the context router all import the * same set, and a misspelt id fails the first build step. */ export function selectAppIndexes( source: TopologyDeclarationSource, appId: string, productFeatures?: string, ): SelectedAppIndexes { const app = source.app(appId); if (!app) throw new Error(`Unknown deployable app: ${appId}`); const contexts = [...source.contextsOf(appId)].sort((left, right) => left.id.localeCompare(right.id), ); const entries: FeatureIndexEntry[] = []; let populatedContexts = 0; for (const context of contexts) { const features = source.featuresOf(context.id); if (features.length === 0) continue; populatedContexts += 1; if (features.length > context.maxFeatures) { throw new Error( `Context ${context.id} feature cardinality ${features.length} exceeds budget ${context.maxFeatures}`, ); } for (const feature of features) { entries.push({ id: feature.id, importPath: `../features/${feature.directory}/feature-module.ts`, directory: feature.directory, contextId: context.id, contextRoutePath: context.routePath, contextMaxFeatures: context.maxFeatures, }); } } if (populatedContexts > app.maxContexts) { throw new Error( `App ${app.id} context cardinality ${populatedContexts} exceeds budget ${app.maxContexts}`, ); } const ids = entries.map((entry) => entry.id); if (new Set(ids).size !== ids.length) { throw new Error(`Duplicate generated feature ids: ${ids.join(", ")}`); } const selected = selectCompiledProductFeatures( entries.map((entry) => Object.freeze({ featureId: entry.id, entry })), productFeatures, ).map(({ entry }) => entry); return Object.freeze({ app, entries: Object.freeze(selected), featureIndex: renderFeatureIndex(selected, ids), contextIndex: renderContextIndex(selected), appIndex: renderAppIndex(app), }); } function requiredLiteral(source: string, name: string, file: string): string { const match = source.match( new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']([^"']+)["']`), ); if (!match?.[1]) { throw new Error(`${file} must export a literal ${name}`); } return match[1]; } function requiredInteger(source: string, name: string, file: string): number { const match = source.match( new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(\\d+)`), ); const parsed = match?.[1] ? Number.parseInt(match[1], 10) : Number.NaN; if (!Number.isSafeInteger(parsed) || parsed < 1) { throw new Error(`${file} must export a positive integer ${name}`); } 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[]> { const found: { directory: string; file: string; source: string }[] = []; let items; try { items = await readdir(directory, { withFileTypes: true }); } catch { return found; } for (const item of items) { if (!item.isDirectory()) continue; const file = resolve(directory, item.name, fileName); try { found.push({ directory: item.name, file, source: await readFile(file, "utf8") }); } catch { 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; } /** * Filesystem declaration source. Declarations are small literal headers, so * reading them is a metadata scan; only the selected app's features are ever * imported by the generated output. */ export async function createFileSystemDeclarationSource( root: string, ): Promise { const apps = new Map(); for (const declaration of await readDeclarations(resolve(root, "src/apps"), "app-module.ts")) { const id = requiredLiteral(declaration.source, "APP_MODULE_ID", declaration.file); if (apps.has(id)) throw new Error(`Duplicate app id: ${id}`); apps.set(id, { id, maxContexts: requiredInteger(declaration.source, "APP_MAX_CONTEXTS", declaration.file), }); } const contextsByApp = new Map(); const contextIds = new Set(); for (const declaration of await readDeclarations(resolve(root, "src/contexts"), "context-module.ts")) { const context: ContextDeclaration = { id: requiredLiteral(declaration.source, "CONTEXT_MODULE_ID", declaration.file), appId: requiredLiteral(declaration.source, "CONTEXT_APP_ID", declaration.file), routePath: requiredLiteral(declaration.source, "CONTEXT_ROUTE_PATH", declaration.file), maxFeatures: requiredInteger(declaration.source, "CONTEXT_MAX_FEATURES", declaration.file), }; if (contextIds.has(context.id)) throw new Error(`Duplicate context id: ${context.id}`); if (!apps.has(context.appId)) { throw new Error(`Context ${context.id} belongs to undeclared app ${context.appId}`); } contextIds.add(context.id); const owned = contextsByApp.get(context.appId) ?? []; owned.push(context); contextsByApp.set(context.appId, owned); } const featuresByContext = new Map(); const featureIds = new Set(); 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), directory: declaration.directory, }; if (featureIds.has(feature.id)) throw new Error(`Duplicate generated feature ids: ${feature.id}`); if (!contextIds.has(feature.contextId)) { throw new Error(`Feature ${feature.id} belongs to undeclared context ${feature.contextId}`); } featureIds.add(feature.id); const owned = featuresByContext.get(feature.contextId) ?? []; owned.push(feature); featuresByContext.set(feature.contextId, owned); } return Object.freeze({ appIds: () => [...apps.keys()].sort(), app: (appId: string) => apps.get(appId), contextsOf: (appId: string) => contextsByApp.get(appId) ?? [], featuresOf: (contextId: string) => featuresByContext.get(contextId) ?? [], }); } export async function generateAppIndexes( root: string, requestedApp: string | undefined, productFeatures?: string, ): Promise { const source = await createFileSystemDeclarationSource(root); return selectAppIndexes( source, resolveSelectedApp(source, requestedApp), productFeatures, ); } async function main(): Promise { const scriptDir = dirname(fileURLToPath(import.meta.url)); // `--root=` points the same production command at another checkout (used by // the multi-app topology evidence); the default is this repository. const rootArgument = process.argv .find((argument) => argument.startsWith("--root=")) ?.slice("--root=".length); const root = rootArgument ? resolve(rootArgument) : resolve(scriptDir, ".."); const outputRoot = resolve(root, "src/.generated"); const outputs = { feature: resolve(outputRoot, "product-feature-index.ts"), context: resolve(outputRoot, "product-context-index.ts"), app: resolve(outputRoot, "product-app.ts"), }; const requestedApp = process.argv.find((argument) => argument.startsWith("--app="))?.slice("--app=".length) || process.env["PRODUCT_APP_ID"] || undefined; const selected = await generateAppIndexes( root, requestedApp, process.env["VITE_PRODUCT_FEATURES"], ); const rendered = { feature: selected.featureIndex, context: selected.contextIndex, app: selected.appIndex, }; await mkdir(outputRoot, { recursive: true }); if (process.argv.includes("--check")) { const stale: string[] = []; for (const key of ["feature", "context", "app"] as const) { const current = await readFile(outputs[key], "utf8").catch(() => ""); if (current !== rendered[key]) stale.push(relative(root, outputs[key])); } if (stale.length > 0) { throw new Error(`Generated topology index is stale: ${stale.join(", ")}`); } return; } await Promise.all( (["feature", "context", "app"] as const).map((key) => writeFile(outputs[key], rendered[key], "utf8"), ), ); } if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { await main(); }