@kubb/core 5.0.0-beta.6 → 5.0.0-beta.61

package/src/createRenderer.ts

@@ -3,53 +3,68 @@ 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.
+ * `TElement` is the type the renderer accepts, for example `KubbReactElement`
+ * for `@kubb/renderer-jsx` or a custom type for your own renderer. Defaults to
+ * `unknown` so generators that don't care about the element type work without
+ * specifying it.
  */
 export type Renderer<TElement = unknown> = {
+  /**
+   * Renders `element` and populates {@link files} with the resulting {@link FileNode} objects.
+   * Called once per render cycle. Must resolve before {@link files} is read.
+   */
   render(element: TElement): Promise<void>
-  unmount(error?: Error | number | null): void
+  /**
+   * Accumulated {@link FileNode} results produced by the last {@link render} call.
+   * Not populated when {@link stream} is implemented.
+   */
   readonly files: Array<FileNode>
+  /**
+   * When present, core calls this instead of {@link render} and {@link files},
+   * forwarding each file to `FileManager` as soon as it is ready.
+   */
+  stream?(element: TElement): Iterable<FileNode>
+  /**
+   * Disposer hook so renderers participate in `using` blocks: `using r = rendererFactory()`
+   * runs cleanup on every exit path, including thrown errors.
+   */
+  [Symbol.dispose](): void
 }
 
 /**
- * A factory function that produces a fresh {@link Renderer} per render.
+ * A factory function that produces a fresh {@link Renderer} per render cycle.
  *
  * 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.
+ * Defines a renderer factory. Renderers turn the generator's return value
+ * (JSX, a template string, a tree of any shape) into `FileNode`s that get
+ * written to disk.
  *
- * 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.
+ * A renderer can target output formats beyond JSX, for instance a Handlebars
+ * renderer or one that writes binary files. Plugins and generators pick the
+ * renderer to use via the `renderer` field on `defineGenerator`.
  *
- * @example
+ * @example A minimal renderer that wraps a custom runtime
  * ```ts
- * // packages/renderer-jsx/src/index.ts
- * export const jsxRenderer = createRenderer(() => {
- *   const runtime = new Runtime()
+ * import { createRenderer } from '@kubb/core'
+ *
+ * export const myRenderer = createRenderer(() => {
+ *   const runtime = new MyRuntime()
  *   return {
- *     async render(element) { await runtime.render(element) },
- *     get files() { return runtime.nodes },
- *     unmount(error) { runtime.unmount(error) },
+ *     async render(element) {
+ *       await runtime.render(element)
+ *     },
+ *     get files() {
+ *       return runtime.files
+ *     },
+ *     [Symbol.dispose]() {
+ *       runtime.dispose()
+ *     },
  *   }
  * })
- *
- * // 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> {

package/src/createReporter.ts

@@ -0,0 +1,134 @@
+import type { Config } from './types.ts'
+import type { Diagnostic } from './diagnostics.ts'
+
+/**
+ * Numeric log-level thresholds used internally to compare verbosity.
+ *
+ * Higher numbers are more verbose.
+ */
+export const logLevel = {
+  silent: Number.NEGATIVE_INFINITY,
+  error: 0,
+  warn: 1,
+  info: 3,
+  verbose: 4,
+} as const
+
+/**
+ * A built-in reporter that renders a run's output, independent of the live logger view.
+ *
+ * - `cli` renders the per-config summary to the terminal (the default).
+ * - `json` writes a machine-readable report to stdout, for CI.
+ * - `file` writes a config's diagnostics to `.kubb/kubb-<name>-<timestamp>.log`.
+ */
+export type ReporterName = 'cli' | 'json' | 'file'
+
+/**
+ * One config's outcome within a run, as handed to a {@link Reporter}.
+ */
+export type GenerationResult = {
+  config: Config
+  /**
+   * Diagnostics collected while generating this config.
+   */
+  diagnostics: Array<Diagnostic>
+  /**
+   * Number of files written for this config.
+   */
+  filesCreated: number
+  status: 'success' | 'failed'
+  /**
+   * `process.hrtime()` snapshot taken when this config started generating.
+   */
+  hrStart: [number, number]
+}
+
+/**
+ * Render context passed alongside the {@link GenerationResult}, carrying knobs a reporter needs
+ * but that are not part of the run data (e.g. verbosity).
+ */
+export type ReporterContext = {
+  /**
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
+   */
+  logLevel: (typeof logLevel)[keyof typeof logLevel]
+}
+
+/**
+ * Host-facing reporter, as installed onto a run. Unlike a Logger (the live TUI view), a reporter
+ * never sees the event emitter. `report` runs once per config. `drain`, when present, runs once
+ * after the last config.
+ */
+export type Reporter = {
+  /**
+   * Display name, matching a {@link ReporterName} for the built-ins.
+   */
+  name: string
+  /**
+   * Called once per config with that config's result and the render context.
+   */
+  report: (result: GenerationResult, context: ReporterContext) => void | Promise<void>
+  /**
+   * Optional finalizer called once after the run's last config. The host wires it to
+   * `kubb:lifecycle:end`. {@link createReporter} closes it over the reports `report` returned.
+   */
+  drain?: (context: ReporterContext) => void | Promise<void>
+}
+
+/**
+ * Reporter definition passed to {@link createReporter}. `report` returns the value to collect for
+ * this config (e.g. a built report), and the optional `drain` receives the collected reports to
+ * emit as one document. `T` is inferred from `report`'s return type.
+ */
+export type UserReporter<T = void> = {
+  name: string
+  report: (result: GenerationResult, context: ReporterContext) => T | Promise<T>
+  drain?: (context: ReporterContext, reports: Array<T>) => void | Promise<void>
+}
+
+/**
+ * Defines a reporter. When the definition has a `drain`, the returned reporter buffers each value
+ * `report` returns and hands the array to `drain` once, then clears it. Without a `drain`, nothing
+ * is buffered. Wiring the reporter onto the run's events is the host's job, so the reporter only
+ * ever deals with a {@link GenerationResult}.
+ *
+ * @example
+ * ```ts
+ * import { createReporter, Diagnostics } from '@kubb/core'
+ *
+ * export const jsonReporter = createReporter({
+ *   name: 'json',
+ *   report(result) {
+ *     return { status: Diagnostics.hasError(result.diagnostics) ? 'failed' : 'success', diagnostics: result.diagnostics }
+ *   },
+ *   drain(context, reports) {
+ *     process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`)
+ *   },
+ * })
+ * ```
+ */
+export function createReporter<T = void>(reporter: UserReporter<T>): Reporter {
+  const drain = reporter.drain
+  if (!drain) {
+    return {
+      name: reporter.name,
+      async report(result, context) {
+        await reporter.report(result, context)
+      },
+    }
+  }
+
+  const reports: Array<T> = []
+
+  return {
+    name: reporter.name,
+    async report(result, context) {
+      reports.push(await reporter.report(result, context))
+    },
+    async drain(context) {
+      await drain(context, reports)
+      reports.length = 0
+    },
+  }
+}

