@speclynx/apidom-reference 6.2.0 → 7.0.0

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

@@ -1,406 +1,255 @@
-import { propEq, none } from 'ramda';
+import { none } from 'ramda';
 import { isUndefined } from 'ramda-adjunct';
-import { isElement, isStringElement, isObjectElement, isParseResultElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
-import { toValue, fixedFields, toYAML } from '@speclynx/apidom-core';
+import { isElement, isStringElement, isObjectElement, isParseResultElement, isPrimitiveElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
+import { toValue, fixedFields } from '@speclynx/apidom-core';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
-import { traverse, traverseAsync, find } from '@speclynx/apidom-traverse';
+import { traverse, find } from '@speclynx/apidom-traverse';
 import { evaluate as jsonPointerEvaluate, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
-import { isReferenceLikeElement, isPathItemElement, isReferenceElement, isSchemaElement, isOperationElement, isBooleanJSONSchemaElement, refract, refractReference, refractPathItem, refractOperation } from '@speclynx/apidom-ns-openapi-3-1';
+import { isReferenceLikeElement, isPathItemElement, isReferenceElement, isSchemaElement, isOperationElement, isBooleanJSONSchemaElement, refract, refractReference, refractSchema } from '@speclynx/apidom-ns-openapi-3-1';
 import { isAnchor, uriToAnchor, locate as $anchorLocate } from "./selectors/$anchor.mjs";
 import { locate as uriLocate } from "./selectors/uri.mjs";
 import { locate as jsonPointerLocate } from "./selectors/json-pointer.mjs";
-import MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
-import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
-import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
 import EvaluationJsonSchemaUriError from "../../../errors/EvaluationJsonSchemaUriError.mjs";
+import DereferenceVisitor from "../DereferenceVisitor.mjs";
 import * as url from "../../../util/url.mjs";
-import parse from "../../../parse/index.mjs";
-import Reference from "../../../Reference.mjs";
 import File from "../../../File.mjs";
-import { schema$idsOf, resolveSchema$ids, resolveSchemaBaseURI, resolveSchema$refField, maybeRefractToSchemaElement } from "./util.mjs";
-import { AncestorLineage } from "../../util.mjs";
+import { isJSONSchemaElementWith$id, collectSchema$ids, resolveSchema$ids, resolveSchemaBaseURI, resolveSchema$refField } from "./util.mjs";
 /**
- * @public
+ * Type a Schema Object `$ref` expects its target to have.
+ */
+const SCHEMA_TYPE = 'schema';
+
+/**
+ * Context of a source being dereferenced: the `$id`s of the Schema Objects enclosing it.
  */
+
 /**
  * @public
  */
-class OpenAPI3_1DereferenceVisitor {
-  indirections;
-  reference;
-  options;
-  refractCache;
 
+/**
+ * Dereferences an OpenAPI 3.1 document. Reference Objects expect the type of their
+ * `referenced-element` meta, Path Item `$ref`s a Path Item, Schema Object `$ref`s a Schema Object.
+ * Link Objects get the Operation Object they point at attached, Example Objects
+ * the external value.
+ *
+ * @public
+ */
+class OpenAPI3_1DereferenceVisitor extends DereferenceVisitor {
   /**
-   * Index of `$id`-bearing schemas per document, shared across nested visitors
-   * of a single dereference run so it never outlives mutations of the documents.
+   * Index of `$id`-bearing schemas per document, shared across the visitors
+   * of a single dereference run.
    */
   schema$idIndex;
-  visited;
 
   /**
    * `$id`s of the JSON Schema elements enclosing the traversal root within its
    * document (outermost first). Empty when the root is the document itself; a
-   * nested visitor traversing a fragment is seeded with the `$id`s of the
-   * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
-   * against the same base as they would from the document root.
+   * visitor traversing a fragment is seeded with the `$id`s of the schemas the
+   * fragment sits under, so the `$ref`s and `$id`s within resolve against the
+   * same base as they would from the document root.
    */
   ancestorSchema$ids;
-
-  /**
-   * 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(),
     schema$idIndex = new WeakMap(),
-    ancestors = new AncestorLineage(),
-    visited = new WeakSet(),
     ancestorSchema$ids = []
   }) {
-    this.indirections = indirections;
-    this.reference = reference;
-    this.options = options;
-    this.refractCache = refractCache;
+    super({
+      reference,
+      options
+    });
     this.schema$idIndex = schema$idIndex;
-    this.ancestors = new AncestorLineage(...ancestors);
-    this.visited = visited;
     this.ancestorSchema$ids = ancestorSchema$ids;
   }
-  toAncestorLineage(path) {
-    const ancestorNodes = path.getAncestorNodes();
-    const directAncestors = new Set(ancestorNodes.filter(isElement));
-    const ancestorsLineage = new AncestorLineage(...this.ancestors, directAncestors);
-    return [ancestorsLineage, directAncestors];
+  get strategyName() {
+    return 'openapi-3-1';
   }
-  toBaseURI(uri) {
-    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+  createVisitor(reference, {
+    ancestorSchema$ids
+  }) {
+    return new OpenAPI3_1DereferenceVisitor({
+      reference,
+      options: this.options,
+      schema$idIndex: this.schema$idIndex,
+      ancestorSchema$ids
+    });
   }
-  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'));
+
+  /**
+   * A Reference Object stands for the type its reference expects: it's dereferenced as that type.
+   */
+  isOfType(element, type) {
+    if (isReferenceElement(element)) return true;
+    return type === SCHEMA_TYPE ? isSchemaElement(element) || isBooleanJSONSchemaElement(element) : element.element === type;
+  }
+
+  /**
+   * A generic structure holding a `$ref` is a Reference Object to the expected type,
+   * unless the type has its own `$ref` field (Path Item Object, Schema Object).
+   */
+  refractTo(element, type) {
+    if (type !== SCHEMA_TYPE && type !== 'pathItem' && isReferenceLikeElement(element)) {
+      const referenceElement = refractReference(element);
+      referenceElement.meta.set('referenced-element', type);
+      return referenceElement;
     }
-    const parseResult = await parse(url.unsanitize(baseURI), {
-      ...this.options,
-      parse: {
-        ...this.options.parse,
-        mediaType: 'text/plain'
-      }
+    return refract(element, {
+      element: type
     });
+  }
 
-    // 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({
-      uri: baseURI,
-      value: this.options.dereference.immutable ? 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({
-        uri: `immutable://${baseURI}`,
-        value: parseResult,
-        depth: this.reference.depth + 1
-      });
-      refSet.add(immutableReference);
+  /**
+   * A document as Schema Object for locating schemas within it: a generic document is
+   * refracted to Schema Object once per dereference run, a semantic one is used as it is.
+   */
+  toSchemaDocument(document) {
+    if (!isPrimitiveElement(document)) return document;
+    let byType = this.run.refracted.get(document);
+    if (byType === undefined) {
+      byType = new Map();
+      this.run.refracted.set(document, byType);
     }
-    return mutableReference;
+    let refracted = byType.get(SCHEMA_TYPE);
+    if (refracted === undefined) {
+      refracted = refractSchema(document);
+      byType.set(SCHEMA_TYPE, refracted);
+    }
+    return refracted;
   }
 
   /**
-   * 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).
+   * Indexes the `$id`-bearing schemas of an element for the run. Transcluded elements aren't
+   * indexed: they're copies of structures indexed where they're defined,
+   * and in a document dereferenced in place their shared structure would be walked once per path.
    */
-  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 = 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 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 || 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) {
-      // prefix relative locations for entries belonging to the referenced document
-      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;
+  index$ids(element) {
+    if (this.schema$idIndex.has(element)) return;
+    const entries = [];
+    traverse(element, {
+      enter: path => {
+        if (this.isTranscluded(path.node)) {
+          path.skip();
+        } else if (isJSONSchemaElementWith$id(path.node)) {
+          entries.push({
+            schema: path.node,
+            $ids: collectSchema$ids(path)
+          });
         }
       }
-      // @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);
+    });
+    this.schema$idIndex.set(element, entries);
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
-    // ignore Reference Object without a string $ref, e.g. an empty YAML value
-    if (!isStringElement(referencingElement.$ref)) {
-      return;
-    }
+    // the fields of a Reference Object hold no references
+    path.skip();
 
-    // skip current referencing element as it's already been accessed
-    if (this.indirections.includes(referencingElement)) {
-      path.skip();
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (this.isTranscluded(referencingElement) || !isStringElement(referencingElement.$ref)) {
       return;
     }
-    const retrievalURI = this.toBaseURI(toValue(referencingElement.$ref));
+    const $ref = toValue(referencingElement.$ref);
+    const retrievalURI = this.toBaseURI($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, toValue(referencingElement.$ref));
-    const indirectionsSize = this.indirections.length;
+    const $refBaseURI = url.resolve(retrievalURI, $ref);
     try {
-      const reference = await this.toReference(toValue(referencingElement.$ref));
-      this.indirections.push(referencingElement);
+      const reference = await this.toReference($ref);
       const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
-
       // possibly non-semantic fragment
-      let referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
-
-      // applying semantics to a fragment
-      const referencedElementType = referencingElement.meta.get('referenced-element');
-      if (referencedElement.element !== referencedElementType && !isReferenceElement(referencedElement)) {
-        if (this.refractCache.has(referencedElement)) {
-          referencedElement = this.refractCache.get(referencedElement);
-        } else if (isReferenceLikeElement(referencedElement)) {
-          // handling generic indirect references
-          const sourceElement = referencedElement;
-          referencedElement = refractReference(referencedElement);
-          referencedElement.meta.set('referenced-element', referencedElementType);
-          this.refractCache.set(sourceElement, referencedElement);
-        } else {
-          // handling direct references
-          const sourceElement = referencedElement;
-          referencedElement = refract(referencedElement, {
-            element: referencedElementType
-          });
-          this.refractCache.set(sourceElement, referencedElement);
-        }
-      }
+      const referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
 
-      // detect direct or indirect reference
+      // detect direct reference
       if (referencingElement === referencedElement) {
         throw new ApiDOMStructuredError('Recursive Reference Object detected', {
-          $ref: toValue(referencingElement.$ref)
-        });
-      }
-
-      // detect maximum depth of dereferencing
-      if (this.indirections.length > this.options.dereference.maxDepth) {
-        throw new MaximumDereferenceDepthError(`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
+          $ref
         });
       }
 
-      // 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 ApiDOMStructuredError('Circular reference detected', {
-            $ref: toValue(referencingElement.$ref)
+      // a reference without an expected type reads its target as its own type
+      const type = toValue(referencingElement.meta.get('referenced-element')) ?? referencedElement.element;
+      await this.addTransclusion(path, {
+        source: referencedElement,
+        type,
+        reference,
+        context: {
+          ancestorSchema$ids: []
+        }
+      }, {
+        toTranscludedElement: (element, target) => {
+          // a chain of Reference Objects leading back to itself never reaches a value
+          if (isReferenceElement(target)) return element;
+          const reusingElement = element;
+          /**
+           * Creating a new version of referenced element to avoid modifying the original one.
+           */
+          const mergedElement = cloneShallow(target);
+          // annotate fragment with info about original Reference element
+          mergedElement.meta.set('ref-fields', {
+            $ref,
+            description: toValue(reusingElement.get('description')),
+            summary: toValue(reusingElement.get('summary'))
           });
-        } else if (this.options.dereference.circular === 'replace') {
-          const refElement = new RefElement($refBaseURI, {
-            type: referencingElement.element,
+          // annotate fragment with info about origin and type
+          mergedElement.meta.set('ref-origin', reference.uri);
+          mergedElement.meta.set('ref-type', element.element);
+
+          // override description and summary (outer has higher priority then inner)
+          if (isObjectElement(target) && isObjectElement(mergedElement)) {
+            const fields = fixedFields(target, {
+              indexed: true
+            });
+            if (reusingElement.hasKey('description') && Object.hasOwn(fields, 'description')) {
+              mergedElement.remove('description');
+              mergedElement.set('description', reusingElement.get('description'));
+            }
+            if (reusingElement.hasKey('summary') && Object.hasOwn(fields, 'summary')) {
+              mergedElement.remove('summary');
+              mergedElement.set('summary', reusingElement.get('summary'));
+            }
+          }
+          return mergedElement;
+        },
+        circular: {
+          uri: $refBaseURI,
+          meta: {
             uri: reference.uri,
-            $ref: toValue(referencingElement.$ref)
-          });
-          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-          const replacement = replacer(refElement);
-          path.replaceWith(replacement);
-          path.skip();
-          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 || isReferenceElement(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
-        if (shouldDetectCircular) {
-          this.visited.add(referencedElement);
+            $ref
+          },
+          details: {
+            $ref
+          }
         }
-        directAncestors.add(referencingElement);
-        const visitor = new OpenAPI3_1DereferenceVisitor({
-          reference,
-          indirections: [...this.indirections],
-          options: this.options,
-          refractCache: this.refractCache,
-          schema$idIndex: this.schema$idIndex,
-          visited: this.visited,
-          ancestors: ancestorsLineage
-        });
-        referencedElement = await traverseAsync(referencedElement, visitor, {
-          mutable: true,
-          skipVisited: 'skip'
-        });
-        directAncestors.delete(referencingElement);
-      }
-
-      /**
-       * Creating a new version of referenced element to avoid modifying the original one.
-       */
-      const mergedElement = cloneShallow(referencedElement);
-      // annotate fragment with info about original Reference element
-      mergedElement.meta.set('ref-fields', {
-        $ref: toValue(referencingElement.$ref),
-        // @ts-ignore
-        description: toValue(referencingElement.description),
-        // @ts-ignore
-        summary: 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 (isObjectElement(referencedElement) && isObjectElement(mergedElement)) {
-        const fields = 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 = 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 (!isStringElement(referencingElement.$ref)) {
+    if (this.isTranscluded(referencingElement)) {
+      path.skip();
       return;
     }
 
-    // skip current referencing element as it's already been accessed
-    if (this.indirections.includes(referencingElement)) {
-      path.skip();
+    // ignore PathItemElement without $ref field
+    if (!isStringElement(referencingElement.$ref)) {
       return;
     }
-    const retrievalURI = this.toBaseURI(toValue(referencingElement.$ref));
+    const $ref = toValue(referencingElement.$ref);
+    const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
     const isExternalReference = !isInternalReference;
 
@@ -414,131 +263,72 @@ class OpenAPI3_1DereferenceVisitor {
       // skip traversing this Path Item element but traverse all it's child elements
       return;
     }
-    const $refBaseURI = url.resolve(retrievalURI, toValue(referencingElement.$ref));
-    const indirectionsSize = this.indirections.length;
+    const $refBaseURI = url.resolve(retrievalURI, $ref);
     try {
-      const reference = await this.toReference(toValue(referencingElement.$ref));
-      this.indirections.push(referencingElement);
+      const reference = await this.toReference($ref);
       const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
-
       // possibly non-semantic referenced element
-      let referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
+      const referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
 
-      // applying semantics to a referenced element
-      if (!isPathItemElement(referencedElement)) {
-        if (this.refractCache.has(referencedElement)) {
-          referencedElement = this.refractCache.get(referencedElement);
-        } else {
-          const sourceElement = referencedElement;
-          referencedElement = refractPathItem(referencedElement);
-          this.refractCache.set(sourceElement, referencedElement);
-        }
-      }
-
-      // detect direct or indirect reference
+      // detect direct reference
       if (referencingElement === referencedElement) {
         throw new ApiDOMStructuredError('Recursive Path Item Object reference detected', {
-          $ref: toValue(referencingElement.$ref)
-        });
-      }
-
-      // detect maximum depth of dereferencing
-      if (this.indirections.length > this.options.dereference.maxDepth) {
-        throw new MaximumDereferenceDepthError(`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
+          $ref
         });
       }
+      await this.addTransclusion(path, {
+        source: referencedElement,
+        type: 'pathItem',
+        reference,
+        context: {
+          ancestorSchema$ids: []
+        }
+      }, {
+        toTranscludedElement: (element, target) => {
+          if (!isPathItemElement(target)) return target;
+
+          /**
+           * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
+           */
+          const mergedElement = cloneShallow(target);
+          // existing keywords from referencing PathItemElement overrides ones from referenced element
+          element.forEach((value, keyElement, item) => {
+            mergedElement.remove(toValue(keyElement));
+            mergedElement.content.push(item);
+          });
+          mergedElement.remove('$ref');
 
-      // 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 ApiDOMStructuredError('Circular reference detected', {
-            $ref: toValue(referencingElement.$ref)
+          // annotate referenced element with info about original referencing element
+          mergedElement.meta.set('ref-fields', {
+            $ref
           });
-        } else if (this.options.dereference.circular === 'replace') {
-          const refElement = new RefElement($refBaseURI, {
-            type: referencingElement.element,
+          // annotate referenced element with info about origin and type
+          mergedElement.meta.set('ref-origin', reference.uri);
+          mergedElement.meta.set('ref-type', element.element);
+          return mergedElement;
+        },
+        aliasField: '$ref',
+        circular: {
+          uri: $refBaseURI,
+          meta: {
             uri: reference.uri,
-            $ref: toValue(referencingElement.$ref)
-          });
-          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-          const replacement = replacer(refElement);
-          path.replaceWith(replacement);
-          path.skip();
-          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 || isPathItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
-        if (shouldDetectCircular) {
-          this.visited.add(referencedElement);
+            $ref
+          },
+          details: {
+            $ref
+          }
         }
-        directAncestors.add(referencingElement);
-        const visitor = new OpenAPI3_1DereferenceVisitor({
-          reference,
-          indirections: [...this.indirections],
-          options: this.options,
-          refractCache: this.refractCache,
-          schema$idIndex: this.schema$idIndex,
-          visited: this.visited,
-          ancestors: ancestorsLineage
-        });
-        referencedElement = await traverseAsync(referencedElement, visitor, {
-          mutable: true,
-          skipVisited: 'skip'
-        });
-        directAncestors.delete(referencingElement);
-      }
-
-      /**
-       * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
-       */
-      if (isPathItemElement(referencedElement)) {
-        const mergedElement = cloneShallow(referencedElement);
-        // existing keywords from referencing PathItemElement overrides ones from referenced element
-        referencingElement.forEach((value, keyElement, item) => {
-          mergedElement.remove(toValue(keyElement));
-          mergedElement.content.push(item);
-        });
-        mergedElement.remove('$ref');
-
-        // annotate referenced element with info about original referencing element
-        mergedElement.meta.set('ref-fields', {
-          $ref: 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 = 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;
+    if (this.isTranscluded(linkElement)) {
+      path.skip();
+      return;
+    }
 
     // ignore LinkElement without operationRef or operationId field
     if (!isStringElement(linkElement.operationRef) && !isStringElement(linkElement.operationId)) {
@@ -553,11 +343,11 @@ class OpenAPI3_1DereferenceVisitor {
       });
     }
     try {
-      let operationElement;
       if (isStringElement(linkElement.operationRef)) {
+        const operationRef = toValue(linkElement.operationRef);
         // possibly non-semantic referenced element
-        const jsonPointer = URIFragmentIdentifier.fromURIReference(toValue(linkElement.operationRef));
-        const retrievalURI = this.toBaseURI(toValue(linkElement.operationRef));
+        const jsonPointer = URIFragmentIdentifier.fromURIReference(operationRef);
+        const retrievalURI = this.toBaseURI(operationRef);
         const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
         const isExternalReference = !isInternalReference;
 
@@ -571,51 +361,56 @@ class OpenAPI3_1DereferenceVisitor {
           // skip traversing this Link element but traverse all it's child elements
           return;
         }
-        const reference = await this.toReference(toValue(linkElement.operationRef));
-        operationElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
-        // applying semantics to a referenced element
-        if (!isOperationElement(operationElement)) {
-          if (this.refractCache.has(operationElement)) {
-            operationElement = this.refractCache.get(operationElement);
-          } else {
-            const sourceElement = operationElement;
-            operationElement = refractOperation(operationElement);
-            this.refractCache.set(sourceElement, operationElement);
+        const reference = await this.toReference(operationRef);
+        const operationElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
+        await this.addAttachment(path, {
+          source: operationElement,
+          type: 'operation',
+          reference,
+          context: {
+            ancestorSchema$ids: []
           }
-        }
-        // create shallow clone to be able to annotate with metadata
-        operationElement = 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 = cloneShallow(linkElement);
-        linkElementCopy.operationRef?.meta.set('operation', operationElement);
-
-        /**
-         * Transclude Link Object containing Operation Object in its meta.
-         */
-        path.replaceWith(linkElementCopy);
+        }, (element, target) => {
+          // create shallow clone to be able to annotate with metadata
+          const operationCopy = cloneShallow(target);
+          // annotate operation element with info about origin and type
+          operationCopy.meta.set('ref-origin', reference.uri);
+          operationCopy.meta.set('ref-type', element.element);
+
+          /**
+           * Transclude Link Object containing Operation Object in its meta.
+           */
+          const linkElementCopy = cloneShallow(element);
+          linkElementCopy.operationRef?.meta.set('operation', operationCopy);
+          return linkElementCopy;
+        });
         return;
       }
-      if (isStringElement(linkElement.operationId)) {
-        const operationId = toValue(linkElement.operationId);
-        const reference = await this.toReference(url.unsanitize(this.reference.uri));
-        const operationPath = find(reference.value.result, path => isOperationElement(path.node) && isElement(path.node.operationId) && path.node.operationId.equals(operationId));
-        operationElement = operationPath?.node;
-        // OperationElement not found by its operationId
-        if (isUndefined(operationElement)) {
-          throw new ApiDOMStructuredError(`OperationElement(operationId=${operationId}) not found`, {
-            operationId
-          });
+      const operationId = toValue(linkElement.operationId);
+      const reference = await this.toReference(url.unsanitize(this.reference.uri));
+      const operationPath = find(reference.value.result, p => isOperationElement(p.node) && isElement(p.node.operationId) && p.node.operationId.equals(operationId));
+      const operationElement = operationPath?.node;
+      // OperationElement not found by its operationId
+      if (isUndefined(operationElement)) {
+        throw new ApiDOMStructuredError(`OperationElement(operationId=${operationId}) not found`, {
+          operationId
+        });
+      }
+      await this.addAttachment(path, {
+        source: operationElement,
+        type: 'operation',
+        reference,
+        context: {
+          ancestorSchema$ids: []
         }
-        const linkElementCopy = cloneShallow(linkElement);
-        linkElementCopy.operationId?.meta.set('operation', operationElement);
-
+      }, (element, target) => {
         /**
          * Transclude Link Object containing Operation Object in its meta.
          */
-        path.replaceWith(linkElementCopy);
-      }
+        const linkElementCopy = cloneShallow(element);
+        linkElementCopy.operationId?.meta.set('operation', target);
+        return linkElementCopy;
+      });
     } catch (error) {
       const refFieldName = isStringElement(linkElement.operationRef) ? 'operationRef' : 'operationId';
       const refFieldValue = isStringElement(linkElement.operationRef) ? toValue(linkElement.operationRef) : toValue(linkElement.operationId);
@@ -624,6 +419,10 @@ class OpenAPI3_1DereferenceVisitor {
   }
   async ExampleElement(path) {
     const exampleElement = path.node;
+    if (this.isTranscluded(exampleElement)) {
+      path.skip();
+      return;
+    }
 
     // ignore ExampleElement without externalValue field
     if (!isStringElement(exampleElement.externalValue)) {
@@ -637,7 +436,8 @@ class OpenAPI3_1DereferenceVisitor {
         externalValue: toValue(exampleElement.externalValue)
       });
     }
-    const retrievalURI = this.toBaseURI(toValue(exampleElement.externalValue));
+    const externalValue = toValue(exampleElement.externalValue);
+    const retrievalURI = this.toBaseURI(externalValue);
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
     const isExternalReference = !isInternalReference;
 
@@ -652,39 +452,44 @@ class OpenAPI3_1DereferenceVisitor {
       return;
     }
     try {
-      const reference = await this.toReference(toValue(exampleElement.externalValue));
-
-      // shallow clone of the referenced element
-      const valueElement = 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 = cloneShallow(exampleElement);
-      exampleElementCopy.value = valueElement;
-
-      /**
-       * Transclude Example Object containing external value.
-       */
-      path.replaceWith(exampleElementCopy);
+      const reference = await this.toReference(externalValue);
+      const valueSource = reference.value.result;
+      await this.addAttachment(path, {
+        source: valueSource,
+        type: valueSource.element,
+        reference,
+        context: {
+          ancestorSchema$ids: []
+        }
+      }, (element, target) => {
+        // shallow clone of the referenced element
+        const valueElement = cloneShallow(target);
+        // annotate element with info about origin and type
+        valueElement.meta.set('ref-origin', reference.uri);
+        valueElement.meta.set('ref-type', element.element);
+
+        /**
+         * Transclude Example Object containing external value.
+         */
+        const exampleElementCopy = cloneShallow(element);
+        exampleElementCopy.value = valueElement;
+        return exampleElementCopy;
+      });
     } catch (error) {
-      const externalValue = 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 (!isStringElement(referencingElement.$ref)) {
+    if (this.isTranscluded(referencingElement)) {
+      path.skip();
       return;
     }
 
-    // skip current referencing element as it's already been accessed
-    if (this.indirections.includes(referencingElement)) {
-      path.skip();
+    // skip current referencing schema as $ref keyword was not defined
+    if (!isStringElement(referencingElement.$ref)) {
       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));
@@ -727,10 +532,12 @@ class OpenAPI3_1DereferenceVisitor {
           try {
             // the fragment's $ids resolve against the base its enclosing chain
             // leaves in effect, which then also prefixes the located schema's chain
+            const fragmentAsSchema = this.toSchemaDocument(fragmentElement);
+            this.index$ids(fragmentAsSchema);
             ({
               element: referencedElement,
               ancestorSchema$ids
-            } = uriLocate(selector, maybeRefractToSchemaElement(fragmentElement), {
+            } = uriLocate(selector, fragmentAsSchema, {
               baseURI: rootBaseURI,
               index: this.schema$idIndex
             }));
@@ -741,15 +548,16 @@ class OpenAPI3_1DereferenceVisitor {
             }
             // the document index is rooted at the document, so the located chain
             // is already document-relative and takes no prefix
+            const documentAsSchema = this.toSchemaDocument(documentElement);
+            this.index$ids(documentAsSchema);
             ({
               element: referencedElement,
               ancestorSchema$ids
-            } = uriLocate(selector, maybeRefractToSchemaElement(documentElement), {
+            } = uriLocate(selector, documentAsSchema, {
               baseURI: reference.uri,
               index: this.schema$idIndex
             }));
           }
-          referencedElement = maybeRefractToSchemaElement(referencedElement);
 
           // ignore resolving internal Schema Objects
           if (!this.options.resolve.internal && isInternalReference) {
@@ -779,12 +587,10 @@ class OpenAPI3_1DereferenceVisitor {
           }
           reference = await this.toReference(url.unsanitize($refBaseURI));
           const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
-          const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
           ({
             element: referencedElement,
             ancestorSchema$ids
-          } = jsonPointerLocate(referenceAsSchema, selector));
-          referencedElement = maybeRefractToSchemaElement(referencedElement);
+          } = jsonPointerLocate(this.toSchemaDocument(reference.value.result), selector));
         }
       } catch (error) {
         /**
@@ -809,12 +615,10 @@ class OpenAPI3_1DereferenceVisitor {
             }
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = uriToAnchor($refBaseURI);
-            const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
             ({
               element: referencedElement,
               ancestorSchema$ids
-            } = $anchorLocate(selector, referenceAsSchema));
-            referencedElement = maybeRefractToSchemaElement(referencedElement);
+            } = $anchorLocate(selector, this.toSchemaDocument(reference.value.result)));
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
             retrievalURI = this.toBaseURI($refBaseURI);
@@ -833,137 +637,82 @@ class OpenAPI3_1DereferenceVisitor {
             }
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
-            const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
             ({
               element: referencedElement,
               ancestorSchema$ids
-            } = jsonPointerLocate(referenceAsSchema, selector));
-            referencedElement = maybeRefractToSchemaElement(referencedElement);
+            } = jsonPointerLocate(this.toSchemaDocument(reference.value.result), selector));
           }
         } else {
           throw error;
         }
       }
-      this.indirections.push(referencingElement);
+      const $ref = toValue(referencingElement.$ref);
 
-      // detect direct or indirect reference
+      // detect direct reference
       if (referencingElement === referencedElement) {
         throw new ApiDOMStructuredError('Recursive Schema Object reference detected', {
-          $ref: toValue(referencingElement.$ref)
+          $ref
         });
       }
-
-      // detect maximum depth of dereferencing
-      if (this.indirections.length > this.options.dereference.maxDepth) {
-        throw new MaximumDereferenceDepthError(`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 ApiDOMStructuredError('Circular reference detected', {
-            $ref: toValue(referencingElement.$ref)
+      const origin = reference.uri;
+      // a Schema Object $ref reads whatever it points at as a Schema Object
+      await this.addTransclusion(path, {
+        source: referencedElement,
+        type: SCHEMA_TYPE,
+        reference,
+        context: {
+          ancestorSchema$ids
+        }
+      }, {
+        toTranscludedElement: (element, target) => {
+          // Boolean JSON Schemas
+          if (isBooleanJSONSchemaElement(target)) {
+            const booleanJsonSchemaElement = cloneDeep(target);
+            // annotate referenced element with info about original referencing element
+            booleanJsonSchemaElement.meta.set('ref-fields', {
+              $ref
+            });
+            // annotate referenced element with info about origin and type
+            booleanJsonSchemaElement.meta.set('ref-origin', origin);
+            booleanJsonSchemaElement.meta.set('ref-type', element.element);
+            return booleanJsonSchemaElement;
+          }
+          if (!isSchemaElement(target)) return target;
+
+          /**
+           * Creating a new version of Schema Object by merging fields from referenced Schema Object with referencing one.
+           */
+          const mergedElement = cloneShallow(target);
+          // existing keywords from referencing schema overrides ones from referenced schema
+          element.forEach((value, keyElement, item) => {
+            mergedElement.remove(toValue(keyElement));
+            mergedElement.content.push(item);
           });
-        } else if (this.options.dereference.circular === 'replace') {
-          const refElement = new RefElement($refBaseURI, {
-            type: referencingElement.element,
-            uri: reference.uri,
-            $ref: toValue(referencingElement.$ref)
+          mergedElement.remove('$ref');
+          // annotate referenced element with info about original referencing element
+          mergedElement.meta.set('ref-fields', {
+            $ref
           });
-          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-          const replacement = replacer(refElement);
-          path.replaceWith(replacement);
-          path.skip();
-          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);
-      // content transplanted into the referencing site is traversed under that
-      // site's $id chain; a fragment enclosed by a different chain has its own
-      // $refs resolved in place first, by a nested visitor seeded with that chain
-      const hasDifferentEnclosingBase = resolveSchema$ids(reference.uri, ancestorSchema$ids) !== resolveSchema$ids(rootBaseURI, schema$idsOf(path.getAncestorNodes().reverse()));
-      if ((isExternalReference || isNonEntryDocument || hasDifferentEnclosingBase || isSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
-        if (shouldDetectCircular) {
-          this.visited.add(referencedElement);
+          // annotate fragment with info about origin and type
+          mergedElement.meta.set('ref-origin', origin);
+          mergedElement.meta.set('ref-type', element.element);
+          return mergedElement;
+        },
+        aliasField: '$ref',
+        circular: {
+          uri: $refBaseURI,
+          meta: {
+            uri: origin,
+            $ref
+          },
+          details: {
+            $ref
+          }
         }
-        directAncestors.add(referencingElement);
-        const visitor = new OpenAPI3_1DereferenceVisitor({
-          reference,
-          indirections: [...this.indirections],
-          options: this.options,
-          refractCache: this.refractCache,
-          schema$idIndex: this.schema$idIndex,
-          visited: this.visited,
-          ancestors: ancestorsLineage,
-          ancestorSchema$ids
-        });
-        referencedElement = await traverseAsync(referencedElement, visitor, {
-          mutable: true,
-          skipVisited: 'skip'
-        });
-        directAncestors.delete(referencingElement);
-      }
-
-      // Boolean JSON Schemas
-      if (isBooleanJSONSchemaElement(referencedElement)) {
-        const booleanJsonSchemaElement = cloneDeep(referencedElement);
-        // annotate referenced element with info about original referencing element
-        booleanJsonSchemaElement.meta.set('ref-fields', {
-          $ref: 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);
-        path.skip();
-        return;
-      }
-
-      /**
-       * Creating a new version of Schema Object by merging fields from referenced Schema Object with referencing one.
-       */
-      if (isSchemaElement(referencedElement)) {
-        const mergedElement = cloneShallow(referencedElement);
-        // existing keywords from referencing schema overrides ones from referenced schema
-        referencingElement.forEach((value, keyElement, item) => {
-          mergedElement.remove(toValue(keyElement));
-          mergedElement.content.push(item);
-        });
-        mergedElement.remove('$ref');
-        // annotate referenced element with info about original referencing element
-        mergedElement.meta.set('ref-fields', {
-          $ref: 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 = 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();
     }
   }
 }