import { access, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; import { pathToFileURL } from "node:url"; import { afterEach, describe, expect, it } from "vitest"; import { CreateFeatureError, parseRequest, planFeature, randomTopicSuffix, writeFeatureFiles, type FeatureRequest, type InstalledFacts, } from "../../scripts/create-feature.ts"; import { createFileSystemDeclarationSource } from "../../scripts/generate-product-feature-index.ts"; import { PLACEHOLDER_CONTRACT_PACKAGE_DIGEST } from "../../src/contracts/deployment-admission.ts"; /** * U7. What `pnpm create:feature` renders, checked without touching the * repository. test:feature-scaffold writes a feature into a copy and runs the * gates on it; this file covers the ids, the topic, the order and the refusals. */ const INSTALLED: InstalledFacts = Object.freeze({ appIds: ["template-app"], featureIds: ["orders-feature", "drafts-feature"], contexts: [ { id: "orders-context", routePath: "orders/*" }, { id: "billing-context", routePath: "billing/*" }, ], contextDirectories: ["orders-context", "billing-context"], routes: [ { routeId: "APP_HOME", path: "/", chunkId: "route-home", navigationOrder: 10 }, { routeId: "ORDERS_LIST", path: "/orders", chunkId: "route-orders-list", navigationOrder: 50 }, { routeId: "NOT_FOUND", path: "*", chunkId: "route-not-found", navigationOrder: null }, ], topics: ["qinv.0000000000000000000000000a"], messageKeys: ["route.APP_HOME.title", "home.list.title"], }); const TOPIC_SUFFIX = "abcdefghjkmnpqrstvwxyz0123"; function plan(request: FeatureRequest, installed: InstalledFacts = INSTALLED) { return planFeature(request, installed, () => TOPIC_SUFFIX); } function rendered(request: FeatureRequest): string { return [...plan(request).files.values()].join("\n"); } describe("create:feature rendering", () => { it("prefixes every global id with the feature and carries no sample token", () => { const text = rendered({ id: "invoice-feature" }); expect(text).not.toMatch(/reference/iu); const ids = [ ...text.matchAll( /\b(?:schemaId|inputSchemaId|operationId|mapperId|outputContractId|policyId|diagnosticsOperation|definitionId|chunkId|routeId|moduleId|loadingSurface|contributionId|owner)\s*:\s*"([^"]+)"/gu, ), ...text.matchAll(/\bzodValidator\(\s*"([^"]+)"/gu), ...text.matchAll(/defineQueryNamespaceIdentity\(\s*"([^"]+)"/gu), ...text.matchAll(/kind: "([a-z][^"]*\.[^"]*)"/gu), ...text.matchAll(/^\s+"((?:route\.)?[A-Za-z_.]+)": "/gmu), ].map((match) => match[1] ?? ""); expect(ids.length).toBeGreaterThan(30); for (const id of ids) { expect(id).toMatch( /^(?:INVOICE_|Invoice|invoice[.-]|route\.INVOICE_LIST\.|route-invoice-|feature-frontend-invoice-feature$)/u, ); } expect(text).not.toMatch(/"NoRequest"/u); }); it("names the route, context and topic it creates", () => { const created = plan({ id: "invoice-feature" }); expect(created).toMatchObject({ contextId: "invoice-context", newContext: true, routeId: "INVOICE_LIST", routePath: "/invoice", topic: `qinv.${TOPIC_SUFFIX}`, placeholder: true, }); expect([...created.files.keys()]).toEqual( expect.arrayContaining([ "src/contexts/invoice-context/context-module.ts", "src/features/invoice-feature/feature-module.ts", "tests/features/invoice-feature/invoice-feature-input.test.ts", "tests/features/invoice-feature/invoice-list-page.test.tsx", "docs/accessibility/route-reviews/INVOICE_LIST.md", ]), ); expect([...created.files.keys()].some((file) => file.includes("/domain/"))).toBe(false); expect(created.files.get("src/contexts/invoice-context/context-module.ts")).toContain( 'CONTEXT_ROUTE_PATH = "invoice/*"', ); expect(created.files.get("docs/accessibility/route-reviews/INVOICE_LIST.md")).toMatch( /^Status: pending-manual-review$/mu, ); }); it("generates a fresh lower-case 26-character topic and refuses an installed one", () => { const first = randomTopicSuffix(); expect(first).toMatch(/^[0-9a-hjkmnp-tv-z]{26}$/u); expect(randomTopicSuffix()).not.toBe(first); expect(() => planFeature({ id: "invoice-feature" }, INSTALLED, () => "0000000000000000000000000a"), ).toThrow(/qinv\.0000000000000000000000000a is already installed/u); }); it("places the route after the last navigation entry", () => { expect(rendered({ id: "invoice-feature" })).toContain("navigationOrder: 60,"); }); it("adds the route under an existing context's root", () => { const created = plan({ id: "invoice-feature", context: "billing-context" }); expect(created).toMatchObject({ newContext: false, routePath: "/billing/invoice" }); expect([...created.files.keys()].some((file) => file.startsWith("src/contexts/"))).toBe(false); }); it("pins the placeholder through its exported constant, or the given package", () => { expect(rendered({ id: "invoice-feature" })).toContain( "digest: PLACEHOLDER_CONTRACT_PACKAGE_DIGEST,", ); const digest = `sha256:${"ab".repeat(32)}`; const pinned = plan({ id: "invoice-feature", contractPackage: { packageId: "@org-contracts/invoice", version: "1.4.2", digest, sourceRevision: "0a1b2c3d", }, }); const contract = pinned.files.get( "src/features/invoice-feature/contracts/invoice-feature-contract.ts", ); expect(pinned.placeholder).toBe(false); expect(contract).toContain(`digest: "${digest}",`); expect(contract).not.toContain("PLACEHOLDER"); expect(digest).not.toBe(PLACEHOLDER_CONTRACT_PACKAGE_DIGEST); }); // 1101 README 14.3. test:feature-scaffold runs the gateway test this renders. it("reads the paired backend's Envelope and tests it with the backend's own bodies", () => { const { files } = plan({ id: "invoice-feature" }); const contracts = "src/features/invoice-feature/contracts"; expect(files.get(`${contracts}/invoice-contract-contribution.ts`)).toContain( 'responseEnvelope: "ENVELOPE_V1" as const,', ); expect(files.get(`${contracts}/invoice-schemas.ts`)).toMatch( /invoiceProblemSchema = z\s*\.object\(\{\s*code: z\.string\(\)\.regex/u, ); expect( files.get("tests/features/invoice-feature/invoice-http-gateway.test.ts"), ).toContain('success: true, data: [{ id: "item-1", name: "First item" }]'); }); // 1103/03-07. The paired backend's new-feature.sh maps / (its // camel-case name plus s, es or ies); the frontend's list reads the same // resource path. The backend's api-base-path belongs in API_BASE_URL. it.each([ ["invoice-feature", "/invoices"], ["purchase-order-feature", "/purchaseOrders"], ["batch-feature", "/batches"], ["box-feature", "/boxes"], ["company-feature", "/companies"], ["day-feature", "/days"], ["status-feature", "/statuses"], ])("lists %s at the backend scaffold's resource path %s", (id, apiPath) => { const base = id.slice(0, -"-feature".length); const contribution = plan({ id }).files.get( `src/features/${id}/contracts/${base}-contract-contribution.ts`, ); expect(contribution).toContain(`const API_PATH = "${apiPath}";`); }); // 1103/03-02. A page list's meta.page.total counts every page. it("shows the total the backend counted, not the length of the first page", () => { const { files } = plan({ id: "invoice-feature" }); expect(files.get("src/features/invoice-feature/contracts/invoice-mapper.ts")).toContain( "total: page?.total ?? items.length", ); expect( files.get("src/features/invoice-feature/presentation/invoice-list-page.tsx"), ).toContain('message("invoice.list.resultCount", { count: query.data.total })'); }); }); /** * 1103/09-06, 03-07. `--with-create` adds the paired backend scaffold's other * two endpoints (POST /, GET //{id}) with a detail page, a * create form and the unknown-result handling. test:feature-scaffold and * test:sample-removal generate it and run the gates on it. */ describe("create:feature --with-create", () => { const contributionOf = (files: ReadonlyMap) => files.get("src/features/invoice-feature/contracts/invoice-contract-contribution.ts") ?? ""; it("prefixes every id of the slice and adds its routes, pages and tests", () => { const created = plan({ id: "invoice-feature", write: "NEVER" }); const text = [...created.files.values()].join("\n"); // No sample id. (`supportReference` is a platform prop.) Written so this // file holds no sample id itself, which test:sample-removal looks for. expect(text).not.toMatch(/REFERENCE_|ReferenceResource|reference-(?:feature|context)/u); const ids = [ ...text.matchAll( /\b(?:schemaId|operationId|policyId|diagnosticsOperation|definitionId|chunkId|routeId|moduleId|loadingSurface|contributionId)\s*:\s*"([^"]+)"/gu, ), ...text.matchAll(/\bzodValidator\(\s*"([^"]+)"/gu), ...text.matchAll(/kind: "([a-z][^"]*\.[^"]*)"/gu), ...text.matchAll(/^\s+"((?:route\.)?[A-Za-z_.]+)": "/gmu), ].map((match) => match[1] ?? ""); expect(ids.length).toBeGreaterThan(50); for (const id of ids) { expect(id).toMatch( /^(?:INVOICE_|Invoice|invoice[.-]|route\.INVOICE_(?:LIST|DETAIL|CREATE)\.|route-invoice-)/u, ); } expect([...created.files.keys()]).toEqual( expect.arrayContaining([ "src/features/invoice-feature/presentation/invoice-detail-page.tsx", "src/features/invoice-feature/presentation/invoice-create-page.tsx", "src/features/invoice-feature/presentation/invoice-form.ts", "src/features/invoice-feature/presentation/invoice-route-codecs.ts", "src/features/invoice-feature/presentation/use-invoice-item.ts", "src/features/invoice-feature/presentation/use-invoice-create.ts", "tests/features/invoice-feature/invoice-create-page.test.tsx", "docs/accessibility/route-reviews/INVOICE_DETAIL.md", "docs/accessibility/route-reviews/INVOICE_CREATE.md", ]), ); expect(created.routes).toEqual([ { routeId: "INVOICE_LIST", path: "/invoice" }, { routeId: "INVOICE_DETAIL", path: "/invoice/items/:invoiceId" }, { routeId: "INVOICE_CREATE", path: "/invoice/new" }, ]); }); // 1103/16-01. Every generated operation declares the Envelope. it("declares the Envelope on every operation it writes", () => { const contribution = contributionOf(plan({ id: "invoice-feature", write: "NEVER" }).files); expect(contribution.match(/operationId: "INVOICE_[A-Z_]+",/gu)).toHaveLength(3); expect(contribution.match(/responseEnvelope: "ENVELOPE_V1" as const,/gu)).toHaveLength(3); expect(contribution).toContain("pathTemplate: `${API_PATH}/{id}`,"); }); // 1103/03-07. new-feature.sh generates a NOT_IDEMPOTENT create: the backend // ignores a key, so a same-key resend would create a second item. it("matches the backend scaffold's NOT_IDEMPOTENT create with a NEVER command", () => { const contribution = contributionOf(plan({ id: "invoice-feature", write: "NEVER" }).files); expect(contribution).toContain('retrySemantics: "NEVER" as const,'); expect(contribution).toContain("retryBudget: 0 as const,"); expect(contribution).not.toContain("IDEMPOTENCY_REPLAY"); expect(contribution).toContain("acceptedStatuses: Object.freeze([201]),"); // 1103/03-01. The backend checks the name before its transaction. expect(contribution).toContain('refusedBeforeWrite: Object.freeze(["INVOICE_INVALID"]),'); }); // 1105/08-04. Like the reference form: while a save this page did not // start holds the coordinator, the save is off and the feedback says a // save is running, instead of a save button that does nothing. // 1112/01-01. The rule is the platform form's (useAppForm `mutation`, // FormSaveFeedback; tests/component/form-foundation.test.tsx walks it): // the page turns the button off from the form's state. it("keeps the create's save off and says so while another save of it runs", () => { const page = plan({ id: "invoice-feature", write: "NEVER" }).files.get( "src/features/invoice-feature/presentation/invoice-create-page.tsx", ) ?? ""; expect(page).toContain("disabled={form.effectUnknown || form.otherSaveRunning}"); expect(page).toContain(" { const { files } = plan({ id: "invoice-feature", write }); expect( files.get("src/features/invoice-feature/presentation/invoice-create-page.tsx"), ).toContain('void navigate(invoiceRouteUrl("INVOICE_LIST"));'); expect( files.get("tests/features/invoice-feature/invoice-create-page.test.tsx"), ).toContain('it("opens the list after the user confirms a create whose response was lost"'); }, ); // 1106/08-02. A save that ended after the user left the form took them to // the item anyway. The page opens the item or the list only while it is // still mounted, and the generated page test walks that path. // 1112/01-01. "While mounted" is the platform form's rule: the page opens // the item in `onSaved` and the list in FormSaveFeedback's `onConfirmed`, // which the form calls only while it is mounted. it.each(["NEVER", "KEYED"] as const)( "does not open the item when the user left during a %s create", (write) => { const { files } = plan({ id: "invoice-feature", write }); const page = files.get("src/features/invoice-feature/presentation/invoice-create-page.tsx") ?? ""; expect(page).toContain("onSaved: (item) => {"); expect(page).toContain("onConfirmed={() => {"); expect(page).not.toContain("mounted"); expect( files.get("tests/features/invoice-feature/invoice-create-page.test.tsx"), ).toContain('it("stays on the list the user went to while the create was saving"'); }, ); // 1103/16-07. A backend create made KEYED (IdempotencyExecutor) takes these. it("writes the KEYED values for a backend create made KEYED", () => { const { files } = plan({ id: "invoice-feature", write: "KEYED" }); const contribution = contributionOf(files); expect(contribution).toContain('retrySemantics: "KEYED" as const,'); expect(contribution).toContain('mode: "IDEMPOTENCY_REPLAY" as const,'); expect(contribution).toContain('operationIdentityField: "idempotencyKey",'); expect(contribution).toContain("retryBudget: 1 as const,"); expect( files.get("tests/features/invoice-feature/invoice-create-page.test.tsx"), ).toContain('posts[1]!.headers.get("idempotency-key")'); expect( files.get("src/features/invoice-feature/presentation/use-invoice-create.ts"), ).toContain("...commandMutationIdentity(INVOICE_CREATE_ITEM_CONTRACT),"); }); it("refuses a slice route that collides with an installed one", () => { expect(() => plan( { id: "invoice-feature", write: "NEVER" }, { ...INSTALLED, routes: [ ...INSTALLED.routes, { routeId: "LEGACY", path: "/invoice/new", chunkId: "route-legacy", navigationOrder: null }, ], }, ), ).toThrow(/route INVOICE_CREATE .* collides with installed route LEGACY/u); }); it("takes --with-create and --keyed, and --keyed only with --with-create", () => { expect(parseRequest(["invoice-feature", "--with-create"])).toMatchObject({ write: "NEVER", }); expect(parseRequest(["invoice-feature", "--with-create", "--keyed"])).toMatchObject({ write: "KEYED", }); expect(parseRequest(["invoice-feature"]).write).toBeUndefined(); expect(() => parseRequest(["invoice-feature", "--keyed"])).toThrow( /--keyed needs --with-create/u, ); }); }); /** * X1 (2026-11-04). The generated context declaration is executed, not only * read as text: the generator's declaration source reads it from disk, and an * app module built from its exported route root accepts every route the * feature declares (the check the router relies on, 09-06). */ describe("create:feature context declaration", () => { const roots: string[] = []; afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); }); async function appFor( contextId: string, routePath: string, maxFeatures: number, routes: readonly Readonly<{ routeId: string; path: string }>[], ) { const { defineBoundedContextModule } = await import( "../../src/contexts/bounded-context-module.ts" ); const { defineDeployableAppModule } = await import("../../src/apps/deployable-app-module.ts"); return defineDeployableAppModule({ id: "template-app", budget: { maxContexts: 20 }, contexts: [ defineBoundedContextModule({ id: contextId, budget: { maxFeatures }, features: [ { id: "invoice-feature", contracts: { routes: Object.fromEntries(routes.map((route) => [route.routeId, route])), }, } as never, ], route: { path: routePath, loadRoutes: async () => [] }, }), ], }); } it.each([undefined, "NEVER"] as const)( "writes a context module the generator reads and whose root holds the routes (write %s)", async (write) => { const root = await mkdtemp(path.join(tmpdir(), "create-feature-context-")); roots.push(root); const created = plan({ id: "invoice-feature", write }); await mkdir(path.join(root, "src/apps/template-app"), { recursive: true }); await writeFile( path.join(root, "src/apps/template-app/app-module.ts"), 'export const APP_MODULE_ID = "template-app";\nexport const APP_MAX_CONTEXTS = 20;\n', ); await writeFeatureFiles(root, created.files); const source = await createFileSystemDeclarationSource(root); expect(source.contextsOf("template-app")).toEqual([ { id: "invoice-context", appId: "template-app", routePath: "invoice/*", maxFeatures: 20 }, ]); expect(source.featuresOf("invoice-context").map((feature) => feature.id)).toEqual([ "invoice-feature", ]); const declared = (await import( pathToFileURL(path.join(root, "src/contexts/invoice-context/context-module.ts")).href )) as Record; expect(declared).toMatchObject({ CONTEXT_MODULE_ID: "invoice-context", CONTEXT_APP_ID: "template-app", CONTEXT_ROUTE_PATH: "invoice/*", }); const app = await appFor( String(declared["CONTEXT_MODULE_ID"]), String(declared["CONTEXT_ROUTE_PATH"]), Number(declared["CONTEXT_MAX_FEATURES"]), created.routes, ); expect(app.contexts.map((context) => context.id)).toEqual(["invoice-context"]); }, ); it("puts the routes under an existing context's root", async () => { const created = plan({ id: "invoice-feature", context: "billing-context", write: "NEVER" }); expect(created.routes.map((route) => route.path)).toEqual([ "/billing/invoice", "/billing/invoice/items/:invoiceId", "/billing/invoice/new", ]); await expect(appFor("billing-context", "billing/*", 20, created.routes)).resolves.toBeDefined(); }); }); // 1112/01-03. The generated input reports a failed load, not one a scope // fence ended (sign-out, account switch): it asks the shared rule. describe("generated feature input telemetry", () => { it("does not report a load a scope fence ended", () => { const { files } = plan({ id: "invoice-feature" }); expect(files.get("src/features/invoice-feature/application/invoice-feature-api.ts")).toContain( "isAbortFailure(result.error)", ); expect(files.get("tests/features/invoice-feature/invoice-feature-input.test.ts")).toContain( 'createFailure("SCOPE_GENERATION_CHANGED"', ); }); }); describe("create:feature refusals", () => { it.each(["Invoice", "invoice_feature", "-invoice", "invoice--x", "invoice-", "", "a".repeat(41)])( "refuses the id %j", (id) => { expect(() => plan({ id })).toThrow(/kebab-case/u); }, ); it.each([ [{ id: "orders-feature" }, /already a feature or context/u], [{ id: "orders-context" }, /already a feature or context/u], [{ id: "orders" }, /prefix its ids with "orders", which orders-feature already uses/u], [{ id: "billing-feature" }, /pass --context billing-context/u], [{ id: "invoice-feature", context: "orders" }, /already owns the route root orders\/\*/u], [{ id: "invoice-feature", context: "drafts-feature" }, /is a feature id/u], [{ id: "home-feature" }, /message keys already exist: home\.list\.title/u], [ { id: "invoice-feature", contractPackage: { packageId: "@org-contracts/invoice", version: "1.4.2", digest: "sha256:abc", sourceRevision: "0a1b2c3d", }, }, /not a pinned identity: invoice-feature: package digest/u, ], ] as const)("refuses %j", (request, reason) => { expect(() => plan(request)).toThrow(reason); }); it("refuses a route that collides with an installed one", () => { expect(() => plan( { id: "invoice-feature" }, { ...INSTALLED, routes: [ ...INSTALLED.routes, { routeId: "LEGACY", path: "/invoice", chunkId: "route-legacy", navigationOrder: null }, ], }, ), ).toThrow(/collides with installed route LEGACY/u); }); }); describe("create:feature writing", () => { const roots: string[] = []; afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); }); async function emptyRoot(): Promise { const root = await mkdtemp(path.join(tmpdir(), "create-feature-")); roots.push(root); return root; } it("refuses to overwrite and writes nothing when one target exists", async () => { const root = await emptyRoot(); const files = plan({ id: "invoice-feature" }).files; await mkdir(path.join(root, "docs/accessibility/route-reviews"), { recursive: true }); await writeFile(path.join(root, "docs/accessibility/route-reviews/INVOICE_LIST.md"), "kept\n"); await expect(writeFeatureFiles(root, files)).rejects.toThrow( /refusing to overwrite: docs\/accessibility\/route-reviews\/INVOICE_LIST\.md/u, ); expect(await readdir(root)).toEqual(["docs"]); }); it("refuses an existing feature directory", async () => { const root = await emptyRoot(); await mkdir(path.join(root, "src/features/invoice-feature"), { recursive: true }); await expect( writeFeatureFiles(root, plan({ id: "invoice-feature" }).files, [ "src/features/invoice-feature", ]), ).rejects.toThrow(CreateFeatureError); }); it("removes what it wrote when a later write fails", async () => { const root = await emptyRoot(); const files = new Map([ ["src/features/broken/first.ts", "export {};\n"], // A file cannot be a directory, so this write fails after the first. ["src/features/broken/first.ts/second.ts", "export {};\n"], ]); await expect(writeFeatureFiles(root, files)).rejects.toThrow(); await expect(access(path.join(root, "src"))).rejects.toThrow(); }); }); // 1112/01-01. The generated create page leaves the rules of a save through // its mutation to the platform form: it gives useAppForm the mutation and // draws FormSaveFeedback, so a platform fix to those rules reaches it. describe("generated create page", () => { it("hands the save rules to the platform form", () => { const { files } = plan({ id: "invoice-feature", write: "KEYED" }); const page = files.get("src/features/invoice-feature/presentation/invoice-create-page.tsx") ?? ""; expect(page).toContain(" mutation,\n"); expect(page).toContain(" { const { files } = plan({ id: "invoice-feature", write: "KEYED" }); const page = files.get("src/features/invoice-feature/presentation/invoice-create-page.tsx") ?? ""; expect(page).toContain("onSaved:"); expect(page).not.toMatch(/useRef|useEffect|mounted/u); expect(page).not.toMatch(/resendUnknown|settleApplied|onResent/u); }); });