@kubb/core 5.0.0-beta.3 → 5.0.0-beta.31

package/src/defineResolver.ts

@@ -1,18 +1,236 @@
 import path from 'node:path'
 import { camelCase, pascalCase } from '@internals/utils'
-import type { FileNode, InputNode, Node, OperationNode, SchemaNode } from '@kubb/ast'
+import type { FileNode, InputMeta, 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(meta: InputMeta | undefined, context: ResolveBannerContext): string | null
+  resolveFooter(meta: InputMeta | undefined, context: ResolveBannerContext): string | null
+}
+
+/**
+ * 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
+}
+
+/**
+ * Per-file context describing the file a banner/footer is being resolved for.
+ *
+ * Supplied by the generator (or the barrel middleware) at resolve-time and merged
+ * into `BannerMeta` so a `banner`/`footer` function can branch on the file kind —
+ * e.g. omit a `'use server'` directive on re-export files.
+ */
+export type ResolveBannerFile = {
+  /**
+   * Full output path of the file being generated.
+   */
+  path: string
+  /**
+   * File name only, e.g. `'stocks.ts'`.
+   */
+  baseName: string
+  /**
+   * `true` for `index.ts` re-export barrels.
+   */
+  isBarrel?: boolean
+  /**
+   * `true` for group `[dir]/[dir].ts` aggregation files.
+   */
+  isAggregation?: boolean
+}
+
+/**
+ * Document metadata extended with per-file context, passed to a `banner`/`footer` function.
+ *
+ * Carries everything in {@link InputMeta} plus the file the banner is rendered into, so a
+ * single function can decide per file (e.g. skip a directive on barrel/aggregation files).
+ *
+ * @example Skip a directive on re-export files
+ * `banner: (meta) => (meta.isBarrel || meta.isAggregation) ? '' : "'use server'"`
+ */
+export type BannerMeta = InputMeta & {
+  /**
+   * Full output path of the file being generated.
+   */
+  filePath: string
+  /**
+   * File name only, e.g. `'stocks.ts'`.
+   */
+  baseName: string
+  /**
+   * `true` for `index.ts` re-export barrels.
+   */
+  isBarrel: boolean
+  /**
+   * `true` for group `[dir]/[dir].ts` aggregation files.
+   */
+  isAggregation: boolean
+}
+
+/**
+ * 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.
+ * `file` carries per-file context forwarded to a `banner`/`footer` function.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveBanner(meta, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+export type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>
+  config: Config
+  file?: ResolveBannerFile
+}
+
+/**
+ * Merges document `meta` with per-file `file` context into the `BannerMeta` passed to a
+ * `banner`/`footer` function. Missing fields default to empty/`false` so the object shape
+ * is stable even when a caller (e.g. the barrel middleware) has no document metadata.
+ */
+function buildBannerMeta({ meta, file }: { meta: InputMeta | undefined; file: ResolveBannerFile | undefined }): BannerMeta {
+  return {
+    title: meta?.title,
+    description: meta?.description,
+    version: meta?.version,
+    baseURL: meta?.baseURL,
+    circularNames: meta?.circularNames ?? [],
+    enumNames: meta?.enumNames ?? [],
+    filePath: file?.path ?? '',
+    baseName: file?.baseName ?? '',
+    isBarrel: file?.isBarrel ?? false,
+    isAggregation: file?.isAggregation ?? false,
+  }
+}
 
 /**
  * Builder type for the plugin-specific resolver fields.
@@ -20,19 +238,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>()
@@ -54,20 +269,12 @@ function testPattern(value: string, pattern: string | RegExp): boolean {
  * Checks if an operation matches a pattern for a given filter type (`tag`, `operationId`, `path`, `method`).
  */
 function matchesOperationPattern(node: OperationNode, type: string, pattern: string | RegExp): boolean {
-  switch (type) {
-    case 'tag':
-      return node.tags.some((tag) => testPattern(tag, pattern))
-    case 'operationId':
-      return testPattern(node.operationId, pattern)
-    case 'path':
-      return testPattern(node.path, pattern)
-    case 'method':
-      return testPattern(node.method.toLowerCase(), pattern)
-    case 'contentType':
-      return node.requestBody?.content?.some((c) => testPattern(c.contentType, pattern)) ?? false
-    default:
-      return false
-  }
+  if (type === 'tag') return node.tags.some((tag) => testPattern(tag, pattern))
+  if (type === 'operationId') return testPattern(node.operationId, pattern)
+  if (type === 'path') return node.path !== undefined && testPattern(node.path, pattern)
+  if (type === 'method') return node.method !== undefined && testPattern(node.method.toLowerCase(), pattern)
+  if (type === 'contentType') return node.requestBody?.content?.some((c) => testPattern(c.contentType, pattern)) ?? false
+  return false
 }
 
 /**
@@ -76,12 +283,8 @@ function matchesOperationPattern(node: OperationNode, type: string, pattern: str
  * Returns `null` when the filter type doesn't apply to schemas.
  */
 function matchesSchemaPattern(node: SchemaNode, type: string, pattern: string | RegExp): boolean | null {
-  switch (type) {
-    case 'schemaName':
-      return node.name ? testPattern(node.name, pattern) : false
-    default:
-      return null
-  }
+  if (type === 'schemaName') return node.name ? testPattern(node.name, pattern) : false
+  return null
 }
 
 /**
@@ -92,19 +295,9 @@ function matchesSchemaPattern(node: SchemaNode, type: string, pattern: string |
  * - `camelCase` for everything else.
  */
 function defaultResolver(name: string, type?: 'file' | 'function' | 'type' | 'const'): string {
-  let resolvedName = camelCase(name)
-
-  if (type === 'file' || type === 'function') {
-    resolvedName = camelCase(name, {
-      isFile: type === 'file',
-    })
-  }
-
-  if (type === 'type') {
-    resolvedName = pascalCase(name)
-  }
-
-  return resolvedName
+  if (type === 'file' || type === 'function') return camelCase(name, { isFile: type === 'file' })
+  if (type === 'type') return pascalCase(name)
+  return camelCase(name)
 }
 
 /**
@@ -130,19 +323,18 @@ function defaultResolver(name: string, type?: 'file' | 'function' | 'type' | 'co
  * // → { enumType: 'enum' } when operationId matches
  * ```
  */
