@kubb/core 5.0.0-alpha.9 → 5.0.0-beta.75

package/src/types.ts

@@ -1,241 +1,420 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { Node, RootNode, SchemaNode } from '@kubb/ast/types'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+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 { Storage } from './createStorage.ts'
-import type { KubbEvents } from './Kubb.ts'
+import type { Generator } from './defineGenerator.ts'
+import type { Middleware } from './defineMiddleware.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 { Printer, PrinterFactoryOptions } from '@kubb/ast/types'
-
-declare global {
-  namespace Kubb {
-    interface PluginContext {}
-  }
-}
+export type { Renderer, RendererFactory } from './createRenderer.ts'
 
 /**
- * Config used in `kubb.config.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.
  *
- * @example
- * import { defineConfig } from '@kubb/core'
- * export default defineConfig({
- * ...
- * })
+ * @internal
  */
-export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins'> & {
-  /**
-   * The project root directory, which can be either an absolute path or a path relative to the location of your `kubb.config.ts` file.
-   * @default process.cwd()
-   */
-  root?: string
-  /**
-   * An array of Kubb plugins used for generation. Each plugin may have additional configurable options (defined within the plugin itself). If a plugin relies on another plugin, an error will occur if the required dependency is missing. Refer to “pre” for more details.
-   */
-  // inject needs to be omitted because else we have a clash with the PluginDriver instance
-  plugins?: Array<Omit<UnknownUserPlugin, 'inject'>>
-}
+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.
+ */
 export type InputPath = {
   /**
-   * Specify your Swagger/OpenAPI file, either as an absolute path or a path relative to the root.
+   * Path to your Swagger/OpenAPI file, absolute or relative to the config file location.
+   *
+   * @example
+   * ```ts
+   * { path: './petstore.yaml' }
+   * { path: '/absolute/path/to/openapi.json' }
+   * ```
    */
   path: string
 }
 
+/**
+ * Inline 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.
+ */
 export type InputData = {
   /**
-   * A `string` or `object` that contains your Swagger/OpenAPI data.
+   * Swagger/OpenAPI data as a string (YAML/JSON) or a parsed object.
+   *
+   * @example
+   * ```ts
+   * { data: fs.readFileSync('./openapi.yaml', 'utf8') }
+   * { data: { openapi: '3.1.0', info: { ... } } }
+   * ```
    */
   data: string | unknown
 }
 
-type Input = InputPath | InputData | Array<InputPath>
+type Input = InputPath | InputData
 
 /**
- * The raw source passed to an adapter's `parse` function.
- * Mirrors the shape of `Config['input']` with paths already resolved to absolute.
+ * 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> }
 
 /**
- * Type parameters for an adapter definition.
+ * Generic type parameters for an adapter definition.
  *
- * Mirrors `PluginFactoryOptions` but scoped to the adapter lifecycle:
- * - `TName` — unique string identifier (e.g. `'oas'`, `'asyncapi'`)
- * - `TOptions` — raw user-facing options passed to the adapter factory
- * - `TResolvedOptions` — defaults applied; what the adapter stores as `options`
+ * - `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> = {
+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
 }
 
 /**
- * An adapter converts a source file or data into a `@kubb/ast` `RootNode`.
+ * Adapter that converts input files or data into an `InputNode`.
  *
- * Adapters are the single entry-point for different schema formats
- * (OpenAPI, AsyncAPI, Drizzle, …) and produce the universal `RootNode`
- * that all Kubb plugins consume.
+ * Adapters parse different schema formats (OpenAPI, AsyncAPI, Drizzle, etc.) into Kubb's
+ * universal intermediate representation that all plugins consume.
  *
  * @example
  * ```ts
- * import { oasAdapter } from '@kubb/adapter-oas'
+ * import { adapterOas } from '@kubb/adapter-oas'
  *
  * export default defineConfig({
- *   adapter: adapterOas(),         // default — OpenAPI / Swagger
- *   input:   { path: './openapi.yaml' },
+ *   adapter: adapterOas(),
+ *   input: { path: './openapi.yaml' },
  *   plugins: [pluginTs(), pluginZod()],
  * })
  * ```
  */
 export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
-  /** Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`. */
+  /**
+   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
+   */
   name: TOptions['name']
