fix: follow chained $ref pointers in dereference

src/open-api/utils/dereference.test.ts

@@ -1,5 +1,57 @@
 import { dereference } from './dereference.js'
 
+it('follows chained $ref pointers to a leaf value', async () => {
+  await expect(
+    dereference({
+      foo: {
+        $ref: '#/components/schemas/A',
+      },
+      components: {
+        schemas: {
+          A: { $ref: '#/components/schemas/B' },
+          B: { $ref: '#/components/schemas/C' },
+          C: { type: 'string' },
+        },
+      },
+    }),
+  ).resolves.toMatchInlineSnapshot(`
+    {
+      "components": {
+        "schemas": {
+          "A": {
+            "type": "string",
+          },
+          "B": {
+            "type": "string",
+          },
+          "C": {
+            "type": "string",
+          },
+        },
+      },
+      "foo": {
+        "type": "string",
+      },
+    }
+  `)
+})
+
+it('throws when a $ref chain is circular', async () => {
+  await expect(
+    dereference({
+      foo: {
+        $ref: '#/components/schemas/A',
+      },
+      components: {
+        schemas: {
+          A: { $ref: '#/components/schemas/B' },
+          B: { $ref: '#/components/schemas/A' },
+        },
+      },
+    }),
+  ).rejects.toThrow(/circular \$ref chain/i)
+})
+
 it('dereferences', async () => {
   await expect(
     dereference({

src/open-api/utils/dereference.ts

@@ -19,8 +19,28 @@ export async function dereference(document: unknown, root?: any): Promise<any> {
 
   if (typeof document === 'object' && document !== null) {
     if ('$ref' in document && typeof document['$ref'] === 'string') {
-      const path = pointerToPath(document['$ref'])
-      return path.reduce((item, key) => item[key], root)
+      const visited = new Set<string>()
+      let resolved: any = document
+      while (
+        resolved !== null &&
+        typeof resolved === 'object' &&
+        '$ref' in resolved &&
+        typeof resolved['$ref'] === 'string'
+      ) {
+        const ref = resolved['$ref']
+        if (visited.has(ref)) {
+          throw new Error(
+            `Failed to dereference document: circular $ref chain detected (${[
+              ...visited,
+              ref,
+            ].join(' -> ')})`,
+          )
+        }
+        visited.add(ref)
+        const path = pointerToPath(ref)
+        resolved = path.reduce((item, key) => item[key], root)
+      }
+      return dereference(resolved, root)
     }
 
     await Promise.all(