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

package/dist/{types-B7eZvqwD.d.ts → types-Bbh1o0yW.d.ts}

@@ -1,8 +1,9 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
 import { EventEmitter } from "node:events";
 import { Fabric } from "@kubb/react-fabric";
+import { OperationNode, Printer, PrinterFactoryOptions, RootNode, SchemaNode } from "@kubb/ast/types";
 import { KubbFile } from "@kubb/fabric-core/types";
-import { Printer, PrinterFactoryOptions, RootNode } from "@kubb/ast/types";
+import { FabricReactNode } from "@kubb/react-fabric/types";
 
 //#region ../../internals/utils/dist/index.d.ts
 /**
@@ -226,6 +227,7 @@ declare class PluginManager {
    * the build pipeline after the adapter's `parse()` resolves.
    */
   rootNode: RootNode | undefined;
+  adapter: Adapter | undefined;
   constructor(config: Config, options: Options);
   get events(): AsyncEventEmitter<KubbEvents>;
   getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown>;
@@ -529,6 +531,61 @@ interface KubbEvents {
   'plugins:hook:processing:end': [meta: ExecutedMeta];
 }
 //#endregion
+//#region src/defineGenerator.d.ts
+type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config;
+  adapter: Adapter;
+  options: Plugin<TPlugin>['options'];
+  nodes: Array<OperationNode>;
+};
+type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config;
+  adapter: Adapter;
+  options: Plugin<TPlugin>['options'];
+  node: OperationNode;
+};
+type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config;
+  adapter: Adapter;
+  options: Plugin<TPlugin>['options'];
+  node: SchemaNode;
+};
+type UserCoreGeneratorV2<TPlugin extends PluginFactoryOptions> = {
+  name: string;
+  type: 'core';
+  version?: '2';
+  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
+  operation?(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
+  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
+};
+type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
+  name: string;
+  type: 'react';
+  version?: '2';
+  Operations?(props: OperationsV2Props<TPlugin>): FabricReactNode;
+  Operation?(props: OperationV2Props<TPlugin>): FabricReactNode;
+  Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode;
+};
+type CoreGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  name: string;
+  type: 'core';
+  version: '2';
+  operations(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
+  operation(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
+  schema(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
+};
+type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  name: string;
+  type: 'react';
+  version: '2';
+  Operations(props: OperationsV2Props<TPlugin>): FabricReactNode;
+  Operation(props: OperationV2Props<TPlugin>): FabricReactNode;
+  Schema(props: SchemaV2Props<TPlugin>): FabricReactNode;
+};
+type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>;
+declare function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserReactGeneratorV2<TPlugin>): ReactGeneratorV2<TPlugin>;
+declare function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserCoreGeneratorV2<TPlugin>): CoreGeneratorV2<TPlugin>;
+//#endregion
 //#region src/types.d.ts
 declare global {
   namespace Kubb {
@@ -617,6 +674,17 @@ type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
   /** Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`. */name: TOptions['name']; /** Resolved options (after defaults have been applied). */
   options: TOptions['resolvedOptions']; /** Convert the raw source into a universal `RootNode`. */
   parse: (source: AdapterSource) => PossiblePromise<RootNode>;
+  /**
+   * Extracts `KubbFile.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>;
 };
 type BarrelType = 'all' | 'named' | 'propagate';
 type DevtoolsOptions = {
@@ -905,18 +973,26 @@ type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
    * Current plugin
    */
   plugin: Plugin<TOptions>;
-  /**
-   * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
-   * Returns `undefined` when no adapter was set (legacy OAS-only usage).
-   */
-  rootNode: RootNode | undefined;
   /**
    * 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.
    * No-ops silently when no adapter has set a `rootNode`.
    */
   openInStudio: (options?: DevtoolsOptions) => Promise<void>;
-} & Kubb.PluginContext;
+} & ({
+  /**
+   * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
+   * Returns `undefined` when no adapter was set (legacy OAS-only usage).
+   */
+  rootNode: RootNode;
+  /**
+   * Return the adapter from `@kubb/ast`
+   */
+  adapter: Adapter;
+} | {
+  rootNode?: never;
+  adapter?: never;
+}) & Kubb.PluginContext;
 /**
  * Specify the export location for the files and define the behavior of the output
  */
@@ -977,5 +1053,5 @@ type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
 };
 type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>;
 //#endregion
