@kubb/core 5.0.0-alpha.7 → 5.0.0-alpha.71

package/src/Kubb.ts

@@ -1,37 +1,73 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Strategy } from './PluginDriver.ts'
-import type { Config, Plugin, PluginLifecycleHooks } from './types'
-
-type DebugEvent = {
-  date: Date
-  logs: string[]
-  fileName?: string
-}
-
-type ProgressStartMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  hookName: H
-  plugins: Array<Plugin>
-}
-
-type ProgressStopMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  hookName: H
-}
-
-type ExecutingMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  strategy: Strategy
-  hookName: H
-  plugin: Plugin
-  parameters?: unknown[] | undefined
-  output?: unknown
-}
+import type { AsyncEventEmitter } from '@internals/utils'
+import type { OperationNode, SchemaNode } from '@kubb/ast'
+import type { BuildOutput } from './createKubb.ts'
+import type { PluginDriver } from './PluginDriver.ts'
+import type {
+  Config,
+  GeneratorContext,
+  KubbBuildEndContext,
+  KubbBuildStartContext,
+  KubbConfigEndContext,
+  KubbDebugContext,
+  KubbErrorContext,
+  KubbFileProcessingUpdateContext,
+  KubbFilesProcessingEndContext,
+  KubbFilesProcessingStartContext,
+  KubbGenerationEndContext,
+  KubbGenerationStartContext,
+  KubbGenerationSummaryContext,
+  KubbHookEndContext,
+  KubbHookStartContext,
+  KubbInfoContext,
+  KubbLifecycleStartContext,
+  KubbPluginEndContext,
+  KubbPluginSetupContext,
+  KubbPluginStartContext,
+  KubbPluginsEndContext,
+  KubbSuccessContext,
+  KubbVersionNewContext,
+  KubbWarnContext,
+} from './types'
 
-type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  duration: number
-  strategy: Strategy
-  hookName: H
-  plugin: Plugin
-  parameters?: unknown[] | undefined
-  output?: unknown
+/**
+ * The instance returned by {@link createKubb}.
+ */
+export type Kubb = {
+  /**
+   * The shared event emitter. Attach listeners here before calling `setup()` or `build()`.
+   */
+  readonly hooks: AsyncEventEmitter<KubbHooks>
+  /**
+   * Raw generated source, keyed by absolute file path.
+   * Populated after a successful `build()` or `safeBuild()` call.
+   */
+  readonly sources: Map<string, string>
+  /**
+   * The plugin driver. Available after `setup()` has been called.
+   */
+  readonly driver: PluginDriver | undefined
+  /**
+   * The resolved config with applied defaults. Available after `setup()` has been called.
+   */
+  readonly config: Config | undefined
+  /**
+   * Initializes all Kubb infrastructure: validates input, applies config defaults,
+   * runs the adapter, and creates the PluginDriver.
+   *
+   * Calling `build()` or `safeBuild()` without calling `setup()` first will
+   * automatically invoke `setup()` before proceeding.
+   */
+  setup(): Promise<void>
+  /**
+   * Runs a full Kubb build and throws on any error or plugin failure.
+   * Automatically calls `setup()` if it has not been called yet.
+   */
+  build(): Promise<BuildOutput>
+  /**
+   * Runs a full Kubb build and captures errors instead of throwing.
+   * Automatically calls `setup()` if it has not been called yet.
+   */
+  safeBuild(): Promise<BuildOutput>
 }
 
 /**
@@ -40,213 +76,252 @@ type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
  *
  * @example
  * ```typescript
- * import type { AsyncEventEmitter } from '@kubb/core'
- * import type { KubbEvents } from '@kubb/core'
+ * import type { AsyncEventEmitter } from '@internals/utils'
+ * import type { KubbHooks } from '@kubb/core'
  *
- * const events: AsyncEventEmitter<KubbEvents> = new AsyncEventEmitter()
+ * const hooks: AsyncEventEmitter<KubbHooks> = new AsyncEventEmitter()
  *
- * events.on('lifecycle:start', () => {
+ * hooks.on('kubb:lifecycle:start', () => {
  *   console.log('Starting Kubb generation')
  * })
  *
- * events.on('plugin:end', (plugin, { duration }) => {
+ * hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
  *   console.log(`Plugin ${plugin.name} completed in ${duration}ms`)
  * })
  * ```
  */
