@kubb/core 5.0.0-alpha.4 → 5.0.0-alpha.41

package/src/build.ts

@@ -1,420 +0,0 @@
-import { dirname, relative, resolve } from 'node:path'
-import { AsyncEventEmitter, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Fabric } from '@kubb/react-fabric'
-import { createFabric } from '@kubb/react-fabric'
-import { typescriptParser } from '@kubb/react-fabric/parsers'
-import { fsPlugin } from '@kubb/react-fabric/plugins'
-import { isInputPath } from './config.ts'
-import { BARREL_FILENAME, DEFAULT_BANNER, DEFAULT_CONCURRENCY, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
-import { BuildError } from './errors.ts'
-import { PluginManager } from './PluginManager.ts'
-import { fsStorage } from './storages/fsStorage.ts'
-import type { AdapterSource, Config, DefineStorage, KubbEvents, Output, Plugin, UserConfig } from './types.ts'
-import { getDiagnosticInfo } from './utils/diagnostics.ts'
-import type { FileMetaBase } from './utils/getBarrelFiles.ts'
-
-type BuildOptions = {
-  config: UserConfig
-  events?: AsyncEventEmitter<KubbEvents>
-}
-
-type BuildOutput = {
-  failedPlugins: Set<{ plugin: Plugin; error: Error }>
-  fabric: Fabric
-  files: Array<KubbFile.ResolvedFile>
-  pluginManager: PluginManager
-  pluginTimings: Map<string, number>
-  error?: Error
-  sources: Map<KubbFile.Path, string>
-}
-
-type SetupResult = {
-  events: AsyncEventEmitter<KubbEvents>
-  fabric: Fabric
-  pluginManager: PluginManager
-  sources: Map<KubbFile.Path, string>
-}
-
-export async function setup(options: BuildOptions): Promise<SetupResult> {
-  const { config: userConfig, events = new AsyncEventEmitter<KubbEvents>() } = options
-
-  const sources: Map<KubbFile.Path, string> = new Map<KubbFile.Path, string>()
-  const diagnosticInfo = getDiagnosticInfo()
-
-  if (Array.isArray(userConfig.input)) {
-    await events.emit('warn', 'This feature is still under development — use with caution')
-  }
-
-  await events.emit('debug', {
-    date: new Date(),
-    logs: [
-      'Configuration:',
-      `  • Name: ${userConfig.name || 'unnamed'}`,
-      `  • Root: ${userConfig.root || process.cwd()}`,
-      `  • Output: ${userConfig.output?.path || 'not specified'}`,
-      `  • Plugins: ${userConfig.plugins?.length || 0}`,
-      'Output Settings:',
-      `  • Storage: ${userConfig.output?.storage ? `custom(${userConfig.output.storage.name})` : userConfig.output?.write === false ? 'disabled' : 'filesystem (default)'}`,
-      `  • Formatter: ${userConfig.output?.format || 'none'}`,
-      `  • Linter: ${userConfig.output?.lint || 'none'}`,
-      'Environment:',
-      Object.entries(diagnosticInfo)
-        .map(([key, value]) => `  • ${key}: ${value}`)
-        .join('\n'),
-    ],
-  })
-
-  try {
-    if (isInputPath(userConfig) && !new URLPath(userConfig.input.path).isURL) {
-      await exists(userConfig.input.path)
-
-      await events.emit('debug', {
-        date: new Date(),
-        logs: [`✓ Input file validated: ${userConfig.input.path}`],
-      })
-    }
-  } catch (caughtError) {
-    if (isInputPath(userConfig)) {
-      const error = caughtError as Error
-
-      throw new Error(
-        `Cannot read file/URL defined in \`input.path\` or set with \`kubb generate PATH\` in the CLI of your Kubb config ${userConfig.input.path}`,
-        {
-          cause: error,
-        },
-      )
-    }
-  }
-
-  const definedConfig: Config = {
-    root: userConfig.root || process.cwd(),
-    ...userConfig,
-    output: {
-      write: true,
-      barrelType: 'named',
-      extension: DEFAULT_EXTENSION,
-      defaultBanner: DEFAULT_BANNER,
-      ...userConfig.output,
-    },
-    devtools: userConfig.devtools
-      ? {
-          studioUrl: DEFAULT_STUDIO_URL,
-          ...(typeof userConfig.devtools === 'boolean' ? {} : userConfig.devtools),
-        }
-      : undefined,
-    plugins: userConfig.plugins as Config['plugins'],
-  }
-
-  // write: false is the explicit dry-run opt-out; otherwise use the provided
-  // storage or fall back to fsStorage (backwards-compatible default).
-  // Keys are root-relative (e.g. `src/gen/api/getPets.ts`) so fsStorage()
-  // needs no configuration — it resolves them against process.cwd().
-  const storage: DefineStorage | null = definedConfig.output.write === false ? null : (definedConfig.output.storage ?? fsStorage())
-
-  if (definedConfig.output.clean) {
-    await events.emit('debug', {
-      date: new Date(),
-      logs: ['Cleaning output directories', `  • Output: ${definedConfig.output.path}`],
-    })
-    await storage?.clear(resolve(definedConfig.root, definedConfig.output.path))
-  }
-
-  const fabric = createFabric()
-  fabric.use(fsPlugin)
-  fabric.use(typescriptParser)
-
-  fabric.context.on('files:processing:start', (files) => {
-    events.emit('files:processing:start', files)
-    events.emit('debug', {
-      date: new Date(),
-      logs: [`Writing ${files.length} files...`],
-    })
-  })
-
-  fabric.context.on('file:processing:update', async (params) => {
-    const { file, source } = params
-    await events.emit('file:processing:update', {
-      ...params,
-      config: definedConfig,
-      source,
-    })
-
-    if (source) {
-      // Key is root-relative so it's meaningful for any backend (fs, S3, Redis…)
-      const key = relative(resolve(definedConfig.root), file.path)
-      await storage?.setItem(key, source)
-      sources.set(file.path, source)
-    }
-  })
-
-  fabric.context.on('files:processing:end', async (files) => {
-    await events.emit('files:processing:end', files)
-    await events.emit('debug', {
-      date: new Date(),
-      logs: [`✓ File write process completed for ${files.length} files`],
-    })
-  })
-
-  await events.emit('debug', {
-    date: new Date(),
-    logs: [
-      '✓ Fabric initialized',
-      `  • Storage: ${storage ? storage.name : 'disabled (dry-run)'}`,
-      `  • Barrel type: ${definedConfig.output.barrelType || 'none'}`,
-    ],
-  })
-
-  const pluginManager = new PluginManager(definedConfig, {
-    fabric,
-    events,
-    concurrency: DEFAULT_CONCURRENCY,
-  })
-
-  // Run the adapter (if provided) to produce the universal RootNode
-  if (definedConfig.adapter) {
-    const source = inputToAdapterSource(definedConfig)
-
-    await events.emit('debug', {
-      date: new Date(),
-      logs: [`Running adapter: ${definedConfig.adapter.name}`],
-    })
-
-    pluginManager.adapter = definedConfig.adapter
-    pluginManager.rootNode = await definedConfig.adapter.parse(source)
-
-    await events.emit('debug', {
-      date: new Date(),
-      logs: [
-        `✓ Adapter '${definedConfig.adapter.name}' resolved RootNode`,
-        `  • Schemas: ${pluginManager.rootNode.schemas.length}`,
-        `  • Operations: ${pluginManager.rootNode.operations.length}`,
-      ],
-    })
-  }
-
-  return {
-    events,
-    fabric,
-    pluginManager,
-    sources,
-  }
-}
-
-export async function build(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const { fabric, files, pluginManager, failedPlugins, pluginTimings, error, sources } = await safeBuild(options, overrides)
-
-  if (error) {
-    throw error
-  }
-
-  if (failedPlugins.size > 0) {
-    const errors = [...failedPlugins].map(({ error }) => error)
-
-    throw new BuildError(`Build Error with ${failedPlugins.size} failed plugins`, { errors })
-  }
-
-  return {
-    failedPlugins,
-    fabric,
-    files,
-    pluginManager,
-    pluginTimings,
-    error: undefined,
-    sources,
-  }
-}
-
-export async function safeBuild(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const { fabric, pluginManager, events, sources } = overrides ? overrides : await setup(options)
-
-  const failedPlugins = new Set<{ plugin: Plugin; error: Error }>()
-  // in ms
-  const pluginTimings = new Map<string, number>()
-  const config = pluginManager.config
-
-  try {
-    for (const plugin of pluginManager.plugins) {
-      const context = pluginManager.getContext(plugin)
-      const hrStart = process.hrtime()
-
-      const installer = plugin.install.bind(context)
-
-      try {
-        const timestamp = new Date()
-
-        await events.emit('plugin:start', plugin)
-
-        await events.emit('debug', {
-          date: timestamp,
-          logs: ['Installing plugin...', `  • Plugin Name: ${plugin.name}`],
-        })
-
-        await installer(context)
-
-        const duration = getElapsedMs(hrStart)
-        pluginTimings.set(plugin.name, duration)
-
-        await events.emit('plugin:end', plugin, { duration, success: true })
-
-        await events.emit('debug', {
-          date: new Date(),
-          logs: [`✓ Plugin installed successfully (${formatMs(duration)})`],
-        })
-      } catch (caughtError) {
-        const error = caughtError as Error
-        const errorTimestamp = new Date()
-        const duration = getElapsedMs(hrStart)
-
-        await events.emit('plugin:end', plugin, {
-          duration,
-          success: false,
-          error,
-        })
-
-        await events.emit('debug', {
-          date: errorTimestamp,
-          logs: [
-            '✗ Plugin installation failed',
-            `  • Plugin Name: ${plugin.name}`,
-            `  • Error: ${error.constructor.name} - ${error.message}`,
-            '  • Stack Trace:',
-            error.stack || 'No stack trace available',
-          ],
-        })
-
-        failedPlugins.add({ plugin, error })
-      }
-    }
-
-    if (config.output.barrelType) {
-      const root = resolve(config.root)
-      const rootPath = resolve(root, config.output.path, BARREL_FILENAME)
-      const rootDir = dirname(rootPath)
-
-      await events.emit('debug', {
-        date: new Date(),
-        logs: ['Generating barrel file', `  • Type: ${config.output.barrelType}`, `  • Path: ${rootPath}`],
-      })
-
-      const barrelFiles = fabric.files.filter((file) => {
-        return file.sources.some((source) => source.isIndexable)
-      })
-
-      await events.emit('debug', {
-        date: new Date(),
-        logs: [`Found ${barrelFiles.length} indexable files for barrel export`],
-      })
-
-      const existingBarrel = fabric.files.find((f) => f.path === rootPath)
-      const existingExports = new Set(
-        existingBarrel?.exports?.flatMap((e) => (Array.isArray(e.name) ? e.name : [e.name])).filter((n): n is string => Boolean(n)) ?? [],
-      )
-
-      const rootFile: KubbFile.File = {
-        path: rootPath,
-        baseName: BARREL_FILENAME,
-        exports: buildBarrelExports({ barrelFiles, rootDir, existingExports, config, pluginManager }),
-        sources: [],
-        imports: [],
-        meta: {},
-      }
-
-      await fabric.upsertFile(rootFile)
-
-      await events.emit('debug', {
-        date: new Date(),
-        logs: [`✓ Generated barrel file (${rootFile.exports?.length || 0} exports)`],
-      })
-    }
-
-    const files = [...fabric.files]
-
-    await fabric.write({ extension: config.output.extension })
-
-    return {
-      failedPlugins,
-      fabric,
-      files,
-      pluginManager,
-      pluginTimings,
-      sources,
-    }
-  } catch (error) {
-    return {
-      failedPlugins,
-      fabric,
-      files: [],
-      pluginManager,
-      pluginTimings,
-      error: error as Error,
-      sources,
-    }
-  }
-}
-
-type BuildBarrelExportsParams = {
-  barrelFiles: KubbFile.ResolvedFile[]
-  rootDir: string
-  existingExports: Set<string>
-  config: Config
-  pluginManager: PluginManager
-}
-
-function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, pluginManager }: BuildBarrelExportsParams): KubbFile.Export[] {
-  const pluginNameMap = new Map<string, Plugin>()
-  for (const plugin of pluginManager.plugins) {
-    pluginNameMap.set(plugin.name, plugin)
-  }
-
-  return barrelFiles.flatMap((file) => {
-    const containsOnlyTypes = file.sources?.every((source) => source.isTypeOnly)
-
-    return (file.sources ?? []).flatMap((source) => {
-      if (!file.path || !source.isIndexable) {
-        return []
-      }
-
-      const meta = file.meta as FileMetaBase | undefined
-      const plugin = meta?.pluginName ? pluginNameMap.get(meta.pluginName) : undefined
-      const pluginOptions = plugin?.options as { output?: Output<unknown> } | undefined
-
-      if (!pluginOptions || pluginOptions.output?.barrelType === false) {
-        return []
-      }
-
-      const exportName = config.output.barrelType === 'all' ? undefined : source.name ? [source.name] : undefined
-      if (exportName?.some((n) => existingExports.has(n))) {
-        return []
-      }
-
-      return [
-        {
-          name: exportName,
-          path: getRelativePath(rootDir, file.path),
-          isTypeOnly: config.output.barrelType === 'all' ? containsOnlyTypes : source.isTypeOnly,
-        } satisfies KubbFile.Export,
-      ]
-    })
-  })
-}
-
-/**
- * Maps the resolved `Config['input']` shape into an `AdapterSource` that
- * the adapter's `parse()` can consume.
- */
-function inputToAdapterSource(config: Config): AdapterSource {
-  if (Array.isArray(config.input)) {
-    return {
-      type: 'paths',
-      paths: config.input.map((i) => resolve(config.root, i.path)),
-    }
-  }
-
-  if ('data' in config.input) {
-    return { type: 'data', data: config.input.data }
-  }
-
-  const resolved = resolve(config.root, config.input.path)
-  return { type: 'path', path: resolved }
-}

