@schmock/openapi 1.2.1 → 1.4.0

package/src/content-negotiation.ts

@@ -0,0 +1,53 @@
+/**
+ * Negotiate the best content type match for an Accept header.
+ * Supports quality values (q=0.8) and wildcards (*\/*).
+ * Returns the matched content type or null if no match.
+ */
+export function negotiateContentType(
+  accept: string,
+  available: string[],
+): string | null {
+  if (!accept || accept === "*/*") {
+    return available[0] ?? null;
+  }
+
+  // Parse Accept header into sorted entries by quality
+  const entries = accept
+    .split(",")
+    .map((part) => {
+      const [type, ...params] = part.trim().split(";");
+      let q = 1;
+      for (const param of params) {
+        const match = param.trim().match(/^q\s*=\s*([\d.]+)$/);
+        if (match) {
+          q = Number.parseFloat(match[1]);
+        }
+      }
+      return { type: type.trim(), q };
+    })
+    .sort((a, b) => b.q - a.q);
+
+  for (const entry of entries) {
+    if (entry.q === 0) continue;
+
+    // Wildcard matches anything
+    if (entry.type === "*/*") {
+      return available[0] ?? null;
+    }
+
+    // Type wildcard (e.g., "application/*")
+    if (entry.type.endsWith("/*")) {
+      const prefix = entry.type.slice(0, -1);
+      const match = available.find((ct) => ct.startsWith(prefix));
+      if (match) return match;
+      continue;
+    }
+
+    // Exact match
+    if (available.includes(entry.type)) {
+      return entry.type;
+    }
+  }
+
+  return null;
+}

package/src/crud-detector.ts

@@ -1,6 +1,7 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../../core/schmock.d.ts" />
 
 import type { JSONSchema7 } from "json-schema";
+import { findArrayProperty } from "./generators.js";
 import type { ParsedPath } from "./parser.js";
 import { isRecord, toJsonSchema } from "./utils.js";
 
