@speclynx/apidom-reference 5.2.4 → 5.2.6

package/src/util/url.cjs

@@ -4,7 +4,7 @@ var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequ
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
+exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.relative = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
 var _process = _interopRequireDefault(require("process"));
 var _ramda = require("ramda");
 var _ramdaAdjunct = require("ramda-adjunct");
@@ -275,6 +275,39 @@ const resolve = (from, to) => {
   return resolvedUrl.toString();
 };
 
+/**
+ * Computes the URI reference that resolves to `to` against `from` — the inverse
+ * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is
+ * relative to the directory of `from` (its last path segment is the document,
+ * not a directory). When the two URIs differ in scheme or authority, or either
+ * has no hierarchical path (e.g. a URN), no relative form exists and `to` is
+ * returned unchanged.
+ * @public
+ */
+exports.resolve = resolve;
+const relative = (from, to) => {
+  const fromURL = new URL(from, 'resolve://');
+  const toURL = new URL(to, 'resolve://');
+
+  // the authority is host plus userinfo; a relative reference keeps both from `from`
+  if (fromURL.protocol !== toURL.protocol || fromURL.host !== toURL.host || fromURL.username !== toURL.username || fromURL.password !== toURL.password || !fromURL.pathname.startsWith('/') || !toURL.pathname.startsWith('/')) {
+    return to;
+  }
+  const fromSegments = fromURL.pathname.split('/').slice(0, -1);
+  const toSegments = toURL.pathname.split('/');
+  let common = 0;
+  while (common < fromSegments.length && common < toSegments.length - 1 && fromSegments[common] === toSegments[common]) {
+    common += 1;
+  }
+  const segments = [...fromSegments.slice(common).map(() => '..'), ...toSegments.slice(common)];
+  // a leading segment with a colon would be parsed as a scheme, and an empty
+  // reference (`to` is the directory of `from`) would resolve back to `from`
+  if (segments[0].includes(':') || segments.join('/') === '') {
+    segments.unshift('.');
+  }
+  return segments.join('/') + toURL.search + toURL.hash;
+};
+
 /**
  * Sanitizes/Encodes URI to it's url encoded form.
  *
@@ -283,7 +316,7 @@ const resolve = (from, to) => {
  * by first unsatizing it and then performing sanitization again.
  * @public
  */
