@speclynx/apidom-reference 2.6.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "publishConfig": {
     "access": "public",
@@ -231,29 +231,29 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "^2.6.0",
-    "@speclynx/apidom-datamodel": "^2.6.0",
-    "@speclynx/apidom-error": "^2.6.0",
-    "@speclynx/apidom-json-pointer": "^2.6.0",
-    "@speclynx/apidom-ns-arazzo-1": "^2.6.0",
-    "@speclynx/apidom-ns-asyncapi-2": "^2.6.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "^2.6.0",
-    "@speclynx/apidom-ns-openapi-2": "^2.6.0",
-    "@speclynx/apidom-ns-openapi-3-0": "^2.6.0",
-    "@speclynx/apidom-ns-openapi-3-1": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-json": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.6.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.6.0",
-    "@speclynx/apidom-traverse": "^2.6.0",
+    "@speclynx/apidom-core": "^2.7.0",
+    "@speclynx/apidom-datamodel": "^2.7.0",
+    "@speclynx/apidom-error": "^2.7.0",
+    "@speclynx/apidom-json-pointer": "^2.7.0",
+    "@speclynx/apidom-ns-arazzo-1": "^2.7.0",
+    "@speclynx/apidom-ns-asyncapi-2": "^2.7.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "^2.7.0",
+    "@speclynx/apidom-ns-openapi-2": "^2.7.0",
+    "@speclynx/apidom-ns-openapi-3-0": "^2.7.0",
+    "@speclynx/apidom-ns-openapi-3-1": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-json": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.7.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.7.0",
+    "@speclynx/apidom-traverse": "^2.7.0",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.2",
     "axios": "^1.13.0",
     "minimatch": "^7.4.6",
@@ -274,5 +274,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "d96eb344cc26a57935aa3a425ea2447d6e8e77b2"
+  "gitHead": "82ac9430aa882d0a5c63a17f7da8f5c0dcbca737"
 }

package/src/bundle/index.cjs