package/src/config.ts

@@ -1,56 +0,0 @@
-import type { PossiblePromise } from '@internals/utils'
-import type { InputPath, UserConfig } from './types.ts'
-
-/**
- * CLI options derived from command-line flags.
- */
-export type CLIOptions = {
-  /** Path to `kubb.config.js` */
-  config?: string
-
-  /** Enable watch mode for input files */
-  watch?: boolean
-
-  /**
-   * Logging verbosity for CLI usage.
-   *
-   * - `silent`: hide non-essential logs
-   * - `info`: show general logs (non-plugin-related)
-   * - `debug`: include detailed plugin lifecycle logs
-   * @default 'silent'
-   */
-  logLevel?: 'silent' | 'info' | 'debug'
-
-  /** Run Kubb with Bun */
-  bun?: boolean
-}
-
-/** All accepted forms of a Kubb configuration. */
-export type ConfigInput = PossiblePromise<UserConfig | UserConfig[]> | ((cli: CLIOptions) => PossiblePromise<UserConfig | UserConfig[]>)
-
-/**
- * Helper for defining a Kubb configuration.
- *
- * Accepts either:
- * - A config object or array of configs
- * - A function returning the config(s), optionally async,
- *   receiving the CLI options as argument
- *
- * @example
- * export default defineConfig(({ logLevel }) => ({
- *   root: 'src',
- *   plugins: [myPlugin()],
- * }))
- */
-export function defineConfig(config: (cli: CLIOptions) => PossiblePromise<UserConfig | UserConfig[]>): typeof config
-export function defineConfig(config: PossiblePromise<UserConfig | UserConfig[]>): typeof config
-export function defineConfig(config: ConfigInput): ConfigInput {
-  return config
-}
-
-/**
- * Type guard to check if a given config has an `input.path`.
- */
-export function isInputPath(config: UserConfig | undefined): config is UserConfig<InputPath> {
-  return typeof config?.input === 'object' && config.input !== null && 'path' in config.input
-}

