@kubb/core 5.0.0-alpha.21 → 5.0.0-alpha.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.21",
+  "version": "5.0.0-alpha.22",
   "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.21"
+    "@kubb/ast": "5.0.0-alpha.22"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/Kubb.ts

@@ -1,4 +1,4 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 import type { Strategy } from './PluginDriver.ts'
 import type { Config, Plugin, PluginLifecycleHooks } from './types'
 
@@ -76,7 +76,7 @@ export interface KubbEvents {
   /**
    * Emitted when code generation phase completes.
    */
-  'generation:end': [config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>]
+  'generation:end': [config: Config, files: Array<FabricFile.ResolvedFile>, sources: Map<FabricFile.Path, string>]
   /**
    * Emitted with a summary of the generation results.
    * Contains summary lines, title, and success status.
@@ -160,7 +160,7 @@ export interface KubbEvents {
    * Emitted when file processing starts.
    * Contains the list of files to be processed.
    */
-  'files:processing:start': [files: Array<KubbFile.ResolvedFile>]
+  'files:processing:start': [files: Array<FabricFile.ResolvedFile>]
   /**
    * Emitted for each file being processed, providing progress updates.
    * Contains processed count, total count, percentage, and file details.
@@ -186,7 +186,7 @@ export interface KubbEvents {
       /**
        * The file being processed.
        */
-      file: KubbFile.ResolvedFile
+      file: FabricFile.ResolvedFile
       /**
        * Kubb configuration (not present in Fabric).
        * Provides access to the current config during file processing.
@@ -198,7 +198,7 @@ export interface KubbEvents {
    * Emitted when file processing completes.
    * Contains the list of processed files.
    */
-  'files:processing:end': [files: Array<KubbFile.ResolvedFile>]
+  'files:processing:end': [files: Array<FabricFile.ResolvedFile>]
 
   /**
    * Emitted when a plugin starts executing.

package/src/PluginDriver.ts

@@ -3,7 +3,7 @@ import { performance } from 'node:perf_hooks'
 import type { AsyncEventEmitter } from '@internals/utils'
 import { isPromiseRejectedResult, setUniqueName, transformReservedWord, ValidationPluginError } from '@internals/utils'
 import type { RootNode } from '@kubb/ast/types'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
 import { CORE_PLUGIN_NAME, DEFAULT_STUDIO_URL } from './constants.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
 
@@ -27,6 +27,14 @@ 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]
@@ -47,15 +55,27 @@ type Options = {
   concurrency?: number
 }
 
+/**
+ * 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'
   }
@@ -104,10 +124,10 @@ export class PluginDriver {
       events: this.options.events,
       driver: this,
       mode: getMode(resolve(this.config.root, this.config.output.path)),
-      addFile: async (...files: Array<KubbFile.File>) => {
+      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 {
@@ -160,7 +180,7 @@ export class PluginDriver {
     return this.#getSortedPlugins()
   }
 
-  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): KubbFile.File<{ pluginName: string }> {
+  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({
@@ -176,7 +196,7 @@ export class PluginDriver {
 
     return {
       path,
-      baseName: basename(path) as KubbFile.File['baseName'],
+      baseName: basename(path) as FabricFile.File['baseName'],
       meta: {
         pluginName,
       },
@@ -186,7 +206,7 @@ export class PluginDriver {
     }
   }
 
-  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
+  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): FabricFile.Path => {
     const root = resolve(this.config.root, this.config.output.path)
     const defaultPath = resolve(root, params.baseName)
 

package/src/build.ts

@@ -1,6 +1,6 @@
 import { dirname, relative, resolve } from 'node:path'
 import { AsyncEventEmitter, BuildError, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
 import { createFabric } from '@kubb/react-fabric'
 import { typescriptParser } from '@kubb/react-fabric/parsers'
 import { fsPlugin } from '@kubb/react-fabric/plugins'
@@ -26,7 +26,7 @@ type BuildOutput = {
    */
   failedPlugins: Set<{ plugin: Plugin; error: Error }>
   fabric: FabricType
-  files: Array<KubbFile.ResolvedFile>
+  files: Array<FabricFile.ResolvedFile>
   driver: PluginDriver
   /**
    * Elapsed time in milliseconds for each plugin, keyed by plugin name.
@@ -36,7 +36,7 @@ type BuildOutput = {
   /**
    * Raw generated source, keyed by absolute file path.
    */
-  sources: Map<KubbFile.Path, string>
+  sources: Map<FabricFile.Path, string>
 }
 
 /**
@@ -46,7 +46,7 @@ type SetupResult = {
   events: AsyncEventEmitter<KubbEvents>
   fabric: FabricType
   driver: PluginDriver
-  sources: Map<KubbFile.Path, string>
+  sources: Map<FabricFile.Path, string>
 }
 
 /**
@@ -63,7 +63,7 @@ type SetupResult = {
 export async function setup(options: BuildOptions): Promise<SetupResult> {
   const { config: userConfig, events = new AsyncEventEmitter<KubbEvents>() } = options
 
-  const sources: Map<KubbFile.Path, string> = new Map<KubbFile.Path, string>()
+  const sources: Map<FabricFile.Path, string> = new Map<FabricFile.Path, string>()
   const diagnosticInfo = getDiagnosticInfo()
 
   if (Array.isArray(userConfig.input)) {
@@ -351,7 +351,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
         existingBarrel?.exports?.flatMap((e) => (Array.isArray(e.name) ? e.name : [e.name])).filter((n): n is string => Boolean(n)) ?? [],
       )
 
-      const rootFile: KubbFile.File = {
+      const rootFile: FabricFile.File = {
         path: rootPath,
         baseName: BARREL_FILENAME,
         exports: buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }),
@@ -394,14 +394,14 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 }
 
 type BuildBarrelExportsParams = {
-  barrelFiles: KubbFile.ResolvedFile[]
+  barrelFiles: FabricFile.ResolvedFile[]
   rootDir: string
   existingExports: Set<string>
   config: Config
   driver: PluginDriver
 }
 
-function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }: BuildBarrelExportsParams): KubbFile.Export[] {
+function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }: BuildBarrelExportsParams): FabricFile.Export[] {
   const pluginNameMap = new Map<string, Plugin>()
   for (const plugin of driver.plugins) {
     pluginNameMap.set(plugin.name, plugin)
@@ -433,7 +433,7 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, dri
           name: exportName,
           path: getRelativePath(rootDir, file.path),
           isTypeOnly: config.output.barrelType === 'all' ? containsOnlyTypes : source.isTypeOnly,
-        } satisfies KubbFile.Export,
+        } satisfies FabricFile.Export,
       ]
     })
   })

package/src/constants.ts

@@ -1,4 +1,4 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 
 /**
  * Base URL for the Kubb Studio web app.
@@ -33,7 +33,7 @@ export const DEFAULT_BANNER = 'simple' as const
 /**
  * Default file-extension mapping used when no explicit mapping is configured.
  */
