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

package/src/createKubb.ts

@@ -1,17 +1,16 @@
 import { resolve } from 'node:path'
-import { version as nodeVersion } from 'node:process'
 import type { PossiblePromise } from '@internals/utils'
-import { AsyncEventEmitter, BuildError, exists, URLPath } from '@internals/utils'
+import { AsyncEventEmitter, BuildError } from '@internals/utils'
 import type { FileNode, InputMeta, OperationNode, SchemaNode } from '@kubb/ast'
-import { version as KubbVersion } from '../package.json'
-import { DEFAULT_BANNER, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
+import { DEFAULT_STUDIO_URL, HOOK_LISTENERS_PER_PLUGIN } from './constants.ts'
 import type { Adapter } from './createAdapter.ts'
-import type { RendererFactory } from './createRenderer.ts'
+import { type Diagnostic, DiagnosticError, Diagnostics, isProblemDiagnostic, type ProblemDiagnostic, type UpdateDiagnostic } from './diagnostics.ts'
 import { createStorage, type Storage } from './createStorage.ts'
 import type { GeneratorContext } from './defineGenerator.ts'
 import type { Middleware } from './defineMiddleware.ts'
 import type { Parser } from './defineParser.ts'
 import type { KubbPluginEndContext, KubbPluginSetupContext, KubbPluginStartContext, Plugin } from './definePlugin.ts'
+import type { ReporterName } from './createReporter.ts'
 
 import { KubbDriver } from './KubbDriver.ts'
 import { fsStorage } from './storages/fsStorage.ts'
@@ -26,10 +25,8 @@ import { fsStorage } from './storages/fsStorage.ts'
 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.
  */
 export type InputPath = {
   /**
@@ -45,10 +42,8 @@ export type InputPath = {
 }
 
 /**
- * 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.
  */
 export type InputData = {
   /**
@@ -66,15 +61,9 @@ export 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
  */
@@ -91,16 +80,16 @@ export 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
@@ -134,15 +123,13 @@ export 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
@@ -153,10 +140,8 @@ export 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
@@ -166,10 +151,8 @@ export 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
@@ -181,10 +164,8 @@ export 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
@@ -196,10 +177,8 @@ export 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
@@ -210,10 +189,8 @@ export 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
@@ -225,10 +202,8 @@ export 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
@@ -240,10 +215,8 @@ export type Config<TInput = Input> = {
     override?: boolean
   } & ExtractRegistryKey<Kubb.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
@@ -261,13 +234,9 @@ export 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
@@ -300,22 +269,6 @@ export 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.
    *
@@ -369,6 +322,22 @@ export 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>
 }
 
 /**
@@ -376,7 +345,7 @@ export type Config<TInput = Input> = {
  *
  * `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
@@ -502,7 +471,6 @@ export 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': []
@@ -511,12 +479,11 @@ export 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]
@@ -618,7 +585,7 @@ export 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')`
@@ -631,44 +598,24 @@ export type KubbGenerationEndContext = {
    * ```
    */
   storage: Storage
-}
-
-export 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>
-}
-
-export type KubbVersionNewContext = {
-  /**
-   * The installed Kubb version.
-   */
-  currentVersion: string
-  /**
-   * The newest available version on npm.
-   */
-  latestVersion: string
+  filesCreated?: number
 }
 
 export type KubbInfoContext = {
@@ -715,19 +662,11 @@ export type KubbWarnContext = {
   info?: string
 }
 
-export type KubbDebugContext = {
-  /**
-   * Timestamp when the debug entry was created.
-   */
-  date: Date
-  /**
-   * One or more log lines to emit.
-   */
-  logs: Array<string>
+export type KubbDiagnosticContext = {
   /**
-   * Optional source file name associated with this entry.
+   * The structured diagnostic to render: a build problem or a version-update notice.
    */
-  fileName?: string
+  diagnostic: ProblemDiagnostic | UpdateDiagnostic
 }
 
 export type KubbFilesProcessingStartContext = {
@@ -747,7 +686,7 @@ export type KubbFileProcessingUpdate = {
    */
   total: number
   /**
-   * Completion percentage (`0`–`100`).
+   * Completion percentage, `0` to `100`.
    */
   percentage: number
   /**
@@ -838,7 +777,11 @@ export 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>
 }
 
 /**
@@ -854,9 +797,12 @@ export type PossibleConfig<TCliOptions = undefined> =
  */
 export 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.
    */
@@ -865,17 +811,9 @@ export 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')`
@@ -889,7 +827,7 @@ export type BuildOutput = {
 /**
  * Builds a `Storage` view scoped to the file paths produced by the current build.
  * Reads delegate to the underlying `storage` so source bytes stay where they were
- * written; writes register the key so subsequent reads and `getKeys` are scoped
+ * written. Writes register the key so subsequent reads and `getKeys` are scoped
  * to this build's output.
  */
 function createSourcesView(storage: Storage): Storage {
@@ -934,8 +872,8 @@ function resolveConfig(userConfig: UserConfig): Config {
     output: {
       format: false,
       lint: false,
-      extension: DEFAULT_EXTENSION,
-      defaultBanner: DEFAULT_BANNER,
+      extension: { '.ts': '.ts' },
+      defaultBanner: 'simple',
       ...userConfig.output,
     },
     storage: userConfig.storage ?? fsStorage(),
@@ -949,22 +887,6 @@ function resolveConfig(userConfig: UserConfig): Config {
   }
 }
 
-/**
- * Returns a snapshot of the current runtime environment.
- *
- * Useful for attaching context to debug logs and error reports so that
- * issues can be reproduced without manual information gathering.
- */
-export function getDiagnosticInfo() {
-  return {
-    nodeVersion,
-    KubbVersion,
-    platform: process.platform,
-    arch: process.arch,
-    cwd: process.cwd(),
-  } as const
-}
-
 /**
  * Type guard to check if a given config has an `input.path`.
  */
@@ -989,7 +911,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()
  * ```
  */
 export class Kubb {
@@ -1027,22 +949,12 @@ export class Kubb {
     const driver = new KubbDriver(config, { hooks: this.hooks })
     const storage = createSourcesView(config.storage)
 
-    await this.hooks.emit('kubb:debug', { date: new Date(), logs: this.#configLogs(config) })
-
-    if (isInputPath(this.#userConfig) && !new URLPath(this.#userConfig.input.path).isURL) {
-      try {
-        await exists(this.#userConfig.input.path)
-        await this.hooks.emit('kubb:debug', { date: new Date(), logs: [`✓ Input file validated: ${this.#userConfig.input.path}`] })
-      } catch (caughtError) {
-        throw new Error(
-          `Cannot read file/URL defined in \`input.path\` or set with \`kubb generate PATH\` in the CLI of your Kubb config ${this.#userConfig.input.path}`,
-          { cause: caughtError as Error },
-        )
-      }
-    }
+    // Each generator a plugin registers adds a listener to the shared hooks emitter, so size the
+    // ceiling to the plugin count. Without this, a multi-generator plugin set trips Node's
+    // EventEmitter leak warning at the default 10.
+    this.hooks.setMaxListeners(Math.max(10, config.plugins.length * HOOK_LISTENERS_PER_PLUGIN))
 
     if (config.output.clean) {
-      await this.hooks.emit('kubb:debug', { date: new Date(), logs: ['Cleaning output directories', `  • Output: ${config.output.path}`] })
       await config.storage.clear(resolve(config.root, config.output.path))
     }
 
@@ -1059,10 +971,12 @@ export class Kubb {
    */
   async build(): Promise<BuildOutput> {
     const out = await this.safeBuild()
-    if (out.error) throw out.error
-    if (out.failedPlugins.size > 0) {
-      const errors = [...out.failedPlugins].map(({ error }) => error)
-      throw new BuildError(`Build Error with ${out.failedPlugins.size} failed plugins`, { errors })
+    if (Diagnostics.hasError(out.diagnostics)) {
+      const errors = out.diagnostics
+        .filter(isProblemDiagnostic)
+        .filter((diagnostic) => diagnostic.severity === 'error')
+        .map((diagnostic) => diagnostic.cause ?? new DiagnosticError(diagnostic))
+      throw new BuildError(`Build failed with ${errors.length} ${errors.length === 1 ? 'error' : 'errors'}`, { errors })
     }
     return out
   }
@@ -1076,8 +990,9 @@ export class Kubb {
     using cleanup = this
     const driver = cleanup.driver
     const storage = cleanup.storage
-    const { failedPlugins, pluginTimings, error } = await driver.run({ storage })
-    return { failedPlugins, files: driver.fileManager.files, driver, pluginTimings, storage, ...(error ? { error } : {}) }
+    const { diagnostics } = await driver.run({ storage })
+
+    return { diagnostics, files: driver.fileManager.files, driver, storage }
   }
 
   dispose(): void {
@@ -1087,27 +1002,6 @@ export class Kubb {
   [Symbol.dispose](): void {
     this.dispose()
   }
-
-  #configLogs(config: Config): Array<string> {
-    const u = this.#userConfig
-    const diag = getDiagnosticInfo()
-    return [
-      'Configuration:',
-      `  • Name: ${u.name || 'unnamed'}`,
-      `  • Root: ${u.root || process.cwd()}`,
-      `  • Output: ${u.output?.path || 'not specified'}`,
-      `  • Plugins: ${u.plugins?.length || 0}`,
-      'Output Settings:',
-      `  • Storage: ${config.storage.name}`,
-      `  • Formatter: ${u.output?.format || 'none'}`,
-      `  • Linter: ${u.output?.lint || 'none'}`,
-      `Running adapter: ${config.adapter?.name || 'none'}`,
-      'Environment:',
-      Object.entries(diag)
-        .map(([key, value]) => `  • ${key}: ${value}`)
-        .join('\n'),
-    ]
-  }
 }
 
 /**

package/src/createRenderer.ts

@@ -11,7 +11,7 @@ import type { FileNode } from '@kubb/ast'
 export 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>
   /**
@@ -52,7 +52,7 @@ export 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`.

package/src/createReporter.ts

@@ -0,0 +1,84 @@
+import type { logLevel } from './constants.ts'
+import type { Config } from './createKubb.ts'
+import type { Diagnostic } from './diagnostics.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`.
+ */
+export type ReporterName = 'cli' | 'json' | 'file'
+
+/**
+ * One config's outcome within a run, as handed to a {@link Reporter}.
+ */
+export 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 context passed alongside the {@link GenerationResult}, carrying knobs a reporter needs
+ * but that are not part of the run data (e.g. verbosity).
+ */
+export type ReporterContext = {
+  /**
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
+   */
+  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).
+ */
+export 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>
+}
+
+export type UserReporter = Reporter
+
+/**
+ * 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
+ * ```ts
+ * import { createReporter, Diagnostics } from '@kubb/core'
+ *
+ * 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`)
+ *   },
+ * })
+ * ```
+ */
+export function createReporter(reporter: UserReporter): Reporter {
+  return reporter
+}

package/src/createStorage.ts

@@ -43,7 +43,7 @@ export type Storage = {
 /**
  * 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
+ * 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)