@kubb/core 5.0.0-beta.75 → 5.0.0-beta.76

package/src/createKubb.ts

@@ -1,548 +0,0 @@
-import { resolve } from 'node:path'
-import { AsyncEventEmitter, BuildError, exists, formatMs, getElapsedMs, URLPath } from '@internals/utils'
-import type { FileNode, OperationNode } from '@kubb/ast'
-import { transform, walk } from '@kubb/ast'
-import { DEFAULT_BANNER, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
-import type { RendererFactory } from './createRenderer.ts'
-import type { Generator } from './defineGenerator.ts'
-import type { Parser } from './defineParser.ts'
-import type { Plugin } from './definePlugin.ts'
-import { FileProcessor } from './FileProcessor.ts'
-import type { Kubb } from './Kubb.ts'
-import { PluginDriver } from './PluginDriver.ts'
-import { applyHookResult } from './renderNode.ts'
-import { fsStorage } from './storages/fsStorage.ts'
-import type { AdapterSource, Config, GeneratorContext, KubbHooks, Middleware, NormalizedPlugin, Storage, UserConfig } from './types.ts'
-import { getDiagnosticInfo } from './utils/diagnostics.ts'
-import { isInputPath } from './utils/isInputPath.ts'
-
-type SetupOptions = {
-  hooks?: AsyncEventEmitter<KubbHooks>
-}
-
-/**
- * Full output produced by a successful or failed build.
- */
-export type BuildOutput = {
-  /**
-   * Plugins that threw during installation, paired with the caught error.
-   */
-  failedPlugins: Set<{ plugin: Plugin; error: Error }>
-  files: Array<FileNode>
-  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<string, string>
-}
-
-type SetupResult = {
-  hooks: AsyncEventEmitter<KubbHooks>
-  driver: PluginDriver
-  sources: Map<string, string>
-  config: Config
-  storage: Storage | null
-}
-
-async function setup(userConfig: UserConfig, options: SetupOptions = {}): Promise<SetupResult> {
-  const hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
-
-  const sources: Map<string, string> = new Map<string, string>()
-  const diagnosticInfo = getDiagnosticInfo()
-
-  if (Array.isArray(userConfig.input)) {
-    await hooks.emit('kubb:warn', { message: 'This feature is still under development — use with caution' })
-  }
-
-  await hooks.emit('kubb: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.storage ? `custom(${userConfig.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 hooks.emit('kubb: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,
-        },
-      )
-    }
-  }
-
-  if (!userConfig.adapter) {
-    throw new Error('Adapter should be defined')
-  }
-
-  const config: Config = {
-    ...userConfig,
-    root: userConfig.root || process.cwd(),
-    parsers: userConfig.parsers ?? [],
-    adapter: userConfig.adapter,
-    output: {
-      format: false,
-      lint: false,
-      write: true,
-      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 unknown as Config['plugins'],
-  }
-
-  const storage: Storage | null = config.output.write === false ? null : (config.storage ?? fsStorage())
-
-  if (config.output.clean) {
-    await hooks.emit('kubb:debug', {
-      date: new Date(),
-      logs: ['Cleaning output directories', `  • Output: ${config.output.path}`],
-    })
-    await storage?.clear(resolve(config.root, config.output.path))
-  }
-
-  const driver = new PluginDriver(config, {
-    hooks,
-  })
-
-  // Register middleware hooks after all plugin hooks are registered.
-  // Because AsyncEventEmitter calls listeners in registration order,
-  // middleware hooks for any event fire after all plugin hooks for that event.
-  function registerMiddlewareHook<K extends keyof KubbHooks & string>(event: K, middlewareHooks: Middleware['hooks']) {
-    const handler = middlewareHooks[event]
-    if (handler) {
-      hooks.on(event, handler)
-    }
-  }
-
-  for (const middleware of config.middleware ?? []) {
-    for (const event of Object.keys(middleware.hooks) as Array<keyof KubbHooks & string>) {
-      registerMiddlewareHook(event, middleware.hooks)
-    }
-  }
-
-  const adapter = config.adapter
-  if (!adapter) {
-    throw new Error('No adapter configured. Please provide an adapter in your kubb.config.ts.')
-  }
-  const source = inputToAdapterSource(config)
-
-  await hooks.emit('kubb:debug', {
-    date: new Date(),
-    logs: [`Running adapter: ${adapter.name}`],
-  })
-
-  driver.adapter = adapter
-  driver.inputNode = await adapter.parse(source)
-
-  await hooks.emit('kubb:debug', {
-    date: new Date(),
-    logs: [
-      `✓ Adapter '${adapter.name}' resolved InputNode`,
-      `  • Schemas: ${driver.inputNode.schemas.length}`,
-      `  • Operations: ${driver.inputNode.operations.length}`,
-    ],
-  })
-
-  return {
-    config,
-    hooks,
-    driver,
-    sources,
-    storage,
-  }
-}
-
-/**
- * Walks the AST and dispatches nodes to a plugin's direct AST hooks
- * (`schema`, `operation`, `operations`).
- */
-async function runPluginAstHooks(plugin: NormalizedPlugin, context: GeneratorContext): Promise<void> {
-  const { adapter, inputNode, resolver, driver } = context
-  const { exclude, include, override } = plugin.options
-
-  if (!adapter || !inputNode) {
-    throw new Error(`[${plugin.name}] No adapter found. Add an OAS adapter (e.g. pluginOas()) before this plugin in your Kubb config.`)
-  }
-
-  function resolveRenderer(gen: Generator): RendererFactory | undefined {
-    return gen.renderer === null ? undefined : (gen.renderer ?? plugin.renderer ?? context.config.renderer)
-  }
-
-  const generators = plugin.generators ?? []
-  const collectedOperations: Array<OperationNode> = []
-
-  const generatorContext = {
-    ...context,
-    resolver: driver.getResolver(plugin.name),
-  }
-
-  await walk(inputNode, {
-    depth: 'shallow',
-    async schema(node) {
-      const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
-      const options = resolver.resolveOptions(transformedNode, {
-        options: plugin.options,
-        exclude,
-        include,
-        override,
-      })
-      if (options === null) return
-
-      const ctx = { ...generatorContext, options }
-
-      for (const gen of generators) {
-        if (!gen.schema) continue
-        const result = await gen.schema(transformedNode, ctx)
-        await applyHookResult(result, driver, resolveRenderer(gen))
-      }
-
-      await driver.hooks.emit('kubb:generate:schema', transformedNode, ctx)
-    },
-    async operation(node) {
-      const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
-      const options = resolver.resolveOptions(transformedNode, {
-        options: plugin.options,
-        exclude,
-        include,
-        override,
-      })
-      if (options !== null) {
-        collectedOperations.push(transformedNode)
-
-        const ctx = { ...generatorContext, options }
-
-        for (const gen of generators) {
-          if (!gen.operation) continue
-          const result = await gen.operation(transformedNode, ctx)
-          await applyHookResult(result, driver, resolveRenderer(gen))
-        }
-
-        await driver.hooks.emit('kubb:generate:operation', transformedNode, ctx)
-      }
-    },
-  })
-
-  if (collectedOperations.length > 0) {
-    const ctx = { ...generatorContext, options: plugin.options }
-
-    for (const gen of generators) {
-      if (!gen.operations) continue
-      const result = await gen.operations(collectedOperations, ctx)
-      await applyHookResult(result, driver, resolveRenderer(gen))
-    }
-
-    await driver.hooks.emit('kubb:generate:operations', collectedOperations, ctx)
-  }
-}
-
-async function safeBuild(setupResult: SetupResult): Promise<BuildOutput> {
-  const { driver, hooks, sources, storage } = setupResult
-
-  const failedPlugins = new Set<{ plugin: Plugin; error: Error }>()
-  const pluginTimings = new Map<string, number>()
-  const config = driver.config
-
-  try {
-    await driver.emitSetupHooks()
-
-    if (driver.adapter && driver.inputNode) {
-      await hooks.emit('kubb:build:start', {
-        config,
-        adapter: driver.adapter,
-        inputNode: driver.inputNode,
-        getPlugin: driver.getPlugin.bind(driver),
-        get files() {
-          return driver.fileManager.files
-        },
-        upsertFile: (...files) => driver.fileManager.upsert(...files),
-      })
-    }
-
-    for (const plugin of driver.plugins.values()) {
-      const context = driver.getContext(plugin)
-      const hrStart = process.hrtime()
-
-      try {
-        const timestamp = new Date()
-
-        await hooks.emit('kubb:plugin:start', { plugin })
-
-        await hooks.emit('kubb:debug', {
-          date: timestamp,
-          logs: ['Starting plugin...', `  • Plugin Name: ${plugin.name}`],
-        })
-
-        if (plugin.generators?.length || driver.hasRegisteredGenerators(plugin.name)) {
-          await runPluginAstHooks(plugin, context)
-        }
-
-        const duration = getElapsedMs(hrStart)
-        pluginTimings.set(plugin.name, duration)
-
-        await hooks.emit('kubb:plugin:end', {
-          plugin,
-          duration,
-          success: true,
-          config,
-          get files() {
-            return driver.fileManager.files
-          },
-          upsertFile: (...files) => driver.fileManager.upsert(...files),
-        })
-
-        await hooks.emit('kubb:debug', {
-          date: new Date(),
-          logs: [`✓ Plugin started successfully (${formatMs(duration)})`],
-        })
-      } catch (caughtError) {
-        const error = caughtError as Error
-        const errorTimestamp = new Date()
-        const duration = getElapsedMs(hrStart)
-
-        await hooks.emit('kubb:plugin:end', {
-          plugin,
-          duration,
-          success: false,
-          error,
-          config,
-          get files() {
-            return driver.fileManager.files
-          },
-          upsertFile: (...files) => driver.fileManager.upsert(...files),
-        })
-
-        await hooks.emit('kubb:debug', {
-          date: errorTimestamp,
-          logs: [
-            '✗ Plugin start failed',
-            `  • Plugin Name: ${plugin.name}`,
-            `  • Error: ${error.constructor.name} - ${error.message}`,
-            '  • Stack Trace:',
-            error.stack || 'No stack trace available',
-          ],
-        })
-
-        failedPlugins.add({ plugin, error })
-      }
-    }
-
-    await hooks.emit('kubb:plugins:end', {
-      config,
-      get files() {
-        return driver.fileManager.files
-      },
-      upsertFile: (...files) => driver.fileManager.upsert(...files),
-    })
-
-    const files = driver.fileManager.files
-
-    const parsersMap = new Map<FileNode['extname'], Parser>()
-    for (const parser of config.parsers) {
-      if (parser.extNames) {
-        for (const extname of parser.extNames) {
-          parsersMap.set(extname, parser)
-        }
-      }
-    }
-
-    const fileProcessor = new FileProcessor()
-
-    await hooks.emit('kubb:debug', {
-      date: new Date(),
-      logs: [`Writing ${files.length} files...`],
-    })
-
-    await fileProcessor.run(files, {
-      parsers: parsersMap,
-      extension: config.output.extension,
-      onStart: async (processingFiles) => {
-        await hooks.emit('kubb:files:processing:start', { files: processingFiles })
-      },
-      onUpdate: async ({ file, source, processed, total, percentage }) => {
-        await hooks.emit('kubb:file:processing:update', {
-          file,
-          source,
-          processed,
-          total,
-          percentage,
-          config,
-        })
-        if (source) {
-          await storage?.setItem(file.path, source)
-          sources.set(file.path, source)
-        }
-      },
-      onEnd: async (processedFiles) => {
-        await hooks.emit('kubb:files:processing:end', { files: processedFiles })
-        await hooks.emit('kubb:debug', {
-          date: new Date(),
-          logs: [`✓ File write process completed for ${processedFiles.length} files`],
-        })
-      },
-    })
-
-    await hooks.emit('kubb:build:end', {
-      files,
-      config,
-      outputDir: resolve(config.root, config.output.path),
-    })
-
-    return {
-      failedPlugins,
-      files,
-      driver,
-      pluginTimings,
-      sources,
-    }
-  } catch (error) {
-    return {
-      failedPlugins,
-      files: [],
-      driver,
-      pluginTimings,
-      error: error as Error,
-      sources,
-    }
-  } finally {
-    driver.dispose()
-  }
-}
-
-async function build(setupResult: SetupResult): Promise<BuildOutput> {
-  const { files, driver, failedPlugins, pluginTimings, error, sources } = await safeBuild(setupResult)
-
-  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,
-    files,
-    driver,
-    pluginTimings,
-    error: undefined,
-    sources,
-  }
-}
-
-function inputToAdapterSource(config: Config): AdapterSource {
-  if (Array.isArray(config.input)) {
-    return {
-      type: 'paths',
-      paths: config.input.map((i) => (new URLPath(i.path).isURL ? i.path : resolve(config.root, i.path))),
-    }
-  }
-
-  if ('data' in config.input) {
-    return { type: 'data', data: config.input.data }
-  }
-
-  if (new URLPath(config.input.path).isURL) {
-    return { type: 'path', path: config.input.path }
-  }
-
-  const resolved = resolve(config.root, config.input.path)
-  return { type: 'path', path: resolved }
-}
-
-type CreateKubbOptions = {
-  hooks?: AsyncEventEmitter<KubbHooks>
-}
-
-/**
- * Creates a Kubb instance bound to a single config entry.
- *
- * Accepts a user-facing config shape and resolves it to a full {@link Config} during
- * `setup()`. The instance then holds shared state (`hooks`, `sources`, `driver`, `config`)
- * across the `setup → build` lifecycle. Attach event listeners to `kubb.hooks` before
- * calling `setup()` or `build()`.
- *
- * @example
- * ```ts
- * const kubb = createKubb(userConfig)
- *
- * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
- *   console.log(`${plugin.name} completed in ${duration}ms`)
- * })
- *
- * const { files, failedPlugins } = await kubb.safeBuild()
- * ```
- */
-export function createKubb(userConfig: UserConfig, options: CreateKubbOptions = {}): Kubb {
-  const hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
-  let setupResult: SetupResult | undefined
-
-  const instance: Kubb = {
-    get hooks() {
-      return hooks
-    },
-    get sources() {
-      return setupResult?.sources ?? new Map()
-    },
-    get driver() {
-      return setupResult?.driver
-    },
-    get config() {
-      return setupResult?.config
-    },
-    async setup() {
-      setupResult = await setup(userConfig, { hooks })
-    },
-    async build() {
-      if (!setupResult) {
-        await instance.setup()
-      }
-      return build(setupResult!)
-    },
-    async safeBuild() {
-      if (!setupResult) {
-        await instance.setup()
-      }
-      return safeBuild(setupResult!)
-    },
-  }
-
-  return instance
-}

