fix(reference): add support for external cycles detection in OpenAPI 3.0.x dereference strategy (#3870)

Refs #3863

Author: char0n

packages/apidom-reference/src/dereference/strategies/openapi-3-0/visitor.ts

@@ -62,13 +62,22 @@ const OpenApi3_0DereferenceVisitor = stampit({
     reference: null,
     options: null,
     ancestors: null,
+    refractCache: null,
   },
-  init({ indirections = [], reference, namespace, options, ancestors = new AncestorLineage() }) {
+  init({
+    indirections = [],
+    reference,
+    namespace,
+    options,
+    ancestors = new AncestorLineage(),
+    refractCache = new Map(),
+  }) {
     this.indirections = indirections;
     this.namespace = namespace;
     this.reference = reference;
     this.options = options;
     this.ancestors = new AncestorLineage(...ancestors);
+    this.refractCache = refractCache;
   },
   methods: {
     toBaseURI(uri: string): string {
@@ -154,15 +163,20 @@ const OpenApi3_0DereferenceVisitor = stampit({
       // applying semantics to a fragment
       if (isPrimitiveElement(referencedElement)) {
         const referencedElementType = toValue(referencingElement.meta.get('referenced-element'));
+        const cacheKey = `${referencedElementType}-${toValue(identityManager.identify(referencedElement))}`;
 
-        if (isReferenceLikeElement(referencedElement)) {
+        if (this.refractCache.has(cacheKey)) {
+          referencedElement = this.refractCache.get(cacheKey);
+        } else if (isReferenceLikeElement(referencedElement)) {
           // handling indirect references
           referencedElement = ReferenceElement.refract(referencedElement);
           referencedElement.setMetaProperty('referenced-element', referencedElementType);
+          this.refractCache.set(cacheKey, referencedElement);
         } else {
           // handling direct references
           const ElementClass = this.namespace.getElementClass(referencedElementType);
           referencedElement = ElementClass.refract(referencedElement);
+          this.refractCache.set(cacheKey, referencedElement);
         }
       }
 
@@ -188,6 +202,7 @@ const OpenApi3_0DereferenceVisitor = stampit({
         indirections: [...this.indirections],
         options: this.options,
         ancestors: ancestorsLineage,
+        refractCache: this.refractCache,
       });
       referencedElement = await visitAsync(referencedElement, visitor, {
         keyMap,
@@ -277,7 +292,14 @@ const OpenApi3_0DereferenceVisitor = stampit({
 
       // applying semantics to a referenced element
       if (isPrimitiveElement(referencedElement)) {
-        referencedElement = PathItemElement.refract(referencedElement);
+        const cacheKey = `pathItem-${toValue(identityManager.identify(referencedElement))}`;
+
+        if (this.refractCache.has(cacheKey)) {
+          referencedElement = this.refractCache.get(cacheKey);
+        } else {
+          referencedElement = PathItemElement.refract(referencedElement);
+          this.refractCache.set(cacheKey, referencedElement);
+        }
       }
 
       // detect direct or indirect reference
@@ -302,6 +324,7 @@ const OpenApi3_0DereferenceVisitor = stampit({
         indirections: [...this.indirections],
         options: this.options,
         ancestors: ancestorsLineage,
+        refractCache: this.refractCache,
       });
       referencedElement = await visitAsync(referencedElement, visitor, {
         keyMap,

packages/apidom-reference/test/dereference/strategies/openapi-3-0/path-item-object/fixtures/external-cycle/ex.json

@@ -0,0 +1,13 @@
+{
+  "summary": "path item summary",
+  "description": "path item description",
+  "get": {
+    "callbacks": {
+      "myCallback": {
+        "{$request.query.queryUrl}": {
+          "$ref": "#"
+        }
+      }
+    }
+  }
+}

packages/apidom-reference/test/dereference/strategies/openapi-3-0/path-item-object/fixtures/external-cycle/root.json

@@ -0,0 +1,8 @@
+{
+  "openapi": "3.0.3",
+  "paths": {
+    "/path1": {
+      "$ref": "./ex.json"
+    }
+  }
+}

packages/apidom-reference/test/dereference/strategies/openapi-3-0/path-item-object/index.ts

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { assert } from 'chai';
 import { toValue } from '@swagger-api/apidom-core';
 import { mediaTypes } from '@swagger-api/apidom-ns-openapi-3-0';
+import { evaluate } from '@swagger-api/apidom-json-pointer';
 
 import { loadJsonFile } from '../../../../helpers';
 import { dereference } from '../../../../../src';
@@ -114,6 +115,24 @@ describe('dereference', function () {
             });
           });
 
+          context('given $ref field pointing to external cycles', function () {
+            const fixturePath = path.join(rootFixturePath, 'external-cycle');
+
+            specify('should dereference', async function () {
+              const rootFilePath = path.join(fixturePath, 'root.json');
+              const dereferenced = await dereference(rootFilePath, {
+                parse: { mediaType: mediaTypes.latest('json') },
+              });
+              const parent = evaluate('/0/paths/~1path1/get', dereferenced);
+              const cyclicParent = evaluate(
+                '/0/paths/~1path1/get/callbacks/myCallback/{$request.query.queryUrl}/get',
+                dereferenced,
+              );
+
+              assert.strictEqual(parent, cyclicParent);
+            });
+          });
+
           context('given $ref field pointing to external indirections', function () {
             const fixturePath = path.join(rootFixturePath, 'external-indirections');
 

packages/apidom-reference/test/dereference/strategies/openapi-3-0/reference-object/fixtures/external-cycle/ex.json

@@ -0,0 +1,8 @@
+{
+  "type": "object",
+  "properties": {
+    "parent": {
+      "$ref": "#"
+    }
+  }
+}

packages/apidom-reference/test/dereference/strategies/openapi-3-0/reference-object/fixtures/external-cycle/root.json

@@ -0,0 +1,10 @@
+{
+  "openapi": "3.0.3",
+  "components": {
+    "schemas": {
+       "externalSchema": {
+        "$ref": "./ex.json"
+      }
+    }
+  }
+}

packages/apidom-reference/test/dereference/strategies/openapi-3-0/reference-object/index.ts

@@ -84,6 +84,27 @@ describe('dereference', function () {
           });
         });
 
+        context('given Reference Objects pointing to external cycles', function () {
+          const fixturePath = path.join(rootFixturePath, 'external-cycle');
+
+          specify('should dereference', async function () {
+            const rootFilePath = path.join(fixturePath, 'root.json');
+            const dereferenced = await dereference(rootFilePath, {
+              parse: { mediaType: mediaTypes.latest('json') },
+            });
+            const parent = evaluate(
+              '/0/components/schemas/externalSchema/properties',
+              dereferenced,
+            );
+            const cyclicParent = evaluate(
+              '/0/components/schemas/externalSchema/properties/parent/properties',
+              dereferenced,
+            );
+
+            assert.strictEqual(parent, cyclicParent);
+          });
+        });
+
         context('given Reference Objects pointing to external indirections', function () {
           const fixturePath = path.join(rootFixturePath, 'external-indirections');