Commit Graph
5 Commits
Author SHA1 Message Date
DongHyeonka 138c195fcd fix(examples): 릴리스 신원 칸의 자리를 미리 잡고 lab이 대상 화면 직접 진입 CLS를 잰다
문제: 플랫폼 구성 화면(lab 대상)은 getReleaseSummary()가 끝날 때까지
릴리스 신원 칸을 "상태" 한 칸으로 그리고, 끝나면 hint 줄이 있는 네 칸으로
바꾼다. 제목이 보인 뒤 약 30~100 ms에 grid가 hint 한 줄만큼 커져 아래
section이 21 px 내려간다(layout shift 0.00461, 리뷰 15-platform-shift
16회). lab은 `/`에서 클릭으로만 들어가고, 클릭 뒤 500 ms 안의 shift는
hadRecentInput이라 CLS에서 빠지므로 0을 낸다. `/` 밖의 라우트 CLS는 어느
게이트도 보지 않는다.

고른 방법:
- 화면: 요약 전·실패 때도 같은 네 칸(빌드·릴리스·설정 스키마·계약 집합
  다이제스트)을 같은 hint 줄 구성으로 그린다. 값만 "확인하고 있습니다."
  / "확인하지 못했습니다." / "—"다. 상태 문장은 가장 좁은 칸(13rem)에서도
  한 줄이 되게 짧게 했다. dl에 aria-busy를 둔다. 시각 테스트는 이미
  `main [aria-busy='true']`가 0개가 될 때까지 기다리므로, dt만 보고 찍던
  대기가 값이 채워진 뒤로 유지된다.
- lab: run마다 대상 라우트를 새 context에서 직접 열고 heading 뒤 network
  idle까지의 CLS를 잰다(metrics.targetDeepLinkCls, 중앙값,
  context.sampling.targetDeepLink에 표본). evaluateLabBudget가 lab.cls
  임계값으로 판정한다. 클릭 시계(상호작용 중앙값)와 대상 라우트는 그대로다.
- 컴포넌트 테스트: 요약 전과 후의 칸 이름·hint 유무가 같다. 실패 테스트는
  빌드 칸의 값으로 본다. 단위 테스트: 직접 진입 CLS가 임계값을 넘으면
  lab 판정이 실패한다.
버린 대안: 릴리스 요약을 동기로 읽기 — getReleaseSummary()가 비동기
포트 계약이라 포트를 바꿔야 한다. 클릭 run에서 hadRecentInput을 무시 —
CLS 정의와 달라져 field 값과 비교할 수 없다.

위험·한계: lab 시간이 run마다 cold navigation 하나(lab 조건 약 2~3초)
늘어 5회면 +10~15초다. 직접 진입 CLS 예산은 0.1이라 0.0046 같은 작은
shift는 실패시키지 않고 lab.json에 값으로만 남는다. layout shift 0건은
lab 값(0)과 15-platform-shift 방법으로 확인해야 한다. 상태 문구가 바뀌어
"런타임 정보를 확인하고 있습니다." 문장은 이 화면에서 사라졌다(홈 화면
문구는 그대로). lab.json 스키마 문서(config/schemas/lab-performance.schema.json)에
새 칸을 필수로 더했다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/component/starter-platform-overview-page.test.tsx
tests/unit/performance-budgets.test.ts
corepack pnpm build && corepack pnpm test:performance -- --runs=5
(lab.json metrics.targetDeepLinkCls가 0인지)

Refs: 1105/15-01
2026-11-06 01:23:48 +09:00
DongHyeonka d549ceb330 perf(examples): 플랫폼 구성 화면이 제목을 먼저 그리고 실행부 표만 기다린다
문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).

고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
  제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
  snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
  표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
  청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
  실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
  이유), hover 프리페치(키보드·직접 진입에 효과 작음).

위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
  직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
  페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
  약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.

