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

package/src/types.ts

@@ -1,17 +1,37 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { RootNode, SchemaNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Fabric } from '@kubb/react-fabric'
+import type { Node, OperationNode, Printer, RootNode, SchemaNode, Visitor } from '@kubb/ast/types'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
+import type { HttpMethod } from '@kubb/oas'
+import type { FabricReactNode } from '@kubb/react-fabric/types'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
-import type { DefineStorage } from './defineStorage.ts'
+import type { Storage } from './createStorage.ts'
+import type { Generator } from './defineGenerator.ts'
 import type { KubbEvents } from './Kubb.ts'
-import type { PluginManager } from './PluginManager.ts'
+import type { PluginDriver } from './PluginDriver.ts'
 
-export type { Printer, PrinterFactoryOptions } from '@kubb/ast/types'
+export type { Printer, PrinterFactoryOptions, PrinterPartial } from '@kubb/ast/types'
 
 declare global {
   namespace Kubb {
     interface PluginContext {}
+    /**
+     * Registry that maps plugin names to their `PluginFactoryOptions`.
+     * Augment this interface in each plugin's `types.ts` to enable automatic
+     * typing for `getPlugin` and `requirePlugin`.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-ts/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginRegistry {
+     *       'plugin-ts': PluginTs
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginRegistry {}
   }
 }
 
@@ -33,7 +53,7 @@ export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins'
   /**
    * An array of Kubb plugins used for generation. Each plugin may have additional configurable options (defined within the plugin itself). If a plugin relies on another plugin, an error will occur if the required dependency is missing. Refer to “pre” for more details.
    */
-  // inject needs to be omitted because else we have a clash with the PluginManager instance
+  // inject needs to be omitted because else we have a clash with the PluginDriver instance
   plugins?: Array<Omit<UnknownUserPlugin, 'inject'>>
 }
 
@@ -66,11 +86,18 @@ export type AdapterSource = { type: 'path'; path: string } | { type: 'data'; dat
  * - `TName` — unique string identifier (e.g. `'oas'`, `'asyncapi'`)
  * - `TOptions` — raw user-facing options passed to the adapter factory
  * - `TResolvedOptions` — defaults applied; what the adapter stores as `options`
+ * - `TDocument` — type of the raw source document exposed by the adapter after `parse()`
  */
-export type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions> = {
+export type AdapterFactoryOptions<
+  TName extends string = string,
+  TOptions extends object = object,
+  TResolvedOptions extends object = TOptions,
+  TDocument = unknown,
+> = {
   name: TName
   options: TOptions
   resolvedOptions: TResolvedOptions
+  document: TDocument
 }
 
 /**
@@ -92,20 +119,32 @@ 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`. */
+  /**
+   * The raw source document produced after the first `parse()` call.
+   * `undefined` before parsing; typed by the adapter's `TDocument` generic.
+   */
+  document: TOptions['document'] | null
+  rootNode: RootNode | null
+  /**
+   * Convert the raw source into a universal `RootNode`.
+   */
   parse: (source: AdapterSource) => PossiblePromise<RootNode>
   /**
-   * Extracts `KubbFile.Import` entries needed by a `SchemaNode` tree.
+   * Extracts `FabricFile.Import` entries needed by a `SchemaNode` tree.
    * Populated after the first `parse()` call. Returns an empty array before that.
    *
    * The `resolve` callback receives the collision-corrected schema name and must
    * return the `{ name, path }` pair for the import, or `undefined` to skip it.
    */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<KubbFile.Import>
+  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<FabricFile.Import>
 }
 
 export type BarrelType = 'all' | 'named' | 'propagate'
@@ -173,16 +212,16 @@ export type Config<TInput = Input> = {
     /**
      * Storage backend for generated files.
      * Defaults to `fsStorage()` — the built-in filesystem driver.
-     * Accepts any object implementing the {@link DefineStorage} interface.
+     * Accepts any object implementing the {@link Storage} interface.
      * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
      * @default fsStorage()
      * @example
      * ```ts
-     * import { defineStorage, fsStorage } from '@kubb/core'
-     * storage: defineStorage(fsStorage())
+     * import { memoryStorage } from '@kubb/core'
+     * storage: memoryStorage()
      * ```
      */
-    storage?: DefineStorage
+    storage?: Storage
     /**
      * Specifies the formatting tool to be used.
      * - 'auto' automatically detects and uses biome or prettier (in that order of preference).
@@ -207,12 +246,12 @@ export type Config<TInput = Input> = {
      * Overrides the extension for generated imports and exports. By default, each plugin adds an extension.
      * @default { '.ts': '.ts'}
      */
-    extension?: Record<KubbFile.Extname, KubbFile.Extname | ''>
+    extension?: Record<FabricFile.Extname, FabricFile.Extname | ''>
     /**
      * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
      * @default 'named'
      */
-    barrelType?: Exclude<BarrelType, 'propagate'> | false
+    barrelType?: 'all' | 'named' | false
     /**
      * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
      * - 'simple' adds banner with link to Kubb.
@@ -234,7 +273,7 @@ export type Config<TInput = Input> = {
    * Each plugin may include additional configurable options(defined in the plugin itself).
    * If a plugin depends on another plugin, an error is returned if the required dependency is missing. See pre for more details.
    */
-  plugins?: Array<Plugin>
+  plugins: Array<Plugin>
   /**
    * Devtools configuration for Kubb Studio integration.
    */
@@ -261,6 +300,74 @@ export type Config<TInput = Input> = {
 
 // plugin
 
+/**
+ * A type/string-pattern filter used for `include`, `exclude`, and `override` matching.
+ */
+type PatternFilter = {
+  type: string
+  pattern: string | RegExp
+}
+
+/**
+ * A pattern filter paired with partial option overrides to apply when the pattern matches.
+ */
+type PatternOverride<TOptions> = PatternFilter & {
+  options: Omit<Partial<TOptions>, 'override'>
+}
+
+/**
+ * Context passed to `resolver.resolveOptions` to apply include/exclude/override filtering
+ * for a given operation or schema node.
+ */
+export type ResolveOptionsContext<TOptions> = {
+  options: TOptions
+  exclude?: Array<PatternFilter>
+  include?: Array<PatternFilter>
+  override?: Array<PatternOverride<TOptions>>
+}
+
+/**
+ * Base constraint for all plugin resolver objects.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, and `resolveFile` are injected automatically
+ * by `defineResolver` — plugin authors may override them but never need to implement them
+ * from scratch.
+ *
+ * @example
+ * ```ts
+ * type MyResolver = Resolver & {
+ *   resolveName(node: SchemaNode): string
+ *   resolveTypedName(node: SchemaNode): string
+ * }
+ * ```
+ */
+export type Resolver = {
+  name: string
+  pluginName: Plugin['name']
+  default(name: ResolveNameParams['name'], type?: ResolveNameParams['type']): string
+  resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null
+  resolvePath(params: ResolverPathParams, context: ResolverContext): FabricFile.Path
+  resolveFile(params: ResolverFileParams, context: ResolverContext): FabricFile.File
+  resolveBanner(node: RootNode | null, context: ResolveBannerContext): string | undefined
+  resolveFooter(node: RootNode | null, context: ResolveBannerContext): string | undefined
+}
+
+/**
+ * The user-facing subset of a `Resolver` — everything except the four methods injected by
+ * `defineResolver` (`default`, `resolveOptions`, `resolvePath`, and `resolveFile`).
+ *
+ * All four injected methods can still be overridden by providing them explicitly in the builder.
+ *
+ * @example
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(node) { return this.default(node.name, 'function') },
+ * }))
+ * ```
+ */
+export type UserResolver = Omit<Resolver, 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>
+
 export type PluginFactoryOptions<
   /**
    * Name to be used for the plugin.
@@ -282,16 +389,20 @@ export type PluginFactoryOptions<
    * When calling `resolvePath` you can specify better types.
    */
   TResolvePathOptions extends object = object,
+  /**
+   * Resolver object that encapsulates the naming and path-resolution helpers used by this plugin.
+   * Use `defineResolver` to define the resolver object and export it alongside the plugin.
+   */
+  TResolver extends Resolver = Resolver,
 > = {
   name: TName
   options: TOptions
   resolvedOptions: TResolvedOptions
   context: TContext
   resolvePathOptions: TResolvePathOptions
+  resolver: TResolver
 }
 
-export type GetPluginFactoryOptions<TPlugin extends UserPlugin> = TPlugin extends UserPlugin<infer X> ? X : never
-
 export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
    * Unique name used for the plugin
@@ -302,7 +413,23 @@ export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOpti
   /**
    * Options set for a specific plugin(see kubb.config.js), passthrough of options.
    */
-  options: TOptions['resolvedOptions']
+  options: TOptions['resolvedOptions'] & {
+    output: Output
+    include?: Array<Include>
+    exclude: Array<Exclude>
+    override: Array<Override<TOptions['resolvedOptions']>>
+  }
+  /**
+   * The resolver for this plugin.
+   * Composed by `getPreset` from the preset resolver and the user's `resolver` partial override.
+   */
+  resolver?: TOptions['resolver']
+  /**
+   * The composed transformer for this plugin.
+   * Composed by `getPreset` from the preset's transformers and the user's `transformer` visitor.
+   * When a visitor method returns `null`/`undefined`, the preset transformer's result is used instead.
+   */
+  transformer?: Visitor
   /**
    * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
    * Can be used to validate dependent plugins.
@@ -312,12 +439,63 @@ export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOpti
    * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin is executed before these plugins.
    */
   post?: Array<string>
-  inject?: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context']
+  /**
+   * When `apply` is defined, the plugin is only activated when `apply(config)` returns `true`.
+   * Inspired by Vite's `apply` option.
+   *
+   * @example
+   * ```ts
+   * apply: (config) => config.output.path !== 'disabled'
+   * ```
+   */
+  apply?: (config: Config) => boolean
+  /**
+   * Expose shared helpers or data to all other plugins via `PluginContext`.
+   * The object returned is merged into the context that every plugin receives.
+   * Use the `declare global { namespace Kubb { interface PluginContext { … } } }` pattern
+   * to make the injected properties type-safe.
+   *
+   * @example
+   * ```ts
+   * inject() {
+   *   return { getOas: () => parseSpec(this.config) }
+   * }
+   * // Other plugins can then call `this.getOas()` inside buildStart()
+   * ```
+   */
+  inject?: (this: PluginContext<TOptions>) => TOptions['context']
 }
 
 export type UserPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = UserPlugin<TOptions> & PluginLifecycle<TOptions>
 
-export type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<any, any, any, any, any>>
+type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<string, object, object, unknown, object>>
+
+/**
+ * Handler for a single schema node. Used by the `schema` hook on a plugin.
+ */
+export type SchemaHook<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = (
+  this: GeneratorContext<TOptions>,
+  node: SchemaNode,
+  options: TOptions['resolvedOptions'],
+) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+
+/**
+ * Handler for a single operation node. Used by the `operation` hook on a plugin.
+ */
+export type OperationHook<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = (
+  this: GeneratorContext<TOptions>,
+  node: OperationNode,
+  options: TOptions['resolvedOptions'],
+) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+
+/**
+ * Handler for all collected operation nodes. Used by the `operations` hook on a plugin.
+ */
+export type OperationsHook<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = (
+  this: GeneratorContext<TOptions>,
+  nodes: Array<OperationNode>,
+  options: TOptions['resolvedOptions'],
+) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
 
 export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
@@ -337,35 +515,127 @@ export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
   /**
    * Options set for a specific plugin(see kubb.config.js), passthrough of options.
    */
-  options: TOptions['resolvedOptions']
+  options: TOptions['resolvedOptions'] & {
+    output: Output
+    include?: Array<Include>
+    exclude: Array<Exclude>
+    override: Array<Override<TOptions['resolvedOptions']>>
+  }
+  /**
+   * The resolver for this plugin.
+   * Composed by `getPreset` from the preset resolver and the user's `resolver` partial override.
+   */
+  resolver: TOptions['resolver']
+  /**
+   * The composed transformer for this plugin. Accessible via `context.transformer`.
+   * Composed by `getPreset` from the preset's transformers and the user's `transformer` visitor.
+   * When a visitor method returns `null`/`undefined`, the preset transformer's result is used instead.
+   */
+  transformer?: Visitor
 
-  install: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => PossiblePromise<void>
   /**
-   * Define a context that can be used by other plugins, see `PluginManager' where we convert from `UserPlugin` to `Plugin`(used when calling `definePlugin`).
+   * When `apply` is defined, the plugin is only activated when `apply(config)` returns `true`.
+   * Inspired by Vite's `apply` option.
+   */
+  apply?: (config: Config) => boolean
+  /**
+   * Optional semver version string for this plugin, e.g. `"1.2.3"`.
+   * Used in diagnostic messages and version-conflict detection.
+   */
+  version?: string
+
+  buildStart: (this: PluginContext<TOptions>) => PossiblePromise<void>
+  /**
+   * Called once per plugin after all files have been written to disk.
+   * Use this for post-processing, copying assets, or generating summary reports.
+   */
+  buildEnd: (this: PluginContext<TOptions>) => PossiblePromise<void>
+  /**
+   * Called for each schema node during the AST walk.
+   * Return a React element, an array of `FabricFile.File`, or `void` for manual handling.
+   * Nodes matching `exclude`/`include` filters are skipped automatically.
+   *
+   * For multiple generators, use `composeGenerators` inside the plugin factory.
+   */
+  schema?: SchemaHook<TOptions>
+  /**
+   * Called for each operation node during the AST walk.
+   * Return a React element, an array of `FabricFile.File`, or `void` for manual handling.
+   *
+   * For multiple generators, use `composeGenerators` inside the plugin factory.
+   */
+  operation?: OperationHook<TOptions>
+  /**
+   * Called once after all operations have been walked, with the full collected set.
+   *
+   * For multiple generators, use `composeGenerators` inside the plugin factory.
    */
-  inject: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context']
+  operations?: OperationsHook<TOptions>
+  /**
+   * Expose shared helpers or data to all other plugins via `PluginContext`.
+   * The returned object is merged into the context received by every plugin.
+   */
+  inject: (this: PluginContext<TOptions>) => TOptions['context']
 }
 
 export type PluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & PluginLifecycle<TOptions>
 
 export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
-   * Start of the lifecycle of a plugin.
+   * Called once per plugin at the start of its processing phase, before schema/operation/operations hooks run.
+   * Use this to set up shared state, fetch remote data, or perform any async initialization.
    * @type hookParallel
    */
-  install?: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => PossiblePromise<void>
+  buildStart?: (this: PluginContext<TOptions>) => PossiblePromise<void>
+  /**
+   * Called once per plugin after all files have been written to disk.
+   * Use this for post-processing, copying assets, or generating summary reports.
+   * @type hookParallel
+   */
+  buildEnd?: (this: PluginContext<TOptions>) => PossiblePromise<void>
+  /**
+   * Called for each schema node during the AST walk.
+   * Return a React element (`<File>...</File>`), an array of `FabricFile.File` objects,
+   * or `void` to handle file writing manually via `this.upsertFile`.
+   * Nodes matching `exclude` / `include` filters are skipped automatically.
+   *
+   * For multiple generators, use `composeGenerators` inside the plugin factory.
+   */
+  schema?: SchemaHook<TOptions>
+  /**
+   * Called for each operation node during the AST walk.
+   * Return a React element (`<File>...</File>`), an array of `FabricFile.File` objects,
+   * or `void` to handle file writing manually via `this.upsertFile`.
+   *
+   * For multiple generators, use `composeGenerators` inside the plugin factory.
+   */
+  operation?: OperationHook<TOptions>
+  /**
+   * Called once after all operation nodes have been walked, with the full collection.
+   * Useful for generating index/barrel files per group or aggregate operation handlers.
+   *
+   * For multiple generators, use `composeGenerators` inside the plugin factory.
+   */
+  operations?: OperationsHook<TOptions>
   /**
    * Resolve to a Path based on a baseName(example: `./Pet.ts`) and directory(example: `./models`).
    * Options can als be included.
    * @type hookFirst
    * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
+   * @deprecated this will be replaced by resolvers
    */
-  resolvePath?: (this: PluginContext<TOptions>, baseName: KubbFile.BaseName, mode?: KubbFile.Mode, options?: TOptions['resolvePathOptions']) => KubbFile.Path
+  resolvePath?: (
+    this: PluginContext<TOptions>,
+    baseName: FabricFile.BaseName,
+    mode?: FabricFile.Mode,
+    options?: TOptions['resolvePathOptions'],
+  ) => FabricFile.Path
   /**
    * Resolve to a name based on a string.
    * Useful when converting to PascalCase or camelCase.
    * @type hookFirst
    * @example ('pet') => 'Pet'
+   * @deprecated this will be replaced by resolvers
    */
   resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
 }
@@ -376,8 +646,8 @@ export type PluginParameter<H extends PluginLifecycleHooks> = Parameters<Require
 
 export type ResolvePathParams<TOptions = object> = {
   pluginName?: string
-  baseName: KubbFile.BaseName
-  mode?: KubbFile.Mode
+  baseName: FabricFile.BaseName
+  mode?: FabricFile.Mode
   /**
    * Options to be passed to 'resolvePath' 3th parameter
    */
@@ -399,24 +669,73 @@ export type ResolveNameParams = {
 }
 
 export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  fabric: Fabric
+  fabric: FabricType
   config: Config
-  pluginManager: PluginManager
+  /**
+   * Absolute path to the output directory for the current plugin.
+   * Shorthand for `path.resolve(config.root, config.output.path)`.
+   */
+  root: string
+  /**
+   * Returns the output mode for the given output config.
+   * Returns `'single'` when `output.path` has a file extension, `'split'` otherwise.
+   * Shorthand for `getMode(path.resolve(this.root, output.path))`.
+   */
+  getMode: (output: { path: string }) => FabricFile.Mode
+  driver: PluginDriver
+  /**
+   * Get a plugin by name. Returns the plugin typed via `Kubb.PluginRegistry` when
+   * the name is a registered key, otherwise returns the generic `Plugin`.
+   */
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
+  getPlugin(name: string): Plugin | undefined
+  /**
+   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
+   * Useful for enforcing dependencies inside `buildStart()`.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>
+  requirePlugin(name: string): Plugin
   /**
    * Only add when the file does not exist yet
    */
-  addFile: (...file: Array<KubbFile.File>) => Promise<void>
+  addFile: (...file: Array<FabricFile.File>) => Promise<void>
   /**
    * merging multiple sources into the same output file
    */
-  upsertFile: (...file: Array<KubbFile.File>) => Promise<void>
+  upsertFile: (...file: Array<FabricFile.File>) => Promise<void>
+  /**
+   * @deprecated use this.warn, this.error, this.info instead
+   */
   events: AsyncEventEmitter<KubbEvents>
-  mode: KubbFile.Mode
   /**
    * Current plugin
    */
   plugin: Plugin<TOptions>
+  /**
+   * Resolver for the current plugin. Shorthand for `plugin.resolver`.
+   */
+  resolver: TOptions['resolver']
+  /**
+   * Composed transformer for the current plugin. Shorthand for `plugin.transformer`.
+   * Apply with `transform(node, context.transformer)` to pre-process AST nodes before printing.
+   */
+  transformer: Visitor | undefined
 
+  /**
+   * Emit a warning via the build event system.
+   * Shorthand for `this.events.emit('warn', message)`.
+   */
+  warn: (message: string) => void
+  /**
+   * Emit an error via the build event system.
+   * Shorthand for `this.events.emit('error', error)`.
+   */
+  error: (error: string | Error) => void
+  /**
+   * Emit an info message via the build event system.
+   * Shorthand for `this.events.emit('info', message)`.
+   */
+  info: (message: string) => void
   /**
    * Opens the Kubb Studio URL for the current `rootNode` in the default browser.
    * Falls back to printing the URL if the browser cannot be launched.
@@ -441,10 +760,23 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
     }
 ) &
   Kubb.PluginContext
+
+/**
+ * Narrowed `PluginContext` used as the `this` type inside generator and plugin AST hook methods.
+ *
+ * Generators and the `schema`/`operation`/`operations` plugin hooks are only invoked from
+ * `runPluginAstHooks`, which already guards against a missing adapter. This type reflects
+ * that guarantee — `this.adapter` and `this.rootNode` are always defined, so no runtime
+ * checks or casts are needed inside the method bodies.
+ */
+export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Omit<PluginContext<TOptions>, 'adapter' | 'rootNode'> & {
+  adapter: Adapter
+  rootNode: RootNode
+}
 /**
  * Specify the export location for the files and define the behavior of the output
  */
-export type Output<TOptions> = {
+export type Output<_TOptions = unknown> = {
   /**
    * Path to the output folder or file that will contain the generated code
    */
@@ -457,11 +789,11 @@ export type Output<TOptions> = {
   /**
    * Add a banner text in the beginning of every file
    */
-  banner?: string | ((options: TOptions) => string)
+  banner?: string | ((node?: RootNode) => string)
   /**
    * Add a footer text in the beginning of every file
    */
-  footer?: string | ((options: TOptions) => string)
+  footer?: string | ((node?: RootNode) => string)
   /**
    * Whether to override existing external files if they already exist.
    * @default false
@@ -469,8 +801,18 @@ export type Output<TOptions> = {
   override?: boolean
 }
 
-type GroupContext = {
-  group: string
+export type UserGroup = {
+  /**
+   * Defines the type where to group the files.
+   * - 'tag' groups files by OpenAPI tags.
+   * - 'path' groups files by OpenAPI paths.
+   * @default undefined
+   */
+  type: 'tag' | 'path'
+  /**
+   * Return the name of a group based on the group name, this is used for the file and name generation.
+   */
+  name?: (context: { group: string }) => string
 }
 
 export type Group = {
@@ -482,9 +824,9 @@ export type Group = {
    */
   type: 'tag' | 'path'
   /**
-   * Return the name of a group based on the group name, this used for the file and name generation
+   * Return the name of a group based on the group name, this is used for the file and name generation.
    */
-  name?: (context: GroupContext) => string
+  name: (context: { group: string }) => string
 }
 
 export type LoggerOptions = {
@@ -497,16 +839,211 @@ export type LoggerOptions = {
 /**
  * Shared context passed to all plugins, parsers, and Fabric internals.
  */
-export interface LoggerContext extends AsyncEventEmitter<KubbEvents> {}
-
-type Install<TOptions = unknown> = (context: LoggerContext, options?: TOptions) => void | Promise<void>
+export type LoggerContext = AsyncEventEmitter<KubbEvents>
 
 export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
   name: string
-  install: Install<TOptions>
+  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>
 }
 
-export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>
+export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>
+
+/**
+ * Compatibility preset for code generation tools.
+ * - `'default'` – no compatibility adjustments (default behavior).
+ * - `'kubbV4'` – align generated names and structures with Kubb v4 output.
+ */
+export type CompatibilityPreset = 'default' | 'kubbV4'
 
-export type { DefineStorage } from './defineStorage.ts'
+export type { Storage } from './createStorage.ts'
+export type { Generator } from './defineGenerator.ts'
 export type { KubbEvents } from './Kubb.ts'
+
+/**
+ * A preset bundles a name, a resolver, optional AST transformers,
+ * and optional generators into a single reusable configuration object.
+ *
+ * @template TResolver - The concrete resolver type for this preset.
+ */
+export type Preset<TResolver extends Resolver = Resolver> = {
+  /**
+   * Unique identifier for this preset.
+   */
+  name: string
+  /**
+   * The resolver used by this preset.
+   */
+  resolver: TResolver
+  /**
+   * Optional AST visitors / transformers applied after resolving.
+   */
+  transformers?: Array<Visitor>
+  /**
+   * Optional generators used by this preset. Plugin implementations cast this
+   * to their concrete generator type.
+   */
+  generators?: Array<Generator<any>>
+  /**
+   * Optional printer factory used by this preset.
+   * The generator calls this function at render-time to produce a configured printer instance.
+   */
+  printer?: (options: any) => Printer
+}
+
+/**
+ * A named registry of presets, keyed by preset name.
+ *
+ * @template TResolver - The concrete resolver type shared by all presets in this registry.
+ * @template TName - The union of valid preset name keys.
+ */
+export type Presets<TResolver extends Resolver = Resolver> = Record<CompatibilityPreset, Preset<TResolver>>
+
+type ByTag = {
+  type: 'tag'
+  pattern: string | RegExp
+}
+
+type ByOperationId = {
+  type: 'operationId'
+  pattern: string | RegExp
+}
+
+type ByPath = {
+  type: 'path'
+  pattern: string | RegExp
+}
+
+type ByMethod = {
+  type: 'method'
+  pattern: HttpMethod | RegExp
+}
+// TODO implement as alternative for ByMethod
+// type ByMethods = {
+//   type: 'methods'
+//   pattern: Array<HttpMethod>
+// }
+
+type BySchemaName = {
+  type: 'schemaName'
+  pattern: string | RegExp
+}
+
+type ByContentType = {
+  type: 'contentType'
+  pattern: string | RegExp
+}
+
+export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  //TODO should be options: Omit<Partial<TOptions>, 'override'>
+  options: Partial<TOptions>
+}
+
+export type ResolvePathOptions = {
+  pluginName?: string
+  group?: {
+    tag?: string
+    path?: string
+  }
+  type?: ResolveNameParams['type']
+}
+
+/**
+ * File-specific parameters for `Resolver.resolvePath`.
+ *
+ * Pass alongside a `ResolverContext` to identify which file to resolve.
+ * Provide `tag` for tag-based grouping or `path` for path-based grouping.
+ *
+ * @example
+ * ```ts
+ * resolver.resolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/petsController/petTypes.ts'
+ * ```
+ */
+export type ResolverPathParams = {
+  baseName: FabricFile.BaseName
+  pathMode?: FabricFile.Mode
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string
+}
+
+/**
+ * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
+ *
+ * Describes where on disk output is rooted, which output config is active, and the optional
+ * grouping strategy that controls subdirectory layout.
+ *
+ * @example
+ * ```ts
+ * const context: ResolverContext = {
+ *   root: config.root,
+ *   output,
+ *   group,
+ * }
+ * ```
+ */
+export type ResolverContext = {
+  root: string
+  output: Output
+  group?: Group
+  /**
+   * Plugin name used to populate `meta.pluginName` on the resolved file.
+   */
+  pluginName?: string
+}
+
+/**
+ * File-specific parameters for `Resolver.resolveFile`.
+ *
+ * Pass alongside a `ResolverContext` to fully describe the file to resolve.
+ * `tag` and `path` are used only when a matching `group` is present in the context.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveFile(
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+ * ```
+ */
+export type ResolverFileParams = {
+  name: string
+  extname: FabricFile.Extname
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string
+}
+
+/**
+ * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
+ *
+ * `output` is optional — not every plugin configures a banner/footer.
+ * `config` carries the global Kubb config, used to derive the default Kubb banner.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveBanner(rootNode, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+export type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>
+  config: Config
+}