@speclynx/apidom-overlay 5.2.5 → 5.2.6

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 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)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
 ## [5.2.5](https://github.com/speclynx/apidom/compare/v5.2.4...v5.2.5) (2026-09-17)
 
 **Note:** Version bump only for package @speclynx/apidom-overlay

package/dist/apidom-overlay.browser.js

@@ -102127,6 +102127,17 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPOR
       })
     });
 
+    /**
+     * 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_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
     /**
      * Dereference source descriptions if option is enabled.
      */
@@ -102141,16 +102152,6 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPOR
       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_mjs__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.
@@ -102187,10 +102188,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_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(18917);
-/* harmony import */ var _options_util_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(7778);
-/* harmony import */ var _index_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(79920);
-/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(42424);
+/* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(164);
+/* harmony import */ var _util_url_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(18917);
+/* harmony import */ var _Reference_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(82302);
+/* harmony import */ var _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(88526);
+/* harmony import */ var _options_util_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(7778);
+/* harmony import */ var _parse_index_mjs__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(85533);
+/* harmony import */ var _index_mjs__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(79920);
+/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(42424);
+
+
+
+
 
 
 
@@ -102224,7 +102233,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
   }
 
   // normalize URI for consistent cycle detection and refSet cache key matching
-  const retrievalURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_6__.sanitize(_util_url_mjs__WEBPACK_IMPORTED_MODULE_6__.stripHash(_util_url_mjs__WEBPACK_IMPORTED_MODULE_6__.resolve(ctx.baseURI, sourceDescriptionURI)));
+  const retrievalURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_7__.sanitize(_util_url_mjs__WEBPACK_IMPORTED_MODULE_7__.stripHash(_util_url_mjs__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)
@@ -102243,58 +102252,69 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     annotation.classes.push('info');
     parseResult.push(annotation);
     parseResult.meta.set('parseResult', sharedDereferenceResult);
-    (0,_util_mjs__WEBPACK_IMPORTED_MODULE_9__.validateSourceDescriptionAPI)(parseResult, sourceDescription, sharedDereferenceResult.api, retrievalURI);
+    (0,_util_mjs__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_mjs__WEBPACK_IMPORTED_MODULE_8__.dereferenceApiDOM)(existingParseResult, (0,_options_util_mjs__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_mjs__WEBPACK_IMPORTED_MODULE_8__["default"])(retrievalURI, (0,_options_util_mjs__WEBPACK_IMPORTED_MODULE_7__.merge)(ctx.options, {
+      sourceDescriptionParseResult = await (0,_parse_index_mjs__WEBPACK_IMPORTED_MODULE_11__["default"])(retrievalURI, (0,_options_util_mjs__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_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
+        refs: [new _Reference_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]({
+          uri: retrievalURI,
+          value: sourceDescriptionParseResult
+        }), ...parentRefSet.refs.map(ref => new _Reference_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]({
+          ...ref,
+          refSet: undefined
+        }))]
+      });
     }
+    const sourceDescriptionDereferenced = await (0,_index_mjs__WEBPACK_IMPORTED_MODULE_12__.dereferenceApiDOM)(sourceDescriptionParseResult, (0,_options_util_mjs__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) {
@@ -102307,16 +102327,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_mjs__WEBPACK_IMPORTED_MODULE_9__.arazzoDocumentURIs)(retrievalURI, sourceDescriptionAPI)) {
+  for (const documentURI of (0,_util_mjs__WEBPACK_IMPORTED_MODULE_13__.arazzoDocumentURIs)(retrievalURI, sourceDescriptionAPI)) {
     ctx.dereferenced.set(documentURI, parseResult);
   }
-  ;(0,_util_mjs__WEBPACK_IMPORTED_MODULE_9__.validateSourceDescriptionAPI)(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
+  ;(0,_util_mjs__WEBPACK_IMPORTED_MODULE_13__.validateSourceDescriptionAPI)(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
   return parseResult;
 }
 
@@ -102369,7 +102396,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * @public
  */
 async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
-  const retrievalURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_6__.sanitize(_util_url_mjs__WEBPACK_IMPORTED_MODULE_6__.stripHash(parseResultRetrievalURI));
+  const retrievalURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_7__.sanitize(_util_url_mjs__WEBPACK_IMPORTED_MODULE_7__.stripHash(parseResultRetrievalURI));
   const results = [];
 
   // get API from dereferenced parse result
@@ -102400,7 +102427,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_mjs__WEBPACK_IMPORTED_MODULE_9__.arazzoDocumentURIs)(retrievalURI, api)];
+  const ancestors = [...(sharedOpts.sourceDescriptionsAncestors ?? []), ...(0,_util_mjs__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');
@@ -102410,7 +102437,7 @@ async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalUR
   }
   const ctx = {
     // base URI for resolving source description URLs honors Arazzo `$self` field
-    baseURI: (0,_util_mjs__WEBPACK_IMPORTED_MODULE_9__.resolveArazzo$selfField)(retrievalURI, api),
+    baseURI: (0,_util_mjs__WEBPACK_IMPORTED_MODULE_13__.resolveArazzo$selfField)(retrievalURI, api),
     options,
     strategyName,
     currentDepth,
@@ -102859,34 +102886,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;
     }
 
     /**