-export const DEFAULT_EXTENSION: Record<KubbFile.Extname, KubbFile.Extname | ''> = { '.ts': '.ts' }
+export const DEFAULT_EXTENSION: Record<FabricFile.Extname, FabricFile.Extname | ''> = { '.ts': '.ts' }
 
 /**
  * Characters recognized as path separators on both POSIX and Windows.

package/src/defineGenerator.ts

@@ -1,5 +1,5 @@
 import type { OperationNode, SchemaNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 import type { FabricReactNode } from '@kubb/react-fabric/types'
 import type { Adapter, Config, Plugin, PluginFactoryOptions } from './types.ts'
 
@@ -38,15 +38,21 @@ export type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOp
   node: SchemaNode
 }
 
+/**
+ * Input shape for a core v2 async generator — lifecycle methods are optional.
+ */
 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>>
+  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  operation?(props: OperationV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<FabricFile.File>>
 }
 
+/**
+ * Input shape for a React v2 generator — component methods are optional.
+ */
 type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
   name: string
   type: 'react'
@@ -56,15 +62,21 @@ type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
   Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode
 }
 
+/**
+ * A fully resolved core v2 generator with `version: '2'` and guaranteed async lifecycle methods.
+ */
 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>>
+  operations(props: OperationsV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  operation(props: OperationV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  schema(props: SchemaV2Props<TPlugin>): Promise<Array<FabricFile.File>>
 }
 
+/**
+ * A fully resolved React v2 generator with `version: '2'` and guaranteed component methods.
+ */
 export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
   name: string
   type: 'react'
@@ -74,6 +86,9 @@ export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactor
   Schema(props: SchemaV2Props<TPlugin>): FabricReactNode
 }
 
