@kubb/core 5.0.0-beta.1 → 5.0.0-beta.11

package/src/defineResolver.ts

@@ -2,17 +2,159 @@ import path from 'node:path'
 import { camelCase, pascalCase } from '@internals/utils'
 import type { FileNode, InputNode, Node, OperationNode, SchemaNode } from '@kubb/ast'
 import { createFile, isOperationNode, isSchemaNode } from '@kubb/ast'
-import { PluginDriver } from './PluginDriver.ts'
-import type {
-  Config,
-  PluginFactoryOptions,
-  ResolveBannerContext,
-  ResolveOptionsContext,
-  Resolver,
-  ResolverContext,
-  ResolverFileParams,
-  ResolverPathParams,
-} from './types.ts'
+import type { PluginFactoryOptions } from './definePlugin.ts'
+import { getMode } from './definePlugin.ts'
+import type { Config, Group, Output } from './types.ts'
+
+/**
+ * Type/string pattern filter for include/exclude/override matching.
+ */
+type PatternFilter = {
+  type: string
+  pattern: string | RegExp
+}
+
+/**
+ * Pattern filter with partial option overrides applied when the pattern matches.
+ */
+type PatternOverride<TOptions> = PatternFilter & {
+  options: Omit<Partial<TOptions>, 'override'>
+}
+
+/**
+ * Context for resolving filtered options for a given operation or schema node.
+ *
+ * @internal
+ */
+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`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are injected automatically by `defineResolver` — extend this type to add custom resolution methods.
+ *
+ * @example
+ * ```ts
+ * type MyResolver = Resolver & {
+ *   resolveName(node: SchemaNode): string
+ *   resolveTypedName(node: SchemaNode): string
+ * }
+ * ```
+ */
+export type Resolver = {
+  name: string
+  pluginName: string
+  default(name: string, type?: 'file' | 'function' | 'type' | 'const'): string
+  resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null
+  resolvePath(params: ResolverPathParams, context: ResolverContext): string
+  resolveFile(params: ResolverFileParams, context: ResolverContext): FileNode
+  resolveBanner(node: InputNode | null, context: ResolveBannerContext): string | undefined
+  resolveFooter(node: InputNode | null, context: ResolveBannerContext): string | undefined
+}
+
+/**
+ * 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: FileNode['baseName']
+  pathMode?: 'single' | 'split'
+  /**
+   * 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: FileNode['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(inputNode, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+export type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>
+  config: Config
+}
 
 /**
  * Builder type for the plugin-specific resolver fields.
@@ -20,19 +162,16 @@ import type {
  * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
  * are optional — built-in fallbacks are injected when omitted.
  *
- * The builder receives `ctx` — a reference to the fully assembled resolver — so methods can
- * call sibling resolver methods without using `this`.  Because `ctx` is captured by the closure
- * and the resolver is populated after the builder runs, `ctx` correctly reflects any overrides
- * that were applied by the builder itself.
+ * Methods in the returned object can call sibling resolver methods via `this`.
  */
-type ResolverBuilder<T extends PluginFactoryOptions> = (ctx: T['resolver']) => Omit<
+type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<
   T['resolver'],
   'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter' | 'name' | 'pluginName'
 > &
   Partial<Pick<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>> & {
     name: string
     pluginName: T['name']
-  }
+  } & ThisType<T['resolver']>
 
 // String patterns are compiled lazily and cached — the same filter is reused for every node.
 const stringPatternCache = new Map<string, RegExp>()
@@ -215,7 +354,7 @@ export function defaultResolveOptions<TOptions>(
  * ```
  */
 export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }: ResolverPathParams, { root, output, group }: ResolverContext): string {
-  const mode = pathMode ?? PluginDriver.getMode(path.resolve(root, output.path))
+  const mode = pathMode ?? getMode(path.resolve(root, output.path))
 
   if (mode === 'single') {
     return path.resolve(root, output.path)
@@ -268,35 +407,35 @@ export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }:
  *
  * @example Resolve a schema file
  * ```ts
- * const file = defaultResolveFile(
+ * const file = defaultResolveFile.call(
+ *   resolver,
  *   { name: 'pet', extname: '.ts' },
  *   { root: '/src', output: { path: 'types' } },
- *   resolver,
  * )
  * // → { baseName: 'pet.ts', path: '/src/types/pet.ts', sources: [], ... }
  * ```
  *
  * @example Resolve an operation file with tag grouping
  * ```ts
- * const file = defaultResolveFile(
+ * const file = defaultResolveFile.call(
+ *   resolver,
  *   { name: 'listPets', extname: '.ts', tag: 'pets' },
  *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
- *   resolver,
  * )
  * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
  * ```
  */
-export function defaultResolveFile({ name, extname, tag, path: groupPath }: ResolverFileParams, context: ResolverContext, ctx: Resolver): FileNode {
-  const pathMode = PluginDriver.getMode(path.resolve(context.root, context.output.path))
-  const resolvedName = pathMode === 'single' ? '' : ctx.default(name, 'file')
+export function defaultResolveFile(this: Resolver, { name, extname, tag, path: groupPath }: ResolverFileParams, context: ResolverContext): FileNode {
+  const pathMode = getMode(path.resolve(context.root, context.output.path))
+  const resolvedName = pathMode === 'single' ? '' : this.default(name, 'file')
   const baseName = `${resolvedName}${extname}` as FileNode['baseName']
-  const filePath = ctx.resolvePath({ baseName, pathMode, tag, path: groupPath }, context)
+  const filePath = this.resolvePath({ baseName, pathMode, tag, path: groupPath }, context)
 
   return createFile({
     path: filePath,
     baseName: path.basename(filePath) as `${string}.${string}`,
     meta: {
-      pluginName: ctx.pluginName,
+      pluginName: this.pluginName,
     },
     sources: [],
     imports: [],
@@ -325,9 +464,9 @@ export function buildDefaultBanner({
       if (first && 'path' in first) {
         source = path.basename(first.path)
       }
-    } else if ('path' in config.input) {
+    } else if (config.input && 'path' in config.input) {
       source = path.basename(config.input.path)
-    } else if ('data' in config.input) {
+    } else if (config.input && 'data' in config.input) {
       source = 'text content'
     }
 
@@ -459,25 +598,24 @@ export function defaultResolveFooter(node: InputNode | undefined, { output }: Re
  * - `resolvePath` — output path computation
  * - `resolveFile` — full `FileNode` construction
  *
- * The builder receives `ctx` — a reference to the assembled resolver — so methods can
- * call sibling resolver methods using `ctx` instead of `this`.
+ * Methods in the returned object can call sibling resolver methods via `this`.
  *
  * @example Basic resolver with naming helpers
  * ```ts
- * export const resolver = defineResolver<PluginTs>((ctx) => ({
+ * export const resolver = defineResolver<PluginTs>(() => ({
  *   name: 'default',
  *   resolveName(node) {
- *     return ctx.default(node.name, 'function')
+ *     return this.default(node.name, 'function')
  *   },
  *   resolveTypedName(node) {
- *     return ctx.default(node.name, 'type')
+ *     return this.default(node.name, 'type')
  *   },
  * }))
  * ```
  *
  * @example Override resolvePath for a custom output structure
  * ```ts
- * export const resolver = defineResolver<PluginTs>((_ctx) => ({
+ * export const resolver = defineResolver<PluginTs>(() => ({
  *   name: 'custom',
  *   resolvePath({ baseName }, { root, output }) {
  *     return path.resolve(root, output.path, 'generated', baseName)
@@ -485,37 +623,32 @@ export function defaultResolveFooter(node: InputNode | undefined, { output }: Re
  * }))
  * ```
  *
- * @example Use ctx.default inside a helper
+ * @example Use this.default inside a helper
  * ```ts
- * export const resolver = defineResolver<PluginTs>((ctx) => ({
+ * export const resolver = defineResolver<PluginTs>(() => ({
  *   name: 'default',
  *   resolveParamName(node, param) {
- *     return ctx.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
+ *     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
  *   },
  * }))
  * ```
  */
 export function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'] {
-  // Create the resolver shell first.  When `build(resolver)` executes below, `resolver` is
-  // still empty, but methods returned by the builder capture it by reference.  By the time
-  // those methods are actually called, `Object.assign` will have already populated all
-  // properties (including any overrides from the builder itself).
-  const resolver = {} as T['resolver']
+  // `resolver` is kept so the default `resolveFile` wrapper can reference the fully assembled
+  // object via `.call(resolver, ...)` at call-time, after the result is assigned below.
+  let resolver: T['resolver']
 
-  Object.assign(resolver, {
+  const result = {
     default: defaultResolver,
     resolveOptions: defaultResolveOptions,
     resolvePath: defaultResolvePath,
-    // Wire the default resolveFile implementation with a wrapper that passes resolver as ctx.
-    // Unlike other defaults which can be assigned directly, defaultResolveFile requires the
-    // resolver as its third parameter.
-    resolveFile: (params: ResolverFileParams, context: ResolverContext) => defaultResolveFile(params, context, resolver as Resolver),
+    resolveFile: (params: ResolverFileParams, context: ResolverContext) => defaultResolveFile.call(resolver as Resolver, params, context),
     resolveBanner: defaultResolveBanner,
     resolveFooter: defaultResolveFooter,
-    // Builder overrides are applied last.  Any method in the builder can call
-    // ctx.xxx() and will see the fully merged resolver (including its own overrides).
-    ...build(resolver),
-  })
+    ...build(),
+  } as T['resolver']
+
+  resolver = result
 
   return resolver
 }

package/src/devtools.ts

@@ -1,7 +1,14 @@
 import type { InputNode } from '@kubb/ast'
 import { deflateSync, inflateSync } from 'fflate'
 import { x } from 'tinyexec'
-import type { DevtoolsOptions } from './types.ts'
+
+export type DevtoolsOptions = {
+  /**
+   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
+   * @default false
+   */
+  ast?: boolean
+}
 
 /**
  * Encodes an `InputNode` as a compressed, URL-safe string.

package/src/index.ts

@@ -17,4 +17,4 @@ export { PluginDriver } from './PluginDriver.ts'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'
-export { isInputPath } from './utils/isInputPath.ts'
+export { isInputPath } from './createKubb.ts'

package/src/mocks.ts

@@ -2,8 +2,7 @@ import { resolve } from 'node:path'
 import type { FileNode, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
 import { transform } from '@kubb/ast'
 import { FileManager } from './FileManager.ts'
-import { PluginDriver } from './PluginDriver.ts'
-import { applyHookResult } from './renderNode.ts'
+import { applyHookResult, PluginDriver } from './PluginDriver.ts'
 import type { Adapter, AdapterFactoryOptions, Config, Generator, GeneratorContext, NormalizedPlugin, PluginFactoryOptions } from './types.ts'
 
 /**

package/src/storages/fsStorage.ts

@@ -4,13 +4,6 @@ import { join, resolve } from 'node:path'
 import { clean, write } from '@internals/utils'
 import { createStorage } from '../createStorage.ts'
 
-/**
- * Detects the filesystem error used to indicate that a path does not exist.
- */
-function isMissingPathError(error: unknown): error is NodeJS.ErrnoException {
-  return typeof error === 'object' && error !== null && 'code' in error && (error as NodeJS.ErrnoException).code === 'ENOENT'
-}
-
 /**
  * Built-in filesystem storage driver.
  *
@@ -42,27 +35,15 @@ export const fsStorage = createStorage(() => ({
     try {
       await access(resolve(key))
       return true
-    } catch (error) {
-      if (isMissingPathError(error)) {
-        return false
-      }
-
-      throw new Error(`Failed to access storage item "${key}"`, {
-        cause: error as Error,
-      })
+    } catch (_error) {
+      return false
     }
   },
   async getItem(key: string) {
     try {
       return await readFile(resolve(key), 'utf8')
-    } catch (error) {
-      if (isMissingPathError(error)) {
-        return null
-      }
-
-      throw new Error(`Failed to read storage item "${key}"`, {
-        cause: error as Error,
-      })
+    } catch (_error) {
+      return null
     }
   },
   async setItem(key: string, value: string) {
@@ -81,14 +62,8 @@ export const fsStorage = createStorage(() => ({
         entries = (await readdir(dir, {
           withFileTypes: true,
         })) as Array<Dirent>
-      } catch (error) {
-        if (isMissingPathError(error)) {
-          return
-        }
-
-        throw new Error(`Failed to list storage keys under "${resolvedBase}"`, {
-          cause: error as Error,
-        })
+      } catch (_error) {
+        return
       }
       for (const entry of entries) {
         const rel = prefix ? `${prefix}/${entry.name}` : entry.name