@@ -19,6 +20,8 @@ export interface CrudResource {
   operations: CrudOperation[];
   /** Response schema for the resource item */
   schema?: JSONSchema7;
+  /** Per-operation metadata auto-detected from spec */
+  operationMeta?: Map<CrudOperation, Schmock.CrudOperationMeta>;
 }
 
 interface DetectionResult {
@@ -97,6 +100,7 @@ function buildResource(
   let itemPath = "";
   let idParam = "";
   let schema: JSONSchema7 | undefined;
+  const operationMeta = new Map<CrudOperation, Schmock.CrudOperationMeta>();
 
   for (const p of paths) {
     const isCollection = p.path === basePath;
@@ -105,18 +109,30 @@ function buildResource(
     if (isCollection) {
       if (p.method === "GET") {
         operations.push("list");
-        // Try to extract item schema from list response (array items)
         const listSchema = getSuccessResponseSchema(p);
-        if (listSchema && listSchema.type === "array" && listSchema.items) {
-          const items = Array.isArray(listSchema.items)
-            ? listSchema.items[0]
-            : listSchema.items;
-          if (isRecord(items)) {
-            schema = schema ?? toJsonSchema(items);
+        if (listSchema) {
+          // Extract item schema from both flat arrays and wrapped lists
+          const arrayInfo = findArrayProperty(listSchema);
+          if (arrayInfo.itemSchema) {
+            schema = schema ?? arrayInfo.itemSchema;
+          } else if (listSchema.type === "array" && listSchema.items) {
+            // Fallback: direct flat array
+            const items = Array.isArray(listSchema.items)
+              ? listSchema.items[0]
+              : listSchema.items;
+            if (isRecord(items)) {
+              schema = schema ?? toJsonSchema(items);
+            }
           }
         }
+
+        // Capture list operation metadata
+        const meta = buildOperationMeta(p, "list");
+        operationMeta.set("list", meta);
       } else if (p.method === "POST") {
         operations.push("create");
+        const meta = buildOperationMeta(p, "create");
+        operationMeta.set("create", meta);
       }
     } else if (isItem) {
       // Extract ID param from the item path
@@ -134,12 +150,18 @@ function buildResource(
         if (p.method === "GET") {
           operations.push("read");
           schema = schema ?? getSuccessResponseSchema(p);
+          const meta = buildOperationMeta(p, "read");
+          operationMeta.set("read", meta);
         } else if (p.method === "PUT" || p.method === "PATCH") {
           if (!operations.includes("update")) {
             operations.push("update");
+            const meta = buildOperationMeta(p, "update");
+            operationMeta.set("update", meta);
           }
         } else if (p.method === "DELETE") {
           operations.push("delete");
+          const meta = buildOperationMeta(p, "delete");
+          operationMeta.set("delete", meta);
         }
       }
     }
@@ -177,9 +199,44 @@ function buildResource(
     idParam,
     operations,
     schema,
+    operationMeta: operationMeta.size > 0 ? operationMeta : undefined,
   };
 }
 
+function buildOperationMeta(
+  p: ParsedPath,
+  _operation: CrudOperation,
+): Schmock.CrudOperationMeta {
+  const meta: Schmock.CrudOperationMeta = {};
+
+  // Capture full success response schema
+  const responseSchema = getSuccessResponseSchema(p);
+  if (responseSchema) {
+    meta.responseSchema = responseSchema;
+  }
+
+  // Capture success response headers
+  for (const [code, resp] of p.responses) {
+    if (code >= 200 && code < 300 && resp.headers) {
+      meta.responseHeaders = resp.headers;
+      break;
+    }
+  }
+
+  // Capture error response schemas (4xx)
+  const errorSchemas = new Map<number, JSONSchema7>();
+  for (const [code, resp] of p.responses) {
+    if (code >= 400 && code < 600 && resp.schema) {
+      errorSchemas.set(code, resp.schema);
+    }
+  }
+  if (errorSchemas.size > 0) {
+    meta.errorSchemas = errorSchemas;
+  }
+
+  return meta;
+}
+
 function getSuccessResponseSchema(p: ParsedPath): JSONSchema7 | undefined {
   // Try 200, then 201, then first 2xx
   for (const code of [200, 201]) {

package/src/generators.test.ts

@@ -6,6 +6,8 @@ import {
   createListGenerator,
   createReadGenerator,
   createUpdateGenerator,
+  findArrayProperty,
+  generateHeaderValues,
   generateSeedItems,
 } from "./generators";
 
@@ -211,4 +213,272 @@ describe("generators", () => {
       }
     });
   });
+
+  describe("findArrayProperty", () => {
+    it("returns empty for flat type:array schema", () => {
+      const result = findArrayProperty({
+        type: "array",
+        items: { type: "object", properties: { id: { type: "integer" } } },
+      });
+      expect(result.property).toBeUndefined();
+      expect(result.itemSchema).toBeDefined();
+    });
+
+    it("finds array in Stripe-style inline object", () => {
+      const result = findArrayProperty({
+        type: "object",
+        properties: {
+          data: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { email: { type: "string" } },
+            },
+          },
+          has_more: { type: "boolean" },
+          object: { type: "string", enum: ["list"] },
+          url: { type: "string" },
+        },
+        required: ["data", "has_more", "object", "url"],
+      });
+      expect(result.property).toBe("data");
+      expect(result.itemSchema).toBeDefined();
+    });
+
+    it("finds array in allOf composition (Scalar Galaxy style)", () => {
+      const result = findArrayProperty({
+        allOf: [
+          {
+            type: "object",
+            properties: {
+              data: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: { name: { type: "string" } },
+                },
+              },
+            },
+          },
+          {
+            type: "object",
+            properties: {
+              meta: {
+                type: "object",
+                properties: { total: { type: "integer" } },
+              },
+            },
+          },
+        ],
+      });
+      expect(result.property).toBe("data");
+      expect(result.itemSchema).toBeDefined();
+    });
+
+    it("tries first branch of anyOf", () => {
+      const result = findArrayProperty({
+        anyOf: [
+          {
+            type: "array",
+            items: { type: "object" },
+          },
+          { type: "null" },
+        ],
+      });
+      expect(result.property).toBeUndefined();
+      expect(result.itemSchema).toBeDefined();
+    });
+
+    it("returns empty for schema with no array property", () => {
+      const result = findArrayProperty({
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          count: { type: "integer" },
+        },
+      });
+      expect(result.property).toBeUndefined();
+      expect(result.itemSchema).toBeUndefined();
+    });
+
+    it("returns empty for empty schema", () => {
+      const result = findArrayProperty({});
+      expect(result.property).toBeUndefined();
+      expect(result.itemSchema).toBeUndefined();
+    });
+  });
+
+  describe("generateHeaderValues", () => {
+    it("returns empty object for undefined defs", () => {
+      expect(generateHeaderValues(undefined)).toEqual({});
+    });
+
+    it("returns empty object for empty defs", () => {
+      expect(generateHeaderValues({})).toEqual({});
+    });
+
+    it("generates UUID for format:uuid", () => {
+      const headers = generateHeaderValues({
+        "X-Request-ID": {
+          schema: { type: "string", format: "uuid" },
+          description: "Request ID",
+        },
+      });
+      expect(headers["X-Request-ID"]).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+      );
+    });
+
+    it("generates ISO date for format:date-time", () => {
+      const headers = generateHeaderValues({
+        "X-Timestamp": {
+          schema: { type: "string", format: "date-time" },
+          description: "Timestamp",
+        },
+      });
+      expect(new Date(headers["X-Timestamp"]).toISOString()).toBe(
+        headers["X-Timestamp"],
+      );
+    });
+
+    it("uses first enum value", () => {
+      const headers = generateHeaderValues({
+        "X-Cache": {
+          schema: { type: "string", enum: ["HIT", "MISS"] },
+          description: "Cache status",
+        },
+      });
+      expect(headers["X-Cache"]).toBe("HIT");
+    });
+
+    it("uses default value from example normalization", () => {
+      const headers = generateHeaderValues({
+        "X-Total": {
+          schema: { type: "integer", default: 1000 },
+          description: "Total items",
+        },
+      });
+      expect(headers["X-Total"]).toBe("1000");
+    });
+
+    it("generates 0 for integer type", () => {
+      const headers = generateHeaderValues({
+        "X-Count": {
+          schema: { type: "integer" },
+          description: "Count",
+        },
+      });
+      expect(headers["X-Count"]).toBe("0");
+    });
+
+    it("generates empty string for string type", () => {
+      const headers = generateHeaderValues({
+        "X-Token": {
+          schema: { type: "string" },
+          description: "Token",
+        },
+      });
+      expect(headers["X-Token"]).toBe("");
+    });
+
+    it("skips headers with no schema", () => {
+      const headers = generateHeaderValues({
+        "X-NoSchema": {
+          description: "No schema defined",
+        },
+      });
+      expect(headers["X-NoSchema"]).toBeUndefined();
+    });
+  });
+
+  describe("list generator with meta (wrapped response)", () => {
+    it("wraps list in schema-defined object when wrapper detected", () => {
+      const resource = makeResource();
+      const state: Record<string, unknown> = {
+        "openapi:collections:pets": [
+          { petId: 1, name: "Buddy" },
+          { petId: 2, name: "Max" },
+        ],
+      };
+
+      const meta: Schmock.CrudOperationMeta = {
+        responseSchema: {
+          type: "object",
+          properties: {
+            data: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: { petId: { type: "integer" } },
+              },
+            },
+            total: { type: "integer", default: 0 },
+          },
+        },
+      };
+
+      const list = createListGenerator(resource, meta);
+      const result = list(makeContext({ state }));
+      const body = result as Record<string, unknown>;
+      expect(body.data).toHaveLength(2);
+      expect(body.total).toBeDefined();
+    });
+
+    it("returns flat array when no meta provided", () => {
+      const resource = makeResource();
+      const state: Record<string, unknown> = {
+        "openapi:collections:pets": [{ petId: 1, name: "Buddy" }],
+      };
+
+      const list = createListGenerator(resource);
+      const result = list(makeContext({ state }));
+      expect(Array.isArray(result)).toBe(true);
+    });
+  });
+
+  describe("error generator with meta (spec-defined errors)", () => {
+    it("uses error schema from meta when available", () => {
+      const resource = makeResource();
+      const state: Record<string, unknown> = {
+        "openapi:collections:pets": [],
+      };
+
+      const errorSchemas = new Map<number, Schmock.JSONSchema7>();
+      errorSchemas.set(404, {
+        type: "object",
+        properties: {
+          title: { type: "string", default: "Not Found" },
+          status: { type: "integer", default: 404 },
+        },
+        required: ["title", "status"],
+      });
+
+      const meta: Schmock.CrudOperationMeta = { errorSchemas };
+      const read = createReadGenerator(resource, meta);
+      const result = read(
+        makeContext({ path: "/pets/999", params: { petId: "999" }, state }),
+      );
+
+      expect(Array.isArray(result)).toBe(true);
+      const tuple = result as [number, unknown];
+      expect(tuple[0]).toBe(404);
+      const body = tuple[1] as Record<string, unknown>;
+      expect(body.title).toBeDefined();
+      expect(body.status).toBeDefined();
+    });
+
+    it("falls back to default error when no meta", () => {
+      const resource = makeResource();
+      const state: Record<string, unknown> = {
+        "openapi:collections:pets": [],
+      };
+
+      const read = createReadGenerator(resource);
+      const result = read(
+        makeContext({ path: "/pets/999", params: { petId: "999" }, state }),
+      );
+
+      expect(result).toEqual([404, { error: "Not found", code: "NOT_FOUND" }]);
+    });
+  });
 });