From 287dc6fa9b137197ed491939f656c88e9e7ace2c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 02:59:03 +0900 Subject: [PATCH] =?UTF-8?q?build(perf):=20=EC=B4=88=EA=B8=B0=20JS=20?= =?UTF-8?q?=EC=98=88=EC=82=B0=EC=9D=84=20202=20KiB=EB=A1=9C=20=EC=98=AC?= =?UTF-8?q?=EB=A6=B0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 1105 PR B의 수정이 템플릿 초기 JS를 1,184 B 늘렸다(202,927 → 204,111 B, 초기 파일 26 → 27개, `0fee3fe`). 예산 204,800 B까지 남은 여유가 689 B로, 기능 하나가 더하는 768 B보다 작다. FE-GATE-020의 생성 기능 드릴이 기능 둘을 더하면 205,463 B가 되어 check:bundle이 "over by 663"으로 실패한다. PR A 끝(`a793b83`)에서는 통과했다. 늘어난 곳(desktop, 2026-11-06, 커밋마다 `--initial-baseline`으로 잼): - 1105/03-01 `ab0d4a1` +327 B: 조립 때 `refusedBeforeWrite` code 검사 - 1105/08-03 `7ce9bf1` +293 B, 초기 파일 +1: `navigation-policy` 공유 청크 - 1105/02-01 `f738348` +251 B: scope closer 진단 - 계약·앱 코어 브랜치를 합칠 때 +148 B - 나머지 +165 B: realtime +72 B, 05-01 +46 B, 테스트 +23 B, 03-02 +15 B와 합칠 때의 압축 차 고른 방법: `config/performance/budgets.json`의 `initialJsGzipBytes`를 204,800 → 206,848 B(202 KiB)로 올린다(메인 세션 결정, 2026-11-06). 늘어난 바이트는 비대가 아니라 검사와 진단 코드다. 이유와 재검토 조건을 `docs/operations/performance-evidence.md`에, 계약 행을 CHANGELOG 미출시 절에 적는다. 초기 파일 상한을 26 → 32로 올린 `2fef27d`와 같은 방식이다. 버린 대안: 줄이기. 08-03 청크를 기존 청크 그룹에 넣으면 약 240 B가 돌아올 것으로 본다(추정, 재지 않음). 663 B에는 모자라서 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 설계 변경이 더 필요하다. 리뷰 라운드 중간의 설계 변경은 다음 라운드의 숫자를 흐린다. 위험·한계: - 올린 뒤 여유는 템플릿 그대로 2,737 B(768 B 기능 셋), 드릴이 기능 둘을 더한 뒤 1,385 B다. 기록 대조 허용치 256 B(1105/15-02)는 두 여유보다 작다. - 재검토 조건: 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다. - 기준선 기록(`initialJavascript`)은 앞 커밋 `0fee3fe`이 측정 스크립트 `--initial-baseline --write`로 다시 썼다. 이 커밋은 기록을 바꾸지 않는다. 검증: desktop batch에서 확인. corepack pnpm ci:gate FE-GATE-020 (CI env) node scripts/run-vitest.ts run tests/unit/performance-budgets.test.ts tests/unit/check-bundle-output.test.ts tests/unit/feature-shape-growth.test.ts Refs: 1105/15-02 --- CHANGELOG.md | 1 + config/performance/budgets.json | 2 +- docs/operations/performance-evidence.md | 12 +++++++++++- tests/unit/feature-shape-growth.test.ts | 2 +- 4 files changed, 14 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c9aa9e46..58db029f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,6 +53,7 @@ | [계약] **BREAKING** | `artifacts/tests/a11y.json`이 schemaVersion 2다. 실패 화면으로만 axe를 돌린 라우트(일반 답이 없는 상세 라우트)는 `scope`에서 빠져 `notChecked`(`{ routeId, reason }`)에 들어간다. 라우트 test가 자기 상태를 `artifacts/tests/a11y-data-state/.json`에 남긴다. 위 "먼저 할 일" 5단계 (1103/11-01) | `scripts/write-a11y-report.ts`, `scripts/lib/a11y-data-state.ts`, `scripts/contracts/release-artifacts.ts`, `tests/e2e/accessibility.spec.ts` | `757d1c7` | | [계약] | lab(FE-GATE-026)이 기능 라우트 첫 진입을 잰다. 대상은 설치된 기능의 첫 공개 내비게이션 라우트(`labFeatureRoute`, 템플릿에서는 `EXAMPLES_UI`)이고 예산은 `budgets.json`의 `lab.featureRouteInteractionMs` 500 ms다. 그런 라우트가 없으면 `measured: false`로 남기고 판정하지 않는다. run마다 대상 라우트를 직접 열어 CLS도 잰다(`metrics.targetDeepLinkCls`, 예산 `lab.cls`). lab은 스크롤바를 보이게 띄운다. `lab.json` schema에 새 칸이 필수다 (1105/15-04, 1105/15-01, 1105/15-05) | `config/performance/budgets.json`, `config/schemas/lab-performance.schema.json`, `scripts/test-performance.ts`, `scripts/lib/lab-performance.ts` | `81701ad`, `138c195`, `e02f252` | | [계약] | 초기 JS 기록 대조(`tests/unit/feature-shape-growth.test.ts`)의 합계 허용 오차가 1%(약 2 KB)가 아니라 256 B다. 초기 JS를 수백 바이트 움직이는 변경은 기록을 다시 쓴다 (1105/15-02) | `scripts/scale/measure-feature-shape-growth.ts` | `46359a1` | +| [계약] | 초기 JS 예산(`initialJsGzipBytes`)이 204,800 B가 아니라 206,848 B(202 KiB)다. 이 묶음의 검사·진단 코드가 초기 JS를 1,184 B 늘려 생성 기능 둘을 더한 드릴(FE-GATE-020)이 예산을 넘었다. 템플릿 기록은 204,111 B·초기 파일 27개로 다시 적었다. 예산을 복사한 제품은 자기 값을 그대로 두거나 같은 이유로 올린다. 재검토 조건은 `docs/operations/performance-evidence.md` (1105/15-02) | `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json` | `0fee3fe` | | [계약] | `test:all`이 `test:coverage`(FE-GATE-005)가 도는 Vitest 경로를 모두 돈다(`tests/features` 전체, `tests/scripts`, browser-soak 계약 테스트). `tests/unit/test-all-paths.test.ts`가 대조한다 (0929/10-05) | `package.json` | `7ead8d3` | | [계약] | 제품 기능 제거 드릴(`test:sample-removal -- --feature=`)의 잔여 판정: `src`는 기능 ID·폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 그 기능 폴더에서 import하는 파일만이다. 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여가 아니다. 참조 기능은 전처럼 넓게 찾는다 (1105/16-04) | `scripts/lib/feature-residue.ts`, `scripts/test-sample-removal.ts` | `b45d6a0` | | [계약] **BREAKING** | `InstalledHttpContract`의 `contract.responseEnvelope`가 필수다. 참조 기능과 테스트 fixture는 `"NONE"`을 적는다. 조립은 빠진 값을 전처럼 `NONE`으로 읽는다. 위 "먼저 할 일" 1단계 (1103/16-01) | `src/contracts/external-contract-runtime.ts`, `scripts/create-feature.ts`, `src/features/reference-feature/contracts/` | `56272e8` | diff --git a/config/performance/budgets.json b/config/performance/budgets.json index 26b5a1d5..20e06f40 100644 --- a/config/performance/budgets.json +++ b/config/performance/budgets.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, "bundle": { - "initialJsGzipBytes": 204800, + "initialJsGzipBytes": 206848, "initialJsFiles": 32, "lazyChunkGzipBytes": 122880 }, diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 5c231aee..081b6f40 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -3,7 +3,7 @@ Performance evidence is deliberately split by measurement context: - `bundle.json` records production build output and enforces initial JavaScript - at 200 KiB gzip, the number of initial JavaScript files (`initialJsFiles`), + at 202 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 @@ -41,6 +41,16 @@ Performance evidence is deliberately split by measurement context: 돌리고 같은 변경에 넣는다. - 여유는 예산에서 `gzipBytes`를 뺀 값이다. 그것을 `perFeatureGzipBytes`로 나누면 더 넣을 수 있는 기능 수다. 새 context마다 `perContextGzipBytes`가 더 든다. +- 예산 값 `initialJsGzipBytes`는 206,848 B(202 KiB)다. 1105 수정 라운드에서 + 204,800 B를 올렸다(2026-11-06). 그 라운드의 검사·진단 코드(조립 때 code 검사 + 1105/03-01, 홈 시작 링크 08-03, scope closer 진단 02-01 등)가 초기 JS를 + 1,184 B 늘려, 생성 기능 둘을 더하는 FE-GATE-020 드릴이 예산을 663 B + 넘었다(그 라운드를 합친 빌드에서 잼, 기록 커밋 `0fee3fe`). 버린 대안은 런타임 + 검사를 빌드 시점으로 옮겨 줄이기다. + 라운드 중간의 설계 변경이라 다음 라운드 숫자를 흐린다. 다시 볼 때: 예산을 또 + 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 + 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 + 않는다. 결정 기록은 `docs/reviews/2026-11-05-maturity-review/README.md` 16절이다. - 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다. lazy chunk 예산은 파일마다 120 KiB(`lazyChunkGzipBytes`)다. diff --git a/tests/unit/feature-shape-growth.test.ts b/tests/unit/feature-shape-growth.test.ts index 22ad957f..c8df8f69 100644 --- a/tests/unit/feature-shape-growth.test.ts +++ b/tests/unit/feature-shape-growth.test.ts @@ -128,7 +128,7 @@ describe("feature-shape growth measurement (11-04)", () => { /** * 15-01. The initial budget (config/performance/budgets.json) is a fixed - * 200 KiB for the whole app, so what one installed feature adds to the + * 202 KiB for the whole app, so what one installed feature adds to the * initial chunk decides how many features fit. Before 15-01 every feature's * 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