@speclynx/apidom-reference 5.2.5 → 5.2.6

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.2.6](https://github.com/speclynx/apidom/compare/v5.2.5...v5.2.6) (2026-09-19)
+
+### Bug Fixes
+
+- **reference:** honour continueOnError for Arazzo Reusable Objects ([#552](https://github.com/speclynx/apidom/issues/552)) ([2bcd675](https://github.com/speclynx/apidom/commit/2bcd675d16fc1bf3fc5079fdee37419c1d84017c)), closes [#550](https://github.com/speclynx/apidom/issues/550)
+- **reference:** isolate refSet of Arazzo source descriptions ([#553](https://github.com/speclynx/apidom/issues/553)) ([ac21c16](https://github.com/speclynx/apidom/commit/ac21c165104e604aa59f027a8d78645c8bd9ca66)), closes [#551](https://github.com/speclynx/apidom/issues/551)
+
 ## [5.2.5](https://github.com/speclynx/apidom/compare/v5.2.4...v5.2.5) (2026-09-17)
 
 ### Bug Fixes

package/README.md

@@ -2071,6 +2071,10 @@ Strategy-specific options take precedence over global options.
   The `SourceDescriptionElement`'s `'parseResult'` meta points at that same `ParseResultElement`, so the dereferenced
   document is reachable from every source description that references it.
 
+  When `dereference.refSet` is provided, source descriptions reuse the documents it already contains,
+  and every document reached through a source description is added to it.
+  This is also how resolving with `sourceDescriptions` enabled reports the documents behind source descriptions.
+
 ###### Error handling
 
 The source descriptions dereferencing uses annotations instead of throwing errors, allowing dereferencing to continue
@@ -2496,16 +2500,16 @@ await dereference('/home/user/oas.json', {
 // errors is an array of UnresolvableReferenceError instances
 ```
 
-Each `UnresolvableReferenceError` (extends `DereferenceError`) carries structured context:
+Each `UnresolvableReferenceError` (extends `ResolveError`) carries structured context:
 
 | Property | Type | Description |
 |---|---|---|
 | `message` | `string` | Contextual description (e.g., "Error while dereferencing Reference Object. Cannot resolve $ref ...") |
-| `type` | `string` | Element type that failed (e.g., `"reference"`, `"pathItem"`, `"schema"`, `"link"`, `"example"`) |
+| `type` | `string` | Element type that failed (e.g., `"reference"`, `"pathItem"`, `"schema"`, `"link"`, `"example"`, `"reusable"`) |
 | `uri` | `string` | Document URI where the error occurred |
 | `location` | `string` | JSON Pointer to the element within the document |
 | `codeFrame` | `string` | YAML snippet of the referencing element |
-| `refFieldName` | `string` | Reference field name (e.g., `"$ref"`, `"operationRef"`, `"externalValue"`) |
+| `refFieldName` | `string` | Reference field name (e.g., `"$ref"`, `"operationRef"`, `"externalValue"`, `"reference"`) |
 | `refFieldValue` | `string` | Reference field value |
 | `trace` | `Array` | Chain of reference hops from entry document to the failure |
 | `cause` | `Error` | The underlying error |

package/dist/apidom-reference.browser.js

@@ -5036,6 +5036,17 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMPORT
       })
     });
 
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     * Replayed before source descriptions are dereferenced, so they can reuse the refs.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference_ts__WEBPACK_IMPORTED_MODULE_7__["default"]({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
     /**
      * Dereference source descriptions if option is enabled.
      */
@@ -5050,16 +5061,6 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_ts__WEBPACK_IMPORT
       parseResult.push(...sourceDescriptions);
     }
 
-    /**
-     * If immutable option is set, replay refs from the refSet.
-     */
-    if (options.dereference.immutable) {
-      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference_ts__WEBPACK_IMPORTED_MODULE_7__["default"]({
-        ...ref,
-        uri: ref.uri.replace(/^immutable:\/\//, '')
-      })).forEach(ref => immutableRefSet.add(ref));
-    }
-
     /**
      * Release all memory if this refSet was not provided as a configuration option.
      * If provided as configuration option, then provider is responsible for cleanup.
@@ -5096,10 +5097,18 @@ __webpack_require__.r(__webpack_exports__);
 /* 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_core__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(44673);
-/* harmony import */ var _util_url_ts__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(30658);
-/* harmony import */ var _options_util_ts__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(86547);
-/* harmony import */ var _index_ts__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(42037);
-/* harmony import */ var _util_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(91005);
+/* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(164);
+/* harmony import */ var _util_url_ts__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(30658);
+/* harmony import */ var _Reference_ts__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(98979);
+/* harmony import */ var _ReferenceSet_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(24131);
+/* harmony import */ var _options_util_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(86547);
+/* harmony import */ var _parse_index_ts__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(35014);
+/* harmony import */ var _index_ts__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(42037);
+/* harmony import */ var _util_ts__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(91005);
+
+
+
+
 
 
 
@@ -5133,7 +5142,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
   }
 
   // normalize URI for consistent cycle detection and refSet cache key matching
-  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_6__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_6__.stripHash(_util_url_ts__WEBPACK_IMPORTED_MODULE_6__.resolve(ctx.baseURI, sourceDescriptionURI)));
+  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_7__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_7__.stripHash(_util_url_ts__WEBPACK_IMPORTED_MODULE_7__.resolve(ctx.baseURI, sourceDescriptionURI)));
   parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if the document is still being dereferenced higher up the chain (cycle detection)
@@ -5152,58 +5161,69 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     annotation.classes.push('info');
     parseResult.push(annotation);
     parseResult.meta.set('parseResult', sharedDereferenceResult);
-    (0,_util_ts__WEBPACK_IMPORTED_MODULE_9__.validateSourceDescriptionAPI)(parseResult, sourceDescription, sharedDereferenceResult.api, retrievalURI);
+    (0,_util_ts__WEBPACK_IMPORTED_MODULE_13__.validateSourceDescriptionAPI)(parseResult, sourceDescription, sharedDereferenceResult.api, retrievalURI);
     return parseResult;
   }
 
   // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
   const existingParseResult = sourceDescription.meta.get('parseResult');
+  const parentRefSet = ctx.options.dereference.refSet;
+  let refSet = null;
   try {
-    let sourceDescriptionDereferenced;
-    if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isParseResultElement)(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      sourceDescriptionDereferenced = await (0,_index_ts__WEBPACK_IMPORTED_MODULE_8__.dereferenceApiDOM)(existingParseResult, (0,_options_util_ts__WEBPACK_IMPORTED_MODULE_7__.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,
-              sourceDescriptionsAncestors: ctx.ancestors,
-              sourceDescriptionsDereferenced: ctx.dereferenced
-            }
-          }
-        }
-      }));
+    // source description document comes from, in order of preference:
+    // caller-supplied refSet, parse phase, or is fetched and parsed now
+    const cachedReference = parentRefSet?.find(ref => ref.uri === retrievalURI);
+    let sourceDescriptionParseResult;
+    let isFreshlyParsed = false;
+    if (cachedReference !== undefined) {
+      sourceDescriptionParseResult = cachedReference.value;
+    } else if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isParseResultElement)(existingParseResult)) {
+      sourceDescriptionParseResult = existingParseResult;
     } else {
-      // no existing parse result - fetch, parse, and dereference
-      sourceDescriptionDereferenced = await (0,_index_ts__WEBPACK_IMPORTED_MODULE_8__["default"])(retrievalURI, (0,_options_util_ts__WEBPACK_IMPORTED_MODULE_7__.merge)(ctx.options, {
+      sourceDescriptionParseResult = await (0,_parse_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: {
-            // 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,
-              sourceDescriptionsAncestors: ctx.ancestors,
-              sourceDescriptionsDereferenced: ctx.dereferenced
-            }
-          }
-        }
+          mediaType: 'text/plain'
+        } // allow parser plugin detection
       }));
+      isFreshlyParsed = true;
+    }
+
+    // caller-supplied refSet is rooted at the entry document, but strategies dereference
+    // the root of the refSet; re-root its references at the source description
+    if (parentRefSet !== null) {
+      refSet = new _ReferenceSet_ts__WEBPACK_IMPORTED_MODULE_9__["default"]({
+        refs: [new _Reference_ts__WEBPACK_IMPORTED_MODULE_8__["default"]({
+          uri: retrievalURI,
+          value: sourceDescriptionParseResult
+        }), ...parentRefSet.refs.map(ref => new _Reference_ts__WEBPACK_IMPORTED_MODULE_8__["default"]({
+          ...ref,
+          refSet: undefined
+        }))]
+      });
     }
+    const sourceDescriptionDereferenced = await (0,_index_ts__WEBPACK_IMPORTED_MODULE_12__.dereferenceApiDOM)(sourceDescriptionParseResult, (0,_options_util_ts__WEBPACK_IMPORTED_MODULE_10__.merge)((0,ramda__WEBPACK_IMPORTED_MODULE_6__["default"])(['dereference', 'refSet'], refSet, ctx.options), {
+      parse: {
+        mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
+      },
+      resolve: {
+        baseURI: retrievalURI
+      },
+      dereference: {
+        // freshly parsed document not reported to any refSet can be dereferenced in mutable mode
+        immutable: ctx.options.dereference.immutable && !(isFreshlyParsed && parentRefSet === null),
+        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,
+            sourceDescriptionsAncestors: ctx.ancestors,
+            sourceDescriptionsDereferenced: ctx.dereferenced
+          }
+        }
+      }
+    }));
 
     // merge dereferenced result into our parse result
     for (const item of sourceDescriptionDereferenced) {
@@ -5216,16 +5236,23 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     annotation.classes.push('error');
     parseResult.push(annotation);
     return parseResult;
+  } finally {
+    // report documents reached through the source description to the caller-supplied refSet,
+    // even when dereferencing it failed
+    if (parentRefSet !== null && refSet !== null) {
+      parentRefSet.merge(refSet);
+      parentRefSet.circular ||= refSet.circular;
+    }
   }
 
   // register dereferenced document for later references to it
   const {
     api: sourceDescriptionAPI
   } = parseResult;
-  for (const documentURI of (0,_util_ts__WEBPACK_IMPORTED_MODULE_9__.arazzoDocumentURIs)(retrievalURI, sourceDescriptionAPI)) {
+  for (const documentURI of (0,_util_ts__WEBPACK_IMPORTED_MODULE_13__.arazzoDocumentURIs)(retrievalURI, sourceDescriptionAPI)) {
     ctx.dereferenced.set(documentURI, parseResult);
   }
-  ;(0,_util_ts__WEBPACK_IMPORTED_MODULE_9__.validateSourceDescriptionAPI)(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
+  ;(0,_util_ts__WEBPACK_IMPORTED_MODULE_13__.validateSourceDescriptionAPI)(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
   return parseResult;
 }
 
@@ -5278,7 +5305,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * @public
  */
 async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
-  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_6__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_6__.stripHash(parseResultRetrievalURI));
+  const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_7__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_7__.stripHash(parseResultRetrievalURI));
   const results = [];
 
   // get API from dereferenced parse result
@@ -5309,7 +5336,7 @@ async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalUR
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
   const dereferenced = sharedOpts.sourceDescriptionsDereferenced ?? new Map();
   // current file is an ancestor of everything dereferenced below
-  const ancestors = [...(sharedOpts.sourceDescriptionsAncestors ?? []), ...(0,_util_ts__WEBPACK_IMPORTED_MODULE_9__.arazzoDocumentURIs)(retrievalURI, api)];
+  const ancestors = [...(sharedOpts.sourceDescriptionsAncestors ?? []), ...(0,_util_ts__WEBPACK_IMPORTED_MODULE_13__.arazzoDocumentURIs)(retrievalURI, api)];
   if (currentDepth >= maxDepth) {
     const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](`Maximum dereference depth of ${maxDepth} has been exceeded by file "${retrievalURI}"`);
     annotation.classes.push('error');
@@ -5319,7 +5346,7 @@ async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalUR
   }
   const ctx = {
     // base URI for resolving source description URLs honors Arazzo `$self` field
-    baseURI: (0,_util_ts__WEBPACK_IMPORTED_MODULE_9__.resolveArazzo$selfField)(retrievalURI, api),
+    baseURI: (0,_util_ts__WEBPACK_IMPORTED_MODULE_13__.resolveArazzo$selfField)(retrievalURI, api),
     options,
     strategyName,
     currentDepth,
@@ -5771,34 +5798,38 @@ class Arazzo1DereferenceVisitor {
       return;
     }
     const runtimeExpression = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(referencingElement.reference);
-
-    // parse the runtime expression
-    const {
-      result,
-      tree
-    } = (0,_swaggerexpert_arazzo_runtime_expression__WEBPACK_IMPORTED_MODULE_15__.parse)(runtimeExpression);
-    if (!result.success) {
-      throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_8__["default"](`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
-        runtimeExpression
-      });
-    }
-
-    // ReusableElement can only reference components
-    if (tree.type !== 'ComponentsExpression') {
-      throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_8__["default"](`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
-        runtimeExpression
-      });
-    }
-
-    // evaluate runtime expression as JSON Pointer to get the referenced element
-    const jsonPointer = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_11__.compile)(['components', tree.componentType, tree.componentName]);
     let referencedElement;
     try {
-      referencedElement = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_10__.evaluate)(this.reference.value.result, jsonPointer);
-    } catch {
-      throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_8__["default"](`Reusable Object reference "${runtimeExpression}" cannot be resolved`, {
-        runtimeExpression
-      });
+      // parse the runtime expression
+      const {
+        result,
+        tree
+      } = (0,_swaggerexpert_arazzo_runtime_expression__WEBPACK_IMPORTED_MODULE_15__.parse)(runtimeExpression);
+      if (!result.success) {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_8__["default"](`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
+          runtimeExpression
+        });
+      }
+
+      // ReusableElement can only reference components
+      if (tree.type !== 'ComponentsExpression') {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_8__["default"](`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
+          runtimeExpression
+        });
+      }
+
+      // evaluate runtime expression as JSON Pointer to get the referenced element
+      const jsonPointer = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_11__.compile)(['components', tree.componentType, tree.componentName]);
+      try {
+        referencedElement = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_10__.evaluate)(this.reference.value.result, jsonPointer);
+      } catch {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_8__["default"](`Reusable Object reference "${runtimeExpression}" cannot be resolved`, {
+          runtimeExpression
+        });
+      }
+    } catch (error) {
+      this.handleError(`Error while dereferencing Reusable Object. Cannot resolve reference "${runtimeExpression}": ${error.message}`, error, referencingElement, 'reference', runtimeExpression, path);
+      return;
     }
 
     /**