@kubb/core 5.0.0-beta.6 → 5.0.0-beta.60

package/src/types.ts

@@ -1,31 +1,26 @@
-import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { FileNode, HttpMethod, ImportNode, InputNode, Node, SchemaNode, UserFileNode, Visitor } from '@kubb/ast'
-import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
-import type { RendererFactory } from './createRenderer.ts'
+import type { PossiblePromise } from '@internals/utils'
+import type { FileNode, InputMeta, OperationNode, SchemaNode } from '@kubb/ast'
+import type { Adapter } from './createAdapter.ts'
+import type { Reporter, ReporterName } from './createReporter.ts'
 import type { Storage } from './createStorage.ts'
-import type { Generator } from './defineGenerator.ts'
-import type { Middleware } from './defineMiddleware.ts'
+import type { Diagnostic, ProblemDiagnostic, UpdateDiagnostic } from './diagnostics.ts'
+import type { GeneratorContext } from './defineGenerator.ts'
 import type { Parser } from './defineParser.ts'
-import type { Plugin } from './definePlugin.ts'
-import type { KubbHooks } from './Kubb.ts'
-import type { PluginDriver } from './PluginDriver.ts'
-
-export type { Renderer, RendererFactory } from './createRenderer.ts'
+import type { KubbPluginEndContext, KubbPluginSetupContext, KubbPluginStartContext, Plugin } from './definePlugin.ts'
+import type { KubbDriver } from './KubbDriver.ts'
 
 /**
- * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
- * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
- * without requiring changes to core.
+ * Extracts a type from a registry, falling back to `{}` when the key doesn't exist.
+ * Lets plugins augment `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without changing core.
  *
  * @internal
  */
 type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {}
 
 /**
- * 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 = {
   /**
@@ -41,10 +36,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 = {
   /**
@@ -62,98 +55,9 @@ export type InputData = {
 type Input = InputPath | InputData
 
 /**
- * Source data passed to an adapter's `parse` function.
- * Mirrors the config input shape with paths resolved to absolute.
- */
-export type AdapterSource = { type: 'path'; path: string } | { type: 'data'; data: string | unknown } | { type: 'paths'; paths: Array<string> }
-
-/**
- * Generic type parameters for an adapter definition.
- *
- * - `TName` — unique identifier (e.g. `'oas'`, `'asyncapi'`)
- * - `TOptions` — user-facing options passed to the adapter factory
- * - `TResolvedOptions` — options after defaults applied
- * - `TDocument` — type of the parsed source document
- */
-export type AdapterFactoryOptions<
-  TName extends string = string,
-  TOptions extends object = object,
-  TResolvedOptions extends object = TOptions,
-  TDocument = unknown,
-> = {
-  name: TName
-  options: TOptions
-  resolvedOptions: TResolvedOptions
-  document: TDocument
-}
-
-/**
- * Adapter that converts input files or data into an `InputNode`.
- *
- * Adapters parse different schema formats (OpenAPI, AsyncAPI, Drizzle, etc.) into Kubb's
- * universal intermediate representation that all plugins consume.
- *
- * @example
- * ```ts
- * import { adapterOas } from '@kubb/adapter-oas'
- *
- * export default defineConfig({
- *   adapter: adapterOas(),
- *   input: { path: './openapi.yaml' },
- *   plugins: [pluginTs(), pluginZod()],
- * })
- * ```
- */
-export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
-  /**
-   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
-   */
-  name: TOptions['name']
-  /**
-   * Resolved adapter options after defaults have been applied.
-   */
-  options: TOptions['resolvedOptions']
-  /**
-   * Parsed source document after the first `parse()` call. `null` before parsing.
-   */
-  document: TOptions['document'] | null
-  inputNode: InputNode | null
-  /**
-   * Parse the source into a universal `InputNode`.
-   */
-  parse: (source: AdapterSource) => PossiblePromise<InputNode>
-  /**
-   * Extract `ImportNode` entries for a schema tree.
-   * Returns an empty array before the first `parse()` call.
-   *
-   * The `resolve` callback receives the collision-corrected schema name and must
-   * return `{ name, path }` for the import, or `undefined` to skip it.
-   */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<ImportNode>
-  /**
-   * Validate the document at the given path or URL.
-   */
-  validate: (input: string, options?: { throwOnError?: boolean }) => Promise<void>
-}
-
-export type DevtoolsOptions = {
-  /**
-   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
-   * @default false
-   */
-  ast?: boolean
-}
-
-/**
- * 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), and the runtime pieces (parsers, storage). See
+ * `UserConfig` for the relaxed form with defaults applied.
  *
  * @private
  */
