@kubb/core 5.0.0-alpha.9 → 5.0.0-beta.10

package/src/PluginDriver.ts

@@ -1,663 +1,457 @@
-import { basename, extname, resolve } from 'node:path'
-import { performance } from 'node:perf_hooks'
+import { resolve } from 'node:path'
 import type { AsyncEventEmitter } from '@internals/utils'
-import { isPromiseRejectedResult, setUniqueName, transformReservedWord, ValidationPluginError } from '@internals/utils'
-import type { RootNode } from '@kubb/ast/types'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
-import { CORE_PLUGIN_NAME, DEFAULT_STUDIO_URL } from './constants.ts'
+import type { FileNode, InputNode, OperationNode, SchemaNode } from '@kubb/ast'
+import { createFile } from '@kubb/ast'
+import { DEFAULT_STUDIO_URL } from './constants.ts'
+import type { Generator } from './defineGenerator.ts'
+import type { Plugin } from './definePlugin.ts'
+import { getMode } from './definePlugin.ts'
+import { defineResolver } from './defineResolver.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
+import { FileManager } from './FileManager.ts'
+import type { RendererFactory } from './createRenderer.ts'
 
 import type {
   Adapter,
   Config,
   DevtoolsOptions,
-  KubbEvents,
-  Plugin,
-  PluginContext,
+  GeneratorContext,
+  KubbHooks,
+  KubbPluginSetupContext,
+  NormalizedPlugin,
   PluginFactoryOptions,
-  PluginLifecycle,
-  PluginLifecycleHooks,
-  PluginParameter,
-  PluginWithLifeCycle,
-  ResolveNameParams,
-  ResolvePathParams,
-  UserPlugin,
+  Resolver,
 } from './types.ts'
-import { hookFirst, hookParallel, hookSeq } from './utils/executeStrategies.ts'
-
-type RequiredPluginLifecycle = Required<PluginLifecycle>
-
-export type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookSeq'
-
-type ParseResult<H extends PluginLifecycleHooks> = RequiredPluginLifecycle[H]
-
-type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseResult<H>>> = {
-  result: Result
-  plugin: Plugin
-}
 
 // inspired by: https://github.com/rollup/rollup/blob/master/src/utils/PluginDriver.ts#
 
 type Options = {
-  fabric: FabricType
-  events: AsyncEventEmitter<KubbEvents>
-  /**
-   * @default Number.POSITIVE_INFINITY
-   */
-  concurrency?: number
+  hooks: AsyncEventEmitter<KubbHooks>
 }
 
