@speclynx/apidom-reference 5.2.5 → 5.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "5.2.5",
+  "version": "5.2.6",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -298,33 +298,33 @@
   "author": "Vladimir Gorej",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^8.0.0",
-    "@speclynx/apidom-core": "5.2.5",
-    "@speclynx/apidom-datamodel": "5.2.5",
-    "@speclynx/apidom-error": "5.2.5",
-    "@speclynx/apidom-json-pointer": "5.2.5",
-    "@speclynx/apidom-ns-arazzo-1": "5.2.5",
-    "@speclynx/apidom-ns-asyncapi-2": "5.2.5",
-    "@speclynx/apidom-ns-json-schema-2020-12": "5.2.5",
-    "@speclynx/apidom-ns-openapi-2": "5.2.5",
-    "@speclynx/apidom-ns-openapi-3-0": "5.2.5",
-    "@speclynx/apidom-ns-openapi-3-1": "5.2.5",
-    "@speclynx/apidom-ns-overlay-1": "5.2.5",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "5.2.5",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "5.2.5",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "5.2.5",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "5.2.5",
-    "@speclynx/apidom-parser-adapter-json": "5.2.5",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "5.2.5",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "5.2.5",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "5.2.5",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "5.2.5",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "5.2.5",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "5.2.5",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "5.2.5",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "5.2.5",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "5.2.5",
-    "@speclynx/apidom-traverse": "5.2.5",
+    "@babel/runtime-corejs3": "^8.0.5",
+    "@speclynx/apidom-core": "5.2.6",
+    "@speclynx/apidom-datamodel": "5.2.6",
+    "@speclynx/apidom-error": "5.2.6",
+    "@speclynx/apidom-json-pointer": "5.2.6",
+    "@speclynx/apidom-ns-arazzo-1": "5.2.6",
+    "@speclynx/apidom-ns-asyncapi-2": "5.2.6",
+    "@speclynx/apidom-ns-json-schema-2020-12": "5.2.6",
+    "@speclynx/apidom-ns-openapi-2": "5.2.6",
+    "@speclynx/apidom-ns-openapi-3-0": "5.2.6",
+    "@speclynx/apidom-ns-openapi-3-1": "5.2.6",
+    "@speclynx/apidom-ns-overlay-1": "5.2.6",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "5.2.6",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "5.2.6",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "5.2.6",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "5.2.6",
+    "@speclynx/apidom-parser-adapter-json": "5.2.6",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "5.2.6",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "5.2.6",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "5.2.6",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "5.2.6",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "5.2.6",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "5.2.6",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "5.2.6",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "5.2.6",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "5.2.6",
+    "@speclynx/apidom-traverse": "5.2.6",
     "@swaggerexpert/arazzo-runtime-expression": "^3.2.0",
     "axios": "^1.20.0",
     "picomatch": "^4.0.7",
@@ -346,5 +346,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "677f42e6af4e7b5311c74cd054283c943f8700a9"
+  "gitHead": "c78f4a79e2b91b9ad099dff6dff5dc35236ae75b"
 }

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

@@ -121,6 +121,17 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
       })
     });
 
+    /**
+     * 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.default({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
     /**
      * Dereference source descriptions if option is enabled.
      */
@@ -135,16 +146,6 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
       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.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.

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

@@ -70,6 +70,17 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
       })
     });
 
+    /**
+     * 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({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
     /**
      * Dereference source descriptions if option is enabled.
      */
