@speclynx/apidom-reference 3.2.0 → 4.0.0

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

@@ -1,867 +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 _ramdaAdjunct = require("ramda-adjunct");
-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 _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-1");
-var _$anchor = require("./selectors/$anchor.cjs");
-var _uri = require("./selectors/uri.cjs");
-var _MaximumDereferenceDepthError = _interopRequireDefault(require("../../../errors/MaximumDereferenceDepthError.cjs"));
-var _MaximumResolveDepthError = _interopRequireDefault(require("../../../errors/MaximumResolveDepthError.cjs"));
-var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
-var _EvaluationJsonSchemaUriError = _interopRequireDefault(require("../../../errors/EvaluationJsonSchemaUriError.cjs"));
-var url = _interopRequireWildcard(require("../../../util/url.cjs"));
-var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
-var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
-var _File = _interopRequireDefault(require("../../../File.cjs"));
-var _util = require("./util.cjs");
-var _util2 = require("../../util.cjs");
-/**
- * @public
- */
-
-/**
- * @public
- */
-class OpenAPI3_1DereferenceVisitor {
-  indirections;
-  reference;
-  options;
-  refractCache;
-
-  /**
-   * Tracks element ancestors across dive-deep traversal boundaries.
-   * Used for cycle detection: if a referenced element is found in
-   * the ancestor lineage, a circular reference is detected.
-   */
-  ancestors;
-  constructor({
-    reference,
-    options,
-    indirections = [],
-    refractCache = new WeakMap(),
-    ancestors = new _util2.AncestorLineage()
-  }) {
-    this.indirections = indirections;
-    this.reference = reference;
-    this.options = options;
-    this.refractCache = refractCache;
-    this.ancestors = new _util2.AncestorLineage(...ancestors);
-  }
-  toAncestorLineage(path) {
-    const ancestorNodes = path.getAncestorNodes();
-    const directAncestors = new Set(ancestorNodes.filter(_apidomDatamodel.isElement));
-    const ancestorsLineage = new _util2.AncestorLineage(...this.ancestors, directAncestors);
-    return [ancestorsLineage, directAncestors];
-  }
-  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
-    //
-    // NOTE(known limitation): the mutable reference is mutated in place during traversal
-    // (via `{ mutable: true }`). When an external document evaluates a JSON pointer back
-    // into this document, it may receive an already-resolved element instead of the original
-    // $ref. That resolved element was produced using the entry document's resolution context
-    // (ancestors, indirections), which may differ from the external document's context.
-    // This can affect cycle detection in rare cross-document circular reference patterns.
-    //
-    // Remediation: evaluate JSON pointers against the immutable (original) parse tree
-    // instead of the mutable working copy. The `immutable://` reference below preserves
-    // the original tree and could be used for pointer evaluation, ensuring every resolution
-    // context always sees raw, unresolved elements and processes them with its own
-    // ancestors/indirections. The trade-off is that elements referenced by multiple
-    // documents would be resolved once per context instead of being reused.
-    const mutableReference = new _Reference.default({
-      uri: baseURI,
-      value: this.options.dereference.immutable ? (0, _apidomDatamodel.cloneDeep)(parseResult) : parseResult,
-      depth: this.reference.depth + 1
-    });
-    refSet.add(mutableReference);
-    if (this.options.dereference.immutable) {
-      // register new immutable reference with original parseResult
-      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
-   * (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).
-   */
-  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: tree search for entry documents, visitor path for external
-    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();
-        }
-      }
-    });
-    location ??= visitorPath.formatPath();
-    const hop = {
-      uri,
-      type,
-      refFieldName,
-      refFieldValue,
-      location,
-      codeFrame
-    };
-
-    // 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) {
-        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 ReferenceElement(path) {
-    const referencingElement = path.node;
-
-    // skip current referencing element as it's already been accessed
-    if (this.indirections.includes(referencingElement)) {
-      path.skip();
-      return;
-    }
-    const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(referencingElement.$ref));
-    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-    const isExternalReference = !isInternalReference;
-
-    // ignore resolving internal Reference Objects
-    if (!this.options.resolve.internal && isInternalReference) {
-      // skip traversing this reference element and all it's child elements
-      path.skip();
-      return;
-    }
-    // ignore resolving external Reference Objects
-    if (!this.options.resolve.external && isExternalReference) {
-      // skip traversing this reference element and all it's child elements
-      path.skip();
-      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);
-      const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
-
-      // possibly non-semantic fragment
-      let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
-
-      // applying semantics to a fragment
-      const referencedElementType = referencingElement.meta.get('referenced-element');
-      if (referencedElement.element !== referencedElementType && !(0, _apidomNsOpenapi.isReferenceElement)(referencedElement)) {
-        if (this.refractCache.has(referencedElement)) {
-          referencedElement = this.refractCache.get(referencedElement);
-        } else if ((0, _apidomNsOpenapi.isReferenceLikeElement)(referencedElement)) {
-          // handling generic indirect references
-          const sourceElement = referencedElement;
-          referencedElement = (0, _apidomNsOpenapi.refractReference)(referencedElement);
-          referencedElement.meta.set('referenced-element', referencedElementType);
-          this.refractCache.set(sourceElement, referencedElement);
-        } else {
-          // handling direct references
-          const sourceElement = referencedElement;
-          referencedElement = (0, _apidomNsOpenapi.refract)(referencedElement, {
-            element: referencedElementType
-          });
-          this.refractCache.set(sourceElement, referencedElement);
-        }
-      }
-
-      // detect direct or indirect reference
-      if (referencingElement === referencedElement) {
-        throw new _apidomError.ApiDOMStructuredError('Recursive Reference Object detected', {
-          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-        });
-      }
-
-      // detect maximum depth of dereferencing
-      if (this.indirections.length > this.options.dereference.maxDepth) {
-        throw new _MaximumDereferenceDepthError.default(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
-          maxDepth: this.options.dereference.maxDepth,
-          uri: this.reference.uri
-        });
-      }
-
-      // detect cross-boundary cycle
-      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
-      if (ancestorsLineage.includes(referencedElement)) {
-        reference.refSet.circular = true;
-        if (this.options.dereference.circular === 'error') {
-          throw new _apidomError.ApiDOMStructuredError('Circular reference detected', {
-            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-          });
-        } else if (this.options.dereference.circular === 'replace') {
-          const refElement = new _apidomDatamodel.RefElement($refBaseURI, {
-            type: referencingElement.element,
-            uri: reference.uri,
-            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-          });
-          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-          const replacement = replacer(refElement);
-          path.replaceWith(replacement);
-          return;
-        }
-      }
-
-      /**
-       * Dive deep into the fragment.
-       *
-       * Cases to consider:
-       *  1. We're crossing document boundary
-       *  2. Fragment is from non-entry document
-       *  3. Fragment is a Reference Object. We need to follow it to get the eventual value
-       *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
-       */
-      const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
-      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
-        directAncestors.add(referencingElement);
-        const visitor = new OpenAPI3_1DereferenceVisitor({
-          reference,
-          indirections: [...this.indirections],
-          options: this.options,
-          refractCache: this.refractCache,
-          ancestors: ancestorsLineage
-        });
-        referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
-          mutable: true
-        });
-        directAncestors.delete(referencingElement);
-      }
-
-      /**
-       * Creating a new version of referenced element to avoid modifying the original one.
-       */
-      const mergedElement = (0, _apidomDatamodel.cloneShallow)(referencedElement);
-      // annotate fragment with info about original Reference element
-      mergedElement.meta.set('ref-fields', {
-        $ref: (0, _apidomCore.toValue)(referencingElement.$ref),
-        // @ts-ignore
-        description: (0, _apidomCore.toValue)(referencingElement.description),
-        // @ts-ignore
-        summary: (0, _apidomCore.toValue)(referencingElement.summary)
-      });
-      // annotate fragment with info about origin and type
-      mergedElement.meta.set('ref-origin', reference.uri);
-      mergedElement.meta.set('ref-type', referencingElement.element);
-
-      // override description and summary (outer has higher priority then inner)
-      if ((0, _apidomDatamodel.isObjectElement)(referencedElement) && (0, _apidomDatamodel.isObjectElement)(mergedElement)) {
-        const fields = (0, _apidomCore.fixedFields)(referencedElement, {
-          indexed: true
-        });
-        if (referencingElement.hasKey('description') && Object.hasOwn(fields, 'description')) {
-          mergedElement.remove('description');
-          mergedElement.set('description', referencingElement.get('description'));
-        }
-        if (referencingElement.hasKey('summary') && Object.hasOwn(fields, 'summary')) {
-          mergedElement.remove('summary');
-          mergedElement.set('summary', referencingElement.get('summary'));
-        }
-      }
-
-      /**
-       * Transclude referencing element with merged referenced element.
-       */
-      path.replaceWith(mergedElement);
-    } 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) {
-    const referencingElement = path.node;
-
-    // ignore PathItemElement without $ref field
-    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
-      return;
-    }
-
-    // skip current referencing element as it's already been accessed
-    if (this.indirections.includes(referencingElement)) {
-      path.skip();
-      return;
-    }
-    const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(referencingElement.$ref));
-    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-    const isExternalReference = !isInternalReference;
-
-    // ignore resolving internal Path Item Objects
-    if (!this.options.resolve.internal && isInternalReference) {
-      // skip traversing this Path Item element but traverse all it's child elements
-      return;
-    }
-    // ignore resolving external Path Item Objects
-    if (!this.options.resolve.external && isExternalReference) {
-      // skip traversing this Path Item element but traverse all it's child elements
-      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);
-      const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
-
-      // possibly non-semantic referenced element
-      let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
-
-      // applying semantics to a referenced element
-      if (!(0, _apidomNsOpenapi.isPathItemElement)(referencedElement)) {
-        if (this.refractCache.has(referencedElement)) {
-          referencedElement = this.refractCache.get(referencedElement);
-        } else {
-          const sourceElement = referencedElement;
-          referencedElement = (0, _apidomNsOpenapi.refractPathItem)(referencedElement);
-          this.refractCache.set(sourceElement, referencedElement);
-        }
-      }
-
-      // detect direct or indirect reference
-      if (referencingElement === referencedElement) {
-        throw new _apidomError.ApiDOMStructuredError('Recursive Path Item Object reference detected', {
-          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-        });
-      }
-
-      // detect maximum depth of dereferencing
-      if (this.indirections.length > this.options.dereference.maxDepth) {
-        throw new _MaximumDereferenceDepthError.default(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
-          maxDepth: this.options.dereference.maxDepth,
-          uri: this.reference.uri
-        });
-      }
-
-      // detect cross-boundary cycle
-      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
-      if (ancestorsLineage.includes(referencedElement)) {
-        reference.refSet.circular = true;
-        if (this.options.dereference.circular === 'error') {
-          throw new _apidomError.ApiDOMStructuredError('Circular reference detected', {
-            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-          });
-        } else if (this.options.dereference.circular === 'replace') {
-          const refElement = new _apidomDatamodel.RefElement($refBaseURI, {
-            type: referencingElement.element,
-            uri: reference.uri,
-            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-          });
-          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-          const replacement = replacer(refElement);
-          path.replaceWith(replacement);
-          return;
-        }
-      }
-
-      /**
-       * Dive deep into the fragment.
-       *
-       * Cases to consider:
-       *  1. We're crossing document boundary
-       *  2. Fragment is from non-entry document
-       *  3. Fragment is a Path Item Object with $ref field. We need to follow it to get the eventual value
-       *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
-       */
-      const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
-      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isPathItemElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
-        directAncestors.add(referencingElement);
-        const visitor = new OpenAPI3_1DereferenceVisitor({
-          reference,
-          indirections: [...this.indirections],
-          options: this.options,
-          refractCache: this.refractCache,
-          ancestors: ancestorsLineage
-        });
-        referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
-          mutable: true
-        });
-        directAncestors.delete(referencingElement);
-      }
-
-      /**
-       * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
-       */
-      if ((0, _apidomNsOpenapi.isPathItemElement)(referencedElement)) {
-        const mergedElement = (0, _apidomDatamodel.cloneShallow)(referencedElement);
-        // existing keywords from referencing PathItemElement overrides ones from referenced element
-        referencingElement.forEach((value, keyElement, item) => {
-          mergedElement.remove((0, _apidomCore.toValue)(keyElement));
-          mergedElement.content.push(item);
-        });
-        mergedElement.remove('$ref');
-
-        // annotate referenced element with info about original referencing element
-        mergedElement.meta.set('ref-fields', {
-          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-        });
-        // annotate referenced element with info about origin and type
-        mergedElement.meta.set('ref-origin', reference.uri);
-        mergedElement.meta.set('ref-type', referencingElement.element);
-        referencedElement = mergedElement;
-      }
-
-      /**
-       * Transclude referencing element with merged referenced element.
-       */
-      path.replaceWith(referencedElement);
-    } 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) {
-    const linkElement = path.node;
-
-    // ignore LinkElement without operationRef or operationId field
-    if (!(0, _apidomDatamodel.isStringElement)(linkElement.operationRef) && !(0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
-      return;
-    }
-
-    // operationRef and operationId fields are mutually exclusive
-    if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef) && (0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
-      throw new _apidomError.ApiDOMStructuredError('LinkElement operationRef and operationId fields are mutually exclusive', {
-        operationRef: (0, _apidomCore.toValue)(linkElement.operationRef),
-        operationId: (0, _apidomCore.toValue)(linkElement.operationId)
-      });
-    }
-    try {
-      let operationElement;
-      if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef)) {
-        // possibly non-semantic referenced element
-        const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference((0, _apidomCore.toValue)(linkElement.operationRef));
-        const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(linkElement.operationRef));
-        const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-        const isExternalReference = !isInternalReference;
-
-        // ignore resolving internal Operation Object reference
-        if (!this.options.resolve.internal && isInternalReference) {
-          // skip traversing this Link element but traverse all it's child elements
-          return;
-        }
-        // ignore resolving external Operation Object reference
-        if (!this.options.resolve.external && isExternalReference) {
-          // skip traversing this Link element but traverse all it's child elements
-          return;
-        }
-        const reference = await this.toReference((0, _apidomCore.toValue)(linkElement.operationRef));
-        operationElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
-        // applying semantics to a referenced element
-        if (!(0, _apidomNsOpenapi.isOperationElement)(operationElement)) {
-          if (this.refractCache.has(operationElement)) {
-            operationElement = this.refractCache.get(operationElement);
-          } else {
-            const sourceElement = operationElement;
-            operationElement = (0, _apidomNsOpenapi.refractOperation)(operationElement);
-            this.refractCache.set(sourceElement, operationElement);
-          }
-        }
-        // create shallow clone to be able to annotate with metadata
-        operationElement = (0, _apidomDatamodel.cloneShallow)(operationElement);
-        // annotate operation element with info about origin and type
-        operationElement.meta.set('ref-origin', reference.uri);
-        operationElement.meta.set('ref-type', linkElement.element);
-        const linkElementCopy = (0, _apidomDatamodel.cloneShallow)(linkElement);
-        linkElementCopy.operationRef?.meta.set('operation', operationElement);
-
-        /**
-         * Transclude Link Object containing Operation Object in its meta.
-         */
-        path.replaceWith(linkElementCopy);
-        return;
-      }
-      if ((0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
-        const operationId = (0, _apidomCore.toValue)(linkElement.operationId);
-        const reference = await this.toReference(url.unsanitize(this.reference.uri));
-        operationElement = (0, _apidomTraverse.find)(reference.value.result, e => (0, _apidomNsOpenapi.isOperationElement)(e) && (0, _apidomDatamodel.isElement)(e.operationId) && e.operationId.equals(operationId));
-        // OperationElement not found by its operationId
-        if ((0, _ramdaAdjunct.isUndefined)(operationElement)) {
-          throw new _apidomError.ApiDOMStructuredError(`OperationElement(operationId=${operationId}) not found`, {
-            operationId
-          });
-        }
-        const linkElementCopy = (0, _apidomDatamodel.cloneShallow)(linkElement);
-        linkElementCopy.operationId?.meta.set('operation', operationElement);
-
-        /**
-         * Transclude Link Object containing Operation Object in its meta.
-         */
-        path.replaceWith(linkElementCopy);
-      }
-    } catch (error) {
-      const refFieldName = (0, _apidomDatamodel.isStringElement)(linkElement.operationRef) ? 'operationRef' : 'operationId';
-      const refFieldValue = (0, _apidomDatamodel.isStringElement)(linkElement.operationRef) ? (0, _apidomCore.toValue)(linkElement.operationRef) : (0, _apidomCore.toValue)(linkElement.operationId);
-      this.handleError(`Error while dereferencing Link Object. Cannot resolve ${refFieldName} "${refFieldValue}": ${error.message}`, error, linkElement, refFieldName, refFieldValue, path);
-    }
-  }
-  async ExampleElement(path) {
-    const exampleElement = path.node;
-
-    // ignore ExampleElement without externalValue field
-    if (!(0, _apidomDatamodel.isStringElement)(exampleElement.externalValue)) {
-      return;
-    }
-
-    // value and externalValue fields are mutually exclusive
-    if (exampleElement.hasKey('value') && (0, _apidomDatamodel.isStringElement)(exampleElement.externalValue)) {
-      throw new _apidomError.ApiDOMStructuredError('ExampleElement value and externalValue fields are mutually exclusive', {
-        value: (0, _apidomCore.toValue)(exampleElement.value),
-        externalValue: (0, _apidomCore.toValue)(exampleElement.externalValue)
-      });
-    }
-    const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(exampleElement.externalValue));
-    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-    const isExternalReference = !isInternalReference;
-
-    // ignore resolving internal Example Objects
-    if (!this.options.resolve.internal && isInternalReference) {
-      // skip traversing this Example element but traverse all it's child elements
-      return;
-    }
-    // ignore resolving external Example Objects
-    if (!this.options.resolve.external && isExternalReference) {
-      // skip traversing this Example element but traverse all it's child elements
-      return;
-    }
-    try {
-      const reference = await this.toReference((0, _apidomCore.toValue)(exampleElement.externalValue));
-
-      // shallow clone of the referenced element
-      const valueElement = (0, _apidomDatamodel.cloneShallow)(reference.value.result);
-      // annotate element with info about origin and type
-      valueElement.meta.set('ref-origin', reference.uri);
-      valueElement.meta.set('ref-type', exampleElement.element);
-      const exampleElementCopy = (0, _apidomDatamodel.cloneShallow)(exampleElement);
-      exampleElementCopy.value = valueElement;
-
-      /**
-       * Transclude Example Object containing external value.
-       */
-      path.replaceWith(exampleElementCopy);
-    } catch (error) {
-      const externalValue = (0, _apidomCore.toValue)(exampleElement.externalValue);
-      this.handleError(`Error while dereferencing Example Object. Cannot resolve externalValue "${externalValue}": ${error.message}`, error, exampleElement, 'externalValue', externalValue, path);
-    }
-  }
-  async SchemaElement(path) {
-    const referencingElement = path.node;
-
-    // skip current referencing schema as $ref keyword was not defined
-    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
-      return;
-    }
-
-    // skip current referencing element as it's already been accessed
-    if (this.indirections.includes(referencingElement)) {
-      path.skip();
-      return;
-    }
-    const indirectionsSize = this.indirections.length;
-    try {
-      // compute baseURI using rules around $id and $ref keywords
-      let reference = await this.toReference(url.unsanitize(this.reference.uri));
-      let {
-        uri: retrievalURI
-      } = reference;
-      const $refBaseURI = (0, _util.resolveSchema$refField)(retrievalURI, referencingElement);
-      const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
-      const file = new _File.default({
-        uri: $refBaseURIStrippedHash
-      });
-      const isUnknownURI = (0, _ramda.none)(r => r.canRead(file), this.options.resolve.resolvers);
-      const isURL = !isUnknownURI;
-      let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
-      let isExternalReference = !isInternalReference;
-
-      // determining reference, proper evaluation and selection mechanism
-      let referencedElement;
-      try {
-        if (isUnknownURI || isURL) {
-          // we're dealing with canonical URI or URL with possible fragment
-          retrievalURI = this.toBaseURI($refBaseURI);
-          const selector = $refBaseURI;
-          const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-          referencedElement = (0, _uri.evaluate)(selector, referenceAsSchema);
-          referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
-
-          // ignore resolving internal Schema Objects
-          if (!this.options.resolve.internal && isInternalReference) {
-            // skip traversing this schema element but traverse all it's child elements
-            return;
-          }
-          // ignore resolving external Schema Objects
-          if (!this.options.resolve.external && isExternalReference) {
-            // skip traversing this schema element but traverse all it's child elements
-            return;
-          }
-        } else {
-          // we're assuming here that we're dealing with JSON Pointer here
-          retrievalURI = this.toBaseURI($refBaseURI);
-          isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-          isExternalReference = !isInternalReference;
-
-          // ignore resolving internal Schema Objects
-          if (!this.options.resolve.internal && isInternalReference) {
-            // skip traversing this schema element but traverse all it's child elements
-            return;
-          }
-          // ignore resolving external Schema Objects
-          if (!this.options.resolve.external && isExternalReference) {
-            // skip traversing this schema element but traverse all it's child elements
-            return;
-          }
-          reference = await this.toReference(url.unsanitize($refBaseURI));
-          const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
-          const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-          referencedElement = (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
-          referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
-        }
-      } catch (error) {
-        /**
-         * SchemaElement($id=URL) was not found, so we're going to try to resolve
-         * the URL and assume the returned response is a JSON Schema.
-         */
-        if (isURL && error instanceof _EvaluationJsonSchemaUriError.default) {
-          if ((0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)($refBaseURI))) {
-            // we're dealing with JSON Schema $anchor here
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-            isExternalReference = !isInternalReference;
-
-            // ignore resolving internal Schema Objects
-            if (!this.options.resolve.internal && isInternalReference) {
-              // skip traversing this schema element but traverse all it's child elements
-              return;
-            }
-            // ignore resolving external Schema Objects
-            if (!this.options.resolve.external && isExternalReference) {
-              // skip traversing this schema element but traverse all it's child elements
-              return;
-            }
-            reference = await this.toReference(url.unsanitize($refBaseURI));
-            const selector = (0, _$anchor.uriToAnchor)($refBaseURI);
-            const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-            referencedElement = (0, _$anchor.evaluate)(selector, referenceAsSchema);
-            referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
-          } else {
-            // we're assuming here that we're dealing with JSON Pointer here
-            retrievalURI = this.toBaseURI($refBaseURI);
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-            isExternalReference = !isInternalReference;
-
-            // ignore resolving internal Schema Objects
-            if (!this.options.resolve.internal && isInternalReference) {
-              // skip traversing this schema element but traverse all it's child elements
-              return;
-            }
-            // ignore resolving external Schema Objects
-            if (!this.options.resolve.external && isExternalReference) {
-              // skip traversing this schema element but traverse all it's child elements
-              return;
-            }
-            reference = await this.toReference(url.unsanitize($refBaseURI));
-            const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
-            const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-            referencedElement = (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
-            referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
-          }
-        } else {
-          throw error;
-        }
-      }
-      this.indirections.push(referencingElement);
-
-      // detect direct or indirect reference
-      if (referencingElement === referencedElement) {
-        throw new _apidomError.ApiDOMStructuredError('Recursive Schema Object reference detected', {
-          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-        });
-      }
-
-      // detect maximum depth of dereferencing
-      if (this.indirections.length > this.options.dereference.maxDepth) {
-        throw new _MaximumDereferenceDepthError.default(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
-          maxDepth: this.options.dereference.maxDepth,
-          uri: this.reference.uri
-        });
-      }
-
-      // detect cross-boundary cycle
-      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
-      if (ancestorsLineage.includes(referencedElement)) {
-        reference.refSet.circular = true;
-        if (this.options.dereference.circular === 'error') {
-          throw new _apidomError.ApiDOMStructuredError('Circular reference detected', {
-            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-          });
-        } else if (this.options.dereference.circular === 'replace') {
-          const refElement = new _apidomDatamodel.RefElement($refBaseURI, {
-            type: referencingElement.element,
-            uri: reference.uri,
-            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-          });
-          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-          const replacement = replacer(refElement);
-          path.replaceWith(replacement);
-          return;
-        }
-      }
-
-      /**
-       * Dive deep into the fragment.
-       *
-       * Cases to consider:
-       *  1. We're crossing document boundary
-       *  2. Fragment is from non-entry document
-       *  3. Fragment is a Schema Object with $ref field. We need to follow it to get the eventual value
-       *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
-       */
-      const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
-      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isSchemaElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
-        directAncestors.add(referencingElement);
-        const visitor = new OpenAPI3_1DereferenceVisitor({
-          reference,
-          indirections: [...this.indirections],
-          options: this.options,
-          refractCache: this.refractCache,
-          ancestors: ancestorsLineage
-        });
-        referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
-          mutable: true
-        });
-        directAncestors.delete(referencingElement);
-      }
-
-      // Boolean JSON Schemas
-      if ((0, _apidomNsOpenapi.isBooleanJSONSchemaElement)(referencedElement)) {
-        const booleanJsonSchemaElement = (0, _apidomDatamodel.cloneDeep)(referencedElement);
-        // annotate referenced element with info about original referencing element
-        booleanJsonSchemaElement.meta.set('ref-fields', {
-          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-        });
-        // annotate referenced element with info about origin and type
-        booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
-        booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
-        path.replaceWith(booleanJsonSchemaElement);
-        return;
-      }
-
-      /**
-       * Creating a new version of Schema Object by merging fields from referenced Schema Object with referencing one.
-       */
-      if ((0, _apidomNsOpenapi.isSchemaElement)(referencedElement)) {
-        const mergedElement = (0, _apidomDatamodel.cloneShallow)(referencedElement);
-        // existing keywords from referencing schema overrides ones from referenced schema
-        referencingElement.forEach((value, keyElement, item) => {
-          mergedElement.remove((0, _apidomCore.toValue)(keyElement));
-          mergedElement.content.push(item);
-        });
-        mergedElement.remove('$ref');
-        // annotate referenced element with info about original referencing element
-        mergedElement.meta.set('ref-fields', {
-          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
-        });
-        // annotate fragment with info about origin and type
-        mergedElement.meta.set('ref-origin', reference.uri);
-        mergedElement.meta.set('ref-type', referencingElement.element);
-        referencedElement = mergedElement;
-      }
-      /**
-       * Transclude referencing element with merged referenced element.
-       */
-      path.replaceWith(referencedElement);
-    } catch (error) {
-      const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
-      this.handleError(`Error while dereferencing Schema Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
-    } finally {
-      if (this.indirections.length > indirectionsSize) this.indirections.pop();
-    }
-  }
-}
-var _default = exports.default = OpenAPI3_1DereferenceVisitor;