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

package/src/Transform.ts

@@ -1,105 +0,0 @@
-import type { Macro, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
-import { composeMacros, transform } from '@kubb/ast'
-
-/**
- * Holds an ordered list of macros per plugin, keyed by plugin name. Each plugin's macros run in
- * isolation on the original adapter node and are composed into a single `Visitor` that the
- * `@kubb/ast` `transform` primitive applies. `applyTo` is a per-plugin lookup, not a cross-plugin
- * chain, so plugin A's macros never see plugin B's output. When a plugin has no macros, `applyTo`
- * returns the original node reference, and `transform` does the same when the composed visitor
- * leaves the tree untouched, so callers can detect a no-op by identity.
- *
- * Registration order matches the order setup hooks fire, which the driver has already sorted by
- * `enforce` and dependency edges. The registry preserves that order. Macro `enforce` only reorders
- * within a single plugin's list.
- */
-export class Transform {
-  readonly #macros = new Map<string, Array<Macro>>()
-  // Composed visitor per plugin, rebuilt lazily after the macro list changes.
-  readonly #composed = new Map<string, Visitor>()
-  // Memoized results per plugin. Repeated `applyTo` calls return the same node identity, so
-  // downstream WeakMap caches keyed by node (the resolver's resolveOptions memo) hit when the
-  // driver resolves a node a second time, and a stateful macro runs once per node.
-  readonly #memo = new Map<string, WeakMap<SchemaNode | OperationNode, SchemaNode | OperationNode>>()
-
-  /**
-   * Number of plugins with at least one registered macro.
-   */
-  get size(): number {
-    return this.#macros.size
-  }
-
-  /**
-   * Appends `macro` to the plugin's list, after any macros already registered.
-   */
-  add(pluginName: string, macro: Macro): void {
-    const list = this.#macros.get(pluginName)
-    if (list) list.push(macro)
-    else this.#macros.set(pluginName, [macro])
-    this.#invalidate(pluginName)
-  }
-
-  /**
-   * Replaces the plugin's macro list with `macros`.
-   */
-  set(pluginName: string, macros: ReadonlyArray<Macro>): void {
-    this.#macros.set(pluginName, [...macros])
-    this.#invalidate(pluginName)
-  }
-
-  /**
-   * Looks up the composed visitor for `pluginName`, or `undefined` when the plugin has no macros.
-   */
-  get(pluginName: string): Visitor | undefined {
-    return this.#visitorFor(pluginName)
-  }
-
-  /**
-   * Runs the plugin's macros on `node`. Returns the original node reference when the plugin has no
-   * macros, so callers can compare by identity to detect a no-op.
-   */
-  applyTo<TNode extends SchemaNode | OperationNode>(pluginName: string, node: TNode): TNode {
-    const visitor = this.#visitorFor(pluginName)
-    if (!visitor) return node
-
-    let memo = this.#memo.get(pluginName)
-    if (!memo) {
-      memo = new WeakMap()
-      this.#memo.set(pluginName, memo)
-    }
-
-    const cached = memo.get(node)
-    if (cached) return cached as TNode
-
-    const result = transform(node, visitor) as TNode
-    memo.set(node, result)
-    return result
-  }
-
-  /**
-   * Clears every registration. Called from the driver's `dispose()` so macros do not leak across
-   * builds.
-   */
-  dispose(): void {
-    this.#macros.clear()
-    this.#composed.clear()
-    this.#memo.clear()
-  }
-
-  #invalidate(pluginName: string): void {
-    this.#composed.delete(pluginName)
-    this.#memo.delete(pluginName)
-  }
-
-  #visitorFor(pluginName: string): Visitor | undefined {
-    const macros = this.#macros.get(pluginName)
-    if (!macros || macros.length === 0) return undefined
-
-    let composed = this.#composed.get(pluginName)
-    if (!composed) {
-      composed = composeMacros(macros)
-      this.#composed.set(pluginName, composed)
-    }
-    return composed
-  }
-}

package/src/constants.ts