-exports.resolve = resolve;
+exports.relative = relative;
 const sanitize = uri => {
   if (isFileSystemPath(uri)) {
     return fromFileSystemPath(toFileSystemPath(uri));

package/src/util/url.mjs

@@ -259,6 +259,38 @@ export const resolve = (from, to) => {
   return resolvedUrl.toString();
 };
 
+/**
+ * Computes the URI reference that resolves to `to` against `from` — the inverse
+ * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is
+ * relative to the directory of `from` (its last path segment is the document,
+ * not a directory). When the two URIs differ in scheme or authority, or either
+ * has no hierarchical path (e.g. a URN), no relative form exists and `to` is
+ * returned unchanged.
+ * @public
+ */
+export const relative = (from, to) => {
+  const fromURL = new URL(from, 'resolve://');
+  const toURL = new URL(to, 'resolve://');
+
+  // the authority is host plus userinfo; a relative reference keeps both from `from`
+  if (fromURL.protocol !== toURL.protocol || fromURL.host !== toURL.host || fromURL.username !== toURL.username || fromURL.password !== toURL.password || !fromURL.pathname.startsWith('/') || !toURL.pathname.startsWith('/')) {
+    return to;
+  }
+  const fromSegments = fromURL.pathname.split('/').slice(0, -1);
+  const toSegments = toURL.pathname.split('/');
+  let common = 0;
+  while (common < fromSegments.length && common < toSegments.length - 1 && fromSegments[common] === toSegments[common]) {
+    common += 1;
+  }
+  const segments = [...fromSegments.slice(common).map(() => '..'), ...toSegments.slice(common)];
+  // a leading segment with a colon would be parsed as a scheme, and an empty
+  // reference (`to` is the directory of `from`) would resolve back to `from`
+  if (segments[0].includes(':') || segments.join('/') === '') {
+    segments.unshift('.');
+  }
+  return segments.join('/') + toURL.search + toURL.hash;
+};
+
 /**
  * Sanitizes/Encodes URI to it's url encoded form.
  *

package/types/apidom-reference.d.ts

@@ -491,6 +491,17 @@ export declare interface ReferenceSetOptions {
     readonly circular?: boolean;
 }
 
+/**
+ * Computes the URI reference that resolves to `to` against `from` — the inverse
+ * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is
+ * relative to the directory of `from` (its last path segment is the document,
+ * not a directory). When the two URIs differ in scheme or authority, or either
+ * has no hierarchical path (e.g. a URN), no relative form exists and `to` is
+ * returned unchanged.
+ * @public
+ */
+declare const relative: (from: string, to: string) => string;
+
 /**
  * @public
  */
@@ -647,6 +658,7 @@ declare namespace url {
         stripHash,
         cwd,
         resolve_2 as resolve,
+        relative,
         sanitize,
         unsanitize
     }

package/types/bundle/strategies/arazzo-1/index.d.ts

@@ -7,7 +7,7 @@ export type { default as DereferenceStrategy, DereferenceStrategyOptions, } from
 export type { default as File, FileOptions } from '../../../File.ts';
 export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
 export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
-export type { Arazzo1BundleVisitorOptions } from './visitor.ts';
+export type { Arazzo1BundleVisitorOptions, InputPlacement } from './visitor.ts';
 export type { ReferenceOptions as ApiDOMReferenceOptions, ReferenceBundleOptions as ApiDOMReferenceBundleOptions, ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions, ReferenceParseOptions as ApiDOMReferenceParseOptions, ReferenceResolveOptions as ApiDOMReferenceResolveOptions, } from '../../../options/index.ts';
 export type { default as Parser, ParserOptions } from '../../../parse/parsers/Parser.ts';
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';

package/types/bundle/strategies/arazzo-1/visitor.d.ts

@@ -2,7 +2,17 @@ import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-dat
 import { type Path } from '@speclynx/apidom-traverse';
 import { ArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
 import Reference from '../../../Reference.ts';
+import { type Schema$idIndex } from '../../../dereference/strategies/arazzo-1/selectors/uri.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * A bundled JSON Schema resource awaiting placement into the entry document's
+ * `components.inputs`.
+ * @public
+ */
+export interface InputPlacement {
+    readonly name: string;
+    readonly element: Element;
+}
 /**
  * @public
  */
@@ -11,6 +21,8 @@ export interface Arazzo1BundleVisitorOptions {
     readonly options: ReferenceOptions;
     readonly assignments?: Map<string, string>;
     readonly reservedNames?: Map<string, Set<string>>;
+    readonly placements?: InputPlacement[];
+    readonly schema$idIndex?: Schema$idIndex;
 }
 /**
  * @public
@@ -46,7 +58,28 @@ declare class Arazzo1BundleVisitor {
      * components that are still being bundled.
      */
     protected readonly reservedNames: Map<string, Set<string>>;
-    constructor({ reference, options, assignments, reservedNames, }: Arazzo1BundleVisitorOptions);
+    /**
+     * Embedded resources waiting to be placed into the entry document's
+     * `components.inputs`, shared across the entry document and every external
+     * document visitor. Placement is deferred until the entry document traversal
+     * completes: the traversal walks live content, so placing a resource mid-way
+     * would make it descend into the resource and re-bundle its `$ref`s against
+     * the entry document's base URI instead of the resource's own.
+     */
+    protected readonly placements: InputPlacement[];
+    /**
+     * Index of `$id`-bearing schemas per document, shared across the entry document
+     * and every external document visitor of a single bundle run so it never
+     * outlives mutations of the documents (e.g. the final placement of inputs).
+     */
+    protected readonly schema$idIndex: Schema$idIndex;
+    constructor({ reference, options, assignments, reservedNames, placements, schema$idIndex, }: Arazzo1BundleVisitorOptions);
+    /**
+     * Base URI of the entry document — its `$self` when present, otherwise its
+     * retrieval URI. It is the base against which a relative `$id` written into
+     * `components.inputs` resolves.
+     */
+    protected get entryBaseURI(): string;
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
     /**
@@ -72,8 +105,8 @@ declare class Arazzo1BundleVisitor {
     protected baseName(element: Element, baseURI: string): string;
     /**
      * Computes a collision-free component name within `components.inputs`. A name
-     * is taken if it's already placed in inputs or reserved by a component that is
-     * still being bundled (reserved before recursion).
+     * is taken if it's already present in the entry document's inputs or reserved
+     * by a component that is still being bundled (reserved before recursion).
      */
     protected uniqueName(candidate: string): string;
     /**
@@ -82,14 +115,26 @@ declare class Arazzo1BundleVisitor {
      * its own component (and origin), so report the rename per severity.
      */
     protected reportNameCollision(preferredName: string, componentName: string): void;
+    /**
+     * The entry document traversal is rooted at its Parse Result (nested
+     * traversals are rooted at schema resources), so leaving it marks the moment
+     * the whole entry document has been visited and the collected resources can
+     * be placed into `components.inputs` without the traversal descending into them.
+     * Guarded on the node so that a traversal rooted at any other Parse Result
+     * never flushes the shared placements early.
+     */
+    readonly ParseResultElement: {
+        leave: (path: Path<Element>) => void;
+    };
     /**
      * JSON Schema Objects in Arazzo (used by Input Objects and inline schemas) are
      * a JSON Schema 2020-12 dialect — the only external reference type Arazzo
      * defines. They are bundled per the JSON Schema Compound Document rules: the
      * external schema RESOURCE is embedded verbatim into `components.inputs`
-     * (carrying its `$id`), and the referencing `$ref` is left UNCHANGED — it
-     * keeps resolving against the embedded resource's `$id`. This mirrors the
-     * openapi-3-1 strategy's Schema Object handling.
+     * (carrying its `$id`), and the referencing `$ref` is rebased onto that `$id`
+     * when it resolves to a different URI (a location-based `$ref` to a
+     * self-identifying resource); otherwise it is left unchanged. This mirrors
+     * the openapi-3-1 strategy's Schema Object handling.
      */
     JSONSchemaElement(path: Path<Element>): Promise<void>;
 }

package/types/bundle/strategies/openapi-3-1/index.d.ts

@@ -7,7 +7,7 @@ export type { default as DereferenceStrategy, DereferenceStrategyOptions, } from
 export type { default as File, FileOptions } from '../../../File.ts';
 export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
 export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
-export type { OpenAPI3_1BundleVisitorOptions } from './visitor.ts';
+export type { OpenAPI3_1BundleVisitorOptions, ComponentPlacement } from './visitor.ts';
 export type { ReferenceOptions as ApiDOMReferenceOptions, ReferenceBundleOptions as ApiDOMReferenceBundleOptions, ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions, ReferenceParseOptions as ApiDOMReferenceParseOptions, ReferenceResolveOptions as ApiDOMReferenceResolveOptions, } from '../../../options/index.ts';
 export type { default as Parser, ParserOptions } from '../../../parse/parsers/Parser.ts';
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';

package/types/bundle/strategies/openapi-3-1/visitor.d.ts

@@ -2,7 +2,18 @@ import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-dat
 import { type Path } from '@speclynx/apidom-traverse';
 import { OpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
 import Reference from '../../../Reference.ts';
+import { type Schema$idIndex } from '../../../dereference/strategies/openapi-3-1/selectors/uri.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * A bundled element awaiting placement into the entry document's Components
+ * Object field.
+ * @public
+ */
+export interface ComponentPlacement {
+    readonly field: string;
+    readonly name: string;
+    readonly element: Element;
+}
 /**
  * @public
  */
@@ -12,6 +23,9 @@ export interface OpenAPI3_1BundleVisitorOptions {
     readonly assignments?: Map<string, string>;
     readonly reservedNames?: Map<string, Set<string>>;
     readonly refractCache?: WeakMap<Element, Map<string, Element>>;
+    readonly schema$idIndex?: Schema$idIndex;
+    readonly placements?: ComponentPlacement[];
+    readonly relocationBaseURI?: string;
 }
 /**
  * @public
@@ -54,7 +68,30 @@ declare class OpenAPI3_1BundleVisitor {
      * generic object referenced once as a Parameter and once as a Response).
      */
     protected readonly refractCache: WeakMap<Element, Map<string, Element>>;
-    constructor({ reference, options, assignments, reservedNames, refractCache, }: OpenAPI3_1BundleVisitorOptions);
+    /**
+     * Index of `$id`-bearing schemas per document, shared across the entry document
+     * and every external document visitor of a single bundle run so it never
+     * outlives mutations of the documents (e.g. the final placement of components).
+     */
+    protected readonly schema$idIndex: Schema$idIndex;
+    /**
+     * Bundled fragments waiting to be placed into the entry document's
+     * Components Object, shared across the entry document and every external
+     * document visitor. Placement is deferred until the entry document traversal
+     * completes: the traversal walks live content, so placing a fragment mid-way
+     * would make it descend into the fragment and re-bundle its `$ref`s against
+     * the entry document's base URI instead of the fragment's own.
+     */
+    protected readonly placements: ComponentPlacement[];
+    /**
+     * The base URI the traversed content will have once placed into the entry
+     * document, when placement changes it: content hoisted out of a non-schema
+     * document (a Response, Parameter, Path Item, ...) trades that document's
+     * base URI for the entry document's. Unset for the entry document itself and
+     * for embedded schema resources, whose `$id` carries their base along.
+     */
+    protected readonly relocationBaseURI: string | undefined;
+    constructor({ reference, options, assignments, reservedNames, refractCache, schema$idIndex, placements, relocationBaseURI, }: OpenAPI3_1BundleVisitorOptions);
     protected getRefracted(source: Element, type: string): Element | undefined;
     protected setRefracted(source: Element, type: string, refracted: Element): void;
     protected toBaseURI(uri: string): string;
@@ -65,6 +102,14 @@ declare class OpenAPI3_1BundleVisitor {
      * transferable. Bare fragments are returned unchanged.
      */
     protected normalizeSelfReference(ref: string): string;
+    /**
+     * The base URI the given Schema Object's `$ref` will be resolved against once
+     * the content is placed into the entry document, or `undefined` when the
+     * `$ref` as written resolves to `$refBaseURI` from there as well: the content
+     * isn't relocated, an absolute `$id` on the schema's ancestor chain pins its
+     * base, or the hoisted document sits next to the entry document.
+     */
+    protected relocatedSchemaBaseURI(path: Path<Element>, $refBaseURI: string): string | undefined;
     /**
      * Handles an error according to the `bundle.continueOnError` option.
      *
@@ -93,8 +138,8 @@ declare class OpenAPI3_1BundleVisitor {
     protected baseName(element: Element, field: string, jsonPointer: string, baseURI: string): string;
     /**
      * Computes a collision-free component name within the target field. A name is
-     * taken if it's already placed in components or reserved by a component that
-     * is still being bundled (reserved before recursion).
+     * taken if it's already present in the entry document's components or reserved
+     * by a component that is still being bundled (reserved before recursion).
      */
     protected uniqueName(candidate: string, field: string): string;
     /**
@@ -103,6 +148,17 @@ declare class OpenAPI3_1BundleVisitor {
      * its own component (and origin), so report the rename per severity.
      */
     protected reportNameCollision(preferredName: string, componentName: string, field: string): void;
+    /**
+     * The entry document traversal is rooted at its Parse Result (nested
+     * traversals are rooted at fragments), so leaving it marks the moment the
+     * whole entry document has been visited and the collected fragments can be
+     * placed into its Components Object without the traversal descending into them.
+     * Guarded on the node so that a traversal rooted at any other Parse Result
+     * never flushes the shared placements early.
+     */
+    readonly ParseResultElement: {
+        leave: (path: Path<Element>) => void;
+    };
     ReferenceElement(path: Path<Element>): Promise<void>;
     /**
      * Unlike OpenAPI 3.0 (which has no `components.pathItems` field and therefore

package/types/bundle/util.d.ts

@@ -20,3 +20,42 @@ export declare const sanitizeComponentName: (value: string) => string;
  * @public
  */
 export declare const uniqueName: (candidate: string, isTaken: (name: string) => boolean) => string;
+/**
+ * Computes the `$ref` value addressing an embedded JSON Schema resource by its
+ * canonical `$id`. `$refURI` is the `$ref` resolved against the referencing
+ * document's base URI; `resourceURI` is the embedded resource's canonical URI
+ * (its `$id`, or the retrieval URI when it has none).
+ *
+ * When the two differ — a location-based `$ref` (e.g. `./ex.json#/$defs/Pet`)
+ * to a resource that identifies itself differently (`$id: https://example.com/pets`)
+ * — the `$ref` is rebased onto the resource URI, keeping its `$anchor` or JSON
+ * Pointer fragment. Once embedded, the resource is reachable only by its `$id`,
+ * so an unchanged `$ref` would dangle. When they already agree, `undefined` is
+ * returned and the `$ref` is to be left as written.
+ *
+ * This knowingly departs from the letter of JSON Schema 2020-12 §9.3.1
+ * ("references ... MUST NOT be changed"), which presumes `$ref`s are written
+ * against `$id`s. The target schema — and thus evaluation output — is unchanged;
+ * only the alias the loader knew the resource by is normalized to its canonical URI.
+ *
+ * @public
+ */
+export declare const rebaseSchema$ref: ($refURI: string, resourceURI: string) => string | undefined;
+/**
+ * Computes the `$ref` value addressing an embedded JSON Schema resource from a
+ * Schema Object whose base URI changes when it is relocated into the entry
+ * document — one carried inside a hoisted Response, Parameter, Path Item, etc.
+ * `$refURI` and `resourceURI` are as in `rebaseSchema$ref`; `baseURI` is the
+ * base the `$ref` resolves against after relocation.
+ *
+ * A resource that identifies itself (`isResourceIdentified`, i.e. it declares a
+ * `$id`) is addressed by that `$id`, exactly as `rebaseSchema$ref` does. A
+ * resource identified only by its retrieval URI is addressed by a URI reference
+ * relative to `baseURI`: it then resolves to the `$id` assigned from that
+ * retrieval URI wherever the bundle is placed, and no absolute retrieval
+ * location leaks into the `$ref`. The `$anchor` or JSON Pointer fragment is
+ * kept in both cases.
+ *
+ * @public
+ */
+export declare const relocateSchema$ref: ($refURI: string, resourceURI: string, baseURI: string, isResourceIdentified: boolean) => string;

package/types/dereference/strategies/arazzo-1/selectors/$anchor.d.ts

@@ -1 +1 @@
-export { isAnchor, uriToAnchor, parse, evaluate, EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError, JsonSchema$anchorError, } from '../../openapi-3-1/selectors/$anchor.ts';
+export { isAnchor, uriToAnchor, parse, locate, evaluate, EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError, JsonSchema$anchorError, } from '../../openapi-3-1/selectors/$anchor.ts';

package/types/dereference/strategies/arazzo-1/selectors/uri.d.ts

@@ -1 +1 @@
-export { evaluate, EvaluationJsonSchemaUriError, JsonSchemaUriError, } from '../../openapi-3-1/selectors/uri.ts';
+export { locate, evaluate, EvaluationJsonSchemaUriError, JsonSchemaUriError, type EvaluateOptions, type Schema$idIndex, } from '../../openapi-3-1/selectors/uri.ts';

package/types/dereference/strategies/arazzo-1/util.d.ts

@@ -1,7 +1,7 @@
 import { Element, ParseResultElement } from '@speclynx/apidom-datamodel';
 import { SourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
 import type Reference from '../../../Reference.ts';
-export { resolveSchema$refField, resolveSchema$idField } from '../openapi-3-1/util.ts';
+export { resolveSchema$refField, resolveSchema$idField, resolveSchemaBaseURI, } from '../openapi-3-1/util.ts';
 /**
  * Computes the base URI of an Arazzo document per Arazzo 1.1.0 rules.
  *

package/types/dereference/strategies/arazzo-1/visitor.d.ts

@@ -1,5 +1,6 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
+import { type Schema$idIndex } from './selectors/uri.ts';
 import Reference from '../../../Reference.ts';
 import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
@@ -10,8 +11,10 @@ export interface Arazzo1DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
+    readonly schema$idIndex?: Schema$idIndex;
     readonly ancestors?: AncestorLineage<Element>;
     readonly visited?: WeakSet<Element>;
+    readonly ancestorSchema$ids?: string[];
 }
 /**
  * @public
@@ -26,14 +29,27 @@ declare class Arazzo1DereferenceVisitor {
      */
     protected readonly baseURI: string;
     protected readonly options: ReferenceOptions;
+    /**
+     * Index of `$id`-bearing schemas per document, shared across nested visitors
+     * of a single dereference run so it never outlives mutations of the documents.
+     */
+    protected readonly schema$idIndex: Schema$idIndex;
     protected readonly visited: WeakSet<Element>;
+    /**
+     * `$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.
+     */
+    protected readonly ancestorSchema$ids: string[];
     /**
      * Tracks element ancestors across dive-deep traversal boundaries.
      * Used for cycle detection: if a referenced element is found in
      * the ancestor lineage, a circular reference is detected.
      */
     protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, visited, }: Arazzo1DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, schema$idIndex, ancestors, visited, ancestorSchema$ids, }: Arazzo1DereferenceVisitorOptions);
     protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;

package/types/dereference/strategies/openapi-3-1/selectors/$anchor.d.ts

@@ -1,4 +1,5 @@
 import { Element } from '@speclynx/apidom-datamodel';
+import { type SchemaLocation } from '../util.ts';
 import EvaluationJsonSchema$anchorError from '../../../../errors/EvaluationJsonSchema$anchorError.ts';
 import InvalidJsonSchema$anchorError from '../../../../errors/InvalidJsonSchema$anchorError.ts';
 /**
@@ -13,10 +14,17 @@ export declare const uriToAnchor: (uri: string) => string;
  * @public
  */
 export declare const parse: (anchor: string) => string;
+/**
+ * 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 declare const locate: <T extends Element>(anchor: string, element: T) => SchemaLocation;
 /**
  * Evaluates JSON Schema $anchor against ApiDOM fragment.
  * @public
  */
 export declare const evaluate: <T extends Element>(anchor: string, element: T) => Element | undefined;
+export type { SchemaLocation } from '../util.ts';
 export { EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError };
 export { default as JsonSchema$anchorError } from '../../../../errors/JsonSchema$anchorError.ts';

package/types/dereference/strategies/openapi-3-1/selectors/json-pointer.d.ts

@@ -0,0 +1,9 @@
+import { Element } from '@speclynx/apidom-datamodel';
+import { type JSONPointer } from '@speclynx/apidom-json-pointer';
+import { type SchemaLocation } from '../util.ts';
+/**
+ * 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 declare const locate: <T extends Element>(element: T, jsonPointer: JSONPointer) => SchemaLocation;

package/types/dereference/strategies/openapi-3-1/selectors/uri.d.ts

@@ -1,12 +1,45 @@
 import { Element } from '@speclynx/apidom-datamodel';
+import { JSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
 import EvaluationJsonSchemaUriError from '../../../../errors/EvaluationJsonSchemaUriError.ts';
+import { type SchemaLocation } from '../util.ts';
+/**
+ * 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 type Schema$idIndex = WeakMap<Element, {
+    schema: JSONSchemaElement;
+    $ids: string[];
+}[]>;
+/**
+ * @public
+ */
+export interface EvaluateOptions {
+    /**
+     * URI the `$id`s of the document resolve against (its retrieval URI or `$self`).
+     * Defaults to the evaluated URI itself, which only matches schemas identified by an
+     * absolute `$id`; pass the document's base URI to match relative `$id`s correctly.
+     */
+    readonly baseURI?: string;
+    readonly index?: Schema$idIndex;
+}
+/**
+ * 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 declare const locate: <T extends Element>(uri: string, element: T, options?: EvaluateOptions) => SchemaLocation;
 /**
  * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
  * @public
  */
-export declare const evaluate: {
-    <T extends Element>(uri: string, element: T): Element | undefined;
-    cache: WeakMap<WeakKey, any>;
-};
+export declare const evaluate: <T extends Element>(uri: string, element: T, options?: EvaluateOptions) => Element | undefined;
+export type { SchemaLocation } from '../util.ts';
 export { EvaluationJsonSchemaUriError };
 export { default as JsonSchemaUriError } from '../../../../errors/JsonSchemaUriError.ts';

package/types/dereference/strategies/openapi-3-1/util.d.ts

@@ -1,13 +1,64 @@
 import { Element } from '@speclynx/apidom-datamodel';
+import type { Path } from '@speclynx/apidom-traverse';
 import { JSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
 /**
+ * A schema located within a document, together with the `$id`s of the JSON Schema
+ * elements enclosing it (outermost first; the located schema's own `$id` excluded).
  * @public
  */
-export declare const resolveSchema$refField: (retrievalURI: string, schemaElement: JSONSchemaElement) => string | undefined;
+export interface SchemaLocation {
+    readonly element: Element;
+    readonly ancestorSchema$ids: string[];
+}
 /**
+ * Whether the element is a JSON Schema element declaring a `$id`.
+ */
+export declare const isJSONSchemaElementWith$id: (element: unknown) => element is JSONSchemaElement;
+/**
+ * `$id`s declared by the JSON Schema elements among `nodes`, in order.
+ */
+export declare const schema$idsOf: (nodes: readonly unknown[]) => string[];
+/**
+ * `$id`s of the JSON Schema elements on `path` (outermost first, the node itself
+ * included). The `$id`s are read from the elements themselves rather than from
+ * refraction-time metadata, so a `$id` assigned after refraction (e.g. by the
+ * bundler) is honored.
+ */
+export declare const collectSchema$ids: (path: Path<Element>) => string[];
+/**
+ * `$id`s of the schemas enclosing a traversal root that is a fragment detached
+ * from its document, read from the `ancestorsSchemaIdentifiers` meta the JSON
+ * Schema refractors record. The meta also carries the root's own `$id`, which
+ * the ancestor walk contributes itself, so it is dropped. A detached fragment
+ * has no live ancestors, so the meta is the only carrier of its lexical
+ * context; this is the one reader of it the refractors must keep serving.
+ */
+export declare const detachedRootSchema$ids: (root: Element | undefined) => string[];
+/**
+ * Resolves a chain of `$id`s (outermost first) against `baseURI`, each `$id`
+ * refining the base the next one resolves against.
+ */
+export declare const resolveSchema$ids: (baseURI: string, $ids: readonly string[]) => string;
+/**
+ * Resolves the base URI of the schema at `path`: `baseURI` (the base URI in
+ * effect at the traversal root) refined by each `$id` on the schema's ancestor
+ * chain in turn, the schema's own `$id` included.
+ */
+export declare const resolveSchemaBaseURI: (baseURI: string, path: Path<Element>) => string;
+/**
+ * Resolves the `$ref` of the schema against its base URI (see
+ * `resolveSchemaBaseURI`), or returns `undefined` when the schema has no string `$ref`.
+ *
+ * @public
+ */
+export declare const resolveSchema$refField: (schemaBaseURI: string, schemaElement: JSONSchemaElement) => string | undefined;
+/**
+ * Resolves the `$id` of the schema against `baseURI`, the base URI in effect
+ * where the schema sits, or returns `undefined` when the schema declares no string `$id`.
+ *
  * @public
  */
-export declare const resolveSchema$idField: (retrievalURI: string, schemaElement: JSONSchemaElement) => string | undefined;
+export declare const resolveSchema$idField: (baseURI: string, schemaElement: JSONSchemaElement) => string | undefined;
 /**
  * Cached version of SchemaElement.refract.
  */