-export { UserPluginWithLifeCycle as A, URLPath as B, PrinterFactoryOptions as C, UserConfig as D, UnknownUserPlugin as E, defineStorage as F, formatters as I, linters as L, PluginManager as M, getMode as N, UserLogger as O, DefineStorage as P, logLevel as R, Printer as S, ResolvePathParams as T, PluginFactoryOptions as _, Config as a, PluginParameter as b, Group as c, Logger as d, LoggerContext as f, PluginContext as g, Plugin as h, BarrelType as i, KubbEvents as j, UserPlugin as k, InputData as l, Output as m, AdapterFactoryOptions as n, DevtoolsOptions as o, LoggerOptions as p, AdapterSource as r, GetPluginFactoryOptions as s, Adapter as t, InputPath as u, PluginLifecycle as v, ResolveNameParams as w, PluginWithLifeCycle as x, PluginLifecycleHooks as y, AsyncEventEmitter as z };
-//# sourceMappingURL=types-B7eZvqwD.d.ts.map
+export { UserPluginWithLifeCycle as A, formatters as B, PrinterFactoryOptions as C, UserConfig as D, UnknownUserPlugin as E, KubbEvents as F, logLevel as H, PluginManager as I, getMode as L, Generator as M, ReactGeneratorV2 as N, UserLogger as O, defineGenerator as P, DefineStorage as R, Printer as S, ResolvePathParams as T, AsyncEventEmitter as U, linters as V, URLPath as W, PluginFactoryOptions as _, Config as a, PluginParameter as b, Group as c, Logger as d, LoggerContext as f, PluginContext as g, Plugin as h, BarrelType as i, CoreGeneratorV2 as j, UserPlugin as k, InputData as l, Output as m, AdapterFactoryOptions as n, DevtoolsOptions as o, LoggerOptions as p, AdapterSource as r, GetPluginFactoryOptions as s, Adapter as t, InputPath as u, PluginLifecycle as v, ResolveNameParams as w, PluginWithLifeCycle as x, PluginLifecycleHooks as y, defineStorage as z };
+//# sourceMappingURL=types-Bbh1o0yW.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.2",
+  "version": "5.0.0-alpha.4",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "typescript",
@@ -71,7 +71,7 @@
     "remeda": "^2.33.6",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "5.0.0-alpha.2"
+    "@kubb/ast": "5.0.0-alpha.4"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/PluginManager.ts

@@ -1,4 +1,4 @@
-import path from 'node:path'
+import { basename, extname, resolve } from 'node:path'
 import { performance } from 'node:perf_hooks'
 import type { AsyncEventEmitter } from '@internals/utils'
 import { setUniqueName, transformReservedWord } from '@internals/utils'
