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

package/src/createRenderer.ts

@@ -0,0 +1,57 @@
+import type { FileNode } from '@kubb/ast'
+
+/**
+ * Minimal interface any Kubb renderer must satisfy.
+ *
+ * The generic `TElement` is the type of the element the renderer accepts —
+ * e.g. `KubbReactElement` for `@kubb/renderer-jsx`, or a custom type for
+ * your own renderer.  Defaults to `unknown` so that generators which do not
+ * care about the element type continue to work without specifying it.
+ *
+ * This allows core to drive rendering without a hard dependency on
+ * `@kubb/renderer-jsx` or any specific renderer implementation.
+ */
+export type Renderer<TElement = unknown> = {
+  render(element: TElement): Promise<void>
+  unmount(error?: Error | number | null): void
+  readonly files: Array<FileNode>
+}
+
+/**
+ * A factory function that produces a fresh {@link Renderer} per render.
+ *
+ * Generators use this to declare which renderer handles their output.
+ */
+export type RendererFactory<TElement = unknown> = () => Renderer<TElement>
+
+/**
+ * Creates a renderer factory for use in generator definitions.
+ *
+ * Wrap your renderer factory function with this helper to register it as the
+ * renderer for a generator. Core will call this factory once per render cycle
+ * to obtain a fresh renderer instance.
+ *
+ * @example
+ * ```ts
+ * // packages/renderer-jsx/src/index.ts
+ * export const jsxRenderer = createRenderer(() => {
+ *   const runtime = new Runtime()
+ *   return {
+ *     async render(element) { await runtime.render(element) },
+ *     get files() { return runtime.nodes },
+ *     unmount(error) { runtime.unmount(error) },
+ *   }
+ * })
+ *
+ * // packages/plugin-zod/src/generators/zodGenerator.tsx
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ * export const zodGenerator = defineGenerator<PluginZod>({
+ *   name: 'zod',
+ *   renderer: jsxRenderer,
+ *   schema(node, options) { return <File ...>...</File> },
+ * })
+ * ```
+ */
+export function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement> {
+  return factory
+}

package/src/createStorage.ts

