@kubb/core 5.0.0-beta.61 → 5.0.0-beta.63

package/src/KubbDriver.ts

@@ -2,7 +2,7 @@ import { resolve } from 'node:path'
 import { arrayToAsyncIterable, type AsyncEventEmitter, forBatches, getElapsedMs, isPromise, memoize, Url } from '@internals/utils'
 import * as factory from '@kubb/ast/factory'
 import { collectUsedSchemaNames } from '@kubb/ast/utils'
-import type { FileNode, InputMeta, InputNode, OperationNode, SchemaNode } from '@kubb/ast'
+import type { Enforce, FileNode, InputMeta, InputNode, OperationNode, SchemaNode } from '@kubb/ast'
 import { OPERATION_FILTER_TYPES, SCHEMA_PARALLEL } from './constants.ts'
 import { type Diagnostic, Diagnostics, type ProblemDiagnostic } from './diagnostics.ts'
 import type { RendererFactory } from './createRenderer.ts'
@@ -45,7 +45,7 @@ type RequirePluginContext = {
   requiredBy?: string
 }
 
-function enforceOrder(enforce: 'pre' | 'post' | undefined): number {
+function enforceOrder(enforce: Enforce | undefined): number {
   return enforce === 'pre' ? -1 : enforce === 'post' ? 1 : 0
 }
 
@@ -108,6 +108,12 @@ export class KubbDriver {
     this.#listeners.push([event, handler as HookListener<Array<unknown>, unknown>])
   }
 
+  /**
+   * Normalizes every configured plugin, orders them, and registers their lifecycle handlers.
+   * A plugin that another lists as a dependency runs first, then `enforce: 'pre'` before
+   * `'post'`. When the config has an adapter, the adapter source is resolved from the input
+   * so `run` can parse it later.
+   */
   async setup() {
     const normalized: Array<NormalizedPlugin> = this.config.plugins.map((rawPlugin) => this.#normalizePlugin(rawPlugin as Plugin))
 
@@ -139,8 +145,9 @@ export class KubbDriver {
   }
 
   /**
-   * Creates an `NormalizedPlugin` from a hook-style plugin and registers
-   * its lifecycle handlers on the `AsyncEventEmitter`.
+   * Builds a `NormalizedPlugin` from a hook-style plugin, filling in default
+   * options and copying `apply` when present. Registering its lifecycle handlers
+   * on the `AsyncEventEmitter` is done separately by `#registerPlugin`.
    */
   #normalizePlugin(plugin: Plugin): NormalizedPlugin {
     const normalized: NormalizedPlugin = {
@@ -250,7 +257,7 @@ export class KubbDriver {
    * Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
    * can configure generators, resolvers, macros and renderers before `buildStart` runs.
    *
-   * Call this once from `safeBuild` before the plugin execution loop begins.
+   * Called once from `run` before the plugin execution loop begins.
    */
   async emitSetupHooks(): Promise<void> {
     const noop = () => {}
@@ -282,37 +289,21 @@ export class KubbDriver {
    * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
    */
   registerGenerator(pluginName: string, generator: Generator): void {
-    if (generator.schema) {
-      const schemaHandler = async (node: SchemaNode, ctx: GeneratorContext) => {
-        if (ctx.plugin.name !== pluginName) return
-        const result = await generator.schema!(node, ctx)
-
-        await this.dispatch({ result, renderer: generator.renderer })
-      }
-
-      this.#trackListener('kubb:generate:schema', schemaHandler)
-    }
+    const register = <TNode>(event: keyof KubbHooks & string, method: ((node: TNode, ctx: GeneratorContext) => unknown) | undefined): void => {
+      if (!method) return
 
-    if (generator.operation) {
-      const operationHandler = async (node: OperationNode, ctx: GeneratorContext) => {
+      const handler = async (node: TNode, ctx: GeneratorContext) => {
         if (ctx.plugin.name !== pluginName) return
-
-        const result = await generator.operation!(node, ctx)
+        const result = await method(node, ctx)
         await this.dispatch({ result, renderer: generator.renderer })
       }
 
-      this.#trackListener('kubb:generate:operation', operationHandler)
+      this.#trackListener(event, handler as HookListener<KubbHooks[typeof event], unknown>)
     }
 
-    if (generator.operations) {
-      const operationsHandler = async (nodes: Array<OperationNode>, ctx: GeneratorContext) => {
-        if (ctx.plugin.name !== pluginName) return
-        const result = await generator.operations!(nodes, ctx)
-        await this.dispatch({ result, renderer: generator.renderer })
-      }
-
-      this.#trackListener('kubb:generate:operations', operationsHandler)
-    }
+    register('kubb:generate:schema', generator.schema)
+    register('kubb:generate:operation', generator.operation)
+    register('kubb:generate:operations', generator.operations)
 
     this.#eventGeneratorPlugins.add(pluginName)
   }
@@ -422,8 +413,8 @@ export class KubbDriver {
           }
 
           // Stream every node through the transform registry and into each plugin's generators.
-          // Handles the empty-entries and missing-`inputNode` cases by closing out each entry's
-          // `kubb:plugin:end` directly.
+          // When there are no entries it returns early. When `inputNode` is missing it still
+          // closes out each entry's `kubb:plugin:end` directly.
           diagnostics.push(...(await this.#runGenerators(generatorPlugins, () => processor.flush())))
           // Wait for the last in-flight batch and write anything still pending.
           await processor.drain()
@@ -480,8 +471,8 @@ export class KubbDriver {
    * That ordering is what drives the CLI's `Plugins N/M` counter. Without it the bar would
    * sit at the initial value until the very end of the run.
    *
-   * When `entries` is empty or `this.inputNode` is `null`, every entry still gets a
-   * `kubb:plugin:end` so post-plugin listeners (the barrel writer and friends) complete.
+   * When `this.inputNode` is `null`, every entry still gets a `kubb:plugin:end` so
+   * post-plugin listeners (the barrel writer and friends) complete.
    */
   async #runGenerators(
     entries: Array<{ plugin: NormalizedPlugin; context: Omit<GeneratorContext, 'options'>; hrStart: ReturnType<typeof process.hrtime> }>,

package/src/Transform.ts

@@ -10,7 +10,7 @@ import { composeMacros, transform } from '@kubb/ast'
  * leaves the tree untouched, so callers can detect a no-op by identity.
  *
  * Registration order matches the order setup hooks fire, which the driver has already sorted by
- * `enforce` and dependency edges. The registry preserves that order; macro `enforce` only reorders
+ * `enforce` and dependency edges. The registry preserves that order. Macro `enforce` only reorders
  * within a single plugin's list.
  */
 export class Transform {

package/src/createAdapter.ts

@@ -112,12 +112,12 @@ type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) =
  *   options,
  *   document: null,
  *   async parse(_source) {
- *     // Convert `source` (path or inline data) into an InputNode.
+ *     // Convert the source (path or inline data) into an InputNode.
  *     return ast.factory.createInput()
  *   },
  *   getImports: () => [],
  *   async validate() {
- *     // Throw or call ctx.error here when the spec is invalid.
+ *     // Throw here when the spec is invalid.
  *   },
  * }))
  * ```

package/src/createKubb.ts

@@ -74,9 +74,8 @@ type CreateKubbOptions = {
  * config in the constructor, so `config` is available right away, and shares `hooks`,
  * `storage`, and `driver` across the `setup → build` lifecycle.
  *
- * `createKubb` takes a plain, serializable config object (the shape `defineConfig`
- * produces), not a fluent builder. Config stays plain data so it can be cache
- * fingerprinted and validated against the shipped JSON schema.
+ * `createKubb` takes a plain config object (the shape `defineConfig` produces),
+ * not a fluent builder.
  *
  * Attach event listeners to `.hooks` before calling `setup()` or `build()`.
  *

package/src/createReporter.ts

@@ -44,13 +44,13 @@ export type GenerationResult = {
 }
 
 /**
- * Render context passed alongside the {@link GenerationResult}, carrying knobs a reporter needs
- * but that are not part of the run data (e.g. verbosity).
+ * Render settings passed alongside the {@link GenerationResult}. These are not part of the run
+ * data, such as the output verbosity.
  */
 export type ReporterContext = {
   /**
    * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
-   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
+   * (`silent`, `error`, `warn`, `info`, `verbose`).
    */
   logLevel: (typeof logLevel)[keyof typeof logLevel]
 }
@@ -71,7 +71,7 @@ export type Reporter = {
   report: (result: GenerationResult, context: ReporterContext) => void | Promise<void>
   /**
    * Optional finalizer called once after the run's last config. The host wires it to
-   * `kubb:lifecycle:end`. {@link createReporter} closes it over the reports `report` returned.
+   * `kubb:lifecycle:end`. {@link createReporter} closes it over the values that `report` returned.
    */
   drain?: (context: ReporterContext) => void | Promise<void>
 }

package/src/createStorage.ts

@@ -34,8 +34,8 @@ export type Storage = {
    */
   clear(base?: string): Promise<void>
   /**
-   * Optional teardown hook called after the build completes. Use to flush
-   * buffers, close connections, or release file locks.
+   * Optional teardown hook for a backend to flush buffers, close connections,
+   * or release file locks.
    */
   dispose?(): Promise<void>
 }

package/src/defineGenerator.ts

@@ -9,11 +9,11 @@ import type { Resolver } from './defineResolver.ts'
 import type { Config } from './types.ts'
 
 /**
- * Context object passed to generator `schema`, `operation`, and `operations` methods.
+ * Context passed to a generator's `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.
+ * The driver sets `adapter` on the context before it runs a generator, so methods can read it
+ * without a null check. `ctx.options` carries the per-node options after exclude/include/override
+ * filtering for `schema` and `operation`, or the plugin-level options for `operations`.
  */
 export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
@@ -109,9 +109,10 @@ export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFacto
 /**
  * Declares a named generator unit that walks the AST and emits files.
  *
- * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
- * JSX-based generators require a `renderer` factory. Return `Array<FileNode>` directly, or call
- * `ctx.upsertFile()` manually and return `null` to bypass rendering.
+ * `schema` runs for each schema node and `operation` for each operation node. `operations` runs
+ * once after every operation node is walked. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly, or call `ctx.upsertFile()` manually and return `null` to
+ * bypass rendering.
  *
  * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *

package/src/defineParser.ts

@@ -15,8 +15,9 @@ export type Parser<TMeta extends object = object, TNode = unknown> = {
    */
   name: string
   /**
-   * File extensions this parser handles. Set to `undefined` to define a
-   * catch-all fallback used when no other parser claims the extension.
+   * File extensions this parser handles. The driver registers the parser for each
+   * extension in this list. A parser with `undefined` here is not registered, so
+   * files of an unclaimed extension fall back to joining their sources verbatim.
    *
    * @example
    * `['.ts', '.js']`

package/src/definePlugin.ts

@@ -1,4 +1,4 @@
-import type { FileNode, HttpMethod, Macro, UserFileNode } from '@kubb/ast'
+import type { Enforce, FileNode, HttpMethod, Macro, UserFileNode } from '@kubb/ast'
 import { diagnosticCode } from './constants.ts'
 import type { Generator } from './defineGenerator.ts'
 import type { BannerMeta, Resolver } from './defineResolver.ts'
@@ -79,8 +79,8 @@ export type Group = {
    */
   type: 'tag' | 'path'
   /**
-   * Returns the subdirectory name from the group key. Defaults to the
-   * camelCased tag for `tag` groups, or the first path segment for `path` groups.
+   * Returns the subdirectory name from the group key. Defaults to the camelCased tag for
+   * `tag` groups, or the camelCased first path segment for `path` groups.
    */
   name?: (context: { group: string }) => string
 }
@@ -169,11 +169,12 @@ type ByPath = {
 
 type ByMethod = {
   /**
-   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   * Filter by HTTP method: `'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, `'DELETE'`, `'HEAD'`, `'OPTIONS'`, `'TRACE'`.
    */
   type: 'method'
   /**
-   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   * HTTP method to match, as one of the `HttpMethod` values (`'GET'`, `'POST'`, `'PUT'`,
+   * `'PATCH'`, `'DELETE'`, `'HEAD'`, `'OPTIONS'`, `'TRACE'`) or a regex.
    */
   pattern: HttpMethod | RegExp
 }
@@ -347,11 +348,11 @@ export type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>
    *
    * - `'pre'` runs before all normal plugins.
    * - `'post'` runs after all normal plugins.
-   * - `undefined` (default), runs in declaration order among normal plugins.
+   * - `undefined` (default) runs in declaration order among normal plugins.
    *
    * Dependency constraints always take precedence over `enforce`.
    */
-  enforce?: 'pre' | 'post'
+  enforce?: Enforce
   /**
    * The options passed by the user when calling the plugin factory.
    */

package/src/diagnostics.ts

@@ -235,7 +235,7 @@ const severityStyle: Record<DiagnosticSeverity, { glyph: string; color: 'red' |
 /**
  * A {@link Diagnostic} reduced to its JSON-safe fields plus a `docsUrl`, for
  * machine-readable output (the `--reporter json` report, the MCP tools). Drops the
- * non-serializable `cause` and the `timing`/`duration` bookkeeping.
+ * non-serializable `cause` and the `kind`/`duration` bookkeeping.
  */
 export type SerializedDiagnostic = {
   code: DiagnosticCode
@@ -541,8 +541,8 @@ export class Diagnostics {
   }
 
   /**
-   * Counts `problem` diagnostics by severity for the run summary. `timing`
-   * diagnostics are ignored.
+   * Counts `problem` diagnostics by severity for the run summary. `performance` and
+   * `update` diagnostics are ignored.
    */
   static count(diagnostics: ReadonlyArray<Diagnostic>): { errors: number; warnings: number; infos: number } {
     let errors = 0

package/src/mocks.ts

@@ -11,7 +11,7 @@ import { memoryStorage } from './storages/memoryStorage.ts'
 import type { Adapter, AdapterFactoryOptions, Config, Generator, GeneratorContext, NormalizedPlugin, PluginFactoryOptions, RendererFactory } from './types.ts'
 
 /**
- * Creates a minimal `PluginDriver` mock for unit tests.
+ * Creates a minimal `KubbDriver` mock for unit tests.
  */
 export function createMockedPluginDriver(options: { name?: string; plugin?: NormalizedPlugin; config?: Config } = {}): KubbDriver {
   const fileManager = new FileManager()

package/src/reporters/fileReporter.ts

@@ -74,12 +74,11 @@ function buildTimingSection(report: Report): Array<string> {
  * The `file` reporter. Writes a config's {@link Report} to `.kubb/kubb-<name>-<timestamp>.log` as a
  * plain-text document: a `# <name> — <timestamp>` header, a `## Summary` with the same counts the
  * cli and json reporters expose, a `## Problems` section in the miette block format, and a
- * `## Timings` section. Selected with `--reporter file` (or `reporters: ['file']`), replacing the
- * old `--debug` flag.
+ * `## Timings` section. Selected with `--reporter file` (or `reporters: ['file']`).
  *
- * @note Unlike the streaming logger it replaced, it captures the collected diagnostics once a
- * config finishes, not the live `kubb:info`/`kubb:plugin` event stream. Color is stripped so the
- * file stays plain text even when the run is attached to a TTY.
+ * @note It captures the collected diagnostics once a config finishes, not the live
+ * `kubb:info`/`kubb:plugin` event stream. Color is stripped so the file stays plain text even when
+ * the run is attached to a TTY.
  */
 export const fileReporter = createReporter({
   name: 'file',

package/src/types.ts

@@ -149,7 +149,7 @@ export type Config<TInput = Input> = {
      *
      * @example
      * ```ts
-     * format: 'auto'        // auto-detect prettier, biome, or oxfmt
+     * format: 'auto'        // auto-detect oxfmt, biome, or prettier
      * format: 'prettier'    // force prettier
      * format: false         // skip formatting
      * ```