Carries 359 template commits, tag v0.2.0 plus one documentation commit: the generator-built feature index with its app, bounded-context and feature declarations, the src/platform kernel and scale tooling, the 2026-09-24 src review fixes, and the 2026-09-25 maturity review round with its CHANGELOG [보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them merged with product changes; 127 are not carried. Product identity is unchanged: name, version 0.1.0, routes, design and the TechLog domain. Three decisions worth naming. TechLog stays composed directly, as the last two syncs recorded; its directory carries a NOT_INSTALLED marker that says so, and every installed-* composer takes the template's projection with TechLog added on top. The reference sample is no longer installed: the template now installs a feature only through feature-module.ts and context-routes.ts, which load the screens this product deleted, so its three operations, six schemas and one topic leave the registries, recorded as registry change evidence. And AppRouter mounts the platform and TechLog routes only; the template's bounded-context route gateway waits for a generator-installed feature. Required fixes: readSubject on the BFF session owner (without it every HTTP Studio session would close as integration-failed), zod through the facade in nine TechLog files, noUnusedLocals, and public/config.json written out to match the local profile. Derived baselines were recomputed after reproducing both sides' values: CI contract 101 commands / 106 references / 141 artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime config schema baseline equals the schema at8210d48. Verified here: types, lint, architecture, adapter inventory, CI contract, i18n, design system, diagnostics, browser security, dev release manifest, TechLog contract and build pass; 220 component, 155 integration, 15 contract, 418 TechLog, 43 reference-feature, 18 recipe and 46 release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at8210d48first and unchanged: check:registries (byte-identical), test:runtime-schema, verify:documentation. Brought by the template and escalated rather than suppressed: check:request-fanout on TechLog's cursor pagination, check:remediation-ledger (fails upstream too), the shared-chunk hash test, and the registry-dependent sample removal and second-feature tests. Playwright suites were not run. Full record, the five open questions and the follow-ups in docs/operations/template-sync-2026-09-29.md. (cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
428 lines
17 KiB
TypeScript
428 lines
17 KiB
TypeScript
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<string, FeatureIndexEntry[]>();
|
|
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>/app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS
|
|
* src/contexts/<context>/context-module.ts CONTEXT_MODULE_ID, CONTEXT_APP_ID,
|
|
* CONTEXT_ROUTE_PATH, CONTEXT_MAX_FEATURES
|
|
* src/features/<feature>/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=<id> 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<readonly Readonly<{ directory: string; file: string; source: string }>[]> {
|
|
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<TopologyDeclarationSource> {
|
|
const apps = new Map<string, AppDeclaration>();
|
|
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<string, ContextDeclaration[]>();
|
|
const contextIds = new Set<string>();
|
|
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<string, FeatureDeclaration[]>();
|
|
const featureIds = new Set<string>();
|
|
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<SelectedAppIndexes> {
|
|
const source = await createFileSystemDeclarationSource(root);
|
|
return selectAppIndexes(
|
|
source,
|
|
resolveSelectedApp(source, requestedApp),
|
|
productFeatures,
|
|
);
|
|
}
|
|
|
|
async function main(): Promise<void> {
|
|
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();
|
|
}
|