@speclynx/apidom-reference 2.5.1 → 2.6.1

package/package.json

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

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,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/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/openapi-3-0/visitor.cjs

@@ -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);

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

@@ -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);

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

@@ -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);

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

@@ -456,7 +456,7 @@ class OpenAPI3_1DereferenceVisitor {
       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);

package/src/errors/InvalidJsonSchema$anchorError.cjs

@@ -9,7 +9,7 @@ var _JsonSchema$anchorError = _interopRequireDefault(require("./JsonSchema$ancho
  */
 class InvalidJsonSchema$anchorError extends _JsonSchema$anchorError.default {
   constructor(anchor) {
-    super(`Invalid JSON Schema $anchor "${anchor}".`);
+    super(`Invalid JSON Schema $anchor "${anchor}"`);
   }
 }
 var _default = exports.default = InvalidJsonSchema$anchorError;

package/src/errors/InvalidJsonSchema$anchorError.mjs

@@ -4,7 +4,7 @@ import JsonSchema$anchorError from "./JsonSchema$anchorError.mjs";
  */
 class InvalidJsonSchema$anchorError extends JsonSchema$anchorError {
   constructor(anchor) {
-    super(`Invalid JSON Schema $anchor "${anchor}".`);
+    super(`Invalid JSON Schema $anchor "${anchor}"`);
   }
 }
 export default InvalidJsonSchema$anchorError;

package/src/errors/UnmatchedParserError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ParserError = _interopRequireDefault(require("./ParserError.cjs"));
+/**
+ * @public
+ */
+class UnmatchedParserError extends _ParserError.default {}
+var _default = exports.default = UnmatchedParserError;

package/src/errors/UnmatchedParserError.mjs

@@ -0,0 +1,6 @@
+import ParserError from "./ParserError.mjs";
+/**
+ * @public
+ */
+class UnmatchedParserError extends ParserError {}
+export default UnmatchedParserError;

package/src/index.cjs

@@ -3,7 +3,7 @@
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
-exports.url = exports.resolveApiDOM = exports.resolve = exports.readFile = exports.parse = exports.options = exports.mergeOptions = exports.dereferenceApiDOM = exports.dereference = exports.bundle = exports.UnmatchedResolverError = exports.UnmatchedResolveStrategyError = exports.UnmatchedDereferenceStrategyError = exports.UnmatchedBundleStrategyError = exports.ResolverError = exports.Resolver = exports.ResolveStrategy = exports.ResolveError = exports.Reference = exports.PluginError = exports.ParserError = exports.Parser = exports.ParseError = exports.MaximumResolveDepthError = exports.MaximumDereferenceDepthError = exports.MaximumBundleDepthError = exports.JsonSchemaURIError = exports.JsonSchema$anchorError = exports.InvalidJsonSchema$anchorError = exports.HTTPResolver = exports.EvaluationJsonSchemaUriError = exports.EvaluationJsonSchema$anchorError = exports.EvaluationElementIdError = exports.DereferenceStrategy = exports.DereferenceError = exports.DereferenceAncestorLineage = exports.BundleStrategy = exports.BundleError = void 0;
+exports.url = exports.resolveApiDOM = exports.resolve = exports.readFile = exports.parse = exports.options = exports.mergeOptions = exports.dereferenceApiDOM = exports.dereference = exports.bundle = exports.UnmatchedResolverError = exports.UnmatchedResolveStrategyError = exports.UnmatchedParserError = exports.UnmatchedDereferenceStrategyError = exports.UnmatchedBundleStrategyError = exports.ResolverError = exports.Resolver = exports.ResolveStrategy = exports.ResolveError = exports.Reference = exports.PluginError = exports.ParserError = exports.Parser = exports.ParseError = exports.MaximumResolveDepthError = exports.MaximumDereferenceDepthError = exports.MaximumBundleDepthError = exports.JsonSchemaURIError = exports.JsonSchema$anchorError = exports.InvalidJsonSchema$anchorError = exports.HTTPResolver = exports.EvaluationJsonSchemaUriError = exports.EvaluationJsonSchema$anchorError = exports.EvaluationElementIdError = exports.DereferenceStrategy = exports.DereferenceError = exports.DereferenceAncestorLineage = exports.BundleStrategy = exports.BundleError = void 0;
 var _File = _interopRequireDefault(require("./File.cjs"));
 exports.File = _File.default;
 var _ReferenceSet = _interopRequireDefault(require("./ReferenceSet.cjs"));
@@ -75,6 +75,8 @@ var _UnmatchedResolveStrategyError = _interopRequireDefault(require("./errors/Un
 exports.UnmatchedResolveStrategyError = _UnmatchedResolveStrategyError.default;
 var _UnmatchedResolverError = _interopRequireDefault(require("./errors/UnmatchedResolverError.cjs"));
 exports.UnmatchedResolverError = _UnmatchedResolverError.default;
+var _UnmatchedParserError = _interopRequireDefault(require("./errors/UnmatchedParserError.cjs"));
+exports.UnmatchedParserError = _UnmatchedParserError.default;
 /**
  * @public
  */

package/src/index.mjs

@@ -41,6 +41,7 @@ export { default as ResolverError } from "./errors/ResolverError.mjs";
 export { default as UnmatchedDereferenceStrategyError } from "./errors/UnmatchedDereferenceStrategyError.mjs";
 export { default as UnmatchedResolveStrategyError } from "./errors/UnmatchedResolveStrategyError.mjs";
 export { default as UnmatchedResolverError } from "./errors/UnmatchedResolverError.mjs";
+export { default as UnmatchedParserError } from "./errors/UnmatchedParserError.mjs";
 /**
  * @public
  */

package/src/parse/index.cjs

@@ -9,7 +9,7 @@ var url = _interopRequireWildcard(require("../util/url.cjs"));
 var _File = _interopRequireDefault(require("../File.cjs"));
 var plugins = _interopRequireWildcard(require("../util/plugins.cjs"));
 var _ParseError = _interopRequireDefault(require("../errors/ParseError.cjs"));
-var _UnmatchedResolverError = _interopRequireDefault(require("../errors/UnmatchedResolverError.cjs"));
+var _UnmatchedParserError = _interopRequireDefault(require("../errors/UnmatchedParserError.cjs"));
 var _util = require("../resolve/util.cjs");
 /**
  * Parses the given file's contents, using the configured parser plugins.
@@ -23,7 +23,7 @@ const parseFile = async (file, options) => {
 
   // we couldn't find any parser for this File
   if ((0, _ramda.isEmpty)(parsers)) {
-    throw new _UnmatchedResolverError.default(file.uri);
+    throw new _UnmatchedParserError.default(`Could not find a parser that can parse the file "${file.uri}"`);
   }
   try {
     const {
@@ -33,7 +33,7 @@ const parseFile = async (file, options) => {
 
     // empty files handling
     if (!plugin.allowEmpty && result.isEmpty) {
-      return Promise.reject(new _ParseError.default(`Error while parsing file "${file.uri}". File is empty.`));
+      return Promise.reject(new _ParseError.default(`Error while parsing file "${file.uri}": file is empty`));
     }
     return result;
   } catch (error) {

package/src/parse/index.mjs

@@ -3,7 +3,7 @@ import * as url from "../util/url.mjs";
 import File from "../File.mjs";
 import * as plugins from "../util/plugins.mjs";
 import ParseError from "../errors/ParseError.mjs";
-import UnmatchedResolverError from "../errors/UnmatchedResolverError.mjs";
+import UnmatchedParserError from "../errors/UnmatchedParserError.mjs";
 import { readFile } from "../resolve/util.mjs";
 /**
  * Parses the given file's contents, using the configured parser plugins.
@@ -17,7 +17,7 @@ const parseFile = async (file, options) => {
 
   // we couldn't find any parser for this File
   if (isEmpty(parsers)) {
-    throw new UnmatchedResolverError(file.uri);
+    throw new UnmatchedParserError(`Could not find a parser that can parse the file "${file.uri}"`);
   }
   try {
     const {
@@ -27,7 +27,7 @@ const parseFile = async (file, options) => {
 
     // empty files handling
     if (!plugin.allowEmpty && result.isEmpty) {
-      return Promise.reject(new ParseError(`Error while parsing file "${file.uri}". File is empty.`));
+      return Promise.reject(new ParseError(`Error while parsing file "${file.uri}": file is empty`));
     }
     return result;
   } catch (error) {

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;
+}