create-ailk 0.2.0 → 0.3.0

package/templates/apps/api/src/openapi/__tests__/surface-drift.test.ts

@@ -0,0 +1,293 @@
+/**
+ * @file surface-drift.test.ts
+ * @description The self-description drift gate (#5314).
+ *
+ * Builds the REAL server, takes the route table Fastify actually registered,
+ * and diffs it against both surfaces that claim to describe it — the root
+ * index `endpoints` object and the served OpenAPI `paths` object.
+ *
+ * Both surfaces are read over `inject`, i.e. exactly what an agent would
+ * fetch, never the object the builder returned.
+ *
+ * This gate was RED before the derivation landed: 61 registered routes were
+ * missing from `paths` and 53 from `endpoints`. Two of its five concerns
+ * (AC-1 coverage on each surface) are unfailable now that both surfaces
+ * derive from the same registry they are compared against — that is the
+ * inherent consequence of AC-2's "derived" branch, and the spec's D5 says so.
+ * What stays live is the overlay join (a hand-authored entry whose route no
+ * longer registers — the concern that caught `DELETE /v1/auth/tokens`, whose
+ * real path is `/v1/auth/tokens/:id`), the anti-vacuity floor (an empty or
+ * stale registry would pass a coverage check trivially, so it is asserted
+ * against directly), and the module-agreement case's non-empty guard, which
+ * fails if module gating ever collapses so both configs register identically.
+ *
+ * Mirrors `src/__tests__/module-exclusion.test.ts`'s external-boundary mocks
+ * (CORS, rate-limit, email) — see that file's header for why each is mocked.
+ */
+
+jest.mock("@fastify/cors", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@fastify/rate-limit", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+import { build } from "../../server";
+import { readRegisteredRoutes } from "../spec";
+import {
+  compareSurfaces,
+  formatSurfaceDrift,
+  hasDrift,
+  openApiSurfaceKeys,
+  rootIndexSurfaceKeys,
+  routeKey,
+  toOpenApiPath,
+  type RegisteredRoute,
+} from "../surface-drift";
+
+/** A route every build registers, outside every module conditional. */
+const FLOOR_ROUTE = routeKey("GET", "/v1/content/types");
+
+interface Surfaces {
+  registered: RegisteredRoute[];
+  paths: Record<string, Record<string, unknown>>;
+  endpoints: Record<string, string>;
+}
+
+/**
+ * Build the server under one module configuration and read both surfaces back
+ * over the wire. `undefined` means "leave AILK_ENABLED_MODULES unset", which
+ * is now the default deployment shape (no paid module, D-44 / #5368).
+ */
+async function surfacesFor(enabled: string | undefined): Promise<Surfaces> {
+  const prior = process.env.AILK_ENABLED_MODULES;
+  if (enabled === undefined) {
+    delete process.env.AILK_ENABLED_MODULES;
+  } else {
+    process.env.AILK_ENABLED_MODULES = enabled;
+  }
+
+  try {
+    const app = await build();
+    await app.ready();
+
+    const registered = [...readRegisteredRoutes(app)];
+
+    const rootRes = await app.inject({ method: "GET", url: "/" });
+    const specRes = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    await app.close();
+
+    expect(rootRes.statusCode).toBe(200);
+    expect(specRes.statusCode).toBe(200);
+
+    return {
+      registered,
+      paths: JSON.parse(specRes.body).paths,
+      endpoints: JSON.parse(rootRes.body).endpoints,
+    };
+  } finally {
+    if (prior === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = prior;
+    }
+  }
+}
+
+// The module configurations every claim below is asserted under. Unset is now
+// the default deployment (no paid module, D-44 / #5368), the same as an
+// explicit "" (the OSS-strip build target); a full allowlist is the
+// every-module-on case. A slice route absent under "" must be absent from
+// BOTH surfaces there, which is what makes its absence agreement rather than
+// drift.
+const ALL_PAID_MODULES =
+  "docs,multi-tenant,scheduling,content-write,signal-collectors";
+const CONFIGS: Array<[string, string | undefined]> = [
+  ["AILK_ENABLED_MODULES unset (no paid module, the default)", undefined],
+  ['AILK_ENABLED_MODULES="" (no paid module)', ""],
+  [
+    `AILK_ENABLED_MODULES="${ALL_PAID_MODULES}" (every paid module on)`,
+    ALL_PAID_MODULES,
+  ],
+];
+
+describe("API self-description drift (#5314)", () => {
+  describe.each(CONFIGS)("%s", (_label, enabled) => {
+    let surfaces: Surfaces;
+
+    beforeAll(async () => {
+      surfaces = await surfacesFor(enabled);
+    }, 60000);
+
+    // Anti-vacuity floor. A coverage assertion over an empty registry passes
+    // trivially, so an empty or stale registry is failed directly — the most
+    // likely way a derivation gate silently stops testing anything.
+    it("registers a non-empty route table including the floor route", () => {
+      expect(surfaces.registered.length).toBeGreaterThan(0);
+      const keys = surfaces.registered.map((r) => routeKey(r.method, r.url));
+      expect(keys).toContain(FLOOR_ROUTE);
+      expect(new Set(keys).size).toBe(keys.length);
+    });
+
+    it("publishes no surface entry for a route the server does not register", () => {
+      const diffs = compareSurfaces(
+        surfaces.registered,
+        surfaces.paths,
+        surfaces.endpoints,
+      );
+      const orphaned = diffs.filter((d) => d.orphanedInSurface.length > 0);
+      expect(formatSurfaceDrift(orphaned)).toBe("");
+    });
+
+    it("describes every registered route on both surfaces", () => {
+      const diffs = compareSurfaces(
+        surfaces.registered,
+        surfaces.paths,
+        surfaces.endpoints,
+      );
+      expect(formatSurfaceDrift(diffs)).toBe("");
+      expect(hasDrift(diffs)).toBe(false);
+    });
+
+    // AC-1 names this endpoint specifically: it returns 200 and is what the
+    // consuming site depends on, and before #5314 both surfaces omitted it.
+    // #5366 (D-48) moved it to signal-collectors: the no-drift half
+    // (`missingFromSurface`) holds regardless of whether the route
+    // registers at all, but the route itself now only registers when
+    // signal-collectors is one of the enabled modules for this config.
+    it("describes GET /v1/project-listings/public on both surfaces when registered", () => {
+      const diffs = compareSurfaces(
+        surfaces.registered,
+        surfaces.paths,
+        surfaces.endpoints,
+      );
+      for (const d of diffs) {
+        expect(d.missingFromSurface).not.toContain(
+          routeKey("GET", "/v1/project-listings/public"),
+        );
+      }
+      const signalCollectorsEnabled = (enabled ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .includes("signal-collectors");
+      expect(
+        surfaces.registered.some(
+          (r) => r.url === "/v1/project-listings/public" && r.method === "GET",
+        ),
+      ).toBe(signalCollectorsEnabled);
+    });
+  });
+
+  // Regression: the route table is per-instance, not module state.
+  //
+  // `vercel-handler.ts`'s `getServer()` is a check-then-set — it tests
+  // `!serverInstance`, then awaits twice before assigning — so two concurrent
+  // invocations can both call `build()`. With a module-level table, one
+  // build's reset would land mid-fill of the other and leave a truncated or
+  // doubled set, and both surfaces would silently misreport. Building two
+  // servers under DIFFERENT module configs and asserting each keeps its own
+  // table is what makes that unreachable rather than merely unlikely.
+  it("keeps each server's route table on its own instance", async () => {
+    const prior = process.env.AILK_ENABLED_MODULES;
+    try {
+      process.env.AILK_ENABLED_MODULES = ALL_PAID_MODULES;
+      const allOn = await build();
+      await allOn.ready();
+
+      process.env.AILK_ENABLED_MODULES = "";
+      const noneOn = await build();
+      await noneOn.ready();
+
+      const allKeys = readRegisteredRoutes(allOn).map((r) =>
+        routeKey(r.method, r.url),
+      );
+      const noneKeys = readRegisteredRoutes(noneOn).map((r) =>
+        routeKey(r.method, r.url),
+      );
+
+      // The second build must not have emptied, truncated or doubled the
+      // first — the exact corruption a shared table would produce.
+      expect(allKeys.length).toBeGreaterThan(noneKeys.length);
+      expect(new Set(allKeys).size).toBe(allKeys.length);
+      expect(new Set(noneKeys).size).toBe(noneKeys.length);
+      expect(allKeys).toContain(FLOOR_ROUTE);
+      expect(noneKeys).toContain(FLOOR_ROUTE);
+
+      // And each server's own OpenAPI document still matches its own table.
+      for (const app of [allOn, noneOn]) {
+        const paths = JSON.parse(
+          (await app.inject({ method: "GET", url: "/v1/openapi.json" })).body,
+        ).paths;
+        const endpoints = JSON.parse(
+          (await app.inject({ method: "GET", url: "/" })).body,
+        ).endpoints;
+        expect(
+          formatSurfaceDrift(
+            compareSurfaces(readRegisteredRoutes(app), paths, endpoints),
+          ),
+        ).toBe("");
+      }
+
+      await allOn.close();
+      await noneOn.close();
+    } finally {
+      if (prior === undefined) {
+        delete process.env.AILK_ENABLED_MODULES;
+      } else {
+        process.env.AILK_ENABLED_MODULES = prior;
+      }
+    }
+  }, 60000);
+
+  // AC-4. Asserted as agreement rather than as an exemption list: a disabled
+  // module's routes vanish from the registered set and from both surfaces at
+  // once, so there is nothing for the gate to forgive.
+  it("drops a disabled module's routes from the route table AND both surfaces together", async () => {
+    const allOn = await surfacesFor(ALL_PAID_MODULES);
+    const noneOn = await surfacesFor("");
+
+    const noneKeys = new Set(
+      noneOn.registered.map((r) => routeKey(r.method, r.url)),
+    );
+    const moduleOnly = allOn.registered.filter(
+      (r) => !noneKeys.has(routeKey(r.method, r.url)),
+    );
+
+    // The configurations must actually differ, or this asserts nothing.
+    expect(moduleOnly.length).toBeGreaterThan(0);
+
+    // Every module-only route is described when its module is on...
+    expect(
+      formatSurfaceDrift(
+        compareSurfaces(allOn.registered, allOn.paths, allOn.endpoints),
+      ),
+    ).toBe("");
+
+    // ...and named by neither surface when it is off, which is agreement.
+    //
+    // Each surface is parsed by the instrument's own reader, and each route is
+    // compared in that surface's vocabulary — OpenAPI-templated for `paths`,
+    // Fastify-shaped for `endpoints`. Comparing raw values instead would make
+    // this assertion quietly weaker than it reads: `paths` keys `{id}` where a
+    // registered route says `:id`, so every parametric route would "pass" on a
+    // vocabulary mismatch, and `endpoints` groups methods into one value
+    // (`"GET/PUT/DELETE /v1/user/data/:key"`), which never equals a
+    // single-method key. Both halves would then be vacuous for exactly the
+    // routes most likely to regress.
+    const offPathKeys = openApiSurfaceKeys(noneOn.paths);
+    const offEndpointKeys = rootIndexSurfaceKeys(noneOn.endpoints);
+    for (const { method, url } of moduleOnly) {
+      expect(offPathKeys).not.toContain(routeKey(method, toOpenApiPath(url)));
+      expect(offEndpointKeys).not.toContain(routeKey(method, url));
+    }
+  }, 60000);
+});

package/templates/apps/api/src/openapi/index.ts

@@ -3,10 +3,16 @@
  */
 import type { FastifyPluginAsync } from "fastify";
 
-import { buildOpenApiSpec } from "./spec.js";
+import { buildOpenApiSpec, readRegisteredRoutes } from "./spec.js";
 
 export const openapiRoutes: FastifyPluginAsync = async (fastify) => {
-  fastify.get("/v1/openapi.json", async (_request, reply) => {
-    return reply.send(buildOpenApiSpec());
+  fastify.get("/v1/openapi.json", async (request, reply) => {
+    // The route table comes off the instance that served this request (#5314),
+    // never from module state — two servers built concurrently in one process
+    // would otherwise share, and corrupt, one table. Absent (a bare Fastify
+    // instance with no `build()`) degrades to the hand-authored paths.
+    return reply.send(
+      buildOpenApiSpec(undefined, readRegisteredRoutes(request.server)),
+    );
   });
 };