zudoku 0.0.0-feat-openapi-docs-redesign.dab3fc6a → 0.0.0-feat-navigation-at-property.z8cd07fa5

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", () => {
@@ -362,16 +363,12 @@ describe("flattenAllOf processor", () => {
       },
     };
 
-    const mockDereference = vi.fn().mockResolvedValue(schema);
-
     const result = await flattenAllOfProcessor({
       schema,
       file: "/test/schema.json",
-      dereference: mockDereference,
+      dereference: vi.fn(),
     });
 
-    expect(mockDereference).toHaveBeenCalledWith(schema);
-
     const responseSchema =
       result.paths?.["/users"]?.get?.responses?.[200]?.content?.[
         "application/json"
@@ -423,31 +420,20 @@ describe("flattenAllOf processor", () => {
     expect(userSchema).not.toHaveProperty("allOf");
   });
 
-  it("should handle errors gracefully and return original schema", async () => {
+  it("should handle schemas without allOf gracefully", async () => {
     const schema: OpenAPIDocument = {
       openapi: "3.0.0",
       info: { title: "Test API", version: "1.0.0" },
       paths: {},
     };
 
-    const mockDereference = vi
-      .fn()
-      .mockRejectedValue(new Error("Dereference failed"));
-
-    const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-
     const result = await flattenAllOfProcessor({
       schema,
       file: "/test/schema.json",
-      dereference: mockDereference,
+      dereference: vi.fn(),
     });
 
-    expect(result).toBe(schema);
-    expect(consoleSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Failed to flatten"),
-    );
-
-    consoleSpy.mockRestore();
+    expect(result).toStrictEqual(schema);
   });
 
   it("should only flatten schema objects, not other OpenAPI structures", async () => {
@@ -634,4 +620,71 @@ describe("flattenAllOf processor", () => {
     });
     expect(containerSchema?.oneOf?.[1]).not.toHaveProperty("allOf");
   });
+
+  it("should preserve $refs outside of allOf while flattening allOf with $refs", async () => {
+    // Schema with:
+    // 1. A reusable component (Base) that's referenced multiple times
+    // 2. An allOf that references Base (should be resolved for merging)
+    // 3. A property that references Base (should stay as $ref)
+    const schema = {
+      openapi: "3.0.0",
+      info: { title: "Test API", version: "1.0.0" },
+      paths: {},
+      components: {
+        schemas: {
+          Base: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              createdAt: { type: "string", format: "date-time" },
+            },
+          },
+          Extended: {
+            allOf: [
+              { $ref: "#/components/schemas/Base" },
+              {
+                type: "object",
+                properties: {
+                  name: { type: "string" },
+                },
+              },
+            ],
+          },
+          Container: {
+            type: "object",
+            properties: {
+              // This $ref should NOT be expanded
+              nested: { $ref: "#/components/schemas/Base" },
+            },
+          },
+        },
+      },
+    } as OpenAPIDocument;
+
+    const result = await flattenAllOfProcessor({
+      schema,
+      file: "/test/schema.json",
+      dereference: vi.fn(),
+    });
+
+    // Extended should have allOf flattened (merged with Base)
+    const extendedSchema = result.components?.schemas?.Extended;
+    expect(extendedSchema).not.toHaveProperty("allOf");
+    expect(extendedSchema).toMatchObject({
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        createdAt: { type: "string", format: "date-time" },
+        name: { type: "string" },
+      },
+    });
+
+    // Container.nested should still be a $ref (NOT expanded)
+    const containerSchema = result.components?.schemas
+      ?.Container as unknown as Record<string, unknown>;
+    const nestedProp = (containerSchema?.properties as Record<string, unknown>)
+      ?.nested as Record<string, unknown>;
+    expect(nestedProp).toHaveProperty("$ref");
+    expect(nestedProp.$ref).toBe("#/components/schemas/Base");
+  });
 });

package/src/lib/util/flattenAllOf.ts

@@ -8,42 +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,
-  dereference,
-}) => {
-  try {
-    const dereferenced = await dereference(schema);
-
-    const flattened = traverse(dereferenced, (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;
-
-      return isSchemaObject ? (flattenAllOf(spec) as RecordAny) : spec;
-    }) 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/invariant.ts

@@ -7,6 +7,7 @@ export default function invariant(
    * the message takes a fair amount of effort to compute
    */
   message?: string | (() => string),
+  options?: ZudokuErrorOptions,
 ): asserts condition {
   if (condition) {
     return;
@@ -16,7 +17,7 @@ export default function invariant(
   const provided: string | undefined =
     typeof message === "function" ? message() : message;
 
-  throw new ZudokuError(provided ?? "Invariant failed");
+  throw new ZudokuError(provided ?? "Invariant failed", options);
 }
 
 export type ZudokuErrorOptions = {

package/src/lib/util/readFrontmatter.ts

@@ -0,0 +1,14 @@
+import { readFile } from "node:fs/promises";
+import matter from "gray-matter";
+import { parse, stringify } from "yaml";
+
+export const yaml = {
+  parse: (input: string) => parse(input) ?? {},
+  stringify: (obj: object) => stringify(obj),
+};
+
+export const readFrontmatter = async (filePath: string) => {
+  const content = await readFile(filePath, "utf-8");
+  const normalizedContent = content.replace(/\r\n/g, "\n");
+  return matter(normalizedContent, { engines: { yaml } });
+};

package/src/shiki/langs/c3.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/c3";

package/src/shiki/langs/gn.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/gn";

package/src/shiki/langs/markdown-nix.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/markdown-nix";

package/src/shiki/langs/moonbit.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/moonbit";

package/src/shiki/langs/openscad.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/openscad";

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;
+  };
+};