@speclynx/apidom-reference 3.2.1 → 4.0.0

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

@@ -1,100 +0,0 @@
-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/selectors/$anchor.cjs

@@ -1,12 +0,0 @@
-"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;

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

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

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

@@ -1,8 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.evaluate = exports.JsonSchemaUriError = exports.EvaluationJsonSchemaUriError = void 0;
-var _uri = require("../../openapi-3-1/selectors/uri.cjs");
-exports.evaluate = _uri.evaluate;
-exports.EvaluationJsonSchemaUriError = _uri.EvaluationJsonSchemaUriError;
-exports.JsonSchemaUriError = _uri.JsonSchemaUriError;

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

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

package/src/dereference/strategies/arazzo-1/source-descriptions.cjs

@@ -1,248 +0,0 @@
-"use strict";
-
-var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
-exports.__esModule = true;
-exports.dereferenceSourceDescriptions = dereferenceSourceDescriptions;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
-var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
-var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
-var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
-var _apidomCore = require("@speclynx/apidom-core");
-var url = _interopRequireWildcard(require("../../../util/url.cjs"));
-var _util = require("../../../options/util.cjs");
-var _index = _interopRequireWildcard(require("../../index.cjs"));
-/**
- * Dereferences a single source description element.
- * Returns ParseResultElement on success, or with annotation if skipped.
- */
-async function dereferenceSourceDescription(sourceDescription, ctx) {
-  const parseResult = new _apidomDatamodel.ParseResultElement();
-  if (!(0, _apidomNsArazzo.isSourceDescriptionElement)(sourceDescription)) {
-    const annotation = new _apidomDatamodel.AnnotationElement('Element is not a valid SourceDescriptionElement. Skipping');
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // set class and metadata from source description element
-  parseResult.classes.push('source-description');
-  if ((0, _apidomDatamodel.isStringElement)(sourceDescription.name)) parseResult.setMetaProperty('name', (0, _apidomCore.toValue)(sourceDescription.name));
-  if ((0, _apidomDatamodel.isStringElement)(sourceDescription.type)) parseResult.setMetaProperty('type', (0, _apidomCore.toValue)(sourceDescription.type));
-  const sourceDescriptionURI = (0, _apidomCore.toValue)(sourceDescription.url);
-  if (typeof sourceDescriptionURI !== 'string') {
-    const annotation = new _apidomDatamodel.AnnotationElement('Source description URL is missing or not a string. Skipping');
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // normalize URI for consistent cycle detection and refSet cache key matching
-  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
-  parseResult.setMetaProperty('retrievalURI', retrievalURI);
-
-  // skip if already visited (cycle detection)
-  if (ctx.visitedUrls.has(retrievalURI)) {
-    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-  ctx.visitedUrls.add(retrievalURI);
-
-  // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
-  const existingParseResult = sourceDescription.meta.get('parseResult');
-  try {
-    let sourceDescriptionDereferenced;
-    if ((0, _apidomDatamodel.isParseResultElement)(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      sourceDescriptionDereferenced = await (0, _index.dereferenceApiDOM)(existingParseResult, (0, _util.merge)(ctx.options, {
-        parse: {
-          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
-        },
-        resolve: {
-          baseURI: retrievalURI
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
-            }
-          }
-        }
-      }));
-    } else {
-      // no existing parse result - fetch, parse, and dereference
-      sourceDescriptionDereferenced = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
-        parse: {
-          mediaType: 'text/plain' // allow parser plugin detection
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
-            }
-          }
-        }
-      }));
-    }
-
-    // merge dereferenced result into our parse result
-    for (const item of sourceDescriptionDereferenced) {
-      parseResult.push(item);
-    }
-  } catch (error) {
-    // create error annotation instead of failing entire dereference
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new _apidomDatamodel.AnnotationElement(`Error dereferencing source description "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // only allow OpenAPI and Arazzo as source descriptions
-  const {
-    api: sourceDescriptionAPI
-  } = parseResult;
-  const isOpenApi = (0, _apidomNsOpenapi.isSwaggerElement)(sourceDescriptionAPI) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(sourceDescriptionAPI) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(sourceDescriptionAPI);
-  const isArazzo = (0, _apidomNsArazzo.isArazzoSpecification1Element)(sourceDescriptionAPI);
-  if (!isOpenApi && !isArazzo) {
-    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // validate declared type matches actual dereferenced type
-  const declaredType = (0, _apidomCore.toValue)(sourceDescription.type);
-  if (typeof declaredType === 'string') {
-    if (declaredType === 'openapi' && !isOpenApi) {
-      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but dereferenced as Arazzo document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    } else if (declaredType === 'arazzo' && !isArazzo) {
-      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but dereferenced as OpenAPI document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    }
-  }
-  return parseResult;
-}
-
-/**
- * Dereferences source descriptions from an Arazzo document.
- *
- * Each source description result is attached to its corresponding
- * SourceDescriptionElement's meta as 'parseResult' for easy access,
- * regardless of success or failure. On failure, the ParseResultElement
- * contains annotations explaining what went wrong.
- *
- * @param parseResult - ParseResult containing a parsed (optionally dereferenced) Arazzo specification
- * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
- * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
- *   in `dereference.strategyOpts` to filter which source descriptions to process.
- * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
- * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and metadata: name, type, retrievalURI).
- *   May return early with a single-element array containing a warning annotation when:
- *   - The API is not an Arazzo specification
- *   - The sourceDescriptions field is missing or not an array
- *   - Maximum dereference depth is exceeded (error annotation)
- *   Returns an empty array when no source description names match the filter.
- *
- * @example
- * ```typescript
- * import { toValue } from '@speclynx/apidom-core';
- *
- * // Dereference all source descriptions
- * await dereferenceSourceDescriptions(parseResult, uri, options);
- *
- * // Filter by name
- * await dereferenceSourceDescriptions(parseResult, uri, mergeOptions(options, {
- *   dereference: { strategyOpts: { sourceDescriptions: ['petStore'] } },
- * }));
- *
- * // Access dereferenced document from source description element
- * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
- * const dereferencedDoc = sourceDesc.meta.get('parseResult');
- * const retrievalURI = toValue(dereferencedDoc.meta.get('retrievalURI'));
- * ```
- *
- * @public
- */
-async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
-  const baseURI = url.sanitize(url.stripHash(parseResultRetrievalURI));
-  const results = [];
-
-  // get API from dereferenced parse result
-  const {
-    api
-  } = parseResult;
-
-  /**
-   * Validate prerequisites for dereferencing source descriptions.
-   * Return warning annotations if validation fails.
-   */
-  if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(api)) {
-    const annotation = new _apidomDatamodel.AnnotationElement('Cannot dereference source descriptions: API is not an Arazzo specification');
-    annotation.classes.push('warning');
-    return [new _apidomDatamodel.ParseResultElement([annotation])];
-  }
-  if (!(0, _apidomDatamodel.isArrayElement)(api.sourceDescriptions)) {
-    const annotation = new _apidomDatamodel.AnnotationElement('Cannot dereference source descriptions: sourceDescriptions field is missing or not an array');
-    annotation.classes.push('warning');
-    return [new _apidomDatamodel.ParseResultElement([annotation])];
-  }
-
-  // user config: strategy-specific options take precedence over global strategyOpts
-  const maxDepth = options?.dereference?.strategyOpts?.[strategyName]?.sourceDescriptionsMaxDepth ?? options?.dereference?.strategyOpts?.sourceDescriptionsMaxDepth ?? +Infinity;
-
-  // recursion state comes from strategy-specific options
-  const sharedOpts = options?.dereference?.strategyOpts?.[strategyName] ?? {};
-  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
-  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
-
-  // add current file to visited URLs to prevent cycles
-  visitedUrls.add(baseURI);
-  if (currentDepth >= maxDepth) {
-    const annotation = new _apidomDatamodel.AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${baseURI}"`);
-    annotation.classes.push('error');
-    const parseResult = new _apidomDatamodel.ParseResultElement([annotation]);
-    parseResult.classes.push('source-description');
-    return [parseResult];
-  }
-  const ctx = {
-    baseURI,
-    options,
-    strategyName,
-    currentDepth,
-    visitedUrls
-  };
-
-  // determine which source descriptions to dereference (array filters by name)
-  const sourceDescriptionsOption = options?.dereference?.strategyOpts?.[strategyName]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
-  const sourceDescriptions = Array.isArray(sourceDescriptionsOption) ? api.sourceDescriptions.filter(sd => {
-    if (!(0, _apidomNsArazzo.isSourceDescriptionElement)(sd)) return false;
-    const name = (0, _apidomCore.toValue)(sd.name);
-    return typeof name === 'string' && sourceDescriptionsOption.includes(name);
-  }) : api.sourceDescriptions;
-
-  // process sequentially to ensure proper cycle detection with shared visitedUrls
-  for (const sourceDescription of sourceDescriptions) {
-    const sourceDescriptionDereferenceResult = await dereferenceSourceDescription(sourceDescription, ctx);
-    // always attach result (even on failure - contains annotations)
-    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult);
-    results.push(sourceDescriptionDereferenceResult);
-  }
-  return results;
-}

