@speclynx/apidom-reference 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.8.0](https://github.com/speclynx/apidom/compare/v2.7.0...v2.8.0) (2026-02-06)
+
+### Features
+
+- **reference:** expose low level API for parsing Arazzo source descriptions ([#73](https://github.com/speclynx/apidom/issues/73)) ([1f0d771](https://github.com/speclynx/apidom/commit/1f0d7713f864924e03c601113c0270aeed6e9f81))
+
 # [2.7.0](https://github.com/speclynx/apidom/compare/v2.6.1...v2.7.0) (2026-02-05)
 
 ### Features

package/dist/apidom-reference.browser.js

@@ -5704,14 +5704,15 @@ class ApiDOMJSONParser extends _Parser_ts__WEBPACK_IMPORTED_MODULE_4__["default"
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__),
+/* harmony export */   parseSourceDescriptions: () => (/* reexport safe */ _source_descriptions_ts__WEBPACK_IMPORTED_MODULE_5__.parseSourceDescriptions)
 /* harmony export */ });
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(14494);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_json_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6017);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_json_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(29028);
 /* harmony import */ var _errors_ParserError_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(89371);
 /* harmony import */ var _Parser_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(13166);
-/* harmony import */ var _source_description_ts__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(69848);
+/* harmony import */ var _source_descriptions_ts__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(61407);
 
 
 
@@ -5757,7 +5758,7 @@ class ArazzoJSON1Parser extends _Parser_ts__WEBPACK_IMPORTED_MODULE_4__["default
       const parseResult = await (0,_speclynx_apidom_parser_adapter_arazzo_json_1__WEBPACK_IMPORTED_MODULE_1__.parse)(source, parserOpts);
       const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
       if (shouldParseSourceDescriptions) {
-        const sourceDescriptions = await (0,_source_description_ts__WEBPACK_IMPORTED_MODULE_5__.parseSourceDescriptions)(this.name, parseResult.api, file, options);
+        const sourceDescriptions = await (0,_source_descriptions_ts__WEBPACK_IMPORTED_MODULE_5__.parseSourceDescriptions)(parseResult, file.uri, options, this.name);
         parseResult.push(...sourceDescriptions);
       }
       return parseResult;
@@ -5768,11 +5769,12 @@ class ArazzoJSON1Parser extends _Parser_ts__WEBPACK_IMPORTED_MODULE_4__["default
     }
   }
 }
+
 /* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (ArazzoJSON1Parser);
 
 /***/ },
 
-/***/ 69848
+/***/ 61407
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -5789,9 +5791,11 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(32131);
 /* harmony import */ var _speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(76332);
 /* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(44673);
-/* harmony import */ var _util_url_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(30658);
-/* harmony import */ var _options_util_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(86547);
-/* harmony import */ var _index_ts__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(35014);
+/* harmony import */ var _File_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(10682);
+/* harmony import */ var _util_url_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(30658);
+/* harmony import */ var _options_util_ts__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(86547);
+/* harmony import */ var _index_ts__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(35014);
+
 
 
 
