@mandujs/core 0.35.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/openapi/generator.ts

@@ -26,6 +26,33 @@ import {
   isZodRequired,
 } from "../contract/zod-utils";
 
+// ============================================
+// Schema name-hint side table
+// ============================================
+
+/**
+ * Side-channel naming hints for generated OpenAPI schemas.
+ *
+ * The hoist pass needs a preferred name for each object schema but we
+ * don't want to serialize that hint into the output document. A WeakMap
+ * keyed by the generated `OpenAPISchema` object gives us name access
+ * during the post-processing pass without polluting the spec JSON.
+ *
+ * Hints are advisory — the hoist pass falls back to a deterministic
+ * `Schema_<hash8>` name when no hint is attached.
+ */
+const schemaNameHints = new WeakMap<OpenAPISchema, string>();
+
+function setSchemaNameHint(schema: OpenAPISchema | undefined, hint: string | undefined): void {
+  if (!schema || !hint) return;
+  // Don't overwrite an existing hint — first attribution wins. This matches
+  // the "first-come wins" policy for structurally-identical schemas with
+  // different user-given names.
+  if (!schemaNameHints.has(schema)) {
+    schemaNameHints.set(schema, hint);
+  }
+}
+
 // ============================================
 // OpenAPI Types
 // ============================================
