@speclynx/apidom-reference 4.7.0 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -279,32 +279,32 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "4.7.0",
-    "@speclynx/apidom-datamodel": "4.7.0",
-    "@speclynx/apidom-error": "4.7.0",
-    "@speclynx/apidom-json-pointer": "4.7.0",
-    "@speclynx/apidom-ns-arazzo-1": "4.7.0",
-    "@speclynx/apidom-ns-asyncapi-2": "4.7.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "4.7.0",
-    "@speclynx/apidom-ns-openapi-2": "4.7.0",
-    "@speclynx/apidom-ns-openapi-3-0": "4.7.0",
-    "@speclynx/apidom-ns-openapi-3-1": "4.7.0",
-    "@speclynx/apidom-ns-overlay-1": "4.7.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.7.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.7.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.7.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.7.0",
-    "@speclynx/apidom-parser-adapter-json": "4.7.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.7.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.7.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.7.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.7.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.7.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.7.0",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "4.7.0",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "4.7.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.7.0",
-    "@speclynx/apidom-traverse": "4.7.0",
+    "@speclynx/apidom-core": "4.8.0",
+    "@speclynx/apidom-datamodel": "4.8.0",
+    "@speclynx/apidom-error": "4.8.0",
+    "@speclynx/apidom-json-pointer": "4.8.0",
+    "@speclynx/apidom-ns-arazzo-1": "4.8.0",
+    "@speclynx/apidom-ns-asyncapi-2": "4.8.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "4.8.0",
+    "@speclynx/apidom-ns-openapi-2": "4.8.0",
+    "@speclynx/apidom-ns-openapi-3-0": "4.8.0",
+    "@speclynx/apidom-ns-openapi-3-1": "4.8.0",
+    "@speclynx/apidom-ns-overlay-1": "4.8.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.8.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.8.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.8.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.8.0",
+    "@speclynx/apidom-parser-adapter-json": "4.8.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.8.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.8.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.8.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.8.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.8.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.8.0",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "4.8.0",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "4.8.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.8.0",
+    "@speclynx/apidom-traverse": "4.8.0",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
     "axios": "^1.15.0",
     "picomatch": "^4.0.4",
@@ -326,5 +326,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "5afe50e432d90185f514e91bb35319aa4e23ba7b"
+  "gitHead": "ef77101edfc6567d9b265bc30708bf2c65fd1d15"
 }

package/src/dereference/strategies/arazzo-1/index.cjs

@@ -68,12 +68,16 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor.default({
       reference,
       options
     });
     const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**

package/src/dereference/strategies/arazzo-1/index.mjs

@@ -56,12 +56,16 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new Arazzo1DereferenceVisitor({
       reference,
       options
     });
     const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**

package/src/dereference/strategies/arazzo-1/visitor.cjs

@@ -36,6 +36,7 @@ class Arazzo1DereferenceVisitor {
   indirections;
   reference;
   options;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -47,12 +48,14 @@ class Arazzo1DereferenceVisitor {
     reference,
     options,
     indirections = [],
-    ancestors = new _util3.AncestorLineage()
+    ancestors = new _util3.AncestorLineage(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util3.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -266,6 +269,7 @@ class Arazzo1DereferenceVisitor {
      * Transclude referencing element with merged referenced element.
      */
     path.replaceWith(mergedElement);
+    path.skip();
   }
   async JSONSchemaElement(path) {
     const referencingElement = path.node;
@@ -426,6 +430,7 @@ class Arazzo1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['arazzo-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -441,17 +446,23 @@ class Arazzo1DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsArazzo.isJSONSchemaElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsArazzo.isJSONSchemaElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new Arazzo1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -469,6 +480,7 @@ class Arazzo1DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 

package/src/dereference/strategies/arazzo-1/visitor.mjs

@@ -29,6 +29,7 @@ class Arazzo1DereferenceVisitor {
   indirections;
   reference;
   options;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -40,12 +41,14 @@ class Arazzo1DereferenceVisitor {
     reference,
     options,
     indirections = [],
-    ancestors = new AncestorLineage()
+    ancestors = new AncestorLineage(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -259,6 +262,7 @@ class Arazzo1DereferenceVisitor {
      * Transclude referencing element with merged referenced element.
      */
     path.replaceWith(mergedElement);
+    path.skip();
   }
   async JSONSchemaElement(path) {
     const referencingElement = path.node;
@@ -419,6 +423,7 @@ class Arazzo1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['arazzo-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -434,17 +439,23 @@ class Arazzo1DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isJSONSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || isJSONSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new Arazzo1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await traverseAsync(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -462,6 +473,7 @@ class Arazzo1DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 

package/src/dereference/strategies/asyncapi-2/index.cjs

@@ -62,12 +62,16 @@ class AsyncAPI2DereferenceStrategy extends _DereferenceStrategy.default {
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor.default({
       reference,
       options
     });
     const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**

package/src/dereference/strategies/asyncapi-2/index.mjs

@@ -55,12 +55,16 @@ class AsyncAPI2DereferenceStrategy extends DereferenceStrategy {
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new AsyncAPI2DereferenceVisitor({
       reference,
       options
     });
     const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**

package/src/dereference/strategies/asyncapi-2/visitor.cjs

@@ -30,6 +30,7 @@ class AsyncAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -42,13 +43,15 @@ class AsyncAPI2DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new _util.AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util.AncestorLineage(...ancestors);
     this.refractCache = refractCache;
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -281,6 +284,7 @@ class AsyncAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -296,7 +300,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsAsyncapi.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsAsyncapi.isReferenceElement)(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new AsyncAPI2DereferenceVisitor({
@@ -304,10 +312,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -325,6 +335,7 @@ class AsyncAPI2DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -344,6 +355,7 @@ class AsyncAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -446,7 +458,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsAsyncapi.isChannelItemElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsAsyncapi.isChannelItemElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new AsyncAPI2DereferenceVisitor({
@@ -454,10 +470,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage

package/src/dereference/strategies/asyncapi-2/visitor.mjs

@@ -23,6 +23,7 @@ class AsyncAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -35,13 +36,15 @@ class AsyncAPI2DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new AncestorLineage(...ancestors);
     this.refractCache = refractCache;
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -274,6 +277,7 @@ class AsyncAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -289,7 +293,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isReferenceElement(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || isReferenceElement(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new AsyncAPI2DereferenceVisitor({
@@ -297,10 +305,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await traverseAsync(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -318,6 +328,7 @@ class AsyncAPI2DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -337,6 +348,7 @@ class AsyncAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = toValue(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -439,7 +451,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isChannelItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || isChannelItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new AsyncAPI2DereferenceVisitor({
@@ -447,10 +463,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await traverseAsync(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage

package/src/dereference/strategies/openapi-2/index.cjs

@@ -62,12 +62,16 @@ class OpenAPI2DereferenceStrategy extends _DereferenceStrategy.default {
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor.default({
       reference: reference,
       options
     });
     const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**

package/src/dereference/strategies/openapi-2/index.mjs

@@ -55,12 +55,16 @@ class OpenAPI2DereferenceStrategy extends DereferenceStrategy {
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new OpenAPI2DereferenceVisitor({
       reference: reference,
       options
     });
     const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**