diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 427727dd..f45c76f7 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -140,7 +140,10 @@ selected app. Every build and check script runs it first; run it yourself with `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each route handle carries the route's params/search `codecs`; the owning context loads this file only when its route root is visited - (`src/features/reference-feature/context-routes.ts`). + (`src/features/reference-feature/context-routes.ts`). Each handle's + `routeId` must be a route of a feature contract in the same context; the + context refuses the routes when they load, naming the route, context and + features (`src/contexts/bounded-context-module.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 diff --git a/src/apps/deployable-app-module.ts b/src/apps/deployable-app-module.ts index d9c5716b..c84bce0e 100644 --- a/src/apps/deployable-app-module.ts +++ b/src/apps/deployable-app-module.ts @@ -1,6 +1,9 @@ import { matchRoutes } from "react-router-dom"; -import type { BoundedContextModule } from "../contexts/bounded-context-module.ts"; +import { + contractRoutePaths, + type BoundedContextModule, +} from "../contexts/bounded-context-module.ts"; import { assertWithinCardinalityBudget } from "../platform/cardinality/cardinality-budget.ts"; export type DeployableAppModule = Readonly<{ @@ -67,20 +70,3 @@ function assertFeatureRoutesReachOwningContext( } } } - -/** 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/src/contexts/bounded-context-module.ts b/src/contexts/bounded-context-module.ts index 1e05f34b..545a5c42 100644 --- a/src/contexts/bounded-context-module.ts +++ b/src/contexts/bounded-context-module.ts @@ -36,10 +36,72 @@ export function defineBoundedContextModule + assertHandlesNameContractRoutes( + definition.id, + definition.features, + await route.loadRoutes(), + ), + }), + } + : {}), }); } + +/** + * 09-06 (3). The gateway renders the registered route a loaded route's handle + * names. A handle that no feature of this context declares in its contract + * would only fail when its URL renders, inside the context boundary; checking + * here fails every context whose routes any test or visit loads. Routes stay + * lazy: this runs when they load, not when the context is defined. Only + * top-level routes are checked; context routes are flat today. + */ +function assertHandlesNameContractRoutes( + contextId: string, + features: readonly AnyFeatureModule[], + routes: readonly RouteObject[], +): readonly RouteObject[] { + const routeIds = new Set( + features.flatMap((feature) => + contractRoutePaths(feature.contracts).map(([routeId]) => routeId), + ), + ); + for (const route of routes) { + const handle: unknown = route.handle; + const routeId = + typeof handle === "object" && handle !== null && "routeId" in handle + ? handle.routeId + : undefined; + if (typeof routeId === "string" && routeIds.has(routeId)) continue; + throw new TypeError( + `Route handle ${String(routeId)} loaded by context ${contextId} is not a contract route of its features (${features.map((feature) => feature.id).join(", ")}).`, + ); + } + return routes; +} + +/** The route registry reads `contracts.routes`; a feature may have none. */ +export 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 index 8e5bcf29..0d4ad017 100644 --- a/tests/architecture/context-route-roots.test.ts +++ b/tests/architecture/context-route-roots.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts"; import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts"; @@ -136,3 +136,63 @@ describe("feature routes and their context route root", () => { ).toThrow(/DETAIL.*list.*items.*status/); }); }); + +/** + * 09-06 (3). The gateway renders the registered route a loaded route's handle + * names. A handle no feature of the context declares in its contract fails + * when the context's routes load, not later when that URL renders. + */ +describe("context route handles and their features' contract routes", () => { + function contextLoading( + features: readonly ReturnType[], + handles: readonly unknown[], + ) { + const loadRoutes = vi.fn(async () => + handles.map((handle, index) => ({ + id: `route-${index}`, + path: `/shop/${index}`, + handle, + })), + ); + const module = defineBoundedContextModule({ + id: "shop-context", + features, + budget: { maxFeatures: 10 }, + route: { path: "shop/*", loadRoutes }, + }); + return { module, loadRoutes }; + } + + it("loads routes whose handles name the context's contract routes", async () => { + const { module } = contextLoading( + [ + feature("shop-feature", { SHOP_ITEMS: "/shop/items" }), + feature("cart-feature", { CART: "/shop/cart" }), + ], + [{ routeId: "SHOP_ITEMS" }, { routeId: "CART" }], + ); + await expect(module.route?.loadRoutes()).resolves.toHaveLength(2); + }); + + it("rejects an unregistered handle at load, naming the feature and route ids", async () => { + // E7: a typo in context-routes.ts used to surface only as a context + // boundary failure when that URL rendered. + const { module, loadRoutes } = contextLoading( + [feature("shop-feature", { SHOP_ITEMS: "/shop/items" })], + [{ routeId: "SHOP_ITEMS" }, { routeId: "SHOP_ITEMSS" }], + ); + // Defining the context still does not load its routes. + expect(loadRoutes).not.toHaveBeenCalled(); + await expect(module.route?.loadRoutes()).rejects.toThrow( + /SHOP_ITEMSS.*shop-context.*shop-feature/, + ); + }); + + it("rejects a handle without a route id", async () => { + const { module } = contextLoading( + [feature("shop-feature", { SHOP_ITEMS: "/shop/items" })], + [{ runtime: {} }], + ); + await expect(module.route?.loadRoutes()).rejects.toThrow(/shop-feature/); + }); +}); diff --git a/tests/component/context-boundary-diagnostics.test.tsx b/tests/component/context-boundary-diagnostics.test.tsx index a1b33e6e..079e2508 100644 --- a/tests/component/context-boundary-diagnostics.test.tsx +++ b/tests/component/context-boundary-diagnostics.test.tsx @@ -21,14 +21,36 @@ vi.mock("../../src/.generated/product-feature-index.ts", async () => ({ PRODUCT_FEATURE_MODULES: [(await import("../helpers/fixture-feature.tsx")).FIXTURE_FEATURE_MODULE], })); vi.mock("../../src/apps/template-app.ts", async () => { - const { FIXTURE_CONTEXT_ROUTES } = await import("../helpers/fixture-feature.tsx"); + const { FIXTURE_CONTEXT_ROUTES, FIXTURE_FEATURE_MODULE } = await import( + "../helpers/fixture-feature.tsx" + ); + const { defineBoundedContextModule } = await import( + "../../src/contexts/bounded-context-module.ts" + ); const items = FIXTURE_CONTEXT_ROUTES.find((route) => route.id === "FIXTURE_ITEMS"); const runtime = (items?.handle as { runtime: unknown }).runtime; return { TEMPLATE_APP_MODULE: { id: "boundary-app", - budget: { maxContexts: 3 }, + budget: { maxContexts: 4 }, contexts: [ + // 09-06 (3). A context defined the regular way refuses the same typo + // when its routes load, before anything renders. + defineBoundedContextModule({ + id: "context-checked-typo", + features: [FIXTURE_FEATURE_MODULE], + budget: { maxFeatures: 1 }, + route: { + path: "fixture/checked/*", + loadRoutes: async () => [ + { + id: "FIXTURE_ITEMSS", + path: "/fixture/checked", + handle: { routeId: "FIXTURE_ITEMSS", runtime }, + }, + ], + }, + }), { id: "context-without-codecs", route: { @@ -131,4 +153,12 @@ describe("context gateway failure diagnostics", () => { boundary: "route", }); }); + + it("reports an unregistered handle refused while the routes load", async () => { + // No feature route owns this URL; the registry's NOT_FOUND splat does. + await expectReportedFailure("/fixture/checked", { + routeId: "NOT_FOUND", + boundary: "route", + }); + }); });