@speclynx/apidom-reference 2.7.0 → 2.9.0

package/dist/apidom-reference.browser.js

@@ -816,6 +816,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   Arazzo1DereferenceVisitor: () => (/* reexport safe */ _visitor_ts__WEBPACK_IMPORTED_MODULE_9__["default"]),
 /* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__),
+/* harmony export */   dereferenceSourceDescriptions: () => (/* reexport safe */ _source_descriptions_ts__WEBPACK_IMPORTED_MODULE_10__.dereferenceSourceDescriptions),
 /* harmony export */   maybeRefractToJSONSchemaElement: () => (/* reexport safe */ _util_ts__WEBPACK_IMPORTED_MODULE_11__.maybeRefractToJSONSchemaElement),
 /* harmony export */   resolveSchema$idField: () => (/* reexport safe */ _util_ts__WEBPACK_IMPORTED_MODULE_12__.resolveSchema$idField),
 /* harmony export */   resolveSchema$refField: () => (/* reexport safe */ _util_ts__WEBPACK_IMPORTED_MODULE_12__.resolveSchema$refField)
@@ -830,7 +831,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _Reference_ts__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(98979);
 /* harmony import */ var _ReferenceSet_ts__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(24131);
 /* harmony import */ var _visitor_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(31843);
-/* harmony import */ var _source_description_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(99371);
+/* harmony import */ var _source_descriptions_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(12586);
 /* harmony import */ var _util_ts__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(91005);
 /* harmony import */ var _util_ts__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(60888);
 
@@ -908,7 +909,7 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMPORT
      */
     const shouldDereferenceSourceDescriptions = options?.dereference?.strategyOpts?.[this.name]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
     if (shouldDereferenceSourceDescriptions) {
-      const sourceDescriptions = await (0,_source_description_ts__WEBPACK_IMPORTED_MODULE_10__.dereferenceSourceDescriptions)(dereferencedElement, reference, options);
+      const sourceDescriptions = await (0,_source_descriptions_ts__WEBPACK_IMPORTED_MODULE_10__.dereferenceSourceDescriptions)(dereferencedElement, reference.uri, options, this.name);
       dereferencedElement.push(...sourceDescriptions);
     }
 
@@ -935,11 +936,12 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMPORT
 }
 
 
+
 /* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (Arazzo1DereferenceStrategy);
 
 /***/ },
 