@@ -1,126 +0,0 @@
-/**
- * Number of file writes to batch in parallel during `flushPendingFiles`.
- */
-export const STREAM_FLUSH_EVERY = 50
-
-/**
- * Maximum number of █ characters in a plugin timing bar.
- */
-export const SUMMARY_MAX_BAR_LENGTH = 10 as const
-
-/**
- * Divides elapsed milliseconds into bar-length units (1 block per 100 ms).
- */
-export const SUMMARY_TIME_SCALE_DIVISOR = 100 as const
-
-/**
- * Number of schema/operation nodes to dispatch concurrently during generation.
- */
-export const SCHEMA_PARALLEL = 8
-
-/**
- * Upper bound of hook listeners a single plugin can add to one event (its schema, operation,
- * and operations generators, plus lifecycle hooks). Used to size the hooks emitter's
- * max-listener ceiling so a multi-generator plugin set does not trip Node's leak warning.
- */
-export const HOOK_LISTENERS_PER_PLUGIN = 4
-
-/**
- * Plugin `include` filter types that select operations directly. When one of these is set
- * without a `schemaName` include, the generate phase pre-scans operations to compute the set
- * of schemas they reach, so unreachable schemas can be pruned for that plugin.
- */
-export const OPERATION_FILTER_TYPES: ReadonlySet<string> = new Set(['tag', 'operationId', 'path', 'method', 'contentType'])
-
-/**
- * Stable codes Kubb attaches to a `Diagnostic`. Each maps to a known failure mode
- * and stays stable so it can be referenced in tooling and (later) docs. Reference
- * these instead of inlining the string at a throw site.
- */
-export const diagnosticCode = {
-  /**
-   * Fallback for an unstructured error with no specific code.
-   */
-  unknown: 'KUBB_UNKNOWN',
-  /**
-   * The `input.path` file or URL could not be read.
-   */
-  inputNotFound: 'KUBB_INPUT_NOT_FOUND',
-  /**
-   * An adapter was configured without an `input`.
-   */
-  inputRequired: 'KUBB_INPUT_REQUIRED',
-  /**
-   * A `$ref` (or equivalent reference) could not be resolved in the source document.
-   */
-  refNotFound: 'KUBB_REF_NOT_FOUND',
-  /**
-   * A server variable value is not allowed by its `enum`.
-   */
-  invalidServerVariable: 'KUBB_INVALID_SERVER_VARIABLE',
-  /**
-   * A required plugin is missing from the config.
-   */
-  pluginNotFound: 'KUBB_PLUGIN_NOT_FOUND',
-  /**
-   * A plugin threw while generating.
-   */
-  pluginFailed: 'KUBB_PLUGIN_FAILED',
-  /**
-   * A plugin reported a non-fatal warning through `ctx.warn`.
-   */
-  pluginWarning: 'KUBB_PLUGIN_WARNING',
-  /**
-   * A plugin reported an informational message through `ctx.info`.
-   */
-  pluginInfo: 'KUBB_PLUGIN_INFO',
-  /**
-   * A schema uses a `format` Kubb does not map to a specific type. Reserved for
-   * adapters to emit as a `warning`.
-   */
-  unsupportedFormat: 'KUBB_UNSUPPORTED_FORMAT',
-  /**
-   * A referenced schema or operation is marked `deprecated`. Reserved for adapters
-   * to emit as an `info`.
-   */
-  deprecated: 'KUBB_DEPRECATED',
-  /**
-   * An adapter is required but the config has none. The build cannot read the input
-   * without one.
-   */
-  adapterRequired: 'KUBB_ADAPTER_REQUIRED',
-  /**
-   * A resolved output path escapes the output directory, which can stem from a path
-   * traversal in the spec or a misconfigured `group.name`.
-   */
-  pathTraversal: 'KUBB_PATH_TRAVERSAL',
-  /**
-   * A plugin's options are invalid, for example `output.mode: 'file'` paired with a `group` option.
-   */
-  invalidPluginOptions: 'KUBB_INVALID_PLUGIN_OPTIONS',
-  /**
-   * A post-generate shell hook (`hooks.done`) exited with a failure.
-   */
-  hookFailed: 'KUBB_HOOK_FAILED',
-  /**
-   * The formatter pass over the generated files failed.
-   */
-  formatFailed: 'KUBB_FORMAT_FAILED',
-  /**
-   * The linter pass over the generated files failed.
-   */
-  lintFailed: 'KUBB_LINT_FAILED',
-  /**
-   * Not a failure. Carries a plugin's elapsed time, summed into the run total.
-   */
-  performance: 'KUBB_PERFORMANCE',
-  /**
-   * Not a failure. A newer Kubb version is available on npm.
-   */
-  updateAvailable: 'KUBB_UPDATE_AVAILABLE',
-} as const
-
-/**
- * Union of the stable {@link diagnosticCode} values.
- */
-export type DiagnosticCode = (typeof diagnosticCode)[keyof typeof diagnosticCode]

