test(scale): 기능·context 비용을 따로 재고 초기 JS 기준선을 빌드와 대조한다

문제: (1) 기능당 1 KiB 상한 테스트는 복사본 0개와 1개만 쟀다. 첫
복사본은 새 context(shape-context-0)도 만들어서, 잰 값에 context 비용이
섞였고 상한까지 40 B만 남았다. 넘으면 기능이 커졌는지 context가
비싸졌는지 알 수 없었다. (2) 성능 기준선 숫자는 performance-evidence.md,
static-delivery.md, feature-shape-ceilings.json에 손으로 적혀 있었고
현재 빌드와도, 같은 파일 안에서도 서로 달랐다(1101/15-02 재발).
(3) 이 테스트는 vitest 안에서 돌아 NODE_ENV=test를 물려받았다. 그래서
픽스처 vite build가 React 개발 빌드를 묶었고, 잰 합계가 운영 빌드
(약 201 KB)가 아니라 약 264 KB였다.

고른 방법: 복사본 0·1·2개를 잰다. 둘째 복사본은 같은 context에 들어가
기능 하나의 비용이고, 첫 복사본에서 그것을 뺀 나머지가 context 하나의
비용이다. 기능은 1 KiB, context는 512 B로 따로 막고 실패 메시지에 잰
값을 넣는다. 기준선은 feature-shape-ceilings.json의 initialJavascript
한 곳에 기계가 읽는 칸으로 두고, 같은 테스트가 빌드와 대조한다(합계
1%, 파일 수 정확히, 기능·context 비용 10%). 기록은
`measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다.
문서는 숫자 대신 그 칸을 가리킨다. 픽스처 명령은 NODE_ENV를 지우고
돈다.
버린 대안: 문서 숫자를 다시 손으로 고치기(두 번 낡았다), 문서에서
숫자를 지우고 bundle.json만 가리키기(예산을 정할 숫자를 보려면 빌드가
필요하다).

위험·한계: unit에 빌드가 하나 늘었다(약 3초). 초기 JS를 움직이는
변경은 기록도 다시 써야 test:unit이 통과한다. 그것이 목적이다.
`298201f` 출처별 크기 표와 `ec7435c` HTTP/1.1 측정 표는 날짜가 붙은
측정 기록으로 남겼다.

검증: 기록을 쓰기 전 새 테스트가 실패했다. 기록 gzipBytes를 2%
바꾸면 실패하고 되돌리면 통과한다. 지금 기록: 200,939 B, 파일 25개,
기능 +765 B, context +214 B. feature-shape-growth 7건 통과,
verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, 15-04
This commit is contained in:
DongHyeonka
2026-11-04 20:34:39 +09:00
parent e440ece9fe
commit c9e7bab2d7
5 changed files with 184 additions and 41 deletions
+89 -7
View File
@@ -25,8 +25,11 @@ import { parseTscExtendedDiagnostics, type TscDiagnostics } from "./collect-tsc-
* 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.
* `--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. */
@@ -143,10 +146,15 @@ function run(
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);
@@ -167,23 +175,77 @@ async function javascriptGzipBytes(root: string, files: readonly string[]) {
}
/**
* 15-01. Initial JavaScript gzip bytes of the app with `features` reference
* 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.
* 15-01. Initial JavaScript of the app with `features` reference 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.
*/
export async function measureInitialJavascriptGzipBytes(features: number): Promise<number> {
async function measureInitialJavascript(
features: number,
): Promise<Readonly<{ gzipBytes: number; files: number }>> {
const root = await createFixture(features);
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"));
return await javascriptGzipBytes(root, classifyViteJavascript(manifest).initialFiles);
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 one more
* feature and one more context add to it. The first copy lands in a new
* context (shape-context-0) and the second in the same one, so the second
* copy is a feature alone and the rest of the first is the context.
* `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;
perFeatureGzipBytes: number;
perContextGzipBytes: number;
}>;
export async function measureInitialJavascriptCosts(): Promise<InitialJavascriptCosts> {
const none = await measureInitialJavascript(0);
const one = await measureInitialJavascript(1);
const two = await measureInitialJavascript(2);
const perFeatureGzipBytes = two.gzipBytes - one.gzipBytes;
return {
gzipBytes: none.gzipBytes,
files: none.files,
perFeatureGzipBytes,
perContextGzipBytes: one.gzipBytes - none.gzipBytes - perFeatureGzipBytes,
};
}
/**
* Fields of the record that no longer describe the build. The total moves
* by tens of bytes with the build id (CI and local builds differ), so it may
* be 1% off; the per-feature and per-context costs are differences of builds
* with the same id but only a few hundred bytes, so 10%; the file count is
* exact.
*/
export function initialJavascriptRecordDrift(
measured: InitialJavascriptCosts,
record: InitialJavascriptCosts,
): string[] {
const tolerance: Readonly<Record<keyof InitialJavascriptCosts, number>> = {
gzipBytes: 0.01,
files: 0,
perFeatureGzipBytes: 0.1,
perContextGzipBytes: 0.1,
};
return (Object.keys(tolerance) as (keyof InitialJavascriptCosts)[])
.filter((field) => Math.abs(record[field] - measured[field]) > Math.abs(measured[field]) * tolerance[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);
@@ -262,7 +324,27 @@ function version(bin: string): string {
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);