package/src/defineAdapter.ts

@@ -1,22 +0,0 @@
-import type { Adapter, AdapterFactoryOptions } from './types.ts'
-
-type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
-
-/**
- * Wraps an adapter builder to make the options parameter optional.
- *
- * @example
- * ```ts
- * export const adapterOas = defineAdapter<OasAdapter>((options) => {
- *   const { validate = true, dateType = 'string' } = options
- *   return {
- *     name: adapterOasName,
- *     options: { validate, dateType, ... },
- *     parse(source) { ... },
- *   }
- * })
- * ```
- */
-export function defineAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {
-  return (options) => build(options ?? ({} as T['options']))
-}

package/src/defineStorage.ts

@@ -1,56 +0,0 @@
-/**
- * Storage interface for persisting Kubb output.
- *
- * Keys are root-relative forward-slash paths (e.g. `src/gen/api/getPets.ts`).
- * Implement this interface to route generated files to any backend — filesystem,
- * S3, Redis, in-memory, etc.
- *
- * Use `defineStorage` to create a typed storage driver.
- */
-export interface DefineStorage {
-  /** Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`). */
-  readonly name: string
-  /** Returns `true` when an entry for `key` exists in storage. */
-  hasItem(key: string): Promise<boolean>
-  /** Returns the stored string value, or `null` when `key` does not exist. */
-  getItem(key: string): Promise<string | null>
-  /** Persists `value` under `key`, creating any required structure. */
-  setItem(key: string, value: string): Promise<void>
-  /** Removes the entry for `key`. No-ops when the key does not exist. */
-  removeItem(key: string): Promise<void>
-  /** Returns all keys, optionally filtered to those starting with `base`. */
-  getKeys(base?: string): Promise<Array<string>>
-  /** Removes all entries, optionally scoped to those starting with `base`. */
-  clear(base?: string): Promise<void>
-  /** Optional teardown hook called after the build completes. */
-  dispose?(): Promise<void>
-}
-
-/**
- * Wraps a storage builder so the `options` argument is optional, following the
- * same factory pattern as `definePlugin`, `defineLogger`, and `defineAdapter`.
- *
- * The builder receives the resolved options object and must return a
- * `DefineStorage`-compatible object that includes a `name` string.
- *
- * @example
- * ```ts
- * import { defineStorage } from '@kubb/core'
- *
- * export const memoryStorage = defineStorage((_options) => {
- *   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() { return [...store.keys()] },
- *     async clear() { store.clear() },
- *   }
- * })
- * ```
- */
-export function defineStorage<TOptions = Record<string, never>>(build: (options: TOptions) => DefineStorage): (options?: TOptions) => DefineStorage {
-  return (options) => build(options ?? ({} as TOptions))
-}

