@kubb/core 5.0.0-alpha.34 → 5.0.0-alpha.36

package/src/PluginDriver.ts

@@ -2,17 +2,24 @@ import { basename, extname, resolve } from 'node:path'
 import { performance } from 'node:perf_hooks'
 import type { AsyncEventEmitter } from '@internals/utils'
 import { isPromiseRejectedResult, transformReservedWord } from '@internals/utils'
+import type { FileNode, InputNode } from '@kubb/ast'
 import { createFile } from '@kubb/ast'
-import type { FileNode, InputNode } from '@kubb/ast/types'
 import { DEFAULT_STUDIO_URL } from './constants.ts'
+import type { Generator } from './defineGenerator.ts'
+import { type HookStylePlugin, isHookStylePlugin } from './definePlugin.ts'
+import { defineResolver } from './defineResolver.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
 import { FileManager } from './FileManager.ts'
+import { applyHookResult } from './renderNode.ts'
 
 import type {
   Adapter,
   Config,
   DevtoolsOptions,
-  KubbEvents,
+  Group,
+  KubbHooks,
+  KubbPluginSetupContext,
+  Output,
   Plugin,
   PluginContext,
   PluginFactoryOptions,
@@ -22,6 +29,7 @@ import type {
   PluginWithLifeCycle,
   ResolveNameParams,
   ResolvePathParams,
+  Resolver,
 } from './types.ts'
 import { hookFirst, hookParallel, hookSeq } from './utils/executeStrategies.ts'
 
@@ -47,7 +55,7 @@ type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseRe
 // inspired by: https://github.com/rollup/rollup/blob/master/src/utils/PluginDriver.ts#
 
 type Options = {
-  events: AsyncEventEmitter<KubbEvents>
+  hooks?: AsyncEventEmitter<KubbHooks>
   /**
    * @default Number.POSITIVE_INFINITY
    */
@@ -104,11 +112,28 @@ export class PluginDriver {
 
   readonly plugins = new Map<string, Plugin>()
 
+  /**
+   * 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
+    this.options = {
+      ...options,
+      hooks: options.hooks,
+    }
     config.plugins
-      .map((plugin) => Object.assign({ buildStart() {}, buildEnd() {} }, plugin) as unknown as Plugin)
+      .map((rawPlugin) => {
+        if (isHookStylePlugin(rawPlugin)) {
+          return this.#normalizeHookStylePlugin(rawPlugin as HookStylePlugin)
+        }
+        return { ...rawPlugin, buildStart: rawPlugin.buildStart ?? (() => {}), buildEnd: rawPlugin.buildEnd ?? (() => {}) } as unknown as Plugin
+      })
       .filter((plugin) => {
         if (typeof plugin.apply === 'function') {
           return plugin.apply(config)
@@ -116,8 +141,8 @@ export class PluginDriver {
         return true
       })
       .sort((a, b) => {
-        if (b.pre?.includes(a.name)) return 1
-        if (b.post?.includes(a.name)) return -1
+        if (b.dependencies?.includes(a.name)) return -1
+        if (a.dependencies?.includes(b.name)) return 1
         return 0
       })
       .forEach((plugin) => {
@@ -125,8 +150,267 @@ export class PluginDriver {
       })
   }
 
-  get events() {
-    return this.options.events
+  get hooks() {
+    if (!this.options.hooks) {
+      throw new Error('hooks are not defined')
+    }
+    return this.options.hooks
+  }
+
+  /**
+   * Creates a `Plugin`-compatible object from a hook-style plugin and registers
+   * its lifecycle handlers on the `AsyncEventEmitter`.
+   *
+   * The normalized plugin has an empty `buildStart` — generators registered via
+   * `addGenerator()` in `kubb:plugin:setup` are stored on `normalizedPlugin.generators`
+   * and used by `runPluginAstHooks` during the build.
+   */
+  #normalizeHookStylePlugin(hookPlugin: HookStylePlugin): Plugin {
+    const generators: Plugin['generators'] = []
+    const driver = this
+    // The options shape is the minimal struct required by Plugin. Hook-style plugins
+    // use generators registered via addGenerator() and resolvers set via setResolver().
+    // `inject` and `resolver` are required by the Plugin type but are irrelevant for hook-style
+    // plugins: inject is a no-op and resolver is set dynamically via setResolver() in kubb:plugin:setup.
+    //
+    // `resolveName` and `resolvePath` bridge the legacy PluginDriver.resolveName/resolvePath
+    // lifecycle so that other plugins calling `driver.resolveName({ pluginName })` or
+    // `driver.getFile({ pluginName })` still get correct results from hook-style plugins.
+    const normalizedPlugin = {
+      name: hookPlugin.name,
+      dependencies: hookPlugin.dependencies,
+      options: { output: { path: '.' }, exclude: [], override: [] },
+      generators,
+      inject: () => undefined,
+      resolveName(name: string, type?: ResolveNameParams['type']) {
+        const resolver = driver.getResolver(hookPlugin.name)
+        return resolver.default(name, type)
+      },
+      resolvePath(baseName: FileNode['baseName'], pathMode?: 'single' | 'split', resolveOptions?: Record<string, unknown>) {
+        const resolver = driver.getResolver(hookPlugin.name)
+        const opts = normalizedPlugin.options as Record<string, unknown>
+        const group = resolveOptions?.group as Record<string, string> | undefined
+        return resolver.resolvePath(
+          { baseName, pathMode, tag: group?.tag, path: group?.path },
+          { root: resolve(driver.config.root, driver.config.output.path), output: opts.output as Output, group: opts.group as Group | undefined },
+        )
+      },
+      buildStart() {},
+      buildEnd() {},
+    } as unknown as Plugin
+    this.registerPluginHooks(hookPlugin, normalizedPlugin)
+    return normalizedPlugin
+  }
+
+  /**
+   * 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.
+   */
+  registerPluginHooks(hookPlugin: HookStylePlugin, normalizedPlugin: Plugin): void {
+    const { hooks } = hookPlugin
+
+    // 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: (file) => {
+            const fileNode = createFile({
+              baseName: file.baseName,
+              path: file.path,
+              sources: file.sources ?? [],
+              imports: [],
+              exports: [],
+            })
+            this.fileManager.add(fileNode)
+          },
+        }
+        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>)
+    }
+
+    // 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
+      this.hooks.on(event, handler as never)
+      this.#trackHookListener(event, handler as (...args: never[]) => void | Promise<void>)
+    }
+  }
+
+  /**
+   * 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> {
+    await this.hooks.emit('kubb:plugin:setup', {
+      config: this.config,
+      addGenerator: () => {},
+      setResolver: () => {},
+      setTransformer: () => {},
+      setRenderer: () => {},
+      setOptions: () => {},
+      injectFile: () => {},
+      updateConfig: () => {},
+      options: {},
+    })
+  }
+
+  /**
+   * 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.
+   */
+  registerGenerator(pluginName: string, gen: Generator<any>): void {
+    const resolveRenderer = () => {
+      const plugin = this.plugins.get(pluginName)
+      return gen.renderer === null ? undefined : (gen.renderer ?? plugin?.renderer ?? this.config.renderer)
+    }
+
+    if (gen.schema) {
+      const schemaHandler = async (node: Parameters<NonNullable<typeof gen.schema>>[0], ctx: Parameters<NonNullable<typeof gen.schema>>[1]) => {
+        if (ctx.plugin.name !== pluginName) return
+        const result = await gen.schema!(node, ctx)
+        await applyHookResult(result, this, resolveRenderer())
+      }
+
+      this.hooks.on('kubb:generate:schema', schemaHandler)
+      this.#trackHookListener('kubb:generate:schema', schemaHandler as (...args: never[]) => void | Promise<void>)
+    }
+
+    if (gen.operation) {
+      const operationHandler = async (node: Parameters<NonNullable<typeof gen.operation>>[0], ctx: Parameters<NonNullable<typeof gen.operation>>[1]) => {
+        if (ctx.plugin.name !== pluginName) return
+        const result = await gen.operation!(node, ctx)
+        await applyHookResult(result, this, resolveRenderer())
+      }
+
+      this.hooks.on('kubb:generate:operation', operationHandler)
+      this.#trackHookListener('kubb:generate:operation', operationHandler as (...args: never[]) => void | Promise<void>)
+    }
+
+    if (gen.operations) {
+      const operationsHandler = async (nodes: Parameters<NonNullable<typeof gen.operations>>[0], ctx: Parameters<NonNullable<typeof gen.operations>>[1]) => {
+        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>)
+    }
+
+    this.#pluginsWithEventGenerators.add(pluginName)
+  }
+
+  /**
+   * 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`.
+   */
+  hasRegisteredGenerators(pluginName: string): boolean {
+    return this.#pluginsWithEventGenerators.has(pluginName)
+  }
+
+  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()
+  }
+
+  #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)
+    }
+    handlers.add(handler)
+  }
+
+  #createDefaultResolver(pluginName: string): Resolver {
+    const existingResolver = this.#defaultResolvers.get(pluginName)
+    if (existingResolver) {
+      return existingResolver
+    }
+
+    const resolver = defineResolver<PluginFactoryOptions>(() => ({
+      name: 'default',
+      pluginName,
+    }))
+    this.#defaultResolvers.set(pluginName, resolver)
+    return resolver
+  }
+
+  setPluginResolver(pluginName: string, partial: Partial<Resolver>): void {
+    const defaultResolver = this.#createDefaultResolver(pluginName)
+    const merged = { ...defaultResolver, ...partial }
+    this.#resolvers.set(pluginName, merged)
+    // Mirror the resolved resolver onto the plugin so that consumers using
+    // `getPlugin(name).resolver` get the correct resolver without going through getResolver().
+    const plugin = this.plugins.get(pluginName)
+    if (plugin) {
+      plugin.resolver = merged
+    }
+  }
+
+  getResolver(pluginName: string): Resolver {
+    const dynamicResolver = this.#resolvers.get(pluginName)
+    if (dynamicResolver) {
+      return dynamicResolver
+    }
+
+    const pluginResolver = this.plugins.get(pluginName)?.resolver
+    if (pluginResolver) {
+      return pluginResolver
+    }
+
+    return this.#createDefaultResolver(pluginName)
   }
 
   getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown> {
@@ -140,7 +424,7 @@ export class PluginDriver {
       getMode(output: { path: string }): 'single' | 'split' {
         return getMode(resolve(driver.config.root, driver.config.output.path, output.path))
       },
-      events: driver.options.events,
+      hooks: driver.hooks,
       plugin,
       getPlugin: driver.getPlugin.bind(driver),
       requirePlugin: driver.requirePlugin.bind(driver),
@@ -158,19 +442,19 @@ export class PluginDriver {
         return driver.adapter
       },
       get resolver() {
-        return plugin.resolver
+        return driver.getResolver(plugin.name)
       },
       get transformer() {
         return plugin.transformer
       },
       warn(message: string) {
-        driver.events.emit('warn', message)
+        driver.hooks.emit('kubb:warn', message)
       },
       error(error: string | Error) {
-        driver.events.emit('error', typeof error === 'string' ? new Error(error) : error)
+        driver.hooks.emit('kubb:error', typeof error === 'string' ? new Error(error) : error)
       },
       info(message: string) {
-        driver.events.emit('info', message)
+        driver.hooks.emit('kubb:info', message)
       },
       openInStudio(options?: DevtoolsOptions) {
         if (!driver.config.devtools || driver.#studioIsOpen) {
@@ -193,13 +477,13 @@ export class PluginDriver {
       },
     } as unknown as PluginContext<TOptions>
 
-    const mergedExtras: Record<string, unknown> = {}
+    let mergedExtras: Record<string, unknown> = {}
 
     for (const p of this.plugins.values()) {
       if (typeof p.inject === 'function') {
         const result = (p.inject as (this: PluginContext) => unknown).call(baseContext as unknown as PluginContext)
         if (result !== null && typeof result === 'object') {
-          Object.assign(mergedExtras, result)
+          mergedExtras = { ...mergedExtras, ...(result as Record<string, unknown>) }
         }
       }
     }
@@ -302,7 +586,7 @@ export class PluginDriver {
       return [null]
     }
 
-    this.events.emit('plugins:hook:progress:start', {
+    this.hooks.emit('kubb:plugins:hook:progress:start', {
       hookName,
       plugins: [plugin],
     })
@@ -314,7 +598,7 @@ export class PluginDriver {
       plugin,
     })
 
-    this.events.emit('plugins:hook:progress:end', { hookName })
+    this.hooks.emit('kubb:plugins:hook:progress:end', { hookName })
 
     return [result]
   }
@@ -364,7 +648,7 @@ export class PluginDriver {
       if (hookName in plugin && (skipped ? !skipped.has(plugin) : true)) plugins.push(plugin)
     }
 
-    this.events.emit('plugins:hook:progress:start', { hookName, plugins })
+    this.hooks.emit('kubb:plugins:hook:progress:start', { hookName, plugins })
 
     const promises = plugins.map((plugin) => {
       return async () => {
@@ -384,7 +668,7 @@ export class PluginDriver {
 
     const result = await hookFirst(promises, hookFirstNullCheck)
 
-    this.events.emit('plugins:hook:progress:end', { hookName })
+    this.hooks.emit('kubb:plugins:hook:progress:end', { hookName })
 
     return result
   }
@@ -424,7 +708,7 @@ export class PluginDriver {
   }
 
   /**
-   * Runs all plugins in parallel based on `this.plugin` order and `pre`/`post` settings.
+   * Runs all plugins in parallel based on `this.plugin` order and `dependencies` settings.
    */
   async hookParallel<H extends PluginLifecycleHooks, TOutput = void>({
     hookName,
@@ -437,7 +721,7 @@ export class PluginDriver {
     for (const plugin of this.plugins.values()) {
       if (hookName in plugin) plugins.push(plugin)
     }
-    this.events.emit('plugins:hook:progress:start', { hookName, plugins })
+    this.hooks.emit('kubb:plugins:hook:progress:start', { hookName, plugins })
 
     const pluginStartTimes = new Map<Plugin, number>()
 
@@ -461,7 +745,7 @@ export class PluginDriver {
 
         if (plugin) {
           const startTime = pluginStartTimes.get(plugin) ?? performance.now()
-          this.events.emit('error', result.reason, {
+          this.hooks.emit('kubb:error', result.reason, {
             plugin,
             hookName,
             strategy: 'hookParallel',
@@ -472,7 +756,7 @@ export class PluginDriver {
       }
     })
 
-    this.events.emit('plugins:hook:progress:end', { hookName })
+    this.hooks.emit('kubb:plugins:hook:progress:end', { hookName })
 
     return results.reduce((acc, result) => {
       if (result.status === 'fulfilled') {
@@ -483,14 +767,14 @@ export class PluginDriver {
   }
 
   /**
-   * Chains plugins
+   * Execute a lifecycle hook sequentially for all plugins that implement it.
    */
   async hookSeq<H extends PluginLifecycleHooks>({ hookName, parameters }: { hookName: H; parameters?: PluginParameter<H> }): Promise<void> {
     const plugins: Array<Plugin> = []
     for (const plugin of this.plugins.values()) {
       if (hookName in plugin) plugins.push(plugin)
     }
-    this.events.emit('plugins:hook:progress:start', { hookName, plugins })
+    this.hooks.emit('kubb:plugins:hook:progress:start', { hookName, plugins })
 
     const promises = plugins.map((plugin) => {
       return () =>
@@ -504,7 +788,7 @@ export class PluginDriver {
 
     await hookSeq(promises)
 
-    this.events.emit('plugins:hook:progress:end', { hookName })
+    this.hooks.emit('kubb:plugins:hook:progress:end', { hookName })
   }
 
   getPlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
@@ -527,10 +811,7 @@ export class PluginDriver {
   }
 
   /**
-   * 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.
+   * Emit hook-processing completion metadata after a plugin hook resolves.
    */
   #emitProcessingEnd<H extends PluginLifecycleHooks>({
     startTime,
@@ -547,7 +828,7 @@ export class PluginDriver {
     plugin: PluginWithLifeCycle
     parameters: unknown[] | undefined
   }): void {
-    this.events.emit('plugins:hook:processing:end', {
+    this.hooks.emit('kubb:plugins:hook:processing:end', {
       duration: Math.round(performance.now() - startTime),
       parameters,
       output,
@@ -575,7 +856,7 @@ export class PluginDriver {
       return null
     }
 
-    this.events.emit('plugins:hook:processing:start', {
+    this.hooks.emit('kubb:plugins:hook:processing:start', {
       strategy,
       hookName,
       parameters,
@@ -593,7 +874,7 @@ export class PluginDriver {
 
         return output as ReturnType<ParseResult<H>>
       } catch (error) {
-        this.events.emit('error', error as Error, {
+        this.hooks.emit('kubb:error', error as Error, {
           plugin,
           hookName,
           strategy,
@@ -608,10 +889,7 @@ export class PluginDriver {
   }
 
   /**
-   * 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
+   * Execute a plugin lifecycle hook synchronously and return its output.
    */
   #executeSync<H extends PluginLifecycleHooks>({
     strategy,
@@ -630,7 +908,7 @@ export class PluginDriver {
       return null
     }
 
-    this.events.emit('plugins:hook:processing:start', {
+    this.hooks.emit('kubb:plugins:hook:processing:start', {
       strategy,
       hookName,
       parameters,
@@ -649,7 +927,7 @@ export class PluginDriver {
 
       return output
     } catch (error) {
-      this.events.emit('error', error as Error, {
+      this.hooks.emit('kubb:error', error as Error, {
         plugin,
         hookName,
         strategy,

package/src/constants.ts

@@ -1,4 +1,4 @@
-import type { FileNode } from '@kubb/ast/types'
+import type { FileNode } from '@kubb/ast'
 
 /**
  * Base URL for the Kubb Studio web app.