From e58322addb0e66fc3699524c11153214117cca0c Mon Sep 17 00:00:00 2001
From: Lubos <lubos@heyapi.dev>
Date: Thu, 23 Oct 2025 02:39:11 +0800
Subject: [PATCH] fix: do not overwrite  in circular self references

---
 lib/__tests__/bundle.test.ts  | 12 +++++++++++-
 lib/__tests__/pointer.test.ts |  1 -
 lib/bundle.ts                 |  6 ++++--
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/lib/__tests__/bundle.test.ts b/lib/__tests__/bundle.test.ts
index 8a65e023..e234984f 100644
--- a/lib/__tests__/bundle.test.ts
+++ b/lib/__tests__/bundle.test.ts
@@ -9,7 +9,17 @@ describe("bundle", () => {
     const refParser = new $RefParser();
     const pathOrUrlOrSchema = path.resolve("lib", "__tests__", "spec", "circular-ref-with-description.json");
     const schema = await refParser.bundle({ pathOrUrlOrSchema });
-    expect(schema).not.toBeUndefined();
+    expect(schema).toEqual({
+      schemas: {
+        Bar: {
+          $ref: '#/schemas/Foo',
+          description: 'ok',
+        },
+        Foo: {
+          $ref: '#/schemas/Bar',
+        },
+      },
+    });
   });
 
   it("bundles multiple references to the same file correctly", async () => {
diff --git a/lib/__tests__/pointer.test.ts b/lib/__tests__/pointer.test.ts
index bc876110..cd0ca223 100644
--- a/lib/__tests__/pointer.test.ts
+++ b/lib/__tests__/pointer.test.ts
@@ -7,7 +7,6 @@ describe("pointer", () => {
     const refParser = new $RefParser();
     const pathOrUrlOrSchema = path.resolve("lib", "__tests__", "spec", "openapi-paths-ref.json");
     const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
-    console.log(JSON.stringify(schema, null, 2));
 
     // The GET endpoint should have its schema defined inline
     const getSchema = schema.paths["/foo"].get.responses["200"].content["application/json"].schema;
diff --git a/lib/bundle.ts b/lib/bundle.ts
index 4bc45afd..7b73e677 100644
--- a/lib/bundle.ts
+++ b/lib/bundle.ts
@@ -579,9 +579,11 @@ function remap(parser: $RefParser, inventory: InventoryEntry[]) {
       continue;
     }
 
-    // Keep internal refs internal
+    // Keep internal refs internal. However, if the $ref extends the resolved value
+    // (i.e. it has additional properties in addition to "$ref"), then we must
+    // preserve the original $ref rather than rewriting it to the resolved hash.
     if (!entry.external) {
-      if (entry.$ref && typeof entry.$ref === "object") {
+      if (!entry.extended && entry.$ref && typeof entry.$ref === "object") {
         entry.$ref.$ref = entry.hash;
       }
       continue;