@kubb/core 5.0.0-beta.58 → 5.0.0-beta.59

package/dist/{diagnostics-BNcDERWL.d.ts → diagnostics-B-UZnFqP.d.ts}

@@ -145,8 +145,8 @@ type AdapterFactoryOptions<TName extends string = string, TOptions extends objec
  * Converts input files or inline data into Kubb's universal AST `InputNode`.
  *
  * Adapters live between the spec format and the plugins. The built-in
- * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1; custom adapters can
- * support GraphQL, gRPC, AsyncAPI, or any domain-specific schema language.
+ * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1. A custom adapter can
+ * support GraphQL, gRPC, or another schema language.
  *
  * @example
  * ```ts
@@ -208,9 +208,8 @@ type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
 type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>;
 /**
  * Defines a custom adapter that translates a spec format into Kubb's universal
- * AST. Use this when you need to consume GraphQL, gRPC, AsyncAPI, or another
- * domain-specific schema. Built-in adapters: `@kubb/adapter-oas` for
- * OpenAPI/Swagger documents.
+ * AST, for example GraphQL, gRPC, or AsyncAPI. The built-in `@kubb/adapter-oas`
+ * handles OpenAPI/Swagger documents.
  *
  * Adapters must return an `InputNode` from `parse`. That node is what every
  * plugin in the build consumes.
@@ -384,7 +383,7 @@ type ReporterContext = {
 };
 /**
  * Host-facing reporter, as installed onto a run. Unlike a Logger (the live TUI view), a reporter
- * never sees the event emitter. `report` runs once per config; `drain`, when present, runs once
+ * never sees the event emitter. `report` runs once per config. `drain`, when present, runs once
  * after the last config.
  */
 type Reporter = {
@@ -439,7 +438,7 @@ declare function createReporter<T = void>(reporter: UserReporter<T>): Reporter;
 /**
  * Backend that persists generated files. Kubb ships with `fsStorage` (writes
  * to disk) and `memoryStorage` (keeps everything in RAM). Implement this
- * interface to write to S3, a database, or any other target.
+ * interface to write somewhere else, such as S3 or a database.
  */
 type Storage = {
   /**
@@ -479,9 +478,9 @@ type Storage = {
 };
 /**
  * Defines a custom storage backend. The builder receives user options and
- * returns a `Storage` implementation. Kubb ships with filesystem and
- * in-memory storages, reach for this when you need to write generated files
- * elsewhere (cloud storage, a database, a remote API).
+ * returns a `Storage` implementation. Kubb ships with filesystem and in-memory
+ * storages. A custom backend writes generated files elsewhere, such as cloud
+ * storage or a database.
  *
  * @example In-memory storage (the built-in implementation)
  * ```ts
@@ -559,10 +558,9 @@ type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
  * (JSX, a template string, a tree of any shape) into `FileNode`s that get
  * written to disk.
  *
- * Use this to support output formats beyond JSX, for instance, a Handlebars
- * renderer, a string-template renderer, or a renderer that writes binary
- * files. Plugins and generators pick the renderer to use via the `renderer`
- * field on `defineGenerator`.
+ * A renderer can target output formats beyond JSX, for instance a Handlebars
+ * renderer or one that writes binary files. Plugins and generators pick the
+ * renderer to use via the `renderer` field on `defineGenerator`.
  *
  * @example A minimal renderer that wraps a custom runtime
  * ```ts
@@ -797,8 +795,8 @@ type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'],
 /**
  * Default path resolver used by `defineResolver`.
  *
- * - `mode: 'file'` — resolves directly to `output.path` (the full file path, extension included).
- * - `mode: 'directory'` (default) — resolves to `output.path/{baseName}`, or into a
+ * - `mode: 'file'` resolves directly to `output.path` (the full file path, extension included).
+ * - `mode: 'directory'` (default) resolves to `output.path/{baseName}`, or into a
  *   subdirectory when `group` and a `tag`/`path` value are provided.
  *
  * A custom `group.name` function overrides the default subdirectory naming.
@@ -850,8 +848,8 @@ type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'],
  * - `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).
