@speclynx/apidom-reference 5.2.2 → 5.2.5

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

@@ -1,13 +1,14 @@
 import { propEq, none } from 'ramda';
 import { isUndefined } from 'ramda-adjunct';
-import { isElement, isStringElement, isObjectElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
+import { isElement, isStringElement, isObjectElement, isParseResultElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
 import { toValue, fixedFields, toYAML } from '@speclynx/apidom-core';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { traverse, traverseAsync, find } from '@speclynx/apidom-traverse';
 import { evaluate as jsonPointerEvaluate, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
 import { isReferenceLikeElement, isPathItemElement, isReferenceElement, isSchemaElement, isOperationElement, isBooleanJSONSchemaElement, refract, refractReference, refractPathItem, refractOperation } from '@speclynx/apidom-ns-openapi-3-1';
-import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./selectors/$anchor.mjs";
-import { evaluate as uriEvaluate } from "./selectors/uri.mjs";
+import { isAnchor, uriToAnchor, locate as $anchorLocate } from "./selectors/$anchor.mjs";
+import { locate as uriLocate } from "./selectors/uri.mjs";
+import { locate as jsonPointerLocate } from "./selectors/json-pointer.mjs";
 import MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
 import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
 import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
@@ -16,7 +17,7 @@ import * as url from "../../../util/url.mjs";
 import parse from "../../../parse/index.mjs";
 import Reference from "../../../Reference.mjs";
 import File from "../../../File.mjs";
-import { resolveSchema$refField, maybeRefractToSchemaElement } from "./util.mjs";
+import { schema$idsOf, resolveSchema$ids, resolveSchemaBaseURI, resolveSchema$refField, maybeRefractToSchemaElement } from "./util.mjs";
 import { AncestorLineage } from "../../util.mjs";
 /**
  * @public
@@ -29,8 +30,23 @@ class OpenAPI3_1DereferenceVisitor {
   reference;
   options;
   refractCache;
+
+  /**
+   * 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
@@ -42,15 +58,19 @@ class OpenAPI3_1DereferenceVisitor {
     options,
     indirections = [],
     refractCache = new WeakMap(),
+    schema$idIndex = new WeakMap(),
     ancestors = new AncestorLineage(),
-    visited = new WeakSet()
+    visited = new WeakSet(),
+    ancestorSchema$ids = []
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.refractCache = refractCache;
+    this.schema$idIndex = schema$idIndex;
     this.ancestors = new AncestorLineage(...ancestors);
     this.visited = visited;
+    this.ancestorSchema$ids = ancestorSchema$ids;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -309,6 +329,7 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
           ancestors: ancestorsLineage
         });
@@ -467,6 +488,7 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
           ancestors: ancestorsLineage
         });
@@ -664,7 +686,11 @@ class OpenAPI3_1DereferenceVisitor {
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = resolveSchema$refField(retrievalURI, 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(retrievalURI, 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
@@ -676,13 +702,48 @@ class OpenAPI3_1DereferenceVisitor {
 
       // 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 = maybeRefractToSchemaElement(reference.value.result);
-          referencedElement = uriEvaluate(selector, referenceAsSchema);
+          // the fragment being traversed is searched before the whole document: a
+          // fragment referenced from another document (a Response, Parameter, Path
+          // Item, ...) is refracted with its own semantics, so the Schema Objects it
+          // contains are indexed, whereas the referenced document as a whole is
+          // parsed generically and refracted as a bare JSON Schema, which leaves
+          // those Schema Objects (under `content`, `schema`, ...) unrecognized and
+          // their `$id`s out of the index
+          const documentElement = reference.value.result;
+          const rootNode = path.getAncestorNodes().at(-1) ?? path.node;
+          const fragmentElement = isParseResultElement(rootNode) ? rootNode.result : rootNode;
+          try {
+            // the fragment's $ids resolve against the base its enclosing chain
+            // leaves in effect, which then also prefixes the located schema's chain
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = uriLocate(selector, maybeRefractToSchemaElement(fragmentElement), {
+              baseURI: rootBaseURI,
+              index: this.schema$idIndex
+            }));
+            ancestorSchema$ids = [...this.ancestorSchema$ids, ...ancestorSchema$ids];
+          } catch (error) {
+            if (!(error instanceof EvaluationJsonSchemaUriError) || fragmentElement === documentElement) {
+              throw error;
+            }
+            // the document index is rooted at the document, so the located chain
+            // is already document-relative and takes no prefix
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = uriLocate(selector, maybeRefractToSchemaElement(documentElement), {
+              baseURI: reference.uri,
+              index: this.schema$idIndex
+            }));
+          }
           referencedElement = maybeRefractToSchemaElement(referencedElement);
 
           // ignore resolving internal Schema Objects
@@ -714,7 +775,10 @@ class OpenAPI3_1DereferenceVisitor {
           reference = await this.toReference(url.unsanitize($refBaseURI));
           const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
           const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-          referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
+          ({
+            element: referencedElement,
+            ancestorSchema$ids
+          } = jsonPointerLocate(referenceAsSchema, selector));
           referencedElement = maybeRefractToSchemaElement(referencedElement);
         }
       } catch (error) {
@@ -741,7 +805,10 @@ class OpenAPI3_1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = uriToAnchor($refBaseURI);
             const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-            referencedElement = $anchorEvaluate(selector, referenceAsSchema);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = $anchorLocate(selector, referenceAsSchema));
             referencedElement = maybeRefractToSchemaElement(referencedElement);
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
@@ -762,7 +829,10 @@ class OpenAPI3_1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
             const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-            referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = jsonPointerLocate(referenceAsSchema, selector));
             referencedElement = maybeRefractToSchemaElement(referencedElement);
           }
         } else {
@@ -819,7 +889,11 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isSchemaElement(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(reference.uri, ancestorSchema$ids) !== resolveSchema$ids(rootBaseURI, schema$idsOf(path.getAncestorNodes().reverse()));
+      if ((isExternalReference || isNonEntryDocument || hasDifferentEnclosingBase || isSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
         if (shouldDetectCircular) {
           this.visited.add(referencedElement);
         }
@@ -829,8 +903,10 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
-          ancestors: ancestorsLineage
+          ancestors: ancestorsLineage,
+          ancestorSchema$ids
         });
         referencedElement = await traverseAsync(referencedElement, visitor, {
           mutable: true,

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.
  *