@speclynx/apidom-reference 3.1.0 → 3.2.1

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
+  "keywords": [
+    "apidom",
+    "api",
+    "$ref",
+    "dereference",
+    "reference",
+    "resolve",
+    "resolver",
+    "bundle",
+    "openapi",
+    "swagger",
+    "oas",
+    "asyncapi",
+    "arazzo",
+    "json-schema",
+    "json",
+    "yaml",
+    "spec",
+    "specification",
+    "parse",
+    "typescript",
+    "javascript"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org",
@@ -231,29 +254,29 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "3.1.0",
-    "@speclynx/apidom-datamodel": "3.1.0",
-    "@speclynx/apidom-error": "3.1.0",
-    "@speclynx/apidom-json-pointer": "3.1.0",
-    "@speclynx/apidom-ns-arazzo-1": "3.1.0",
-    "@speclynx/apidom-ns-asyncapi-2": "3.1.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "3.1.0",
-    "@speclynx/apidom-ns-openapi-2": "3.1.0",
-    "@speclynx/apidom-ns-openapi-3-0": "3.1.0",
-    "@speclynx/apidom-ns-openapi-3-1": "3.1.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "3.1.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "3.1.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "3.1.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "3.1.0",
-    "@speclynx/apidom-parser-adapter-json": "3.1.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "3.1.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "3.1.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "3.1.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "3.1.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "3.1.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "3.1.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "3.1.0",
-    "@speclynx/apidom-traverse": "3.1.0",
+    "@speclynx/apidom-core": "3.2.1",
+    "@speclynx/apidom-datamodel": "3.2.1",
+    "@speclynx/apidom-error": "3.2.1",
+    "@speclynx/apidom-json-pointer": "3.2.1",
+    "@speclynx/apidom-ns-arazzo-1": "3.2.1",
+    "@speclynx/apidom-ns-asyncapi-2": "3.2.1",
+    "@speclynx/apidom-ns-json-schema-2020-12": "3.2.1",
+    "@speclynx/apidom-ns-openapi-2": "3.2.1",
+    "@speclynx/apidom-ns-openapi-3-0": "3.2.1",
+    "@speclynx/apidom-ns-openapi-3-1": "3.2.1",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "3.2.1",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "3.2.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "3.2.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "3.2.1",
+    "@speclynx/apidom-parser-adapter-json": "3.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "3.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "3.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "3.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "3.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "3.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "3.2.1",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "3.2.1",
+    "@speclynx/apidom-traverse": "3.2.1",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
     "axios": "^1.13.5",
     "picomatch": "^4.0.3",
@@ -275,5 +298,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "c0807dd0b7770eaaf594bd0013be65e2c28c504a"
+  "gitHead": "83a1e97089ef29134e41ff7cacd351973114ea5b"
 }

package/src/dereference/strategies/apidom/visitor.cjs