package/src/createRenderer.ts

@@ -1,57 +0,0 @@
-import type { FileNode } from '@kubb/ast'
-
-/**
- * Minimal interface any Kubb renderer must satisfy.
- *
- * The generic `TElement` is the type of the element the renderer accepts —
- * e.g. `KubbReactElement` for `@kubb/renderer-jsx`, or a custom type for
- * your own renderer.  Defaults to `unknown` so that generators which do not
- * care about the element type continue to work without specifying it.
- *
- * This allows core to drive rendering without a hard dependency on
- * `@kubb/renderer-jsx` or any specific renderer implementation.
- */
-export type Renderer<TElement = unknown> = {
-  render(element: TElement): Promise<void>
-  unmount(error?: Error | number | null): void
-  readonly files: Array<FileNode>
-}
-
-/**
- * A factory function that produces a fresh {@link Renderer} per render.
- *
- * Generators use this to declare which renderer handles their output.
- */
-export type RendererFactory<TElement = unknown> = () => Renderer<TElement>
-
-/**
- * Creates a renderer factory for use in generator definitions.
- *
- * Wrap your renderer factory function with this helper to register it as the
- * renderer for a generator. Core will call this factory once per render cycle
- * to obtain a fresh renderer instance.
- *
- * @example
- * ```ts
- * // packages/renderer-jsx/src/index.ts
- * export const jsxRenderer = createRenderer(() => {
- *   const runtime = new Runtime()
- *   return {
- *     async render(element) { await runtime.render(element) },
- *     get files() { return runtime.nodes },
- *     unmount(error) { runtime.unmount(error) },
- *   }
- * })
- *
- * // packages/plugin-zod/src/generators/zodGenerator.tsx
- * import { jsxRenderer } from '@kubb/renderer-jsx'
- * export const zodGenerator = defineGenerator<PluginZod>({
- *   name: 'zod',
- *   renderer: jsxRenderer,
- *   schema(node, options) { return <File ...>...</File> },
- * })
- * ```
- */
-export function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement> {
-  return factory
-}

package/src/createStorage.ts

@@ -1,70 +0,0 @@
-export type Storage = {
-  /**
-   * 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>
-}
-
-/**
- * Factory for implementing custom storage backends that control where generated files are written.
- *
- * Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
- * Kubb provides filesystem and in-memory implementations out of the box.
- *
- * @note Call the returned factory with optional options to instantiate the storage adapter.
- *
- * @example
- * ```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() },
- *   }
- * })
- *
- * // Instantiate:
- * const storage = memoryStorage()
- * ```
- */
-export function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage {
-  return (options) => build(options ?? ({} as TOptions))
-}