@@ -45,7 +45,7 @@ const bundle = async (uri, options) => {
 
   // we couldn't find any bundle strategy for this File
   if ((0, _ramda.isEmpty)(bundleStrategies)) {
-    throw new _UnmatchedBundleStrategyError.default(file.uri);
+    throw new _UnmatchedBundleStrategyError.default(`Could not find a bundle strategy that can bundle the file "${file.uri}"`);
   }
   try {
     const {

package/src/bundle/index.mjs

@@ -39,7 +39,7 @@ const bundle = async (uri, options) => {
 
   // we couldn't find any bundle strategy for this File
   if (isEmpty(bundleStrategies)) {
-    throw new UnmatchedBundleStrategyError(file.uri);
+    throw new UnmatchedBundleStrategyError(`Could not find a bundle strategy that can bundle the file "${file.uri}"`);
   }
   try {
     const {

package/src/configuration/saturated.cjs

@@ -62,12 +62,10 @@ _index25.options.parse.parsers = [new _index7.default({
   sourceMap: false
 }), new _index13.default({
   allowEmpty: true,
-  sourceMap: false,
-  parseFn: _index25.parse
+  sourceMap: false
 }), new _index14.default({
   allowEmpty: true,
-  sourceMap: false,
-  parseFn: _index25.parse
+  sourceMap: false
 }), new _index15.default({
   allowEmpty: true,
   sourceMap: false

package/src/configuration/saturated.mjs

@@ -26,7 +26,7 @@ import OpenAPI3_1DereferenceStrategy from "../dereference/strategies/openapi-3-1
 import AsyncAPI2DereferenceStrategy from "../dereference/strategies/asyncapi-2/index.mjs";
 import Arazzo1DereferenceStrategy from "../dereference/strategies/arazzo-1/index.mjs";
 import OpenAPI3_1BundleStrategy from "../bundle/strategies/openapi-3-1/index.mjs";
-import { options, parse } from "../index.mjs";
+import { options } from "../index.mjs";
 options.parse.parsers = [new OpenAPIJSON2Parser({
   allowEmpty: true,
   sourceMap: false
@@ -53,12 +53,10 @@ options.parse.parsers = [new OpenAPIJSON2Parser({
   sourceMap: false
 }), new ArazzoJSON1Parser({
   allowEmpty: true,
-  sourceMap: false,
-  parseFn: parse
+  sourceMap: false
 }), new ArazzoYAML1Parser({
   allowEmpty: true,
-  sourceMap: false,
-  parseFn: parse
+  sourceMap: false
 }), new APIDOMJSONParser({
   allowEmpty: true,
   sourceMap: false

package/src/dereference/index.cjs

@@ -37,7 +37,7 @@ const dereferenceApiDOM = async (element, options) => {
 
   // we couldn't find any dereference strategy for this File
   if ((0, _ramda.isEmpty)(dereferenceStrategies)) {
-    throw new _UnmatchedDereferenceStrategyError.default(file.uri);
+    throw new _UnmatchedDereferenceStrategyError.default(`Could not find a dereference strategy that can dereference the file "${file.uri}"`);
   }
   try {
     const {

package/src/dereference/index.mjs

@@ -31,7 +31,7 @@ export const dereferenceApiDOM = async (element, options) => {
 
   // we couldn't find any dereference strategy for this File
   if (isEmpty(dereferenceStrategies)) {
-    throw new UnmatchedDereferenceStrategyError(file.uri);
+    throw new UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference the file "${file.uri}"`);
   }
   try {
     const {

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

@@ -12,6 +12,7 @@ var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
 var _visitor = _interopRequireDefault(require("./visitor.cjs"));
 exports.Arazzo1DereferenceVisitor = _visitor.default;
+var _sourceDescription = require("./source-description.cjs");
 var _util = require("./util.cjs");
 exports.resolveSchema$refField = _util.resolveSchema$refField;
 exports.resolveSchema$idField = _util.resolveSchema$idField;
@@ -77,6 +78,15 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
       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, _sourceDescription.dereferenceSourceDescriptions)(dereferencedElement, reference, options);
+      dereferencedElement.push(...sourceDescriptions);
+    }
+
     /**
      * If immutable option is set, replay refs from the refSet.
      */

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

@@ -5,6 +5,7 @@ import DereferenceStrategy from "../DereferenceStrategy.mjs";
 import Reference from "../../../Reference.mjs";
 import ReferenceSet from "../../../ReferenceSet.mjs";
 import Arazzo1DereferenceVisitor from "./visitor.mjs";
+import { dereferenceSourceDescriptions } from "./source-description.mjs";
 /**
  * @public
  */
@@ -65,6 +66,15 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
       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, options);
+      dereferencedElement.push(...sourceDescriptions);
+    }
+
     /**
      * If immutable option is set, replay refs from the refSet.
      */

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

@@ -0,0 +1,179 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+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 = _interopRequireDefault(require("../../index.cjs"));
+// shared key for recursion state (works across JSON/YAML documents)
+const ARAZZO_DEREFERENCE_RECURSION_KEY = 'arazzo-1';
+/**
+ * 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, _apidomDatamodel.cloneDeep)(sourceDescription.name));
+  if ((0, _apidomDatamodel.isStringElement)(sourceDescription.type)) parseResult.setMetaProperty('type', (0, _apidomDatamodel.cloneDeep)(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;
+  }
+  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // 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);
+  try {
+    const sourceDescriptionDereferenced = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
+      parse: {
+        mediaType: 'text/plain' // allow parser plugin detection
+      },
+      dereference: {
+        strategyOpts: {
+          [ARAZZO_DEREFERENCE_RECURSION_KEY]: {
+            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.
+ * @public
+ */
+async function dereferenceSourceDescriptions(parseResult, reference, options) {
+  const results = [];
+  const strategyName = 'arazzo-1';
+
+  // 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 shared key (works across JSON/YAML)
+  const sharedOpts = options?.dereference?.strategyOpts?.[ARAZZO_DEREFERENCE_RECURSION_KEY] ?? {};
+  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
+  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
+
+  // add current file to visited URLs to prevent cycles
+  visitedUrls.add(reference.uri);
+  if (currentDepth >= maxDepth) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${reference.uri}"`);
+    annotation.classes.push('error');
+    const parseResult = new _apidomDatamodel.ParseResultElement([annotation]);
+    parseResult.classes.push('source-description');
+    return [parseResult];
+  }
+  const ctx = {
+    baseURI: reference.uri,
+    options,
+    currentDepth,
+    visitedUrls
+  };
+
+  // determine which source descriptions to dereference
+  const sourceDescriptionsOption = options?.dereference?.strategyOpts?.[strategyName]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
+
+  // handle false or other falsy values - no source descriptions should be dereferenced
+  if (!sourceDescriptionsOption) {
+    return results;
+  }
+  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);
+    results.push(sourceDescriptionDereferenceResult);
+  }
+  return results;
+}

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

@@ -0,0 +1,172 @@
+import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, cloneDeep } 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 from "../../index.mjs"; // shared key for recursion state (works across JSON/YAML documents)
+const ARAZZO_DEREFERENCE_RECURSION_KEY = 'arazzo-1';
+/**
+ * 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', cloneDeep(sourceDescription.name));
+  if (isStringElement(sourceDescription.type)) parseResult.setMetaProperty('type', cloneDeep(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;
+  }
+  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // 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);
+  try {
+    const sourceDescriptionDereferenced = await dereference(retrievalURI, mergeOptions(ctx.options, {
+      parse: {
+        mediaType: 'text/plain' // allow parser plugin detection
+      },
+      dereference: {
+        strategyOpts: {
+          [ARAZZO_DEREFERENCE_RECURSION_KEY]: {
+            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.
+ * @public
+ */
+export async function dereferenceSourceDescriptions(parseResult, reference, options) {
+  const results = [];
+  const strategyName = 'arazzo-1';
+
+  // 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 shared key (works across JSON/YAML)
+  const sharedOpts = options?.dereference?.strategyOpts?.[ARAZZO_DEREFERENCE_RECURSION_KEY] ?? {};
+  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
+  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
+
+  // add current file to visited URLs to prevent cycles
+  visitedUrls.add(reference.uri);
+  if (currentDepth >= maxDepth) {
+    const annotation = new AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${reference.uri}"`);
+    annotation.classes.push('error');
+    const parseResult = new ParseResultElement([annotation]);
+    parseResult.classes.push('source-description');
+    return [parseResult];
+  }
+  const ctx = {
+    baseURI: reference.uri,
+    options,
+    currentDepth,
+    visitedUrls
+  };
+
+  // determine which source descriptions to dereference
+  const sourceDescriptionsOption = options?.dereference?.strategyOpts?.[strategyName]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
+
+  // handle false or other falsy values - no source descriptions should be dereferenced
+  if (!sourceDescriptionsOption) {
+    return results;
+  }
+  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);
+    results.push(sourceDescriptionDereferenceResult);
+  }
+  return results;
+}

package/src/dereference/strategies/openapi-3-0/visitor.cjs

@@ -389,7 +389,7 @@ class OpenAPI3_0DereferenceVisitor {
 
     // operationRef and operationId fields are mutually exclusive
     if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef) && (0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
-      throw new _apidomError.ApiDOMError('LinkElement operationRef and operationId fields are mutually exclusive.');
+      throw new _apidomError.ApiDOMError('LinkElement operationRef and operationId fields are mutually exclusive');
     }
     let operationElement;
     if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef)) {
@@ -440,7 +440,7 @@ class OpenAPI3_0DereferenceVisitor {
       operationElement = (0, _apidomTraverse.find)(reference.value.result, e => (0, _apidomNsOpenapi.isOperationElement)(e) && (0, _apidomDatamodel.isElement)(e.operationId) && e.operationId.equals(operationId));
       // OperationElement not found by its operationId
       if ((0, _ramdaAdjunct.isUndefined)(operationElement)) {
-        throw new _apidomError.ApiDOMError(`OperationElement(operationId=${operationId}) not found.`);
+        throw new _apidomError.ApiDOMError(`OperationElement(operationId=${operationId}) not found`);
       }
       const linkElementCopy = (0, _apidomDatamodel.cloneShallow)(linkElement);
       linkElementCopy.operationId?.meta.set('operation', operationElement);
@@ -462,7 +462,7 @@ class OpenAPI3_0DereferenceVisitor {
 
     // value and externalValue fields are mutually exclusive
     if (exampleElement.hasKey('value') && (0, _apidomDatamodel.isStringElement)(exampleElement.externalValue)) {
-      throw new _apidomError.ApiDOMError('ExampleElement value and externalValue fields are mutually exclusive.');
+      throw new _apidomError.ApiDOMError('ExampleElement value and externalValue fields are mutually exclusive');
     }
     const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(exampleElement.externalValue));
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;

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

@@ -383,7 +383,7 @@ class OpenAPI3_0DereferenceVisitor {
 
     // operationRef and operationId fields are mutually exclusive
     if (isStringElement(linkElement.operationRef) && isStringElement(linkElement.operationId)) {
-      throw new ApiDOMError('LinkElement operationRef and operationId fields are mutually exclusive.');
+      throw new ApiDOMError('LinkElement operationRef and operationId fields are mutually exclusive');
     }
     let operationElement;
     if (isStringElement(linkElement.operationRef)) {
@@ -434,7 +434,7 @@ class OpenAPI3_0DereferenceVisitor {
       operationElement = find(reference.value.result, e => isOperationElement(e) && isElement(e.operationId) && e.operationId.equals(operationId));
       // OperationElement not found by its operationId
       if (isUndefined(operationElement)) {
-        throw new ApiDOMError(`OperationElement(operationId=${operationId}) not found.`);
+        throw new ApiDOMError(`OperationElement(operationId=${operationId}) not found`);
       }
       const linkElementCopy = cloneShallow(linkElement);
       linkElementCopy.operationId?.meta.set('operation', operationElement);
@@ -456,7 +456,7 @@ class OpenAPI3_0DereferenceVisitor {
 
     // value and externalValue fields are mutually exclusive
     if (exampleElement.hasKey('value') && isStringElement(exampleElement.externalValue)) {
-      throw new ApiDOMError('ExampleElement value and externalValue fields are mutually exclusive.');
+      throw new ApiDOMError('ExampleElement value and externalValue fields are mutually exclusive');
     }
     const retrievalURI = this.toBaseURI(toValue(exampleElement.externalValue));
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;

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

@@ -411,7 +411,7 @@ class OpenAPI3_1DereferenceVisitor {
 
     // operationRef and operationId fields are mutually exclusive
     if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef) && (0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
-      throw new _apidomError.ApiDOMError('LinkElement operationRef and operationId fields are mutually exclusive.');
+      throw new _apidomError.ApiDOMError('LinkElement operationRef and operationId fields are mutually exclusive');
     }
     let operationElement;
     if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef)) {
@@ -462,7 +462,7 @@ class OpenAPI3_1DereferenceVisitor {
       operationElement = (0, _apidomTraverse.find)(reference.value.result, e => (0, _apidomNsOpenapi.isOperationElement)(e) && (0, _apidomDatamodel.isElement)(e.operationId) && e.operationId.equals(operationId));
       // OperationElement not found by its operationId
       if ((0, _ramdaAdjunct.isUndefined)(operationElement)) {
-        throw new _apidomError.ApiDOMError(`OperationElement(operationId=${operationId}) not found.`);
+        throw new _apidomError.ApiDOMError(`OperationElement(operationId=${operationId}) not found`);
       }
       const linkElementCopy = (0, _apidomDatamodel.cloneShallow)(linkElement);
       linkElementCopy.operationId?.meta.set('operation', operationElement);
@@ -483,7 +483,7 @@ class OpenAPI3_1DereferenceVisitor {
 
     // value and externalValue fields are mutually exclusive
     if (exampleElement.hasKey('value') && (0, _apidomDatamodel.isStringElement)(exampleElement.externalValue)) {
-      throw new _apidomError.ApiDOMError('ExampleElement value and externalValue fields are mutually exclusive.');
+      throw new _apidomError.ApiDOMError('ExampleElement value and externalValue fields are mutually exclusive');
     }
     const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(exampleElement.externalValue));
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;