From 46dfe23f699a756efed2ca40ee91b3b4a8fec85a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:22:27 +0900 Subject: [PATCH] =?UTF-8?q?fix(bundle):=20=EC=98=88=EC=82=B0=EC=9D=84=20?= =?UTF-8?q?=EB=84=98=EC=9C=BC=EB=A9=B4=20=EB=84=98=EC=9D=80=20=ED=95=9C?= =?UTF-8?q?=EB=8F=84=EC=99=80=20=EC=B4=88=EA=B3=BC=EB=9F=89=EC=9D=84=20?= =?UTF-8?q?=EC=B6=9C=EB=A0=A5=ED=95=98=EA=B3=A0=20=EC=B4=88=EA=B8=B0=20?= =?UTF-8?q?=ED=8C=8C=EC=9D=BC=20=EC=88=98=EB=A5=BC=20=EB=A7=89=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 초기 JS가 예산을 넘으면 check:bundle은 "Bundle budget or manifest integrity failed: " 한 줄만 쓰고 콜론 뒤가 비어 있었다. 측정값과 한도는 artifacts/performance/bundle.json에만 있어 예산 실패인지 manifest 무결성 실패인지, 몇 바이트 넘었는지 알 수 없었다. 또 초기 JS 파일 수에는 상한이 없어 08-08처럼 파일을 16개에서 25개로 늘리는 변경도 모든 게이트를 통과했다. 템플릿은 HTTP/2를 전제로 초기 청크를 나눠 두었는데, 파일 수를 늘리는 결정이 어디에도 드러나지 않았다. 고른 방법: 예산 실패와 무결성 실패를 다른 문장으로 쓴다. 예산 실패는 넘은 한도마다 측정값·한도·초과량을 한 줄로 쓴다 (describeBundleBudgetFailures). config/performance/budgets.json에 initialJsFiles(지금 25)를 두고 check:bundle이 entry를 포함한 초기 파일 수를 센다. bundle.json 스키마는 측정값·한도·결과와 자가 검사 fixture를 하나씩 더 가진다. 두 변경은 같은 함수와 스키마를 고치므로 한 커밋에 넣었다. 버린 대안: 파일 수를 문서에만 적기. 08-08이 그 상태에서 파일을 늘렸다. 위험·한계: 초기 파일을 하나라도 늘리는 변경은 이제 budgets.json을 같이 고쳐야 통과한다. 그것이 목적이다. HTTP/2 확인 자체는 이 커밋에 없다 (13-02에서 probe에 넣는다). 검증: tests/unit/check-bundle-output.test.ts가 손으로 만든 빌드 출력에 check-bundle.ts를 돌려 통과·초기 바이트 초과·lazy 초과·파일 수 초과· 무결성 실패의 출력을 본다(고치기 전 4건 실패). bundle-artifact-contract, performance-budgets 통과. 실제 빌드에서 check:bundle PASS(25 / 25 files). Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-03, 15-05 --- config/performance/budgets.json | 1 + docs/operations/performance-evidence.md | 8 +- scripts/check-bundle.ts | 57 +++++++-- scripts/contracts/release-artifacts.ts | 16 ++- scripts/lib/performance-budgets.ts | 38 +++++- tests/unit/bundle-artifact-contract.test.ts | 9 +- tests/unit/check-bundle-output.test.ts | 128 ++++++++++++++++++++ tests/unit/performance-budgets.test.ts | 10 +- 8 files changed, 251 insertions(+), 16 deletions(-) create mode 100644 tests/unit/check-bundle-output.test.ts diff --git a/config/performance/budgets.json b/config/performance/budgets.json index adf9cc73..495e8a98 100644 --- a/config/performance/budgets.json +++ b/config/performance/budgets.json @@ -2,6 +2,7 @@ "schemaVersion": 1, "bundle": { "initialJsGzipBytes": 204800, + "initialJsFiles": 25, "lazyChunkGzipBytes": 122880 }, "lab": { diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 6bf1c888..16e5cc36 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -3,7 +3,9 @@ Performance evidence is deliberately split by measurement context: - `bundle.json` records production build output and enforces initial JavaScript - at 200 KiB gzip and every lazy chunk at 120 KiB gzip. + at 200 KiB gzip, the number of initial JavaScript files (`initialJsFiles`), + and every lazy chunk at 120 KiB gzip. A failure names each exceeded limit, + the measured value and the excess (1103/15-03). - `lab.json` records Chromium/runner/viewport/network/CPU/cache/build context and enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms. - `field-web-vitals.json` records consent-filtered, route-ID aggregated, @@ -154,6 +156,8 @@ the example can never serve as production evidence. 버렸다. - HTTP/2에서는 (나)도 Fast 3G 85 ms, Fast 4G 22 ms 차이다(위 둘째 표). -그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. HTTP/1.1로만 서빙해야 하는 +그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. 초기 파일 수는 +`config/performance/budgets.json`의 `initialJsFiles`가 막는다(1103/15-05). 초기 +파일을 늘리는 변경은 그 값을 같이 고치고, 이유를 같은 변경에 적는다. HTTP/1.1로만 서빙해야 하는 제품은 (나)처럼 초기 청크를 묶는 그룹을 `vite.config.ts`에 넣는다. 그 목록은 셸을 바꿀 때마다 위 방법으로 다시 잰다. diff --git a/scripts/check-bundle.ts b/scripts/check-bundle.ts index 64223b20..bbd9fb9e 100644 --- a/scripts/check-bundle.ts +++ b/scripts/check-bundle.ts @@ -1,6 +1,9 @@ import { readFile } from "node:fs/promises"; -import { evaluateBundleBudget } from "./lib/performance-budgets.ts"; +import { + describeBundleBudgetFailures, + evaluateBundleBudget, +} from "./lib/performance-budgets.ts"; import { bundleOutputInventoryArtifactSchema, bundlePerformanceArtifactSchema, @@ -14,6 +17,7 @@ type ViteManifest = Record< >; type BundleBudgets = { initialJsGzipBytes: number; + initialJsFiles: number; lazyChunkGzipBytes: number; }; @@ -43,7 +47,11 @@ const missingOutputs = [ ...classification.initialFiles, ...classification.lazyFiles, ].filter((file) => !outputByPath.has(file)); -const measurements = { initialJsGzipBytes, lazyChunks }; +const measurements = { + initialJsGzipBytes, + initialJsFiles: classification.initialFiles.length, + lazyChunks, +}; const result = evaluateBundleBudget(measurements, budgets); const fixtures = [ { @@ -52,6 +60,7 @@ const fixtures = [ !evaluateBundleBudget( { initialJsGzipBytes: budgets.initialJsGzipBytes + 1, + initialJsFiles: 0, lazyChunks: [], }, budgets, @@ -63,6 +72,7 @@ const fixtures = [ !evaluateBundleBudget( { initialJsGzipBytes: 0, + initialJsFiles: 0, lazyChunks: [ { path: "fixture.js", @@ -73,6 +83,18 @@ const fixtures = [ budgets, ).passed, }, + { + name: "initial-files-over-budget", + passed: + !evaluateBundleBudget( + { + initialJsGzipBytes: 0, + initialJsFiles: budgets.initialJsFiles + 1, + lazyChunks: [], + }, + budgets, + ).passed, + }, ]; const passed = result.passed && @@ -95,15 +117,32 @@ await writeValidatedJsonArtifact({ schema: bundlePerformanceArtifactSchema, value: completedReport, }); +// 1103/15-03. The budget and the manifest integrity fail for different +// reasons, so each says what failed and by how much. if (!passed) { - process.stderr.write( - `Bundle budget or manifest integrity failed: ${[ - ...classification.missingImports, - ...missingOutputs, - ].join(", ")}\n`, - ); + const budgetFailures = describeBundleBudgetFailures(measurements, budgets); + if (budgetFailures.length > 0) { + process.stderr.write( + `Bundle budget failed (config/performance/budgets.json):\n${budgetFailures + .map((line) => ` ${line}\n`) + .join("")}`, + ); + } + const integrityFailures = [ + ...classification.missingImports.map((key) => `manifest import without an entry: ${key}`), + ...missingOutputs.map((file) => `output missing from the inventory: ${file}`), + ...fixtures + .filter((fixture) => !fixture.passed) + .map((fixture) => `budget self-check did not fail: ${fixture.name}`), + ]; + if (integrityFailures.length > 0) { + process.stderr.write( + `Bundle manifest integrity failed:\n${integrityFailures.map((line) => ` ${line}\n`).join("")}`, + ); + } process.exit(1); } process.stdout.write( - `Bundle budget: PASS (initial JS ${initialJsGzipBytes} / ${budgets.initialJsGzipBytes} gzip bytes)\n`, + `Bundle budget: PASS (initial JS ${initialJsGzipBytes} / ${budgets.initialJsGzipBytes} gzip bytes, ` + + `${measurements.initialJsFiles} / ${budgets.initialJsFiles} files)\n`, ); diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index d70ed79a..7891ff28 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -364,12 +364,14 @@ const bundleClassificationSchema = z const bundleThresholdsSchema = z .object({ initialJsGzipBytes: z.int().positive(), + initialJsFiles: z.int().positive(), lazyChunkGzipBytes: z.int().positive(), }) .strict(); const bundleBudgetResultSchema = z .object({ initialPassed: z.boolean(), + initialFilesPassed: z.boolean(), lazyResults: z.array( bundleMeasurementSchema.extend({ threshold: z.int().positive(), @@ -386,6 +388,7 @@ export const bundlePerformanceArtifactSchema = z measurements: z .object({ initialJsGzipBytes: z.int().nonnegative(), + initialJsFiles: z.int().nonnegative(), lazyChunks: z.array(bundleMeasurementSchema), }) .strict(), @@ -396,6 +399,7 @@ export const bundlePerformanceArtifactSchema = z fixtures: z.tuple([ z.object({ name: z.literal("initial-js-over-budget"), passed: z.boolean() }).strict(), z.object({ name: z.literal("lazy-chunk-over-budget"), passed: z.boolean() }).strict(), + z.object({ name: z.literal("initial-files-over-budget"), passed: z.boolean() }).strict(), ]), passed: z.boolean(), }) @@ -441,6 +445,9 @@ export const bundlePerformanceArtifactSchema = z if (artifact.measurements.initialJsGzipBytes !== expectedInitialBytes) { issue(["measurements", "initialJsGzipBytes"], "must equal classified initial output bytes"); } + if (artifact.measurements.initialJsFiles !== artifact.classification.initialFiles.length) { + issue(["measurements", "initialJsFiles"], "must equal the classified initial file count"); + } const expectedLazyChunks = artifact.classification.lazyFiles.map((file) => ({ path: file, gzipBytes: outputs.get(file)?.gzipBytes ?? 0, @@ -453,6 +460,11 @@ export const bundlePerformanceArtifactSchema = z if (artifact.results.initialPassed !== expectedInitialPassed) { issue(["results", "initialPassed"], "must agree with initial threshold"); } + const expectedInitialFilesPassed = + artifact.measurements.initialJsFiles <= artifact.thresholds.initialJsFiles; + if (artifact.results.initialFilesPassed !== expectedInitialFilesPassed) { + issue(["results", "initialFilesPassed"], "must agree with the initial file threshold"); + } const expectedLazyResults = artifact.measurements.lazyChunks.map((chunk) => ({ ...chunk, threshold: artifact.thresholds.lazyChunkGzipBytes, @@ -462,7 +474,9 @@ export const bundlePerformanceArtifactSchema = z issue(["results", "lazyResults"], "must agree with lazy measurements and threshold"); } const expectedBudgetPassed = - expectedInitialPassed && expectedLazyResults.every(({ passed }) => passed); + expectedInitialPassed && + expectedInitialFilesPassed && + expectedLazyResults.every(({ passed }) => passed); if (artifact.results.passed !== expectedBudgetPassed) { issue(["results", "passed"], "must agree with budget results"); } diff --git a/scripts/lib/performance-budgets.ts b/scripts/lib/performance-budgets.ts index d6caac34..b2bf26b1 100644 --- a/scripts/lib/performance-budgets.ts +++ b/scripts/lib/performance-budgets.ts @@ -1,10 +1,18 @@ export type BundleMeasurements = Readonly<{ initialJsGzipBytes: number; + initialJsFiles: number; lazyChunks: readonly Readonly<{ path: string; gzipBytes: number }>[]; }>; +/** + * 1103/15-05. `initialJsFiles` bounds the number of initial JavaScript files + * (entry included). The entry preloads them in parallel, which costs no round + * trip over HTTP/2 and queues them six at a time over HTTP/1.1 + * (docs/operations/performance-evidence.md, "초기 청크 수와 HTTP/1.1"). + */ export type BundleThresholds = Readonly<{ initialJsGzipBytes: number; + initialJsFiles: number; lazyChunkGzipBytes: number; }>; @@ -14,6 +22,7 @@ export function evaluateBundleBudget( ) { const initialPassed = measurements.initialJsGzipBytes <= thresholds.initialJsGzipBytes; + const initialFilesPassed = measurements.initialJsFiles <= thresholds.initialJsFiles; const lazyResults = measurements.lazyChunks.map((chunk) => ({ ...chunk, threshold: thresholds.lazyChunkGzipBytes, @@ -21,11 +30,38 @@ export function evaluateBundleBudget( })); return Object.freeze({ initialPassed, + initialFilesPassed, lazyResults: Object.freeze(lazyResults), - passed: initialPassed && lazyResults.every((chunk) => chunk.passed), + passed: initialPassed && initialFilesPassed && lazyResults.every((chunk) => chunk.passed), }); } +/** + * 1103/15-03. One line per exceeded limit with the measured value, the limit + * and the excess, so a failed check:bundle says what to cut without opening + * artifacts/performance/bundle.json. + */ +export function describeBundleBudgetFailures( + measurements: BundleMeasurements, + thresholds: BundleThresholds, +): string[] { + const over = (label: string, measured: number, limit: number, unit = " gzip bytes") => + `${label} ${measured}${unit} > budget ${limit} (over by ${measured - limit})`; + const lines: string[] = []; + if (measurements.initialJsGzipBytes > thresholds.initialJsGzipBytes) { + lines.push(over("initial JavaScript", measurements.initialJsGzipBytes, thresholds.initialJsGzipBytes)); + } + if (measurements.initialJsFiles > thresholds.initialJsFiles) { + lines.push(over("initial JavaScript files", measurements.initialJsFiles, thresholds.initialJsFiles, "")); + } + for (const chunk of measurements.lazyChunks) { + if (chunk.gzipBytes > thresholds.lazyChunkGzipBytes) { + lines.push(over(`lazy chunk ${chunk.path}`, chunk.gzipBytes, thresholds.lazyChunkGzipBytes)); + } + } + return lines; +} + export type LabMetrics = Readonly<{ lcpMs: number; cls: number; diff --git a/tests/unit/bundle-artifact-contract.test.ts b/tests/unit/bundle-artifact-contract.test.ts index 478c2a70..cb42caf9 100644 --- a/tests/unit/bundle-artifact-contract.test.ts +++ b/tests/unit/bundle-artifact-contract.test.ts @@ -28,6 +28,7 @@ const completed = { ...inventory, measurements: { initialJsGzipBytes: 50, + initialJsFiles: 1, lazyChunks: [{ path: "assets/lazy.js", gzipBytes: 40 }], }, classification: { @@ -36,9 +37,10 @@ const completed = { missingImports: [], }, missingOutputs: [], - thresholds: { initialJsGzipBytes: 60, lazyChunkGzipBytes: 45 }, + thresholds: { initialJsGzipBytes: 60, initialJsFiles: 1, lazyChunkGzipBytes: 45 }, results: { initialPassed: true, + initialFilesPassed: true, lazyResults: [ { path: "assets/lazy.js", gzipBytes: 40, threshold: 45, passed: true }, ], @@ -47,6 +49,7 @@ const completed = { fixtures: [ { name: "initial-js-over-budget", passed: true }, { name: "lazy-chunk-over-budget", passed: true }, + { name: "initial-files-over-budget", passed: true }, ], passed: true, } as const; @@ -64,8 +67,10 @@ describe("bundle artifact contracts", () => { ["lazy classification", { classification: { ...completed.classification, lazyFiles: [] } }], ["missing output", { missingOutputs: ["assets/missing.js"], passed: true }], ["threshold result", { results: { ...completed.results, initialPassed: false } }], + ["initial file count", { measurements: { ...completed.measurements, initialJsFiles: 2 } }], + ["initial file result", { results: { ...completed.results, initialFilesPassed: false } }], ["lazy result", { results: { ...completed.results, lazyResults: [] } }], - ["fixture identity", { fixtures: [{ name: "other", passed: true }, completed.fixtures[1]] }], + ["fixture identity", { fixtures: [{ name: "other", passed: true }, completed.fixtures[1], completed.fixtures[2]] }], ["overall result", { passed: false }], ] as const)("rejects inconsistent %s evidence", (_name, mutation) => { expect(() => diff --git a/tests/unit/check-bundle-output.test.ts b/tests/unit/check-bundle-output.test.ts new file mode 100644 index 00000000..f5dd42ee --- /dev/null +++ b/tests/unit/check-bundle-output.test.ts @@ -0,0 +1,128 @@ +import { spawnSync } from "node:child_process"; +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { afterEach, describe, expect, it } from "vitest"; + +/** + * 1103/15-03. An over-budget build printed only + * "Bundle budget or manifest integrity failed: " with nothing after the + * colon, so the first budget failure a project meets named neither the limit + * nor the excess. check-bundle runs here on a hand-made build output. + */ +const roots: string[] = []; + +afterEach(async () => { + await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); +}); + +type Output = Readonly<{ path: string; gzipBytes: number }>; + +async function checkBundle( + options: Readonly<{ + outputs: readonly Output[]; + manifest: Record; + budgets: Record; + }>, +) { + const root = await mkdtemp(path.join(tmpdir(), "check-bundle-output-")); + roots.push(root); + const write = async (file: string, value: unknown) => { + await mkdir(path.dirname(path.join(root, file)), { recursive: true }); + await writeFile(path.join(root, file), `${JSON.stringify(value, null, 2)}\n`); + }; + await write("config/performance/budgets.json", { schemaVersion: 1, bundle: options.budgets }); + await write("dist/.vite/manifest.json", options.manifest); + await write("artifacts/performance/bundle.json", { + schemaVersion: 1, + generatedAt: "2026-11-04T00:00:00.000Z", + context: { nodeVersion: "v24.14.0", packageManager: "pnpm@11.17.0", runnerImage: "fixture" }, + outputs: options.outputs.map((output) => ({ + path: `dist/${output.path}`, + bytes: output.gzipBytes * 3, + gzipBytes: output.gzipBytes, + sha256: "a".repeat(64), + })), + }); + const result = spawnSync(process.execPath, [path.resolve("scripts/check-bundle.ts")], { + cwd: root, + encoding: "utf8", + }); + return { status: result.status, stdout: result.stdout, stderr: result.stderr }; +} + +const MANIFEST = { + "index.html": { + file: "assets/index-A.js", + isEntry: true, + imports: ["_boot"], + }, + // The entry's own dynamic imports are initial (09-03); a route's are lazy. + _boot: { file: "assets/boot-B.js", dynamicImports: ["src/lazy.tsx"] }, + "src/lazy.tsx": { file: "assets/lazy-C.js" }, +}; +const OUTPUTS = [ + { path: "assets/index-A.js", gzipBytes: 400 }, + { path: "assets/boot-B.js", gzipBytes: 500 }, + { path: "assets/lazy-C.js", gzipBytes: 300 }, +]; +const BUDGETS = { initialJsGzipBytes: 1_000, initialJsFiles: 2, lazyChunkGzipBytes: 400 }; + +describe("check:bundle failure output (1103/15-03)", () => { + it("passes and prints the total within budget", async () => { + const result = await checkBundle({ outputs: OUTPUTS, manifest: MANIFEST, budgets: BUDGETS }); + expect(result.stderr).toBe(""); + expect(result.status).toBe(0); + expect(result.stdout).toContain("initial JS 900 / 1000 gzip bytes"); + }); + + it("names the measured initial total, the budget and the excess", async () => { + const result = await checkBundle({ + outputs: OUTPUTS, + manifest: MANIFEST, + budgets: { ...BUDGETS, initialJsGzipBytes: 899 }, + }); + expect(result.status).toBe(1); + expect(result.stderr).toContain("Bundle budget failed (config/performance/budgets.json):"); + expect(result.stderr).toContain("initial JavaScript 900 gzip bytes > budget 899 (over by 1)"); + expect(result.stderr).not.toContain("manifest integrity"); + }); + + it("names each lazy chunk over its budget", async () => { + const result = await checkBundle({ + outputs: OUTPUTS, + manifest: MANIFEST, + budgets: { ...BUDGETS, lazyChunkGzipBytes: 250 }, + }); + expect(result.status).toBe(1); + expect(result.stderr).toContain( + "lazy chunk assets/lazy-C.js 300 gzip bytes > budget 250 (over by 50)", + ); + }); + + // 1103/15-05. The entry preloads every initial file at once; over HTTP/1.1 + // they queue for six connections. A change that adds an initial file is a + // decision recorded in the budget, not a side effect. + it("fails when the initial JavaScript has more files than the budget", async () => { + const result = await checkBundle({ + outputs: OUTPUTS, + manifest: MANIFEST, + budgets: { ...BUDGETS, initialJsFiles: 1 }, + }); + expect(result.status).toBe(1); + expect(result.stderr).toContain("initial JavaScript files 2 > budget 1 (over by 1)"); + }); + + it("reports a manifest integrity failure apart from the budget", async () => { + const result = await checkBundle({ + outputs: OUTPUTS.filter(({ path: file }) => file !== "assets/boot-B.js"), + manifest: MANIFEST, + budgets: BUDGETS, + }); + expect(result.status).toBe(1); + expect(result.stderr).toContain("Bundle manifest integrity failed:"); + expect(result.stderr).toContain("output missing from the inventory: assets/boot-B.js"); + expect(result.stderr).not.toContain("Bundle budget failed"); + }); +}); diff --git a/tests/unit/performance-budgets.test.ts b/tests/unit/performance-budgets.test.ts index 8d33d5d8..7cff0612 100644 --- a/tests/unit/performance-budgets.test.ts +++ b/tests/unit/performance-budgets.test.ts @@ -11,11 +11,12 @@ describe("performance budgets", () => { it("rejects initial and lazy JavaScript above their named limits", () => { const thresholds = { initialJsGzipBytes: 200, + initialJsFiles: 2, lazyChunkGzipBytes: 120, }; expect( evaluateBundleBudget( - { initialJsGzipBytes: 201, lazyChunks: [] }, + { initialJsGzipBytes: 201, initialJsFiles: 1, lazyChunks: [] }, thresholds, ).passed, ).toBe(false); @@ -23,11 +24,18 @@ describe("performance budgets", () => { evaluateBundleBudget( { initialJsGzipBytes: 100, + initialJsFiles: 1, lazyChunks: [{ path: "lazy.js", gzipBytes: 121 }], }, thresholds, ).passed, ).toBe(false); + expect( + evaluateBundleBudget( + { initialJsGzipBytes: 100, initialJsFiles: 3, lazyChunks: [] }, + thresholds, + ), + ).toMatchObject({ initialPassed: true, initialFilesPassed: false, passed: false }); }); it("fails lab evidence when context is absent or a metric is over budget", () => {