@kubb/core 5.0.0-alpha.16 → 5.0.0-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.16",
+  "version": "5.0.0-alpha.18",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "typescript",
@@ -64,14 +64,14 @@
     }
   ],
   "dependencies": {
-    "@kubb/fabric-core": "0.14.0",
-    "@kubb/react-fabric": "0.14.0",
+    "@kubb/fabric-core": "0.15.1",
+    "@kubb/react-fabric": "0.15.1",
     "empathic": "^2.0.0",
     "fflate": "^0.8.2",
     "remeda": "^2.33.6",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "5.0.0-alpha.16"
+    "@kubb/ast": "5.0.0-alpha.18"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/Kubb.ts

@@ -167,15 +167,25 @@ export interface KubbEvents {
    */
   'file:processing:update': [
     {
-      /** Number of files processed so far. */
+      /**
+       * Number of files processed so far.
+       */
       processed: number
-      /** Total number of files to process. */
+      /**
+       * Total number of files to process.
+       */
       total: number
-      /** Processing percentage (0–100). */
+      /**
+       * Processing percentage (0–100).
+       */
       percentage: number
-      /** Optional source identifier. */
+      /**
+       * Optional source identifier.
+       */
       source?: string
-      /** The file being processed. */
+      /**
+       * The file being processed.
+       */
       file: KubbFile.ResolvedFile
       /**
        * Kubb configuration (not present in Fabric).

package/src/build.ts

@@ -17,16 +17,31 @@ type BuildOptions = {
   events?: AsyncEventEmitter<KubbEvents>
 }
 
+/**
+ * Full output produced by a successful or failed build.
+ */
 type BuildOutput = {
+  /**
+   * Plugins that threw during installation, paired with the caught error.
+   */
   failedPlugins: Set<{ plugin: Plugin; error: Error }>
   fabric: FabricType
   files: Array<KubbFile.ResolvedFile>
   driver: PluginDriver
+  /**
+   * Elapsed time in milliseconds for each plugin, keyed by plugin name.
+   */
   pluginTimings: Map<string, number>
   error?: Error
+  /**
+   * Raw generated source, keyed by absolute file path.
+   */
   sources: Map<KubbFile.Path, string>
 }
 
+/**
+ * Intermediate result returned by {@link setup} and accepted by {@link safeBuild}.
+ */
 type SetupResult = {
   events: AsyncEventEmitter<KubbEvents>
   fabric: FabricType
@@ -34,6 +49,17 @@ type SetupResult = {
   sources: Map<KubbFile.Path, string>
 }
 
+/**
+ * Initializes all Kubb infrastructure for a build without executing any plugins.
+ *
+ * - Validates the input path (when applicable).
+ * - Applies config defaults (`root`, `output.*`, `devtools`).
+ * - Creates the Fabric instance and wires storage, format, and lint hooks.
+ * - Runs the adapter (if configured) to produce the universal `RootNode`.
+ *
+ * Pass the returned {@link SetupResult} directly to {@link safeBuild} or {@link build}
+ * via the `overrides` argument to reuse the same infrastructure across multiple runs.
+ */
 export async function setup(options: BuildOptions): Promise<SetupResult> {
   const { config: userConfig, events = new AsyncEventEmitter<KubbEvents>() } = options
 
@@ -199,6 +225,12 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   }
 }
 
+/**
+ * Runs a full Kubb build and throws on any error or plugin failure.
+ *
+ * Internally delegates to {@link safeBuild} and rethrows collected errors.
+ * Pass an existing {@link SetupResult} via `overrides` to skip the setup phase.
+ */
 export async function build(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
   const { fabric, files, driver, failedPlugins, pluginTimings, error, sources } = await safeBuild(options, overrides)
 
@@ -223,6 +255,16 @@ export async function build(options: BuildOptions, overrides?: SetupResult): Pro
   }
 }
 
+/**
+ * Runs a full Kubb build and captures errors instead of throwing.
+ *
+ * - Installs each plugin in order, recording failures in `failedPlugins`.
+ * - Generates the root barrel file when `output.barrelType` is set.
+ * - Writes all files through Fabric.
+ *
+ * Returns a {@link BuildOutput} even on failure — inspect `error` and
+ * `failedPlugins` to determine whether the build succeeded.
+ */
 export async function safeBuild(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
   const { fabric, driver, events, sources } = overrides ? overrides : await setup(options)
 

package/src/config.ts

@@ -5,12 +5,14 @@ import type { InputPath, UserConfig } from './types.ts'
  * CLI options derived from command-line flags.
  */
 export type CLIOptions = {
-  /** Path to `kubb.config.js` */
+  /**
+   * Path to `kubb.config.js`.
+   */
   config?: string
-
-  /** Enable watch mode for input files */
+  /**
+   * Enable watch mode for input files.
+   */
   watch?: boolean
-
   /**
    * Logging verbosity for CLI usage.
    *
@@ -20,12 +22,11 @@ export type CLIOptions = {
    * @default 'silent'
    */
   logLevel?: 'silent' | 'info' | 'debug'
-
-  /** Run Kubb with Bun */
-  bun?: boolean
 }
 
-/** All accepted forms of a Kubb configuration. */
+/**
+ * All accepted forms of a Kubb configuration.
+ */
 export type ConfigInput = PossiblePromise<UserConfig | UserConfig[]> | ((cli: CLIOptions) => PossiblePromise<UserConfig | UserConfig[]>)
 
 /**

package/src/constants.ts

@@ -1,21 +1,50 @@
 import type { KubbFile } from '@kubb/fabric-core/types'
 
+/**
+ * Base URL for the Kubb Studio web app.
+ */
 export const DEFAULT_STUDIO_URL = 'https://studio.kubb.dev' as const
 
+/**
+ * Internal plugin name used to identify the core Kubb runtime.
+ */
 export const CORE_PLUGIN_NAME = 'core' as const
 
+/**
+ * Maximum number of event-emitter listeners before Node.js emits a warning.
+ */
 export const DEFAULT_MAX_LISTENERS = 100
 
+/**
+ * Default number of plugins that may run concurrently during a build.
+ */
 export const DEFAULT_CONCURRENCY = 15
 
+/**
+ * File name used for generated barrel (index) files.
+ */
 export const BARREL_FILENAME = 'index.ts' as const
 
+/**
+ * Default banner style written at the top of every generated file.
+ */
 export const DEFAULT_BANNER = 'simple' as const
 
+/**
+ * Default file-extension mapping used when no explicit mapping is configured.
+ */
 export const DEFAULT_EXTENSION: Record<KubbFile.Extname, KubbFile.Extname | ''> = { '.ts': '.ts' }
 
+/**
+ * Characters recognized as path separators on both POSIX and Windows.
+ */
 export const PATH_SEPARATORS = new Set(['/', '\\'] as const)
 
+/**
+ * Numeric log-level thresholds used internally to compare verbosity.
+ *
+ * Higher numbers are more verbose.
+ */
 export const logLevel = {
   silent: Number.NEGATIVE_INFINITY,
   error: 0,
@@ -25,6 +54,13 @@ export const logLevel = {
   debug: 5,
 } as const
 
+/**
+ * CLI command descriptors for each supported linter.
+ *
+ * Each entry contains the executable `command`, an `args` factory that maps an
+ * output path to the correct argument list, and an `errorMessage` shown when
+ * the linter is not found.
+ */
 export const linters = {
   eslint: {
     command: 'eslint',
@@ -43,6 +79,13 @@ export const linters = {
   },
 } as const
 
+/**
+ * CLI command descriptors for each supported code formatter.
+ *
+ * Each entry contains the executable `command`, an `args` factory that maps an
+ * output path to the correct argument list, and an `errorMessage` shown when
+ * the formatter is not found.
+ */
 export const formatters = {
   prettier: {
     command: 'prettier',

package/src/hooks/useKubb.ts

@@ -97,6 +97,22 @@ function buildDefaultBanner({ title, description, version, config }: { title?: s
   }
 }
 
+/**
+ * React-Fabric hook that exposes the current plugin context inside a generator component.
+ *
+ * Returns the active `plugin`, `mode`, `config`, and a set of resolver helpers
+ * (`getFile`, `resolveName`, `resolvePath`, `resolveBanner`, `resolveFooter`) that
+ * all default to the current plugin when no explicit `pluginName` is provided.
+ *
+ * @example
+ * ```ts
+ * function Operation({ node }: OperationProps) {
+ *   const { config, resolvePath } = useKubb()
+ *   const filePath = resolvePath({ baseName: node.operationId })
+ *   return <File path={filePath}>...</File>
+ * }
+ * ```
+ */
 export function useKubb<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(): UseKubbReturn<TOptions> {
   const { meta } = useFabric<{
     plugin: Plugin<TOptions>

package/src/index.ts

@@ -1,3 +1,4 @@
+export { AsyncEventEmitter, URLPath } from '@internals/utils'
 export { definePrinter } from '@kubb/ast'
 export { build, build as default, safeBuild, setup } from './build.ts'
 export { type CLIOptions, type ConfigInput, defineConfig, isInputPath } from './config.ts'

package/src/types.ts

@@ -91,11 +91,17 @@ export type AdapterFactoryOptions<TName extends string = string, TOptions extend
  * ```
  */
 export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
-  /** Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`. */
+  /**
+   * Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`.
+   */
   name: TOptions['name']
-  /** Resolved options (after defaults have been applied). */
+  /**
+   * Resolved options (after defaults have been applied).
+   */
   options: TOptions['resolvedOptions']
-  /** Convert the raw source into a universal `RootNode`. */
+  /**
+   * Convert the raw source into a universal `RootNode`.
+   */
   parse: (source: AdapterSource) => PossiblePromise<RootNode>
   /**
    * Extracts `KubbFile.Import` entries needed by a `SchemaNode` tree.

package/src/utils/TreeNode.ts

@@ -12,6 +12,15 @@ type BarrelData = {
   name: string
 }
 
+/**
+ * Tree structure used to build per-directory barrel (`index.ts`) files from a
+ * flat list of generated {@link KubbFile.File} entries.
+ *
+ * Each node represents either a directory or a file within the output tree.
+ * Use {@link TreeNode.build} to construct a root node from a file list, then
+ * traverse with {@link TreeNode.forEach}, {@link TreeNode.leaves}, or the
+ * `*Deep` helpers.
+ */
 export class TreeNode {
   data: BarrelData
   parent?: TreeNode
@@ -32,6 +41,9 @@ export class TreeNode {
     return child
   }
 
+  /**
+   * Returns the root ancestor of this node, walking up via `parent` links.
+   */
   get root(): TreeNode {
     if (!this.parent) {
       return this
@@ -39,6 +51,11 @@ export class TreeNode {
     return this.parent.root
   }
 
+  /**
+   * Returns all leaf descendants (nodes with no children) of this node.
+   *
+   * Results are cached after the first traversal.
+   */
   get leaves(): Array<TreeNode> {
     if (!this.children || this.children.length === 0) {
       // this is a leaf
@@ -105,6 +122,12 @@ export class TreeNode {
     return this.leaves.map(callback)
   }
 
+  /**
+   * Builds a {@link TreeNode} tree from a flat list of files.
+   *
+   * - Filters to files under `root` (when provided) and skips `.json` files.
+   * - Returns `null` when no files match.
+   */
   public static build(files: KubbFile.File[], root?: string): TreeNode | null {
     try {
       const filteredTree = buildDirectoryTree(files, root)

package/src/utils/diagnostics.ts

@@ -2,7 +2,10 @@ import { version as nodeVersion } from 'node:process'
 import { version as KubbVersion } from '../../package.json'
 
 /**
- * Get diagnostic information for debugging
+ * Returns a snapshot of the current runtime environment.
+ *
+ * Useful for attaching context to debug logs and error reports so that
+ * issues can be reproduced without manual information gathering.
  */
 export function getDiagnosticInfo() {
   return {

package/src/utils/executeStrategies.ts

@@ -7,7 +7,11 @@ type ValueOfPromiseFuncArray<TInput extends Array<unknown>> = TInput extends Arr
 type SeqOutput<TInput extends Array<PromiseFunc<TValue, null>>, TValue> = Promise<Array<Awaited<ValueOfPromiseFuncArray<TInput>>>>
 
 /**
- * Chains promises
+ * Runs promise functions in sequence, threading each result into the next call.
+ *
+ * - Each function receives the accumulated state from the previous call.
+ * - Skips functions that return a falsy value (acts as a no-op for that step).
+ * - Returns an array of all individual results.
  */
 export function hookSeq<TInput extends Array<PromiseFunc<TValue, null>>, TValue, TOutput = SeqOutput<TInput, TValue>>(promises: TInput): TOutput {
   return promises.filter(Boolean).reduce(
@@ -33,7 +37,10 @@ export function hookSeq<TInput extends Array<PromiseFunc<TValue, null>>, TValue,
 type HookFirstOutput<TInput extends Array<PromiseFunc<TValue, null>>, TValue = unknown> = ValueOfPromiseFuncArray<TInput>
 
 /**
- * Chains promises, first non-null result stops and returns
+ * Runs promise functions in sequence and returns the first non-null result.
+ *
+ * - Stops as soon as `nullCheck` passes for a result (default: `!== null`).
+ * - Subsequent functions are skipped once a match is found.
  */
 export function hookFirst<TInput extends Array<PromiseFunc<TValue, null>>, TValue = unknown, TOutput = HookFirstOutput<TInput, TValue>>(
   promises: TInput,
@@ -57,7 +64,10 @@ export function hookFirst<TInput extends Array<PromiseFunc<TValue, null>>, TValu
 type HookParallelOutput<TInput extends Array<PromiseFunc<TValue, null>>, TValue> = Promise<PromiseSettledResult<Awaited<ValueOfPromiseFuncArray<TInput>>>[]>
 
 /**
- * Runs an array of promise functions with optional concurrency limit.
+ * Runs promise functions concurrently and returns all settled results.
+ *
+ * - Limits simultaneous executions to `concurrency` (default: unlimited).
+ * - Uses `Promise.allSettled` so individual failures do not cancel other tasks.
  */
 export function hookParallel<TInput extends Array<PromiseFunc<TValue, null>>, TValue = unknown, TOutput = HookParallelOutput<TInput, TValue>>(
   promises: TInput,
@@ -70,6 +80,9 @@ export function hookParallel<TInput extends Array<PromiseFunc<TValue, null>>, TV
   return Promise.allSettled(tasks) as TOutput
 }
 
+/**
+ * Execution strategy used when dispatching plugin hook calls.
+ */
 export type Strategy = 'seq' | 'first' | 'parallel'
 
 type StrategyOutputMap<TInput extends Array<PromiseFunc<TValue, null>>, TValue> = {

package/src/utils/formatters.ts

@@ -4,18 +4,13 @@ import type { formatters } from '../constants.ts'
 type Formatter = keyof typeof formatters
 
 /**
- * Check if a formatter command is available in the system.
+ * Returns `true` when the given formatter is installed and callable.
  *
- * @param formatter - The formatter to check ('biome', 'prettier', or 'oxfmt')
- * @returns Promise that resolves to true if the formatter is available, false otherwise
- *
- * @remarks
- * This function checks availability by running `<formatter> --version` command.
- * All supported formatters (biome, prettier, oxfmt) implement the --version flag.
+ * Availability is detected by running `<formatter> --version` and checking
+ * that the process exits without error.
  */
 async function isFormatterAvailable(formatter: Formatter): Promise<boolean> {
   try {
-    // Try to get the version of the formatter to check if it's installed
     await x(formatter, ['--version'], { nodeOptions: { stdio: 'ignore' } })
     return true
   } catch {
@@ -24,26 +19,20 @@ async function isFormatterAvailable(formatter: Formatter): Promise<boolean> {
 }
 
 /**
- * Detect which formatter is available in the system.
- *
- * @returns Promise that resolves to the first available formatter or undefined if none are found
+ * Detects the first available code formatter on the current system.
  *
- * @remarks
- * Checks in order of preference: biome, oxfmt, prettier.
- * Uses the `--version` flag to detect if each formatter command is available.
- * This is a reliable method as all supported formatters implement this flag.
+ * - Checks in preference order: `biome`, `oxfmt`, `prettier`.
+ * - Returns `null` when none are found.
  *
  * @example
- * ```typescript
+ * ```ts
  * const formatter = await detectFormatter()
  * if (formatter) {
  *   console.log(`Using ${formatter} for formatting`)
- * } else {
- *   console.log('No formatter found')
  * }
  * ```
  */
-export async function detectFormatter(): Promise<Formatter | undefined> {
+export async function detectFormatter(): Promise<Formatter | null> {
   const formatterNames = new Set(['biome', 'oxfmt', 'prettier'] as const)
 
   for (const formatter of formatterNames) {
@@ -52,5 +41,5 @@ export async function detectFormatter(): Promise<Formatter | undefined> {
     }
   }
 
-  return undefined
+  return null
 }

package/src/utils/getBarrelFiles.ts

@@ -105,6 +105,14 @@ function trimExtName(text: string): string {
   return text
 }
 
+/**
+ * Generates `index.ts` barrel files for all directories under `root/output.path`.
+ *
+ * - Returns an empty array when `type` is falsy or `'propagate'`.
+ * - Skips generation when the output path itself ends with `index` (already a barrel).
+ * - When `type` is `'all'`, strips named exports so every re-export becomes a wildcard (`export * from`).
+ * - Attaches `meta` to each barrel file for downstream plugin identification.
+ */
 export async function getBarrelFiles(files: Array<KubbFile.ResolvedFile>, { type, meta = {}, root, output }: AddIndexesProps): Promise<Array<KubbFile.File>> {
   if (!type || type === 'propagate') {
     return []

package/src/utils/getConfigs.ts

@@ -2,7 +2,11 @@ import type { CLIOptions, ConfigInput } from '../config.ts'
 import type { Config, UserConfig } from '../types.ts'
 
 /**
- * Converting UserConfig to Config Array without a change in the object beside the JSON convert.
+ * Resolves a {@link ConfigInput} into a normalized array of {@link Config} objects.
+ *
+ * - Awaits the config when it is a `Promise`.
+ * - Calls the factory function with `args` when the config is a function.
+ * - Wraps a single config object in an array for uniform downstream handling.
  */
 export async function getConfigs(config: ConfigInput | UserConfig, args: CLIOptions): Promise<Array<Config>> {
   const resolved = await (typeof config === 'function' ? config(args as CLIOptions) : config)

package/src/utils/getPreset.ts

@@ -16,6 +16,13 @@ type GetPresetResult<TResolver extends Resolver> = {
   preset: Preset<TResolver> | undefined
 }
 
+/**
+ * Resolves a named preset into merged resolvers and transformers.
+ *
+ * - Merges the preset's resolvers on top of the first (default) resolver to produce `baseResolver`.
+ * - Merges any additional user-supplied resolvers on top of that to produce the final `resolver`.
+ * - Concatenates preset transformers before user-supplied transformers.
+ */
 export function getPreset<TResolver extends Resolver = Resolver>(params: GetPresetParams<TResolver>): GetPresetResult<TResolver> {
   const { preset: presetName, presets, resolvers, transformers: userTransformers } = params
   const [defaultResolver, ...userResolvers] = resolvers

package/src/utils/linters.ts

@@ -3,6 +3,12 @@ import type { linters } from '../constants.ts'
 
 type Linter = keyof typeof linters
 
+/**
+ * Returns `true` when the given linter is installed and callable.
+ *
+ * Availability is detected by running `<linter> --version` and checking
+ * that the process exits without error.
+ */
 async function isLinterAvailable(linter: Linter): Promise<boolean> {
   try {
     await x(linter, ['--version'], { nodeOptions: { stdio: 'ignore' } })
@@ -12,7 +18,21 @@ async function isLinterAvailable(linter: Linter): Promise<boolean> {
   }
 }
 
-export async function detectLinter(): Promise<Linter | undefined> {
+/**
+ * Detects the first available linter on the current system.
+ *
+ * - Checks in preference order: `biome`, `oxlint`, `eslint`.
+ * - Returns `null` when none are found.
+ *
+ * @example
+ * ```ts
+ * const linter = await detectLinter()
+ * if (linter) {
+ *   console.log(`Using ${linter} for linting`)
+ * }
+ * ```
+ */
+export async function detectLinter(): Promise<Linter | null> {
   const linterNames = new Set(['biome', 'oxlint', 'eslint'] as const)
 
   for (const linter of linterNames) {
@@ -21,5 +41,5 @@ export async function detectLinter(): Promise<Linter | undefined> {
     }
   }
 
-  return undefined
+  return null
 }

package/src/utils/packageJSON.ts

@@ -10,16 +10,16 @@ type PackageJSON = {
 type DependencyName = string
 type DependencyVersion = string
 
-function getPackageJSONSync(cwd?: string): PackageJSON | undefined {
+function getPackageJSONSync(cwd?: string): PackageJSON | null {
   const pkgPath = pkg.up({ cwd })
   if (!pkgPath) {
-    return undefined
+    return null
   }
 
   return JSON.parse(readSync(pkgPath)) as PackageJSON
 }
 
-function match(packageJSON: PackageJSON, dependency: DependencyName | RegExp): string | undefined {
+function match(packageJSON: PackageJSON, dependency: DependencyName | RegExp): string | null {
   const dependencies = {
     ...(packageJSON.dependencies || {}),
     ...(packageJSON.devDependencies || {}),
@@ -31,15 +31,30 @@ function match(packageJSON: PackageJSON, dependency: DependencyName | RegExp): s
 
   const matched = Object.keys(dependencies).find((dep) => dep.match(dependency))
 
-  return matched ? dependencies[matched] : undefined
+  return matched ? (dependencies[matched] ?? null) : null
 }
 
-function getVersionSync(dependency: DependencyName | RegExp, cwd?: string): DependencyVersion | undefined {
+function getVersionSync(dependency: DependencyName | RegExp, cwd?: string): DependencyVersion | null {
   const packageJSON = getPackageJSONSync(cwd)
 
-  return packageJSON ? match(packageJSON, dependency) : undefined
+  return packageJSON ? match(packageJSON, dependency) : null
 }
 
+/**
+ * Returns `true` when the nearest `package.json` declares a dependency that
+ * satisfies the given semver range.
+ *
+ * - Searches both `dependencies` and `devDependencies`.
+ * - Accepts a string package name or a `RegExp` to match scoped/pattern packages.
+ * - Uses `semver.satisfies` for range comparison; returns `false` when the
+ *   version string cannot be coerced into a valid semver.
+ *
+ * @example
+ * ```ts
+ * satisfiesDependency('react', '>=18')          // true when react@18.x is installed
+ * satisfiesDependency(/^@tanstack\//, '>=5')    // true when any @tanstack/* >=5 is found
+ * ```
+ */
 export function satisfiesDependency(dependency: DependencyName | RegExp, version: DependencyVersion, cwd?: string): boolean {
   const packageVersion = getVersionSync(dependency, cwd)