-/***/ 99371
+/***/ 12586
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -949,17 +951,17 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ });
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(25162);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(12111);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(84660);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(4823);
-/* harmony import */ var _speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(28839);
-/* harmony import */ var _speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(26365);
-/* 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__(42037);
-
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(96911);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(84660);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(4823);
+/* harmony import */ var _speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(28839);
+/* harmony import */ var _speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(26365);
+/* harmony import */ var _speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(32131);
+/* harmony import */ var _speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(76332);
+/* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(44673);
+/* 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__(42037);
 
 
 
@@ -969,16 +971,14 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
-// 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 _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]();
-  if (!(0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_4__.isSourceDescriptionElement)(sourceDescription)) {
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]('Element is not a valid SourceDescriptionElement. Skipping');
+  const parseResult = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"]();
+  if (!(0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_5__.isSourceDescriptionElement)(sourceDescription)) {
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]('Element is not a valid SourceDescriptionElement. Skipping');
     annotation.classes.push('warning');
     parseResult.push(annotation);
     return parseResult;
@@ -988,37 +988,73 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
   parseResult.classes.push('source-description');
   if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isStringElement)(sourceDescription.name)) parseResult.setMetaProperty('name', (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(sourceDescription.name));
   if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isStringElement)(sourceDescription.type)) parseResult.setMetaProperty('type', (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(sourceDescription.type));
-  const sourceDescriptionURI = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_8__["default"])(sourceDescription.url);
+  const sourceDescriptionURI = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_9__["default"])(sourceDescription.url);
   if (typeof sourceDescriptionURI !== 'string') {
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]('Source description URL is missing or not a string. Skipping');
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]('Source description URL is missing or not a string. Skipping');
     annotation.classes.push('warning');
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_9__.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // normalize URI for consistent cycle detection and refSet cache key matching
+  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_10__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.stripHash(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.resolve(ctx.baseURI, sourceDescriptionURI)));
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
     annotation.classes.push('warning');
     parseResult.push(annotation);
     return parseResult;
   }
   ctx.visitedUrls.add(retrievalURI);
+
+  // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
+  const existingParseResult = sourceDescription.meta.get('parseResult');
   try {
-    const sourceDescriptionDereferenced = await (0,_index_ts__WEBPACK_IMPORTED_MODULE_11__["default"])(retrievalURI, (0,_options_util_ts__WEBPACK_IMPORTED_MODULE_10__.merge)(ctx.options, {
-      parse: {
-        mediaType: 'text/plain' // allow parser plugin detection
-      },
-      dereference: {
-        strategyOpts: {
-          [ARAZZO_DEREFERENCE_RECURSION_KEY]: {
-            sourceDescriptionsDepth: ctx.currentDepth + 1,
-            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+    let sourceDescriptionDereferenced;
+    if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isParseResultElement)(existingParseResult)) {
+      // use existing parsed result - just dereference it (no re-fetch/re-parse)
+      sourceDescriptionDereferenced = await (0,_index_ts__WEBPACK_IMPORTED_MODULE_12__.dereferenceApiDOM)(existingParseResult, (0,_options_util_ts__WEBPACK_IMPORTED_MODULE_11__.merge)(ctx.options, {
+        parse: {
+          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
+        },
+        resolve: {
+          baseURI: retrievalURI
+        },
+        dereference: {
+          strategyOpts: {
+            // nested documents should dereference all their source descriptions
+            // (parent's name filter doesn't apply to nested documents)
+            // set at strategy-specific level to override any inherited filters
+            [ctx.strategyName]: {
+              sourceDescriptions: true,
+              sourceDescriptionsDepth: ctx.currentDepth + 1,
+              sourceDescriptionsVisitedUrls: ctx.visitedUrls
+            }
           }
         }
-      }
-    }));
+      }));
+    } else {
+      // no existing parse result - fetch, parse, and dereference
+      sourceDescriptionDereferenced = await (0,_index_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
+        },
+        dereference: {
+          strategyOpts: {
+            // nested documents should dereference all their source descriptions
+            // (parent's name filter doesn't apply to nested documents)
+            // set at strategy-specific level to override any inherited filters
+            [ctx.strategyName]: {
+              sourceDescriptions: true,
+              sourceDescriptionsDepth: ctx.currentDepth + 1,
+              sourceDescriptionsVisitedUrls: ctx.visitedUrls
+            }
+          }
+        }
+      }));
+    }
+
     // merge dereferenced result into our parse result
     for (const item of sourceDescriptionDereferenced) {
       parseResult.push(item);
@@ -1026,7 +1062,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
   } catch (error) {
     // create error annotation instead of failing entire dereference
     const message = error instanceof Error ? error.message : String(error);
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](`Error dereferencing source description "${retrievalURI}": ${message}`);
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`Error dereferencing source description "${retrievalURI}": ${message}`);
     annotation.classes.push('error');
     parseResult.push(annotation);
     return parseResult;
@@ -1036,24 +1072,24 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
   const {
     api: sourceDescriptionAPI
   } = parseResult;
-  const isOpenApi = (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_5__.isSwaggerElement)(sourceDescriptionAPI) || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_6__.isOpenApi3_0Element)(sourceDescriptionAPI) || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_7__.isOpenApi3_1Element)(sourceDescriptionAPI);
-  const isArazzo = (0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_4__.isArazzoSpecification1Element)(sourceDescriptionAPI);
+  const isOpenApi = (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_6__.isSwaggerElement)(sourceDescriptionAPI) || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_7__.isOpenApi3_0Element)(sourceDescriptionAPI) || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_8__.isOpenApi3_1Element)(sourceDescriptionAPI);
+  const isArazzo = (0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_5__.isArazzoSpecification1Element)(sourceDescriptionAPI);
   if (!isOpenApi && !isArazzo) {
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`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,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_8__["default"])(sourceDescription.type);
+  const declaredType = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_9__["default"])(sourceDescription.type);
   if (typeof declaredType === 'string') {
     if (declaredType === 'openapi' && !isOpenApi) {
-      const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](`Source description "${retrievalURI}" declared as "openapi" but dereferenced as Arazzo document`);
+      const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`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 _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](`Source description "${retrievalURI}" declared as "arazzo" but dereferenced as OpenAPI document`);
+      const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`Source description "${retrievalURI}" declared as "arazzo" but dereferenced as OpenAPI document`);
       annotation.classes.push('warning');
       parseResult.push(annotation);
     }
@@ -1063,11 +1099,45 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
 /**
  * Dereferences source descriptions from an Arazzo document.
+ *
+ * Each source description result is attached to its corresponding
+ * SourceDescriptionElement's meta as 'parseResult' for easy access,
+ * regardless of success or failure. On failure, the ParseResultElement
+ * contains annotations explaining what went wrong.
+ *
+ * @param parseResult - ParseResult containing a parsed (optionally dereferenced) Arazzo specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
+ *   in `dereference.strategyOpts` to filter which source descriptions to process.
+ * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
+ * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
+ *   (each with class 'source-description' and 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 dereference depth is exceeded (error annotation)
+ *   Returns an empty array when no source description names match the filter.
+ *
+ * @example
+ * ```typescript
+ * // Dereference all source descriptions
+ * await dereferenceSourceDescriptions(parseResult, uri, options);
+ *
+ * // Filter by name
+ * await dereferenceSourceDescriptions(parseResult, uri, mergeOptions(options, {
+ *   dereference: { strategyOpts: { sourceDescriptions: ['petStore'] } },
+ * }));
+ *
+ * // Access dereferenced document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const dereferencedDoc = sourceDesc.meta.get('parseResult');
+ * ```
+ *
  * @public
  */
