@speclynx/apidom-reference 4.0.2 → 4.0.3

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

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

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

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

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

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

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

@@ -0,0 +1,158 @@
+import { Element, cloneDeep, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { traverseAsync } from '@speclynx/apidom-traverse';
+import { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+
+import DereferenceStrategy, { DereferenceStrategyOptions } from '../DereferenceStrategy.ts';
+import File from '../../../File.ts';
+import Reference from '../../../Reference.ts';
+import ReferenceSet from '../../../ReferenceSet.ts';
+import Arazzo1DereferenceVisitor from './visitor.ts';
+import { dereferenceSourceDescriptions } from './source-descriptions.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+
+export type {
+  default as DereferenceStrategy,
+  DereferenceStrategyOptions,
+} from '../DereferenceStrategy.ts';
+export type { default as File, FileOptions } from '../../../File.ts';
+export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
+export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
+export type { Arazzo1DereferenceVisitorOptions } from './visitor.ts';
+export type {
+  ReferenceOptions as ApiDOMReferenceOptions,
+  ReferenceBundleOptions as ApiDOMReferenceBundleOptions,
+  ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions,
+  ReferenceParseOptions as ApiDOMReferenceParseOptions,
+  ReferenceResolveOptions as ApiDOMReferenceResolveOptions,
+} from '../../../options/index.ts';
+export type { default as Parser, ParserOptions } from '../../../parse/parsers/Parser.ts';
+export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
+export type {
+  default as ResolveStrategy,
+  ResolveStrategyOptions,
+} from '../../../resolve/strategies/ResolveStrategy.ts';
+export type {
+  default as BundleStrategy,
+  BundleStrategyOptions,
+} from '../../../bundle/strategies/BundleStrategy.ts';
+export type { AncestorLineage } from '../../util.ts';
+
+/**
+ * @public
+ */
+export interface Arazzo1DereferenceStrategyOptions extends Omit<
+  DereferenceStrategyOptions,
+  'name'
+> {}
+
+/**
+ * @public
+ */
+class Arazzo1DereferenceStrategy extends DereferenceStrategy {
+  constructor(options?: Arazzo1DereferenceStrategyOptions) {
+    super({ ...(options ?? {}), name: 'arazzo-1' });
+  }
+
+  canDereference(file: File): boolean {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return isArazzoSpecification1Element(file.parseResult?.result);
+  }
+
+  async dereference(file: File, options: ReferenceOptions): Promise<Element> {
+    const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let refSet = immutableRefSet;
+    let reference: Reference;
+
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new Reference({ uri: file.uri, value: file.parseResult! });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find((ref) => ref.uri === file.uri)!;
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs
+        .map(
+          (ref) =>
+            new Reference({
+              ...ref,
+              value: cloneDeep(ref.value),
+            }),
+        )
+        .forEach((ref) => mutableRefSet.add(ref));
+      reference = mutableRefSet.find((ref) => ref.uri === file.uri)!;
+      refSet = mutableRefSet;
+    }
+
+    const visitor = new Arazzo1DereferenceVisitor({ reference, options });
+    const dereferencedElement = await traverseAsync(refSet.rootRef!.value, visitor, {
+      mutable: true,
+    });
+
+    /**
+     * Dereference source descriptions if option is enabled.
+     */
+    const shouldDereferenceSourceDescriptions =
+      options?.dereference?.strategyOpts?.[this.name]?.sourceDescriptions ??
+      options?.dereference?.strategyOpts?.sourceDescriptions;
+
+    if (shouldDereferenceSourceDescriptions) {
+      const sourceDescriptions = await dereferenceSourceDescriptions(
+        dereferencedElement as ParseResultElement,
+        reference.uri,
+        options,
+        this.name,
+      );
+      (dereferencedElement as ParseResultElement).push(...sourceDescriptions);
+    }
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs
+        .filter((ref) => ref.uri.startsWith('immutable://'))
+        .map(
+          (ref) =>
+            new Reference({
+              ...ref,
+              uri: ref.uri.replace(/^immutable:\/\//, ''),
+            }),
+        )
+        .forEach((ref) => immutableRefSet.add(ref));
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+
+    mutableRefSet.clean();
+
+    return dereferencedElement;
+  }
+}
+
+export { Arazzo1DereferenceVisitor };
+export {
+  resolveSchema$refField,
+  resolveSchema$idField,
+  maybeRefractToJSONSchemaElement,
+} from './util.ts';
+export { dereferenceSourceDescriptions } from './source-descriptions.ts';
+
+export default Arazzo1DereferenceStrategy;

package/src/dereference/strategies/arazzo-1/selectors/$anchor.cjs

@@ -0,0 +1,12 @@
+"use strict";
+
+exports.__esModule = true;
+exports.uriToAnchor = exports.parse = exports.isAnchor = exports.evaluate = exports.JsonSchema$anchorError = exports.InvalidJsonSchema$anchorError = exports.EvaluationJsonSchema$anchorError = void 0;
+var _$anchor = require("../../openapi-3-1/selectors/$anchor.cjs");
+exports.isAnchor = _$anchor.isAnchor;
+exports.uriToAnchor = _$anchor.uriToAnchor;
+exports.parse = _$anchor.parse;
+exports.evaluate = _$anchor.evaluate;
+exports.EvaluationJsonSchema$anchorError = _$anchor.EvaluationJsonSchema$anchorError;
+exports.InvalidJsonSchema$anchorError = _$anchor.InvalidJsonSchema$anchorError;
+exports.JsonSchema$anchorError = _$anchor.JsonSchema$anchorError;