@speclynx/apidom-reference 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "2.5.0",
+  "version": "2.6.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.5.0",
-    "@speclynx/apidom-datamodel": "^2.5.0",
-    "@speclynx/apidom-error": "^2.5.0",
-    "@speclynx/apidom-json-pointer": "^2.5.0",
-    "@speclynx/apidom-ns-arazzo-1": "^2.5.0",
-    "@speclynx/apidom-ns-asyncapi-2": "^2.5.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "^2.5.0",
-    "@speclynx/apidom-ns-openapi-2": "^2.5.0",
-    "@speclynx/apidom-ns-openapi-3-0": "^2.5.0",
-    "@speclynx/apidom-ns-openapi-3-1": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-json": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.5.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.5.0",
-    "@speclynx/apidom-traverse": "^2.5.0",
+    "@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",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.2",
     "axios": "^1.13.0",
     "minimatch": "^7.4.6",
@@ -274,5 +274,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "6473d0f9ea30c7fe89aae039e91a0859eaf3cd1c"
+  "gitHead": "d96eb344cc26a57935aa3a425ea2447d6e8e77b2"
 }

package/src/configuration/saturated.cjs

@@ -62,10 +62,12 @@ _index25.options.parse.parsers = [new _index7.default({
   sourceMap: false
 }), new _index13.default({
   allowEmpty: true,
-  sourceMap: false
+  sourceMap: false,
+  parseFn: _index25.parse
 }), new _index14.default({
   allowEmpty: true,
-  sourceMap: false
+  sourceMap: false,
+  parseFn: _index25.parse
 }), 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 } from "../index.mjs";
