@kubb/core 5.0.0-beta.3 → 5.0.0-beta.31

package/src/definePlugin.ts

@@ -1,5 +1,273 @@
-import type { KubbHooks } from './Kubb.ts'
-import type { KubbPluginSetupContext, PluginFactoryOptions } from './types.ts'
+import { extname } from 'node:path'
+import type { FileNode, HttpMethod, UserFileNode, Visitor } from '@kubb/ast'
+import type { RendererFactory } from './createRenderer.ts'
+import type { Generator } from './defineGenerator.ts'
+import type { BannerMeta, Resolver } from './defineResolver.ts'
+import type { Config, KubbHooks } from './types.ts'
+
+/**
+ * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
+ * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without requiring changes to core.
+ *
+ * @internal
+ */
+type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {}
+
+/**
+ * Output configuration shared by every plugin. Each plugin extends this with
+ * its own keys via the `Kubb.PluginOptionsRegistry.output` interface merge.
+ */
+export type Output<_TOptions = unknown> = {
+  /**
+   * Folder (or single file) where the plugin writes its generated code.
+   * Resolved against the global `output.path` set on `defineConfig`.
+   */
+  path: string
+  /**
+   * Text prepended to every generated file. Useful for license headers,
+   * lint disables, or `@ts-nocheck` directives.
+   *
+   * A string is applied to every file (including barrel and aggregation re-export files).
+   * Pass a function to compute the banner from the file's `BannerMeta` — document metadata
+   * plus per-file context (`isBarrel`, `isAggregation`, `filePath`, `baseName`) — so you can
+   * skip the banner on specific files.
+   *
+   * @example Add a directive to source files but not re-export files
+   * `banner: (meta) => (meta.isBarrel || meta.isAggregation) ? '' : "'use server'"`
+   */
+  banner?: string | ((meta: BannerMeta) => string)
+  /**
+   * Text appended at the end of every generated file. Mirror of `banner`.
+   * Pass a function to compute the footer from the file's `BannerMeta`.
+   */
+  footer?: string | ((meta: BannerMeta) => string)
+  /**
+   * Allows the plugin to overwrite hand-written files at the same path.
+   * Defaults to `false` to protect manual edits.
+   *
+   * @default false
+   */
+  override?: boolean
+} & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>
+
+/**
+ * Groups generated files into subdirectories based on an OpenAPI tag or path
+ * segment.
+ */
+export type Group = {
+  /**
+   * Property used to assign each operation to a group.
+   * - `'tag'` — uses the first tag (`operation.getTags().at(0)?.name`).
+   * - `'path'` — uses the first segment of the operation's URL.
+   */
+  type: 'tag' | 'path'
+  /**
+   * Returns the subdirectory name from the group key. Defaults to
+   * `${camelCase(group)}Controller` for tags, or the first path segment.
+   */
+  name?: (context: { group: string }) => string
+}
+
+type ByTag = {
+  /**
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   */
+  type: 'tag'
+  /**
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+type ByOperationId = {
+  /**
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   */
+  type: 'operationId'
+  /**
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+type ByPath = {
+  /**
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
+   */
+  type: 'path'
+  /**
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   */
+  pattern: string | RegExp
+}
+
+type ByMethod = {
+  /**
+   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   */
+  type: 'method'
+  /**
+   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   */
+  pattern: HttpMethod | RegExp
+}
+// TODO implement as alternative for ByMethod
+// type ByMethods = {
+//   type: 'methods'
+//   pattern: Array<HttpMethod>
+// }
+
+type BySchemaName = {
+  /**
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   */
+  type: 'schemaName'
+  /**
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+type ByContentType = {
+  /**
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   */
+  type: 'contentType'
+  /**
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+/**
+ * Filter that skips matching operations or schemas during generation. Use it
+ * to drop deprecated endpoints, internal-only schemas, or anything you do
+ * not want code generated for.
+ *
+ * @example
+ * ```ts
+ * exclude: [
+ *   { type: 'tag', pattern: 'internal' },
+ *   { type: 'path', pattern: /^\/admin/ },
+ *   { type: 'operationId', pattern: /^deprecated_/ },
+ * ]
+ * ```
+ */
+export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+/**
+ * Filter that restricts generation to operations or schemas matching at least
+ * one entry. Useful for partial builds (one tag, one API version).
+ *
+ * @example
+ * ```ts
+ * include: [
+ *   { type: 'tag', pattern: 'public' },
+ *   { type: 'path', pattern: /^\/api\/v1/ },
+ * ]
+ * ```
+ */
+export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+/**
+ * Filter paired with a partial options object. When the filter matches, the
+ * options are merged on top of the plugin defaults for that operation only.
+ * Useful for "this one tag goes to a different folder" rules.
+ *
+ * Entries are evaluated top to bottom; the first matching entry wins.
+ *
+ * @example
+ * ```ts
+ * override: [
+ *   {
+ *     type: 'tag',
+ *     pattern: 'admin',
+ *     options: { output: { path: './src/gen/admin' } },
+ *   },
+ *   {
+ *     type: 'operationId',
+ *     pattern: 'listPets',
+ *     options: { enumType: 'literal' },
+ *   },
+ * ]
+ * ```
+ */
+export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  //TODO should be options: Omit<Partial<TOptions>, 'override'>
+  options: Partial<TOptions>
+}
+
+export type PluginFactoryOptions<
+  /**
+   * Unique plugin name.
+   */
+  TName extends string = string,
+  /**
+   * User-facing plugin options.
+   */
+  TOptions extends object = object,
+  /**
+   * Plugin options after defaults are applied.
+   */
+  TResolvedOptions extends object = TOptions,
+  /**
+   * Resolver that encapsulates naming and path-resolution helpers.
+   * Define with `defineResolver` and export alongside the plugin.
+   */
+  TResolver extends Resolver = Resolver,
+> = {
+  name: TName
+  options: TOptions
+  resolvedOptions: TResolvedOptions
+  resolver: TResolver
+}
+
+/**
+ * Context for hook-style plugin `kubb:plugin:setup` handler.
+ * Provides methods to register generators, configure resolvers, transformers, and renderers.
+ */
+export type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Register a generator dynamically. Generators fire during the AST walk (schema/operation/operations)
+   * just like generators declared statically on `createPlugin`.
+   */
+  addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void
+  /**
+   * Set or override the resolver for this plugin.
+   * The resolver controls file naming and path resolution.
+   */
+  setResolver(resolver: Partial<TFactory['resolver']>): void
+  /**
+   * Set the AST transformer to pre-process nodes before they reach generators.
+   */
+  setTransformer(visitor: Visitor): void
+  /**
+   * Set the renderer factory to process JSX elements from generators.
+   */
+  setRenderer(renderer: RendererFactory): void
+  /**
+   * Set resolved options merged into the normalized plugin's `options`.
+   * Call this in `kubb:plugin:setup` to provide options generators need.
+   */
+  setOptions(options: TFactory['resolvedOptions']): void
+  /**
+   * Inject a raw file into the build output, bypassing the generation pipeline.
+   */
+  injectFile(userFileNode: UserFileNode): void
+  /**
+   * Merge a partial config update into the current build configuration.
+   */
+  updateConfig(config: Partial<Config>): void
+  /**
+   * The resolved build configuration at setup time.
+   */
+  config: Config
+  /**
+   * The plugin's user-provided options.
+   */
+  options: TFactory['options']
+}
 
 /**
  * A plugin object produced by `definePlugin`.
@@ -37,30 +305,62 @@ export type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>
    * Any event from the global `KubbHooks` map can be subscribed to here.
    */
   hooks: {
-    [K in Exclude<keyof KubbHooks, 'kubb:plugin:setup'>]?: (...args: KubbHooks[K]) => void | Promise<void>
+    [K in keyof KubbHooks as K extends 'kubb:plugin:setup' ? never : K]?: (...args: KubbHooks[K]) => void | Promise<void>
   } & {
     'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>
   }
 }
 
 /**
- * Returns `true` when `plugin` is a hook-style plugin created with `definePlugin`.
+ * Normalized plugin after setup, with runtime fields populated.
+ * For internal use only — plugins use the public `Plugin` type externally.
  *
- * Used by `PluginDriver` to distinguish hook-style plugins from legacy `createPlugin` plugins
- * so it can normalize them and register their handlers on the `AsyncEventEmitter`.
+ * @internal
  */
