@speclynx/apidom-reference 2.8.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "2.8.0",
+  "version": "2.9.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.8.0",
-    "@speclynx/apidom-datamodel": "^2.8.0",
-    "@speclynx/apidom-error": "^2.8.0",
-    "@speclynx/apidom-json-pointer": "^2.8.0",
-    "@speclynx/apidom-ns-arazzo-1": "^2.8.0",
-    "@speclynx/apidom-ns-asyncapi-2": "^2.8.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "^2.8.0",
-    "@speclynx/apidom-ns-openapi-2": "^2.8.0",
-    "@speclynx/apidom-ns-openapi-3-0": "^2.8.0",
-    "@speclynx/apidom-ns-openapi-3-1": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-json": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.8.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.8.0",
-    "@speclynx/apidom-traverse": "^2.8.0",
+    "@speclynx/apidom-core": "^2.9.0",
+    "@speclynx/apidom-datamodel": "^2.9.0",
+    "@speclynx/apidom-error": "^2.9.0",
+    "@speclynx/apidom-json-pointer": "^2.9.0",
+    "@speclynx/apidom-ns-arazzo-1": "^2.9.0",
+    "@speclynx/apidom-ns-asyncapi-2": "^2.9.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "^2.9.0",
+    "@speclynx/apidom-ns-openapi-2": "^2.9.0",
+    "@speclynx/apidom-ns-openapi-3-0": "^2.9.0",
+    "@speclynx/apidom-ns-openapi-3-1": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-json": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.9.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.9.0",
+    "@speclynx/apidom-traverse": "^2.9.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": "467e34a8f8a9d56622faf0794e4ef9c1fe86b849"
+  "gitHead": "171956df4417a88238134c1854a5ff823aa144d8"
 }

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

@@ -12,7 +12,8 @@ var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
 var _visitor = _interopRequireDefault(require("./visitor.cjs"));
 exports.Arazzo1DereferenceVisitor = _visitor.default;
-var _sourceDescription = require("./source-description.cjs");
+var _sourceDescriptions = require("./source-descriptions.cjs");
+exports.dereferenceSourceDescriptions = _sourceDescriptions.dereferenceSourceDescriptions;
 var _util = require("./util.cjs");
 exports.resolveSchema$refField = _util.resolveSchema$refField;
 exports.resolveSchema$idField = _util.resolveSchema$idField;
@@ -83,7 +84,7 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
      */
     const shouldDereferenceSourceDescriptions = options?.dereference?.strategyOpts?.[this.name]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
     if (shouldDereferenceSourceDescriptions) {
-      const sourceDescriptions = await (0, _sourceDescription.dereferenceSourceDescriptions)(dereferencedElement, reference, options);
+      const sourceDescriptions = await (0, _sourceDescriptions.dereferenceSourceDescriptions)(dereferencedElement, reference.uri, options, this.name);
       dereferencedElement.push(...sourceDescriptions);
     }
 

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

@@ -5,7 +5,7 @@ import DereferenceStrategy from "../DereferenceStrategy.mjs";
 import Reference from "../../../Reference.mjs";
 import ReferenceSet from "../../../ReferenceSet.mjs";
 import Arazzo1DereferenceVisitor from "./visitor.mjs";
-import { dereferenceSourceDescriptions } from "./source-description.mjs";
+import { dereferenceSourceDescriptions } from "./source-descriptions.mjs";
 /**
  * @public
  */
@@ -71,7 +71,7 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
      */
     const shouldDereferenceSourceDescriptions = options?.dereference?.strategyOpts?.[this.name]?.sourceDescriptions ?? options?.dereference?.strategyOpts?.sourceDescriptions;
     if (shouldDereferenceSourceDescriptions) {
-      const sourceDescriptions = await dereferenceSourceDescriptions(dereferencedElement, reference, options);
+      const sourceDescriptions = await dereferenceSourceDescriptions(dereferencedElement, reference.uri, options, this.name);
       dereferencedElement.push(...sourceDescriptions);
     }
 
@@ -98,4 +98,5 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
 }
 export { Arazzo1DereferenceVisitor };
 export { resolveSchema$refField, resolveSchema$idField, maybeRefractToJSONSchemaElement } from "./util.mjs";
+export { dereferenceSourceDescriptions } from "./source-descriptions.mjs";
 export default Arazzo1DereferenceStrategy;

package/src/dereference/strategies/arazzo-1/{source-description.cjs → source-descriptions.cjs}

@@ -1,6 +1,5 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 exports.__esModule = true;
 exports.dereferenceSourceDescriptions = dereferenceSourceDescriptions;