-export interface KubbEvents {
+export interface KubbHooks {
   /**
    * Emitted at the beginning of the Kubb lifecycle, before any code generation starts.
    */
-  'lifecycle:start': [version: string]
-
+  'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext]
   /**
    * Emitted at the end of the Kubb lifecycle, after all code generation is complete.
    */
-  'lifecycle:end': []
+  'kubb:lifecycle:end': []
 
   /**
    * Emitted when configuration loading starts.
    */
-  'config:start': []
-
+  'kubb:config:start': []
   /**
    * Emitted when configuration loading is complete.
    */
-  'config:end': [configs: Array<Config>]
+  'kubb:config:end': [ctx: KubbConfigEndContext]
 
   /**
    * Emitted when code generation phase starts.
    */
-  'generation:start': [config: Config]
-
+  'kubb:generation:start': [ctx: KubbGenerationStartContext]
   /**
    * Emitted when code generation phase completes.
    */
-  'generation:end': [Config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>]
-
+  'kubb:generation:end': [ctx: KubbGenerationEndContext]
   /**
    * Emitted with a summary of the generation results.
    * Contains summary lines, title, and success status.
    */
-  'generation:summary': [
-    Config: Config,
-    {
-      failedPlugins: Set<{ plugin: Plugin; error: Error }>
-      status: 'success' | 'failed'
-      hrStart: [number, number]
-      filesCreated: number
-      pluginTimings?: Map<string, number>
-    },
-  ]
+  'kubb:generation:summary': [ctx: KubbGenerationSummaryContext]
 
   /**
    * Emitted when code formatting starts (e.g., running Biome or Prettier).
    */
-  'format:start': []
-
+  'kubb:format:start': []
   /**
    * Emitted when code formatting completes.
    */
-  'format:end': []
+  'kubb:format:end': []
 
   /**
    * Emitted when linting starts.
    */
-  'lint:start': []
-
+  'kubb:lint:start': []
   /**
    * Emitted when linting completes.
    */
-  'lint:end': []
+  'kubb:lint:end': []
 
   /**
    * Emitted when plugin hooks execution starts.
    */
-  'hooks:start': []
-
+  'kubb:hooks:start': []
   /**
    * Emitted when plugin hooks execution completes.
    */
-  'hooks:end': []
+  'kubb:hooks:end': []
 
   /**
-   * Emitted when a single hook execution starts. (e.g., format or lint).
+   * Emitted when a single hook execution starts (e.g., format or lint).
    * The callback should be invoked when the command completes.
    */
-  'hook:start': [{ id?: string; command: string; args?: readonly string[] }]
+  'kubb:hook:start': [ctx: KubbHookStartContext]
   /**
    * Emitted when a single hook execution completes.
    */
-  'hook:end': [
-    {
-      id?: string
-      command: string
-      args?: readonly string[]
-      success: boolean
-      error: Error | null
-    },
-  ]
+  'kubb:hook:end': [ctx: KubbHookEndContext]
 
   /**
    * Emitted when a new version of Kubb is available.
    */
-  'version:new': [currentVersion: string, latestVersion: string]
+  'kubb:version:new': [ctx: KubbVersionNewContext]
 
   /**
    * Informational message event.
    */
-  info: [message: string, info?: string]
-
+  'kubb:info': [ctx: KubbInfoContext]
   /**
    * Error event. Emitted when an error occurs during code generation.
    */
-  error: [error: Error, meta?: Record<string, unknown>]
-
+  'kubb:error': [ctx: KubbErrorContext]
   /**
    * Success message event.
    */
-  success: [message: string, info?: string]
-
+  'kubb:success': [ctx: KubbSuccessContext]
   /**
    * Warning message event.
    */
-  warn: [message: string, info?: string]
-
+  'kubb:warn': [ctx: KubbWarnContext]
   /**
    * Debug event for detailed logging.
    * Contains timestamp, log messages, and optional filename.
    */
-  debug: [meta: DebugEvent]
+  'kubb:debug': [ctx: KubbDebugContext]
 
   /**
    * Emitted when file processing starts.
    * Contains the list of files to be processed.
    */
-  'files:processing:start': [files: Array<KubbFile.ResolvedFile>]
-
+  'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext]
   /**
    * Emitted for each file being processed, providing progress updates.
    * Contains processed count, total count, percentage, and file details.
    */
-  'file:processing:update': [
-    {
-      /** Number of files processed so far */
-      processed: number
-      /** Total number of files to process */
-      total: number
-      /** Processing percentage (0-100) */
-      percentage: number
-      /** Optional source identifier */
-      source?: string
-      /** The file being processed */
-      file: KubbFile.ResolvedFile
-      /**
-       * Kubb configuration (not present in Fabric).
-       * Provides access to the current config during file processing.
-       */
-      config: Config
-    },
-  ]
-
+  'kubb:file:processing:update': [ctx: KubbFileProcessingUpdateContext]
   /**
    * Emitted when file processing completes.
    * Contains the list of processed files.
    */
-  'files:processing:end': [files: KubbFile.ResolvedFile[]]
+  'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext]
 
   /**
    * Emitted when a plugin starts executing.
    */
-  'plugin:start': [plugin: Plugin]
-
+  'kubb:plugin:start': [ctx: KubbPluginStartContext]
   /**
    * Emitted when a plugin completes execution.
-   * Duration in ms
+   * Duration in ms.
    */
-  'plugin:end': [plugin: Plugin, meta: { duration: number; success: boolean; error?: Error }]
+  'kubb:plugin:end': [ctx: KubbPluginEndContext]
 
   /**
-   * Emitted when plugin hook progress tracking starts.
-   * Contains the hook name and list of plugins to execute.
+   * Fired once — before any plugin's `buildStart` runs — so that hook-style plugins
+   * can register generators, configure resolvers/transformers/renderers, or inject
+   * extra files.  All `kubb:plugin:setup` handlers registered via `definePlugin` receive
+   * a plugin-specific context (with the correct `addGenerator` closure).
+   * External tooling can observe this event via `hooks.on('kubb:plugin:setup', …)`.
    */
-  'plugins:hook:progress:start': [meta: ProgressStartMeta]
-
+  'kubb:plugin:setup': [ctx: KubbPluginSetupContext]
   /**
-   * Emitted when plugin hook progress tracking ends.
-   * Contains the hook name that completed.
+   * Fired immediately before the plugin execution loop begins.
+   * The adapter has already parsed the source and `inputNode` is available.
    */
-  'plugins:hook:progress:end': [meta: ProgressStopMeta]
-
+  'kubb:build:start': [ctx: KubbBuildStartContext]
   /**
-   * Emitted when a plugin hook starts processing.
-   * Contains strategy, hook name, plugin, parameters, and output.
+   * Fired after all plugins have run and all per-plugin barrels have been generated,
+   * but BEFORE files are written to disk.
+   * Use this event to inject final files (e.g. a root barrel) that must be persisted
+   * in the same write pass as the plugin output.
    */
-  'plugins:hook:processing:start': [meta: ExecutingMeta]
+  'kubb:plugins:end': [ctx: KubbPluginsEndContext]
+  /**
+   * Fired after all files have been written to disk.
+   */
+  'kubb:build:end': [ctx: KubbBuildEndContext]
 
   /**
-   * Emitted when a plugin hook completes processing.
-   * Contains duration, strategy, hook name, plugin, parameters, and output.
+   * Emitted for each schema node during the AST walk.
+   * Generator listeners registered via `addGenerator()` in `kubb:plugin:setup` respond to this event.
+   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
+   * `ctx.options` carries the per-node resolved options (after exclude/include/override).
    */
-  'plugins:hook:processing:end': [meta: ExecutedMeta]
+  'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext]
+  /**
+   * Emitted for each operation node during the AST walk.
+   * Generator listeners registered via `addGenerator()` in `kubb:plugin:setup` respond to this event.
+   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
+   * `ctx.options` carries the per-node resolved options (after exclude/include/override).
+   */
+  'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext]
+  /**
+   * Emitted once after all operations have been walked, with the full collected array.
+   * Generator listeners with an `operations()` method respond to this event.
+   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
+   * `ctx.options` carries the plugin-level resolved options for the batch call.
+   */
+  'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext]
+}
+
+declare global {
+  namespace Kubb {
+    /**
+     * Registry that maps plugin names to their `PluginFactoryOptions`.
+     * Augment this interface in each plugin's `types.ts` to enable automatic
+     * typing for `getPlugin` and `requirePlugin`.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-ts/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginRegistry {
+     *       'plugin-ts': PluginTs
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginRegistry {}
+
+    /**
+     * Extension point for root `Config['output']` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the global output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface ConfigOptionsRegistry {
+     *       output: {
+     *         barrelType?: import('./types.ts').BarrelType | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface ConfigOptionsRegistry {}
+
+    /**
+     * Extension point for per-plugin `Output` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the per-plugin output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginOptionsRegistry {
+     *       output: {
+     *         barrelType?: import('./types.ts').BarrelType | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginOptionsRegistry {}
+  }
 }