@kubb/core 5.0.0-alpha.29 → 5.0.0-alpha.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.29",
+  "version": "5.0.0-alpha.30",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "typescript",
@@ -71,7 +71,7 @@
     "remeda": "^2.33.7",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "5.0.0-alpha.29"
+    "@kubb/ast": "5.0.0-alpha.30"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/PluginDriver.ts

@@ -101,7 +101,13 @@ export class PluginDriver {
     this.config = config
     this.options = options
     config.plugins
-      .map((plugin) => Object.assign({ install() {} }, plugin) as unknown as Plugin)
+      .map((plugin) => Object.assign({ buildStart() {}, buildEnd() {} }, plugin) as unknown as Plugin)
+      .filter((plugin) => {
+        if (typeof plugin.apply === 'function') {
+          return plugin.apply(config)
+        }
+        return true
+      })
       .sort((a, b) => {
         if (b.pre?.includes(a.name)) return 1
         if (b.post?.includes(a.name)) return -1
@@ -122,9 +128,16 @@ export class PluginDriver {
     const baseContext = {
       fabric: driver.options.fabric,
       config: driver.config,
+      get root(): string {
+        return resolve(driver.config.root, driver.config.output.path)
+      },
+      getMode(output: { path: string }): FabricFile.Mode {
+        return getMode(resolve(driver.config.root, driver.config.output.path, output.path))
+      },
+      events: driver.options.events,
       plugin,
       getPlugin: driver.getPlugin.bind(driver),
-      events: driver.options.events,
+      requirePlugin: driver.requirePlugin.bind(driver),
       driver: driver,
       addFile: async (...files: Array<FabricFile.File>) => {
         await this.options.fabric.addFile(...files)
@@ -144,6 +157,15 @@ export class PluginDriver {
       get transformer() {
         return plugin.transformer
       },
+      warn(message: string) {
+        driver.events.emit('warn', message)
+      },
+      error(error: string | Error) {
+        driver.events.emit('error', typeof error === 'string' ? new Error(error) : error)
+      },
+      info(message: string) {
+        driver.events.emit('info', message)
+      },
       openInStudio(options?: DevtoolsOptions) {
         if (!driver.config.devtools || driver.#studioIsOpen) {
           return
@@ -167,12 +189,9 @@ export class PluginDriver {
 
     const mergedExtras: Record<string, unknown> = {}
 
-    for (const plugin of this.plugins.values()) {
-      if (typeof plugin.inject === 'function') {
-        const result = (plugin.inject as (this: PluginContext, context: PluginContext) => unknown).call(
-          baseContext as unknown as PluginContext,
-          baseContext as unknown as PluginContext,
-        )
+    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)
         }
@@ -482,8 +501,23 @@ export class PluginDriver {
     this.events.emit('plugins:hook:progress:end', { hookName })
   }
 
-  getPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions> | undefined {
-    return this.plugins.get(pluginName) as Plugin<TOptions> | undefined
+  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) as Plugin | undefined
+  }
+
+  /**
+   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
+   */
+  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
   }
 
   /**

package/src/build.ts

@@ -1,5 +1,7 @@
 import { dirname, relative, resolve } from 'node:path'
 import { AsyncEventEmitter, BuildError, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
+import { transform, walk } from '@kubb/ast'
+import type { OperationNode } from '@kubb/ast/types'
 import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
 import { createFabric } from '@kubb/react-fabric'
 import { typescriptParser } from '@kubb/react-fabric/parsers'
@@ -7,10 +9,12 @@ import { fsPlugin } from '@kubb/react-fabric/plugins'
 import { isInputPath } from './config.ts'
 import { BARREL_FILENAME, DEFAULT_BANNER, DEFAULT_CONCURRENCY, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
 import { PluginDriver } from './PluginDriver.ts'
+import { applyHookResult } from './renderNode.tsx'
 import { fsStorage } from './storages/fsStorage.ts'
-import type { AdapterSource, Config, KubbEvents, Output, Plugin, Storage, UserConfig } from './types.ts'
+import type { AdapterSource, Config, KubbEvents, Plugin, PluginContext, Storage, UserConfig } from './types.ts'
 import { getDiagnosticInfo } from './utils/diagnostics.ts'
 import type { FileMetaBase } from './utils/getBarrelFiles.ts'
+import { getBarrelFiles } from './utils/getBarrelFiles.ts'
 
 type BuildOptions = {
   config: UserConfig
@@ -255,6 +259,57 @@ export async function build(options: BuildOptions, overrides?: SetupResult): Pro
   }
 }
 
+/**
+ * Walks the AST and dispatches nodes to a plugin's direct AST hooks
+ * (`schema`, `operation`, `operations`).
+ *
+ * - Each hook accepts a single handler **or an array** — all entries are called in sequence.
+ * - Nodes that are excluded by `exclude`/`include` plugin options are skipped automatically.
+ * - Return values are handled via `applyHookResult`: React elements are rendered,
+ *   `FabricFile.File[]` are written via upsert, and `void` is a no-op (manual handling).
+ * - Barrel files are generated automatically when `output.barrelType` is set.
+ */
+async function runPluginAstHooks(plugin: Plugin, context: PluginContext): Promise<void> {
+  const { adapter, rootNode, resolver, fabric } = context
+  const { exclude, include, override } = plugin.options
+
+  if (!adapter || !rootNode) {
+    throw new Error(`[${plugin.name}] No adapter found. Add an OAS adapter (e.g. pluginOas()) before this plugin in your Kubb config.`)
+  }
+
+  const collectedOperations: Array<OperationNode> = []
+
+  await walk(rootNode, {
+    depth: 'shallow',
+    async schema(node) {
+      if (!plugin.schema) return
+      const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
+      const options = resolver.resolveOptions(transformedNode, { options: plugin.options, exclude, include, override })
+      if (options === null) return
+      const result = await plugin.schema.call(context, transformedNode, options)
+
+      await applyHookResult(result, fabric)
+    },
+    async operation(node) {
+      const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
+      const options = resolver.resolveOptions(transformedNode, { options: plugin.options, exclude, include, override })
+      if (options !== null) {
+        collectedOperations.push(transformedNode)
+        if (plugin.operation) {
+          const result = await plugin.operation.call(context, transformedNode, options)
+          await applyHookResult(result, fabric)
+        }
+      }
+    },
+  })
+
+  if (plugin.operations && collectedOperations.length > 0) {
+    const result = await plugin.operations.call(context, collectedOperations, plugin.options)
+
+    await applyHookResult(result, fabric)
+  }
+}
+
 /**
  * Runs a full Kubb build and captures errors instead of throwing.
  *
@@ -277,8 +332,8 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
     for (const plugin of driver.plugins.values()) {
       const context = driver.getContext(plugin)
       const hrStart = process.hrtime()
-
-      const installer = plugin.install.bind(context)
+      const { output } = plugin.options ?? {}
+      const root = resolve(config.root, config.output.path)
 
       try {
         const timestamp = new Date()
@@ -287,10 +342,26 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 
         await events.emit('debug', {
           date: timestamp,
-          logs: ['Installing plugin...', `  • Plugin Name: ${plugin.name}`],
+          logs: ['Starting plugin...', `  • Plugin Name: ${plugin.name}`],
         })
 
-        await installer(context)
+        // Call buildStart() for any custom plugin logic
+        await plugin.buildStart.call(context)
+
+        // Dispatch schema/operation/operations hooks (direct hooks or composed via composeGenerators)
+        if (plugin.schema || plugin.operation || plugin.operations) {
+          await runPluginAstHooks(plugin, context)
+        }
+
+        if (output) {
+          const barrelFiles = await getBarrelFiles(fabric.files, {
+            type: output.barrelType ?? 'named',
+            root,
+            output,
+            meta: { pluginName: plugin.name },
+          })
+          await context.upsertFile(...barrelFiles)
+        }
 
         const duration = getElapsedMs(hrStart)
         pluginTimings.set(plugin.name, duration)
@@ -299,7 +370,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 
         await events.emit('debug', {
           date: new Date(),
-          logs: [`✓ Plugin installed successfully (${formatMs(duration)})`],
+          logs: [`✓ Plugin started successfully (${formatMs(duration)})`],
         })
       } catch (caughtError) {
         const error = caughtError as Error
@@ -315,7 +386,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
         await events.emit('debug', {
           date: errorTimestamp,
           logs: [
-            '✗ Plugin installation failed',
+            '✗ Plugin start failed',
             `  • Plugin Name: ${plugin.name}`,
             `  • Error: ${error.constructor.name} - ${error.message}`,
             '  • Stack Trace:',
@@ -372,6 +443,14 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 
     await fabric.write({ extension: config.output.extension })
 
+    // Call buildEnd() on each plugin after all files are written
+    for (const plugin of driver.plugins.values()) {
+      if (plugin.buildEnd) {
+        const context = driver.getContext(plugin)
+        await plugin.buildEnd.call(context)
+      }
+    }
+
     return {
       failedPlugins,
       fabric,
@@ -417,7 +496,7 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, dri
 
       const meta = file.meta as FileMetaBase | undefined
       const plugin = meta?.pluginName ? pluginNameMap.get(meta.pluginName) : undefined
-      const pluginOptions = plugin?.options as { output?: Output<unknown> } | undefined
+      const pluginOptions = plugin?.options
 
       if (!pluginOptions || pluginOptions.output?.barrelType === false) {
         return []

package/src/createPlugin.ts

@@ -9,10 +9,11 @@ type PluginBuilder<T extends PluginFactoryOptions = PluginFactoryOptions> = (opt
  * Creates a plugin factory. Call the returned function with optional options to get the plugin instance.
  *
  * @example
+ * ```ts
  * export const myPlugin = createPlugin<MyPlugin>((options) => {
  *   return {
  *     name: 'my-plugin',
- *     options,
+ *     get options() { return options },
  *     resolvePath(baseName) { ... },
  *     resolveName(name, type) { ... },
  *   }
@@ -20,6 +21,7 @@ type PluginBuilder<T extends PluginFactoryOptions = PluginFactoryOptions> = (opt
  *
  * // instantiate
  * const plugin = myPlugin({ output: { path: 'src/gen' } })
+ * ```
  */
 export function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(
   build: PluginBuilder<T>,

package/src/defineGenerator.ts

@@ -1,159 +1,126 @@
+import type { PossiblePromise } from '@internals/utils'
 import type { OperationNode, SchemaNode } from '@kubb/ast/types'
 import type { FabricFile } from '@kubb/fabric-core/types'
 import type { FabricReactNode } from '@kubb/react-fabric/types'
-import type { PluginDriver } from './PluginDriver.ts'
-import type { Adapter, Config, Plugin, PluginFactoryOptions } from './types.ts'
+import { applyHookResult } from './renderNode.tsx'
+import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
 
-export type Version = '1' | '2'
+export type { GeneratorContext } from './types.ts'
 
 /**
- * Props for the `operations` lifecycle — receives all operation nodes at once.
- */
-export type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  plugin: Plugin<TPlugin>
-  adapter: Adapter
-  driver: PluginDriver
-  options: Plugin<TPlugin>['options']
-  resolver: TPlugin['resolver']
-  nodes: Array<OperationNode>
-}
-
-/**
- * Props for the `operation` lifecycle — receives a single operation node.
- */
-export type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  adapter: Adapter
-  driver: PluginDriver
-  plugin: Plugin<TPlugin>
-  options: Plugin<TPlugin>['options']
-  resolver: TPlugin['resolver']
-  node: OperationNode
-}
-
-/**
- * Props for the `schema` lifecycle — receives a single schema node.
- */
-export type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  adapter: Adapter
-  driver: PluginDriver
-  plugin: Plugin<TPlugin>
-  options: Plugin<TPlugin>['options']
-  resolver: TPlugin['resolver']
-  node: SchemaNode
-}
-
-/**
- * Input shape for a core v2 async generator — lifecycle methods are optional.
- */
-type UserCoreGeneratorV2<TPlugin extends PluginFactoryOptions> = {
-  name: string
-  type: 'core'
-  version?: '2'
-  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<FabricFile.File>>
-  operation?(props: OperationV2Props<TPlugin>): Promise<Array<FabricFile.File>>
-  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<FabricFile.File>>
-}
-
-/**
- * Input shape for a React v2 generator — component methods are optional.
- */
-type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
-  name: string
-  type: 'react'
-  version?: '2'
-  Operations?(props: OperationsV2Props<TPlugin>): FabricReactNode
-  Operation?(props: OperationV2Props<TPlugin>): FabricReactNode
-  Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode
-}
-
-/**
- * A fully resolved core v2 generator with `version: '2'` and guaranteed async lifecycle methods.
+ * 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.fabric`,
+ * `this.driver`, etc.
+ *
+ * Return a React element, an array of `FabricFile.File`, 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.
+ *
+ * @example
+ * ```ts
+ * export const typeGenerator = defineGenerator<PluginTs>({
+ *   name: 'typescript',
+ *   schema(node, options) {
+ *     const { adapter, resolver, root } = this
+ *     return <File ...><Type node={node} resolver={resolver} /></File>
+ *   },
+ *   operation(node, options) {
+ *     return <File ...><OperationType node={node} /></File>
+ *   },
+ * })
+ * ```
  */
-export type CoreGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /** Used in diagnostic messages and debug output. */
   name: string
-  type: 'core'
-  version: '2'
-  operations(props: OperationsV2Props<TPlugin>): Promise<Array<FabricFile.File>>
-  operation(props: OperationV2Props<TPlugin>): Promise<Array<FabricFile.File>>
-  schema(props: SchemaV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  /**
+   * Called for each schema node in the AST walk.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   * `options` contains the per-node resolved options (after exclude/include/override).
+   */
+  schema?: (
+    this: GeneratorContext<TOptions>,
+    node: SchemaNode,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+  /**
+   * Called for each operation node in the AST walk.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   */
+  operation?: (
+    this: GeneratorContext<TOptions>,
+    node: OperationNode,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+  /**
+   * Called once after all operations have been walked.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   */
+  operations?: (
+    this: GeneratorContext<TOptions>,
+    nodes: Array<OperationNode>,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
 }
 
 /**
- * A fully resolved React v2 generator with `version: '2'` and guaranteed component methods.
+ * 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.
  */
-export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  name: string
-  type: 'react'
-  version: '2'
-  Operations(props: OperationsV2Props<TPlugin>): FabricReactNode
-  Operation(props: OperationV2Props<TPlugin>): FabricReactNode
-  Schema(props: SchemaV2Props<TPlugin>): FabricReactNode
+export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generator: Generator<TOptions>): Generator<TOptions> {
+  return generator
 }
 
 /**
- * Union of all v2 generator shapes accepted by the plugin system.
- */
-export type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>
-
-/**
- * Defines a generator with no-op defaults for any omitted lifecycle methods.
- * Works for both `core` (async file output) and `react` (JSX component) generators.
+ * Merges an array of generators into a single generator.
  *
- * @example
- * // react generator
- * export const typeGenerator = defineGenerator<PluginTs>({
- *   name: 'typescript',
- *   type: 'react',
- *   Operation({ node, options }) { return <File>...</File> },
- *   Schema({ node, options }) { return <File>...</File> },
- * })
+ * 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
- * // core generator
- * export const myGenerator = defineGenerator<MyPlugin>({
- *   name: 'my-generator',
- *   type: 'core',
- *   async operation({ node, options }) { return [{ path: '...', content: '...' }] },
- * })
+ * ```ts
+ * const merged = mergeGenerators(generators)
+ *
+ * return {
+ *   name: pluginName,
+ *   schema: merged.schema,
+ *   operation: merged.operation,
+ *   operations: merged.operations,
+ * }
+ * ```
  */
-export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
-  generator: UserReactGeneratorV2<TPlugin>,
-): ReactGeneratorV2<TPlugin>
-
-export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserCoreGeneratorV2<TPlugin>): CoreGeneratorV2<TPlugin>
-export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
-  generator: UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>,
-): unknown {
-  if (generator.type === 'react') {
-    return {
-      version: '2',
-      Operations() {
-        return null
-      },
-      Operation() {
-        return null
-      },
-      Schema() {
-        return null
-      },
-      ...generator,
-    }
-  }
-
+export function mergeGenerators<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generators: Array<Generator<TOptions>>): Generator<TOptions> {
   return {
-    version: '2',
-    async operations() {
-      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.fabric)
+      }
     },
-    async operation() {
-      return []
+    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.fabric)
+      }
     },
-    async schema() {
-      return []
+    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.fabric)
+      }
     },
-    ...generator,
   }
 }

package/src/index.ts

@@ -6,7 +6,7 @@ export { formatters, linters, logLevel } from './constants.ts'
 export { createAdapter } from './createAdapter.ts'
 export { createPlugin } from './createPlugin.ts'
 export { createStorage } from './createStorage.ts'
-export { defineGenerator } from './defineGenerator.ts'
+export { defineGenerator, mergeGenerators } from './defineGenerator.ts'
 export { defineLogger } from './defineLogger.ts'
 export { definePresets } from './definePresets.ts'
 export {
@@ -19,7 +19,6 @@ export {
   defineResolver,
 } from './defineResolver.ts'
 export { getMode, PluginDriver } from './PluginDriver.ts'
-export { renderOperation, renderOperations, renderSchema, runGeneratorOperation, runGeneratorOperations, runGeneratorSchema } from './renderNode.tsx'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'