-  /** Resolved options (after defaults have been applied). */
+  /**
+   * Resolved adapter options after defaults have been applied.
+   */
   options: TOptions['resolvedOptions']
-  /** Convert the raw source into a universal `RootNode`. */
-  parse: (source: AdapterSource) => PossiblePromise<RootNode>
   /**
-   * Extracts `KubbFile.Import` entries needed by a `SchemaNode` tree.
-   * Populated after the first `parse()` call. Returns an empty array before that.
+   * 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 the `{ name, path }` pair for the import, or `undefined` to skip it.
+   * return `{ name, path }` for the import, or `undefined` to skip it.
    */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<KubbFile.Import>
+  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<ImportNode>
 }
 
-export type BarrelType = 'all' | 'named' | 'propagate'
-
 export type DevtoolsOptions = {
   /**
-   * Open the AST inspector view (`/ast`) in Kubb Studio.
-   * When `false`, opens the main Studio page instead.
+   * 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.
+ *
  * @private
  */
 export type Config<TInput = Input> = {
   /**
-   * The name to display in the CLI output.
+   * Display name for this configuration in CLI output and logs.
+   * Useful when running multiple builds with `defineConfig` arrays.
+   *
+   * @example
+   * ```ts
+   * name: 'api-client'
+   * ```
    */
   name?: string
   /**
-   * The project root directory, which can be either an absolute path or a path relative to the location of your `kubb.config.ts` file.
+   * Project root directory, absolute or relative to the config file.
    * @default process.cwd()
    */
   root: string
   /**
-   * Adapter that converts the input file into a `@kubb/ast` `RootNode` — the universal
-   * intermediate representation consumed by all Kubb plugins.
+   * 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`.
    *
-   * - Omit (or pass `undefined`) to use the built-in OpenAPI/Swagger adapter.
-   * - Use `@kubb/adapter-oas` for explicit OpenAPI configuration (validate, contentType, …).
-   * - Use `@kubb/adapter-drizzle` or `@kubb/adapter-asyncapi` for other formats.
+   * @default [parserTs] from `@kubb/parser-ts`
+   * @example
+   * ```ts
+   * import { parserTs, tsxParser } from '@kubb/parser-ts'
+   * export default defineConfig({
+   *   parsers: [parserTs, tsxParser],
+   * })
+   * ```
+   */
+  parsers: Array<Parser>
+  /**
+   * Adapter that parses input files into the universal `InputNode` representation.
+   * Use `@kubb/adapter-oas` for OpenAPI/Swagger or `@kubb/adapter-asyncapi` for other formats.
    *
    * @example
    * ```ts
-   * import { drizzleAdapter } from '@kubb/adapter-drizzle'
+   * import { adapterOas } from '@kubb/adapter-oas'
    * export default defineConfig({
-   *   adapter: drizzleAdapter(),
-   *   input: { path: './src/schema.ts' },
+   *   adapter: adapterOas(),
+   *   input: { path: './petstore.yaml' },
    * })
    * ```
    */
-  adapter?: Adapter
+  adapter: Adapter
   /**
-   * You can use either `input.path` or `input.data`, depending on your specific needs.
+   * Source file or data to generate code from.
+   * Use `input.path` for a file path or `input.data` for inline data.
    */
   input: TInput
   output: {
     /**
-     * The path where all generated files receives exported.
-     * This can be an absolute path or a path relative to the specified root option.
+     * 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.).
+     *
+     * @example
+     * ```ts
+     * output: {
+     *   path: './src/gen',  // generates ./src/gen/api.ts, ./src/gen/types.ts, etc.
+     * }
+     * ```
      */
     path: string
     /**
-     * Clean the output directory before each build.
+     * 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.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * clean: true  // wipes ./src/gen/* before generating
+     * ```
      */
     clean?: boolean
     /**
-     * Save files to the file system.
+     * Persists generated files to the file system.
+     *
      * @default true
-     * @deprecated Use `storage` to control where files are written.
+     * @deprecated Use `storage` option to control where files are written instead.
      */
     write?: boolean
     /**
-     * Storage backend for generated files.
-     * Defaults to `fsStorage()` — the built-in filesystem driver.
-     * Accepts any object implementing the {@link Storage} interface.
-     * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
-     * @default fsStorage()
+     * 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).
+     *
+     * @default false
      * @example
      * ```ts
-     * import { memoryStorage } from '@kubb/core'
-     * storage: memoryStorage()
+     * format: 'auto'        // auto-detect prettier, biome, or oxfmt
+     * format: 'prettier'    // force prettier
+     * format: false         // skip formatting
      * ```
      */
-    storage?: Storage
-    /**
-     * Specifies the formatting tool to be used.
-     * - 'auto' automatically detects and uses biome or prettier (in that order of preference).
-     * - 'prettier' uses Prettier for code formatting.
-     * - 'biome' uses Biome for code formatting.
-     * - 'oxfmt' uses Oxfmt for code formatting.
-     * - false disables code formatting.
-     * @default 'prettier'
-     */
     format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false
     /**
-     * Specifies the linter that should be used to analyze the code.
-     * - 'auto' automatically detects and uses biome, oxlint, or eslint (in that order of preference).
-     * - 'eslint' uses ESLint for linting.
-     * - 'biome' uses Biome for linting.
-     * - 'oxlint' uses Oxlint for linting.
-     * - false disables linting.
-     * @default 'auto'
+     * 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.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * lint: 'auto'      // auto-detect oxlint, biome, or eslint
+     * lint: 'eslint'    // force eslint
+     * lint: false       // skip linting
+     * ```
      */
     lint?: 'auto' | 'eslint' | 'biome' | 'oxlint' | false
     /**
-     * Overrides the extension for generated imports and exports. By default, each plugin adds an extension.
-     * @default { '.ts': '.ts'}
-     */
-    extension?: Record<KubbFile.Extname, KubbFile.Extname | ''>
-    /**
-     * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
-     * @default 'named'
+     * 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.
+     *
+     * @default { '.ts': '.ts' }
+     * @example
+     * ```ts
+     * extension: { '.ts': '.js' }      // generates import './api.js' instead of './api.ts'
+     * extension: { '.ts': '', '.tsx': '.jsx' }
+     * ```
      */
-    barrelType?: Exclude<BarrelType, 'propagate'> | false
+    extension?: Record<FileNode['extname'], FileNode['extname'] | ''>
     /**
-     * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
-     * - 'simple' adds banner with link to Kubb.
-     * - 'full' adds source, title, description, and OpenAPI version.
-     * - false disables banner generation.
+     * 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.
+     *
      * @default 'simple'
+     * @example
+     * ```ts
+     * defaultBanner: 'simple'   // "This file was autogenerated by Kubb"
+     * defaultBanner: 'full'     // adds source, title, description, API version
+     * defaultBanner: false      // no banner
+     * ```
      */
     defaultBanner?: 'simple' | 'full' | false
     /**
-     * Whether to override existing external files if they already exist.
-     * When setting the option in the global configuration, all plugins inherit the same behavior by default.
-     * However, all plugins also have an `output.override` option, which can be used to override the behavior for a specific plugin.
+     * 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.
+     *
      * @default false
+     * @example
+     * ```ts
+     * override: true   // regenerate everything, even existing files
+     * override: false  // skip files that already exist
+     * ```
      */
     override?: boolean
-  }
+  } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>
   /**
-   * An array of Kubb plugins that used in the generation.
-   * Each plugin may include additional configurable options(defined in the plugin itself).
-   * If a plugin depends on another plugin, an error is returned if the required dependency is missing. See pre for more details.
+   * 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.
+   *
+   * @default fsStorage()
+   * @example
+   * ```ts
+   * import { memoryStorage } from '@kubb/core'
+   *
+   * // Keep generated files in memory (useful for testing, CI pipelines)
+   * storage: memoryStorage()
+   *
+   * // Use custom S3 storage
+   * storage: myS3Storage()
+   * ```
+   *
+   * @see {@link Storage} interface for implementing custom backends.
    */
-  plugins?: Array<Plugin>
+  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.
+   *
+   * @example
+   * ```ts
+   * import { pluginTs } from '@kubb/plugin-ts'
+   * import { pluginZod } from '@kubb/plugin-zod'
+   *
+   * plugins: [
+   *   pluginTs({ output: { path: './src/gen' } }),
+   *   pluginZod({ output: { path: './src/gen' } }),
+   * ]
+   * ```
+   */
+  plugins: Array<Plugin>
+  /**
+   * 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.
+   *
+   * 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
   /**
-   * Devtools configuration for Kubb Studio integration.
+   * Kubb Studio cloud integration settings.
+   *
+   * Kubb Studio (https://studio.kubb.dev) 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
@@ -247,12 +426,33 @@ export type Config<TInput = Input> = {
         studioUrl?: typeof DEFAULT_STUDIO_URL | (string & {})
       }
   /**
-   * Hooks triggered when a specific action occurs in Kubb.
+   * 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.
+   *
+   * @example
+   * ```ts
+   * hooks: {
+   *   done: 'prettier --write "./src/gen"',      // auto-format generated files
+   *   // or multiple commands:
+   *   done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+   * }
+   * ```
    */
   hooks?: {
     /**
-     * Hook that triggers at the end of all executions.
-     * Useful for running Prettier or ESLint to format/lint your code.
+     * Command(s) to run after all plugins and middleware complete generation.
+     *
+     * 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.
+     *
+     * @example
+     * ```ts
+     * done: 'prettier --write "./src/gen"'
+     * done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+     * ```
      */
     done?: string | Array<string>
   }
@@ -260,15 +460,26 @@ export type Config<TInput = Input> = {
 
 // 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>
@@ -279,270 +490,807 @@ export type ResolveOptionsContext<TOptions> = {
 /**
  * Base constraint for all plugin resolver objects.
  *
- * `default` and `resolveOptions` are injected automatically by `defineResolver` — plugin
- * authors may override them but never need to implement them from scratch.
- * Concrete plugin resolver types extend this with their own helper methods.
+ * `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 = {
-  default(name: ResolveNameParams['name'], type?: ResolveNameParams['type']): string
+  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
 }
 
-/**
- * The user-facing subset of a `Resolver` — everything except the methods injected by
- * `defineResolver` (`default` and `resolveOptions`).
- *
- * When you pass a `UserResolver` to `defineResolver`, the standard `default` and
- * `resolveOptions` implementations are injected automatically so plugin authors never
- * need to define them by hand. Both can still be overridden by providing them explicitly.
- */
-export type UserResolver = Omit<Resolver, 'default' | 'resolveOptions'>
-
 export type PluginFactoryOptions<
   /**
-   * Name to be used for the plugin.
+   * Unique plugin name.
    */
   TName extends string = string,
   /**
-   * Options of the plugin.
+   * User-facing plugin options.
    */
   TOptions extends object = object,
   /**
-   * Options of the plugin that can be used later on, see `options` inside your plugin config.
+   * Plugin options after defaults are applied.
    */
   TResolvedOptions extends object = TOptions,
   /**
-   * Context that you want to expose to other plugins.
-   */
-  TContext = unknown,
-  /**
-   * When calling `resolvePath` you can specify better types.
-   */
-  TResolvePathOptions extends object = object,
-  /**
-   * Resolver object that encapsulates the naming and path-resolution helpers used by this plugin.
-   * Use `defineResolver` to define the resolver object and export it alongside the plugin.
+   * Resolver that encapsulates naming and path-resolution helpers.
+   * Define with `defineResolver` and export alongside the plugin.
    */
   TResolver extends Resolver = Resolver,
 > = {
   name: TName
   options: TOptions
   resolvedOptions: TResolvedOptions
-  context: TContext
-  resolvePathOptions: TResolvePathOptions
   resolver: TResolver
 }
 
-export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+/**
+ * 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
+}
+
+/**
+ * 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`.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   input: { path: './petstore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [pluginTs(), pluginZod()],
+ * })
+ * ```
+ */
+export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter'> & {
   /**
-   * Unique name used for the plugin
-   * The name of the plugin follows the format scope:foo-bar or foo-bar, adding scope: can avoid naming conflicts with other plugins.
-   * @example @kubb/typescript
+   * 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
+   * ```
    */
-  name: TOptions['name']
+  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.
+   */
+  parsers?: Array<Parser>
+  /**
+   * Adapter that parses your API specification (OpenAPI, GraphQL, AsyncAPI, etc.) into Kubb's universal AST.
+   *
+   * The adapter bridge between your input format and Kubb's internal representation. By default, uses the OAS adapter.
+   * Pass an alternative adapter (or multiple configs with different adapters) to support different spec formats.
+   *
+   * @default new OasAdapter()  // from @kubb/adapter-oas
+   * @example
+   * ```ts
+   * import { Oas } from '@kubb/adapter-oas'
+   *
+   * adapter: new Oas({ apiVersion: '3.0.0' })
+   * ```
+   *
+   * @see {@link Adapter} to implement a custom adapter for GraphQL or other formats.
+   */
+  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.
+   */
+  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
   /**
-   * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+   * The universal `InputNode` produced by the adapter.
+   */
+  inputNode: InputNode
+  /**
+   * Resolved options after exclude/include/override filtering.
    */
   options: TOptions['resolvedOptions']
+}
+/**
+ * Output configuration for generated files.
+ */
+export type Output<_TOptions = unknown> = {
+  /**
+   * Output folder or file path for generated code.
+   */
+  path: string
   /**
-   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
-   * Can be used to validate dependent plugins.
+   * Text or function prepended to every generated file.
+   * When a function, receives the current `InputNode` and returns a string.
    */
-  pre?: Array<string>
+  banner?: string | ((node?: InputNode) => string)
   /**
-   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin is executed before these plugins.
+   * 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
    */
-  post?: Array<string>
-  inject?: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context']
+  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
+}
+
+export type LoggerOptions = {
+  /**
+   * Log level for output verbosity.
+   * @default 3
+   */
+  logLevel: (typeof logLevel)[keyof typeof logLevel]
+}
+
+/**
+ * Shared context passed to plugins, parsers, and other internals.
+ */
+export type LoggerContext = AsyncEventEmitter<KubbHooks>
+
+export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
+  name: string
+  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>
 }
 
-export type UserPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = UserPlugin<TOptions> & PluginLifecycle<TOptions>
+export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>
 
-type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<string, object, object, unknown, object>>
+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'
 
-export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+/**
+ * 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> = {
   /**
-   * Unique name used for the plugin
-   * @example @kubb/typescript
+   * Register a generator dynamically. Generators fire during the AST walk (schema/operation/operations)
+   * just like generators declared statically on `createPlugin`.
    */
-  name: TOptions['name']
+  addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void
   /**
-   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
-   * Can be used to validate dependent plugins.
+   * Set or override the resolver for this plugin.
+   * The resolver controls file naming and path resolution.
    */
-  pre?: Array<string>
+  setResolver(resolver: Partial<TFactory['resolver']>): void
   /**
-   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin is executed before these plugins.
+   * Set the AST transformer to pre-process nodes before they reach generators.
    */
-  post?: Array<string>
+  setTransformer(visitor: Visitor): void
   /**
-   * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+   * Set the renderer factory to process JSX elements from generators.
    */
-  options: TOptions['resolvedOptions']
+  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
+  /**
+   * The resolved build configuration at setup time.
+   */
+  config: Config
+  /**
+   * The plugin's user-provided options.
+   */
+  options: TFactory['options']
+}
 
