@kubb/core 5.0.0-beta.35 → 5.0.0-beta.37

package/dist/{createKubb-BKpcUB6g.d.ts → diagnostics-B0ONXReg.d.ts}

@@ -71,6 +71,20 @@ declare class AsyncEventEmitter<TEvents extends { [K in keyof TEvents]: unknown[
    * ```
    */
   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;
+  /**
+   * Returns the current per-event listener ceiling.
+   */
+  getMaxListeners(): number;
   /**
    * Removes all listeners from every event channel.
    *
@@ -110,8 +124,98 @@ declare const logLevel: {
   readonly warn: 1;
   readonly info: 3;
   readonly verbose: 4;
-  readonly debug: 5;
 };
+/**
+ * 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";
+  /**
+   * The `devtools` config is set to something other than an object.
+   */
+  readonly devtoolsInvalid: "KUBB_DEVTOOLS_INVALID";
+  /**
+   * 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 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/createAdapter.d.ts
 /**
@@ -243,6 +347,88 @@ type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) =
  */
 declare function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T>;
 //#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 to S3, a database, or any other target.
+ */
+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 called after the build completes. Use 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, reach for this when you need to write generated files
+ * elsewhere (cloud storage, a database, a remote API).
+ *
+ * @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.
@@ -255,7 +441,7 @@ declare function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryO
 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.
+   * Called once per render cycle. Must resolve before {@link files} is read.
    */
   render(element: TElement): Promise<void>;
   /**
@@ -294,7 +480,7 @@ type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
  * (JSX, a template string, a tree of any shape) into `FileNode`s that get
  * written to disk.
  *
- * Use this to support output formats beyond JSX — for instance, a Handlebars
+ * Use this to support output formats beyond JSX, for instance, a Handlebars
  * renderer, a string-template renderer, or a renderer that writes binary
  * files. Plugins and generators pick the renderer to use via the `renderer`
  * field on `defineGenerator`.
@@ -327,96 +513,89 @@ type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
  */
 declare function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement>;
 //#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 to S3, a database, or any other target.
- */
-type Storage = {
-  /**
-   * Identifier used in logs and diagnostics (`'fs'`, `'memory'`, `'s3'`).
-   */
-  readonly name: string;
+//#region src/devtools.d.ts
+type DevtoolsOptions = {
   /**
-   * Returns `true` when an entry for `key` exists.
+   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
+   * @default false
    */
-  hasItem(key: string): Promise<boolean>;
+  ast?: boolean;
+};
+//#endregion
+//#region src/createReporter.d.ts
+/**
+ * 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;
   /**
-   * Reads the stored string. Returns `null` when the key is missing.
+   * Diagnostics collected while generating this config.
    */
-  getItem(key: string): Promise<string | null>;
+  diagnostics: Array<Diagnostic>;
   /**
-   * Stores `value` under `key`, creating any required structure (directories,
-   * buckets, ...).
+   * Number of files written for this config.
    */
-  setItem(key: string, value: string): Promise<void>;
+  filesCreated: number;
+  status: 'success' | 'failed';
   /**
-   * Deletes the entry for `key`. No-op when the key does not exist.
+   * `process.hrtime()` snapshot taken when this config started generating.
    */
-  removeItem(key: string): Promise<void>;
+  hrStart: [number, number];
+};
+/**
+ * Render context passed alongside the {@link GenerationResult}, carrying knobs a reporter needs
+ * but that are not part of the run data (e.g. verbosity).
+ */
+type ReporterContext = {
   /**
-   * Returns every key. Pass `base` to filter to keys starting with that prefix.
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
    */
-  getKeys(base?: string): Promise<Array<string>>;
+  logLevel: (typeof logLevel)[keyof typeof logLevel];
+};
+/**
+ * Reporter contract. Unlike a Logger (the live TUI view), a reporter never sees the event
+ * emitter. `report` is called once per config with its {@link GenerationResult} and produces
+ * output (a terminal summary, a JSON report, a log file).
+ */
+type Reporter = {
   /**
-   * Removes every entry. Pass `base` to scope the wipe to a key prefix.
+   * Display name, matching a {@link ReporterName} for the built-ins.
    */
-  clear(base?: string): Promise<void>;
+  name: string;
   /**
-   * Optional teardown hook called after the build completes. Use to flush
-   * buffers, close connections, or release file locks.
+   * Called once per config with that config's result and the render context.
    */
-  dispose?(): Promise<void>;
+  report: (result: GenerationResult, context: ReporterContext) => void | Promise<void>;
 };
+type UserReporter = Reporter;
 /**
- * Defines a custom storage backend. The builder receives user options and
- * returns a `Storage` implementation. Kubb ships with filesystem and
- * in-memory storages — reach for this when you need to write generated files
- * elsewhere (cloud storage, a database, a remote API).
+ * Defines a reporter. Returns the reporter unchanged at runtime. It exists for type inference and
+ * to mark the value as a reporter, mirroring {@link defineLogger}. Wiring the reporter onto the
+ * run's events is the host's job, so the reporter only ever deals with a {@link GenerationResult}.
  *
- * @example In-memory storage (the built-in implementation)
+ * @example
  * ```ts
- * import { createStorage } from '@kubb/core'
- *
- * export const memoryStorage = createStorage(() => {
- *   const store = new Map<string, string>()
+ * import { createReporter, Diagnostics } from '@kubb/core'
  *
- *   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()
- *     },
- *   }
+ * export const jsonReporter = createReporter({
+ *   name: 'json',
+ *   report(result) {
+ *     const status = Diagnostics.hasError(result.diagnostics) ? 'failed' : 'success'
+ *     process.stdout.write(`${JSON.stringify({ status, diagnostics: result.diagnostics }, null, 2)}\n`)
+ *   },
  * })
  * ```
  */
-declare function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage;
-//#endregion
-//#region src/devtools.d.ts
-type DevtoolsOptions = {
-  /**
-   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
-   * @default false
-   */
-  ast?: boolean;
-};
+declare function createReporter(reporter: UserReporter): Reporter;
 //#endregion
 //#region src/defineParser.d.ts
 type PrintOptions = {
@@ -424,7 +603,7 @@ type PrintOptions = {
 };
 /**
  * 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
+ * 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> = {
@@ -476,11 +655,16 @@ type Parser<TMeta extends object = object, TNode = unknown> = {
 declare function defineParser<T extends Parser>(parser: T): T;
 //#endregion
 //#region src/FileProcessor.d.ts
-type ParseOptions = {
-  parsers?: Map<FileNode['extname'], Parser>;
-  extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
-};
-type FileProcessorEvents = {
+/**
+ * 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;
@@ -490,7 +674,12 @@ type FileProcessorEvents = {
     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;
@@ -498,22 +687,63 @@ type ParsedFile = {
   total: number;
   percentage: number;
 };
+type FileProcessorOptions = {
+  /**
+   * Storage destination for queued writes.
+   */
+  storage: Storage;
+  /**
+   * Parsers indexed by file extension.
+   */
+  parsers?: Map<FileNode['extname'], Parser>;
+  /**
+   * Output extname per source extname, applied during conversion.
+   */
+  extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
+};
 /**
- * Converts a single file to a string using the registered parsers.
- * Falls back to joining source values when no matching parser is found.
+ * Turns `FileNode`s into source strings and writes them to storage.
  *
- * @internal
+ * Two modes share the same instance. Stateless mode (`parse`, `stream`, `run`) just runs the
+ * conversion. Queue mode (`enqueue`, `flush`, `drain`) buffers files deduped by path and
+ * writes each batch through storage with up to `STREAM_FLUSH_EVERY` requests in flight.
+ *
+ * `flush` does not wait for its batch to finish, so dispatch can overlap with IO. The next
+ * `flush` or `drain` picks the in-flight batch up. `drain` blocks until everything has been
+ * written and is meant for the end of a build.
+ *
+ * To surface build-level hook signals (`kubb:files:processing:*` and friends) subscribe to
+ * `hooks` and re-emit on the kubb bus.
  */
 declare class FileProcessor {
-  readonly events: AsyncEventEmitter<FileProcessorEvents>;
-  parse(file: FileNode, {
-    parsers,
-    extension
-  }?: ParseOptions): string;
-  stream(files: ReadonlyArray<FileNode>, options?: ParseOptions): Generator<ParsedFile>;
-  run(files: Array<FileNode>, options?: ParseOptions): Promise<Array<FileNode>>;
+  #private;
+  readonly hooks: AsyncEventEmitter<FileProcessorHooks>;
+  constructor(options: FileProcessorOptions);
+  /**
+   * Files waiting in the queue.
+   */
+  get size(): number;
+  parse(file: FileNode): string;
+  stream(files: ReadonlyArray<FileNode>): Generator<ParsedFile>;
+  run(files: Array<FileNode>): Promise<Array<FileNode>>;
+  /**
+   * Adds a file to the next flush. A later `enqueue` for the same path replaces the previous
+   * entry, matching `FileManager.upsert`. Fires the `enqueue` event.
+   */
+  enqueue(file: FileNode): void;
+  /**
+   * Starts processing the queued files. Waits for any previous flush to finish (so two
+   * batches never run together) and then returns without waiting for the new one. The next
+   * `flush` or `drain` picks up the in-flight task.
+   */
+  flush(): Promise<void>;
+  /**
+   * Waits for the in-flight flush and writes any files still queued. Fires the `drain` event
+   * when both are done.
+   */
+  drain(): Promise<void>;
   /**
-   * Clears all registered event listeners.
+   * Clears every listener and the pending queue.
    */
   dispose(): void;
   [Symbol.dispose](): void;
@@ -675,7 +905,7 @@ type ResolveOptionsContext<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.
+ * are injected automatically by `defineResolver`. Extend this type to add custom resolution methods.
  *
  * @example
  * ```ts
@@ -777,7 +1007,7 @@ type ResolverFileParams = {
  * Per-file context describing the file a banner/footer is being resolved for.
  *
  * Supplied by the generator (or the barrel middleware) at resolve-time and merged
- * into `BannerMeta` so a `banner`/`footer` function can branch on the file kind —
+ * 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 = {
@@ -828,7 +1058,7 @@ type BannerMeta = InputMeta & {
 /**
  * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
  *
- * `output` is optional — not every plugin configures a banner/footer.
+ * `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.
  *
@@ -847,7 +1077,7 @@ type ResolveBannerContext = {
  * Builder type for the plugin-specific resolver fields.
  *
  * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
- * are optional — built-in fallbacks are injected when omitted.
+ * are optional, with built-in fallbacks injected when omitted.
  *
  * Methods in the returned object can call sibling resolver methods via `this`.
  */
@@ -861,11 +1091,11 @@ type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'],
  * name casing, include/exclude/override filtering, output path computation,
  * and file construction. Supply your own to override any of them:
  *
- * - `default` — name casing strategy (camelCase / PascalCase).
- * - `resolveOptions` — include/exclude/override filtering.
- * - `resolvePath` — output path computation.
- * - `resolveFile` — full `FileNode` construction.
- * - `resolveBanner` / `resolveFooter` — top/bottom-of-file text.
+ * - `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`,
  * which keeps custom rules small (`this.default(name, 'type')` to delegate).
@@ -921,8 +1151,8 @@ type Output<_TOptions = unknown> = {
    * 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
+   * 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
@@ -949,8 +1179,8 @@ type Output<_TOptions = unknown> = {
 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.
+   * - `'tag'` uses the first tag (`operation.getTags().at(0)?.name`).
+   * - `'path'` uses the first segment of the operation's URL.
    */
   type: 'tag' | 'path';
   /**
@@ -1035,7 +1265,7 @@ type ByContentType = {
  * ]
  * ```
  */
-type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
+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).
@@ -1054,7 +1284,7 @@ type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySch
  * 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.
+ * Entries are evaluated top to bottom. The first matching entry wins.
  *
  * @example
  * ```ts
@@ -1073,7 +1303,7 @@ type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySch
  * ```
  */
 type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
-  options: Partial<TOptions>;
+  options: Omit<Partial<TOptions>, 'override'>;
 };
 type PluginFactoryOptions<
 /**
@@ -1117,10 +1347,6 @@ type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactor
    * Set the AST transformer to pre-process nodes before they reach generators.
    */
   setTransformer(visitor: Visitor): void;
-  /**
-   * Set the renderer factory to process JSX elements from generators.
-   */
-  setRenderer(renderer: RendererFactory): void;
   /**
    * Set resolved options merged into the normalized plugin's `options`.
    * Call this in `kubb:plugin:setup` to provide options generators need.
@@ -1163,9 +1389,9 @@ type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
    * 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.
+   * - `'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`.
    */
@@ -1184,7 +1410,7 @@ type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
 };
 /**
  * Normalized plugin after setup, with runtime fields populated.
- * For internal use only — plugins use the public `Plugin` type externally.
+ * For internal use only, plugins use the public `Plugin` type externally.
  *
  * @internal
  */
@@ -1192,12 +1418,11 @@ type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptio
   options: TOptions['resolvedOptions'] & {
     output: Output;
     include?: Array<Include>;
-    exclude: Array<Exclude>;
+    exclude: Array<Exclude$1>;
     override: Array<Override<TOptions['resolvedOptions']>>;
   };
   resolver: TOptions['resolver'];
   transformer?: Visitor;
-  renderer?: RendererFactory;
   generators?: Array<Generator$1>;
   apply?: (config: Config) => boolean;
   version?: string;
@@ -1247,6 +1472,14 @@ type KubbPluginEndContext = {
 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
@@ -1262,25 +1495,24 @@ declare function definePlugin<TFactory extends PluginFactoryOptions = PluginFact
 declare class FileManager {
   #private;
   /**
-   * Registers a callback invoked with the resolved {@link FileNode} on every
-   * `add` / `upsert`. Used by the build loop to track newly written files
-   * without keeping its own scan-based diff. Single subscriber by design —
-   * setting again replaces the previous callback. Pass `null` to detach.
+   * Subscribe to file-store changes. Listeners on `upsert` see each resolved file as it lands
+   * through `add` or `upsert`.
    */
-  setOnUpsert(callback: ((file: FileNode) => void) | null): void;
+  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. Called by the core after `kubb:build:end`.
+   * 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.
+   * last within a length bucket). Returns a cached view, do not mutate.
    */
   get files(): Array<FileNode>;
 }
@@ -1305,14 +1537,14 @@ declare class KubbDriver {
   static getMode(fileOrFolder: string | undefined | null): 'single' | 'split';
   /**
    * The streaming `InputStreamNode` produced by the adapter.
-   * Always set after adapter setup — parse-only adapters are wrapped automatically.
+   * Always set after adapter setup, parse-only adapters are wrapped automatically.
    */
   inputNode: InputStreamNode | 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.
+   * add files. This property gives direct read/write access when needed.
    */
   readonly fileManager: FileManager;
   readonly plugins: Map<string, NormalizedPlugin>;
@@ -1334,13 +1566,12 @@ declare class KubbDriver {
    * 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 resolution chain is: `generator.renderer → plugin.renderer → config.renderer`.
-   * Set `generator.renderer = null` to explicitly opt out of rendering even when the plugin
-   * declares a renderer.
+   * 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, gen: Generator$1): void;
+  registerGenerator(pluginName: string, generator: Generator$1): void;
   /**
    * Returns `true` when at least one generator was registered for the given plugin
    * via `addGenerator()` in `kubb:plugin:setup` (event-based path).
@@ -1350,25 +1581,40 @@ declare class KubbDriver {
    */
   hasEventGenerators(pluginName: string): boolean;
   /**
-   * Runs the full plugin pipeline. Returns timings/failures collected so far even
-   * when an outer hook throws — the orchestrator preserves partial state by capturing
-   * the error into `error` instead of propagating.
+   * 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<{
-    failedPlugins: Set<{
-      plugin: Plugin;
-      error: Error;
-    }>;
-    pluginTimings: Map<string, number>;
-    error?: Error;
+    diagnostics: Array<Diagnostic>;
   }>;
   /**
-   * Unregisters all plugin lifecycle listeners from the shared event emitter.
-   * Called at the end of a build to prevent listener leaks across repeated builds.
+   * 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
    */
@@ -1457,15 +1703,20 @@ type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptio
    */
   transformer: Visitor | undefined;
   /**
-   * Emit a warning.
+   * 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
+   * `DiagnosticError` directly.
    */
   warn: (message: string) => void;
   /**
-   * Emit an error.
+   * Report an error. Collected as an `error` diagnostic attributed to the current
+   * plugin, which fails the build.
    */
   error: (error: string | Error) => void;
   /**
-   * Emit an info message.
+   * Report an informational message. Collected as an `info` diagnostic attributed to
+   * the current plugin.
    */
   info: (message: string) => void;
   /**
@@ -1477,7 +1728,7 @@ type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptio
    */
   adapter: Adapter;
   /**
-   * Document metadata from the adapter — title, version, base URL, and pre-computed
+   * Document metadata from the adapter: title, version, base URL, and pre-computed
    * schema index fields (`circularNames`, `enumNames`).
    */
   meta: InputMeta;
@@ -1523,8 +1774,7 @@ type Generator$1<TOptions extends PluginFactoryOptions = PluginFactoryOptions, T
    *
    * Generators that only return `Array<FileNode>` or `void` do not need to set this.
    *
-   * Set `renderer: null` to explicitly opt out of rendering even when the parent plugin
-   * declares a `renderer` (overrides the plugin-level fallback).
+   * Leave it unset or set `renderer: null` to opt out of rendering.
    *
    * @example
    * ```ts
@@ -1563,7 +1813,7 @@ type Generator$1<TOptions extends PluginFactoryOptions = PluginFactoryOptions, T
  * 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 — pick whichever style fits.
+ * are both handled by the runtime, so pick whichever style fits.
  *
  * @example JSX-based schema generator
  * ```tsx
@@ -1595,10 +1845,8 @@ declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginF
  */
 type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
 /**
- * Reference to an input file to generate code from.
- *
- * Specify an absolute path or a path relative to the config file location.
- * The adapter will parse this file (e.g., OpenAPI YAML or JSON) into the universal AST.
+ * 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 = {
   /**
@@ -1613,10 +1861,8 @@ type InputPath = {
   path: string;
 };
 /**
- * Inline input data to generate code from.
- *
- * Useful when you want to pass the specification directly instead of from a file.
- * Can be a string (YAML/JSON) or a parsed object.
+ * Inline spec to generate from, passed directly instead of read from a file. A string
+ * (YAML/JSON) or a parsed object.
  */
 type InputData = {
   /**
@@ -1632,15 +1878,9 @@ type InputData = {
 };
 type Input = InputPath | InputData;
 /**
- * Build configuration for Kubb code generation.
- *
- * The Config is the main entry point for customizing how Kubb generates code. It specifies:
- * - What to generate from (adapter + input)
- * - Where to output generated code (output)
- * - How to generate (plugins + middleware)
- * - Runtime details (parsers, storage, renderer)
- *
- * See `UserConfig` for a relaxed version with sensible defaults.
+ * Resolved build configuration for a Kubb run: what to generate from (adapter, input), where to
+ * write it (output), how (plugins, middleware), and the runtime pieces (parsers, storage). See
+ * `UserConfig` for the relaxed form with defaults applied.
  *
  * @private
  */
@@ -1657,16 +1897,16 @@ type Config<TInput = Input> = {
   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()`.
+   * 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; a fallback parser handles anything else.
+   * 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]`.
+   * Already resolved on the `Config` instance (see `UserConfig` for the
+   * optional form that defaults to `[parserTs, parserTsx, parserMd]`).
    *
    * @example
    * ```ts
@@ -1700,15 +1940,13 @@ type Config<TInput = Input> = {
   /**
    * 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 when running in plugin-only mode.
+   * 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`.
-     *
-     * All generated files will be written under this directory. Subdirectories can be created
-     * by plugins based on grouping strategy (by tag, path, etc.).
+     * Output directory for generated files, absolute or relative to `root`. Plugins can nest
+     * subdirectories under it by grouping strategy (tag, path).
      *
      * @example
      * ```ts
@@ -1719,10 +1957,8 @@ type Config<TInput = Input> = {
      */
     path: string;
     /**
-     * Remove all files from the output directory before starting the build.
-     *
-     * Useful to ensure old generated files aren't mixed with new ones.
-     * Set to `true` for fresh builds, `false` to preserve manual edits in output dir.
+     * 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.
      *
      * @default false
      * @example
@@ -1732,10 +1968,8 @@ type Config<TInput = Input> = {
      */
     clean?: boolean;
     /**
-     * Auto-format generated files after code generation completes.
-     *
-     * Applies a code formatter to all generated files. Use `'auto'` to detect which formatter
-     * is available on your system. Pass `false` to skip formatting (useful for CI or specific workflows).
+     * 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.
      *
      * @default false
      * @example
@@ -1747,10 +1981,8 @@ type Config<TInput = Input> = {
      */
     format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false;
     /**
-     * Auto-lint generated files after code generation completes.
-     *
-     * Analyzes all generated files for style/correctness issues. Use `'auto'` to detect which linter
-     * is available on your system. Pass `false` to skip linting.
+     * 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.
      *
      * @default false
      * @example
@@ -1762,10 +1994,8 @@ type Config<TInput = Input> = {
      */
     lint?: 'auto' | 'eslint' | 'biome' | 'oxlint' | false;
     /**
-     * Map file extensions to different output extensions.
-     *
-     * Useful when you want generated `.ts` imports to reference `.js` files or vice versa (e.g., for ESM dual packages).
-     * Keys are the original extension, values are the output extension. Use empty string `''` to omit extension.
+     * 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
@@ -1776,10 +2006,8 @@ type Config<TInput = Input> = {
      */
     extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
     /**
-     * Banner text prepended to every generated file.
-     *
-     * Useful for auto-generation notices or license headers. Choose a preset or write custom text.
-     * Use `'simple'` for a basic Kubb banner, `'full'` for detailed metadata, or `false` to omit.
+     * 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
@@ -1791,10 +2019,8 @@ type Config<TInput = Input> = {
      */
     defaultBanner?: 'simple' | 'full' | false;
     /**
-     * When `true`, overwrites existing files. When `false`, skips generated files that already exist.
-     *
-     * Individual plugins can override this setting. This is useful for preventing accidental data loss
-     * when re-generating while you have local edits in the output folder.
+     * Overwrite existing files when `true`, skip files that already exist when `false`. Individual
+     * plugins can override it. Keep `false` to avoid clobbering local edits in the output folder.
      *
      * @default false
      * @example
@@ -1806,10 +2032,8 @@ type Config<TInput = Input> = {
     override?: boolean;
   } & ExtractRegistryKey<Kubb$1.ConfigOptionsRegistry, 'output'>;
   /**
-   * Storage backend that controls where and how generated files are persisted.
-   *
-   * Defaults to `fsStorage()` which writes to the file system. Pass `memoryStorage()` to keep files in RAM,
-   * or implement a custom `Storage` interface to write to cloud storage, databases, or other backends.
+   * 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
@@ -1827,13 +2051,9 @@ type Config<TInput = Input> = {
    */
   storage: Storage;
   /**
-   * Plugins that execute during the build to generate code and transform the AST.
-   *
-   * Each plugin processes the AST produced by the adapter and can emit files for different
-   * programming languages or formats (TypeScript, Zod schemas, Faker data, etc.).
-   * Dependencies are enforced — an error is thrown if a plugin requires another plugin that isn't registered.
-   *
-   * Plugins can declare their own options via `PluginFactoryOptions`. See plugin documentation for details.
+   * 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
@@ -1866,22 +2086,6 @@ type Config<TInput = Input> = {
    * @see {@link defineMiddleware} to create custom middleware.
    */
   middleware?: Array<Middleware>;
-  /**
-   * Renderer that converts generated AST nodes to code strings.
-   *
-   * By default, Kubb uses the JSX renderer (`rendererJsx`). Pass a custom renderer to support
-   * different output formats (template engines, code generation DSLs, etc.).
-   *
-   * @default rendererJsx()  // from @kubb/renderer-jsx
-   * @example
-   * ```ts
-   * import { rendererJsx } from '@kubb/renderer-jsx'
-   * renderer: rendererJsx()
-   * ```
-   *
-   * @see {@link Renderer} to implement a custom renderer.
-   */
-  renderer?: RendererFactory;
   /**
    * Kubb Studio cloud integration settings.
    *
@@ -1933,13 +2137,29 @@ type Config<TInput = Input> = {
      */
     done?: string | Array<string>;
   };
+  /**
+   * Reporters that render the run's output, like Vitest. List one or more by name;
+   * the CLI `--reporter` flag overrides this when set.
+   *
+   * - `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`.
+   *
+   * @default ['cli']
+   *
+   * @example
+   * ```ts
+   * reporters: ['cli', 'file']
+   * ```
+   */
+  reporters?: Array<ReporterName>;
 };
 /**
  * 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`, `middleware`, `renderer`, `devtools`, and `hooks`.
+ * `storage`, `middleware`, `devtools`, and `hooks`.
  *
  * @example
  * ```ts
@@ -2061,7 +2281,6 @@ interface KubbHooks {
   'kubb:config:end': [ctx: KubbConfigEndContext];
   'kubb:generation:start': [ctx: KubbGenerationStartContext];
   'kubb:generation:end': [ctx: KubbGenerationEndContext];
-  'kubb:generation:summary': [ctx: KubbGenerationSummaryContext];
   'kubb:format:start': [];
   'kubb:format:end': [];
   'kubb:lint:start': [];
@@ -2070,12 +2289,11 @@ interface KubbHooks {
   'kubb:hooks:end': [];
   'kubb:hook:start': [ctx: KubbHookStartContext];
   'kubb:hook:end': [ctx: KubbHookEndContext];
-  'kubb:version:new': [ctx: KubbVersionNewContext];
   'kubb:info': [ctx: KubbInfoContext];
   'kubb:error': [ctx: KubbErrorContext];
   'kubb:success': [ctx: KubbSuccessContext];
   'kubb:warn': [ctx: KubbWarnContext];
-  'kubb:debug': [ctx: KubbDebugContext];
+  'kubb:diagnostic': [ctx: KubbDiagnosticContext];
   'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext];
   'kubb:files:processing:update': [ctx: KubbFilesProcessingUpdateContext];
   'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext];
@@ -2170,7 +2388,7 @@ type KubbGenerationEndContext = {
   config: Config;
   /**
    * Read-only view of the files written during this build.
-   * Reads go directly to `config.storage` — nothing extra is held in memory.
+   * 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')`
@@ -2183,45 +2401,24 @@ type KubbGenerationEndContext = {
    * ```
    */
   storage: Storage;
-};
-type KubbGenerationSummaryContext = {
   /**
-   * Resolved configuration for this generation run.
+   * Diagnostics collected during the build: error/warning/info problems plus a
+   * `timing` 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.
    */
-  config: Config;
-  /**
-   * Plugins that threw during generation, paired with their errors.
-   */
-  failedPlugins: Set<{
-    plugin: Plugin;
-    error: Error;
-  }>;
+  diagnostics?: Array<Diagnostic>;
   /**
    * `'success'` when all plugins completed without errors, `'failed'` otherwise.
    */
-  status: 'success' | 'failed';
+  status?: 'success' | 'failed';
   /**
-   * High-resolution start time from `process.hrtime()`.
+   * High-resolution start time from `process.hrtime()`, used to compute the elapsed time.
    */
-  hrStart: [number, number];
+  hrStart?: [number, number];
   /**
    * Total number of files created during this run.
    */
-  filesCreated: number;
-  /**
-   * Elapsed milliseconds per plugin, keyed by plugin name.
-   */
-  pluginTimings?: Map<Plugin['name'], number>;
-};
-type KubbVersionNewContext = {
-  /**
-   * The installed Kubb version.
-   */
-  currentVersion: string;
-  /**
-   * The newest available version on npm.
-   */
-  latestVersion: string;
+  filesCreated?: number;
 };
 type KubbInfoContext = {
   /**
@@ -2263,19 +2460,11 @@ type KubbWarnContext = {
    */
   info?: string;
 };
-type KubbDebugContext = {
-  /**
-   * Timestamp when the debug entry was created.
-   */
-  date: Date;
+type KubbDiagnosticContext = {
   /**
-   * One or more log lines to emit.
+   * The structured diagnostic to render: a build problem or a version-update notice.
    */
-  logs: Array<string>;
-  /**
-   * Optional source file name associated with this entry.
-   */
-  fileName?: string;
+  diagnostic: ProblemDiagnostic | UpdateDiagnostic;
 };
 type KubbFilesProcessingStartContext = {
   /**
@@ -2293,7 +2482,7 @@ type KubbFileProcessingUpdate = {
    */
   total: number;
   /**
-   * Completion percentage (`0`–`100`).
+   * Completion percentage, `0` to `100`.
    */
   percentage: number;
   /**
@@ -2379,7 +2568,11 @@ type CLIOptions = {
    *
    * @default 'info'
    */
-  logLevel?: 'silent' | 'info' | 'verbose' | 'debug';
+  logLevel?: 'silent' | 'info' | 'verbose';
+  /**
+   * Reporters selected on the CLI via `--reporter`, overriding `config.reporters`.
+   */
+  reporters?: Array<ReporterName>;
 };
 /**
  * All accepted forms of a Kubb configuration.
@@ -2391,12 +2584,12 @@ type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Array<Co
  */
 type BuildOutput = {
   /**
-   * Plugins that threw during generation, paired with their errors.
+   * Structured diagnostics collected during the build: error/warning/info problems
+   * (each with a code, severity, and where known a JSON-pointer location) plus a
+   * `timing` diagnostic per plugin. Includes a top-level diagnostic when the build
+   * threw before completing. Use {@link Diagnostics.hasError} to test for failure.
    */
-  failedPlugins: Set<{
-    plugin: Plugin;
-    error: Error;
-  }>;
+  diagnostics: Array<Diagnostic>;
   /**
    * All files generated during this build.
    */
@@ -2405,17 +2598,9 @@ type BuildOutput = {
    * The plugin driver that orchestrated this build.
    */
   driver: KubbDriver;
-  /**
-   * Elapsed milliseconds per plugin, keyed by plugin name.
-   */
-  pluginTimings: Map<string, number>;
-  /**
-   * Top-level error when the build threw before completing, otherwise `undefined`.
-   */
-  error?: Error;
   /**
    * Read-only view of every file written during this build.
-   * Reads go straight to `config.storage` — nothing extra is held in memory.
+   * 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')`
@@ -2448,7 +2633,7 @@ type CreateKubbOptions = {
  * ```ts
  * const kubb = createKubb(userConfig)
  * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => console.log(plugin.name, duration))
- * const { files, failedPlugins } = await kubb.safeBuild()
+ * const { files, diagnostics } = await kubb.safeBuild()
  * ```
  */
 declare class Kubb$1 {
@@ -2497,5 +2682,323 @@ declare class Kubb$1 {
  */
 declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions): Kubb$1;
 //#endregion
-export { Resolver as $, createKubb as A, KubbPluginEndContext as B, KubbLifecycleStartContext as C, AdapterFactoryOptions as Ct, KubbWarnContext as D, AsyncEventEmitter as Dt, KubbVersionNewContext as E, logLevel as Et, KubbDriver as F, Override as G, KubbPluginStartContext as H, FileManager as I, definePlugin as J, Plugin as K, Exclude as L, Generator$1 as M, GeneratorContext as N, PossibleConfig as O, defineGenerator as P, ResolveOptionsContext as Q, Group as R, KubbInfoContext as S, Adapter as St, KubbSuccessContext as T, createAdapter as Tt, NormalizedPlugin as U, KubbPluginSetupContext as V, Output as W, ResolveBannerContext as X, BannerMeta as Y, ResolveBannerFile as Z, KubbGenerationStartContext as _, Storage as _t, InputPath as a, defineMiddleware as at, KubbHookStartContext as b, RendererFactory as bt, KubbBuildStartContext as c, LoggerOptions as ct, KubbErrorContext as d, FileProcessor as dt, ResolverContext as et, KubbFileProcessingUpdate as f, FileProcessorEvents as ft, KubbGenerationEndContext as g, DevtoolsOptions as gt, KubbFilesProcessingUpdateContext as h, defineParser as ht, InputData as i, Middleware as it, isInputPath as j, UserConfig as k, KubbConfigEndContext as l, UserLogger as lt, KubbFilesProcessingStartContext as m, Parser as mt, CLIOptions as n, ResolverPathParams as nt, Kubb$1 as o, Logger as ot, KubbFilesProcessingEndContext as p, ParsedFile as pt, PluginFactoryOptions as q, Config as r, defineResolver as rt, KubbBuildEndContext as s, LoggerContext as st, BuildOutput as t, ResolverFileParams as tt, KubbDebugContext as u, defineLogger as ut, KubbGenerationSummaryContext as v, createStorage as vt, KubbPluginsEndContext as w, AdapterSource as wt, KubbHooks as x, createRenderer as xt, KubbHookEndContext as y, Renderer as yt, Include as z };
-//# sourceMappingURL=createKubb-BKpcUB6g.d.ts.map
+//#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 single source of truth the kubb.dev `/diagnostics/<slug>` pages
+ * mirror, so every code stays documented in one place. Typed as a total record over
+ * {@link DiagnosticCode}, so 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. It carries a stable {@link ProblemCode}, a
+ * `severity`, a `message`, and optionally a `location` into the source document,
+ * a `help`, the `plugin` that produced it, and the `cause` it wraps.
+ */
+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}. It carries the
+ * `plugin` and its elapsed `duration`, and 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 carries the running and latest versions and 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 narrowDiagnostic}.
+ * 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 = narrowDiagnostic(diagnostic, diagnosticCode.updateAvailable)
+ * if (update) {
+ *   console.log(update.latestVersion)
+ * }
+ * ```
+ */
+declare function narrowDiagnostic<C extends DiagnosticCode>(diagnostic: Diagnostic, code: C): DiagnosticByCode[C] | null;
+/**
+ * Returns `true` when the diagnostic is a build {@link ProblemDiagnostic}.
+ *
+ * @example
+ * ```ts
+ * if (isProblemDiagnostic(diagnostic)) {
+ *   console.log(diagnostic.location)
+ * }
+ * ```
+ */
+declare const isProblemDiagnostic: (diagnostic: Diagnostic) => diagnostic is ProblemDiagnostic;
+/**
+ * Returns `true` when the diagnostic is a per-plugin {@link PerformanceDiagnostic}.
+ *
+ * @example
+ * ```ts
+ * const timings = diagnostics.filter(isPerformanceDiagnostic)
+ * ```
+ */
+declare const isPerformanceDiagnostic: (diagnostic: Diagnostic) => diagnostic is PerformanceDiagnostic;
+/**
+ * Returns `true` when the diagnostic is a version-update {@link UpdateDiagnostic}.
+ *
+ * @example
+ * ```ts
+ * if (isUpdateDiagnostic(diagnostic)) {
+ *   console.log(diagnostic.latestVersion)
+ * }
+ * ```
+ */
+declare const isUpdateDiagnostic: (diagnostic: Diagnostic) => diagnostic is UpdateDiagnostic;
+/**
+ * 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 `timing`/`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;
+};
+/**
+ * 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 DiagnosticError({ code: diagnosticCode.refNotFound, severity: 'error', message: `Could not find ${ref}`, location: { kind: 'schema', pointer: ref, ref } })
+ * ```
+ */
+declare class DiagnosticError extends Error {
+  diagnostic: ProblemDiagnostic;
+  constructor(diagnostic: ProblemDiagnostic);
+}
+/**
+ * Explanation for every {@link diagnosticCode}. Use {@link Diagnostics.explain} to look one up
+ * and `Diagnostics.docsUrl` for the matching kubb.dev page.
+ */
+declare const diagnosticCatalog: Record<DiagnosticCode, DiagnosticDoc>;
+/**
+ * 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;
+  /**
+   * 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 DiagnosticError}
+   * 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. `timing`
+   * 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;
+}
+//#endregion
+export { Exclude$1 as $, KubbFileProcessingUpdate as A, Parser as At, KubbLifecycleStartContext as B, RendererFactory as Bt, InputPath as C, LoggerContext as Ct, KubbConfigEndContext as D, FileProcessor as Dt, KubbBuildStartContext as E, defineLogger as Et, KubbGenerationStartContext as F, ReporterName as Ft, UserConfig as G, AdapterFactoryOptions as Gt, KubbSuccessContext as H, Storage as Ht, KubbHookEndContext as I, UserReporter as It, Generator$1 as J, diagnosticCode as Jt, createKubb as K, AdapterSource as Kt, KubbHookStartContext as L, createReporter as Lt, KubbFilesProcessingStartContext as M, GenerationResult as Mt, KubbFilesProcessingUpdateContext as N, Reporter as Nt, KubbDiagnosticContext as O, FileProcessorHooks as Ot, KubbGenerationEndContext as P, ReporterContext as Pt, FileManager as Q, KubbHooks as R, DevtoolsOptions as Rt, InputData as S, Logger as St, KubbBuildEndContext as T, UserLogger as Tt, KubbWarnContext as U, createStorage as Ut, KubbPluginsEndContext as V, createRenderer as Vt, PossibleConfig as W, Adapter as Wt, defineGenerator as X, AsyncEventEmitter as Xt, GeneratorContext as Y, logLevel as Yt, KubbDriver as Z, isUpdateDiagnostic as _, ResolverFileParams as _t, DiagnosticKind as a, NormalizedPlugin as at, CLIOptions as b, Middleware as bt, Diagnostics as c, Plugin as ct, ProblemDiagnostic as d, BannerMeta as dt, Group as et, SerializedDiagnostic as f, ResolveBannerContext as ft, isProblemDiagnostic as g, ResolverContext as gt, isPerformanceDiagnostic as h, Resolver as ht, DiagnosticError as i, KubbPluginStartContext as it, KubbFilesProcessingEndContext as j, defineParser as jt, KubbErrorContext as k, ParsedFile as kt, PerformanceDiagnostic as l, PluginFactoryOptions as lt, diagnosticCatalog as m, ResolveOptionsContext as mt, DiagnosticByCode as n, KubbPluginEndContext as nt, DiagnosticLocation as o, Output as ot, UpdateDiagnostic as p, ResolveBannerFile as pt, isInputPath as q, createAdapter as qt, DiagnosticDoc as r, KubbPluginSetupContext as rt, DiagnosticSeverity as s, Override as st, Diagnostic as t, Include as tt, ProblemCode as u, definePlugin as ut, narrowDiagnostic as v, ResolverPathParams as vt, Kubb$1 as w, LoggerOptions as wt, Config as x, defineMiddleware as xt, BuildOutput as y, defineResolver as yt, KubbInfoContext as z, Renderer as zt };
+//# sourceMappingURL=diagnostics-B0ONXReg.d.ts.map