@speclynx/apidom-reference 4.12.1 → 4.14.0

package/src/configuration/saturated.cjs

@@ -36,20 +36,21 @@ var _index25 = _interopRequireDefault(require("../dereference/strategies/openapi
 var _index26 = _interopRequireDefault(require("../dereference/strategies/asyncapi-2/index.cjs"));
 var _index27 = _interopRequireDefault(require("../dereference/strategies/arazzo-1/index.cjs"));
 var _index28 = _interopRequireDefault(require("../dereference/strategies/overlay-1/index.cjs"));
-var _index29 = _interopRequireDefault(require("../bundle/strategies/openapi-3-0/index.cjs"));
-var _index30 = _interopRequireDefault(require("../bundle/strategies/openapi-3-1/index.cjs"));
-var _index31 = require("../index.cjs");
-Object.keys(_index31).forEach(function (key) {
+var _index29 = _interopRequireDefault(require("../bundle/strategies/openapi-2/index.cjs"));
+var _index30 = _interopRequireDefault(require("../bundle/strategies/openapi-3-0/index.cjs"));
+var _index31 = _interopRequireDefault(require("../bundle/strategies/openapi-3-1/index.cjs"));
+var _index32 = require("../index.cjs");
+Object.keys(_index32).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _index31[key]) return;
+  if (key in exports && exports[key] === _index32[key]) return;
   Object.defineProperty(exports, key, {
     enumerable: true,
     get: function () {
-      return _index31[key];
+      return _index32[key];
     }
   });
 });
-_index31.options.parse.parsers = [new _index9.default({
+_index32.options.parse.parsers = [new _index9.default({
   allowEmpty: true,
   sourceMap: false
 }), new _index0.default({
@@ -97,11 +98,11 @@ _index31.options.parse.parsers = [new _index9.default({
 }), new _indexNode2.default({
   allowEmpty: true
 })];
-_index31.options.resolve.resolvers = [new _indexNode.default(), new _index.default({
+_index32.options.resolve.resolvers = [new _indexNode.default(), new _index.default({
   timeout: 5000,
   redirects: 5,
   withCredentials: false
 })];
-_index31.options.resolve.strategies = [new _index2.default(), new _index3.default(), new _index4.default(), new _index5.default(), new _index6.default(), new _index7.default(), new _index8.default()];
-_index31.options.dereference.strategies = [new _index23.default(), new _index24.default(), new _index25.default(), new _index26.default(), new _index27.default(), new _index28.default(), new _index22.default()];
-_index31.options.bundle.strategies = [new _index29.default(), new _index30.default()];
+_index32.options.resolve.strategies = [new _index2.default(), new _index3.default(), new _index4.default(), new _index5.default(), new _index6.default(), new _index7.default(), new _index8.default()];
+_index32.options.dereference.strategies = [new _index23.default(), new _index24.default(), new _index25.default(), new _index26.default(), new _index27.default(), new _index28.default(), new _index22.default()];
+_index32.options.bundle.strategies = [new _index29.default(), new _index30.default(), new _index31.default()];

package/src/configuration/saturated.mjs

@@ -30,6 +30,7 @@ import OpenAPI3_1DereferenceStrategy from "../dereference/strategies/openapi-3-1
 import AsyncAPI2DereferenceStrategy from "../dereference/strategies/asyncapi-2/index.mjs";
 import Arazzo1DereferenceStrategy from "../dereference/strategies/arazzo-1/index.mjs";
 import Overlay1DereferenceStrategy from "../dereference/strategies/overlay-1/index.mjs";
+import OpenAPI2BundleStrategy from "../bundle/strategies/openapi-2/index.mjs";
 import OpenAPI3_0BundleStrategy from "../bundle/strategies/openapi-3-0/index.mjs";
 import OpenAPI3_1BundleStrategy from "../bundle/strategies/openapi-3-1/index.mjs";
 import { options } from "../index.mjs";
@@ -88,5 +89,5 @@ options.resolve.resolvers = [new FileResolver(), new HTTPResolverAxios({
 })];
 options.resolve.strategies = [new OpenAPI2ResolveStrategy(), new OpenAPI3_0ResolveStrategy(), new OpenAPI3_1ResolveStrategy(), new AsyncAPI2ResolveStrategy(), new Arazzo1ResolveStrategy(), new Overlay1ResolveStrategy(), new ApiDOMResolveStrategy()];
 options.dereference.strategies = [new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy(), new AsyncAPI2DereferenceStrategy(), new Arazzo1DereferenceStrategy(), new Overlay1DereferenceStrategy(), new ApiDOMDereferenceStrategy()];
-options.bundle.strategies = [new OpenAPI3_0BundleStrategy(), new OpenAPI3_1BundleStrategy()];
+options.bundle.strategies = [new OpenAPI2BundleStrategy(), new OpenAPI3_0BundleStrategy(), new OpenAPI3_1BundleStrategy()];
 export * from "../index.mjs";

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.fromFileSystemPath = exports.cwd = void 0;
+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;
 var _process = _interopRequireDefault(require("process"));
 var _ramda = require("ramda");
 var _ramdaAdjunct = require("ramda-adjunct");
@@ -40,25 +40,47 @@ const getProtocol = url => {
 exports.getProtocol = getProtocol;
 const hasProtocol = exports.hasProtocol = (0, _ramda.pipe)(getProtocol, _ramdaAdjunct.isNotUndefined);
 
+/**
+ * Returns the final path segment of the given URI (the part after the last
+ * `/`). Inputs are URIs, whose path separator is `/` — filesystem paths are
+ * forward-slashed by `sanitize` before reaching here.
+ */
+const getFilename = uri => uri.slice(uri.lastIndexOf('/') + 1);
+
 /**
  * Returns the lower-cased file extension of the given URL,
  * or an empty string if it has no extension.
  * @public
  */
 const getExtension = url => {
-  const lastDotPosition = url.lastIndexOf('.');
+  const fileName = getFilename(url);
+  const lastDotPosition = fileName.lastIndexOf('.');
   if (lastDotPosition >= 0) {
-    return url.substring(lastDotPosition).toLowerCase();
+    return fileName.substring(lastDotPosition).toLowerCase();
   }
   return '';
 };
 
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+exports.getExtension = getExtension;
+const getBasename = uri => {
+  const fileName = getFilename(uri);
+  const extension = getExtension(uri);
+  return extension === '' ? fileName : fileName.slice(0, -extension.length);
+};
+
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.
  * @public
  */
-exports.getExtension = getExtension;
+exports.getBasename = getBasename;
 const isFileSystemPath = uri => {
   const protocol = getProtocol(uri);
   return (0, _ramdaAdjunct.isUndefined)(protocol) || protocol === 'file' || /^[a-zA-Z]$/.test(protocol);

package/src/util/url.mjs

@@ -33,19 +33,40 @@ export const getProtocol = url => {
  */
 export const hasProtocol = pipe(getProtocol, isNotUndefined);
 
+/**
+ * Returns the final path segment of the given URI (the part after the last
+ * `/`). Inputs are URIs, whose path separator is `/` — filesystem paths are
+ * forward-slashed by `sanitize` before reaching here.
+ */
+const getFilename = uri => uri.slice(uri.lastIndexOf('/') + 1);
+
 /**
  * Returns the lower-cased file extension of the given URL,
  * or an empty string if it has no extension.
  * @public
  */
 export const getExtension = url => {
-  const lastDotPosition = url.lastIndexOf('.');
+  const fileName = getFilename(url);
+  const lastDotPosition = fileName.lastIndexOf('.');
   if (lastDotPosition >= 0) {
-    return url.substring(lastDotPosition).toLowerCase();
+    return fileName.substring(lastDotPosition).toLowerCase();
   }
   return '';
 };
 
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+export const getBasename = uri => {
+  const fileName = getFilename(uri);
+  const extension = getExtension(uri);
+  return extension === '' ? fileName : fileName.slice(0, -extension.length);
+};
+
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.

package/types/apidom-reference.d.ts

@@ -240,6 +240,15 @@ export declare interface FileOptions {
  */
 declare const fromFileSystemPath: (uri: string) => string;
 
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+declare const getBasename: (uri: string) => string;
+
 /**
  * Returns the lower-cased file extension of the given URL,
  * or an empty string if it has no extension.
@@ -627,6 +636,7 @@ declare namespace url {
         getProtocol,
         hasProtocol,
         getExtension,
+        getBasename,
         isFileSystemPath,
         isHttpUrl,
         isURI,

package/types/bundle/strategies/openapi-2/index.d.ts

@@ -0,0 +1,31 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import File from '../../../File.ts';
+import BundleStrategy, { BundleStrategyOptions } from '../BundleStrategy.ts';
+import OpenAPI2BundleVisitor from './visitor.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+export type { default as DereferenceStrategy, DereferenceStrategyOptions, } from '../../../dereference/strategies/DereferenceStrategy.ts';
+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 { OpenAPI2BundleVisitorOptions } 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';
+export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
+export type { default as BundleStrategy, BundleStrategyOptions } from '../BundleStrategy.ts';
+export type { ComponentNamesStrategy, ComponentNameResolver, ComponentNameResolverArgs, ComponentNameCollisionSeverity, } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface OpenAPI2BundleStrategyOptions extends Omit<BundleStrategyOptions, 'name'> {
+}
+/**
+ * @public
+ */
+declare class OpenAPI2BundleStrategy extends BundleStrategy {
+    constructor(options?: OpenAPI2BundleStrategyOptions);
+    canBundle(file: File): boolean;
+    bundle(file: File, options: ReferenceOptions): Promise<ParseResultElement>;
+}
+export { OpenAPI2BundleVisitor };
+export default OpenAPI2BundleStrategy;

package/types/bundle/strategies/openapi-2/visitor.d.ts

@@ -0,0 +1,131 @@
+import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { type Path } from '@speclynx/apidom-traverse';
+import { ReferenceElement, JSONReferenceElement, SwaggerElement } from '@speclynx/apidom-ns-openapi-2';
+import Reference from '../../../Reference.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface OpenAPI2BundleVisitorOptions {
+    readonly reference: Reference;
+    readonly options: ReferenceOptions;
+    readonly assignments?: Map<string, string>;
+    readonly reservedNames?: Map<string, Set<string>>;
+    readonly refractCache?: WeakMap<Element, Map<string, Element>>;
+    readonly inlineStack?: Set<string>;
+}
+/**
+ * @public
+ */
+declare class OpenAPI2BundleVisitor {
+    protected readonly reference: Reference;
+    protected readonly options: ReferenceOptions;
+    /**
+     * The base URI (without hash) of the entry document. A reference is
+     * considered internal when it resolves to this URI and external otherwise.
+     * Derived from the shared refSet's root reference.
+     */
+    protected get entryURI(): string;
+    /**
+     * The entry parse result. Derived from the shared refSet's root reference.
+     */
+    protected get entryParseResult(): ParseResultElement;
+    /**
+     * The entry document element. Hoisted external fragments are placed into its
+     * top-level definition fields. The `canBundle` guard guarantees it is a
+     * SwaggerElement.
+     */
+    protected get entryResult(): SwaggerElement;
+    /**
+     * Shared across the entry document and every external document visitor.
+     * Guarantees each external fragment is hoisted exactly once and gives us a
+     * stable internal pointer to rewrite every referencing element to.
+     */
+    protected readonly assignments: Map<string, string>;
+    /**
+     * Component names already reserved per definition field. Reserved before
+     * recursion so collision suffixing (`Pet`, `Pet-2`, ...) accounts for
+     * components that are still being bundled.
+     */
+    protected readonly reservedNames: Map<string, Set<string>>;
+    /**
+     * Caches refracted fragments keyed by source element and target element type.
+     * The type is part of the key because the same source can be refracted into
+     * different semantic elements depending on the referencing context (e.g. a
+     * generic object referenced once as a Parameter and once as a Response).
+     */
+    protected readonly refractCache: WeakMap<Element, Map<string, Element>>;
+    /**
+     * Canonical URIs of Path Item Objects currently being inlined. Path Items
+     * are not a top-level definition field in OpenAPI 2.0, so the `assignments`
+     * map can't break their cycles. This stack guards against circular external
+     * Path Item references.
+     */
+    protected readonly inlineStack: Set<string>;
+    constructor({ reference, options, assignments, reservedNames, refractCache, inlineStack, }: OpenAPI2BundleVisitorOptions);
+    protected getRefracted(source: Element, type: string): Element | undefined;
+    protected setRefracted(source: Element, type: string, refracted: Element): void;
+    protected toBaseURI(uri: string): string;
+    protected toReference(uri: string): Promise<Reference>;
+    /**
+     * Normalizes a self-reference (e.g. `./root.json#/definitions/Pet`)
+     * to a bare fragment (`#/definitions/Pet`) so the bundled document stays
+     * transferable. Bare fragments are returned unchanged.
+     */
+    protected normalizeSelfReference(ref: string): string;
+    /**
+     * Handles an error according to the `bundle.continueOnError` option.
+     *
+     * For new errors: wraps in UnresolvableReferenceError with structured
+     * context. For errors already wrapped by a nested visitor: prepends the
+     * current hop to the trace.
+     *
+     * Inner/intermediate visitors always throw to let the trace accumulate. Only
+     * the entry document visitor respects continueOnError (callback/swallow/throw).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    /**
+     * Lazily creates the requested top-level definition field on the entry
+     * document, returning the field where a fragment is hoisted.
+     */
+    protected ensureField(field: string): ObjectElement;
+    /**
+     * Derives a component name from the referenced JSON Pointer's last token,
+     * falling back to the referenced file's basename.
+     */
+    protected basenameOf(jsonPointer: string, baseURI: string): string;
+    /**
+     * Computes the base component name (before collision suffixing) according to
+     * the configured naming strategy.
+     */
+    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 the field or reserved by a component that
+     * is still being bundled (reserved before recursion).
+     */
+    protected uniqueName(candidate: string, field: string): string;
+    /**
+     * Bundles a Reference Object (parameters/responses) or a JSON Reference
+     * Object (schemas). The two reference flavors differ only in their predicate
+     * and refraction helpers, so the shared logic is parameterized here.
+     */
+    protected bundleReference(path: Path<Element>, referencingElement: ReferenceElement | JSONReferenceElement, isSemanticReference: (element: Element) => boolean, isReferenceLike: (element: Element) => boolean, refractReferenceFn: (element: Element) => Element, label: string): Promise<void>;
+    /**
+     * Reference Object covers reusable Parameter and Response Objects, which are
+     * hoisted into the top-level `parameters` and `responses` fields.
+     */
+    ReferenceElement(path: Path<Element>): Promise<void>;
+    /**
+     * JSON Reference Object covers reusable Schema Objects, which are hoisted
+     * into the top-level `definitions` field.
+     */
+    JSONReferenceElement(path: Path<Element>): Promise<void>;
+    /**
+     * Path Item Object is not a top-level definition field in OpenAPI 2.0, so an
+     * external Path Item reference cannot be hoisted; it is inlined in place
+     * instead, after bundling its own external references.
+     */
+    PathItemElement(path: Path<Element>): Promise<void>;
+}
+export default OpenAPI2BundleVisitor;

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

@@ -68,11 +68,11 @@ declare class OpenAPI3_0BundleVisitor {
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
     /**
-     * Normalizes a self-file reference (e.g. `./root.json#/components/schemas/Pet`)
+     * Normalizes a self-reference (e.g. `./root.json#/components/schemas/Pet`)
      * to a bare fragment (`#/components/schemas/Pet`) so the bundled document stays
      * transferable. Bare fragments are returned unchanged.
      */
-    protected normalizeSelfFileRef(ref: string): string;
+    protected normalizeSelfReference(ref: string): string;
     /**
      * Handles an error according to the `bundle.continueOnError` option.
      *

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

@@ -1,15 +1,19 @@
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import File from '../../../File.ts';
 import BundleStrategy, { BundleStrategyOptions } from '../BundleStrategy.ts';
+import OpenAPI3_1BundleVisitor from './visitor.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
 export type { default as DereferenceStrategy, DereferenceStrategyOptions, } from '../../../dereference/strategies/DereferenceStrategy.ts';
 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 { 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';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions } from '../BundleStrategy.ts';
+export type { ComponentNamesStrategy, ComponentNameResolver, ComponentNameResolverArgs, ComponentNameCollisionSeverity, } from '../../../options/index.ts';
 /**
  * @public
  */
@@ -21,6 +25,7 @@ export interface OpenAPI3_1BundleStrategyOptions extends Omit<BundleStrategyOpti
 declare class OpenAPI3_1BundleStrategy extends BundleStrategy {
     constructor(options?: OpenAPI3_1BundleStrategyOptions);
     canBundle(file: File): boolean;
-    bundle(file: File): Promise<ParseResultElement>;
+    bundle(file: File, options: ReferenceOptions): Promise<ParseResultElement>;
 }
+export { OpenAPI3_1BundleVisitor };
 export default OpenAPI3_1BundleStrategy;

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

@@ -0,0 +1,141 @@
+import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { type Path } from '@speclynx/apidom-traverse';
+import { OpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
+import Reference from '../../../Reference.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface OpenAPI3_1BundleVisitorOptions {
+    readonly reference: Reference;
+    readonly options: ReferenceOptions;
+    readonly assignments?: Map<string, string>;
+    readonly reservedNames?: Map<string, Set<string>>;
+    readonly refractCache?: WeakMap<Element, Map<string, Element>>;
+}
+/**
+ * @public
+ */
+declare class OpenAPI3_1BundleVisitor {
+    protected readonly reference: Reference;
+    protected readonly options: ReferenceOptions;
+    /**
+     * The base URI (without hash) of the entry document. A reference is
+     * considered internal when it resolves to this URI and external otherwise.
+     * Derived from the shared refSet's root reference.
+     */
+    protected get entryURI(): string;
+    /**
+     * The entry parse result. Derived from the shared refSet's root reference.
+     */
+    protected get entryParseResult(): ParseResultElement;
+    /**
+     * The entry document element. Hoisted external fragments are placed into its
+     * `components` object. The `canBundle` guard guarantees it is an
+     * OpenApi3_1Element.
+     */
+    protected get entryResult(): OpenApi3_1Element;
+    /**
+     * Shared across the entry document and every external document visitor.
+     * Guarantees each external fragment is hoisted exactly once and gives us a
+     * stable internal pointer to rewrite every referencing element to.
+     */
+    protected readonly assignments: Map<string, string>;
+    /**
+     * Component names already reserved per Components Object field. Reserved
+     * before recursion so collision suffixing (`Pet`, `Pet-2`, ...) accounts for
+     * components that are still being bundled.
+     */
+    protected readonly reservedNames: Map<string, Set<string>>;
+    /**
+     * Caches refracted fragments keyed by source element and target element type.
+     * The type is part of the key because the same source can be refracted into
+     * different semantic elements depending on the referencing context (e.g. a
+     * 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);
+    protected getRefracted(source: Element, type: string): Element | undefined;
+    protected setRefracted(source: Element, type: string, refracted: Element): void;
+    protected toBaseURI(uri: string): string;
+    protected toReference(uri: string): Promise<Reference>;
+    /**
+     * Normalizes a self-reference (e.g. `./root.json#/components/schemas/Pet`)
+     * to a bare fragment (`#/components/schemas/Pet`) so the bundled document stays
+     * transferable. Bare fragments are returned unchanged.
+     */
+    protected normalizeSelfReference(ref: string): string;
+    /**
+     * Handles an error according to the `bundle.continueOnError` option.
+     *
+     * For new errors: wraps in UnresolvableReferenceError with structured
+     * context. For errors already wrapped by a nested visitor: prepends the
+     * current hop to the trace.
+     *
+     * Inner/intermediate visitors always throw to let the trace accumulate. Only
+     * the entry document visitor respects continueOnError (callback/swallow/throw).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    /**
+     * Lazily creates the Components Object (and the requested field within it)
+     * on the entry document, returning the field where a fragment is hoisted.
+     */
+    protected ensureComponentsField(field: string): ObjectElement;
+    /**
+     * Derives a component name from the referenced JSON Pointer's last token,
+     * falling back to the referenced file's basename.
+     */
+    protected basenameOf(jsonPointer: string, baseURI: string): string;
+    /**
+     * Computes the base component name (before collision suffixing) according to
+     * the configured naming strategy.
+     */
+    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).
+     */
+    protected uniqueName(candidate: string, field: string): string;
+    /**
+     * Reports a collision-forced rename according to the configured severity.
+     * A rename means two distinct targets resolved to the same name; each keeps
+     * its own component (and origin), so report the rename per severity.
+     */
+    protected reportNameCollision(preferredName: string, componentName: string, field: string): void;
+    ReferenceElement(path: Path<Element>): Promise<void>;
+    /**
+     * Unlike OpenAPI 3.0 (which has no `components.pathItems` field and therefore
+     * inlines external Path Items in place), OpenAPI 3.1 hoists an external Path
+     * Item Object into `components.pathItems` and rewrites the referencing `$ref`
+     * to an internal pointer — mirroring how Reference Objects are bundled.
+     * Sibling fields next to the `$ref` (e.g. `summary`, `description`) are kept
+     * on the referencing element.
+     */
+    PathItemElement(path: Path<Element>): Promise<void>;
+    /**
+     * Schema Objects in OpenAPI 3.1 are a JSON Schema 2020-12 dialect, so they are
+     * bundled per the JSON Schema Compound Document rules: the external schema
+     * RESOURCE is embedded verbatim into `components.schemas` (carrying its `$id`),
+     * and the referencing `$ref` is left UNCHANGED — it keeps resolving against the
+     * embedded resource's `$id`. This mirrors the canonical hyperjump
+     * `json-schema-bundle` behavior (the whole resource is embedded once, keyed by
+     * its `$id`; references are not rewritten).
+     */
+    SchemaElement(path: Path<Element>): Promise<void>;
+    /**
+     * Example Object `externalValue` points at arbitrary external content that
+     * has no place in the Components Object. The referenced value is inlined into
+     * the Example's `value` field.
+     */
+    ExampleElement(path: Path<Element>): Promise<void>;
+    /**
+     * Link Object `operationRef` points at an Operation Object, which has no
+     * Components Object field in OpenAPI 3.1 and therefore cannot be hoisted or
+     * inlined. To keep the link resolvable from the bundled document, an external
+     * `operationRef` is rewritten to its absolute URI. Internal `operationRef`
+     * values and `operationId` links are left untouched.
+     */
+    LinkElement(path: Path<Element>): Promise<void>;
+}
+export default OpenAPI3_1BundleVisitor;

package/types/util/url.d.ts

@@ -23,6 +23,14 @@ export declare const hasProtocol: (url: string) => boolean;
  * @public
  */
 export declare const getExtension: (url: string) => string;
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+export declare const getBasename: (uri: string) => string;
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.