-  install: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => PossiblePromise<void>
+/**
+ * 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
   /**
-   * Defines a context that can be used by other plugins, see `PluginDriver` where we convert from `UserPlugin` to `Plugin` (used when calling `createPlugin`).
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
    */
-  inject: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context']
+  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.
+   */
+  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`.
+   */
+  upsertFile: (...files: Array<FileNode>) => void
 }
 
-export type PluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & PluginLifecycle<TOptions>
+/**
+ * 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 = {
+  config: Config
+  /**
+   * All files currently in the file manager (lazy snapshot).
+   */
+  readonly files: ReadonlyArray<FileNode>
+  /**
+   * Upsert files into the file manager.
+   * Files added here are included in the write pass.
+   */
+  upsertFile: (...files: Array<FileNode>) => void
+}
 
-export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+/**
+ * Context for hook-style plugin `kubb:build:end` handler.
+ * Fires after all files have been written to disk.
+ */
+export type KubbBuildEndContext = {
+  files: Array<FileNode>
+  config: Config
+  outputDir: string
+}
+
+export type KubbLifecycleStartContext = {
+  version: string
+}
+
+export type KubbConfigEndContext = {
+  configs: Array<Config>
+}
+
+export type KubbGenerationStartContext = {
+  config: Config
+}
+
+export type KubbGenerationEndContext = {
+  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
+}
+
+export type KubbInfoContext = {
+  message: string
+  info?: string
+}
+
+export type KubbErrorContext = {
+  error: Error
+  meta?: Record<string, unknown>
+}
+
+export type KubbSuccessContext = {
+  message: string
+  info?: string
+}
+
+export type KubbWarnContext = {
+  message: string
+  info?: string
+}
+
+export type KubbDebugContext = {
+  date: Date
+  logs: Array<string>
+  fileName?: string
+}
+
+export type KubbFilesProcessingStartContext = {
+  files: Array<FileNode>
+}
+
+export type KubbFileProcessingUpdateContext = {
+  /**
+   * Number of files processed.
+   */
+  processed: number
   /**
-   * Start of the lifecycle of a plugin.
-   * @type hookParallel
+   * Total files to process.
    */
-  install?: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => PossiblePromise<void>
+  total: number
   /**
-   * Resolve to a Path based on a baseName(example: `./Pet.ts`) and directory(example: `./models`).
-   * Options can als be included.
-   * @type hookFirst
-   * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
+   * Processing percentage (0–100).
    */
-  resolvePath?: (this: PluginContext<TOptions>, baseName: KubbFile.BaseName, mode?: KubbFile.Mode, options?: TOptions['resolvePathOptions']) => KubbFile.Path
+  percentage: number
   /**
-   * Resolve to a name based on a string.
-   * Useful when converting to PascalCase or camelCase.
-   * @type hookFirst
-   * @example ('pet') => 'Pet'
+   * Optional source identifier.
    */
-  resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
+  source?: string
+  /**
+   * The file being processed.
+   */
+  file: FileNode
+  /**
+   * The current build configuration.
+   */
+  config: Config
 }
 
-export type PluginLifecycleHooks = keyof PluginLifecycle
+export type KubbFilesProcessingEndContext = {
+  files: Array<FileNode>
+}
 
-export type PluginParameter<H extends PluginLifecycleHooks> = Parameters<Required<PluginLifecycle>[H]>
+export type KubbPluginStartContext = {
+  plugin: NormalizedPlugin
+}
 
-export type ResolvePathParams<TOptions = object> = {
-  pluginName?: string
-  baseName: KubbFile.BaseName
-  mode?: KubbFile.Mode
+export type KubbPluginEndContext = {
+  plugin: NormalizedPlugin
+  duration: number
+  success: boolean
+  error?: Error
+  config: Config
+  /**
+   * Returns all files currently in the file manager (lazy snapshot).
+   * Includes files added by plugins that have already run.
+   */
+  readonly files: ReadonlyArray<FileNode>
   /**
-   * Options to be passed to 'resolvePath' 3th parameter
+   * Upsert one or more files into the file manager.
    */
-  options?: TOptions
+  upsertFile: (...files: Array<FileNode>) => void
 }
 
-export type ResolveNameParams = {
-  name: string
-  pluginName?: string
+export type KubbHookStartContext = {
+  id?: string
+  command: string
+  args?: readonly string[]
+}
+
+export type KubbHookEndContext = {
+  id?: string
+  command: string
+  args?: readonly string[]
+  success: boolean
+  error: Error | null
+}
+
+type ByTag = {
   /**
-   * Specifies the type of entity being named.
-   * - 'file' customizes the name of the created file (uses camelCase).
-   * - 'function' customizes the exported function names (uses camelCase).
-   * - 'type' customizes TypeScript types (uses PascalCase).
-   * - 'const' customizes variable names (uses camelCase).
-   * @default undefined
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
    */
-  type?: 'file' | 'function' | 'type' | 'const'
+  type: 'tag'
+  /**
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
 }
 
-export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  fabric: FabricType
-  config: Config
-  driver: PluginDriver
+type ByOperationId = {
+  /**
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   */
+  type: 'operationId'
   /**
-   * Only add when the file does not exist yet
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
    */
-  addFile: (...file: Array<KubbFile.File>) => Promise<void>
+  pattern: string | RegExp
+}
+
+type ByPath = {
   /**
-   * merging multiple sources into the same output file
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
    */
-  upsertFile: (...file: Array<KubbFile.File>) => Promise<void>
-  events: AsyncEventEmitter<KubbEvents>
-  mode: KubbFile.Mode
+  type: 'path'
   /**
-   * Current plugin
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
    */
-  plugin: Plugin<TOptions>
+  pattern: string | RegExp
+}
 
+type ByMethod = {
   /**
-   * Opens the Kubb Studio URL for the current `rootNode` in the default browser.
-   * Falls back to printing the URL if the browser cannot be launched.
-   * No-ops silently when no adapter has set a `rootNode`.
+   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
    */
-  openInStudio: (options?: DevtoolsOptions) => Promise<void>
-} & (
-  | {
-      /**
-       * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
-       * Returns `undefined` when no adapter was set (legacy OAS-only usage).
-       */
-      rootNode: RootNode
-      /**
-       * Return the adapter from `@kubb/ast`
-       */
-      adapter: Adapter
-    }
-  | {
-      rootNode?: never
-      adapter?: never
-    }
-) &
-  Kubb.PluginContext
-/**
- * Specify the export location for the files and define the behavior of the output
- */
-export type Output<TOptions> = {
+  type: 'method'
   /**
-   * Path to the output folder or file that will contain the generated code
+   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
    */
-  path: string
+  pattern: HttpMethod | RegExp
+}
+// TODO implement as alternative for ByMethod
+// type ByMethods = {
+//   type: 'methods'
+//   pattern: Array<HttpMethod>
+// }
+
+type BySchemaName = {
   /**
-   * Define what needs to be exported, here you can also disable the export of barrel files
-   * @default 'named'
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
    */
-  barrelType?: BarrelType | false
+  type: 'schemaName'
   /**
-   * Add a banner text in the beginning of every file
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
    */
-  banner?: string | ((options: TOptions) => string)
+  pattern: string | RegExp
+}
+
+type ByContentType = {
   /**
-   * Add a footer text in the beginning of every file
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
    */
-  footer?: string | ((options: TOptions) => string)
+  type: 'contentType'
   /**
-   * Whether to override existing external files if they already exist.
-   * @default false
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
    */
-  override?: boolean
+  pattern: string | RegExp
 }
 
-export type Group = {
+/**
+ * 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'
+ * ```
+ */
+export type ResolverPathParams = {
+  baseName: FileNode['baseName']
+  pathMode?: 'single' | 'split'
   /**
-   * Defines the type where to group the files.
-   * - 'tag' groups files by OpenAPI tags.
-   * - 'path' groups files by OpenAPI paths.
-   * @default undefined
+   * Tag value used when `group.type === 'tag'`.
    */
-  type: 'tag' | 'path'
+  tag?: string
   /**
-   * Return the name of a group based on the group name, this is used for the file and name generation.
+   * Path value used when `group.type === 'path'`.
    */
-  name?: (context: { group: string }) => string
+  path?: string
 }
 
