@kubb/core 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/defineGenerator.ts

@@ -0,0 +1,126 @@
+import type { PossiblePromise } from '@internals/utils'
+import type { OperationNode, SchemaNode } from '@kubb/ast/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
+import type { FabricReactNode } from '@kubb/react-fabric/types'
+import { applyHookResult } from './renderNode.tsx'
+import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
+
+export type { GeneratorContext } from './types.ts'
+
+/**
+ * A generator is a named object with optional `schema`, `operation`, and `operations`
+ * methods. Each method is called with `this = PluginContext` of the parent plugin,
+ * giving full access to `this.config`, `this.resolver`, `this.adapter`, `this.fabric`,
+ * `this.driver`, etc.
+ *
+ * Return a React element, an array of `FabricFile.File`, or `void` to handle file
+ * writing manually via `this.upsertFile`. Both React and core (non-React) generators
+ * use the same method signatures — the return type determines how output is handled.
+ *
+ * @example
+ * ```ts
+ * export const typeGenerator = defineGenerator<PluginTs>({
+ *   name: 'typescript',
+ *   schema(node, options) {
+ *     const { adapter, resolver, root } = this
+ *     return <File ...><Type node={node} resolver={resolver} /></File>
+ *   },
+ *   operation(node, options) {
+ *     return <File ...><OperationType node={node} /></File>
+ *   },
+ * })
+ * ```
+ */
+export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /** Used in diagnostic messages and debug output. */
+  name: string
+  /**
+   * Called for each schema node in the AST walk.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   * `options` contains the per-node resolved options (after exclude/include/override).
+   */
+  schema?: (
+    this: GeneratorContext<TOptions>,
+    node: SchemaNode,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+  /**
+   * Called for each operation node in the AST walk.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   */
+  operation?: (
+    this: GeneratorContext<TOptions>,
+    node: OperationNode,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+  /**
+   * Called once after all operations have been walked.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   */
+  operations?: (
+    this: GeneratorContext<TOptions>,
+    nodes: Array<OperationNode>,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+}
+
+/**
+ * Defines a generator. Returns the object as-is with correct `this` typings.
+ * No type discrimination (`type: 'react' | 'core'`) needed — `applyHookResult`
+ * handles React elements and `File[]` uniformly.
+ */
+export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generator: Generator<TOptions>): Generator<TOptions> {
+  return generator
+}
+
+/**
+ * Merges an array of generators into a single generator.
+ *
+ * The merged generator's `schema`, `operation`, and `operations` methods run
+ * the corresponding method from each input generator in sequence, applying each
+ * result via `applyHookResult`. This eliminates the need to write the loop
+ * manually in each plugin.
+ *
+ * @param generators - Array of generators to merge into a single generator.
+ *
+ * @example
+ * ```ts
+ * const merged = mergeGenerators(generators)
+ *
+ * return {
+ *   name: pluginName,
+ *   schema: merged.schema,
+ *   operation: merged.operation,
+ *   operations: merged.operations,
+ * }
+ * ```
+ */
+export function mergeGenerators<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generators: Array<Generator<TOptions>>): Generator<TOptions> {
+  return {
+    name: generators.length > 0 ? generators.map((g) => g.name).join('+') : 'merged',
+    async schema(node, options) {
+      for (const gen of generators) {
+        if (!gen.schema) continue
+        const result = await gen.schema.call(this, node, options)
+
+        await applyHookResult(result, this.fabric)
+      }
+    },
+    async operation(node, options) {
+      for (const gen of generators) {
+        if (!gen.operation) continue
+        const result = await gen.operation.call(this, node, options)
+
+        await applyHookResult(result, this.fabric)
+      }
+    },
+    async operations(nodes, options) {
+      for (const gen of generators) {
+        if (!gen.operations) continue
+        const result = await gen.operations.call(this, nodes, options)
+
+        await applyHookResult(result, this.fabric)
+      }
+    },
+  }
+}

package/src/defineLogger.ts

