@kubb/core 5.0.0-beta.38 → 5.0.0-beta.39

package/src/constants.ts

@@ -1,12 +1,22 @@
 /**
- * Base URL for the Kubb Studio web app.
+ * Number of file writes to batch in parallel during `flushPendingFiles`.
  */
-export const DEFAULT_STUDIO_URL = 'https://kubb.studio' as const
+export const STREAM_FLUSH_EVERY = 50
 
 /**
- * Number of file writes to batch in parallel during `flushPendingFiles`.
+ * OpenTelemetry ingestion endpoint for anonymous usage telemetry.
  */
-export const STREAM_FLUSH_EVERY = 50
+export const OTLP_ENDPOINT = 'https://otlp.kubb.dev' as const
+
+/**
+ * Maximum number of █ characters in a plugin timing bar.
+ */
+export const SUMMARY_MAX_BAR_LENGTH = 10 as const
+
+/**
+ * Divides elapsed milliseconds into bar-length units (1 block per 100 ms).
+ */
+export const SUMMARY_TIME_SCALE_DIVISOR = 100 as const
 
 /**
  * Number of schema/operation nodes to dispatch concurrently during generation.
@@ -27,19 +37,6 @@ export const HOOK_LISTENERS_PER_PLUGIN = 4
  */
 export const OPERATION_FILTER_TYPES: ReadonlySet<string> = new Set(['tag', 'operationId', 'path', 'method', 'contentType'])
 
-/**
- * Numeric log-level thresholds used internally to compare verbosity.
- *
- * Higher numbers are more verbose.
- */
-export const logLevel = {
-  silent: Number.NEGATIVE_INFINITY,
-  error: 0,
-  warn: 1,
-  info: 3,
-  verbose: 4,
-} as const
-
 /**
  * Stable codes Kubb attaches to a `Diagnostic`. Each maps to a known failure mode
  * and stays stable so it can be referenced in tooling and (later) docs. Reference
@@ -97,10 +94,6 @@ export const diagnosticCode = {
    * without one.
    */
   adapterRequired: 'KUBB_ADAPTER_REQUIRED',
-  /**
-   * The `devtools` config is set to something other than an object.
-   */
-  devtoolsInvalid: 'KUBB_DEVTOOLS_INVALID',
   /**
    * A resolved output path escapes the output directory, which can stem from a path
    * traversal in the spec or a misconfigured `group.name`.

package/src/createKubb.ts

@@ -2,15 +2,15 @@ import { resolve } from 'node:path'
 import type { PossiblePromise } from '@internals/utils'
 import { AsyncEventEmitter, BuildError } from '@internals/utils'
 import type { FileNode, InputMeta, OperationNode, SchemaNode } from '@kubb/ast'
-import { DEFAULT_STUDIO_URL, HOOK_LISTENERS_PER_PLUGIN } from './constants.ts'
+import { HOOK_LISTENERS_PER_PLUGIN } from './constants.ts'
 import type { Adapter } from './createAdapter.ts'
-import { type Diagnostic, DiagnosticError, Diagnostics, isProblemDiagnostic, type ProblemDiagnostic, type UpdateDiagnostic } from './diagnostics.ts'
+import { type Diagnostic, Diagnostics, type ProblemDiagnostic, type UpdateDiagnostic } from './diagnostics.ts'
 import { createStorage, type Storage } from './createStorage.ts'
 import type { GeneratorContext } from './defineGenerator.ts'
 import type { Middleware } from './defineMiddleware.ts'
 import type { Parser } from './defineParser.ts'
 import type { KubbPluginEndContext, KubbPluginSetupContext, KubbPluginStartContext, Plugin } from './definePlugin.ts'
-import type { ReporterName } from './createReporter.ts'
+import type { Reporter, ReporterName } from './createReporter.ts'
 
 import { KubbDriver } from './KubbDriver.ts'
 import { fsStorage } from './storages/fsStorage.ts'
@@ -269,28 +269,6 @@ export type Config<TInput = Input> = {
    * @see {@link defineMiddleware} to create custom middleware.
    */
   middleware?: Array<Middleware>