@@ -169,28 +73,31 @@ export type Config<TInput = Input> = {
    */
   name?: string
   /**
-   * Project root directory, absolute or relative to the config file.
-   * @default process.cwd()
+   * Project root directory, absolute or relative to the config file. Already
+   * resolved on the `Config` instance (see `UserConfig` for the optional
+   * form that defaults to `process.cwd()`).
    */
   root: string
   /**
-   * Parsers that convert generated files to strings.
-   * Each parser handles specific extensions (e.g. `.ts`, `.tsx`).
-   * A fallback parser is appended for unhandled extensions.
-   * When omitted, defaults to `parserTs` from `@kubb/parser-ts`.
+   * Parsers that convert generated files into strings. Each parser handles a
+   * set of file extensions, and a fallback parser handles anything else.
+   *
+   * Already resolved on the `Config` instance (see `UserConfig` for the
+   * optional form that defaults to `[parserTs, parserTsx, parserMd]`).
    *
-   * @default [parserTs] from `@kubb/parser-ts`
    * @example
    * ```ts
-   * import { parserTs, tsxParser } from '@kubb/parser-ts'
+   * import { defineConfig } from 'kubb'
+   * import { parserTs, parserTsx } from '@kubb/parser-ts'
+   *
    * export default defineConfig({
-   *   parsers: [parserTs, tsxParser],
+   *   parsers: [parserTs, parserTsx],
    * })
    * ```
    */
   parsers: Array<Parser>
   /**
-   * Adapter that parses input files into the universal `InputNode` representation.
+   * Adapter that parses input files into the universal AST representation.
    * Use `@kubb/adapter-oas` for OpenAPI/Swagger or `@kubb/adapter-asyncapi` for other formats.
    *
    * When omitted, Kubb runs in plugin-only mode: `kubb:plugin:setup` fires and files
@@ -210,15 +117,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
@@ -229,12 +134,9 @@ 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
      * ```ts
      * clean: true  // wipes ./src/gen/* before generating
@@ -242,19 +144,9 @@ export type Config<TInput = Input> = {
      */
     clean?: boolean
     /**
-     * Persists generated files to the file system.
-     *
-     * @default true
-     * @deprecated Use `storage` option to control where files are written instead.
-     */
-    write?: 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
      * ```ts
      * format: 'auto'        // auto-detect prettier, biome, or oxfmt
@@ -264,12 +156,9 @@ export type Config<TInput = Input> = {
      */
     format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false
     /**
-     * Auto-lint generated files after code generation completes.
+     * 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.
      *
-     * Analyzes all generated files for style/correctness issues. Use `'auto'` to detect which linter
-     * is available on your system. Pass `false` to skip linting.
-     *
-     * @default false
      * @example
      * ```ts
      * lint: 'auto'      // auto-detect oxlint, biome, or eslint
@@ -279,10 +168,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
@@ -293,10 +180,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
@@ -308,12 +193,9 @@ 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
      * ```ts
      * override: true   // regenerate everything, even existing files
@@ -323,10 +205,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
@@ -342,15 +222,11 @@ export type Config<TInput = Input> = {
    *
    * @see {@link Storage} interface for implementing custom backends.
    */
-  storage?: Storage
+  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
@@ -365,80 +241,9 @@ export type Config<TInput = Input> = {
    */
   plugins: Array<Plugin>
   /**
-   * Middleware instances that observe build events and post-process generated code.
-   *
-   * Middleware fires AFTER all plugins for each event. Perfect for tasks like:
-   * - Auditing what was generated
-   * - Adding barrel/index files
-   * - Validating output
-   * - Running custom transformations
-   *
-   * @example
-   * ```ts
-   * import { middlewareBarrel } from '@kubb/middleware-barrel'
-   *
-   * middleware: [middlewareBarrel()]
-   * ```
-   *
-   * @see {@link defineMiddleware} to create custom middleware.
-   */
-  middleware?: Array<Middleware>
-  /**
-   * Default renderer factory used by all plugins and generators.
-   * Resolution chain: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw FileNode[] mode).
-   *
-   * @example
-   * ```ts
-   * import { jsxRenderer } from '@kubb/renderer-jsx'
-   * export default defineConfig({
-   *   renderer: jsxRenderer,
-   *   plugins: [pluginTs(), pluginZod()],
-   * })
-   * ```
-   */
-  /**
-   * Renderer that converts generated AST nodes to code strings.
+   * Lifecycle hooks that run external tools (prettier, eslint, a custom script) on build events.
    *
-   * 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.
-   *
-   * Kubb Studio (https://kubb.studio) is a web-based IDE for managing API specs and generated code.
-   * Set to `true` to enable with default settings, or pass an object to customize the Studio URL.
-   *
-   * @default false  // disabled by default
-   * @example
-   * ```ts
-   * devtools: true                                   // use default Kubb Studio
-   * devtools: { studioUrl: 'https://my-studio.dev' } // custom Studio instance
-   * ```
-   */
-  devtools?:
-    | true
-    | {
-        /**
-         * Override the Kubb Studio base URL.
-         * @default 'https://kubb.studio'
-         */
-        studioUrl?: typeof DEFAULT_STUDIO_URL | (string & {})
-      }
-  /**
-   * Lifecycle hooks that execute during or after the build process.
-   *
-   * Hooks allow you to run external tools (prettier, eslint, custom scripts) based on build events.
-   * Currently supports the `done` hook which fires after all plugins and middleware complete.
+   * Currently supports the `done` hook, which fires after all plugins complete.
    *
    * @example
    * ```ts
@@ -451,11 +256,10 @@ export type Config<TInput = Input> = {
    */
   hooks?: {
     /**
-     * Command(s) to run after all plugins and middleware complete generation.
+     * Command(s) to run after all plugins finish generating, for post-processing the output.
      *
-     * Useful for post-processing: formatting, linting, copying files, or custom validation.
-     * Pass a single command string or array of command strings to run sequentially.
-     * Commands are executed relative to the `root` directory.
+     * Pass a single command string, or an array to run them in sequence.
+     * Commands run relative to the `root` directory.
      *
      * @example
      * ```ts
@@ -465,106 +269,24 @@ export type Config<TInput = Input> = {
      */
     done?: string | Array<string>
   }
-}
-
-// plugin
-
-/**
- * Type/string pattern filter for include/exclude/override matching.
- */
-type PatternFilter = {
-  type: string
-  pattern: string | RegExp
-}
-
-/**
- * Pattern filter with partial option overrides applied when the pattern matches.
- */
-type PatternOverride<TOptions> = PatternFilter & {
-  options: Omit<Partial<TOptions>, 'override'>
-}
-
-/**
- * Context for resolving filtered options for a given operation or schema node.
- *
- * @internal
- */
-export type ResolveOptionsContext<TOptions> = {
-  options: TOptions
-  exclude?: Array<PatternFilter>
-  include?: Array<PatternFilter>
-  override?: Array<PatternOverride<TOptions>>
-}
-
-/**
- * Base constraint for all plugin resolver objects.
- *
- * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
- * are injected automatically by `defineResolver` — extend this type to add custom resolution methods.
- *
- * @example
- * ```ts
- * type MyResolver = Resolver & {
- *   resolveName(node: SchemaNode): string
- *   resolveTypedName(node: SchemaNode): string
- * }
- * ```
- */
-export type Resolver = {
-  name: string
-  pluginName: Plugin['name']
-  default(name: string, type?: 'file' | 'function' | 'type' | 'const'): string
-  resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null
-  resolvePath(params: ResolverPathParams, context: ResolverContext): string
-  resolveFile(params: ResolverFileParams, context: ResolverContext): FileNode
-  resolveBanner(node: InputNode | null, context: ResolveBannerContext): string | undefined
-  resolveFooter(node: InputNode | null, context: ResolveBannerContext): string | undefined
-}
-
-export type PluginFactoryOptions<
-  /**
-   * Unique plugin name.
-   */
-  TName extends string = string,
-  /**
-   * User-facing plugin options.
-   */
-  TOptions extends object = object,
-  /**
-   * Plugin options after defaults are applied.
-   */
-  TResolvedOptions extends object = TOptions,
   /**
-   * Resolver that encapsulates naming and path-resolution helpers.
-   * Define with `defineResolver` and export alongside the plugin.
+   * The reporters available to the run, registered as instances. The host
+   * (the CLI via `--reporter`) selects which ones to trigger by `name` with {@link selectReporters}.
+   * `defineConfig` from the `kubb` package registers the built-in `cli`, `json`, and `file`
+   * reporters by default.
+   *
+   * - `cli` writes the end-of-run summary to the terminal.
+   * - `json` writes a machine-readable report to stdout, for CI.
+   * - `file` writes a debug log to `.kubb/<name>-<timestamp>.log`.
+   *
+   * @example
+   * ```ts
+   * import { cliReporter, jsonReporter } from '@kubb/core'
+   *
+   * reporters: [cliReporter, jsonReporter, myReporter]
+   * ```
    */
-  TResolver extends Resolver = Resolver,
-> = {
-  name: TName
-  options: TOptions
-  resolvedOptions: TResolvedOptions
-  resolver: TResolver
-}
-
-/**
- * Normalized plugin after setup, with runtime fields populated.
- * For internal use only — plugins use the public `Plugin` type externally.
- *
- * @internal
- */
-export type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & {
-  options: TOptions['resolvedOptions'] & {
-    output: Output
-    include?: Array<Include>
-    exclude: Array<Exclude>
-    override: Array<Override<TOptions['resolvedOptions']>>
-  }
-  resolver: TOptions['resolver']
-  transformer?: Visitor
-  renderer?: RendererFactory
-  generators?: Array<Generator>
-  apply?: (config: Config) => boolean
-  version?: string
+  reporters: Array<Reporter>
 }
 
 /**
@@ -572,7 +294,7 @@ export type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFacto
  *
  * `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`, and `hooks`.
  *
  * @example
  * ```ts
@@ -583,723 +305,525 @@ export type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFacto
  * })
  * ```
  */
-export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter'> & {
+export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters'> & {
   /**
    * Project root directory, absolute or relative to the config file location.
-   *
-   * Used as the base path for `root`-relative paths (e.g., `output.path`, file paths in hooks).
-   *
    * @default process.cwd()
-   * @example
-   * ```ts
-   * root: '/home/user/my-project'
-   * root: './my-project'  // relative to config file
-   * ```
    */
   root?: string
   /**
    * Custom parsers that convert generated AST nodes to strings (TypeScript, JSON, markdown, etc.).
-   *
-   * Each parser handles a specific file type. By default, Kubb uses `parserTs` from `@kubb/parser-ts` for TypeScript files.
-   * Pass custom parsers to support additional languages or custom formats.
-   *
-   * @default [parserTs]  // from `@kubb/parser-ts`
-   * @example
-   * ```ts
-   * import { parserTs } from '@kubb/parser-ts'
-   * import { parserJsonSchema } from '@kubb/parser-json-schema'
-   *
-   * parsers: [parserTs(), parserJsonSchema()]
-   * ```
-   *
-   * @see {@link Parser} to implement a custom parser.
+   * @default [parserTs, parserTsx, parserMd]  // applied by `defineConfig` from the `kubb` package
    */
   parsers?: Array<Parser>
   /**
-   * Adapter that parses your API specification (OpenAPI, GraphQL, AsyncAPI, etc.) into Kubb's universal AST.
-   *
-   * Pass an adapter to support different spec formats. When omitted, Kubb runs in plugin-only mode —
-   * `kubb:plugin:setup` fires and `injectFile` works, but no AST walk occurs and generator hooks
-   * (`kubb:generate:schema`, `kubb:generate:operation`) are never emitted.
-   *
-   * @example
-   * ```ts
-   * import { adapterOas } from '@kubb/adapter-oas'
-   *
-   * adapter: adapterOas()
-   * ```
-   *
-   * @see {@link Adapter} to implement a custom adapter for GraphQL or other formats.
+   * Adapter that parses your API specification into Kubb's universal AST.
+   * When omitted, Kubb runs in plugin-only mode.
    */
   adapter?: Adapter
   /**
    * Plugins that execute during the build to generate code and transform the AST.
-   *
-   * 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.).
-   *
-   * @default []  // no plugins (useful for setup/testing)
-   * @example
-   * ```ts
-   * plugins: [
-   *   pluginTs({ output: { path: './src/gen' } }),
-   *   pluginZod({ output: { path: './src/gen' } }),
-   * ]
-   * ```
-   *
-   * @see {@link definePlugin} to create a custom plugin.
+   * @default []
    */
   plugins?: Array<Plugin>
-}
-
-export type ResolveNameParams = {
-  name: string
-  pluginName?: string
-  /**
-   * Entity type being named.
-   * - `'file'` — file name (camelCase)
-   * - `'function'` — exported function name (camelCase)
-   * - `'type'` — TypeScript type name (PascalCase)
-   * - `'const'` — variable name (camelCase)
-   */
-  type?: 'file' | 'function' | 'type' | 'const'
-}
-/**
- * Context object passed to generator `schema`, `operation`, and `operations` methods.
- *
- * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
- * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
- * filtering for individual schema/operation calls, or plugin-level options for operations.
- */
-export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
   /**
-   * Absolute path to the current plugin's output directory.
-   */
-  root: string
-  /**
-   * Determine output mode based on the output config.
-   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
-   */
-  getMode: (output: { path: string }) => 'single' | 'split'
-  driver: PluginDriver
-  /**
-   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
-   */
-  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
-  getPlugin(name: string): Plugin | undefined
-  /**
-   * Get a plugin by name, throws an error if not found.
-   */
-  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>
-  requirePlugin(name: string): Plugin
-  /**
-   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
-   */
-  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver']
-  getResolver(name: string): Resolver
-  /**
-   * Add files only if they don't exist.
-   */
-  addFile: (...file: Array<FileNode>) => Promise<void>
-  /**
-   * Merge sources into the same output file.
-   */
-  upsertFile: (...file: Array<FileNode>) => Promise<void>
-  hooks: AsyncEventEmitter<KubbHooks>
-  /**
-   * The current plugin instance.
-   */
-  plugin: Plugin<TOptions>
-  /**
-   * The current plugin's resolver.
-   */
-  resolver: TOptions['resolver']
-  /**
-   * The current plugin's transformer.
-   */
-  transformer: Visitor | undefined
-  /**
-   * Emit a warning.
-   */
-  warn: (message: string) => void
-  /**
-   * Emit an error.
-   */
-  error: (error: string | Error) => void
-  /**
-   * Emit an info message.
-   */
-  info: (message: string) => void
-  /**
-   * Open the current input node in Kubb Studio.
-   */
-  openInStudio: (options?: DevtoolsOptions) => Promise<void>
-  /**
-   * The configured adapter instance.
-   */
-  adapter: Adapter
-  /**
-   * The universal `InputNode` produced by the adapter.
+   * Storage backend that controls where and how generated files are persisted.
+   * @default fsStorage()
    */