@@ -1,7 +1,17 @@
 import type { Logger, LoggerOptions, UserLogger } from './types.ts'
 
+/**
+ * Wraps a logger definition into a typed {@link Logger}.
+ *
+ * @example
+ * export const myLogger = defineLogger({
+ *   name: 'my-logger',
+ *   install(context, options) {
+ *     context.on('info', (message) => console.log('ℹ', message))
+ *     context.on('error', (error) => console.error('✗', error.message))
+ *   },
+ * })
+ */
 export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
-  return {
-    ...logger,
-  }
+  return logger
 }

package/src/definePresets.ts

@@ -0,0 +1,16 @@
+import type { Preset, Presets, Resolver } from './types.ts'
+
+/**
+ * Creates a typed presets registry object — a named collection of {@link Preset} entries.
+ *
+ * @example
+ * import { definePreset, definePresets } from '@kubb/core'
+ * import { resolverTsLegacy } from '@kubb/plugin-ts'
+ *
+ * export const myPresets = definePresets({
+ *   kubbV4: definePreset('kubbV4', { resolvers: [resolverTsLegacy] }),
+ * })
+ */
+export function definePresets<TResolver extends Resolver = Resolver>(presets: Presets<TResolver>): Presets<TResolver> {
+  return presets
+}

package/src/defineResolver.ts

