fix(parser): internal cache improvements to dereferencing circular refs (#973)

## 🧰 Changes

We uncovered a problem with the dereferencing functionality within our
OpenAPI parser on schemas with an extensive amount of circular
references where under these circumstances it could take upwards to an
hour to dereference a schema. I was able to trace it down to being a
problem within
[@apidevtools/json-schema-ref-parser](https://npm.im/@apidevtools/json-schema-ref-parser)
where because it was not always using its internal cache it would get
into situations where, when parsing a circular reference, it would often
attempt to re-parse that same reference multiple times.

I submitted a fix for this over in
APIDevTools/json-schema-ref-parser#380, and this
pulls that in along with builds a unit test around one of these
problematic schemas.

Author: erunion

package-lock.json

@@ -89,13 +89,8 @@ describe('analyzer queries (OpenAPI)', () => {
   describe('circularRefs', () => {
     it('should determine if a definition has circular refs when it does', async () => {
       await expect(QUERIES.circularRefs(circular)).resolves.toStrictEqual([
-        '#/components/schemas/BodyPart/properties/parent',
-        '#/components/schemas/MultiPart/properties/bodyParts/items',
         '#/components/schemas/MultiPart/properties/parent',
         '#/components/schemas/ZoneOffset/properties/rules',
-        '#/components/schemas/ZoneOffsetTransition/properties/offsetAfter',
-        '#/components/schemas/ZoneOffsetTransition/properties/offsetBefore',
-        '#/components/schemas/ZoneRules/properties/transitions/items',
       ]);
     });
 

packages/oas/test/analyzer/queries/openapi.test.ts

@@ -1753,11 +1753,7 @@ describe('Oas', () => {
 
       expect(oas.getCircularReferences()).toStrictEqual([
         '#/components/schemas/offsetTransition/properties/offsetAfter',
-        '#/components/schemas/offsetTransition/properties/offsetBefore',
         '#/components/schemas/ProductStock/properties/test_param/items',
-        '#/components/schemas/rules/properties/transitions/items',
-        '#/components/schemas/offset/properties/rules',
-        '#/components/schemas/SalesLine/properties/stock',
       ]);
     });
 

packages/oas/test/index.test.ts

@@ -58,7 +58,7 @@
     "test": "echo 'Please run tests from the root!' && exit 1"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^11.9.2",
+    "@apidevtools/json-schema-ref-parser": "^12.0.1",
     "@readme/better-ajv-errors": "^2.3.2",
     "@readme/openapi-schemas": "^3.1.0",
     "@types/json-schema": "^7.0.15",

packages/parser/package.json

@@ -0,0 +1,103 @@
+import type { ValidAPIDefinition } from '../../utils.js';
+
+import { describe, it, expect, assert } from 'vitest';
+
+import { dereference, validate } from '../../../src/index.js';
+import { relativePath } from '../../utils.js';
+import { toValidate } from '../../vitest.matchers.js';
+
+expect.extend({ toValidate });
+
+describe('API with extensive circular $refs that cause slowdowns', () => {
+  it('should validate successfully', async () => {
+    await expect(relativePath('specs/circular-slowdowns/schema.json')).toValidate();
+  });
+
+  it('should dereference successfully', async () => {
+    const circularRefs = new Set<string>();
+
+    const schema = await dereference<ValidAPIDefinition>(relativePath('specs/circular-slowdowns/schema.json'), {
+      dereference: {
+        onCircular: (ref: string) => circularRefs.add(ref),
+      },
+    });
+
+    // Ensure that a non-circular $ref was dereferenced.
+    expect(schema.components?.schemas?.ArrayOfMappedData).toStrictEqual({
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          mappingTypeName: { type: 'string' },
+          sourceSystemValue: { type: 'string' },
+          mappedValueID: { type: 'string' },
+          mappedValue: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    });
+
+    // Ensure that a circular $ref **was** dereferenced.
+    expect(circularRefs).toHaveLength(23);
+    expect(schema.components?.schemas?.Customer?.properties?.customerNode).toStrictEqual({
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          customerNodeGuid: expect.any(Object),
+          customerGuid: expect.any(Object),
+          nodeId: expect.any(Object),
+          customerGu: expect.any(Object),
+        },
+        additionalProperties: false,
+      },
+    });
+  });
+
+  it('should not dereference circular $refs if "options.dereference.circular" is "ignore"', async () => {
+    const circularRefs = new Set<string>();
+
+    const schema = await dereference<ValidAPIDefinition>(relativePath('specs/circular-slowdowns/schema.json'), {
+      dereference: {
+        circular: 'ignore',
+        onCircular: (ref: string) => circularRefs.add(ref),
+      },
+    });
+
+    // Ensure that a non-circular $ref was dereferenced.
+    expect(schema.components?.schemas?.ArrayOfMappedData).toStrictEqual({
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          mappingTypeName: { type: 'string' },
+          sourceSystemValue: { type: 'string' },
+          mappedValueID: { type: 'string' },
+          mappedValue: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    });
+
+    // Ensure that a circular $ref was **not** dereferenced.
+    expect(circularRefs).toHaveLength(23);
+    expect(schema.components?.schemas?.Customer?.properties?.customerNode).toStrictEqual({
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CustomerNode',
+      },
+    });
+  });
+
+  it('should fail validation if "options.dereference.circular" is false', async () => {
+    try {
+      await validate(relativePath('specs/circular-slowdowns/schema.json'), { dereference: { circular: false } });
+      assert.fail();
+    } catch (err) {
+      expect(err).toBeInstanceOf(ReferenceError);
+      expect(err.message).toBe(
+        'The API contains circular references but the validator is configured to not permit them.',
+      );
+    }
+  });
+});