zudoku 0.0.0-fix-firebase-export.2e421fda → 0.0.0-fix-circular-ref-false-positives.zbe02c6a6

package/src/lib/core/transform-config.ts

@@ -0,0 +1,29 @@
+import createDeepmerge from "@fastify/deepmerge";
+import type { ConfigWithMeta } from "../../config/loader.js";
+import { type ConfigHookContext, isTransformConfigPlugin } from "./plugins.js";
+
+const mergeConfig = createDeepmerge({
+  mergeArray: (opt) => (_, source) => opt.clone(source),
+});
+
+export const runTransformConfigHooks = async (
+  config: ConfigWithMeta,
+): Promise<ConfigWithMeta> => {
+  const ctx = {
+    mode: config.__meta.mode,
+    rootDir: config.__meta.rootDir,
+    configPath: config.__meta.configPath,
+  } satisfies ConfigHookContext;
+  const plugins = config.plugins ?? [];
+
+  let result = config;
+
+  for (const plugin of plugins.filter(isTransformConfigPlugin)) {
+    const partial = await plugin.transformConfig?.(result, ctx);
+    if (!partial) continue;
+
+    result = mergeConfig(result, partial) as ConfigWithMeta;
+  }
+
+  return result;
+};

package/src/lib/errors/ErrorMessage.tsx

