fix: resolve multiple dereference and bundle issues (#338, #370, #395) (#409)

- Fix #370: Reset false circular detection for extended $refs during pointer token walking to handle Pydantic-style schemas with $ref alongside $defs
- Fix #338: Add post-processing in bundle() to correct $ref paths that incorrectly traverse through other $ref nodes
- Fix #395: Add maxDepth option to dereference (default 500) to prevent stack overflow on deeply nested schemas
- All fixes include comprehensive tests and pass full test suite (298 tests)

Author: jonluca

lib/bundle.ts

@@ -41,6 +41,9 @@ function bundle<S extends object = JSONSchema, O extends ParserOptions<S> = Pars
 
   // Remap all $ref pointers
   remap<S, O>(inventory, options);
+
+  // Fix any $ref paths that traverse through other $refs (which is invalid per JSON Schema spec)
+  fixRefsThroughRefs(inventory, parser.schema as any);
 }
 
 /**
@@ -316,4 +319,94 @@ function removeFromInventory(inventory: InventoryEntry[], entry: any) {
   const index = inventory.indexOf(entry);
   inventory.splice(index, 1);
 }
+
+/**
+ * After remapping, some $ref paths may traverse through other $ref nodes.
+ * JSON pointer resolution does not follow $ref indirection, so these paths are invalid.
+ * This function detects and fixes such paths by following any intermediate $refs
+ * to compute a valid direct path.
+ */
+function fixRefsThroughRefs(inventory: InventoryEntry[], schema: any) {
+  for (const entry of inventory) {
+    if (!entry.$ref || typeof entry.$ref !== "object" || !("$ref" in entry.$ref)) {
+      continue;
+    }
+
+    const refValue = entry.$ref.$ref;
+    if (typeof refValue !== "string" || !refValue.startsWith("#/")) {
+      continue;
+    }
+
+    const fixedPath = resolvePathThroughRefs(schema, refValue);
+    if (fixedPath !== refValue) {
+      entry.$ref.$ref = fixedPath;
+    }
+  }
+}
+
+/**
+ * Walks a JSON pointer path through the schema. If any intermediate value
+ * is a $ref, follows it and adjusts the path accordingly.
+ * Returns the corrected path that doesn't traverse through any $ref.
+ */
+function resolvePathThroughRefs(schema: any, refPath: string): string {
+  if (!refPath.startsWith("#/")) {
+    return refPath;
+  }
+
+  const segments = refPath.slice(2).split("/");
+  let current = schema;
+  const resolvedSegments: string[] = [];
+
+  for (const seg of segments) {
+    if (current === null || current === undefined || typeof current !== "object") {
+      // Can't walk further, return original path
+      return refPath;
+    }
+
+    // If the current value is a $ref, follow it
+    if ("$ref" in current && typeof current.$ref === "string" && current.$ref.startsWith("#/")) {
+      // Follow the $ref and restart the path from its target
+      const targetSegments = current.$ref.slice(2).split("/");
+      resolvedSegments.length = 0;
+      resolvedSegments.push(...targetSegments);
+      current = walkPath(schema, current.$ref);
+      if (current === null || current === undefined || typeof current !== "object") {
+        return refPath;
+      }
+    }
+
+    const decoded = seg.replace(/~1/g, "/").replace(/~0/g, "~");
+    const idx = Array.isArray(current) ? parseInt(decoded) : decoded;
+    current = current[idx];
+    resolvedSegments.push(seg);
+  }
+
+  const result = "#/" + resolvedSegments.join("/");
+  return result;
+}
+
+/**
+ * Walks a JSON pointer path through a schema object, returning the value at that path.
+ */
+function walkPath(schema: any, path: string): any {
+  if (!path.startsWith("#/")) {
+    return undefined;
+  }
+
+  const segments = path.slice(2).split("/");
+  let current = schema;
+
+  for (const seg of segments) {
+    if (current === null || current === undefined || typeof current !== "object") {
+      return undefined;
+    }
+    const decoded = seg.replace(/~1/g, "/").replace(/~0/g, "~");
+    const idx = Array.isArray(current) ? parseInt(decoded) : decoded;
+    current = current[idx];
+  }
+
+  return current;
+}
+
 export default bundle;

lib/dereference.ts

@@ -31,6 +31,7 @@ function dereference<S extends object = JSONSchema, O extends ParserOptions<S> =
     parser.$refs,
     options,
     start,
+    0,
   );
   parser.$refs.circular = dereferenced.circular;
   parser.schema = dereferenced.value;