검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
  보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
  eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
  test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
  부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
  LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
  홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
  잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
  feature-runtime·reference-schemas는 제목 뒤에 받는다.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
2026-11-04 22:59:03 +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 d3ddc8957f feat(contracts): zod 검증기 어댑터를 공유하고 검증 생략을 이름으로 드러낸다 (1101/07-03)
문제
- zod 스키마를 RuntimeValidator로 바꾸는 zodValidator가 참조 기능의
  reference-schemas.ts 안에만 있다. 기능끼리 import가 금지라 새 기능은
  복사하고, 복사본은 이미 갈라졌다(tests/helpers 복사본은 성공 값을
  structuredClone하지 않는다). 참조 기능을 지우면 어댑터도 사라진다.
- RuntimeValidator<T>는 schemaId와 safeParse만 요구한다. 아무것도
  검증하지 않는 검증기도 조립을 통과하고, 검증을 생략했다는 사실이
  타입·이름·조립 결과 어디에도 남지 않는다.

고른 방법 (C: 공유 어댑터 + 생략 표시)
- zodValidator를 src/contracts/zod-validator.ts로 옮긴다. 참조 기능과
  tests/helpers/external-contract-fixture.ts가 이것을 import한다. 동작은
  참조 기능 쪽 원본 그대로다(성공 값 structuredClone, 경로 배열, code
  문자열). tests/helpers도 이제 성공 값을 복사한다.
- unvalidatedPayload(schemaId, reason)를 external-contract-runtime.ts에
  둔다. 만든 검증기에는 validation: "NONE"과 unvalidatedReason이 붙는다.
  zod가 필요 없어서 검증기 프로토콜 옆에 뒀다.
- composeContractContributions가 이 표시가 붙은 검증기를
  unvalidatedPayloads(featureId, contractId, validator, schemaId, reason)로
  내놓는다. HTTP의 input·output·problem과 이벤트의 envelope·payload를 모두
  본다. 표시가 "NONE"이 아니거나 이유가 비어 있으면 조립을 거부한다.
- 플랫폼 개요 화면(스타터 화면)의 계약 절에 "런타임 검증을 생략한 계약"
  표를 둔다. 목록이 비면 그리지 않는다.

버린 대안
- (B) 공유 어댑터만: 검증 생략이 여전히 보이지 않는다.
- (D) 브랜드 타입으로 zodValidator가 만든 검증기만 받기: 외부 패키지의
  자체 검증기까지 막아 §4 설계와 충돌한다.

위험·한계
- 표시 없이 손으로 쓴 통과 검증기(리뷰 실험 L5)는 여전히 조립을
  통과하고 목록에도 없다. 이 변경은 생략을 막지 않는다. 이름 있는 길을
  만들어 그 길로 생략한 것만 드러낸다.
- 공개 계약 추가: RuntimeValidator에 선택 필드 2개,
  ComposedContractContributions에 필드 1개, 새 export zodValidator·
  unvalidatedPayload·UnvalidatedPayloadEntry. 기존 호출자는 바뀌지 않는다.
  ComposedContractContributions를 손으로 만드는 코드는 새 필드를 채워야
  한다(repo 안에는 없다).
- 초기 JS gzip 204,586 → 204,745 B(+159). 예산 204,800까지 55 B 남는다.
  플랫폼 개요 청크 4,625 → 4,750 B.
- 참조 기능은 모든 검증기가 검증하므로 화면 모양은 그대로다. 시각 회귀는
  돌리지 않았다.
- tests/unit/second-api-feature-registries.test.ts의 V2 codec 통과 검증기는
  그대로 둔다(16-01이 그 파일을 넓힌다).

검증
- RED(수정 전): zod-validator.test.ts "Cannot find module
  '../../src/contracts/zod-validator.ts'", external-contract-runtime.test.ts와
  starter-platform-overview-page.test.tsx "unvalidatedPayload is not a
  function". 3파일 모두 실패.
