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

package/src/createKubb.ts

@@ -1,21 +1,19 @@
 import { resolve } from 'node:path'
 import { version as nodeVersion } from 'node:process'
 import type { PossiblePromise } from '@internals/utils'
-import { AsyncEventEmitter, BuildError, exists, forBatches, formatMs, getElapsedMs, URLPath, isPromise, withDrain } from '@internals/utils'
+import { AsyncEventEmitter, BuildError, exists, URLPath } from '@internals/utils'
 import type { FileNode, InputMeta, OperationNode, SchemaNode } from '@kubb/ast'
-import { collectUsedSchemaNames, transform } from '@kubb/ast'
 import { version as KubbVersion } from '../package.json'
-import { DEFAULT_BANNER, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL, SCHEMA_PARALLEL, STREAM_FLUSH_EVERY } from './constants.ts'
+import { DEFAULT_BANNER, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
 import type { Adapter } from './createAdapter.ts'
 import type { RendererFactory } from './createRenderer.ts'
 import { createStorage, type Storage } from './createStorage.ts'
-import type { GeneratorContext, Generator } from './defineGenerator.ts'
+import type { GeneratorContext } from './defineGenerator.ts'
 import type { Middleware } from './defineMiddleware.ts'
 import type { Parser } from './defineParser.ts'
-import type { KubbPluginEndContext, KubbPluginSetupContext, KubbPluginStartContext, NormalizedPlugin, Plugin } from './definePlugin.ts'
-import { FileProcessor } from './FileProcessor.ts'
+import type { KubbPluginEndContext, KubbPluginSetupContext, KubbPluginStartContext, Plugin } from './definePlugin.ts'
 
-import { applyHookResult, KubbDriver } from './KubbDriver.ts'
+import { KubbDriver } from './KubbDriver.ts'
 import { fsStorage } from './storages/fsStorage.ts'
 
 /**
@@ -517,7 +515,7 @@ export interface KubbHooks {
   'kubb:warn': [ctx: KubbWarnContext]
   'kubb:debug': [ctx: KubbDebugContext]
   'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext]
-  'kubb:file:processing:update': [ctx: KubbFileProcessingUpdateContext]
+  'kubb:files:processing:update': [ctx: KubbFilesProcessingUpdateContext]
   'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext]
   'kubb:plugin:start': [ctx: KubbPluginStartContext]
   'kubb:plugin:end': [ctx: KubbPluginEndContext]
@@ -736,7 +734,7 @@ export type KubbFilesProcessingStartContext = {
   files: Array<FileNode>
 }
 
-export type KubbFileProcessingUpdateContext = {
+export type KubbFileProcessingUpdate = {
   /**
    * Number of files processed so far in this batch.
    */
@@ -763,6 +761,13 @@ export type KubbFileProcessingUpdateContext = {
   config: Config
 }
 
+export type KubbFilesProcessingUpdateContext = {
+  /**
+   * All files processed in this flush chunk.
+   */
+  files: Array<KubbFileProcessingUpdate>
+}
+
 export type KubbFilesProcessingEndContext = {
   /**
    * All files that were serialised in this batch.
@@ -836,10 +841,6 @@ export type PossibleConfig<TCliOptions = undefined> =
   | PossiblePromise<Config | Config[]>
   | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>)
 
-type SetupOptions = {
-  hooks?: AsyncEventEmitter<KubbHooks>
-}
-
 /**
  * Full output produced by a successful or failed build.
  */
@@ -877,76 +878,11 @@ export type BuildOutput = {
   storage: Storage
 }
 
-/**
- * Kubb code generation instance returned by {@link createKubb}.
- *
- * Use this when orchestrating multiple builds, inspecting plugin timings, or integrating Kubb into a larger toolchain.
- * For a single one-off build, chain directly: `await createKubb(config).build()`.
- */
-export type Kubb = {
-  /**
-   * Shared event emitter for lifecycle and status events. Attach listeners before calling `setup()` or `build()`.
-   */
-  readonly hooks: AsyncEventEmitter<KubbHooks>
-  /**
-   * Read-only view of the files from the most recent `build()` or `safeBuild()` call.
-   * Only populated after the build completes.
-   *
-   * Keys are scoped to the current run. Reads go straight to `config.storage`,
-   * so nothing extra is held in memory.
-   *
-   * @example Read a generated file
-   * ```ts
-   * const { storage } = await kubb.safeBuild()
-   * const code = await storage.getItem('/src/gen/pet.ts')
-   * ```
-   *
-   * @example Walk every generated file
-   * ```ts
-   * for (const path of await kubb.storage.getKeys()) {
-   *   const code = await kubb.storage.getItem(path)
-   * }
-   * ```
-   */
-  readonly storage: Storage
-  /**
-   * Plugin driver managing all plugins. Available after `setup()` completes.
-   */
-  readonly driver: KubbDriver
-  /**
-   * Resolved configuration with defaults applied. Available after `setup()` completes.
-   */
-  readonly config: Config
-  /**
-   * Resolves config and initializes the driver. `build()` calls this automatically.
-   */
-  setup(): Promise<void>
-  /**
-   * Runs the full pipeline and throws on any plugin error. Automatically calls `setup()` if needed.
-   */
-  build(): Promise<BuildOutput>
-  /**
-   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing. Automatically calls `setup()` if needed.
-   */
-  safeBuild(): Promise<BuildOutput>
-}
-
-type SetupResult = {
-  hooks: AsyncEventEmitter<KubbHooks>
-  driver: KubbDriver
-  storage: Storage
-  config: Config
-  dispose: () => void
-  [Symbol.dispose](): void
-}
-
 /**
  * Builds a `Storage` view scoped to the file paths produced by the current build.
- *
- * Reads delegate to the underlying `storage` (typically `fsStorage()`) so source bytes
- * stay where they were written instead of being held in an extra in-memory map.
- * Writing via `setItem` stores the content in the underlying storage and registers the
- * key so subsequent reads and `getKeys` are scoped to this build's output.
+ * Reads delegate to the underlying `storage` so source bytes stay where they were
+ * written; writes register the key so subsequent reads and `getKeys` are scoped
+ * to this build's output.
  */
 function createSourcesView(storage: Storage): Storage {
   const paths = new Set<string>()
@@ -982,9 +918,8 @@ function createSourcesView(storage: Storage): Storage {
   }))()
 }
 