-  /**
-   * Kubb Studio cloud integration settings.
-   *
-   * Kubb Studio (https://kubb.studio) is a web-based IDE for managing API specs and generated code.
-   * Set to `true` to enable with default settings, or pass an object to customize the Studio URL.
-   *
-   * @default false  // disabled by default
-   * @example
-   * ```ts
-   * devtools: true                                   // use default Kubb Studio
-   * devtools: { studioUrl: 'https://my-studio.dev' } // custom Studio instance
-   * ```
-   */
-  devtools?:
-    | true
-    | {
-        /**
-         * Override the Kubb Studio base URL.
-         * @default 'https://kubb.studio'
-         */
-        studioUrl?: typeof DEFAULT_STUDIO_URL | (string & {})
-      }
   /**
    * Lifecycle hooks that execute during or after the build process.
    *
@@ -323,21 +301,23 @@ export type Config<TInput = Input> = {
     done?: string | Array<string>
   }
   /**
-   * Reporters that render the run's output, like Vitest. List one or more by name;
-   * the CLI `--reporter` flag overrides this when set.
+   * The reporters available to the run, registered as instances. The host
+   * (the CLI via `--reporter`) selects which ones to trigger by `name` with {@link selectReporters}.
+   * `defineConfig` from the `kubb` package registers the built-in `cli`, `json`, and `file`
+   * reporters by default.
    *
    * - `cli` writes the end-of-run summary to the terminal.
    * - `json` writes a machine-readable report to stdout, for CI.
    * - `file` writes a debug log to `.kubb/<name>-<timestamp>.log`.
    *
-   * @default ['cli']
-   *
    * @example
    * ```ts
-   * reporters: ['cli', 'file']
+   * import { cliReporter, jsonReporter } from '@kubb/core'
+   *
+   * reporters: [cliReporter, jsonReporter, myReporter]
    * ```
    */
-  reporters?: Array<ReporterName>
+  reporters: Array<Reporter>
 }
 
 /**
@@ -345,7 +325,7 @@ export type Config<TInput = Input> = {
  *
  * `UserConfig` is what you pass to `defineConfig()`. It has optional `root`, `plugins`, `parsers`, and `adapter`
  * fields (which fall back to sensible defaults). All other Config options are available, including `output`, `input`,
- * `storage`, `middleware`, `devtools`, and `hooks`.
+ * `storage`, `middleware`, and `hooks`.
  *
  * @example
  * ```ts
@@ -356,7 +336,7 @@ export type Config<TInput = Input> = {
  * })
  * ```
  */
-export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage'> & {
+export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters'> & {
   /**
    * Project root directory, absolute or relative to the config file location.
    * @default process.cwd()
@@ -382,6 +362,12 @@ export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins'
    * @default fsStorage()
    */
   storage?: Storage
+  /**
+   * Reporters available to the run. `defineConfig` registers the built-in `cli`, `json`, and
+   * `file` reporters when omitted.
+   * @default [cliReporter, jsonReporter, fileReporter]  // applied by `defineConfig` from the `kubb` package
+   */
+  reporters?: Array<Reporter>
 }
 
 declare global {
@@ -877,25 +863,11 @@ function resolveConfig(userConfig: UserConfig): Config {
       ...userConfig.output,
     },
     storage: userConfig.storage ?? fsStorage(),
-    devtools: userConfig.devtools
-      ? {
-          studioUrl: DEFAULT_STUDIO_URL,
-          ...(typeof userConfig.devtools === 'boolean' ? {} : userConfig.devtools),
-        }
-      : undefined,
+    reporters: userConfig.reporters ?? [],
     plugins: userConfig.plugins ?? [],
   }
 }
 
-/**
- * Type guard to check if a given config has an `input.path`.
- */
-export function isInputPath(config: UserConfig | undefined): config is UserConfig<InputPath> & { input: InputPath }
-export function isInputPath(config: Config | undefined): config is Config<InputPath> & { input: InputPath }
-export function isInputPath(config: Config | UserConfig | undefined): config is (Config<InputPath> | UserConfig<InputPath>) & { input: InputPath } {
-  return typeof config?.input === 'object' && config.input !== null && 'path' in config.input
-}
-
 type CreateKubbOptions = {
   hooks?: AsyncEventEmitter<KubbHooks>
 }