@@ -34,9 +34,17 @@ export type Storage = {
 }
 
 /**
- * Creates a storage factory. Call the returned function with optional options to get the storage instance.
+ * Factory for implementing custom storage backends that control where generated files are written.
+ *
+ * Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
+ * Kubb provides filesystem and in-memory implementations out of the box.
+ *
+ * @note Call the returned factory with optional options to instantiate the storage adapter.
  *
  * @example
+ * ```ts
+ * import { createStorage } from '@kubb/core'
+ *
  * export const memoryStorage = createStorage(() => {
  *   const store = new Map<string, string>()
  *   return {
@@ -52,6 +60,10 @@ export type Storage = {
  *     async clear(base) { if (!base) store.clear() },
  *   }
  * })
+ *
+ * // Instantiate:
+ * const storage = memoryStorage()
+ * ```
  */
 export function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage {
   return (options) => build(options ?? ({} as TOptions))

package/src/defineGenerator.ts

@@ -1,134 +1,175 @@
-import type { OperationNode, SchemaNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { FabricReactNode } from '@kubb/react-fabric/types'
-import type { Adapter, Config, Plugin, PluginFactoryOptions } from './types.ts'
-
-export type Version = '1' | '2'
-
-/**
- * Props for the `operations` lifecycle — receives all operation nodes at once.
- */
-export type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  adapter: Adapter
-  options: Plugin<TPlugin>['options']
-  nodes: Array<OperationNode>
-}
+import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
+import type { FileNode, InputNode, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
+import type { Adapter } from './createAdapter.ts'
+import type { RendererFactory } from './createRenderer.ts'
+import type { KubbHooks } from './types.ts'
+import type { PluginDriver } from './PluginDriver.ts'
+import type { Plugin, PluginFactoryOptions } from './definePlugin.ts'
+import type { Resolver } from './defineResolver.ts'
+import type { Config, DevtoolsOptions } from './types.ts'
 
 /**
- * Props for the `operation` lifecycle — receives a single operation node.
- */
-export type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  adapter: Adapter
-  options: Plugin<TPlugin>['options']
-  node: OperationNode
-}
-
-/**
- * Props for the `schema` lifecycle — receives a single schema node.
+ * Context object passed to generator `schema`, `operation`, and `operations` methods.
+ *
+ * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
+ * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
+ * filtering for individual schema/operation calls, or plugin-level options for operations.
  */
-export type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   config: Config
+  /**
+   * Absolute path to the current plugin's output directory.
+   */
+  root: string
+  /**
+   * Determine output mode based on the output config.
+   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
+   */
+  getMode: (output: { path: string }) => 'single' | 'split'
+  driver: PluginDriver
+  /**
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
+  getPlugin(name: string): Plugin | undefined
+  /**
+   * Get a plugin by name, throws an error if not found.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>
+  requirePlugin(name: string): Plugin
+  /**
+   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver']
+  getResolver(name: string): Resolver
+  /**
+   * Add files only if they don't exist.
+   */
+  addFile: (...file: Array<FileNode>) => Promise<void>
+  /**
+   * Merge sources into the same output file.
+   */
+  upsertFile: (...file: Array<FileNode>) => Promise<void>
+  hooks: AsyncEventEmitter<KubbHooks>
+  /**
+   * The current plugin instance.
+   */
+  plugin: Plugin<TOptions>
+  /**
+   * The current plugin's resolver.
+   */
+  resolver: TOptions['resolver']
+  /**
+   * The current plugin's transformer.
+   */
+  transformer: Visitor | undefined
+  /**
+   * Emit a warning.
+   */
+  warn: (message: string) => void
+  /**
+   * Emit an error.
+   */
+  error: (error: string | Error) => void
+  /**
+   * Emit an info message.
+   */
+  info: (message: string) => void
+  /**
+   * Open the current input node in Kubb Studio.
+   */
+  openInStudio: (options?: DevtoolsOptions) => Promise<void>
+  /**
+   * The configured adapter instance.
+   */
   adapter: Adapter
-  options: Plugin<TPlugin>['options']
-  node: SchemaNode
-}
-
-type UserCoreGeneratorV2<TPlugin extends PluginFactoryOptions> = {
-  name: string
-  type: 'core'
-  version?: '2'
-  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  operation?(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-}
-
-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
-}
-
-export type CoreGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  name: string
-  type: 'core'
-  version: '2'
-  operations(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  operation(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  schema(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-}
-
-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
+  /**
+   * The universal `InputNode` produced by the adapter.
+   */
+  inputNode: InputNode
+  /**
+   * Resolved options after exclude/include/override filtering.
+   */
+  options: TOptions['resolvedOptions']
 }
 
-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.
+ * Declares a named generator unit that walks the AST and emits files.
  *
- * @example
- * // react generator
- * export const typeGenerator = defineGenerator<PluginTs>({
- *   name: 'typescript',
- *   type: 'react',
- *   Operation({ node, options }) { return <File>...</File> },
- *   Schema({ node, options }) { return <File>...</File> },
- * })
+ * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
+ * Each method returns `TElement | Array<FileNode> | void`. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `void` to bypass rendering.
+ *
+ * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
  * @example
- * // core generator
- * export const myGenerator = defineGenerator<MyPlugin>({
- *   name: 'my-generator',
- *   type: 'core',
- *   async operation({ node, options }) { return [{ path: '...', content: '...' }] },
+ * ```ts
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     const { adapter, resolver, root, options } = ctx
+ *     return <File ...><Type node={node} resolver={resolver} /></File>
+ *   },
  * })
+ * ```
  */
-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 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.
+   * `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?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  /**
+   * Called for each operation node in the AST walk.
+   * `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?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  /**
+   * Called once after all operations have been walked.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the plugin-level options for the batch call.
+   */
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+}
 
-  return {
-    version: '2',
-    async operations() {
-      return []
-    },
-    async operation() {
-      return []
-    },
-    async schema() {
-      return []
-    },
-    ...generator,
-  }
+/**
+ * Defines a generator. Returns the object as-is with correct `this` typings.
+ * `applyHookResult` handles renderer elements and `File[]` uniformly using
+ * the generator's declared `renderer` factory.
+ */
+export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(
+  generator: Generator<TOptions, TElement>,
+): Generator<TOptions, TElement> {
+  return generator
 }

package/src/defineLogger.ts

@@ -1,17 +1,58 @@
-import type { Logger, LoggerOptions, UserLogger } from './types.ts'
+import type { AsyncEventEmitter } from '@internals/utils'
+import type { logLevel } from './constants.ts'
+import type { KubbHooks } from './types.ts'
+
+export type LoggerOptions = {
+  /**
+   * Log level for output verbosity.
+   * @default 3
+   */
+  logLevel: (typeof logLevel)[keyof typeof logLevel]
+}
+
+/**
+ * Shared context passed to plugins, parsers, and other internals.
+ */
+export type LoggerContext = AsyncEventEmitter<KubbHooks>
+
+export type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
+  name: string
+  install: (context: LoggerContext, options?: TOptions) => TInstallReturn | Promise<TInstallReturn>
+}
+
+export type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = Logger<TOptions, TInstallReturn>
 
 /**
  * Wraps a logger definition into a typed {@link Logger}.
  *
- * @example
+ * The optional second type parameter `TInstallReturn` allows loggers to return
+ * a value from `install` — for example, a sink factory that the caller can
+ * forward to hook execution.
+ *
+ * @example Basic logger
+ * ```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))
+ *   },
+ * })
+ * ```
+ *
+ * @example Logger that returns a hook sink factory
+ * ```ts
+ * export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
+ *   name: 'my-logger',
+ *   install(context, options) {
+ *     // … register event handlers …
+ *     return (commandWithArgs) => ({ onStdout: console.log })
  *   },
  * })
+ * ```
  */
-export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
+export function defineLogger<Options extends LoggerOptions = LoggerOptions, TInstallReturn = void>(
+  logger: UserLogger<Options, TInstallReturn>,
+): Logger<Options, TInstallReturn> {
   return logger
 }

package/src/defineMiddleware.ts

@@ -0,0 +1,62 @@
+import type { KubbHooks } from './types.ts'
+
+/**
+ * A middleware instance produced by calling a factory created with `defineMiddleware`.
+ * It declares event handlers under a `hooks` object which are registered on the
+ * shared emitter after all plugin hooks, so middleware handlers for any event
+ * always fire last.
+ */
+export type Middleware = {
+  /**
+   * Unique identifier for this middleware.
+   */
+  name: string
+  /**
+   * Lifecycle event handlers for this middleware.
+   * Any event from the global `KubbHooks` map can be subscribed to here.
+   * Handlers are registered after all plugin handlers, so they always fire last.
+   */
+  hooks: {
+    [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void>
+  }
+}
+
+/**
+ * Creates a middleware factory using the hook-style `hooks` API.
+ *
+ * Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
+ * Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
+ *
+ * @note The factory can accept typed options. See examples for using options and per-build state patterns.
+ *
+ * @example
+ * ```ts
+ * import { defineMiddleware } from '@kubb/core'
+ *
+ * // Stateless middleware
+ * export const logMiddleware = defineMiddleware(() => ({
+ *   name: 'log-middleware',
+ *   hooks: {
+ *     'kubb:build:end'({ files }) {
+ *       console.log(`Build complete with ${files.length} files`)
+ *     },
+ *   },
+ * }))
+ *
+ * // Middleware with options and per-build state
+ * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
+ *   const seen = new Set<string>()
+ *   return {
+ *     name: 'prefix-middleware',
+ *     hooks: {
+ *       'kubb:plugin:end'({ plugin }) {
+ *         seen.add(`${options.prefix}${plugin.name}`)
+ *       },
+ *     },
+ *   }
+ * })
+ * ```
+ */
+export function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware {
+  return (options) => factory(options ?? ({} as TOptions))
+}

package/src/defineParser.ts

@@ -0,0 +1,44 @@
+import type { FileNode } from '@kubb/ast'
+
+type PrintOptions = {
+  extname?: FileNode['extname']
+}
+
+export type Parser<TMeta extends object = any> = {
+  name: string
+  /**
+   * File extensions this parser handles.
+   * Use `undefined` to create a catch-all fallback parser.
+   *
+   * @example Handled extensions
+   * `['.ts', '.js']`
+   */
+  extNames: Array<FileNode['extname']> | undefined
+  /**
+   * Convert a resolved file to a string.
+   */
+  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string
+}
+
+/**
+ * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
+ *
+ * @note Call the returned factory with optional options to instantiate the parser.
+ *
+ * @example
+ * ```ts
+ * import { defineParser } from '@kubb/core'
+ *
+ * export const jsonParser = defineParser({
+ *   name: 'json',
+ *   extNames: ['.json'],
+ *   parse(file) {
+ *     const { extractStringsFromNodes } = await import('@kubb/ast')
+ *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+ *   },
+ * })
+ * ```
+ */
+export function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta> {
+  return parser
+}