-async function setup(userConfig: UserConfig, options: SetupOptions = {}): Promise<SetupResult> {
-  const hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
-  const config: Config = {
+function resolveConfig(userConfig: UserConfig): Config {
+  return {
     ...userConfig,
     root: userConfig.root || process.cwd(),
     parsers: userConfig.parsers ?? [],
@@ -1004,518 +939,6 @@ async function setup(userConfig: UserConfig, options: SetupOptions = {}): Promis
       : undefined,
     plugins: (userConfig.plugins ?? []) as unknown as Config['plugins'],
   }
-  const driver = new KubbDriver(config, {
-    hooks,
-  })
-  const storage = createSourcesView(config.storage)
-  const diagnosticInfo = getDiagnosticInfo()
-
-  await hooks.emit('kubb:debug', {
-    date: new Date(),
-    logs: [
-      'Configuration:',
-      `  • Name: ${userConfig.name || 'unnamed'}`,
-      `  • Root: ${userConfig.root || process.cwd()}`,
-      `  • Output: ${userConfig.output?.path || 'not specified'}`,
-      `  • Plugins: ${userConfig.plugins?.length || 0}`,
-      'Output Settings:',
-      `  • Storage: ${config.storage.name}`,
-      `  • Formatter: ${userConfig.output?.format || 'none'}`,
-      `  • Linter: ${userConfig.output?.lint || 'none'}`,
-      `Running adapter: ${config.adapter?.name || 'none'}`,
-      'Environment:',
-      Object.entries(diagnosticInfo)
-        .map(([key, value]) => `  • ${key}: ${value}`)
-        .join('\n'),
-    ],
-  })
-
-  try {
-    if (isInputPath(userConfig) && !new URLPath(userConfig.input.path).isURL) {
-      await exists(userConfig.input.path)
-
-      await hooks.emit('kubb:debug', {
-        date: new Date(),
-        logs: [`✓ Input file validated: ${userConfig.input.path}`],
-      })
-    }
-  } catch (caughtError) {
-    if (isInputPath(userConfig)) {
-      const error = caughtError as Error
-
-      throw new Error(
-        `Cannot read file/URL defined in \`input.path\` or set with \`kubb generate PATH\` in the CLI of your Kubb config ${userConfig.input.path}`,
-        {
-          cause: error,
-        },
-      )
-    }
-  }
-
-  if (config.output.clean) {
-    await hooks.emit('kubb:debug', {
-      date: new Date(),
-      logs: ['Cleaning output directories', `  • Output: ${config.output.path}`],
-    })
-
-    await config.storage.clear(resolve(config.root, config.output.path))
-  }
-
-  await driver.setup()
-
-  return {
-    config,
-    hooks,
-    driver,
-    storage,
-    dispose,
-    [Symbol.dispose]: dispose,
-  }
-
-  function dispose() {
-    driver.dispose()
-  }
-}
-
-type GeneratorEntry = { plugin: NormalizedPlugin; context: GeneratorContext; hrStart: ReturnType<typeof process.hrtime> }
-
-async function safeBuild(setupResult: SetupResult): Promise<BuildOutput> {
-  using _cleanup = setupResult
-  const { driver, hooks, storage } = setupResult
-
-  const failedPlugins = new Set<{ plugin: Plugin; error: Error }>()
-  const pluginTimings = new Map<string, number>()
-  const config = driver.config
-  const writtenPaths = new Set<string>()
-  const parsersMap = new Map<FileNode['extname'], Parser>()
-  const fileProcessor = new FileProcessor()
-
-  for (const parser of config.parsers) {
-    if (parser.extNames) {
-      for (const extname of parser.extNames) {
-        parsersMap.set(extname, parser)
-      }
-    }
-  }
-
-  async function flushPendingFiles(): Promise<void> {
-    const files = driver.fileManager.files.filter((f) => !writtenPaths.has(f.path))
-    if (files.length === 0) {
-      return
-    }
-
-    await hooks.emit('kubb:debug', {
-      date: new Date(),
-      logs: [`Writing ${files.length} files...`],
-    })
-
-    await hooks.emit('kubb:files:processing:start', { files })
-
-    const stream = fileProcessor.stream(files, { parsers: parsersMap, extension: config.output.extension })
-
-    const queue: Array<Promise<void>> = []
-    for (const { file, source, processed, total, percentage } of stream) {
-      writtenPaths.add(file.path)
-      queue.push(
-        (async () => {
-          await hooks.emit('kubb:file:processing:update', { file, source, processed, total, percentage, config })
-          if (source) {
-            await storage.setItem(file.path, source)
-          }
-        })(),
-      )
-      if (queue.length >= STREAM_FLUSH_EVERY) {
-        await Promise.all(queue.splice(0))
-      }
-    }
-    await Promise.all(queue)
-
-    await hooks.emit('kubb:files:processing:end', { files })
-    await hooks.emit('kubb:debug', {
-      date: new Date(),
-      logs: [`✓ File write process completed for ${files.length} files`],
-    })
-  }
-
-  async function dispatchOperationsToGenerators(
-    generators: Generator[],
-    collectedOperations: OperationNode[],
-    ctx: GeneratorContext,
-    rendererFor: (gen: Generator) => RendererFactory | undefined,
-  ): Promise<void> {
-    for (const gen of generators) {
-      if (!gen.operations) continue
-      const result = await gen.operations(collectedOperations, ctx)
-      await applyHookResult({ result, driver, rendererFactory: rendererFor(gen) })
-    }
-    await driver.hooks.emit('kubb:generate:operations', collectedOperations, ctx)
-  }
-
-  /**
-   * Single-pass fan-out: iterates all schemas and operations once, distributing each node
-   * to every generator-plugin in parallel. This replaces the N-pass-per-plugin pattern
-   * (each plugin getting its own iterator) with one parse pass fanned to all plugins,
-   * eliminating the N×parse-time overhead for multi-plugin builds.
-   */
-  async function runPlugins(entries: Array<GeneratorEntry>): Promise<void> {
-    type PluginState = {
-      plugin: NormalizedPlugin
-      generatorContext: GeneratorContext
-      generators: Generator[]
-      hrStart: ReturnType<typeof process.hrtime>
-      failed: boolean
-      error: Error | undefined
-      /**
-       * `true` when the plugin's options have no `include`, `exclude`, or `override`
-       * filters. The per-node `resolveOptions` call always returns the same `options`
-       * reference in that case, so the inner loop can skip it entirely.
-       */
-      optionsAreStatic: boolean
-      /**
-       * Set when the plugin has operation-based includes (tag, operationId, path, method, contentType)
-       * but no schemaName includes. Schema nodes whose name is not in this set are skipped,
-       * matching the pruning behavior of the eager path.
-       */
-      allowedSchemaNames: Set<string> | undefined
-    }
-
-    const { schemas, operations } = driver.inputNode!
-    const operationFilterTypes = new Set(['tag', 'operationId', 'path', 'method', 'contentType'])
-    const states: PluginState[] = entries.map(({ plugin, context, hrStart }) => {
-      const { exclude, include, override } = plugin.options
-      const hasExclude = Array.isArray(exclude) && exclude.length > 0
-      const hasInclude = Array.isArray(include) && include.length > 0
-      const hasOverride = Array.isArray(override) && override.length > 0
-      return {
-        plugin,
-        generatorContext: { ...context, resolver: driver.getResolver(plugin.name) },
-        generators: plugin.generators ?? [],
-        hrStart,
-        failed: false,
-        error: undefined,
-        optionsAreStatic: !hasExclude && !hasInclude && !hasOverride,
-        allowedSchemaNames: undefined,
-      }
-    })
-
-    // Pre-scan: compute allowedSchemaNames for plugins that use operation-based includes
-    // without schemaName filters. Each AsyncIterable yields a fresh iterator on every call,
-    // so consuming them here does not affect the main dispatch passes below.
-    const pruningStates = states.filter(({ plugin }) => {
-      const { include } = plugin.options
-      return (include?.some(({ type }) => operationFilterTypes.has(type)) ?? false) && !(include?.some(({ type }) => type === 'schemaName') ?? false)
-    })
-
-    if (pruningStates.length > 0) {
-      // Known trade-off: computing the reachable-schema set for operation-based includes
-      // requires the full schema graph in memory at once — there is no way to determine
-      // transitive reachability from a single schema node in isolation.
-      // `allSchemas` is released as soon as this block exits; it is never held past
-      // the pruning pre-scan. The main dispatch passes below each get their own
-      // fresh iterator from the AsyncIterable, so this consumption does not affect them.
-      const allSchemas: SchemaNode[] = []
-      for await (const schema of schemas) {
-        allSchemas.push(schema)
-      }
-
-      // Collect the included operations for each pruning plugin in one shared pass.
-      const includedOpsByState = new Map<PluginState, OperationNode[]>(pruningStates.map((s) => [s, []]))
-      for await (const operation of operations) {
-        for (const state of pruningStates) {
-          const { exclude, include, override } = state.plugin.options
-          const options = state.generatorContext.resolver.resolveOptions(operation, { options: state.plugin.options, exclude, include, override })
-          if (options !== null) includedOpsByState.get(state)?.push(operation)
-        }
-      }
-
-      // Derive the allowed schema name set per pruning plugin.
-      for (const state of pruningStates) {
-        state.allowedSchemaNames = collectUsedSchemaNames(includedOpsByState.get(state) ?? [], allSchemas)
-      }
-    }
-
-    function resolveRendererFor(gen: Generator, state: PluginState): RendererFactory | undefined {
-      return gen.renderer === null ? undefined : (gen.renderer ?? state.plugin.renderer ?? state.generatorContext.config.renderer)
-    }
-
-    async function dispatchSchema(state: PluginState, node: SchemaNode): Promise<void> {
-      if (state.failed) return
-
-      try {
-        const { plugin, generatorContext, generators } = state
-
-        const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
-
-        // Skip named top-level schemas not reachable from any included operation.
-        if (state.allowedSchemaNames !== undefined && transformedNode.name && !state.allowedSchemaNames.has(transformedNode.name)) {
-          return
-        }
-
-        const { exclude, include, override } = plugin.options
-        const options = state.optionsAreStatic
-          ? plugin.options
-          : generatorContext.resolver.resolveOptions(transformedNode, { options: plugin.options, exclude, include, override })
-        if (options === null) return
-
-        const ctx = { ...generatorContext, options }
-
-        for (const gen of generators) {
-          if (!gen.schema) continue
-          const raw = gen.schema(transformedNode, ctx)
-          const result = isPromise(raw) ? await raw : raw
-          const applied = applyHookResult({ result, driver, rendererFactory: resolveRendererFor(gen, state) })
-          if (isPromise(applied)) await applied
-        }
-
-        await driver.hooks.emit('kubb:generate:schema', transformedNode, ctx)
-      } catch (caughtError) {
-        state.failed = true
-        state.error = caughtError as Error
-      }
-    }
-
-    async function dispatchOperation(state: PluginState, node: OperationNode): Promise<void> {
-      if (state.failed) return
-
-      try {
-        const { plugin, generatorContext, generators } = state
-
-        const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
-        const { exclude, include, override } = plugin.options
-        const options = state.optionsAreStatic
-          ? plugin.options
-          : generatorContext.resolver.resolveOptions(transformedNode, { options: plugin.options, exclude, include, override })
-        if (options === null) return
-
-        const ctx = { ...generatorContext, options }
-
-        for (const gen of generators) {
-          if (!gen.operation) continue
-          const raw = gen.operation(transformedNode, ctx)
-          const result = isPromise(raw) ? await raw : raw
-          const applied = applyHookResult({ result, driver, rendererFactory: resolveRendererFor(gen, state) })
-          if (isPromise(applied)) await applied
-        }
-
-        await driver.hooks.emit('kubb:generate:operation', transformedNode, ctx)
-      } catch (caughtError) {
-        state.failed = true
-        state.error = caughtError as Error
-      }
-    }
-
-    // Batch schemas: SCHEMA_PARALLEL nodes dispatched across all plugins concurrently.
-    // Per-plugin work inside dispatchSchema stays sequential so FileManager.upsert
-    // ordering for any single plugin chain remains deterministic.
-    await forBatches(schemas, (nodes) => Promise.all(nodes.flatMap((n) => states.map((state) => dispatchSchema(state, n)))), {
-      concurrency: SCHEMA_PARALLEL,
-      flush: flushPendingFiles,
-    })
-
-    const collectedOperations: OperationNode[] = []
-
-    await forBatches(
-      operations,
-      (nodes) => {
-        collectedOperations.push(...nodes)
-        return Promise.all(nodes.flatMap((n) => states.map((state) => dispatchOperation(state, n))))
-      },
-      { concurrency: SCHEMA_PARALLEL, flush: flushPendingFiles },
-    )
-
-    for (const state of states) {
-      if (!state.failed) {
-        try {
-          const { plugin, generatorContext, generators } = state
-          const ctx = { ...generatorContext, options: plugin.options }
-          await dispatchOperationsToGenerators(generators, collectedOperations, ctx, (gen) => resolveRendererFor(gen, state))
-        } catch (caughtError) {
-          state.failed = true
-          state.error = caughtError as Error
-        }
-      }
-
-      const duration = getElapsedMs(state.hrStart)
-      pluginTimings.set(state.plugin.name, duration)
-
-      await driver.hooks.emit('kubb:plugin:end', {
-        plugin: state.plugin,
-        duration,
-        success: !state.failed,
-        ...(state.failed && state.error ? { error: state.error } : {}),
-        config: driver.config,
-        get files() {
-          return driver.fileManager.files
-        },
-        upsertFile: (...files) => driver.fileManager.upsert(...files),
-      })
-
-      if (state.failed && state.error) {
-        failedPlugins.add({ plugin: state.plugin, error: state.error })
-      }
-
-      await driver.hooks.emit('kubb:debug', {
-        date: new Date(),
-        logs: [state.failed ? '✗ Plugin start failed' : `✓ Plugin started successfully (${formatMs(duration)})`],
-      })
-    }
-  }
-
-  try {
-    await driver.emitSetupHooks()
-
-    if (driver.adapter && driver.inputNode) {
-      await hooks.emit('kubb:build:start', {
-        config,
-        adapter: driver.adapter,
-        meta: driver.inputNode.meta,
-        getPlugin: driver.getPlugin.bind(driver),
-        get files() {
-          return driver.fileManager.files
-        },
-        upsertFile: (...files) => driver.fileManager.upsert(...files),
-      })
-    }
-
-    // Always run the plugin lifecycle so middleware hooks (kubb:plugin:start,
-    // kubb:plugin:end) fire even when no adapter is configured.
-    // Generator-plugins are collected for the stream fan-out pass below.
-    const generatorPlugins: Array<GeneratorEntry> = []
-
-    for (const plugin of driver.plugins.values()) {
-      const context = driver.getContext(plugin)
-      const hrStart = process.hrtime()
-
-      try {
-        await hooks.emit('kubb:plugin:start', { plugin })
-        await hooks.emit('kubb:debug', {
-          date: new Date(),
-          logs: ['Starting plugin...', `  • Plugin Name: ${plugin.name}`],
-        })
-      } catch (caughtError) {
-        const error = caughtError as Error
-        const duration = getElapsedMs(hrStart)
-        pluginTimings.set(plugin.name, duration)
-        await hooks.emit('kubb:plugin:end', {
-          plugin,
-          duration,
-          success: false,
-          error,
-          config,
-          get files() {
-            return driver.fileManager.files
-          },
-          upsertFile: (...files) => driver.fileManager.upsert(...files),
-        })
-        failedPlugins.add({ plugin, error })
-        continue
-      }
-
-      if (plugin.generators?.length || driver.hasEventGenerators(plugin.name)) {
-        generatorPlugins.push({ plugin, context, hrStart })
-        continue
-      }
-      // No generators: plugin ran via setup hooks; finish it now.
-      const duration = getElapsedMs(hrStart)
-      pluginTimings.set(plugin.name, duration)
-      await hooks.emit('kubb:plugin:end', {
-        plugin,
-        duration,
-        success: true,
-        config,
-        get files() {
-          return driver.fileManager.files
-        },
-        upsertFile: (...files) => driver.fileManager.upsert(...files),
-      })
-      await hooks.emit('kubb:debug', {
-        date: new Date(),
-        logs: [`✓ Plugin started successfully (${formatMs(duration)})`],
-      })
-    }
-
-    if (generatorPlugins.length > 0) {
-      if (driver.inputNode) {
-        // Normal path: fan-out schemas and operations to all generator-plugins in one pass.
-        await withDrain(() => runPlugins(generatorPlugins), flushPendingFiles)
-      } else {
-        // No adapter configured — generator-plugins have nothing to process.
-        // Still emit plugin:end so middleware hooks (e.g. barrel) complete their lifecycle.
-        for (const { plugin, hrStart } of generatorPlugins) {
-          const duration = getElapsedMs(hrStart)
-          pluginTimings.set(plugin.name, duration)
-          await hooks.emit('kubb:plugin:end', {
-            plugin,
-            duration,
-            success: true,
-            config,
-            get files() {
-              return driver.fileManager.files
-            },
-            upsertFile: (...files) => driver.fileManager.upsert(...files),
-          })
-        }
-      }
-    }
-
-    await hooks.emit('kubb:plugins:end', {
-      config,
-      get files() {
-        return driver.fileManager.files
-      },
-      upsertFile: (...files) => driver.fileManager.upsert(...files),
-    })
-
-    await flushPendingFiles()
-
-    const files = driver.fileManager.files
-
-    await hooks.emit('kubb:build:end', {
-      files,
-      config,
-      outputDir: resolve(config.root, config.output.path),
-    })
-
-    return {
-      failedPlugins,
-      files,
-      driver,
-      pluginTimings,
-      storage,
-    }
-  } catch (error) {
-    return {
-      failedPlugins,
-      files: [],
-      driver,
-      pluginTimings,
-      error: error as Error,
-      storage,
-    }
-  }
-}
-
-async function build(setupResult: SetupResult): Promise<BuildOutput> {
-  const { files, driver, failedPlugins, pluginTimings, error, storage } = await safeBuild(setupResult)
-
-  if (error) {
-    throw error
-  }
-
-  if (failedPlugins.size > 0) {
-    const errors = [...failedPlugins].map(({ error }) => error)
-
-    throw new BuildError(`Build Error with ${failedPlugins.size} failed plugins`, { errors })
-  }
-
-  return {
-    failedPlugins,
-    files,
-    driver,
-    pluginTimings,
-    error: undefined,
-    storage,
-  }
 }
 
 /**
@@ -1548,66 +971,141 @@ type CreateKubbOptions = {
 }
 
 /**
- * Creates a Kubb instance bound to a single config entry.
+ * Kubb code-generation instance bound to a single config entry. Resolves the user
+ * config during `setup()` and shares `hooks`, `storage`, `driver`, and `config` across
+ * the `setup → build` lifecycle.
  *
- * Accepts a user-facing config shape and resolves it to a full {@link Config} during
- * `setup()`. The instance then holds shared state (`hooks`, `storage`, `driver`, `config`)
- * across the `setup → build` lifecycle. Attach event listeners to `kubb.hooks` before
- * calling `setup()` or `build()`.
+ * Attach event listeners to `.hooks` before calling `setup()` or `build()`.
  *
  * @example
  * ```ts
  * const kubb = createKubb(userConfig)
- *
- * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
- *   console.log(`${plugin.name} completed in ${duration}ms`)
- * })
- *
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => console.log(plugin.name, duration))
  * const { files, failedPlugins } = await kubb.safeBuild()
  * ```
  */
-export function createKubb(userConfig: UserConfig, options: CreateKubbOptions = {}): Kubb {
-  const hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
-  let setupResult: SetupResult | undefined
+export class Kubb {
+  readonly hooks: AsyncEventEmitter<KubbHooks>
+  readonly #userConfig: UserConfig
+  #config: Config | null = null
+  #driver: KubbDriver | null = null
+  #storage: Storage | null = null
+
+  constructor(userConfig: UserConfig, options: CreateKubbOptions = {}) {
+    this.#userConfig = userConfig
+    this.hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
+  }
 
-  const instance: Kubb = {
-    get hooks() {
-      return hooks
-    },
-    get storage() {
-      if (!setupResult) {
-        throw new Error('[kubb] setup() must be called before accessing storage')
-      }
-      return setupResult.storage
-    },
-    get driver() {
-      if (!setupResult) {
-        throw new Error('[kubb] setup() must be called before accessing driver')
-      }
-      return setupResult.driver
-    },
-    get config() {
-      if (!setupResult) {
-        throw new Error('[kubb] setup() must be called before accessing config')
-      }
-      return setupResult.config
-    },
-    async setup() {
-      setupResult = await setup(userConfig, { hooks })
-    },
-    async build() {
-      if (!setupResult) {
-        await instance.setup()
-      }
-      return build(setupResult!)
-    },
-    async safeBuild() {
-      if (!setupResult) {
-        await instance.setup()
+  get storage(): Storage {
+    if (!this.#storage) throw new Error('[kubb] setup() must be called before accessing storage')
+    return this.#storage
+  }
+
+  get driver(): KubbDriver {
+    if (!this.#driver) throw new Error('[kubb] setup() must be called before accessing driver')
+    return this.#driver
+  }
+
+  get config(): Config {
+    if (!this.#config) throw new Error('[kubb] setup() must be called before accessing config')
+    return this.#config
+  }
+
+  /**
+   * Resolves config and initializes the driver. `build()` calls this automatically.
+   */
+  async setup(): Promise<void> {
+    const config = resolveConfig(this.#userConfig)
+    const driver = new KubbDriver(config, { hooks: this.hooks })
+    const storage = createSourcesView(config.storage)
+
+    await this.hooks.emit('kubb:debug', { date: new Date(), logs: this.#configLogs(config) })
+
+    if (isInputPath(this.#userConfig) && !new URLPath(this.#userConfig.input.path).isURL) {
+      try {
+        await exists(this.#userConfig.input.path)
+        await this.hooks.emit('kubb:debug', { date: new Date(), logs: [`✓ Input file validated: ${this.#userConfig.input.path}`] })
+      } catch (caughtError) {
+        throw new Error(
+          `Cannot read file/URL defined in \`input.path\` or set with \`kubb generate PATH\` in the CLI of your Kubb config ${this.#userConfig.input.path}`,
+          { cause: caughtError as Error },
+        )
       }
-      return safeBuild(setupResult!)
-    },
+    }
+
+    if (config.output.clean) {
+      await this.hooks.emit('kubb:debug', { date: new Date(), logs: ['Cleaning output directories', `  • Output: ${config.output.path}`] })
+      await config.storage.clear(resolve(config.root, config.output.path))
+    }
+
+    await driver.setup()
+
+    this.#config = config
+    this.#driver = driver
+    this.#storage = storage
+  }
+
+  /**
+   * Runs the full pipeline and throws on any plugin error.
+   * Automatically calls `setup()` if needed.
+   */
+  async build(): Promise<BuildOutput> {
+    const out = await this.safeBuild()
+    if (out.error) throw out.error
+    if (out.failedPlugins.size > 0) {
+      const errors = [...out.failedPlugins].map(({ error }) => error)
+      throw new BuildError(`Build Error with ${out.failedPlugins.size} failed plugins`, { errors })
+    }
+    return out
+  }
+
+  /**
+   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing.
+   * Automatically calls `setup()` if needed.
+   */
+  async safeBuild(): Promise<BuildOutput> {
+    if (!this.#driver) await this.setup()
+    using cleanup = this
+    const driver = cleanup.driver
+    const storage = cleanup.storage
+    const { failedPlugins, pluginTimings, error } = await driver.run({ storage })
+    return { failedPlugins, files: driver.fileManager.files, driver, pluginTimings, storage, ...(error ? { error } : {}) }
+  }
+
+  dispose(): void {
+    this.#driver?.dispose()
   }
 
-  return instance
+  [Symbol.dispose](): void {
+    this.dispose()
+  }
+
+  #configLogs(config: Config): Array<string> {
+    const u = this.#userConfig
+    const diag = getDiagnosticInfo()
+    return [
+      'Configuration:',
+      `  • Name: ${u.name || 'unnamed'}`,
+      `  • Root: ${u.root || process.cwd()}`,
+      `  • Output: ${u.output?.path || 'not specified'}`,
+      `  • Plugins: ${u.plugins?.length || 0}`,
+      'Output Settings:',
+      `  • Storage: ${config.storage.name}`,
+      `  • Formatter: ${u.output?.format || 'none'}`,
+      `  • Linter: ${u.output?.lint || 'none'}`,
+      `Running adapter: ${config.adapter?.name || 'none'}`,
+      'Environment:',
+      Object.entries(diag)
+        .map(([key, value]) => `  • ${key}: ${value}`)
+        .join('\n'),
+    ]
+  }
+}
+
+/**
+ * Factory for {@link Kubb}. Equivalent to `new Kubb(userConfig, options)` and kept
+ * as the canonical public entry point.
+ */
+export function createKubb(userConfig: UserConfig, options: CreateKubbOptions = {}): Kubb {
+  return new Kubb(userConfig, options)
 }