@@ -140,11 +167,14 @@ export interface OpenAPIDocument {
 export function zodToOpenAPISchema(zodSchema: z.ZodTypeAny): OpenAPISchema {
   const typeName = getZodTypeName(zodSchema);
 
-  // Handle ZodOptional
+  // Handle ZodOptional — optionality is expressed by the parent object's
+  // `required[]` array (or by `parameter.required: false`), NOT by the
+  // field's own schema. Emitting `nullable: true` here would conflate
+  // "may be absent" with "may literally be null", which breaks Postman,
+  // codegen, and Swagger UI (they'd all treat the field as nullable).
   if (typeName === "ZodOptional") {
     const inner = getZodInnerType(zodSchema);
-    const innerSchema = inner ? zodToOpenAPISchema(inner) : {};
-    return { ...innerSchema, nullable: true };
+    return inner ? zodToOpenAPISchema(inner) : {};
   }
 
   // Handle ZodDefault
@@ -370,6 +400,35 @@ function generateParameters(
   return parameters;
 }
 
+/**
+ * Convert an arbitrary identifier to a PascalCase token suitable for an
+ * OpenAPI component name. Non-alphanumeric characters become word
+ * separators; leading digits are prefixed with `_` so the result is a
+ * valid JSON Schema identifier.
+ */
+function pascal(input: string): string {
+  if (!input) return "";
+  const words = input
+    .split(/[^a-zA-Z0-9]+/g)
+    .filter((w) => w.length > 0)
+    .map((w) => w[0].toUpperCase() + w.slice(1));
+  const joined = words.join("");
+  if (!joined) return "";
+  return /^[0-9]/.test(joined) ? `_${joined}` : joined;
+}
+
+/**
+ * Derive a naming hint root for a contract. Prefers the explicit
+ * `contract.name`; falls back to the route id (e.g. `api/users` →
+ * `ApiUsers`). Guarantees we always have a non-empty PascalCase prefix
+ * for generated component names.
+ */
+function deriveContractNameRoot(contract: ContractSchema, route: RouteSpec): string {
+  const hint = contract.name ?? route.id;
+  const pascalized = pascal(hint);
+  return pascalized || "Schema";
+}
+
 /**
  * Generate OpenAPI operation for a method
  */
@@ -386,6 +445,11 @@ function generateOperation(
     responses: {},
   };
 
+  // Derive a naming hint root from the contract for the hoist pass.
+  // Example: `contract.name = "users"` → `Users`. Falls back to a
+  // route-derived identifier so every contract has *some* stable prefix.
+  const nameRoot = deriveContractNameRoot(contract, route);
+
   // Parameters
   if (methodSchema) {
     const params = generateParameters(methodSchema, route.pattern);
@@ -395,8 +459,13 @@ function generateOperation(
 
     // Request body
     if (methodSchema.body) {
+      const bodySchema = zodToOpenAPISchema(methodSchema.body);
+      // Hint: `UsersBody` / `UsersPostBody` — method-qualified avoids
+      // collisions when GET/POST/PUT on the same contract have distinct
+      // request bodies.
+      setSchemaNameHint(bodySchema, `${nameRoot}${pascal(method)}Body`);
       const requestBodyContent: OpenAPIRequestBody["content"]["application/json"] = {
-        schema: zodToOpenAPISchema(methodSchema.body),
+        schema: bodySchema,
       };
 
       // Add examples if provided
@@ -430,6 +499,10 @@ function generateOperation(
     }
 
     const schema = zodToOpenAPISchema(zodSchema);
+    // Hint: `UsersResponse200` / `UsersPostResponse201`. Status-qualified
+    // so `200` and `400` responses don't collide when both are
+    // `{ error: string }` style objects.
+    setSchemaNameHint(schema, `${nameRoot}${pascal(method)}Response${statusCode}`);
     const hasContent = Object.keys(schema).length > 0;
 
     const responseContent: OpenAPIResponse["content"] = hasContent
@@ -493,6 +566,17 @@ export async function generateOpenAPIDocument(
     version?: string;
     description?: string;
     servers?: OpenAPIServer[];
+    /**
+     * Hoist schemas that appear ≥`hoistThreshold` times into
+     * `components.schemas` and replace inline occurrences with `$ref`.
+     * @default true
+     */
+    hoistSchemas?: boolean;
+    /**
+     * Minimum occurrence count required to hoist a schema.
+     * @default 2
+     */
+    hoistThreshold?: number;
   } = {}
 ): Promise<OpenAPIDocument> {
   const paths: Record<string, OpenAPIPathItem> = {};
@@ -527,7 +611,7 @@ export async function generateOpenAPIDocument(
     paths[openApiPattern] = pathItem;
   }
 
-  return {
+  const doc: OpenAPIDocument = {
     openapi: "3.0.3",
     info: {
       title: options.title || "Mandu API",
@@ -540,6 +624,277 @@ export async function generateOpenAPIDocument(
     paths,
     tags: Array.from(tags).map((name) => ({ name })),
   };
+
+  // Post-processing: hoist shared schemas into components.schemas.
+  // `hoistSchemas: false` → pure backwards-compatible inline output.
+  const hoistEnabled = options.hoistSchemas !== false;
+  if (hoistEnabled) {
+    await hoistSharedSchemas(doc, {
+      threshold: options.hoistThreshold ?? 2,
+    });
+  }
+
+  return doc;
+}
+
+// ============================================
+// Schema hoisting (post-processing)
+// ============================================
+
+export interface HoistOptions {
+  /** Minimum occurrences required to hoist. Default `2`. */
+  threshold?: number;
+}
+
+interface SchemaOccurrence {
+  /** Structural hash of the schema body (identity key). */
+  hash: string;
+  /** Every parent reference we might need to rewrite to `$ref`. */
+  sites: Array<{ parent: Record<string, unknown>; key: string | number }>;
+  /** The canonical schema body (first-seen value; all sites share equal shape). */
+  body: OpenAPISchema;
+  /** Ordered list of name hints collected at each occurrence site. */
+  hints: string[];
+}
+
+/**
+ * Hoist shared object schemas into `components.schemas` and replace
+ * inline occurrences with `$ref` pointers.
+ *
+ * Only hoists:
+ *   - `type: "object"` schemas (primitives / enums / unions-of-primitives stay inline).
+ *   - Schemas appearing at a "hoistable site" (requestBody/response root or a top-level
+ *     property of either). Path/query/header parameter schemas are explicitly skipped.
+ *   - Schemas reaching the occurrence threshold (default 2).
+ *
+ * Naming:
+ *   - First hint wins for structurally-identical schemas.
+ *   - Name collisions across structurally-different schemas are disambiguated with
+ *     `_v2`, `_v3`, … suffixes (deterministic by walk order).
+ *   - Hint-less schemas fall back to `Schema_<first-8-hex-of-hash>`.
+ */
+export async function hoistSharedSchemas(
+  doc: OpenAPIDocument,
+  options: HoistOptions = {}
+): Promise<void> {
+  const threshold = Math.max(2, options.threshold ?? 2);
+  const occurrences = new Map<string, SchemaOccurrence>();
+
+  // --- Pass 1: walk every hoistable site and record occurrences. ---
+  for (const pathItem of Object.values(doc.paths)) {
+    for (const method of ["get", "post", "put", "patch", "delete"] as const) {
+      const op = pathItem[method];
+      if (!op) continue;
+
+      // Request body root schema (+ top-level property values).
+      if (op.requestBody?.content) {
+        for (const mediaObj of Object.values(op.requestBody.content)) {
+          recordHoistableTree(mediaObj as Record<string, unknown>, "schema", occurrences);
+        }
+      }
+
+      // Response root schema (+ top-level property values).
+      for (const resp of Object.values(op.responses)) {
+        if (!resp.content) continue;
+        for (const mediaObj of Object.values(resp.content)) {
+          recordHoistableTree(mediaObj as Record<string, unknown>, "schema", occurrences);
+        }
+      }
+    }
+  }
+
+  // --- Pass 2: pick the winners (count ≥ threshold, type === "object"). ---
+  const winners: Array<{ name: string; hash: string; body: OpenAPISchema; sites: SchemaOccurrence["sites"] }> = [];
+  const nameIndex = new Map<string, string>(); // name → hash (for collision detection)
+
+  // Stable iteration: sort by hash so hoisted output is deterministic
+  // regardless of JS property enumeration order quirks.
+  const entries = Array.from(occurrences.entries()).sort(([a], [b]) => a.localeCompare(b));
+  for (const [hash, entry] of entries) {
+    if (entry.sites.length < threshold) continue;
+    if (!isHoistableObject(entry.body)) continue;
+
+    // Pick the first-seen hint; fall back to the hash-derived default.
+    const preferred = entry.hints[0] || `Schema_${hash.slice(0, 8)}`;
+    let finalName = preferred;
+    let suffix = 2;
+    // If the name is already claimed by a *different* hash, walk `_v2`, `_v3`…
+    while (nameIndex.has(finalName) && nameIndex.get(finalName) !== hash) {
+      finalName = `${preferred}_v${suffix++}`;
+    }
+    nameIndex.set(finalName, hash);
+    winners.push({ name: finalName, hash, body: entry.body, sites: entry.sites });
+  }
+
+  if (winners.length === 0) return;
+
+  // --- Pass 3: install winners into components.schemas + rewrite sites. ---
+  if (!doc.components) doc.components = {};
+  if (!doc.components.schemas) doc.components.schemas = {};
+  const schemas = doc.components.schemas;
+
+  for (const winner of winners) {
+    schemas[winner.name] = winner.body;
+    const ref: OpenAPISchema = { $ref: `#/components/schemas/${winner.name}` };
+    for (const site of winner.sites) {
+      // Replace inline schema with a `$ref` pointer. We write a *new*
+      // ref object per site (JSON.stringify would collapse shared refs
+      // anyway, but distinct identities make future passes safer).
+      (site.parent as Record<string | number, unknown>)[site.key] = { ...ref };
+    }
+  }
+}
+
+/**
+ * Walk a container object and record every hoistable schema site. A
+ * hoistable site is:
+ *
+ *   1. The root schema at `container[key]` (typically the `"schema"` key of a
+ *      requestBody/response media type object).
+ *   2. Every top-level property of that root, *if* the root is an object schema.
+ *
+ * Nested properties beyond depth 1 are intentionally ignored — hoisting
+ * deep nests produces spec trees that are harder for codegen tools to
+ * follow than the inline original.
+ */
+function recordHoistableTree(
+  container: Record<string, unknown>,
+  key: string,
+  occurrences: Map<string, SchemaOccurrence>
+): void {
+  const root = container[key] as OpenAPISchema | undefined;
+  if (!root || typeof root !== "object") return;
+  // Skip anything that's already a $ref (e.g., from an earlier pass).
+  if ("$ref" in root && root.$ref) return;
+
+  // Record the root itself (regardless of object vs primitive — we filter
+  // in pass 2 so that primitives with many occurrences still get counted
+  // but are never emitted as component entries).
+  recordOccurrence(root, container as Record<string, unknown>, key, occurrences);
+
+  // Drill into top-level properties for object roots.
+  if (root.type === "object" && root.properties) {
+    for (const [propKey, propSchema] of Object.entries(root.properties)) {
+      if (!propSchema || typeof propSchema !== "object") continue;
+      if ("$ref" in propSchema && propSchema.$ref) continue;
+      recordOccurrence(
+        propSchema as OpenAPISchema,
+        root.properties as Record<string, unknown>,
+        propKey,
+        occurrences
+      );
+    }
+  }
+
+  // Drill into array items when the root is an array — the element shape
+  // is the real reusable schema, not the array wrapper itself.
+  if (root.type === "array" && root.items) {
+    const items = root.items;
+    if (items && typeof items === "object" && !("$ref" in items && items.$ref)) {
+      recordOccurrence(
+        items,
+        root as unknown as Record<string, unknown>,
+        "items",
+        occurrences
+      );
+    }
+  }
+}
+
+function recordOccurrence(
+  schema: OpenAPISchema,
+  parent: Record<string, unknown>,
+  key: string | number,
+  occurrences: Map<string, SchemaOccurrence>
+): void {
+  const hash = structuralHash(schema);
+  let entry = occurrences.get(hash);
+  if (!entry) {
+    entry = { hash, sites: [], body: schema, hints: [] };
+    occurrences.set(hash, entry);
+  }
+  entry.sites.push({ parent, key });
+  const hint = schemaNameHints.get(schema);
+  if (hint && !entry.hints.includes(hint)) {
+    entry.hints.push(hint);
+  }
+}
+
+/**
+ * A schema is hoistable iff it is an object with ≥1 property. We
+ * deliberately skip:
+ *   - primitives (`string`, `number`, `boolean`, `integer`) — they are
+ *     small enough that inline is clearer than a pointer chase.
+ *   - enums and unions of primitives — same argument, and codegen tools
+ *     tend to de-duplicate these separately.
+ *   - empty object schemas — no information to share.
+ *   - $ref passthroughs — already hoisted.
+ *   - object schemas with a composed keyword (allOf/oneOf/anyOf) but no
+ *     `properties` — these are structural compositions, not data shapes.
+ */
+function isHoistableObject(schema: OpenAPISchema): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  if (schema.$ref) return false;
+  if (schema.type !== "object") return false;
+  if (!schema.properties) return false;
+  if (Object.keys(schema.properties).length === 0) return false;
+  return true;
+}
+
+/**
+ * Stable structural hash of a schema. Sorts object keys recursively
+ * before stringifying so `{a:1,b:2}` and `{b:2,a:1}` hash identically,
+ * then feeds the canonical string through SHA-256.
+ */
+function structuralHash(schema: OpenAPISchema): string {
+  const canonical = stableStringify(schema);
+  return sha256Hex(canonical);
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "boolean" || typeof value === "number") return JSON.stringify(value);
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    const parts: string[] = [];
+    for (const k of keys) {
+      const v = (value as Record<string, unknown>)[k];
+      if (v === undefined) continue;
+      parts.push(JSON.stringify(k) + ":" + stableStringify(v));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Synchronous SHA-256 hex digest. Uses `Bun.CryptoHasher` when present,
+ * then Node `crypto.createHash` as a fallback. WebCrypto is async-only
+ * so we intentionally skip it here — the hoist pass hashes many small
+ * payloads and the sync path keeps the post-process simple and fast.
+ *
+ * This is a purely structural identity key (not a security primitive),
+ * so the brief Node-fallback surface is acceptable.
+ */
+function sha256Hex(input: string): string {
+  const bunGlobal = (globalThis as { Bun?: { CryptoHasher?: new (algo: string) => { update(input: string | Uint8Array): void; digest(encoding: "hex"): string } } }).Bun;
+  if (bunGlobal?.CryptoHasher) {
+    const hasher = new bunGlobal.CryptoHasher("sha256");
+    hasher.update(input);
+    return hasher.digest("hex");
+  }
+  // Node fallback — `require` at call time to keep module-load lean.
+  // Callers who run in an edge runtime without Node crypto should have
+  // Bun available; we therefore don't bother with a WebCrypto async
+  // path (it would turn `hoistSharedSchemas` into an unnecessarily async
+  // cascade on the hot path).
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const nodeCrypto = require("node:crypto") as typeof import("node:crypto");
+  return nodeCrypto.createHash("sha256").update(input).digest("hex");
 }
 
 // ============================================

package/src/openapi/openapi.test.ts

@@ -7,12 +7,14 @@ import { z } from "zod";
 import {
   generateOpenAPIDocument,
   hashOpenAPIJSON,
+  hoistSharedSchemas,
   openAPIToJSON,
   openAPIToYAML,
   readOpenAPIArtifacts,
   writeOpenAPIArtifacts,
   zodToOpenAPISchema,
 } from "./generator";
+import type { OpenAPIDocument } from "./generator";
 import type { RoutesManifest } from "../spec/schema";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -147,12 +149,14 @@ describe("zodToOpenAPISchema", () => {
   });
 
   describe("modifiers", () => {
-    test("should convert ZodOptional", () => {
+    test("should convert ZodOptional — unwraps without adding nullable (optional != nullable)", () => {
       const schema = z.string().optional();
       const result = zodToOpenAPISchema(schema);
 
       expect(result.type).toBe("string");
-      expect(result.nullable).toBe(true);
+      // Optionality is expressed by the parent object's required[] / parameter.required,
+      // NOT by marking the field nullable. See generator.ts comment.
+      expect(result.nullable).toBeUndefined();
     });
 
     test("should convert ZodNullable", () => {
@@ -163,6 +167,26 @@ describe("zodToOpenAPISchema", () => {
       expect(result.nullable).toBe(true);
     });
 
+    test("should convert ZodOptional(ZodNullable) — inner nullable preserved", () => {
+      const schema = z.string().nullable().optional();
+      const result = zodToOpenAPISchema(schema);
+
+      expect(result.type).toBe("string");
+      expect(result.nullable).toBe(true);
+    });
+
+    test("object with optional field — field omitted from required[] but schema itself is not nullable", () => {
+      const schema = z.object({
+        name: z.string(),
+        age: z.number().optional(),
+      });
+      const result = zodToOpenAPISchema(schema);
+
+      expect(result.type).toBe("object");
+      expect(result.required).toEqual(["name"]);
+      expect(result.properties?.age).toEqual({ type: "number" });
+    });
+
     test("should convert ZodDefault", () => {
       const schema = z.number().default(10);
       const result = zodToOpenAPISchema(schema);
@@ -490,3 +514,433 @@ describe("writeOpenAPIArtifacts + readOpenAPIArtifacts", () => {
     }
   });
 });
+
+// ============================================
+// Schema hoisting (shared schemas → components.schemas)
+// ============================================
+
+/**
+ * Build a two-contract fixture where both contracts share the same
+ * `User` body shape. The generator should hoist `{ name, email }` into
+ * `components.schemas` when hoisting is enabled.
+ */
+async function buildSharedSchemaFixture(opts: {
+  /** Override the `name` attribute on each contract (in file order). */
+  contractNames?: [string, string];
+  /** Replace the second contract's body shape to exercise collision paths. */
+  secondBody?: string;
+} = {}): Promise<{
+  rootDir: string;
+  manifest: RoutesManifest;
+  cleanup: () => Promise<void>;
+}> {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-hoist-"));
+  const [nameA, nameB] = opts.contractNames ?? ["users", "admins"];
+  const bodyB =
+    opts.secondBody ??
+    `z.object({ name: z.string().min(2), email: z.string().email() })`;
+
+  await fs.mkdir(path.join(rootDir, "contracts"), { recursive: true });
+  await fs.writeFile(
+    path.join(rootDir, "contracts/users.contract.ts"),
+    `import { z } from "zod";
+export default {
+  name: "${nameA}",
+  request: {
+    POST: {
+      body: z.object({ name: z.string().min(2), email: z.string().email() }),
+    },
+  },
+  response: {
+    200: z.object({ id: z.string().uuid(), status: z.string() }),
+  },
+};
+`,
+    "utf-8"
+  );
+  await fs.writeFile(
+    path.join(rootDir, "contracts/admins.contract.ts"),
+    `import { z } from "zod";
+export default {
+  name: "${nameB}",
+  request: {
+    POST: {
+      body: ${bodyB},
+    },
+  },
+  response: {
+    200: z.object({ id: z.string().uuid(), status: z.string() }),
+  },
+};
+`,
+    "utf-8"
+  );
+
+  const manifest: RoutesManifest = {
+    version: 1,
+    routes: [
+      {
+        id: "api/users",
+        pattern: "/api/users",
+        kind: "api",
+        module: "contracts/users.contract.ts",
+        contractModule: "contracts/users.contract.ts",
+        methods: ["POST"],
+      },
+      {
+        id: "api/admins",
+        pattern: "/api/admins",
+        kind: "api",
+        module: "contracts/admins.contract.ts",
+        contractModule: "contracts/admins.contract.ts",
+        methods: ["POST"],
+      },
+    ],
+  };
+
+  return {
+    rootDir,
+    manifest,
+    cleanup: async () => {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("hoistSharedSchemas", () => {
+  test("two routes sharing a body shape emit a single components.schemas entry with $ref", async () => {
+    const { rootDir, manifest, cleanup } = await buildSharedSchemaFixture();
+    try {
+      const doc = await generateOpenAPIDocument(manifest, rootDir, {
+        title: "Hoist Test",
+      });
+
+      // The shared POST body should be hoisted. There are also shared
+      // 200 responses so we expect at least 2 hoisted entries.
+      expect(doc.components?.schemas).toBeDefined();
+      const schemaNames = Object.keys(doc.components!.schemas!);
+      expect(schemaNames.length).toBeGreaterThanOrEqual(1);
+
+      const usersBody = doc.paths["/api/users"].post!.requestBody!.content["application/json"].schema;
+      const adminsBody = doc.paths["/api/admins"].post!.requestBody!.content["application/json"].schema;
+
+      // Both bodies must now be $ref pointers into components.schemas.
+      expect(usersBody.$ref).toBeDefined();
+      expect(adminsBody.$ref).toBeDefined();
+      // ... and they must point to the exact same entry (shared shape).
+      expect(usersBody.$ref).toBe(adminsBody.$ref);
+
+      // The pointed-to entry must exist and retain the object shape.
+      const refTarget = usersBody.$ref!.replace("#/components/schemas/", "");
+      const hoisted = doc.components!.schemas![refTarget];
+      expect(hoisted.type).toBe("object");
+      expect(hoisted.properties!.name).toBeDefined();
+      expect(hoisted.properties!.email).toBeDefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("one-off schema stays inline (no hoist, no components.schemas entry for it)", async () => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-oneoff-"));
+    try {
+      await fs.mkdir(path.join(rootDir, "contracts"), { recursive: true });
+      await fs.writeFile(
+        path.join(rootDir, "contracts/solo.contract.ts"),
+        `import { z } from "zod";
+export default {
+  name: "solo",
+  request: {
+    POST: { body: z.object({ uniqueField: z.string() }) },
+  },
+  response: { 200: z.object({ ok: z.boolean() }) },
+};
+`,
+        "utf-8"
+      );
+      const manifest: RoutesManifest = {
+        version: 1,
+        routes: [
+          {
+            id: "api/solo",
+            pattern: "/api/solo",
+            kind: "api",
+            module: "contracts/solo.contract.ts",
+            contractModule: "contracts/solo.contract.ts",
+            methods: ["POST"],
+          },
+        ],
+      };
+
+      const doc = await generateOpenAPIDocument(manifest, rootDir);
+      const body = doc.paths["/api/solo"].post!.requestBody!.content["application/json"].schema;
+
+      // Solo schemas must NOT be hoisted — stays inline.
+      expect(body.$ref).toBeUndefined();
+      expect(body.type).toBe("object");
+      expect(body.properties?.uniqueField).toBeDefined();
+
+      // components.schemas may exist (e.g. for the default 500 shape if it
+      // happened to collide with another schema), but the one-off body's
+      // uniqueField shape must not appear as a hoisted entry.
+      const schemas = doc.components?.schemas ?? {};
+      for (const entry of Object.values(schemas)) {
+        expect(entry.properties?.uniqueField).toBeUndefined();
+      }
+    } finally {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  test("same shape with different user-given names collapses to one entry (first-come wins)", async () => {
+    const { rootDir, manifest, cleanup } = await buildSharedSchemaFixture({
+      contractNames: ["users", "admins"],
+    });
+    try {
+      const doc = await generateOpenAPIDocument(manifest, rootDir);
+
+      const usersBody = doc.paths["/api/users"].post!.requestBody!.content["application/json"].schema;
+      const adminsBody = doc.paths["/api/admins"].post!.requestBody!.content["application/json"].schema;
+
+      // Both must resolve to the *same* $ref — structural identity wins
+      // over the user-given name split.
+      expect(usersBody.$ref).toBeDefined();
+      expect(usersBody.$ref).toBe(adminsBody.$ref);
+
+      // Exactly one body component (not two) for this shape. Count entries
+      // that match `{name,email}` shape.
+      const sharedEntries = Object.values(doc.components!.schemas!).filter(
+        (s) => s.properties?.name && s.properties?.email
+      );
+      expect(sharedEntries.length).toBe(1);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("name collision across structurally-different schemas → _v2 suffix", () => {
+    // Hand-craft a doc with two different body shapes whose name hints
+    // would collide. We exercise the hoist pass directly so we can
+    // control the hints without routing through Zod.
+    const shapeA = {
+      type: "object" as const,
+      properties: { a: { type: "string" as const } },
+      required: ["a"],
+    };
+    const shapeB = {
+      type: "object" as const,
+      properties: { b: { type: "number" as const } },
+      required: ["b"],
+    };
+
+    // Two routes use shape A, two use shape B — every schema gets the
+    // same name hint "Shared". The second winning hash should be renamed
+    // to "Shared_v2".
+    const a1 = { ...shapeA };
+    const a2 = { ...shapeA };
+    const b1 = { ...shapeB };
+    const b2 = { ...shapeB };
+
+    const doc: OpenAPIDocument = {
+      openapi: "3.0.3",
+      info: { title: "t", version: "1.0.0" },
+      paths: {
+        "/a1": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: a1 } } },
+          },
+        },
+        "/a2": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: a2 } } },
+          },
+        },
+        "/b1": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: b1 } } },
+          },
+        },
+        "/b2": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: b2 } } },
+          },
+        },
+      },
+    };
+
+    // Attach the same hint to both shapes via hoistSharedSchemas's own
+    // name-hint mechanism: we can't from here (WeakMap is module-private).
+    // So we instead rely on the deterministic hash-based fallback name,
+    // then assert both shapes are hoisted and receive distinct entries.
+    return hoistSharedSchemas(doc).then(() => {
+      const schemas = doc.components?.schemas ?? {};
+      const names = Object.keys(schemas);
+      // Both shapes qualify (appear twice each) → 2 hoisted entries.
+      expect(names.length).toBe(2);
+      // No two entries share the exact same name.
+      expect(new Set(names).size).toBe(names.length);
+      // The generated names must be stable strings (start with `Schema_`
+      // in the fallback path).
+      for (const n of names) {
+        expect(n).toMatch(/^Schema_[0-9a-f]{8}$/);
+      }
+    });
+  });
+
+  test("hoistSchemas: false produces the legacy inline-only document", async () => {
+    const { rootDir, manifest, cleanup } = await buildSharedSchemaFixture();
+    try {
+      const docOn = await generateOpenAPIDocument(manifest, rootDir, {
+        hoistSchemas: true,
+      });
+      const docOff = await generateOpenAPIDocument(manifest, rootDir, {
+        hoistSchemas: false,
+      });
+
+      // Off: no $refs anywhere, no components.schemas emitted.
+      const offJson = JSON.stringify(docOff);
+      expect(offJson.includes("$ref")).toBe(false);
+      expect(docOff.components?.schemas).toBeUndefined();
+
+      // On: at least one $ref appeared. Confirms the two paths diverge.
+      const onJson = JSON.stringify(docOn);
+      expect(onJson.includes("$ref")).toBe(true);
+      expect(docOn.components?.schemas).toBeDefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("enum / primitive schemas are never hoisted", async () => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-enum-"));
+    try {
+      await fs.mkdir(path.join(rootDir, "contracts"), { recursive: true });
+      const contractBody = `import { z } from "zod";
+export default {
+  name: NAME,
+  request: {
+    POST: { body: z.object({ role: z.enum(["a", "b", "c"]) }) },
+  },
+  response: { 200: z.object({ role: z.enum(["a", "b", "c"]) }) },
+};
+`;
+      await fs.writeFile(
+        path.join(rootDir, "contracts/one.contract.ts"),
+        contractBody.replace("NAME", '"one"'),
+        "utf-8"
+      );
+      await fs.writeFile(
+        path.join(rootDir, "contracts/two.contract.ts"),
+        contractBody.replace("NAME", '"two"'),
+        "utf-8"
+      );
+      const manifest: RoutesManifest = {
+        version: 1,
+        routes: [
+          {
+            id: "api/one",
+            pattern: "/api/one",
+            kind: "api",
+            module: "contracts/one.contract.ts",
+            contractModule: "contracts/one.contract.ts",
+            methods: ["POST"],
+          },
+          {
+            id: "api/two",
+            pattern: "/api/two",
+            kind: "api",
+            module: "contracts/two.contract.ts",
+            contractModule: "contracts/two.contract.ts",
+            methods: ["POST"],
+          },
+        ],
+      };
+
+      const doc = await generateOpenAPIDocument(manifest, rootDir);
+
+      // The outer {role: enum} object *is* hoistable and shared — that's fine.
+      // The inner enum itself must NOT be hoisted — scan every component
+      // entry and assert none of them is a bare enum-typed schema.
+      for (const entry of Object.values(doc.components?.schemas ?? {})) {
+        expect(entry.enum).toBeUndefined();
+        if (entry.type === "string" && !entry.properties) {
+          throw new Error(`Primitive string schema should not be hoisted: ${JSON.stringify(entry)}`);
+        }
+      }
+    } finally {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  test("hoistThreshold: 3 → 2-use schemas stay inline; 3-use schemas get hoisted", () => {
+    // Doc with the same shape appearing exactly twice.
+    const shape = {
+      type: "object" as const,
+      properties: { x: { type: "string" as const } },
+      required: ["x"],
+    };
+    const buildDoc = (): OpenAPIDocument => ({
+      openapi: "3.0.3",
+      info: { title: "t", version: "1.0.0" },
+      paths: {
+        "/a": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: { ...shape } } } },
+          },
+        },
+        "/b": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: { ...shape } } } },
+          },
+        },
+      },
+    });
+
+    const doc2 = buildDoc();
+    return hoistSharedSchemas(doc2, { threshold: 3 }).then(() => {
+      // With threshold=3 and only 2 uses → nothing hoisted.
+      expect(doc2.components?.schemas).toBeUndefined();
+      expect(doc2.paths["/a"].post!.requestBody!.content["application/json"].schema.$ref).toBeUndefined();
+
+      // Re-run with threshold=2 on a fresh doc → the same shape is hoisted.
+      const doc1 = buildDoc();
+      return hoistSharedSchemas(doc1, { threshold: 2 }).then(() => {
+        expect(doc1.components?.schemas).toBeDefined();
+        expect(Object.keys(doc1.components!.schemas!).length).toBe(1);
+      });
+    });
+  });
+
+  test("threshold values < 2 clamp up to 2 (never hoist single-use schemas)", () => {
+    // Edge: a malicious / misconfigured `hoistThreshold: 1` would otherwise
+    // hoist every schema including one-offs, blowing up the spec.
+    const shape = {
+      type: "object" as const,
+      properties: { solo: { type: "string" as const } },
+      required: ["solo"],
+    };
+    const doc: OpenAPIDocument = {
+      openapi: "3.0.3",
+      info: { title: "t", version: "1.0.0" },
+      paths: {
+        "/only": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: { ...shape } } } },
+          },
+        },
+      },
+    };
+
+    return hoistSharedSchemas(doc, { threshold: 1 }).then(() => {
+      expect(doc.components?.schemas).toBeUndefined();
+      expect(doc.paths["/only"].post!.requestBody!.content["application/json"].schema.$ref).toBeUndefined();
+    });
+  });
+});