-async function dereferenceSourceDescriptions(parseResult, reference, options) {
+async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
+  const baseURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_10__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.stripHash(parseResultRetrievalURI));
   const results = [];
-  const strategyName = 'arazzo-1';
 
   // get API from dereferenced parse result
   const {
@@ -1078,57 +1148,55 @@ async function dereferenceSourceDescriptions(parseResult, reference, options) {
    * Validate prerequisites for dereferencing source descriptions.
    * Return warning annotations if validation fails.
    */
-  if (!(0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_4__.isArazzoSpecification1Element)(api)) {
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]('Cannot dereference source descriptions: API is not an Arazzo specification');
+  if (!(0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_5__.isArazzoSpecification1Element)(api)) {
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]('Cannot dereference source descriptions: API is not an Arazzo specification');
     annotation.classes.push('warning');
-    return [new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]([annotation])];
+    return [new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"]([annotation])];
   }
   if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isArrayElement)(api.sourceDescriptions)) {
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]('Cannot dereference source descriptions: sourceDescriptions field is missing or not an array');
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]('Cannot dereference source descriptions: sourceDescriptions field is missing or not an array');
     annotation.classes.push('warning');
-    return [new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]([annotation])];
+    return [new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"]([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] ?? {};
+  // recursion state comes from strategy-specific options
+  const sharedOpts = options?.dereference?.strategyOpts?.[strategyName] ?? {};
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
   const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
 
   // add current file to visited URLs to prevent cycles
-  visitedUrls.add(reference.uri);
+  visitedUrls.add(baseURI);
   if (currentDepth >= maxDepth) {
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](`Maximum dereference depth of ${maxDepth} has been exceeded by file "${reference.uri}"`);
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`Maximum dereference depth of ${maxDepth} has been exceeded by file "${baseURI}"`);
     annotation.classes.push('error');
-    const parseResult = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]([annotation]);
+    const parseResult = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"]([annotation]);
     parseResult.classes.push('source-description');
     return [parseResult];
   }
   const ctx = {
-    baseURI: reference.uri,
+    baseURI,
     options,
+    strategyName,
     currentDepth,
     visitedUrls
   };
 