-  inputNode: InputNode
+  storage?: Storage
   /**
-   * Resolved options after exclude/include/override filtering.
+   * Reporters available to the run. `defineConfig` registers the built-in `cli`, `json`, and
+   * `file` reporters when omitted.
+   * @default [cliReporter, jsonReporter, fileReporter]  // applied by `defineConfig` from the `kubb` package
    */
-  options: TOptions['resolvedOptions']
+  reporters?: Array<Reporter>
 }
-/**
- * Output configuration for generated files.
- */
-export type Output<_TOptions = unknown> = {
-  /**
-   * Output folder or file path for generated code.
-   */
-  path: string
-  /**
-   * Text or function prepended to every generated file.
-   * When a function, receives the current `InputNode` and returns a string.
-   */
-  banner?: string | ((node?: InputNode) => string)
-  /**
-   * Text or function appended to every generated file.
-   * When a function, receives the current `InputNode` and returns a string.
-   */
-  footer?: string | ((node?: InputNode) => string)
-  /**
-   * Whether to override existing external files if they already exist.
-   * @default false
-   */
-  override?: boolean
-} & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>
 
-export type Group = {
-  /**
-   * How to group files into subdirectories.
-   * - `'tag'` — group by OpenAPI tags
-   * - `'path'` — group by OpenAPI paths
-   */
-  type: 'tag' | 'path'
-  /**
-   * Function that returns the subdirectory name for a group value.
-   * Defaults to `${camelCase(group)}Controller` for tags, first path segment for paths.
-   */
-  name?: (context: { group: string }) => string
-}
+declare global {
+  namespace Kubb {
+    /**
+     * Registry that maps plugin names to their `PluginFactoryOptions`.
+     * Augment this interface in each plugin's `types.ts` to enable automatic
+     * typing for `getPlugin` and `requirePlugin`.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-ts/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginRegistry {
+     *       'plugin-ts': PluginTs
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginRegistry {}
 
-export type LoggerOptions = {
-  /**
-   * Log level for output verbosity.
-   * @default 3
-   */
-  logLevel: (typeof logLevel)[keyof typeof logLevel]
+    /**
+     * Extension point for root `Config['output']` options.
+     * Augment the `output` key in plugin packages to add extra fields
+     * to the global output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-barrel/src/plugin.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface ConfigOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').BarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface ConfigOptionsRegistry {}
+
+    /**
+     * Extension point for per-plugin `Output` options.
+     * Augment the `output` key in plugin packages to add extra fields
+     * to the per-plugin output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-barrel/src/plugin.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').PluginBarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginOptionsRegistry {}
+  }
 }
 
 /**
- * Shared context passed to plugins, parsers, and other internals.
+ * Lifecycle events emitted during Kubb code generation.
+ * Attach listeners before calling `setup()` or `build()` to observe and react to build progress.
+ *
+ * @example
+ * ```ts
+ * kubb.hooks.on('kubb:lifecycle:start', () => {
+ *   console.log('Starting Kubb generation')
+ * })
+ *
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
+ *   console.log(`${plugin.name} completed in ${duration}ms`)
+ * })
+ * ```
  */
-export type LoggerContext = AsyncEventEmitter<KubbHooks>
-
-export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
-  name: string
-  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>
+export interface KubbHooks {
+  'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext]
+  'kubb:lifecycle:end': []
+  'kubb:generation:start': [ctx: KubbGenerationStartContext]
+  'kubb:generation:end': [ctx: KubbGenerationEndContext]
+  'kubb:format:start': []
+  'kubb:format:end': []
+  'kubb:lint:start': []
+  'kubb:lint:end': []
+  'kubb:hooks:start': []
+  'kubb:hooks:end': []
+  'kubb:hook:start': [ctx: KubbHookStartContext]
+  'kubb:hook:line': [ctx: KubbHookLineContext]
+  'kubb:hook:end': [ctx: KubbHookEndContext]
+  'kubb:info': [ctx: KubbInfoContext]
+  'kubb:error': [ctx: KubbErrorContext]
+  'kubb:success': [ctx: KubbSuccessContext]
+  'kubb:warn': [ctx: KubbWarnContext]
+  'kubb:diagnostic': [ctx: KubbDiagnosticContext]
+  'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext]
+  'kubb:files:processing:update': [ctx: KubbFilesProcessingUpdateContext]
+  'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext]
+  'kubb:plugin:start': [ctx: KubbPluginStartContext]
+  'kubb:plugin:end': [ctx: KubbPluginEndContext]
+  'kubb:plugin:setup': [ctx: KubbPluginSetupContext]
+  'kubb:build:start': [ctx: KubbBuildStartContext]
+  'kubb:plugins:end': [ctx: KubbPluginsEndContext]
+  'kubb:build:end': [ctx: KubbBuildEndContext]
+  'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext]
+  'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext]
+  'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext]
 }
 
-export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>
-
-export type { Storage } from './createStorage.ts'
-export type { Generator } from './defineGenerator.ts'
-export type { Middleware } from './defineMiddleware.ts'
-export type { Plugin } from './definePlugin.ts'
-export type { Kubb, KubbHooks } from './Kubb.ts'
-
-/**
- * Context for hook-style plugin `kubb:plugin:setup` handler.
- * Provides methods to register generators, configure resolvers, transformers, and renderers.
- */
-export type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
-  /**
-   * Register a generator dynamically. Generators fire during the AST walk (schema/operation/operations)
-   * just like generators declared statically on `createPlugin`.
-   */
-  addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void
-  /**
-   * Set or override the resolver for this plugin.
-   * The resolver controls file naming and path resolution.
-   */
-  setResolver(resolver: Partial<TFactory['resolver']>): void
-  /**
-   * 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.
-   */
-  setOptions(options: TFactory['resolvedOptions']): void
-  /**
-   * Inject a raw file into the build output, bypassing the generation pipeline.
-   */
-  injectFile(userFileNode: UserFileNode): void
-  /**
-   * Merge a partial config update into the current build configuration.
-   */
-  updateConfig(config: Partial<Config>): void
+export type KubbBuildStartContext = {
   /**
-   * The resolved build configuration at setup time.
+   * Resolved configuration for this build.
    */
   config: Config
   /**
-   * The plugin's user-provided options.
+   * Adapter that parsed the input into the universal AST.
    */
-  options: TFactory['options']
-}
-
-/**
- * Context for hook-style plugin `kubb:build:start` handler.
- * Fires immediately before the plugin execution loop begins.
- */
-export type KubbBuildStartContext = {
-  config: Config
   adapter: Adapter
-  inputNode: InputNode
   /**
-   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
+   * Metadata about the parsed document (title, version, base URL, circular schema names, enum names).
+   * To observe individual schemas and operations use the `kubb:generate:schema` / `kubb:generate:operation` hooks.
+   */
+  meta: InputMeta | undefined
+  /**
+   * Looks up a registered plugin by name, typed by the plugin registry.
    */
   getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
   getPlugin(name: string): Plugin | undefined
   /**
-   * Get all files currently in the file manager.
-   * Call this lazily (e.g. in `kubb:plugin:end`) to see files added by prior plugins.
+   * Snapshot of all files accumulated so far.
    */
   readonly files: ReadonlyArray<FileNode>
   /**
-   * Upsert one or more files into the file manager.
-   * Files with the same path are merged; new files are appended.
-   * Safe to call at any point during the plugin lifecycle, including inside `kubb:plugin:end`.
+   * Adds or merges one or more files into the file manager.
    */
   upsertFile: (...files: Array<FileNode>) => void
 }
 
-/**
- * Context for `kubb:plugins:end` handlers.
- * Fires after plugins run and per-plugin barrels are written, before final write to disk.
- * Middleware that needs final files (e.g. root barrel) use this event.
- */
 export type KubbPluginsEndContext = {
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config
   /**
-   * All files currently in the file manager (lazy snapshot).
+   * Snapshot of all files accumulated across all plugins.
    */
   readonly files: ReadonlyArray<FileNode>
   /**
-   * Upsert files into the file manager.
-   * Files added here are included in the write pass.
+   * Adds or merges one or more files into the file manager.
    */
   upsertFile: (...files: Array<FileNode>) => void
 }
 
-/**
- * Context for hook-style plugin `kubb:build:end` handler.
- * Fires after all files have been written to disk.
- */
 export type KubbBuildEndContext = {
+  /**
+   * All files generated during this build.
+   */
   files: Array<FileNode>
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config
+  /**
+   * Absolute path to the output directory.
+   */
   outputDir: string
 }
 
 export type KubbLifecycleStartContext = {
+  /**
+   * Current Kubb version string.
+   */
   version: string
 }
 
-export type KubbConfigEndContext = {
-  configs: Array<Config>
-}
-
 export type KubbGenerationStartContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config
 }
 
 export type KubbGenerationEndContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config
-  files: Array<FileNode>
-  sources: Map<string, string>
-}
-
-export type KubbGenerationSummaryContext = {
-  config: Config
-  failedPlugins: Set<{ plugin: Plugin; error: Error }>
-  status: 'success' | 'failed'
-  hrStart: [number, number]
-  filesCreated: number
-  pluginTimings?: Map<Plugin['name'], number>
-}
-
-export type KubbVersionNewContext = {
-  currentVersion: string
-  latestVersion: string
+  /**
+   * Read-only view of the files written during this build.
+   * Reads go directly to `config.storage`, nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * `const code = await storage.getItem('/src/gen/pet.ts')`
+   *
+   * @example Walk every generated file
+   * ```ts
+   * for (const path of await storage.getKeys()) {
+   *   const code = await storage.getItem(path)
+   * }
+   * ```
+   */
+  storage: Storage
+  /**
+   * Diagnostics collected during the build: error/warning/info problems plus a
+   * `performance` diagnostic per plugin. The end-of-run summary derives its failure counts
+   * and per-plugin timings from these. Set by the CLI runner, omitted by other callers.
+   */
+  diagnostics?: Array<Diagnostic>
+  /**
+   * `'success'` when all plugins completed without errors, `'failed'` otherwise.
+   */
+  status?: 'success' | 'failed'
+  /**
+   * High-resolution start time from `process.hrtime()`, used to compute the elapsed time.
+   */
+  hrStart?: [number, number]
+  /**
+   * Total number of files created during this run.
+   */
+  filesCreated?: number
 }
 
 export type KubbInfoContext = {
+  /**
+   * Human-readable info message.
+   */
   message: string
+  /**
+   * Optional supplementary detail.
+   */
   info?: string
 }
 
 export type KubbErrorContext = {
+  /**
+   * The caught error.
+   */
   error: Error
+  /**
+   * Optional structured metadata for additional context.
+   */
   meta?: Record<string, unknown>
 }
 
 export type KubbSuccessContext = {
+  /**
+   * Human-readable success message.
+   */
   message: string
+  /**
+   * Optional supplementary detail.
+   */
   info?: string
 }
 
 export type KubbWarnContext = {
+  /**
+   * Human-readable warning message.
+   */
   message: string
+  /**
+   * Optional supplementary detail.
+   */
   info?: string
 }
 