+ * Methods in the returned object can call sibling resolver methods via `this`.
+ * A custom rule can delegate to a default, for example `this.default(name, 'type')`.
  *
  * @example Basic resolver with naming helpers
  * ```ts
@@ -882,9 +880,9 @@ declare function defineResolver<T extends PluginFactoryOptions>(build: ResolverB
 //#endregion
 //#region src/definePlugin.d.ts
 /**
- * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
- * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
- * without requiring changes to core.
+ * Reads a type from a registry, falling back to `{}` when the key is absent. Lets
+ * `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry` be augmented without
+ * touching core.
  *
  * @internal
  */
@@ -966,7 +964,7 @@ type Group = {
  *   files into per-group subdirectories.
  *
  * Intersect into a plugin's `Options` type instead of declaring `output` and
- * `group` directly — `mode` lives inside `output` while `group` is its sibling.
+ * `group` directly, since `mode` lives inside `output` while `group` is its sibling.
  * The generic keeps a plugin's extended `Output` shape intact.
  *
  * @example
@@ -1048,9 +1046,8 @@ type ByContentType = {
   pattern: string | RegExp;
 };
 /**
- * Filter that skips matching operations or schemas during generation. Use it
- * to drop deprecated endpoints, internal-only schemas, or anything you do
- * not want code generated for.
+ * Filter that skips matching operations or schemas during generation, for example
+ * deprecated endpoints or internal-only schemas.
  *
  * @example
  * ```ts
@@ -1125,8 +1122,8 @@ TResolver extends Resolver = Resolver> = {
   resolver: TResolver;
 };
 /**
- * Context for hook-style plugin `kubb:plugin:setup` handler.
- * Provides methods to register generators, configure resolvers, transformers, and renderers.
+ * Context passed to a plugin's `kubb:plugin:setup` handler, where it registers generators and
+ * sets its resolver, transformer, and options.
  */
 type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
@@ -1166,11 +1163,8 @@ type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactor
   options: TFactory['options'];
 };
 /**
- * A plugin object produced by `definePlugin`.
- * Instead of flat lifecycle methods, it groups all handlers under a `hooks:` property
- * (matching Astro's integration naming convention).
- *
- * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ * A plugin object produced by `definePlugin`. Its lifecycle handlers live under a single
+ * `hooks` property rather than flat methods.
  */
 type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
@@ -1205,8 +1199,8 @@ 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.
+ * Normalized plugin after setup, with runtime fields populated. Internal only. Plugins use the
+ * public `Plugin` type.
  *
  * @internal
  */
@@ -1244,8 +1238,7 @@ type KubbPluginEndContext = {
 };
 /**
  * Wraps a plugin factory and returns a function that accepts user options and
- * yields a fully typed `Plugin`. Lifecycle handlers go inside a single
- * `hooks` object (inspired by Astro integrations).
+ * yields a typed `Plugin`. Lifecycle handlers go inside a single `hooks` object.
  *
  * Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
  * `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
@@ -1329,7 +1322,8 @@ declare class KubbDriver {
   readonly config: Config;
   readonly options: Options;
   /**
-   * The streaming `InputNode<true>` produced by the adapter.   * Always set after adapter setup, parse-only adapters are wrapped automatically.
+   * The streaming `InputNode<true>` produced by the adapter. Set after adapter setup.
+   * Parse-only adapters are wrapped automatically.
    */
   inputNode: InputNode<true> | null;
   adapter: Adapter | null;
@@ -1545,8 +1539,8 @@ type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptio
  * Declares a named generator unit that walks the AST and emits files.
  *
  * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
- * Each method returns `TElement | Array<FileNode> | undefined | null`. JSX-based generators require a `renderer` factory.
- * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `undefined` or `null` to bypass rendering.
+ * JSX-based generators require a `renderer` factory. Return `Array<FileNode>` directly, or call
+ * `ctx.upsertFile()` manually and return `null` to bypass rendering.
  *
  * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
