import { spawnSync } from "node:child_process"; import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { availableParallelism, cpus, loadavg, tmpdir } from "node:os"; import path from "node:path"; import { pathToFileURL } from "node:url"; import { gzipSync } from "node:zlib"; import { PLATFORM_ROUTE_REGISTRY } from "../../src/contracts/routes.ts"; import { planFeature, type InstalledFacts } from "../create-feature.ts"; import { classifyViteJavascript } from "../lib/classify-vite-bundle.ts"; import { linkFixtureNodeModules } from "../lib/fixture-node-modules.ts"; import { VITE_BUILD_INPUTS } from "../lib/vite-build-inputs.ts"; import { parseTscExtendedDiagnostics, type TscDiagnostics } from "./collect-tsc-diagnostics.ts"; /** * 11-04 (D-18). Cost of one app as its feature count grows, measured with * features shaped like a real one: N copies of the feature `create:feature` * writes with `--with-create --keyed` (a list, a detail and a create with its * form), each planned by the command's own planner (`planFeature`) with its * own ids and its own pinned contract package. The copies live in contexts of * their own, 200 features each (the context ceiling the baseline records). * 2026-11-07: the copies were the template's reference sample, renamed; the * template ships no sample now. * * For each N the script runs the product generator, `tsc --extendedDiagnostics` * over tsconfig.app.json and `vite build`, and records compiler counts, wall * times and initial/lazy JavaScript gzip bytes. Deterministic counts repeat * exactly; times depend on the host, so the CPU and load average are recorded * next to them. A typecheck that fails (for example TS2590, a union too complex * to represent) is recorded as a result with its first error. * * node scripts/scale/measure-feature-shape-growth.ts [--sizes=0,25,100] [--repeats=2] [--write] * node scripts/scale/measure-feature-shape-growth.ts --initial-baseline [--write] * * `--write` stores the result as config/scale/feature-shape-growth.json, or * with `--initial-baseline` the initial JavaScript record in * config/scale/feature-shape-ceilings.json. */ export const FEATURE_SHAPE_BASELINE_PATH = "config/scale/feature-shape-growth.json"; /** What the declared ceilings rest on, derived by hand from the baseline. */ export const FEATURE_SHAPE_CEILINGS_PATH = "config/scale/feature-shape-ceilings.json"; /** The command each copy is, as the baseline records it. */ export const SHAPE_FEATURE_COMMAND = "create:feature --with-create --keyed"; export const FEATURES_PER_CONTEXT = 200; /** Copy `index`: its feature id and the context it lands in. */ export function shapeFeature(index: number, featuresPerContext = FEATURES_PER_CONTEXT) { const contextNumber = Math.floor(index / featuresPerContext); return Object.freeze({ id: `s${String(index).padStart(3, "0")}-feature`, context: Object.freeze({ id: `shape-context-${contextNumber}`, routeRoot: `shape-${contextNumber}` }), }); } function contextModule(context: Readonly<{ id: string; routeRoot: string }>): string { return ( `export const CONTEXT_MODULE_ID = "${context.id}";\n` + `export const CONTEXT_APP_ID = "template-app";\n` + `export const CONTEXT_ROUTE_PATH = "${context.routeRoot}/*";\n` + `export const CONTEXT_MAX_FEATURES = ${FEATURES_PER_CONTEXT};\n` ); } /** * The source files of `features` copies: the context declarations and what * `create:feature` writes under src/features (its tests and accessibility * records are not part of a build). Each copy pins `@feature-shape/`, as * a product feature pins its published package, and gets a topic of its own. */ export function planShapeFeatures( features: number, featuresPerContext = FEATURES_PER_CONTEXT, ): ReadonlyMap { const files = new Map(); const contexts: { id: string; routePath: string }[] = []; const routes: InstalledFacts["routes"][number][] = Object.values(PLATFORM_ROUTE_REGISTRY).map( (route) => ({ routeId: route.routeId, path: route.path, chunkId: route.chunkId, navigationOrder: route.navigationOrder, }), ); const featureIds: string[] = []; const topics: string[] = []; for (let index = 0; index < features; index += 1) { const { id, context } = shapeFeature(index, featuresPerContext); if (index % featuresPerContext === 0) { contexts.push({ id: context.id, routePath: `${context.routeRoot}/*` }); files.set(`src/contexts/${context.id}/context-module.ts`, contextModule(context)); } const navigationOrder = Math.max(0, ...routes.flatMap((route) => (route.navigationOrder === null ? [] : [route.navigationOrder]))) + 10; const plan = planFeature( { id, context: context.id, write: "KEYED", contractPackage: { packageId: `@feature-shape/${id}`, version: "1.0.0", digest: `sha256:${"0".repeat(64)}`, sourceRevision: "0000000", }, }, { appIds: ["template-app"], featureIds, contexts, contextDirectories: contexts.map((declared) => declared.id), routes, topics, messageKeys: [], }, () => String(index).padStart(26, "0"), ); for (const [file, content] of plan.files) { if (file.startsWith("src/")) files.set(file, content); } featureIds.push(id); topics.push(plan.topic); for (const route of plan.routes) { routes.push({ routeId: route.routeId, path: route.path, chunkId: `${route.routeId}-chunk`, navigationOrder: route.routeId === plan.routeId ? navigationOrder : null, }); } } return files; } async function createFixture( features: number, featuresPerContext = FEATURES_PER_CONTEXT, ): Promise { const root = await mkdtemp(path.join(tmpdir(), `feature-shape-${features}-`)); for (const input of VITE_BUILD_INPUTS) { await mkdir(path.dirname(path.join(root, input)), { recursive: true }); await cp(path.resolve(input), path.join(root, input), { recursive: true }); } await rm(path.join(root, "src/.generated"), { recursive: true, force: true }); await linkFixtureNodeModules(root); for (const [file, content] of planShapeFeatures(features, featuresPerContext)) { await mkdir(path.dirname(path.join(root, file)), { recursive: true }); await writeFile(path.join(root, file), content); } return root; } function run( command: string, args: readonly string[], cwd: string, options: Readonly<{ allowFailure?: boolean }> = {}, ) { // 1103/15-02. Vitest sets NODE_ENV=test, and a vite build that inherits it // bundles React's development build: the unit test measured 264 KB where // the production build is 201 KB. Every command here measures production. const { NODE_ENV: _inherited, ...environment } = process.env; const started = performance.now(); const result = spawnSync(command, args, { cwd, encoding: "utf8", env: environment, maxBuffer: 64 * 1024 * 1024, }); const ms = Math.round(performance.now() - started); if (result.status !== 0 && !(options.allowFailure && result.stdout.includes("Instantiations:"))) { throw new Error( `${path.basename(command)} ${args.join(" ")} failed in ${cwd}:\n${(result.stdout + result.stderr).slice(0, 4_000)}`, ); } return { ms, passed: result.status === 0, stdout: result.stdout }; } const load = () => loadavg().map((value) => Math.round(value * 100) / 100); async function javascriptGzipBytes(root: string, files: readonly string[]) { let bytes = 0; for (const file of files) bytes += gzipSync(await readFile(path.join(root, "dist", file))).byteLength; return bytes; } /** * 15-01. Initial JavaScript of the app with `features` copies added: the generator and `vite build` only, no typecheck. The unit suite * (merge stage) bounds what one more feature adds to the initial chunk with * it, so the growth is caught on the PR instead of at the next release. */ async function measureInitialJavascript( features: number, featuresPerContext = FEATURES_PER_CONTEXT, ): Promise> { const root = await createFixture(features, featuresPerContext); try { run(process.execPath, [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], root); run(path.resolve("node_modules/.bin/vite"), ["build", "--logLevel", "error"], root); const manifest = JSON.parse(await readFile(path.join(root, "dist/.vite/manifest.json"), "utf8")); const { initialFiles } = classifyViteJavascript(manifest); return { gzipBytes: await javascriptGzipBytes(root, initialFiles), files: initialFiles.length }; } finally { await rm(root, { recursive: true, force: true }); } } /** * 1103/15-02, 15-04. The template's initial JavaScript and what features add * to it. Two copies in one context against one copy are one more feature * alone; the same two copies in two contexts against that are one more * context. 2026-11-07: the template has no feature, so the first copy also * brings the code every feature shares into the initial chunks; that is * `firstFeatureGzipBytes`, paid once. `initialJavascript` in * config/scale/feature-shape-ceilings.json records these numbers; * tests/unit/feature-shape-growth.test.ts compares them with the build on * every unit run. */ export type InitialJavascriptCosts = Readonly<{ gzipBytes: number; files: number; firstFeatureGzipBytes: number; perFeatureGzipBytes: number; perContextGzipBytes: number; }>; export async function measureInitialJavascriptCosts(): Promise { const none = await measureInitialJavascript(0); const one = await measureInitialJavascript(1); const twoInOneContext = await measureInitialJavascript(2); const twoInTwoContexts = await measureInitialJavascript(2, 1); return { gzipBytes: none.gzipBytes, files: none.files, firstFeatureGzipBytes: one.gzipBytes - none.gzipBytes, perFeatureGzipBytes: twoInOneContext.gzipBytes - one.gzipBytes, perContextGzipBytes: twoInTwoContexts.gzipBytes - twoInOneContext.gzipBytes, }; } /** * 1105/15-02. How far the total may be from the record, in gzip bytes. The * total moves by tens of bytes with the build id (CI and local builds * differ: 6 B and 48 B between recorded runs), so it cannot be exact. It * used to be 1% of the total, 2,029 B, which is more than the room left * under the budget (1,873 B at 8a44226) and more than one feature (768 B): * the record and the documents that cite it could claim room that was * gone. 256 B is above the build id spread and below one feature. */ export const INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES = 256; /** * Fields of the record that no longer describe the build. The total may be * INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES off; the first-feature, * per-feature and per-context costs are differences of builds with the same * id, so 10%, and at least COST_RECORD_TOLERANCE_BYTES: a context costs a few * bytes now, and gzip moves a difference that small by a byte or two when * the build id changes. The file count is exact. */ export const COST_RECORD_TOLERANCE_BYTES = 16; function costTolerance(bytes: number): number { return Math.max(Math.abs(bytes) * 0.1, COST_RECORD_TOLERANCE_BYTES); } export function initialJavascriptRecordDrift( measured: InitialJavascriptCosts, record: InitialJavascriptCosts, ): string[] { const allowed: Readonly> = { gzipBytes: INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES, files: 0, firstFeatureGzipBytes: costTolerance(measured.firstFeatureGzipBytes), perFeatureGzipBytes: costTolerance(measured.perFeatureGzipBytes), perContextGzipBytes: costTolerance(measured.perContextGzipBytes), }; return (Object.keys(allowed) as (keyof InitialJavascriptCosts)[]) .filter((field) => Math.abs(record[field] - measured[field]) > allowed[field]) .map((field) => `${field}: record ${record[field]}, build ${measured[field]}`); } async function measureOnce(root: string, features: number) { const loadBefore = load(); run(process.execPath, [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], root); // The composed registries throw at module evaluation on a duplicate route, // operation, schema, namespace or message key: prove the copies compose. const contracts = (await import( `${pathToFileURL(path.join(root, "src/features/installed-feature-contracts.ts")).href}?features=${features}` )) as typeof import("../../src/features/installed-feature-contracts.ts"); // 15-01. Operations, schemas and contract contributions compose from the // runtime halves, which only this module loads. await import( `${pathToFileURL(path.join(root, "src/features/loaded-feature-runtimes.ts")).href}?features=${features}` ); const routes = Object.keys(contracts.ROUTE_REGISTRY).length; const tsc = run( path.resolve("node_modules/.bin/tsc"), ["--project", path.join(root, "tsconfig.app.json"), "--noEmit", "--extendedDiagnostics"], root, // A type error is a result here (the typecheck stops scaling), not a crash. { allowFailure: true }, ); await rm(path.join(root, "dist"), { recursive: true, force: true }); const build = run(path.resolve("node_modules/.bin/vite"), ["build", "--logLevel", "error"], root); const manifest = JSON.parse(await readFile(path.join(root, "dist/.vite/manifest.json"), "utf8")); const javascript = classifyViteJavascript(manifest); const diagnostics: TscDiagnostics = parseTscExtendedDiagnostics(tsc.stdout); return { addedFeatures: features, routes, tsc: { passed: tsc.passed, firstError: tsc.stdout.split("\n").find((line) => line.includes("error TS")) ?? null, files: diagnostics.files, types: diagnostics.types, symbols: diagnostics.symbols, instantiations: diagnostics.instantiations, memoryKb: diagnostics.memoryKb ?? null, wallMs: tsc.ms, }, build: { wallMs: build.ms, initialJavascriptFiles: javascript.initialFiles.length, initialJavascriptGzipBytes: await javascriptGzipBytes(root, javascript.initialFiles), lazyJavascriptFiles: javascript.lazyFiles.length, lazyJavascriptGzipBytes: await javascriptGzipBytes(root, javascript.lazyFiles), }, loadBefore, loadAfter: load(), }; } /** * 11-05 (2026-09-29). The commit the run measured, so a later run can be * compared with the same code and a reader can tell whether the baseline * still describes the tree. Tracked files that differed from that commit are * listed; an empty list means the commit alone reproduces the run. */ function sourceRevision(): Readonly<{ commit: string; modifiedPaths: string[] }> { const git = (...args: string[]) => spawnSync("git", args, { encoding: "utf8" }); const head = git("rev-parse", "HEAD"); const status = git("status", "--porcelain", "--untracked-files=no"); if (head.status !== 0 || status.status !== 0) { throw new Error("feature-shape growth: cannot read the source commit (git rev-parse HEAD, git status)"); } return { commit: head.stdout.trim(), modifiedPaths: status.stdout .split("\n") .filter(Boolean) .map((line) => line.slice(3)), }; } function version(bin: string): string { const result = spawnSync(path.resolve("node_modules/.bin", bin), ["--version"], { encoding: "utf8" }); return (result.stdout ?? "").trim(); } /** * 1103/15-02. `--initial-baseline` measures the record the documents cite and, * with `--write`, stores it as `initialJavascript` in * config/scale/feature-shape-ceilings.json. Run it in the change that moves * the initial JavaScript. */ async function writeInitialBaseline(): Promise { const measured = await measureInitialJavascriptCosts(); process.stdout.write(`initial JavaScript: ${JSON.stringify(measured)}\n`); if (!process.argv.includes("--write")) return; const ceilings = JSON.parse(await readFile(FEATURE_SHAPE_CEILINGS_PATH, "utf8")) as Record; ceilings["initialJavascript"] = measured; await writeFile(FEATURE_SHAPE_CEILINGS_PATH, `${JSON.stringify(ceilings, null, 2)}\n`); process.stdout.write(`feature-shape initial baseline: ${FEATURE_SHAPE_CEILINGS_PATH}\n`); } async function main(): Promise { if (process.argv.includes("--initial-baseline")) { await writeInitialBaseline(); return; } const argument = (name: string) => process.argv.find((entry) => entry.startsWith(`--${name}=`))?.slice(name.length + 3); const sizes = (argument("sizes") ?? "0,25,100").split(",").map(Number); const repeats = Number(argument("repeats") ?? "2"); if (!sizes.every((size) => Number.isSafeInteger(size) && size >= 0) || !(repeats >= 1)) { throw new TypeError("--sizes must be nonnegative integers and --repeats at least 1"); } // Read before measuring: the run takes minutes and the tree may move. const source = sourceRevision(); const runs = []; for (const features of sizes) { const root = await createFixture(features); try { for (let repeat = 1; repeat <= repeats; repeat += 1) { const measured = await measureOnce(root, features); runs.push({ repeat, ...measured }); process.stdout.write( `features +${features} (repeat ${repeat}): routes=${measured.routes} ` + `instantiations=${measured.tsc.instantiations} tsc=${measured.tsc.wallMs}ms ` + `build=${measured.build.wallMs}ms initial=${measured.build.initialJavascriptGzipBytes}B ` + `lazy=${measured.build.lazyJavascriptGzipBytes}B load=${measured.loadBefore.join("/")}` + `${measured.tsc.passed ? "" : ` typecheck FAILED: ${measured.tsc.firstError}`}\n`, ); // Compiler results repeat exactly; a failed typecheck costs minutes and // gigabytes again for no new information. if (!measured.tsc.passed) break; } } finally { await rm(root, { recursive: true, force: true }); } } const cpu = cpus(); const result = { schemaVersion: 1, measuredAt: new Date().toISOString(), command: `node scripts/scale/measure-feature-shape-growth.ts --sizes=${sizes.join(",")} --repeats=${repeats}`, environment: { node: process.versions.node, platform: process.platform, arch: process.arch, cpuModel: cpu[0]?.model.trim() ?? "unknown", logicalCpus: cpu.length, availableParallelism: availableParallelism(), typescript: version("tsc"), vite: version("vite"), }, source, sourceFeature: SHAPE_FEATURE_COMMAND, runs, }; const output = process.argv.includes("--write") ? FEATURE_SHAPE_BASELINE_PATH : "artifacts/scale/feature-shape-growth.json"; await mkdir(path.dirname(output), { recursive: true }); await writeFile(output, `${JSON.stringify(result, null, 2)}\n`); process.stdout.write(`feature-shape growth: ${output}\n`); } if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) { await main(); }