fix(reference): add support for external cycles detection in OpenAPI …

…3.1.0 dereference strategy (#3873)

Refs #3863

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

@@ -418,7 +418,14 @@ const OpenApi3_0DereferenceVisitor = stampit({
         operationElement = evaluate(jsonPointer, reference.value.result);
         // applying semantics to a referenced element
         if (isPrimitiveElement(operationElement)) {
-          operationElement = OperationElement.refract(operationElement);
+          const cacheKey = `operation-${toValue(identityManager.identify(operationElement))}`;
+
+          if (this.refractCache.has(cacheKey)) {
+            operationElement = this.refractCache.get(cacheKey);
+          } else {
+            operationElement = OperationElement.refract(operationElement);
+            this.refractCache.set(cacheKey, operationElement);
+          }
         }
         // create shallow clone to be able to annotate with metadata
         operationElement = cloneShallow(operationElement);

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

@@ -73,13 +73,22 @@ const OpenApi3_1DereferenceVisitor = 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 {
@@ -165,15 +174,20 @@ const OpenApi3_1DereferenceVisitor = 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);
         }
       }
 
@@ -199,6 +213,7 @@ const OpenApi3_1DereferenceVisitor = stampit({
         indirections: [...this.indirections],
         options: this.options,
         ancestors: ancestorsLineage,
+        refractCache: this.refractCache,
       });
       referencedElement = await visitAsync(referencedElement, visitor, {
         keyMap,
@@ -307,7 +322,14 @@ const OpenApi3_1DereferenceVisitor = 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
@@ -332,6 +354,7 @@ const OpenApi3_1DereferenceVisitor = stampit({
         indirections: [...this.indirections],
         options: this.options,
         ancestors: ancestorsLineage,
+        refractCache: this.refractCache,
       });
       referencedElement = await visitAsync(referencedElement, visitor, {
         keyMap,
@@ -425,7 +448,14 @@ const OpenApi3_1DereferenceVisitor = stampit({
         operationElement = jsonPointerEvaluate(jsonPointer, reference.value.result);
         // applying semantics to a referenced element
         if (isPrimitiveElement(operationElement)) {
-          operationElement = OperationElement.refract(operationElement);
+          const cacheKey = `operation-${toValue(identityManager.identify(operationElement))}`;
+
+          if (this.refractCache.has(cacheKey)) {
+            operationElement = this.refractCache.get(cacheKey);
+          } else {
+            operationElement = OperationElement.refract(operationElement);
+            this.refractCache.set(cacheKey, operationElement);
+          }
         }
         // create shallow clone to be able to annotate with metadata
         operationElement = cloneShallow(operationElement);

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

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

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

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

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

@@ -90,6 +90,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');