- GREEN: 같은 3파일 33건 통과.
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
  268파일 3,189건, tests/integration 12파일 158건(pnpm을 띄우는
  security-followup-archive 제외), tests/architecture 7파일 33건 통과.
  tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
  eslint 0. check-registries PASS(compatibility=none), verify-documentation
  PASS_SCOPED, check-adapter-inventory PASS. 아키텍처 그래프 검사(pnpm 대신
  exec stub) 383 모듈 PASS.
- 참조 기능 삭제 모의: scripts/test-sample-removal.ts의 삭제 목록(기능
  폴더, tests/features, reference-context, SAMPLE_EXTRAS)을 복사본에 적용.
  src/contracts/zod-validator.ts가 남고, tsc app·test 오류 0, 어댑터·조립·
  플랫폼 개요·HTTP 시나리오 테스트 4파일 35건 통과.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03, 5.3
2026-11-03 01:34:32 +09:00
DongHyeonka ca74caa2a8 test(component): 플랫폼 화면 테스트를 테스트 전용 페이지로 옮긴다 (0929/10-02)
문제: 라우터·chunk 복구·render 경계·앱 셸·런타임 트리 테스트가 스타터
화면(`/`의 h1, 홈의 "플랫폼 구성 보기" 링크, /examples/ui·states)을
대상으로 쓴다. 문서는 스타터 화면을 "페이지 단위로 교체 가능"하다고 하는데,
제품이 화면을 바꾸면 스타터와 무관한 플랫폼 테스트가 깨지고 동기화 때마다
같은 파일이 충돌한다(두 제품 기록).

방법: tests/helpers/fixture-feature.tsx에 테스트 전용 public 페이지 4개를
더했다. 메뉴에 나오는 지연 로드 페이지 2개(제목 h1, 런타임 릴리스 표시),
chunk 로드 실패 페이지, render 결함 페이지다. 플랫폼 테스트는 이미 쓰던
방식대로 생성 인덱스를 mock해 이 기능을 설치하고 그 페이지를 쓴다.
스타터 화면 자체를 검사하던 것(홈 시작 링크, 홈·플랫폼 구성의 릴리스 로딩
실패, 인증 예제의 복귀 URL, 상태 갤러리 제목 구조, 플랫폼 구성 화면)은
starter-pages.test.tsx와 starter-platform-overview-page.test.tsx로
모았다. 제품은 스타터 화면과 함께 starter-* 파일을 지우면 된다.
fixture는 design-system 배럴 대신 page-header.tsx를 직접 import한다.
배럴이 설치 카탈로그를 거쳐 mock된 생성 인덱스를 다시 불러 mock 팩토리가
자기 자신을 기다린다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
화면을 바꾸면 검사는 여전히 깨지거나 사라진다.

위험: 플랫폼 경로(createRegisteredRoutes의 platformChildren)를 지나는
화면 이동 테스트가 줄고 context 라우트 경로로 옮겨 갔다. `/`와 not-found는
여전히 플랫폼 경로로 돈다. ui-gallery-page는 이제 component 테스트에서
렌더되지 않는다(e2e·visual이 본다). sibling chunk 초기화 테스트는
key={definition.routeId}를 지우면 여전히 실패한다(변이 확인).

검증: RED는 템플릿 복사본에서 home-page.tsx와 examples/*를 다른 화면으로
바꾸고 test:component를 돌렸다. 7파일 20개 실패(router 5, route-status 4,
platform-overview 7, app-shell·async-surface·chunk-recovery·
runtime-application 각 1). GREEN은 같은 조작에서 starter-* 2파일 12개만
실패하고, starter-*를 지우면 34파일 216개 전부 통과. worktree에서
tests/component 36파일 228개 통과, tsc -p tsconfig.test.json 통과, 바꾼
파일 eslint 통과.
2026-11-03 01:18:21 +09:00