fix(bundle): 예산을 넘으면 넘은 한도와 초과량을 출력하고 초기 파일 수를 막는다
문제: 초기 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
This commit is contained in:
+48
-9
@@ -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`,
|
||||
);
|
||||
|
||||
@@ -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");
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user