@speclynx/apidom-reference 3.2.0 → 4.0.0

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

@@ -1,259 +0,0 @@
-"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;
-    let location;
-    (0, _apidomTraverse.traverse)(this.reference.value.result, {
-      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

@@ -1,252 +0,0 @@
-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;
-    let location;
-    traverse(this.reference.value.result, {
-      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;

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

@@ -1,109 +0,0 @@
-"use strict";
-
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
-exports.resolveSchema$refField = exports.resolveSchema$idField = exports.maybeRefractToJSONSchemaElement = exports.default = void 0;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-var _apidomTraverse = require("@speclynx/apidom-traverse");
-var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
-var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrategy.cjs"));
-var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
-var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
-var _visitor = _interopRequireDefault(require("./visitor.cjs"));
-exports.Arazzo1DereferenceVisitor = _visitor.default;
-var _sourceDescriptions = require("./source-descriptions.cjs");
-exports.dereferenceSourceDescriptions = _sourceDescriptions.dereferenceSourceDescriptions;
-var _util = require("./util.cjs");
-exports.resolveSchema$refField = _util.resolveSchema$refField;
-exports.resolveSchema$idField = _util.resolveSchema$idField;
-exports.maybeRefractToJSONSchemaElement = _util.maybeRefractToJSONSchemaElement;
-/**
- * @public
- */
-
-/**
- * @public
- */
-class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
-  constructor(options) {
-    super({
-      ...(options ?? {}),
-      name: 'arazzo-1'
-    });
-  }
-  canDereference(file) {
-    // assert by media type
-    if (file.mediaType !== 'text/plain') {
-      return _apidomNsArazzo.mediaTypes.includes(file.mediaType);
-    }
-
-    // assert by inspecting ApiDOM
-    return (0, _apidomNsArazzo.isArazzoSpecification1Element)(file.parseResult?.result);
-  }
-  async dereference(file, options) {
-    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet.default();
-    const mutableRefSet = new _ReferenceSet.default();
-    let refSet = immutableRefSet;
-    let reference;
-    if (!immutableRefSet.has(file.uri)) {
-      reference = new _Reference.default({
-        uri: file.uri,
-        value: file.parseResult
-      });
-      immutableRefSet.add(reference);
-    } else {
-      // pre-computed refSet was provided as configuration option
-      reference = immutableRefSet.find(ref => ref.uri === file.uri);
-    }
-
-    /**
-     * Clone refSet due the dereferencing process being mutable.
-     * We don't want to mutate the original refSet and the references.
-     */
-    if (options.dereference.immutable) {
-      immutableRefSet.refs.map(ref => new _Reference.default({
-        ...ref,
-        value: (0, _apidomDatamodel.cloneDeep)(ref.value)
-      })).forEach(ref => mutableRefSet.add(ref));
-      reference = mutableRefSet.find(ref => ref.uri === file.uri);
-      refSet = mutableRefSet;
-    }
-    const visitor = new _visitor.default({
-      reference,
-      options
-    });
-    const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
-    });
-
-    /**
-     * Dereference source descriptions if option is enabled.
-     */
-    const shouldDereferenceSourceDescriptions = options?.dereference?.strategyOpts?.[this.name]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
-    if (shouldDereferenceSourceDescriptions) {
-      const sourceDescriptions = await (0, _sourceDescriptions.dereferenceSourceDescriptions)(dereferencedElement, reference.uri, options, this.name);
-      dereferencedElement.push(...sourceDescriptions);
-    }
-
-    /**
-     * If immutable option is set, replay refs from the refSet.
-     */
-    if (options.dereference.immutable) {
-      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference.default({
-        ...ref,
-        uri: ref.uri.replace(/^immutable:\/\//, '')
-      })).forEach(ref => immutableRefSet.add(ref));
-    }
-
-    /**
-     * Release all memory if this refSet was not provided as a configuration option.
-     * If provided as configuration option, then provider is responsible for cleanup.
-     */
-    if (options.dereference.refSet === null) {
-      immutableRefSet.clean();
-    }
-    mutableRefSet.clean();
-    return dereferencedElement;
-  }
-}
-var _default = exports.default = Arazzo1DereferenceStrategy;