17fa8d1f653e59ea1fdb75162e3cf973ef8b8da2
6
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
b26517e6f2 |
fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N" 처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4). 가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에 있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지 못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다: docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로, docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와 docs/superpowers/plans의 계획으로. 고른 방법: - 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞 커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절 번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다. - tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 + "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에 .dependency-cruiser.json을 넣는다. - README "Files you can delete after copying"에서 INVENTORY.md 한 파일 대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과 ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다. INVENTORY의 행 구조는 바꾸지 않는다. - 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은 링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다. 버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도 상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기 목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시 다른 이력을 가리키면 남길 목록이 계속 커진다. 위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는 주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다. src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼 이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미 docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의 이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다. check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던 실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가 바뀐다. 검증: - RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed). - GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를 src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림. - 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0). - 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크 148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계 참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서 verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트 2 passed. - node scripts/verify-documentation-readiness.ts: PASS_SCOPED - node scripts/check-adapter-inventory.ts: PASS - node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts: 50 passed. tests/architecture: 39 passed. - npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과. .dependency-cruiser.json JSON 파싱 통과. - 미실행: check:architecture(pnpm 필요). |
||
|
|
ca161878f2 |
feat(routes): 기능이 홈을 대신하고 context가 자기 레이아웃을 선언한다 (1101/09-03)
문제: 라우터는 모든 context gateway를 `AppShell` 하나 아래에 붙이고 플랫폼
`/`를 index로 둔다. 기능이 `APP_HOME`을 선언하면 `composeUniqueRecord`가
throw한다. 그래서 제품 홈이 기능 화면이거나 화면이 `AppShell`이 아닌 자기
셸을 쓰면 제품이 템플릿 라우터와 조립 카탈로그를 고쳐야 한다. memento는
카탈로그 브리지(`APP_HOME` 허용 목록)와 라우터 브리지(`ownsShell`)를 넣고
동기화마다 병합한다. tech-log는 라우터를 PUBLIC/STUDIO 그룹 라우터로 통째로
바꿔 생성기 설치 경로(context gateway)를 쓰지 못한다.
고른 방법: 리뷰 4.3의 (B). 선언 두 개를 연다.
- 홈 대체: 플랫폼이 기능이 대신할 수 있는 라우트 id를 선언한다
(`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS = ["APP_HOME"]`,
src/contracts/routes.ts). 그 id를 선언한 기능의 정의가 플랫폼 정의를
대신한다. 둘이 선언하면 카탈로그를 읽을 때 두 기능 id를 담아 throw한다
(`withoutTakenOverPlatformRoutes`). 다른 플랫폼 id는 지금처럼 중복 오류다.
라우터는 대체된 라우트를 소유 context와 함께 그 경로에 붙인다.
- context 레이아웃: `BoundedContextRouteModule.loadLayout`(선택). 생성기는
`src/contexts/<context>/context-layout.tsx`가 있으면 그 `CONTEXT_LAYOUT`을
지연 import로 싣는다. 라우터는 그 context를 `AppShell` 형제인 `/` 레이아웃
라우트 아래, 기능의 등록 경로마다 붙인다. 그래서 모르는 URL은 여전히
`AppShell`의 NOT_FOUND로 간다. 선언이 없으면 지금처럼 `AppShell` 아래 루트에
붙는다. 레이아웃 청크 실패는 라우트 청크와 같은 reload-once 복구를 받는다.
- 09-06 불변식을 레이아웃으로 넓힌다. 레이아웃 라우트는 모두 `/`의
형제라서 루트는 레이아웃과 상관없이 그 아래 URL을 가진다. 그래서 기존
루트 검사가 모든 레이아웃에 걸친다. 한 레이아웃 아래 루트 여럿(같은
컴포넌트를 싣는 context들)은 허용한다. 대체된 플랫폼 라우트는 라우터가
경로에 직접 붙이므로 루트 검사에서 뺀다(09-06 재검토 조건).
- tests/unit/product-features.test.ts의 "플랫폼 라우트는 소유자가 없다"
검사가 대체 가능한 id는 건너뛴다. memento가 고쳤던 템플릿 테스트다.
- `ContextRouteModule`에 `featureIds`가 생겨서, `TEMPLATE_APP_MODULE`을
손으로 mock하며 필수 필드 `features`를 빼먹은 두 테스트
(context-route-gateway, context-boundary-diagnostics)에 `features: []`를
넣었다.
버린 대안:
- (A) 현 상태: 제품마다 브리지를 넣고 동기화마다 병합한다.
- (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 tech-log를 담지 못한다.
- 같은 레이아웃을 쓰는 context를 로더 함수로 묶어 레이아웃 라우트 하나에
모으기: 만들었다가 지웠다. React 19는 같은 컴포넌트로 풀린 lazy 타입을 같은
타입으로 맞춰 레이아웃 인스턴스를 그대로 둔다. 묶지 않은 변이로 테스트가
그대로 통과해서 쓸모없는 코드였다.
- `CONTEXT_LAYOUT_ID` 리터럴로 다른 context의 레이아웃을 가리키기: 같은
컴포넌트를 내보내는 파일 두 개로 같은 결과가 나와 선언을 하나 덜 둔다.
- 레이아웃 라우트를 `AppShell`보다 앞에 두기(memento 브리지 순서): 경로가
같으면 기능이 플랫폼 라우트를 조용히 가린다. `AppShell`을 앞에 두어
지금처럼 플랫폼이 이긴다.
위험·한계:
- 레이아웃이 skip link와 `<main id="main-content">` 하나를 그리는 것은
계약(타입 주석, starter-experience.md)과 테스트 fixture로만 지킨다. 실행 중
검사는 없다. 레이아웃 로딩·실패 화면에는 `<main>`이 없다(`AppShell`의
errorElement와 같다).
- 레이아웃 렌더 결함(청크 실패가 아닌 것)은 라우트 errorElement로 가고
진단을 남기지 않는다. `AppShell` 렌더 결함과 같다.
- 홈을 대신한 기능을 실행 중에 끄면 `/`는 비활성 기능 화면이 된다. 빌드에서
빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
- tech-log의 PUBLIC 셸 안 NOT_FOUND는 표현하지 않는다. 모르는 URL은
`AppShell`의 NOT_FOUND다. STUDIO의 `/studio/*` 라우트는 STUDIO 레이아웃
아래에서 동작한다. tech-log는 기능 하나를 레이아웃 그룹별 기능 둘(context
둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(
|
||
|
|
d6e4e51688 |
fix(contexts): 계약에 없는 라우트 핸들을 라우트 적재 때 막는다 (09-06)
문제: context gateway는 적재한 라우트의 handle `routeId`가 가리키는
등록 라우트를 그린다. `context-routes.ts`가 기능 계약에 없는 route id를
handle에 실으면(오타, 계약에서 지운 라우트) 적재는 성공하고, 그 URL을
그릴 때 context 경계 실패 화면이 된다. 7139c7c가 리뷰의 (1)(2)를 했고
(3) "핸들의 route id가 레지스트리에 있는가"는 설계 선택으로 남겼다.
고른 방법: 적재 때 검사한다. `defineBoundedContextModule`이
`route.loadRoutes`를 감싸, 적재한 각 라우트의 handle `routeId`가 그
context 기능들의 계약 라우트 id에 없으면 TypeError로 실패한다. 메시지에
route id, context id, 기능 id를 담는다. handle에 `routeId`가 없어도
실패한다(gateway는 그 라우트를 NOT_FOUND로 그린다).
- 모든 context가 이 함수를 거치므로(생성된 product-context-index) 모든
context에 걸린다. 모든 context의 라우트를 적재하는 기존 단위 테스트
(tests/unit/route-runtime.test.ts)가 개발 단계에서 잡는다.
- 적재 실패는 09-09(
|
||
|
|
7139c7c61e |
fix(apps): 소유 context 루트가 닿지 않는 기능 라우트를 조립 때 막는다 (09-06)
문제: 라우터는 context마다 gateway 하나를 그 루트 경로에 붙이고 기능
라우트를 그 안에서만 렌더한다. 레지스트리와 탐색 메뉴는 경로와 상관없이
모든 기능 라우트를 싣는다. 그래서 루트 `shop/*` context의 `/catalog`
라우트는 메뉴 링크로 나오고 그 URL은 NOT_FOUND가 된다. 같은 루트를 쓰는
context가 둘이면 id가 늦은 쪽 전체가 닿지 않는다. 어떤 게이트도 경로와
루트를 비교하지 않았다.
고른 방법: `defineDeployableAppModule`이 context별 기능 계약 라우트를
React Router `matchRoutes`로 전체 context 루트에 맞춰 보고, 그 라우트를
받는 context가 소유 context가 아니면 라우트 id·경로·기능 id·context
id·루트를 담아 throw한다. 앱 모듈은 부트 정적 그래프에서 평가되므로
부트 실패 화면과 라우터를 거치는 모든 테스트에서 드러난다. 라우터와 같은
매칭 규칙을 쓰므로 루트 밖 경로, `/`, 루트 없는 context, 같은 루트, 더
구체적인 다른 루트에 먹히는 경로를 한 검사로 잡는다. 중첩 루트 자체는
허용한다(`tests/component/context-route-gateway.test.tsx`가 쓰는 모양).
starter-experience.md 기능 추가 4단계에 규칙을 적었다.
버린 대안:
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 라우트 경로를 모른다.
- `defineBoundedContextModule`에서 검사: 다른 context의 루트를 모른다.
같은 루트·중첩 루트를 앱 단위에서 따로 또 봐야 해서 검사가 두 곳이 된다.
- 루트 문자열 접두어 비교: `:param`·splat 규칙을 다시 구현하게 된다.
위험·한계:
- 리뷰 09-06의 (3) "context 라우트 핸들의 route id가 레지스트리에 있는가"는
넣지 않았다. 핸들은 `context-routes.ts`를 읽어야 보이는데 이 파일은 늦게
읽어야 한다. 헬퍼 제공과 적재 시 검사 중 고르는 설계 선택이라 남긴다.
그 실패의 진단 누락은 09-09에서 다룬다.
- 플랫폼 라우트와 기능 라우트의 경로 충돌은 검사하지 않는다.
- 초기 JS +239 B gzip(202,509 → 202,748 B, 여유 2,291 → 2,052 B).
같은 worktree에서 `vite build` 두 번으로 쟀다.
검증:
- RED: tests/architecture/context-route-roots.test.ts 7건 중 거절 5건이
"expected [Function] to throw an error"로 실패(수정 전,
|
||
|
|
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절 |
||
|
|
6f6c48ebb7 | refactor: 도메인이 100개 1000개씩 늘어나도 유지보수 쉬운 구조로 변경 |