Commit Graph
6 Commits
Author SHA1 Message Date
DongHyeonka 7c8cb19e94 fix(routes): 등록 라우트 없는 URL의 적재 실패를 UNREGISTERED_ROUTE로 적는다 (1101/14.3)
문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때
`route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다.
- 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`.
  레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은
  `NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found
  화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의
  라우트 모듈이다.
- 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는
  `route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는
  `invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인).
- 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만
  붙어서 지금은 닿지 않는 값이다.

이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나,
그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다.

고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록
라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값
`UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를
쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트
id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지
않았다.

버린 대안:
- context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히
  가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자
  kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의
  `route_id` 검사가 약해진다.
- context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트
  id와 섞인다.
- `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을
  바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다.

위험·한계:
- 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은
  결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다.
- [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다.
  복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다.
  `route_id` 이름과 허용 문법은 그대로다.
- 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지
  않았다.

검증:
- RED: context-boundary-diagnostics "unregistered handle" 1건이
  `"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이
  `"route_id": "context-offline"`로 실패(8건 중 3 실패).
- GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영
  (`projectTelemetryEvent`)도 통과한다.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
  runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
  files, 3,572건 통과.
- tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries,
  check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.
2026-11-03 20:30:35 +09:00
DongHyeonka 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
  둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(7139c7c
  한계). 루트 `*` context에서 `APP_HOME`이 아닌 id로 `/`를 선언하면 플랫폼
  홈에 가려진다.
- 초기 JS gzip +349 B(204,586 -> 204,935 B). 예산 204,800 B를 135 B
  넘는다(이전 여유 214 B). boot 청크 +228(라우터·앱 모듈),
  installed-feature-contracts 청크 +121. 같은 worktree에서 HEAD 파일로
  `vite build`를 한 번 더 해서 청크별로 비교했다. 예산은 고치지 않았다.

검증:
- RED: tests/component/context-layouts.test.tsx는 파일 적재에서
  "Duplicate route registry key: APP_HOME"으로 실패.
  tests/architecture/context-route-roots.test.ts 15건 중 3건 실패(APP_HOME
  루트 예외 "not under the route root", 대체 함수가 없어 2건).
  tests/scripts/generate-product-feature-index.test.ts 새 1건이 HEAD 생성기로
  "expected ... to contain 'loadLayout: async () => (await import…'"로 실패.
- GREEN: 세 파일 37건 통과(생성기 15, 루트 16, context-layouts 6).
- 변이: 라우터가 `loadLayout`을 무시하면 context-layouts 6건 중 5건 실패.
  topics 레이아웃을 다른 컴포넌트로 바꾸면 "keeps one layout instance" 실패.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
  runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
  300 files, 3,451건 통과. check-registries, check-adapter-inventory,
  verify-documentation-readiness(PASS_SCOPED) 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과. 생성기 --check 통과.
- check:architecture는 pnpm이 필요해 돌리지 않았다.

Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-03, 4.3
2026-11-03 01:52:18 +09:00
DongHyeonkaandClaude Opus 5.5 a8111f7647 fix(features): apply VITE_PRODUCT_FEATURES in the index generator (09-02)
The bundle applied the selection at runtime while Node build scripts and the
context router ignored it, and a typo only failed in the browser. The generator
now imports only the selected features and rejects unknown ids (D-9); declared
ids stay in the index for NOT_INSTALLED reporting. Default build modules are
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:29:51 +09:00
DongHyeonkaandClaude Opus 5.5 991da882e2 test(platform): run platform tests on a test-only feature, not the sample (14-01)
Six platform tests imported or named the removable reference feature, so
FE-GATE-020 failed on typecheck, unit, coverage, home smoke and residue.
Router surfaces now install tests/helpers/fixture-feature.tsx by mocking
the generated indexes; the rest use neutral names or read the installed
modules. test:sample-removal passes 13/13.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 21:18:39 +09:00
DongHyeonkaandClaude Opus 5.5 40659de7ec fix(release): share one reload-once guard between chunk and boot recovery (Q-6.9-9)
Chunk recovery kept its own guard: marker keyed by the release pair, no
TTL, trusted write().ok. Round 1 fixed the boot guard (key-independent
marker within a TTL, read-back check) but the chunk copy still reloaded
on every failure when replicas alternated A->B, B->A.

platform/release gains createReloadOnceGuard (the round-1 boot rule,
now with a refusal reason); createReleaseMismatchRecovery wraps it with
unchanged boot semantics (marker within TTL blocks regardless of key,
markCoherentBoot clears), and decideChunkRecovery uses it over its own
CHUNK_RELOAD_GUARD key, keeping its reason vocabulary. Application ->
platform is allowed by .dependency-cruiser.json; platform may not import
application, so the guard lives in platform.

Behavior change (chunk only): a second reload within the TTL is refused
even for a different release pair, and a marker that does not read back
is guard-write-failed. tests/component/context-route-gateway.test.tsx
used a preferences stub that dropped writes; it now persists them.

Verified: tests/unit/chunk-recovery.test.ts characterization (read/write
failure, same pair, invariants) green before the change; alternating
pair test RED before, green after. Boot tests unchanged and green;
FE-RB-002 drill PASS; test:integration PASS; all gates PASS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:58:35 +09:00
DongHyeonkaandClaude Opus 5.5 7022a1efd0 fix(presentation): key the context gateway and recover its chunk failures (R-8.7)
(a) ContextRouteGateway had no key, so React Router reused one instance
across sibling contexts. On a context A -> B move the first render still
held A's routes, matched B's URL against them and mounted NOT_FOUND, which
reported route.changed(NOT_FOUND) and moved title/focus once. The gateway
element is now keyed by the context id.

(b) A rejected loadRoutes() always showed RouteFailureSurface, so a
routes module missing after a deploy never reached recoverChunk. A chunk
load failure is now rethrown inside a ChunkRecoveryBoundary keyed on the
chunk of the registered route the URL names (the routes module has no
manifest entry of its own; recoverChunk needs one to decide
reload-once). Other load errors still show RouteFailureSurface.

Verified: new tests/component/context-route-gateway.test.tsx mocks the
app with contexts cut from the real reference routes. RED "never matches
a new context's URL against the previous context's routes" (NOT_FOUND
reported) and "sends a failed routes-module download through chunk
recovery" (navigation.reload never called after a release change) failed
before and pass after. check:architecture, check:types:app,
check:types:test, lint, test:component, test:reference-feature pass;
test:unit passes except the pre-existing removal-fixture test (needs
generated artifacts/ files absent from a fresh worktree).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 12:39:51 +09:00