@@ -973,9 +945,9 @@ export class Kubb {
     const out = await this.safeBuild()
     if (Diagnostics.hasError(out.diagnostics)) {
       const errors = out.diagnostics
-        .filter(isProblemDiagnostic)
+        .filter(Diagnostics.isProblem)
         .filter((diagnostic) => diagnostic.severity === 'error')
-        .map((diagnostic) => diagnostic.cause ?? new DiagnosticError(diagnostic))
+        .map((diagnostic) => diagnostic.cause ?? new Diagnostics.Error(diagnostic))
       throw new BuildError(`Build failed with ${errors.length} ${errors.length === 1 ? 'error' : 'errors'}`, { errors })
     }
     return out

package/src/createReporter.ts

@@ -1,4 +1,4 @@
-import type { logLevel } from './constants.ts'
+import type { logLevel } from './defineLogger.ts'
 import type { Config } from './createKubb.ts'
 import type { Diagnostic } from './diagnostics.ts'
 
@@ -45,7 +45,7 @@ export 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; `flush`, when present, runs once
+ * never sees the event emitter. `report` runs once per config; `drain`, when present, runs once
  * after the last config.
  */
 export type Reporter = {
@@ -61,23 +61,23 @@ export type Reporter = {
    * 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.
    */
-  flush?: (context: ReporterContext) => void | Promise<void>
+  drain?: (context: ReporterContext) => void | Promise<void>
 }
 
 /**
  * Reporter definition passed to {@link createReporter}. `report` returns the value to collect for
- * this config (e.g. a built report), and the optional `flush` receives the collected reports to
+ * this config (e.g. a built report), and the optional `drain` receives the collected reports to
  * emit as one document. `T` is inferred from `report`'s return type.
  */
 export type UserReporter<T = void> = {
   name: string
   report: (result: GenerationResult, context: ReporterContext) => T | Promise<T>
-  flush?: (context: ReporterContext, reports: Array<T>) => void | Promise<void>
+  drain?: (context: ReporterContext, reports: Array<T>) => void | Promise<void>
 }
 
 /**
- * Defines a reporter. When the definition has a `flush`, the returned reporter buffers each value
- * `report` returns and hands the array to `flush` once, then clears it. Without a `flush`, nothing
+ * Defines a reporter. When the definition has a `drain`, the returned reporter buffers each value
+ * `report` returns and hands the array to `drain` once, then clears it. Without a `drain`, nothing
  * is buffered. Wiring the reporter onto the run's events is the host's job, so the reporter only
  * ever deals with a {@link GenerationResult}.
  *
@@ -90,16 +90,21 @@ export type UserReporter<T = void> = {
  *   report(result) {
  *     return { status: Diagnostics.hasError(result.diagnostics) ? 'failed' : 'success', diagnostics: result.diagnostics }
  *   },
- *   flush(context, reports) {
+ *   drain(context, reports) {
  *     process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`)
  *   },
  * })
  * ```
  */
 export function createReporter<T = void>(reporter: UserReporter<T>): Reporter {
-  const flush = reporter.flush
-  if (!flush) {
-    return { name: reporter.name, report: reporter.report }
+  const drain = reporter.drain
+  if (!drain) {
+    return {
+      name: reporter.name,
+      async report(result, context) {
+        await reporter.report(result, context)
+      },
+    }
   }
 
   const reports: Array<T> = []
@@ -109,9 +114,34 @@ export function createReporter<T = void>(reporter: UserReporter<T>): Reporter {
     async report(result, context) {
       reports.push(await reporter.report(result, context))
     },
-    async flush(context) {
-      await flush(context, reports)
+    async drain(context) {
+      await drain(context, reports)
       reports.length = 0
     },
   }
 }
+
+/**
+ * Picks the reporters whose `name` matches one of `names`, in the order the names are given.
+ * The config carries every available reporter, and the host selects which to activate by name
+ * (the CLI maps `--reporter` to this). Duplicate names and names without a matching reporter are
+ * skipped.
+ */
+export function selectReporters(reporters: ReadonlyArray<Reporter>, names: ReadonlyArray<string>): Array<Reporter> {
+  const seen = new Set<string>()
+  const selected: Array<Reporter> = []
+
+  for (const name of names) {
+    if (seen.has(name)) {
+      continue
+    }
+    seen.add(name)
+
+    const reporter = reporters.find((candidate) => candidate.name === name)
+    if (reporter) {
+      selected.push(reporter)
+    }
+  }
+
+  return selected
+}

package/src/defineGenerator.ts

@@ -6,7 +6,7 @@ import type { KubbHooks } from './types.ts'
 import type { KubbDriver } from './KubbDriver.ts'
 import type { Plugin, PluginFactoryOptions } from './definePlugin.ts'
 import type { Resolver } from './defineResolver.ts'
-import type { Config, DevtoolsOptions } from './types.ts'
+import type { Config } from './types.ts'
 
 /**
  * Context object passed to generator `schema`, `operation`, and `operations` methods.
@@ -67,7 +67,7 @@ export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFacto
    * 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.
+   * `Diagnostics.Error` directly.
    */
   warn: (message: string) => void
   /**
@@ -80,10 +80,6 @@ export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFacto
    * the current plugin.
    */
   info: (message: string) => void
-  /**
-   * Open the current input node in Kubb Studio.
-   */
-  openInStudio: (options?: DevtoolsOptions) => Promise<void>
   /**
    * The configured adapter instance.
    */

package/src/defineLogger.ts

@@ -1,7 +1,19 @@
 import type { AsyncEventEmitter } from '@internals/utils'
-import type { logLevel } from './constants.ts'
 import type { KubbHooks } from './types.ts'
 
+/**
+ * Numeric log-level thresholds used internally to compare verbosity.
+ *
+ * Higher numbers are more verbose.
+ */
+export const logLevel = {
+  silent: Number.NEGATIVE_INFINITY,
+  error: 0,
+  warn: 1,
+  info: 3,
+  verbose: 4,
+} as const
+
 /**
  * Options accepted by a logger's `install` callback.
  */

package/src/defineResolver.ts

@@ -2,8 +2,7 @@ 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 { Diagnostics } from './diagnostics.ts'
 import type { PluginFactoryOptions } from './definePlugin.ts'
 import { getMode } from './definePlugin.ts'
 import type { Config, Group, Output } from './types.ts'
@@ -456,8 +455,8 @@ 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 DiagnosticError({
-      code: diagnosticCode.pathTraversal,
+    throw new Diagnostics.Error({
+      code: Diagnostics.code.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.',