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

package/src/defineGenerator.ts

@@ -1,121 +1,94 @@
 import type { PossiblePromise } from '@internals/utils'
-import type { FileNode, OperationNode, SchemaNode } from '@kubb/ast/types'
-import type { KubbReactNode } from '@kubb/renderer-jsx/types'
-import { applyHookResult } from './renderNode.tsx'
+import type { FileNode, OperationNode, SchemaNode } from '@kubb/ast'
+import type { RendererFactory } from './createRenderer.ts'
 import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
 
 export type { GeneratorContext } from './types.ts'
 
 /**
  * A generator is a named object with optional `schema`, `operation`, and `operations`
- * methods. Each method is called with `this = PluginContext` of the parent plugin,
- * giving full access to `this.config`, `this.resolver`, `this.adapter`,
- * `this.driver`, etc.
+ * methods. Each method receives the AST node as the first argument and a typed
+ * `ctx` object as the second, giving access to `ctx.config`, `ctx.resolver`,
+ * `ctx.adapter`, `ctx.options`, `ctx.upsertFile`, etc.
  *
- * Return a React element, an array of `FileNode`, or `void` to handle file
- * writing manually via `this.upsertFile`. Both React and core (non-React) generators
- * use the same method signatures — the return type determines how output is handled.
+ * Generators that return renderer elements (e.g. JSX) must declare a `renderer`
+ * factory so that core knows how to process the output without coupling core
+ * to any specific renderer package.
+ *
+ * Return a renderer element, an array of `FileNode`, or `void` to handle file
+ * writing manually via `ctx.upsertFile`.
  *
  * @example
  * ```ts
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
  * export const typeGenerator = defineGenerator<PluginTs>({
  *   name: 'typescript',
- *   schema(node, options) {
- *     const { adapter, resolver, root } = this
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     const { adapter, resolver, root, options } = ctx
  *     return <File ...><Type node={node} resolver={resolver} /></File>
  *   },
- *   operation(node, options) {
+ *   operation(node, ctx) {
+ *     const { options } = ctx
  *     return <File ...><OperationType node={node} /></File>
  *   },
  * })
  * ```
  */
-export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  /** Used in diagnostic messages and debug output. */
+export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
+  /**
+   * Used in diagnostic messages and debug output.
+   */
   name: string
+  /**
+   * Optional renderer factory that produces a {@link Renderer} for each render cycle.
+   *
+   * Generators that return renderer elements (e.g. JSX via `@kubb/renderer-jsx`) must set this
+   * to the matching renderer factory (e.g. `jsxRenderer` from `@kubb/renderer-jsx`).
+   *
+   * Generators that only return `Array<FileNode>` or `void` do not need to set this.
+   *
+   * Set `renderer: null` to explicitly opt out of rendering even when the parent plugin
+   * declares a `renderer` (overrides the plugin-level fallback).
+   *
+   * @example
+   * ```ts
+   * import { jsxRenderer } from '@kubb/renderer-jsx'
+   * export const myGenerator = defineGenerator<PluginTs>({
+   *   renderer: jsxRenderer,
+   *   schema(node, ctx) { return <File ...>...</File> },
+   * })
+   * ```
+   */
+  renderer?: RendererFactory<TElement> | null
   /**
    * Called for each schema node in the AST walk.
-   * `this` is the parent plugin's context with `adapter` and `inputNode` guaranteed present.
-   * `options` contains the per-node resolved options (after exclude/include/override).
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  schema?: (this: GeneratorContext<TOptions>, node: SchemaNode, options: TOptions['resolvedOptions']) => PossiblePromise<KubbReactNode | Array<FileNode> | void>
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
   /**
    * Called for each operation node in the AST walk.
-   * `this` is the parent plugin's context with `adapter` and `inputNode` guaranteed present.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  operation?: (
-    this: GeneratorContext<TOptions>,
-    node: OperationNode,
-    options: TOptions['resolvedOptions'],
-  ) => PossiblePromise<KubbReactNode | Array<FileNode> | void>
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
   /**
    * Called once after all operations have been walked.
-   * `this` is the parent plugin's context with `adapter` and `inputNode` guaranteed present.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the plugin-level options for the batch call.
    */
