@kubb/core 5.0.0-alpha.73 → 5.0.0-alpha.74

package/src/types.ts

@@ -13,25 +13,48 @@ import type { PluginDriver } from './PluginDriver.ts'
 export type { Renderer, RendererFactory } from './createRenderer.ts'
 
 /**
- * Safely extracts the type of key `K` from `T`, returning `{}` when `K` is not a key of `T`.
- * Used to implement optional interface augmentation for `Kubb.ConfigOptionsRegistry` and
- * `Kubb.PluginOptionsRegistry` so that middleware and plugin packages can extend core types
- * without requiring modifications to core.
+ * 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.
  *
  * @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.
+ */
 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
 }
@@ -39,19 +62,18 @@ export type InputData = {
 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`
- * - `TDocument` — type of the raw source document exposed by the adapter after `parse()`
+ * - `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,
@@ -66,83 +88,94 @@ export type AdapterFactoryOptions<
 }
 
 /**
- * An adapter converts a source file or data into a `@kubb/ast` `InputNode`.
+ * 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 `InputNode`
- * 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']
   /**
-   * The raw source document produced after the first `parse()` call.
-   * `undefined` before parsing; typed by the adapter's `TDocument` generic.
+   * Parsed source document after the first `parse()` call. `null` before parsing.
    */
   document: TOptions['document'] | null
   inputNode: InputNode | null
   /**
-   * Convert the raw source into a universal `InputNode`.
+   * Parse the source into a universal `InputNode`.
    */
   parse: (source: AdapterSource) => PossiblePromise<InputNode>
   /**
-   * Extracts `ImportNode` entries needed by a `SchemaNode` tree.
-   * Populated after the first `parse()` call. Returns an empty array before that.
+   * 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<ImportNode>
 }
 
 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
   /**
-   * An array of parsers used to convert generated files to strings.
-   * Each parser handles specific file extensions (e.g. `.ts`, `.tsx`).
+   * 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`.
    *
-   * A catch-all fallback parser is always appended last for any unhandled extension.
-   *
-   * When omitted, `parserTs` from `@kubb/parser-ts` is used automatically as the
-   * default (requires `@kubb/parser-ts` to be installed as an optional dependency).
-   * @default [parserTs] — from `@kubb/parser-ts`
+   * @default [parserTs] from `@kubb/parser-ts`
    * @example
    * ```ts
    * import { parserTs, tsxParser } from '@kubb/parser-ts'
@@ -153,125 +186,197 @@ export type Config<TInput = Input> = {
    */
   parsers: Array<Parser>
   /**
-   * Adapter that converts the input file into a `@kubb/ast` `InputNode` — the universal
-   * intermediate representation consumed by all Kubb plugins.
-   *
-   * - Use `@kubb/adapter-oas` for OpenAPI / Swagger.
-   * - Use `@kubb/adapter-drizzle` or `@kubb/adapter-asyncapi` for other formats.
+   * 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 { adapterOas } from '@kubb/adapter-oas'
    * export default defineConfig({
    *   adapter: adapterOas(),
-   *   input: { path: './petStore.yaml' },
+   *   input: { path: './petstore.yaml' },
    * })
    * ```
    */
   adapter: Adapter
   /**
    * Source file or data to generate code from.
-   * Use `input.path` for a file on disk or `input.data` for an inline string or object.
+   * Use `input.path` for a file path or `input.data` for inline data.
    */
   input: TInput
   output: {
     /**
-     * Output directory for generated files.
-     * Accepts an absolute path or a path relative to `root`.
+     * 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
     /**
-     * Specifies the formatting tool to be used.
-     * - 'auto' automatically detects and uses oxfmt, biome, or prettier (in that order of preference).
-     * - 'oxfmt' uses Oxfmt for code formatting.
-     * - 'prettier' uses Prettier for code formatting.
-     * - 'biome' uses Biome for code formatting.
-     * - false disables code formatting.
+     * 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
+     * format: 'auto'        // auto-detect prettier, biome, or oxfmt
+     * format: 'prettier'    // force prettier
+     * format: false         // skip formatting
+     * ```
      */
     format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false
     /**
-     * Specifies the linter that should be used to analyze the code.
-     * - 'auto' automatically detects and uses oxlint, biome, or eslint (in that order of preference).
-     * - 'oxlint' uses Oxlint for linting.
-     * - 'eslint' uses ESLint for linting.
-     * - 'biome' uses Biome for linting.
-     * - false disables linting.
+     * 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'}
+     * 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' }
+     * ```
      */
     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'>
   /**
-   * 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`).
+   * 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.
    */
   storage?: Storage
   /**
-   * An array of Kubb plugins used for code generation.
-   * Each plugin may declare additional configurable options.
-   * If a plugin depends on another, an error is thrown when the dependency is missing.
-   * Use `dependencies` on the plugin to declare execution order.
+   * 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 and post-process the build output.
-   * Each middleware receives the `hooks` emitter and attaches its own listeners.
-   * Middleware listeners are always registered after all plugin listeners,
-   * so middleware hooks fire last for any given event.
+   * 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'
-   * export default defineConfig({
-   *   middleware: [middlewareBarrel],
-   *   plugins: [pluginTs(), pluginZod()],
-   * })
+   *
+   * middleware: [middlewareBarrel()]
    * ```
+   *
+   * @see {@link defineMiddleware} to create custom middleware.
    */
   middleware?: Array<Middleware>
   /**
-   * Project-wide renderer factory. All plugins and generators that do not declare their own
-   * `renderer` ultimately fall back to this value.
-   *
-   * The resolution chain is: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw `FileNode[]` mode).
+   * Default renderer factory used by all plugins and generators.
+   * Resolution chain: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw FileNode[] mode).
    *
    * @example
    * ```ts
@@ -282,9 +387,34 @@ export type Config<TInput = Input> = {
    * })
    * ```
    */
+  /**
+   * 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
@@ -296,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>
   }
@@ -310,7 +461,7 @@ export type Config<TInput = Input> = {
 // plugin
 
 /**
- * A type/string-pattern filter used for `include`, `exclude`, and `override` matching.
+ * Type/string pattern filter for include/exclude/override matching.
  */
 type PatternFilter = {
   type: string
@@ -318,18 +469,14 @@ type PatternFilter = {
 }
 
 /**
- * A pattern filter paired with partial option overrides to apply when the pattern matches.
+ * Pattern filter with partial option overrides applied when the pattern matches.
  */
 type PatternOverride<TOptions> = PatternFilter & {
   options: Omit<Partial<TOptions>, 'override'>
 }
 
 /**
- * Context passed to `resolver.resolveOptions` to apply include/exclude/override filtering
- * for a given operation or schema node.
- */
-/**
- * Resolves filtered options for a given operation or schema node.
+ * Context for resolving filtered options for a given operation or schema node.
  *
  * @internal
  */
@@ -343,9 +490,8 @@ export type ResolveOptionsContext<TOptions> = {
 /**
  * Base constraint for all plugin resolver objects.
  *
- * `default`, `resolveOptions`, `resolvePath`, and `resolveFile` are injected automatically
- * by `defineResolver` — plugin authors may override them but never need to implement them
- * from scratch.
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are injected automatically by `defineResolver` — extend this type to add custom resolution methods.
  *
  * @example
  * ```ts
@@ -368,20 +514,20 @@ export type Resolver = {
 
 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,
   /**
-   * 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,
 > = {
@@ -392,9 +538,9 @@ export type PluginFactoryOptions<
 }
 
 /**
- * Internal representation of a plugin after normalization.
- * Extends the user-facing `Plugin` with runtime fields populated during `kubb:plugin:setup`.
- * Not part of the public API — use `Plugin` for external-facing interactions.
+ * 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> & {
@@ -413,30 +559,86 @@ export type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFacto
 }
 
 /**
- * Partial version of {@link Config} intended for user-facing config entry points.
+ * Partial `Config` for user-facing entry points with sensible defaults.
  *
- * Fields that have sensible defaults (`root`, `plugins`, `parsers`, `adapter`) are optional.
+ * `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'> & {
   /**
-   * 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 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
   /**
-   * An array of parsers used to convert generated files to strings.
-   * Each parser handles specific file extensions (e.g. `.ts`, `.tsx`).
+   * 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()]
+   * ```
    *
-   * A catch-all fallback parser is always appended last for any unhandled extension.
+   * @see {@link Parser} to implement a custom parser.
    */
   parsers?: Array<Parser>
   /**
-   * Adapter that converts the input file into a `@kubb/ast` `InputNode`.
+   * 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
   /**
-   * An array of Kubb plugins used for code generation.
-   * Each entry is a hook-style plugin created with `definePlugin`.
+   * 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>
 }
@@ -445,121 +647,114 @@ export type ResolveNameParams = {
   name: string
   pluginName?: string
   /**
-   * Specifies the type of entity being named.
-   * - `'file'` — customizes the name of the created file (camelCase).
-   * - `'function'` — customizes the exported function names (camelCase).
-   * - `'type'` — customizes TypeScript type names (PascalCase).
-   * - `'const'` — customizes variable names (camelCase).
+   * 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 as the second argument to generator `schema`, `operation`, and
- * `operations` methods.
+ * Context object passed to generator `schema`, `operation`, and `operations` methods.
  *
- * Generators are only invoked from `runPluginAstHooks`, which already guards against a
- * missing adapter. This type reflects that guarantee — `ctx.adapter` and `ctx.inputNode`
- * are always defined, so no runtime checks or casts are needed inside generator bodies.
- *
- * `ctx.options` carries the per-node resolved options for `schema`/`operation` calls
- * (after exclude/include/override filtering) and the plugin-level options for `operations`.
+ * 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 output directory for the current plugin.
-   * Shorthand for `path.resolve(config.root, config.output.path)`.
+   * Absolute path to the current plugin's output directory.
    */
   root: string
   /**
-   * Returns the output mode for the given output config.
-   * Returns `'single'` when `output.path` has a file extension, `'split'` otherwise.
+   * 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. Returns the plugin typed via `Kubb.PluginRegistry` when
-   * the name is a registered key, otherwise returns the generic `Plugin`.
+   * 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
   /**
-   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
+   * 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. Returns the resolver typed via `Kubb.PluginRegistry` when
-   * the name is a registered key, otherwise returns the generic `Resolver`.
+   * 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 when they do not exist yet.
+   * Add files only if they don't exist.
    */
   addFile: (...file: Array<FileNode>) => Promise<void>
   /**
-   * Merge multiple sources into the same output file.
+   * Merge sources into the same output file.
    */
   upsertFile: (...file: Array<FileNode>) => Promise<void>
   hooks: AsyncEventEmitter<KubbHooks>
   /**
-   * The current plugin.
+   * The current plugin instance.
    */
   plugin: Plugin<TOptions>
   /**
-   * Resolver for the current plugin.
+   * The current plugin's resolver.
    */
   resolver: TOptions['resolver']
   /**
-   * Composed transformer for the current plugin.
+   * The current plugin's transformer.
    */
   transformer: Visitor | undefined
   /**
-   * Emit a warning via the build event system.
+   * Emit a warning.
    */
   warn: (message: string) => void
   /**
-   * Emit an error via the build event system.
+   * Emit an error.
    */
   error: (error: string | Error) => void
   /**
-   * Emit an info message via the build event system.
+   * Emit an info message.
    */
   info: (message: string) => void
   /**
-   * Opens the Kubb Studio URL for the current `inputNode` in the default browser.
+   * Open the current input node in Kubb Studio.
    */
   openInStudio: (options?: DevtoolsOptions) => Promise<void>
   /**
-   * The adapter from `@kubb/ast`.
+   * The configured adapter instance.
    */
   adapter: Adapter
   /**
-   * The universal `@kubb/ast` `InputNode` produced by the configured adapter.
+   * The universal `InputNode` produced by the adapter.
    */
   inputNode: InputNode
   /**
-   * Per-node resolved options (after exclude/include/override filtering).
+   * Resolved options after exclude/include/override filtering.
    */
   options: TOptions['resolvedOptions']
 }
 /**
- * Configure generated file output location and behavior.
+ * Output configuration for generated files.
  */
 export type Output<_TOptions = unknown> = {
   /**
-   * Path to the output folder or file that will contain generated code.
+   * Output folder or file path for generated code.
    */
   path: string
   /**
-   * Text or function appended at the start of every generated file.
-   * When a function, receives the current `InputNode` and must return a 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 at the end of every generated file.
-   * When a function, receives the current `InputNode` and must return a 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)
   /**
@@ -571,27 +766,28 @@ export type Output<_TOptions = unknown> = {
 
 export type Group = {
   /**
-   * Determines how files are grouped into subdirectories.
-   * - `'tag'` groups files by OpenAPI tags.
-   * - `'path'` groups files by OpenAPI paths.
+   * How to group files into subdirectories.
+   * - `'tag'` — group by OpenAPI tags
+   * - `'path'` — group by OpenAPI paths
    */
   type: 'tag' | 'path'
   /**
-   * Returns the subdirectory name for a given group value.
-   * Defaults to `${camelCase(group)}Controller` for tags and the first path segment for paths.
+   * 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 all plugins, parsers, and other internals.
+ * Shared context passed to plugins, parsers, and other internals.
  */
 export type LoggerContext = AsyncEventEmitter<KubbHooks>
 
@@ -609,44 +805,35 @@ export type { Plugin } from './definePlugin.ts'
 export type { Kubb, KubbHooks } from './Kubb.ts'
 
 /**
- * Context passed to a hook-style plugin's `kubb:plugin:setup` handler.
- * Provides methods to register generators, configure the resolver, transformer,
- * and renderer, as well as access to the current build configuration.
+ * 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 on this plugin. Generators are invoked during the AST walk
-   * (schema/operation/operations) exactly like generators declared statically on `createPlugin`.
+   * 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 partially override the resolver for this plugin.
-   * The resolver controls file naming and path resolution for generated files.
-   *
-   * When `TFactory` is a concrete `PluginFactoryOptions` (e.g. `PluginClient`),
-   * the resolver parameter is typed to the plugin's own resolver type (e.g. `ResolverClient`).
+   * 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 (visitor) for this plugin.
-   * The transformer pre-processes nodes before they reach the generators.
+   * Set the AST transformer to pre-process nodes before they reach generators.
    */
   setTransformer(visitor: Visitor): void
   /**
-   * Set the renderer factory for this plugin.
-   * Used to process JSX elements returned by generators.
+   * Set the renderer factory to process JSX elements from generators.
    */
   setRenderer(renderer: RendererFactory): void
   /**
-   * Set the resolved options for the build loop. These options are merged into the
-   * normalized plugin's `options` object (which includes `output`, `exclude`, `override`).
-   *
-   * Call this in `kubb:plugin:setup` to provide the resolved options that generators
-   * and the build loop need (e.g., `enumType`, `optionalType`, `group`).
+   * 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 normal generation pipeline.
+   * Inject a raw file into the build output, bypassing the generation pipeline.
    */
   injectFile(userFileNode: UserFileNode): void
   /**
@@ -654,17 +841,17 @@ export type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = Plugi
    */
   updateConfig(config: Partial<Config>): void
   /**
-   * The resolved build configuration at the time of setup.
+   * The resolved build configuration at setup time.
    */
   config: Config
   /**
-   * The plugin's own options as passed by the user.
+   * The plugin's user-provided options.
    */
   options: TFactory['options']
 }
 
 /**
- * Context passed to a hook-style plugin's `kubb:build:start` handler.
+ * Context for hook-style plugin `kubb:build:start` handler.
  * Fires immediately before the plugin execution loop begins.
  */
 export type KubbBuildStartContext = {
@@ -672,15 +859,13 @@ export type KubbBuildStartContext = {
   adapter: Adapter
   inputNode: InputNode
   /**
-   * Get a plugin by name. Returns the plugin typed via `Kubb.PluginRegistry` when
-   * the name is a registered key, otherwise returns the generic `Plugin`.
+   * 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
   /**
-   * Returns all files currently in the file manager.
-   * Call this lazily (e.g. inside a `kubb:plugin:end` listener) to see files added by plugins
-   * that have already run.
+   * 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>
   /**
@@ -692,27 +877,25 @@ export type KubbBuildStartContext = {
 }
 
 /**
- * Context passed to `kubb:plugins:end` handlers.
- * Fires after all plugins have run and per-plugin barrels have been written,
- * but BEFORE files are written to disk.
- * Middleware that needs to inject final files (e.g. a root barrel) should use this event.
+ * 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
   /**
-   * Returns all files currently in the file manager (lazy snapshot).
-   * Includes files added by plugins and per-plugin barrel middleware.
+   * All files currently in the file manager (lazy snapshot).
    */
   readonly files: ReadonlyArray<FileNode>
   /**
-   * Upsert one or more files into the file manager.
-   * Files added here will be included in the write pass that follows.
+   * Upsert files into the file manager.
+   * Files added here are included in the write pass.
    */
   upsertFile: (...files: Array<FileNode>) => void
 }
 
 /**
- * Context passed to a hook-style plugin's `kubb:build:end` handler.
+ * Context for hook-style plugin `kubb:build:end` handler.
  * Fires after all files have been written to disk.
  */
 export type KubbBuildEndContext = {
@@ -785,11 +968,11 @@ export type KubbFilesProcessingStartContext = {
 
 export type KubbFileProcessingUpdateContext = {
   /**
-   * Number of files processed so far.
+   * Number of files processed.
    */
   processed: number
   /**
-   * Total number of files to process.
+   * Total files to process.
    */
   total: number
   /**
@@ -805,8 +988,7 @@ export type KubbFileProcessingUpdateContext = {
    */
   file: FileNode
   /**
-   * Kubb configuration.
-   * Provides access to the current config during file processing.
+   * The current build configuration.
    */
   config: Config
 }
@@ -851,22 +1033,46 @@ export type KubbHookEndContext = {
 }
 
 type ByTag = {
+  /**
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   */
   type: 'tag'
+  /**
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp
 }
 
 type ByOperationId = {
+  /**
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   */
   type: 'operationId'
+  /**
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp
 }
 
 type ByPath = {
+  /**
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
+   */
   type: 'path'
+  /**
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   */
   pattern: string | RegExp
 }
 
 type ByMethod = {
+  /**
+   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   */
   type: 'method'
+  /**
+   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   */
   pattern: HttpMethod | RegExp
 }
 // TODO implement as alternative for ByMethod
@@ -876,30 +1082,82 @@ type ByMethod = {
 // }
 
 type BySchemaName = {
+  /**
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   */
   type: 'schemaName'
+  /**
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp
 }
 
 type ByContentType = {
+  /**
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   */
   type: 'contentType'
+  /**
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp
 }
 
 /**
  * A pattern filter that prevents matching nodes from being generated.
- * Match by `tag`, `operationId`, `path`, `method`, `contentType`, or `schemaName`.
+ *
+ * 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.
- * Match by `tag`, `operationId`, `path`, `method`, `contentType`, or `schemaName`.
+ *
+ * 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.
- * Match by `tag`, `operationId`, `path`, `method`, `schemaName`, or `contentType`.
+ *
+ * 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'>