@@ -1802,9 +1796,9 @@ type ParsedFile = {
 //#endregion
 //#region src/types.d.ts
 /**
- * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
- * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
- * without requiring changes to core.
+ * Extracts a type from a registry, falling back to `{}` when the key doesn't exist.
+ * Lets plugins augment `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without changing core.
  *
  * @internal
  */
@@ -1925,7 +1919,6 @@ type Config<TInput = Input> = {
      * Remove every file in the output directory before the build, so stale output isn't mixed
      * with new files. Leave `false` to preserve manual edits in the output directory.
      *
-     * @default false
      * @example
      * ```ts
      * clean: true  // wipes ./src/gen/* before generating
@@ -1936,7 +1929,6 @@ type Config<TInput = Input> = {
      * Format the generated files after generation. `'auto'` runs the first formatter it finds
      * (oxfmt, biome, or prettier), a named tool forces that one, and `false` skips formatting.
      *
-     * @default false
      * @example
      * ```ts
      * format: 'auto'        // auto-detect prettier, biome, or oxfmt
@@ -1949,7 +1941,6 @@ type Config<TInput = Input> = {
      * Lint the generated files after generation. `'auto'` runs the first linter it finds
      * (oxlint, biome, or eslint), a named tool forces that one, and `false` skips linting.
      *
-     * @default false
      * @example
      * ```ts
      * lint: 'auto'      // auto-detect oxlint, biome, or eslint
@@ -1987,7 +1978,6 @@ type Config<TInput = Input> = {
      * Overwrite existing files when `true`, skip files that already exist when `false`. Individual
      * plugins can override it. Keep `false` to avoid clobbering local edits in the output folder.
      *
-     * @default false
      * @example
      * ```ts
      * override: true   // regenerate everything, even existing files
@@ -2033,10 +2023,9 @@ type Config<TInput = Input> = {
    */
   plugins: Array<Plugin>;
   /**
-   * Lifecycle hooks that execute during or after the build process.
+   * Lifecycle hooks that run external tools (prettier, eslint, a custom script) on build events.
    *
-   * Hooks allow you to run external tools (prettier, eslint, custom scripts) based on build events.
-   * Currently supports the `done` hook which fires after all plugins complete.
+   * Currently supports the `done` hook, which fires after all plugins complete.
    *
    * @example
    * ```ts
@@ -2049,11 +2038,10 @@ type Config<TInput = Input> = {
    */
   hooks?: {
     /**
-     * Command(s) to run after all plugins complete generation.
+     * Command(s) to run after all plugins finish generating, for post-processing the output.
      *
-     * Useful for post-processing: formatting, linting, copying files, or custom validation.
-     * Pass a single command string or array of command strings to run sequentially.
-     * Commands are executed relative to the `root` directory.
+     * Pass a single command string, or an array to run them in sequence.
+     * Commands run relative to the `root` directory.
      *
      * @example
      * ```ts
@@ -2525,7 +2513,7 @@ type CLIOptions = {
 };
 /**
  * All accepted forms of a Kubb configuration.
- * Accepts `Config`/`Config[]`/promise or a factory (optionally receiving `TCliOptions`.
+ * Accepts `Config`/`Config[]`/promise or a factory (optionally receiving `TCliOptions`).
  */
 type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Array<Config>> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Array<Config>>);
 /**
@@ -2568,9 +2556,8 @@ type BuildOutput = {
 type DiagnosticSeverity = 'error' | 'warning' | 'info';
 /**
  * A human-readable explanation of a diagnostic code: a short title, what triggers it, and how
- * to resolve it. This is the single source of truth the kubb.dev `/diagnostics/<slug>` pages
- * mirror, so every code stays documented in one place. Typed as a total record over
- * {@link DiagnosticCode}, so adding a code without documenting it fails the build.
+ * to resolve it. This is the source of truth the kubb.dev `/diagnostics/<slug>` pages mirror, so
+ * every code stays documented in one place. Adding a code without documenting it fails the build.
  */
 type DiagnosticDoc = {
   /**
@@ -2625,9 +2612,7 @@ type DiagnosticKind = 'problem' | 'performance' | 'update';
 type ProblemCode = Exclude<DiagnosticCode, typeof diagnosticCode.performance | typeof diagnosticCode.updateAvailable>;
 /**
  * A build problem collected during a run, gathered into the result instead of
- * aborting on the first failure. It carries a stable {@link ProblemCode}, a
- * `severity`, a `message`, and optionally a `location` into the source document,
- * a `help`, the `plugin` that produced it, and the `cause` it wraps.
+ * aborting on the first failure.
  */
 type ProblemDiagnostic = {
   /**
@@ -2655,9 +2640,9 @@ type ProblemDiagnostic = {
   cause?: Error;
 };
 /**
- * A per-plugin performance record, built with {@link Diagnostics.performance}. It carries the
- * `plugin` and its elapsed `duration`, and the `performance` kind keeps it out of the problem
- * list. It feeds the per-plugin timing bars, and reporters sum these into the run total.
+ * A per-plugin performance record, built with {@link Diagnostics.performance}. The `performance`
+ * kind keeps it out of the problem list. It feeds the per-plugin timing bars, and reporters sum
+ * these into the run total.
  */
 type PerformanceDiagnostic = {
   kind: 'performance';
@@ -2675,7 +2660,7 @@ type PerformanceDiagnostic = {
 };
 /**
  * A notice that a newer Kubb version is available on npm, built with {@link Diagnostics.update}.
- * It carries the running and latest versions and renders like any info diagnostic.
+ * It renders like any info diagnostic.
  */
 type UpdateDiagnostic = {
   kind: 'update';
@@ -2918,4 +2903,4 @@ declare class Diagnostics {
 }
 //#endregion
 export { KubbPluginSetupContext as $, KubbHookStartContext as A, Adapter as At, ParsedFile as B, KubbFilesProcessingEndContext as C, GenerationResult as Ct, KubbGenerationStartContext as D, UserReporter as Dt, KubbGenerationEndContext as E, ReporterName as Et, KubbSuccessContext as F, Generator$1 as G, createKubb as H, KubbWarnContext as I, KubbDriver as J, GeneratorContext as K, PossibleConfig as L, KubbInfoContext as M, AdapterSource as Mt, KubbLifecycleStartContext as N, createAdapter as Nt, KubbHookEndContext as O, createReporter as Ot, KubbPluginsEndContext as P, AsyncEventEmitter as Pt, KubbPluginEndContext as Q, UserConfig as R, KubbFileProcessingUpdate as S, createStorage as St, KubbFilesProcessingUpdateContext as T, ReporterContext as Tt, Parser as U, Kubb$1 as V, defineParser as W, Group as X, Exclude$1 as Y, Include as Z, InputPath as _, defineResolver as _t, DiagnosticLocation as a, Override as at, KubbDiagnosticContext as b, createRenderer as bt, PerformanceDiagnostic as c, definePlugin as ct, SerializedDiagnostic as d, ResolveBannerFile as dt, KubbPluginStartContext as et, UpdateDiagnostic as f, ResolveOptionsContext as ft, InputData as g, ResolverPathParams as gt, Config as h, ResolverFileParams as ht, DiagnosticKind as i, OutputOptions as it, KubbHooks as j, AdapterFactoryOptions as jt, KubbHookLineContext as k, logLevel as kt, ProblemCode as l, BannerMeta as lt, CLIOptions as m, ResolverContext as mt, DiagnosticByCode as n, Output as nt, DiagnosticSeverity as o, Plugin as ot, BuildOutput as p, Resolver as pt, defineGenerator as q, DiagnosticDoc as r, OutputMode as rt, Diagnostics as s, PluginFactoryOptions as st, Diagnostic as t, NormalizedPlugin as tt, ProblemDiagnostic as u, ResolveBannerContext as ut, KubbBuildEndContext as v, Renderer as vt, KubbFilesProcessingStartContext as w, Reporter as wt, KubbErrorContext as x, Storage as xt, KubbBuildStartContext as y, RendererFactory as yt, FileProcessorHooks as z };
-//# sourceMappingURL=diagnostics-BNcDERWL.d.ts.map
+//# sourceMappingURL=diagnostics-B-UZnFqP.d.ts.map

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_memoryStorage = require("./memoryStorage-Bz4ZDIZz.cjs");
+const require_memoryStorage = require("./memoryStorage-CUj1hrxa.cjs");
 let node_crypto = require("node:crypto");
 let node_util = require("node:util");
 let node_fs_promises = require("node:fs/promises");
@@ -576,9 +576,8 @@ var Url = class Url {
 //#region src/createAdapter.ts
 /**
 * Defines a custom adapter that translates a spec format into Kubb's universal
-* AST. Use this when you need to consume GraphQL, gRPC, AsyncAPI, or another
-* domain-specific schema. Built-in adapters: `@kubb/adapter-oas` for
-* OpenAPI/Swagger documents.
+* AST, for example GraphQL, gRPC, or AsyncAPI. The built-in `@kubb/adapter-oas`
+* handles OpenAPI/Swagger documents.
 *
 * Adapters must return an `InputNode` from `parse`. That node is what every
 * plugin in the build consumes.
@@ -610,9 +609,9 @@ function createAdapter(build) {
 //#endregion
 //#region src/diagnostics.ts
 /**
-* Docs major, derived from the package version so the link tracks the published major.
+* Docs major version, derived from the package version so the link tracks the published major.
 */
-const docsMajor = "5.0.0-beta.58".split(".")[0] ?? "5";
+const docsMajor = "5.0.0-beta.59".split(".")[0] ?? "5";
 /**
 * Narrows a {@link Diagnostic} to the variant for `code`, or `null` when it does not match.
 *
@@ -1059,8 +1058,7 @@ function normalizeOutput({ output, group, pluginName }) {
 }
 /**
 * Wraps a plugin factory and returns a function that accepts user options and
-* yields a fully typed `Plugin`. Lifecycle handlers go inside a single
-* `hooks` object (inspired by Astro integrations).
+* yields a typed `Plugin`. Lifecycle handlers go inside a single `hooks` object.
 *
 * Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
 * `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
@@ -1212,8 +1210,8 @@ function defaultResolveOptions(node, { options, exclude = [], include, override
 /**
 * Default path resolver used by `defineResolver`.
 *
-* - `mode: 'file'` — resolves directly to `output.path` (the full file path, extension included).
-* - `mode: 'directory'` (default) — resolves to `output.path/{baseName}`, or into a
+* - `mode: 'file'` resolves directly to `output.path` (the full file path, extension included).
+* - `mode: 'directory'` (default) resolves to `output.path/{baseName}`, or into a
 *   subdirectory when `group` and a `tag`/`path` value are provided.
 *
 * A custom `group.name` function overrides the default subdirectory naming.
@@ -1450,8 +1448,8 @@ function defaultResolveFooter(meta, { output, file }) {
 * - `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).
+* Methods in the returned object can call sibling resolver methods via `this`.
+* A custom rule can delegate to a default, for example `this.default(name, 'type')`.
 *
 * @example Basic resolver with naming helpers
 * ```ts
@@ -1563,7 +1561,8 @@ var KubbDriver = class {
 	config;
 	options;
 	/**
-	* The streaming `InputNode<true>` produced by the adapter.   * Always set after adapter setup, parse-only adapters are wrapped automatically.
+	* The streaming `InputNode<true>` produced by the adapter. Set after adapter setup.
+	* Parse-only adapters are wrapped automatically.
 	*/
 	inputNode = null;
 	adapter = null;
@@ -1940,7 +1939,7 @@ var KubbDriver = class {
 	*
 	* Plugins run sequentially so `kubb:plugin:end` fires as each plugin completes, instead
 	* of all at once after every plugin has marched through the parallel batches together.
-	* That ordering is what drives the CLI's `Plugins N/M` counter; without it the bar would
+	* That ordering is what drives the CLI's `Plugins N/M` counter. Without it the bar would
 	* sit at the initial value until the very end of the run.
 	*
 	* When `entries` is empty or `this.inputNode` is `null`, every entry still gets a
@@ -2680,7 +2679,7 @@ function renderSummary(lines, { title, status }) {
 }
 /**
 * The default `cli` reporter. Renders the {@link Report} for each config as it finishes, independent
-* of the live logger view. Suppressed at `silent`; the `verbose` level adds the per-plugin timings.
+* of the live logger view. Suppressed at `silent`. The `verbose` level adds the per-plugin timings.
 */
 const cliReporter = createReporter({
 	name: "cli",
@@ -2802,10 +2801,9 @@ const jsonReporter = createReporter({
 * (JSX, a template string, a tree of any shape) into `FileNode`s that get
 * written to disk.
 *
-* Use this to support output formats beyond JSX, for instance, a Handlebars
-* renderer, a string-template renderer, or a renderer that writes binary
-* files. Plugins and generators pick the renderer to use via the `renderer`
-* field on `defineGenerator`.
+* A renderer can target output formats beyond JSX, for instance a Handlebars
+* renderer or one that writes binary files. Plugins and generators pick the
+* renderer to use via the `renderer` field on `defineGenerator`.
 *
 * @example A minimal renderer that wraps a custom runtime
 * ```ts