@speclynx/apidom-reference 4.11.1 → 4.12.1

package/src/resolve/strategies/asyncapi-2/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _ResolveStrategy = _interopRequireDefault(require("../ResolveStrategy.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));

package/src/resolve/strategies/openapi-2/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _ResolveStrategy = _interopRequireDefault(require("../ResolveStrategy.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));

package/src/resolve/strategies/openapi-3-0/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _ResolveStrategy = _interopRequireDefault(require("../ResolveStrategy.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));

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

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _ResolveStrategy = _interopRequireDefault(require("../ResolveStrategy.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));

package/src/resolve/strategies/overlay-1/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _ResolveStrategy = _interopRequireDefault(require("../ResolveStrategy.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));

package/src/resolve/util.cjs

@@ -2,7 +2,9 @@
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.readFile = void 0;
 var _ramda = require("ramda");
 var plugins = _interopRequireWildcard(require("../util/plugins.cjs"));

package/src/util/plugins.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.run = exports.filter = void 0;
 var _ramdaAdjunct = require("ramda-adjunct");
 /**

package/src/util/url.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+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;
 var _process = _interopRequireDefault(require("process"));
 var _ramda = require("ramda");

package/types/apidom-reference.d.ts

@@ -9,8 +9,13 @@ import type { RefElement } from '@speclynx/apidom-datamodel';
  */
 export declare interface ApiDOMReferenceBundleOptions {
     strategies: Array<BundleStrategy>;
+    strategyOpts: Record<string, any>;
     refSet: null | ReferenceSet;
     maxDepth: number;
+    immutable: boolean;
+    componentNamesStrategy: ComponentNamesStrategy;
+    onComponentNameCollision: ComponentNameCollisionSeverity;
+    continueOnError: boolean | ((error: UnresolvableReferenceError) => void);
 }
 
 /**
@@ -68,7 +73,7 @@ export declare const bundle: (uri: string, options?: {}) => Promise<ParseResultE
 /**
  * @public
  */
-export declare class BundleError extends ApiDOMError {
+export declare class BundleError extends ApiDOMStructuredError {
 }
 
 /**
@@ -96,6 +101,37 @@ export declare interface CacheOptions {
     readonly maxStaleAge?: number | false;
 }
 
+/**
+ * @public
+ */
+export declare type ComponentNameCollisionSeverity = 'off' | 'warn' | 'error';
+
+/**
+ * @public
+ */
+export declare type ComponentNameResolver = (args: ComponentNameResolverArgs) => string;
+
+/**
+ * Context passed to a custom component-name resolver.
+ *
+ * @public
+ */
+export declare interface ComponentNameResolverArgs {
+    /** The refracted element being hoisted. */
+    readonly element: Element_2;
+    /** The Components Object field the element is hoisted into (e.g. `schemas`). */
+    readonly field: string;
+    /** The JSON Pointer of the referenced fragment within its document. */
+    readonly jsonPointer: string;
+    /** The base URI (without hash) of the referenced document. */
+    readonly baseURI: string;
+}
+
+/**
+ * @public
+ */
+export declare type ComponentNamesStrategy = 'basename' | 'title' | ComponentNameResolver;
+
 /**
  * Returns the current working directory (in Node) or the current page URL (in browsers).
  * @public
@@ -569,9 +605,12 @@ export declare class UnmatchedResolveStrategyError extends ResolveError {
 }
 
 /**
+ * Thrown when a reference cannot be resolved. Resolution is shared by the
+ * dereference and bundle components, so this error lives under `ResolveError`.
+ *
  * @public
  */
-export declare class UnresolvableReferenceError extends DereferenceError {
+export declare class UnresolvableReferenceError extends ResolveError {
 }
 
 /**

package/types/bundle/strategies/openapi-3-0/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 OpenAPI3_0BundleVisitor 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_0BundleVisitorOptions } 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 OpenAPI3_0BundleStrategyOptions extends Omit<BundleStrategyOptions, 'name'> {
+}
+/**
+ * @public
+ */
+declare class OpenAPI3_0BundleStrategy extends BundleStrategy {
+    constructor(options?: OpenAPI3_0BundleStrategyOptions);
+    canBundle(file: File): boolean;
+    bundle(file: File, options: ReferenceOptions): Promise<ParseResultElement>;
+}
+export { OpenAPI3_0BundleVisitor };
+export default OpenAPI3_0BundleStrategy;

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

@@ -0,0 +1,131 @@
+import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { type Path } from '@speclynx/apidom-traverse';
+import { OpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
+import Reference from '../../../Reference.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface OpenAPI3_0BundleVisitorOptions {
+    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 OpenAPI3_0BundleVisitor {
+    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_0Element.
+     */
+    protected get entryResult(): OpenApi3_0Element;
+    /**
+     * 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>>;
+    /**
+     * Canonical URIs of Path Item Objects currently being inlined. Path Items
+     * are not hoisted into Components Object (no `components.pathItems` in
+     * OpenAPI 3.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, }: OpenAPI3_0BundleVisitorOptions);
+    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-file 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;
+    /**
+     * 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;
+    ReferenceElement(path: Path<Element>): Promise<void>;
+    /**
+     * Path Item Object is not a Components Object field in OpenAPI 3.0
+     * (unlike 3.1 which has `components.pathItems`). An external Path Item
+     * reference therefore cannot be hoisted; it is inlined in place instead,
+     * after bundling its own external references.
+     */
+    PathItemElement(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.0 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_0BundleVisitor;

package/types/bundle/util.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Upper-cases the first letter of each whitespace-separated word and joins
+ * them, e.g. `pet model` -> `PetModel`.
+ *
+ * @public
+ */
+export declare const toPascalCase: (value: string) => string;
+/**
+ * Replaces characters that are invalid in a Components Object name with `-`,
+ * then collapses repeated separators and trims leading/trailing ones.
+ *
+ * @public
+ */
+export declare const sanitizeComponentName: (value: string) => string;
+/**
+ * Returns a collision-free name by suffixing `-2`, `-3`, ... onto `candidate`
+ * until `isTaken` reports it free. `isTaken` decides what counts as taken
+ * (e.g. names already placed in or reserved for a Components Object field).
+ *
+ * @public
+ */
+export declare const uniqueName: (candidate: string, isTaken: (name: string) => boolean) => string;

package/types/errors/BundleError.d.ts

@@ -1,7 +1,7 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 /**
  * @public
  */
-declare class BundleError extends ApiDOMError {
+declare class BundleError extends ApiDOMStructuredError {
 }
 export default BundleError;

package/types/errors/UnresolvableReferenceError.d.ts

@@ -1,7 +1,10 @@
-import DereferenceError from './DereferenceError.ts';
+import ResolveError from './ResolveError.ts';
 /**
+ * Thrown when a reference cannot be resolved. Resolution is shared by the
+ * dereference and bundle components, so this error lives under `ResolveError`.
+ *
  * @public
  */
-declare class UnresolvableReferenceError extends DereferenceError {
+declare class UnresolvableReferenceError extends ResolveError {
 }
 export default UnresolvableReferenceError;

package/types/index.d.ts

@@ -16,6 +16,7 @@ export type { DereferenceStrategyOptions } from './dereference/strategies/Derefe
 export { AncestorLineage as DereferenceAncestorLineage } from './dereference/util.ts';
 export { default as BundleStrategy } from './bundle/strategies/BundleStrategy.ts';
 export type { BundleStrategyOptions } from './bundle/strategies/BundleStrategy.ts';
+export type { ComponentNamesStrategy, ComponentNameResolver, ComponentNameResolverArgs, ComponentNameCollisionSeverity, } from './options/index.ts';
 export { default as options } from './options/index.ts';
 export { merge as mergeOptions } from './options/util.ts';
 export type { ReferenceOptions as ApiDOMReferenceOptions, ReferenceBundleOptions as ApiDOMReferenceBundleOptions, ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions, ReferenceParseOptions as ApiDOMReferenceParseOptions, ReferenceResolveOptions as ApiDOMReferenceResolveOptions, } from './options/index.ts';

package/types/options/index.d.ts

@@ -1,4 +1,4 @@
-import type { RefElement } from '@speclynx/apidom-datamodel';
+import type { RefElement, Element } from '@speclynx/apidom-datamodel';
 import type Parser from '../parse/parsers/Parser.ts';
 import type Resolver from '../resolve/resolvers/Resolver.ts';
 import type ResolveStrategy from '../resolve/strategies/ResolveStrategy.ts';
@@ -40,13 +40,45 @@ export interface ReferenceDereferenceOptions {
     immutable: boolean;
     continueOnError: boolean | ((error: UnresolvableReferenceError) => void);
 }
+/**
+ * Context passed to a custom component-name resolver.
+ *
+ * @public
+ */
+export interface ComponentNameResolverArgs {
+    /** The refracted element being hoisted. */
+    readonly element: Element;
+    /** The Components Object field the element is hoisted into (e.g. `schemas`). */
+    readonly field: string;
+    /** The JSON Pointer of the referenced fragment within its document. */
+    readonly jsonPointer: string;
+    /** The base URI (without hash) of the referenced document. */
+    readonly baseURI: string;
+}
+/**
+ * @public
+ */
+export type ComponentNameResolver = (args: ComponentNameResolverArgs) => string;
+/**
+ * @public
+ */
+export type ComponentNamesStrategy = 'basename' | 'title' | ComponentNameResolver;
+/**
+ * @public
+ */
+export type ComponentNameCollisionSeverity = 'off' | 'warn' | 'error';
 /**
  * @public
  */
 export interface ReferenceBundleOptions {
     strategies: Array<BundleStrategy>;
+    strategyOpts: Record<string, any>;
     refSet: null | ReferenceSet;
     maxDepth: number;
+    immutable: boolean;
+    componentNamesStrategy: ComponentNamesStrategy;
+    onComponentNameCollision: ComponentNameCollisionSeverity;
+    continueOnError: boolean | ((error: UnresolvableReferenceError) => void);
 }
 /**
  * @public