@@ -0,0 +1,38 @@
+import { Alert, AlertDescription, AlertTitle } from "zudoku/ui/Alert.js";
+import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight.js";
+import { DeveloperHint } from "../components/DeveloperHint.js";
+import { ZudokuError } from "../util/invariant.js";
+
+export function ErrorMessage({ error }: { error: unknown }) {
+  const message =
+    error instanceof Error ? error.message : "Something went wrong";
+
+  const showDeveloperHints = process.env.NODE_ENV === "development";
+
+  const hint = error instanceof ZudokuError ? error.developerHint : undefined;
+  const title =
+    error instanceof ZudokuError ? error.title : "Something went wrong";
+  const stack = error instanceof Error ? error.stack : undefined;
+  const cause = error instanceof Error ? error.cause : undefined;
+
+  const stringError = cause instanceof Error ? String(cause.stack) : stack;
+
+  return (
+    <>
+      <Alert variant="destructive">
+        <AlertTitle>{title}</AlertTitle>
+        <AlertDescription>{message}</AlertDescription>
+      </Alert>
+      {showDeveloperHints && hint && (
+        <DeveloperHint className="mb-4">{hint}</DeveloperHint>
+      )}
+      {showDeveloperHints && stringError && (
+        <SyntaxHighlight
+          className="max-h-[400px] [&>pre]:p-4"
+          language="js"
+          code={stringError}
+        />
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,221 @@
+import { describe, expect, it } from "vitest";
+import {
+  CIRCULAR_REF,
+  handleCircularRefs,
+  SCHEMA_REF_PREFIX,
+} from "./circular.js";
+
+describe("handleCircularRefs", () => {
+  it("should return primitives unchanged", () => {
+    expect(handleCircularRefs(null)).toBe(null);
+    expect(handleCircularRefs(undefined)).toBe(undefined);
+    expect(handleCircularRefs(42)).toBe(42);
+    expect(handleCircularRefs("hello")).toBe("hello");
+    expect(handleCircularRefs(true)).toBe(true);
+  });
+
+  it("should handle simple objects without refs", () => {
+    const obj = { type: "string", description: "A string" };
+    const result = handleCircularRefs(obj);
+    expect(result).toEqual(obj);
+  });
+
+  it("should handle arrays", () => {
+    const arr = [{ type: "string" }, { type: "number" }];
+    const result = handleCircularRefs(arr);
+    expect(result).toEqual(arr);
+  });
+
+  it("should detect true circular references via object identity", () => {
+    const obj: Record<string, unknown> = { type: "object" };
+    obj.self = obj;
+
+    const result = handleCircularRefs(obj);
+    expect(result.type).toBe("object");
+    expect(result.self).toContain(CIRCULAR_REF);
+  });
+
+  it("should detect circular refs via __$ref path", () => {
+    const inner = { __$ref: "#/components/schemas/Node", type: "object" };
+    const obj = {
+      __$ref: "#/components/schemas/Node",
+      type: "object",
+      properties: {
+        child: inner,
+      },
+    };
+    (inner as Record<string, unknown>).properties = { parent: obj };
+
+    const result = handleCircularRefs(obj);
+    expect(result.properties.child).toBe(
+      `${SCHEMA_REF_PREFIX}#/components/schemas/Node`,
+    );
+  });
+
+  // Regression test for #1869
+  it("should NOT mark sibling refs to the same schema as circular", () => {
+    const timestampSchema1 = {
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    };
+    const timestampSchema2 = {
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    };
+
+    const obj = {
+      type: "object",
+      properties: {
+        created_at: timestampSchema1,
+        updated_at: timestampSchema2,
+      },
+    };
+
+    const result = handleCircularRefs(obj);
+
+    expect(result.properties.created_at).toEqual({
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    });
+    expect(result.properties.updated_at).toEqual({
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    });
+  });
+
+  it("should allow same ref path in different branches of the tree", () => {
+    const obj = {
+      type: "object",
+      properties: {
+        user: {
+          type: "object",
+          properties: {
+            id: { __$ref: "#/components/schemas/identifier", type: "string" },
+            name: { type: "string" },
+          },
+        },
+        post: {
+          type: "object",
+          properties: {
+            id: { __$ref: "#/components/schemas/identifier", type: "string" },
+            title: { type: "string" },
+          },
+        },
+      },
+    };
+
+    const result = handleCircularRefs(obj);
+
+    expect(result.properties.user.properties.id.type).toBe("string");
+    expect(result.properties.post.properties.id.type).toBe("string");
+    expect(result.properties.user.properties.id).not.toBe(
+      expect.stringContaining(SCHEMA_REF_PREFIX),
+    );
+    expect(result.properties.post.properties.id).not.toBe(
+      expect.stringContaining(SCHEMA_REF_PREFIX),
+    );
+  });
+
+  it("should handle shared object instances (same object, multiple references)", () => {
+    const sharedSchema = { type: "string", description: "Shared" };
+    const obj = {
+      type: "object",
+      properties: { field1: sharedSchema, field2: sharedSchema },
+    };
+
+    const result = handleCircularRefs(obj);
+
+    expect(result.properties.field1).toEqual({
+      type: "string",
+      description: "Shared",
+    });
+    expect(result.properties.field2).toEqual({
+      type: "string",
+      description: "Shared",
+    });
+  });
+
+  it("should handle nested arrays with refs", () => {
+    const obj = {
+      type: "object",
+      allOf: [
+        { __$ref: "#/components/schemas/Base", type: "object" },
+        { type: "object", properties: { extra: { type: "string" } } },
+      ],
+    };
+
+    const result = handleCircularRefs(obj);
+
+    expect(result.allOf[0]).toEqual({
+      __$ref: "#/components/schemas/Base",
+      type: "object",
+    });
+  });
+
+  it("should handle shared object instances with __$ref without marking circular", () => {
+    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",
+    });
+  });
+
+  it("should mark circular ref with property name from path", () => {
+    const parent: Record<string, unknown> = {
+      type: "object",
+      properties: {} as Record<string, unknown>,
+    };
+    const child: Record<string, unknown> = {
+      type: "object",
+      properties: { back: parent },
+    };
+    (parent.properties as Record<string, unknown>).child = child;
+
+    const result = handleCircularRefs(parent);
+
+    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,8 +1,8 @@
 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:";
 
 const OPENAPI_PROPS = new Set([
   "properties",
@@ -13,39 +13,52 @@ const OPENAPI_PROPS = new Set([
   "oneOf",
 ]);
 
-const handleCircularRefs = (
+export const handleCircularRefs = (
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   obj: any,
-  visited = new WeakSet(),
+  currentPath = new WeakSet(),
   refs = new WeakMap(),
   path: string[] = [],
+  currentRefPaths = new Set<string>(),
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
 ): any => {
   if (obj === null || typeof obj !== "object") return obj;
 
-  if (visited.has(obj)) {
-    const cached = refs.get(obj);
-    if (cached) return cached;
-    const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
+  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;
+    const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
     return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
 
-  visited.add(obj);
+  if (refs.has(obj)) return refs.get(obj);
 
-  if (Array.isArray(obj)) {
-    const result = obj.map((item, index) =>
-      handleCircularRefs(item, visited, refs, [...path, index.toString()]),
+  currentPath.add(obj);
+  if (typeof refPath === "string") currentRefPaths.add(refPath);
+
+  const recurse = (value: unknown, key: string) =>
+    handleCircularRefs(
+      value,
+      currentPath,
+      refs,
+      [...path, key],
+      currentRefPaths,
     );
-    refs.set(obj, result);
-    return result;
-  }
 
-  const result: RecordAny = {};
-  for (const [key, value] of Object.entries(obj)) {
-    result[key] = handleCircularRefs(value, visited, refs, [...path, key]);
-  }
+  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)]),
+      );
+
   refs.set(obj, result);
+  currentPath.delete(obj);
+  if (typeof refPath === "string") currentRefPaths.delete(refPath);
+
   return result;
 };
 

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

@@ -473,7 +473,9 @@ const OperationItem = builder
                     name,
                     ...(typeof value === "string" ? { value } : value),
                   }))
-                : [],
+                : content.example !== undefined
+                  ? [{ name: "", value: content.example }]
+                  : [],
               encoding: Object.entries(content.encoding ?? {}).map(
                 ([name, value]) => ({ name, ...value }),
               ),
@@ -490,7 +492,7 @@ const OperationItem = builder
               statusCode,
               description: response.description,
               content: Object.entries(response.content ?? {}).map(
-                ([mediaType, { schema, examples }]) => ({
+                ([mediaType, { schema, examples, example }]) => ({
                   mediaType,
                   schema,
                   examples: examples
@@ -498,7 +500,9 @@ const OperationItem = builder
                         name,
                         ...(typeof value === "string" ? { value } : value),
                       }))
-                    : [],
+                    : example !== undefined
+                      ? [{ name: "", value: example }]
+                      : [],
                 }),
               ),
               headers: response.headers,