import { spawnSync } from "node:child_process"; import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; import { afterAll, describe, expect, it } from "vitest"; import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; /** * F-3 (09-07). Adding a feature that owns an API operation must not require * edits outside its own directory: governance, composers and the registry * baseline stay as they are. This writes one such feature (plus the bounded * context it declares, so the check survives the sample's removal) into a copy * of the repository and runs the production generator and `check-registries`. * 0929/07-03. The feature also owns a route with its own search schema and its * own loading surface name, the values FE-REG-ROUTE once kept in a central * allowlist. * 1101/16-01. And an invalidation topic, namespace and edge: every feature * with server state has them, and adding them is additive. */ const FEATURE_ID = "second-api-feature"; const CONTEXT_ID = "second-api-context"; const TOPIC_ID = "qinv.01kb3m8q2v6t4r9s1n5p7c0w"; const FEATURE_CONTRACT = `import { defineRestOperation } from "../../../contracts/api-operations.ts"; import type { InstalledBoundaryMapper } from "../../../contracts/boundary-mapper.ts"; import { mappingFailure, mappingSuccess } from "../../../contracts/boundary-mapper.ts"; import { unvalidatedPayload } from "../../../contracts/unvalidated-payload.ts"; import { defineQueryInvalidationTopic } from "../../../contracts/query-invalidation.ts"; import { defineQueryNamespaceIdentity } from "../../../contracts/query-keys.ts"; import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts"; const OWNER = "feature-frontend-second-api-feature"; const SECOND_ITEM_TOPIC = defineQueryInvalidationTopic("${TOPIC_ID}"); const SECOND_ITEM_NAMESPACE = defineQueryNamespaceIdentity("second-item", 1); const schema = (schemaId: string, boundary: string, direction: string) => Object.freeze({ schemaId, boundary, owner: OWNER, runtime: "zod", schemaVersion: 1, direction }); const codec = (schemaId: string) => runtimeSchemaCodecFromValidator( unvalidatedPayload(schemaId, "registry fixture: only check-registries reads it"), ); const ROUTES = Object.freeze({ SECOND_ITEM_LIST: Object.freeze({ routeId: "SECOND_ITEM_LIST", path: "/second-api/items", paramsSchema: null, searchSchema: "SecondItemListQuery", access: "public", loadingSurface: "second-item-list", errorSurface: "feature-boundary", chunkId: "route-second-item-list", title: "Second items", navigationLabel: null, navigationOrder: null, }), }); // 15-01. Declaration half: what the shell reads at boot. export const SECOND_API_CONTRACT = Object.freeze({ featureId: "${FEATURE_ID}", routes: ROUTES, routeRuntimeContracts: Object.freeze({ SECOND_ITEM_LIST: Object.freeze({ routeId: "SECOND_ITEM_LIST", moduleId: "second-item-list-page", paramsCodec: "none", searchCodec: "SecondItemListQuery", }), }), invalidation: Object.freeze({ topics: Object.freeze([SECOND_ITEM_TOPIC]), namespaces: Object.freeze([SECOND_ITEM_NAMESPACE]), edges: Object.freeze([ Object.freeze({ topicId: SECOND_ITEM_TOPIC, namespace: SECOND_ITEM_NAMESPACE }), ]), }), topicVersions: Object.freeze([ Object.freeze({ topicId: SECOND_ITEM_TOPIC, topicVersion: 1 }), ]), contractPackages: Object.freeze([]), } as const); // Runtime half: the V2 API contract, loaded with feature-runtime.ts. export const SECOND_API_V2_CONTRACT = Object.freeze({ apiOperations: Object.freeze({ GET_SECOND_ITEM: defineRestOperation({ method: "GET", path: "/api/second-items/{itemId}", operationId: "GET_SECOND_ITEM", auth: "none", timeoutMs: null, idempotency: "safe", retry: "runtime", requestSource: "none", requestSchema: "SecondItemRequest", responseSchema: "SecondItemPayload", owner: OWNER, contractVersion: 2, protocol: "REST", semantics: "QUERY", replayPolicy: "SAFE", idempotencyKeyPolicy: "NONE", mapperId: "SecondItemMapper", successStatuses: [200], responseMediaTypes: ["application/json"], maxResponseBytes: 16_384, providerId: "PRIMARY_API", authProfileId: "ANONYMOUS", csrfProfileId: "NO_CSRF_BEARER", pathSchema: "SecondItemParams", pathParameterNames: ["itemId"], maxEncodedSearchBytes: 0, }), }), schemas: Object.freeze({ SecondItemListQuery: schema("SecondItemListQuery", "route-search", "REQUEST"), SecondItemParams: schema("SecondItemParams", "api-request", "REQUEST"), SecondItemRequest: schema("SecondItemRequest", "api-request", "REQUEST"), SecondItemPayload: schema("SecondItemPayload", "api-response", "RESPONSE"), }), runtimeSchemas: Object.freeze({ SecondItemListQuery: codec("SecondItemListQuery"), SecondItemParams: codec("SecondItemParams"), SecondItemRequest: codec("SecondItemRequest"), SecondItemPayload: codec("SecondItemPayload"), }), mappers: Object.freeze({ SecondItemMapper: Object.freeze({ mapperId: "SecondItemMapper", mapperVersion: 1, inputSchemaId: "SecondItemPayload", outputContractId: "SecondItem", owner: OWNER, maxOutputItems: 1, map: (value: unknown) => value && typeof value === "object" ? mappingSuccess(value) : mappingFailure("MAPPING_INVARIANT_REJECTED"), } satisfies InstalledBoundaryMapper), }), } as const); `; const FEATURE_MODULE = `import { defineFeatureModule } from "../feature-module.ts"; import { SECOND_API_CONTRACT } from "./contracts/second-api-contract.ts"; export const FEATURE_MODULE_ID = "${FEATURE_ID}"; export const FEATURE_CONTEXT_ID = "${CONTEXT_ID}"; export const FEATURE_MODULE = defineFeatureModule({ id: FEATURE_MODULE_ID, contracts: SECOND_API_CONTRACT, routes: SECOND_API_CONTRACT.routes, messages: {}, loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME, } as const); `; const FEATURE_RUNTIME = `import { defineFeatureRuntime } from "../feature-module.ts"; import { SECOND_API_V2_CONTRACT } from "./contracts/second-api-contract.ts"; export const FEATURE_RUNTIME = defineFeatureRuntime({ featureId: "${FEATURE_ID}", apiContract: SECOND_API_V2_CONTRACT, adapters: [], contractContributions: [], } as const); `; const FEATURE_GATEWAY = `// The executable consumer of GET_SECOND_ITEM. export const SECOND_ITEM_OPERATION = "GET_SECOND_ITEM"; `; const CONTEXT_ROUTES = `import type { RouteObject } from "react-router-dom"; export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze([]); `; const CONTEXT_MODULE = `export const CONTEXT_MODULE_ID = "${CONTEXT_ID}"; export const CONTEXT_APP_ID = "template-app"; export const CONTEXT_ROUTE_PATH = "second-api/*"; export const CONTEXT_MAX_FEATURES = 1; `; const roots: string[] = []; afterAll(async () => { await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); }); describe("adding a feature with an API operation, a route and an invalidation topic (F-3, 09-07, 0929/07-03, 1101/16-01)", () => { it("passes check-registries without edits outside the feature and its context", async () => { const root = await mkdtemp(path.join(tmpdir(), "second-api-feature-")); roots.push(root); // scripts/check-diagnostics.ts is a FE-REG-TELEMETRY consumer path. for (const entry of [ "src", "config/contracts", "schemas/artifacts", "scripts/check-diagnostics.ts", ]) { await cp(path.resolve(entry), path.join(root, entry), { recursive: true }); } await linkFixtureNodeModules(root); const files: Readonly> = { [`src/contexts/${CONTEXT_ID}/context-module.ts`]: CONTEXT_MODULE, [`src/features/${FEATURE_ID}/feature-module.ts`]: FEATURE_MODULE, [`src/features/${FEATURE_ID}/feature-runtime.ts`]: FEATURE_RUNTIME, [`src/features/${FEATURE_ID}/context-routes.ts`]: CONTEXT_ROUTES, [`src/features/${FEATURE_ID}/contracts/second-api-contract.ts`]: FEATURE_CONTRACT, [`src/features/${FEATURE_ID}/adapters/second-api-gateway.ts`]: FEATURE_GATEWAY, }; for (const [file, content] of Object.entries(files)) { await mkdir(path.dirname(path.join(root, file)), { recursive: true }); await writeFile(path.join(root, file), content); } const generated = spawnSync( process.execPath, [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], { encoding: "utf8" }, ); expect(generated.stderr).toBe(""); expect(generated.status).toBe(0); const checked = spawnSync( process.execPath, [path.resolve("scripts/check-registries.ts")], { cwd: root, encoding: "utf8" }, ); expect(checked.stderr).toBe(""); expect(checked.stdout).toMatch(/11 registries PASS/u); expect(checked.status).toBe(0); const report = JSON.parse( await readFile(path.join(root, "artifacts/quality/registries.json"), "utf8"), ) as { registries: { registryId: string; rows: Record }[]; compatibility: { changes: { registryId: string; field: string; impact: string }[] }; }; const api = report.registries.find(({ registryId }) => registryId === "FE-REG-API"); expect(Object.keys(api?.rows ?? {})).toContain("GET_SECOND_ITEM"); const routes = report.registries.find(({ registryId }) => registryId === "FE-REG-ROUTE"); expect(routes?.rows.SECOND_ITEM_LIST).toMatchObject({ searchSchema: "SecondItemListQuery", loadingSurface: "second-item-list", }); const graph = report.registries.find( ({ registryId }) => registryId === "FE-REG-QUERY-INVALIDATION", ); expect(graph?.rows["invalidation-graph"]).toMatchObject({ topics: expect.arrayContaining([TOPIC_ID]), }); expect( report.compatibility.changes .filter(({ registryId }) => registryId === "FE-REG-QUERY-INVALIDATION") .map(({ field, impact }) => [field, impact]), ).toEqual([ ["edges", "additive"], ["namespaces", "additive"], ["topics", "additive"], ]); }, 60_000); });