+/**
+ * Union of all v2 generator shapes accepted by the plugin system.
+ */
 export type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>
 
 /**

package/src/defineResolver.ts

@@ -2,7 +2,7 @@ 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 { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 import { getMode } from './PluginDriver.ts'
 import type {
   Config,
@@ -193,11 +193,14 @@ export function defaultResolveOptions<TOptions>(
  * // → '/src/types'
  * ```
  */
-export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }: ResolverPathParams, { root, output, group }: ResolverContext): KubbFile.Path {
+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 KubbFile.Path
+    return path.resolve(root, output.path) as FabricFile.Path
   }
 
   if (group && (groupPath || tag)) {
@@ -210,16 +213,16 @@ export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }:
           return `${camelCase(ctx.group)}Controller`
         }
 
-    return path.resolve(root, output.path, groupName({ group: group.type === 'path' ? groupPath! : tag! }), baseName) as KubbFile.Path
+    return path.resolve(root, output.path, groupName({ group: group.type === 'path' ? groupPath! : tag! }), baseName) as FabricFile.Path
   }
 
-  return path.resolve(root, output.path, baseName) as KubbFile.Path
+  return path.resolve(root, output.path, baseName) as FabricFile.Path
 }
 
 /**
  * Default file resolver used by `defineResolver`.
  *
- * Resolves a `KubbFile.File` by combining name resolution (`resolver.default`) with
+ * 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.
  *
@@ -243,15 +246,15 @@ export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }:
  * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
  * ```
  */
