@kubb/core 5.0.0-beta.62 → 5.0.0-beta.64

package/src/createReporter.ts

@@ -1,134 +0,0 @@
-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,83 +0,0 @@
-/**
- * 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 in logs and diagnostics (`'fs'`, `'memory'`, `'s3'`).
-   */
-  readonly name: string
-  /**
-   * Returns `true` when an entry for `key` exists.
-   */
-  hasItem(key: string): Promise<boolean>
-  /**
-   * Reads the stored string. Returns `null` when the key is missing.
-   */
-  getItem(key: string): Promise<string | null>
-  /**
-   * Stores `value` under `key`, creating any required structure (directories,
-   * buckets, ...).
-   */
-  setItem(key: string, value: string): Promise<void>
-  /**
-   * Deletes the entry for `key`. No-op when the key does not exist.
-   */
-  removeItem(key: string): Promise<void>
-  /**
-   * Returns every key. Pass `base` to filter to keys starting with that prefix.
-   */
-  getKeys(base?: string): Promise<Array<string>>
-  /**
-   * 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. Use to flush
-   * buffers, close connections, or release file locks.
-   */
-  dispose?(): Promise<void>
-}
-
-/**
- * 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.
- *
- * @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 getKeys(base) {
- *       const keys = [...store.keys()]
- *       return base ? keys.filter((k) => k.startsWith(base)) : keys
- *     },
- *     async clear(base) {
- *       if (!base) store.clear()
- *     },
- *   }
- * })
- * ```
- */
-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,210 +0,0 @@
-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 { 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'
-
-/**
- * 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.
- * 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`.
- *
- * @example
- * ```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 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.
-   *
-   * Leave it unset or set `renderer: null` to opt out of rendering.
-   *
-   * @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 `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> | undefined | null>
-  /**
-   * Called for each operation node in the AST walk.
-   * `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> | undefined | null>
-  /**
-   * Called once after all operations have been walked.
-   * `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> | undefined | null>
-}
-
-/**
- * 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>,
-): Generator<TOptions, TElement> {
-  return generator
-}

package/src/defineParser.ts

@@ -1,62 +0,0 @@
-import type { FileNode } from '@kubb/ast'
-
-type PrintOptions = {
-  extname?: FileNode['extname']
-}
-
-/**
- * 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. Set to `undefined` to define a
-   * catch-all fallback used when no other parser claims the extension.
-   *
-   * @example
-   * `['.ts', '.js']`
-   */
-  extNames: Array<FileNode['extname']> | undefined
-  /**
-   * Serialize the file's AST into source code.
-   */
-  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-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) {
- *     return file.sources
- *       .map((source) => extractStringsFromNodes(source.nodes ?? []))
- *       .join('\n')
- *   },
- *   print(...nodes) {
- *     return nodes.map(String).join('\n')
- *   },
- * })
- * ```
- */
-export function defineParser<T extends Parser>(parser: T): T {
-  return parser
-}