package/src/createAdapter.ts

@@ -1,127 +0,0 @@
-import type { PossiblePromise } from '@internals/utils'
-import type { ImportNode, InputNode, SchemaNode } from '@kubb/ast'
-
-/**
- * Source data handed to an adapter's `parse` function. Mirrors the config
- * input shape with paths resolved to absolute.
- *
- * - `{ type: 'path' }`: single file on disk.
- * - `{ type: 'paths' }`: multiple files (e.g. split spec).
- * - `{ type: 'data' }`: raw string or parsed object provided inline.
- */
-export type AdapterSource = { type: 'path'; path: string } | { type: 'data'; data: string | unknown } | { type: 'paths'; paths: Array<string> }
-
-/**
- * Generic parameters used by `createAdapter` and the resulting `Adapter` type.
- *
- * - `TName`: unique adapter identifier (`'oas'`, `'asyncapi'`, ...).
- * - `TOptions`: user-facing options accepted by the adapter factory.
- * - `TResolvedOptions`: options after defaults are applied.
- * - `TDocument`: type of the parsed source document.
- */
-export type AdapterFactoryOptions<
-  TName extends string = string,
-  TOptions extends object = object,
-  TResolvedOptions extends object = TOptions,
-  TDocument = unknown,
-> = {
-  name: TName
-  options: TOptions
-  resolvedOptions: TResolvedOptions
-  document: TDocument
-}
-
-/**
- * Converts input files or inline data into Kubb's universal AST `InputNode`.
- *
- * Adapters live between the spec format and the plugins. The built-in
- * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1. A custom adapter can
- * support GraphQL, gRPC, or another schema language.
- *
- * @example
- * ```ts
- * import { defineConfig } from 'kubb'
- * import { adapterOas } from '@kubb/adapter-oas'
- * import { pluginTs } from '@kubb/plugin-ts'
- *
- * export default defineConfig({
- *   input: { path: './petStore.yaml' },
- *   output: { path: './src/gen' },
- *   adapter: adapterOas(),
- *   plugins: [pluginTs()],
- * })
- * ```
- */
-export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
-  /**
-   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
-   */
-  name: TOptions['name']
-  /**
-   * Resolved adapter options after defaults have been applied.
-   */
-  options: TOptions['resolvedOptions']
-  /**
-   * Parsed source document after the first `parse()` call. `null` before parsing.
-   */
-  document: TOptions['document'] | null
-  /**
-   * Parse the source into a universal `InputNode`.
-   */
-  parse: (source: AdapterSource) => PossiblePromise<InputNode>
-  /**
-   * Extract `ImportNode` entries for a schema tree.
-   * Returns an empty array before the first `parse()` call.
-   *
-   * The `resolve` callback receives the collision-corrected schema name and must
-   * return `{ name, path }` for the import, or `undefined` to skip it.
-   */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<ImportNode>
-  /**
-   * Validate the document at the given path or URL.
-   */
-  validate: (input: string, options?: { throwOnError?: boolean }) => Promise<void>
-  /**
-   * Memory-efficient streaming variant of `parse()`.
-   *
-   * Returns an `InputNode<true>` whose `schemas` and `operations` are `AsyncIterable`.
-   * Each `for await` loop creates a fresh parse pass over the cached in-memory document.
-   * No pre-built arrays are held in memory.
-   */
-  stream?: (source: AdapterSource) => Promise<InputNode<true>>
-}
-
-type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
-
-/**
- * Defines a custom adapter that translates a spec format into Kubb's universal
- * AST, for example GraphQL, gRPC, or AsyncAPI. The built-in `@kubb/adapter-oas`
- * handles OpenAPI/Swagger documents.
- *
- * Adapters must return an `InputNode` from `parse`. That node is what every
- * plugin in the build consumes.
- *
- * @example
- * ```ts
- * import { createAdapter, ast, type AdapterFactoryOptions } from '@kubb/core'
- *
- * type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
- *
- * export const myAdapter = createAdapter<MyAdapter>((options) => ({
- *   name: 'my-adapter',
- *   options,
- *   document: null,
- *   async parse(_source) {
- *     // Convert the source (path or inline data) into an InputNode.
- *     return ast.factory.createInput()
- *   },
- *   getImports: () => [],
- *   async validate() {
- *     // Throw here when the spec is invalid.
- *   },
- * }))
- * ```
- */
-export function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {
-  return (options) => build(options ?? ({} as T['options']))
-}

