@kubb/core 5.0.0-beta.36 → 5.0.0-beta.37

package/src/KubbDriver.ts

@@ -1,8 +1,10 @@
 import { resolve } from 'node:path'
-import { arrayToAsyncIterable, type AsyncEventEmitter, forBatches, formatMs, getElapsedMs, isPromise, memoize, URLPath } from '@internals/utils'
-import { collectUsedSchemaNames, createFile, createStreamInput, transform } from '@kubb/ast'
+import { arrayToAsyncIterable, type AsyncEventEmitter, forBatches, getElapsedMs, isPromise, memoize, URLPath } from '@internals/utils'
+import { collectUsedSchemaNames, createFile, createStreamInput } from '@kubb/ast'
 import type { FileNode, InputMeta, InputNode, InputStreamNode, OperationNode, SchemaNode } from '@kubb/ast'
-import { DEFAULT_STUDIO_URL, SCHEMA_PARALLEL, STREAM_FLUSH_EVERY } from './constants.ts'
+import { DEFAULT_STUDIO_URL, diagnosticCode, OPERATION_FILTER_TYPES, SCHEMA_PARALLEL } from './constants.ts'
+import { type Diagnostic, DiagnosticError, Diagnostics, type ProblemDiagnostic } from './diagnostics.ts'
+import type { RendererFactory } from './createRenderer.ts'
 import type { Storage } from './createStorage.ts'
 import type { Generator } from './defineGenerator.ts'
 import type { Parser } from './defineParser.ts'
@@ -12,7 +14,8 @@ import { defineResolver } from './defineResolver.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
 import { FileManager } from './FileManager.ts'
 import { FileProcessor } from './FileProcessor.ts'