package/src/createStorage.ts

@@ -1,68 +1,81 @@
+/**
+ * Backend that persists generated files. Kubb ships with `fsStorage` (writes
+ * to disk) and `memoryStorage` (keeps everything in RAM). Implement this
+ * interface to write somewhere else, such as S3 or a database.
+ */
 export type Storage = {
   /**
-   * Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`).
+   * Identifier used in logs and diagnostics (`'fs'`, `'memory'`, `'s3'`).
    */
   readonly name: string
   /**
-   * Returns `true` when an entry for `key` exists in storage.
+   * Returns `true` when an entry for `key` exists.
    */
   hasItem(key: string): Promise<boolean>
   /**
-   * Returns the stored string value, or `null` when `key` does not exist.
+   * Reads the stored string. Returns `null` when the key is missing.
    */
   getItem(key: string): Promise<string | null>
   /**
-   * Persists `value` under `key`, creating any required structure.
+   * Stores `value` under `key`, creating any required structure (directories,
+   * buckets, ...).
    */
   setItem(key: string, value: string): Promise<void>
   /**
-   *  Removes the entry for `key`. No-ops when the key does not exist.
+   * Deletes the entry for `key`. No-op when the key does not exist.
    */
   removeItem(key: string): Promise<void>
   /**
-   * Returns all keys, optionally filtered to those starting with `base`.
+   * Returns every key. Pass `base` to filter to keys starting with that prefix.
    */
   getKeys(base?: string): Promise<Array<string>>
   /**
-   * Removes all entries, optionally scoped to those starting with `base`.
+   * Removes every entry. Pass `base` to scope the wipe to a key prefix.
    */
   clear(base?: string): Promise<void>
   /**
-   * Optional teardown hook called after the build completes.
+   * Optional teardown hook called after the build completes. Use to flush
+   * buffers, close connections, or release file locks.
    */
   dispose?(): Promise<void>
 }
 
 /**
- * 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.
+ * Defines a custom storage backend. The builder receives user options and
+ * returns a `Storage` implementation. Kubb ships with filesystem and in-memory
+ * storages. A custom backend writes generated files elsewhere, such as cloud
+ * storage or a database.
  *
- * @note Call the returned factory with optional options to instantiate the storage adapter.
- *
- * @example
+ * @example In-memory storage (the built-in implementation)
  * ```ts
  * import { createStorage } from '@kubb/core'
  *
  * export const memoryStorage = createStorage(() => {
  *   const store = new Map<string, string>()
+ *
  *   return {
  *     name: 'memory',
- *     async hasItem(key) { return store.has(key) },
- *     async getItem(key) { return store.get(key) ?? null },
- *     async setItem(key, value) { store.set(key, value) },
- *     async removeItem(key) { store.delete(key) },
+ *     async hasItem(key) {
+ *       return store.has(key)
+ *     },
+ *     async getItem(key) {
+ *       return store.get(key) ?? null
+ *     },
+ *     async setItem(key, value) {
+ *       store.set(key, value)
+ *     },
+ *     async removeItem(key) {
+ *       store.delete(key)
+ *     },
  *     async getKeys(base) {
  *       const keys = [...store.keys()]
  *       return base ? keys.filter((k) => k.startsWith(base)) : keys
  *     },
- *     async clear(base) { if (!base) store.clear() },
+ *     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 {

package/src/defineGenerator.ts

@@ -1,16 +1,117 @@
-import type { PossiblePromise } from '@internals/utils'
-import type { FileNode, OperationNode, SchemaNode } from '@kubb/ast'
+import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
+import type { FileNode, InputMeta, OperationNode, SchemaNode } from '@kubb/ast'
+import type { Adapter } from './createAdapter.ts'
 import type { RendererFactory } from './createRenderer.ts'
-import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
+import type { KubbHooks } from './types.ts'
+import type { KubbDriver } from './KubbDriver.ts'
+import type { Plugin, PluginFactoryOptions } from './definePlugin.ts'
+import type { Resolver } from './defineResolver.ts'
+import type { Config } from './types.ts'
 
-export type { GeneratorContext } from './types.ts'
+/**
+ * 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 GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * The resolved Kubb config for this build, including `root`, `input`, `output`, and the
+   * full plugin list.
+   */
+  config: Config
+  /**
+   * Absolute path to the current plugin's output directory.
+   */
+  root: string
+  /**
+   * The driver running this build. Most generators never need it. Prefer the scoped helpers
+   * on this context (`getPlugin`, `getResolver`, `upsertFile`) over reaching into the driver.
+   */
+  driver: KubbDriver
+  /**
+   * 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>
+  /**
+   * The build's event bus. Emit or listen to any `KubbHooks` event, for example to react to
+   * `kubb:build:end` from inside a generator.
+   */
+  hooks: AsyncEventEmitter<KubbHooks>
+  /**
+   * The current plugin instance.
+   */
+  plugin: Plugin<TOptions>
+  /**
+   * The current plugin's resolver. It decides what every generated symbol and file path is
+   * called. Kubb picks a `setResolver` registration first, then the plugin's static
+   * `resolver`, then the built-in default.
+   *
+   * @example Resolve a type name
+   * `ctx.resolver.default('pet', 'type') // 'Pet'`
+   *
+   * @example Resolve an output file
+   * `ctx.resolver.resolveFile({ name: 'pet', extname: '.ts' }, { root, output })`
+   */
+  resolver: TOptions['resolver']
+  /**
+   * Report a warning. Collected as a `warning` diagnostic attributed to the current
+   * plugin. It surfaces in the run summary but does not fail the build. For a structured
+   * diagnostic with a code and source location, use `Diagnostics.report` or throw a
+   * `Diagnostics.Error` directly.
+   */
+  warn: (message: string) => void
+  /**
+   * Report an error. Collected as an `error` diagnostic attributed to the current
+   * plugin, which fails the build.
+   */
+  error: (error: string | Error) => void
+  /**
+   * Report an informational message. Collected as an `info` diagnostic attributed to
+   * the current plugin.
+   */
+  info: (message: string) => void
+  /**
+   * The configured adapter instance.
+   */
+  adapter: Adapter
+  /**
+   * Document metadata from the adapter: title, version, base URL, and pre-computed
+   * schema index fields (`circularNames`, `enumNames`).
+   */
+  meta: InputMeta
+  /**
+   * Resolved options after exclude/include/override filtering.
+   */
+  options: TOptions['resolvedOptions']
+}
 
 /**
  * Declares a named generator unit that walks the AST and emits files.
  *
  * 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.
+ * JSX-based generators require a `renderer` factory. Return `Array<FileNode>` directly, or call
+ * `ctx.upsertFile()` manually and return `null` to bypass rendering.
  *
  * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
@@ -42,8 +143,7 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
    *
    * 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).
+   * Leave it unset or set `renderer: null` to opt out of rendering.
    *
    * @example
    * ```ts
@@ -57,28 +157,51 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
   renderer?: RendererFactory<TElement> | null
   /**
    * Called for each schema node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>
   /**
    * Called for each operation node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>
   /**
    * Called once after all operations have been walked.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the plugin-level options for the batch call.
    */