@@ -84,16 +95,6 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
       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({
-        ...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.

package/src/dereference/strategies/arazzo-1/source-descriptions.cjs

@@ -1,5 +1,6 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
@@ -8,9 +9,13 @@ exports.dereferenceSourceDescriptions = dereferenceSourceDescriptions;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
 var _apidomCore = require("@speclynx/apidom-core");
+var _ramda = require("ramda");
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
 var _util = require("../../../options/util.cjs");
-var _index = _interopRequireWildcard(require("../../index.cjs"));
+var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
+var _index2 = require("../../index.cjs");
 var _util2 = require("./util.cjs");
 /**
  * Dereferences a single source description element.
@@ -63,53 +68,64 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
   // 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, _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,
-              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, _apidomDatamodel.isParseResultElement)(existingParseResult)) {
+      sourceDescriptionParseResult = existingParseResult;
     } else {
-      // no existing parse result - fetch, parse, and dereference
-      sourceDescriptionDereferenced = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
+      sourceDescriptionParseResult = 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,
-              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.default({
+        refs: [new _Reference.default({
+          uri: retrievalURI,
+          value: sourceDescriptionParseResult
+        }), ...parentRefSet.refs.map(ref => new _Reference.default({
+          ...ref,
+          refSet: undefined
+        }))]
+      });
+    }
+    const sourceDescriptionDereferenced = await (0, _index2.dereferenceApiDOM)(sourceDescriptionParseResult, (0, _util.merge)((0, _ramda.assocPath)(['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) {
       parseResult.push(item);
@@ -121,6 +137,13 @@ 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

package/src/dereference/strategies/arazzo-1/source-descriptions.mjs

@@ -1,9 +1,13 @@
 import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, isParseResultElement } from '@speclynx/apidom-datamodel';
 import { isArazzoSpecification1Element, isSourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
 import { toValue } from '@speclynx/apidom-core';
+import { assocPath } from 'ramda';
 import * as url from "../../../util/url.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
-import dereference, { dereferenceApiDOM } from "../../index.mjs";
+import parse from "../../../parse/index.mjs";
+import { dereferenceApiDOM } from "../../index.mjs";
 import { arazzoDocumentURIs, resolveArazzo$selfField, validateSourceDescriptionAPI } from "./util.mjs";
 /**
  * Dereferences a single source description element.
@@ -56,53 +60,64 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
   // 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 (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,
-              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 (isParseResultElement(existingParseResult)) {
+      sourceDescriptionParseResult = existingParseResult;
     } else {
-      // no existing parse result - fetch, parse, and dereference
-      sourceDescriptionDereferenced = await dereference(retrievalURI, mergeOptions(ctx.options, {
+      sourceDescriptionParseResult = await parse(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,
-              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({
+        refs: [new Reference({
+          uri: retrievalURI,
+          value: sourceDescriptionParseResult
+        }), ...parentRefSet.refs.map(ref => new Reference({
+          ...ref,
+          refSet: undefined
+        }))]
+      });
+    }
+    const sourceDescriptionDereferenced = await dereferenceApiDOM(sourceDescriptionParseResult, mergeOptions(assocPath(['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) {
       parseResult.push(item);
@@ -114,6 +129,13 @@ 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

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

@@ -252,34 +252,38 @@ class Arazzo1DereferenceVisitor {
       return;
     }
     const runtimeExpression = (0, _apidomCore.toValue)(referencingElement.reference);
-
-    // parse the runtime expression
-    const {
-      result,
-      tree
-    } = (0, _arazzoRuntimeExpression.parse)(runtimeExpression);
-    if (!result.success) {
-      throw new _apidomError.ApiDOMStructuredError(`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
-        runtimeExpression
-      });
-    }
-
-    // ReusableElement can only reference components
-    if (tree.type !== 'ComponentsExpression') {
-      throw new _apidomError.ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
-        runtimeExpression
-      });
-    }
-
-    // evaluate runtime expression as JSON Pointer to get the referenced element
-    const jsonPointer = (0, _apidomJsonPointer.compile)(['components', tree.componentType, tree.componentName]);
     let referencedElement;
     try {
-      referencedElement = (0, _apidomJsonPointer.evaluate)(this.reference.value.result, jsonPointer);
-    } catch {
-      throw new _apidomError.ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" cannot be resolved`, {
-        runtimeExpression
-      });
+      // parse the runtime expression
+      const {
+        result,
+        tree
+      } = (0, _arazzoRuntimeExpression.parse)(runtimeExpression);
+      if (!result.success) {
+        throw new _apidomError.ApiDOMStructuredError(`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
+          runtimeExpression
+        });
+      }
+
+      // ReusableElement can only reference components
+      if (tree.type !== 'ComponentsExpression') {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
+          runtimeExpression
+        });
+      }
+
+      // evaluate runtime expression as JSON Pointer to get the referenced element
+      const jsonPointer = (0, _apidomJsonPointer.compile)(['components', tree.componentType, tree.componentName]);
+      try {
+        referencedElement = (0, _apidomJsonPointer.evaluate)(this.reference.value.result, jsonPointer);
+      } catch {
+        throw new _apidomError.ApiDOMStructuredError(`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;
     }
 
     /**

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

@@ -243,34 +243,38 @@ class Arazzo1DereferenceVisitor {
       return;
     }
     const runtimeExpression = toValue(referencingElement.reference);
-
-    // parse the runtime expression
-    const {
-      result,
-      tree
-    } = parseRuntimeExpression(runtimeExpression);
-    if (!result.success) {
-      throw new ApiDOMStructuredError(`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
-        runtimeExpression
-      });
-    }
-
-    // ReusableElement can only reference components
-    if (tree.type !== 'ComponentsExpression') {
-      throw new ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
-        runtimeExpression
-      });
-    }
-
-    // evaluate runtime expression as JSON Pointer to get the referenced element
-    const jsonPointer = jsonPointerCompile(['components', tree.componentType, tree.componentName]);
     let referencedElement;
     try {
-      referencedElement = jsonPointerEvaluate(this.reference.value.result, jsonPointer);
-    } catch {
-      throw new ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" cannot be resolved`, {
-        runtimeExpression
-      });
+      // parse the runtime expression
+      const {
+        result,
+        tree
+      } = parseRuntimeExpression(runtimeExpression);
+      if (!result.success) {
+        throw new ApiDOMStructuredError(`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
+          runtimeExpression
+        });
+      }
+
+      // ReusableElement can only reference components
+      if (tree.type !== 'ComponentsExpression') {
+        throw new ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
+          runtimeExpression
+        });
+      }
+
+      // evaluate runtime expression as JSON Pointer to get the referenced element
+      const jsonPointer = jsonPointerCompile(['components', tree.componentType, tree.componentName]);
+      try {
+        referencedElement = jsonPointerEvaluate(this.reference.value.result, jsonPointer);
+      } catch {
+        throw new ApiDOMStructuredError(`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;
     }
 
     /**