@kubb/core 5.0.0-beta.35 → 5.0.0-beta.37

package/src/defineGenerator.ts

@@ -64,15 +64,20 @@ export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFacto
    */
   transformer: Visitor | undefined
   /**
-   * Emit a warning.
+   * Report a warning. Collected as a `warning` diagnostic attributed to the current
+   * plugin. It surfaces in the run summary but does not fail the build. For a structured
+   * diagnostic with a code and source location, use `Diagnostics.report` or throw a
+   * `DiagnosticError` directly.
    */
   warn: (message: string) => void
   /**
-   * Emit an error.
+   * Report an error. Collected as an `error` diagnostic attributed to the current
+   * plugin, which fails the build.
    */
   error: (error: string | Error) => void
   /**
-   * Emit an info message.
+   * Report an informational message. Collected as an `info` diagnostic attributed to
+   * the current plugin.
    */
   info: (message: string) => void
   /**
@@ -84,7 +89,7 @@ export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFacto
    */
   adapter: Adapter
   /**
-   * Document metadata from the adapter — title, version, base URL, and pre-computed
+   * Document metadata from the adapter: title, version, base URL, and pre-computed
    * schema index fields (`circularNames`, `enumNames`).
    */
   meta: InputMeta
@@ -131,8 +136,7 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
    *
    * Generators that only return `Array<FileNode>` or `void` do not need to set this.
    *
-   * Set `renderer: null` to explicitly opt out of rendering even when the parent plugin
-   * declares a `renderer` (overrides the plugin-level fallback).
+   * Leave it unset or set `renderer: null` to opt out of rendering.
    *
    * @example
    * ```ts
@@ -172,7 +176,7 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
  * The returned object is the input as-is, but with `this` types preserved so
  * `schema`/`operation`/`operations` methods are correctly typed against the
  * plugin's `PluginFactoryOptions`. Renderer elements and `FileNode[]` returns
- * are both handled by the runtime — pick whichever style fits.
+ * are both handled by the runtime, so pick whichever style fits.
  *
  * @example JSX-based schema generator
  * ```tsx

package/src/defineParser.ts