+import { options, parse } from "../index.mjs";
 options.parse.parsers = [new OpenAPIJSON2Parser({
   allowEmpty: true,
   sourceMap: false
@@ -53,10 +53,12 @@ options.parse.parsers = [new OpenAPIJSON2Parser({
   sourceMap: false
 }), new ArazzoJSON1Parser({
   allowEmpty: true,
-  sourceMap: false
+  sourceMap: false,
+  parseFn: parse
 }), new ArazzoYAML1Parser({
   allowEmpty: true,
-  sourceMap: false
+  sourceMap: false,
+  parseFn: parse
 }), new APIDOMJSONParser({
   allowEmpty: true,
   sourceMap: false

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

@@ -37,7 +37,7 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
     }
 
     // assert by inspecting ApiDOM
-    return (0, _apidomNsArazzo.isArazzoSpecification1Element)(file.parseResult?.api);
+    return (0, _apidomNsArazzo.isArazzoSpecification1Element)(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new _apidomDatamodel.Namespace().use(_apidomNsArazzo.default);

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

@@ -25,7 +25,7 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
     }
 
     // assert by inspecting ApiDOM
-    return isArazzoSpecification1Element(file.parseResult?.api);
+    return isArazzoSpecification1Element(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new Namespace().use(arazzo1Namespace);

package/src/dereference/strategies/asyncapi-2/index.cjs

@@ -33,7 +33,7 @@ class AsyncAPI2DereferenceStrategy extends _DereferenceStrategy.default {
     }
 
     // assert by inspecting ApiDOM
-    return (0, _apidomNsAsyncapi.isAsyncApi2Element)(file.parseResult?.api);
+    return (0, _apidomNsAsyncapi.isAsyncApi2Element)(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new _apidomDatamodel.Namespace().use(_apidomNsAsyncapi.default);

package/src/dereference/strategies/asyncapi-2/index.mjs

@@ -25,7 +25,7 @@ class AsyncAPI2DereferenceStrategy extends DereferenceStrategy {
     }
 
     // assert by inspecting ApiDOM
-    return isAsyncApi2Element(file.parseResult?.api);
+    return isAsyncApi2Element(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new Namespace().use(asyncApi2Namespace);

package/src/dereference/strategies/openapi-2/index.cjs

@@ -33,7 +33,7 @@ class OpenAPI2DereferenceStrategy extends _DereferenceStrategy.default {
     }
 
     // assert by inspecting ApiDOM
-    return (0, _apidomNsOpenapi.isSwaggerElement)(file.parseResult?.api);
+    return (0, _apidomNsOpenapi.isSwaggerElement)(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new _apidomDatamodel.Namespace().use(_apidomNsOpenapi.default);

package/src/dereference/strategies/openapi-2/index.mjs

@@ -25,7 +25,7 @@ class OpenAPI2DereferenceStrategy extends DereferenceStrategy {
     }
 
     // assert by inspecting ApiDOM
-    return isSwaggerElement(file.parseResult?.api);
+    return isSwaggerElement(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new Namespace().use(openApi2Namespace);

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

@@ -33,7 +33,7 @@ class OpenAPI3_0DereferenceStrategy extends _DereferenceStrategy.default {
     }
 
     // assert by inspecting ApiDOM
-    return (0, _apidomNsOpenapi.isOpenApi3_0Element)(file.parseResult?.api);
+    return (0, _apidomNsOpenapi.isOpenApi3_0Element)(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new _apidomDatamodel.Namespace().use(_apidomNsOpenapi.default);

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

@@ -25,7 +25,7 @@ class OpenAPI3_0DereferenceStrategy extends DereferenceStrategy {
     }
 
     // assert by inspecting ApiDOM
-    return isOpenApi3_0Element(file.parseResult?.api);
+    return isOpenApi3_0Element(file.parseResult?.result);
   }
   async dereference(file, options) {
     const namespace = new Namespace().use(openApi3_0Namespace);

package/src/parse/parsers/arazzo-json-1/index.cjs

@@ -7,6 +7,7 @@ var _ramda = require("ramda");
 var _apidomParserAdapterArazzoJson = require("@speclynx/apidom-parser-adapter-arazzo-json-1");
 var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
 var _Parser = _interopRequireDefault(require("../Parser.cjs"));
+var _sourceDescription = require("./source-description.cjs");
 /**
  * @public
  */
@@ -16,8 +17,10 @@ var _Parser = _interopRequireDefault(require("../Parser.cjs"));
  */
 class ArazzoJSON1Parser extends _Parser.default {
   refractorOpts;
+  parseFn;
   constructor(options) {
     const {
+      parseFn,
       fileExtensions = [],
       mediaTypes = _apidomParserAdapterArazzoJson.mediaTypes,
       ...rest
@@ -28,6 +31,7 @@ class ArazzoJSON1Parser extends _Parser.default {
       fileExtensions,
       mediaTypes
     });
+    this.parseFn = parseFn;
   }
   async canParse(file) {
     const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
@@ -39,11 +43,17 @@ class ArazzoJSON1Parser extends _Parser.default {
     }
     return false;
   }
-  async parse(file) {
+  async parse(file, options) {
     const source = file.toString();
     try {
       const parserOpts = (0, _ramda.pick)(['sourceMap', 'strict', 'refractorOpts'], this);
-      return await (0, _apidomParserAdapterArazzoJson.parse)(source, parserOpts);
+      const parseResult = await (0, _apidomParserAdapterArazzoJson.parse)(source, parserOpts);
+      const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+      if (shouldParseSourceDescriptions) {
+        const sourceDescriptions = await _sourceDescription.parseSourceDescriptions.call(this, parseResult.api, file, options);
+        parseResult.push(...sourceDescriptions);
+      }
+      return parseResult;
     } catch (error) {
       throw new _ParserError.default(`Error parsing "${file.uri}"`, {
         cause: error

package/src/parse/parsers/arazzo-json-1/index.mjs

@@ -1,7 +1,8 @@
 import { pick } from 'ramda';
-import { parse, mediaTypes as Arazzo1MediaTypes, detect } from '@speclynx/apidom-parser-adapter-arazzo-json-1';
+import { parse, mediaTypes as ArazzoJSON1MediaTypes, detect } from '@speclynx/apidom-parser-adapter-arazzo-json-1';
 import ParserError from "../../../errors/ParserError.mjs";
 import Parser from "../Parser.mjs";
+import { parseSourceDescriptions } from "./source-description.mjs";
 /**
  * @public
  */
@@ -10,10 +11,12 @@ import Parser from "../Parser.mjs";
  */
 class ArazzoJSON1Parser extends Parser {
   refractorOpts;
+  parseFn;
   constructor(options) {
     const {
+      parseFn,
       fileExtensions = [],
-      mediaTypes = Arazzo1MediaTypes,
+      mediaTypes = ArazzoJSON1MediaTypes,
       ...rest
     } = options ?? {};
     super({
@@ -22,6 +25,7 @@ class ArazzoJSON1Parser extends Parser {
       fileExtensions,
       mediaTypes
     });
+    this.parseFn = parseFn;
   }
   async canParse(file) {
     const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
@@ -33,11 +37,17 @@ class ArazzoJSON1Parser extends Parser {
     }
     return false;
   }
-  async parse(file) {
+  async parse(file, options) {
     const source = file.toString();
     try {
       const parserOpts = pick(['sourceMap', 'strict', 'refractorOpts'], this);
-      return await parse(source, parserOpts);
+      const parseResult = await parse(source, parserOpts);
+      const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+      if (shouldParseSourceDescriptions) {
+        const sourceDescriptions = await parseSourceDescriptions.call(this, parseResult.api, file, options);
+        parseResult.push(...sourceDescriptions);
+      }
+      return parseResult;
     } catch (error) {
       throw new ParserError(`Error parsing "${file.uri}"`, {
         cause: error

package/src/parse/parsers/arazzo-json-1/source-description.cjs

@@ -0,0 +1,177 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.parseSourceDescriptions = parseSourceDescriptions;
+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");
+// shared key for recursion state (works across JSON/YAML parsers)
+const ARAZZO_RECURSION_KEY = 'arazzo-1';
+/**
+ * Parses a single source description element.
+ * Returns ParseResultElement on success, or undefined if skipped.
+ */
+async function parseSourceDescription(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 sdParseResult = await ctx.parseFn(retrievalURI, (0, _util.merge)(ctx.options, {
+      parse: {
+        mediaType: 'text/plain',
+        // allow parser plugin detection
+        parserOpts: {
+          [ARAZZO_RECURSION_KEY]: {
+            sourceDescriptionsDepth: ctx.currentDepth + 1,
+            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+          }
+        }
+      }
+    }));
+    // merge parsed result into our parse result
+    for (const item of sdParseResult) {
+      parseResult.push(item);
+    }
+  } catch (error) {
+    // create error annotation instead of failing entire parse
+    const message = error instanceof Error ? error.message : String(error);
+    const annotation = new _apidomDatamodel.AnnotationElement(`Error parsing 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. Skipping.`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return parseResult;
+  }
+
+  // validate declared type matches actual parsed 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 parsed 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 parsed as OpenAPI document.`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    }
+  }
+  return parseResult;
+}
+
+/**
+ * Shared function for parsing source descriptions.
+ * Call with `.call(this, ...)` where `this` has `name` and `parseFn` properties.
+ * @public
+ */
+async function parseSourceDescriptions(api, file, options) {
+  const results = [];
+
+  /**
+   * Validate prerequisites for parsing source descriptions.
+   * Return warning annotations if validation fails.
+   */
+  if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(api)) {
+    const annotation = new _apidomDatamodel.AnnotationElement('Cannot parse 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 parse source descriptions: sourceDescriptions field is missing or not an array.');
+    annotation.classes.push('warning');
+    return [new _apidomDatamodel.ParseResultElement([annotation])];
+  }
+  if (typeof this.parseFn !== 'function') {
+    const annotation = new _apidomDatamodel.AnnotationElement('Source descriptions found but parseFn is not configured. Skipping source description parsing.');
+    annotation.classes.push('error');
+    return [new _apidomDatamodel.ParseResultElement([annotation])];
+  }
+
+  // user config: parser-specific options take precedence over global parserOpts
+  const maxDepth = options?.parse?.parserOpts?.[this.name]?.sourceDescriptionsMaxDepth ?? options?.parse?.parserOpts?.sourceDescriptionsMaxDepth ?? +Infinity;
+
+  // recursion state comes from shared key (works across JSON/YAML)
+  const sharedOpts = options?.parse?.parserOpts?.[ARAZZO_RECURSION_KEY] ?? {};
+  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
+  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
+
+  // add current file to visited URLs to prevent cycles
+  visitedUrls.add(file.uri);
+  if (currentDepth >= maxDepth) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Maximum parse depth of ${maxDepth} has been exceeded by file "${file.uri}"`);
+    annotation.classes.push('error');
+    const parseResult = new _apidomDatamodel.ParseResultElement([annotation]);
+    parseResult.classes.push('source-description');
+    return [parseResult];
+  }
+  const ctx = {
+    parseFn: this.parseFn,
+    baseURI: file.uri,
+    options,
+    currentDepth,
+    visitedUrls
+  };
+
+  // determine which source descriptions to parse
+  const sourceDescriptionsOption = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+
+  // handle false or other falsy values - no source descriptions should be parsed
+  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 sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
+    results.push(sourceDescriptionParseResult);
+  }
+  return results;
+}

package/src/parse/parsers/arazzo-json-1/source-description.mjs

@@ -0,0 +1,171 @@
+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"; // shared key for recursion state (works across JSON/YAML parsers)
+const ARAZZO_RECURSION_KEY = 'arazzo-1';
+/**
+ * Parses a single source description element.
+ * Returns ParseResultElement on success, or undefined if skipped.
+ */
+async function parseSourceDescription(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 sdParseResult = await ctx.parseFn(retrievalURI, mergeOptions(ctx.options, {
+      parse: {
+        mediaType: 'text/plain',
+        // allow parser plugin detection
+        parserOpts: {
+          [ARAZZO_RECURSION_KEY]: {
+            sourceDescriptionsDepth: ctx.currentDepth + 1,
+            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+          }
+        }
+      }
+    }));
+    // merge parsed result into our parse result
+    for (const item of sdParseResult) {
+      parseResult.push(item);
+    }
+  } catch (error) {
+    // create error annotation instead of failing entire parse
+    const message = error instanceof Error ? error.message : String(error);
+    const annotation = new AnnotationElement(`Error parsing 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. Skipping.`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return parseResult;
+  }
+
+  // validate declared type matches actual parsed 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 parsed 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 parsed as OpenAPI document.`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    }
+  }
+  return parseResult;
+}
+
+/**
+ * Shared function for parsing source descriptions.
+ * Call with `.call(this, ...)` where `this` has `name` and `parseFn` properties.
+ * @public
+ */
+export async function parseSourceDescriptions(api, file, options) {
+  const results = [];
+
+  /**
+   * Validate prerequisites for parsing source descriptions.
+   * Return warning annotations if validation fails.
+   */
+  if (!isArazzoSpecification1Element(api)) {
+    const annotation = new AnnotationElement('Cannot parse 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 parse source descriptions: sourceDescriptions field is missing or not an array.');
+    annotation.classes.push('warning');
+    return [new ParseResultElement([annotation])];
+  }
+  if (typeof this.parseFn !== 'function') {
+    const annotation = new AnnotationElement('Source descriptions found but parseFn is not configured. Skipping source description parsing.');
+    annotation.classes.push('error');
+    return [new ParseResultElement([annotation])];
+  }
+
+  // user config: parser-specific options take precedence over global parserOpts
+  const maxDepth = options?.parse?.parserOpts?.[this.name]?.sourceDescriptionsMaxDepth ?? options?.parse?.parserOpts?.sourceDescriptionsMaxDepth ?? +Infinity;
+
+  // recursion state comes from shared key (works across JSON/YAML)
+  const sharedOpts = options?.parse?.parserOpts?.[ARAZZO_RECURSION_KEY] ?? {};
+  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
+  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
+
+  // add current file to visited URLs to prevent cycles
+  visitedUrls.add(file.uri);
+  if (currentDepth >= maxDepth) {
+    const annotation = new AnnotationElement(`Maximum parse depth of ${maxDepth} has been exceeded by file "${file.uri}"`);
+    annotation.classes.push('error');
+    const parseResult = new ParseResultElement([annotation]);
+    parseResult.classes.push('source-description');
+    return [parseResult];
+  }
+  const ctx = {
+    parseFn: this.parseFn,
+    baseURI: file.uri,
+    options,
+    currentDepth,
+    visitedUrls
+  };
+
+  // determine which source descriptions to parse
+  const sourceDescriptionsOption = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+
+  // handle false or other falsy values - no source descriptions should be parsed
+  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 sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
+    results.push(sourceDescriptionParseResult);
+  }
+  return results;
+}