-export type GetFileOptions<TOptions = object> = {
-  name: string
-  mode?: KubbFile.Mode
-  extname: KubbFile.Extname
-  pluginName: string
-  options?: TOptions
+function enforceOrder(enforce: 'pre' | 'post' | undefined): number {
+  return enforce === 'pre' ? -1 : enforce === 'post' ? 1 : 0
 }
 
-export function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode {
-  if (!fileOrFolder) {
-    return 'split'
-  }
-  return extname(fileOrFolder) ? 'single' : 'split'
-}
-
-const hookFirstNullCheck = (state: unknown) => !!(state as SafeParseResult<'resolveName'> | null)?.result
-
 export class PluginDriver {
   readonly config: Config
   readonly options: Options
 
   /**
-   * The universal `@kubb/ast` `RootNode` produced by the adapter, set by
+   * Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
+   *
+   * @example
+   * ```ts
+   * PluginDriver.getMode('src/gen/types.ts')  // 'single'
+   * PluginDriver.getMode('src/gen/types')     // 'split'
+   * ```
+   */
+  static getMode(fileOrFolder: string | undefined | null): 'single' | 'split' {
+    return getMode(fileOrFolder)
+  }
+
+  /**
+   * The universal `@kubb/ast` `InputNode` produced by the adapter, set by
    * the build pipeline after the adapter's `parse()` resolves.
    */
-  rootNode: RootNode | undefined = undefined
+  inputNode: InputNode | undefined = undefined
   adapter: Adapter | undefined = undefined
   #studioIsOpen = false
 
-  readonly #plugins = new Set<Plugin>()
-  readonly #usedPluginNames: Record<string, number> = {}
+  /**
+   * 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.
+   */
+  readonly fileManager = new FileManager()
+
+  readonly plugins = new Map<string, NormalizedPlugin>()
+
+  /**
+   * Tracks which plugins have generators registered via `addGenerator()` (event-based path).
+   * Used by the build loop to decide whether to emit generator events for a given plugin.
+   */
+  readonly #pluginsWithEventGenerators = new Set<string>()
+  readonly #resolvers = new Map<string, Resolver>()
+  readonly #defaultResolvers = new Map<string, Resolver>()
+  readonly #hookListeners = new Map<keyof KubbHooks, Set<(...args: never[]) => void | Promise<void>>>()
 
   constructor(config: Config, options: Options) {
     this.config = config
     this.options = options
-    ;[...(config.plugins || [])].forEach((plugin) => {
-      const parsedPlugin = this.#parse(plugin as UserPlugin)
-
-      this.#plugins.add(parsedPlugin)
-    })
-  }
-
-  get events() {
-    return this.options.events
-  }
-
-  getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown> {
-    const plugins = [...this.#plugins]
-    const driver = this
-
-    const baseContext = {
-      fabric: this.options.fabric,
-      config: this.config,
-      plugin,
-      events: this.options.events,
-      driver: this,
-      mode: getMode(resolve(this.config.root, this.config.output.path)),
-      addFile: async (...files: Array<KubbFile.File>) => {
-        await this.options.fabric.addFile(...files)
-      },
-      upsertFile: async (...files: Array<KubbFile.File>) => {
-        await this.options.fabric.upsertFile(...files)
-      },
-      get rootNode(): RootNode | undefined {
-        return driver.rootNode
-      },
-      get adapter(): Adapter | undefined {
-        return driver.adapter
-      },
-      openInStudio(options?: DevtoolsOptions) {
-        if (!driver.config.devtools || driver.#studioIsOpen) {
-          return
-        }
-
-        if (typeof driver.config.devtools !== 'object') {
-          throw new Error('Devtools must be an object')
-        }
-
-        if (!driver.rootNode || !driver.adapter) {
-          throw new Error('adapter is not defined, make sure you have set the parser in kubb.config.ts')
+    config.plugins
+      .map((rawPlugin) => this.#normalizePlugin(rawPlugin as Plugin))
+      .filter((plugin) => {
+        if (typeof plugin.apply === 'function') {
+          return plugin.apply(config)
         }
-
-        driver.#studioIsOpen = true
-
-        const studioUrl = driver.config.devtools?.studioUrl ?? DEFAULT_STUDIO_URL
-
-        return openInStudioFn(driver.rootNode, studioUrl, options)
-      },
-    } as unknown as PluginContext<TOptions>
-
-    const mergedExtras: Record<string, unknown> = {}
-    for (const p of plugins) {
-      if (typeof p.inject === 'function') {
-        const result = (p.inject as (this: PluginContext, context: PluginContext) => unknown).call(
-          baseContext as unknown as PluginContext,
-          baseContext as unknown as PluginContext,
-        )
-        if (result !== null && typeof result === 'object') {
-          Object.assign(mergedExtras, result)
-        }
-      }
-    }
-
-    return {
-      ...baseContext,
-      ...mergedExtras,
-    }
-  }
-
-  get plugins(): Array<Plugin> {
-    return this.#getSortedPlugins()
-  }
-
-  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): KubbFile.File<{ pluginName: string }> {
-    const resolvedName = mode ? (mode === 'single' ? '' : this.resolveName({ name, pluginName, type: 'file' })) : name
-
-    const path = this.resolvePath({
-      baseName: `${resolvedName}${extname}` as const,
-      mode,
-      pluginName,
-      options,
-    })
-
-    if (!path) {
-      throw new Error(`Filepath should be defined for resolvedName "${resolvedName}" and pluginName "${pluginName}"`)
-    }
-
-    return {
-      path,
-      baseName: basename(path) as KubbFile.File['baseName'],
-      meta: {
-        pluginName,
-      },
-      sources: [],
-      imports: [],
-      exports: [],
-    }
-  }
-
-  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
-    const root = resolve(this.config.root, this.config.output.path)
-    const defaultPath = resolve(root, params.baseName)
-
-    if (params.pluginName) {
-      const paths = this.hookForPluginSync({
-        pluginName: params.pluginName,
-        hookName: 'resolvePath',
-        parameters: [params.baseName, params.mode, params.options as object],
+        return true
       })
-
-      return paths?.at(0) || defaultPath
-    }
-
-    const firstResult = this.hookFirstSync({
-      hookName: 'resolvePath',
-      parameters: [params.baseName, params.mode, params.options as object],
-    })
-
-    return firstResult?.result || defaultPath
-  }
-  //TODO refactor by using the order of plugins and the cache of the fileManager instead of guessing and recreating the name/path
-  resolveName = (params: ResolveNameParams): string => {
-    if (params.pluginName) {
-      const names = this.hookForPluginSync({
-        pluginName: params.pluginName,
-        hookName: 'resolveName',
-        parameters: [params.name.trim(), params.type],
+      .sort((a, b) => {
+        if (b.dependencies?.includes(a.name)) return -1
+        if (a.dependencies?.includes(b.name)) return 1
+        // enforce: 'pre' plugins run first, 'post' plugins run last
+        return enforceOrder(a.enforce) - enforceOrder(b.enforce)
       })
+      .forEach((plugin) => {
+        this.plugins.set(plugin.name, plugin)
+      })
+  }
 
-      const uniqueNames = new Set(names)
-
-      return transformReservedWord([...uniqueNames].at(0) || params.name)
-    }
-
-    const name = this.hookFirstSync({
-      hookName: 'resolveName',
-      parameters: [params.name.trim(), params.type],
-    })?.result
-
-    return transformReservedWord(name ?? params.name)
+  get hooks() {
+    return this.options.hooks
   }
 
   /**
-   * Run a specific hookName for plugin x.
+   * Creates an `NormalizedPlugin` from a hook-style plugin and registers
+   * its lifecycle handlers on the `AsyncEventEmitter`.
    */
-  async hookForPlugin<H extends PluginLifecycleHooks>({
-    pluginName,
-    hookName,
-    parameters,
-  }: {
-    pluginName: string
-    hookName: H
-    parameters: PluginParameter<H>
-  }): Promise<Array<ReturnType<ParseResult<H>> | null>> {
-    const plugins = this.getPluginsByName(hookName, pluginName)
-
-    this.events.emit('plugins:hook:progress:start', {
-      hookName,
-      plugins,
-    })
-
-    const items: Array<ReturnType<ParseResult<H>>> = []
-
-    for (const plugin of plugins) {
-      const result = await this.#execute<H>({
-        strategy: 'hookFirst',
-        hookName,
-        parameters,
-        plugin,
-      })
+  #normalizePlugin(hookPlugin: Plugin): NormalizedPlugin {
+    const normalizedPlugin = {
+      name: hookPlugin.name,
+      dependencies: hookPlugin.dependencies,
+      enforce: hookPlugin.enforce,
+      options: { output: { path: '.' }, exclude: [], override: [] },
+    } as unknown as NormalizedPlugin
+
+    this.registerPluginHooks(hookPlugin, normalizedPlugin)
+    return normalizedPlugin
+  }
 
-      if (result !== undefined && result !== null) {
-        items.push(result)
+  /**
+   * 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.
+   *
+   * @internal
+   */
+  registerPluginHooks(hookPlugin: Plugin, normalizedPlugin: NormalizedPlugin): void {
+    const { hooks } = hookPlugin
+
+    if (!hooks) return
+
+    // kubb:plugin:setup gets special treatment: the globally emitted context is wrapped with
+    // plugin-specific implementations so that addGenerator / setResolver / etc. target
+    // this plugin's normalizedPlugin entry rather than being no-ops.
+    if (hooks['kubb:plugin:setup']) {
+      const setupHandler = (globalCtx: KubbPluginSetupContext) => {
+        const pluginCtx: KubbPluginSetupContext = {
+          ...globalCtx,
+          options: hookPlugin.options ?? {},
+          addGenerator: (gen) => {
+            this.registerGenerator(normalizedPlugin.name, gen)
+          },
+          setResolver: (resolver) => {
+            this.setPluginResolver(normalizedPlugin.name, resolver)
+          },
+          setTransformer: (visitor) => {
+            normalizedPlugin.transformer = visitor
+          },
+          setRenderer: (renderer) => {
+            normalizedPlugin.renderer = renderer
+          },
+          setOptions: (opts) => {
+            normalizedPlugin.options = { ...normalizedPlugin.options, ...opts }
+          },
+          injectFile: (userFileNode) => {
+            this.fileManager.add(createFile(userFileNode))
+          },
+        }
+        return hooks['kubb:plugin:setup']!(pluginCtx)
       }
+
+      this.hooks.on('kubb:plugin:setup', setupHandler)
+      this.#trackHookListener('kubb:plugin:setup', setupHandler as (...args: never[]) => void | Promise<void>)
     }
 
-    this.events.emit('plugins:hook:progress:end', { hookName })
+    // 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: never[]) => void | Promise<void>) | undefined]>) {
+      if (event === 'kubb:plugin:setup' || !handler) continue
 
-    return items
+      this.hooks.on(event, handler as never)
+      this.#trackHookListener(event, handler as (...args: never[]) => void | Promise<void>)
+    }
   }
+
   /**
-   * Run a specific hookName for plugin x.
+   * Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
+   * can configure generators, resolvers, transformers and renderers before `buildStart` runs.
+   *
+   * Call this once from `safeBuild` before the plugin execution loop begins.
    */
+  async emitSetupHooks(): Promise<void> {
+    const noop = () => {}
 
-  hookForPluginSync<H extends PluginLifecycleHooks>({
-    pluginName,
-    hookName,
-    parameters,
-  }: {
-    pluginName: string
-    hookName: H
-    parameters: PluginParameter<H>
-  }): Array<ReturnType<ParseResult<H>>> | null {
-    const plugins = this.getPluginsByName(hookName, pluginName)
-
-    const result = plugins
-      .map((plugin) => {
-        return this.#executeSync<H>({
-          strategy: 'hookFirst',
-          hookName,
-          parameters,
-          plugin,
-        })
-      })
-      .filter((x): x is NonNullable<typeof x> => x !== null)
-
-    return result
+    await this.hooks.emit('kubb:plugin:setup', {
+      config: this.config,
+      options: {},
+      addGenerator: noop,
+      setResolver: noop,
+      setTransformer: noop,
+      setRenderer: noop,
+      setOptions: noop,
+      injectFile: noop,
+      updateConfig: noop,
+    })
   }
 
   /**
-   * Returns the first non-null result.
+   * Registers a generator for the given plugin on the shared event emitter.
+   *
+   * The generator's `schema`, `operation`, and `operations` methods are registered as
+   * listeners on `kubb:generate:schema`, `kubb:generate:operation`, and `kubb:generate:operations`
+   * 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.
+   *
+   * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
    */
-  async hookFirst<H extends PluginLifecycleHooks>({
-    hookName,
-    parameters,
-    skipped,
-  }: {
-    hookName: H
-    parameters: PluginParameter<H>
-    skipped?: ReadonlySet<Plugin> | null
-  }): Promise<SafeParseResult<H>> {
-    const plugins = this.#getSortedPlugins(hookName).filter((plugin) => {
-      return skipped ? !skipped.has(plugin) : true
-    })
+  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)
+    }
 
-    this.events.emit('plugins:hook:progress:start', { hookName, plugins })
-
-    const promises = plugins.map((plugin) => {
-      return async () => {
-        const value = await this.#execute<H>({
-          strategy: 'hookFirst',
-          hookName,
-          parameters,
-          plugin,
-        })
-
-        return Promise.resolve({
-          plugin,
-          result: value,
-        } as SafeParseResult<H>)
+    if (gen.schema) {
+      const schemaHandler = async (node: SchemaNode, ctx: GeneratorContext) => {
+        if (ctx.plugin.name !== pluginName) return
+        const result = await gen.schema!(node, ctx)
+        await applyHookResult(result, this, resolveRenderer())
       }
-    })
-
-    const result = await hookFirst(promises, hookFirstNullCheck)
 
-    this.events.emit('plugins:hook:progress:end', { hookName })
+      this.hooks.on('kubb:generate:schema', schemaHandler)
+      this.#trackHookListener('kubb:generate:schema', schemaHandler as (...args: never[]) => void | Promise<void>)
+    }
 
-    return result
-  }
+    if (gen.operation) {
+      const operationHandler = async (node: OperationNode, ctx: GeneratorContext) => {
+        if (ctx.plugin.name !== pluginName) return
+        const result = await gen.operation!(node, ctx)
+        await applyHookResult(result, this, resolveRenderer())
+      }
 
-  /**
-   * Returns the first non-null result.
-   */
-  hookFirstSync<H extends PluginLifecycleHooks>({
-    hookName,
-    parameters,
-    skipped,
-  }: {
-    hookName: H
-    parameters: PluginParameter<H>
-    skipped?: ReadonlySet<Plugin> | null
-  }): SafeParseResult<H> | null {
-    let parseResult: SafeParseResult<H> | null = null
-    const plugins = this.#getSortedPlugins(hookName).filter((plugin) => {
-      return skipped ? !skipped.has(plugin) : true
-    })
+      this.hooks.on('kubb:generate:operation', operationHandler)
+      this.#trackHookListener('kubb:generate:operation', operationHandler as (...args: never[]) => void | Promise<void>)
+    }
 
