@kubb/cli 5.0.0-beta.36 → 5.0.0-beta.38

package/src/loggers/githubActionsLogger.ts

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util'
-import { formatHrtime, formatMs, formatMsWithColor, toCause } from '@internals/utils'
-import { type Config, defineLogger, type KubbHooks, logLevel as logLevelMap } from '@kubb/core'
+import { formatMs, formatMsWithColor, toCause } from '@internals/utils'
+import { type Config, defineLogger, diagnosticCode, Diagnostics, isProblemDiagnostic, type KubbHooks, logLevel as logLevelMap } from '@kubb/core'
 import {
   buildProgressLine,
   createHookTimer,
@@ -127,14 +127,12 @@ export const githubActionsLogger = defineLogger({
       // (e.g., when getConfigs or kubb.setup throws) doesn't leak an open section.
       closeAllGroups()
 
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
+      // Errors are always surfaced, even at silent, so failures stay visible.
       const message = error.message || String(error)
       console.error(`::error::${message}`)
 
-      // Show stack trace in debug mode (first 3 frames)
-      if (logLevel >= logLevelMap.debug && error.stack) {
+      // Show stack trace in verbose mode (first 3 frames)
+      if (logLevel >= logLevelMap.verbose && error.stack) {
         const frames = error.stack.split('\n').slice(1, 4)
         for (const frame of frames) {
           console.log(getMessage(styleText('dim', frame.trim())))
@@ -151,15 +149,40 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
+    context.on('kubb:diagnostic', ({ diagnostic }) => {
+      closeAllGroups()
+
+      // Silent still surfaces errors so failures stay visible. It drops warnings and info.
+      if (logLevel <= logLevelMap.silent && diagnostic.severity !== 'error') {
+        return
+      }
+
+      if (!isProblemDiagnostic(diagnostic)) {
+        console.log(`::notice::${diagnostic.message}`)
+        return
+      }
+
+      const parts = [`${diagnostic.code} ${diagnostic.message}`]
+      if (diagnostic.location && 'pointer' in diagnostic.location) {
+        parts.push(`(at ${diagnostic.location.pointer})`)
+      }
+      if (diagnostic.plugin) {
+        parts.push(`[plugin: ${diagnostic.plugin}]`)
+      }
+      if (diagnostic.help) {
+        parts.push(`help: ${diagnostic.help}`)
+      }
+      if (diagnostic.code !== diagnosticCode.unknown) {
+        parts.push(`docs: ${Diagnostics.docsUrl(diagnostic.code)}`)
+      }
+      console.error(`::error::${parts.join(' ')}`)
+    })
+
     context.on('kubb:lifecycle:start', ({ version }) => {
       console.log(styleText('yellow', `Kubb ${version} 🧩`))
       reset()
     })
 
-    context.on('kubb:version:new', ({ currentVersion, latestVersion }) => {
-      console.log(`::notice::Update available for Kubb: v${currentVersion} → v${latestVersion}. Run \`npm install -g @kubb/cli\` to update.`)
-    })
-
     context.on('kubb:config:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
@@ -289,6 +312,10 @@ export const githubActionsLogger = defineLogger({
       )
 
       console.log(text)
+
+      if (state.currentConfigs.length > 1) {
+        closeGroup(config.name ? `Generation for ${styleText('bold', config.name)}` : 'Generation')
+      }
     })
 
     onGroupStart('kubb:format:start', 'Format started', 'Formatting')
@@ -338,26 +365,6 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('kubb:generation:summary', ({ config, status, hrStart, failedPlugins }) => {
-      const pluginsCount = config.plugins?.length ?? 0
-      const successCount = pluginsCount - failedPlugins.size
-      const duration = formatHrtime(hrStart)
-
-      if (state.currentConfigs.length > 1) {
-        console.log(' ')
-      }
-
-      console.log(
-        status === 'success'
-          ? `Kubb Summary: ${styleText('blue', '✓')} ${`${successCount} successful`}, ${pluginsCount} total, ${styleText('green', duration)}`
-          : `Kubb Summary: ${styleText('blue', '✓')} ${`${successCount} successful`}, ✗ ${`${failedPlugins.size} failed`}, ${pluginsCount} total, ${styleText('green', duration)}`,
-      )
-
-      if (state.currentConfigs.length > 1) {
-        closeGroup(config.name ? `Generation for ${styleText('bold', config.name)}` : 'Generation')
-      }
-    })
-
     context.on('kubb:lifecycle:end', () => {
       reset()
     })

package/src/loggers/plainLogger.ts

@@ -1,8 +1,7 @@
 import { relative } from 'node:path'
 import { formatMs, toCause } from '@internals/utils'
 import { defineLogger, type KubbHooks, logLevel as logLevelMap } from '@kubb/core'
-import { SUMMARY_SEPARATOR } from '../constants.ts'
-import { getSummary } from './utils.ts'
+import { formatDiagnostic } from './diagnostics.ts'
 import { createHookTimer, formatCommandWithArgs, formatMessage } from './utils.ts'
 
 /**
@@ -65,8 +64,8 @@ export const plainLogger = defineLogger({
 
       console.log(text)
 
-      // Show stack trace in debug mode (first 3 frames)
-      if (logLevel >= logLevelMap.debug && error.stack) {
+      // Show stack trace in verbose mode (first 3 frames)
+      if (logLevel >= logLevelMap.verbose && error.stack) {
         const frames = error.stack.split('\n').slice(1, 4)
         for (const frame of frames) {
           console.log(getMessage(frame.trim()))
@@ -83,16 +82,16 @@ export const plainLogger = defineLogger({
       }
     })
 
-    context.on('kubb:lifecycle:start', ({ version }) => {
-      console.log(`Kubb CLI v${version}`)
-    })
-
-    context.on('kubb:version:new', ({ currentVersion, latestVersion }) => {
-      if (logLevel <= logLevelMap.silent) {
+    context.on('kubb:diagnostic', ({ diagnostic }) => {
+      // Silent still surfaces errors so failures stay visible. It drops warnings and info.
+      if (logLevel <= logLevelMap.silent && diagnostic.severity !== 'error') {
         return
       }
+      console.log(getMessage(formatDiagnostic(diagnostic).join('\n')))
+    })
 
-      console.log(getMessage(`Update available: v${currentVersion} → v${latestVersion}. Run \`npm install -g @kubb/cli\` to update.`))
+    context.on('kubb:lifecycle:start', ({ version }) => {
+      console.log(`Kubb CLI v${version}`)
     })
 
     onStep('kubb:config:start', 'Configuration started')
@@ -198,21 +197,6 @@ export const plainLogger = defineLogger({
       }
     })
 
-    context.on('kubb:generation:summary', ({ config, pluginTimings, status, hrStart, failedPlugins, filesCreated }) => {
-      const summary = getSummary({
-        failedPlugins,
-        filesCreated,
-        config,
-        status,
-        hrStart,
-        pluginTimings: logLevel >= logLevelMap.verbose ? pluginTimings : undefined,
-      })
-
-      console.log(SUMMARY_SEPARATOR)
-      console.log(summary.join('\n'))
-      console.log(SUMMARY_SEPARATOR)
-    })
-
     return (_commandWithArgs: string, _hookId: string) => ({
       onStdout: logLevel > logLevelMap.silent ? (s: string) => console.log(s) : undefined,
       onStderr: logLevel > logLevelMap.silent ? (s: string) => console.error(s) : undefined,

package/src/loggers/types.ts

@@ -1,5 +1,5 @@
 /**
- * Logger adapter selected by `setupLogger` based on the runtime environment.
+ * Logger adapter selected by `setupReporters` based on the runtime environment.
  * - `'clack'`: TTY-aware output with spinners and progress bars.
  * - `'github-actions'`: CI output using `::group::` annotations.
  * - `'plain'`: Plain `console.log` output for non-TTY environments.

package/src/loggers/utils.ts

@@ -1,12 +1,12 @@
-import path from 'node:path'
 import process from 'node:process'
 import { styleText } from 'node:util'
-import { canUseTTY, formatHrtime, getElapsedMs, isGitHubActions, randomCliColor } from '@internals/utils'
-import type { Config, Logger, LoggerContext, LoggerOptions, Plugin } from '@kubb/core'
+import { canUseTTY, formatHrtime, getElapsedMs, isGitHubActions } from '@internals/utils'
+import type { Logger, LoggerContext, LoggerOptions, Reporter, ReporterContext, ReporterName } from '@kubb/core'
 import { logLevel as logLevelMap } from '@kubb/core'
-import { SUMMARY_MAX_BAR_LENGTH, SUMMARY_TIME_SCALE_DIVISOR } from '../constants.ts'
+import { cliReporter } from '../reporters/cliReporter.ts'
+import { fileReporter } from '../reporters/fileReporter.ts'
+import { jsonReporter } from '../reporters/jsonReporter.ts'
 import { clackLogger } from './clackLogger.ts'
-import { fileSystemLogger } from './fileSystemLogger.ts'
 import { githubActionsLogger } from './githubActionsLogger.ts'
 import { plainLogger } from './plainLogger.ts'
 import type { LoggerType } from './types.ts'
@@ -226,105 +226,58 @@ const logMapper: Record<LoggerType, CLILogger> = {
   'github-actions': githubActionsLogger,
 }
 
-export async function setupLogger(context: LoggerContext, { logLevel }: LoggerOptions): Promise<HookSinkFactory | null> {
-  const type = detectLogger()
-
-  const logger = logMapper[type]
-
-  if (!logger) {
-    throw new Error(`Unknown adapter type: ${type}`)
-  }
-
-  const makeSink = await logger.install(context, { logLevel })
+/**
+ * Bridges a {@link Reporter} onto the run's event emitter: calls `report` with each config's
+ * {@link GenerationResult} on `kubb:generation:end`. The reporter never touches the emitter.
+ */
+export function installReporter(context: LoggerContext, reporter: Reporter, ctx: ReporterContext): void {
+  context.on('kubb:generation:end', async ({ config, diagnostics = [], filesCreated = 0, status = 'success', hrStart = process.hrtime() }) => {
+    await reporter.report({ config, diagnostics, filesCreated, status, hrStart }, ctx)
+  })
 
-  if (logLevel >= logLevelMap.debug) {
-    await fileSystemLogger.install(context, { logLevel })
+  if (reporter.flush) {
+    context.on('kubb:lifecycle:end', () => reporter.flush?.(ctx))
   }
-
-  return typeof makeSink === 'function' ? makeSink : null
-}
-
-type SummaryProps = {
-  /**
-   * Set of plugins that failed during this generation run, each with its error.
-   */
-  failedPlugins: Set<{ plugin: Plugin; error: Error }>
-  /**
-   * Overall generation status used to choose success or failure formatting.
-   */
-  status: 'success' | 'failed'
-  /**
-   * `process.hrtime()` snapshot taken at the start of generation, used to compute elapsed time.
-   */
-  hrStart: [number, number]
-  /**
-   * Total number of files written during this generation run.
-   */
-  filesCreated: number
-  /**
-   * Resolved Kubb config for this generation entry, used to read plugin count and output path.
-   */
-  config: Config
-  /**
-   * Per-plugin timing map (plugin name → duration in ms). When provided, a timing bar chart is appended.
-   */
-  pluginTimings?: Map<string, number>
 }
 
 /**
- * Builds the generation summary lines rendered in the end-of-run box.
- * Returns an array of styled strings, one per summary row.
+ * Installs the live logger (the TUI view) and the selected reporters (the output), returning the
+ * terminal logger's hook sink when one was installed. Loggers and reporters are independent: the
+ * `cli` selection activates the env logger plus the {@link cliReporter} summary.
+ *
+ * The `json` reporter owns stdout, so the terminal logger and `cli` summary are suppressed whenever
+ * `json` is selected, even if `cli` is also listed.
  */
-export function getSummary({ failedPlugins, filesCreated, status, hrStart, config, pluginTimings }: SummaryProps): Array<string> {
-  const duration = formatHrtime(hrStart)
-
-  const pluginsCount = config.plugins?.length ?? 0
-  const successCount = pluginsCount - failedPlugins.size
-
-  const meta = {
-    plugins:
-      status === 'success'
-        ? `${styleText('green', `${successCount} successful`)}, ${pluginsCount} total`
-        : `${styleText('green', `${successCount} successful`)}, ${styleText('red', `${failedPlugins.size} failed`)}, ${pluginsCount} total`,
-    pluginsFailed: status === 'failed' ? [...failedPlugins].map(({ plugin }) => randomCliColor(plugin.name)).join(', ') : undefined,
-    filesCreated,
-    time: styleText('green', duration),
-    output: path.resolve(config.root, config.output.path),
-  } as const
-
-  const labels = {
-    plugins: 'Plugins:',
-    failed: 'Failed:',
-    generated: 'Generated:',
-    pluginTimings: 'Plugin Timings:',
-    output: 'Output:',
+export async function setupReporters(
+  context: LoggerContext,
+  { logLevel, reporters }: LoggerOptions & { reporters: ReadonlyArray<ReporterName> },
+): Promise<HookSinkFactory | null> {
+  const unique = new Set<ReporterName>(reporters.length ? reporters : ['cli'])
+  const hasJson = unique.has('json')
+  const ctx: ReporterContext = { logLevel }
+
+  let makeSink: HookSinkFactory | null = null
+
+  if (unique.has('cli') && !hasJson) {
+    const type = detectLogger()
+    const logger = logMapper[type]
+    if (!logger) {
+      throw new Error(`Unknown adapter type: ${type}`)
+    }
+    const sink = await logger.install(context, { logLevel })
+    makeSink = typeof sink === 'function' ? sink : null
+    installReporter(context, cliReporter, ctx)
   }
-  const maxLength = Math.max(0, ...[...Object.values(labels), ...(pluginTimings ? Array.from(pluginTimings.keys()) : [])].map((s) => s.length))
-
-  const summaryLines: Array<string> = []
-  summaryLines.push(`${labels.plugins.padEnd(maxLength + 2)} ${meta.plugins}`)
 
-  if (meta.pluginsFailed) {
-    summaryLines.push(`${labels.failed.padEnd(maxLength + 2)} ${meta.pluginsFailed}`)
+  if (hasJson) {
+    // json aggregates across configs: report buffers each result and flush writes one array on
+    // lifecycle end, rather than printing per config (which would concatenate documents and break `jq .`).
+    installReporter(context, jsonReporter, ctx)
   }
 
-  summaryLines.push(`${labels.generated.padEnd(maxLength + 2)} ${meta.filesCreated} files in ${meta.time}`)
-
-  if (pluginTimings && pluginTimings.size > 0) {
-    const sortedTimings = Array.from(pluginTimings.entries()).sort((a, b) => b[1] - a[1])
-
-    summaryLines.push(`${labels.pluginTimings}`)
-
-    sortedTimings.forEach(([name, time]) => {
-      const timeStr = time >= 1000 ? `${(time / 1000).toFixed(2)}s` : `${Math.round(time)}ms`
-      const barLength = Math.min(Math.ceil(time / SUMMARY_TIME_SCALE_DIVISOR), SUMMARY_MAX_BAR_LENGTH)
-      const bar = styleText('dim', '█'.repeat(barLength))
-
-      summaryLines.push(`${styleText('dim', '•')} ${name.padEnd(maxLength + 1)}${bar} ${timeStr}`)
-    })
+  if (unique.has('file')) {
+    installReporter(context, fileReporter, ctx)
   }
 
-  summaryLines.push(`${labels.output.padEnd(maxLength + 2)} ${meta.output}`)
-
-  return summaryLines
+  return makeSink
 }

package/src/reporters/cliReporter.ts

@@ -0,0 +1,89 @@
+import { styleText } from 'node:util'
+import { formatMs, randomCliColor } from '@internals/utils'
+import { createReporter, logLevel as logLevelMap } from '@kubb/core'
+import { SUMMARY_MAX_BAR_LENGTH, SUMMARY_TIME_SCALE_DIVISOR } from '../constants.ts'
+import { buildReport, type Report } from './report.ts'
+
+/**
+ * Builds the vitest/jest-style summary for one {@link Report}: right-aligned dim labels with
+ * `N passed (total)` counts, and a per-plugin `Timings` section when `showTimings`.
+ */
+function buildSummaryLines(report: Report, { showTimings }: { showTimings: boolean }): Array<string> {
+  const { status, plugins, counts, filesCreated, durationMs, output, timings } = report
+
+  const rows: Array<[label: string, value: string]> = []
+
+  rows.push([
+    'Plugins',
+    status === 'success'
+      ? `${styleText('green', `${plugins.passed} passed`)} (${plugins.total})`
+      : `${styleText('green', `${plugins.passed} passed`)} | ${styleText('red', `${plugins.failed.length} failed`)} (${plugins.total})`,
+  ])
+
+  if (status === 'failed' && plugins.failed.length > 0) {
+    rows.push(['Failed', plugins.failed.map((name) => randomCliColor(name)).join(', ')])
+  }
+
+  if (counts.errors > 0 || counts.warnings > 0) {
+    const issues = [
+      counts.errors > 0 ? styleText('red', `${counts.errors} ${counts.errors === 1 ? 'error' : 'errors'}`) : undefined,
+      counts.warnings > 0 ? styleText('yellow', `${counts.warnings} ${counts.warnings === 1 ? 'warning' : 'warnings'}`) : undefined,
+    ]
+      .filter(Boolean)
+      .join(' | ')
+    rows.push(['Issues', issues])
+  }
+
+  rows.push(['Files', `${styleText('green', String(filesCreated))} generated`])
+  rows.push(['Duration', styleText('green', formatMs(durationMs))])
+  rows.push(['Output', output])
+
+  const labelWidth = Math.max(...rows.map(([label]) => label.length), timings.length > 0 ? 'Timings'.length : 0)
+  const lines = rows.map(([label, value]) => `${styleText('dim', label.padStart(labelWidth))}  ${value}`)
+
+  if (showTimings && timings.length > 0) {
+    const nameWidth = Math.max(0, ...timings.map((timing) => timing.plugin.length))
+    const indent = ' '.repeat(labelWidth + 2)
+
+    lines.push(styleText('dim', 'Timings'.padStart(labelWidth)))
+    for (const timing of timings) {
+      const timeStr = formatMs(timing.durationMs)
+      const barLength = Math.min(Math.ceil(timing.durationMs / SUMMARY_TIME_SCALE_DIVISOR), SUMMARY_MAX_BAR_LENGTH)
+      const bar = styleText('dim', '█'.repeat(barLength))
+      lines.push(`${indent}${styleText('dim', '•')} ${timing.plugin.padEnd(nameWidth)} ${bar} ${timeStr}`)
+    }
+  }
+
+  return lines
+}
+
+/**
+ * Renders the summary as plain `console.log` lines so it works in every CLI (no clack/TTY
+ * dependency): a blank line, the config name colored by status, then the summary rows.
+ */
+function renderSummary(lines: ReadonlyArray<string>, { title, status }: { title: string; status: 'success' | 'failed' }): void {
+  console.log('')
+  if (title) {
+    console.log(styleText(status === 'failed' ? 'red' : 'green', title))
+  }
+  for (const line of lines) {
+    console.log(line)
+  }
+}
+
+/**
+ * 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.
+ */
+export const cliReporter = createReporter({
+  name: 'cli',
+  report(result, { logLevel }) {
+    if (logLevel <= logLevelMap.silent) {
+      return
+    }
+
+    const report = buildReport(result)
+    const lines = buildSummaryLines(report, { showTimings: logLevel >= logLevelMap.verbose })
+    renderSummary(lines, { title: report.name, status: report.status })
+  },
+})

package/src/reporters/fileReporter.ts

@@ -0,0 +1,103 @@
+import { relative, resolve } from 'node:path'
+import process from 'node:process'
+import { stripVTControlCharacters } from 'node:util'
+import { formatMs, write } from '@internals/utils'
+import { createReporter, type Diagnostic, isProblemDiagnostic } from '@kubb/core'
+import { formatDiagnostic } from '../loggers/diagnostics.ts'
+import { buildReport, type Report } from './report.ts'
+
+/**
+ * Builds the `## Summary` section: the same counts the cli and json reporters expose, as a list of
+ * `label  value` rows with the labels padded to a common width.
+ */
+function buildSummarySection(report: Report): Array<string> {
+  const { status, plugins, counts, filesCreated, durationMs, output } = report
+
+  const rows: Array<[label: string, value: string]> = [
+    ['Status', status],
+    [
+      'Plugins',
+      status === 'success' ? `${plugins.passed} passed (${plugins.total})` : `${plugins.passed} passed | ${plugins.failed.length} failed (${plugins.total})`,
+    ],
+  ]
+
+  if (plugins.failed.length > 0) {
+    rows.push(['Failed', plugins.failed.join(', ')])
+  }
+
+  rows.push(['Issues', `${counts.errors} errors | ${counts.warnings} warnings | ${counts.infos} infos`])
+  rows.push(['Files', `${filesCreated} generated`])
+  rows.push(['Duration', formatMs(durationMs)])
+  rows.push(['Output', output])
+
+  const labelWidth = Math.max(...rows.map(([label]) => label.length))
+  const lines = rows.map(([label, value]) => `  ${label.padEnd(labelWidth)}  ${value}`)
+
+  return ['## Summary', '', ...lines]
+}
+
+/**
+ * Builds the `## Problems` section: each problem rendered in the miette block format, blocks
+ * separated by a blank line. Returns an empty array when there are no problems, so the caller
+ * can drop the heading.
+ */
+function buildProblemSection(diagnostics: ReadonlyArray<Diagnostic>): Array<string> {
+  const problems = diagnostics.filter(isProblemDiagnostic)
+  if (problems.length === 0) {
+    return []
+  }
+
+  const blocks = problems.map((diagnostic) => formatDiagnostic(diagnostic).join('\n'))
+  return ['## Problems', '', blocks.join('\n\n')]
+}
+
+/**
+ * Builds the `## Timings` section from a {@link Report}: one `plugin   duration` row per record,
+ * slowest first with the plugin names left-aligned and the durations right-aligned. Returns an
+ * empty array when there are no timings.
+ */
+function buildTimingSection(report: Report): Array<string> {
+  const { timings } = report
+  if (timings.length === 0) {
+    return []
+  }
+
+  const nameWidth = Math.max(...timings.map((timing) => timing.plugin.length))
+  const durations = timings.map((timing) => formatMs(timing.durationMs))
+  const durationWidth = Math.max(...durations.map((duration) => duration.length))
+  const rows = timings.map((timing, index) => `  ${timing.plugin.padEnd(nameWidth)}  ${durations[index]!.padStart(durationWidth)}`)
+
+  return ['## Timings', '', ...rows]
+}
+
+/**
+ * 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.
+ *
+ * @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.
+ */
+export const fileReporter = createReporter({
+  name: 'file',
+  async report(result) {
+    const { diagnostics, config } = result
+    if (diagnostics.length === 0) {
+      return
+    }
+
+    const report = buildReport(result)
+    const header = config.name ? `# ${config.name} — ${new Date().toISOString()}` : `# ${new Date().toISOString()}`
+    const sections = [buildSummarySection(report), buildProblemSection(diagnostics), buildTimingSection(report)].filter((section) => section.length > 0)
+    const content = stripVTControlCharacters([header, ...sections.map((section) => section.join('\n'))].join('\n\n'))
+
+    const baseName = `${['kubb', config.name, Date.now()].filter(Boolean).join('-')}.log`
+    const pathName = resolve(process.cwd(), '.kubb', baseName)
+
+    await write(pathName, `${content}\n`)
+    console.error(`Debug log written to ${relative(process.cwd(), pathName)}`)
+  },
+})

package/src/reporters/jsonReporter.ts

@@ -0,0 +1,20 @@
+import process from 'node:process'
+import { createReporter } from '@kubb/core'
+import { buildReport } from './report.ts'
+
+/**
+ * The `json` reporter. `report` returns one config's {@link Report}, which {@link createReporter}
+ * buffers, and `flush` writes them as a single pretty-printed JSON array on `kubb:lifecycle:end`.
+ * Buffering keeps a multi-config run one valid JSON document on stdout instead of concatenated
+ * objects that would break `jq .`. The terminal reporter is suppressed while `json` is active so
+ * stdout stays valid JSON.
+ */
+export const jsonReporter = createReporter({
+  name: 'json',
+  report(result) {
+    return buildReport(result)
+  },
+  flush(_context, reports) {
+    process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`)
+  },
+})

package/src/reporters/report.ts

@@ -0,0 +1,84 @@
+import { resolve } from 'node:path'
+import { getElapsedMs } from '@internals/utils'
+import { Diagnostics, type GenerationResult, isPerformanceDiagnostic, isProblemDiagnostic, type SerializedDiagnostic } from '@kubb/core'
+
+/**
+ * One plugin's elapsed time, derived from a `performance` diagnostic.
+ */
+export type ReportTiming = {
+  plugin: string
+  durationMs: number
+}
+
+/**
+ * The normalized result of generating one config, shared by every reporter. Each reporter renders
+ * the same {@link Report} in its own format (the `cli` summary, the `json` document, the `file`
+ * log), so they always agree on the numbers. Build it with {@link buildReport}.
+ */
+export type Report = {
+  /**
+   * The config name, or an empty string when it is unnamed.
+   */
+  name: string
+  status: 'success' | 'failed'
+  plugins: {
+    passed: number
+    /**
+     * Names of the plugins that failed.
+     */
+    failed: Array<string>
+    total: number
+  }
+  counts: {
+    errors: number
+    warnings: number
+    infos: number
+  }
+  filesCreated: number
+  /**
+   * Wall-clock time spent generating this config, in milliseconds.
+   */
+  durationMs: number
+  /**
+   * Absolute output directory the files were written to.
+   */
+  output: string
+  /**
+   * Per-plugin durations, slowest first.
+   */
+  timings: Array<ReportTiming>
+  /**
+   * The build problems, serialized to their JSON-safe fields plus a `docsUrl`.
+   */
+  diagnostics: Array<SerializedDiagnostic>
+}
+
+/**
+ * Builds the normalized {@link Report} for one config from its {@link GenerationResult}. Splits the
+ * diagnostics into problems and per-plugin timings (slowest first) and derives the plugin and issue
+ * counts, so every reporter renders the same data.
+ */
+export function buildReport(result: GenerationResult): Report {
+  const { config, diagnostics, filesCreated, status, hrStart } = result
+
+  const failed = Diagnostics.failedPlugins(diagnostics)
+  const total = config.plugins?.length ?? 0
+  const counts = Diagnostics.count(diagnostics)
+  const problems = diagnostics.filter(isProblemDiagnostic)
+  const timings = diagnostics
+    .filter(isPerformanceDiagnostic)
+    .sort((a, b) => b.duration - a.duration)
+    .map((diagnostic) => ({ plugin: diagnostic.plugin, durationMs: diagnostic.duration }))
+
+  return {
+    name: config.name ?? '',
+    status,
+    plugins: { passed: total - failed.length, failed, total },
+    counts,
+    filesCreated,
+    durationMs: getElapsedMs(hrStart),
+    output: resolve(config.root, config.output.path),
+    timings,
+    diagnostics: problems.map((diagnostic) => Diagnostics.serialize(diagnostic)),
+  }
+}

package/src/runners/agent/run.ts

@@ -50,10 +50,10 @@ export async function run({ port, host, configPath, allowWrite, allowAll, versio
     try {
       process.loadEnvFile()
     } catch {
-      // .env file may not exist; ignore
+      // .env file may not exist. Ignore
     }
 
-    // Resolve the @kubb/agent package path — createRequire is CJS/ESM compatible (import.meta.resolve is ESM-only)
+    // Resolve the @kubb/agent package path, createRequire is CJS/ESM compatible (import.meta.resolve is ESM-only)
     const require = createRequire(import.meta.url)
     let agentPkgPath: string
     try {