@kubb/core 5.0.0-beta.8 → 5.0.0-beta.81

package/dist/diagnostics-DcFh-77r.d.ts

@@ -0,0 +1,2889 @@
+import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
+import { Enforce, FileNode, HttpMethod, ImportNode, InputMeta, InputNode, Macro, Node, OperationNode, SchemaNode, UserFileNode } from "@kubb/ast";
+
+//#region ../../internals/utils/src/asyncEventEmitter.d.ts
+/**
+ * A function that can be registered as an event listener, synchronous or async.
+ */
+type AsyncListener<TArgs extends Array<unknown>> = (...args: TArgs) => void | Promise<void>;
+/**
+ * Typed `EventEmitter` that awaits all async listeners before resolving.
+ * Wraps Node's `EventEmitter` with full TypeScript event-map inference.
+ *
+ * @example
+ * ```ts
+ * const emitter = new AsyncEventEmitter<{ build: [name: string] }>()
+ * emitter.on('build', async (name) => { console.log(name) })
+ * await emitter.emit('build', 'petstore') // all listeners awaited
+ * ```
+ */
+declare class AsyncEventEmitter<TEvents extends { [K in keyof TEvents]: Array<unknown> }> {
+  #private;
+  /**
+   * Maximum number of listeners per event before Node emits a memory-leak warning.
+   * @default 10
+   */
+  constructor(maxListener?: number);
+  /**
+   * Emits `eventName` and awaits all registered listeners sequentially.
+   * Throws if any listener rejects, wrapping the cause with the event name and serialized arguments.
+   *
+   * @example
+   * ```ts
+   * await emitter.emit('build', 'petstore')
+   * ```
+   */
+  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void> | void;
+  /**
+   * Registers a persistent listener for `eventName`.
+   *
+   * @example
+   * ```ts
+   * emitter.on('build', async (name) => { console.log(name) })
+   * ```
+   */
+  on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: AsyncListener<TEvents[TEventName]>): void;
+  /**
+   * Removes a previously registered listener.
+   *
+   * @example
+   * ```ts
+   * emitter.off('build', handler)
+   * ```
+   */
+  off<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: AsyncListener<TEvents[TEventName]>): void;
+  /**
+   * Returns the number of listeners registered for `eventName`.
+   *
+   * @example
+   * ```ts
+   * emitter.on('build', handler)
+   * emitter.listenerCount('build') // 1
+   * ```
+   */
+  listenerCount<TEventName extends keyof TEvents & string>(eventName: TEventName): number;
+  /**
+   * Raises or lowers the per-event listener ceiling before Node warns about a memory leak.
+   * Set this above the expected listener count when many listeners attach by design.
+   *
+   * @example
+   * ```ts
+   * emitter.setMaxListeners(40)
+   * ```
+   */
+  setMaxListeners(max: number): void;
+  /**
+   * Removes all listeners from every event channel.
+   *
+   * @example
+   * ```ts
+   * emitter.removeAll()
+   * ```
+   */
+  removeAll(): void;
+}
+//#endregion
+//#region ../../internals/utils/src/promise.d.ts
+/** A value that may already be resolved or still pending.
+ *
+ * @example
+ * ```ts
+ * function load(id: string): PossiblePromise<string> {
+ *   return cache.get(id) ?? fetchRemote(id)
+ * }
+ * ```
+ */
+type PossiblePromise<T> = Promise<T> | T;
+//#endregion
+//#region src/createAdapter.d.ts
+/**
+ * Source data handed to an adapter's `parse` function. Mirrors the config
+ * input shape with paths resolved to absolute.
+ *
+ * - `{ type: 'path' }`: single file on disk.
+ * - `{ type: 'data' }`: raw string or parsed object provided inline.
+ */
+type AdapterSource = {
+  type: 'path';
+  path: string;
+} | {
+  type: 'data';
+  data: string | unknown;
+};
+/**
+ * Generic parameters used by `createAdapter` and the resulting `Adapter` type.
+ *
+ * - `TName`: unique adapter identifier (`'oas'`, `'asyncapi'`, ...).
+ * - `TOptions`: user-facing options accepted by the adapter factory.
+ * - `TResolvedOptions`: options after defaults are applied.
+ * - `TDocument`: type of the parsed source document.
+ */
+type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions, TDocument = unknown> = {
+  name: TName;
+  options: TOptions;
+  resolvedOptions: TResolvedOptions;
+  document: TDocument;
+};
+/**
+ * Converts input files or inline data into Kubb's universal AST `InputNode`.
+ *
+ * Adapters live between the spec format and the plugins. The built-in
+ * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1. A custom adapter can
+ * support GraphQL, gRPC, or another schema language.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
+ * })
+ * ```
+ */
+type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
+  /**
+   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
+   */
+  name: TOptions['name'];
+  /**
+   * Resolved adapter options after defaults have been applied.
+   */
+  options: TOptions['resolvedOptions'];
+  /**
+   * Parsed source document after the first `parse()` call. `null` before parsing.
+   */
+  document: TOptions['document'] | null;
+  /**
+   * Parse the source into a universal `InputNode`.
+   */
+  parse: (source: AdapterSource) => PossiblePromise<InputNode>;
+  /**
+   * Extract `ImportNode` entries for a schema tree.
+   * Returns an empty array before the first `parse()` call.
+   *
+   * The `resolve` callback receives the collision-corrected schema name and must
+   * return `{ name, path }` for the import, or `undefined` to skip it.
+   */
+  getImports: (node: SchemaNode, resolve: (schemaName: string) => {
+    name: string;
+    path: string;
+  }) => Array<ImportNode>;
+  /**
+   * Validate the document at the given path or URL.
+   */
+  validate: (input: string, options?: {
+    throwOnError?: boolean;
+  }) => Promise<void>;
+  /**
+   * Memory-efficient streaming variant of `parse()`.
+   *
+   * Returns an `InputNode<true>` whose `schemas` and `operations` are `AsyncIterable`.
+   * Each `for await` loop creates a fresh parse pass over the cached in-memory document.
+   * No pre-built arrays are held in memory.
+   */
+  stream?: (source: AdapterSource) => Promise<InputNode<true>>;
+};
+type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>;
+/**
+ * Defines a custom adapter that translates a spec format into Kubb's universal
+ * AST, for example GraphQL, gRPC, or AsyncAPI. The built-in `@kubb/adapter-oas`
+ * handles OpenAPI/Swagger documents.
+ *
+ * Adapters must return an `InputNode` from `parse`. That node is what every
+ * plugin in the build consumes.
+ *
+ * @example
+ * ```ts
+ * import { createAdapter, type AdapterFactoryOptions } from '@kubb/core'
+ * import { ast } from '@kubb/ast'
+ *
+ * type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
+ *
+ * export const myAdapter = createAdapter<MyAdapter>((options) => ({
+ *   name: 'my-adapter',
+ *   options,
+ *   document: null,
+ *   async parse(_source) {
+ *     // Convert the source (path or inline data) into an InputNode.
+ *     return ast.factory.createInput()
+ *   },
+ *   getImports: () => [],
+ *   async validate() {
+ *     // Throw here when the spec is invalid.
+ *   },
+ * }))
+ * ```
+ */
+declare function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T>;
+//#endregion
+//#region src/constants.d.ts
+/**
+ * Stable codes Kubb attaches to a `Diagnostic`. Each maps to a known failure mode
+ * and stays stable so it can be referenced in tooling and (later) docs. Reference
+ * these instead of inlining the string at a throw site.
+ */
+declare const diagnosticCode: {
+  /**
+   * Fallback for an unstructured error with no specific code.
+   */
+  readonly unknown: "KUBB_UNKNOWN";
+  /**
+   * The `input.path` file or URL could not be read.
+   */
+  readonly inputNotFound: "KUBB_INPUT_NOT_FOUND";
+  /**
+   * An adapter was configured without an `input`.
+   */
+  readonly inputRequired: "KUBB_INPUT_REQUIRED";
+  /**
+   * A `$ref` (or equivalent reference) could not be resolved in the source document.
+   */
+  readonly refNotFound: "KUBB_REF_NOT_FOUND";
+  /**
+   * A server variable value is not allowed by its `enum`.
+   */
+  readonly invalidServerVariable: "KUBB_INVALID_SERVER_VARIABLE";
+  /**
+   * A required plugin is missing from the config.
+   */
+  readonly pluginNotFound: "KUBB_PLUGIN_NOT_FOUND";
+  /**
+   * A plugin threw while generating.
+   */
+  readonly pluginFailed: "KUBB_PLUGIN_FAILED";
+  /**
+   * A plugin reported a non-fatal warning through `ctx.warn`.
+   */
+  readonly pluginWarning: "KUBB_PLUGIN_WARNING";
+  /**
+   * A plugin reported an informational message through `ctx.info`.
+   */
+  readonly pluginInfo: "KUBB_PLUGIN_INFO";
+  /**
+   * A schema uses a `format` Kubb does not map to a specific type. Reserved for
+   * adapters to emit as a `warning`.
+   */
+  readonly unsupportedFormat: "KUBB_UNSUPPORTED_FORMAT";
+  /**
+   * A referenced schema or operation is marked `deprecated`. Reserved for adapters
+   * to emit as an `info`.
+   */
+  readonly deprecated: "KUBB_DEPRECATED";
+  /**
+   * An adapter is required but the config has none. The build cannot read the input
+   * without one.
+   */
+  readonly adapterRequired: "KUBB_ADAPTER_REQUIRED";
+  /**
+   * A resolved output path escapes the output directory, which can stem from a path
+   * traversal in the spec or a misconfigured `group.name`.
+   */
+  readonly pathTraversal: "KUBB_PATH_TRAVERSAL";
+  /**
+   * A plugin's options are invalid, for example `output.mode: 'file'` paired with a `group` option.
+   */
+  readonly invalidPluginOptions: "KUBB_INVALID_PLUGIN_OPTIONS";
+  /**
+   * A post-generate shell hook (`hooks.done`) exited with a failure.
+   */
+  readonly hookFailed: "KUBB_HOOK_FAILED";
+  /**
+   * The formatter pass over the generated files failed.
+   */
+  readonly formatFailed: "KUBB_FORMAT_FAILED";
+  /**
+   * The linter pass over the generated files failed.
+   */
+  readonly lintFailed: "KUBB_LINT_FAILED";
+  /**
+   * Not a failure. Carries a plugin's elapsed time, summed into the run total.
+   */
+  readonly performance: "KUBB_PERFORMANCE";
+  /**
+   * Not a failure. A newer Kubb version is available on npm.
+   */
+  readonly updateAvailable: "KUBB_UPDATE_AVAILABLE";
+};
+/**
+ * Union of the stable {@link diagnosticCode} values.
+ */
+type DiagnosticCode = (typeof diagnosticCode)[keyof typeof diagnosticCode];
+//#endregion
+//#region src/createReporter.d.ts
+/**
+ * Numeric log-level thresholds used internally to compare verbosity.
+ *
+ * Higher numbers are more verbose.
+ */
+declare const logLevel: {
+  readonly silent: number;
+  readonly error: 0;
+  readonly warn: 1;
+  readonly info: 3;
+  readonly verbose: 4;
+};
+/**
+ * A built-in reporter that renders a run's output, independent of the live logger view.
+ *
+ * - `cli` renders the per-config summary to the terminal (the default).
+ * - `json` writes a machine-readable report to stdout, for CI.
+ * - `file` writes a config's diagnostics to `.kubb/kubb-<name>-<timestamp>.log`.
+ */
+type ReporterName = 'cli' | 'json' | 'file';
+/**
+ * One config's outcome within a run, as handed to a {@link Reporter}.
+ */
+type GenerationResult = {
+  config: Config;
+  /**
+   * Diagnostics collected while generating this config.
+   */
+  diagnostics: Array<Diagnostic>;
+  /**
+   * Number of files written for this config.
+   */
+  filesCreated: number;
+  status: 'success' | 'failed';
+  /**
+   * `process.hrtime()` snapshot taken when this config started generating.
+   */
+  hrStart: [number, number];
+};
+/**
+ * Render settings passed alongside the {@link GenerationResult}. These are not part of the run
+ * data, such as the output verbosity.
+ */
+type ReporterContext = {
+  /**
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`).
+   */
+  logLevel: (typeof logLevel)[keyof typeof logLevel];
+};
+/**
+ * Host-facing reporter, as installed onto a run. Unlike a Logger (the live TUI view), a reporter
+ * never sees the event emitter. `report` runs once per config. `drain`, when present, runs once
+ * after the last config.
+ */
+type Reporter = {
+  /**
+   * Display name, matching a {@link ReporterName} for the built-ins.
+   */
+  name: string;
+  /**
+   * Called once per config with that config's result and the render context.
+   */
+  report: (result: GenerationResult, context: ReporterContext) => void | Promise<void>;
+  /**
+   * Optional finalizer called once after the run's last config. The host wires it to
+   * `kubb:lifecycle:end`. {@link createReporter} closes it over the values that `report` returned.
+   */
+  drain?: (context: ReporterContext) => void | Promise<void>;
+};
+/**
+ * Reporter definition passed to {@link createReporter}. `report` returns the value to collect for
+ * this config (e.g. a built report), and the optional `drain` receives the collected reports to
+ * emit as one document. `T` is inferred from `report`'s return type.
+ */
+type UserReporter<T = void> = {
+  name: string;
+  report: (result: GenerationResult, context: ReporterContext) => T | Promise<T>;
+  drain?: (context: ReporterContext, reports: Array<T>) => void | Promise<void>;
+};
+/**
+ * Defines a reporter. When the definition has a `drain`, the returned reporter buffers each value
+ * `report` returns and hands the array to `drain` once, then clears it. Without a `drain`, nothing
+ * is buffered. Wiring the reporter onto the run's events is the host's job, so the reporter only
+ * ever deals with a {@link GenerationResult}.
+ *
+ * @example
+ * ```ts
+ * import { createReporter, Diagnostics } from '@kubb/core'
+ *
+ * export const jsonReporter = createReporter({
+ *   name: 'json',
+ *   report(result) {
+ *     return { status: Diagnostics.hasError(result.diagnostics) ? 'failed' : 'success', diagnostics: result.diagnostics }
+ *   },
+ *   drain(context, reports) {
+ *     process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`)
+ *   },
+ * })
+ * ```
+ */
+declare function createReporter<T = void>(reporter: UserReporter<T>): Reporter;
+//#endregion
+//#region src/createStorage.d.ts
+/**
+ * Backend that persists generated files. Kubb ships with `fsStorage` (writes
+ * to disk) and `memoryStorage` (keeps everything in RAM). Implement this
+ * interface to write somewhere else, such as S3 or a database.
+ */
+type Storage = {
+  /**
+   * Identifier used in logs and diagnostics (`'fs'`, `'memory'`, `'s3'`).
+   */
+  readonly name: string;
+  /**
+   * Returns `true` when an entry for `key` exists.
+   */
+  hasItem(key: string): Promise<boolean>;
+  /**
+   * Reads the stored string. Returns `null` when the key is missing.
+   */
+  getItem(key: string): Promise<string | null>;
+  /**
+   * Stores `value` under `key`, creating any required structure (directories,
+   * buckets, ...).
+   */
+  setItem(key: string, value: string): Promise<void>;
+  /**
+   * Deletes the entry for `key`. No-op when the key does not exist.
+   */
+  removeItem(key: string): Promise<void>;
+  /**
+   * Returns every key. Pass `base` to filter to keys starting with that prefix.
+   */
+  getKeys(base?: string): Promise<Array<string>>;
+  /**
+   * Removes every entry. Pass `base` to scope the wipe to a key prefix.
+   */
+  clear(base?: string): Promise<void>;
+  /**
+   * Optional teardown hook for a backend to flush buffers, close connections,
+   * or release file locks.
+   */
+  dispose?(): Promise<void>;
+};
+/**
+ * Defines a custom storage backend. The builder receives user options and
+ * returns a `Storage` implementation. Kubb ships with filesystem and in-memory
+ * storages. A custom backend writes generated files elsewhere, such as cloud
+ * storage or a database.
+ *
+ * @example In-memory storage (the built-in implementation)
+ * ```ts
+ * import { createStorage } from '@kubb/core'
+ *
+ * export const memoryStorage = createStorage(() => {
+ *   const store = new Map<string, string>()
+ *
+ *   return {
+ *     name: 'memory',
+ *     async hasItem(key) {
+ *       return store.has(key)
+ *     },
+ *     async getItem(key) {
+ *       return store.get(key) ?? null
+ *     },
+ *     async setItem(key, value) {
+ *       store.set(key, value)
+ *     },
+ *     async removeItem(key) {
+ *       store.delete(key)
+ *     },
+ *     async getKeys(base) {
+ *       const keys = [...store.keys()]
+ *       return base ? keys.filter((k) => k.startsWith(base)) : keys
+ *     },
+ *     async clear(base) {
+ *       if (!base) store.clear()
+ *     },
+ *   }
+ * })
+ * ```
+ */
+declare function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage;
+//#endregion
+//#region src/createRenderer.d.ts
+/**
+ * Minimal interface any Kubb renderer must satisfy.
+ *
+ * `TElement` is the type the renderer accepts, for example `KubbReactElement`
+ * for `@kubb/renderer-jsx` or a custom type for your own renderer. Defaults to
+ * `unknown` so generators that don't care about the element type work without
+ * specifying it.
+ */
+type Renderer<TElement = unknown> = {
+  /**
+   * Renders `element` and populates {@link files} with the resulting {@link FileNode} objects.
+   * Called once per render cycle. Must resolve before {@link files} is read.
+   */
+  render(element: TElement): Promise<void>;
+  /**
+   * Accumulated {@link FileNode} results produced by the last {@link render} call.
+   * Not populated when {@link stream} is implemented.
+   */
+  readonly files: Array<FileNode>;
+  /**
+   * When present, core calls this instead of {@link render} and {@link files},
+   * forwarding each file to `FileManager` as soon as it is ready.
+   */
+  stream?(element: TElement): Iterable<FileNode>;
+  /**
+   * Disposer hook so renderers participate in `using` blocks: `using r = rendererFactory()`
+   * runs cleanup on every exit path, including thrown errors.
+   */
+  [Symbol.dispose](): void;
+};
+/**
+ * A factory function that produces a fresh {@link Renderer} per render cycle.
+ *
+ * Generators use this to declare which renderer handles their output.
+ */
+type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
+/**
+ * Defines a renderer factory. Renderers turn the generator's return value
+ * (JSX, a template string, a tree of any shape) into `FileNode`s that get
+ * written to disk.
+ *
+ * A renderer can target output formats beyond JSX, for instance a Handlebars
+ * renderer or one that writes binary files. Plugins and generators pick the
+ * renderer to use via the `renderer` field on `defineGenerator`.
+ *
+ * @example A minimal renderer that wraps a custom runtime
+ * ```ts
+ * import { createRenderer } from '@kubb/core'
+ *
+ * export const myRenderer = createRenderer(() => {
+ *   const runtime = new MyRuntime()
+ *   return {
+ *     async render(element) {
+ *       await runtime.render(element)
+ *     },
+ *     get files() {
+ *       return runtime.files
+ *     },
+ *     [Symbol.dispose]() {
+ *       runtime.dispose()
+ *     },
+ *   }
+ * })
+ * ```
+ */
+declare function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement>;
+//#endregion
+//#region src/defineResolver.d.ts
+/**
+ * Type/string pattern filter for include/exclude/override matching.
+ */
+type PatternFilter = {
+  type: string;
+  pattern: string | RegExp;
+};
+/**
+ * Pattern filter with partial option overrides applied when the pattern matches.
+ */
+type PatternOverride<TOptions> = PatternFilter & {
+  options: Omit<Partial<TOptions>, 'override'>;
+};
+/**
+ * Context for resolving filtered options for a given operation or schema node.
+ *
+ * @internal
+ */
+type ResolveOptionsContext<TOptions> = {
+  options: TOptions;
+  exclude?: Array<PatternFilter>;
+  include?: Array<PatternFilter>;
+  override?: Array<PatternOverride<TOptions>>;
+};
+/**
+ * Base constraint for all plugin resolver objects.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are injected automatically by `defineResolver`. Extend this type to add custom resolution methods.
+ *
+ * @example
+ * ```ts
+ * type MyResolver = Resolver & {
+ *   resolveName(node: SchemaNode): string
+ *   resolveTypedName(node: SchemaNode): string
+ * }
+ * ```
+ */
+type Resolver = {
+  name: string;
+  pluginName: string;
+  default(name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null;
+  resolvePath(params: ResolverPathParams, context: ResolverContext): string;
+  resolveFile(params: ResolverFileParams, context: ResolverContext): FileNode;
+  resolveBanner(meta: InputMeta | undefined, context: ResolveBannerContext): string | null;
+  resolveFooter(meta: InputMeta | undefined, context: ResolveBannerContext): string | null;
+};
+/**
+ * File-specific parameters for `Resolver.resolvePath`.
+ *
+ * Pass alongside a `ResolverContext` to identify which file to resolve.
+ * Provide `tag` for tag-based grouping or `path` for path-based grouping.
+ *
+ * @example
+ * ```ts
+ * resolver.resolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/pets/petTypes.ts'
+ * ```
+ */
+type ResolverPathParams = {
+  baseName: FileNode['baseName'];
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string;
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string;
+};
+/**
+ * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
+ *
+ * Describes where on disk output is rooted, which output config is active, and the optional
+ * grouping strategy that controls subdirectory layout.
+ *
+ * @example
+ * ```ts
+ * const context: ResolverContext = {
+ *   root: config.root,
+ *   output,
+ *   group,
+ * }
+ * ```
+ */
+type ResolverContext = {
+  root: string;
+  output: Output;
+  group?: Group;
+  /**
+   * Plugin name used to populate `meta.pluginName` on the resolved file.
+   */
+  pluginName?: string;
+};
+/**
+ * File-specific parameters for `Resolver.resolveFile`.
+ *
+ * Pass alongside a `ResolverContext` to fully describe the file to resolve.
+ * `tag` and `path` are used only when a matching `group` is present in the context.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveFile(
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/pets/listPets.ts', ... }
+ * ```
+ */
+type ResolverFileParams = {
+  name: string;
+  extname: FileNode['extname'];
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string;
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string;
+};
+/**
+ * Per-file context describing the file a banner/footer is being resolved for.
+ *
+ * Supplied by the generator (or the barrel plugin) at resolve-time and merged
+ * into `BannerMeta` so a `banner`/`footer` function can branch on the file kind,
+ * e.g. omit a `'use server'` directive on re-export files.
+ */
+type ResolveBannerFile = {
+  /**
+   * Full output path of the file being generated.
+   */
+  path: string;
+  /**
+   * File name only, e.g. `'stocks.ts'`.
+   */
+  baseName: string;
+  /**
+   * `true` for `index.ts` re-export barrels.
+   */
+  isBarrel?: boolean;
+  /**
+   * `true` for group `[dir]/[dir].ts` aggregation files.
+   */
+  isAggregation?: boolean;
+};
+/**
+ * Document metadata extended with per-file context, passed to a `banner`/`footer` function.
+ *
+ * Carries everything in {@link InputMeta} plus the file the banner is rendered into, so a
+ * single function can decide per file (e.g. skip a directive on barrel/aggregation files).
+ *
+ * @example Skip a directive on re-export files
+ * `banner: (meta) => (meta.isBarrel || meta.isAggregation) ? '' : "'use server'"`
+ */
+type BannerMeta = InputMeta & {
+  /**
+   * Full output path of the file being generated.
+   */
+  filePath: string;
+  /**
+   * File name only, e.g. `'stocks.ts'`.
+   */
+  baseName: string;
+  /**
+   * `true` for `index.ts` re-export barrels.
+   */
+  isBarrel: boolean;
+  /**
+   * `true` for group `[dir]/[dir].ts` aggregation files.
+   */
+  isAggregation: boolean;
+};
+/**
+ * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
+ *
+ * `output` is optional, since not every plugin configures a banner/footer.
+ * `config` carries the global Kubb config, used to derive the default Kubb banner.
+ * `file` carries per-file context forwarded to a `banner`/`footer` function.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveBanner(meta, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>;
+  config: Config;
+  file?: ResolveBannerFile;
+};
+/**
+ * Builder type for the plugin-specific resolver fields.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are optional, with built-in fallbacks injected when omitted.
+ *
+ * Methods in the returned object can call sibling resolver methods via `this`.
+ */
+type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter' | 'name' | 'pluginName'> & Partial<Pick<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>> & {
+  name: string;
+  pluginName: T['name'];
+} & ThisType<T['resolver']>;
+/**
+ * Default path resolver used by `defineResolver`.
+ *
+ * - `mode: 'file'` resolves directly to `output.path` (the full file path, extension included).
+ * - `mode: 'directory'` (default) resolves to `output.path/{baseName}`, or into a
+ *   subdirectory when `group` and a `tag`/`path` value are provided.
+ *
+ * A custom `group.name` function overrides the default subdirectory naming.
+ * For `tag` groups the default is the camelCased tag.
+ * For `path` groups the default is the first path segment after `/`.
+ *
+ * @example Flat output
+ * ```ts
+ * defaultResolvePath({ baseName: 'petTypes.ts' }, { root: '/src', output: { path: 'types' } })
+ * // → '/src/types/petTypes.ts'
+ * ```
+ *
+ * @example Tag-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/pets/petTypes.ts'
+ * ```
+ *
+ * @example Path-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', path: '/pets/list' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'path' } },
+ * )
+ * // → '/src/types/pets/petTypes.ts'
+ * ```
+ *
+ * @example Single file (`mode: 'file'`)
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts' },
+ *   { root: '/src', output: { path: 'types.ts', mode: 'file' } },
+ * )
+ * // → '/src/types.ts'
+ * ```
+ */
+/**
+ * Defines a plugin resolver. The resolver is the object that decides what
+ * every generated symbol and file path is called. Built-in defaults handle
+ * name casing, include/exclude/override filtering, output path computation,
+ * and file construction. Supply your own to override any of them:
+ *
+ * - `default` sets the name casing strategy (camelCase or PascalCase).
+ * - `resolveOptions` does include/exclude/override filtering.
+ * - `resolvePath` computes the output path.
+ * - `resolveFile` builds the full `FileNode`.
+ * - `resolveBanner` and `resolveFooter` produce the top and bottom of file text.
+ *
+ * Methods in the returned object can call sibling resolver methods via `this`.
+ * A custom rule can delegate to a default, for example `this.default(name, 'type')`.
+ *
+ * @example Basic resolver with naming helpers
+ * ```ts
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(name) {
+ *     return this.default(name, 'function')
+ *   },
+ *   resolveTypeName(name) {
+ *     return this.default(name, 'type')
+ *   },
+ * }))
+ * ```
+ *
+ * @example Custom output path
+ * ```ts
+ * import path from 'node:path'
+ *
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
+ *   name: 'custom',
+ *   resolvePath({ baseName }, { root, output }) {
+ *     return path.resolve(root, output.path, 'generated', baseName)
+ *   },
+ * }))
+ * ```
+ */
+declare function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'];
+//#endregion
+//#region src/definePlugin.d.ts
+/**
+ * Reads a type from a registry, falling back to `{}` when the key is absent. Lets
+ * `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry` be augmented without
+ * touching core.
+ *
+ * @internal
+ */
+type ExtractRegistryKey$1<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
+/**
+ * How a plugin consolidates its generated code into files.
+ * - `'directory'` writes one file per operation or schema under `path`.
+ * - `'file'` writes everything into a single file.
+ */
+type OutputMode = 'directory' | 'file';
+/**
+ * Output configuration shared by every plugin. Each plugin extends this with
+ * its own keys via the `Kubb.PluginOptionsRegistry.output` interface merge.
+ */
+type Output<_TOptions = unknown> = {
+  /**
+   * Directory where the plugin writes its generated code, resolved against the global
+   * `output.path` set on `defineConfig`. With `mode: 'file'`, this is the full output file
+   * path and must include the extension (e.g. `'types.ts'`, `'models.py'`).
+   */
+  path: string;
+  /**
+   * How generated code is consolidated into files.
+   * - `'directory'` writes one file per operation or schema under `path`.
+   * - `'file'` writes everything into a single file. The `path` must include the file extension.
+   *
+   * @default 'directory'
+   */
+  mode?: OutputMode;
+  /**
+   * Text prepended to every generated file. Useful for license headers,
+   * lint disables, or `@ts-nocheck` directives.
+   *
+   * A string is applied to every file (including barrel and aggregation re-export files).
+   * Pass a function to compute the banner from the file's `BannerMeta` document metadata
+   * plus per-file context (`isBarrel`, `isAggregation`, `filePath`, `baseName`), so you can
+   * skip the banner on specific files.
+   *
+   * @example Add a directive to source files but not re-export files
+   * `banner: (meta) => (meta.isBarrel || meta.isAggregation) ? '' : "'use server'"`
+   */
+  banner?: string | ((meta: BannerMeta) => string);
+  /**
+   * Text appended at the end of every generated file. Mirror of `banner`.
+   * Pass a function to compute the footer from the file's `BannerMeta`.
+   */
+  footer?: string | ((meta: BannerMeta) => string);
+} & ExtractRegistryKey$1<Kubb.PluginOptionsRegistry, 'output'>;
+/**
+ * Groups generated files into subdirectories based on an OpenAPI tag or path
+ * segment.
+ */
+type Group = {
+  /**
+   * Property used to assign each operation to a group.
+   * - `'tag'` uses the first tag (`operation.getTags().at(0)?.name`).
+   * - `'path'` uses the first segment of the operation's URL.
+   */
+  type: 'tag' | 'path';
+  /**
+   * Returns the subdirectory name from the group key. Defaults to the camelCased tag for
+   * `tag` groups, or the camelCased first path segment for `path` groups.
+   */
+  name?: (context: {
+    group: string;
+  }) => string;
+};
+/**
+ * Couples `output.mode` with the plugin's `group` option at the type level.
+ * - `mode: 'file'` forbids `group` (a single file has nothing to group).
+ * - `mode: 'directory'` (or no mode) allows an optional `group` to organize
+ *   files into per-group subdirectories.
+ *
+ * Intersect into a plugin's `Options` type instead of declaring `output` and
+ * `group` directly, since `mode` lives inside `output` while `group` is its sibling.
+ * The generic keeps a plugin's extended `Output` shape intact.
+ *
+ * @example
+ * ```ts
+ * export type Options = OutputOptions & {
+ *   exclude?: Array<Exclude>
+ * }
+ * ```
+ */
+type OutputOptions<TOutput extends Output = Output> = {
+  output?: TOutput & {
+    mode?: 'directory';
+  };
+  group?: Group;
+} | {
+  output: TOutput & {
+    mode: 'file';
+  };
+  group?: never;
+};
+type ByTag = {
+  /**
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   */
+  type: 'tag';
+  /**
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+type ByOperationId = {
+  /**
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   */
+  type: 'operationId';
+  /**
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+type ByPath = {
+  /**
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
+   */
+  type: 'path';
+  /**
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   */
+  pattern: string | RegExp;
+};
+type ByMethod = {
+  /**
+   * Filter by HTTP method: `'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, `'DELETE'`, `'HEAD'`, `'OPTIONS'`, `'TRACE'`.
+   */
+  type: 'method';
+  /**
+   * HTTP method to match, as one of the `HttpMethod` values (`'GET'`, `'POST'`, `'PUT'`,
+   * `'PATCH'`, `'DELETE'`, `'HEAD'`, `'OPTIONS'`, `'TRACE'`) or a regex.
+   */
+  pattern: HttpMethod | RegExp;
+};
+type BySchemaName = {
+  /**
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   */
+  type: 'schemaName';
+  /**
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+type ByContentType = {
+  /**
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   */
+  type: 'contentType';
+  /**
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+/**
+ * Filter that skips matching operations or schemas during generation, for example
+ * deprecated endpoints or internal-only schemas.
+ *
+ * @example
+ * ```ts
+ * exclude: [
+ *   { type: 'tag', pattern: 'internal' },
+ *   { type: 'path', pattern: /^\/admin/ },
+ *   { type: 'operationId', pattern: /^deprecated_/ },
+ * ]
+ * ```
+ */
+type Exclude$1 = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
+/**
+ * Filter that restricts generation to operations or schemas matching at least
+ * one entry. Useful for partial builds (one tag, one API version).
+ *
+ * @example
+ * ```ts
+ * include: [
+ *   { type: 'tag', pattern: 'public' },
+ *   { type: 'path', pattern: /^\/api\/v1/ },
+ * ]
+ * ```
+ */
+type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
+/**
+ * Filter paired with a partial options object. When the filter matches, the
+ * options are merged on top of the plugin defaults for that operation only.
+ * Useful for "this one tag goes to a different folder" rules.
+ *
+ * Entries are evaluated top to bottom. The first matching entry wins.
+ *
+ * @example
+ * ```ts
+ * override: [
+ *   {
+ *     type: 'tag',
+ *     pattern: 'admin',
+ *     options: { output: { path: './src/gen/admin' } },
+ *   },
+ *   {
+ *     type: 'operationId',
+ *     pattern: 'listPets',
+ *     options: { enumType: 'literal' },
+ *   },
+ * ]
+ * ```
+ */
+type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  options: Omit<Partial<TOptions>, 'override'>;
+};
+type PluginFactoryOptions<
+/**
+ * Unique plugin name.
+ */
+TName extends string = string,
+/**
+ * User-facing plugin options.
+ */
+TOptions extends object = object,
+/**
+ * Plugin options after defaults are applied.
+ */
+TResolvedOptions extends object = TOptions,
+/**
+ * Resolver that encapsulates naming and path-resolution helpers.
+ * Define with `defineResolver` and export alongside the plugin.
+ */
+TResolver extends Resolver = Resolver> = {
+  name: TName;
+  options: TOptions;
+  resolvedOptions: TResolvedOptions;
+  resolver: TResolver;
+};
+/**
+ * Context passed to a plugin's `kubb:plugin:setup` handler, where it registers generators and
+ * sets its resolver, transformer, and options.
+ */
+type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Register one or more generators dynamically. Generators fire during the AST walk
+   * (schema/operation/operations) just like generators declared statically on `createPlugin`.
+   *
+   * Pass generators as separate arguments. Spread an existing list to register it in one call.
+   *
+   * @example
+   * ```ts
+   * ctx.addGenerator(myGenerator)
+   * ctx.addGenerator(schemaGenerator, operationGenerator)
+   * ctx.addGenerator(...selectedGenerators)
+   * ```
+   */
+  addGenerator<TElement = unknown>(...generators: Array<Generator<TFactory, TElement>>): void;
+  /**
+   * Set or override the resolver for this plugin.
+   * The resolver controls file naming and path resolution.
+   */
+  setResolver(resolver: Partial<TFactory['resolver']>): void;
+  /**
+   * Add a macro that rewrites AST nodes before they reach generators. Macros run in the order they
+   * are added, after any macros from earlier `addMacro` calls.
+   */
+  addMacro(macro: Macro): void;
+  /**
+   * Replace this plugin's macros with `macros`.
+   */
+  setMacros(macros: ReadonlyArray<Macro>): void;
+  /**
+   * Set resolved options merged into the normalized plugin's `options`.
+   * Call this in `kubb:plugin:setup` to provide options generators need.
+   */
+  setOptions(options: TFactory['resolvedOptions']): void;
+  /**
+   * Inject a raw file into the build output, bypassing the generation pipeline.
+   *
+   * Pass `copy` with an absolute path to emit a real source file (a shipped template) into the
+   * generated folder verbatim, instead of building its content from `sources`.
+   */
+  injectFile(userFileNode: UserFileNode): void;
+  /**
+   * Merge a partial config update into the current build configuration.
+   */
+  updateConfig(config: Partial<Config>): void;
+  /**
+   * The resolved build configuration at setup time.
+   */
+  config: Config;
+  /**
+   * The plugin's user-provided options.
+   */
+  options: TFactory['options'];
+};
+/**
+ * A plugin object produced by `definePlugin`. Its lifecycle handlers live under a single
+ * `hooks` property rather than flat methods.
+ */
+type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Unique name for the plugin, following the same naming convention as `createPlugin`.
+   */
+  name: string;
+  /**
+   * Plugins that must be registered before this plugin executes.
+   * An error is thrown at startup when any listed dependency is missing.
+   */
+  dependencies?: Array<string>;
+  /**
+   * Controls the execution order of this plugin relative to others.
+   *
+   * - `'pre'` runs before all normal plugins.
+   * - `'post'` runs after all normal plugins.
+   * - `undefined` (default) runs in declaration order among normal plugins.
+   *
+   * Dependency constraints always take precedence over `enforce`.
+   */
+  enforce?: Enforce;
+  /**
+   * The options passed by the user when calling the plugin factory.
+   */
+  options?: TFactory['options'];
+  /**
+   * Lifecycle event handlers for this plugin.
+   * Any event from the global `KubbHooks` map can be subscribed to here.
+   */
+  hooks: { [K in keyof KubbHooks as K extends 'kubb:plugin:setup' ? never : K]?: (...args: KubbHooks[K]) => void | Promise<void> } & {
+    'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>;
+  };
+};
+/**
+ * Normalized plugin after setup, with runtime fields populated. Internal only. Plugins use the
+ * public `Plugin` type.
+ *
+ * @internal
+ */
+type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & {
+  options: TOptions['resolvedOptions'] & {
+    output: Output;
+    include?: Array<Include>;
+    exclude: Array<Exclude$1>;
+    override: Array<Override<TOptions['resolvedOptions']>>;
+  };
+  resolver: TOptions['resolver'];
+  macros?: Array<Macro>;
+  generators?: Array<Generator>;
+  apply?: (config: Config) => boolean;
+  version?: string;
+};
+type KubbPluginStartContext = {
+  plugin: NormalizedPlugin;
+};
+type KubbPluginEndContext = {
+  plugin: NormalizedPlugin;
+  duration: number;
+  success: boolean;
+  error?: Error;
+  config: Config;
+  /**
+   * Returns all files currently in the file manager (lazy snapshot).
+   * Includes files added by plugins that have already run.
+   */
+  readonly files: ReadonlyArray<FileNode>;
+  /**
+   * Upsert one or more files into the file manager.
+   */
+  upsertFile: (...files: Array<FileNode>) => void;
+};
+/**
+ * Wraps a plugin factory and returns a function that accepts user options and
+ * yields a typed `Plugin`. Lifecycle handlers go inside a single `hooks` object.
+ *
+ * Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
+ * `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
+ * convention (`plugin-react-query`, `plugin-zod`, ...).
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from '@kubb/core'
+ *
+ * export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
+ *   name: 'plugin-ts',
+ *   hooks: {
+ *     'kubb:plugin:setup'(ctx) {
+ *       ctx.setResolver(resolverTs)
+ *     },
+ *   },
+ * }))
+ * ```
+ */
+declare function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(factory: (options: TFactory['options']) => Plugin<TFactory>): (options?: TFactory['options']) => Plugin<TFactory>;
+//#endregion
+//#region src/FileManager.d.ts
+/**
+ * Hooks fired by a `FileManager`.
+ *
+ * - `upsert` fires once per resolved file added through `add` or `upsert`.
+ */
+type FileManagerHooks = {
+  upsert: [file: FileNode];
+};
+/**
+ * In-memory file store for generated files. Files sharing a `path` are merged
+ * (sources/imports/exports concatenated). The `files` getter is sorted by
+ * path length (barrel `index.ts` last within a bucket).
+ *
+ * @example
+ * ```ts
+ * const manager = new FileManager()
+ * manager.upsert(myFile)
+ * manager.files // sorted view
+ * ```
+ */
+declare class FileManager {
+  #private;
+  /**
+   * Subscribe to file-store changes. Listeners on `upsert` see each resolved file as it lands
+   * through `add` or `upsert`.
+   */
+  readonly hooks: AsyncEventEmitter<FileManagerHooks>;
+  add(...files: Array<FileNode>): Array<FileNode>;
+  upsert(...files: Array<FileNode>): Array<FileNode>;
+  getByPath(path: string): FileNode | null;
+  deleteByPath(path: string): void;
+  clear(): void;
+  /**
+   * Releases all stored files and clears every `hooks` listener. Called by the core after
+   * `kubb:build:end`.
+   */
+  dispose(): void;
+  [Symbol.dispose](): void;
+  /**
+   * All stored files in stable sort order (shortest path first, barrel files
+   * last within a length bucket). Returns a cached view, do not mutate.
+   */
+  get files(): Array<FileNode>;
+}
+//#endregion
+//#region src/KubbDriver.d.ts
+type Options = {
+  hooks: AsyncEventEmitter<KubbHooks>;
+};
+type RequirePluginContext = {
+  /**
+   * Name of the plugin that declared the dependency, included in the error so users can
+   * trace which plugin needs the missing one.
+   */
+  requiredBy?: string;
+};
+declare class KubbDriver {
+  #private;
+  readonly config: Config;
+  readonly options: Options;
+  /**
+   * The streaming `InputNode<true>` produced by the adapter. Set after adapter setup.
+   * Parse-only adapters are wrapped automatically.
+   */
+  inputNode: InputNode<true> | null;
+  adapter: Adapter | null;
+  /**
+   * Central file store for all generated files.
+   * Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
+   * add files. This property gives direct read/write access when needed.
+   */
+  readonly fileManager: FileManager;
+  readonly plugins: Map<string, NormalizedPlugin>;
+  constructor(config: Config, options: Options);
+  /**
+   * Normalizes every configured plugin, orders them, and registers their lifecycle handlers.
+   * A plugin that another lists as a dependency runs first, then `enforce: 'pre'` before
+   * `'post'`. When the config has an adapter, the adapter source is resolved from the input
+   * so `run` can parse it later.
+   */
+  setup(): Promise<void>;
+  get hooks(): AsyncEventEmitter<KubbHooks>;
+  /**
+   * Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
+   * can configure generators, resolvers, macros and renderers before `buildStart` runs.
+   *
+   * Called once from `run` before the plugin execution loop begins.
+   */
+  emitSetupHooks(): Promise<void>;
+  /**
+   * Registers a generator for the given plugin on the shared event emitter.
+   *
+   * The generator's `schema`, `operation`, and `operations` methods are registered as
+   * listeners on `kubb:generate:schema`, `kubb:generate:operation`, and `kubb:generate:operations`
+   * respectively. Each listener is scoped to the owning plugin via a `ctx.plugin.name` check
+   * so that generators from different plugins do not cross-fire.
+   *
+   * The renderer comes from `generator.renderer`. Set `generator.renderer = null` (or leave it
+   * unset) to opt out of rendering.
+   *
+   * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
+   */
+  registerGenerator(pluginName: string, generator: Generator): void;
+  /**
+   * Returns `true` when at least one generator was registered for the given plugin
+   * via `addGenerator()` in `kubb:plugin:setup` (event-based path).
+   *
+   * Used by the build loop to decide whether to walk the AST and emit generator events
+   * for a plugin that has no static `plugin.generators`.
+   */
+  hasEventGenerators(pluginName: string): boolean;
+  /**
+   * Runs the full plugin pipeline. Returns the diagnostics collected so far even
+   * when an outer hook throws, since the orchestrator preserves partial state by capturing
+   * the failure as a {@link Diagnostic} instead of propagating. Each plugin also
+   * contributes a `timing` diagnostic for the run summary.
+   */
+  run({
+    storage
+  }: {
+    storage: Storage;
+  }): Promise<{
+    diagnostics: Array<Diagnostic>;
+  }>;
+  /**
+   * Stores whatever a generator method or `kubb:generate:*` hook returned.
+   *
+   * - An `Array<FileNode>` goes straight into `fileManager` via `upsert`.
+   * - A renderer element runs through `renderer` (the renderer factory, e.g. JSX) and the
+   *   produced files go to `fileManager.upsert`.
+   * - A falsy result is treated as a no-op. The generator wrote files itself via
+   *   `ctx.upsertFile`.
+   *
+   * Pass `renderer` when the result may be a renderer element. Generators that only return
+   * `Array<FileNode>` do not need one.
+   */
+  dispatch<TElement = unknown>({
+    result,
+    renderer
+  }: {
+    result: TElement | Array<FileNode> | undefined | null;
+    renderer?: RendererFactory<TElement> | null;
+  }): Promise<void>;
+  /**
+   * Removes every listener the driver added. Listeners attached directly to `hooks` from outside
+   * the driver survive. Called at the end of a build to prevent leaks across repeated builds.
+   *
+   * @internal
+   */
+  dispose(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Merges `partial` with the plugin's default resolver and stores the result.
+   * Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
+   * get the up-to-date resolver without going through `getResolver()`.
+   */
+  setPluginResolver(pluginName: string, partial: Partial<Resolver>): void;
+  /**
+   * Returns the resolver for the given plugin.
+   *
+   * Resolution order: dynamic resolver set via `setPluginResolver` → static resolver on the
+   * plugin → lazily created default resolver (identity name, no path transforms).
+   */
+  getResolver<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Kubb.PluginRegistry[TName]['resolver'];
+  getResolver<TResolver extends Resolver = Resolver>(pluginName: string): TResolver;
+  getContext<TOptions extends PluginFactoryOptions>(plugin: NormalizedPlugin<TOptions>): Omit<GeneratorContext<TOptions>, 'options'>;
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  getPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions> | undefined;
+  /**
+   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName, context?: RequirePluginContext): Plugin<Kubb.PluginRegistry[TName]>;
+  requirePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string, context?: RequirePluginContext): Plugin<TOptions>;
+}
+//#endregion
+//#region src/defineGenerator.d.ts
+/**
+ * Context passed to a generator's `schema`, `operation`, and `operations` methods.
+ *
+ * The driver sets `adapter` on the context before it runs a generator, so methods can read it
+ * without a null check. `ctx.options` carries the per-node options after exclude/include/override
+ * filtering for `schema` and `operation`, or the plugin-level options for `operations`.
+ */
+type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * The resolved Kubb config for this build, including `root`, `input`, `output`, and the
+   * full plugin list.
+   */
+  config: Config;
+  /**
+   * Absolute path to the current plugin's output directory.
+   */
+  root: string;
+  /**
+   * The driver running this build. Most generators never need it. Prefer the scoped helpers
+   * on this context (`getPlugin`, `getResolver`, `upsertFile`) over reaching into the driver.
+   */
+  driver: KubbDriver;
+  /**
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  getPlugin(name: string): Plugin | undefined;
+  /**
+   * Get a plugin by name, throws an error if not found.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>;
+  requirePlugin(name: string): Plugin;
+  /**
+   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver'];
+  getResolver(name: string): Resolver;
+  /**
+   * Add files only if they don't exist.
+   */
+  addFile: (...file: Array<FileNode>) => Promise<void>;
+  /**
+   * Merge sources into the same output file.
+   */
+  upsertFile: (...file: Array<FileNode>) => Promise<void>;
+  /**
+   * The build's event bus. Emit or listen to any `KubbHooks` event, for example to react to
+   * `kubb:build:end` from inside a generator.
+   */
+  hooks: AsyncEventEmitter<KubbHooks>;
+  /**
+   * The current plugin instance.
+   */
+  plugin: Plugin<TOptions>;
+  /**
+   * The current plugin's resolver. It decides what every generated symbol and file path is
+   * called. Kubb picks a `setResolver` registration first, then the plugin's static
+   * `resolver`, then the built-in default.
+   *
+   * @example Resolve a type name
+   * `ctx.resolver.default('pet', 'type') // 'Pet'`
+   *
+   * @example Resolve an output file
+   * `ctx.resolver.resolveFile({ name: 'pet', extname: '.ts' }, { root, output })`
+   */
+  resolver: TOptions['resolver'];
+  /**
+   * Report a warning. Collected as a `warning` diagnostic attributed to the current
+   * plugin. It surfaces in the run summary but does not fail the build. For a structured
+   * diagnostic with a code and source location, use `Diagnostics.report` or throw a
+   * `Diagnostics.Error` directly.
+   */
+  warn: (message: string) => void;
+  /**
+   * Report an error. Collected as an `error` diagnostic attributed to the current
+   * plugin, which fails the build.
+   */
+  error: (error: string | Error) => void;
+  /**
+   * Report an informational message. Collected as an `info` diagnostic attributed to
+   * the current plugin.
+   */
+  info: (message: string) => void;
+  /**
+   * The configured adapter instance.
+   */
+  adapter: Adapter;
+  /**
+   * Document metadata from the adapter: title, version, base URL, and pre-computed
+   * schema index fields (`circularNames`, `enumNames`).
+   */
+  meta: InputMeta;
+  /**
+   * Resolved options after exclude/include/override filtering.
+   */
+  options: TOptions['resolvedOptions'];
+};
+/**
+ * Declares a named generator unit that walks the AST and emits files.
+ *
+ * `schema` runs for each schema node and `operation` for each operation node. `operations` runs
+ * once after every operation node is walked. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly, or call `ctx.upsertFile()` manually and return `null` to
+ * bypass rendering.
+ *
+ * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
+ *
+ * @example
+ * ```ts
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     const { adapter, resolver, root, options } = ctx
+ *     return <File ...><Type node={node} resolver={resolver} /></File>
+ *   },
+ * })
+ * ```
+ */
+type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
+  /**
+   * Used in diagnostic messages and debug output.
+   */
+  name: string;
+  /**
+   * Optional renderer factory that produces a {@link Renderer} for each render cycle.
+   *
+   * Generators that return renderer elements (e.g. JSX via `@kubb/renderer-jsx`) must set this
+   * to the matching renderer factory (e.g. `jsxRenderer` from `@kubb/renderer-jsx`).
+   *
+   * Generators that only return `Array<FileNode>` or `void` do not need to set this.
+   *
+   * Leave it unset or set `renderer: null` to opt out of rendering.
+   *
+   * @example
+   * ```ts
+   * import { jsxRenderer } from '@kubb/renderer-jsx'
+   * export const myGenerator = defineGenerator<PluginTs>({
+   *   renderer: jsxRenderer,
+   *   schema(node, ctx) { return <File ...>...</File> },
+   * })
+   * ```
+   */
+  renderer?: RendererFactory<TElement> | null;
+  /**
+   * Called for each schema node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
+  /**
+   * Called for each operation node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
+  /**
+   * Called once after all operations have been walked.
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
+   * plus `ctx.options` with the plugin-level options for the batch call.
+   */
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
+};
+/**
+ * Defines a generator: a unit of work that runs during the plugin's AST walk
+ * and produces files. Plugins register generators via `ctx.addGenerator()`
+ * inside `kubb:plugin:setup`.
+ *
+ * The returned object is the input as-is, but with `this` types preserved so
+ * `schema`/`operation`/`operations` methods are correctly typed against the
+ * plugin's `PluginFactoryOptions`. Renderer elements and `FileNode[]` returns
+ * are both handled by the runtime, so pick whichever style fits.
+ *
+ * @example JSX-based schema generator
+ * ```tsx
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     return (
+ *       <File path={`${ctx.root}/${node.name}.ts`}>
+ *         <Type node={node} resolver={ctx.resolver} />
+ *       </File>
+ *     )
+ *   },
+ * })
+ * ```
+ */
+declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator<TOptions, TElement>): Generator<TOptions, TElement>;
+//#endregion
+//#region src/defineParser.d.ts
+type PrintOptions = {
+  extname?: FileNode['extname'];
+};
+/**
+ * Converts a resolved {@link FileNode} into the final source string that gets
+ * written to disk. Kubb ships with TypeScript and TSX parsers. Add your own
+ * for new file types (JSON, Markdown, ...).
+ */
+type Parser<TMeta extends object = object, TNode = unknown> = {
+  /**
+   * Display name used in diagnostics and the parser registry.
+   */
+  name: string;
+  /**
+   * File extensions this parser handles. The driver registers the parser for each
+   * extension in this list. A parser with `undefined` here is not registered, so
+   * files of an unclaimed extension fall back to joining their sources verbatim.
+   *
+   * @example
+   * `['.ts', '.js']`
+   */
+  extNames: Array<FileNode['extname']> | undefined;
+  /**
+   * Serialize the file's AST into source code.
+   */
+  parse(file: FileNode<TMeta>, options?: PrintOptions): string;
+  /**
+   * Render compiler AST nodes for this parser's language into source text.
+   * Plugins call this to format the nodes they assemble before handing them
+   * back to the parser as `FileNode.sources`.
+   */
+  print(...nodes: Array<TNode>): string;
+};
+/**
+ * Defines a parser with type-safe `this`. Used to register handlers for new
+ * file extensions or to plug a non-TypeScript output into the build.
+ *
+ * @example
+ * ```ts
+ * import { defineParser } from '@kubb/core'
+ * import { extractStringsFromNodes } from '@kubb/ast'
+ *
+ * export const jsonParser = defineParser({
+ *   name: 'json',
+ *   extNames: ['.json'],
+ *   parse(file) {
+ *     return file.sources
+ *       .map((source) => extractStringsFromNodes(source.nodes ?? []))
+ *       .join('\n')
+ *   },
+ *   print(...nodes) {
+ *     return nodes.map(String).join('\n')
+ *   },
+ * })
+ * ```
+ */
+declare function defineParser<T extends Parser>(parser: T): T;
+//#endregion
+//#region src/createKubb.d.ts
+type CreateKubbOptions = {
+  hooks?: AsyncEventEmitter<KubbHooks>;
+};
+/**
+ * Kubb code-generation instance bound to a single config entry. Resolves the user
+ * config in the constructor, so `config` is available right away, and shares `hooks`,
+ * `storage`, and `driver` across the `setup → build` lifecycle.
+ *
+ * `createKubb` takes a plain config object (the shape `defineConfig` produces),
+ * not a fluent builder.
+ *
+ * Attach event listeners to `.hooks` before calling `setup()` or `build()`.
+ *
+ * @example
+ * ```ts
+ * const kubb = createKubb(userConfig)
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => console.log(plugin.name, duration))
+ * const { files, diagnostics } = await kubb.safeBuild()
+ * ```
+ */
+declare class Kubb$1 {
+  #private;
+  readonly hooks: AsyncEventEmitter<KubbHooks>;
+  readonly config: Config;
+  constructor(userConfig: UserConfig, options?: CreateKubbOptions);
+  get storage(): Storage;
+  get driver(): KubbDriver;
+  /**
+   * Initializes the driver and storage. `build()` calls this automatically.
+   */
+  setup(): Promise<void>;
+  /**
+   * Runs the full pipeline and throws on any plugin error.
+   * Automatically calls `setup()` if needed.
+   */
+  build(): Promise<BuildOutput>;
+  /**
+   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing.
+   * Automatically calls `setup()` if needed. This is the canonical call: it never throws on
+   * plugin errors, so callers stay in control of how failures surface.
+   */
+  safeBuild(): Promise<BuildOutput>;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+/**
+ * Constructs a {@link Kubb} build orchestrator from a user config. Equivalent
+ * to `new Kubb(userConfig, options)` and the canonical public entry point.
+ *
+ * @example
+ * ```ts
+ * import { createKubb } from '@kubb/core'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * const kubb = createKubb({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
+ * })
+ *
+ * await kubb.build()
+ * ```
+ */
+declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions): Kubb$1;
+//#endregion
+//#region src/FileProcessor.d.ts
+/**
+ * Hooks fired by a `FileProcessor`.
+ *
+ * - `start` opens a batch, from `run` or a queue flush.
+ * - `update` fires once per file as it is converted.
+ * - `end` closes a batch.
+ * - `enqueue` fires for every `enqueue` call.
+ * - `drain` fires when `drain()` empties the queue with no in-flight batch left.
+ */
+type FileProcessorHooks = {
+  start: [files: Array<FileNode>];
+  update: [params: {
+    file: FileNode;
+    source?: string;
+    processed: number;
+    total: number;
+    percentage: number;
+  }];
+  end: [files: Array<FileNode>];
+  enqueue: [file: FileNode];
+  drain: [];
+};
+/**
+ * Per-file progress record yielded by `stream` and surfaced through the `update` event.
+ */
+type ParsedFile = {
+  file: FileNode;
+  source: string;
+  processed: number;
+  total: number;
+  percentage: number;
+};
+//#endregion
+//#region src/types.d.ts
+/**
+ * Extracts a type from a registry, falling back to `{}` when the key doesn't exist.
+ * Lets plugins augment `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without changing core.
+ *
+ * @internal
+ */
+type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
+/**
+ * Path to an input file to generate from, absolute or relative to the config file. The adapter
+ * parses it (e.g. an OpenAPI YAML or JSON spec) into the universal AST.
+ */
+type InputPath = {
+  /**
+   * Path to your Swagger/OpenAPI file, absolute or relative to the config file location.
+   *
+   * @example
+   * ```ts
+   * { path: './petstore.yaml' }
+   * { path: '/absolute/path/to/openapi.json' }
+   * ```
+   */
+  path: string;
+};
+/**
+ * Inline spec to generate from, passed directly instead of read from a file. A string
+ * (YAML/JSON) or a parsed object.
+ */
+type InputData = {
+  /**
+   * Swagger/OpenAPI data as a string (YAML/JSON) or a parsed object.
+   *
+   * @example
+   * ```ts
+   * { data: fs.readFileSync('./openapi.yaml', 'utf8') }
+   * { data: { openapi: '3.1.0', info: { ... } } }
+   * ```
+   */
+  data: string | unknown;
+};
+type Input = InputPath | InputData;
+/**
+ * Resolved build configuration for a Kubb run: what to generate from (adapter, input), where to
+ * write it (output), how (plugins), and the runtime pieces (parsers, storage). See
+ * `UserConfig` for the relaxed form with defaults applied.
+ *
+ * @private
+ */
+type Config<TInput = Input> = {
+  /**
+   * Display name for this configuration in CLI output and logs.
+   * Useful when running multiple builds with `defineConfig` arrays.
+   *
+   * @example
+   * ```ts
+   * name: 'api-client'
+   * ```
+   */
+  name?: string;
+  /**
+   * Project root directory, absolute or relative to the config file. Already
+   * resolved on the `Config` instance (see `UserConfig` for the optional
+   * form that defaults to `process.cwd()`).
+   */
+  root: string;
+  /**
+   * Parsers that convert generated files into strings. Each parser handles a
+   * set of file extensions, and a fallback parser handles anything else.
+   *
+   * Already resolved on the `Config` instance (see `UserConfig` for the
+   * optional form that defaults to `[parserTs, parserTsx, parserMd]`).
+   *
+   * @example
+   * ```ts
+   * import { defineConfig } from 'kubb'
+   * import { parserTs, parserTsx } from '@kubb/parser-ts'
+   *
+   * export default defineConfig({
+   *   parsers: [parserTs, parserTsx],
+   * })
+   * ```
+   */
+  parsers: Array<Parser>;
+  /**
+   * Adapter that parses input files into the universal AST representation.
+   * Use `@kubb/adapter-oas` for OpenAPI/Swagger or `@kubb/adapter-asyncapi` for other formats.
+   *
+   * When omitted, Kubb runs in plugin-only mode: `kubb:plugin:setup` fires and files
+   * injected via `injectFile` are written, but no AST walk occurs and generator hooks
+   * (`kubb:generate:schema`, `kubb:generate:operation`) are never emitted.
+   *
+   * @example
+   * ```ts
+   * import { adapterOas } from '@kubb/adapter-oas'
+   * export default defineConfig({
+   *   adapter: adapterOas(),
+   *   input: { path: './petstore.yaml' },
+   * })
+   * ```
+   */
+  adapter?: Adapter;
+  /**
+   * Source file or data to generate code from.
+   * Use `input.path` for a file path or `input.data` for inline data.
+   * Required when an adapter is configured. Omit it when running in plugin-only mode.
+   */
+  input?: TInput;
+  output: {
+    /**
+     * Output directory for generated files, absolute or relative to `root`. Plugins can nest
+     * subdirectories under it by grouping strategy (tag, path).
+     *
+     * @example
+     * ```ts
+     * output: {
+     *   path: './src/gen',  // generates ./src/gen/api.ts, ./src/gen/types.ts, etc.
+     * }
+     * ```
+     */
+    path: string;
+    /**
+     * Remove every file in the output directory before the build, so stale output isn't mixed
+     * with new files. Leave `false` to preserve manual edits in the output directory.
+     *
+     * @example
+     * ```ts
+     * clean: true  // wipes ./src/gen/* before generating
+     * ```
+     */
+    clean?: boolean;
+    /**
+     * Format the generated files after generation. `'auto'` runs the first formatter it finds
+     * (oxfmt, biome, or prettier), a named tool forces that one, and `false` skips formatting.
+     *
+     * @example
+     * ```ts
+     * format: 'auto'        // auto-detect oxfmt, biome, or prettier
+     * format: 'prettier'    // force prettier
+     * format: false         // skip formatting
+     * ```
+     */
+    format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false;
+    /**
+     * Lint the generated files after generation. `'auto'` runs the first linter it finds
+     * (oxlint, biome, or eslint), a named tool forces that one, and `false` skips linting.
+     *
+     * @example
+     * ```ts
+     * lint: 'auto'      // auto-detect oxlint, biome, or eslint
+     * lint: 'eslint'    // force eslint
+     * lint: false       // skip linting
+     * ```
+     */
+    lint?: 'auto' | 'eslint' | 'biome' | 'oxlint' | false;
+    /**
+     * Rewrite import extensions in generated files, e.g. emit `.js` imports from `.ts` sources for
+     * ESM dual packages. Keys are the source extension, values the output, and `''` drops it.
+     *
+     * @default { '.ts': '.ts' }
+     * @example
+     * ```ts
+     * extension: { '.ts': '.js' }      // generates import './api.js' instead of './api.ts'
+     * extension: { '.ts': '', '.tsx': '.jsx' }
+     * ```
+     */
+    extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
+    /**
+     * Banner prepended to every generated file. `'simple'` is the basic Kubb notice, `'full'` adds
+     * source, title, description, and API version, and `false` omits it.
+     *
+     * @default 'simple'
+     * @example
+     * ```ts
+     * defaultBanner: 'simple'   // "This file was autogenerated by Kubb"
+     * defaultBanner: 'full'     // adds source, title, description, API version
+     * defaultBanner: false      // no banner
+     * ```
+     */
+    defaultBanner?: 'simple' | 'full' | false;
+  } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>;
+  /**
+   * Where generated files are persisted. Defaults to `fsStorage()` (disk). Pass `memoryStorage()`
+   * to keep files in RAM, or implement `Storage` for a custom backend such as cloud or a database.
+   *
+   * @default fsStorage()
+   * @example
+   * ```ts
+   * import { memoryStorage } from '@kubb/core'
+   *
+   * // Keep generated files in memory (useful for testing, CI pipelines)
+   * storage: memoryStorage()
+   *
+   * // Use custom S3 storage
+   * storage: myS3Storage()
+   * ```
+   *
+   * @see {@link Storage} interface for implementing custom backends.
+   */
+  storage: Storage;
+  /**
+   * Plugins that run during the build to generate code and transform the AST. Each one processes
+   * the adapter's AST and can emit files for a different target (TypeScript, Zod, Faker). A plugin
+   * that depends on another throws when that plugin isn't registered.
+   *
+   * @example
+   * ```ts
+   * import { pluginTs } from '@kubb/plugin-ts'
+   * import { pluginZod } from '@kubb/plugin-zod'
+   *
+   * plugins: [
+   *   pluginTs({ output: { path: './src/gen' } }),
+   *   pluginZod({ output: { path: './src/gen' } }),
+   * ]
+   * ```
+   */
+  plugins: Array<Plugin>;
+  /**
+   * Lifecycle hooks that run external tools (prettier, eslint, a custom script) on build events.
+   *
+   * Currently supports the `done` hook, which fires after all plugins complete.
+   *
+   * @example
+   * ```ts
+   * hooks: {
+   *   done: 'prettier --write "./src/gen"',      // auto-format generated files
+   *   // or multiple commands:
+   *   done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+   * }
+   * ```
+   */
+  hooks?: {
+    /**
+     * Command(s) to run after all plugins finish generating, for post-processing the output.
+     *
+     * Pass a single command string, or an array to run them in sequence.
+     * Commands run relative to the `root` directory.
+     *
+     * @example
+     * ```ts
+     * done: 'prettier --write "./src/gen"'
+     * done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+     * ```
+     */
+    done?: string | Array<string>;
+  };
+  /**
+   * The reporters available to the run, registered as instances. The host
+   * (the CLI via `--reporter`) selects which ones to trigger by `name` with {@link selectReporters}.
+   * `defineConfig` from the `kubb` package registers the built-in `cli`, `json`, and `file`
+   * reporters by default.
+   *
+   * - `cli` writes the end-of-run summary to the terminal.
+   * - `json` writes a machine-readable report to stdout, for CI.
+   * - `file` writes a debug log to `.kubb/<name>-<timestamp>.log`.
+   *
+   * @example
+   * ```ts
+   * import { cliReporter, jsonReporter } from '@kubb/core'
+   *
+   * reporters: [cliReporter, jsonReporter, myReporter]
+   * ```
+   */
+  reporters: Array<Reporter>;
+};
+/**
+ * Partial `Config` for user-facing entry points with sensible defaults.
+ *
+ * `UserConfig` is what you pass to `defineConfig()`. It has optional `root`, `plugins`, `parsers`, and `adapter`
+ * fields (which fall back to sensible defaults). All other Config options are available, including `output`, `input`,
+ * `storage`, and `hooks`.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   input: { path: './petstore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [pluginTs(), pluginZod()],
+ * })
+ * ```
+ */
+type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters'> & {
+  /**
+   * Project root directory, absolute or relative to the config file location.
+   * @default process.cwd()
+   */
+  root?: string;
+  /**
+   * Custom parsers that convert generated AST nodes to strings (TypeScript, JSON, markdown, etc.).
+   * @default [parserTs, parserTsx, parserMd]  // applied by `defineConfig` from the `kubb` package
+   */
+  parsers?: Array<Parser>;
+  /**
+   * Adapter that parses your API specification into Kubb's universal AST.
+   * When omitted, Kubb runs in plugin-only mode.
+   */
+  adapter?: Adapter;
+  /**
+   * Plugins that execute during the build to generate code and transform the AST.
+   * @default []
+   */
+  plugins?: Array<Plugin>;
+  /**
+   * Storage backend that controls where and how generated files are persisted.
+   * @default fsStorage()
+   */
+  storage?: Storage;
+  /**
+   * Reporters available to the run. `defineConfig` registers the built-in `cli`, `json`, and
+   * `file` reporters when omitted.
+   * @default [cliReporter, jsonReporter, fileReporter]  // applied by `defineConfig` from the `kubb` package
+   */
+  reporters?: Array<Reporter>;
+};
+declare global {
+  namespace Kubb {
+    /**
+     * Registry that maps plugin names to their `PluginFactoryOptions`.
+     * Augment this interface in each plugin's `types.ts` to enable automatic
+     * typing for `getPlugin` and `requirePlugin`.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-ts/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginRegistry {
+     *       'plugin-ts': PluginTs
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginRegistry {}
+    /**
+     * Extension point for root `Config['output']` options.
+     * Augment the `output` key in plugin packages to add extra fields
+     * to the global output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-barrel/src/plugin.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface ConfigOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').BarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface ConfigOptionsRegistry {}
+    /**
+     * Extension point for per-plugin `Output` options.
+     * Augment the `output` key in plugin packages to add extra fields
+     * to the per-plugin output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-barrel/src/plugin.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').PluginBarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginOptionsRegistry {}
+  }
+}
+/**
+ * Lifecycle events emitted during Kubb code generation.
+ * Attach listeners before calling `setup()` or `build()` to observe and react to build progress.
+ *
+ * @example
+ * ```ts
+ * kubb.hooks.on('kubb:lifecycle:start', () => {
+ *   console.log('Starting Kubb generation')
+ * })
+ *
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
+ *   console.log(`${plugin.name} completed in ${duration}ms`)
+ * })
+ * ```
+ */
+interface KubbHooks {
+  'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext];
+  'kubb:lifecycle:end': [];
+  'kubb:generation:start': [ctx: KubbGenerationStartContext];
+  'kubb:generation:end': [ctx: KubbGenerationEndContext];
+  'kubb:format:start': [];
+  'kubb:format:end': [];
+  'kubb:lint:start': [];
+  'kubb:lint:end': [];
+  'kubb:hooks:start': [];
+  'kubb:hooks:end': [];
+  'kubb:hook:start': [ctx: KubbHookStartContext];
+  'kubb:hook:line': [ctx: KubbHookLineContext];
+  'kubb:hook:end': [ctx: KubbHookEndContext];
+  'kubb:info': [ctx: KubbInfoContext];
+  'kubb:error': [ctx: KubbErrorContext];
+  'kubb:success': [ctx: KubbSuccessContext];
+  'kubb:warn': [ctx: KubbWarnContext];
+  'kubb:diagnostic': [ctx: KubbDiagnosticContext];
+  'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext];
+  'kubb:files:processing:update': [ctx: KubbFilesProcessingUpdateContext];
+  'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext];
+  'kubb:plugin:start': [ctx: KubbPluginStartContext];
+  'kubb:plugin:end': [ctx: KubbPluginEndContext];
+  'kubb:plugin:setup': [ctx: KubbPluginSetupContext];
+  'kubb:build:start': [ctx: KubbBuildStartContext];
+  'kubb:plugins:end': [ctx: KubbPluginsEndContext];
+  'kubb:build:end': [ctx: KubbBuildEndContext];
+  'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext];
+  'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext];
+  'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext];
+}
+type KubbBuildStartContext = {
+  /**
+   * Resolved configuration for this build.
+   */
+  config: Config;
+  /**
+   * Adapter that parsed the input into the universal AST.
+   */
+  adapter: Adapter;
+  /**
+   * Metadata about the parsed document (title, version, base URL, circular schema names, enum names).
+   * To observe individual schemas and operations use the `kubb:generate:schema` / `kubb:generate:operation` hooks.
+   */
+  meta: InputMeta | undefined;
+  /**
+   * Looks up a registered plugin by name, typed by the plugin registry.
+   */
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  getPlugin(name: string): Plugin | undefined;
+  /**
+   * Snapshot of all files accumulated so far.
+   */
+  readonly files: ReadonlyArray<FileNode>;
+  /**
+   * Adds or merges one or more files into the file manager.
+   */
+  upsertFile: (...files: Array<FileNode>) => void;
+};
+type KubbPluginsEndContext = {
+  /**
+   * Resolved configuration for this build.
+   */
+  config: Config;
+  /**
+   * Snapshot of all files accumulated across all plugins.
+   */
+  readonly files: ReadonlyArray<FileNode>;
+  /**
+   * Adds or merges one or more files into the file manager.
+   */
+  upsertFile: (...files: Array<FileNode>) => void;
+};
+type KubbBuildEndContext = {
+  /**
+   * All files generated during this build.
+   */
+  files: Array<FileNode>;
+  /**
+   * Resolved configuration for this build.
+   */
+  config: Config;
+  /**
+   * Absolute path to the output directory.
+   */
+  outputDir: string;
+};
+type KubbLifecycleStartContext = {
+  /**
+   * Current Kubb version string.
+   */
+  version: string;
+};
+type KubbGenerationStartContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
+  config: Config;
+};
+type KubbGenerationEndContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
+  config: Config;
+  /**
+   * Read-only view of the files written during this build.
+   * Reads go directly to `config.storage`, nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * `const code = await storage.getItem('/src/gen/pet.ts')`
+   *
+   * @example Walk every generated file
+   * ```ts
+   * for (const path of await storage.getKeys()) {
+   *   const code = await storage.getItem(path)
+   * }
+   * ```
+   */
+  storage: Storage;
+  /**
+   * Diagnostics collected during the build: error/warning/info problems plus a
+   * `performance` diagnostic per plugin. The end-of-run summary derives its failure counts
+   * and per-plugin timings from these. Set by the CLI runner, omitted by other callers.
+   */
+  diagnostics?: Array<Diagnostic>;
+  /**
+   * `'success'` when all plugins completed without errors, `'failed'` otherwise.
+   */
+  status?: 'success' | 'failed';
+  /**
+   * High-resolution start time from `process.hrtime()`, used to compute the elapsed time.
+   */
+  hrStart?: [number, number];
+  /**
+   * Total number of files created during this run.
+   */
+  filesCreated?: number;
+};
+type KubbInfoContext = {
+  /**
+   * Human-readable info message.
+   */
+  message: string;
+  /**
+   * Optional supplementary detail.
+   */
+  info?: string;
+};
+type KubbErrorContext = {
+  /**
+   * The caught error.
+   */
+  error: Error;
+  /**
+   * Optional structured metadata for additional context.
+   */
+  meta?: Record<string, unknown>;
+};
+type KubbSuccessContext = {
+  /**
+   * Human-readable success message.
+   */
+  message: string;
+  /**
+   * Optional supplementary detail.
+   */
+  info?: string;
+};
+type KubbWarnContext = {
+  /**
+   * Human-readable warning message.
+   */
+  message: string;
+  /**
+   * Optional supplementary detail.
+   */
+  info?: string;
+};
+type KubbDiagnosticContext = {
+  /**
+   * The structured diagnostic to render: a build problem or a version-update notice.
+   */
+  diagnostic: ProblemDiagnostic | UpdateDiagnostic;
+};
+type KubbFilesProcessingStartContext = {
+  /**
+   * Files about to be serialized and written.
+   */
+  files: Array<FileNode>;
+};
+type KubbFileProcessingUpdate = {
+  /**
+   * Number of files processed so far in this batch.
+   */
+  processed: number;
+  /**
+   * Total number of files in this batch.
+   */
+  total: number;
+  /**
+   * Completion percentage, `0` to `100`.
+   */
+  percentage: number;
+  /**
+   * Serialized file content, or `undefined` when the file produced no output.
+   */
+  source?: string;
+  /**
+   * The file that was just processed.
+   */
+  file: FileNode;
+  /**
+   * Resolved configuration for this build.
+   */
+  config: Config;
+};
+type KubbFilesProcessingUpdateContext = {
+  /**
+   * All files processed in this flush chunk.
+   */
+  files: Array<KubbFileProcessingUpdate>;
+};
+type KubbFilesProcessingEndContext = {
+  /**
+   * All files that were serialized in this batch.
+   */
+  files: Array<FileNode>;
+};
+type KubbHookStartContext = {
+  /**
+   * Optional identifier for correlating start/end events.
+   */
+  id?: string;
+  /**
+   * The shell command that is about to run.
+   */
+  command: string;
+  /**
+   * Parsed argument list, when available.
+   */
+  args?: ReadonlyArray<string>;
+};
+/**
+ * Emitted for each line streamed from a hook's stdout while it runs.
+ * A logger correlates the line to its active UI element via `id`.
+ */
+type KubbHookLineContext = {
+  /**
+   * Identifier matching the corresponding `kubb:hook:start` event.
+   */
+  id: string;
+  /**
+   * A single streamed stdout line, without its trailing newline.
+   */
+  line: string;
+};
+type KubbHookEndContext = {
+  /**
+   * Optional identifier matching the corresponding `kubb:hook:start` event.
+   */
+  id?: string;
+  /**
+   * The shell command that ran.
+   */
+  command: string;
+  /**
+   * Parsed argument list, when available.
+   */
+  args?: ReadonlyArray<string>;
+  /**
+   * `true` when the command exited with code `0`.
+   */
+  success: boolean;
+  /**
+   * Error thrown by the command, or `null` on success.
+   */
+  error: Error | null;
+  /**
+   * Captured stdout from the process, populated when it exits non-zero.
+   */
+  stdout?: string;
+  /**
+   * Captured stderr from the process, populated when it exits non-zero.
+   */
+  stderr?: string;
+};
+/**
+ * CLI options derived from command-line flags.
+ */
+type CLIOptions = {
+  /**
+   * Path to the Kubb config file.
+   */
+  config?: string;
+  /**
+   * OpenAPI input path passed as the positional argument to `kubb generate`.
+   * Overrides `config.input.path` when set.
+   */
+  input?: string;
+  /**
+   * Re-run generation whenever input files change.
+   */
+  watch?: boolean;
+  /**
+   * Controls how much output the CLI prints.
+   *
+   * @default 'info'
+   */
+  logLevel?: 'silent' | 'info' | 'verbose';
+  /**
+   * Reporters selected on the CLI via `--reporter`, overriding `config.reporters`.
+   */
+  reporters?: Array<ReporterName>;
+};
+/**
+ * All accepted forms of a Kubb configuration.
+ * Accepts `Config`/`Config[]`/promise or a factory (optionally receiving `TCliOptions`).
+ */
+type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Array<Config>> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Array<Config>>);
+/**
+ * Full output produced by a successful or failed build.
+ */
+type BuildOutput = {
+  /**
+   * Structured diagnostics collected during the build: error/warning/info problems
+   * (each with a code, severity, and where known a JSON-pointer location) plus a
+   * `performance` diagnostic per plugin. Includes a top-level diagnostic when the build
+   * threw before completing. Use {@link Diagnostics.hasError} to test for failure.
+   */
+  diagnostics: Array<Diagnostic>;
+  /**
+   * All files generated during this build.
+   */
+  files: Array<FileNode>;
+  /**
+   * The plugin driver that orchestrated this build.
+   */
+  driver: KubbDriver;
+  /**
+   * Read-only view of every file written during this build.
+   * Reads go straight to `config.storage`, nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * `const code = await buildOutput.storage.getItem('/src/gen/pet.ts')`
+   *
+   * @example List all generated file paths
+   * `const paths = await buildOutput.storage.getKeys()`
+   */
+  storage: Storage;
+};
+//#endregion
+//#region src/diagnostics.d.ts
+/**
+ * How serious a diagnostic is. `error` fails the build, `warning` and `info`
+ * are reported but do not.
+ */
+type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * A human-readable explanation of a diagnostic code: a short title, what triggers it, and how
+ * to resolve it. This is the source of truth the kubb.dev `/diagnostics/<slug>` pages mirror, so
+ * every code stays documented in one place. Adding a code without documenting it fails the build.
+ */
+type DiagnosticDoc = {
+  /**
+   * Short title shown as the docs heading.
+   */
+  title: string;
+  /**
+   * What triggers the diagnostic.
+   */
+  cause: string;
+  /**
+   * The action that resolves it.
+   */
+  fix: string;
+};
+/**
+ * Points a diagnostic back into the source document. Inputs are parsed into an
+ * object model with no line/column, so locations carry a JSON pointer the adapter
+ * builds (the OAS adapter emits `#/components/schemas/Pet`). A `config` diagnostic
+ * points at the Kubb config itself and so has no pointer.
+ */
+type DiagnosticLocation = {
+  kind: 'schema';
+  /**
+   * RFC 6901 JSON pointer into the source document.
+   */
+  pointer: string;
+  /**
+   * The original reference when the diagnostic stems from an unresolved one.
+   */
+  ref?: string;
+} | {
+  kind: 'operation' | 'document';
+  /**
+   * RFC 6901 JSON pointer into the source document.
+   */
+  pointer: string;
+} | {
+  kind: 'config';
+};
+/**
+ * What a diagnostic carries.
+ * - `problem` is a build issue shown to the user, and the only kind rendered as a problem.
+ * - `performance` records a plugin's elapsed time.
+ * - `update` is a version notice.
+ */
+type DiagnosticKind = 'problem' | 'performance' | 'update';
+/**
+ * Codes that describe a build problem: every {@link DiagnosticCode} except the
+ * `performance` and `updateAvailable` codes, which ride on their own variants.
+ */
+type ProblemCode = Exclude<DiagnosticCode, typeof diagnosticCode.performance | typeof diagnosticCode.updateAvailable>;
+/**
+ * A build problem collected during a run, gathered into the result instead of
+ * aborting on the first failure.
+ */
+type ProblemDiagnostic = {
+  /**
+   * @default 'problem'
+   */
+  kind?: 'problem';
+  /**
+   * Stable identifier for the problem, from the {@link diagnosticCode} catalog.
+   */
+  code: ProblemCode;
+  severity: DiagnosticSeverity;
+  message: string;
+  location?: DiagnosticLocation;
+  /**
+   * A suggested fix, phrased as an action the user can take.
+   */
+  help?: string;
+  /**
+   * Name of the plugin or subsystem that produced the diagnostic.
+   */
+  plugin?: string;
+  /**
+   * The underlying error, when the diagnostic wraps a thrown one.
+   */
+  cause?: Error;
+};
+/**
+ * A per-plugin performance record, built with {@link Diagnostics.performance}. The `performance`
+ * kind keeps it out of the problem list. It feeds the per-plugin timing bars, and reporters sum
+ * these into the run total.
+ */
+type PerformanceDiagnostic = {
+  kind: 'performance';
+  code: typeof diagnosticCode.performance;
+  severity: 'info';
+  message: string;
+  /**
+   * The plugin this measurement belongs to.
+   */
+  plugin: string;
+  /**
+   * Elapsed milliseconds.
+   */
+  duration: number;
+};
+/**
+ * A notice that a newer Kubb version is available on npm, built with {@link Diagnostics.update}.
+ * It renders like any info diagnostic.
+ */
+type UpdateDiagnostic = {
+  kind: 'update';
+  code: typeof diagnosticCode.updateAvailable;
+  severity: 'info';
+  message: string;
+  /**
+   * The running Kubb version.
+   */
+  currentVersion: string;
+  /**
+   * The newest version published on npm.
+   */
+  latestVersion: string;
+};
+/**
+ * A structured record collected during a build, discriminated on `kind`: a
+ * {@link ProblemDiagnostic} for an issue, a {@link PerformanceDiagnostic} for a per-plugin
+ * timing, or an {@link UpdateDiagnostic} for a version notice.
+ */
+type Diagnostic = ProblemDiagnostic | PerformanceDiagnostic | UpdateDiagnostic;
+/**
+ * Maps each {@link DiagnosticCode} to the variant it selects, for {@link narrow}.
+ * Every {@link ProblemCode} selects a {@link ProblemDiagnostic}, and the two bookkeeping codes
+ * select their own variant.
+ */
+type DiagnosticByCode = Record<ProblemCode, ProblemDiagnostic> & Record<typeof diagnosticCode.performance, PerformanceDiagnostic> & Record<typeof diagnosticCode.updateAvailable, UpdateDiagnostic>;
+/**
+ * Narrows a {@link Diagnostic} to the variant for `code`, or `null` when it does not match.
+ *
+ * @example
+ * ```ts
+ * const update = narrow(diagnostic, diagnosticCode.updateAvailable)
+ * if (update) {
+ *   console.log(update.latestVersion)
+ * }
+ * ```
+ */
+declare function narrow<C extends DiagnosticCode>(diagnostic: Diagnostic, code: C): DiagnosticByCode[C] | null;
+/**
+ * A {@link Diagnostic} reduced to its JSON-safe fields plus a `docsUrl`, for
+ * machine-readable output (the `--reporter json` report, the MCP tools). Drops the
+ * non-serializable `cause` and the `kind`/`duration` bookkeeping.
+ */
+type SerializedDiagnostic = {
+  code: DiagnosticCode;
+  severity: DiagnosticSeverity;
+  message: string;
+  location?: DiagnosticLocation;
+  help?: string;
+  plugin?: string;
+  /**
+   * The kubb.dev docs link for the code, omitted for the unknown fallback.
+   */
+  docsUrl?: string;
+};
+/**
+ * Static helpers for working with {@link Diagnostic}s, plus the run-scoped sink
+ * that lets deep code report a diagnostic without threading a callback.
+ *
+ * The sink lives in a single `AsyncLocalStorage` in the `@kubb/core` bundle.
+ * `Diagnostics.scope` activates it for a run, so anything inside that run (the
+ * adapter parse, a lazily consumed stream, a generator) reports through
+ * `Diagnostics.report` and lands in the same run.
+ */
+declare class Diagnostics {
+  #private;
+  /**
+   * The diagnostic code catalog, exposed as `Diagnostics.code` (e.g. `Diagnostics.code.refNotFound`).
+   */
+  static code: {
+    readonly unknown: "KUBB_UNKNOWN";
+    readonly inputNotFound: "KUBB_INPUT_NOT_FOUND";
+    readonly inputRequired: "KUBB_INPUT_REQUIRED";
+    readonly refNotFound: "KUBB_REF_NOT_FOUND";
+    readonly invalidServerVariable: "KUBB_INVALID_SERVER_VARIABLE";
+    readonly pluginNotFound: "KUBB_PLUGIN_NOT_FOUND";
+    readonly pluginFailed: "KUBB_PLUGIN_FAILED";
+    readonly pluginWarning: "KUBB_PLUGIN_WARNING";
+    readonly pluginInfo: "KUBB_PLUGIN_INFO";
+    readonly unsupportedFormat: "KUBB_UNSUPPORTED_FORMAT";
+    readonly deprecated: "KUBB_DEPRECATED";
+    readonly adapterRequired: "KUBB_ADAPTER_REQUIRED";
+    readonly pathTraversal: "KUBB_PATH_TRAVERSAL";
+    readonly invalidPluginOptions: "KUBB_INVALID_PLUGIN_OPTIONS";
+    readonly hookFailed: "KUBB_HOOK_FAILED";
+    readonly formatFailed: "KUBB_FORMAT_FAILED";
+    readonly lintFailed: "KUBB_LINT_FAILED";
+    readonly performance: "KUBB_PERFORMANCE";
+    readonly updateAvailable: "KUBB_UPDATE_AVAILABLE";
+  };
+  /**
+   * Type guard for a build {@link ProblemDiagnostic}.
+   */
+  static isProblem: (diagnostic: Diagnostic) => diagnostic is ProblemDiagnostic;
+  /**
+   * Type guard for a version-update {@link UpdateDiagnostic}.
+   */
+  static isUpdate: (diagnostic: Diagnostic) => diagnostic is UpdateDiagnostic;
+  /**
+   * Type guard for a per-plugin {@link PerformanceDiagnostic}.
+   */
+  static isPerformance: (diagnostic: Diagnostic) => diagnostic is PerformanceDiagnostic;
+  /**
+   * Narrows a {@link Diagnostic} to the variant for `code`, or `null` when it does not match.
+   */
+  static narrow: typeof narrow;
+  /**
+   * An `Error` that carries a {@link Diagnostic}, so structured problems can flow
+   * through the existing throw/catch paths while keeping their code and location.
+   *
+   * @example
+   * ```ts
+   * throw new Diagnostics.Error({ code: diagnosticCode.refNotFound, severity: 'error', message: `Could not find ${ref}`, location: { kind: 'schema', pointer: ref, ref } })
+   * ```
+   */
+  static Error: {
+    new (diagnostic: ProblemDiagnostic): {
+      diagnostic: ProblemDiagnostic;
+      name: string;
+      message: string;
+      stack?: string;
+      cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    isError(value: unknown): value is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+  };
+  /**
+   * Structural check for a {@link Diagnostics.Error}, including one thrown from a duplicated
+   * `@kubb/core` copy where `instanceof` fails. Matches on the `name` and a `diagnostic`
+   * that carries a `code`.
+   */
+  static isError(error: unknown): error is InstanceType<typeof Diagnostics.Error>;
+  /**
+   * Runs `fn` with `sink` as the active diagnostic sink for the whole async
+   * subtree, so {@link Diagnostics.report} reaches it from anywhere inside.
+   */
+  static scope<T>(sink: (diagnostic: Diagnostic) => void, fn: () => T): T;
+  /**
+   * Collects a diagnostic into the active build via the run-scoped sink, without throwing.
+   * Returns `true` when a run consumed it, `false` when called outside a {@link Diagnostics.scope}
+   * (so callers can fall back to throwing). Use a `warning`/`info` severity for non-fatal issues.
+   * For rendering a diagnostic live on the hook bus, use {@link Diagnostics.emit} instead.
+   */
+  static report(diagnostic: Diagnostic): boolean;
+  /**
+   * Emits a diagnostic on the run's `kubb:diagnostic` event so the loggers render it live.
+   * Use it instead of calling `hooks.emit('kubb:diagnostic', ...)` directly. To collect a
+   * diagnostic into the build result from deep in a run, use {@link Diagnostics.report} instead.
+   */
+  static emit(hooks: AsyncEventEmitter<KubbHooks>, diagnostic: ProblemDiagnostic | UpdateDiagnostic): Promise<void>;
+  /**
+   * Coerces any thrown value into a {@link ProblemDiagnostic}. A {@link Diagnostics.Error}
+   * keeps its structured data, and anything else becomes a `KUBB_UNKNOWN` error.
+   */
+  static from(error: unknown): ProblemDiagnostic;
+  /**
+   * Builds a per-plugin performance record. Reporters sum these into the run total.
+   */
+  static performance({
+    plugin,
+    duration
+  }: {
+    plugin: string;
+    duration: number;
+  }): PerformanceDiagnostic;
+  /**
+   * Builds the version-update notice shown when a newer Kubb is published on npm.
+   */
+  static update({
+    currentVersion,
+    latestVersion
+  }: {
+    currentVersion: string;
+    latestVersion: string;
+  }): UpdateDiagnostic;
+  /**
+   * True when any diagnostic is an error, the severity that fails a build. Non-error
+   * diagnostics are ignored.
+   */
+  static hasError(diagnostics: ReadonlyArray<Diagnostic>): boolean;
+  /**
+   * Names of the plugins that failed, deduped, derived from the error diagnostics
+   * that carry a `plugin`.
+   */
+  static failedPlugins(diagnostics: ReadonlyArray<Diagnostic>): Array<string>;
+  /**
+   * Counts `problem` diagnostics by severity for the run summary. `performance` and
+   * `update` diagnostics are ignored.
+   */
+  static count(diagnostics: ReadonlyArray<Diagnostic>): {
+    errors: number;
+    warnings: number;
+    infos: number;
+  };
+  /**
+   * Drops duplicate `problem` diagnostics that share a code, location pointer, and
+   * plugin, so the same issue reported across several passes is shown once. Non-problem
+   * diagnostics are always kept.
+   */
+  static dedupe(diagnostics: ReadonlyArray<Diagnostic>): Array<Diagnostic>;
+  /**
+   * Builds the kubb.dev docs URL for a diagnostic code, e.g.
+   * `KUBB_REF_NOT_FOUND` → `https://kubb.dev/docs/5.x/reference/diagnostics/kubb-ref-not-found`.
+   */
+  static docsUrl(code: string): string;
+  /**
+   * The catalog entry for a code: its title, cause, and fix. Mirrors the kubb.dev
+   * `/diagnostics/<slug>` page.
+   */
+  static explain(code: DiagnosticCode): DiagnosticDoc;
+  /**
+   * Reduces a diagnostic to its JSON-safe fields plus a `docsUrl`, for machine-readable
+   * consumers. The `cause`, `kind`, and `duration` are dropped, and absent optional
+   * fields are omitted rather than set to `undefined`.
+   */
+  static serialize(diagnostic: Diagnostic): SerializedDiagnostic;
+  /**
+   * Renders a {@link Diagnostic} for terminal output as its parts: the `headline`
+   * (`[CODE] plugin: message`, with the code in the severity color) and the indented `details`
+   * rows (`at:` pointer, `fix:` help, `see:` docs link).
+   *
+   * Hosts compose these to fit their gutter: a clack logger passes `[headline, ...details]` as the
+   * message with no gutter symbol, while plain text outputs use {@link Diagnostics.formatLines}.
+   */
+  static format(diagnostic: Diagnostic): {
+    headline: string;
+    details: Array<string>;
+  };
+  /**
+   * The self-contained block form of {@link Diagnostics.format}: the `headline` followed by the
+   * indented detail rows. Used where there is no gutter (plain and file output).
+   */
+  static formatLines(diagnostic: Diagnostic): Array<string>;
+}
+//#endregion
+export { KubbPluginSetupContext as $, KubbHookStartContext as A, Adapter as At, ParsedFile as B, KubbFilesProcessingEndContext as C, GenerationResult as Ct, KubbGenerationStartContext as D, UserReporter as Dt, KubbGenerationEndContext as E, ReporterName as Et, KubbSuccessContext as F, Generator as G, createKubb as H, KubbWarnContext as I, KubbDriver as J, GeneratorContext as K, PossibleConfig as L, KubbInfoContext as M, AdapterSource as Mt, KubbLifecycleStartContext as N, createAdapter as Nt, KubbHookEndContext as O, createReporter as Ot, KubbPluginsEndContext as P, AsyncEventEmitter as Pt, KubbPluginEndContext as Q, UserConfig as R, KubbFileProcessingUpdate as S, createStorage as St, KubbFilesProcessingUpdateContext as T, ReporterContext as Tt, Parser as U, Kubb$1 as V, defineParser as W, Group as X, Exclude$1 as Y, Include as Z, InputPath as _, defineResolver as _t, DiagnosticLocation as a, Override as at, KubbDiagnosticContext as b, createRenderer as bt, PerformanceDiagnostic as c, definePlugin as ct, SerializedDiagnostic as d, ResolveBannerFile as dt, KubbPluginStartContext as et, UpdateDiagnostic as f, ResolveOptionsContext as ft, InputData as g, ResolverPathParams as gt, Config as h, ResolverFileParams as ht, DiagnosticKind as i, OutputOptions as it, KubbHooks as j, AdapterFactoryOptions as jt, KubbHookLineContext as k, logLevel as kt, ProblemCode as l, BannerMeta as lt, CLIOptions as m, ResolverContext as mt, DiagnosticByCode as n, Output as nt, DiagnosticSeverity as o, Plugin as ot, BuildOutput as p, Resolver as pt, defineGenerator as q, DiagnosticDoc as r, OutputMode as rt, Diagnostics as s, PluginFactoryOptions as st, Diagnostic as t, NormalizedPlugin as tt, ProblemDiagnostic as u, ResolveBannerContext as ut, KubbBuildEndContext as v, Renderer as vt, KubbFilesProcessingStartContext as w, Reporter as wt, KubbErrorContext as x, Storage as xt, KubbBuildStartContext as y, RendererFactory as yt, FileProcessorHooks as z };
+//# sourceMappingURL=diagnostics-DcFh-77r.d.ts.map