-    for (const plugin of plugins) {
-      parseResult = {
-        result: this.#executeSync<H>({
-          strategy: 'hookFirst',
-          hookName,
-          parameters,
-          plugin,
-        }),
-        plugin,
-      } as SafeParseResult<H>
-
-      if (parseResult?.result != null) {
-        break
+    if (gen.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, this, resolveRenderer())
       }
+
+      this.hooks.on('kubb:generate:operations', operationsHandler)
+      this.#trackHookListener('kubb:generate:operations', operationsHandler as (...args: never[]) => void | Promise<void>)
     }
 
-    return parseResult
+    this.#pluginsWithEventGenerators.add(pluginName)
   }
 
   /**
-   * Runs all plugins in parallel based on `this.plugin` order and `pre`/`post` settings.
+   * Returns `true` when at least one generator was registered for the given plugin
+   * via `addGenerator()` in `kubb:plugin:setup` (event-based path).
+   *
+   * Used by the build loop to decide whether to walk the AST and emit generator events
+   * for a plugin that has no static `plugin.generators`.
    */
-  async hookParallel<H extends PluginLifecycleHooks, TOutput = void>({
-    hookName,
-    parameters,
-  }: {
-    hookName: H
-    parameters?: Parameters<RequiredPluginLifecycle[H]> | undefined
-  }): Promise<Awaited<TOutput>[]> {
-    const plugins = this.#getSortedPlugins(hookName)
-    this.events.emit('plugins:hook:progress:start', { hookName, plugins })
-
-    const pluginStartTimes = new Map<Plugin, number>()
-
-    const promises = plugins.map((plugin) => {
-      return () => {
-        pluginStartTimes.set(plugin, performance.now())
-        return this.#execute({
-          strategy: 'hookParallel',
-          hookName,
-          parameters,
-          plugin,
-        }) as Promise<TOutput>
-      }
-    })
-
-    const results = await hookParallel(promises, this.options.concurrency)
-
-    results.forEach((result, index) => {
-      if (isPromiseRejectedResult<Error>(result)) {
-        const plugin = this.#getSortedPlugins(hookName)[index]
-
-        if (plugin) {
-          const startTime = pluginStartTimes.get(plugin) ?? performance.now()
-          this.events.emit('error', result.reason, {
-            plugin,
-            hookName,
-            strategy: 'hookParallel',
-            duration: Math.round(performance.now() - startTime),
-            parameters,
-          })
-        }
-      }
-    })
-
-    this.events.emit('plugins:hook:progress:end', { hookName })
-
-    return results.reduce((acc, result) => {
-      if (result.status === 'fulfilled') {
-        acc.push(result.value)
-      }
-      return acc
-    }, [] as Awaited<TOutput>[])
+  hasRegisteredGenerators(pluginName: string): boolean {
+    return this.#pluginsWithEventGenerators.has(pluginName)
   }
 
   /**
-   * Chains plugins
+   * Unregisters all plugin lifecycle listeners from the shared event emitter.
+   * Called at the end of a build to prevent listener leaks across repeated builds.
+   *
+   * @internal
    */