-export function defaultResolveOptions<TOptions>(
+const resolveOptionsCache = new WeakMap<object, WeakMap<Node, { value: unknown }>>()
+
+function computeOptions<TOptions>(
   node: Node,
-  { options, exclude = [], include, override = [] }: ResolveOptionsContext<TOptions>,
+  options: TOptions,
+  exclude: Array<PatternFilter>,
+  include: Array<PatternFilter> | undefined,
+  override: Array<PatternOverride<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
-    }
+    if (exclude.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))) 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
 
@@ -150,18 +342,13 @@ export function defaultResolveOptions<TOptions>(
   }
 
   if (isSchemaNode(node)) {
-    if (exclude.some(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)) {
-      return null
-    }
-
+    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
-      }
-    }
 
+      if (applicable.length > 0 && !applicable.includes(true)) return null
+    }
     const overrideOptions = override.find(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)?.options
 
     return { ...options, ...overrideOptions }
@@ -170,6 +357,26 @@ export function defaultResolveOptions<TOptions>(
   return options
 }
 
+export function defaultResolveOptions<TOptions>(
+  node: Node,
+  { options, exclude = [], include, override = [] }: ResolveOptionsContext<TOptions>,
+): TOptions | null {
+  const optionsKey = options as object
+  let byOptions = resolveOptionsCache.get(optionsKey)
+  if (!byOptions) {
+    byOptions = new WeakMap()
+    resolveOptionsCache.set(optionsKey, byOptions)
+  }
+  const cached = byOptions.get(node)
+  if (cached !== undefined) return cached.value as TOptions | null
+
+  const result = computeOptions(node, options, exclude, include, override)
+
+  byOptions.set(node, { value: result })
+
+  return result
+}
+
 /**
  * Default path resolver used by `defineResolver`.
  *
@@ -215,31 +422,30 @@ 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)
   }
 
-  let result: string
-
-  if (group && (groupPath || tag)) {
-    const groupValue = group.type === 'path' ? groupPath! : tag!
-    const defaultName =
-      group.type === 'tag'
-        ? ({ group: g }: { group: string }) => `${camelCase(g)}Controller`
-        : ({ group: g }: { group: string }) => {
-            // Strip traversal components (empty, '.', '..') before taking the first meaningful segment.
-            // When every segment is a traversal component (e.g. '../../') we fall back to '' so the
-            // file is placed directly in the output root — the boundary check below ensures safety.
-            const segment = g.split('/').filter((s) => s !== '' && s !== '.' && s !== '..')[0]
-            return segment ? camelCase(segment) : ''
-          }
-    const resolveName = group.name ?? defaultName
-    result = path.resolve(root, output.path, resolveName({ group: groupValue }), baseName)
-  } else {
-    result = path.resolve(root, output.path, baseName)
-  }
+  const result: string = (() => {
+    if (group && (groupPath || tag)) {
+      const groupValue = group.type === 'path' ? groupPath! : tag!
+      const defaultName =
+        group.type === 'tag'
+          ? ({ group: g }: { group: string }) => `${camelCase(g)}Controller`
+          : ({ group: g }: { group: string }) => {
+              // Strip traversal components (empty, '.', '..') before taking the first meaningful segment.
+              // When every segment is a traversal component (e.g. '../../') we fall back to '' so the
+              // file is placed directly in the output root — the boundary check below ensures safety.
+              const segment = g.split('/').filter((s) => s !== '' && s !== '.' && s !== '..')[0]
+              return segment ? camelCase(segment) : ''
+            }
+      const resolveName = group.name ?? defaultName
+      return path.resolve(root, output.path, resolveName({ group: groupValue }), baseName)
+    }
+    return path.resolve(root, output.path, baseName)
+  })()
 
   // Ensure the resolved path stays within the configured output directory.
   // This prevents path traversal from malicious OpenAPI specs or custom group.name functions.
@@ -268,35 +474,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: [],
@@ -319,17 +525,16 @@ export function buildDefaultBanner({
   config: Config
 }): string {
   try {
-    let source = ''
-    if (Array.isArray(config.input)) {
-      const first = config.input[0]
-      if (first && 'path' in first) {
-        source = path.basename(first.path)
+    const source = (() => {
+      if (Array.isArray(config.input)) {
+        const first = config.input[0]
+        if (first && 'path' in first) return path.basename(first.path)
+        return ''
       }
-    } else if ('path' in config.input) {
-      source = path.basename(config.input.path)
-    } else if ('data' in config.input) {
-      source = 'text content'
-    }
+      if (config.input && 'path' in config.input) return path.basename(config.input.path)
+      if (config.input && 'data' in config.input) return 'text content'
+      return ''
+    })()
 
     let banner = '/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n'
 
@@ -367,10 +572,9 @@ export function buildDefaultBanner({
  *
  * A user-supplied `output.banner` overrides the default Kubb "Generated by Kubb" notice.
  * When no `output.banner` is set, the Kubb notice is used (including `title` and `version`
- * from the OAS spec when a `node` is provided).
+ * from the document metadata when `meta` is provided).
  *
- * - When `output.banner` is a function and `node` is provided, returns `output.banner(node)`.
- * - When `output.banner` is a function and `node` is absent, falls back to the Kubb notice.
+ * - When `output.banner` is a function, calls it with the file's `BannerMeta` and returns the result.
  * - When `output.banner` is a string, returns it directly.
  * - When `config.output.defaultBanner` is `false`, returns `undefined`.
  * - Otherwise returns the Kubb "Generated by Kubb" notice.
@@ -381,27 +585,33 @@ export function buildDefaultBanner({
  * // → '// my banner'
  * ```
  *
- * @example Function banner with node
+ * @example Function banner with metadata
  * ```ts
- * defaultResolveBanner(inputNode, { output: { banner: (node) => `// v${node.version}` }, config })
+ * defaultResolveBanner(meta, { output: { banner: (m) => `// v${m.version}` }, config })
  * // → '// v3.0.0'
  * ```
  *
+ * @example Function banner skips re-export files
+ * ```ts
+ * defaultResolveBanner(meta, { output: { banner: (m) => (m.isBarrel ? '' : "'use server'") }, config, file: { path, baseName, isBarrel: true } })
+ * // → ''
+ * ```
+ *
  * @example No user banner — Kubb notice with OAS metadata
  * ```ts
- * defaultResolveBanner(inputNode, { config })
+ * defaultResolveBanner(meta, { config })
  * // → '/** Generated by Kubb ... Title: Pet Store ... *\/'
  * ```
  *
  * @example Disabled default banner
  * ```ts
  * defaultResolveBanner(undefined, { config: { output: { defaultBanner: false }, ...config } })
- * // → undefined
+ * // → null
  * ```
  */
