문제: lab(FE-GATE-026)은 플랫폼 구성 화면(EXAMPLES_PLATFORM) 하나만 잰다.
이 화면은 기능 코드를 받지 않아 기능을 더해도 수치가 거의 그대로다
(146 → 154 ms). 기능 라우트는 처음 들어갈 때 context 라우트 모듈과 기능
실행부를 받고, 그다음 페이지 청크를 받는 두 번의 요청 묶음을 거친다.
lab 조건에서 EXAMPLES_UI 첫 진입은 중앙값 406 ms(403~410, 리뷰 15-R1)로
대상 화면의 2.7배인데 어느 게이트도 재지 않는다. 다운스트림의 화면은
모두 기능 라우트다.
고른 방법:
- labFeatureRoute(scripts/lib/lab-performance.ts): 설치된 기능이 가진,
세션 없이 열리는 첫 내비게이션 라우트. 템플릿에서는 EXAMPLES_UI다.
없으면 null이고 lab은 measured: false로 남기고 판정하지 않는다.
- lab은 run마다 `/`에서 그 라우트의 내비게이션 링크를 눌러 heading까지를
같은 페이지 시계로 잰다(새 cold context). metrics.featureRouteInteractionMs
(중앙값), context.sampling.featureRoute(표본, owner)에 남긴다. 기존 대상
라우트와 그 예산(200 ms)은 그대로라 회귀 비교가 이어진다.
- 예산 config/performance/budgets.json lab.featureRouteInteractionMs = 500 ms.
측정 406 ms(8a44226, i5-10400F, lab 조건)를 통과시키고, 지금 둘째 요청
묶음 크기(약 100 ms, 클릭 뒤 98~204 ms)의 왕복이 하나 더 붙으면 넘는다.
lab 자가 검사 fixture에 feature-route-over-threshold를 더해 이 예산이
실패할 수 있음을 매번 확인한다.
- 단위 테스트: 라우트 선택 규칙, 설치된 레지스트리에서의 선택, 커밋된
예산이 406 ms는 통과·516 ms는 실패·null은 판정 제외.
버린 대안:
- 두 요청 묶음을 하나로 줄이기(진입한 URL의 페이지 청크를 context 라우트
모듈과 같이 받기): 페이지 청크 이름이 context 라우트 모듈 안의 lazy()에만
있어, 첫 묶음에서 받으려면 초기 청크의 라우트 선언이 페이지 로더를 가져야
한다. 선언 모양·생성기·초기 JS를 바꾸는 일이라 이 커밋에서 하지 않았다
(결정 대기, performance-evidence.md에 적음).
- 처음에는 기록만 하기: 기록만 하면 늘어도 아무도 모른다. 측정값이 있으니
예산을 같이 둔다.
- 라우트별 예산 표: 다운스트림이 채워야 하는 표가 는다.
위험·한계: 예산 여유가 94 ms(23%)라 lab 호스트가 지금보다 20% 이상 느리면
기능 라우트 판정이 흔들릴 수 있다(0929/11-04 lab 부하 가드는 여전히 없음).
FE-GATE-026 시간이 run마다 cold navigation 하나(약 2~3초) 늘어 5회면
+10~15초다. 생성 기능의 목록 라우트는 session-required라 lab 대상이 되지
않는다. 기능 라우트의 heading은 계약 `title`과 같은 글자로 찾는다(대상
라우트와 같은 방식). CHANGELOG의 "기능 라우트 첫 진입은 어느 게이트도
재지 않는다" 제한 문장은 이 커밋에서 고치지 않았다(오케스트레이터 몫).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
tests/unit/performance-budgets.test.ts
corepack pnpm build && corepack pnpm test:performance -- --runs=5
(featureRoute EXAMPLES_UI 중앙값이 500 ms 안인지, 표본 기록)
Refs: 1105/15-04
179 lines
5.6 KiB
TypeScript
179 lines
5.6 KiB
TypeScript
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;
|
|
}>;
|
|
|
|
export function evaluateBundleBudget(
|
|
measurements: BundleMeasurements,
|
|
thresholds: BundleThresholds,
|
|
) {
|
|
const initialPassed =
|
|
measurements.initialJsGzipBytes <= thresholds.initialJsGzipBytes;
|
|
const initialFilesPassed = measurements.initialJsFiles <= thresholds.initialJsFiles;
|
|
const lazyResults = measurements.lazyChunks.map((chunk) => ({
|
|
...chunk,
|
|
threshold: thresholds.lazyChunkGzipBytes,
|
|
passed: chunk.gzipBytes <= thresholds.lazyChunkGzipBytes,
|
|
}));
|
|
return Object.freeze({
|
|
initialPassed,
|
|
initialFilesPassed,
|
|
lazyResults: Object.freeze(lazyResults),
|
|
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;
|
|
}
|
|
|
|
/**
|
|
* 1105/15-01. `targetDeepLinkCls` is the CLS of a direct visit to the lab's
|
|
* target route, judged against the same `cls` threshold. The click run
|
|
* cannot see a shift the target makes while it fills in: one within 500 ms
|
|
* of the click is input-driven by definition.
|
|
*/
|
|
export type LabMetrics = Readonly<{
|
|
lcpMs: number;
|
|
cls: number;
|
|
namedInteractionMs: number;
|
|
targetDeepLinkCls: number;
|
|
/**
|
|
* 1105/15-04. Click to heading on the first public navigation route an
|
|
* installed feature owns (`labFeatureRoute`). `null` when there is none:
|
|
* nothing to judge.
|
|
*/
|
|
featureRouteInteractionMs: number | null;
|
|
}>;
|
|
|
|
export type LabThresholds = Readonly<{
|
|
lcpMs: number;
|
|
cls: number;
|
|
namedInteractionMs: number;
|
|
featureRouteInteractionMs: number;
|
|
}>;
|
|
|
|
export function evaluateLabBudget(
|
|
report: Readonly<{
|
|
context?: Readonly<Record<string, unknown>>;
|
|
metrics: LabMetrics;
|
|
}>,
|
|
thresholds: LabThresholds,
|
|
) {
|
|
const requiredContext = [
|
|
"runner",
|
|
"browser",
|
|
"viewport",
|
|
"network",
|
|
"cpu",
|
|
"cache",
|
|
"build",
|
|
];
|
|
const missingContext = requiredContext.filter(
|
|
(field) => report.context?.[field] === undefined,
|
|
);
|
|
const results = {
|
|
lcp: report.metrics.lcpMs <= thresholds.lcpMs,
|
|
cls: report.metrics.cls <= thresholds.cls,
|
|
namedInteraction:
|
|
report.metrics.namedInteractionMs <= thresholds.namedInteractionMs,
|
|
targetDeepLinkCls: report.metrics.targetDeepLinkCls <= thresholds.cls,
|
|
featureRouteInteraction:
|
|
report.metrics.featureRouteInteractionMs === null ||
|
|
report.metrics.featureRouteInteractionMs <= thresholds.featureRouteInteractionMs,
|
|
};
|
|
return Object.freeze({
|
|
missingContext: Object.freeze(missingContext),
|
|
results: Object.freeze(results),
|
|
passed: missingContext.length === 0 && Object.values(results).every(Boolean),
|
|
});
|
|
}
|
|
|
|
export function percentile75(values: readonly number[]): number | null {
|
|
if (values.length === 0) return null;
|
|
const sorted = [...values].sort((left, right) => left - right);
|
|
return sorted[Math.ceil(sorted.length * 0.75) - 1];
|
|
}
|
|
|
|
export type FieldMetrics = Readonly<{
|
|
p75LcpMs: number | null;
|
|
p75Cls: number | null;
|
|
p75InpMs: number | null;
|
|
}>;
|
|
|
|
export type FieldThresholds = Readonly<{
|
|
p75LcpMs: number;
|
|
p75Cls: number;
|
|
p75InpMs: number;
|
|
minimumEligibleSamples: number | null;
|
|
}>;
|
|
|
|
export type FieldBudgetResult = Readonly<{
|
|
status: "PASS" | "FAIL_THRESHOLD" | "FAIL_UNVERIFIED";
|
|
passed: boolean;
|
|
}>;
|
|
|
|
export function evaluateFieldBudget(
|
|
report: Readonly<{ metrics: FieldMetrics; eligibleSamples: number }>,
|
|
thresholds: FieldThresholds,
|
|
): FieldBudgetResult {
|
|
if (
|
|
thresholds.minimumEligibleSamples === null ||
|
|
report.eligibleSamples < thresholds.minimumEligibleSamples ||
|
|
Object.values(report.metrics).some((value) => value === null)
|
|
) {
|
|
return Object.freeze({
|
|
status: "FAIL_UNVERIFIED",
|
|
passed: false,
|
|
});
|
|
}
|
|
const metrics = report.metrics as Readonly<{
|
|
p75LcpMs: number;
|
|
p75Cls: number;
|
|
p75InpMs: number;
|
|
}>;
|
|
const passed =
|
|
metrics.p75LcpMs <= thresholds.p75LcpMs &&
|
|
metrics.p75Cls <= thresholds.p75Cls &&
|
|
metrics.p75InpMs <= thresholds.p75InpMs;
|
|
return Object.freeze({
|
|
status: passed ? "PASS" : "FAIL_THRESHOLD",
|
|
passed,
|
|
});
|
|
}
|