@speclynx/apidom-reference 3.2.0 → 3.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -254,29 +254,29 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "3.2.0",
-    "@speclynx/apidom-datamodel": "3.2.0",
-    "@speclynx/apidom-error": "3.2.0",
-    "@speclynx/apidom-json-pointer": "3.2.0",
-    "@speclynx/apidom-ns-arazzo-1": "3.2.0",
-    "@speclynx/apidom-ns-asyncapi-2": "3.2.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "3.2.0",
-    "@speclynx/apidom-ns-openapi-2": "3.2.0",
-    "@speclynx/apidom-ns-openapi-3-0": "3.2.0",
-    "@speclynx/apidom-ns-openapi-3-1": "3.2.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "3.2.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "3.2.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "3.2.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "3.2.0",
-    "@speclynx/apidom-parser-adapter-json": "3.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "3.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "3.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "3.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "3.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "3.2.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "3.2.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "3.2.0",
-    "@speclynx/apidom-traverse": "3.2.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",
@@ -298,5 +298,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "eeb2f01cd34fb0a95617f02bc1b6683aefc028f2"
+  "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,

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,

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,

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,

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,

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,

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,

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,

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,