-export function defaultResolveFile(this: Resolver, { name, extname, tag, path: groupPath }: ResolverFileParams, context: ResolverContext): KubbFile.File {
+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 KubbFile.BaseName
+  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 KubbFile.BaseName,
+    baseName: path.basename(filePath) as FabricFile.BaseName,
     meta: {
       pluginName: this.pluginName,
     },
@@ -397,7 +400,7 @@ export function defaultResolveFooter(node: RootNode | undefined, { output }: Res
  * - `default` — name casing strategy (camelCase / PascalCase)
  * - `resolveOptions` — include/exclude/override filtering
  * - `resolvePath` — output path computation
- * - `resolveFile` — full `KubbFile.File` construction
+ * - `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.

package/src/hooks/useDriver.ts

@@ -1,6 +1,11 @@
 import { useFabric } from '@kubb/react-fabric'
 import type { PluginDriver } from '../PluginDriver.ts'
 
+/**
+ * Returns the `PluginDriver` instance from Fabric context.
+ *
+ * Use this inside React generator components to access the driver, config, and adapter.
+ */
 export function useDriver(): PluginDriver {
   const { meta } = useFabric<{ driver: PluginDriver }>()
 

package/src/hooks/useMode.ts

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

package/src/types.ts

@@ -1,6 +1,6 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
 import type { Node, RootNode, SchemaNode, Visitor } from '@kubb/ast/types'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
 import type { HttpMethod } from '@kubb/oas'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
 import type { Storage } from './createStorage.ts'
@@ -119,13 +119,13 @@ export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptio
    */
   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'
@@ -227,7 +227,7 @@ 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'
@@ -281,15 +281,25 @@ 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>
@@ -317,8 +327,8 @@ export type Resolver = {
   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): KubbFile.Path
-  resolveFile(params: ResolverFileParams, context: ResolverContext): KubbFile.File
+  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
 }
@@ -458,7 +468,12 @@ export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactor
    * @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.
@@ -475,8 +490,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
    */
@@ -504,13 +519,13 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
   /**
    * 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>
   events: AsyncEventEmitter<KubbEvents>
-  mode: KubbFile.Mode
+  mode: FabricFile.Mode
   /**
    * Current plugin
    */
@@ -714,8 +729,8 @@ export type ResolvePathOptions = {
  * ```
  */
 export type ResolverPathParams = {
-  baseName: KubbFile.BaseName
-  pathMode?: KubbFile.Mode
+  baseName: FabricFile.BaseName
+  pathMode?: FabricFile.Mode
   /**
    * Tag value used when `group.type === 'tag'`.
    */
@@ -745,7 +760,9 @@ export type ResolverContext = {
   root: string
   output: Output
   group?: Group
-  /** Plugin name used to populate `meta.pluginName` on the resolved file. */
+  /**
+   * Plugin name used to populate `meta.pluginName` on the resolved file.
+   */
   pluginName?: string
 }
 
@@ -766,10 +783,14 @@ export type ResolverContext = {
  */
 export type ResolverFileParams = {
   name: string
-  extname: KubbFile.Extname
-  /** Tag value used when `group.type === 'tag'`. */
+  extname: FabricFile.Extname
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
   tag?: string
-  /** Path value used when `group.type === 'path'`. */
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
   path?: string
 }
 

package/src/utils/TreeNode.ts

@@ -1,20 +1,20 @@
 import path from 'node:path'
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 import { getMode } from '../PluginDriver.ts'
 
 type BarrelData = {
-  file?: KubbFile.File
+  file?: FabricFile.File
   /**
    * @deprecated use file instead
    */
-  type: KubbFile.Mode
+  type: FabricFile.Mode
   path: string
   name: string
 }
 
 /**
  * Tree structure used to build per-directory barrel (`index.ts`) files from a
- * flat list of generated {@link KubbFile.File} entries.
+ * flat list of generated {@link FabricFile.File} entries.
  *
  * Each node represents either a directory or a file within the output tree.
  * Use {@link TreeNode.build} to construct a root node from a file list, then
@@ -76,6 +76,9 @@ export class TreeNode {
     return leaves
   }
 
+  /**
+   * Visits this node and every descendant in depth-first order.
+   */
   forEach(callback: (treeNode: TreeNode) => void): this {
     if (typeof callback !== 'function') {
       throw new TypeError('forEach() callback must be a function')
@@ -90,6 +93,9 @@ export class TreeNode {
     return this
   }
 
+  /**
+   * Finds the first leaf that satisfies `predicate`, or `undefined` when none match.
+   */
   findDeep(predicate?: (value: TreeNode, index: number, obj: TreeNode[]) => boolean): TreeNode | undefined {
     if (typeof predicate !== 'function') {
       throw new TypeError('find() predicate must be a function')
@@ -98,6 +104,9 @@ export class TreeNode {
     return this.leaves.find(predicate)
   }
 
+  /**
+   * Calls `callback` for every leaf of this node.
+   */
   forEachDeep(callback: (treeNode: TreeNode) => void): void {
     if (typeof callback !== 'function') {
       throw new TypeError('forEach() callback must be a function')
@@ -106,6 +115,9 @@ export class TreeNode {
     this.leaves.forEach(callback)
   }
 
+  /**
+   * Returns all leaves that satisfy `callback`.
+   */
   filterDeep(callback: (treeNode: TreeNode) => boolean): Array<TreeNode> {
     if (typeof callback !== 'function') {
       throw new TypeError('filter() callback must be a function')
@@ -114,6 +126,9 @@ export class TreeNode {
     return this.leaves.filter(callback)
   }
 
+  /**
+   * Maps every leaf through `callback` and returns the resulting array.
+   */
   mapDeep<T>(callback: (treeNode: TreeNode) => T): Array<T> {
     if (typeof callback !== 'function') {
       throw new TypeError('map() callback must be a function')
@@ -128,7 +143,7 @@ export class TreeNode {
    * - Filters to files under `root` (when provided) and skips `.json` files.
    * - Returns `null` when no files match.
    */
-  public static build(files: KubbFile.File[], root?: string): TreeNode | null {
+  public static build(files: FabricFile.File[], root?: string): TreeNode | null {
     try {
       const filteredTree = buildDirectoryTree(files, root)
 
@@ -172,13 +187,13 @@ export class TreeNode {
 type DirectoryTree = {
   name: string
   path: string
-  file?: KubbFile.File
+  file?: FabricFile.File
   children: Array<DirectoryTree>
 }
 
 const normalizePath = (p: string): string => p.replaceAll('\\', '/')
 
-function buildDirectoryTree(files: Array<KubbFile.File>, rootFolder = ''): DirectoryTree | null {
+function buildDirectoryTree(files: Array<FabricFile.File>, rootFolder = ''): DirectoryTree | null {
   const normalizedRootFolder = normalizePath(rootFolder)
   const rootPrefix = normalizedRootFolder.endsWith('/') ? normalizedRootFolder : `${normalizedRootFolder}/`