@speclynx/apidom-reference 4.0.1 → 4.0.3

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

@@ -0,0 +1,266 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomError = require("@speclynx/apidom-error");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _MaximumResolveDepthError = _interopRequireDefault(require("../../../errors/MaximumResolveDepthError.cjs"));
+var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _elementId = require("./selectors/element-id.cjs");
+/**
+ * The following rules apply:
+ *
+ * 1. When referencing an element in the local document, the id of the element MAY be used
+ * 2. When referencing remote elements, an absolute URL or relative URL MAY be used
+ * 3. When a URL fragment exists in the URL given, it references the element with the matching id in the given document. The URL fragment MAY need to be URL decoded before making a match.
+ * 4. When a URL fragment does not exist, the URL references the root element
+ * 5. When path is used, it references the given property of the referenced element
+ * 6. When path is used in an element that includes the data of the pointer (such as with ref), the referenced path MAY need to be converted to a refract structure in order to be valid
+ *
+ * WARNING: this implementation only supports referencing elements in the local document. Points 2-4 are not supported.
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ApiDOMDereferenceVisitor {
+  reference;
+  options;
+  constructor({
+    reference,
+    options
+  }) {
+    this.reference = reference;
+    this.options = options;
+  }
+  toBaseURI(uri) {
+    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+  }
+  async toReference(uri) {
+    // detect maximum depth of resolution
+    if (this.reference.depth >= this.options.resolve.maxDepth) {
+      throw new _MaximumResolveDepthError.default(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`, {
+        maxDepth: this.options.resolve.maxDepth,
+        uri: this.reference.uri
+      });
+    }
+    const baseURI = this.toBaseURI(uri);
+    const {
+      refSet
+    } = this.reference;
+
+    // we've already processed this Reference in past
+    if (refSet.has(baseURI)) {
+      return refSet.find((0, _ramda.propEq)(baseURI, 'uri'));
+    }
+    const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+
+    // register new mutable reference with a refSet
+    const mutableReference = new _Reference.default({
+      uri: baseURI,
+      value: (0, _apidomDatamodel.cloneDeep)(parseResult),
+      depth: this.reference.depth + 1
+    });
+    refSet.add(mutableReference);
+    if (this.options.dereference.immutable) {
+      // register new immutable reference with a refSet
+      const immutableReference = new _Reference.default({
+        uri: `immutable://${baseURI}`,
+        value: parseResult,
+        depth: this.reference.depth + 1
+      });
+      refSet.add(immutableReference);
+    }
+    return mutableReference;
+  }
+
+  /**
+   * Handles an error according to the continueOnError option.
+   *
+   * For new errors: wraps in UnresolvableReferenceError with structured context.
+   * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
+   *
+   * Inner/intermediate visitors always throw to let the trace accumulate.
+   * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+   */
+  handleError(message, error, referencingElement, refFieldName, refFieldValue, visitorPath) {
+    const {
+      continueOnError
+    } = this.options.dereference;
+    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;
+    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 = {
+      uri,
+      type,
+      refFieldName,
+      refFieldValue,
+      location,
+      codeFrame
+    };
+    let unresolvedError;
+    if (error instanceof _UnresolvableReferenceError.default) {
+      const refBaseURI = this.toBaseURI(refFieldValue);
+      const fragment = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(refFieldValue);
+      if (fragment) {
+        if (refBaseURI === error.uri && error.location) {
+          error.location = fragment + error.location;
+        }
+        for (const h of error.trace) {
+          if (h.uri === refBaseURI && h.location) h.location = fragment + h.location;
+        }
+      }
+      // @ts-ignore
+      error.trace = [hop, ...error.trace];
+      unresolvedError = error;
+    } else {
+      unresolvedError = new _UnresolvableReferenceError.default(message, {
+        cause: error,
+        type,
+        uri,
+        location,
+        codeFrame,
+        refFieldName,
+        refFieldValue,
+        trace: []
+      });
+    }
+    if (!isEntryDocument || continueOnError === false) throw unresolvedError;
+    if (typeof continueOnError === 'function') continueOnError(unresolvedError);
+  }
+  async RefElement(path) {
+    const refElement = path.node;
+    const {
+      parent,
+      key
+    } = path;
+    const ancestors = path.getAncestorNodes();
+    const refURI = (0, _apidomCore.toValue)(refElement);
+    const refNormalizedURI = refURI.includes('#') ? refURI : `#${refURI}`;
+    const retrievalURI = this.toBaseURI(refNormalizedURI);
+    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+    const isExternalReference = !isInternalReference;
+
+    // ignore resolving internal RefElements
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this ref element
+      path.skip();
+      return;
+    }
+    // ignore resolving external RefElements
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this ref element
+      path.skip();
+      return;
+    }
+    try {
+      const reference = await this.toReference(refNormalizedURI);
+      const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
+      const elementID = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(refBaseURI);
+      let referencedElement = (0, _elementId.evaluate)(elementID, reference.value.result);
+      if (!(0, _apidomDatamodel.isElement)(referencedElement)) {
+        throw new _apidomError.ApiDOMStructuredError(`Referenced element with id="${elementID}" was not found`, {
+          elementID
+        });
+      }
+      if (refElement === referencedElement) {
+        throw new _apidomError.ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference itself`, {
+          elementID
+        });
+      }
+      if ((0, _apidomDatamodel.isRefElement)(referencedElement)) {
+        throw new _apidomError.ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference another RefElement`, {
+          elementID
+        });
+      }
+      if (isExternalReference) {
+        // dive deep into the fragment
+        const visitor = new ApiDOMDereferenceVisitor({
+          reference,
+          options: this.options
+        });
+        referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
+          mutable: true
+        });
+      }
+
+      /**
+       * When path is used, it references the given property of the referenced element.
+       * Valid paths are: 'element', 'content', 'meta', 'attributes'.
+       */
+      const referencedElementPath = (0, _apidomCore.toValue)(refElement.path);
+      if (referencedElementPath !== 'element' && (0, _apidomDatamodel.isElement)(referencedElement)) {
+        referencedElement = (0, _apidomDatamodel.refract)(referencedElement[referencedElementPath]);
+      }
+
+      /**
+       * Transclusion of a Ref Element SHALL be defined in the if/else block below.
+       */
+      // ancestors[0] is the grandparent (nearest ancestor from getAncestorNodes())
+      const grandparent = ancestors[0];
+      if ((0, _apidomDatamodel.isObjectElement)(referencedElement) && (0, _apidomDatamodel.isObjectElement)(grandparent) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Object Element and references an Object Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if ((0, _apidomDatamodel.isArrayElement)(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Array Element and references an Array Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if ((0, _apidomDatamodel.isMemberElement)(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent.value = referencedElement;
+      } else if (Array.isArray(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent[key] = referencedElement;
+      }
+      if (!parent) {
+        path.replaceWith(referencedElement);
+      }
+    } catch (error) {
+      this.handleError(`Error while dereferencing Ref Element. Cannot resolve ref "${refURI}": ${error.message}`, error, refElement, null, refURI, path);
+    }
+  }
+}
+var _default = exports.default = ApiDOMDereferenceVisitor;

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

@@ -0,0 +1,259 @@
+import { propEq } from 'ramda';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+import { isElement, isMemberElement, isArrayElement, isObjectElement, isRefElement, refract, cloneDeep } from '@speclynx/apidom-datamodel';
+import { toValue, toYAML } from '@speclynx/apidom-core';
+import { traverse, traverseAsync } from '@speclynx/apidom-traverse';
+import { URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
+import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
+import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
+import * as url from "../../../util/url.mjs";
+import parse from "../../../parse/index.mjs";
+import Reference from "../../../Reference.mjs";
+import { evaluate } from "./selectors/element-id.mjs";
+/**
+ * The following rules apply:
+ *
+ * 1. When referencing an element in the local document, the id of the element MAY be used
+ * 2. When referencing remote elements, an absolute URL or relative URL MAY be used
+ * 3. When a URL fragment exists in the URL given, it references the element with the matching id in the given document. The URL fragment MAY need to be URL decoded before making a match.
+ * 4. When a URL fragment does not exist, the URL references the root element
+ * 5. When path is used, it references the given property of the referenced element
+ * 6. When path is used in an element that includes the data of the pointer (such as with ref), the referenced path MAY need to be converted to a refract structure in order to be valid
+ *
+ * WARNING: this implementation only supports referencing elements in the local document. Points 2-4 are not supported.
+ * @public
+ */
+/**
+ * @public
+ */
+class ApiDOMDereferenceVisitor {
+  reference;
+  options;
+  constructor({
+    reference,
+    options
+  }) {
+    this.reference = reference;
+    this.options = options;
+  }
+  toBaseURI(uri) {
+    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+  }
+  async toReference(uri) {
+    // detect maximum depth of resolution
+    if (this.reference.depth >= this.options.resolve.maxDepth) {
+      throw new MaximumResolveDepthError(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`, {
+        maxDepth: this.options.resolve.maxDepth,
+        uri: this.reference.uri
+      });
+    }
+    const baseURI = this.toBaseURI(uri);
+    const {
+      refSet
+    } = this.reference;
+
+    // we've already processed this Reference in past
+    if (refSet.has(baseURI)) {
+      return refSet.find(propEq(baseURI, 'uri'));
+    }
+    const parseResult = await parse(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+
+    // register new mutable reference with a refSet
+    const mutableReference = new Reference({
+      uri: baseURI,
+      value: cloneDeep(parseResult),
+      depth: this.reference.depth + 1
+    });
+    refSet.add(mutableReference);
+    if (this.options.dereference.immutable) {
+      // register new immutable reference with a refSet
+      const immutableReference = new Reference({
+        uri: `immutable://${baseURI}`,
+        value: parseResult,
+        depth: this.reference.depth + 1
+      });
+      refSet.add(immutableReference);
+    }
+    return mutableReference;
+  }
+
+  /**
+   * Handles an error according to the continueOnError option.
+   *
+   * For new errors: wraps in UnresolvableReferenceError with structured context.
+   * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
+   *
+   * Inner/intermediate visitors always throw to let the trace accumulate.
+   * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+   */
+  handleError(message, error, referencingElement, refFieldName, refFieldValue, visitorPath) {
+    const {
+      continueOnError
+    } = this.options.dereference;
+    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;
+    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 = {
+      uri,
+      type,
+      refFieldName,
+      refFieldValue,
+      location,
+      codeFrame
+    };
+    let unresolvedError;
+    if (error instanceof UnresolvableReferenceError) {
+      const refBaseURI = this.toBaseURI(refFieldValue);
+      const fragment = URIFragmentIdentifier.fromURIReference(refFieldValue);
+      if (fragment) {
+        if (refBaseURI === error.uri && error.location) {
+          error.location = fragment + error.location;
+        }
+        for (const h of error.trace) {
+          if (h.uri === refBaseURI && h.location) h.location = fragment + h.location;
+        }
+      }
+      // @ts-ignore
+      error.trace = [hop, ...error.trace];
+      unresolvedError = error;
+    } else {
+      unresolvedError = new UnresolvableReferenceError(message, {
+        cause: error,
+        type,
+        uri,
+        location,
+        codeFrame,
+        refFieldName,
+        refFieldValue,
+        trace: []
+      });
+    }
+    if (!isEntryDocument || continueOnError === false) throw unresolvedError;
+    if (typeof continueOnError === 'function') continueOnError(unresolvedError);
+  }
+  async RefElement(path) {
+    const refElement = path.node;
+    const {
+      parent,
+      key
+    } = path;
+    const ancestors = path.getAncestorNodes();
+    const refURI = toValue(refElement);
+    const refNormalizedURI = refURI.includes('#') ? refURI : `#${refURI}`;
+    const retrievalURI = this.toBaseURI(refNormalizedURI);
+    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+    const isExternalReference = !isInternalReference;
+
+    // ignore resolving internal RefElements
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this ref element
+      path.skip();
+      return;
+    }
+    // ignore resolving external RefElements
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this ref element
+      path.skip();
+      return;
+    }
+    try {
+      const reference = await this.toReference(refNormalizedURI);
+      const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
+      const elementID = URIFragmentIdentifier.fromURIReference(refBaseURI);
+      let referencedElement = evaluate(elementID, reference.value.result);
+      if (!isElement(referencedElement)) {
+        throw new ApiDOMStructuredError(`Referenced element with id="${elementID}" was not found`, {
+          elementID
+        });
+      }
+      if (refElement === referencedElement) {
+        throw new ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference itself`, {
+          elementID
+        });
+      }
+      if (isRefElement(referencedElement)) {
+        throw new ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference another RefElement`, {
+          elementID
+        });
+      }
+      if (isExternalReference) {
+        // dive deep into the fragment
+        const visitor = new ApiDOMDereferenceVisitor({
+          reference,
+          options: this.options
+        });
+        referencedElement = await traverseAsync(referencedElement, visitor, {
+          mutable: true
+        });
+      }
+
+      /**
+       * When path is used, it references the given property of the referenced element.
+       * Valid paths are: 'element', 'content', 'meta', 'attributes'.
+       */
+      const referencedElementPath = toValue(refElement.path);
+      if (referencedElementPath !== 'element' && isElement(referencedElement)) {
+        referencedElement = refract(referencedElement[referencedElementPath]);
+      }
+
+      /**
+       * Transclusion of a Ref Element SHALL be defined in the if/else block below.
+       */
+      // ancestors[0] is the grandparent (nearest ancestor from getAncestorNodes())
+      const grandparent = ancestors[0];
+      if (isObjectElement(referencedElement) && isObjectElement(grandparent) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Object Element and references an Object Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if (isArrayElement(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Array Element and references an Array Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if (isMemberElement(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent.value = referencedElement;
+      } else if (Array.isArray(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent[key] = referencedElement;
+      }
+      if (!parent) {
+        path.replaceWith(referencedElement);
+      }
+    } catch (error) {
+      this.handleError(`Error while dereferencing Ref Element. Cannot resolve ref "${refURI}": ${error.message}`, error, refElement, null, refURI, path);
+    }
+  }
+}
+export default ApiDOMDereferenceVisitor;