Files
clean-architecture-frontend…/.dependency-cruiser.json
T
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

360 lines
18 KiB
JSON

{
"forbidden": [
{
"name": "domain-is-framework-neutral",
"comment": "domain holds framework-neutral models and pure policies. Keep the dependency out: move the code to application, or pass the value in from there.",
"severity": "error",
"from": {
"path": "^src/domain"
},
"to": {
"path": "^(src/(application|presentation|adapters|bootstrap)|react|react-dom|@tanstack)"
}
},
{
"name": "application-does-not-know-concrete-runtime",
"comment": "application owns use cases and the ports they need. Declare a port under src/application/ports and let src/bootstrap pass the concrete adapter.",
"severity": "error",
"from": {
"path": "^src/application"
},
"to": {
"path": "^(src/(presentation|adapters|bootstrap)|react|react-dom|@tanstack)"
}
},
{
"name": "presentation-does-not-know-adapters",
"comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.",
"severity": "error",
"from": {
"path": "^src/presentation/(?!adapters/query)"
},
"to": {
"path": "^(src/(adapters|bootstrap)|@tanstack)"
}
},
{
"name": "page-templates-own-layout-only",
"comment": "Page templates own layout only. Take data and actions as props from the page that uses the template.",
"severity": "error",
"from": {
"path": "^src/presentation/templates"
},
"to": {
"path": "^(src/(application|adapters|bootstrap)|src/presentation/adapters|@tanstack)"
}
},
{
"name": "icon-vendor-is-facade-only",
"comment": "VD-05. lucide-react is imported by the icon vendor facade only; product code uses the semantic icons from the design-system index, so replacing the vendor touches one file.",
"severity": "error",
"from": {
"path": "^src",
"pathNot": "^src/presentation/design-system/icons/vendors/lucide\\.tsx$"
},
"to": {
"path": "^lucide-react$"
}
},
{
"name": "zod-is-reached-through-contracts-zod",
"comment": "F-7 (13-08). src/contracts/zod.ts sets zod jitless before any schema is built, so the production CSP never sees zod's Function probe. Schema code imports z from there.",
"severity": "error",
"from": {
"path": "^src",
"pathNot": "^src/contracts/zod\\.ts$"
},
"to": {
"path": "^zod$"
}
},
{
"name": "design-system-is-reached-through-its-index",
"comment": "VD-05, 12-08. Code outside src/presentation/design-system imports its public index.ts only, so the primitives can change behind it. Named facades: src/presentation/components/ui/*.ts re-export the canonical primitives under their pre-VD-05 paths (VD-05 Rollback). Exception: src/presentation/templates/page-templates.tsx reads PaginationLandmarkContext, which index.ts does not export. Owner: frontend-platform. Revisit: export it from index.ts or move the page templates into the design system.",
"severity": "error",
"from": {
"path": "^src/",
"pathNot": "^src/presentation/(design-system/|components/ui/[^/]+\\.ts$|templates/page-templates\\.tsx$)"
},
"to": {
"path": "^src/presentation/design-system/",
"pathNot": "^src/presentation/design-system/index\\.ts$"
}
},
{
"name": "adapters-do-not-know-presentation",
"comment": "An adapter implements an application port. It never imports UI or the composition root; pass what it needs through the port or its factory arguments.",
"severity": "error",
"from": {
"path": "^src/adapters"
},
"to": {
"path": "^src/(presentation|bootstrap)"
}
},
{
"name": "feature-domain-is-framework-neutral",
"comment": "A feature's domain is framework-neutral, like src/domain. Move the code to the feature's application, or pass the value in from there.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/domain"
},
"to": {
"path": "^(src/(application|presentation|adapters|bootstrap)|src/features/[^/]+/(application|adapters|presentation)|react|react-dom|@tanstack)"
}
},
{
"name": "feature-application-does-not-know-runtime",
"comment": "A feature's application declares the ports it needs. Put the port in the feature's application and implement it in the feature's adapters/; bootstrap wires the two.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/application"
},
"to": {
"path": "^(src/(presentation|adapters|bootstrap)|src/features/[^/]+/(adapters|presentation)|react|react-dom|@tanstack)"
}
},
{
"name": "feature-presentation-does-not-know-outbound-adapters",
"comment": "Feature presentation calls its application API. The feature's adapters/ are wired by bootstrap, so import the application facade instead.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/presentation"
},
"to": {
"path": "^(src/(adapters|bootstrap)|src/features/[^/]+/adapters|@tanstack)"
}
},
{
"name": "feature-adapters-do-not-know-presentation",
"comment": "A feature adapter implements the feature's ports and never imports UI or the composition root. Pass what it needs through the port.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/adapters"
},
"to": {
"path": "^(src/(presentation|bootstrap)|src/features/[^/]+/presentation)"
}
},
{
"name": "concrete-adapters-compose-only-in-bootstrap",
"comment": "Only src/bootstrap constructs concrete adapters. Depend on the application port or facade; bootstrap composes the adapter behind it.",
"severity": "error",
"from": {
"path": "^src/(domain|application|presentation|contracts)"
},
"to": {
"path": "^src/adapters"
}
},
{
"name": "external-contract-package-single-import-path",
"comment": "§4.1: a generated service package may only be imported from src/features/<feature>/contracts/*-contract-contribution.ts. Owner: frontend-platform.",
"severity": "error",
"from": {
"path": "^src",
"pathNot": "^src/features/[^/]+/contracts/[^/]+-contract-contribution\\.ts$"
},
"to": {
"path": "^@org-contracts/"
}
},
{
"name": "presentation-does-not-fetch-directly",
"comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself. Call the application API; bootstrap composes the adapter behind it.",
"severity": "error",
"from": {
"path": "^src/(presentation|features/[^/]+/presentation)"
},
"to": {
"path": "^src/adapters/(http|realtime|service-worker|web-worker|storage)"
}
},
{
"name": "unselected-realtime-runtime-is-not-composed",
"comment": "§9.2 / 12-10. Realtime and Web Push are NOT_SELECTED in the template (src/features/installed-runtime-capabilities.ts), so the composition root and the installed-feature registries do not import their concrete adapters. A project that selects one replaces this rule when it wires the runtime. Owner: frontend-platform.",
"severity": "error",
"from": {
"path": "^src/(bootstrap/|features/installed-feature-)"
},
"to": {
"path": "^src/adapters/(realtime|web-push)/"
}
},
{
"name": "generic-worker-has-no-network-or-credentials",
"comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth. Do the network call on the page side and post the data to the worker.",
"severity": "error",
"from": {
"path": "^src/adapters/web-worker"
},
"to": {
"path": "^src/adapters/(http|realtime|auth|web-push)"
}
},
{
"name": "service-worker-entry-is-not-page-code",
"comment": "§17.2.1: the worker realm never imports React, presentation or bootstrap page code",
"severity": "error",
"from": {
"path": "^src/adapters/service-worker"
},
"to": {
"path": "^(src/(presentation|bootstrap)|react|react-dom|@tanstack)"
}
},
{
"name": "contracts-do-not-know-application",
"comment": "§4. `src/contracts` is the lower of the two packages: application reads contracts, never the other way round. Before this rule the shared Result carrier and the compatibility predicate lived in application and were imported back down by contracts, so neither package owned the shared vocabulary and the coupling was invisible to every gate.",
"severity": "error",
"from": {
"path": "^src/contracts"
},
"to": {
"path": "^src/(application|features)"
}
},
{
"name": "contracts-do-not-know-presentation-or-bootstrap",
"comment": "Q-6.7-12. `src/contracts` is shared vocabulary read by every layer, including the service worker and web worker builds. Importing presentation or the composition root from it would pull React and the whole app into those builds. There is no such import today; this keeps it that way.",
"severity": "error",
"from": {
"path": "^src/contracts"
},
"to": {
"path": "^src/(presentation|bootstrap)"
}
},
{
"name": "generic-presentation-does-not-compose-the-product",
"comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Exception: the generic presentation modules in pathNot read the installed registries today. The list names exact files, so a new module that reads a registry fails the gate. Owner: frontend-platform. Revisit when the assembly is lifted into bootstrap; remove each file from the list as it stops reading the registries.",
"severity": "error",
"from": {
"path": "^src/presentation/",
"pathNot": "^src/presentation/(layouts/app-shell\\.tsx|pages/(not-found-page|home-page)\\.tsx|routes/(route-contract|route-codecs|app-router|navigation-policy)\\.(ts|tsx)|i18n/catalog\\.ts|examples/platform-overview-page\\.tsx)$"
},
"to": {
"path": "^src/features/installed-"
}
},
{
"name": "boot-does-not-load-every-feature-runtime",
"comment": "15-01. src/features/loaded-feature-runtimes.ts awaits every installed feature's runtime half at module evaluation. Imported anywhere on the boot path, the first render would wait for all feature code, and the initial-chunk budget would not see it because the runtimes are dynamic imports. Any top-level await in the browser graph also turns off rolldown chunk optimizations for the whole build. At runtime the composition root loads one feature at a time when its routes are entered; the platform overview route calls loadInstalledFeatureRuntimeRegistries() instead. Node scripts and tests are outside src and may import it. Owner: frontend-platform.",
"severity": "error",
"from": {
"path": "^src/",
"pathNot": "^src/features/loaded-feature-runtimes\\.ts$"
},
"to": {
"path": "^src/features/loaded-feature-runtimes\\.ts$"
}
},
{
"name": "adapters-do-not-know-other-concrete-adapters",
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (clock, abort primitive, capacity guard), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
"severity": "error",
"from": {
"path": "^src/adapters/([^/]+)/"
},
"to": {
"path": "^src/adapters/([^/]+)/",
"pathNot": "^src/adapters/($1/|platform/|browser-file-storage/result\\.ts$|cross-context-invalidation/index\\.ts$)"
}
},
{
"name": "adapter-groups-are-reached-through-their-barrel",
"comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 예외: 도착점에서 storage/indexeddb/index.ts와 storage/opfs/index.ts만 서브배럴로 허용한다. 두 폴더는 browser-file-storage 번들의 런타임이고, 제거 드릴(scripts/test-browser-file-storage-runtime-removal.ts)은 그 번들 전체(browser-file-storage, browser-files, browser-transfer, cache-storage, storage/indexeddb, storage/opfs)를 함께 지운다. 최상위 storage 배럴(Web Storage)은 그 뒤에도 남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개 경계다. 다른 2단계 index.ts는 공개 배럴이 아니다(리뷰 12-07). 담당: frontend-platform. 재검토: 새 런타임을 따로 제거할 수 있게 만들 때 그 서브배럴을 이 목록에 추가한다.",
"severity": "error",
"from": {
"path": "^src/",
"pathNot": "^src/adapters/"
},
"to": {
"path": "^src/adapters/[^/]+/",
"pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/storage/(indexeddb|opfs)/index\\.ts$"
}
},
{
"name": "features-do-not-import-other-features",
"comment": "A feature may depend on shared contracts/ports, but never on another feature concrete implementation.",
"severity": "error",
"from": {
"path": "^src/features/([^/]+)/"
},
"to": {
"path": "^src/features/[^/]+/",
"pathNot": "^src/features/$1/"
}
},
{
"name": "contexts-do-not-import-other-contexts",
"comment": "A bounded context may compose its own features and shared platform contracts, but not another context concrete implementation.",
"severity": "error",
"from": {
"path": "^src/contexts/([^/]+)/"
},
"to": {
"path": "^src/contexts/[^/]+/",
"pathNot": "^src/contexts/$1/"
}
},
{
"name": "feature-and-app-roots-do-not-reach-adapters",
"comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers the files outside a feature's layer folders (src/features/*.ts, src/features/<feature>/*.ts), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.",
"severity": "error",
"from": {
"path": "^src/(features/[^/]+\\.tsx?$|features/[^/]+/[^/]+\\.tsx?$|contexts/|apps/)",
"pathNot": "^src/features/feature-adapter-contribution\\.ts$"
},
"to": {
"path": "^src/adapters/"
}
},
{
"name": "presentation-does-not-import-apps-or-contexts",
"comment": "12-03. Apps and contexts compose features, including their runtime, so presentation importing them is a path around presentation-does-not-know-adapters. Exception: src/presentation/routes/app-router.tsx mounts the deployable app's route tree (src/apps/template-app.ts). Owner: frontend-platform. Revisit when the router is assembled in bootstrap together with the frozen generic-presentation-does-not-compose-the-product list.",
"severity": "error",
"from": {
"path": "^src/(presentation/|features/[^/]+/presentation/)",
"pathNot": "^src/presentation/routes/app-router\\.tsx$"
},
"to": {
"path": "^src/(apps|contexts)/"
}
},
{
"name": "observability-vendors-live-behind-adapters",
"comment": "Spec §24. Features, platform, application, domain, contracts and presentation emit observability only through the provider-neutral TelemetryPort. A vendor telemetry SDK may be imported only by an adapter-side transport under src/adapters.",
"severity": "error",
"from": {
"path": "^src/",
"pathNot": "^src/adapters/"
},
"to": {
"path": "^(@sentry|@datadog|@opentelemetry|@newrelic|newrelic|@honeycombio|@bugsnag|bugsnag-js|@rollbar|rollbar|logrocket|@logrocket|@amplitude|posthog-js|mixpanel-browser|@segment|@elastic/apm-rum|@grafana/faro-web-sdk|@microsoft/applicationinsights-web)(/|$)"
}
},
{
"name": "platform-kernel-is-product-neutral",
"comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.",
"severity": "error",
"from": {
"path": "^src/platform/",
"pathNot": "^src/platform/routing/"
},
"to": {
"path": "^src/(features|contexts|apps|adapters|bootstrap|presentation|application)/"
}
},
{
"name": "no-circular-dependencies",
"comment": "A cycle makes the modules impossible to load or remove one at a time. Move the shared part into a lower module that both import.",
"severity": "error",
"from": {},
"to": {
"circular": true
}
}
]
}