@kubb/core 5.0.0-beta.21 → 5.0.0-beta.23

package/dist/{createKubb-CYrw_xaR.d.ts → createKubb-CvfQXK_j.d.ts}

@@ -115,8 +115,12 @@ declare const logLevel: {
 //#endregion
 //#region src/createAdapter.d.ts
 /**
- * Source data passed to an adapter's `parse` function.
- * Mirrors the config input shape with paths resolved to absolute.
+ * Source data handed to an adapter's `parse` function. Mirrors the config
+ * input shape with paths resolved to absolute.
+ *
+ * - `{ type: 'path' }`: single file on disk.
+ * - `{ type: 'paths' }`: multiple files (e.g. split spec).
+ * - `{ type: 'data' }`: raw string or parsed object provided inline.
  */
 type AdapterSource = {
   type: 'path';
@@ -129,12 +133,12 @@ type AdapterSource = {
   paths: Array<string>;
 };
 /**
- * Generic type parameters for an adapter definition.
+ * Generic parameters used by `createAdapter` and the resulting `Adapter` type.
  *
- * - `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
+ * - `TName`: unique adapter identifier (`'oas'`, `'asyncapi'`, ...).
+ * - `TOptions`: user-facing options accepted by the adapter factory.
+ * - `TResolvedOptions`: options after defaults are applied.
+ * - `TDocument`: type of the parsed source document.
  */
 type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions, TDocument = unknown> = {
   name: TName;
@@ -143,19 +147,23 @@ type AdapterFactoryOptions<TName extends string = string, TOptions extends objec
   document: TDocument;
 };
 /**
- * Adapter that converts input files or data into an `InputNode`.
+ * Converts input files or inline data into Kubb's universal AST `InputNode`.
  *
- * Adapters parse different schema formats (OpenAPI, AsyncAPI, Drizzle, etc.) into Kubb's
- * universal intermediate representation that all plugins consume.
+ * Adapters live between the spec format and the plugins. The built-in
+ * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1; custom adapters can
+ * support GraphQL, gRPC, AsyncAPI, or any domain-specific schema language.
  *
  * @example
  * ```ts
+ * import { defineConfig } from 'kubb'
  * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
  *
  * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
  *   adapter: adapterOas(),
- *   input: { path: './openapi.yaml' },
- *   plugins: [pluginTs(), pluginZod()],
+ *   plugins: [pluginTs()],
  * })
  * ```
  */
@@ -197,35 +205,40 @@ type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
    * Memory-efficient streaming variant of `parse()`.
    *
    * Returns an `InputStreamNode` whose `schemas` and `operations` are `AsyncIterable`.
-   * Each `for await` loop creates a fresh parse pass over the cached in-memory document —
-   * no pre-built arrays are held in memory.
+   * Each `for await` loop creates a fresh parse pass over the cached in-memory document.
+   * No pre-built arrays are held in memory.
    */
   stream?: (source: AdapterSource) => Promise<InputStreamNode>;
 };
 type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>;
 /**
- * Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
- *
- * Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
- * Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
+ * Defines a custom adapter that translates a spec format into Kubb's universal
+ * AST. Use this when you need to consume GraphQL, gRPC, AsyncAPI, or another
+ * domain-specific schema. Built-in adapters: `@kubb/adapter-oas` for
+ * OpenAPI/Swagger documents.
  *
- * @note Adapters must parse their input format to Kubb's `InputNode` structure.
+ * Adapters must return an `InputNode` from `parse`. That node is what every
+ * plugin in the build consumes.
  *
  * @example
  * ```ts
- * export const myAdapter = createAdapter<MyAdapter>((options) => {
- *   return {
- *     name: 'my-adapter',
- *     options,
- *     async parse(source) {
- *       // Transform source format to InputNode
- *       return { ... }
- *     },
- *   }
- * })
+ * import { createAdapter, ast, type AdapterFactoryOptions } from '@kubb/core'
+ *
+ * type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
  *
- * // Instantiate:
- * const adapter = myAdapter({ validate: true })
+ * export const myAdapter = createAdapter<MyAdapter>((options) => ({
+ *   name: 'my-adapter',
+ *   options,
+ *   document: null,
+ *   async parse(_source) {
+ *     // Convert `source` (path or inline data) into an InputNode.
+ *     return ast.createInput()
+ *   },
+ *   getImports: () => [],
+ *   async validate() {
+ *     // Throw or call ctx.error here when the spec is invalid.
+ *   },
+ * }))
  * ```
  */
 declare function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T>;
@@ -277,17 +290,37 @@ type Renderer<TElement = unknown> = {
  */
 type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
 /**
- * Wraps a renderer factory for use in generator definitions.
+ * Defines a renderer factory. Renderers turn the generator's return value
+ * (JSX, a template string, a tree of any shape) into `FileNode`s that get
+ * written to disk.
  *
- * @example
+ * Use this to support output formats beyond JSX — for instance, a Handlebars
+ * renderer, a string-template renderer, or a renderer that writes binary
+ * files. Plugins and generators pick the renderer to use via the `renderer`
+ * field on `defineGenerator`.
+ *
+ * @example A minimal renderer that wraps a custom runtime
  * ```ts
- * export const jsxRenderer = createRenderer(() => {
- *   const runtime = new Runtime()
+ * import { createRenderer } from '@kubb/core'
+ *
+ * export const myRenderer = createRenderer(() => {
+ *   const runtime = new MyRuntime()
  *   return {
- *     async render(element) { await runtime.render(element) },
- *     get files() { return runtime.nodes },
- *     dispose() { runtime.unmount() },
- *     unmount(error) { runtime.unmount(error) },
+ *     async render(element) {
+ *       await runtime.render(element)
+ *     },
+ *     get files() {
+ *       return runtime.files
+ *     },
+ *     dispose() {
+ *       runtime.dispose()
+ *     },
+ *     unmount(error) {
+ *       runtime.dispose(error)
+ *     },
+ *     [Symbol.dispose]() {
+ *       this.dispose()
+ *     },
  *   }
  * })
  * ```
@@ -295,70 +328,83 @@ type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
 declare function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement>;
 //#endregion
 //#region src/createStorage.d.ts
+/**
+ * Backend that persists generated files. Kubb ships with `fsStorage` (writes
+ * to disk) and `memoryStorage` (keeps everything in RAM). Implement this
+ * interface to write to S3, a database, or any other target.
+ */
 type Storage = {
   /**
-   * Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`).
+   * Identifier used in logs and diagnostics (`'fs'`, `'memory'`, `'s3'`).
    */
   readonly name: string;
   /**
-   * Returns `true` when an entry for `key` exists in storage.
+   * Returns `true` when an entry for `key` exists.
    */
   hasItem(key: string): Promise<boolean>;
   /**
-   * Returns the stored string value, or `null` when `key` does not exist.
+   * Reads the stored string. Returns `null` when the key is missing.
    */
   getItem(key: string): Promise<string | null>;
   /**
-   * Persists `value` under `key`, creating any required structure.
+   * Stores `value` under `key`, creating any required structure (directories,
+   * buckets, ...).
    */
   setItem(key: string, value: string): Promise<void>;
   /**
-   *  Removes the entry for `key`. No-ops when the key does not exist.
+   * Deletes the entry for `key`. No-op when the key does not exist.
    */
   removeItem(key: string): Promise<void>;
   /**
-   * Returns all keys, optionally filtered to those starting with `base`.
+   * Returns every key. Pass `base` to filter to keys starting with that prefix.
    */
   getKeys(base?: string): Promise<Array<string>>;
   /**
-   * Removes all entries, optionally scoped to those starting with `base`.
+   * Removes every entry. Pass `base` to scope the wipe to a key prefix.
    */
   clear(base?: string): Promise<void>;
   /**
-   * Optional teardown hook called after the build completes.
+   * Optional teardown hook called after the build completes. Use to flush
+   * buffers, close connections, or release file locks.
    */
   dispose?(): Promise<void>;
 };
 /**
- * Factory for implementing custom storage backends that control where generated files are written.
+ * Defines a custom storage backend. The builder receives user options and
+ * returns a `Storage` implementation. Kubb ships with filesystem and
+ * in-memory storages — reach for this when you need to write generated files
+ * elsewhere (cloud storage, a database, a remote API).
  *
- * Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
- * Kubb provides filesystem and in-memory implementations out of the box.
- *
- * @note Call the returned factory with optional options to instantiate the storage adapter.
- *
- * @example
+ * @example In-memory storage (the built-in implementation)
  * ```ts
  * import { createStorage } from '@kubb/core'
  *
  * export const memoryStorage = createStorage(() => {
  *   const store = new Map<string, string>()
+ *
  *   return {
  *     name: 'memory',
- *     async hasItem(key) { return store.has(key) },
- *     async getItem(key) { return store.get(key) ?? null },
- *     async setItem(key, value) { store.set(key, value) },
- *     async removeItem(key) { store.delete(key) },
+ *     async hasItem(key) {
+ *       return store.has(key)
+ *     },
+ *     async getItem(key) {
+ *       return store.get(key) ?? null
+ *     },
+ *     async setItem(key, value) {
+ *       store.set(key, value)
+ *     },
+ *     async removeItem(key) {
+ *       store.delete(key)
+ *     },
  *     async getKeys(base) {
  *       const keys = [...store.keys()]
  *       return base ? keys.filter((k) => k.startsWith(base)) : keys
  *     },
- *     async clear(base) { if (!base) store.clear() },
+ *     async clear(base) {
+ *       if (!base) store.clear()
+ *     },
  *   }
  * })
- *
- * // Instantiate:
- * const storage = memoryStorage()
  * ```
  */
 declare function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage;
@@ -376,36 +422,44 @@ type DevtoolsOptions = {
 type PrintOptions = {
   extname?: FileNode['extname'];
 };
+/**
+ * Converts a resolved {@link FileNode} into the final source string that gets
+ * written to disk. Kubb ships with TypeScript and TSX parsers; add your own
+ * for new file types (JSON, Markdown, ...).
+ */
 type Parser<TMeta extends object = any> = {
+  /**
+   * Display name used in diagnostics and the parser registry.
+   */
   name: string;
   /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
+   * File extensions this parser handles. Set to `undefined` to define a
+   * catch-all fallback used when no other parser claims the extension.
    *
-   * @example Handled extensions
+   * @example
    * `['.ts', '.js']`
    */
   extNames: Array<FileNode['extname']> | undefined;
   /**
-   * Convert a resolved file to a string.
+   * Serialise the file's AST into source code.
    */
   parse(file: FileNode<TMeta>, options?: PrintOptions): string;
 };
 /**
- * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
- *
- * @note Call the returned factory with optional options to instantiate the parser.
+ * Defines a parser with type-safe `this`. Used to register handlers for new
+ * file extensions or to plug a non-TypeScript output into the build.
  *
  * @example
  * ```ts
- * import { defineParser } from '@kubb/core'
+ * import { defineParser, ast } from '@kubb/core'
  *
  * export const jsonParser = defineParser({
  *   name: 'json',
  *   extNames: ['.json'],
  *   parse(file) {
- *     const { extractStringsFromNodes } = await import('@kubb/ast')
- *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+ *     return file.sources
+ *       .map((source) => ast.extractStringsFromNodes(source.nodes ?? []))
+ *       .join('\n')
  *   },
  * })
  * ```
@@ -457,47 +511,67 @@ declare class FileProcessor {
 }
 //#endregion
 //#region src/defineLogger.d.ts
+/**
+ * Options accepted by a logger's `install` callback.
+ */
 type LoggerOptions = {
   /**
-   * Log level for output verbosity.
-   * @default 3
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
    */
   logLevel: (typeof logLevel)[keyof typeof logLevel];
 };
 /**
- * Shared context passed to plugins, parsers, and other internals.
+ * Event emitter handed to `Logger.install`. Use `.on('kubb:info', ...)` and
+ * friends to subscribe to build events.
  */
 type LoggerContext = AsyncEventEmitter<KubbHooks>;
+/**
+ * Logger contract. A logger receives the build's event emitter and subscribes
+ * to whichever lifecycle events it wants to forward to its destination
+ * (console, file, remote sink).
+ */
 type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
+  /**
+   * Display name used in diagnostics.
+   */
   name: string;
+  /**
+   * Called once per build with the shared event emitter. Subscribe to events
+   * here. The return value (if any) is forwarded to whoever installed the
+   * logger, which is handy for sink factories.
+   */
   install: (context: LoggerContext, options?: TOptions) => TInstallReturn | Promise<TInstallReturn>;
 };
 type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = Logger<TOptions, TInstallReturn>;
 /**
- * Wraps a logger definition into a typed {@link Logger}.
- *
- * The optional second type parameter `TInstallReturn` allows loggers to return
- * a value from `install` — for example, a sink factory that the caller can
- * forward to hook execution.
+ * Defines a typed logger. Use the second type parameter to declare a return
+ * value from `install`, which is handy when the logger exposes a sink factory
+ * or cleanup callback to the caller.
  *
  * @example Basic logger
  * ```ts
+ * import { defineLogger } from '@kubb/core'
+ *
  * export const myLogger = defineLogger({
  *   name: 'my-logger',
- *   install(context, options) {
- *     context.on('kubb:info', (message) => console.log('ℹ', message))
- *     context.on('kubb:error', (error) => console.error('✗', error.message))
+ *   install(context) {
+ *     context.on('kubb:info', ({ message }) => console.log('ℹ', message))
+ *     context.on('kubb:error', ({ error }) => console.error('✗', error.message))
  *   },
  * })
  * ```
  *
  * @example Logger that returns a hook sink factory
  * ```ts
+ * import { defineLogger, type LoggerOptions } from '@kubb/core'
+ * import type { HookSinkFactory } from './sinks'
+ *
  * export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
  *   name: 'my-logger',
- *   install(context, options) {
+ *   install(context) {
  *     // … register event handlers …
- *     return (commandWithArgs) => ({ onStdout: console.log })
+ *     return () => ({ onStdout: console.log })
  *   },
  * })
  * ```
@@ -506,36 +580,34 @@ declare function defineLogger<Options extends LoggerOptions = LoggerOptions, TIn
 //#endregion
 //#region src/defineMiddleware.d.ts
 /**
- * A middleware instance produced by calling a factory created with `defineMiddleware`.
- * It declares event handlers under a `hooks` object which are registered on the
- * shared emitter after all plugin hooks, so middleware handlers for any event
- * always fire last.
+ * A middleware instance. Subscribes to lifecycle events via `hooks`. Middleware
+ * handlers always fire after every plugin handler for the same event, so they
+ * see the full set of generated files.
  */
 type Middleware = {
   /**
-   * Unique identifier for this middleware.
+   * Unique name. Use a `middleware-<feature>` convention (e.g.
+   * `middleware-barrel`).
    */
   name: string;
   /**
-   * Lifecycle event handlers for this middleware.
-   * Any event from the global `KubbHooks` map can be subscribed to here.
-   * Handlers are registered after all plugin handlers, so they always fire last.
+   * Lifecycle event handlers. Any event from the global `KubbHooks` map can be
+   * subscribed to here. Handlers run after all plugin handlers for that event.
    */
   hooks: { [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void> };
 };
 /**
- * Creates a middleware factory using the hook-style `hooks` API.
+ * Creates a middleware factory. Middleware fires after every plugin handler
+ * for the same event, which makes it the natural place for post-processing
+ * (barrel files, lint runs, audit logs).
  *
- * Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
- * Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
+ * Per-build state belongs inside the factory closure so each `createKubb`
+ * invocation gets its own isolated instance.
  *
- * @note The factory can accept typed options. See examples for using options and per-build state patterns.
- *
- * @example
+ * @example Stateless middleware
  * ```ts
  * import { defineMiddleware } from '@kubb/core'
  *
- * // Stateless middleware
  * export const logMiddleware = defineMiddleware(() => ({
  *   name: 'log-middleware',
  *   hooks: {
@@ -544,8 +616,12 @@ type Middleware = {
  *     },
  *   },
  * }))
+ * ```
+ *
+ * @example Middleware with options and per-build state
+ * ```ts
+ * import { defineMiddleware } from '@kubb/core'
  *
- * // Middleware with options and per-build state
  * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
  *   const seen = new Set<string>()
  *   return {
@@ -717,49 +793,44 @@ type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'],
   pluginName: T['name'];
 } & ThisType<T['resolver']>;
 /**
- * Defines a resolver for a plugin, injecting built-in defaults for name casing,
- * include/exclude/override filtering, path resolution, and file construction.
+ * Defines a plugin resolver. The resolver is the object that decides what
+ * every generated symbol and file path is called. Built-in defaults handle
+ * name casing, include/exclude/override filtering, output path computation,
+ * and file construction. Supply your own to override any of them:
  *
- * All four defaults can be overridden by providing them in the builder function:
- * - `default` — name casing strategy (camelCase / PascalCase)
- * - `resolveOptions` — include/exclude/override filtering
- * - `resolvePath` — output path computation
- * - `resolveFile` — full `FileNode` construction
+ * - `default` — name casing strategy (camelCase / PascalCase).
+ * - `resolveOptions` — include/exclude/override filtering.
+ * - `resolvePath` — output path computation.
+ * - `resolveFile` — full `FileNode` construction.
+ * - `resolveBanner` / `resolveFooter` — top/bottom-of-file text.
  *
- * Methods in the returned object can call sibling resolver methods via `this`.
+ * Methods in the returned object can call sibling resolver methods via `this`,
+ * which keeps custom rules small (`this.default(name, 'type')` to delegate).
  *
  * @example Basic resolver with naming helpers
  * ```ts
- * export const resolver = defineResolver<PluginTs>(() => ({
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
  *   name: 'default',
- *   resolveName(node) {
- *     return this.default(node.name, 'function')
+ *   resolveName(name) {
+ *     return this.default(name, 'function')
  *   },
- *   resolveTypedName(node) {
- *     return this.default(node.name, 'type')
+ *   resolveTypeName(name) {
+ *     return this.default(name, 'type')
  *   },
  * }))
  * ```
  *
- * @example Override resolvePath for a custom output structure
+ * @example Custom output path
  * ```ts
- * export const resolver = defineResolver<PluginTs>(() => ({
+ * import path from 'node:path'
+ *
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
  *   name: 'custom',
  *   resolvePath({ baseName }, { root, output }) {
  *     return path.resolve(root, output.path, 'generated', baseName)
  *   },
  * }))
  * ```
- *
- * @example Use this.default inside a helper
- * ```ts
- * export const resolver = defineResolver<PluginTs>(() => ({
- *   name: 'default',
- *   resolveParamName(node, param) {
- *     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
- *   },
- * }))
- * ```
  */
 declare function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'];
 //#endregion
@@ -773,39 +844,48 @@ declare function defineResolver<T extends PluginFactoryOptions>(build: ResolverB
  */
 type ExtractRegistryKey$1<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
 /**
- * Output configuration for generated files.
+ * Output configuration shared by every plugin. Each plugin extends this with
+ * its own keys via the `Kubb.PluginOptionsRegistry.output` interface merge.
  */
 type Output<_TOptions = unknown> = {
   /**
-   * Output folder or file path for generated code.
+   * Folder (or single file) where the plugin writes its generated code.
+   * Resolved against the global `output.path` set on `defineConfig`.
    */
   path: string;
   /**
-   * Text or function prepended to every generated file.
-   * When a function, receives the document metadata and returns a string.
+   * Text prepended to every generated file. Useful for license headers,
+   * lint disables, or `@ts-nocheck` directives. Pass a function to compute
+   * the banner from the file's `InputMeta`.
    */
   banner?: string | ((meta?: InputMeta) => string);
   /**
-   * Text or function appended to every generated file.
-   * When a function, receives the document metadata and returns a string.
+   * Text appended at the end of every generated file. Mirror of `banner`.
+   * Pass a function to compute the footer from the file's `InputMeta`.
    */
   footer?: string | ((meta?: InputMeta) => string);
   /**
-   * Whether to override existing external files if they already exist.
+   * Allows the plugin to overwrite hand-written files at the same path.
+   * Defaults to `false` to protect manual edits.
+   *
    * @default false
    */
   override?: boolean;
 } & ExtractRegistryKey$1<Kubb.PluginOptionsRegistry, 'output'>;
+/**
+ * Groups generated files into subdirectories based on an OpenAPI tag or path
+ * segment.
+ */
 type Group = {
   /**
-   * How to group files into subdirectories.
-   * - `'tag'` — group by OpenAPI tags
-   * - `'path'` — group by OpenAPI paths
+   * Property used to assign each operation to a group.
+   * - `'tag'` — uses the first tag (`operation.getTags().at(0)?.name`).
+   * - `'path'` — uses the first segment of the operation's URL.
    */
   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.
+   * Returns the subdirectory name from the group key. Defaults to
+   * `${camelCase(group)}Controller` for tags, or the first path segment.
    */
   name?: (context: {
     group: string;
@@ -872,42 +952,39 @@ type ByContentType = {
   pattern: string | RegExp;
 };
 /**
- * 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.
+ * Filter that skips matching operations or schemas during generation. Use it
+ * to drop deprecated endpoints, internal-only schemas, or anything you do
+ * not want code generated for.
  *
  * @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
+ *   { type: 'tag', pattern: 'internal' },
+ *   { type: 'path', pattern: /^\/admin/ },
+ *   { type: 'operationId', pattern: /^deprecated_/ },
  * ]
  * ```
  */
 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.
+ * Filter that restricts generation to operations or schemas matching at least
+ * one entry. Useful for partial builds (one tag, one API version).
  *
  * @example
  * ```ts
  * include: [
- *   { type: 'tag', pattern: 'public' },        // generate only "public" tag
- *   { type: 'path', pattern: /^\/api\/v1/ },   // generate only v1 endpoints
+ *   { type: 'tag', pattern: 'public' },
+ *   { type: 'path', pattern: /^\/api\/v1/ },
  * ]
  * ```
  */
 type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
 /**
- * A pattern filter paired with partial option overrides applied when the pattern matches.
+ * Filter paired with a partial options object. When the filter matches, the
+ * options are merged on top of the plugin defaults for that operation only.
+ * Useful for "this one tag goes to a different folder" rules.
  *
- * 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.
+ * Entries are evaluated top to bottom; the first matching entry wins.
  *
  * @example
  * ```ts
@@ -915,13 +992,13 @@ type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySch
  *   {
  *     type: 'tag',
  *     pattern: 'admin',
- *     options: { output: { path: './src/gen/admin' } }  // admin APIs go to separate folder
+ *     options: { output: { path: './src/gen/admin' } },
  *   },
  *   {
  *     type: 'operationId',
  *     pattern: 'listPets',
- *     options: { exclude: true }  // skip this specific operation
- *   }
+ *     options: { enumType: 'literal' },
+ *   },
  * ]
  * ```
  */
@@ -1075,13 +1152,13 @@ type KubbPluginEndContext = {
   upsertFile: (...files: Array<FileNode>) => void;
 };
 /**
- * Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
- *
- * Handlers live in a single `hooks` object (inspired by Astro integrations).
- * All lifecycle events from `KubbHooks` are available for subscription.
+ * Wraps a plugin factory and returns a function that accepts user options and
+ * yields a fully typed `Plugin`. Lifecycle handlers go inside a single
+ * `hooks` object (inspired by Astro integrations).
  *
- * @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
- * Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
+ * Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
+ * `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
+ * convention (`plugin-react-query`, `plugin-zod`, ...).
  *
  * @example
  * ```ts
@@ -1343,8 +1420,8 @@ type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptio
  * Declares a named generator unit that walks the AST and emits files.
  *
  * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
- * Each method returns `TElement | Array<FileNode> | void`. JSX-based generators require a `renderer` factory.
- * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `void` to bypass rendering.
+ * Each method returns `TElement | Array<FileNode> | undefined | null`. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `undefined` or `null` to bypass rendering.
  *
  * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
@@ -1394,24 +1471,47 @@ type Generator$1<TOptions extends PluginFactoryOptions = PluginFactoryOptions, T
    * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
   /**
    * Called for each operation node in the AST walk.
    * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
   /**
    * Called once after all operations have been walked.
    * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the plugin-level options for the batch call.
    */
-  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
 };
 /**
- * Defines a generator. Returns the object as-is with correct `this` typings.
- * `applyHookResult` handles renderer elements and `File[]` uniformly using
- * the generator's declared `renderer` factory.
+ * Defines a generator: a unit of work that runs during the plugin's AST walk
+ * and produces files. Plugins register generators via `ctx.addGenerator()`
+ * inside `kubb:plugin:setup`.
+ *
+ * The returned object is the input as-is, but with `this` types preserved so
+ * `schema`/`operation`/`operations` methods are correctly typed against the
+ * plugin's `PluginFactoryOptions`. Renderer elements and `FileNode[]` returns
+ * are both handled by the runtime — pick whichever style fits.
+ *
+ * @example JSX-based schema generator
+ * ```tsx
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     return (
+ *       <File path={`${ctx.root}/${node.name}.ts`}>
+ *         <Type node={node} resolver={ctx.resolver} />
+ *       </File>
+ *     )
+ *   },
+ * })
+ * ```
  */
 declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator$1<TOptions, TElement>): Generator$1<TOptions, TElement>;
 //#endregion
@@ -1486,22 +1586,25 @@ type Config<TInput = Input> = {
    */
   name?: string;
   /**
-   * Project root directory, absolute or relative to the config file.
-   * @default process.cwd()
+   * Project root directory, absolute or relative to the config file. Already
+   * resolved on the `Config` instance — see `UserConfig` for the optional
+   * form that defaults to `process.cwd()`.
    */
   root: string;
   /**
-   * Parsers that convert generated files to strings.
-   * Each parser handles specific extensions (e.g. `.ts`, `.tsx`).
-   * A fallback parser is appended for unhandled extensions.
-   * When omitted, defaults to `parserTs` from `@kubb/parser-ts`.
+   * Parsers that convert generated files into strings. Each parser handles a
+   * set of file extensions; a fallback parser handles anything else.
+   *
+   * Already resolved on the `Config` instance — see `UserConfig` for the
+   * optional form that defaults to `[parserTs, parserTsx]`.
    *
-   * @default [parserTs] from `@kubb/parser-ts`
    * @example
    * ```ts
-   * import { parserTs, tsxParser } from '@kubb/parser-ts'
+   * import { defineConfig } from 'kubb'
+   * import { parserTs, parserTsx } from '@kubb/parser-ts'
+   *
    * export default defineConfig({
-   *   parsers: [parserTs, tsxParser],
+   *   parsers: [parserTs, parserTsx],
    * })
    * ```
    */
@@ -2192,6 +2295,11 @@ type CLIOptions = {
    * Path to the Kubb config file.
    */
   config?: string;
+  /**
+   * OpenAPI input path passed as the positional argument to `kubb generate`.
+   * Overrides `config.input.path` when set.
+   */
+  input?: string;
   /**
    * Re-run generation whenever input files change.
    */
@@ -2199,9 +2307,9 @@ type CLIOptions = {
   /**
    * Controls how much output the CLI prints.
    *
-   * @default 'silent'
+   * @default 'info'
    */
-  logLevel?: 'silent' | 'info' | 'debug';
+  logLevel?: 'silent' | 'info' | 'verbose' | 'debug';
 };
 /**
  * All accepted forms of a Kubb configuration.
@@ -2298,10 +2406,26 @@ declare class Kubb$1 {
   [Symbol.dispose](): void;
 }
 /**
- * Factory for {@link Kubb}. Equivalent to `new Kubb(userConfig, options)` and kept
- * as the canonical public entry point.
+ * Constructs a {@link Kubb} build orchestrator from a user config. Equivalent
+ * to `new Kubb(userConfig, options)` and the canonical public entry point.
+ *
+ * @example
+ * ```ts
+ * import { createKubb } from '@kubb/core'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * const kubb = createKubb({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
+ * })
+ *
+ * await kubb.build()
+ * ```
  */
 declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions): Kubb$1;
 //#endregion
 export { ResolverFileParams as $, createKubb as A, KubbPluginEndContext as B, KubbLifecycleStartContext as C, createAdapter as Ct, KubbWarnContext as D, KubbVersionNewContext as E, KubbDriver as F, Override as G, KubbPluginStartContext as H, FileManager as I, definePlugin as J, Plugin as K, Exclude as L, Generator$1 as M, GeneratorContext as N, PossibleConfig as O, defineGenerator as P, ResolverContext as Q, Group as R, KubbInfoContext as S, AdapterSource as St, KubbSuccessContext as T, AsyncEventEmitter as Tt, NormalizedPlugin as U, KubbPluginSetupContext as V, Output as W, ResolveOptionsContext as X, ResolveBannerContext as Y, Resolver as Z, KubbGenerationStartContext as _, Renderer as _t, InputPath as a, LoggerContext as at, KubbHookStartContext as b, Adapter as bt, KubbBuildStartContext as c, defineLogger as ct, KubbErrorContext as d, ParsedFile as dt, ResolverPathParams as et, KubbFileProcessingUpdate as f, Parser as ft, KubbGenerationEndContext as g, createStorage as gt, KubbFilesProcessingUpdateContext as h, Storage as ht, InputData as i, Logger as it, isInputPath as j, UserConfig as k, KubbConfigEndContext as l, FileProcessor as lt, KubbFilesProcessingStartContext as m, DevtoolsOptions as mt, CLIOptions as n, Middleware as nt, Kubb$1 as o, LoggerOptions as ot, KubbFilesProcessingEndContext as p, defineParser as pt, PluginFactoryOptions as q, Config as r, defineMiddleware as rt, KubbBuildEndContext as s, UserLogger as st, BuildOutput as t, defineResolver as tt, KubbDebugContext as u, FileProcessorEvents as ut, KubbGenerationSummaryContext as v, RendererFactory as vt, KubbPluginsEndContext as w, logLevel as wt, KubbHooks as x, AdapterFactoryOptions as xt, KubbHookEndContext as y, createRenderer as yt, Include as z };
-//# sourceMappingURL=createKubb-CYrw_xaR.d.ts.map
+//# sourceMappingURL=createKubb-CvfQXK_j.d.ts.map