@speclynx/apidom-reference 4.12.0 → 4.13.0

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-file 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 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 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;