@speclynx/apidom-reference 4.0.3 → 4.0.4

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

@@ -1,128 +0,0 @@
-import { Element, isElement, cloneDeep } from '@speclynx/apidom-datamodel';
-import { traverseAsync } from '@speclynx/apidom-traverse';
-
-import DereferenceStrategy, { DereferenceStrategyOptions } from '../DereferenceStrategy.ts';
-import File from '../../../File.ts';
-import Reference from '../../../Reference.ts';
-import ReferenceSet from '../../../ReferenceSet.ts';
-import ApiDOMDereferenceVisitor from './visitor.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 { ApiDOMDereferenceVisitorOptions } 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';
-
-/**
- * @public
- */
-export interface ApiDOMDereferenceStrategyOptions extends Omit<
-  DereferenceStrategyOptions,
-  'name'
-> {}
-
-/**
- * @public
- */
-class ApiDOMDereferenceStrategy extends DereferenceStrategy {
-  constructor(options?: ApiDOMDereferenceStrategyOptions) {
-    super({ ...(options ?? {}), name: 'apidom' });
-  }
-
-  canDereference(file: File) {
-    return (
-      file.mediaType.startsWith('application/vnd.apidom') && isElement(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;
-
-    // determine the initial 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 ApiDOMDereferenceVisitor({ reference: reference!, options });
-    const dereferencedElement = await traverseAsync(refSet.rootRef!.value, visitor, {
-      mutable: true,
-    });
-
-    /**
-     * 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 { ApiDOMDereferenceVisitor };
-export default ApiDOMDereferenceStrategy;

package/src/dereference/strategies/apidom/selectors/element-id.ts

@@ -1,48 +0,0 @@
-import { isUndefined } from 'ramda-adjunct';
-import { Element, isElement } from '@speclynx/apidom-datamodel';
-import { toValue } from '@speclynx/apidom-core';
-import { filter, type Path } from '@speclynx/apidom-traverse';
-
-import EvaluationElementIdError from '../../../../errors/EvaluationElementIdError.ts';
-
-const getElementID = (element: Element): string => {
-  const id = element.meta.get('id');
-  // handle both raw string (new format) and StringElement (legacy Refract without __meta_raw__)
-  return isElement(id) ? (toValue(id) as string) : (id as string);
-};
-
-const hasElementID = (path: Path<Element>): boolean => {
-  if (!path.node.hasMetaProperty('id')) return false;
-  const id = getElementID(path.node);
-  return typeof id === 'string' && id !== '';
-};
-
-/**
- * Evaluates element ID against ApiDOM fragment.
- * @public
- */
-export const evaluate = <T extends Element>(elementID: string, element: T): Element | undefined => {
-  const { cache } = evaluate;
-  // warm the cache
-  if (!cache.has(element)) {
-    const pathsWithID = filter(element, hasElementID);
-    cache.set(
-      element,
-      pathsWithID.map((path) => path.node),
-    );
-  }
-
-  // search for the matching element
-  const result = cache.get(element).find((e: Element) => {
-    return getElementID(e) === elementID;
-  });
-
-  if (isUndefined(result)) {
-    throw new EvaluationElementIdError(`Evaluation failed on element ID: "${elementID}"`);
-  }
-
-  return result;
-};
-evaluate.cache = new WeakMap();
-
-export { EvaluationElementIdError };

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

@@ -1,316 +0,0 @@
-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.ts

@@ -1,158 +0,0 @@
-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.ts

@@ -1,9 +0,0 @@
-export {
-  isAnchor,
-  uriToAnchor,
-  parse,
-  evaluate,
-  EvaluationJsonSchema$anchorError,
-  InvalidJsonSchema$anchorError,
-  JsonSchema$anchorError,
-} from '../../openapi-3-1/selectors/$anchor.ts';

package/src/dereference/strategies/arazzo-1/selectors/uri.ts

@@ -1,5 +0,0 @@
-export {
-  evaluate,
-  EvaluationJsonSchemaUriError,
-  JsonSchemaUriError,
-} from '../../openapi-3-1/selectors/uri.ts';