package/src/dereference/strategies/arazzo-1/source-descriptions.mjs

@@ -1,243 +0,0 @@
-import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, isParseResultElement } from '@speclynx/apidom-datamodel';
-import { isArazzoSpecification1Element, isSourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
-import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
-import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
-import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
-import { toValue } from '@speclynx/apidom-core';
-import * as url from "../../../util/url.mjs";
-import { merge as mergeOptions } from "../../../options/util.mjs";
-import dereference, { dereferenceApiDOM } from "../../index.mjs";
-/**
- * Dereferences a single source description element.
- * Returns ParseResultElement on success, or with annotation if skipped.
- */
-async function dereferenceSourceDescription(sourceDescription, ctx) {
-  const parseResult = new ParseResultElement();
-  if (!isSourceDescriptionElement(sourceDescription)) {
-    const annotation = new AnnotationElement('Element is not a valid SourceDescriptionElement. Skipping');
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // set class and metadata from source description element
-  parseResult.classes.push('source-description');
-  if (isStringElement(sourceDescription.name)) parseResult.setMetaProperty('name', toValue(sourceDescription.name));
-  if (isStringElement(sourceDescription.type)) parseResult.setMetaProperty('type', toValue(sourceDescription.type));
-  const sourceDescriptionURI = toValue(sourceDescription.url);
-  if (typeof sourceDescriptionURI !== 'string') {
-    const annotation = new AnnotationElement('Source description URL is missing or not a string. Skipping');
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // normalize URI for consistent cycle detection and refSet cache key matching
-  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
-  parseResult.setMetaProperty('retrievalURI', retrievalURI);
-
-  // skip if already visited (cycle detection)
-  if (ctx.visitedUrls.has(retrievalURI)) {
-    const annotation = new AnnotationElement(`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-  ctx.visitedUrls.add(retrievalURI);
-
-  // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
-  const existingParseResult = sourceDescription.meta.get('parseResult');
-  try {
-    let sourceDescriptionDereferenced;
-    if (isParseResultElement(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      sourceDescriptionDereferenced = await dereferenceApiDOM(existingParseResult, mergeOptions(ctx.options, {
-        parse: {
-          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
-        },
-        resolve: {
-          baseURI: retrievalURI
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
-            }
-          }
-        }
-      }));
-    } else {
-      // no existing parse result - fetch, parse, and dereference
-      sourceDescriptionDereferenced = await dereference(retrievalURI, mergeOptions(ctx.options, {
-        parse: {
-          mediaType: 'text/plain' // allow parser plugin detection
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
-            }
-          }
-        }
-      }));
-    }
-
-    // merge dereferenced result into our parse result
-    for (const item of sourceDescriptionDereferenced) {
-      parseResult.push(item);
-    }
-  } catch (error) {
-    // create error annotation instead of failing entire dereference
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new AnnotationElement(`Error dereferencing source description "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // only allow OpenAPI and Arazzo as source descriptions
-  const {
-    api: sourceDescriptionAPI
-  } = parseResult;
-  const isOpenApi = isSwaggerElement(sourceDescriptionAPI) || isOpenApi3_0Element(sourceDescriptionAPI) || isOpenApi3_1Element(sourceDescriptionAPI);
-  const isArazzo = isArazzoSpecification1Element(sourceDescriptionAPI);
-  if (!isOpenApi && !isArazzo) {
-    const annotation = new AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // validate declared type matches actual dereferenced type
-  const declaredType = toValue(sourceDescription.type);
-  if (typeof declaredType === 'string') {
-    if (declaredType === 'openapi' && !isOpenApi) {
-      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but dereferenced as Arazzo document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    } else if (declaredType === 'arazzo' && !isArazzo) {
-      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but dereferenced as OpenAPI document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    }
-  }
-  return parseResult;
-}
-
-/**
- * Dereferences source descriptions from an Arazzo document.
- *
- * Each source description result is attached to its corresponding
- * SourceDescriptionElement's meta as 'parseResult' for easy access,
- * regardless of success or failure. On failure, the ParseResultElement
- * contains annotations explaining what went wrong.
- *
- * @param parseResult - ParseResult containing a parsed (optionally dereferenced) Arazzo specification
- * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
- * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
- *   in `dereference.strategyOpts` to filter which source descriptions to process.
- * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
- * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and metadata: name, type, retrievalURI).
- *   May return early with a single-element array containing a warning annotation when:
- *   - The API is not an Arazzo specification
- *   - The sourceDescriptions field is missing or not an array
- *   - Maximum dereference depth is exceeded (error annotation)
- *   Returns an empty array when no source description names match the filter.
- *
- * @example
- * ```typescript
- * import { toValue } from '@speclynx/apidom-core';
- *
- * // Dereference all source descriptions
- * await dereferenceSourceDescriptions(parseResult, uri, options);
- *
- * // Filter by name
- * await dereferenceSourceDescriptions(parseResult, uri, mergeOptions(options, {
- *   dereference: { strategyOpts: { sourceDescriptions: ['petStore'] } },
- * }));
- *
- * // Access dereferenced document from source description element
- * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
- * const dereferencedDoc = sourceDesc.meta.get('parseResult');
- * const retrievalURI = toValue(dereferencedDoc.meta.get('retrievalURI'));
- * ```
- *
- * @public
- */
-export async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
-  const baseURI = url.sanitize(url.stripHash(parseResultRetrievalURI));
-  const results = [];
-
-  // get API from dereferenced parse result
-  const {
-    api
-  } = parseResult;
-
-  /**
-   * Validate prerequisites for dereferencing source descriptions.
-   * Return warning annotations if validation fails.
-   */
-  if (!isArazzoSpecification1Element(api)) {
-    const annotation = new AnnotationElement('Cannot dereference source descriptions: API is not an Arazzo specification');
-    annotation.classes.push('warning');
-    return [new ParseResultElement([annotation])];
-  }
-  if (!isArrayElement(api.sourceDescriptions)) {
-    const annotation = new AnnotationElement('Cannot dereference source descriptions: sourceDescriptions field is missing or not an array');
-    annotation.classes.push('warning');
-    return [new ParseResultElement([annotation])];
-  }
-
-  // user config: strategy-specific options take precedence over global strategyOpts
-  const maxDepth = options?.dereference?.strategyOpts?.[strategyName]?.sourceDescriptionsMaxDepth ?? options?.dereference?.strategyOpts?.sourceDescriptionsMaxDepth ?? +Infinity;
-
-  // recursion state comes from strategy-specific options
-  const sharedOpts = options?.dereference?.strategyOpts?.[strategyName] ?? {};
-  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
-  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
-
-  // add current file to visited URLs to prevent cycles
-  visitedUrls.add(baseURI);
-  if (currentDepth >= maxDepth) {
-    const annotation = new AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${baseURI}"`);
-    annotation.classes.push('error');
-    const parseResult = new ParseResultElement([annotation]);
-    parseResult.classes.push('source-description');
-    return [parseResult];
-  }
-  const ctx = {
-    baseURI,
-    options,
-    strategyName,
-    currentDepth,
-    visitedUrls
-  };
-
-  // determine which source descriptions to dereference (array filters by name)
-  const sourceDescriptionsOption = options?.dereference?.strategyOpts?.[strategyName]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
-  const sourceDescriptions = Array.isArray(sourceDescriptionsOption) ? api.sourceDescriptions.filter(sd => {
-    if (!isSourceDescriptionElement(sd)) return false;
-    const name = toValue(sd.name);
-    return typeof name === 'string' && sourceDescriptionsOption.includes(name);
-  }) : api.sourceDescriptions;
-
-  // process sequentially to ensure proper cycle detection with shared visitedUrls
-  for (const sourceDescription of sourceDescriptions) {
-    const sourceDescriptionDereferenceResult = await dereferenceSourceDescription(sourceDescription, ctx);
-    // always attach result (even on failure - contains annotations)
-    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult);
-    results.push(sourceDescriptionDereferenceResult);
-  }
-  return results;
-}

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

@@ -1,37 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.resolveSchema$refField = exports.resolveSchema$idField = exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = void 0;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
-var _util = require("../openapi-3-1/util.cjs");
-exports.resolveSchema$refField = _util.resolveSchema$refField;
-exports.resolveSchema$idField = _util.resolveSchema$idField;
-/**
- * Cached version of JSONSchemaElement.refract.
- */
-const refractToJSONSchemaElement = element => {
-  if (refractToJSONSchemaElement.cache.has(element)) {
-    return refractToJSONSchemaElement.cache.get(element);
-  }
-  const refracted = (0, _apidomNsArazzo.refractJSONSchema)(element);
-  refractToJSONSchemaElement.cache.set(element, refracted);
-  return refracted;
-};
-exports.refractToJSONSchemaElement = refractToJSONSchemaElement;
-refractToJSONSchemaElement.cache = new WeakMap();
-
-/**
- * @public
- */
-const maybeRefractToJSONSchemaElement = element => {
-  /**
-   * Conditional version of refractToJSONSchemaElement, that acts as an identity
-   * function for all non-primitive Element instances.
-   */
-  if ((0, _apidomDatamodel.isPrimitiveElement)(element)) {
-    return refractToJSONSchemaElement(element);
-  }
-  return element;
-};
-exports.maybeRefractToJSONSchemaElement = maybeRefractToJSONSchemaElement;