@speclynx/apidom-reference 4.7.1 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "4.7.1",
+  "version": "4.9.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.1",
-    "@speclynx/apidom-datamodel": "4.7.1",
-    "@speclynx/apidom-error": "4.7.1",
-    "@speclynx/apidom-json-pointer": "4.7.1",
-    "@speclynx/apidom-ns-arazzo-1": "4.7.1",
-    "@speclynx/apidom-ns-asyncapi-2": "4.7.1",
-    "@speclynx/apidom-ns-json-schema-2020-12": "4.7.1",
-    "@speclynx/apidom-ns-openapi-2": "4.7.1",
-    "@speclynx/apidom-ns-openapi-3-0": "4.7.1",
-    "@speclynx/apidom-ns-openapi-3-1": "4.7.1",
-    "@speclynx/apidom-ns-overlay-1": "4.7.1",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.7.1",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.7.1",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.7.1",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.7.1",
-    "@speclynx/apidom-parser-adapter-json": "4.7.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.7.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.7.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.7.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.7.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.7.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.7.1",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "4.7.1",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "4.7.1",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.7.1",
-    "@speclynx/apidom-traverse": "4.7.1",
+    "@speclynx/apidom-core": "4.9.0",
+    "@speclynx/apidom-datamodel": "4.9.0",
+    "@speclynx/apidom-error": "4.9.0",
+    "@speclynx/apidom-json-pointer": "4.9.0",
+    "@speclynx/apidom-ns-arazzo-1": "4.9.0",
+    "@speclynx/apidom-ns-asyncapi-2": "4.9.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "4.9.0",
+    "@speclynx/apidom-ns-openapi-2": "4.9.0",
+    "@speclynx/apidom-ns-openapi-3-0": "4.9.0",
+    "@speclynx/apidom-ns-openapi-3-1": "4.9.0",
+    "@speclynx/apidom-ns-overlay-1": "4.9.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.9.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.9.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.9.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.9.0",
+    "@speclynx/apidom-parser-adapter-json": "4.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.9.0",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "4.9.0",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "4.9.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.9.0",
+    "@speclynx/apidom-traverse": "4.9.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": "ee7c6fc79ed7af3550290c8fb76557967433167e"
+  "gitHead": "918b3a7102bc7a8991b0fe1b92aeeb0aaeb2b30f"
 }

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();
@@ -443,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

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();
@@ -436,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

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();
@@ -297,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({
@@ -305,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
@@ -449,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({
@@ -457,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();
@@ -290,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({
@@ -298,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
@@ -442,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({
@@ -450,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
+      })
     });
 
     /**

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

@@ -30,6 +30,7 @@ class OpenAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -42,13 +43,15 @@ class OpenAPI2DereferenceVisitor {
     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.refractCache = refractCache;
     this.ancestors = new _util.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -297,7 +300,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.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 OpenAPI2DereferenceVisitor({
@@ -305,10 +312,12 @@ class OpenAPI2DereferenceVisitor {
           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
         });
         directAncestors.delete(referencingElement);
       }
@@ -433,7 +442,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isPathItemElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isPathItemElement)(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 OpenAPI2DereferenceVisitor({
@@ -441,10 +454,12 @@ class OpenAPI2DereferenceVisitor {
           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
@@ -588,7 +603,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isJSONReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isJSONReferenceElement)(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 OpenAPI2DereferenceVisitor({
@@ -596,10 +615,12 @@ class OpenAPI2DereferenceVisitor {
           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/openapi-2/visitor.mjs

@@ -23,6 +23,7 @@ class OpenAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -35,13 +36,15 @@ class OpenAPI2DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.refractCache = refractCache;
     this.ancestors = new AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -290,7 +293,11 @@ class OpenAPI2DereferenceVisitor {
        */
       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 OpenAPI2DereferenceVisitor({
@@ -298,10 +305,12 @@ class OpenAPI2DereferenceVisitor {
           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
         });
         directAncestors.delete(referencingElement);
       }
@@ -426,7 +435,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isPathItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || isPathItemElement(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 OpenAPI2DereferenceVisitor({
@@ -434,10 +447,12 @@ class OpenAPI2DereferenceVisitor {
           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
@@ -581,7 +596,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isJSONReferenceElement(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || isJSONReferenceElement(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 OpenAPI2DereferenceVisitor({
@@ -589,10 +608,12 @@ class OpenAPI2DereferenceVisitor {
           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