@speclynx/apidom-reference 4.14.0 → 4.16.0

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

@@ -0,0 +1,90 @@
+import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { type Path } from '@speclynx/apidom-traverse';
+import { ArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
+import Reference from '../../../Reference.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface Arazzo1BundleVisitorOptions {
+    readonly reference: Reference;
+    readonly options: ReferenceOptions;
+    readonly assignments?: Map<string, string>;
+    readonly reservedNames?: Map<string, Set<string>>;
+}
+/**
+ * @public
+ */
+declare class Arazzo1BundleVisitor {
+    protected readonly reference: Reference;
+    protected readonly options: ReferenceOptions;
+    /**
+     * The entry parse result. Derived from the shared refSet's root reference.
+     */
+    protected get entryParseResult(): ParseResultElement;
+    /**
+     * The entry document element. Embedded external schema resources are placed
+     * into its `components.inputs` object. The `canBundle` guard guarantees it is
+     * an ArazzoSpecification1Element.
+     */
+    protected get entryResult(): ArazzoSpecification1Element;
+    /**
+     * Shared across the entry document and every external document visitor.
+     * Guarantees each external resource is embedded exactly once, keyed by its
+     * resource URI.
+     */
+    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>>;
+    constructor({ reference, options, assignments, reservedNames, }: Arazzo1BundleVisitorOptions);
+    protected toBaseURI(uri: string): string;
+    protected toReference(uri: string): Promise<Reference>;
+    /**
+     * 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 `inputs` field within it) on
+     * the entry document, returning the field where a resource is embedded.
+     */
+    protected ensureInputsField(): ObjectElement;
+    /**
+     * Computes the base component name (before collision suffixing) according to
+     * the configured naming strategy.
+     */
+    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).
+     */
+    protected uniqueName(candidate: 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): 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.
+     */
+    JSONSchemaElement(path: Path<Element>): Promise<void>;
+}
+export default Arazzo1BundleVisitor;

package/types/bundle/strategies/asyncapi-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 AsyncAPI2BundleVisitor 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 { AsyncAPI2BundleVisitorOptions } 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 AsyncAPI2BundleStrategyOptions extends Omit<BundleStrategyOptions, 'name'> {
+}
+/**
+ * @public
+ */
+declare class AsyncAPI2BundleStrategy extends BundleStrategy {
+    constructor(options?: AsyncAPI2BundleStrategyOptions);
+    canBundle(file: File): boolean;
+    bundle(file: File, options: ReferenceOptions): Promise<ParseResultElement>;
+}
+export { AsyncAPI2BundleVisitor };
+export default AsyncAPI2BundleStrategy;

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

@@ -0,0 +1,116 @@
+import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { type Path } from '@speclynx/apidom-traverse';
+import { AsyncApi2Element } from '@speclynx/apidom-ns-asyncapi-2';
+import Reference from '../../../Reference.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface AsyncAPI2BundleVisitorOptions {
+    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 AsyncAPI2BundleVisitor {
+    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
+     * AsyncApi2Element.
+     */
+    protected get entryResult(): AsyncApi2Element;
+    /**
+     * 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 Schema).
+     */
+    protected readonly refractCache: WeakMap<Element, Map<string, Element>>;
+    constructor({ reference, options, assignments, reservedNames, refractCache, }: AsyncAPI2BundleVisitorOptions);
+    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>;
+    /**
+     * AsyncAPI 2.0 has a `components.channels` field, so an external Channel Item
+     * Object is hoisted there and the referencing `$ref` is rewritten to an
+     * internal pointer — mirroring how Reference Objects are bundled. Sibling
+     * fields next to the `$ref` (e.g. `description`) are kept on the referencing
+     * element.
+     */
+    ChannelItemElement(path: Path<Element>): Promise<void>;
+}
+export default AsyncAPI2BundleVisitor;