@speclynx/apidom-reference 4.7.0 → 4.8.0

package/dist/apidom-reference.browser.js

@@ -997,12 +997,16 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMPORT
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_ts__WEBPACK_IMPORTED_MODULE_9__["default"]({
       reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -1429,6 +1433,7 @@ class Arazzo1DereferenceVisitor {
   indirections;
   reference;
   options;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -1440,12 +1445,14 @@ class Arazzo1DereferenceVisitor {
     reference,
     options,
     indirections = [],
-    ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_26__.AncestorLineage()
+    ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_26__.AncestorLineage(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_26__.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -1659,6 +1666,7 @@ class Arazzo1DereferenceVisitor {
      * Transclude referencing element with merged referenced element.
      */
     path.replaceWith(mergedElement);
+    path.skip();
   }
   async JSONSchemaElement(path) {
     const referencingElement = path.node;
@@ -1819,6 +1827,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;
         }
       }
@@ -1834,17 +1843,23 @@ class Arazzo1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_22__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_11__.isJSONSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_11__.isJSONSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.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,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -1862,6 +1877,7 @@ class Arazzo1DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -1977,12 +1993,16 @@ class AsyncAPI2DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMPO
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_ts__WEBPACK_IMPORTED_MODULE_7__["default"]({
       reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -2067,6 +2087,7 @@ class AsyncAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -2079,13 +2100,15 @@ class AsyncAPI2DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_17__.AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_17__.AncestorLineage(...ancestors);
     this.refractCache = refractCache;
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -2318,6 +2341,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;
         }
       }
@@ -2333,7 +2357,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_18__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.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({
@@ -2341,10 +2369,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -2362,6 +2392,7 @@ class AsyncAPI2DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -2381,6 +2412,7 @@ class AsyncAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -2483,7 +2515,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_18__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.isChannelItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.isChannelItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.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({
@@ -2491,10 +2527,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -2615,12 +2653,16 @@ class OpenAPI2DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMPOR
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_ts__WEBPACK_IMPORTED_MODULE_7__["default"]({
       reference: reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -2709,6 +2751,7 @@ class OpenAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -2721,13 +2764,15 @@ class OpenAPI2DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_19__.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_ts__WEBPACK_IMPORTED_MODULE_19__.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -2960,6 +3005,7 @@ class OpenAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -2975,7 +3021,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_20__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.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({
@@ -2983,10 +3033,12 @@ class OpenAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -3007,6 +3059,7 @@ class OpenAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -3094,6 +3147,7 @@ class OpenAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -3109,7 +3163,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_20__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.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({
@@ -3117,10 +3175,12 @@ class OpenAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -3248,6 +3308,7 @@ class OpenAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -3263,7 +3324,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_20__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_11__.isJSONReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_11__.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({
@@ -3271,10 +3336,12 @@ class OpenAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -3297,6 +3364,7 @@ class OpenAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing JSON Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -3387,12 +3455,16 @@ class OpenAPI3_0DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMP
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_ts__WEBPACK_IMPORTED_MODULE_7__["default"]({
       reference: reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -3478,6 +3550,7 @@ class OpenAPI3_0DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -3490,13 +3563,15 @@ class OpenAPI3_0DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_20__.AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_20__.AncestorLineage(...ancestors);
     this.refractCache = refractCache;
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -3729,6 +3804,7 @@ class OpenAPI3_0DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -3744,7 +3820,11 @@ class OpenAPI3_0DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_17__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.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 OpenAPI3_0DereferenceVisitor({
@@ -3752,10 +3832,12 @@ class OpenAPI3_0DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -3778,6 +3860,7 @@ class OpenAPI3_0DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_5__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -3865,6 +3948,7 @@ class OpenAPI3_0DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -3880,7 +3964,11 @@ class OpenAPI3_0DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_17__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.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 OpenAPI3_0DereferenceVisitor({
@@ -3888,10 +3976,12 @@ class OpenAPI3_0DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -4152,12 +4242,16 @@ class OpenAPI3_1DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMP
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_ts__WEBPACK_IMPORTED_MODULE_8__["default"]({
       reference: reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_2__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -4483,6 +4577,7 @@ class OpenAPI3_1DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -4495,13 +4590,15 @@ class OpenAPI3_1DereferenceVisitor {
     options,
     indirections = [],
     refractCache = new WeakMap(),
-    ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_28__.AncestorLineage()
+    ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_28__.AncestorLineage(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.refractCache = refractCache;
     this.ancestors = new _util_ts__WEBPACK_IMPORTED_MODULE_28__.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -4734,6 +4831,7 @@ class OpenAPI3_1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -4749,17 +4847,22 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_23__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isReferenceElement)(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -4886,6 +4989,7 @@ class OpenAPI3_1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -4901,17 +5005,22 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_23__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -5242,6 +5351,7 @@ class OpenAPI3_1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -5257,17 +5367,22 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_ts__WEBPACK_IMPORTED_MODULE_23__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -5283,6 +5398,7 @@ class OpenAPI3_1DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -99222,10 +99338,12 @@ function* traverseGenerator(root, visitor, options) {
     nodePredicate,
     nodeCloneFn,
     detectCycles,
+    skipVisited,
     mutable,
     mutationFn
   } = options;
   const keyMapIsFunction = typeof keyMap === 'function';
+  const visitedNodes = skipVisited ? new WeakSet() : null;
   let stack;
   let inArray = Array.isArray(root);
   let keys = [root];
@@ -99311,6 +99429,14 @@ function* traverseGenerator(root, visitor, options) {
         continue;
       }
 
+      // Skip already-visited nodes (handles DAG structures from cloneShallow)
+      if (skipVisited && !isLeaving) {
+        if (visitedNodes.has(node)) {
+          continue;
+        }
+        visitedNodes.add(node);
+      }
+
       // Always create Path for the current node (needed for parentPath chain)
       currentPath = new _Path_mjs__WEBPACK_IMPORTED_MODULE_2__.Path(node, parent, parentPath, key, inArray);
       const visitFn = (0,_visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.getVisitFn)(visitor, nodeTypeGetter(node), isLeaving);
@@ -99331,11 +99457,6 @@ function* traverseGenerator(root, visitor, options) {
         if (currentPath.shouldStop) {
           break;
         }
-        if (currentPath.shouldSkip) {
-          if (!isLeaving) {
-            continue;
-          }
-        }
         if (currentPath.removed) {
           edits.push([key, null]);
           if (!isLeaving) {
@@ -99345,12 +99466,19 @@ function* traverseGenerator(root, visitor, options) {
           const replacement = currentPath._getReplacementNode();
           edits.push([key, replacement]);
           if (!isLeaving) {
+            if (currentPath.shouldSkip) {
+              continue;
+            }
             if (nodePredicate(replacement)) {
               node = replacement;
             } else {
               continue;
             }
           }
+        } else if (currentPath.shouldSkip) {
+          if (!isLeaving) {
+            continue;
+          }
         } else if (result !== undefined) {
           // Support return value replacement for backwards compatibility
           edits.push([key, result]);
@@ -99452,6 +99580,7 @@ const traverse = (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.cloneNode,
     detectCycles: options.detectCycles ?? true,
+    skipVisited: options.skipVisited ?? false,
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.mutateNode
   };
@@ -99483,6 +99612,7 @@ const traverseAsync = async (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.cloneNode,
     detectCycles: options.detectCycles ?? true,
+    skipVisited: options.skipVisited ?? false,
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.mutateNode
   };