Commit Graph
15 Commits
Author SHA1 Message Date
DongHyeonka f4d5761a2a fix(test-run): 실행마다 빌드·Playwright 출력 폴더를 따로 쓴다
문제: 빌드는 `dist`, `.generated/frontend-runtime`, `artifacts/release`·
`artifacts/quality`에 고정으로 쓰고, 다섯 Playwright 설정은 결과·report·
JUnit을 `artifacts/tests/<이름>/`에 고정으로 쓴다. 한 checkout에서 두
번째 e2e 실행이 시작하면 빌드 1단계가 첫 실행의 preview가 서빙 중인
`dist`를 지우고, Playwright가 `outputDir`을 비워 첫 실행의 trace를 지운다.
증거 파일도 늦게 끝난 쪽 것으로 섞인다(1105/12-04).

고른 방법: 변수 두 개로 나눈다(`scripts/lib/run-isolation.ts`).
- `TEST_RUN_ID`: Playwright 설정이 읽는다. 값이 있으면 그 실행의 결과·
  report·JUnit과 서빙할 빌드를 `.tmp/runs/<id>/` 아래 같은 상대 경로에
  둔다. 없으면 지금 경로 그대로라 게이트, CI upload, 증거 검사가 읽는
  곳이 바뀌지 않는다.
- `RUN_OUTPUT_ROOT`: 설정이 web server에만 넘긴다. 빌드 단계 전부
  (`build-frontend`, contract set, runtime config, SW asset 목록, SW 빌드,
  build manifest)와 `vite.config.ts`가 읽어 `dist`·생성 모듈·증거·Vite
  캐시를 그 아래에 쓴다. preview는 `--outDir`로 같은 `dist`를 서빙한다.