package/src/errors.ts

@@ -1 +0,0 @@
-export { BuildError, ValidationPluginError } from '@internals/utils'

package/src/hooks/index.ts

@@ -1,8 +0,0 @@
-export { useKubb } from './useKubb.ts'
-
-/** @deprecated Use `useKubb` from `@kubb/core/hooks` instead */
-export { useMode } from './useMode.ts'
-/** @deprecated Use `useKubb` from `@kubb/core/hooks` instead */
-export { usePlugin } from './usePlugin.ts'
-/** @deprecated Use `useKubb` from `@kubb/core/hooks` instead */
-export { usePluginManager } from './usePluginManager.ts'

package/src/hooks/useKubb.ts

@@ -1,22 +0,0 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
-import { useApp as useAppBase } from '@kubb/react-fabric'
-import type { PluginManager } from '../PluginManager.ts'
-import type { Plugin, PluginFactoryOptions } from '../types.ts'
-
-export function useKubb<TOptions extends PluginFactoryOptions = PluginFactoryOptions>() {
-  const { meta } = useAppBase<{
-    plugin: Plugin<TOptions>
-    mode: KubbFile.Mode
-    pluginManager: PluginManager
-  }>()
-
-  return {
-    plugin: meta.plugin as Plugin<TOptions>,
-    mode: meta.mode,
-    config: meta.pluginManager.config,
-    getPluginByName: meta.pluginManager.getPluginByName.bind(meta.pluginManager),
-    getFile: meta.pluginManager.getFile.bind(meta.pluginManager),
-    resolveName: meta.pluginManager.resolveName.bind(meta.pluginManager),
-    resolvePath: meta.pluginManager.resolvePath.bind(meta.pluginManager),
-  }
-}

package/src/hooks/useMode.ts

@@ -1,11 +0,0 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
-import { useApp } from '@kubb/react-fabric'
-
-/**
- * @deprecated use `useKubb` instead
- */
-export function useMode(): KubbFile.Mode {
-  const { meta } = useApp<{ mode: KubbFile.Mode }>()
-
-  return meta.mode
-}

package/src/hooks/usePlugin.ts

@@ -1,11 +0,0 @@
-import { useApp } from '@kubb/react-fabric'
-import type { Plugin, PluginFactoryOptions } from '../types.ts'
-
-/**
- * @deprecated use useApp instead
- */
-export function usePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(): Plugin<TOptions> {
-  const { meta } = useApp<{ plugin: Plugin<TOptions> }>()
-
-  return meta.plugin
-}

package/src/hooks/usePluginManager.ts

@@ -1,11 +0,0 @@
-import { useApp } from '@kubb/react-fabric'
-import type { PluginManager } from '../PluginManager.ts'
-
-/**
- * @deprecated use `useKubb` instead
- */
-export function usePluginManager(): PluginManager {
-  const { meta } = useApp<{ pluginManager: PluginManager }>()
-
-  return meta.pluginManager
-}