zudoku 0.0.0-fix-circular-ref-false-positives.zbe02c6a6 → 0.0.0-fix-warnings.z053d4e27

package/src/lib/oas/graphql/circular.test.ts

@@ -156,20 +156,16 @@ describe("handleCircularRefs", () => {
     });
   });
 
-  it("should handle shared object instances with __$ref without marking circular", () => {
+  it("should deduplicate shared object instances with __$ref", () => {
     const shared = { __$ref: "#/components/schemas/Foo", type: "string" };
     const obj = { a: shared, b: shared };
     const result = handleCircularRefs(obj);
 
-    // Both should return the cached result, not mark as circular
     expect(result.a).toEqual({
       __$ref: "#/components/schemas/Foo",
       type: "string",
     });
-    expect(result.b).toEqual({
-      __$ref: "#/components/schemas/Foo",
-      type: "string",
-    });
+    expect(result.b).toBe(`${SCHEMA_REF_PREFIX}#/components/schemas/Foo`);
   });
 
   it("should mark circular ref with property name from path", () => {
@@ -187,35 +183,4 @@ describe("handleCircularRefs", () => {
 
     expect(result.properties.child.properties.back).toContain(CIRCULAR_REF);
   });
-
-  // Exact reproduction of #1869 - shared object instances with __$ref
-  it("should NOT mark shared object instances with __$ref as circular (issue #1869)", () => {
-    // When dereferencing, the SAME object instance is returned for all refs to the same schema
-    const timestampSchema = {
-      __$ref: "#/components/schemas/timestamp",
-      type: "string",
-      format: "date-time",
-    };
-
-    // Both created_at and updated_at point to the SAME object instance
-    const obj = {
-      type: "object",
-      properties: {
-        created_at: timestampSchema,
-        updated_at: timestampSchema,
-      },
-    };
-
-    const result = handleCircularRefs(obj);
-
-    // The first one should be fully expanded
-    expect(result.properties.created_at).toEqual({
-      __$ref: "#/components/schemas/timestamp",
-      type: "string",
-      format: "date-time",
-    });
-    // The second one should ALSO be fully expanded (not marked as circular)
-    expect(typeof result.properties.updated_at).toBe("object");
-    expect(result.properties.updated_at).not.toContain(CIRCULAR_REF);
-  });
 });

package/src/lib/oas/graphql/circular.ts

@@ -1,5 +1,6 @@
 import { GraphQLScalarType } from "graphql/index.js";
 import { GraphQLJSON } from "graphql-type-json";
+import type { RecordAny } from "../../util/traverse.js";
 
 export const CIRCULAR_REF = "$[Circular Reference]";
 export const SCHEMA_REF_PREFIX = "$ref:";
@@ -16,48 +17,73 @@ const OPENAPI_PROPS = new Set([
 export const handleCircularRefs = (
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   obj: any,
-  currentPath = new WeakSet(),
+  visited = new WeakSet(),
   refs = new WeakMap(),
   path: string[] = [],
-  currentRefPaths = new Set<string>(),
+  seenRefPaths = new Set<string>(),
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
 ): any => {
   if (obj === null || typeof obj !== "object") return obj;
 
   const refPath = obj.__$ref;
-  const isCircular =
-    currentPath.has(obj) ||
-    (typeof refPath === "string" && currentRefPaths.has(refPath));
 
-  if (isCircular) {
-    if (typeof refPath === "string") return SCHEMA_REF_PREFIX + refPath;
+  // Check if this object has a __$ref marker (set during schema code generation)
+  // If we've already fully processed this ref path, return a reference marker
+  // instead of the full data to avoid JSON.stringify serializing duplicates
+  if (typeof refPath === "string" && seenRefPaths.has(refPath)) {
+    return SCHEMA_REF_PREFIX + refPath;
+  }
+
+  if (visited.has(obj)) {
+    const cached = refs.get(obj);
+    if (cached) {
+      return typeof refPath === "string"
+        ? // If already processed, return ref marker to avoid duplicate serialization
+          SCHEMA_REF_PREFIX + refPath
+        : cached;
+    }
     const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
+
     return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
 
-  if (refs.has(obj)) return refs.get(obj);
+  visited.add(obj);
 
-  currentPath.add(obj);
-  if (typeof refPath === "string") currentRefPaths.add(refPath);
+  // Add refPath BEFORE recursing to detect cycles within this branch
+  // This will be removed after processing to allow siblings with the same ref
+  if (typeof refPath === "string") {
+    seenRefPaths.add(refPath);
+  }
 
-  const recurse = (value: unknown, key: string) =>
-    handleCircularRefs(
-      value,
-      currentPath,
-      refs,
-      [...path, key],
-      currentRefPaths,
+  let result: RecordAny | RecordAny[];
+  if (Array.isArray(obj)) {
+    result = obj.map((item, index) =>
+      handleCircularRefs(
+        item,
+        visited,
+        refs,
+        [...path, index.toString()],
+        seenRefPaths,
+      ),
     );
-
-  const result = Array.isArray(obj)
-    ? obj.map((item, i) => recurse(item, i.toString()))
-    : Object.fromEntries(
-        Object.entries(obj).map(([k, v]) => [k, recurse(v, k)]),
+  } else {
+    result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = handleCircularRefs(
+        value,
+        visited,
+        refs,
+        [...path, key],
+        seenRefPaths,
       );
-
+    }
+  }
   refs.set(obj, result);
-  currentPath.delete(obj);
-  if (typeof refPath === "string") currentRefPaths.delete(refPath);
+
+  // Remove refPath after processing so sibling refs aren't incorrectly marked
+  if (typeof refPath === "string") {
+    seenRefPaths.delete(refPath);
+  }
 
   return result;
 };

package/src/lib/oas/parser/index.ts

@@ -1,6 +1,7 @@
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
-import { flattenAllOfProcessor } from "../../util/flattenAllOf.js";
+import { flattenAllOf } from "../../util/flattenAllOf.js";
+import { traverse } from "../../util/traverse.js";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
@@ -104,11 +105,21 @@ export const validate = async (schemaInput: unknown) => {
   const dereferenced = await dereference(schema);
   const upgraded = upgradeSchema(dereferenced);
 
-  const flattened = await flattenAllOfProcessor({
-    schema: upgraded,
-    file: "schema.json",
-    dereference: async (schema) => schema,
-  });
+  const flattened = traverse(upgraded, (spec) => {
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+      return spec;
+    }
+    const isSchemaObject =
+      "type" in spec ||
+      "properties" in spec ||
+      "allOf" in spec ||
+      "anyOf" in spec ||
+      "oneOf" in spec;
+
+    if (!isSchemaObject) return spec;
+
+    return flattenAllOf(spec) as typeof spec;
+  }) as OpenAPIDocument;
 
   return flattened;
 };

package/src/lib/util/flattenAllOf.test.ts

@@ -1,7 +1,8 @@
 import type { JSONSchema7 } from "json-schema";
 import { describe, expect, it, vi } from "vitest";
 import type { OpenAPIDocument } from "../oas/parser/index.js";
-import { flattenAllOf, flattenAllOfProcessor } from "./flattenAllOf.js";
+import { flattenAllOf } from "./flattenAllOf.js";
+import { flattenAllOfProcessor } from "./flattenAllOfProcessor.js";
 import invariant from "./invariant.js";
 
 describe("flattenAllOf", () => {

package/src/lib/util/flattenAllOf.ts

@@ -1,4 +1,3 @@
-import { $RefParser } from "@apidevtools/json-schema-ref-parser";
 import {
   createComparator,
   createMerger,
@@ -9,62 +8,6 @@ import {
   createIntersector,
 } from "@x0k/json-schema-merge/lib/array";
 import type { JSONSchema7Definition } from "json-schema";
-import type { Processor } from "../../config/validators/BuildSchema.js";
-import type { OpenAPIDocument } from "../oas/parser/index.js";
-import { type RecordAny, traverse } from "./traverse.js";
-
-export const flattenAllOfProcessor: Processor = async ({ schema, file }) => {
-  try {
-    // Resolve refs once - creates a lookup table without modifying the schema
-    const parser = new $RefParser();
-    await parser.resolve(schema);
-    const $refs = parser.$refs;
-
-    const flattened = traverse(schema, (spec) => {
-      if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
-        return spec;
-      }
-
-      const isSchemaObject =
-        "type" in spec ||
-        "properties" in spec ||
-        "allOf" in spec ||
-        "anyOf" in spec ||
-        "oneOf" in spec;
-
-      if (!isSchemaObject) return spec;
-
-      if ("allOf" in spec && Array.isArray(spec.allOf)) {
-        const resolvedAllOf = spec.allOf.map((item) => {
-          if (
-            item &&
-            typeof item === "object" &&
-            "$ref" in item &&
-            typeof item.$ref === "string"
-          ) {
-            try {
-              return $refs.get(item.$ref) ?? item;
-            } catch {
-              return item;
-            }
-          }
-          return item;
-        });
-        return flattenAllOf({ ...spec, allOf: resolvedAllOf }) as RecordAny;
-      }
-
-      return flattenAllOf(spec) as RecordAny;
-    }) as OpenAPIDocument;
-
-    return flattened;
-  } catch (error) {
-    // biome-ignore lint/suspicious/noConsole: Logging allowed here
-    console.warn(
-      `Failed to flatten \`allOf\` in ${file}: ${error instanceof Error ? error.message : error}`,
-    );
-    return schema;
-  }
-};
 
 const { compareSchemaDefinitions, compareSchemaValues } = createComparator();
 const { mergeArrayOfSchemaDefinitions } = createMerger({

package/src/lib/util/flattenAllOfProcessor.ts

@@ -0,0 +1,58 @@
+import { $RefParser } from "@apidevtools/json-schema-ref-parser";
+import type { Processor } from "../../config/validators/BuildSchema.js";
+import type { OpenAPIDocument } from "../oas/parser/index.js";
+import { flattenAllOf } from "./flattenAllOf.js";
+import { type RecordAny, traverse } from "./traverse.js";
+
+export const flattenAllOfProcessor: Processor = async ({ schema, file }) => {
+  try {
+    // Resolve refs once - creates a lookup table without modifying the schema
+    const parser = new $RefParser();
+    await parser.resolve(schema);
+    const $refs = parser.$refs;
+
+    const flattened = traverse(schema, (spec) => {
+      if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+        return spec;
+      }
+
+      const isSchemaObject =
+        "type" in spec ||
+        "properties" in spec ||
+        "allOf" in spec ||
+        "anyOf" in spec ||
+        "oneOf" in spec;
+
+      if (!isSchemaObject) return spec;
+
+      if ("allOf" in spec && Array.isArray(spec.allOf)) {
+        const resolvedAllOf = spec.allOf.map((item) => {
+          if (
+            item &&
+            typeof item === "object" &&
+            "$ref" in item &&
+            typeof item.$ref === "string"
+          ) {
+            try {
+              return $refs.get(item.$ref) ?? item;
+            } catch {
+              return item;
+            }
+          }
+          return item;
+        });
+        return flattenAllOf({ ...spec, allOf: resolvedAllOf }) as RecordAny;
+      }
+
+      return flattenAllOf(spec) as RecordAny;
+    }) as OpenAPIDocument;
+
+    return flattened;
+  } catch (error) {
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.warn(
+      `Failed to flatten \`allOf\` in ${file}: ${error instanceof Error ? error.message : error}`,
+    );
+    return schema;
+  }
+};

package/src/lib/util/readFrontmatter.ts

@@ -9,5 +9,6 @@ export const yaml = {
 
 export const readFrontmatter = async (filePath: string) => {
   const content = await readFile(filePath, "utf-8");
-  return matter(content, { engines: { yaml } });
+  const normalizedContent = content.replace(/\r\n/g, "\n");
+  return matter(normalizedContent, { engines: { yaml } });
 };

package/src/zuplo/enrich-with-zuplo-mcp.ts

@@ -0,0 +1,168 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type {
+  ExtensionMcpServer,
+  ExtensionMcpServerTool,
+} from "@zuplo/mcp/openapi/types";
+import {
+  DEFAULT_MCP_SERVER_NAME,
+  DEFAULT_MCP_SERVER_VERSION,
+} from "@zuplo/mcp/server";
+import type { OpenAPIV3_1 } from "openapi-types";
+import type { ProcessorArg } from "../config/validators/BuildSchema.js";
+import { traverse, traverseAsync } from "../lib/util/traverse.js";
+import type { RecordAny } from "../lib/util/types.js";
+import { operations } from "./enrich-with-zuplo.js";
+
+// extracts x-mcp-server metadata from the operation using x-zuplo-mcp-tool
+// as a first class citizen.
+const extractOperationSchema = (
+  operation: OpenAPIV3_1.OperationObject & RecordAny,
+): ExtensionMcpServerTool | null => {
+  if (!operation.operationId) return null;
+
+  // Check if tool is explicitly disabled
+  const mcpToolConfig = operation["x-zuplo-mcp-tool"];
+  if (mcpToolConfig?.enabled === false) {
+    return null;
+  }
+
+  const tool: ExtensionMcpServerTool = {
+    // Use custom name from x-zuplo-mcp-tool or fallback to operationId
+    name: mcpToolConfig?.name || operation.operationId,
+
+    // Use custom description from x-zuplo-mcp-tool or fallback
+    // to operation description
+    description:
+      mcpToolConfig?.description ||
+      operation.summary ||
+      operation.description ||
+      `Operation ${operation.operationId}`,
+  };
+
+  // Grab valid request body JSON schema for the tool
+  const requestBody = operation.requestBody as
+    | OpenAPIV3_1.RequestBodyObject
+    | undefined;
+
+  const schema = requestBody?.content?.["application/json"]?.schema;
+  if (schema && typeof schema === "object") {
+    // TODO: @jpmcb - Zuplo also supports in-path parameters and query parameters
+    // as MCP "inputSchema" arguments. In order to document full argument params,
+    // Zudoku will need to more intelligently parse these elements of an operation.
+    tool.inputSchema = { body: schema };
+  }
+
+  return tool;
+};
+
+// Builds a lookup map of operationId -> operation for efficient access
+const buildOperationLookup = (
+  document: OpenAPIV3_1.Document,
+): Map<string, OpenAPIV3_1.OperationObject> => {
+  const operationMap = new Map<string, OpenAPIV3_1.OperationObject>();
+
+  traverse(document, (node, path) => {
+    // Check if we're at a path item level (paths -> /some/path -> method)
+    // and validate it's in allowed operations
+    if (
+      !path ||
+      path.length < 2 ||
+      path[0] !== "paths" ||
+      !operations.includes(path[path.length - 1] as string)
+    ) {
+      return node;
+    }
+
+    if (node.operationId) {
+      operationMap.set(node.operationId, node);
+    }
+
+    return node;
+  });
+
+  return operationMap;
+};
+
+// Takes an OpenAPI document and returns the x-mcp-server tools list defined
+// by an MCP server's options.files[x].operationIds array.
+const findOperationsInDocument = (
+  document: OpenAPIV3_1.Document,
+  operationIds: string[],
+): ExtensionMcpServerTool[] => {
+  const tools: ExtensionMcpServerTool[] = [];
+  const operationLookup = buildOperationLookup(document);
+
+  operationIds.forEach((operationId) => {
+    const operation = operationLookup.get(operationId);
+    if (operation) {
+      const tool = extractOperationSchema(operation);
+      if (tool) {
+        tools.push(tool);
+      }
+    }
+  });
+
+  return tools;
+};
+
+// Enriches an OpenAPI schema with x-mcp-server data based on the Zuplo MCP server handler
+export const enrichWithZuploMcpServerData = ({
+  rootDir,
+}: {
+  rootDir: string;
+}) => {
+  return async ({ schema }: ProcessorArg) => {
+    if (!schema.paths) return schema;
+    const modifiedSchema = { ...schema };
+    if (!modifiedSchema?.paths) return modifiedSchema;
+
+    await traverseAsync(modifiedSchema, async (node, nodePath) => {
+      // Check if we're at a "post" operation (paths -> /some/path -> "post").
+      // HTTP MCP servers are only allow post operations.
+      if (!nodePath || nodePath.length !== 3 || nodePath[2] !== "post") {
+        return node;
+      }
+
+      const operation = node as RecordAny;
+      if (!operation?.["x-zuplo-route"]) return node;
+
+      const handler = operation["x-zuplo-route"]?.handler;
+      if (handler?.export !== "mcpServerHandler" || !handler.options?.files)
+        return node;
+
+      const tools: ExtensionMcpServerTool[] = [];
+
+      for (const fileConfig of handler.options.files) {
+        if (!fileConfig.path || !fileConfig.operationIds) continue;
+
+        const resolvedPath = path.resolve(rootDir, "../", fileConfig.path);
+        const fileContent = await fs.readFile(resolvedPath, "utf-8");
+        const document = JSON.parse(fileContent);
+
+        if (document) {
+          const fileTools = findOperationsInDocument(
+            document,
+            fileConfig.operationIds,
+          );
+
+          tools.push(...fileTools);
+        }
+      }
+
+      const mcpExtension: ExtensionMcpServer = {
+        name: DEFAULT_MCP_SERVER_NAME,
+        version: DEFAULT_MCP_SERVER_VERSION,
+      };
+
+      if (tools.length > 0) {
+        mcpExtension.tools = tools;
+      }
+
+      node["x-mcp-server"] = mcpExtension;
+      return node;
+    });
+
+    return modifiedSchema;
+  };
+};