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/); + }); +});