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

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,

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";
 
@@ -25,6 +26,8 @@ export type TagObject = DeepOmitReference<OpenAPIV3_1.TagObject>;
 export type ExampleObject = DeepOmitReference<OpenAPIV3_1.ExampleObject>;
 export type EncodingObject = DeepOmitReference<OpenAPIV3_1.EncodingObject>;
 export type SchemaObject = DeepOmitReference<OpenAPIV3_1.SchemaObject>;
+export type ArraySchemaObject =
+  DeepOmitReference<OpenAPIV3_1.ArraySchemaObject>;
 export type ServerObject = DeepOmitReference<OpenAPIV3_1.ServerObject>;
 
 export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
@@ -102,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;
 };