@kubb/core 5.0.0-beta.62 → 5.0.0-beta.63

package/dist/{diagnostics-D0G07LHG.d.ts → diagnostics-IjkPEgAO.d.ts}

@@ -225,12 +225,12 @@ type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) =
  *   options,
  *   document: null,
  *   async parse(_source) {
- *     // Convert `source` (path or inline data) into an InputNode.
+ *     // Convert the source (path or inline data) into an InputNode.
  *     return ast.factory.createInput()
  *   },
  *   getImports: () => [],
  *   async validate() {
- *     // Throw or call ctx.error here when the spec is invalid.
+ *     // Throw here when the spec is invalid.
  *   },
  * }))
  * ```
@@ -371,13 +371,13 @@ type GenerationResult = {
   hrStart: [number, number];
 };
 /**
- * Render context passed alongside the {@link GenerationResult}, carrying knobs a reporter needs
- * but that are not part of the run data (e.g. verbosity).
+ * Render settings passed alongside the {@link GenerationResult}. These are not part of the run
+ * data, such as the output verbosity.
  */
 type ReporterContext = {
   /**
    * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
-   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
+   * (`silent`, `error`, `warn`, `info`, `verbose`).
    */
   logLevel: (typeof logLevel)[keyof typeof logLevel];
 };
@@ -397,7 +397,7 @@ type Reporter = {
   report: (result: GenerationResult, context: ReporterContext) => void | Promise<void>;
   /**
    * Optional finalizer called once after the run's last config. The host wires it to
-   * `kubb:lifecycle:end`. {@link createReporter} closes it over the reports `report` returned.
+   * `kubb:lifecycle:end`. {@link createReporter} closes it over the values that `report` returned.
    */
   drain?: (context: ReporterContext) => void | Promise<void>;
 };
@@ -471,8 +471,8 @@ type Storage = {
    */
   clear(base?: string): Promise<void>;
   /**
-   * Optional teardown hook called after the build completes. Use to flush
-   * buffers, close connections, or release file locks.
+   * Optional teardown hook for a backend to flush buffers, close connections,
+   * or release file locks.
    */
   dispose?(): Promise<void>;
 };
@@ -950,8 +950,8 @@ type Group = {
    */
   type: 'tag' | 'path';
   /**
-   * Returns the subdirectory name from the group key. Defaults to the
-   * camelCased tag for `tag` groups, or the first path segment for `path` groups.
+   * Returns the subdirectory name from the group key. Defaults to the camelCased tag for
+   * `tag` groups, or the camelCased first path segment for `path` groups.
    */
   name?: (context: {
     group: string;
@@ -1017,11 +1017,12 @@ type ByPath = {
 };
 type ByMethod = {
   /**
-   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   * Filter by HTTP method: `'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, `'DELETE'`, `'HEAD'`, `'OPTIONS'`, `'TRACE'`.
    */
   type: 'method';
   /**
-   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   * HTTP method to match, as one of the `HttpMethod` values (`'GET'`, `'POST'`, `'PUT'`,
+   * `'PATCH'`, `'DELETE'`, `'HEAD'`, `'OPTIONS'`, `'TRACE'`) or a regex.
    */
   pattern: HttpMethod | RegExp;
 };
@@ -1186,7 +1187,7 @@ type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
    *
    * - `'pre'` runs before all normal plugins.
    * - `'post'` runs after all normal plugins.
-   * - `undefined` (default), runs in declaration order among normal plugins.
+   * - `undefined` (default) runs in declaration order among normal plugins.
    *
    * Dependency constraints always take precedence over `enforce`.
    */