-  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>
 }
 
 /**
- * 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.
+ * Defines a generator: a unit of work that runs during the plugin's AST walk
+ * and produces files. Plugins register generators via `ctx.addGenerator()`
+ * inside `kubb:plugin:setup`.
+ *
+ * The returned object is the input as-is, but with `this` types preserved so
+ * `schema`/`operation`/`operations` methods are correctly typed against the
+ * plugin's `PluginFactoryOptions`. Renderer elements and `FileNode[]` returns
+ * are both handled by the runtime, so pick whichever style fits.
+ *
+ * @example JSX-based schema generator
+ * ```tsx
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     return (
+ *       <File path={`${ctx.root}/${node.name}.ts`}>
+ *         <Type node={node} resolver={ctx.resolver} />
+ *       </File>
+ *     )
+ *   },
+ * })
+ * ```
  */
 export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(
   generator: Generator<TOptions, TElement>,

package/src/defineParser.ts

@@ -4,41 +4,59 @@ type PrintOptions = {
   extname?: FileNode['extname']
 }
 
-export type Parser<TMeta extends object = any> = {
+/**
+ * Converts a resolved {@link FileNode} into the final source string that gets
+ * written to disk. Kubb ships with TypeScript and TSX parsers. Add your own
+ * for new file types (JSON, Markdown, ...).
+ */
+export type Parser<TMeta extends object = object, TNode = unknown> = {
+  /**
+   * Display name used in diagnostics and the parser registry.
+   */
   name: string
   /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
+   * File extensions this parser handles. Set to `undefined` to define a
+   * catch-all fallback used when no other parser claims the extension.
    *
-   * @example Handled extensions
+   * @example
    * `['.ts', '.js']`
    */
   extNames: Array<FileNode['extname']> | undefined
   /**
-   * Convert a resolved file to a string.
+   * Serialize the file's AST into source code.
    */
-  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string
+  parse(file: FileNode<TMeta>, options?: PrintOptions): string
+  /**
+   * Render compiler AST nodes for this parser's language into source text.
+   * Plugins call this to format the nodes they assemble before handing them
+   * back to the parser as `FileNode.sources`.
+   */
+  print(...nodes: Array<TNode>): 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.
+ * Defines a parser with type-safe `this`. Used to register handlers for new
+ * file extensions or to plug a non-TypeScript output into the build.
  *
  * @example
  * ```ts
  * import { defineParser } from '@kubb/core'
+ * import { extractStringsFromNodes } from '@kubb/ast/utils'
  *
  * 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')
+ *     return file.sources
+ *       .map((source) => extractStringsFromNodes(source.nodes ?? []))
+ *       .join('\n')
+ *   },
+ *   print(...nodes) {
+ *     return nodes.map(String).join('\n')
  *   },
  * })
  * ```
  */
-export function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta> {
+export function defineParser<T extends Parser>(parser: T): T {
   return parser
 }