@speclynx/apidom-reference 5.2.4 → 5.2.6

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

@@ -1,14 +1,15 @@
 import { propEq, none } from 'ramda';
-import { isElement, isStringElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
+import { isElement, isStringElement, isParseResultElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
 import { toValue, toYAML } from '@speclynx/apidom-core';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { traverse, traverseAsync } from '@speclynx/apidom-traverse';
 import { evaluate as jsonPointerEvaluate, compile as jsonPointerCompile, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
 import { isParameterElement, isJSONSchemaElement, isBooleanJSONSchemaElement } from '@speclynx/apidom-ns-arazzo-1';
 import { parse as parseRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
-import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./selectors/$anchor.mjs";
-import { evaluate as uriEvaluate } from "./selectors/uri.mjs";
-import { resolveSchema$refField } from "../openapi-3-1/util.mjs";
+import { isAnchor, uriToAnchor, locate as $anchorLocate } from "./selectors/$anchor.mjs";
+import { locate as uriLocate } from "./selectors/uri.mjs";
+import { locate as jsonPointerLocate } from "../openapi-3-1/selectors/json-pointer.mjs";
+import { schema$idsOf, resolveSchema$ids, resolveSchemaBaseURI, resolveSchema$refField } from "../openapi-3-1/util.mjs";
 import { maybeRefractToJSONSchemaElement, resolveArazzo$selfField, identifiedBy$self } from "./util.mjs";
 import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
 import MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
@@ -36,8 +37,23 @@ class Arazzo1DereferenceVisitor {
    */
   baseURI;
   options;
+
+  /**
+   * Index of `$id`-bearing schemas per document, shared across nested visitors
+   * of a single dereference run so it never outlives mutations of the documents.
+   */
+  schema$idIndex;
   visited;
 
+  /**
+   * `$id`s of the JSON Schema elements enclosing the traversal root within its
+   * document (outermost first). Empty when the root is the document itself; a
+   * nested visitor traversing a fragment is seeded with the `$id`s of the
+   * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
+   * against the same base as they would from the document root.
+   */
+  ancestorSchema$ids;
+
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
    * Used for cycle detection: if a referenced element is found in
@@ -48,15 +64,19 @@ class Arazzo1DereferenceVisitor {
     reference,
     options,
     indirections = [],
+    schema$idIndex = new WeakMap(),
     ancestors = new AncestorLineage(),
-    visited = new WeakSet()
+    visited = new WeakSet(),
+    ancestorSchema$ids = []
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.baseURI = resolveArazzo$selfField(reference.uri, reference.value?.result);
     this.options = options;
+    this.schema$idIndex = schema$idIndex;
     this.ancestors = new AncestorLineage(...ancestors);
     this.visited = visited;
+    this.ancestorSchema$ids = ancestorSchema$ids;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -223,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;
     }
 
     /**
@@ -298,7 +322,11 @@ class Arazzo1DereferenceVisitor {
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = resolveSchema$refField(this.baseURI, referencingElement);
+      // base URI in effect at the traversal root: the document base refined by
+      // the $ids of the schemas enclosing the root when the root is a fragment
+      const rootBaseURI = resolveSchema$ids(this.baseURI, this.ancestorSchema$ids);
+      const schemaBaseURI = resolveSchemaBaseURI(rootBaseURI, path);
+      const $refBaseURI = resolveSchema$refField(schemaBaseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new File({
         uri: $refBaseURIStrippedHash
@@ -310,13 +338,32 @@ class Arazzo1DereferenceVisitor {
 
       // determining reference, proper evaluation and selection mechanism
       let referencedElement;
+      // $ids of the schemas enclosing the referenced element within its document
+      let ancestorSchema$ids;
       try {
         if (isUnknownURI || isURL) {
           // we're dealing with canonical URI or URL with possible fragment
           retrievalURI = this.toBaseURI($refBaseURI);
           const selector = $refBaseURI;
-          const referenceAsSchema = maybeRefractToJSONSchemaElement(reference.value.result);
-          referencedElement = uriEvaluate(selector, referenceAsSchema);
+          const documentElement = reference.value.result;
+          const referenceAsSchema = maybeRefractToJSONSchemaElement(documentElement);
+          // a document that is itself a fragment detached from its source carries
+          // the $ids enclosing it only as `ancestorSchema$ids`: its $ids are then
+          // indexed against the base that chain leaves in effect, and the chain
+          // prefixes the one of the located schema. A nested visitor rooted at a
+          // fragment of a whole document indexes that document against its own base.
+          const rootNode = path.getAncestorNodes().at(-1) ?? path.node;
+          const isDocumentRoot = (isParseResultElement(rootNode) ? rootNode.result : rootNode) === documentElement;
+          ({
+            element: referencedElement,
+            ancestorSchema$ids
+          } = uriLocate(selector, referenceAsSchema, {
+            baseURI: isDocumentRoot ? rootBaseURI : this.baseURI,
+            index: this.schema$idIndex
+          }));
+          if (isDocumentRoot) {
+            ancestorSchema$ids = [...this.ancestorSchema$ids, ...ancestorSchema$ids];
+          }
           referencedElement = maybeRefractToJSONSchemaElement(referencedElement);
 
           // ignore resolving internal Schema Objects
@@ -348,7 +395,10 @@ class Arazzo1DereferenceVisitor {
           reference = await this.toReference(url.unsanitize($refBaseURI));
           const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
           const referenceAsSchema = maybeRefractToJSONSchemaElement(reference.value.result);
-          referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
+          ({
+            element: referencedElement,
+            ancestorSchema$ids
+          } = jsonPointerLocate(referenceAsSchema, selector));
           referencedElement = maybeRefractToJSONSchemaElement(referencedElement);
         }
       } catch (error) {
@@ -375,7 +425,10 @@ class Arazzo1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = uriToAnchor($refBaseURI);
             const referenceAsSchema = maybeRefractToJSONSchemaElement(reference.value.result);
-            referencedElement = $anchorEvaluate(selector, referenceAsSchema);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = $anchorLocate(selector, referenceAsSchema));
             referencedElement = maybeRefractToJSONSchemaElement(referencedElement);
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
@@ -396,7 +449,10 @@ class Arazzo1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
             const referenceAsSchema = maybeRefractToJSONSchemaElement(reference.value.result);
-            referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = jsonPointerLocate(referenceAsSchema, selector));
             referencedElement = maybeRefractToJSONSchemaElement(referencedElement);
           }
         } else {
@@ -453,7 +509,11 @@ class Arazzo1DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isJSONSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+      // content transplanted into the referencing site is traversed under that
+      // site's $id chain; a fragment enclosed by a different chain has its own
+      // $refs resolved in place first, by a nested visitor seeded with that chain
+      const hasDifferentEnclosingBase = resolveSchema$ids(resolveArazzo$selfField(reference.uri, reference.value.result), ancestorSchema$ids) !== resolveSchema$ids(rootBaseURI, schema$idsOf(path.getAncestorNodes().reverse()));
+      if ((isExternalReference || isNonEntryDocument || hasDifferentEnclosingBase || isJSONSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
         if (shouldDetectCircular) {
           this.visited.add(referencedElement);
         }
@@ -464,8 +524,10 @@ class Arazzo1DereferenceVisitor {
           reference,
           indirections: [...this.indirections],
           options: this.options,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
-          ancestors: ancestorsLineage
+          ancestors: ancestorsLineage,
+          ancestorSchema$ids
         });
         referencedElement = await traverseAsync(referencedElement, visitor, {
           mutable: true,

package/src/dereference/strategies/openapi-3-1/index.cjs

@@ -92,7 +92,8 @@ class OpenAPI3_1DereferenceStrategy extends _DereferenceStrategy.default {
     const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor.default({
       reference: reference,
-      options
+      options,
+      ancestorSchema$ids: (0, _util.detachedRootSchema$ids)(refSet.rootRef.value.result)
     });
     const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
       mutable: true,

package/src/dereference/strategies/openapi-3-1/index.mjs

@@ -6,6 +6,7 @@ import DereferenceStrategy from "../DereferenceStrategy.mjs";
 import Reference from "../../../Reference.mjs";
 import ReferenceSet from "../../../ReferenceSet.mjs";
 import OpenAPI3_1DereferenceVisitor from "./visitor.mjs";
+import { detachedRootSchema$ids } from "./util.mjs";
 /**
  * @public
  */
@@ -59,7 +60,8 @@ class OpenAPI3_1DereferenceStrategy extends DereferenceStrategy {
     const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new OpenAPI3_1DereferenceVisitor({
       reference: reference,
-      options
+      options,
+      ancestorSchema$ids: detachedRootSchema$ids(refSet.rootRef.value.result)
     });
     const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
       mutable: true,

package/src/dereference/strategies/openapi-3-1/selectors/$anchor.cjs

@@ -22,12 +22,13 @@ Object.defineProperty(exports, "JsonSchema$anchorError", {
     return _JsonSchema$anchorError.default;
   }
 });
-exports.uriToAnchor = exports.parse = exports.isAnchor = exports.evaluate = void 0;
+exports.uriToAnchor = exports.parse = exports.locate = exports.isAnchor = exports.evaluate = void 0;
 var _ramdaAdjunct = require("ramda-adjunct");
 var _apidomCore = require("@speclynx/apidom-core");
 var _apidomTraverse = require("@speclynx/apidom-traverse");
 var _apidomNsJsonSchema = require("@speclynx/apidom-ns-json-schema-2020-12");
 var _url = require("../../../../util/url.cjs");
+var _util = require("../util.cjs");
 var _EvaluationJsonSchema$anchorError = _interopRequireDefault(require("../../../../errors/EvaluationJsonSchema$anchorError.cjs"));
 var _InvalidJsonSchema$anchorError = _interopRequireDefault(require("../../../../errors/InvalidJsonSchema$anchorError.cjs"));
 var _JsonSchema$anchorError = _interopRequireDefault(require("../../../../errors/JsonSchema$anchorError.cjs"));
@@ -65,11 +66,12 @@ const parse = anchor => {
 };
 
 /**
- * Evaluates JSON Schema $anchor against ApiDOM fragment.
+ * Locates the schema identified by JSON Schema $anchor within ApiDOM fragment,
+ * along with the `$id`s of the schemas enclosing it, the search root included.
  * @public
  */
 exports.parse = parse;
-const evaluate = (anchor, element) => {
+const locate = (anchor, element) => {
   const token = parse(anchor);
   const resultPath = (0, _apidomTraverse.find)(element,
   // @ts-ignore
@@ -77,6 +79,16 @@ const evaluate = (anchor, element) => {
   if ((0, _ramdaAdjunct.isUndefined)(resultPath)) {
     throw new _EvaluationJsonSchema$anchorError.default(`Evaluation failed on token: "${token}"`);
   }
-  return resultPath.node;
+  return {
+    element: resultPath.node,
+    ancestorSchema$ids: (0, _util.schema$idsOf)(resultPath.getAncestorNodes().reverse())
+  };
 };
+
+/**
+ * Evaluates JSON Schema $anchor against ApiDOM fragment.
+ * @public
+ */
+exports.locate = locate;
+const evaluate = (anchor, element) => locate(anchor, element).element;
 exports.evaluate = evaluate;

package/src/dereference/strategies/openapi-3-1/selectors/$anchor.mjs

@@ -3,6 +3,7 @@ import { toValue } from '@speclynx/apidom-core';
 import { find } from '@speclynx/apidom-traverse';
 import { isJSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
 import { getHash } from "../../../../util/url.mjs";
+import { schema$idsOf } from "../util.mjs";
 import EvaluationJsonSchema$anchorError from "../../../../errors/EvaluationJsonSchema$anchorError.mjs";
 import InvalidJsonSchema$anchorError from "../../../../errors/InvalidJsonSchema$anchorError.mjs";
 /**
@@ -37,10 +38,11 @@ export const parse = anchor => {
 };
 
 /**
- * Evaluates JSON Schema $anchor against ApiDOM fragment.
+ * Locates the schema identified by JSON Schema $anchor within ApiDOM fragment,
+ * along with the `$id`s of the schemas enclosing it, the search root included.
  * @public
  */
-export const evaluate = (anchor, element) => {
+export const locate = (anchor, element) => {
   const token = parse(anchor);
   const resultPath = find(element,
   // @ts-ignore
@@ -48,7 +50,16 @@ export const evaluate = (anchor, element) => {
   if (isUndefined(resultPath)) {
     throw new EvaluationJsonSchema$anchorError(`Evaluation failed on token: "${token}"`);
   }
-  return resultPath.node;
+  return {
+    element: resultPath.node,
+    ancestorSchema$ids: schema$idsOf(resultPath.getAncestorNodes().reverse())
+  };
 };
+
+/**
+ * Evaluates JSON Schema $anchor against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (anchor, element) => locate(anchor, element).element;
 export { EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError };
 export { default as JsonSchema$anchorError } from "../../../../errors/JsonSchema$anchorError.mjs";

package/src/dereference/strategies/openapi-3-1/selectors/json-pointer.cjs

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.locate = void 0;
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _util = require("../util.cjs");
+/**
+ * Locates the element addressed by JSON Pointer within ApiDOM fragment, along
+ * with the `$id`s of the schemas enclosing it: the elements the pointer walks
+ * through on its way to the target, the search root included.
+ */
+const locate = (element, jsonPointer) => {
+  const trace = {
+    steps: []
+  };
+  const result = (0, _apidomJsonPointer.evaluate)(element, jsonPointer, {
+    trace
+  });
+
+  // each step's input is the node the token was applied to, so the inputs are
+  // exactly the walked nodes minus the target
+  return {
+    element: result,
+    ancestorSchema$ids: (0, _util.schema$idsOf)(trace.steps.map(step => step.input))
+  };
+};
+exports.locate = locate;

package/src/dereference/strategies/openapi-3-1/selectors/json-pointer.mjs

@@ -0,0 +1,22 @@
+import { evaluate as jsonPointerEvaluate } from '@speclynx/apidom-json-pointer';
+import { schema$idsOf } from "../util.mjs";
+/**
+ * Locates the element addressed by JSON Pointer within ApiDOM fragment, along
+ * with the `$id`s of the schemas enclosing it: the elements the pointer walks
+ * through on its way to the target, the search root included.
+ */
+export const locate = (element, jsonPointer) => {
+  const trace = {
+    steps: []
+  };
+  const result = jsonPointerEvaluate(element, jsonPointer, {
+    trace
+  });
+
+  // each step's input is the node the token was applied to, so the inputs are
+  // exactly the walked nodes minus the target
+  return {
+    element: result,
+    ancestorSchema$ids: schema$idsOf(trace.steps.map(step => step.input))
+  };
+};

package/src/dereference/strategies/openapi-3-1/selectors/uri.cjs

@@ -17,46 +17,73 @@ Object.defineProperty(exports, "JsonSchemaUriError", {
     return _JsonSchemaUriError.default;
   }
 });
-exports.evaluate = void 0;
+exports.locate = exports.evaluate = void 0;
 var _ramdaAdjunct = require("ramda-adjunct");
 var _apidomTraverse = require("@speclynx/apidom-traverse");
-var _apidomNsJsonSchema = require("@speclynx/apidom-ns-json-schema-2020-12");
 var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
 var url = _interopRequireWildcard(require("../../../../util/url.cjs"));
 var _EvaluationJsonSchemaUriError = _interopRequireDefault(require("../../../../errors/EvaluationJsonSchemaUriError.cjs"));
-var _$anchor = require("./$anchor.cjs");
 var _util = require("../util.cjs");
+var _$anchor = require("./$anchor.cjs");
+var _jsonPointer = require("./json-pointer.cjs");
 var _JsonSchemaUriError = _interopRequireDefault(require("../../../../errors/JsonSchemaUriError.cjs"));
 /**
- * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * Index of `$id`-bearing schemas per indexed element (a document root, or the
+ * fragment a visitor traverses). Each entry pairs a schema with the `$id`s of its
+ * enclosing schema resources (outermost first, including its own). The index is
+ * populated once per element and never refreshed, so callers scope it
+ * to a single dereference/bundle run instead of sharing it globally. Within a run the
+ * `$id` graph of an indexed document is stable: the bundle strategies mutate deep
+ * clones and place components only after the entry traversal ends, and the
+ * dereference strategies only replace `$ref`-bearing schemas.
  * @public
  */
-const evaluate = (uri, element) => {
-  const {
-    cache
-  } = evaluate;
-  const uriStrippedHash = url.stripHash(uri);
-  const isJSONSchemaElementWith$id = path => (0, _apidomNsJsonSchema.isJSONSchemaElement)(path.node) && typeof path.node.$id !== 'undefined';
 
-  // warm the cache
-  if (!cache.has(element)) {
-    const schemaObjectPaths = (0, _apidomTraverse.filter)(element, isJSONSchemaElementWith$id);
-    cache.set(element, schemaObjectPaths.map(path => path.node));
+/**
+ * @public
+ */
+
+const indexSchema$ids = element => (0, _apidomTraverse.filter)(element, path => (0, _util.isJSONSchemaElementWith$id)(path.node)).map(path => ({
+  schema: path.node,
+  $ids: (0, _util.collectSchema$ids)(path)
+}));
+
+/**
+ * Locates the schema addressed by JSON Schema $ref containing unknown URI within
+ * ApiDOM fragment, along with the `$id`s of the schemas enclosing it.
+ * @public
+ */
+const locate = (uri, element, options = {}) => {
+  const uriStrippedHash = url.stripHash(uri);
+  const {
+    baseURI = uriStrippedHash,
+    index = new WeakMap()
+  } = options;
+  if (!index.has(element)) {
+    index.set(element, indexSchema$ids(element));
   }
 
-  // search for the matching schema
-  const result = cache.get(element).find(e => {
-    const $idBaseURI = (0, _util.resolveSchema$idField)(uriStrippedHash, e);
-    return $idBaseURI === uriStrippedHash;
-  });
-  if ((0, _ramdaAdjunct.isUndefined)(result)) {
+  // search for the schema whose canonical URI matches
+  const entry = index.get(element).find(({
+    $ids
+  }) => (0, _util.resolveSchema$ids)(baseURI, $ids) === uriStrippedHash);
+  if ((0, _ramdaAdjunct.isUndefined)(entry)) {
     throw new _EvaluationJsonSchemaUriError.default(`Evaluation failed on URI: "${uri}"`);
   }
-  if ((0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)(uri))) {
-    // we're dealing with JSON Schema $anchor here
-    return (0, _$anchor.evaluate)((0, _$anchor.uriToAnchor)(uri), result);
-  }
-  return (0, _apidomJsonPointer.evaluate)(result, _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(uri));
+
+  // the fragment is resolved within the matched schema, whose own $id is the
+  // last of its chain; the fragment walk contributes it again when descending
+  const fragmentLocation = (0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)(uri)) ? (0, _$anchor.locate)((0, _$anchor.uriToAnchor)(uri), entry.schema) : (0, _jsonPointer.locate)(entry.schema, _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(uri));
+  return {
+    element: fragmentLocation.element,
+    ancestorSchema$ids: [...entry.$ids.slice(0, -1), ...fragmentLocation.ancestorSchema$ids]
+  };
 };
-exports.evaluate = evaluate;
-evaluate.cache = new WeakMap();
+
+/**
+ * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * @public
+ */
+exports.locate = locate;
+const evaluate = (uri, element, options = {}) => locate(uri, element, options).element;
+exports.evaluate = evaluate;

package/src/dereference/strategies/openapi-3-1/selectors/uri.mjs

@@ -1,42 +1,66 @@
 import { isUndefined } from 'ramda-adjunct';
 import { filter } from '@speclynx/apidom-traverse';
-import { isJSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
-import { URIFragmentIdentifier, evaluate as jsonPointerEvaluate } from '@speclynx/apidom-json-pointer';
+import { URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
 import * as url from "../../../../util/url.mjs";
 import EvaluationJsonSchemaUriError from "../../../../errors/EvaluationJsonSchemaUriError.mjs";
-import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./$anchor.mjs";
-import { resolveSchema$idField } from "../util.mjs";
+import { isJSONSchemaElementWith$id, collectSchema$ids, resolveSchema$ids } from "../util.mjs";
+import { isAnchor, uriToAnchor, locate as $anchorLocate } from "./$anchor.mjs";
+import { locate as jsonPointerLocate } from "./json-pointer.mjs";
 /**
- * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * Index of `$id`-bearing schemas per indexed element (a document root, or the
+ * fragment a visitor traverses). Each entry pairs a schema with the `$id`s of its
+ * enclosing schema resources (outermost first, including its own). The index is
+ * populated once per element and never refreshed, so callers scope it
+ * to a single dereference/bundle run instead of sharing it globally. Within a run the
+ * `$id` graph of an indexed document is stable: the bundle strategies mutate deep
+ * clones and place components only after the entry traversal ends, and the
+ * dereference strategies only replace `$ref`-bearing schemas.
  * @public
  */
-export const evaluate = (uri, element) => {
-  const {
-    cache
-  } = evaluate;
-  const uriStrippedHash = url.stripHash(uri);
-  const isJSONSchemaElementWith$id = path => isJSONSchemaElement(path.node) && typeof path.node.$id !== 'undefined';
+/**
+ * @public
+ */
+const indexSchema$ids = element => filter(element, path => isJSONSchemaElementWith$id(path.node)).map(path => ({
+  schema: path.node,
+  $ids: collectSchema$ids(path)
+}));
 
-  // warm the cache
-  if (!cache.has(element)) {
-    const schemaObjectPaths = filter(element, isJSONSchemaElementWith$id);
-    cache.set(element, schemaObjectPaths.map(path => path.node));
+/**
+ * Locates the schema addressed by JSON Schema $ref containing unknown URI within
+ * ApiDOM fragment, along with the `$id`s of the schemas enclosing it.
+ * @public
+ */
+export const locate = (uri, element, options = {}) => {
+  const uriStrippedHash = url.stripHash(uri);
+  const {
+    baseURI = uriStrippedHash,
+    index = new WeakMap()
+  } = options;
+  if (!index.has(element)) {
+    index.set(element, indexSchema$ids(element));
   }
 
-  // search for the matching schema
-  const result = cache.get(element).find(e => {
-    const $idBaseURI = resolveSchema$idField(uriStrippedHash, e);
-    return $idBaseURI === uriStrippedHash;
-  });
-  if (isUndefined(result)) {
+  // search for the schema whose canonical URI matches
+  const entry = index.get(element).find(({
+    $ids
+  }) => resolveSchema$ids(baseURI, $ids) === uriStrippedHash);
+  if (isUndefined(entry)) {
     throw new EvaluationJsonSchemaUriError(`Evaluation failed on URI: "${uri}"`);
   }
-  if (isAnchor(uriToAnchor(uri))) {
-    // we're dealing with JSON Schema $anchor here
-    return $anchorEvaluate(uriToAnchor(uri), result);
-  }
-  return jsonPointerEvaluate(result, URIFragmentIdentifier.fromURIReference(uri));
+
+  // the fragment is resolved within the matched schema, whose own $id is the
+  // last of its chain; the fragment walk contributes it again when descending
+  const fragmentLocation = isAnchor(uriToAnchor(uri)) ? $anchorLocate(uriToAnchor(uri), entry.schema) : jsonPointerLocate(entry.schema, URIFragmentIdentifier.fromURIReference(uri));
+  return {
+    element: fragmentLocation.element,
+    ancestorSchema$ids: [...entry.$ids.slice(0, -1), ...fragmentLocation.ancestorSchema$ids]
+  };
 };
-evaluate.cache = new WeakMap();
+
+/**
+ * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (uri, element, options = {}) => locate(uri, element, options).element;
 export { EvaluationJsonSchemaUriError };
 export { default as JsonSchemaUriError } from "../../../../errors/JsonSchemaUriError.mjs";