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"로 실패(수정 전, 298201f 기준).
- GREEN: 같은 파일 7건 통과.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
  94 files / 588 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
  1,929 tests 통과. tsc app·test·node 통과. 바꾼 파일 eslint 통과.
  check-architecture.ts(pnpm exec를 node_modules/.bin으로 넘기는 shim)
  통과.
This commit is contained in:
DongHyeonka
2026-11-01 22:56:29 +09:00
parent 96a4f68016
commit 7139c7c61e
3 changed files with 196 additions and 0 deletions
+6
View File
@@ -143,6 +143,12 @@ selected app. Every build and check script runs it first; run it yourself with
(`src/features/reference-feature/context-routes.ts`).
4. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or
add `src/contexts/<context>/context-module.ts` owned by the app.
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`).
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`,
+52
View File
@@ -1,3 +1,5 @@
import { matchRoutes } from "react-router-dom";
import type { BoundedContextModule } from "../contexts/bounded-context-module.ts";
import { assertWithinCardinalityBudget } from "../platform/cardinality/cardinality-budget.ts";
@@ -26,9 +28,59 @@ export function defineDeployableAppModule<const Context extends BoundedContextMo
}
seen.add(context.id);
}
assertFeatureRoutesReachOwningContext(definition.contexts);
return Object.freeze({
...definition,
contexts: Object.freeze([...definition.contexts]),
budget: Object.freeze({ ...definition.budget }),
});
}
/**
* 09-06. The router mounts one gateway per context at its route root and
* renders a feature route only inside that gateway, while the route registry
* and navigation list every feature route wherever it points. A route its
* owning root does not reach (outside the root, at the platform home, or
* under another context's identical or more specific root) would be a menu
* link to NOT_FOUND. Matching uses the router's own ranking, so nested roots
* stay allowed as long as each route lands in its owner. Platform routes are
* not checked here.
*/
function assertFeatureRoutesReachOwningContext(
contexts: readonly BoundedContextModule[],
): void {
const roots = contexts.flatMap((context) =>
context.route ? [{ id: context.id, path: context.route.path }] : [],
);
for (const context of contexts) {
for (const feature of context.features) {
for (const [routeId, path] of contractRoutePaths(feature.contracts)) {
const reached = matchRoutes(roots, path)?.[0]?.route;
if (reached?.id === context.id) 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."),
);
}
}
}
}
/** The route registry reads `contracts.routes`; a feature may have none. */
function contractRoutePaths(
contracts: object,
): readonly (readonly [string, string])[] {
const routes: unknown = "routes" in contracts ? contracts.routes : undefined;
if (typeof routes !== "object" || routes === null) return [];
return Object.entries(routes).flatMap(
([routeId, definition]: [string, unknown]) =>
typeof definition === "object" &&
definition !== null &&
"path" in definition &&
typeof definition.path === "string"
? [[routeId, definition.path] as const]
: [],
);
}
@@ -0,0 +1,138 @@
import { describe, expect, it } from "vitest";
import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts";
import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts";
import { defineFeatureModule } from "../../src/features/feature-module.ts";
/**
* 09-06. The router mounts one gateway per context at its route root and
* renders a feature route only inside it, while the registry and navigation
* list every feature route. A route its owning root does not reach is a menu
* link to NOT_FOUND, so composing the app has to refuse it.
*/
function feature(id: string, paths: Readonly<Record<string, string>>) {
const routes = Object.fromEntries(
Object.entries(paths).map(([routeId, path]) => [routeId, { routeId, path }]),
);
return defineFeatureModule({
id,
contracts: { featureId: id, routes },
routes,
messages: {},
loadRuntime: async () => ({
featureId: id,
apiContract: {},
adapters: [],
contractContributions: [],
}),
});
}
function context(
id: string,
path: string,
features: readonly ReturnType<typeof feature>[],
) {
return defineBoundedContextModule({
id,
features,
budget: { maxFeatures: 10 },
route: { path, loadRoutes: async () => [] },
});
}
function app(...contexts: readonly ReturnType<typeof context>[]) {
return defineDeployableAppModule({
id: "shop-app",
contexts,
budget: { maxContexts: 10 },
});
}
describe("feature routes and their context route root", () => {
it("accepts routes at and under the owning context root", () => {
expect(() =>
app(
context("shop-context", "shop/*", [
feature("shop-feature", {
SHOP_ITEMS: "/shop",
SHOP_ITEM: "/shop/items/:itemId",
SHOP_NEW: "/shop/items/new",
}),
]),
),
).not.toThrow();
});
it("rejects a route outside the owning root, naming the feature, route and root", () => {
// E2: the menu would list /catalog and the URL would render NOT_FOUND.
expect(() =>
app(
context("shop-context", "shop/*", [
feature("shop-feature", {
SHOP_ITEMS: "/shop/items",
SHOP_CATALOG: "/catalog",
}),
]),
),
).toThrow(/SHOP_CATALOG.*\/catalog.*shop-feature.*shop-context.*shop\/\*/);
});
it("rejects a feature route at the platform home", () => {
expect(() =>
app(
context("shop-context", "shop/*", [
feature("shop-feature", { SHOP_HOME: "/" }),
]),
),
).toThrow(/SHOP_HOME/);
});
it("rejects a route whose feature belongs to a context without a route root", () => {
expect(() =>
app(
defineBoundedContextModule({
id: "silent-context",
features: [feature("silent-feature", { SILENT: "/silent" })],
budget: { maxFeatures: 10 },
}),
),
).toThrow(/SILENT.*silent-feature.*silent-context/);
});
it("rejects a second context on the same root, which the router never reaches", () => {
// E5: the first context's gateway takes every URL under shop/*.
expect(() =>
app(
context("shop-a", "shop/*", [feature("feature-a", { A: "/shop/a" })]),
context("shop-b", "shop/*", [feature("feature-b", { B: "/shop/b" })]),
),
).toThrow(/B.*\/shop\/b.*feature-b.*shop-b.*shop-a/);
});
it("accepts nested roots when each route resolves to its own context", () => {
expect(() =>
app(
context("items", "fixture/items/*", [
feature("list", { LIST: "/fixture/items" }),
]),
context("status", "fixture/items/status/*", [
feature("status", { STATUS: "/fixture/items/status" }),
]),
),
).not.toThrow();
});
it("rejects a route a nested root of another context takes over", () => {
expect(() =>
app(
context("items", "fixture/items/*", [
feature("list", { DETAIL: "/fixture/items/status/detail" }),
]),
context("status", "fixture/items/status/*", [
feature("status", { STATUS: "/fixture/items/status" }),
]),
),
).toThrow(/DETAIL.*list.*items.*status/);
});
});