@@ -10,6 +10,7 @@ import { openInStudio as openInStudioFn } from './devtools.ts'
 import { ValidationPluginError } from './errors.ts'
 import { isPromiseRejectedResult, PromiseManager } from './PromiseManager.ts'
 import type {
+  Adapter,
   Config,
   DevtoolsOptions,
   KubbEvents,
@@ -59,7 +60,7 @@ export function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode
   if (!fileOrFolder) {
     return 'split'
   }
-  return path.extname(fileOrFolder) ? 'single' : 'split'
+  return extname(fileOrFolder) ? 'single' : 'split'
 }
 
 export class PluginManager {
@@ -71,6 +72,7 @@ export class PluginManager {
    * the build pipeline after the adapter's `parse()` resolves.
    */
   rootNode: RootNode | undefined = undefined
+  adapter: Adapter | undefined = undefined
   #studioIsOpen = false
 
   readonly #plugins = new Set<Plugin>()
@@ -104,7 +106,7 @@ export class PluginManager {
       plugin,
       events: this.options.events,
       pluginManager: this,
-      mode: getMode(path.resolve(this.config.root, this.config.output.path)),
+      mode: getMode(resolve(this.config.root, this.config.output.path)),
       addFile: async (...files: Array<KubbFile.File>) => {
         await this.options.fabric.addFile(...files)
       },
@@ -114,17 +116,20 @@ export class PluginManager {
       get rootNode(): RootNode | undefined {
         return pluginManager.rootNode
       },
+      get adapter(): Adapter | undefined {
+        return pluginManager.adapter
+      },
       openInStudio(options?: DevtoolsOptions) {
+        if (!pluginManager.config.devtools || pluginManager.#studioIsOpen) {
+          return
+        }
+
         if (typeof pluginManager.config.devtools !== 'object') {
           throw new Error('Devtools must be an object')
         }
 
-        if (!pluginManager.rootNode) {
-          throw new Error('RootNode is not defined, make sure you have set the parser in kubb.config.ts')
-        }
-
-        if (pluginManager.#studioIsOpen) {
-          return
+        if (!pluginManager.rootNode || !pluginManager.adapter) {
+          throw new Error('adapter is not defined, make sure you have set the parser in kubb.config.ts')
         }
 
         pluginManager.#studioIsOpen = true
@@ -159,16 +164,22 @@ export class PluginManager {
   }
 
   getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileProps<TOptions>): KubbFile.File<{ pluginName: string }> {
-    const baseName = `${name}${extname}` as const
-    const path = this.resolvePath({ baseName, mode, pluginName, options })
+    const resolvedName = mode ? (mode === 'single' ? '' : this.resolveName({ name, pluginName, type: 'file' })) : name
+
+    const path = this.resolvePath({
+      baseName: `${resolvedName}${extname}` as const,
+      mode,
+      pluginName,
+      options,
+    })
 
     if (!path) {
-      throw new Error(`Filepath should be defined for resolvedName "${name}" and pluginName "${pluginName}"`)
+      throw new Error(`Filepath should be defined for resolvedName "${resolvedName}" and pluginName "${pluginName}"`)
     }
 
     return {
       path,
-      baseName,
+      baseName: basename(path) as KubbFile.File['baseName'],
       meta: {
         pluginName,
       },
@@ -179,8 +190,8 @@ export class PluginManager {
   }
 
   resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
-    const root = path.resolve(this.config.root, this.config.output.path)
-    const defaultPath = path.resolve(root, params.baseName)
+    const root = resolve(this.config.root, this.config.output.path)
+    const defaultPath = resolve(root, params.baseName)
 
     if (params.pluginName) {
       const paths = this.hookForPluginSync({
@@ -456,7 +467,12 @@ export class PluginManager {
     return plugins
       .map((plugin) => {
         if (plugin.pre) {
-          const missingPlugins = plugin.pre.filter((pluginName) => !plugins.find((pluginToFind) => pluginToFind.name === pluginName))
+          let missingPlugins = plugin.pre.filter((pluginName) => !plugins.find((pluginToFind) => pluginToFind.name === pluginName))
+
+          // when adapter is set, we can ignore the depends on plugin-oas, in v5 this will not be needed anymore
+          if (missingPlugins.includes('plugin-oas') && this.adapter) {
+            missingPlugins = missingPlugins.filter((pluginName) => pluginName !== 'plugin-oas')
+          }
 
           if (missingPlugins.length > 0) {
             throw new ValidationPluginError(`The plugin '${plugin.name}' has a pre set that references missing plugins for '${missingPlugins.join(', ')}'`)

package/src/build.ts

@@ -180,6 +180,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
       logs: [`Running adapter: ${definedConfig.adapter.name}`],
     })
 
+    pluginManager.adapter = definedConfig.adapter
     pluginManager.rootNode = await definedConfig.adapter.parse(source)
 
     await events.emit('debug', {

package/src/defineGenerator.ts

@@ -0,0 +1,106 @@
+import type { OperationNode, SchemaNode } from '@kubb/ast/types'
+import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricReactNode } from '@kubb/react-fabric/types'
+import type { Adapter, Config, Plugin, PluginFactoryOptions } from './types.ts'
+
+export type Version = '1' | '2'
+
+// V2 props — fully typed with @kubb/ast (already a @kubb/core dependency)
+export type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  options: Plugin<TPlugin>['options']
+  nodes: Array<OperationNode>
+}
+
+export type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  options: Plugin<TPlugin>['options']
+  node: OperationNode
+}
+
+export type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  options: Plugin<TPlugin>['options']
+  node: SchemaNode
+}
+
+type UserCoreGeneratorV2<TPlugin extends PluginFactoryOptions> = {
+  name: string
+  type: 'core'
+  version?: '2'
+  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+  operation?(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+}
+
+type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
+  name: string
+  type: 'react'
+  version?: '2'
+  Operations?(props: OperationsV2Props<TPlugin>): FabricReactNode
+  Operation?(props: OperationV2Props<TPlugin>): FabricReactNode
+  Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode
+}
+
+export type CoreGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  name: string
+  type: 'core'
+  version: '2'
+  operations(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+  operation(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+  schema(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+}
+
+export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  name: string
+  type: 'react'
+  version: '2'
+  Operations(props: OperationsV2Props<TPlugin>): FabricReactNode
+  Operation(props: OperationV2Props<TPlugin>): FabricReactNode
+  Schema(props: SchemaV2Props<TPlugin>): FabricReactNode
+}
+
+export type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>
+
+export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
+  generator: UserReactGeneratorV2<TPlugin>,
+): ReactGeneratorV2<TPlugin>
+
+export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserCoreGeneratorV2<TPlugin>): CoreGeneratorV2<TPlugin>
+
+export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
+  generator: UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>,
+): unknown {
+  if (generator.type === 'react') {
+    return {
+      version: '2',
+      Operations() {
+        return null
+      },
+      Operation() {
+        return null
+      },
+      Schema() {
+        return null
+      },
+      ...generator,
+    }
+  }
+
+  return {
+    version: '2',
+    async operations() {
+      return []
+    },
+    async operation() {
+      return []
+    },
+    async schema() {
+      return []
+    },
+    ...generator,
+  }
+}

package/src/hooks/index.ts

@@ -1,3 +1,8 @@
+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

@@ -0,0 +1,22 @@
+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,6 +1,9 @@
 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 }>()
 

package/src/hooks/usePlugin.ts

@@ -1,6 +1,9 @@
 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> }>()
 

package/src/hooks/usePluginManager.ts

@@ -1,6 +1,9 @@
 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 }>()
 

package/src/index.ts

@@ -4,6 +4,7 @@ export { build, build as default, safeBuild, setup } from './build.ts'
 export { type CLIOptions, type ConfigInput, defineConfig, isInputPath } from './config.ts'
 export { formatters, linters, logLevel } from './constants.ts'
 export { defineAdapter } from './defineAdapter.ts'
+export { defineGenerator } from './defineGenerator.ts'
 export { defineLogger } from './defineLogger.ts'
 export { definePlugin } from './definePlugin.ts'
 export { defineStorage } from './defineStorage.ts'
@@ -20,3 +21,4 @@ export type { FileMetaBase } from './utils/getBarrelFiles.ts'
 export { getBarrelFiles } from './utils/getBarrelFiles.ts'
 export { getConfigs } from './utils/getConfigs.ts'
 export { detectLinter } from './utils/linters.ts'
+export { resolveOptions } from './utils/resolveOptions.ts'

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { RootNode } from '@kubb/ast/types'
+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 { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
@@ -98,6 +98,14 @@ export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptio
   options: TOptions['resolvedOptions']
   /** Convert the raw source into a universal `RootNode`. */
   parse: (source: AdapterSource) => PossiblePromise<RootNode>
+  /**
+   * Extracts `KubbFile.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>
 }
 
 export type BarrelType = 'all' | 'named' | 'propagate'
@@ -408,18 +416,31 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
    * Current plugin
    */
   plugin: Plugin<TOptions>
-  /**
-   * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
-   * Returns `undefined` when no adapter was set (legacy OAS-only usage).
-   */
-  rootNode: RootNode | undefined
+
   /**
    * 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.
    * No-ops silently when no adapter has set a `rootNode`.
    */
   openInStudio: (options?: DevtoolsOptions) => Promise<void>
-} & Kubb.PluginContext
+} & (
+  | {
+      /**
+       * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
+       * Returns `undefined` when no adapter was set (legacy OAS-only usage).
+       */
+      rootNode: RootNode
+      /**
+       * Return the adapter from `@kubb/ast`
+       */
+      adapter: Adapter
+    }
+  | {
+      rootNode?: never
+      adapter?: never
+    }
+) &
+  Kubb.PluginContext
 /**
  * Specify the export location for the files and define the behavior of the output
  */
@@ -487,5 +508,6 @@ export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
 
 export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>
 
+export type { CoreGeneratorV2, Generator, ReactGeneratorV2 } from './defineGenerator.ts'
 export type { DefineStorage } from './defineStorage.ts'
 export type { KubbEvents } from './Kubb.ts'

package/src/utils/resolveOptions.ts

@@ -0,0 +1,93 @@
+import { isOperationNode, isSchemaNode } from '@kubb/ast'
+import type { Node, OperationNode, SchemaNode } from '@kubb/ast/types'
+
+type FilterItem = {
+  type: string
+  pattern: string | RegExp
+}
+
+type OverrideItem<TOptions> = FilterItem & {
+  options: Partial<TOptions>
+}
+
+type ResolveOptionsContext<TOptions> = {
+  options: TOptions
+  exclude?: Array<FilterItem>
+  include?: Array<FilterItem>
+  override?: Array<OverrideItem<TOptions>>
+}
+
+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)
+    default:
+      return false
+  }
+}
+
+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
+  }
+}
+
+/**
+ * Resolves the effective plugin options for a given AST node by applying
+ * `exclude`, `include`, and `override` rules from the plugin configuration.
+ *
+ * Returns `null` when the node is excluded or not matched by `include`.
+ * Returns the merged options (base options merged with any matching `override`) otherwise.
+ *
+ * Supported filter types for `OperationNode`: `tag`, `operationId`, `path`, `method`.
+ * Supported filter types for `SchemaNode`: `schemaName`.
+ *
+ * @example
+ * const resolved = resolveOptions(operationNode, { options, exclude, include, override })
+ * if (!resolved) return // excluded
+ */
+export function resolveOptions<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
+}