-import type { Renderer, RendererFactory } from './createRenderer.ts'
+import { type HookListener, HookRegistry } from './HookRegistry.ts'
+import { Transform } from './Transform.ts'
 
 import type {
   Adapter,
@@ -36,8 +39,6 @@ function enforceOrder(enforce: 'pre' | 'post' | undefined): number {
   return enforce === 'pre' ? -1 : enforce === 'post' ? 1 : 0
 }
 
-const OPERATION_FILTER_TYPES = new Set(['tag', 'operationId', 'path', 'method', 'contentType'])
-
 export class KubbDriver {
   readonly config: Config
   readonly options: Options
@@ -57,7 +58,7 @@ export class KubbDriver {
 
   /**
    * The streaming `InputStreamNode` produced by the adapter.
-   * Always set after adapter setup — parse-only adapters are wrapped automatically.
+   * Always set after adapter setup, parse-only adapters are wrapped automatically.
    */
   inputNode: InputStreamNode | null = null
   adapter: Adapter | null = null
@@ -65,7 +66,7 @@ export class KubbDriver {
    * Studio session state, kept together so `dispose()` can reset it atomically.
    *
    * - `source` holds the raw adapter source so `adapter.parse()` can be called lazily.
-   *   Intentionally outlives the build; cleared by `dispose()`.
+   *   Intentionally outlives the build, cleared by `dispose()`.
    * - `isOpen` prevents opening the studio more than once per build.
    * - `inputNode` caches the parse promise so `adapter.parse()` is called at most once
    *   per studio session, even when `openInStudio()` is called multiple times.
@@ -76,21 +77,12 @@ export class KubbDriver {
     inputNode: null,
   }
 
-  // Register middleware hooks after all plugin hooks are registered.
-  // Because AsyncEventEmitter calls listeners in registration order,
-  // middleware hooks for any event fire after all plugin hooks for that event.
-  // Handlers are tracked so they can be removed after each build (disposeMiddleware),
-  // preventing accumulation when multiple configs share the same hooks instance.
-  #middlewareListeners: Array<[keyof KubbHooks & string, (...args: Array<never>) => void | Promise<void>]> = []
-
   /**
    * Central file store for all generated files.
    * Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
-   * add files; this property gives direct read/write access when needed.
+   * add files. This property gives direct read/write access when needed.
    */
   readonly fileManager = new FileManager()
-  readonly #fileProcessor = new FileProcessor()
-
   readonly plugins = new Map<string, NormalizedPlugin>()
 
   /**
@@ -100,12 +92,25 @@ export class KubbDriver {
   readonly #eventGeneratorPlugins = new Set<string>()
   readonly #resolvers = new Map<string, Resolver>()
   readonly #defaultResolvers = new Map<string, Resolver>()
-  readonly #hookListeners = new Map<keyof KubbHooks, Set<(...args: Array<never>) => void | Promise<void>>>()
+
+  /**
+   * Tracks every listener the driver added (plugin, middleware, generator) so `dispose()` can
+   * remove them in one pass. Middleware registers after plugins, so it fires last via `Set`
+   * insertion order. External `hooks.on(...)` listeners are not tracked.
+   */
+  readonly #registry: HookRegistry<KubbHooks>
+
+  /**
+   * Transform registry. Plugins populate it during `kubb:plugin:setup` via `setTransformer`,
+   * and `#runGenerators` reads it once per `(plugin, node)` pair through `applyTo`.
+   */
+  readonly #transforms = new Transform()
 
   constructor(config: Config, options: Options) {
     this.config = config
     this.options = options
     this.adapter = config.adapter ?? null
+    this.#registry = new HookRegistry({ emitter: options.hooks })
   }
 
   async setup() {
@@ -135,7 +140,7 @@ export class KubbDriver {
       }
     }
     if (this.config.adapter) {
-      await this.#registerAdapter(this.config.adapter)
+      this.#studio.source = inputToAdapterSource(this.config)
     }
   }
 
@@ -163,32 +168,25 @@ export class KubbDriver {
     return normalized
   }
 
-  async #registerAdapter(adapter: Adapter) {
-    const source = inputToAdapterSource(this.config)
-    this.#studio.source = source
+  /**
+   * Parses the adapter source into `this.inputNode`. Idempotent, so repeated calls from
+   * `run` or the studio path do not re-parse. Adapters with `stream()` are used directly.
+   * Adapters with only `parse()` are wrapped via `createStreamInput` so the dispatch loop
+   * stays stream-only.
+   */
+  async #parseInput(): Promise<void> {
+    if (this.inputNode || !this.adapter || !this.#studio.source) return
+
+    const adapter = this.adapter
+    const source = this.#studio.source
 
     if (adapter.stream) {
       this.inputNode = await adapter.stream(source)
-
-      await this.hooks.emit('kubb:debug', {
-        date: new Date(),
-        logs: [`✓ Adapter '${adapter.name}' producing input stream`],
-      })
-    } else {
-      // Adapter does not implement stream() — eagerly parse and wrap in a
-      // reusable AsyncIterable so the rest of the pipeline stays stream-only.
-      const inputNode = await adapter.parse(source)
-      this.inputNode = createStreamInput(arrayToAsyncIterable(inputNode.schemas), arrayToAsyncIterable(inputNode.operations), inputNode.meta)
-
-      await this.hooks.emit('kubb:debug', {
-        date: new Date(),
-        logs: [
-          `✓ Adapter '${adapter.name}' resolved InputNode (wrapped as stream)`,
-          `  • Schemas: ${inputNode.schemas.length}`,
-          `  • Operations: ${inputNode.operations.length}`,
-        ],
-      })
+      return
     }
+
+    const parsed = await adapter.parse(source)
+    this.inputNode = createStreamInput(arrayToAsyncIterable(parsed.schemas), arrayToAsyncIterable(parsed.operations), parsed.meta)
   }
 
   #registerMiddleware<K extends keyof KubbHooks & string>(event: K, middlewareHooks: Middleware['hooks']) {
@@ -198,22 +196,16 @@ export class KubbDriver {
       return
     }
 
-    this.hooks.on(event, handler)
-    this.#middlewareListeners.push([event, handler as (...args: Array<never>) => void | Promise<void>])
+    this.#registry.register({ event, handler, source: 'middleware' })
   }
 
   /**
    * Registers a hook-style plugin's lifecycle handlers on the shared `AsyncEventEmitter`.
    *
-   * For `kubb:plugin:setup`, the registered listener wraps the globally emitted context with a
-   * plugin-specific one so that `addGenerator`, `setResolver`, `setTransformer`, and
-   * `setRenderer` all target the correct `normalizedPlugin` entry in the plugins map.
-   *
-   * All other hooks are iterated and registered directly as pass-through listeners.
-   * Any event key present in the global `KubbHooks` interface can be subscribed to.
-   *
-   * External tooling can subscribe to any of these events via `hooks.on(...)` to observe
-   * the plugin lifecycle without modifying plugin behavior.
+   * The `kubb:plugin:setup` listener wraps the global context in a plugin-specific one so
+   * `addGenerator`, `setResolver`, and `setTransformer` target the right `normalizedPlugin`.
+   * Every other `KubbHooks` event registers as a pass-through listener that external tooling
+   * can observe via `hooks.on(...)`.
    *
    * @internal
    */
@@ -237,10 +229,7 @@ export class KubbDriver {
             this.setPluginResolver(plugin.name, resolver)
           },
           setTransformer: (visitor) => {
-            plugin.transformer = visitor
-          },
-          setRenderer: (renderer) => {
-            plugin.renderer = renderer
+            this.#transforms.register(plugin.name, visitor)
           },
           setOptions: (opts) => {
             plugin.options = { ...plugin.options, ...opts }
@@ -252,16 +241,20 @@ export class KubbDriver {
         return hooks['kubb:plugin:setup']!(pluginCtx)
       }
 
-      this.hooks.on('kubb:plugin:setup', setupHandler)
-      this.#trackHookListener('kubb:plugin:setup', setupHandler as (...args: Array<never>) => void | Promise<void>)
+      this.#registry.register({ event: 'kubb:plugin:setup', handler: setupHandler, source: 'plugin' })
     }
 
     // All other hooks are registered as direct pass-through listeners on the shared emitter.
-    for (const [event, handler] of Object.entries(hooks) as Array<[keyof KubbHooks, ((...args: Array<never>) => void | Promise<void>) | undefined]>) {
-      if (event === 'kubb:plugin:setup' || !handler) continue
-
-      this.hooks.on(event, handler as never)
-      this.#trackHookListener(event, handler as (...args: Array<never>) => void | Promise<void>)
+    for (const event of Object.keys(hooks) as Array<keyof KubbHooks & string>) {
+      if (event === 'kubb:plugin:setup') continue
+      const handler = hooks[event]
+      if (!handler) continue
+
+      this.#registry.register({
+        event,
+        handler: handler as HookListener<KubbHooks[typeof event], unknown>,
+        source: 'plugin',
+      })
     }
   }
 
