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

package/src/{PluginManager.ts → PluginDriver.ts}

@@ -1,14 +1,12 @@
 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'
+import { isPromiseRejectedResult, transformReservedWord } from '@internals/utils'
 import type { RootNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Fabric } from '@kubb/react-fabric'
-import { CORE_PLUGIN_NAME, DEFAULT_STUDIO_URL } from './constants.ts'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
+import { DEFAULT_STUDIO_URL } from './constants.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
-import { ValidationPluginError } from './errors.ts'
-import { isPromiseRejectedResult, PromiseManager } from './PromiseManager.ts'
+
 import type {
   Adapter,
   Config,
@@ -23,11 +21,19 @@ import type {
   PluginWithLifeCycle,
   ResolveNameParams,
   ResolvePathParams,
-  UserPlugin,
 } from './types.ts'
+import { hookFirst, hookParallel, hookSeq } from './utils/executeStrategies.ts'
 
 type RequiredPluginLifecycle = Required<PluginLifecycle>
 
+/**
+ * Hook dispatch strategy used by the `PluginDriver`.
+ *
+ * - `hookFirst` — stops at the first non-null result.
+ * - `hookForPlugin` — calls only the matching plugin.
+ * - `hookParallel` — calls all plugins concurrently.
+ * - `hookSeq` — calls all plugins in order, threading the result.
+ */
 export type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookSeq'
 
 type ParseResult<H extends PluginLifecycleHooks> = RequiredPluginLifecycle[H]
@@ -40,7 +46,7 @@ type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseRe
 // inspired by: https://github.com/rollup/rollup/blob/master/src/utils/PluginDriver.ts#
 
 type Options = {
-  fabric: Fabric
+  fabric: FabricType
   events: AsyncEventEmitter<KubbEvents>
   /**
    * @default Number.POSITIVE_INFINITY
@@ -48,22 +54,36 @@ type Options = {
   concurrency?: number
 }
 
-type GetFileProps<TOptions = object> = {
+/**
+ * Parameters accepted by `PluginDriver.getFile` to resolve a generated file descriptor.
+ */
+export type GetFileOptions<TOptions = object> = {
   name: string
-  mode?: KubbFile.Mode
-  extname: KubbFile.Extname
+  mode?: FabricFile.Mode
+  extname: FabricFile.Extname
   pluginName: string
   options?: TOptions
 }
 
-export function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode {
+/**
+ * Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
+ *
+ * @example
+ * ```ts
+ * getMode('src/gen/types.ts')  // 'single'
+ * getMode('src/gen/types')     // 'split'
+ * ```
+ */
+export function getMode(fileOrFolder: string | undefined | null): FabricFile.Mode {
   if (!fileOrFolder) {
     return 'split'
   }
   return extname(fileOrFolder) ? 'single' : 'split'
 }
 
-export class PluginManager {
+const hookFirstNullCheck = (state: unknown) => !!(state as SafeParseResult<'resolveName'> | null)?.result
+
+export class PluginDriver {
   readonly config: Config
   readonly options: Options
 
@@ -75,21 +95,27 @@ export class PluginManager {
   adapter: Adapter | undefined = undefined
   #studioIsOpen = false
 
-  readonly #plugins = new Set<Plugin>()
-  readonly #usedPluginNames: Record<string, number> = {}
-  readonly #promiseManager
+  readonly plugins = new Map<string, Plugin>()
 
   constructor(config: Config, options: Options) {
     this.config = config
     this.options = options
-    this.#promiseManager = new PromiseManager({
-      nullCheck: (state: SafeParseResult<'resolveName'> | null) => !!state?.result,
-    })
-    ;[...(config.plugins || [])].forEach((plugin) => {
-      const parsedPlugin = this.#parse(plugin as UserPlugin)
-
-      this.#plugins.add(parsedPlugin)
-    })
+    config.plugins
+      .map((plugin) => Object.assign({ buildStart() {}, buildEnd() {} }, plugin) as unknown as Plugin)
+      .filter((plugin) => {
+        if (typeof plugin.apply === 'function') {
+          return plugin.apply(config)
+        }
+        return true
+      })
+      .sort((a, b) => {
+        if (b.pre?.includes(a.name)) return 1
+        if (b.post?.includes(a.name)) return -1
+        return 0
+      })
+      .forEach((plugin) => {
+        this.plugins.set(plugin.name, plugin)
+      })
   }
 
   get events() {
@@ -97,56 +123,75 @@ export class PluginManager {
   }
 
   getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown> {
-    const plugins = [...this.#plugins]
-    const pluginManager = this
+    const driver = this
 
     const baseContext = {
-      fabric: this.options.fabric,
-      config: this.config,
+      fabric: driver.options.fabric,
+      config: driver.config,
+      get root(): string {
+        return resolve(driver.config.root, driver.config.output.path)
+      },
+      getMode(output: { path: string }): FabricFile.Mode {
+        return getMode(resolve(driver.config.root, driver.config.output.path, output.path))
+      },
+      events: driver.options.events,
       plugin,
-      events: this.options.events,
-      pluginManager: this,
-      mode: getMode(resolve(this.config.root, this.config.output.path)),
-      addFile: async (...files: Array<KubbFile.File>) => {
+      getPlugin: driver.getPlugin.bind(driver),
+      requirePlugin: driver.requirePlugin.bind(driver),
+      driver: driver,
+      addFile: async (...files: Array<FabricFile.File>) => {
         await this.options.fabric.addFile(...files)
       },
-      upsertFile: async (...files: Array<KubbFile.File>) => {
+      upsertFile: async (...files: Array<FabricFile.File>) => {
         await this.options.fabric.upsertFile(...files)
       },
       get rootNode(): RootNode | undefined {
-        return pluginManager.rootNode
+        return driver.rootNode
       },
       get adapter(): Adapter | undefined {
-        return pluginManager.adapter
+        return driver.adapter
+      },
+      get resolver() {
+        return plugin.resolver
+      },
+      get transformer() {
+        return plugin.transformer
+      },
+      warn(message: string) {
+        driver.events.emit('warn', message)
+      },
+      error(error: string | Error) {
+        driver.events.emit('error', typeof error === 'string' ? new Error(error) : error)
+      },
+      info(message: string) {
+        driver.events.emit('info', message)
       },
       openInStudio(options?: DevtoolsOptions) {
-        if (!pluginManager.config.devtools || pluginManager.#studioIsOpen) {
+        if (!driver.config.devtools || driver.#studioIsOpen) {
           return
         }
 
-        if (typeof pluginManager.config.devtools !== 'object') {
+        if (typeof driver.config.devtools !== 'object') {
           throw new Error('Devtools must be an object')
         }
 
-        if (!pluginManager.rootNode || !pluginManager.adapter) {
+        if (!driver.rootNode || !driver.adapter) {
           throw new Error('adapter is not defined, make sure you have set the parser in kubb.config.ts')
         }
 
-        pluginManager.#studioIsOpen = true
+        driver.#studioIsOpen = true
 
-        const studioUrl = pluginManager.config.devtools?.studioUrl ?? DEFAULT_STUDIO_URL
+        const studioUrl = driver.config.devtools?.studioUrl ?? DEFAULT_STUDIO_URL
 
-        return openInStudioFn(pluginManager.rootNode, studioUrl, options)
+        return openInStudioFn(driver.rootNode, studioUrl, options)
       },
     } as unknown as PluginContext<TOptions>
 
     const mergedExtras: Record<string, unknown> = {}
-    for (const p of plugins) {
+
+    for (const p of this.plugins.values()) {
       if (typeof p.inject === 'function') {
-        const result = (p.inject as (this: PluginContext, context: PluginContext) => unknown).call(
-          baseContext as unknown as PluginContext,
-          baseContext as unknown as PluginContext,
-        )
+        const result = (p.inject as (this: PluginContext) => unknown).call(baseContext as unknown as PluginContext)
         if (result !== null && typeof result === 'object') {
           Object.assign(mergedExtras, result)
         }
@@ -158,12 +203,10 @@ export class PluginManager {
       ...mergedExtras,
     }
   }
-
-  get plugins(): Array<Plugin> {
-    return this.#getSortedPlugins()
-  }
-
-  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileProps<TOptions>): KubbFile.File<{ pluginName: string }> {
+  /**
+   * @deprecated use resolvers context instead
+   */
+  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): FabricFile.File<{ pluginName: string }> {
     const resolvedName = mode ? (mode === 'single' ? '' : this.resolveName({ name, pluginName, type: 'file' })) : name
 
     const path = this.resolvePath({
@@ -179,7 +222,7 @@ export class PluginManager {
 
     return {
       path,
-      baseName: basename(path) as KubbFile.File['baseName'],
+      baseName: basename(path) as FabricFile.File['baseName'],
       meta: {
         pluginName,
       },
@@ -189,7 +232,10 @@ export class PluginManager {
     }
   }
 
-  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
+  /**
+   * @deprecated use resolvers context instead
+   */
+  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): FabricFile.Path => {
     const root = resolve(this.config.root, this.config.output.path)
     const defaultPath = resolve(root, params.baseName)
 
@@ -210,7 +256,9 @@ export class PluginManager {
 
     return firstResult?.result || defaultPath
   }
-  //TODO refactor by using the order of plugins and the cache of the fileManager instead of guessing and recreating the name/path
+  /**
+   * @deprecated use resolvers context instead
+   */
   resolveName = (params: ResolveNameParams): string => {
     if (params.pluginName) {
       const names = this.hookForPluginSync({
@@ -219,9 +267,7 @@ export class PluginManager {
         parameters: [params.name.trim(), params.type],
       })
 
-      const uniqueNames = new Set(names)
-
-      return transformReservedWord([...uniqueNames].at(0) || params.name)
+      return transformReservedWord(names?.at(0) ?? params.name)
     }
 
     const name = this.hookFirstSync({
@@ -244,36 +290,32 @@ export class PluginManager {
     hookName: H
     parameters: PluginParameter<H>
   }): Promise<Array<ReturnType<ParseResult<H>> | null>> {
-    const plugins = this.getPluginsByName(hookName, pluginName)
+    const plugin = this.plugins.get(pluginName)
+
+    if (!plugin) {
+      return [null]
+    }
 
     this.events.emit('plugins:hook:progress:start', {
       hookName,
-      plugins,
+      plugins: [plugin],
     })
 
-    const items: Array<ReturnType<ParseResult<H>>> = []
-
-    for (const plugin of plugins) {
-      const result = await this.#execute<H>({
-        strategy: 'hookFirst',
-        hookName,
-        parameters,
-        plugin,
-      })
-
-      if (result !== undefined && result !== null) {
-        items.push(result)
-      }
-    }
+    const result = await this.#execute<H>({
+      strategy: 'hookFirst',
+      hookName,
+      parameters,
+      plugin,
+    })
 
     this.events.emit('plugins:hook:progress:end', { hookName })
 
-    return items
+    return [result]
   }
+
   /**
    * Run a specific hookName for plugin x.
    */
-
   hookForPluginSync<H extends PluginLifecycleHooks>({
     pluginName,
     hookName,
@@ -283,20 +325,20 @@ export class PluginManager {
     hookName: H
     parameters: PluginParameter<H>
   }): Array<ReturnType<ParseResult<H>>> | null {
-    const plugins = this.getPluginsByName(hookName, pluginName)
+    const plugin = this.plugins.get(pluginName)
 
-    const result = plugins
-      .map((plugin) => {
-        return this.#executeSync<H>({
-          strategy: 'hookFirst',
-          hookName,
-          parameters,
-          plugin,
-        })
-      })
-      .filter((x): x is NonNullable<typeof x> => x !== null)
+    if (!plugin) {
+      return null
+    }
 
-    return result
+    const result = this.#executeSync<H>({
+      strategy: 'hookFirst',
+      hookName,
+      parameters,
+      plugin,
+    })
+
+    return result !== null ? [result] : []
   }
 
   /**
@@ -311,9 +353,10 @@ export class PluginManager {
     parameters: PluginParameter<H>
     skipped?: ReadonlySet<Plugin> | null
   }): Promise<SafeParseResult<H>> {
-    const plugins = this.#getSortedPlugins(hookName).filter((plugin) => {
-      return skipped ? !skipped.has(plugin) : true
-    })
+    const plugins: Array<Plugin> = []
+    for (const plugin of this.plugins.values()) {
+      if (hookName in plugin && (skipped ? !skipped.has(plugin) : true)) plugins.push(plugin)
+    }
 
     this.events.emit('plugins:hook:progress:start', { hookName, plugins })
 
@@ -333,7 +376,7 @@ export class PluginManager {
       }
     })
 
-    const result = await this.#promiseManager.run('first', promises)
+    const result = await hookFirst(promises, hookFirstNullCheck)
 
     this.events.emit('plugins:hook:progress:end', { hookName })
 
@@ -353,11 +396,11 @@ export class PluginManager {
     skipped?: ReadonlySet<Plugin> | null
   }): SafeParseResult<H> | null {
     let parseResult: SafeParseResult<H> | null = null
-    const plugins = this.#getSortedPlugins(hookName).filter((plugin) => {
-      return skipped ? !skipped.has(plugin) : true
-    })
 
-    for (const plugin of plugins) {
+    for (const plugin of this.plugins.values()) {
+      if (!(hookName in plugin)) continue
+      if (skipped?.has(plugin)) continue
+
       parseResult = {
         result: this.#executeSync<H>({
           strategy: 'hookFirst',
@@ -368,9 +411,7 @@ export class PluginManager {
         plugin,
       } as SafeParseResult<H>
 
-      if (parseResult?.result != null) {
-        break
-      }
+      if (parseResult.result != null) break
     }
 
     return parseResult
@@ -386,7 +427,10 @@ export class PluginManager {
     hookName: H
     parameters?: Parameters<RequiredPluginLifecycle[H]> | undefined
   }): Promise<Awaited<TOutput>[]> {
-    const plugins = this.#getSortedPlugins(hookName)
+    const plugins: Array<Plugin> = []
+    for (const plugin of this.plugins.values()) {
+      if (hookName in plugin) plugins.push(plugin)
+    }
     this.events.emit('plugins:hook:progress:start', { hookName, plugins })
 
     const pluginStartTimes = new Map<Plugin, number>()
@@ -403,13 +447,11 @@ export class PluginManager {
       }
     })
 
-    const results = await this.#promiseManager.run('parallel', promises, {
-      concurrency: this.options.concurrency,
-    })
+    const results = await hookParallel(promises, this.options.concurrency)
 
     results.forEach((result, index) => {
       if (isPromiseRejectedResult<Error>(result)) {
-        const plugin = this.#getSortedPlugins(hookName)[index]
+        const plugin = plugins[index]
 
         if (plugin) {
           const startTime = pluginStartTimes.get(plugin) ?? performance.now()
@@ -438,7 +480,10 @@ export class PluginManager {
    * Chains plugins
    */
   async hookSeq<H extends PluginLifecycleHooks>({ hookName, parameters }: { hookName: H; parameters?: PluginParameter<H> }): Promise<void> {
-    const plugins = this.#getSortedPlugins(hookName)
+    const plugins: Array<Plugin> = []
+    for (const plugin of this.plugins.values()) {
+      if (hookName in plugin) plugins.push(plugin)
+    }
     this.events.emit('plugins:hook:progress:start', { hookName, plugins })
 
     const promises = plugins.map((plugin) => {
@@ -451,67 +496,28 @@ export class PluginManager {
         })
     })
 
-    await this.#promiseManager.run('seq', promises)
+    await hookSeq(promises)
 
     this.events.emit('plugins:hook:progress:end', { hookName })
   }
 
-  #getSortedPlugins(hookName?: keyof PluginLifecycle): Array<Plugin> {
-    const plugins = [...this.#plugins]
-
-    if (hookName) {
-      return plugins.filter((plugin) => hookName in plugin)
-    }
-    // TODO add test case for sorting with pre/post
-
-    return plugins
-      .map((plugin) => {
-        if (plugin.pre) {
-          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(', ')}'`)
-          }
-        }
-
-        return plugin
-      })
-      .sort((a, b) => {
-        if (b.pre?.includes(a.name)) {
-          return 1
-        }
-        if (b.post?.includes(a.name)) {
-          return -1
-        }
-        return 0
-      })
-  }
-
-  getPluginByName(pluginName: string): Plugin | undefined {
-    const plugins = [...this.#plugins]
-
-    return plugins.find((item) => item.name === pluginName)
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
+  getPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions> | undefined
+  getPlugin(pluginName: string): Plugin | undefined {
+    return this.plugins.get(pluginName) as Plugin | undefined
   }
 
-  getPluginsByName(hookName: keyof PluginWithLifeCycle, pluginName: string): Plugin[] {
-    const plugins = [...this.plugins]
-
-    const pluginByPluginName = plugins.filter((plugin) => hookName in plugin).filter((item) => item.name === pluginName)
-
-    if (!pluginByPluginName?.length) {
-      // fallback on the core plugin when there is no match
-
-      const corePlugin = plugins.find((plugin) => plugin.name === CORE_PLUGIN_NAME && hookName in plugin)
-
-      return corePlugin ? [corePlugin] : []
+  /**
+   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]>
+  requirePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions>
+  requirePlugin(pluginName: string): Plugin {
+    const plugin = this.plugins.get(pluginName)
+    if (!plugin) {
+      throw new Error(`[kubb] Plugin "${pluginName}" is required but not found. Make sure it is included in your Kubb config.`)
     }
-
-    return pluginByPluginName
+    return plugin
   }
 
   /**
@@ -647,22 +653,4 @@ export class PluginManager {
       return null
     }
   }
-
-  #parse(plugin: UserPlugin): Plugin {
-    const usedPluginNames = this.#usedPluginNames
-
-    setUniqueName(plugin.name, usedPluginNames)
-
-    const usageCount = usedPluginNames[plugin.name]
-    if (usageCount && usageCount > 1) {
-      throw new ValidationPluginError(
-        `Duplicate plugin "${plugin.name}" detected. Each plugin can only be used once. Use a different configuration instead of adding multiple instances of the same plugin.`,
-      )
-    }
-
-    return {
-      install() {},
-      ...plugin,
-    } as unknown as Plugin
-  }
 }