@@ -6,7 +6,7 @@ type PrintOptions = {
 
 /**
  * Converts a resolved {@link FileNode} into the final source string that gets
- * written to disk. Kubb ships with TypeScript and TSX parsers; add your own
+ * written to disk. Kubb ships with TypeScript and TSX parsers. Add your own
  * for new file types (JSON, Markdown, ...).
  */
 export type Parser<TMeta extends object = object, TNode = unknown> = {

package/src/definePlugin.ts

@@ -1,6 +1,5 @@
 import { extname } from 'node:path'
 import type { FileNode, HttpMethod, UserFileNode, Visitor } from '@kubb/ast'
-import type { RendererFactory } from './createRenderer.ts'
 import type { Generator } from './defineGenerator.ts'
 import type { BannerMeta, Resolver } from './defineResolver.ts'
 import type { Config, KubbHooks } from './types.ts'
@@ -29,8 +28,8 @@ export type Output<_TOptions = unknown> = {
    * lint disables, or `@ts-nocheck` directives.
    *
    * A string is applied to every file (including barrel and aggregation re-export files).
-   * Pass a function to compute the banner from the file's `BannerMeta` — document metadata
-   * plus per-file context (`isBarrel`, `isAggregation`, `filePath`, `baseName`) — so you can
+   * Pass a function to compute the banner from the file's `BannerMeta` document metadata
+   * plus per-file context (`isBarrel`, `isAggregation`, `filePath`, `baseName`), so you can
    * skip the banner on specific files.
    *
    * @example Add a directive to source files but not re-export files
@@ -58,8 +57,8 @@ export type Output<_TOptions = unknown> = {
 export type Group = {
   /**
    * Property used to assign each operation to a group.
-   * - `'tag'` — uses the first tag (`operation.getTags().at(0)?.name`).
-   * - `'path'` — uses the first segment of the operation's URL.
+   * - `'tag'` uses the first tag (`operation.getTags().at(0)?.name`).
+   * - `'path'` uses the first segment of the operation's URL.
    */
   type: 'tag' | 'path'
   /**
@@ -112,11 +111,6 @@ type ByMethod = {
    */
   pattern: HttpMethod | RegExp
 }
-// TODO implement as alternative for ByMethod
-// type ByMethods = {
-//   type: 'methods'
-//   pattern: Array<HttpMethod>
-// }
 
 type BySchemaName = {
   /**
@@ -175,7 +169,7 @@ export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType
  * options are merged on top of the plugin defaults for that operation only.
  * Useful for "this one tag goes to a different folder" rules.
  *
- * Entries are evaluated top to bottom; the first matching entry wins.
+ * Entries are evaluated top to bottom. The first matching entry wins.
  *
  * @example
  * ```ts
@@ -194,8 +188,7 @@ export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType
  * ```
  */
 export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
-  //TODO should be options: Omit<Partial<TOptions>, 'override'>
-  options: Partial<TOptions>
+  options: Omit<Partial<TOptions>, 'override'>
 }
 
 export type PluginFactoryOptions<
@@ -242,10 +235,6 @@ export type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = Plugi
    * Set the AST transformer to pre-process nodes before they reach generators.
    */
   setTransformer(visitor: Visitor): void
-  /**
-   * Set the renderer factory to process JSX elements from generators.
-   */
-  setRenderer(renderer: RendererFactory): void
   /**
    * Set resolved options merged into the normalized plugin's `options`.
    * Call this in `kubb:plugin:setup` to provide options generators need.
@@ -289,9 +278,9 @@ export type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>
   /**
    * Controls the execution order of this plugin relative to others.
    *
-   * - `'pre'`  — runs before all normal plugins.
-   * - `'post'` — runs after all normal plugins.
-   * - `undefined` (default) — runs in declaration order among normal plugins.
+   * - `'pre'` runs before all normal plugins.
+   * - `'post'` runs after all normal plugins.
+   * - `undefined` (default), runs in declaration order among normal plugins.
    *
    * Dependency constraints always take precedence over `enforce`.
    */
@@ -313,7 +302,7 @@ export type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>
 
 /**
  * Normalized plugin after setup, with runtime fields populated.
- * For internal use only — plugins use the public `Plugin` type externally.
+ * For internal use only, plugins use the public `Plugin` type externally.
  *
  * @internal
  */
@@ -326,7 +315,6 @@ export type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFacto
   }
   resolver: TOptions['resolver']
   transformer?: Visitor
-  renderer?: RendererFactory
   generators?: Array<Generator>
   apply?: (config: Config) => boolean
   version?: string

package/src/defineResolver.ts

@@ -2,6 +2,8 @@ import path from 'node:path'
 import { camelCase, pascalCase } from '@internals/utils'
 import type { FileNode, InputMeta, Node, OperationNode, SchemaNode } from '@kubb/ast'
 import { createFile, isOperationNode, isSchemaNode } from '@kubb/ast'
+import { diagnosticCode } from './constants.ts'
+import { DiagnosticError } from './diagnostics.ts'
 import type { PluginFactoryOptions } from './definePlugin.ts'
 import { getMode } from './definePlugin.ts'
 import type { Config, Group, Output } from './types.ts'
@@ -37,7 +39,7 @@ export type ResolveOptionsContext<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.
+ * are injected automatically by `defineResolver`. Extend this type to add custom resolution methods.
  *
  * @example
  * ```ts
@@ -143,7 +145,7 @@ export type ResolverFileParams = {
  * 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 —
+ * 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 = {
@@ -196,7 +198,7 @@ export type BannerMeta = InputMeta & {
 /**
  * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
  *
- * `output` is optional — not every plugin configures a banner/footer.
+ * `output` is optional, since 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.
  *
@@ -236,7 +238,7 @@ function buildBannerMeta({ meta, file }: { meta: InputMeta | undefined; file: Re
  * Builder type for the plugin-specific resolver fields.
  *
  * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
- * are optional — built-in fallbacks are injected when omitted.
+ * are optional, with built-in fallbacks injected when omitted.
  *
  * Methods in the returned object can call sibling resolver methods via `this`.
  */
@@ -249,7 +251,7 @@ type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<
     pluginName: T['name']
   } & ThisType<T['resolver']>
 
-// String patterns are compiled lazily and cached — the same filter is reused for every node.
+// String patterns are compiled lazily and cached, so the same filter is reused for every node.
 const stringPatternCache = new Map<string, RegExp>()
 
 function testPattern(value: string, pattern: string | RegExp): boolean {
@@ -301,7 +303,7 @@ function defaultResolver(name: string, type?: 'file' | 'function' | 'type' | 'co
 }
 
 /**
- * Default option resolver — applies include/exclude filters and merges matching override options.
+ * 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.
  *
@@ -345,7 +347,7 @@ function computeOptions<TOptions>(
     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)
+      const applicable = results.filter((result) => result !== null)
 
       if (applicable.length > 0 && !applicable.includes(true)) return null
     }
@@ -433,12 +435,12 @@ export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }:
       const groupValue = group.type === 'path' ? groupPath! : tag!
       const defaultName =
         group.type === 'tag'
-          ? ({ group: g }: { group: string }) => `${camelCase(g)}Controller`
-          : ({ group: g }: { group: string }) => {
+          ? ({ group: groupName }: { group: string }) => `${camelCase(groupName)}Controller`
+          : ({ group: groupName }: { 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]
+              // file is placed directly in the output root, and the boundary check below ensures safety.
+              const segment = groupName.split('/').filter((part) => part !== '' && part !== '.' && part !== '..')[0]
               return segment ? camelCase(segment) : ''
             }
       const resolveName = group.name ?? defaultName
@@ -454,10 +456,13 @@ export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }:
   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.',
-    )
+    throw new DiagnosticError({
+      code: diagnosticCode.pathTraversal,
+      severity: 'error',
+      message: `Resolved path "${result}" is outside the output directory "${outputDir}".`,
+      help: 'This can stem from a path traversal in the OpenAPI specification or a misconfigured `group.name` function. Keep generated paths within the output directory.',
+      location: { kind: 'config' },
+    })
   }
 
   return result
@@ -468,7 +473,7 @@ export function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }:
  *
  * 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.
+ * `sources`, `imports`, and `exports` arrays, which consumers populate separately.
  *
  * In `single` mode the name is omitted and the file sits directly in the output directory.
  *
@@ -568,7 +573,7 @@ export function buildDefaultBanner({
 }
 
 /**
- * Default banner resolver — returns the banner string for a generated file.
+ * 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`
@@ -597,7 +602,7 @@ export function buildDefaultBanner({
  * // → ''
  * ```
  *
- * @example No user banner — Kubb notice with OAS metadata
+ * @example No user banner, Kubb notice with OAS metadata
  * ```ts
  * defaultResolveBanner(meta, { config })
  * // → '/** Generated by Kubb ... Title: Pet Store ... *\/'
@@ -630,7 +635,7 @@ export function defaultResolveBanner(meta: InputMeta | undefined, { output, conf
 }
 
 /**
- * Default footer resolver — returns the footer string for a generated file.
+ * Default footer resolver. Returns the footer string for a generated file.
  *
  * - 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.
@@ -664,11 +669,11 @@ export function defaultResolveFooter(meta: InputMeta | undefined, { output, file
  * name casing, include/exclude/override filtering, output path computation,
  * and file construction. Supply your own to override any of them:
  *
- * - `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.
+ * - `default` sets the name casing strategy (camelCase or PascalCase).
+ * - `resolveOptions` does include/exclude/override filtering.
+ * - `resolvePath` computes the output path.
+ * - `resolveFile` builds the full `FileNode`.
+ * - `resolveBanner` and `resolveFooter` produce the top and bottom of file text.
  *
  * Methods in the returned object can call sibling resolver methods via `this`,
  * which keeps custom rules small (`this.default(name, 'type')` to delegate).

package/src/devtools.ts

@@ -14,7 +14,7 @@ export type DevtoolsOptions = {
  * Encodes an `InputNode` as a compressed, URL-safe string.
  *
  * The JSON representation is deflate-compressed with {@link deflateSync} before
- * base64url encoding, which typically reduces payload size by 70–80 % and
+ * base64url encoding, which typically reduces payload size by 70, 80 % and
  * keeps URLs well within browser and server path-length limits.
  */
 export function encodeAst(input: InputNode): string {
@@ -36,8 +36,7 @@ export function getStudioUrl(input: InputNode, studioUrl: string, options: Devto
 }
 
 /**
- * Opens the Kubb Studio URL for the given `InputNode` in the default browser —
- *
+ * Opens the Kubb Studio URL for the given `InputNode` in the default browser,  *
  * Falls back to printing the URL if the browser cannot be launched.
  */
 export async function openInStudio(input: InputNode, studioUrl: string, options: DevtoolsOptions = {}): Promise<void> {