-  operations?: (
-    this: GeneratorContext<TOptions>,
-    nodes: Array<OperationNode>,
-    options: TOptions['resolvedOptions'],
-  ) => PossiblePromise<KubbReactNode | Array<FileNode> | void>
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
 }
 
 /**
  * Defines a generator. Returns the object as-is with correct `this` typings.
- * No type discrimination (`type: 'react' | 'core'`) needed — `applyHookResult`
- * handles React elements and `File[]` uniformly.
+ * `applyHookResult` handles renderer elements and `File[]` uniformly using
+ * the generator's declared `renderer` factory.
  */
-export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generator: Generator<TOptions>): Generator<TOptions> {
+export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(
+  generator: Generator<TOptions, TElement>,
+): Generator<TOptions, TElement> {
   return generator
 }
-
-/**
- * Merges an array of generators into a single generator.
- *
- * The merged generator's `schema`, `operation`, and `operations` methods run
- * the corresponding method from each input generator in sequence, applying each
- * result via `applyHookResult`. This eliminates the need to write the loop
- * manually in each plugin.
- *
- * @param generators - Array of generators to merge into a single generator.
- *
- * @example
- * ```ts
- * const merged = mergeGenerators(generators)
- *
- * return {
- *   name: pluginName,
- *   schema: merged.schema,
- *   operation: merged.operation,
- *   operations: merged.operations,
- * }
- * ```
- */
-export function mergeGenerators<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generators: Array<Generator<TOptions>>): Generator<TOptions> {
-  return {
-    name: generators.length > 0 ? generators.map((g) => g.name).join('+') : 'merged',
-    async schema(node, options) {
-      for (const gen of generators) {
-        if (!gen.schema) continue
-        const result = await gen.schema.call(this, node, options)
-
-        await applyHookResult(result, this.driver)
-      }
-    },
-    async operation(node, options) {
-      for (const gen of generators) {
-        if (!gen.operation) continue
-        const result = await gen.operation.call(this, node, options)
-
-        await applyHookResult(result, this.driver)
-      }
-    },
-    async operations(nodes, options) {
-      for (const gen of generators) {
-        if (!gen.operations) continue
-        const result = await gen.operations.call(this, nodes, options)
-
-        await applyHookResult(result, this.driver)
-      }
-    },
-  }
-}

package/src/defineLogger.ts

@@ -7,8 +7,8 @@ import type { Logger, LoggerOptions, UserLogger } from './types.ts'
  * export const myLogger = defineLogger({
  *   name: 'my-logger',
  *   install(context, options) {
- *     context.on('info', (message) => console.log('ℹ', message))
- *     context.on('error', (error) => console.error('✗', error.message))
+ *     context.on('kubb:info', (message) => console.log('ℹ', message))
+ *     context.on('kubb:error', (error) => console.error('✗', error.message))
  *   },
  * })
  */

package/src/defineParser.ts