-  async hookSeq<H extends PluginLifecycleHooks>({ hookName, parameters }: { hookName: H; parameters?: PluginParameter<H> }): Promise<void> {
-    const plugins = this.#getSortedPlugins(hookName)
-    this.events.emit('plugins:hook:progress:start', { hookName, plugins })
-
-    const promises = plugins.map((plugin) => {
-      return () =>
-        this.#execute({
-          strategy: 'hookSeq',
-          hookName,
-          parameters,
-          plugin,
-        })
-    })
-
-    await hookSeq(promises)
-
-    this.events.emit('plugins:hook:progress:end', { hookName })
+  dispose(): void {
+    for (const [event, handlers] of this.#hookListeners) {
+      for (const handler of handlers) {
+        this.hooks.off(event, handler as never)
+      }
+    }
+    this.#hookListeners.clear()
+    this.#pluginsWithEventGenerators.clear()
   }
 
-  #getSortedPlugins(hookName?: keyof PluginLifecycle): Array<Plugin> {
-    const plugins = [...this.#plugins]
-
-    if (hookName) {
-      return plugins.filter((plugin) => hookName in plugin)
+  #trackHookListener(event: keyof KubbHooks, handler: (...args: never[]) => void | Promise<void>): void {
+    let handlers = this.#hookListeners.get(event)
+    if (!handlers) {
+      handlers = new Set()
+      this.#hookListeners.set(event, handlers)
     }
-    // TODO add test case for sorting with pre/post
-
-    return plugins
-      .map((plugin) => {
-        if (plugin.pre) {
-          let missingPlugins = plugin.pre.filter((pluginName) => !plugins.find((pluginToFind) => pluginToFind.name === pluginName))
-
-          // when adapter is set, we can ignore the depends on plugin-oas, in v5 this will not be needed anymore
-          if (missingPlugins.includes('plugin-oas') && this.adapter) {
-            missingPlugins = missingPlugins.filter((pluginName) => pluginName !== 'plugin-oas')
-          }
-
-          if (missingPlugins.length > 0) {
-            throw new ValidationPluginError(`The plugin '${plugin.name}' has a pre set that references missing plugins for '${missingPlugins.join(', ')}'`)
-          }
-        }
-
-        return plugin
-      })
-      .sort((a, b) => {
-        if (b.pre?.includes(a.name)) {
-          return 1
-        }
-        if (b.post?.includes(a.name)) {
-          return -1
-        }
-        return 0
-      })
+    handlers.add(handler)
   }
 
-  getPluginByName(pluginName: string): Plugin | undefined {
-    const plugins = [...this.#plugins]
+  #createDefaultResolver(pluginName: string): Resolver {
+    const existingResolver = this.#defaultResolvers.get(pluginName)
+    if (existingResolver) {
+      return existingResolver
+    }
 
-    return plugins.find((item) => item.name === pluginName)
+    const resolver = defineResolver<PluginFactoryOptions>(() => ({
+      name: 'default',
+      pluginName,
+    }))
+    this.#defaultResolvers.set(pluginName, resolver)
+    return resolver
   }
 
-  getPluginsByName(hookName: keyof PluginWithLifeCycle, pluginName: string): Plugin[] {
-    const plugins = [...this.plugins]
-
-    const pluginByPluginName = plugins.filter((plugin) => hookName in plugin).filter((item) => item.name === pluginName)
-
-    if (!pluginByPluginName?.length) {
-      // fallback on the core plugin when there is no match
-
-      const corePlugin = plugins.find((plugin) => plugin.name === CORE_PLUGIN_NAME && hookName in plugin)
-
-      return corePlugin ? [corePlugin] : []
+  /**
+   * Merges `partial` with the plugin's default resolver and stores the result.
+   * Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
+   * get the up-to-date resolver without going through `getResolver()`.
+   */
+  setPluginResolver(pluginName: string, partial: Partial<Resolver>): void {
+    const defaultResolver = this.#createDefaultResolver(pluginName)
+    const merged = { ...defaultResolver, ...partial }
+    this.#resolvers.set(pluginName, merged)
+    const plugin = this.plugins.get(pluginName)
+    if (plugin) {
+      plugin.resolver = merged
     }
-
-    return pluginByPluginName
   }
 
   /**
-   * Run an async plugin hook and return the result.
-   * @param hookName Name of the plugin hook. Must be either in `PluginHooks` or `OutputPluginValueHooks`.
-   * @param args Arguments passed to the plugin hook.
-   * @param plugin The actual pluginObject to run.
+   * Returns the resolver for the given plugin.
+   *
+   * Resolution order: dynamic resolver set via `setPluginResolver` → static resolver on the
+   * plugin → lazily created default resolver (identity name, no path transforms).
    */
-  #emitProcessingEnd<H extends PluginLifecycleHooks>({
-    startTime,
-    output,
-    strategy,
-    hookName,
-    plugin,
-    parameters,
-  }: {
-    startTime: number
-    output: unknown
-    strategy: Strategy
-    hookName: H
-    plugin: PluginWithLifeCycle
-    parameters: unknown[] | undefined
-  }): void {
-    this.events.emit('plugins:hook:processing:end', {
-      duration: Math.round(performance.now() - startTime),
-      parameters,
-      output,
-      strategy,
-      hookName,
-      plugin,
-    })
+  getResolver<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Kubb.PluginRegistry[TName]['resolver']
+  getResolver<TResolver extends Resolver = Resolver>(pluginName: string): TResolver
+  getResolver(pluginName: string): Resolver {
+    return this.#resolvers.get(pluginName) ?? this.plugins.get(pluginName)?.resolver ?? this.#createDefaultResolver(pluginName)
   }
 
-  // Implementation signature
-  #execute<H extends PluginLifecycleHooks>({
-    strategy,
-    hookName,
-    parameters,
-    plugin,
-  }: {
-    strategy: Strategy
-    hookName: H
-    parameters: unknown[] | undefined
-    plugin: PluginWithLifeCycle
-  }): Promise<ReturnType<ParseResult<H>> | null> | null {
-    const hook = plugin[hookName]
-
-    if (!hook) {
-      return null
-    }
+  getContext<TOptions extends PluginFactoryOptions>(plugin: NormalizedPlugin<TOptions>): GeneratorContext<TOptions> & Record<string, unknown> {
+    const driver = this
 
-    this.events.emit('plugins:hook:processing:start', {
-      strategy,
-      hookName,
-      parameters,
+    const baseContext = {
+      config: driver.config,
+      get root(): string {
+        return resolve(driver.config.root, driver.config.output.path)
+      },
+      getMode(output: { path: string }): 'single' | 'split' {
+        return PluginDriver.getMode(resolve(driver.config.root, driver.config.output.path, output.path))
+      },
+      hooks: driver.hooks,
       plugin,
-    })
+      getPlugin: driver.getPlugin.bind(driver),
+      requirePlugin: driver.requirePlugin.bind(driver),
+      getResolver: driver.getResolver.bind(driver),
+      driver,
+      addFile: async (...files: Array<FileNode>) => {
+        driver.fileManager.add(...files)
+      },
+      upsertFile: async (...files: Array<FileNode>) => {
+        driver.fileManager.upsert(...files)
+      },
+      get inputNode(): InputNode | undefined {
+        return driver.inputNode
+      },
+      get adapter(): Adapter | undefined {
+        return driver.adapter
+      },
+      get resolver() {
+        return driver.getResolver(plugin.name)
+      },
+      get transformer() {
+        return plugin.transformer
+      },
+      warn(message: string) {
+        driver.hooks.emit('kubb:warn', { message })
+      },
+      error(error: string | Error) {
+        driver.hooks.emit('kubb:error', { error: typeof error === 'string' ? new Error(error) : error })
+      },
+      info(message: string) {
+        driver.hooks.emit('kubb:info', { message })
+      },
+      openInStudio(options?: DevtoolsOptions) {
+        if (!driver.config.devtools || driver.#studioIsOpen) {
+          return
+        }
 
-    const startTime = performance.now()
+        if (typeof driver.config.devtools !== 'object') {
+          throw new Error('Devtools must be an object')
+        }
 
-    const task = (async () => {
-      try {
-        const output =
-          typeof hook === 'function' ? await Promise.resolve((hook as (...args: unknown[]) => unknown).apply(this.getContext(plugin), parameters ?? [])) : hook
+        if (!driver.inputNode || !driver.adapter) {
+          throw new Error('adapter is not defined, make sure you have set the parser in kubb.config.ts')
+        }
 
-        this.#emitProcessingEnd({ startTime, output, strategy, hookName, plugin, parameters })
+        driver.#studioIsOpen = true
 
-        return output as ReturnType<ParseResult<H>>
-      } catch (error) {
-        this.events.emit('error', error as Error, {
-          plugin,
-          hookName,
-          strategy,
-          duration: Math.round(performance.now() - startTime),
-        })
+        const studioUrl = driver.config.devtools?.studioUrl ?? DEFAULT_STUDIO_URL
 
-        return null
-      }
-    })()
+        return openInStudioFn(driver.inputNode, studioUrl, options)
+      },
+    } as unknown as GeneratorContext<TOptions>
 
-    return task
+    return baseContext
+  }
+
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
+  getPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions> | undefined
+  getPlugin(pluginName: string): Plugin | undefined {
+    return this.plugins.get(pluginName)
   }
 
   /**
-   * Run a sync plugin hook and return the result.
-   * @param hookName Name of the plugin hook. Must be in `PluginHooks`.
-   * @param args Arguments passed to the plugin hook.
-   * @param plugin The actual plugin
+   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
    */
-  #executeSync<H extends PluginLifecycleHooks>({
-    strategy,
-    hookName,
-    parameters,
-    plugin,
-  }: {
-    strategy: Strategy
-    hookName: H
-    parameters: PluginParameter<H>
-    plugin: PluginWithLifeCycle
-  }): ReturnType<ParseResult<H>> | null {
-    const hook = plugin[hookName]
-
-    if (!hook) {
-      return null
-    }
-
-    this.events.emit('plugins:hook:processing:start', {
-      strategy,
-      hookName,
-      parameters,
-      plugin,
-    })
-
-    const startTime = performance.now()
-
-    try {
-      const output =
-        typeof hook === 'function'
-          ? ((hook as (...args: unknown[]) => unknown).apply(this.getContext(plugin), parameters) as ReturnType<ParseResult<H>>)
-          : (hook as ReturnType<ParseResult<H>>)
-
-      this.#emitProcessingEnd({ startTime, output, strategy, hookName, plugin, parameters })
-
-      return output
-    } catch (error) {
-      this.events.emit('error', error as Error, {
-        plugin,
-        hookName,
-        strategy,
-        duration: Math.round(performance.now() - startTime),
-      })
-
-      return null
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]>
+  requirePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions>
+  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.`)
     }
+    return plugin
   }
+}
 
-  #parse(plugin: UserPlugin): Plugin {
-    const usedPluginNames = this.#usedPluginNames
-
-    setUniqueName(plugin.name, usedPluginNames)
-
-    const usageCount = usedPluginNames[plugin.name]
-    if (usageCount && usageCount > 1) {
-      throw new ValidationPluginError(
-        `Duplicate plugin "${plugin.name}" detected. Each plugin can only be used once. Use a different configuration instead of adding multiple instances of the same 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 async function applyHookResult<TElement = unknown>(
+  result: TElement | Array<FileNode> | void,
+  driver: PluginDriver,
+  rendererFactory?: RendererFactory<TElement>,
+): Promise<void> {
+  if (!result) return
+
+  if (Array.isArray(result)) {
+    driver.fileManager.upsert(...(result as Array<FileNode>))
+    return
+  }
 
-    return {
-      install() {},
-      ...plugin,
-    } as unknown as Plugin
+  if (!rendererFactory) {
+    return
   }
+
+  const renderer = rendererFactory()
+  await renderer.render(result)
+  driver.fileManager.upsert(...renderer.files)
+  renderer.unmount()
 }