@@ -106,15 +106,22 @@ class ApiDOMDereferenceVisitor {
     const isEntryDocument = url.stripHash(this.reference.refSet?.rootRef?.uri ?? '') === this.reference.uri;
     const uri = this.reference.uri;
     const type = referencingElement.element;
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
     let location;
-    (0, _apidomTraverse.traverse)(this.reference.value.result, {
-      enter(p) {
-        if (p.node === referencingElement) {
-          location = p.formatPath();
-          p.stop();
+    const root = this.reference.value.result;
+    if ((0, _apidomDatamodel.isElement)(root)) {
+      (0, _apidomTraverse.traverse)(root, {
+        enter(p) {
+          if (p.node === referencingElement) {
+            location = p.formatPath();
+            p.stop();
+          }
         }
-      }
-    });
+      });
+    }
     location ??= visitorPath.formatPath();
     const codeFrame = (0, _apidomCore.toYAML)(referencingElement);
     const hop = {

package/src/dereference/strategies/apidom/visitor.mjs

@@ -99,15 +99,22 @@ class ApiDOMDereferenceVisitor {
     const isEntryDocument = url.stripHash(this.reference.refSet?.rootRef?.uri ?? '') === this.reference.uri;
     const uri = this.reference.uri;
     const type = referencingElement.element;
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
     let location;
-    traverse(this.reference.value.result, {
-      enter(p) {
-        if (p.node === referencingElement) {
-          location = p.formatPath();
-          p.stop();
+    const root = this.reference.value.result;
+    if (isElement(root)) {
+      traverse(root, {
+        enter(p) {
+          if (p.node === referencingElement) {
+            location = p.formatPath();
+            p.stop();
+          }
         }
-      }
-    });
+      });
+    }
     location ??= visitorPath.formatPath();
     const codeFrame = toYAML(referencingElement);
     const hop = {

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

@@ -140,16 +140,22 @@ class Arazzo1DereferenceVisitor {
     const type = referencingElement.element;
     const codeFrame = (0, _apidomCore.toYAML)(referencingElement);
 
-    // find element location: tree search for entry documents, visitor path for external
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
     let location;
-    (0, _apidomTraverse.traverse)(this.reference.value.result, {
-      enter: p => {
-        if (p.node === referencingElement) {
-          location = p.formatPath();
-          p.stop();
+    const root = this.reference.value.result;
+    if ((0, _apidomDatamodel.isElement)(root)) {
+      (0, _apidomTraverse.traverse)(root, {
+        enter(p) {
+          if (p.node === referencingElement) {
+            location = p.formatPath();
+            p.stop();
+          }
         }
-      }
-    });
+      });
+    }
     location ??= visitorPath.formatPath();
     const hop = {
       uri,
@@ -274,6 +280,7 @@ class Arazzo1DereferenceVisitor {
       path.skip();
       return;
     }
+    const indirectionsSize = this.indirections.length;
     try {
       // compute baseURI using rules around $id and $ref keywords
       let reference = await this.toReference(url.unsanitize(this.reference.uri));
@@ -418,7 +425,6 @@ class Arazzo1DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['arazzo-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -451,7 +457,6 @@ class Arazzo1DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       // Boolean JSON Schemas
       if ((0, _apidomNsArazzo.isBooleanJSONSchemaElement)(referencedElement)) {
@@ -494,6 +499,8 @@ class Arazzo1DereferenceVisitor {
     } catch (error) {
       const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
       this.handleError(`Error while dereferencing Schema Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
 }

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

@@ -133,16 +133,22 @@ class Arazzo1DereferenceVisitor {
     const type = referencingElement.element;
     const codeFrame = toYAML(referencingElement);
 
-    // find element location: tree search for entry documents, visitor path for external
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
     let location;
-    traverse(this.reference.value.result, {
-      enter: p => {
-        if (p.node === referencingElement) {
-          location = p.formatPath();
-          p.stop();
+    const root = this.reference.value.result;
+    if (isElement(root)) {
+      traverse(root, {
+        enter(p) {
+          if (p.node === referencingElement) {
+            location = p.formatPath();
+            p.stop();
+          }
         }
-      }
-    });
+      });
+    }
     location ??= visitorPath.formatPath();
     const hop = {
       uri,
@@ -267,6 +273,7 @@ class Arazzo1DereferenceVisitor {
       path.skip();
       return;
     }
+    const indirectionsSize = this.indirections.length;
     try {
       // compute baseURI using rules around $id and $ref keywords
       let reference = await this.toReference(url.unsanitize(this.reference.uri));
@@ -411,7 +418,6 @@ class Arazzo1DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['arazzo-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -444,7 +450,6 @@ class Arazzo1DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       // Boolean JSON Schemas
       if (isBooleanJSONSchemaElement(referencedElement)) {
@@ -487,6 +492,8 @@ class Arazzo1DereferenceVisitor {
     } catch (error) {
       const $ref = toValue(referencingElement.$ref);
       this.handleError(`Error while dereferencing Schema Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
 }

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

@@ -136,16 +136,22 @@ class AsyncAPI2DereferenceVisitor {
     const type = referencingElement.element;
     const codeFrame = (0, _apidomCore.toYAML)(referencingElement);
 
-    // find element location: tree search for entry documents, visitor path for external
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
     let location;
-    (0, _apidomTraverse.traverse)(this.reference.value.result, {
-      enter: p => {
-        if (p.node === referencingElement || this.refractCache.get(p.node) === referencingElement) {
-          location = p.formatPath();
-          p.stop();
+    const root = this.reference.value.result;
+    if ((0, _apidomDatamodel.isElement)(root)) {
+      (0, _apidomTraverse.traverse)(root, {
+        enter: p => {
+          if (p.node === referencingElement || this.refractCache.get(p.node) === referencingElement) {
+            location = p.formatPath();
+            p.stop();
+          }
         }
-      }
-    });
+      });
+    }
     location ??= visitorPath.formatPath();
     const hop = {
       uri,
@@ -213,6 +219,7 @@ class AsyncAPI2DereferenceVisitor {
       return;
     }
     const $refBaseURI = url.resolve(retrievalURI, (0, _apidomCore.toValue)(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
     try {
       const reference = await this.toReference((0, _apidomCore.toValue)(referencingElement.$ref));
       this.indirections.push(referencingElement);
@@ -273,7 +280,6 @@ class AsyncAPI2DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -307,7 +313,6 @@ class AsyncAPI2DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       // Boolean JSON Schemas
       if ((0, _apidomNsAsyncapi.isBooleanJSONSchemaElement)(referencedElement)) {
@@ -342,6 +347,8 @@ class AsyncAPI2DereferenceVisitor {
     } 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);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
   async ChannelItemElement(path) {
@@ -372,6 +379,7 @@ class AsyncAPI2DereferenceVisitor {
       return;
     }
     const $refBaseURI = url.resolve(retrievalURI, (0, _apidomCore.toValue)(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
     try {
       const reference = await this.toReference((0, _apidomCore.toValue)(referencingElement.$ref));
       this.indirections.push(referencingElement);
@@ -422,7 +430,6 @@ class AsyncAPI2DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -456,7 +463,6 @@ class AsyncAPI2DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       /**
        * Creating a new version of Channel Item by merging fields from referenced Channel Item with referencing one.
@@ -487,6 +493,8 @@ class AsyncAPI2DereferenceVisitor {
     } catch (error) {
       const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
       this.handleError(`Error while dereferencing Channel Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
 }

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

@@ -129,16 +129,22 @@ class AsyncAPI2DereferenceVisitor {
     const type = referencingElement.element;
     const codeFrame = toYAML(referencingElement);
 
-    // find element location: tree search for entry documents, visitor path for external
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
     let location;
-    traverse(this.reference.value.result, {
-      enter: p => {
-        if (p.node === referencingElement || this.refractCache.get(p.node) === referencingElement) {
-          location = p.formatPath();
-          p.stop();
+    const root = this.reference.value.result;
+    if (isElement(root)) {
+      traverse(root, {
+        enter: p => {
+          if (p.node === referencingElement || this.refractCache.get(p.node) === referencingElement) {
+            location = p.formatPath();
+            p.stop();
+          }
         }
-      }
-    });
+      });
+    }
     location ??= visitorPath.formatPath();
     const hop = {
       uri,
@@ -206,6 +212,7 @@ class AsyncAPI2DereferenceVisitor {
       return;
     }
     const $refBaseURI = url.resolve(retrievalURI, toValue(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
     try {
       const reference = await this.toReference(toValue(referencingElement.$ref));
       this.indirections.push(referencingElement);
@@ -266,7 +273,6 @@ class AsyncAPI2DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -300,7 +306,6 @@ class AsyncAPI2DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       // Boolean JSON Schemas
       if (isBooleanJSONSchemaElement(referencedElement)) {
@@ -335,6 +340,8 @@ class AsyncAPI2DereferenceVisitor {
     } 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);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
   async ChannelItemElement(path) {
@@ -365,6 +372,7 @@ class AsyncAPI2DereferenceVisitor {
       return;
     }
     const $refBaseURI = url.resolve(retrievalURI, toValue(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
     try {
       const reference = await this.toReference(toValue(referencingElement.$ref));
       this.indirections.push(referencingElement);
@@ -415,7 +423,6 @@ class AsyncAPI2DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -449,7 +456,6 @@ class AsyncAPI2DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       /**
        * Creating a new version of Channel Item by merging fields from referenced Channel Item with referencing one.
@@ -480,6 +486,8 @@ class AsyncAPI2DereferenceVisitor {
     } catch (error) {
       const $ref = toValue(referencingElement.$ref);
       this.handleError(`Error while dereferencing Channel Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
 }

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

@@ -136,16 +136,22 @@ class OpenAPI2DereferenceVisitor {
     const type = referencingElement.element;
     const codeFrame = (0, _apidomCore.toYAML)(referencingElement);
 
-    // find element location: tree search for entry documents, visitor path for external
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
     let location;
-    (0, _apidomTraverse.traverse)(this.reference.value.result, {
-      enter: p => {
-        if (p.node === referencingElement || this.refractCache.get(p.node) === referencingElement) {
-          location = p.formatPath();
-          p.stop();
+    const root = this.reference.value.result;
+    if ((0, _apidomDatamodel.isElement)(root)) {
+      (0, _apidomTraverse.traverse)(root, {
+        enter: p => {
+          if (p.node === referencingElement || this.refractCache.get(p.node) === referencingElement) {
+            location = p.formatPath();
+            p.stop();
+          }
         }
-      }
-    });
+      });
+    }
     location ??= visitorPath.formatPath();
     const hop = {
       uri,
@@ -213,6 +219,7 @@ class OpenAPI2DereferenceVisitor {
       return;
     }
     const $refBaseURI = url.resolve(retrievalURI, (0, _apidomCore.toValue)(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
     try {
       const reference = await this.toReference((0, _apidomCore.toValue)(referencingElement.$ref));
       this.indirections.push(referencingElement);
@@ -273,7 +280,6 @@ class OpenAPI2DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -305,7 +311,6 @@ class OpenAPI2DereferenceVisitor {
         });
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       /**
        * Creating a new version of referenced element to avoid modifying the original one.
@@ -326,6 +331,8 @@ class OpenAPI2DereferenceVisitor {
     } 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);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
   async PathItemElement(path) {
@@ -356,6 +363,7 @@ class OpenAPI2DereferenceVisitor {
       return;
     }
     const $refBaseURI = url.resolve(retrievalURI, (0, _apidomCore.toValue)(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
     try {
       const reference = await this.toReference((0, _apidomCore.toValue)(referencingElement.$ref));
       this.indirections.push(referencingElement);
@@ -406,7 +414,6 @@ class OpenAPI2DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -440,7 +447,6 @@ class OpenAPI2DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       /**
        * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
@@ -472,6 +478,8 @@ class OpenAPI2DereferenceVisitor {
     } catch (error) {
       const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
       this.handleError(`Error while dereferencing Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
   async JSONReferenceElement(path) {
@@ -499,6 +507,7 @@ class OpenAPI2DereferenceVisitor {
       return;
     }
     const $refBaseURI = url.resolve(retrievalURI, (0, _apidomCore.toValue)(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
     try {
       const reference = await this.toReference((0, _apidomCore.toValue)(referencingElement.$ref));
       this.indirections.push(referencingElement);
@@ -559,7 +568,6 @@ class OpenAPI2DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -593,7 +601,6 @@ class OpenAPI2DereferenceVisitor {
         // remove referencing reference from ancestors lineage
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       /**
        * Creating a new version of referenced element to avoid modifying the original one.
@@ -614,6 +621,8 @@ class OpenAPI2DereferenceVisitor {
     } catch (error) {
       const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
       this.handleError(`Error while dereferencing JSON Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
   }
 }