빌드 코드는 `TEST_RUN_ID`를 읽지 않는다. e2e worker가 저장소 복사본을
빌드할 때(fixture-builds, service-worker-builds) runner 환경을 물려받는데,
그 빌드는 복사본 자기 `dist`에 써야 하기 때문이다.
두 루트는 `.` 또는 `.tmp/` 아래만 받는다. git, Tailwind 소스 스캔(report
안 문자열이 CSS에 들어가지 않게), Vite watcher, vitest, 저장소 복사
helper가 모두 `.tmp`를 건너뛴다. service-worker-builds의 복사 제외 목록에
`.tmp`를 더했다(fixture-builds와 같아짐). build manifest의 경로는 빌드가
쓴 폴더 기준 상대 경로로 둔다.
`vite.config.ts`가 새로 가져오는 `scripts/lib/run-isolation.ts`는 저장소
일부를 임시 루트에 복사해 빌드하는 두 목록(초기 JS 측정
`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에도 더한다.
Storybook은 run ID가 있으면 `build:storybook`의 두 단계를 다른 `-o`로
돌린다. 같은 단계인지는 단위 테스트가 package script와 대조한다.
버린 대안: 운영 증거 경로(54개 스크립트, `config/ci/gates.json`)까지 run
ID로 옮기기. 게이트와 workflow upload가 고정 경로를 읽으므로 이번 범위
밖이다(아래 한계). 실행마다 저장소를 임시 폴더로 복사하기: 매번 수십
MB 복사와 node_modules 링크가 들고, 개발자가 보는 결과 위치가 사라진다.

위험·한계: 포트는 아직 고정이라 이 커밋만으로는 두 실행이 함께 돌지
못한다(다음 커밋). `ci:gate`와 증거 검사(`check:test-evidence`,
`verify:browser-capability-evidence`)는 기본 경로만 읽는다. run ID를 준
채 게이트를 돌리면 증거가 기본 경로에 새로 생기지 않아 게이트가 "not
freshly produced"로 실패한다(통과로 새지 않는다). Storybook 내부 캐시
(`node_modules/.cache`)는 여전히 공유한다. capability 설정
(`playwright.capabilities.config.ts`)은 test:browser-file-storage-removal이
capability와 함께 지운다. 설정 테스트는 그 파일이 있을 때만 그 설정을 읽고,
경로를 변수로 두어 타입 검사가 그 파일을 요구하지 않는다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts tests/unit/run-output-root-build.test.ts
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
corepack pnpm test:browser-file-storage-removal

Refs: 1105/12-04
2026-11-06 02:11:17 +09:00
DongHyeonka 799ab7f667 fix(dev): dev manifest를 기능 생성·제거 때 다시 쓰는 커밋 파일로 둔다
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.

고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
  그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
  둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
  돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
  절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
  contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
  Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
  server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
  같은 조건을 dev만 따로 두게 된다.

위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
  test:unit이 그 상태를 이름과 명령으로 알린다.

검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
  check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
  뒤 깨끗한 clone에서 돈다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
2026-11-05 03:30:56 +09:00
DongHyeonka c15345cb1d fix(dev): dev server가 설치된 기능의 contract set으로 release manifest를 낸다
문제
`create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를
선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을
그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이
집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가
CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를
보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의
test:browser-capabilities가 38건 실패하고("Execution context was
destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을
더하는 재실험(리뷰 조치 X2 #3)에서 찾았다.

고른 방법
- dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를
  시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려
  src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고,
  `/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에
  설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다.
- 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을
  import해야 하는데, Vite 설정이 그것을 불러오면 안 된다.
- build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다.
- 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가
  contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을
  다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다.

위험·한계
- dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다.
- 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다).

검증
- tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로
  바꾼다, 템플릿 그대로면 자리표시자와 같다).
- check:types, lint, check:architecture, check:ci 통과.
- 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
2026-11-05 01:33:38 +09:00
DongHyeonka e440ece9fe build(vite): 폐기 예정 build.rollupOptions를 rolldownOptions로 바꾼다
문제: 앱·Service Worker·선택 레시피 번들의 청크 설정이 Vite 8에서
@deprecated인 build.rollupOptions 별칭에 있었다(0929/13-07, 세 라운드
남음). 별칭이 지워지는 Vite 버전으로 올리면 청크 그룹과 treeshake 설정이
조용히 빠질 수 있다.

고른 방법: 세 곳의 키 이름만 rolldownOptions로 바꾼다. 내용은 그대로다.

위험·한계: 없음에 가깝다. 같은 설정의 정식 이름이다.

검증: 바꾸기 전후 빌드의 dist/assets 파일 이름이 모두 같다(해시가 같아
출력이 같다). service-worker-build-output 7건 통과,
check:optional-recipes PASS(레시피 예산 4개 그대로).

Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-07
2026-11-04 20:28:52 +09:00
DongHyeonka 9f9e459c4d perf(build): 운영 빌드가 react-router의 운영 빌드를 싣는다
문제: react-router 7.18.1의 exports는 모든 조건에서
dist/development/*를 가리킨다. 그 파일은 ENABLE_DEV_WARNINGS = true라
운영 번들의 초기 청크에 라우터 개발 경고 문구("You rendered descendant
…")가 들어 있었다. 운영 콘솔에 개발 경고가 뜨고, 초기 JS가 약 600 B 크다.

고른 방법: vite build일 때만 react-router-dom이 import하는 두 진입점
(react-router, react-router/dom)을 같은 패키지의 dist/production 파일로
alias한다. 경로는 react-router-dom에서 react-router를 resolve한 개발
진입점 옆에서 찾고, 파일이 없으면 빌드를 멈춘다. 개발 서버와 테스트는
개발 빌드를 그대로 써서 경고를 받는다.
버린 대안: 고정 경로 alias(리뷰 실험). 업그레이드로 배치가 바뀌면
조용히 깨진다. react-router에 production 조건을 요청하기는 시점을 정할
수 없어 이 alias를 지울 조건으로만 적었다.

위험·한계: exports 밖 경로를 쓴다. 업그레이드 때 배치가 바뀌면 빌드가
실패한다(조용히 개발 빌드로 돌아가지 않는다). Firefox·WebKit e2e는
돌리지 않았다.

검증: tests/unit/build-environment-bundle.test.ts가 빌드한 JS에 개발
경고 문구가 없음을 본다(고치기 전 chunk-KS7C4IRE 1개에서 실패).
같은 빌드(local-build) 초기 JS 201,552 → 200,939 B(−613 B), 파일 25개.
라우터를 쓰는 e2e 5개 spec 14건(app-shell, reference-route,
reference-save, scroll-restoration, platform-overview, chromium) 통과.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-07
2026-11-04 20:25:48 +09:00
DongHyeonka af6d0a9f01 perf(build): react-dom을 자기 청크로 빼 build id만 바뀐 release의 캐시 손실을 줄인다
문제: build id는 부트 실패 화면이 보여 주므로 render-boot-failure 청크에
들어간다. react-dom과 scheduler(약 56 KB gzip)가 같은 청크에 있어서
build id만 다른 두 빌드에서 boot·index·render-boot-failure 세 파일의
이름이 바뀌었다. 합계 99,785 B로 초기 JS의 49.4%다. 해시 자산은 1년
immutable로 캐시되는데, 재방문 사용자는 코드가 같아도 release마다 이만큼
다시 받았다. 1101 O1이 같은 것을 재고 채택을 권했지만 결정 기록이 없었다.

고른 방법: codeSplitting.groups에 react-dom·scheduler 그룹을 더한다
(includeDependenciesRecursively: false라 라이브러리 모듈만 묶는다).
같은 비교에서 바뀐 초기 JS가 44,297 B(22.0%)로 준다. 초기 JS는
201,857 → 201,552 B, 초기 파일 수는 25개 그대로다(react-dom 진입
모듈 1.3 KB 청크가 합쳐졌다).
버린 대안: build id를 JS에 넣지 않고 release-manifest.json에서만 읽기.
boot까지 바뀌지 않아 더 줄지만, 부트 실패 화면이 build id를 보여 주는
계약을 바꿔야 한다.

위험·한계: boot(39 KB)는 build id로 설정을 대조하므로 계속 바뀐다.
그룹 정규식은 pnpm의 node_modules 배치를 가정한다. 배치가 바뀌어 그룹이
비면 새 테스트가 실패한다.

검증: tests/unit/build-environment-bundle.test.ts가 build id만 다른 두
빌드에서 react-dom이 든 청크의 이름이 같고 그 청크가
render-boot-failure가 아님을 본다(고치기 전 실패). 부트 실패 화면
e2e(tests/e2e/boot-module-failure.spec.ts, chromium) 통과.
feature-shape-growth·design-system-initial-chunk·bundle-classification
통과. 두 빌드 비교는 docs/operations/performance-evidence.md에 기록했다.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-06
2026-11-04 20:23:54 +09:00
DongHyeonka 3f9c087798 docs(performance): 초기 청크 수의 HTTP/1.1 비용을 재고 묶지 않는 근거를 적는다 (1101/14.4)
문제
08-08은 초기 JS 바이트를 줄이는 대신 초기 파일을 16개에서 25개(entry
포함 26개)로 늘렸고, "HTTP/1.1 호스팅이면 다시 본다"를 남겼다. vite
preview도 HTTP/1.1이다. 비용을 잰 적이 없어 위험이 열려 있었다.

고른 방법
- 지금 빌드와 묶은 빌드 두 가지를 쟀다. (가) 08-08이 나눈 초기 primitive
  청크 4개(field·button·select·page-templates)를 하나로. (나) 묶을 수 있는
  초기 청크 14개를 하나로(entry·preload-helper·boot, 부트 실패 화면 closure,
  15-01 그룹은 뺐다). 같은 커밋을 임시 복사본에서 그룹 하나만 더해 빌드했다.
- 측정: vite preview(HTTP/1.1, gzip), Chromium CDP 네트워크 에뮬레이션
  (DevTools Fast 3G·Fast 4G 값), 새 context·캐시 없음, 첫 화면 =
  boot 셸이 사라지고 route h1이 들어온 시각. 세 빌드를 번갈아 7번씩, 중앙값.
  HTTP/2(node:http2, 자체 서명 인증서, gzip)도 같은 방법으로 쟀다.
- 결과(Fast 3G / Fast 4G 중앙값)
  - 지금 26개 202,782 B: 5,887 / 1,874 ms
  - (가) 23개 201,818 B: 5,426 / 1,764 ms
  - (나) 13개 198,673 B: 4,930 / 1,535 ms
  - HTTP/2: 지금 4,793 / 1,444, (가) 4,769 / 1,440, (나) 4,708 / 1,422 ms
- 판단: 묶지 않는다. 측정값과 판단을 performance-evidence.md에 적고,
  vite.config.ts의 "재검토" 주석이 그 절을 가리키게 한다.
  - (가)·(나)는 이 빌드의 청크 안 모듈 목록을 그대로 적어 만들었다. 규칙으로
    고를 방법이 없었다. boot 정적 closure는 design-system 배럴을 지나 갤러리
    전용 primitive까지 잡는다. rolldown `$initial` 태그는 entry가 앱을 dynamic
    import로 읽어서(09-03) 아무것도 잡지 않는다. boot.tsx를 entry로 더하면
    manifest 분류가 lazy 화면까지 초기로 센다(28개, 216,820 B, 예산 초과).
  - 고정 목록은 셸이 쓰는 primitive가 바뀔 때마다 맞춰야 하고, 낡아도
    실패하는 검사가 없다. 08-08이 같은 이유로 manualChunks 이름 고정을 버렸다.
  - 템플릿은 HTTP/2 이상 서빙을 전제로 본다. HTTP/1.1로만 서빙하는 제품은
    (나) 같은 그룹을 넣고 셸을 바꿀 때마다 다시 잰다고 문서에 적었다.
버린 대안
- (나)를 고정 목록으로 넣기: HTTP/1.1에서 Fast 3G 0.96초 빠르지만 숨은
  결합이다(위).
- (가)만 넣기: 0.46초. 같은 이유.

위험·한계
- HTTP/1.1로 서빙하는 다운스트림은 첫 화면이 Fast 3G에서 약 1초 늦다.
  이 커밋은 그 비용을 없애지 않고 숫자와 전제를 적는다. 호스팅 HTTP 버전을
  검사하는 게이트는 없다(FE-GATE-019 probe 밖).
- 측정은 이 머신의 loopback과 CDP 에뮬레이션이다. 연결 수립(TCP·TLS) 비용은
  CDP 지연에 들어가지 않는다. loadavg는 HTTP/1.1 측정 6~20, HTTP/2 측정
  3~6이라 두 표끼리는 비교하지 않는다. 각 표 안은 번갈아 재서 비교할 수 있다.

검증
- 빌드 바이트: classify-vite-bundle + gzipSync(check:bundle과 같은 계산).
  지금 빌드는 기준 202,770 B(local-build)와 맞다.
- 측정 스크립트와 로그는 커밋하지 않았다(worktree의 .tmp/ra/, 일회성).
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED.
- npx eslint vite.config.ts, npx tsc --project tsconfig.node.json --noEmit 통과.
2026-11-03 20:47:52 +09:00
DongHyeonka 8b7c6ebf6c perf(contracts): 검증 생략 목록을 부팅 경로 밖에서 만든다 (1101/07-03)
문제
- 93180f6(합친 커밋 d3ddc89)이 초기 JS를 늘렸다. 기능 모양 측정
  (scripts/scale/measure-feature-shape-growth.ts) 기준으로 기능 0개가
  202,376 → 202,526 B(+150)로, 기능 1개 추가분이 960 → 1,029 B로 늘었다.
  tests/unit/feature-shape-growth.test.ts의 1 KiB 상한을 넘는다.
- 원인은 두 가지다.
  - 부팅 때 도는 composeContractContributions가 검증기마다 생략 표시를
    읽고 목록을 만들었다(feature-platform 청크 +164 B). 이 목록을 쓰는
    곳은 플랫폼 개요 화면(lazy 라우트)뿐이다.
  - 공유 zod-validator.ts가 기능이 두 개가 되면 lazy 청크 하나로 따로
    나왔다. 모든 context-routes·feature-runtime import의 preload 목록에
    파일 이름이 하나 늘어 boot·feature-declarations 청크가 각각 약 25 B
    커졌다.

고른 방법
- 목록 계산을 src/contracts/unvalidated-payload.ts의
  listUnvalidatedPayloads(composed)로 옮긴다. 플랫폼 개요 화면만 이것을
  import한다. 결정의 뜻(생략한 operation이 조립 결과에서 목록으로
  나온다)은 그대로다. 계산 시점만 화면이 열릴 때로 미룬다.
  ComposedContractContributions.unvalidatedPayloads 필드는 뺀다.
- unvalidatedPayload 팩토리도 같은 모듈로 옮긴다.
- 조립기의 표시 검사도 뺀다. 이유가 빈 생략은 unvalidatedPayload가 만들
  때 거부한다(TypeError). 손으로 붙인 표시는 값이 "NONE"이 아니거나 이유가
  없어도 목록에 나온다(화면에는 "이유 없음"). 그래서 생략이 숨지 않는다.
  external-contract-runtime.ts에는 RuntimeValidator의 선택 타입 필드
  2개만 남는다.
- vite.config.ts에서 zod-validator.ts를 schema-registry.ts와 같은 lazy
  청크로 묶는다. 어댑터를 import하는 곳은 이미 schema-registry 청크를
  preload한다. includeDependenciesRecursively: false라서 다른 모듈은
  끌려오지 않고, 두 모듈 모두 부팅 그래프 밖이다.

버린 대안
- 조립기에 "NONE + 이유" 검사만 남기기: feature-platform 청크 +57 B gzip.
  검사를 팩토리와 목록으로 옮기면 0 B다. 손으로 붙인 잘못된 표시를
  부팅 때 거부하지 못하지만, 목록에는 나온다.
- zodValidator를 schema-registry.ts 안에 정의: 빌드 설정 없이 같은 결과가
  나오지만 결정한 위치(src/contracts/zod-validator.ts)와 다르고, 다음 단계의
  기능 생성 명령이 그 경로를 쓴다.
- 어댑터를 zod.ts에 두기: zod 입구는 초기 청크라 기능 0개 초기 JS가 는다.

위험·한계
- 조립 결과 타입에서 unvalidatedPayloads 필드가 빠진다. 93180f6 뒤 이
  필드를 쓴 코드는 listUnvalidatedPayloads로 바꿔야 한다. repo 안에서는
  화면과 테스트만 썼다.
- 손으로 만든 잘못된 표시(예: validation: "PARTIAL")는 더 이상 조립에서
  거부되지 않는다. 목록에만 나온다. 테스트 2건을 이 동작으로 바꿨다.
- 청크 묶음은 빌드 설정에 두 파일 경로를 적는다. 파일 이름을 바꾸면
  정규식도 함께 바꿔야 한다. 놓치면 바이트만 늘고 동작은 같다.
- 플랫폼 개요 화면을 열면 schema-registry 청크에 어댑터(351 B raw)가 같이
  온다.

검증
- 기능 모양 측정(0개 / 1개 추가분, gzip B):
  - ee81c44(07-03 전): 202,376 / 960
  - d3ddc89(07-03 합친 뒤): 202,526 / 1,029
  - 목록만 부팅 밖으로: 202,407 / 1,035
  - 청크 묶음 추가: 202,424 / 983
  - 조립기 검사 제거(이 커밋): 202,371 / 958
- feature-shape-growth.test.ts 6건 통과.
- 07-03 테스트 3파일 33건 통과(zod-validator, external-contract-runtime,
  starter-platform-overview-page).
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
  270파일 3,203건, tests/integration 12파일 158건(pnpm을 띄우는
  security-followup-archive 제외), tests/architecture 7파일 33건 통과.
- tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
  eslint 0. 아키텍처 그래프 검사(pnpm 대신 exec stub) 413 모듈 PASS.
  check-registries PASS(compatibility=none).
- 본 빌드 초기 JS gzip 202,371 B(26파일). raw 644,782 B로 ee81c44 측정과
  같다.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03
2026-11-03 01:58:38 +09:00
DongHyeonka 51941a547b perf(build): 갤러리 전용 primitive를 초기 청크에서 뺀다 (1101/08-08)
문제
셸은 design-system/index.ts에서 Button·Drawer·Select를 import한다. 번들러는
배럴이 다시 내보내는 모듈을 side effect가 있다고 보고 모두 실행 순서대로
싣는다. 그래서 갤러리와 예제 화면만 쓰는 Tooltip·Menu·Toast·Tabs·Card·
Alert 등이 초기 청크(design-system-*.js)에 있다. 초기 JS는 203,818 B로
예산 204,800 B에서 982 B 남았다. 파일을 나눈 앞 커밋만으로는 바뀌지
않는다.

고른 방법
- vite.config.ts의 treeshake.moduleSideEffects 규칙으로
  src/presentation/design-system/ 아래 .ts·.tsx를 side effect 없음으로
  선언한다. 이 파일들은 컴포넌트·아이콘·토큰 목록 선언만 한다. CSS
  import는 bootstrap/main.tsx 한 곳뿐이고 이 범위 밖이다.
- 결정: 바이트를 줄인다. 예산이 걸린 지표는 바이트이고, 늘어나는 청크는
  진입 청크의 preload 목록(__vitePreload)으로 병렬로 받으므로 HTTP/2에서
  왕복이 늘지 않는다. 재검토 조건(HTTP/1.1 호스팅이면 청크 수가 비용)을
  설정 주석에 적었다.
- 새 테스트 tests/unit/design-system-initial-chunk.test.ts
  - 실제 vite build를 돌려 초기 청크에 lazy 화면 전용 클래스 13개가
    없는지 본다. 셸의 ui-drawer가 있는지를 같이 봐서 빈 결과로 통과하지
    않게 한다.
  - design-system 파일에 효과만을 위한 import(import "x")가 없는지 본다.
    선언 아래에서는 그런 import가 모듈과 함께 사라지기 때문이다.
- build-environment-bundle 테스트(13-06)는 design-system-* 청크 이름을
  찾았다. 그 청크가 없어져서, Button 코드(ui-button--pending)가 든 청크가
  build id를 바꿔도 같은지로 바꾼다. 두 build id로 빌드해 보면 바뀌는
  파일은 boot·index·render-boot-failure 셋뿐이다.
버린 대안
- 파일 분리만: 실측 효과 없음(203,824 B, 16개).
- manualChunks로 청크 이름을 고정: 제품이 primitive를 쓸 때마다 다시
  맞춰야 한다.
- 청크 수 줄이기: 15-01 청크 그룹과 같이 봤다. rolldown의 $initial 태그는
  main.tsx가 앱을 동적으로 import해서(09-03) 아무것도 잡지 않았다(25개,
  +16 B). 모듈 그래프로 boot 정적 closure를 만들면 배럴을 따라 갤러리
  primitive까지 잡혀 다시 초기 청크로 간다. 바이트 손해 없이 줄일 방법을
  찾지 못해 늘어난 수를 둔다.

위험·한계
- 초기 청크가 16개에서 25개로 는다(결정 당시 추정 21개보다 많다. 앞
  커밋의 파일 분리로 button·field·select가 따로 나온다). 전체(초기+lazy)
  gzip은 232,231 → 236,253 B로 4,022 B 는다. 첫 화면만 보는 사용자는
  2,718 B 덜 받고, 모든 화면을 도는 사용자는 청크 경계 비용만큼 더 받는다.
- 새 파일에 모듈 최상위 효과(전역 등록 등)를 넣으면 이 선언이 그 효과를
  지울 수 있다. 효과만을 위한 import는 테스트가 막지만, 최상위 문장은
  막지 않는다. 설정 주석에 적었다.
- lazy 청크 예산(청크당 122,880 B)에는 영향이 없다. 가장 큰 lazy 청크는
  8,431 B다.
- 화면 변화 없음: 같은 코드를 다른 청크에서 받는다.

검증
- RED(앞 커밋 상태): 새 테스트가 실패. 초기 청크에 ui-alert·ui-badge·
  ui-card·ui-data-table·ui-menu·ui-progress·ui-radio-group·ui-switch·
  ui-tabs·ui-toast·ui-tooltip 11개가 있었다.
- GREEN: design-system-initial-chunk·build-environment-bundle·
  design-system-contract·product-index-entrypoints·bundle-classification·
  sub-path-deployment·product-feature-selection-build 통과.
- 빌드(flock, build-frontend.ts): 초기 JS gzip 203,818 → 201,100 B
  (-2,718 B, 예산 여유 982 → 3,700 B), 초기 청크 16 → 25개, lazy 청크
  17 → 20개.
- node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과.
- Chromium e2e(vite preview, 위 빌드): ui-gallery·design-system-
  interactions·app-shell·accessibility·platform-overview·reference-form·
  reference-route·reference-save·theme·typography·responsive·compact-
  smoke·i18n·scroll-restoration 55/55 통과.
- tsc(app·node·test), 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08
2026-11-03 01:24:31 +09:00
DongHyeonka 298201f3ee perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제
초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의
feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper
포함), HTTP 계약 contribution, application input 팩토리, route codec까지
모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서
예산을 넘었다.

고른 방법
- 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime
  계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼
  contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API
  계약, adapter contribution, contract contribution)는 feature-runtime.ts로
  옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의
  route handle에 실어 route와 함께 적재한다.
- 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route
  모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에
  화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route
  모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은
  적재하지 않는다.
- 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract
  registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다
  (installed-contract-contributions.ts). 선언하지 않은 contract package를
  적재하면 거절한다.
- 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는
  installed-feature-runtime-registries.ts의 async 함수로, Node·테스트·
  registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로
  둔다. src에서 후자를 import하면 새 아키텍처 규칙
  boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은
  route 로더에서 async 함수를 불러 결과를 prop으로 받는다.
- vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy
  청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면
  기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는
  플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져
  템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을,
  feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다.
  render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03:
  애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다).

버린 대안
- 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는
  lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라
  버렸다.
- 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를
  공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다.
- 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당
  -60 B 수준이라 그룹 없이 목표에 못 미쳤다.
- 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만
  i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다.
- boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두
  초기로 세어 218,303 B가 됐다.

위험·한계
- FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로
  실행부를 옮겨야 한다(BREAKING CHANGE).
- 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라
  그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트·
  테스트)로 옮겨 간다.
- 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼
  구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가
  재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다.
- 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가
  비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿
  총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다.
- config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직
  installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인
  때 고친다. check-registries는 통과한다.
- 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의
  98.8%다.

수치 (vite build, classifyViteJavascript + gzipSync 기본 수준)
- 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B
- 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741)
- 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648)
- 참조 복사본 +5: 205,629 B
- lazy JS: 23,516 B -> 28,204 B

검증
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
  "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or
  equal to 1024
- GREEN: 같은 테스트 통과(+741 B)
- node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과
- node scripts/run-vitest.ts run tests/component tests/features
  tests/integration tests/contract tests/runtime-schema tests/architecture
  tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출):
  109파일 787 통과
- npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과
- npx eslint 바뀐 파일 통과
- check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이
  boot.tsx의 import를 거절하는 것 확인
- check-adapter-inventory, check-registries, verify-documentation-readiness,
  check-ci-contract: PASS
- e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트):
  55 통과
- storybook build 성공
- 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026),
  pnpm 경로의 check:bundle, test:system

BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages,
  loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약
  (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로
  만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle
  codecs로 옮긴다. contracts에는 contractPackages를 추가한다.
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01,
  16-structure-patterns.md 9절
2026-11-01 21:57:53 +09:00
DongHyeonkaandClaude Opus 5.5 9c8a5f417a fix(bootstrap): show the boot error shell when the app graph fails to evaluate (09-03)
A module that threw while evaluating stopped main.tsx before boot() ran, so the
static loading shell stayed up. The entry now imports the app (boot.tsx)
dynamically and renders the shell on rejection; the shell reads boot messages
without the feature catalog. The preload helper gets its own chunk so lazy
chunks do not import the per-build entry, and the bundle budget counts the
entry's dynamic imports as initial JS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:54:40 +09:00
DongHyeonkaandClaude Opus 5.5 e215c849fb fix(build): serve config and manifest URLs under the router base path (13-07)
A /app/ build still fetched /config.json and /release-manifest.json and failed
at boot. The config URL default and a root-relative profile manifest URL now
follow VITE_ROUTER_BASE_PATH, and an explicit config URL outside the base fails
the build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:38:34 +09:00
DongHyeonkaandClaude Opus 5.5 2ec59ad9ee fix(build): read VITE_* values by key and refuse undeclared ones (13-06)
getBuildConfig defaulted to the whole import.meta.env, so Vite inlined every
loaded VITE_* value, read or not. Values are now read by key, a lint rule bans
whole-object references in src, and vite.config refuses VITE_* names missing
from ENV_REGISTRY. A build test pins the values that must stay in the bundle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:35:54 +09:00
DongHyeonkaandClaude Opus 5 dfb7734674 fix: run the provider sandbox and admit a release to a named environment
The provider sandbox never ran. bubblewrap 0.9.0 stops parsing an `--args`
file at the first non-option and never hands the remainder back, so the
command written into that file was silently dropped: bwrap printed its usage
text, exited 1, and the provider produced no evidence at all. The options
still travel in the args file — that is what keeps host paths and credentials
out of `/proc/<pid>/cmdline` — but the command now rides on real argv, and
`encodeProviderBwrapInput` refuses a `--` so the drop cannot come back.

The scope wrapper then could not exit. It read the supervisor's liveness pipe
through `fs`, which runs a blocking `read(2)` on a threadpool thread; the
supervisor holds that pipe open for the scope's whole life, so the read never
returned and closing the descriptor did not interrupt it. Once bubblewrap
finished the wrapper deadlocked in `process.exit`, the scope outlived the
provider, and a completed run was reported as a timeout kill. The channel is
now read through the event loop, so teardown is observable and terminal.

Creation modes were left to the ambient umask. `mkdir(mode)` and `open(mode)`
are requests the kernel subtracts the umask from, so a runner exporting a
restrictive umask produced directories it could not enter and handed `tar` a
file it could not re-open. Private modes are pinned instead of inherited.

Promotion cleanup deleted before it checked. Removals run through a pinned
descriptor, so a leaf substituted after validation had this promotion's exact
five destroyed first and the substitution reported afterwards, leaving a
half-emptied directory a retry could not tell from a completed one. The name
is re-bound to the inode before anything is removed, so the failure is total.

Separately, release coherence proved the artifacts agreed with each other but
never that they belonged where they were going: a build whose runtime document
said `APP_ENV: local`, `AUTH_MODE: demo` and a loopback API is coherent with
itself and passed every gate. `public/` is copied verbatim into `dist/`, so
that local document shipped with every build regardless of what the build was
for. Runtime configuration now comes from a declared profile, and FE-GATE-027
refuses to admit an artifact to an environment it does not match — including
refusing an undeclared destination, so nothing is admitted by omission.

`REQUEST_TIMEOUT_MS` and `VITE_ROUTER_BASE_PATH` were validated and then
dropped: the V3 executor ran every operation on its contract's own deadline,
and Vite emitted root-absolute assets for a sub-path deployment. The timeout is
now a ceiling that may tighten a contract but never loosen one, and one base
path feeds the router, the Service Worker scope and the asset base together.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 16:38:19 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00