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"; import { withoutTakenOverPlatformRoutes } from "../../src/contracts/routes.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, schemas: {}, adapters: [], contractContributions: [], }), }); } function context( id: string, path: string, features: readonly ReturnType[], loadLayout?: () => Promise<() => null>, ) { return defineBoundedContextModule({ id, features, budget: { maxFeatures: 10 }, route: { path, loadRoutes: async () => [], ...(loadLayout ? { loadLayout } : {}) }, }); } 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("accepts the platform home a feature replaces whatever its root (09-03)", () => { // The router mounts a replaced platform route at its own path. expect(() => app( context("home-context", "home/*", [ feature("home-feature", { APP_HOME: "/", HOME_FEED: "/home/feed" }), ]), ), ).not.toThrow(); }); 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/); }); }); /** * 09-03. Several context roots may sit under one layout, and layouts are * siblings of AppShell at `/`: a root still takes the URLs under it whatever * layout either context has, so the rule above spans every layout. */ describe("context route roots under layouts", () => { const siteLayout = async () => () => null; const studioLayout = async () => () => null; it("accepts several roots under one layout and nested roots across layouts", () => { expect(() => app( context("site", "*", [feature("site", { APP_HOME: "/", EXPLORE: "/explore" })], siteLayout), context("topics", "topics/*", [feature("topics", { TOPICS: "/topics" })], siteLayout), context("studio", "studio/*", [feature("studio", { STUDIO: "/studio" })], studioLayout), context("shop", "shop/*", [feature("shop", { SHOP: "/shop" })]), ), ).not.toThrow(); }); it("rejects a route another layout's root takes over", () => { expect(() => app( context("site", "*", [feature("site", { DRAFTS: "/studio/drafts" })], siteLayout), context("studio", "studio/*", [feature("studio", { STUDIO: "/studio" })], studioLayout), ), ).toThrow(/DRAFTS.*site.*studio \(studio\/\*\)/); }); }); /** * 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_PLATFORM_COPY: "/examples/platform" }), ]), ), ).toThrow(/EXAMPLES_PLATFORM_COPY.*\/examples\/platform.*examples-feature.*examples.*EXAMPLES_PLATFORM/); }); 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_PLATFORM_COPY: "/examples/platform" }), ], layout), ), ).toThrow(/EXAMPLES_PLATFORM_COPY.*EXAMPLES_PLATFORM/); }); it("rejects two feature routes with the same path, naming both", () => { // The router ranks equal paths by order, so the second is never rendered. // Parameter names do not change the rank. expect(() => app( context("shop", "shop/*", [ feature("orders", { ORDER_DETAIL: "/shop/items/:orderId" }), feature("items", { ITEM_DETAIL: "/shop/items/:itemId" }), ]), ), ).toThrow(/ITEM_DETAIL.*\/shop\/items\/:itemId.*items.*ORDER_DETAIL.*orders/); }); it.each< Readonly<{ differ: string; first: Readonly>; second: Readonly>; }> >([ { differ: "only by letter case", first: { ITEM_DETAIL: "/shop/items/:itemId" }, second: { OTHER_ITEM_DETAIL: "/shop/Items/:id" }, }, { differ: "only by a trailing slash", first: { ITEM_LIST: "/shop/items" }, second: { OTHER_ITEM_LIST: "/shop/items/" }, }, ])("rejects two feature routes whose paths differ $differ", ({ first, second }) => { // 1103/08-04. The router matches paths case-insensitively and ignores a // trailing slash, so these tie like identical paths. expect(() => app( context("shop", "shop/*", [feature("items", first), feature("others", second)]), ), ).toThrow(/OTHER_ITEM_.*others.*has the same path as route ITEM_.*items/); }); it("accepts a static path next to a parameter at the same depth", () => { expect(() => app( context("shop", "shop/*", [ feature("items", { ITEM_NEW: "/shop/items/new", ITEM_DETAIL: "/shop/items/:itemId", }), ]), ), ).not.toThrow(); }); 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[]) => ({ featureId, routes: Object.fromEntries(routeIds.map((routeId) => [routeId, {}])), }); const platform = { APP_HOME: "platform home", NOT_FOUND: "platform not found" }; it("drops the platform routes a feature took over and keeps the rest", () => { expect( withoutTakenOverPlatformRoutes(platform, [contract("site", "APP_HOME", "EXPLORE")]), ).toEqual({ NOT_FOUND: "platform not found" }); expect(withoutTakenOverPlatformRoutes(platform, [contract("shop", "SHOP")])).toEqual(platform); }); it("keeps a platform route the platform does not let features take over", () => { // The registry composition then refuses the duplicate id as before. expect( withoutTakenOverPlatformRoutes(platform, [contract("shop", "NOT_FOUND")]), ).toEqual(platform); }); it("rejects a second feature taking over the same platform route, naming both", () => { expect(() => withoutTakenOverPlatformRoutes(platform, [ contract("site", "APP_HOME"), contract("blog", "APP_HOME"), ]), ).toThrow(/APP_HOME.*site.*blog/); }); }); /** * 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/); }); });