Files
clean-architecture-frontend…/scripts/generate-product-feature-index.ts
T
DongHyeonka ddbda4d21e fix(feature-index): 바뀌지 않은 기능 인덱스는 다시 쓰지 않는다
문제: 빌드, dev 서버, 타입 검사, vitest가 모두 시작할 때
`scripts/generate-product-feature-index.ts`로 `src/.generated/*.ts`를
다시 쓴다. 생성기는 `writeFile`로 파일을 제자리에서 비우고 다시 썼다.
한 checkout에서 두 실행이 겹치면, 한쪽이 파일을 비운 순간 다른 쪽의
Vite나 tsc가 빈 파일이나 반쯤 쓴 파일을 읽을 수 있다(1105/12-04의
"한 checkout 두 실행" 중 공유 소스 파일 부분).

고른 방법: 내용이 같으면 쓰지 않는다. 다르면 같은 폴더의 임시 파일에
쓰고 rename으로 바꾼다. 읽는 쪽은 옛 파일이나 새 파일 하나만 본다.
같은 선택(같은 PRODUCT_APP_ID·VITE_PRODUCT_FEATURES)으로 도는 두 실행은
아예 쓰지 않는다.
버린 대안: 실행마다 `src/.generated`를 따로 두기. 앱 소스가 이 경로를
import하므로 경로를 바꾸면 Vite·tsc·ESLint 설정이 모두 따라 바뀐다.
잠금 파일: 겹친 실행을 직렬로 만들 뿐이고, 죽은 프로세스가 잠금을
남긴다.

위험·한계: 선택이 서로 다른 두 실행(예: 한쪽만 VITE_PRODUCT_FEATURES=none)은
여전히 서로의 인덱스를 바꾼다. 그건 실행이 아니라 checkout 상태가 다른
것이라 이 커밋 범위 밖이다. 임시 파일은 `.tmp`로 끝나 tsc·Vite·ESLint
대상이 아니다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/product-feature-index-write.test.ts

Refs: 1105/12-04
2026-11-05 22:12:33 +09:00

480 lines
19 KiB
TypeScript

import { randomUUID } from "node:crypto";
import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
import { basename, dirname, join, 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;
/** 09-03. Present when the context has a `context-layout.tsx`. */
contextLayoutImportPath?: string;
}>;
/**
* `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(", ");
const layout = first.contextLayoutImportPath
? ` loadLayout: async () => (await import(${JSON.stringify(first.contextLayoutImportPath)})).CONTEXT_LAYOUT,\n`
: "";
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${layout} 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/contexts/<context>/context-layout.tsx CONTEXT_LAYOUT (optional, 09-03:
* the context's own layout)
* 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;
layoutImportPath?: string;
}>;
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,
...(context.layoutImportPath
? { contextLayoutImportPath: context.layoutImportPath }
: {}),
});
}
}
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 a
* feature. A missing or misspelt `feature-module.ts` used to drop the
* feature from the product without a word.
*
* 1103/09-09. The marker was named `NOT_INSTALLED`, the runtime state of a
* declared feature the build or the runtime document left out
* (`src/contracts/product-features.ts`). It marks something else, a directory
* that is no feature at all (an architecture sample), so it has its own name,
* and a directory may not carry both the marker and a declaration.
*/
export const NOT_A_FEATURE_MARKER = "NOT_A_FEATURE";
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);
const marker =
requiredUnless !== undefined &&
(await readFile(resolve(directory, item.name, requiredUnless)).then(
() => true,
() => false,
));
let source: string;
try {
source = await readFile(file, "utf8");
} catch {
if (requiredUnless === undefined || marker) continue;
throw new Error(
`src/features/${item.name} has no ${fileName}; add one or mark the directory with ${requiredUnless}`,
);
}
if (marker) {
throw new Error(
`src/features/${item.name} has both ${fileName} and ${requiredUnless}; delete ${requiredUnless} to install it, or ${fileName} to keep it out`,
);
}
found.push({ directory: item.name, file, source });
}
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")) {
let 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),
};
const layout = `${declaration.directory}/context-layout.tsx`;
if (await readFile(resolve(root, "src/contexts", layout)).then(() => true, () => false)) {
context = { ...context, layoutImportPath: `../contexts/${layout}` };
}
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_A_FEATURE_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,
);
}
/**
* 1105/12-04. Every build, dev server, type check and test run renders these
* files first, so two runs in one checkout render them at the same time while
* the other run's Vite or tsc reads them. `writeFile` truncated the file in
* place, and a reader could see it empty or half written. An index that has
* not changed is left alone; a changed one replaces the old file with one
* rename, so a reader sees the old file or the new one, never a part.
*/
export async function writeIndexIfChanged(file: string, content: string): Promise<void> {
if ((await readFile(file, "utf8").catch(() => null)) === content) return;
const temporary = join(dirname(file), `.${basename(file)}.${randomUUID()}.tmp`);
try {
await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
await rename(temporary, file);
} catch (error) {
await rm(temporary, { force: true });
throw error;
}
}
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) =>
writeIndexIfChanged(outputs[key], rendered[key]),
),
);
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
await main();
}