-  // determine which source descriptions to dereference
+  // determine which source descriptions to dereference (array filters by name)
   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,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_4__.isSourceDescriptionElement)(sd)) return false;
-    const name = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_8__["default"])(sd.name);
+    if (!(0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_5__.isSourceDescriptionElement)(sd)) return false;
+    const name = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_9__["default"])(sd.name);
     return typeof name === 'string' && sourceDescriptionsOption.includes(name);
   }) : api.sourceDescriptions;
 
   // process sequentially to ensure proper cycle detection with shared visitedUrls
   for (const sourceDescription of sourceDescriptions) {
     const sourceDescriptionDereferenceResult = await dereferenceSourceDescription(sourceDescription, ctx);
+    // always attach result (even on failure - contains annotations)
+    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult);
     results.push(sourceDescriptionDereferenceResult);
   }
   return results;
@@ -5704,14 +5772,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 +5826,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 +5837,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 +5859,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 +5900,9 @@ async function parseSourceDescription(sourceDescription, ctx) {
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_9__.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // normalize URI for consistent cycle detection and cache key matching
+  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_10__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.stripHash(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.resolve(ctx.baseURI, sourceDescriptionURI)));
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -5839,11 +5913,14 @@ 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
         parserOpts: {
+          // nested documents should parse all their source descriptions
+          // (parent's name filter doesn't apply to nested documents)
+          sourceDescriptions: true,
           [ARAZZO_RECURSION_KEY]: {
             sourceDescriptionsDepth: ctx.currentDepth + 1,
             sourceDescriptionsVisitedUrls: ctx.visitedUrls
@@ -5852,7 +5929,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 +5971,53 @@ async function parseSourceDescription(sourceDescription, ctx) {
 }
 
 /**
- * Shared function for parsing source descriptions.
+ * Parses source descriptions from an Arazzo document's ParseResult.
+ *
+ * Each source description result is attached to its corresponding
+ * SourceDescriptionElement's meta as 'parseResult' for easy access,
+ * regardless of success or failure. On failure, the ParseResultElement
+ * contains annotations explaining what went wrong.
+ *
+ * @param parseResult - ParseResult containing an Arazzo specification
+ * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
+ * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
+ *   in `parse.parserOpts` to filter which source descriptions to process.
+ * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
+ * @returns Array of ParseResultElements. 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 no source description names match the filter.
+ *
+ * @example
+ * ```typescript
+ * import { options, mergeOptions } from '@speclynx/apidom-reference';
+ * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+ *
+ * // Parse all source descriptions
+ * const results = await parseSourceDescriptions(parseResult, uri, options);
+ *
+ * // Filter by name
+ * const filtered = await parseSourceDescriptions(parseResult, uri, mergeOptions(options, {
+ *   parse: { parserOpts: { sourceDescriptions: ['petStore'] } }
+ * }));
+ *
+ * // Access parsed document from source description element
+ * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+ * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * ```
+ *
  * @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 = [];
 
   /**
@@ -5939,13 +6059,8 @@ async function parseSourceDescriptions(parserName, api, file, options) {
     visitedUrls
   };
 
-  // determine which source descriptions to parse
+  // determine which source descriptions to parse (array filters by name)
   const sourceDescriptionsOption = options?.parse?.parserOpts?.[parserName]?.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,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_4__.isSourceDescriptionElement)(sd)) return false;
     const name = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_8__["default"])(sd.name);
@@ -5955,6 +6070,8 @@ async function parseSourceDescriptions(parserName, api, file, options) {
   // process sequentially to ensure proper cycle detection with shared visitedUrls
   for (const sourceDescription of sourceDescriptions) {
     const sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
+    // always attach result (even on failure - contains annotations)
+    sourceDescription.meta.set('parseResult', sourceDescriptionParseResult);
     results.push(sourceDescriptionParseResult);
   }
   return results;
@@ -5968,14 +6085,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 +6139,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 +6150,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__) {