@@ -1,4 +1,4 @@
-import type { FileNode } from '@kubb/ast/types'
+import type { FileNode } from '@kubb/ast'
 
 type PrintOptions = {
   extname?: FileNode['extname']
@@ -10,7 +10,8 @@ export type Parser<TMeta extends object = any> = {
    * File extensions this parser handles.
    * Use `undefined` to create a catch-all fallback parser.
    *
-   * @example ['.ts', '.js']
+   * @example Handled extensions
+   * `['.ts', '.js']`
    */
   extNames: Array<FileNode['extname']> | undefined
   /**

package/src/definePlugin.ts

@@ -0,0 +1,95 @@
+import type { KubbHooks } from './Kubb.ts'
+import type { KubbPluginSetupContext, PluginFactoryOptions } from './types.ts'
+
+/**
+ * Base hook handlers for all events except `kubb:plugin:setup`.
+ * These handlers have identical signatures regardless of the plugin's
+ * `PluginFactoryOptions` generic — they are split out so that the
+ * interface below only needs to override the one event that depends on
+ * the plugin type.
+ */
+type PluginHooksBase = {
+  [K in Exclude<keyof KubbHooks, 'kubb:plugin:setup'>]?: (...args: KubbHooks[K]) => void | Promise<void>
+}
+
+/**
+ * Plugin hook handlers.
+ *
+ * `kubb:plugin:setup` is typed with the plugin's own `PluginFactoryOptions` so
+ * `ctx.setResolver`, `ctx.setOptions`, `ctx.options` etc. use the correct types.
+ *
+ * Uses interface + method shorthand for `kubb:plugin:setup`
+ * checking, allowing `PluginHooks<PluginTs>` to be assignable to `PluginHooks`.
+ *
+ * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ */
+export interface PluginHooks<TFactory extends PluginFactoryOptions = PluginFactoryOptions> extends PluginHooksBase {
+  'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>
+}
+
+/**
+ * A hook-style plugin object produced by `definePlugin`.
+ * Instead of flat lifecycle methods, it groups all handlers under a `hooks:` property
+ * (matching Astro's integration naming convention).
+ *
+ * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ */
+export type HookStylePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Unique name for the plugin, following the same naming convention as `createPlugin`.
+   */
+  name: string
+  /**
+   * Plugins that must be registered before this plugin executes.
+   * An error is thrown at startup when any listed dependency is missing.
+   */
+  dependencies?: Array<string>
+  /**
+   * The options passed by the user when calling the plugin factory.
+   */
+  options?: TFactory['options']
+  /**
+   * Lifecycle event handlers for this plugin.
+   * Any event from the global `KubbHooks` map can be subscribed to here.
+   */
+  hooks: PluginHooks<TFactory>
+}
+
+/**
+ * Returns `true` when `plugin` is a hook-style plugin created with `definePlugin`.
+ *
+ * Used by `PluginDriver` to distinguish hook-style plugins from legacy `createPlugin` plugins
+ * so it can normalize them and register their handlers on the `AsyncEventEmitter`.
+ */
+export function isHookStylePlugin(plugin: unknown): plugin is HookStylePlugin {
+  return typeof plugin === 'object' && plugin !== null && 'hooks' in plugin
+}
+
+/**
+ * Creates a plugin factory using the new hook-style (`hooks:`) API.
+ *
+ * The returned factory is called with optional options and produces a `HookStylePlugin`
+ * that coexists with plugins created via the legacy `createPlugin` API in the same
+ * `kubb.config.ts`.
+ *
+ * Lifecycle handlers are registered on the `PluginDriver`'s `AsyncEventEmitter`, enabling
+ * both the plugin's own handlers and external tooling (CLI, devtools) to observe every event.
+ *
+ * @example
+ * ```ts
+ * // With PluginFactoryOptions (recommended for real plugins)
+ * export const pluginTs = definePlugin<PluginTs>((options) => ({
+ *   name: 'plugin-ts',
+ *   hooks: {
+ *     'kubb:plugin:setup'(ctx) {
+ *       ctx.setResolver(resolverTs)  // typed as Partial<ResolverTs>
+ *     },
+ *   },
+ * }))
+ * ```
+ */
+export function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(
+  factory: (options: TFactory['options']) => HookStylePlugin<TFactory>,
+): (options?: TFactory['options']) => HookStylePlugin<TFactory> {
+  return (options) => factory(options ?? ({} as TFactory['options']))
+}

package/src/defineResolver.ts

@@ -1,7 +1,7 @@
 import path from 'node:path'
 import { camelCase, pascalCase } from '@internals/utils'
+import type { FileNode, InputNode, Node, OperationNode, SchemaNode } from '@kubb/ast'
 import { createFile, isOperationNode, isSchemaNode } from '@kubb/ast'
-import type { FileNode, InputNode, Node, OperationNode, SchemaNode } from '@kubb/ast/types'
 import { getMode } from './PluginDriver.ts'
 import type {
   Config,

package/src/devtools.ts

@@ -1,4 +1,4 @@
-import type { InputNode } from '@kubb/ast/types'
+import type { InputNode } from '@kubb/ast'
 import { deflateSync, inflateSync } from 'fflate'
 import { x } from 'tinyexec'
 import type { DevtoolsOptions } from './types.ts'

package/src/index.ts

@@ -1,15 +1,16 @@
 export { AsyncEventEmitter, URLPath } from '@internals/utils'
+export * as ast from '@kubb/ast'
 export { composeTransformers, definePrinter } from '@kubb/ast'
-export { build, build as default, safeBuild, setup } from './build.ts'
 export { formatters, linters, logLevel } from './constants.ts'
 export { createAdapter } from './createAdapter.ts'
+export { createKubb } from './createKubb.ts'
 export { createPlugin } from './createPlugin.ts'
+export { createRenderer } from './createRenderer.ts'
 export { createStorage } from './createStorage.ts'
-export { defineConfig } from './defineConfig.ts'
-export { defineGenerator, mergeGenerators } from './defineGenerator.ts'
+export { defineGenerator } from './defineGenerator.ts'
 export { defineLogger } from './defineLogger.ts'
 export { defineParser } from './defineParser.ts'
-export { definePresets } from './definePresets.ts'
+export { definePlugin } from './definePlugin.ts'
 export {
   buildDefaultBanner,
   defaultResolveBanner,
@@ -19,6 +20,8 @@ export {
   defaultResolvePath,
   defineResolver,
 } from './defineResolver.ts'
+export { FileManager } from './FileManager.ts'
+export { FileProcessor } from './FileProcessor.ts'
 export { getMode, PluginDriver } from './PluginDriver.ts'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
@@ -26,10 +29,8 @@ export * from './types.ts'
 export type { FunctionParamsAST } from './utils/FunctionParams.ts'
 export { detectFormatter } from './utils/formatters.ts'
 export { getBarrelFiles } from './utils/getBarrelFiles.ts'
-export { getConfigs } from './utils/getConfigs.ts'
 export type { Param, Params } from './utils/getFunctionParams.ts'
 export { createFunctionParams, FunctionParams, getFunctionParams } from './utils/getFunctionParams.ts'
-export { getPreset } from './utils/getPreset.ts'
 export { isInputPath } from './utils/isInputPath.ts'
 export { detectLinter } from './utils/linters.ts'
 export { satisfiesDependency } from './utils/packageJSON.ts'

package/src/mocks.ts

@@ -0,0 +1,234 @@
+import { resolve } from 'node:path'
+import type { FileNode, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
+import { transform } from '@kubb/ast'
+import { FileManager } from './FileManager.ts'
+import { getMode, type PluginDriver } from './PluginDriver.ts'
+import { applyHookResult } from './renderNode.ts'
+import type {
+  Adapter,
+  AdapterFactoryOptions,
+  Config,
+  Generator,
+  GeneratorContext,
+  Plugin,
+  PluginFactoryOptions,
+  ResolveNameParams,
+  ResolvePathParams,
+} from './types.ts'
+
+function toCamelOrPascal(text: string, pascal: boolean): string {
+  const normalized = text
+    .trim()
+    .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/(\d)([a-z])/g, '$1 $2')
+
+  const words = normalized.split(/[\s\-_./\\:]+/).filter(Boolean)
+
+  return words
+    .map((word, i) => {
+      const allUpper = word.length > 1 && word === word.toUpperCase()
+      if (allUpper) return word
+      if (i === 0 && !pascal) return word.charAt(0).toLowerCase() + word.slice(1)
+      return word.charAt(0).toUpperCase() + word.slice(1)
+    })
+    .join('')
+    .replace(/[^a-zA-Z0-9]/g, '')
+}
+
+function camelCase(text: string): string {
+  return toCamelOrPascal(text, false)
+}
+
+function pascalCase(text: string): string {
+  return toCamelOrPascal(text, true)
+}
+
+/**
+ * Creates a minimal `PluginDriver` mock suitable for unit tests.
+ */
+export function createMockedPluginDriver(options: { name?: string; plugin?: Plugin<any>; config?: Config } = {}): PluginDriver {
+  return {
+    resolveName: (result: ResolveNameParams) => {
+      if (result.type === 'file') {
+        return camelCase(options?.name || result.name)
+      }
+
+      if (result.type === 'type') {
+        return pascalCase(result.name)
+      }
+
+      if (result.type === 'function') {
+        return camelCase(result.name)
+      }
+
+      return camelCase(result.name)
+    },
+    config: options?.config ?? {
+      root: '.',
+      output: {
+        path: './path',
+      },
+    },
+    resolvePath: ({ baseName }: ResolvePathParams) => baseName,
+    getFile: ({
+      name,
+      extname,
+      pluginName,
+      options: fileOptions,
+    }: {
+      name: string
+      extname: `.${string}`
+      pluginName: string
+      options?: { group?: { tag?: string; path?: string } }
+    }) => {
+      const baseName = `${name}${extname}`
+      const groupDir = fileOptions?.group?.tag ?? fileOptions?.group?.path?.split('/').filter(Boolean)[0]
+      const filePath = groupDir ? `${groupDir}/${baseName}` : baseName
+
+      return {
+        path: filePath,
+        baseName,
+        meta: { pluginName },
+      }
+    },
+    getPlugin(_pluginName: Plugin['name']): Plugin | undefined {
+      return options?.plugin
+    },
+    fileManager: new FileManager(),
+  } as unknown as PluginDriver
+}
+
+/**
+ * Creates a minimal `Adapter` mock suitable for unit tests.
+ *
+ * - `parse` returns an empty `InputNode` by default; override via `options.parse`.
+ * - `getImports` returns `[]` by default (single-file mode, no cross-file imports).
+ */
+export function createMockedAdapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions>(
+  options: {
+    name?: TOptions['name']
+    resolvedOptions?: TOptions['resolvedOptions']
+    inputNode?: Adapter<TOptions>['inputNode']
+    parse?: Adapter<TOptions>['parse']
+    getImports?: Adapter<TOptions>['getImports']
+  } = {},
+): Adapter<TOptions> {
+  return {
+    name: (options.name ?? 'oas') as TOptions['name'],
+    options: (options.resolvedOptions ?? {}) as TOptions['resolvedOptions'],
+    inputNode: options.inputNode ?? null,
+    parse: options.parse ?? (async () => ({ kind: 'Input' as const, schemas: [], operations: [] })),
+    getImports: options.getImports ?? ((_node: SchemaNode, _resolve: (schemaName: string) => { name: string; path: string }) => []),
+  } as Adapter<TOptions>
+}
+
+/**
+ * Creates a minimal `Plugin` mock suitable for unit tests.
+ *
+ * @example
+ * const plugin = createMockedPlugin<PluginTs>({ name: '@kubb/plugin-ts', options })
+ */
+export function createMockedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(params: {
+  name: TOptions['name']
+  options: TOptions['resolvedOptions']
+  resolver?: TOptions['resolver']
+  transformer?: Visitor
+  dependencies?: Array<string>
+}): Plugin<TOptions> {
+  return {
+    name: params.name,
+    options: params.options,
+    resolver: params.resolver,
+    transformer: params.transformer,
+    dependencies: params.dependencies,
+    install: () => {},
+    inject: () => undefined as TOptions['context'],
+  } as unknown as Plugin<TOptions>
+}
+
+type RenderGeneratorOptions<TOptions extends PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  driver: PluginDriver
+  plugin: Plugin<TOptions>
+  options: TOptions['resolvedOptions']
+  resolver: TOptions['resolver']
+}
+
+function createMockedPluginContext<TOptions extends PluginFactoryOptions>(opts: RenderGeneratorOptions<TOptions>): Omit<GeneratorContext<TOptions>, 'options'> {
+  const root = resolve(opts.config.root, opts.config.output.path)
+
+  return {
+    config: opts.config,
+    root,
+    getMode: (output: { path: string }) => getMode(resolve(root, output.path)),
+    adapter: opts.adapter,
+    resolver: opts.resolver,
+    plugin: opts.plugin,
+    driver: opts.driver,
+    inputNode: { kind: 'Input', schemas: [], operations: [] },
+    upsertFile: async (...files: Array<FileNode>) => opts.driver.fileManager.upsert(...files),
+    warn: (msg: string) => console.warn(msg),
+    error: (msg: string) => console.error(msg),
+    info: (msg: string) => console.info(msg),
+    openInStudio: async () => {},
+  } as unknown as Omit<GeneratorContext<TOptions>, 'options'>
+}
+
+/**
+ * Renders a generator's `schema` method in a test context.
+ *
+ * @example
+ * await renderGeneratorSchema(typeGenerator, node, { config, adapter, driver, plugin, options, resolver })
+ * await matchFiles(driver.fileManager.files)
+ */
+export async function renderGeneratorSchema<TOptions extends PluginFactoryOptions>(
+  generator: Generator<TOptions>,
+  node: SchemaNode,
+  opts: RenderGeneratorOptions<TOptions>,
+): Promise<void> {
+  if (!generator.schema) return
+  const context = createMockedPluginContext(opts)
+  const transformedNode = opts.plugin.transformer ? transform(node, opts.plugin.transformer) : node
+  const result = await generator.schema(transformedNode, { ...context, options: opts.options })
+  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+}
+
+/**
+ * Renders a generator's `operation` method in a test context.
+ *
+ * @example
+ * await renderGeneratorOperation(typeGenerator, node, { config, adapter, driver, plugin, options, resolver })
+ * await matchFiles(driver.fileManager.files)
+ */
+export async function renderGeneratorOperation<TOptions extends PluginFactoryOptions>(
+  generator: Generator<TOptions>,
+  node: OperationNode,
+  opts: RenderGeneratorOptions<TOptions>,
+): Promise<void> {
+  if (!generator.operation) return
+  const context = createMockedPluginContext(opts)
+  const transformedNode = opts.plugin.transformer ? transform(node, opts.plugin.transformer) : node
+  const result = await generator.operation(transformedNode, { ...context, options: opts.options })
+  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+}
+
+/**
+ * Renders a generator's `operations` method in a test context.
+ *
+ * @example
+ * await renderGeneratorOperations(classClientGenerator, nodes, { config, adapter, driver, plugin, options, resolver })
+ * await matchFiles(driver.fileManager.files)
+ */
+export async function renderGeneratorOperations<TOptions extends PluginFactoryOptions>(
+  generator: Generator<TOptions>,
+  nodes: Array<OperationNode>,
+  opts: RenderGeneratorOptions<TOptions>,
+): Promise<void> {
+  if (!generator.operations) return
+  const context = createMockedPluginContext(opts)
+  const transformedNodes = opts.plugin.transformer ? nodes.map((n) => transform(n, opts.plugin.transformer!)) : nodes
+  const result = await generator.operations(transformedNodes, { ...context, options: opts.options })
+  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+}

package/src/renderNode.ts

@@ -0,0 +1,35 @@
+import type { FileNode } from '@kubb/ast'
+import type { RendererFactory } from './createRenderer.ts'
+import type { PluginDriver } from './PluginDriver.ts'
+
+/**
+ * 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
+  }
+
+  if (!rendererFactory) {
+    return
+  }
+
+  const renderer = rendererFactory()
+  await renderer.render(result)
+  driver.fileManager.upsert(...renderer.files)
+  renderer.unmount()
+}