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
+9 -3
View File
@@ -21,9 +21,9 @@
},
{
"axis": "Initial JavaScript",
"verified": "15-01: only each feature's declaration (route table, messages, invalidation identities) loads at boot; its runtime half loads with its routes. Baseline: 203,816 B with no copy, about 610-630 B and no extra file per copy (219,508 B at 25, 264,841 B at 100; before 15-01: +3,922 B per copy). tests/unit/feature-shape-growth.test.ts keeps one copy at or under 1 KiB",
"verified": "15-01: only each feature's declaration (route table, messages, invalidation identities) loads at boot; its runtime half loads with its routes, and a copy adds no initial file. initialJavascript below is the current template build, what one more feature in an existing context adds (perFeatureGzipBytes) and what a new context adds (perContextGzipBytes); tests/unit/feature-shape-growth.test.ts measures them on every unit run, bounds a feature at 1 KiB and a context at 512 B, and fails when the record no longer matches the build. The 25- and 100-copy runs are in the baseline at its source commit (before 15-01: +3,922 B per copy)",
"condition": "Same; the feature-declarations and feature-platform chunk groups in vite.config.ts",
"notVerified": "The initial budget (204,800 B, config/performance/budgets.json) leaves 2,291 B over the baseline's 202,509 B, so about three more reference-shaped features fit at about 610 B each: the platform itself is 98.9% of it"
"notVerified": "How many more features fit: the initial budget (config/performance/budgets.json) minus initialJavascript.gzipBytes, divided by perFeatureGzipBytes (plus perContextGzipBytes per new context). The platform itself takes most of the budget"
},
{
"axis": "Lazy JavaScript",
@@ -37,5 +37,11 @@
"condition": "Same",
"notVerified": "Router matching cost at runtime"
}
]
],
"initialJavascript": {
"gzipBytes": 200939,
"files": 25,
"perFeatureGzipBytes": 765,
"perContextGzipBytes": 214
}
}
+4 -2
View File
@@ -40,8 +40,10 @@ that the host serves that release; while the slot is empty FE-GATE-019 is
Rollback changes the active pointer only after confirming that the prior
immutable release has a coherent HTML/assets/config/API/manifest tuple.
Serve the app over HTTP/2 or later. The entry preloads about 26 initial
JavaScript files in parallel. Over HTTP/1.1 they queue for six connections per
Serve the app over HTTP/2 or later. The entry preloads every initial
JavaScript file in parallel (`initialJsFiles` in
`config/performance/budgets.json` bounds how many; the current count is
`initialJavascript.files` in `config/scale/feature-shape-ceilings.json`). Over HTTP/1.1 they queue for six connections per
host, and the first screen on Fast 3G came about one second later than with the
initial chunks grouped (2026-11-03). Over HTTP/2 the difference was under
100 ms, so the template keeps the chunks split. A product that can only serve
+28 -19
View File
@@ -14,23 +14,33 @@ Performance evidence is deliberately split by measurement context:
## 번들 예산의 기준선과 여유
리뷰 0925/13-14, 1101/15-02. 예산은 `config/performance/budgets.json`에 있고
`scripts/check-bundle.ts`(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본
화면만으로 초기 JS 예산의 98.9%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를
리뷰 0925/13-14, 1101/15-02, 1103/15-02. 예산은 `config/performance/budgets.json`에
있고 `scripts/check-bundle.ts`(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본
화면만으로 초기 JS 예산의 대부분을 쓴다. 첫 기능을 추가하기 전에 아래 기록을
보고 예산을 정한다.
| 항목 | 값 |
기준선 숫자는 이 문서에 적지 않는다. 손으로 적은 숫자는 두 번 낡았다. 기록은
`config/scale/feature-shape-ceilings.json`의 `initialJavascript` 한 곳이다.
| 칸 | 뜻 |
|---|---|
| 초기 JS 예산 | 204,800 gzip bytes(200 KiB) |
| 템플릿 기준선(2026-11-01, 커밋 `298201f`) | 202,509~202,522 gzip bytes, 16개 파일. local 프로필, `VITE_BUILD_ID`가 `local-build`일 때와 CI 모양(`gitea-<run>-<attempt>`)일 때다. 빌드 ID가 번들에 들어가므로 빌드마다 수십~수백 바이트 다르다 |
| 여유 | 약 2,280 bytes(1.1%) |
| 기능 하나를 더할 때 | 참조 기능 모양 복사본 하나에 약 +650~750 bytes(`298201f` 측정, 상한은 `tests/unit/feature-shape-growth.test.ts`의 1 KiB). 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다 |
| lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 lazy JS는 17개, 합계 28,204 bytes이고 가장 큰 것은 `use-reference-feature` 8,386 bytes다 |
| `gzipBytes`, `files` | 템플릿 그대로의 초기 JS gzip bytes와 파일 수(entry 포함) |
| `perFeatureGzipBytes` | 있는 context에 참조 기능 모양 기능을 하나 더할 때 느는 초기 JS. 상한 1 KiB |
| `perContextGzipBytes` | 새 context를 하나 더할 때 느는 초기 JS. 상한 512 B |
- `tests/unit/feature-shape-growth.test.ts`(unit, merge 단계)가 매번 빌드해 이
값을 재고, 상한을 넘거나 기록과 다르면(합계 1% 초과, 파일 수 불일치, 기능·
context 비용 10% 초과) 실패한다. 실패 메시지에 잰 값이 나온다.
- 기록을 고칠 때는 `node scripts/scale/measure-feature-shape-growth.ts
--initial-baseline --write`를 돌리고 같은 변경에 넣는다.
- 여유는 예산에서 `gzipBytes`를 뺀 값이다. 그것을 `perFeatureGzipBytes`로 나누면
더 넣을 수 있는 기능 수다. 새 context마다 `perContextGzipBytes`가 더 든다.
- 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다.
lazy chunk 예산은 파일마다 120 KiB(`lazyChunkGzipBytes`)다.
청크 이름으로 크기를 판단하지 않는다. rolldown은 공용 청크에 안에 든 모듈
하나의 이름을 붙인다. 예를 들어 `render-boot-failure` 청크(58.6 KB)의 대부분은
react-dom이고, `design-system` 청크(48.2 KB)에는 react-router가 들어 있다.
아래는 출처별 크기다. sourcemap 빌드에서 minify된 바이트를 원래 모듈에 나눠
하나의 이름을 붙인다. 아래는 2026-11-01(`298201f`)에 잰 출처별 크기다. 지금
빌드와는 조금 다르다. sourcemap 빌드에서 minify된 바이트를 원래 모듈에 나눠
붙이고 묶음마다 따로 gzip했다. 따로 압축하므로 합은 실제 합계와 조금 다르다.
| 출처 | minify bytes | 단독 gzip bytes |
@@ -54,8 +64,7 @@ react-dom이고, `design-system` 청크(48.2 KB)에는 react-router가 들어
(`scripts/lib/classify-vite-bundle.ts`). entry는 앱 그래프의 평가 실패를
보고하려고 그 둘을 dynamic import로 읽을 뿐이고, 첫 화면에 항상 필요하다
(0925/09-03). 그 밖의 dynamic import chunk는 lazy다.
- 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.6 KB gzip)는 예산에 들어가지
않는다.
- 합계는 JavaScript만 센다. CSS(`index-*.css`)는 예산에 들어가지 않는다.
- gzip은 Node `zlib.gzipSync` 기본 수준(6)으로 잰다
(`scripts/lib/release-candidate.ts`). 호스팅이 brotli로 보내면 전송 크기는 더
작다. 예산은 gzip 기준 그대로 둔다.
@@ -104,12 +113,12 @@ the example can never serve as production evidence.
리뷰 1101/14.4. 08-08은 초기 JS 바이트를 줄이는 대신 초기 파일 수를 늘렸다
(`vite.config.ts`의 `moduleSideEffects` 주석). HTTP/1.1에서 브라우저는 한
호스트에 연결을 6개까지만 연다. 파일이 많으면 요청이 줄을 서서 왕복이 는다.
그래서 지금 빌드와 작은 초기 청크를 하나로 묶은 빌드를 쟀다(2026-11-03,
커밋 `ec7435c`).
그래서 그때 빌드와 작은 초기 청크를 하나로 묶은 빌드를 쟀다(2026-11-03,
커밋 `ec7435c`). 아래 두 표의 파일 수와 바이트는 그 커밋의 값이다.
| 빌드 | 초기 JS 파일(entry 포함) | 초기 JS gzip(B) | 첫 화면까지 JS 요청 | Fast 3G 첫 화면 | Fast 4G 첫 화면 |
|---|---:|---:|---:|---:|---:|
| 지금 | 26 | 202,782 | 27 | 5,887 ms | 1,874 ms |
| `ec7435c` | 26 | 202,782 | 27 | 5,887 ms | 1,874 ms |
| (가) 08-08이 나눈 초기 primitive 청크 4개(`field`·`button`·`select`·`page-templates`)를 하나로 | 23 | 201,818 | 24 | 5,426 ms | 1,764 ms |
| (나) 묶을 수 있는 초기 청크 14개를 하나로 | 13 | 198,673 | 14 | 4,930 ms | 1,535 ms |
@@ -118,7 +127,7 @@ the example can never serve as production evidence.
| 빌드 | Fast 3G 첫 화면 | Fast 4G 첫 화면 |
|---|---:|---:|
| 지금 | 4,793 ms | 1,444 ms |
| `ec7435c` | 4,793 ms | 1,444 ms |
| (가) | 4,769 ms | 1,440 ms |
| (나) | 4,708 ms | 1,422 ms |
@@ -130,7 +139,7 @@ the example can never serve as production evidence.
- 매번 새 browser context에서 캐시 없이 `/`를 연다. 첫 화면은 boot 셸이
사라지고 `#main-content h1[data-route-heading]`가 DOM에 들어온 시각이다
(`performance.now()`).
- 세 빌드를 번갈아 7번씩 재고 중앙값을 적었다. 7번의 범위는 지금 5,866~6,077 ms,
- 세 빌드를 번갈아 7번씩 재고 중앙값을 적었다. 7번의 범위는 `ec7435c` 5,866~6,077 ms,
(가) 5,384~5,652 ms, (나) 4,891~5,032 ms다(Fast 3G). loadavg는 HTTP/1.1
측정 때 6~20, HTTP/2 측정 때 3~6이었다. 그래서 두 표끼리는 비교하지 않는다.
- CDP 지연은 요청마다 붙는다. 연결 수립(TCP·TLS) 비용은 따로 재지 않았다.
+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);
+54 -10
View File
@@ -5,8 +5,10 @@ import { describe, expect, it } from "vitest";
import {
FEATURE_SHAPE_BASELINE_PATH,
FEATURE_SHAPE_CEILINGS_PATH,
measureInitialJavascriptGzipBytes,
initialJavascriptRecordDrift,
measureInitialJavascriptCosts,
renameReferenceFeature,
type InitialJavascriptCosts,
} from "../../scripts/scale/measure-feature-shape-growth.ts";
import { APP_MAX_CONTEXTS } from "../../src/apps/template-app/app-module.ts";
import { CONTEXT_MAX_FEATURES } from "../../src/contexts/reference-context/context-module.ts";
@@ -131,17 +133,59 @@ describe("feature-shape growth measurement (11-04)", () => {
* contracts, schemas, mappers, HTTP gateway and API loaded at boot: +3,922 B
* per copy, and the first added feature exceeded the budget. Only what the
* shell needs before a feature route is entered may load at boot (route
* table, navigation and page messages, invalidation identities: 741 B when
* 15-01 landed); the rest loads with the feature's routes. The bound also
* fails if the feature-declarations chunk group in vite.config.ts stops
* matching.
* table, navigation and page messages, invalidation identities); the rest
* loads with the feature's routes. The bound also fails if the
* feature-declarations chunk group in vite.config.ts stops matching.
*
* 1103/15-04. The first copy also adds a context (shape-context-0), so one
* number mixed a context's cost with a feature's and had 40 B left under
* the bound. A second copy in the same context is one more feature alone;
* the rest of the first copy is the context. Each has its own bound and
* the failure names which one grew.
*
* 1103/15-02. The record in config/scale/feature-shape-ceilings.json is the
* one place the documents take the template's baseline from. Written by
* hand, it went stale twice; it now has to match this build.
*/
it("adds at most 1 KiB of initial JavaScript per reference-shaped feature (15-01)", async () => {
const withoutCopies = await measureInitialJavascriptGzipBytes(0);
const withOneCopy = await measureInitialJavascriptGzipBytes(1);
it("bounds what one more feature and one more context add, and matches the record (15-01)", async () => {
const measured = await measureInitialJavascriptCosts();
const { initialJavascript: record } = JSON.parse(
await readFile(FEATURE_SHAPE_CEILINGS_PATH, "utf8"),
) as { initialJavascript: InitialJavascriptCosts };
const observed = `measured ${JSON.stringify(measured)}`;
expect(withOneCopy - withoutCopies).toBeLessThanOrEqual(1_024);
}, 120_000);
expect(measured.perFeatureGzipBytes, `one more feature in an existing context: ${observed}`)
.toBeLessThanOrEqual(1_024);
expect(measured.perContextGzipBytes, `one more context: ${observed}`)
.toBeLessThanOrEqual(512);
expect(
initialJavascriptRecordDrift(measured, record),
`${FEATURE_SHAPE_CEILINGS_PATH} initialJavascript is stale (${observed}); ` +
"rewrite it with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write",
).toEqual([]);
}, 180_000);
it("reports a record more than 1% off the build, or a different file count", () => {
const measured = {
gzipBytes: 200_000,
files: 25,
perFeatureGzipBytes: 700,
perContextGzipBytes: 250,
};
expect(initialJavascriptRecordDrift(measured, measured)).toEqual([]);
expect(
initialJavascriptRecordDrift(measured, { ...measured, gzipBytes: 201_500 }),
).toEqual([]);
expect(
initialJavascriptRecordDrift(measured, { ...measured, gzipBytes: 204_000 }),
).toEqual(["gzipBytes: record 204000, build 200000"]);
expect(initialJavascriptRecordDrift(measured, { ...measured, files: 26 })).toEqual([
"files: record 26, build 25",
]);
expect(
initialJavascriptRecordDrift(measured, { ...measured, perFeatureGzipBytes: 800 }),
).toEqual(["perFeatureGzipBytes: record 800, build 700"]);
});
it("states in the committed rationale what the ceilings rest on", async () => {
// The rationale lives next to the baseline, not in a review document: the