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

package/src/Transform.ts

@@ -0,0 +1,105 @@
+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,35 +1,126 @@
-import type { FileNode } from '@kubb/ast'
+/**
+ * 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
 
 /**
- * Base URL for the Kubb Studio web app.
+ * Divides elapsed milliseconds into bar-length units (1 block per 100 ms).
  */
-export const DEFAULT_STUDIO_URL = 'https://kubb.studio' as const
+export const SUMMARY_TIME_SCALE_DIVISOR = 100 as const
 
 /**
- * Maximum number of files processed in parallel by FileProcessor.
+ * Number of schema/operation nodes to dispatch concurrently during generation.
  */
-export const PARALLEL_CONCURRENCY_LIMIT = 100
+export const SCHEMA_PARALLEL = 8
 
 /**
- * Default banner style written at the top of every generated file.
+ * 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 DEFAULT_BANNER = 'simple' as const
+export const HOOK_LISTENERS_PER_PLUGIN = 4
 
 /**
- * Default file-extension mapping used when no explicit mapping is configured.
+ * 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 DEFAULT_EXTENSION: Record<FileNode['extname'], FileNode['extname'] | ''> = { '.ts': '.ts' }
+export const OPERATION_FILTER_TYPES: ReadonlySet<string> = new Set(['tag', 'operationId', 'path', 'method', 'contentType'])
 
 /**
- * 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,
-  debug: 5,
+ * 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,30 +1,125 @@
-import type { Adapter, AdapterFactoryOptions } from './types.ts'
+import type { PossiblePromise } from '@internals/utils'
+import type { ImportNode, InputNode, SchemaNode } from '@kubb/ast'
 
-type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
+/**
+ * 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> }
 
 /**
- * Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+ * Generic parameters used by `createAdapter` and the resulting `Adapter` type.
  *
- * Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
- * Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
+ * - `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`.
  *
- * @note Adapters must parse their input format to Kubb's `InputNode` structure.
+ * 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
- * export const myAdapter = createAdapter<MyAdapter>((options) => {
- *   return {
- *     name: 'my-adapter',
- *     options,
- *     async parse(source) {
- *       // Transform source format to InputNode
- *       return { ... }
- *     },
- *   }
+ * 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 }>
  *
- * // Instantiate:
- * const adapter = myAdapter({ validate: true })
+ * export const myAdapter = createAdapter<MyAdapter>((options) => ({
+ *   name: 'my-adapter',
+ *   options,
+ *   document: null,
+ *   async parse(_source) {
+ *     // Convert `source` (path or inline data) into an InputNode.
+ *     return ast.factory.createInput()
+ *   },
+ *   getImports: () => [],
+ *   async validate() {
+ *     // Throw or call ctx.error here when the spec is invalid.
+ *   },
+ * }))
  * ```
  */
 export function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {