@kubb/core 5.0.0-alpha.9 → 5.0.0-beta.10

package/src/defineResolver.ts

@@ -1,15 +1,193 @@
+import path from 'node:path'
 import { camelCase, pascalCase } from '@internals/utils'
-import { isOperationNode, isSchemaNode } from '@kubb/ast'
-import type { Node, OperationNode, SchemaNode } from '@kubb/ast/types'
-import type { PluginFactoryOptions, ResolveNameParams, ResolveOptionsContext } from './types.ts'
+import type { FileNode, InputNode, Node, OperationNode, SchemaNode } from '@kubb/ast'
+import { createFile, isOperationNode, isSchemaNode } from '@kubb/ast'
+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.
- * `default` and `resolveOptions` are optional — built-in fallbacks are used when omitted.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are optional — built-in fallbacks are injected when omitted.
+ *
+ * Methods in the returned object can call sibling resolver methods via `this`.
  */
-type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'], 'default' | 'resolveOptions'> &
-  Partial<Pick<T['resolver'], 'default' | 'resolveOptions'>> &
-  ThisType<T['resolver']>
+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>()
+
+function testPattern(value: string, pattern: string | RegExp): boolean {
+  if (typeof pattern === 'string') {
+    let regex = stringPatternCache.get(pattern)
+    if (!regex) {
+      regex = new RegExp(pattern)
+      stringPatternCache.set(pattern, regex)
+    }
+    return regex.test(value)
+  }
+  // Use .match() for user-supplied RegExp to preserve semantics regardless of `g`/`y` flags.
+  return value.match(pattern) !== null
+}
 
 /**
  * Checks if an operation matches a pattern for a given filter type (`tag`, `operationId`, `path`, `method`).
@@ -17,13 +195,15 @@ type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'],
 function matchesOperationPattern(node: OperationNode, type: string, pattern: string | RegExp): boolean {
   switch (type) {
     case 'tag':
-      return node.tags.some((tag) => !!tag.match(pattern))
+      return node.tags.some((tag) => testPattern(tag, pattern))
     case 'operationId':
-      return !!node.operationId.match(pattern)
+      return testPattern(node.operationId, pattern)
     case 'path':
-      return !!node.path.match(pattern)
+      return testPattern(node.path, pattern)
     case 'method':
-      return !!(node.method.toLowerCase() as string).match(pattern)
+      return testPattern(node.method.toLowerCase(), pattern)
+    case 'contentType':
+      return node.requestBody?.content?.some((c) => testPattern(c.contentType, pattern)) ?? false
     default:
       return false
   }
@@ -31,21 +211,26 @@ function matchesOperationPattern(node: OperationNode, type: string, pattern: str
 
 /**
  * Checks if a schema matches a pattern for a given filter type (`schemaName`).
+ *
  * 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 ? !!node.name.match(pattern) : false
+      return node.name ? testPattern(node.name, pattern) : false
     default:
       return null
   }
 }
 
 /**
- * Default name resolver — `camelCase` for most types, `PascalCase` for `type`.
+ * Default name resolver used by `defineResolver`.
+ *
+ * - `camelCase` for `function` and `file` types.
+ * - `PascalCase` for `type`.
+ * - `camelCase` for everything else.
  */
-function defaultResolver(name: ResolveNameParams['name'], type: ResolveNameParams['type']): string {
+function defaultResolver(name: string, type?: 'file' | 'function' | 'type' | 'const'): string {
   let resolvedName = camelCase(name)
 
   if (type === 'file' || type === 'function') {
@@ -62,8 +247,27 @@ function defaultResolver(name: ResolveNameParams['name'], type: ResolveNameParam
 }
 
 /**
- * Default option resolver — applies include/exclude filters and merges any matching override options.
- * Returns `null` when the node is filtered out.
+ * Default option resolver — applies include/exclude filters and merges matching override options.
+ *
+ * Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
+ *
+ * @example Include/exclude filtering
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { output: 'types' },
+ *   exclude: [{ type: 'tag', pattern: 'internal' }],
+ * })
+ * // → null when node has tag 'internal'
+ * ```
+ *
+ * @example Override merging
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { enumType: 'asConst' },
+ *   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
+ * })
+ * // → { enumType: 'enum' } when operationId matches
+ * ```
  */
 export function defaultResolveOptions<TOptions>(
   node: Node,
@@ -106,26 +310,345 @@ export function defaultResolveOptions<TOptions>(
 }
 
 /**
- * Defines a resolver for a plugin, with built-in defaults for name casing and include/exclude/override filtering.
- * Override `default` or `resolveOptions` in the builder to customize the behavior.
+ * Default path resolver used by `defineResolver`.
  *
- * @example
+ * - Returns the output directory in `single` mode.
+ * - Resolves into a tag- or path-based subdirectory when `group` and a `tag`/`path` value are provided.
+ * - Falls back to a flat `output/baseName` path otherwise.
+ *
+ * A custom `group.name` function overrides the default subdirectory naming.
+ * For `tag` groups the default is `${camelCase(tag)}Controller`.
+ * For `path` groups the default is the first path segment after `/`.
+ *
+ * @example Flat output
+ * ```ts
+ * defaultResolvePath({ baseName: 'petTypes.ts' }, { root: '/src', output: { path: 'types' } })
+ * // → '/src/types/petTypes.ts'
+ * ```
+ *
+ * @example Tag-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/petsController/petTypes.ts'
+ * ```
+ *
+ * @example Path-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', path: '/pets/list' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'path' } },
+ * )
+ * // → '/src/types/pets/petTypes.ts'
+ * ```
+ *
+ * @example Single-file mode
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', pathMode: 'single' },
+ *   { root: '/src', output: { path: 'types' } },
+ * )
+ * // → '/src/types'
+ * ```
+ */
+export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }: ResolverPathParams, { root, output, group }: ResolverContext): string {
+  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)
+  }
+
+  // Ensure the resolved path stays within the configured output directory.
+  // This prevents path traversal from malicious OpenAPI specs or custom group.name functions.
+  // `result === outputDir` is intentionally permitted: it matches single-file mode paths and
+  // edge cases where baseName resolves to the output directory itself.
+  const outputDir = path.resolve(root, output.path)
+  const outputDirWithSep = outputDir.endsWith(path.sep) ? outputDir : `${outputDir}${path.sep}`
+  if (result !== outputDir && !result.startsWith(outputDirWithSep)) {
+    throw new Error(
+      `[Kubb] Resolved path "${result}" is outside the output directory "${outputDir}". ` +
+        'This may indicate a path traversal attempt in the OpenAPI specification or a misconfigured group.name function.',
+    )
+  }
+
+  return result
+}
+
+/**
+ * Default file resolver used by `defineResolver`.
+ *
+ * Resolves a `FileNode` 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.
+ *
+ * In `single` mode the name is omitted and the file sits directly in the output directory.
+ *
+ * @example Resolve a schema file
+ * ```ts
+ * const file = defaultResolveFile.call(
+ *   resolver,
+ *   { name: 'pet', extname: '.ts' },
+ *   { root: '/src', output: { path: 'types' } },
+ * )
+ * // → { baseName: 'pet.ts', path: '/src/types/pet.ts', sources: [], ... }
+ * ```
+ *
+ * @example Resolve an operation file with tag grouping
+ * ```ts
+ * const file = defaultResolveFile.call(
+ *   resolver,
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+ * ```
+ */
+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 = this.resolvePath({ baseName, pathMode, tag, path: groupPath }, context)
+
+  return createFile({
+    path: filePath,
+    baseName: path.basename(filePath) as `${string}.${string}`,
+    meta: {
+      pluginName: this.pluginName,
+    },
+    sources: [],
+    imports: [],
+    exports: [],
+  })
+}
+
+/**
+ * Generates the default "Generated by Kubb" banner from config and optional node metadata.
+ */
+export function buildDefaultBanner({
+  title,
+  description,
+  version,
+  config,
+}: {
+  title?: string
+  description?: string
+  version?: string
+  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)
+      }
+    } else if (config.input && 'path' in config.input) {
+      source = path.basename(config.input.path)
+    } else if (config.input && 'data' in config.input) {
+      source = 'text content'
+    }
+
+    let banner = '/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n'
+
+    if (config.output.defaultBanner === 'simple') {
+      banner += '*/\n'
+      return banner
+    }
+
+    if (source) {
+      banner += `* Source: ${source}\n`
+    }
+
+    if (title) {
+      banner += `* Title: ${title}\n`
+    }
+
+    if (description) {
+      const formattedDescription = description.replace(/\n/gm, '\n* ')
+      banner += `* Description: ${formattedDescription}\n`
+    }
+
+    if (version) {
+      banner += `* OpenAPI spec version: ${version}\n`
+    }
+
+    banner += '*/\n'
+    return banner
+  } catch (_error) {
+    return '/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n*/'
+  }
+}
+
+/**
+ * Default banner resolver — returns the banner string for a generated file.
+ *
+ * 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).
+ *
+ * - 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 string, returns it directly.
+ * - When `config.output.defaultBanner` is `false`, returns `undefined`.
+ * - Otherwise returns the Kubb "Generated by Kubb" notice.
+ *
+ * @example String banner overrides default
+ * ```ts
+ * defaultResolveBanner(undefined, { output: { banner: '// my banner' }, config })
+ * // → '// my banner'
+ * ```
+ *
+ * @example Function banner with node
+ * ```ts
+ * defaultResolveBanner(inputNode, { output: { banner: (node) => `// v${node.version}` }, config })
+ * // → '// v3.0.0'
+ * ```
+ *
+ * @example No user banner — Kubb notice with OAS metadata
+ * ```ts
+ * defaultResolveBanner(inputNode, { config })
+ * // → '/** Generated by Kubb ... Title: Pet Store ... *\/'
+ * ```
+ *
+ * @example Disabled default banner
+ * ```ts
+ * defaultResolveBanner(undefined, { config: { output: { defaultBanner: false }, ...config } })
+ * // → undefined
+ * ```
+ */
+export function defaultResolveBanner(node: InputNode | undefined, { output, config }: ResolveBannerContext): string | undefined {
+  if (typeof output?.banner === 'function') {
+    return output.banner(node)
+  }
+
+  if (typeof output?.banner === 'string') {
+    return output.banner
+  }
+
+  if (config.output.defaultBanner === false) {
+    return undefined
+  }
+
+  return buildDefaultBanner({
+    title: node?.meta?.title,
+    version: node?.meta?.version,
+    config,
+  })
+}
+
+/**
+ * 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 string, returns it directly.
+ * - Otherwise returns `undefined`.
+ *
+ * @example String footer
+ * ```ts
+ * defaultResolveFooter(undefined, { output: { footer: '// end of file' }, config })
+ * // → '// end of file'
+ * ```
+ *
+ * @example Function footer with node
+ * ```ts
+ * defaultResolveFooter(inputNode, { output: { footer: (node) => `// ${node.title}` }, config })
+ * // → '// Pet Store'
+ * ```
+ */
+export function defaultResolveFooter(node: InputNode | undefined, { output }: ResolveBannerContext): string | undefined {
+  if (typeof output?.footer === 'function') {
+    return node ? output.footer(node) : undefined
+  }
+  if (typeof output?.footer === 'string') {
+    return output.footer
+  }
+  return undefined
+}
+
+/**
+ * Defines a resolver for a plugin, injecting built-in defaults for name casing,
+ * include/exclude/override filtering, path resolution, and file construction.
+ *
+ * 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
+ *
+ * Methods in the returned object can call sibling resolver methods via `this`.
+ *
+ * @example Basic resolver with naming helpers
+ * ```ts
  * export const resolver = defineResolver<PluginTs>(() => ({
- *   resolveName(name) {
- *     return this.default(name, 'function')
+ *   name: 'default',
+ *   resolveName(node) {
+ *     return this.default(node.name, 'function')
+ *   },
+ *   resolveTypedName(node) {
+ *     return this.default(node.name, 'type')
  *   },
- *   resolveTypedName(name) {
- *     return this.default(name, 'type')
+ * }))
+ * ```
+ *
+ * @example Override resolvePath for a custom output structure
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'custom',
+ *   resolvePath({ baseName }, { root, output }) {
+ *     return path.resolve(root, output.path, 'generated', baseName)
  *   },
+ * }))
+ * ```
+ *
+ * @example Use this.default inside a helper
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
  *   resolveParamName(node, param) {
- *     return this.resolveName(`${node.operationId} ${param.in} ${param.name}`)
+ *     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
  *   },
  * }))
+ * ```
  */
 export function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'] {
-  return {
+  // `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']
+
+  const result = {
     default: defaultResolver,
     resolveOptions: defaultResolveOptions,
+    resolvePath: defaultResolvePath,
+    resolveFile: (params: ResolverFileParams, context: ResolverContext) => defaultResolveFile.call(resolver as Resolver, params, context),
+    resolveBanner: defaultResolveBanner,
+    resolveFooter: defaultResolveFooter,
     ...build(),
   } as T['resolver']
+
+  resolver = result
+
+  return resolver
 }