@@ -48,6 +49,7 @@ function dereference<S extends object = JSONSchema, O extends ParserOptions<S> =
  * @param $refs
  * @param options
  * @param startTime - The time when the dereferencing started
+ * @param depth - The current recursion depth
  * @returns
  */
 function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
@@ -60,6 +62,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   $refs: $Refs<S, O>,
   options: O,
   startTime: number,
+  depth: number,
 ) {
   let dereferenced;
   const result = {
@@ -70,6 +73,14 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   checkDereferenceTimeout<S, O>(startTime, options);
 
   const derefOptions = (options.dereference || {}) as DereferenceOptions;
+  const maxDepth = derefOptions.maxDepth ?? 500;
+  if (depth > maxDepth) {
+    throw new RangeError(
+      `Maximum dereference depth (${maxDepth}) exceeded at ${pathFromRoot}. ` +
+        `This likely indicates an extremely deep or recursive schema. ` +
+        `You can increase this limit with the dereference.maxDepth option.`,
+    );
+  }
   const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
 
   if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
@@ -88,6 +99,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
           $refs,
           options,
           startTime,
+          depth,
         );
         result.circular = dereferenced.circular;
         result.value = dereferenced.value;
@@ -116,6 +128,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
               $refs,
               options,
               startTime,
+              depth,
             );
             circular = dereferenced.circular;
             // Avoid pointless mutations; breaks frozen objects to no profit
@@ -159,6 +172,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
                 $refs,
                 options,
                 startTime,
+                depth + 1,
               );
               circular = dereferenced.circular;
               // Avoid pointless mutations; breaks frozen objects to no profit
@@ -205,6 +219,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
   $refs: $Refs<S, O>,
   options: O,
   startTime: number,
+  depth: number,
 ) {
   const isExternalRef = $Ref.isExternal$Ref($ref);
   const shouldResolveOnCwd = isExternalRef && options?.dereference?.externalReferenceResolution === "root";
@@ -295,6 +310,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
       $refs,
       options,
       startTime,
+      depth + 1,
     );
     circular = dereferenced.circular;
     dereferencedValue = dereferenced.value;

lib/options.ts