@@ -280,7 +273,6 @@ export class KubbDriver {
       addGenerator: noop,
       setResolver: noop,
       setTransformer: noop,
-      setRenderer: noop,
       setOptions: noop,
       injectFile: noop,
       updateConfig: noop,
@@ -295,49 +287,42 @@ export class KubbDriver {
    * respectively. Each listener is scoped to the owning plugin via a `ctx.plugin.name` check
    * so that generators from different plugins do not cross-fire.
    *
-   * The renderer resolution chain is: `generator.renderer → plugin.renderer → config.renderer`.
-   * Set `generator.renderer = null` to explicitly opt out of rendering even when the plugin
-   * declares a renderer.
+   * The renderer comes from `generator.renderer`. Set `generator.renderer = null` (or leave it
+   * unset) to opt out of rendering.
    *
    * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
    */
-  registerGenerator(pluginName: string, gen: Generator): void {
-    const resolveRenderer = () => {
-      const plugin = this.plugins.get(pluginName)
-      return gen.renderer === null ? undefined : (gen.renderer ?? plugin?.renderer ?? this.config.renderer)
-    }
-
-    if (gen.schema) {
+  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 gen.schema!(node, ctx)
-        await applyHookResult({ result, driver: this, rendererFactory: resolveRenderer() })
+        const result = await generator.schema!(node, ctx)
+
+        await this.dispatch({ result, renderer: generator.renderer })
       }
 
-      this.hooks.on('kubb:generate:schema', schemaHandler)
-      this.#trackHookListener('kubb:generate:schema', schemaHandler as (...args: Array<never>) => void | Promise<void>)
+      this.#registry.register({ event: 'kubb:generate:schema', handler: schemaHandler, source: 'driver' })
     }
 
-    if (gen.operation) {
+    if (generator.operation) {
       const operationHandler = async (node: OperationNode, ctx: GeneratorContext) => {
         if (ctx.plugin.name !== pluginName) return
-        const result = await gen.operation!(node, ctx)
-        await applyHookResult({ result, driver: this, rendererFactory: resolveRenderer() })
+
+        const result = await generator.operation!(node, ctx)
+        await this.dispatch({ result, renderer: generator.renderer })
       }
 
-      this.hooks.on('kubb:generate:operation', operationHandler)
-      this.#trackHookListener('kubb:generate:operation', operationHandler as (...args: Array<never>) => void | Promise<void>)
+      this.#registry.register({ event: 'kubb:generate:operation', handler: operationHandler, source: 'driver' })
     }
 
-    if (gen.operations) {
+    if (generator.operations) {
       const operationsHandler = async (nodes: Array<OperationNode>, ctx: GeneratorContext) => {
         if (ctx.plugin.name !== pluginName) return
-        const result = await gen.operations!(nodes, ctx)
-        await applyHookResult({ result, driver: this, rendererFactory: resolveRenderer() })
+        const result = await generator.operations!(nodes, ctx)
+        await this.dispatch({ result, renderer: generator.renderer })
       }
 
-      this.hooks.on('kubb:generate:operations', operationsHandler)
-      this.#trackHookListener('kubb:generate:operations', operationsHandler as (...args: Array<never>) => void | Promise<void>)
+      this.#registry.register({ event: 'kubb:generate:operations', handler: operationsHandler, source: 'driver' })
     }
 
     this.#eventGeneratorPlugins.add(pluginName)
@@ -355,19 +340,14 @@ export class KubbDriver {
   }
 
   /**
-   * Runs the full plugin pipeline. Returns timings/failures collected so far even
-   * when an outer hook throws — the orchestrator preserves partial state by capturing
-   * the error into `error` instead of propagating.
+   * Runs the full plugin pipeline. Returns the diagnostics collected so far even
+   * when an outer hook throws, since the orchestrator preserves partial state by capturing
+   * the failure as a {@link Diagnostic} instead of propagating. Each plugin also
+   * contributes a `timing` diagnostic for the run summary.
    */
-  async run({ storage }: { storage: Storage }): Promise<{
-    failedPlugins: Set<{ plugin: Plugin; error: Error }>
-    pluginTimings: Map<string, number>
-    error?: Error
-  }> {
-    const hooks = this.hooks
-    const config = this.config
-    const failedPlugins = new Set<{ plugin: Plugin; error: Error }>()
-    const pluginTimings = new Map<string, number>()
+  async run({ storage }: { storage: Storage }): Promise<{ diagnostics: Array<Diagnostic> }> {
+    const { hooks, config } = this
+    const diagnostics: Array<Diagnostic> = []
     const parsersMap = new Map<FileNode['extname'], Parser>()
 
     for (const parser of config.parsers) {
@@ -376,116 +356,111 @@ export class KubbDriver {
       }
     }
 
-    const pendingFiles = new Map<string, FileNode>()
-    this.fileManager.setOnUpsert((file) => {
-      pendingFiles.set(file.path, file)
+    const processor = new FileProcessor({ parsers: parsersMap, storage, extension: config.output.extension })
+    // Bridge processor lifecycle to the user-facing kubb hooks so existing listeners on
+    // kubb:files:processing:* keep firing.
+    processor.hooks.on('start', async (files) => {
+      await hooks.emit('kubb:files:processing:start', { files })
     })
+    const updateBuffer: Array<{ file: FileNode; source?: string; processed: number; total: number; percentage: number }> = []
+    processor.hooks.on('update', (item) => {
+      updateBuffer.push(item)
+    })
+    processor.hooks.on('end', async (files) => {
+      await hooks.emit('kubb:files:processing:update', {
+        files: updateBuffer.map((item) => ({ ...item, config })),
+      })
+      updateBuffer.length = 0
+      await hooks.emit('kubb:files:processing:end', { files })
+    })
+    const onFileUpsert = (file: FileNode): void => {
+      processor.enqueue(file)
+    }
+    this.fileManager.hooks.on('upsert', onFileUpsert)
 
-    try {
-      const flushPending = async (): Promise<void> => {
-        if (pendingFiles.size === 0) return
-        const files = [...pendingFiles.values()]
-        pendingFiles.clear()
-
-        await hooks.emit('kubb:debug', { date: new Date(), logs: [`Writing ${files.length} files...`] })
-        await hooks.emit('kubb:files:processing:start', { files })
-
-        const items = [...this.#fileProcessor.stream(files, { parsers: parsersMap, extension: config.output.extension })]
-
-        await hooks.emit('kubb:files:processing:update', {
-          files: items.map(({ file, source, processed, total, percentage }) => ({ file, source, processed, total, percentage, config })),
-        })
-
-        const queue: Array<Promise<void>> = []
-        for (const { file, source } of items) {
-          if (source) {
-            queue.push(storage.setItem(file.path, source))
-            if (queue.length >= STREAM_FLUSH_EVERY) await Promise.all(queue.splice(0))
+    // Make `diagnostics` the active sink so deep code (adapter parse, lazily consumed
+    // streams, generators) can report into this run via `Diagnostics.report`.
+    return Diagnostics.scope(
+      (diagnostic) => diagnostics.push(diagnostic),
+      async () => {
+        try {
+          // Parse the adapter source into the streaming `InputNode`.
+          await this.#parseInput()
+          // Emit `kubb:plugin:setup` so plugins can register transformers via `setTransformer`.
+          // Each call writes into `this.#transforms`, which `#runGenerators` later reads through
+          // `transforms.applyTo`.
+          await this.emitSetupHooks()
+
+          if (this.adapter && this.inputNode) {
+            await hooks.emit(
+              'kubb:build:start',
+              Object.assign({ config, adapter: this.adapter, meta: this.inputNode.meta, getPlugin: this.getPlugin.bind(this) }, this.#filesPayload()),
+            )
           }
-        }
-        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`] })
-      }
+          const generatorPlugins: Array<{ plugin: NormalizedPlugin; context: Omit<GeneratorContext, 'options'>; hrStart: ReturnType<typeof process.hrtime> }> =
+            []
 
-      await this.emitSetupHooks()
+          for (const plugin of this.plugins.values()) {
+            const context = this.getContext(plugin)
+            const hrStart = process.hrtime()
 
-      if (this.adapter && this.inputNode) {
-        await hooks.emit(
-          'kubb:build:start',
-          Object.assign({ config, adapter: this.adapter, meta: this.inputNode.meta, getPlugin: this.getPlugin.bind(this) }, this.#filesPayload()),
-        )
-      }
+            try {
+              await hooks.emit('kubb:plugin:start', { plugin })
+            } catch (caughtError) {
+              const error = caughtError as Error
+              const duration = getElapsedMs(hrStart)
 
-      const generatorPlugins: Array<{ plugin: NormalizedPlugin; context: Omit<GeneratorContext, 'options'>; hrStart: ReturnType<typeof process.hrtime> }> = []
+              await this.#emitPluginEnd({ plugin, duration, success: false, error })
 
-      for (const plugin of this.plugins.values()) {
-        const context = this.getContext(plugin)
-        const hrStart = process.hrtime()
+              diagnostics.push({ ...Diagnostics.from(error), plugin: plugin.name }, Diagnostics.performance({ plugin: plugin.name, duration }))
 
-        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 this.#emitPluginEnd({ plugin, duration, success: false, error })
-          failedPlugins.add({ plugin, error })
-          continue
-        }
+              continue
+            }
 
-        if (plugin.generators?.length || this.hasEventGenerators(plugin.name)) {
-          generatorPlugins.push({ plugin, context, hrStart })
-          continue
-        }
+            if (this.hasEventGenerators(plugin.name)) {
+              generatorPlugins.push({ plugin, context, hrStart })
 
-        const duration = getElapsedMs(hrStart)
-        pluginTimings.set(plugin.name, duration)
-        await this.#emitPluginEnd({ plugin, duration, success: true })
-        await hooks.emit('kubb:debug', { date: new Date(), logs: [`✓ Plugin started successfully (${formatMs(duration)})`] })
-      }
+              continue
+            }
 
-      if (generatorPlugins.length > 0) {
-        if (this.inputNode) {
-          const { timings, failed } = await this.#runGenerators(generatorPlugins, flushPending)
-          // Drain any files written after the last batch's flush.
-          await flushPending()
-          for (const [name, duration] of timings) pluginTimings.set(name, duration)
-          for (const entry of failed) failedPlugins.add(entry)
-        } else {
-          // No adapter input: generator-plugins have nothing to dispatch, but still
-          // need their `kubb:plugin:end` so middleware (e.g. barrel) completes.
-          for (const { plugin, hrStart } of generatorPlugins) {
             const duration = getElapsedMs(hrStart)
-            pluginTimings.set(plugin.name, duration)
+            diagnostics.push(Diagnostics.performance({ plugin: plugin.name, duration }))
+
             await this.#emitPluginEnd({ plugin, duration, success: true })
           }
-        }
-      }
 
-      await hooks.emit('kubb:plugins:end', Object.assign({ config }, this.#filesPayload()))
+          // 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.
+          diagnostics.push(...(await this.#runGenerators(generatorPlugins, () => processor.flush())))
+          // Wait for the last in-flight batch and write anything still pending.
+          await processor.drain()
 
-      await flushPending()
+          await hooks.emit('kubb:plugins:end', Object.assign({ config }, this.#filesPayload()))
 
-      const files = this.fileManager.files
+          // Plugins-end listeners (barrel middleware etc.) may have queued more files.
+          await processor.drain()
 
-      await hooks.emit('kubb:build:end', { files, config, outputDir: resolve(config.root, config.output.path) })
+          await hooks.emit('kubb:build:end', { files: this.fileManager.files, config, outputDir: resolve(config.root, config.output.path) })
 
-      return { failedPlugins, pluginTimings }
-    } catch (caughtError) {
-      return { failedPlugins, pluginTimings, error: caughtError as Error }
-    } finally {
-      this.fileManager.setOnUpsert(null)
-    }
+          return { diagnostics: Diagnostics.dedupe(diagnostics) }
+        } catch (caughtError) {
+          diagnostics.push(Diagnostics.from(caughtError))
+          return { diagnostics: Diagnostics.dedupe(diagnostics) }
+        } finally {
+          this.fileManager.hooks.off('upsert', onFileUpsert)
+        }
+      },
+    )
   }
 
   // Returns a fresh object with a lazy `files` getter and a bound `upsertFile`.
-  // Caller must use `Object.assign(extra, this.#filesPayload())`, not object spread —
-  // spread would eagerly invoke the getter and freeze a stale snapshot into the payload.
+  // Caller must use `Object.assign(extra, this.#filesPayload())`, not object spread.
+  // Spread would eagerly invoke the getter and freeze a stale snapshot into the payload.
   #filesPayload(): { readonly files: Array<FileNode>; upsertFile: (...files: Array<FileNode>) => Array<FileNode> } {
     const driver = this
+
     return {
       get files() {
         return driver.fileManager.files
@@ -501,12 +476,37 @@ export class KubbDriver {
     )
   }
 
+  /**
+   * Streams schemas and operations through every plugin's generators. Each node is run
+   * through the plugin's transformer (from `this.#transforms`) before the generator sees it,
+   * so plugins stay isolated and the hot path stays per-node. Schemas run before operations
+   * because the two passes share `flushPending` and the FileProcessor's event emitter.
+   * A failing plugin contributes an error diagnostic so the rest of the build continues.
+   * Every plugin also contributes a `timing` diagnostic.
+   *
+   * When `entries` is empty or `this.inputNode` is `null`, every entry still gets a
+   * `kubb:plugin:end` so middleware listeners (the barrel writer and friends) complete.
+   */
   async #runGenerators(
     entries: Array<{ plugin: NormalizedPlugin; context: Omit<GeneratorContext, 'options'>; hrStart: ReturnType<typeof process.hrtime> }>,
     flushPending: () => Promise<void>,
-  ): Promise<{ timings: Map<string, number>; failed: Set<{ plugin: Plugin; error: Error }> }> {
-    const timings = new Map<string, number>()
-    const failed = new Set<{ plugin: Plugin; error: Error }>()
+  ): Promise<Array<Diagnostic>> {
+    const diagnostics: Array<Diagnostic> = []
+
+    if (entries.length === 0) return diagnostics
+
+    if (!this.inputNode) {
+      for (const { plugin, hrStart } of entries) {
+        const duration = getElapsedMs(hrStart)
+        diagnostics.push(Diagnostics.performance({ plugin: plugin.name, duration }))
+        await this.#emitPluginEnd({ plugin, duration, success: true })
+      }
+      return diagnostics
+    }
+
+    const transforms = this.#transforms
+    const { schemas, operations } = this.inputNode
+
     type PluginState = {
       plugin: NormalizedPlugin
       generatorContext: Omit<GeneratorContext, 'options'>
@@ -518,8 +518,6 @@ export class KubbDriver {
       allowedSchemaNames: Set<string> | null
     }
 
-    const driver = this
-    const { schemas, operations } = this.inputNode!
     const states: Array<PluginState> = entries.map(({ plugin, context, hrStart }) => {
       const { exclude, include, override } = plugin.options
       const hasExclude = Array.isArray(exclude) && exclude.length > 0
@@ -541,9 +539,9 @@ export class KubbDriver {
     const emitsOperationHook = this.hooks.listenerCount('kubb:generate:operation') > 0
 
     // Pre-scan: plugins with operation-based includes (but no schemaName include) need
-    // the reachable schema set. This requires the full schema graph in memory at once —
-    // transitive reachability can't be derived from a single node. `allSchemas` is
-    // released as soon as the pre-scan returns; the main passes get fresh iterators.
+    // the reachable schema set. This requires the full schema graph in memory at once,
+    // since transitive reachability can't be derived from a single node. `allSchemas` is
+    // released as soon as the pre-scan returns, so the main passes get fresh iterators.
     const pruningStates = states.filter(({ plugin }) => {
       const { include } = plugin.options
       return (include?.some(({ type }) => OPERATION_FILTER_TYPES.has(type)) ?? false) && !(include?.some(({ type }) => type === 'schemaName') ?? false)
@@ -553,7 +551,7 @@ export class KubbDriver {
       const allSchemas: Array<SchemaNode> = []
       for await (const schema of schemas) allSchemas.push(schema)
 
-      const includedOpsByState = new Map<PluginState, Array<OperationNode>>(pruningStates.map((s) => [s, []]))
+      const includedOpsByState = new Map<PluginState, Array<OperationNode>>(pruningStates.map((state) => [state, []]))
       for await (const operation of operations) {
         for (const state of pruningStates) {
           const { exclude, include, override } = state.plugin.options
@@ -568,12 +566,27 @@ export class KubbDriver {
       }
     }
 
-    const resolveRendererFor = (gen: Generator, state: PluginState): RendererFactory | undefined =>
-      gen.renderer === null ? undefined : (gen.renderer ?? state.plugin.renderer ?? state.generatorContext.config.renderer)
+    // Apply the plugin's transformer, then resolve options (skipping the resolver when
+    // optionsAreStatic). Returns null when include/exclude/override rules out the node.
+    // The per-node dispatch and the collected-operations tail both go through this so
+    // they agree on what a plugin sees.
+    const resolveForPlugin = <TNode extends SchemaNode | OperationNode>(
+      state: PluginState,
+      node: TNode,
+    ): { transformedNode: TNode; options: NormalizedPlugin['options'] } | null => {
+      const { plugin, generatorContext } = state
+      const transformedNode = transforms.applyTo(plugin.name, node)
+      if (state.optionsAreStatic) return { transformedNode, options: plugin.options }
+
+      const { exclude, include, override } = plugin.options
+      const options = generatorContext.resolver.resolveOptions(transformedNode, { options: plugin.options, exclude, include, override })
+      if (options === null) return null
+      return { transformedNode, options }
+    }
 
-    // Schema and operation passes share this body. They differ only in which
-    // generator method runs, which hook is emitted, and the schema-only
-    // `allowedSchemaNames` prune (operations don't carry that constraint).
+    // Schema and operation passes share this body. They differ only in which generator
+    // method runs, which hook is emitted, and the schema-only `allowedSchemaNames` prune
+    // (operations don't carry that constraint).
     const dispatchNode = async <TNode extends SchemaNode | OperationNode>(
       state: PluginState,
       node: TNode,
@@ -585,9 +598,10 @@ export class KubbDriver {
     ): Promise<void> => {
       if (state.failed) return
       try {
-        const { plugin, generatorContext, generators } = state
-        const transformedNode: TNode = plugin.transformer ? (transform(node, plugin.transformer) as TNode) : node
+        const resolved = resolveForPlugin(state, node)
+        if (!resolved) return
 
+        const { transformedNode, options } = resolved
         if (
           dispatch.checkAllowedNames &&
           state.allowedSchemaNames !== null &&
@@ -598,19 +612,13 @@ export class KubbDriver {
           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) {
-          const generate = gen[dispatch.method] as ((node: TNode, ctx: GeneratorContext) => unknown) | undefined
-          if (!generate) continue
-          const raw = generate(transformedNode, ctx)
+        const ctx = { ...state.generatorContext, options }
+        for (const gen of state.generators) {
+          const run = gen[dispatch.method] as ((node: TNode, ctx: GeneratorContext) => unknown) | undefined
+          if (!run) continue
+          const raw = run(transformedNode, ctx)
           const result = isPromise(raw) ? await raw : raw
-          const applied = applyHookResult({ result, driver, rendererFactory: resolveRendererFor(gen, state) })
+          const applied = this.dispatch({ result, renderer: gen.renderer })
           if (isPromise(applied)) await applied
         }
         if (dispatch.emit) await dispatch.emit(transformedNode, ctx)
@@ -631,16 +639,16 @@ export class KubbDriver {
       emit: emitsOperationHook ? (node: OperationNode, ctx: GeneratorContext) => this.hooks.emit('kubb:generate:operation', node, ctx) : null,
     } as const
 
-    // Skip building the aggregated operations array when nothing consumes it.
-    // Saves an N-sized allocation that lives until the build ends, on the common
-    // path where plugins only define per-node `gen.operation`.
-    const needsCollectedOperations = this.hooks.listenerCount('kubb:generate:operations') > 0 || states.some((s) => s.generators.some((g) => !!g.operations))
+    // Skip building the aggregated operations array when nothing consumes it. Saves an
+    // N-sized allocation on the common path where plugins only define per-node `gen.operation`.
+    const needsCollectedOperations =
+      this.hooks.listenerCount('kubb:generate:operations') > 0 || states.some((state) => state.generators.some((gen) => !!gen.operations))
     const collectedOperations: Array<OperationNode> | undefined = needsCollectedOperations ? [] : undefined
 
     // Run schemas before operations: the two passes share `flushPending` and the
     // FileProcessor's event emitter, so running them concurrently would interleave
     // `kubb:files:processing:start|end` events and race on the shared dirty list.
-    await forBatches(schemas, (nodes) => Promise.all(nodes.flatMap((n) => states.map((state) => dispatchNode(state, n, schemaDispatch)))), {
+    await forBatches(schemas, (nodes) => Promise.all(nodes.flatMap((node) => states.map((state) => dispatchNode(state, node, schemaDispatch)))), {
       concurrency: SCHEMA_PARALLEL,
       flush: flushPending,
     })
@@ -649,7 +657,7 @@ export class KubbDriver {
       operations,
       (nodes) => {
         if (needsCollectedOperations) collectedOperations?.push(...nodes)
-        return Promise.all(nodes.flatMap((n) => states.map((state) => dispatchNode(state, n, operationDispatch))))
+        return Promise.all(nodes.flatMap((node) => states.map((state) => dispatchNode(state, node, operationDispatch))))
       },
       { concurrency: SCHEMA_PARALLEL, flush: flushPending },
     )
@@ -659,23 +667,18 @@ export class KubbDriver {
         try {
           const { plugin, generatorContext, generators } = state
           const ctx = { ...generatorContext, options: plugin.options }
-          // Filter to operations this plugin would have dispatched to gen.operation():
-          // excludes/includes/overrides that resolve to null in dispatchOperation must also
-          // be hidden from the batched gen.operations() hook, otherwise grouped/barrel
-          // generators emit references to operation files that the per-op hook intentionally skipped.
+          // Match what the per-node dispatch passes to gen.operation(): the transformed node,
+          // already filtered by excludes/includes/overrides.
           const ops = collectedOperations ?? []
-          const pluginOperations = state.optionsAreStatic
-            ? ops
-            : ops.filter((node) => {
-                const transformed = plugin.transformer ? transform(node, plugin.transformer) : node
-                const { exclude, include, override } = plugin.options
-
-                return generatorContext.resolver.resolveOptions(transformed, { options: plugin.options, exclude, include, override }) !== null
-              })
+          const pluginOperations = ops.reduce<Array<OperationNode>>((acc, node) => {
+            const resolved = resolveForPlugin(state, node)
+            if (resolved) acc.push(resolved.transformedNode)
+            return acc
+          }, [])
           for (const gen of generators) {
             if (!gen.operations) continue
             const result = await gen.operations(pluginOperations, ctx)
-            await applyHookResult({ result, driver, rendererFactory: resolveRendererFor(gen, state) })
+            await this.dispatch({ result, renderer: gen.renderer })
           }
           await this.hooks.emit('kubb:generate:operations', pluginOperations, ctx)
         } catch (caughtError) {
@@ -685,36 +688,70 @@ export class KubbDriver {
       }
 
       const duration = getElapsedMs(state.hrStart)
-      timings.set(state.plugin.name, duration)
       await this.#emitPluginEnd({ plugin: state.plugin, duration, success: !state.failed, error: state.failed && state.error ? state.error : undefined })
 
-      if (state.failed && state.error) failed.add({ plugin: state.plugin, error: state.error })
-
-      await this.hooks.emit('kubb:debug', {
-        date: new Date(),
-        logs: [state.failed ? '✗ Plugin start failed' : `✓ Plugin started successfully (${formatMs(duration)})`],
-      })
+      if (state.failed && state.error) {
+        diagnostics.push({ ...Diagnostics.from(state.error), plugin: state.plugin.name })
+      }
+      diagnostics.push(Diagnostics.performance({ plugin: state.plugin.name, duration }))
     }
 
-    return { timings, failed }
+    return diagnostics
   }
 
   /**
-   * Unregisters all plugin lifecycle listeners from the shared event emitter.
-   * Called at the end of a build to prevent listener leaks across repeated builds.
+   * Stores whatever a generator method or `kubb:generate:*` hook returned.
    *
-   * @internal
+   * - An `Array<FileNode>` goes straight into `fileManager` via `upsert`.
+   * - A renderer element runs through `renderer` (the renderer factory, e.g. JSX) and the
+   *   produced files go to `fileManager.upsert`.
+   * - A falsy result is treated as a no-op. The generator wrote files itself via
+   *   `ctx.upsertFile`.
+   *
+   * Pass `renderer` when the result may be a renderer element. Generators that only return
+   * `Array<FileNode>` do not need one.
    */
-  dispose(): void {
-    for (const [event, handlers] of this.#hookListeners) {
-      for (const handler of handlers) {
-        this.hooks.off(event, handler as never)
+  async dispatch<TElement = unknown>({
+    result,
+    renderer,
+  }: {
+    result: TElement | Array<FileNode> | undefined | null
+    renderer?: RendererFactory<TElement> | null
+  }): Promise<void> {
+    if (!result) return
+
+    if (Array.isArray(result)) {
+      this.fileManager.upsert(...(result as Array<FileNode>))
+      return
+    }
+
+    if (!renderer) {
+      return
+    }
+
+    using instance = renderer()
+    if (instance.stream) {
+      for (const file of instance.stream(result)) {
+        this.fileManager.upsert(file)
       }
+      return
     }
 
-    this.#hookListeners.clear()
+    await instance.render(result)
+    this.fileManager.upsert(...instance.files)
+  }
+
+  /**
+   * Removes every listener the driver added. Listeners attached directly to `hooks` from outside
+   * the driver survive. Called at the end of a build to prevent leaks across repeated builds.
+   *
+   * @internal
+   */
+  dispose(): void {
+    this.#registry.dispose()
     this.#eventGeneratorPlugins.clear()
-    // Release resolver closures — the driver is rebuilt for each build() call
+    this.#transforms.dispose()
+    // Release resolver closures. The driver is rebuilt for each build() call
     // so there is no value in retaining these maps after disposal.
     this.#resolvers.clear()
     this.#defaultResolvers.clear()
@@ -722,28 +759,14 @@ export class KubbDriver {
     // memory is reclaimed between builds. The returned `BuildOutput.files`
     // array still references any FileNodes the caller needs to inspect.
     this.fileManager.dispose()
-    this.#fileProcessor.dispose()
     this.inputNode = null
     this.#studio = { source: null, isOpen: false, inputNode: null }
-
-    for (const [event, handler] of this.#middlewareListeners) {
-      this.hooks.off(event, handler as never)
-    }
   }
 
   [Symbol.dispose](): void {
     this.dispose()
   }
 
-  #trackHookListener(event: keyof KubbHooks, handler: (...args: Array<never>) => void | Promise<void>): void {
-    let handlers = this.#hookListeners.get(event)
-    if (!handlers) {
-      handlers = new Set()
-      this.#hookListeners.set(event, handlers)
-    }
-    handlers.add(handler)
-  }
-
   #getDefaultResolver = memoize(
     this.#defaultResolvers,
     (pluginName: string): Resolver => defineResolver<PluginFactoryOptions>(() => ({ name: 'default', pluginName })),
@@ -779,6 +802,19 @@ export class KubbDriver {
   getContext<TOptions extends PluginFactoryOptions>(plugin: NormalizedPlugin<TOptions>): Omit<GeneratorContext<TOptions>, 'options'> {
     const driver = this
 
+    const report = (diagnostic: Omit<ProblemDiagnostic, 'plugin'>): void => {
+      Diagnostics.report({ ...diagnostic, plugin: plugin.name })
+      if (diagnostic.severity === 'error') {
+        driver.hooks.emit('kubb:error', { error: diagnostic.cause ?? new Error(diagnostic.message) })
+        return
+      }
+      if (diagnostic.severity === 'warning') {
+        driver.hooks.emit('kubb:warn', { message: diagnostic.message })
+        return
+      }
+      driver.hooks.emit('kubb:info', { message: diagnostic.message })
+    }
+
     return {
       config: driver.config,
       get root(): string {
@@ -811,16 +847,17 @@ export class KubbDriver {
         return driver.getResolver(plugin.name)
       },
       get transformer() {
-        return plugin.transformer
+        return driver.#transforms.get(plugin.name)
       },
       warn(message: string) {
-        driver.hooks.emit('kubb:warn', { message })
+        report({ code: diagnosticCode.pluginWarning, severity: 'warning', message })
       },
       error(error: string | Error) {
-        driver.hooks.emit('kubb:error', { error: typeof error === 'string' ? new Error(error) : error })
+        const cause = typeof error === 'string' ? undefined : error
+        report({ code: diagnosticCode.pluginFailed, severity: 'error', message: typeof error === 'string' ? error : error.message, cause })
       },
       info(message: string) {
-        driver.hooks.emit('kubb:info', { message })
+        report({ code: diagnosticCode.pluginInfo, severity: 'info', message })
       },
       async openInStudio(options?: DevtoolsOptions) {
         if (!driver.config.devtools || driver.#studio.isOpen) {
@@ -828,11 +865,23 @@ export class KubbDriver {
         }
 
         if (typeof driver.config.devtools !== 'object') {
-          throw new Error('Devtools must be an object')
+          throw new DiagnosticError({
+            code: diagnosticCode.devtoolsInvalid,
+            severity: 'error',
+            message: 'The `devtools` config must be an object.',
+            help: 'Set `devtools` to an options object, or remove it to disable Kubb Studio.',
+            location: { kind: 'config' },
+          })
         }
 
         if (!driver.adapter || !driver.#studio.source) {
-          throw new Error('adapter is not defined, make sure you have set the parser in kubb.config.ts')
+          throw new DiagnosticError({
+            code: diagnosticCode.adapterRequired,
+            severity: 'error',
+            message: 'An adapter is required to open Kubb Studio, but none is configured.',
+            help: 'Set `adapter` in kubb.config.ts (for example `adapterOas()`).',
+            location: { kind: 'config' },
+          })
         }
 
         driver.#studio.isOpen = true
@@ -860,63 +909,28 @@ export class KubbDriver {
   requirePlugin(pluginName: string): Plugin {
     const plugin = this.plugins.get(pluginName)
     if (!plugin) {
-      throw new Error(`[kubb] Plugin "${pluginName}" is required but not found. Make sure it is included in your Kubb config.`)
+      throw new DiagnosticError({
+        code: diagnosticCode.pluginNotFound,
+        severity: 'error',
+        message: `Plugin "${pluginName}" is required but not found. Make sure it is included in your Kubb config.`,
+        help: `Add "${pluginName}" to the \`plugins\` array in kubb.config.ts, or remove the dependency on it.`,
+        location: { kind: 'config' },
+      })
     }
     return plugin
   }
 }
 
-/**
- * Handles the return value of a plugin AST hook or generator method.
- *
- * - Renderer output → rendered via the provided `rendererFactory` (e.g. JSX), files stored in `driver.fileManager`
- * - `Array<FileNode>` → added directly into `driver.fileManager`
- * - `void` / `null` / `undefined` → no-op (plugin handled it via `this.upsertFile`)
- *
- * Pass a `rendererFactory` (e.g. `jsxRenderer` from `@kubb/renderer-jsx`) when the result
- * may be a renderer element. Generators that only return `Array<FileNode>` do not need one.
- */
-export function applyHookResult<TElement = unknown>({
-  result,
-  driver,
-  rendererFactory,
-}: {
-  result: TElement | Array<FileNode> | undefined | null
-  driver: KubbDriver
-  rendererFactory?: RendererFactory<TElement> | null
-}): void | Promise<void> {
-  if (!result) return
-
-  if (Array.isArray(result)) {
-    driver.fileManager.upsert(...(result as Array<FileNode>))
-    return
-  }
-
-  if (!rendererFactory) {
-    return
-  }
-
-  const renderer = rendererFactory()
-  if (renderer.stream) {
-    using r = renderer
-    for (const file of r.stream!(result)) {
-      driver.fileManager.upsert(file)
-    }
-    return
-  }
-  return applyAsyncRender({ renderer, result, driver })
-}
-
-async function applyAsyncRender<TElement>({ renderer, result, driver }: { renderer: Renderer<TElement>; result: TElement; driver: KubbDriver }): Promise<void> {
-  using r = renderer
-  await r.render(result)
-  driver.fileManager.upsert(...r.files)
-}
-
 function inputToAdapterSource(config: Config): AdapterSource {
   const input = config.input
   if (!input) {
-    throw new Error('[kubb] input is required when using an adapter. Provide input.path or input.data in your config.')
+    throw new DiagnosticError({
+      code: diagnosticCode.inputRequired,
+      severity: 'error',
+      message: 'An adapter is configured without an input.',
+      help: 'Provide `input.path` (a file or URL) or `input.data` (an inline spec) in your Kubb config.',
+      location: { kind: 'config' },
+    })
   }
 
   if ('data' in input) {