규모 측정(S4 3.1절 S-6)은 참조 기능을 복사해 이름을 바꿔 잰다. create:feature의 planFeature로 사본마다 --with-create --keyed 기능 파일을 만든다(자기 계약 패키지와 topic, context당 200개). 초기 JS 기록에 firstFeatureGzipBytes를 더하고, context 비용은 둘째 기능을 새 context에 둘 때와 같은 context에 둘 때의 차이로 잰다. 옛 정의는 기능이 없는 템플릿에서 첫 기능의 공용 코드까지 context 비용으로 세어 5,788B로 상한 512B를 넘었다. 몇 바이트짜리 비용에는 기록 허용치 하한 16B를 둔다(빌드 ID에 따라 gzip이 1~2B 흔들린다). 이 트리(샘플이 아직 있는 상태)의 기록: 204,266B, 27파일, 첫 기능 797B, 기능 521B, context 12B. 위험: 성장 기준선(0·25·100개)은 샘플을 지운 트리에서 뒤 커밋이 다시 잰다. 이 커밋의 기준선 파일은 아직 참조 사본으로 잰 값이다. 검증(desktop): feature-shape-growth 등 4파일 57 passed, test:unit 통과.
442 lines
19 KiB
TypeScript
442 lines
19 KiB
TypeScript
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 <id> --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/<id>`, 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<string, string> {
|
|
const files = new Map<string, string>();
|
|
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<string> {
|
|
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<Readonly<{ gzipBytes: number; files: number }>> {
|
|
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<InitialJavascriptCosts> {
|
|
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<Record<keyof InitialJavascriptCosts, number>> = {
|
|
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<void> {
|
|
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<string, unknown>;
|
|
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<void> {
|
|
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();
|
|
}
|