@@ -12,9 +11,7 @@ var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
 var _apidomCore = require("@speclynx/apidom-core");
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../../../options/util.cjs");
-var _index = _interopRequireDefault(require("../../index.cjs"));
-// shared key for recursion state (works across JSON/YAML documents)
-const ARAZZO_DEREFERENCE_RECURSION_KEY = 'arazzo-1';
+var _index = _interopRequireWildcard(require("../../index.cjs"));
 /**
  * Dereferences a single source description element.
  * Returns ParseResultElement on success, or with annotation if skipped.
@@ -39,7 +36,9 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // normalize URI for consistent cycle detection and refSet cache key matching
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -49,20 +48,54 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     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.default)(retrievalURI, (0, _util.merge)(ctx.options, {
-      parse: {
-        mediaType: 'text/plain' // allow parser plugin detection
-      },
-      dereference: {
-        strategyOpts: {
-          [ARAZZO_DEREFERENCE_RECURSION_KEY]: {
-            sourceDescriptionsDepth: ctx.currentDepth + 1,
-            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+    let sourceDescriptionDereferenced;
+    if ((0, _apidomDatamodel.isParseResultElement)(existingParseResult)) {
+      // use existing parsed result - just dereference it (no re-fetch/re-parse)
+      sourceDescriptionDereferenced = await (0, _index.dereferenceApiDOM)(existingParseResult, (0, _util.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.default)(retrievalURI, (0, _util.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);
@@ -107,11 +140,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 = url.sanitize(url.stripHash(parseResultRetrievalURI));
   const results = [];
-  const strategyName = 'arazzo-1';
 
   // get API from dereferenced parse result
   const {
@@ -136,34 +203,30 @@ async function dereferenceSourceDescriptions(parseResult, reference, options) {
   // 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 _apidomDatamodel.AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${reference.uri}"`);
+    const annotation = new _apidomDatamodel.AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${baseURI}"`);
     annotation.classes.push('error');
     const parseResult = new _apidomDatamodel.ParseResultElement([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, _apidomNsArazzo.isSourceDescriptionElement)(sd)) return false;
     const name = (0, _apidomCore.toValue)(sd.name);
@@ -173,6 +236,8 @@ async function dereferenceSourceDescriptions(parseResult, reference, options) {
   // 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;

package/src/dereference/strategies/arazzo-1/{source-description.mjs → source-descriptions.mjs}

@@ -1,4 +1,4 @@
-import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, isParseResultElement, 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';
@@ -6,8 +6,7 @@ import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
 import { toValue } from '@speclynx/apidom-core';
 import * as url from "../../../util/url.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
-import dereference from "../../index.mjs"; // shared key for recursion state (works across JSON/YAML documents)
-const ARAZZO_DEREFERENCE_RECURSION_KEY = 'arazzo-1';
+import dereference, { dereferenceApiDOM } from "../../index.mjs";
 /**
  * Dereferences a single source description element.
  * Returns ParseResultElement on success, or with annotation if skipped.
@@ -32,7 +31,9 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // normalize URI for consistent cycle detection and refSet cache key matching
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -42,20 +43,54 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     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 dereference(retrievalURI, mergeOptions(ctx.options, {
-      parse: {
-        mediaType: 'text/plain' // allow parser plugin detection
-      },
-      dereference: {
-        strategyOpts: {
-          [ARAZZO_DEREFERENCE_RECURSION_KEY]: {
-            sourceDescriptionsDepth: ctx.currentDepth + 1,
-            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+    let sourceDescriptionDereferenced;
+    if (isParseResultElement(existingParseResult)) {
+      // use existing parsed result - just dereference it (no re-fetch/re-parse)
+      sourceDescriptionDereferenced = await dereferenceApiDOM(existingParseResult, mergeOptions(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 dereference(retrievalURI, mergeOptions(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);
@@ -100,11 +135,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
  */
-export async function dereferenceSourceDescriptions(parseResult, reference, options) {
+export async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
+  const baseURI = url.sanitize(url.stripHash(parseResultRetrievalURI));
   const results = [];
-  const strategyName = 'arazzo-1';
 
   // get API from dereferenced parse result
   const {
@@ -129,34 +198,30 @@ export async function dereferenceSourceDescriptions(parseResult, reference, opti
   // 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 AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${reference.uri}"`);
+    const annotation = new AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${baseURI}"`);
     annotation.classes.push('error');
     const parseResult = new ParseResultElement([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 (!isSourceDescriptionElement(sd)) return false;
     const name = toValue(sd.name);
@@ -166,6 +231,8 @@ export async function dereferenceSourceDescriptions(parseResult, reference, opti
   // 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;

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

@@ -40,7 +40,9 @@ async function parseSourceDescription(sourceDescription, ctx) {
     parseResult.push(annotation);
     return parseResult;
   }
-  const retrievalURI = url.resolve(ctx.baseURI, sourceDescriptionURI);
+
+  // normalize URI for consistent cycle detection and cache key matching
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -56,6 +58,9 @@ async function parseSourceDescription(sourceDescription, ctx) {
         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
@@ -108,27 +113,40 @@ async function parseSourceDescription(sourceDescription, ctx) {
 /**
  * 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 (caller responsibility to construct)
+ * @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. On success, returns one ParseResultElement per
- *   source description (each with class 'source-description' and name/type metadata).
+ * @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 sourceDescriptions option is disabled or no names match.
+ *   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';
  *
- * const fullOptions = mergeOptions(options, {
- *   parse: { parserOpts: { sourceDescriptions: true } }
- * });
- * const results = await parseSourceDescriptions(parseResult, uri, fullOptions);
+ * // 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
@@ -181,13 +199,8 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
     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, _apidomNsArazzo.isSourceDescriptionElement)(sd)) return false;
     const name = (0, _apidomCore.toValue)(sd.name);
@@ -197,6 +210,8 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
   // 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;