@@ -1340,13 +1341,19 @@ declare class KubbDriver {
   readonly fileManager: FileManager;
   readonly plugins: Map<string, NormalizedPlugin>;
   constructor(config: Config, options: Options);
+  /**
+   * Normalizes every configured plugin, orders them, and registers their lifecycle handlers.
+   * A plugin that another lists as a dependency runs first, then `enforce: 'pre'` before
+   * `'post'`. When the config has an adapter, the adapter source is resolved from the input
+   * so `run` can parse it later.
+   */
   setup(): Promise<void>;
   get hooks(): AsyncEventEmitter<KubbHooks>;
   /**
    * Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
    * can configure generators, resolvers, macros and renderers before `buildStart` runs.
    *
-   * Call this once from `safeBuild` before the plugin execution loop begins.
+   * Called once from `run` before the plugin execution loop begins.
    */
   emitSetupHooks(): Promise<void>;
   /**
@@ -1437,11 +1444,11 @@ declare class KubbDriver {
 //#endregion
 //#region src/defineGenerator.d.ts
 /**
- * Context object passed to generator `schema`, `operation`, and `operations` methods.
+ * Context passed to a generator's `schema`, `operation`, and `operations` methods.
  *
- * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
- * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
- * filtering for individual schema/operation calls, or plugin-level options for operations.
+ * The driver sets `adapter` on the context before it runs a generator, so methods can read it
+ * without a null check. `ctx.options` carries the per-node options after exclude/include/override
+ * filtering for `schema` and `operation`, or the plugin-level options for `operations`.
  */
 type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
@@ -1536,9 +1543,10 @@ 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.
- * JSX-based generators require a `renderer` factory. Return `Array<FileNode>` directly, or call
- * `ctx.upsertFile()` manually and return `null` to bypass rendering.
+ * `schema` runs for each schema node and `operation` for each operation node. `operations` runs
+ * once after every operation node is walked. 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`.
  *
@@ -1646,8 +1654,9 @@ type Parser<TMeta extends object = object, TNode = unknown> = {
    */
   name: string;
   /**
-   * File extensions this parser handles. Set to `undefined` to define a
-   * catch-all fallback used when no other parser claims the extension.
+   * File extensions this parser handles. The driver registers the parser for each
+   * extension in this list. A parser with `undefined` here is not registered, so
+   * files of an unclaimed extension fall back to joining their sources verbatim.
    *
    * @example
    * `['.ts', '.js']`
@@ -1698,9 +1707,8 @@ type CreateKubbOptions = {
  * config in the constructor, so `config` is available right away, and shares `hooks`,
  * `storage`, and `driver` across the `setup → build` lifecycle.
  *
- * `createKubb` takes a plain, serializable config object (the shape `defineConfig`
- * produces), not a fluent builder. Config stays plain data so it can be cache
- * fingerprinted and validated against the shipped JSON schema.
+ * `createKubb` takes a plain config object (the shape `defineConfig` produces),
+ * not a fluent builder.
  *
  * Attach event listeners to `.hooks` before calling `setup()` or `build()`.
  *
@@ -1929,7 +1937,7 @@ type Config<TInput = Input> = {
      *
      * @example
      * ```ts
-     * format: 'auto'        // auto-detect prettier, biome, or oxfmt
+     * format: 'auto'        // auto-detect oxfmt, biome, or prettier
      * format: 'prettier'    // force prettier
      * format: false         // skip formatting
      * ```
@@ -2701,7 +2709,7 @@ declare function narrow<C extends DiagnosticCode>(diagnostic: Diagnostic, code:
 /**
  * A {@link Diagnostic} reduced to its JSON-safe fields plus a `docsUrl`, for
  * machine-readable output (the `--reporter json` report, the MCP tools). Drops the
- * non-serializable `cause` and the `timing`/`duration` bookkeeping.
+ * non-serializable `cause` and the `kind`/`duration` bookkeeping.
  */
 type SerializedDiagnostic = {
   code: DiagnosticCode;
@@ -2850,8 +2858,8 @@ declare class Diagnostics {
    */
   static failedPlugins(diagnostics: ReadonlyArray<Diagnostic>): Array<string>;
   /**
-   * Counts `problem` diagnostics by severity for the run summary. `timing`
-   * diagnostics are ignored.
+   * Counts `problem` diagnostics by severity for the run summary. `performance` and
+   * `update` diagnostics are ignored.
    */
   static count(diagnostics: ReadonlyArray<Diagnostic>): {
     errors: number;
@@ -2901,4 +2909,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-D0G07LHG.d.ts.map
+//# sourceMappingURL=diagnostics-IjkPEgAO.d.ts.map

package/dist/index.cjs

@@ -593,12 +593,12 @@ var Url = class Url {
 *   options,
 *   document: null,
 *   async parse(_source) {
-*     // Convert `source` (path or inline data) into an InputNode.
+*     // Convert the source (path or inline data) into an InputNode.
 *     return ast.factory.createInput()
 *   },
 *   getImports: () => [],
 *   async validate() {
-*     // Throw or call ctx.error here when the spec is invalid.
+*     // Throw here when the spec is invalid.
 *   },
 * }))
 * ```
@@ -611,7 +611,7 @@ function createAdapter(build) {
 /**
 * Docs major version, derived from the package version so the link tracks the published major.
 */
-const docsMajor = "5.0.0-beta.62".split(".")[0] ?? "5";
+const docsMajor = "5.0.0-beta.63".split(".")[0] ?? "5";
 /**
 * Narrows a {@link Diagnostic} to the variant for `code`, or `null` when it does not match.
 *
@@ -931,8 +931,8 @@ var Diagnostics = class Diagnostics {
 		return [...names];
 	}
 	/**
-	* Counts `problem` diagnostics by severity for the run summary. `timing`
-	* diagnostics are ignored.
+	* Counts `problem` diagnostics by severity for the run summary. `performance` and
+	* `update` diagnostics are ignored.
 	*/
 	static count(diagnostics) {
 		let errors = 0;
@@ -1500,7 +1500,7 @@ function defineResolver(build) {
 * leaves the tree untouched, so callers can detect a no-op by identity.
 *
 * Registration order matches the order setup hooks fire, which the driver has already sorted by
-* `enforce` and dependency edges. The registry preserves that order; macro `enforce` only reorders
+* `enforce` and dependency edges. The registry preserves that order. Macro `enforce` only reorders
 * within a single plugin's list.
 */
 var Transform = class {
@@ -1633,6 +1633,12 @@ var KubbDriver = class {
 		this.hooks.on(event, handler);
 		this.#listeners.push([event, handler]);
 	}
+	/**
+	* Normalizes every configured plugin, orders them, and registers their lifecycle handlers.
+	* A plugin that another lists as a dependency runs first, then `enforce: 'pre'` before
+	* `'post'`. When the config has an adapter, the adapter source is resolved from the input
+	* so `run` can parse it later.
+	*/
 	async setup() {
 		const normalized = this.config.plugins.map((rawPlugin) => this.#normalizePlugin(rawPlugin));
 		const dependenciesByName = new Map(normalized.map((plugin) => [plugin.name, new Set(plugin.dependencies ?? [])]));
@@ -1652,8 +1658,9 @@ var KubbDriver = class {
 		return this.options.hooks;
 	}
 	/**
-	* Creates an `NormalizedPlugin` from a hook-style plugin and registers
-	* its lifecycle handlers on the `AsyncEventEmitter`.
+	* Builds a `NormalizedPlugin` from a hook-style plugin, filling in default
+	* options and copying `apply` when present. Registering its lifecycle handlers
+	* on the `AsyncEventEmitter` is done separately by `#registerPlugin`.
 	*/
 	#normalizePlugin(plugin) {
 		const normalized = {
@@ -1758,7 +1765,7 @@ var KubbDriver = class {
 	* Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
 	* can configure generators, resolvers, macros and renderers before `buildStart` runs.
 	*
-	* Call this once from `safeBuild` before the plugin execution loop begins.
+	* Called once from `run` before the plugin execution loop begins.
 	*/
 	async emitSetupHooks() {
 		const noop = () => {};
@@ -1953,8 +1960,8 @@ var KubbDriver = class {
 	* 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
-	* `kubb:plugin:end` so post-plugin listeners (the barrel writer and friends) complete.
+	* When `this.inputNode` is `null`, every entry still gets a `kubb:plugin:end` so
+	* post-plugin listeners (the barrel writer and friends) complete.
 	*/
 	async #runGenerators(entries, flushPending) {
 		const diagnostics = [];
@@ -2445,9 +2452,8 @@ function resolveConfig(userConfig) {
 * config in the constructor, so `config` is available right away, and shares `hooks`,
 * `storage`, and `driver` across the `setup → build` lifecycle.
 *
-* `createKubb` takes a plain, serializable config object (the shape `defineConfig`
-* produces), not a fluent builder. Config stays plain data so it can be cache
-* fingerprinted and validated against the shipped JSON schema.
+* `createKubb` takes a plain config object (the shape `defineConfig` produces),
+* not a fluent builder.
 *
 * Attach event listeners to `.hooks` before calling `setup()` or `build()`.
 *
@@ -2756,12 +2762,11 @@ function buildTimingSection(report) {
 * The `file` reporter. Writes a config's {@link Report} to `.kubb/kubb-<name>-<timestamp>.log` as a
 * plain-text document: a `# <name> — <timestamp>` header, a `## Summary` with the same counts the
 * cli and json reporters expose, a `## Problems` section in the miette block format, and a
-* `## Timings` section. Selected with `--reporter file` (or `reporters: ['file']`), replacing the
-* old `--debug` flag.
+* `## Timings` section. Selected with `--reporter file` (or `reporters: ['file']`).
 *
-* @note Unlike the streaming logger it replaced, it captures the collected diagnostics once a
-* config finishes, not the live `kubb:info`/`kubb:plugin` event stream. Color is stripped so the
-* file stays plain text even when the run is attached to a TTY.
+* @note It captures the collected diagnostics once a config finishes, not the live
+* `kubb:info`/`kubb:plugin` event stream. Color is stripped so the file stays plain text even when
+* the run is attached to a TTY.
 */
 const fileReporter = createReporter({
 	name: "file",