-export function defaultResolveBanner(node: InputNode | undefined, { output, config }: ResolveBannerContext): string | undefined {
+export function defaultResolveBanner(meta: InputMeta | undefined, { output, config, file }: ResolveBannerContext): string | null {
   if (typeof output?.banner === 'function') {
-    return output.banner(node)
+    return output.banner(buildBannerMeta({ meta, file }))
   }
 
   if (typeof output?.banner === 'string') {
@@ -409,12 +619,12 @@ export function defaultResolveBanner(node: InputNode | undefined, { output, conf
   }
 
   if (config.output.defaultBanner === false) {
-    return undefined
+    return null
   }
 
   return buildDefaultBanner({
-    title: node?.meta?.title,
-    version: node?.meta?.version,
+    title: meta?.title,
+    version: meta?.version,
     config,
   })
 }
@@ -422,8 +632,7 @@ export function defaultResolveBanner(node: InputNode | undefined, { output, conf
 /**
  * Default footer resolver — returns the footer string for a generated file.
  *
- * - When `output.footer` is a function and `node` is provided, calls it with the node.
- * - When `output.footer` is a function and `node` is absent, returns `undefined`.
+ * - When `output.footer` is a function, calls it with the file's `BannerMeta` and returns the result.
  * - When `output.footer` is a string, returns it directly.
  * - Otherwise returns `undefined`.
  *
@@ -433,89 +642,78 @@ export function defaultResolveBanner(node: InputNode | undefined, { output, conf
  * // → '// end of file'
  * ```
  *
- * @example Function footer with node
+ * @example Function footer with metadata
  * ```ts
- * defaultResolveFooter(inputNode, { output: { footer: (node) => `// ${node.title}` }, config })
+ * defaultResolveFooter(meta, { output: { footer: (m) => `// ${m.title}` }, config })
  * // → '// Pet Store'
  * ```
  */
-export function defaultResolveFooter(node: InputNode | undefined, { output }: ResolveBannerContext): string | undefined {
+export function defaultResolveFooter(meta: InputMeta | undefined, { output, file }: ResolveBannerContext): string | null {
   if (typeof output?.footer === 'function') {
-    return node ? output.footer(node) : undefined
+    return output.footer(buildBannerMeta({ meta, file }))
   }
   if (typeof output?.footer === 'string') {
     return output.footer
   }
-  return undefined
+  return null
 }
 
 /**
- * Defines a resolver for a plugin, injecting built-in defaults for name casing,
- * include/exclude/override filtering, path resolution, and file construction.
+ * Defines a plugin resolver. The resolver is the object that decides what
+ * every generated symbol and file path is called. Built-in defaults handle
+ * name casing, include/exclude/override filtering, output path computation,
+ * and file construction. Supply your own to override any of them:
  *
- * All four defaults can be overridden by providing them in the builder function:
- * - `default` — name casing strategy (camelCase / PascalCase)
- * - `resolveOptions` — include/exclude/override filtering
- * - `resolvePath` — output path computation
- * - `resolveFile` — full `FileNode` construction
+ * - `default` — name casing strategy (camelCase / PascalCase).
+ * - `resolveOptions` — include/exclude/override filtering.
+ * - `resolvePath` — output path computation.
+ * - `resolveFile` — full `FileNode` construction.
+ * - `resolveBanner` / `resolveFooter` — top/bottom-of-file text.
  *
- * 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`,
+ * which keeps custom rules small (`this.default(name, 'type')` to delegate).
  *
  * @example Basic resolver with naming helpers
  * ```ts
- * export const resolver = defineResolver<PluginTs>((ctx) => ({
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
  *   name: 'default',
- *   resolveName(node) {
- *     return ctx.default(node.name, 'function')
+ *   resolveName(name) {
+ *     return this.default(name, 'function')
  *   },
- *   resolveTypedName(node) {
- *     return ctx.default(node.name, 'type')
+ *   resolveTypeName(name) {
+ *     return this.default(name, 'type')
  *   },
  * }))
  * ```
  *
- * @example Override resolvePath for a custom output structure
+ * @example Custom output path
  * ```ts
- * export const resolver = defineResolver<PluginTs>((_ctx) => ({
+ * import path from 'node:path'
+ *
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
  *   name: 'custom',
  *   resolvePath({ baseName }, { root, output }) {
  *     return path.resolve(root, output.path, 'generated', baseName)
  *   },
  * }))
  * ```
- *
- * @example Use ctx.default inside a helper
- * ```ts
- * export const resolver = defineResolver<PluginTs>((ctx) => ({
- *   name: 'default',
- *   resolveParamName(node, param) {
- *     return ctx.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
 }