@speclynx/apidom-reference 6.2.0 → 7.0.0

package/src/dereference/strategies/DereferenceVisitor.cjs

@@ -0,0 +1,588 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isGenericElement = exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomError = require("@speclynx/apidom-error");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _UnresolvableReferenceError = _interopRequireDefault(require("../../errors/UnresolvableReferenceError.cjs"));
+var _MaximumDereferenceDepthError = _interopRequireDefault(require("../../errors/MaximumDereferenceDepthError.cjs"));
+var _MaximumResolveDepthError = _interopRequireDefault(require("../../errors/MaximumResolveDepthError.cjs"));
+var url = _interopRequireWildcard(require("../../util/url.cjs"));
+var _index = _interopRequireDefault(require("../../parse/index.cjs"));
+var _Reference = _interopRequireDefault(require("../../Reference.cjs"));
+const genericClasses = new Set([_apidomDatamodel.ObjectElement, _apidomDatamodel.ArrayElement, _apidomDatamodel.MemberElement, _apidomDatamodel.StringElement, _apidomDatamodel.NumberElement, _apidomDatamodel.BooleanElement, _apidomDatamodel.NullElement]);
+
+/**
+ * Whether the element is generic ApiDOM: an instance of a primitive element class itself.
+ * Semantic elements may carry a primitive element name (e.g. a map of components named
+ * `object`), so the name alone doesn't tell.
+ * @internal
+ */
+const isGenericElement = element => genericClasses.has(element.constructor);
+
+/**
+ * A source dereferenced as one type: the source as that semantic type, with every reference
+ * within it transcluded. `element` exists from the start, so references leading back to
+ * an element still being dereferenced (cycles) can be transcluded with it.
+ * @internal
+ */
+
+/**
+ * How a referencing element is transcluded with the dereferenced target of its reference.
+ * @internal
+ */
+
+/**
+ * A transclusion to perform.
+ * @internal
+ */
+
+/**
+ * The target of a reference: the source element, the type the reference expects, and the
+ * document the source belongs to. `context` is passed to the visitor dereferencing the source.
+ * @internal
+ */
+
+/**
+ * State shared by all the visitors of a single dereference run.
+ * @internal
+ */
+
+/**
+ * @internal
+ */
+exports.isGenericElement = isGenericElement;
+// errors and trace hops whose location is relative to the source a nested visitor traversed
+const relativeLocations = new WeakSet();
+
+/**
+ * Dereferences a document by the type each reference expects of its target. With the immutable
+ * option the documents aren't edited and the result is a new tree; otherwise they're
+ * dereferenced in place.
+ *
+ * Every referenced structure is dereferenced once per type the references reaching it expect.
+ * A source is dereferenced as a type in two steps. First it's traversed, and for each reference
+ * within it the target is located, dereferenced as the expected type, and recorded as
+ * a transclusion. Then the referencing elements are transcluded with the dereferenced targets.
+ * A dereferenced element is shared by all the references leading to it; a reference leading
+ * to an element still being dereferenced is a cycle.
+ *
+ * Strategies provide the handlers locating the targets of their references, the refraction to
+ * their semantic types and the visitors dereferencing the targets.
+ * @internal
+ */
+class DereferenceVisitor {
+  reference;
+  options;
+
+  /**
+   * Base URI of the current document for resolving relative references.
+   */
+  baseURI;
+  run;
+
+  /**
+   * Map from the elements of the source the visitor traverses to their copies.
+   */
+  cloneMap;
+
+  /**
+   * Source the visitor traverses a refraction of, when it's dereferenced as another type.
+   */
+  refractedFrom;
+
+  /**
+   * Transclusions to perform, keyed by the (copy of the) referencing element.
+   */
+  transclusions = new Map();
+
+  /**
+   * Number of references followed to reach the source the visitor traverses.
+   */
+  depth = 0;
+
+  /**
+   * The source the visitor traverses, dereferenced.
+   */
+  current;
+  constructor({
+    reference,
+    options
+  }) {
+    this.reference = reference;
+    this.options = options;
+    this.baseURI = this.toDocumentBaseURI(reference);
+    this.run = {
+      dereferenced: new WeakMap(),
+      refracted: new WeakMap(),
+      inPlace: !options.dereference.immutable,
+      copies: new WeakMap(),
+      transcluded: new WeakSet(),
+      failed: new WeakSet(),
+      reported: new Set(),
+      undo: []
+    };
+  }
+
+  /**
+   * Name of the strategy, for strategy specific options.
+   */
+
+  /**
+   * Creates the visitor dereferencing a source of the given document.
+   */
+
+  /**
+   * Refracts a generic element to the given type.
+   */
+
+  /**
+   * Whether the element is of the given type, so it needs no refraction.
+   */
+  isOfType(element, type) {
+    return element.element === type;
+  }
+
+  /**
+   * Base URI of a document: its retrieval URI unless the document identifies itself otherwise.
+   */
+  toDocumentBaseURI(reference) {
+    return reference.uri;
+  }
+
+  /**
+   * A document already loaded in the run identified by the URI other than by its retrieval URI.
+   */
+  findReferenceByIdentity(_uri) {
+    return undefined;
+  }
+
+  /**
+   * Dereferences the element, which belongs to the document of the visitor's reference.
+   * With the immutable option the element isn't edited and its dereferenced copy is returned;
+   * otherwise it's dereferenced in place and returned.
+   */
+  async dereference(element, context) {
+    // frozen elements are left as they are: they're dereferenced as with the immutable option
+    const isFrozen = value => (0, _apidomDatamodel.isElement)(value) && (value.isFrozen || value instanceof _apidomDatamodel.ParseResultElement && value.result?.isFrozen === true);
+    if (this.run.inPlace && (isFrozen(element) || this.reference.refSet?.refs.some(ref => isFrozen(ref.value)))) {
+      this.run = {
+        ...this.run,
+        inPlace: false
+      };
+    }
+    const dereferenced = await this.dereferenceAs({
+      source: element,
+      type: element.element,
+      reference: this.reference,
+      context
+    }, 0);
+    return dereferenced.element;
+  }
+  toBaseURI(uri) {
+    return url.resolve(this.baseURI, 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 referenceByIdentity = this.findReferenceByIdentity(baseURI);
+    if (referenceByIdentity !== undefined) {
+      return referenceByIdentity;
+    }
+    const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+
+    // registered as parsed: with the immutable option it's only ever copied, never edited
+    const reference = new _Reference.default({
+      uri: baseURI,
+      value: parseResult,
+      depth: this.reference.depth + 1
+    });
+    refSet.add(reference);
+    return reference;
+  }
+
+  /**
+   * Handles an error according to the continueOnError option.
+   *
+   * For new errors: wraps in UnresolvableReferenceError with structured context
+   * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
+   * 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),
+   * and reports the failure of a referencing element once.
+   */
+  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;
+    const codeFrame = (0, _apidomCore.toYAML)(referencingElement);
+
+    // 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 is relative to the source being traversed
+    let location;
+    let refractedFromLocation;
+    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();
+          } else if (p.node === this.refractedFrom) {
+            refractedFromLocation = p.formatPath();
+          } else if (this.isTranscluded(p.node)) {
+            p.skip();
+          }
+        }
+      });
+    }
+    // not found, the location is relative to the traversed source: an enclosing visitor prefixes it
+    const isRelative = location === undefined && refractedFromLocation === undefined;
+    // within a refraction, the visitor path is relative to the refracted source
+    location ??= (refractedFromLocation ?? '') + visitorPath.formatPath();
+    const hop = {
+      uri,
+      type,
+      refFieldName,
+      refFieldValue,
+      location,
+      codeFrame
+    };
+    if (isRelative) relativeLocations.add(hop);
+
+    // enrich existing error from nested visitor or create new one
+    let unresolvedError;
+    if (error instanceof _UnresolvableReferenceError.default) {
+      // prefix relative locations for entries belonging to the referenced document
+      const refBaseURI = this.toBaseURI(refFieldValue);
+      const fragment = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(refFieldValue);
+      if (fragment) {
+        for (const entry of [error, ...error.trace]) {
+          if (relativeLocations.has(entry) && entry.uri === refBaseURI && entry.location) {
+            entry.location = fragment + entry.location;
+            relativeLocations.delete(entry);
+          }
+        }
+      }
+      // @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 (isRelative) relativeLocations.add(unresolvedError);
+    }
+    if (!isEntryDocument || continueOnError === false) throw unresolvedError;
+    // a referencing element is traversed again by every source containing it: its failure is reported once
+    this.run.failed.add(referencingElement);
+    const failure = JSON.stringify([uri, location, refFieldName, refFieldValue]);
+    if (this.run.reported.has(failure)) return;
+    this.run.reported.add(failure);
+    if (typeof continueOnError === 'function') continueOnError(unresolvedError);
+  }
+
+  /**
+   * The source as the given semantic type: the source itself when it's of that type, otherwise
+   * its refraction to that type, made once per dereference run. The refraction is made from
+   * the source dereferenced as its own type, so it doesn't depend on which reference
+   * reaches the source first.
+   */
+  async toSemantic(target, depth) {
+    const {
+      source,
+      type
+    } = target;
+    if (this.isOfType(source, type)) return source;
+    let byType = this.run.refracted.get(source);
+    if (byType === undefined) {
+      byType = new Map();
+      this.run.refracted.set(source, byType);
+    }
+    const cached = byType.get(type);
+    if (cached !== undefined) return cached;
+    const dereferenced = isGenericElement(source) ? source : (await this.dereferenceAs({
+      ...target,
+      type: source.element
+    }, depth)).element;
+    // dereferencing the source may have led back to this very refraction
+    const reached = byType.get(type);
+    if (reached !== undefined) return reached;
+    const semantic = this.refractTo((0, _apidomCore.toGeneric)(dereferenced), type);
+    byType.set(type, semantic);
+    this.run.undo.push(() => byType.delete(type));
+    return semantic;
+  }
+
+  /**
+   * Dereferences the source as the given type, once per dereference run. `depth` is the number
+   * of references followed to reach the source.
+   */
+  async dereferenceAs(target, depth) {
+    const {
+      source,
+      type,
+      reference,
+      context
+    } = target;
+    let byType = this.run.dereferenced.get(source);
+    if (byType === undefined) {
+      byType = new Map();
+      this.run.dereferenced.set(source, byType);
+    }
+    const existing = byType.get(type);
+    if (existing !== undefined) return existing;
+    const semantic = await this.toSemantic(target, depth);
+    // a refraction is made for the run, so it's dereferenced as is
+    const isOwned = semantic !== source || this.run.inPlace;
+    const cloneMap = isOwned ? undefined : this.run.copies;
+    const dereferenced = {
+      element: isOwned ? semantic : (0, _apidomDatamodel.cloneDeep)(semantic, {
+        visited: cloneMap
+      }),
+      done: false,
+      height: 0,
+      alias: false,
+      unresolved: false
+    };
+    // a failure discards whatever got dereferenced or refracted meanwhile, as it may lead to this element
+    const undoSize = this.run.undo.length;
+    byType.set(type, dereferenced);
+    this.run.undo.push(() => byType.delete(type));
+    const visitor = this.createVisitor(reference, context);
+    visitor.run = this.run;
+    visitor.cloneMap = cloneMap;
+    visitor.refractedFrom = semantic !== source ? source : undefined;
+    visitor.depth = depth;
+    visitor.current = dereferenced;
+    try {
+      // the handlers only record transclusions
+      await (0, _apidomTraverse.traverseAsync)(semantic, visitor);
+    } catch (error) {
+      this.run.undo.splice(undoSize).reverse().forEach(undo => undo());
+      throw error;
+    }
+    for (const transclusion of visitor.transclusions.values()) {
+      if (!transclusion.back && !transclusion.attachment) {
+        dereferenced.height = Math.max(dereferenced.height, transclusion.target.height + 1);
+      }
+    }
+    const rootTransclusion = visitor.transclusions.get(dereferenced.element);
+    dereferenced.unresolved = rootTransclusion !== undefined && (rootTransclusion.keep || rootTransclusion.target.unresolved);
+    dereferenced.element = visitor.transclude(dereferenced.element);
+    dereferenced.done = true;
+    return dereferenced;
+  }
+
+  /**
+   * Dereferences the target of a reference as the expected type and records the transclusion.
+   */
+  async addTransclusion(path, target, spec) {
+    const referencingCopy = this.cloneMap?.get(path.node) ?? path.node;
+    const {
+      maxDepth
+    } = this.options.dereference;
+
+    // the source being traversed is itself a referencing element: an alias of the target
+    if (path.parentPath === null && this.current !== undefined) this.current.alias = true;
+
+    // detect maximum depth of dereferencing
+    if (this.depth + 1 > maxDepth) {
+      throw new _MaximumDereferenceDepthError.default(`Maximum dereference depth of "${maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+        maxDepth,
+        uri: this.reference.uri
+      });
+    }
+    const existing = this.run.dereferenced.get(target.source)?.get(target.type);
+
+    // a target dereferenced earlier counts the references followed within it as well
+    if (existing?.done && this.depth + 1 + existing.height > maxDepth) {
+      throw new _MaximumDereferenceDepthError.default(`Maximum dereference depth of "${maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+        maxDepth,
+        uri: this.reference.uri
+      });
+    }
+
+    // a reference leading to an element still being dereferenced is a cycle
+    if (existing !== undefined && !existing.done) {
+      this.reference.refSet.circular = true;
+      if (this.options.dereference.circular === 'error') {
+        throw new _apidomError.ApiDOMStructuredError('Circular reference detected', spec.circular.details);
+      }
+      // an alias has no value before its own reference is transcluded: the referencing element
+      // is kept, to be transcluded by an enclosing dereferenced element, if any
+      const keep = existing.alias && this.options.dereference.circular === 'ignore';
+      this.transclusions.set(referencingCopy, {
+        ...spec,
+        target: existing,
+        back: true,
+        keep,
+        attachment: false
+      });
+      return;
+    }
+    const dereferenced = existing ?? (await this.dereferenceAs(target, this.depth + 1));
+    // the referencing element failed while its target was dereferenced, e.g. as a circular reference
+    if (this.run.failed.has(path.node)) return;
+    this.transclusions.set(referencingCopy, {
+      ...spec,
+      target: dereferenced,
+      back: false,
+      keep: false,
+      attachment: false
+    });
+  }
+
+  /**
+   * Records the transclusion of a referencing element with a target that isn't dereferenced:
+   * the target as the expected type is attached as it is, e.g. an Operation Object to the Link
+   * Object pointing at it. Attached targets never form cycles.
+   */
+  async addAttachment(path, target, toTranscludedElement) {
+    const referencingCopy = this.cloneMap?.get(path.node) ?? path.node;
+    const semantic = await this.toSemantic(target, this.depth + 1);
+    // with the immutable option, the attached target is its copy in the result when it has one
+    const element = this.run.inPlace ? semantic : this.run.copies.get(semantic) ?? semantic;
+    this.transclusions.set(referencingCopy, {
+      toTranscludedElement,
+      circular: {
+        uri: '',
+        meta: {},
+        details: {}
+      },
+      target: {
+        element,
+        done: true,
+        height: 0,
+        alias: false,
+        unresolved: false
+      },
+      back: false,
+      keep: false,
+      attachment: true
+    });
+  }
+
+  /**
+   * Transcludes every referencing element within the element with its dereferenced target.
+   */
+  transclude(element) {
+    if (this.transclusions.size === 0) return element;
+
+    // replaced on leave: nested referencing elements first, so merges see them replaced
+    (0, _apidomTraverse.traverse)(element, {
+      enter: path => {
+        if (this.isTranscluded(path.node)) path.skip();
+      },
+      leave: path => {
+        const transclusion = this.transclusions.get(path.node);
+        if (path.node !== element && transclusion !== undefined) {
+          const transcludedElement = this.toTranscludedElement(path.node, transclusion);
+          // a kept referencing element is left to be transcluded by an enclosing element
+          if (transcludedElement === path.node) return;
+          this.run.transcluded.add(transcludedElement);
+          path.replaceWith(transcludedElement);
+        }
+      }
+    }, {
+      mutable: true
+    });
+    const rootTransclusion = this.transclusions.get(element);
+    if (rootTransclusion === undefined) return element;
+
+    // references leading back to the element may already be transcluded with it, so it's filled in place
+    const transcludedElement = this.toTranscludedElement(element, rootTransclusion);
+    if (transcludedElement === element) return element;
+    if (transcludedElement.constructor !== element.constructor) return transcludedElement;
+    element.element = transcludedElement.element;
+    element.content = transcludedElement.content;
+    element.meta = transcludedElement.meta;
+    element.attributes = transcludedElement.attributes;
+    return element;
+  }
+
+  /**
+   * The element transcluded in place of a referencing element.
+   */
+  toTranscludedElement(referencingElement, transclusion) {
+    // the referencing element waits for an enclosing element to transclude it
+    if (transclusion.keep) return referencingElement;
+    // an alias whose reference never reaches a value
+    if (transclusion.target.unresolved) {
+      const {
+        aliasField
+      } = transclusion;
+      const alias = transclusion.target.element;
+      if (aliasField === undefined || !(0, _apidomDatamodel.isObjectElement)(alias)) return referencingElement;
+      const fields = (0, _apidomDatamodel.cloneShallow)(alias);
+      fields.remove(aliasField);
+      return transclusion.toTranscludedElement(referencingElement, fields);
+    }
+    if (transclusion.back && this.options.dereference.circular === 'replace') {
+      const refElement = new _apidomDatamodel.RefElement(transclusion.circular.uri, {
+        type: referencingElement.element,
+        ...transclusion.circular.meta
+      });
+      const replacer = this.options.dereference.strategyOpts[this.strategyName]?.circularReplacer ?? this.options.dereference.circularReplacer;
+      return replacer(refElement);
+    }
+    return transclusion.toTranscludedElement(referencingElement, transclusion.target.element);
+  }
+
+  /**
+   * Whether the element is transcluded in place of a referencing element, in this run or,
+   * when dereferencing in place, in an earlier one: transcluded elements carry the `ref-type` meta,
+   * which only dereferencing sets (bundling annotates hoisted elements with `ref-origin` only).
+   */
+  isTranscluded(element) {
+    return this.run.transcluded.has(element) || !element.isMetaEmpty && element.meta.hasKey('ref-type');
+  }
+
+  /**
+   * Dereferenced in place, a source may already hold transcluded elements.
+   */
+  enter(path) {
+    if (this.isTranscluded(path.node)) path.skip();
+  }
+}
+var _default = exports.default = DereferenceVisitor;