@@ -0,0 +1,457 @@
+import path from 'node:path'
+import { camelCase, pascalCase } from '@internals/utils'
+import { isOperationNode, isSchemaNode } from '@kubb/ast'
+import type { Node, OperationNode, RootNode, SchemaNode } from '@kubb/ast/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
+import { getMode } from './PluginDriver.ts'
+import type {
+  Config,
+  PluginFactoryOptions,
+  ResolveBannerContext,
+  ResolveNameParams,
+  ResolveOptionsContext,
+  Resolver,
+  ResolverContext,
+  ResolverFileParams,
+  ResolverPathParams,
+} from './types.ts'
+
+/**
+ * Builder type for the plugin-specific resolver fields.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are optional — built-in fallbacks are injected when omitted.
+ */
+type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<
+  T['resolver'],
+  'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter' | 'name' | 'pluginName'
+> &
+  Partial<Pick<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>> & {
+    name: string
+    pluginName: T['name']
+  } & ThisType<T['resolver']>
+
+/**
+ * Checks if an operation matches a pattern for a given filter type (`tag`, `operationId`, `path`, `method`).
+ */
+function matchesOperationPattern(node: OperationNode, type: string, pattern: string | RegExp): boolean {
+  switch (type) {
+    case 'tag':
+      return node.tags.some((tag) => !!tag.match(pattern))
+    case 'operationId':
+      return !!node.operationId.match(pattern)
+    case 'path':
+      return !!node.path.match(pattern)
+    case 'method':
+      return !!(node.method.toLowerCase() as string).match(pattern)
+    case 'contentType':
+      return !!node.requestBody?.contentType?.match(pattern)
+    default:
+      return false
+  }
+}
+
+/**
+ * Checks if a schema matches a pattern for a given filter type (`schemaName`).
+ *
+ * Returns `null` when the filter type doesn't apply to schemas.
+ */
+function matchesSchemaPattern(node: SchemaNode, type: string, pattern: string | RegExp): boolean | null {
+  switch (type) {
+    case 'schemaName':
+      return node.name ? !!node.name.match(pattern) : false
+    default:
+      return null
+  }
+}
+
+/**
+ * Default name resolver used by `defineResolver`.
+ *
+ * - `camelCase` for `function` and `file` types.
+ * - `PascalCase` for `type`.
+ * - `camelCase` for everything else.
+ */
+function defaultResolver(name: ResolveNameParams['name'], type: ResolveNameParams['type']): string {
+  let resolvedName = camelCase(name)
+
+  if (type === 'file' || type === 'function') {
+    resolvedName = camelCase(name, {
+      isFile: type === 'file',
+    })
+  }
+
+  if (type === 'type') {
+    resolvedName = pascalCase(name)
+  }
+
+  return resolvedName
+}
+
+/**
+ * Default option resolver — applies include/exclude filters and merges matching override options.
+ *
+ * Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
+ *
+ * @example Include/exclude filtering
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { output: 'types' },
+ *   exclude: [{ type: 'tag', pattern: 'internal' }],
+ * })
+ * // → null when node has tag 'internal'
+ * ```
+ *
+ * @example Override merging
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { enumType: 'asConst' },
+ *   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
+ * })
+ * // → { enumType: 'enum' } when operationId matches
+ * ```
+ */
+export function defaultResolveOptions<TOptions>(
+  node: Node,
+  { options, exclude = [], include, override = [] }: ResolveOptionsContext<TOptions>,
+): TOptions | null {
+  if (isOperationNode(node)) {
+    const isExcluded = exclude.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))
+    if (isExcluded) {
+      return null
+    }
+
+    if (include && !include.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))) {
+      return null
+    }
+
+    const overrideOptions = override.find(({ type, pattern }) => matchesOperationPattern(node, type, pattern))?.options
+
+    return { ...options, ...overrideOptions }
+  }
+
+  if (isSchemaNode(node)) {
+    if (exclude.some(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)) {
+      return null
+    }
+
+    if (include) {
+      const results = include.map(({ type, pattern }) => matchesSchemaPattern(node, type, pattern))
+      const applicable = results.filter((r) => r !== null)
+      if (applicable.length > 0 && !applicable.includes(true)) {
+        return null
+      }
+    }
+
+    const overrideOptions = override.find(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)?.options
+
+    return { ...options, ...overrideOptions }
+  }
+
+  return options
+}
+
+/**
+ * Default path resolver used by `defineResolver`.
+ *
+ * - Returns the output directory in `single` mode.
+ * - Resolves into a tag- or path-based subdirectory when `group` and a `tag`/`path` value are provided.
+ * - Falls back to a flat `output/baseName` path otherwise.
+ *
+ * A custom `group.name` function overrides the default subdirectory naming.
+ * For `tag` groups the default is `${camelCase(tag)}Controller`.
+ * For `path` groups the default is the first path segment after `/`.
+ *
+ * @example Flat output
+ * ```ts
+ * defaultResolvePath({ baseName: 'petTypes.ts' }, { root: '/src', output: { path: 'types' } })
+ * // → '/src/types/petTypes.ts'
+ * ```
+ *
+ * @example Tag-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/petsController/petTypes.ts'
+ * ```
+ *
+ * @example Path-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', path: '/pets/list' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'path' } },
+ * )
+ * // → '/src/types/pets/petTypes.ts'
+ * ```
+ *
+ * @example Single-file mode
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', pathMode: 'single' },
+ *   { root: '/src', output: { path: 'types' } },
+ * )
+ * // → '/src/types'
+ * ```
+ */
+export function defaultResolvePath(
+  { baseName, pathMode, tag, path: groupPath }: ResolverPathParams,
+  { root, output, group }: ResolverContext,
+): FabricFile.Path {
+  const mode = pathMode ?? getMode(path.resolve(root, output.path))
+
+  if (mode === 'single') {
+    return path.resolve(root, output.path) as FabricFile.Path
+  }
+
+  if (group && (groupPath || tag)) {
+    return path.resolve(root, output.path, group.name({ group: group.type === 'path' ? groupPath! : tag! }), baseName) as FabricFile.Path
+  }
+
+  return path.resolve(root, output.path, baseName) as FabricFile.Path
+}
+
+/**
+ * Default file resolver used by `defineResolver`.
+ *
+ * Resolves a `FabricFile.File` by combining name resolution (`resolver.default`) with
+ * path resolution (`resolver.resolvePath`). The resolved file always has empty
+ * `sources`, `imports`, and `exports` arrays — consumers populate those separately.
+ *
+ * In `single` mode the name is omitted and the file sits directly in the output directory.
+ *
+ * @example Resolve a schema file
+ * ```ts
+ * const file = defaultResolveFile.call(resolver,
+ *   { name: 'pet', extname: '.ts' },
+ *   { root: '/src', output: { path: 'types' } },
+ * )
+ * // → { baseName: 'pet.ts', path: '/src/types/pet.ts', sources: [], ... }
+ * ```
+ *
+ * @example Resolve an operation file with tag grouping
+ * ```ts
+ * const file = defaultResolveFile.call(resolver,
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+ * ```
+ */
+export function defaultResolveFile(this: Resolver, { name, extname, tag, path: groupPath }: ResolverFileParams, context: ResolverContext): FabricFile.File {
+  const pathMode = getMode(path.resolve(context.root, context.output.path))
+  const resolvedName = pathMode === 'single' ? '' : this.default(name, 'file')
+  const baseName = `${resolvedName}${extname}` as FabricFile.BaseName
+  const filePath = this.resolvePath({ baseName, pathMode, tag, path: groupPath }, context)
+
+  return {
+    path: filePath,
+    baseName: path.basename(filePath) as FabricFile.BaseName,
+    meta: {
+      pluginName: this.pluginName,
+    },
+    sources: [],
+    imports: [],
+    exports: [],
+  }
+}
+
+/**
+ * Generates the default "Generated by Kubb" banner from config and optional node metadata.
+ */
+export function buildDefaultBanner({
+  title,
+  description,
+  version,
+  config,
+}: {
+  title?: string
+  description?: string
+  version?: string
+  config: Config
+}): string {
+  try {
+    let source = ''
+    if (Array.isArray(config.input)) {
+      const first = config.input[0]
+      if (first && 'path' in first) {
+        source = path.basename(first.path)
+      }
+    } else if ('path' in config.input) {
+      source = path.basename(config.input.path)
+    } else if ('data' in config.input) {
+      source = 'text content'
+    }
+
+    let banner = '/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n'
+
+    if (config.output.defaultBanner === 'simple') {
+      banner += '*/\n'
+      return banner
+    }
+
+    if (source) {
+      banner += `* Source: ${source}\n`
+    }
+
+    if (title) {
+      banner += `* Title: ${title}\n`
+    }
+
+    if (description) {
+      const formattedDescription = description.replace(/\n/gm, '\n* ')
+      banner += `* Description: ${formattedDescription}\n`
+    }
+
+    if (version) {
+      banner += `* OpenAPI spec version: ${version}\n`
+    }
+
+    banner += '*/\n'
+    return banner
+  } catch (_error) {
+    return '/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n*/'
+  }
+}
+
+/**
+ * Default banner resolver — returns the banner string for a generated file.
+ *
+ * A user-supplied `output.banner` overrides the default Kubb "Generated by Kubb" notice.
+ * When no `output.banner` is set, the Kubb notice is used (including `title` and `version`
+ * from the OAS spec when a `node` is provided).
+ *
+ * - When `output.banner` is a function and `node` is provided, returns `output.banner(node)`.
+ * - When `output.banner` is a function and `node` is absent, falls back to the Kubb notice.
+ * - When `output.banner` is a string, returns it directly.
+ * - When `config.output.defaultBanner` is `false`, returns `undefined`.
+ * - Otherwise returns the Kubb "Generated by Kubb" notice.
+ *
+ * @example String banner overrides default
+ * ```ts
+ * defaultResolveBanner(undefined, { output: { banner: '// my banner' }, config })
+ * // → '// my banner'
+ * ```
+ *
+ * @example Function banner with node
+ * ```ts
+ * defaultResolveBanner(rootNode, { output: { banner: (node) => `// v${node.version}` }, config })
+ * // → '// v3.0.0'
+ * ```
+ *
+ * @example No user banner — Kubb notice with OAS metadata
+ * ```ts
+ * defaultResolveBanner(rootNode, { config })
+ * // → '/** Generated by Kubb ... Title: Pet Store ... *\/'
+ * ```
+ *
+ * @example Disabled default banner
+ * ```ts
+ * defaultResolveBanner(undefined, { config: { output: { defaultBanner: false }, ...config } })
+ * // → undefined
+ * ```
+ */
+export function defaultResolveBanner(node: RootNode | undefined, { output, config }: ResolveBannerContext): string | undefined {
+  if (typeof output?.banner === 'function') {
+    return output.banner(node)
+  }
+
+  if (typeof output?.banner === 'string') {
+    return output.banner
+  }
+
+  if (config.output.defaultBanner === false) {
+    return undefined
+  }
+
+  return buildDefaultBanner({ title: node?.meta?.title, version: node?.meta?.version, config })
+}
+
+/**
+ * Default footer resolver — returns the footer string for a generated file.
+ *
+ * - When `output.footer` is a function and `node` is provided, calls it with the node.
+ * - When `output.footer` is a function and `node` is absent, returns `undefined`.
+ * - When `output.footer` is a string, returns it directly.
+ * - Otherwise returns `undefined`.
+ *
+ * @example String footer
+ * ```ts
+ * defaultResolveFooter(undefined, { output: { footer: '// end of file' }, config })
+ * // → '// end of file'
+ * ```
+ *
+ * @example Function footer with node
+ * ```ts
+ * defaultResolveFooter(rootNode, { output: { footer: (node) => `// ${node.title}` }, config })
+ * // → '// Pet Store'
+ * ```
+ */
+export function defaultResolveFooter(node: RootNode | undefined, { output }: ResolveBannerContext): string | undefined {
+  if (typeof output?.footer === 'function') {
+    return node ? output.footer(node) : undefined
+  }
+  if (typeof output?.footer === 'string') {
+    return output.footer
+  }
+  return undefined
+}
+
+/**
+ * Defines a resolver for a plugin, injecting built-in defaults for name casing,
+ * include/exclude/override filtering, path resolution, and file construction.
+ *
+ * All four defaults can be overridden by providing them in the builder function:
+ * - `default` — name casing strategy (camelCase / PascalCase)
+ * - `resolveOptions` — include/exclude/override filtering
+ * - `resolvePath` — output path computation
+ * - `resolveFile` — full `FabricFile.File` construction
+ *
+ * Methods in the builder have access to `this` (the full resolver object), so they
+ * can call other resolver methods without circular imports.
+ *
+ * @example Basic resolver with naming helpers
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(node) {
+ *     return this.default(node.name, 'function')
+ *   },
+ *   resolveTypedName(node) {
+ *     return this.default(node.name, 'type')
+ *   },
+ * }))
+ * ```
+ *
+ * @example Override resolvePath for a custom output structure
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'custom',
+ *   resolvePath({ baseName }, { root, output }) {
+ *     return path.resolve(root, output.path, 'generated', baseName)
+ *   },
+ * }))
+ * ```
+ *
+ * @example Use this.default inside a helper
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveParamName(node, param) {
+ *     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
+ *   },
+ * }))
+ * ```
+ */
+export function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'] {
+  return {
+    default: defaultResolver,
+    resolveOptions: defaultResolveOptions,
+    resolvePath: defaultResolvePath,
+    resolveFile: defaultResolveFile,
+    resolveBanner: defaultResolveBanner,
+    resolveFooter: defaultResolveFooter,
+    ...build(),
+  } as T['resolver']
+}

package/src/hooks/index.ts

@@ -1,8 +1,3 @@
-export { useKubb } from './useKubb.ts'
-
-/** @deprecated Use `useKubb` from `@kubb/core/hooks` instead */
+export { useDriver } from './useDriver.ts'
 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/useDriver.ts

@@ -0,0 +1,11 @@
+import { useFabric } from '@kubb/react-fabric'
+import type { PluginDriver } from '../PluginDriver.ts'
+
+/**
+ * @deprecated use `driver` from the generator component props instead
+ */
+export function useDriver(): PluginDriver {
+  const { meta } = useFabric<{ driver: PluginDriver }>()
+
+  return meta.driver
+}

package/src/hooks/useMode.ts

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

package/src/hooks/usePlugin.ts

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