@speclynx/apidom-reference 4.15.0 → 4.16.0

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;