fix(apps): 플랫폼 라우트가 가리는 기능 라우트를 조립 때 막는다 (1101/14.4)

문제: 라우터는 `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.
This commit is contained in:
DongHyeonka
2026-11-03 20:30:35 +09:00
parent 27f45233f9
commit 7d85589ec1
3 changed files with 104 additions and 10 deletions
+8 -4
View File
@@ -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`,
+41 -6
View File
@@ -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<Context extends BoundedContextModule = BoundedContextModule> = Readonly<{
@@ -55,6 +58,13 @@ export function defineDeployableAppModule<const Context extends BoundedContextMo
* share a layout, and a root still takes the URLs under it whichever layout
* either context has, so this check spans every layout. A platform route a
* feature took over (its home) is mounted at its own path and is exempt.
*
* 09-03 (1101/14.4). AppShell's platform routes come before every context in
* the router (`app-router.tsx`), so a route a platform route also answers is
* never rendered: the same path, `/` under another id than `APP_HOME`, or any
* route of a `*` root without a layout (NOT_FOUND's splat ties and wins). The
* context is matched where the router mounts it: at its root, or under a
* layout at the route's own path.
*/
function assertFeatureRoutesReachOwningContext(
contexts: readonly BoundedContextModule[],
@@ -62,17 +72,42 @@ function assertFeatureRoutesReachOwningContext(
const roots = contexts.flatMap((context) =>
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(", ")}).`,
);
}
}
@@ -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[]) => ({