package/src/createKubb.ts

@@ -1,195 +0,0 @@
-import { resolve } from 'node:path'
-import { AsyncEventEmitter, BuildError } from '@internals/utils'
-import { HOOK_LISTENERS_PER_PLUGIN } from './constants.ts'
-import { Diagnostics } from './diagnostics.ts'
-import { createStorage, type Storage } from './createStorage.ts'
-import { KubbDriver } from './KubbDriver.ts'
-import { fsStorage } from './storages/fsStorage.ts'
-import type { BuildOutput, Config, KubbHooks, UserConfig } from './types.ts'
-
-/**
- * Builds a `Storage` view scoped to the file paths produced by the current build.
- * Reads delegate to the underlying `storage` so source bytes stay where they were
- * written. Writes register the key so subsequent reads and `getKeys` are scoped
- * to this build's output.
- */
-function createSourcesView(storage: Storage): Storage {
-  const paths = new Set<string>()
-
-  return createStorage(() => ({
-    name: `${storage.name}:sources`,
-    async hasItem(key: string) {
-      return paths.has(key) && (await storage.hasItem(key))
-    },
-    async getItem(key: string) {
-      return paths.has(key) ? storage.getItem(key) : null
-    },
-    async setItem(key: string, value: string) {
-      paths.add(key)
-      await storage.setItem(key, value)
-    },
-    async removeItem(key: string) {
-      paths.delete(key)
-      await storage.removeItem(key)
-    },
-    async getKeys(base?: string) {
-      if (!base) return [...paths]
-      const result: Array<string> = []
-      for (const key of paths) {
-        if (key.startsWith(base)) result.push(key)
-      }
-      return result
-    },
-    async clear() {
-      paths.clear()
-      await storage.clear()
-    },
-  }))()
-}
-
-function resolveConfig(userConfig: UserConfig): Config {
-  return {
-    ...userConfig,
-    root: userConfig.root || process.cwd(),
-    parsers: userConfig.parsers ?? [],
-    output: {
-      format: false,
-      lint: false,
-      extension: { '.ts': '.ts' },
-      defaultBanner: 'simple',
-      ...userConfig.output,
-    },
-    storage: userConfig.storage ?? fsStorage(),
-    reporters: userConfig.reporters ?? [],
-    plugins: userConfig.plugins ?? [],
-  }
-}
-
-type CreateKubbOptions = {
-  hooks?: AsyncEventEmitter<KubbHooks>
-}
-
-/**
- * Kubb code-generation instance bound to a single config entry. Resolves the user
- * config in the constructor, so `config` is available right away, and shares `hooks`,
- * `storage`, and `driver` across the `setup → build` lifecycle.
- *
- * `createKubb` takes a plain config object (the shape `defineConfig` produces),
- * not a fluent builder.
- *
- * Attach event listeners to `.hooks` before calling `setup()` or `build()`.
- *
- * @example
- * ```ts
- * const kubb = createKubb(userConfig)
- * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => console.log(plugin.name, duration))
- * const { files, diagnostics } = await kubb.safeBuild()
- * ```
- */
-export class Kubb {
-  readonly hooks: AsyncEventEmitter<KubbHooks>
-  readonly config: Config
-  #driver: KubbDriver | null = null
-  #storage: Storage | null = null
-
-  constructor(userConfig: UserConfig, options: CreateKubbOptions = {}) {
-    this.config = resolveConfig(userConfig)
-    this.hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
-  }
-
-  get storage(): Storage {
-    if (!this.#storage) throw new Error('[kubb] setup() must be called before accessing storage')
-    return this.#storage
-  }
-
-  get driver(): KubbDriver {
-    if (!this.#driver) throw new Error('[kubb] setup() must be called before accessing driver')
-    return this.#driver
-  }
-
-  /**
-   * Initializes the driver and storage. `build()` calls this automatically.
-   */
-  async setup(): Promise<void> {
-    const config = this.config
-    const driver = new KubbDriver(config, { hooks: this.hooks })
-    const storage = createSourcesView(config.storage)
-
-    // Each generator a plugin registers adds a listener to the shared hooks emitter, so size the
-    // ceiling to the plugin count. Without this, a multi-generator plugin set trips Node's
-    // EventEmitter leak warning at the default 10.
-    this.hooks.setMaxListeners(Math.max(10, config.plugins.length * HOOK_LISTENERS_PER_PLUGIN))
-
-    if (config.output.clean) {
-      await config.storage.clear(resolve(config.root, config.output.path))
-    }
-
-    await driver.setup()
-
-    this.#driver = driver
-    this.#storage = storage
-  }
-
-  /**
-   * Runs the full pipeline and throws on any plugin error.
-   * Automatically calls `setup()` if needed.
-   */
-  async build(): Promise<BuildOutput> {
-    const out = await this.safeBuild()
-    if (Diagnostics.hasError(out.diagnostics)) {
-      const errors = out.diagnostics
-        .filter(Diagnostics.isProblem)
-        .filter((diagnostic) => diagnostic.severity === 'error')
-        .map((diagnostic) => diagnostic.cause ?? new Diagnostics.Error(diagnostic))
-      throw new BuildError(`Build failed with ${errors.length} ${errors.length === 1 ? 'error' : 'errors'}`, { errors })
-    }
-    return out
-  }
-
-  /**
-   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing.
-   * Automatically calls `setup()` if needed. This is the canonical call: it never throws on
-   * plugin errors, so callers stay in control of how failures surface.
-   */
-  async safeBuild(): Promise<BuildOutput> {
-    if (!this.#driver) await this.setup()
-    using cleanup = this
-    const driver = cleanup.driver
-    const storage = cleanup.storage
-    const { diagnostics } = await driver.run({ storage })
-
-    return { diagnostics, files: driver.fileManager.files, driver, storage }
-  }
-
-  dispose(): void {
-    this.#driver?.dispose()
-  }
-
-  [Symbol.dispose](): void {
-    this.dispose()
-  }
-}
-
-/**
- * Constructs a {@link Kubb} build orchestrator from a user config. Equivalent
- * to `new Kubb(userConfig, options)` and the canonical public entry point.
- *
- * @example
- * ```ts
- * import { createKubb } from '@kubb/core'
- * import { adapterOas } from '@kubb/adapter-oas'
- * import { pluginTs } from '@kubb/plugin-ts'
- *
- * const kubb = createKubb({
- *   input: { path: './petStore.yaml' },
- *   output: { path: './src/gen' },
- *   adapter: adapterOas(),
- *   plugins: [pluginTs()],
- * })
- *
- * await kubb.build()
- * ```
- */
-export function createKubb(userConfig: UserConfig, options: CreateKubbOptions = {}): Kubb {
-  return new Kubb(userConfig, options)
-}

package/src/createRenderer.ts

@@ -1,72 +0,0 @@
-import type { FileNode } from '@kubb/ast'
-
-/**
- * Minimal interface any Kubb renderer must satisfy.
- *
- * `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>
-  /**
-   * 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 cycle.
- *
- * Generators use this to declare which renderer handles their output.
- */
-export type RendererFactory<TElement = unknown> = () => Renderer<TElement>
-
-/**
- * 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.
- *
- * 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 A minimal renderer that wraps a custom runtime
- * ```ts
- * 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.files
- *     },
- *     [Symbol.dispose]() {
- *       runtime.dispose()
- *     },
- *   }
- * })
- * ```
- */
-export function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement> {
-  return factory
-}