diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index f8f7f75d..129a7cc7 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -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 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`). A route that takes over the platform - home is the exception ("Product home and layouts"). + inside the owning context. No platform route may answer it either: the + router tries `AppShell`'s platform routes first, so the same path as a + platform route, `/` under an id other than `APP_HOME`, or a `*` root + 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` 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 2a2fdbd2..c3766b0c 100644 --- a/src/apps/deployable-app-module.ts +++ b/src/apps/deployable-app-module.ts @@ -4,7 +4,10 @@ import { contractRoutePaths, type BoundedContextModule, } 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"; export type DeployableAppModule = Readonly<{ @@ -55,6 +58,13 @@ export function defineDeployableAppModule 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 feature of context.features) { for (const [routeId, path] of contractRoutePaths(feature.contracts)) { if (FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.includes(routeId)) continue; 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( - `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."), + `Route ${routeId} (${path}) of feature ${feature.id} in context ${context.id} is answered by platform route ${answered?.id} (${answered?.path}). ` + + `A feature replaces a platform route only by declaring its id (${FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS.join(", ")}).`, ); } } diff --git a/tests/architecture/context-route-roots.test.ts b/tests/architecture/context-route-roots.test.ts index b74ebc32..0d66c849 100644 --- a/tests/architecture/context-route-roots.test.ts +++ b/tests/architecture/context-route-roots.test.ts @@ -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. */ describe("replaceable platform routes", () => { const contract = (featureId: string, ...routeIds: string[]) => ({