@@ -89,6 +89,15 @@ export interface DereferenceOptions {
    * Default: `true`
    */
   mergeKeys?: boolean;
+
+  /**
+   * The maximum recursion depth for dereferencing nested schemas.
+   * If the schema nesting exceeds this depth, a RangeError will be thrown
+   * with a descriptive message instead of crashing with a stack overflow.
+   *
+   * Default: 500
+   */
+  maxDepth?: number;
 }
 
 /**

lib/pointer.ts

@@ -89,9 +89,22 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
     this.value = unwrapOrThrow(obj);
 
     for (let i = 0; i < tokens.length; i++) {
+      // During token walking, if the current value is an extended $ref (has sibling keys
+      // alongside $ref, as allowed by JSON Schema 2019-09+), and resolveIf$Ref marks it
+      // as circular because the $ref resolves to the same path we're walking, we should
+      // reset the circular flag and continue walking the object's own properties.
+      // This prevents false circular detection when e.g. a root schema has both
+      // $ref: "#/$defs/Foo" and $defs: { Foo: {...} } as siblings.
+      const wasCircular = this.circular;
+      const isExtendedRef = $Ref.isExtended$Ref(this.value);
       if (resolveIf$Ref(this, options, pathFromRoot)) {
         // The $ref path has changed, so append the remaining tokens to the path
         this.path = Pointer.join(this.path, tokens.slice(i));
+      } else if (!wasCircular && this.circular && isExtendedRef) {
+        // resolveIf$Ref set circular=true on an extended $ref during token walking.
+        // Since we still have tokens to process, the object should be walked by its
+        // properties, not treated as a circular self-reference.
+        this.circular = false;
       }
 
       const token = tokens[i];

test/specs/bundle-ref-through-ref/bundle-ref-through-ref.spec.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import $RefParser from "../../../lib/index.js";
+import path from "../../utils/path.js";
+
+describe("Issue #338: bundle() should not create refs through refs", () => {
+  it("should produce valid bundled output where no $ref path traverses through another $ref", async () => {
+    const parser = new $RefParser();
+    const schema = await parser.bundle(path.rel("test/specs/bundle-ref-through-ref/schemaA.json"));
+
+    const bundledStr = JSON.stringify(schema, null, 2);
+
+    // Collect all $ref values in the bundled schema
+    const refs: string[] = [];
+    function collectRefs(obj: any, path: string) {
+      if (!obj || typeof obj !== "object") return;
+      if (Array.isArray(obj)) {
+        obj.forEach((item, i) => collectRefs(item, `${path}/${i}`));
+        return;
+      }
+      for (const [key, val] of Object.entries(obj)) {
+        if (key === "$ref" && typeof val === "string") {
+          refs.push(val);
+        } else {
+          collectRefs(val, `${path}/${key}`);
+        }
+      }
+    }
+    collectRefs(schema, "#");
+
+    // For each $ref, verify the path can be resolved by walking the literal
+    // object structure (without following $ref indirection)
+    for (const ref of refs) {
+      if (!ref.startsWith("#/")) continue;
+
+      const segments = ref.slice(2).split("/");
+      let current: any = schema;
+      let valid = true;
+      let failedAt = "";
+
+      for (const seg of segments) {
+        if (current === null || current === undefined || typeof current !== "object") {
+          valid = false;
+          failedAt = seg;
+          break;
+        }
+        // If the current value at this path is itself a $ref, the path is invalid
+        // (JSON pointer resolution doesn't follow $ref indirection)
+        if ("$ref" in current && typeof current.$ref === "string" && seg !== "$ref") {
+          // This position has a $ref - the pointer can't traverse through it
+          valid = false;
+          failedAt = `$ref at ${seg}`;
+          break;
+        }
+        const idx = Array.isArray(current) ? parseInt(seg) : seg;
+        current = current[idx];
+      }
+
+      expect(valid, `$ref "${ref}" traverses through another $ref (failed at: ${failedAt}). Bundled:\n${bundledStr}`).toBe(
+        true,
+      );
+    }
+  });
+});

test/specs/bundle-ref-through-ref/schemaA.json

@@ -0,0 +1,6 @@
+{
+  "$id": "schemaA/1.0",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "$ref": "schemaB.json#/definitions/SupplierPriceElement"
+}

test/specs/bundle-ref-through-ref/schemaB.json

@@ -0,0 +1,48 @@
+{
+  "$id": "schemaC/1.0",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "SupplierPriceElement": {
+      "type": "object",
+      "properties": {
+        "purchaseRate": {
+          "$ref": "#/definitions/InDetailParent"
+        },
+        "fee": {
+          "$ref": "#/definitions/AllFees"
+        }
+      }
+    },
+    "AllFees": {
+      "type": "object",
+      "properties": {
+        "modificationFee": {
+          "$ref": "#/definitions/MonetaryAmount"
+        }
+      }
+    },
+    "MonetaryAmount": {
+      "type": "object",
+      "properties": {
+        "amount": {
+          "$ref": "#/definitions/Amount"
+        }
+      }
+    },
+    "Amount": {
+      "type": "number",
+      "format": "float"
+    },
+    "InDetailParent": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/MonetaryAmount"
+        },
+        {
+          "type": "object",
+          "$ref": "#/definitions/Amount"
+        }
+      ]
+    }
+  }
+}

test/specs/bundle/bundled.ts

@@ -16,7 +16,7 @@ export default {
         },
         {
           type: "object",
-          $ref: "#/properties/fee/properties/modificationFee/properties/amount",
+          $ref: "#/properties/purchaseRate/allOf/0/properties/amount",
         },
       ],
     },

test/specs/circular-external-self/circular-external-self.spec.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import $RefParser from "../../../lib/index.js";
+import path from "../../utils/path.js";
+
+describe("Circular $ref to self via filename vs hash", () => {
+  it("should dereference $ref: '#' with circular reference at top level", async () => {
+    const parser = new $RefParser();
+    const schema = await parser.dereference(path.rel("test/specs/circular-external-self/recursive-self.json"));
+
+    expect(parser.$refs.circular).to.equal(true);
+    // When using $ref: "#", the value property should directly be a circular reference to the schema itself
+    expect(schema.properties.value).to.equal(schema);
+  });
+
+  it("should dereference $ref: 'recursive-filename.json' with circular reference at top level", async () => {
+    const parser = new $RefParser();
+    const schema = await parser.dereference(
+      path.rel("test/specs/circular-external-self/recursive-filename.json"),
+    );
+
+    expect(parser.$refs.circular).to.equal(true);
+    // When using $ref: "recursive-filename.json", the value property should ALSO directly
+    // be a circular reference to the schema itself (not one level too deep)
+    // Issue #378: this was producing schema.properties.value !== schema (one level too deep)
+    expect(schema.properties.value).to.equal(schema);
+  });
+});

test/specs/circular-external-self/recursive-filename.json

@@ -0,0 +1,11 @@
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "value": {
+      "$ref": "recursive-filename.json"
+    }
+  }
+}