-export type KubbDebugContext = {
-  date: Date
-  logs: Array<string>
-  fileName?: string
+export type KubbDiagnosticContext = {
+  /**
+   * The structured diagnostic to render: a build problem or a version-update notice.
+   */
+  diagnostic: ProblemDiagnostic | UpdateDiagnostic
 }
 
 export type KubbFilesProcessingStartContext = {
+  /**
+   * Files about to be serialized and written.
+   */
   files: Array<FileNode>
 }
 
-export type KubbFileProcessingUpdateContext = {
+export type KubbFileProcessingUpdate = {
   /**
-   * Number of files processed.
+   * Number of files processed so far in this batch.
    */
   processed: number
   /**
-   * Total files to process.
+   * Total number of files in this batch.
    */
   total: number
   /**
-   * Processing percentage (0–100).
+   * Completion percentage, `0` to `100`.
    */
   percentage: number
   /**
-   * Optional source identifier.
+   * Serialized file content, or `undefined` when the file produced no output.
    */
   source?: string
   /**
-   * The file being processed.
+   * The file that was just processed.
    */
   file: FileNode
   /**
-   * The current build configuration.
+   * Resolved configuration for this build.
    */
   config: Config
 }
 
-export type KubbFilesProcessingEndContext = {
-  files: Array<FileNode>
-}
-
-export type KubbPluginStartContext = {
-  plugin: NormalizedPlugin
-}
-
-export type KubbPluginEndContext = {
-  plugin: NormalizedPlugin
-  duration: number
-  success: boolean
-  error?: Error
-  config: Config
+export type KubbFilesProcessingUpdateContext = {
   /**
-   * Returns all files currently in the file manager (lazy snapshot).
-   * Includes files added by plugins that have already run.
+   * All files processed in this flush chunk.
    */
-  readonly files: ReadonlyArray<FileNode>
+  files: Array<KubbFileProcessingUpdate>
+}
+
+export type KubbFilesProcessingEndContext = {
   /**
-   * Upsert one or more files into the file manager.
+   * All files that were serialized in this batch.
    */
-  upsertFile: (...files: Array<FileNode>) => void
+  files: Array<FileNode>
 }
 
 export type KubbHookStartContext = {
+  /**
+   * Optional identifier for correlating start/end events.
+   */
   id?: string
-  command: string
-  args?: readonly string[]
-}
-
-export type KubbHookEndContext = {
-  id?: string
-  command: string
-  args?: readonly string[]
-  success: boolean
-  error: Error | null
-}
-
-type ByTag = {
   /**
-   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   * The shell command that is about to run.
    */
-  type: 'tag'
+  command: string
   /**
-   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   * Parsed argument list, when available.
    */
-  pattern: string | RegExp
+  args?: ReadonlyArray<string>
 }
 
-type ByOperationId = {
+/**
+ * Emitted for each line streamed from a hook's stdout while it runs.
+ * A logger correlates the line to its active UI element via `id`.
+ */
+export type KubbHookLineContext = {
   /**
-   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   * Identifier matching the corresponding `kubb:hook:start` event.
    */
-  type: 'operationId'
+  id: string
   /**
-   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   * A single streamed stdout line, without its trailing newline.
    */
-  pattern: string | RegExp
+  line: string
 }
 
-type ByPath = {
-  /**
-   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
-   */
-  type: 'path'
+export type KubbHookEndContext = {
   /**
-   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   * Optional identifier matching the corresponding `kubb:hook:start` event.
    */
-  pattern: string | RegExp
-}
-
-type ByMethod = {
+  id?: string
   /**
-   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   * The shell command that ran.
    */
-  type: 'method'
+  command: string
   /**
-   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   * Parsed argument list, when available.
    */
-  pattern: HttpMethod | RegExp
-}
-// TODO implement as alternative for ByMethod
-// type ByMethods = {
-//   type: 'methods'
-//   pattern: Array<HttpMethod>
-// }
-
-type BySchemaName = {
+  args?: ReadonlyArray<string>
   /**
-   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   * `true` when the command exited with code `0`.
    */
-  type: 'schemaName'
+  success: boolean
   /**
-   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   * Error thrown by the command, or `null` on success.
    */
-  pattern: string | RegExp
-}
-
-type ByContentType = {
+  error: Error | null
   /**
-   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   * Captured stdout from the process, populated when it exits non-zero.
    */
-  type: 'contentType'
+  stdout?: string
   /**
-   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   * Captured stderr from the process, populated when it exits non-zero.
    */
-  pattern: string | RegExp
+  stderr?: string
 }
 
 /**
- * A pattern filter that prevents matching nodes from being generated.
- *
- * Use to skip code generation for specific operations or schemas. For example, exclude deprecated endpoints
- * or internal-only schemas. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
- *
- * @example
- * ```ts
- * exclude: [
- *   { type: 'tag', pattern: 'internal' },          // skip "internal" tag
- *   { type: 'path', pattern: /^\/admin/ },          // skip all /admin endpoints
- *   { type: 'operationId', pattern: 'deprecated_*' }  // skip operationIds matching pattern
- * ]
- * ```
- */
-export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
-
-/**
- * A pattern filter that restricts generation to only matching nodes.
- *
- * Use to generate code for a subset of operations or schemas. For example, only generate for a specific service
- * tag or only for "production" endpoints. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
- *
- * @example
- * ```ts
- * include: [
- *   { type: 'tag', pattern: 'public' },        // generate only "public" tag
- *   { type: 'path', pattern: /^\/api\/v1/ },   // generate only v1 endpoints
- * ]
- * ```
- */
-export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
-
-/**
- * A pattern filter paired with partial option overrides applied when the pattern matches.
- *
- * Use to customize generation for specific operations or schemas. For example, apply different output paths
- * for different tags, or use custom resolver functions per operation. Can filter by tag, operationId, path,
- * HTTP method, schema name, or content type.
- *
- * @example
- * ```ts
- * override: [
- *   {
- *     type: 'tag',
- *     pattern: 'admin',
- *     options: { output: { path: './src/gen/admin' } }  // admin APIs go to separate folder
- *   },
- *   {
- *     type: 'operationId',
- *     pattern: 'listPets',
- *     options: { exclude: true }  // skip this specific operation
- *   }
- * ]
- * ```
- */
-export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
-  //TODO should be options: Omit<Partial<TOptions>, 'override'>
-  options: Partial<TOptions>
-}
-
-/**
- * File-specific parameters for `Resolver.resolvePath`.
- *
- * Pass alongside a `ResolverContext` to identify which file to resolve.
- * Provide `tag` for tag-based grouping or `path` for path-based grouping.
- *
- * @example
- * ```ts
- * resolver.resolvePath(
- *   { baseName: 'petTypes.ts', tag: 'pets' },
- *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
- * )
- * // → '/src/types/petsController/petTypes.ts'
- * ```
+ * CLI options derived from command-line flags.
  */
-export type ResolverPathParams = {
-  baseName: FileNode['baseName']
-  pathMode?: 'single' | 'split'
+export type CLIOptions = {
   /**
-   * Tag value used when `group.type === 'tag'`.
+   * Path to the Kubb config file.
    */
-  tag?: string
+  config?: string
   /**
-   * Path value used when `group.type === 'path'`.
+   * OpenAPI input path passed as the positional argument to `kubb generate`.
+   * Overrides `config.input.path` when set.
    */
-  path?: string
-}
-
-/**
- * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
- *
- * Describes where on disk output is rooted, which output config is active, and the optional
- * grouping strategy that controls subdirectory layout.
- *
- * @example
- * ```ts
- * const context: ResolverContext = {
- *   root: config.root,
- *   output,
- *   group,
- * }
- * ```
- */
-export type ResolverContext = {
-  root: string
-  output: Output
-  group?: Group
+  input?: string
   /**
-   * Plugin name used to populate `meta.pluginName` on the resolved file.
+   * Re-run generation whenever input files change.
    */
-  pluginName?: string
-}
-
-/**
- * File-specific parameters for `Resolver.resolveFile`.
- *
- * Pass alongside a `ResolverContext` to fully describe the file to resolve.
- * `tag` and `path` are used only when a matching `group` is present in the context.
- *
- * @example
- * ```ts
- * resolver.resolveFile(
- *   { name: 'listPets', extname: '.ts', tag: 'pets' },
- *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
- * )
- * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
- * ```
- */
-export type ResolverFileParams = {
-  name: string
-  extname: FileNode['extname']
+  watch?: boolean
   /**
-   * Tag value used when `group.type === 'tag'`.
+   * Controls how much output the CLI prints.
+   *
+   * @default 'info'
    */
-  tag?: string
+  logLevel?: 'silent' | 'info' | 'verbose'
   /**
-   * Path value used when `group.type === 'path'`.
+   * Reporters selected on the CLI via `--reporter`, overriding `config.reporters`.
    */
-  path?: string
+  reporters?: Array<ReporterName>
 }
 
 /**
- * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
- *
- * `output` is optional — not every plugin configures a banner/footer.
- * `config` carries the global Kubb config, used to derive the default Kubb banner.
- *
- * @example
- * ```ts
- * resolver.resolveBanner(inputNode, { output: { banner: '// generated' }, config })
- * // → '// generated'
- * ```
+ * All accepted forms of a Kubb configuration.
+ * Accepts `Config`/`Config[]`/promise or a factory (optionally receiving `TCliOptions`).
  */
-export type ResolveBannerContext = {
-  output?: Pick<Output, 'banner' | 'footer'>
-  config: Config
-}
+export type PossibleConfig<TCliOptions = undefined> =
+  | PossiblePromise<Config | Array<Config>>
+  | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Array<Config>>)
 
 /**
- * CLI options derived from command-line flags.
+ * Full output produced by a successful or failed build.
  */
-export type CLIOptions = {
+export type BuildOutput = {
   /**
-   * Path to `kubb.config.js`.
+   * Structured diagnostics collected during the build: error/warning/info problems
+   * (each with a code, severity, and where known a JSON-pointer location) plus a
+   * `performance` diagnostic per plugin. Includes a top-level diagnostic when the build
+   * threw before completing. Use {@link Diagnostics.hasError} to test for failure.
    */
-  config?: string
+  diagnostics: Array<Diagnostic>
   /**
-   * Enable watch mode for input files.
+   * All files generated during this build.
    */
-  watch?: boolean
+  files: Array<FileNode>
   /**
-   * Logging verbosity for CLI usage.
-   * @default 'silent'
+   * The plugin driver that orchestrated this build.
    */
-  logLevel?: 'silent' | 'info' | 'debug'
+  driver: KubbDriver
+  /**
+   * Read-only view of every file written during this build.
+   * Reads go straight to `config.storage`, nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * `const code = await buildOutput.storage.getItem('/src/gen/pet.ts')`
+   *
+   * @example List all generated file paths
+   * `const paths = await buildOutput.storage.getKeys()`
+   */
+  storage: Storage
 }
 
-/**
- * All accepted forms of a Kubb configuration.
- *
- * Config is always `@kubb/core` {@link Config}.
- * - `PossibleConfig` accepts `Config`/`Config[]`/promise or a no-arg config factory.
- * - `PossibleConfig<TCliOptions>` accepts the same config forms or a config factory receiving `TCliOptions`.
- */
-export type PossibleConfig<TCliOptions = undefined> =
-  | PossiblePromise<Config | Config[]>
-  | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>)
-
-export type { BuildOutput } from './createKubb.ts'
+export type { Adapter, AdapterFactoryOptions, AdapterSource } from './createAdapter.ts'
+export type {
+  Diagnostic,
+  DiagnosticByCode,
+  DiagnosticDoc,
+  DiagnosticKind,
+  DiagnosticLocation,
+  DiagnosticSeverity,
+  PerformanceDiagnostic,
+  ProblemCode,
+  ProblemDiagnostic,
+  SerializedDiagnostic,
+  UpdateDiagnostic,
+} from './diagnostics.ts'
+export type { Kubb } from './createKubb.ts'
+export type { GenerationResult, Reporter, ReporterContext, ReporterName, UserReporter } from './createReporter.ts'
+export type { Renderer, RendererFactory } from './createRenderer.ts'
+export type { Storage } from './createStorage.ts'
+export type { FileProcessorHooks, ParsedFile } from './FileProcessor.ts'
+export type { Generator, GeneratorContext } from './defineGenerator.ts'
 export type { Parser } from './defineParser.ts'
+export type { Exclude, Group, Include, Output, OutputMode, OutputOptions, Override } from './definePlugin.ts'
+export type { KubbPluginEndContext, KubbPluginSetupContext, KubbPluginStartContext, NormalizedPlugin, Plugin, PluginFactoryOptions } from './definePlugin.ts'
+export type {
+  BannerMeta,
+  ResolveBannerContext,
+  ResolveBannerFile,
+  ResolveOptionsContext,
+  Resolver,
+  ResolverContext,
+  ResolverFileParams,
+  ResolverPathParams,
+} from './defineResolver.ts'