-export type LoggerOptions = {
+/**
+ * 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
   /**
-   * @default 3
+   * Plugin name used to populate `meta.pluginName` on the resolved file.
    */
-  logLevel: (typeof logLevel)[keyof typeof logLevel]
+  pluginName?: string
 }
 
 /**
- * Shared context passed to all plugins, parsers, and Fabric internals.
+ * 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 LoggerContext = AsyncEventEmitter<KubbEvents>
-
-export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
+export type ResolverFileParams = {
   name: string
-  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>
+  extname: FileNode['extname']
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string
 }
 
-export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>
+/**
+ * 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'
+ * ```
+ */
+export type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>
+  config: Config
+}
 
-export type { Storage } from './createStorage.ts'
-export type { CoreGeneratorV2, Generator, ReactGeneratorV2 } from './defineGenerator.ts'
-export type { KubbEvents } from './Kubb.ts'
+/**
+ * CLI options derived from command-line flags.
+ */
+export type CLIOptions = {
+  /**
+   * Path to `kubb.config.js`.
+   */
+  config?: string
+  /**
+   * Enable watch mode for input files.
+   */
+  watch?: boolean
+  /**
+   * Logging verbosity for CLI usage.
+   * @default 'silent'
+   */
+  logLevel?: 'silent' | 'info' | 'debug'
+}
+
+/**
+ * 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 { Parser } from './defineParser.ts'