@@ -5828,7 +5832,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_9__.resolve(ctx.baseURI, sourceDescriptionURI);
+  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_10__.resolve(ctx.baseURI, sourceDescriptionURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -5839,7 +5843,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
   }
   ctx.visitedUrls.add(retrievalURI);
   try {
-    const sdParseResult = await (0,_index_ts__WEBPACK_IMPORTED_MODULE_11__["default"])(retrievalURI, (0,_options_util_ts__WEBPACK_IMPORTED_MODULE_10__.merge)(ctx.options, {
+    const sourceDescriptionParseResult = await (0,_index_ts__WEBPACK_IMPORTED_MODULE_12__["default"])(retrievalURI, (0,_options_util_ts__WEBPACK_IMPORTED_MODULE_11__.merge)(ctx.options, {
       parse: {
         mediaType: 'text/plain',
         // allow parser plugin detection
@@ -5852,7 +5856,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
       }
     }));
     // merge parsed result into our parse result
-    for (const item of sdParseResult) {
+    for (const item of sourceDescriptionParseResult) {
       parseResult.push(item);
     }
   } catch (error) {
@@ -5894,10 +5898,40 @@ async function parseSourceDescription(sourceDescription, ctx) {
 }
 
 /**
- * Shared function for parsing source descriptions.
+ * Parses source descriptions from an Arazzo document's ParseResult.
+ *
+ * @param parseResult - ParseResult containing an Arazzo specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions (caller responsibility to construct)
+ * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
+ * @returns Array of ParseResultElements. On success, returns one ParseResultElement per
+ *   source description (each with class 'source-description' and name/type metadata).
+ *   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 parse depth is exceeded (error annotation)
+ *   Returns an empty array when sourceDescriptions option is disabled or no names match.
+ *
+ * @example
+ * ```typescript
+ * import { options, mergeOptions } from '@speclynx/apidom-reference';
+ * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+ *
+ * const fullOptions = mergeOptions(options, {
+ *   parse: { parserOpts: { sourceDescriptions: true } }
+ * });
+ * const results = await parseSourceDescriptions(parseResult, uri, fullOptions);
+ * ```
+ *
  * @public
  */
-async function parseSourceDescriptions(parserName, api, file, options) {
+async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, options, parserName = 'arazzo-json-1') {
+  const {
+    api
+  } = parseResult;
+  const file = new _File_ts__WEBPACK_IMPORTED_MODULE_9__["default"]({
+    uri: _util_url_ts__WEBPACK_IMPORTED_MODULE_10__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.stripHash(parseResultRetrievalURI))
+  });
   const results = [];
 
   /**
@@ -5968,14 +6002,15 @@ async function parseSourceDescriptions(parserName, api, file, options) {
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__),
+/* harmony export */   parseSourceDescriptions: () => (/* reexport safe */ _source_descriptions_ts__WEBPACK_IMPORTED_MODULE_5__.parseSourceDescriptions)
 /* harmony export */ });
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(14494);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_yaml_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(16206);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_yaml_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(43195);
 /* harmony import */ var _errors_ParserError_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(89371);
 /* harmony import */ var _Parser_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(13166);
-/* harmony import */ var _arazzo_json_1_source_description_ts__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(69848);
+/* harmony import */ var _source_descriptions_ts__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(97782);
 
 
 
@@ -6021,7 +6056,7 @@ class ArazzoYAML1Parser extends _Parser_ts__WEBPACK_IMPORTED_MODULE_4__["default
       const parseResult = await (0,_speclynx_apidom_parser_adapter_arazzo_yaml_1__WEBPACK_IMPORTED_MODULE_1__.parse)(source, parserOpts);
       const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
       if (shouldParseSourceDescriptions) {
-        const sourceDescriptions = await (0,_arazzo_json_1_source_description_ts__WEBPACK_IMPORTED_MODULE_5__.parseSourceDescriptions)(this.name, parseResult.api, file, options);
+        const sourceDescriptions = await (0,_source_descriptions_ts__WEBPACK_IMPORTED_MODULE_5__.parseSourceDescriptions)(parseResult, file.uri, options, this.name);
         parseResult.push(...sourceDescriptions);
       }
       return parseResult;
@@ -6032,10 +6067,30 @@ class ArazzoYAML1Parser extends _Parser_ts__WEBPACK_IMPORTED_MODULE_4__["default
     }
   }
 }
+
 /* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (ArazzoYAML1Parser);
 
 /***/ },
 
+/***/ 97782
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   parseSourceDescriptions: () => (/* binding */ parseSourceDescriptions)
+/* harmony export */ });
+/* harmony import */ var _arazzo_json_1_source_descriptions_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(61407);
+
+/**
+ * @public
+ */
+const parseSourceDescriptions = (parseResult, parseResultRetrievalURI, options, parserName = 'arazzo-yaml-1') => {
+  return (0,_arazzo_json_1_source_descriptions_ts__WEBPACK_IMPORTED_MODULE_0__.parseSourceDescriptions)(parseResult, parseResultRetrievalURI, options, parserName);
+};
+
+/***/ },
+
 /***/ 35844
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {