@speclynx/apidom-reference 3.1.0 → 3.2.1

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

@@ -129,16 +129,22 @@ class OpenAPI2DereferenceVisitor {
     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 OpenAPI2DereferenceVisitor {
       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 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;
         }
@@ -298,7 +304,6 @@ class OpenAPI2DereferenceVisitor {
         });
         directAncestors.delete(referencingElement);
       }
-      this.indirections.pop();
 
       /**
        * Creating a new version of referenced element to avoid modifying the original one.
@@ -319,6 +324,8 @@ class OpenAPI2DereferenceVisitor {
     } 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 PathItemElement(path) {
@@ -349,6 +356,7 @@ class OpenAPI2DereferenceVisitor {
       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);
@@ -399,7 +407,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;
         }
@@ -433,7 +440,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.
@@ -465,6 +471,8 @@ class OpenAPI2DereferenceVisitor {
     } catch (error) {
       const $ref = 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) {
@@ -492,6 +500,7 @@ class OpenAPI2DereferenceVisitor {
       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);
@@ -552,7 +561,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;
         }
@@ -586,7 +594,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.
@@ -607,6 +614,8 @@ class OpenAPI2DereferenceVisitor {
     } catch (error) {
       const $ref = 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();
     }
   }
 }

package/src/dereference/strategies/openapi-3-0/visitor.cjs

@@ -137,16 +137,22 @@ class OpenAPI3_0DereferenceVisitor {
     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,
@@ -214,6 +220,7 @@ class OpenAPI3_0DereferenceVisitor {
       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);
@@ -274,7 +281,6 @@ class OpenAPI3_0DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -308,7 +314,6 @@ class OpenAPI3_0DereferenceVisitor {
         // 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.
@@ -329,6 +334,8 @@ class OpenAPI3_0DereferenceVisitor {
     } 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) {
@@ -359,6 +366,7 @@ class OpenAPI3_0DereferenceVisitor {
       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);
@@ -409,7 +417,6 @@ class OpenAPI3_0DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -443,7 +450,6 @@ class OpenAPI3_0DereferenceVisitor {
         // 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.
@@ -474,6 +480,8 @@ class OpenAPI3_0DereferenceVisitor {
     } 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 LinkElement(path) {

package/src/dereference/strategies/openapi-3-0/visitor.mjs

@@ -130,16 +130,22 @@ class OpenAPI3_0DereferenceVisitor {
     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,
@@ -207,6 +213,7 @@ class OpenAPI3_0DereferenceVisitor {
       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);
@@ -267,7 +274,6 @@ class OpenAPI3_0DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -301,7 +307,6 @@ class OpenAPI3_0DereferenceVisitor {
         // 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.
@@ -322,6 +327,8 @@ class OpenAPI3_0DereferenceVisitor {
     } 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 PathItemElement(path) {
@@ -352,6 +359,7 @@ class OpenAPI3_0DereferenceVisitor {
       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);
@@ -402,7 +410,6 @@ class OpenAPI3_0DereferenceVisitor {
           });
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
-          this.indirections.pop();
           path.replaceWith(replacement);
           return;
         }
@@ -436,7 +443,6 @@ class OpenAPI3_0DereferenceVisitor {
         // 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.
@@ -467,6 +473,8 @@ class OpenAPI3_0DereferenceVisitor {
     } catch (error) {
       const $ref = 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 LinkElement(path) {

package/src/dereference/strategies/openapi-3-1/visitor.cjs

@@ -142,16 +142,22 @@ class OpenAPI3_1DereferenceVisitor {
     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,

package/src/dereference/strategies/openapi-3-1/visitor.mjs

@@ -135,16 +135,22 @@ class OpenAPI3_1DereferenceVisitor {
     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,