From 7139c7c61edf1e8b198026a6a0965bd2f0c1d63e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:04:52 +0900 Subject: [PATCH] =?UTF-8?q?fix(apps):=20=EC=86=8C=EC=9C=A0=20context=20?= =?UTF-8?q?=EB=A3=A8=ED=8A=B8=EA=B0=80=20=EB=8B=BF=EC=A7=80=20=EC=95=8A?= =?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(09-06)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 라우터는 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) 통과. --- docs/architecture/starter-experience.md | 6 + src/apps/deployable-app-module.ts | 52 +++++++ .../architecture/context-route-roots.test.ts | 138 ++++++++++++++++++ 3 files changed, 196 insertions(+) create mode 100644 tests/architecture/context-route-roots.test.ts diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index cfa84ace..427727dd 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -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-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`, diff --git a/src/apps/deployable-app-module.ts b/src/apps/deployable-app-module.ts index 7100473b..d9c5716b 100644 --- a/src/apps/deployable-app-module.ts +++ b/src/apps/deployable-app-module.ts @@ -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 + 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] + : [], + ); +} diff --git a/tests/architecture/context-route-roots.test.ts b/tests/architecture/context-route-roots.test.ts new file mode 100644 index 00000000..8e5bcf29 --- /dev/null +++ b/tests/architecture/context-route-roots.test.ts @@ -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>) { + 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[], +) { + return defineBoundedContextModule({ + id, + features, + budget: { maxFeatures: 10 }, + route: { path, loadRoutes: async () => [] }, + }); +} + +function app(...contexts: readonly ReturnType[]) { + 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/); + }); +});