@speclynx/apidom-reference 4.0.2 → 4.0.4

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/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;

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

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

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

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

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

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

@@ -0,0 +1,243 @@
+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

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