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

package/src/diagnostics.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { styleText } from 'node:util'
 import type { AsyncEventEmitter } from '@internals/utils'
 import { getErrorMessage } from '@internals/utils'
 import { version } from '../package.json'
@@ -159,7 +160,7 @@ export type UpdateDiagnostic = {
 export type Diagnostic = ProblemDiagnostic | PerformanceDiagnostic | UpdateDiagnostic
 
 /**
- * Maps each {@link DiagnosticCode} to the variant it selects, for {@link narrowDiagnostic}.
+ * Maps each {@link DiagnosticCode} to the variant it selects, for {@link narrow}.
  * Every {@link ProblemCode} selects a {@link ProblemDiagnostic}, and the two bookkeeping codes
  * select their own variant.
  */
@@ -172,13 +173,13 @@ export type DiagnosticByCode = Record<ProblemCode, ProblemDiagnostic> &
  *
  * @example
  * ```ts
- * const update = narrowDiagnostic(diagnostic, diagnosticCode.updateAvailable)
+ * const update = narrow(diagnostic, diagnosticCode.updateAvailable)
  * if (update) {
  *   console.log(update.latestVersion)
  * }
  * ```
  */
-export function narrowDiagnostic<C extends DiagnosticCode>(diagnostic: Diagnostic, code: C): DiagnosticByCode[C] | null {
+function narrow<C extends DiagnosticCode>(diagnostic: Diagnostic, code: C): DiagnosticByCode[C] | null {
   return diagnostic.code === code ? (diagnostic as DiagnosticByCode[C]) : null
 }
 
@@ -195,34 +196,44 @@ function isKind<T extends Diagnostic>(kind: DiagnosticKind) {
  *
  * @example
  * ```ts
- * if (isProblemDiagnostic(diagnostic)) {
+ * if (isProblem(diagnostic)) {
  *   console.log(diagnostic.location)
  * }
  * ```
  */
-export const isProblemDiagnostic = isKind<ProblemDiagnostic>('problem')
+const isProblem = isKind<ProblemDiagnostic>('problem')
 
 /**
  * Returns `true` when the diagnostic is a per-plugin {@link PerformanceDiagnostic}.
  *
  * @example
  * ```ts
- * const timings = diagnostics.filter(isPerformanceDiagnostic)
+ * const timings = diagnostics.filter(isPerformance)
  * ```
  */
-export const isPerformanceDiagnostic = isKind<PerformanceDiagnostic>('performance')
+const isPerformance = isKind<PerformanceDiagnostic>('performance')
 
 /**
  * Returns `true` when the diagnostic is a version-update {@link UpdateDiagnostic}.
  *
  * @example
  * ```ts
- * if (isUpdateDiagnostic(diagnostic)) {
+ * if (isUpdate(diagnostic)) {
  *   console.log(diagnostic.latestVersion)
  * }
  * ```
  */
-export const isUpdateDiagnostic = isKind<UpdateDiagnostic>('update')
+const isUpdate = isKind<UpdateDiagnostic>('update')
+
+/**
+ * Glyph and accent color per severity, matching the miette/oxlint convention
+ * (`×` error, `⚠` warning, `ℹ` advice).
+ */
+const severityStyle: Record<DiagnosticSeverity, { glyph: string; color: 'red' | 'yellow' | 'blue' }> = {
+  error: { glyph: '×', color: 'red' },
+  warning: { glyph: '⚠', color: 'yellow' },
+  info: { glyph: 'ℹ', color: 'blue' },
+}
 
 /**
  * A {@link Diagnostic} reduced to its JSON-safe fields plus a `docsUrl`, for
@@ -242,49 +253,11 @@ export type SerializedDiagnostic = {
   docsUrl?: string
 }
 
-/**
- * An `Error` that carries a {@link Diagnostic}, so structured problems can flow
- * through the existing throw/catch paths while keeping their code and location.
- *
- * @example
- * ```ts
- * throw new DiagnosticError({ code: diagnosticCode.refNotFound, severity: 'error', message: `Could not find ${ref}`, location: { kind: 'schema', pointer: ref, ref } })
- * ```
- */
-export class DiagnosticError extends Error {
-  diagnostic: ProblemDiagnostic
-
-  constructor(diagnostic: ProblemDiagnostic) {
-    super(diagnostic.message, { cause: diagnostic.cause })
-    this.name = 'DiagnosticError'
-    this.diagnostic = diagnostic
-  }
-}
-
-/**
- * Structural check for a {@link DiagnosticError}, including one thrown from a duplicated
- * `@kubb/core` copy where `instanceof` fails. Matches on the `name` and a `diagnostic`
- * that carries a `code`.
- */
-function isDiagnosticError(error: unknown): error is DiagnosticError {
-  if (error instanceof DiagnosticError) {
-    return true
-  }
-  return (
-    error instanceof Error &&
-    error.name === 'DiagnosticError' &&
-    'diagnostic' in error &&
-    typeof (error as { diagnostic?: unknown }).diagnostic === 'object' &&
-    (error as { diagnostic?: Diagnostic }).diagnostic !== null &&
-    typeof (error as { diagnostic?: { code?: unknown } }).diagnostic?.code === 'string'
-  )
-}
-
 /**
  * Explanation for every {@link diagnosticCode}. Use {@link Diagnostics.explain} to look one up
  * and `Diagnostics.docsUrl` for the matching kubb.dev page.
  */
-export const diagnosticCatalog: Record<DiagnosticCode, DiagnosticDoc> = {
+const diagnosticCatalog: Record<DiagnosticCode, DiagnosticDoc> = {
   [diagnosticCode.unknown]: {
     title: 'Unknown error',
     cause: 'An error was thrown without a stable Kubb code, so it is reported as-is.',
@@ -342,14 +315,9 @@ export const diagnosticCatalog: Record<DiagnosticCode, DiagnosticDoc> = {
   },
   [diagnosticCode.adapterRequired]: {
     title: 'Adapter required',
-    cause: 'An action needs an adapter (for example opening Kubb Studio) but none is configured.',
+    cause: 'An action needs an adapter but none is configured.',
     fix: 'Set `adapter` in kubb.config.ts, for example `adapterOas()`.',
   },
-  [diagnosticCode.devtoolsInvalid]: {
-    title: 'Invalid devtools config',
-    cause: 'The `devtools` config is set to something other than an object.',
-    fix: 'Set `devtools` to an options object, or remove it to disable Kubb Studio.',
-  },
   [diagnosticCode.pathTraversal]: {
     title: 'Path traversal',
     cause: 'A resolved output path escaped the output directory, which can stem from a path traversal in the spec or a misconfigured `group.name`.',
@@ -394,6 +362,69 @@ export const diagnosticCatalog: Record<DiagnosticCode, DiagnosticDoc> = {
 export class Diagnostics {
   static #reporterStorage = new AsyncLocalStorage<(diagnostic: Diagnostic) => void>()
 
+  /**
+   * The diagnostic code catalog, exposed as `Diagnostics.code` (e.g. `Diagnostics.code.refNotFound`).
+   */
+  static code = diagnosticCode
+
+  /**
+   * Type guard for a build {@link ProblemDiagnostic}.
+   */
+  static isProblem = isProblem
+
+  /**
+   * Type guard for a version-update {@link UpdateDiagnostic}.
+   */
+  static isUpdate = isUpdate
+
+  /**
+   * Type guard for a per-plugin {@link PerformanceDiagnostic}.
+   */
+  static isPerformance = isPerformance
+
+  /**
+   * Narrows a {@link Diagnostic} to the variant for `code`, or `null` when it does not match.
+   */
+  static narrow = narrow
+
+  /**
+   * An `Error` that carries a {@link Diagnostic}, so structured problems can flow
+   * through the existing throw/catch paths while keeping their code and location.
+   *
+   * @example
+   * ```ts
+   * throw new Diagnostics.Error({ code: diagnosticCode.refNotFound, severity: 'error', message: `Could not find ${ref}`, location: { kind: 'schema', pointer: ref, ref } })
+   * ```
+   */
+  static Error = class DiagnosticError extends Error {
+    diagnostic: ProblemDiagnostic
+
+    constructor(diagnostic: ProblemDiagnostic) {
+      super(diagnostic.message, { cause: diagnostic.cause })
+      this.name = 'DiagnosticError'
+      this.diagnostic = diagnostic
+    }
+  }
+
+  /**
+   * Structural check for a {@link Diagnostics.Error}, including one thrown from a duplicated
+   * `@kubb/core` copy where `instanceof` fails. Matches on the `name` and a `diagnostic`
+   * that carries a `code`.
+   */
+  static isError(error: unknown): error is InstanceType<typeof Diagnostics.Error> {
+    if (error instanceof Diagnostics.Error) {
+      return true
+    }
+    return (
+      error instanceof Error &&
+      error.name === 'DiagnosticError' &&
+      'diagnostic' in error &&
+      typeof (error as { diagnostic?: unknown }).diagnostic === 'object' &&
+      (error as { diagnostic?: Diagnostic }).diagnostic !== null &&
+      typeof (error as { diagnostic?: { code?: unknown } }).diagnostic?.code === 'string'
+    )
+  }
+
   /**
    * Runs `fn` with `sink` as the active diagnostic sink for the whole async
    * subtree, so {@link Diagnostics.report} reaches it from anywhere inside.
@@ -427,21 +458,21 @@ export class Diagnostics {
   }
 
   /**
-   * Coerces any thrown value into a {@link ProblemDiagnostic}. A {@link DiagnosticError}
+   * Coerces any thrown value into a {@link ProblemDiagnostic}. A {@link Diagnostics.Error}
    * keeps its structured data, and anything else becomes a `KUBB_UNKNOWN` error.
    */
   static from(error: unknown): ProblemDiagnostic {
     // The event emitter and BuildError wrap the original, so walk the cause chain to
-    // recover a DiagnosticError thrown deeper down. `root` tracks the deepest error so
+    // recover a Diagnostics.Error thrown deeper down. `root` tracks the deepest error so
     // the unknown diagnostic reports the original message and stack, not the wrapper's.
     const seen = new Set<unknown>()
     let current: unknown = error
     let root: Error | undefined
     while (current instanceof Error && !seen.has(current)) {
-      // Match structurally, not just by `instanceof`: a `DiagnosticError` thrown from a
+      // Match structurally, not just by `instanceof`: a `Diagnostics.Error` thrown from a
       // duplicated `@kubb/core` copy (bundled into an adapter or plugin) is a different
       // class, but still carries the same `diagnostic`, so its code must survive.
-      if (isDiagnosticError(current)) {
+      if (Diagnostics.isError(current)) {
         return current.diagnostic
       }
       seen.add(current)
@@ -516,7 +547,7 @@ export class Diagnostics {
     let warnings = 0
     let infos = 0
     for (const diagnostic of diagnostics) {
-      if (!isProblemDiagnostic(diagnostic)) {
+      if (!isProblem(diagnostic)) {
         continue
       }
       if (diagnostic.severity === 'error') {
@@ -539,7 +570,7 @@ export class Diagnostics {
     const seen = new Set<string>()
     const result: Array<Diagnostic> = []
     for (const diagnostic of diagnostics) {
-      if (!isProblemDiagnostic(diagnostic)) {
+      if (!isProblem(diagnostic)) {
         result.push(diagnostic)
         continue
       }
@@ -577,7 +608,7 @@ export class Diagnostics {
    * fields are omitted rather than set to `undefined`.
    */
   static serialize(diagnostic: Diagnostic): SerializedDiagnostic {
-    const problem = isProblemDiagnostic(diagnostic) ? diagnostic : undefined
+    const problem = isProblem(diagnostic) ? diagnostic : undefined
     return {
       code: diagnostic.code,
       severity: diagnostic.severity,
@@ -588,4 +619,42 @@ export class Diagnostics {
       ...(diagnostic.code === diagnosticCode.unknown ? {} : { docsUrl: Diagnostics.docsUrl(diagnostic.code) }),
     }
   }
+
+  /**
+   * Renders a {@link Diagnostic} for terminal output as its parts: the colored severity `symbol`
+   * (the gutter glyph), the `plugin(CODE): message` `headline`, and the `details` lines (optional
+   * `at <pointer>`, `help:`, and `docs:`).
+   *
+   * Hosts compose these to fit their gutter: a clack logger passes `symbol` as its own gutter and
+   * `[headline, ...details]` as the message, while plain text outputs use {@link Diagnostics.formatLines}.
+   */
+  static format(diagnostic: Diagnostic): { symbol: string; headline: string; details: Array<string> } {
+    const { code, severity, message } = diagnostic
+    const { glyph, color } = severityStyle[severity]
+    const problem = isProblem(diagnostic) ? diagnostic : undefined
+
+    const rule = styleText(color, styleText('bold', problem?.plugin ? `${problem.plugin}(${code})` : code))
+    const details: Array<string> = []
+
+    if (problem?.location && 'pointer' in problem.location) {
+      details.push(`  ${styleText('dim', 'at')} ${styleText('cyan', problem.location.pointer)}`)
+    }
+    if (problem?.help) {
+      details.push(`  ${styleText('cyan', 'help:')} ${problem.help}`)
+    }
+    if (code !== diagnosticCode.unknown) {
+      details.push(`  ${styleText('dim', 'docs:')} ${styleText('cyan', Diagnostics.docsUrl(code))}`)
+    }
+
+    return { symbol: styleText(color, styleText('bold', glyph)), headline: `${rule}: ${message}`, details }
+  }
+
+  /**
+   * The self-contained block form of {@link Diagnostics.format}: `${symbol} ${headline}` followed by
+   * the detail lines. Used where there is no gutter to own the symbol (plain and file output).
+   */
+  static formatLines(diagnostic: Diagnostic): Array<string> {
+    const { symbol, headline, details } = Diagnostics.format(diagnostic)
+    return [`${symbol} ${headline}`, ...details]
+  }
 }

package/src/index.ts

@@ -1,30 +1,22 @@
-export { AsyncEventEmitter, URLPath } from '@internals/utils'
+export { AsyncEventEmitter } from '@internals/utils'
 export * as ast from '@kubb/ast'
-export { diagnosticCode, logLevel } from './constants.ts'
 export { createAdapter } from './createAdapter.ts'
-export {
-  diagnosticCatalog,
-  DiagnosticError,
-  Diagnostics,
-  isPerformanceDiagnostic,
-  isProblemDiagnostic,
-  isUpdateDiagnostic,
-  narrowDiagnostic,
-} from './diagnostics.ts'
+export { Diagnostics } from './diagnostics.ts'
 export { createKubb } from './createKubb.ts'
-export { createReporter } from './createReporter.ts'
+export { createReporter, selectReporters } from './createReporter.ts'
+export { cliReporter } from './reporters/cliReporter.ts'
+export { fileReporter } from './reporters/fileReporter.ts'
+export { jsonReporter } from './reporters/jsonReporter.ts'
+export { Telemetry } from './Telemetry.ts'
 export { createRenderer } from './createRenderer.ts'
 export { createStorage } from './createStorage.ts'
 export { defineGenerator } from './defineGenerator.ts'
-export { defineLogger } from './defineLogger.ts'
+export { defineLogger, logLevel } from './defineLogger.ts'
 export { defineMiddleware } from './defineMiddleware.ts'
 export { defineParser } from './defineParser.ts'
 export { definePlugin } from './definePlugin.ts'
 export { defineResolver } from './defineResolver.ts'
-export { FileManager } from './FileManager.ts'
-export { FileProcessor } from './FileProcessor.ts'
 export { KubbDriver } from './KubbDriver.ts'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'
-export { isInputPath } from './createKubb.ts'

package/src/mocks.ts

@@ -1,8 +1,13 @@
-import { resolve } from 'node:path'
+import path, { resolve } from 'node:path'
+import { camelCase } from '@internals/utils'
 import type { FileNode, InputMeta, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
 import { transform } from '@kubb/ast'
+import { expect } from 'vitest'
+import type { Parser } from './defineParser.ts'
 import { FileManager } from './FileManager.ts'
+import { FileProcessor } from './FileProcessor.ts'
 import { KubbDriver } from './KubbDriver.ts'
+import { memoryStorage } from './storages/memoryStorage.ts'
 import type { Adapter, AdapterFactoryOptions, Config, Generator, GeneratorContext, NormalizedPlugin, PluginFactoryOptions, RendererFactory } from './types.ts'
 
 /**
@@ -119,7 +124,6 @@ function createMockedPluginContext<TOptions extends PluginFactoryOptions>(opts:
     warn: (msg: string) => console.warn(msg),
     error: (msg: string) => console.error(msg),
     info: (msg: string) => console.info(msg),
-    openInStudio: async () => {},
   } as unknown as Omit<GeneratorContext<TOptions>, 'options'>
 }
 
@@ -194,3 +198,54 @@ export async function renderGeneratorOperations<TOptions extends PluginFactoryOp
   })
   await opts.driver.dispatch({ result, renderer: generator.renderer })
 }
+
+type MatchFilesOptions = {
+  /**
+   * Parsers indexed by file extension, used to render each `FileNode` to source.
+   * Without a matching parser the file's raw content is used.
+   */
+  parsers?: Map<FileNode['extname'], Parser>
+  /**
+   * Formatter applied to non-JSON output before snapshotting, e.g. prettier. When
+   * omitted the parsed source is snapshotted as-is.
+   */
+  format?: (source?: string) => string | Promise<string>
+  /**
+   * Subfolder under `__snapshots__`, camelCased. Useful to keep variant snapshots apart.
+   */
+  pre?: string
+}
+
+/**
+ * Renders the driver's collected `FileNode`s to source and asserts each against a file snapshot.
+ * Pair it with the `renderGenerator*` helpers to snapshot a generator's output.
+ *
+ * @example
+ * ```ts
+ * await renderGeneratorSchema(typeGenerator, node, { config, adapter, driver, plugin, options, resolver })
+ * await matchFiles(driver.fileManager.files, { parsers, format })
+ * ```
+ */
+export async function matchFiles(files: Array<FileNode> | undefined, options: MatchFilesOptions = {}): Promise<Map<string, string> | undefined> {
+  if (!files?.length) return
+
+  const { parsers = new Map(), format, pre } = options
+  const fileProcessor = new FileProcessor({ storage: memoryStorage(), parsers })
+  const processed = new Map<string, string>()
+
+  for (const file of files) {
+    if (!file?.path || processed.has(file.path)) {
+      continue
+    }
+
+    const parsed = fileProcessor.parse(file)
+    const code = file.baseName.endsWith('.json') || !format ? parsed : await format(parsed)
+
+    processed.set(file.path, code)
+
+    const snapshotPath = path.join('__snapshots__', ...(pre ? [camelCase(pre)] : []), file.baseName)
+    await expect(code).toMatchFileSnapshot(snapshotPath)
+  }
+
+  return processed
+}

package/src/reporters/cliReporter.ts

@@ -0,0 +1,90 @@
+import { styleText } from 'node:util'
+import { formatMs, randomCliColor } from '@internals/utils'
+import { SUMMARY_MAX_BAR_LENGTH, SUMMARY_TIME_SCALE_DIVISOR } from '../constants.ts'
+import { logLevel as logLevelMap } from '../defineLogger.ts'
+import { createReporter } from '../createReporter.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 } from '../createReporter.ts'
+import { type Diagnostic, Diagnostics } from '../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(Diagnostics.isProblem)
+  if (problems.length === 0) {
+    return []
+  }
+
+  const blocks = problems.map((diagnostic) => Diagnostics.formatLines(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 '../createReporter.ts'
+import { buildReport } from './report.ts'
+
+/**
+ * The `json` reporter. `report` returns one config's {@link Report}, which {@link createReporter}
+ * buffers, and `drain` 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)
+  },
+  drain(_context, reports) {
+    process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`)
+  },
+})