-export function isPlugin(plugin: unknown): plugin is Plugin {
-  return typeof plugin === 'object' && plugin !== null && 'hooks' in plugin
+export type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & {
+  options: TOptions['resolvedOptions'] & {
+    output: Output
+    include?: Array<Include>
+    exclude: Array<Exclude>
+    override: Array<Override<TOptions['resolvedOptions']>>
+  }
+  resolver: TOptions['resolver']
+  transformer?: Visitor
+  renderer?: RendererFactory
+  generators?: Array<Generator>
+  apply?: (config: Config) => boolean
+  version?: string
+}
+
+export type KubbPluginStartContext = {
+  plugin: NormalizedPlugin
+}
+
+export type KubbPluginEndContext = {
+  plugin: NormalizedPlugin
+  duration: number
+  success: boolean
+  error?: Error
+  config: Config
+  /**
+   * Returns all files currently in the file manager (lazy snapshot).
+   * Includes files added by plugins that have already run.
+   */
+  readonly files: ReadonlyArray<FileNode>
+  /**
+   * Upsert one or more files into the file manager.
+   */
+  upsertFile: (...files: Array<FileNode>) => void
 }
 
 /**
- * Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
- *
- * Handlers live in a single `hooks` object (inspired by Astro integrations).
- * All lifecycle events from `KubbHooks` are available for subscription.
+ * Wraps a plugin factory and returns a function that accepts user options and
+ * yields a fully typed `Plugin`. Lifecycle handlers go inside a single
+ * `hooks` object (inspired by Astro integrations).
  *
- * @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
- * Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
+ * Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
+ * `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
+ * convention (`plugin-react-query`, `plugin-zod`, ...).
  *
  * @example
  * ```ts
@@ -81,3 +381,18 @@ export function definePlugin<TFactory extends PluginFactoryOptions = PluginFacto
 ): (options?: TFactory['options']) => Plugin<TFactory> {
   return (options) => factory(options ?? ({} as TFactory['options']))
 }
+
+/**
+ * Detects whether an output path points at a single file (`'single'`) or a
+ * directory (`'split'`). Decided purely from the presence of a file extension.
+ *
+ * @example Directory
+ * `getMode('./types') // 'split'`
+ *
+ * @example Single file
+ * `getMode('./api.ts') // 'single'`
+ */
+export function getMode(fileOrFolder: string | undefined | null): 'single' | 'split' {
+  if (!fileOrFolder) return 'split'
+  return extname(fileOrFolder) ? 'single' : 'split'
+}