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 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 context's `CONTEXT_ROUTE_PATH` and must not fall under another context's
identical or more specific root: the router renders feature routes only identical or more specific root: the router renders feature routes only
inside the owning context. The app module refuses anything else when it inside the owning context. No platform route may answer it either: the
loads, naming the route, feature and context router tries `AppShell`'s platform routes first, so the same path as a
(`src/apps/deployable-app-module.ts`). A route that takes over the platform platform route, `/` under an id other than `APP_HOME`, or a `*` root
home is the exception ("Product home and layouts"). 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` 5. If the feature has application input, augment `ApplicationFeatureInputs`
from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`). from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`).
6. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`, 6. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`,
+41 -6
View File
@@ -4,7 +4,10 @@ import {
contractRoutePaths, contractRoutePaths,
type BoundedContextModule, type BoundedContextModule,
} from "../contexts/bounded-context-module.ts"; } 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"; import { assertWithinCardinalityBudget } from "../platform/cardinality/cardinality-budget.ts";
export type DeployableAppModule<Context extends BoundedContextModule = BoundedContextModule> = Readonly<{ 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 * 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 * 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. * 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( function assertFeatureRoutesReachOwningContext(
contexts: readonly BoundedContextModule[], contexts: readonly BoundedContextModule[],
@@ -62,17 +72,42 @@ function assertFeatureRoutesReachOwningContext(
const roots = contexts.flatMap((context) => const roots = contexts.flatMap((context) =>
context.route ? [{ id: context.id, path: context.route.path }] : [], 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 context of contexts) {
for (const feature of context.features) { for (const feature of context.features) {
for (const [routeId, path] of contractRoutePaths(feature.contracts)) { for (const [routeId, path] of contractRoutePaths(feature.contracts)) {
if (FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.includes(routeId)) continue; if (FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.includes(routeId)) continue;
const reached = matchRoutes(roots, path)?.[0]?.route; 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( 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"}): ` + `Route ${routeId} (${path}) of feature ${feature.id} in context ${context.id} is answered by platform route ${answered?.id} (${answered?.path}). ` +
(reached `A feature replaces a platform route only by declaring its id (${FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.join(", ")}).`,
? `context ${reached.id} (${reached.path}) takes that URL.`
: "the router would answer NOT_FOUND."),
); );
} }
} }
@@ -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. */ /** 09-03. The platform names the routes a feature may take over; one feature may. */
describe("replaceable platform routes", () => { describe("replaceable platform routes", () => {
const contract = (featureId: string, ...routeIds: string[]) => ({ const contract = (featureId: string, ...routeIds: string[]) => ({