From 7d85589ec106bb7f616321d43b4e428a5cf6caa1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 20:17:28 +0900 Subject: [PATCH] =?UTF-8?q?fix(apps):=20=ED=94=8C=EB=9E=AB=ED=8F=BC=20?= =?UTF-8?q?=EB=9D=BC=EC=9A=B0=ED=8A=B8=EA=B0=80=20=EA=B0=80=EB=A6=AC?= =?UTF-8?q?=EB=8A=94=20=EA=B8=B0=EB=8A=A5=20=EB=9D=BC=EC=9A=B0=ED=8A=B8?= =?UTF-8?q?=EB=A5=BC=20=EC=A1=B0=EB=A6=BD=20=EB=95=8C=20=EB=A7=89=EB=8A=94?= =?UTF-8?q?=EB=8B=A4=20(1101/14.4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 라우터는 `AppShell` 아래 플랫폼 라우트를 모든 context보다 먼저 붙인다. 그래서 기능 라우트를 플랫폼 라우트도 받으면 오류 없이 플랫폼 화면이 나온다. React Router `matchRoutes`로 라우터와 같은 구조를 만들어 확인했다. - 같은 경로: context `examples/*`의 `/examples/ui`는 `EXAMPLES_UI`가 받는다. 레이아웃 아래에서도 순위가 같으면 앞에 있는 `AppShell`이 이긴다. - `APP_HOME`이 아닌 id로 선언한 `/`는 플랫폼 홈이 받는다(ca16187 한계). - 레이아웃 없는 `*` 루트 context는 모든 URL을 NOT_FOUND splat에 뺏긴다. splat끼리 순위가 같고 플랫폼 쪽이 먼저다. 7139c7c의 루트 검사는 context 루트끼리만 비교해 이 셋을 통과시킨다. 고른 방법: 라우트 조립 런타임, 곧 `defineDeployableAppModule`의 09-06 검사 (`assertFeatureRoutesReachOwningContext`)에 한 단계를 더한다. 기능 라우트 경로마다 `[대체되지 않은 플랫폼 라우트..., context가 붙는 자리]`로 `matchRoutes`를 돌려, 그 context가 받지 않으면 route id, 경로, 기능, context, 가로챈 플랫폼 라우트를 담아 TypeError로 실패한다. context가 붙는 자리는 라우터와 같다. 레이아웃이 없으면 루트이고, 있으면 그 라우트의 경로다. 기능이 대신한 `APP_HOME`은 플랫폼 쪽에서 빼고, `APP_HOME` 라우트 자체는 지금처럼 건너뛴다. - 앱 모듈을 평가할 때 실패하므로 부트와 앱 모듈을 불러오는 모든 테스트가 막힌다(fail-closed). 기존 09-06 검사와 같은 자리이고, 라우트 정의는 이미 초기 그래프에 있다. 버린 대안: - 라우터(`createRegisteredRoutes`)에서 검사: 라우터 표 자체로 보니 순위가 정확하다. 하지만 `AppRouter`가 마운트될 때에야 실패하고, 앱 모듈을 fixture로 바꿔 끼우는 테스트를 따로 만들어야 한다. - 아키텍처 테스트: 템플릿에 설치된 기능만 보고, 다운스트림이 기능을 더한 빌드는 실행 때 지켜지지 않는다. - 레지스트리 검사(`check:registries`) 또는 생성기: 생성기는 정규식으로 리터럴만 읽어 라우트 경로를 모른다. - 경로 문자열 비교: `*` 루트와 파라미터 모양이 같은 경로를 놓친다. 위험·한계: - 라우터 순서를 이 함수가 따라 한다. `app-router.tsx`가 플랫폼 라우트를 context 뒤로 옮기면 이 검사도 같이 바꿔야 한다. 주석에 적었다. - 일부만 겹치는 경우(`/examples/:slug`의 `ui` 값)는 막지 않는다. 그 기능 라우트는 다른 값으로는 닿는다. - 기능끼리 같은 경로는 이 커밋 범위가 아니다. 검증: - RED: tests/architecture/context-route-roots.test.ts 새 5건 중 거절 4건이 "expected [Function] to throw an error"로 실패(21건 중 4 실패). - GREEN: 21건 통과. 메시지 예: "Route EXAMPLES_UI_COPY (/examples/ui) of feature examples-feature in context examples is answered by platform route EXAMPLES_UI (/examples/ui). A feature replaces a platform route only by declaring its id (APP_HOME)." - 회귀: tests/{architecture,unit,features,platform,component,contract, runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306 files 중 3,569 통과, 1 실패. 실패는 telemetry-storm.test.ts 10초 timeout(부하 44)이고 단독 재실행에서 4건 통과했다. - tsc app·test·node 통과. 바꾼 파일 eslint 통과. check-registries 통과. verify-documentation-readiness PASS_SCOPED. --- docs/architecture/starter-experience.md | 12 ++-- src/apps/deployable-app-module.ts | 47 ++++++++++++++-- .../architecture/context-route-roots.test.ts | 55 +++++++++++++++++++ 3 files changed, 104 insertions(+), 10 deletions(-) diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index f8f7f75d..129a7cc7 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -161,10 +161,14 @@ selected app. Every build and check script runs it first; run it yourself with Every route path in the feature contract must sit at or under that context's `CONTEXT_ROUTE_PATH` and must not fall under another context's identical or more specific root: the router renders feature routes only - inside the owning context. The app module refuses anything else when it - loads, naming the route, feature and context - (`src/apps/deployable-app-module.ts`). A route that takes over the platform - home is the exception ("Product home and layouts"). + inside the owning context. No platform route may answer it either: the + router tries `AppShell`'s platform routes first, so the same path as a + platform route, `/` under an id other than `APP_HOME`, or a `*` root + without a layout (the not-found route takes every URL) never renders the + feature. The app module refuses anything else when it loads, naming the + route, feature and context (`src/apps/deployable-app-module.ts`). A route + that takes over the platform home is the exception ("Product home and + layouts"). 5. If the feature has application input, augment `ApplicationFeatureInputs` from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`). 6. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`, diff --git a/src/apps/deployable-app-module.ts b/src/apps/deployable-app-module.ts index 2a2fdbd2..c3766b0c 100644 --- a/src/apps/deployable-app-module.ts +++ b/src/apps/deployable-app-module.ts @@ -4,7 +4,10 @@ import { contractRoutePaths, type BoundedContextModule, } from "../contexts/bounded-context-module.ts"; -import { FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS } from "../contracts/routes.ts"; +import { + FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS, + PLATFORM_ROUTE_REGISTRY, +} from "../contracts/routes.ts"; import { assertWithinCardinalityBudget } from "../platform/cardinality/cardinality-budget.ts"; export type DeployableAppModule = Readonly<{ @@ -55,6 +58,13 @@ export function defineDeployableAppModule context.route ? [{ id: context.id, path: context.route.path }] : [], ); + const featureRouteIds = new Set( + contexts.flatMap((context) => + context.features.flatMap((feature) => + contractRoutePaths(feature.contracts).map(([routeId]) => routeId), + ), + ), + ); + const platformRoutes = Object.values(PLATFORM_ROUTE_REGISTRY).flatMap( + ({ routeId, path }) => + FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.includes(routeId) && + featureRouteIds.has(routeId) + ? [] + : [{ id: routeId, path }], + ); for (const context of contexts) { for (const feature of context.features) { for (const [routeId, path] of contractRoutePaths(feature.contracts)) { if (FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.includes(routeId)) continue; const reached = matchRoutes(roots, path)?.[0]?.route; - if (reached?.id === context.id) continue; + if (reached?.id !== context.id || !context.route) { + throw new TypeError( + `Route ${routeId} (${path}) of feature ${feature.id} is not under the route root of its context ${context.id} (${context.route?.path ?? "no route root"}): ` + + (reached + ? `context ${reached.id} (${reached.path}) takes that URL.` + : "the router would answer NOT_FOUND."), + ); + } + const mount = { + id: context.id, + path: context.route.loadLayout ? path : context.route.path, + }; + const answered = matchRoutes([...platformRoutes, mount], path)?.[0]?.route; + if (answered === mount) continue; throw new TypeError( - `Route ${routeId} (${path}) of feature ${feature.id} is not under the route root of its context ${context.id} (${context.route?.path ?? "no route root"}): ` + - (reached - ? `context ${reached.id} (${reached.path}) takes that URL.` - : "the router would answer NOT_FOUND."), + `Route ${routeId} (${path}) of feature ${feature.id} in context ${context.id} is answered by platform route ${answered?.id} (${answered?.path}). ` + + `A feature replaces a platform route only by declaring its id (${FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.join(", ")}).`, ); } } diff --git a/tests/architecture/context-route-roots.test.ts b/tests/architecture/context-route-roots.test.ts index b74ebc32..0d66c849 100644 --- a/tests/architecture/context-route-roots.test.ts +++ b/tests/architecture/context-route-roots.test.ts @@ -180,6 +180,61 @@ describe("context route roots under layouts", () => { }); }); +/** + * 09-03 (1101/14.4). AppShell mounts the platform routes ahead of every + * context, so a feature route a platform route also answers is never + * rendered: the router picks the platform route without an error. Only the + * home a feature takes over by its id is allowed. + */ +describe("feature routes and platform routes", () => { + const layout = async () => () => null; + + it("rejects a feature route at a platform route's path, naming both", () => { + expect(() => + app( + context("examples", "examples/*", [ + feature("examples-feature", { EXAMPLES_UI_COPY: "/examples/ui" }), + ]), + ), + ).toThrow(/EXAMPLES_UI_COPY.*\/examples\/ui.*examples-feature.*examples.*EXAMPLES_UI/); + }); + + it("rejects the same path under a layout of its own", () => { + // Layout routes sit after AppShell, so the tie goes to the platform. + expect(() => + app( + context("examples", "examples/*", [ + feature("examples-feature", { EXAMPLES_UI_COPY: "/examples/ui" }), + ], layout), + ), + ).toThrow(/EXAMPLES_UI_COPY.*EXAMPLES_UI/); + }); + + it("rejects `/` under another id, which the platform home answers", () => { + expect(() => + app(context("site", "*", [feature("site", { SITE_HOME: "/" })], layout)), + ).toThrow(/SITE_HOME.*\/.*site.*APP_HOME/); + }); + + it("rejects a `*` root without a layout, which NOT_FOUND answers", () => { + // AppShell's NOT_FOUND splat comes before the context's `*` gateway. + expect(() => + app(context("site", "*", [feature("site", { EXPLORE: "/explore" })])), + ).toThrow(/EXPLORE.*\/explore.*site.*NOT_FOUND/); + }); + + it("accepts `/` once a feature took over the platform home", () => { + expect(() => + app( + context("site", "*", [feature("site", { APP_HOME: "/", EXPLORE: "/explore" })], layout), + context("examples", "examples/*", [ + feature("examples-feature", { EXAMPLES_REFERENCE: "/examples/reference" }), + ]), + ), + ).not.toThrow(); + }); +}); + /** 09-03. The platform names the routes a feature may take over; one feature may. */ describe("replaceable platform routes", () => { const contract = (featureId: string, ...routeIds: string[]) => ({