import type { LiteralUnion, ValueOf } from '@internals/utils' import type { Config } from './types.ts' import type { Diagnostic } from './Diagnostics.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 /** * A built-in reporter that renders a run's output, independent of the live logger view. * * - `cli` renders the per-config summary to the terminal (the default). * - `json` writes a machine-readable report to stdout, for CI. * - `file` writes a config's diagnostics to `.kubb/kubb--.log`. * - `html` writes a browsable report directory to `.kubb/kubb--/`. */ export type ReporterName = 'cli' | 'json' | 'file' | 'html' /** * Files attributed to the plugin that first added them. */ export type ReporterPluginFiles = Array<{ /** Plugin name. */ plugin: string /** Generated file paths. */ files: Array }> /** * One config's outcome within a run, as handed to a {@link Reporter}. */ export type GenerationResult = { config: Config /** * Diagnostics collected while generating this config. */ diagnostics: Array /** * Number of generated files for this config, including unchanged files. */ filesCreated: number /** * Number of generated files whose content matches the previous output. */ filesUnchanged?: number /** * Changes compared with the output before this run, when the host collected them. * Line totals include added and deleted files. */ fileChanges?: { added: number modified: number deleted: number linesAdded: number linesRemoved: number } /** * The result previews generation without writing output. */ dryRun?: boolean status: 'success' | 'failed' /** * `process.hrtime()` snapshot taken when this config started generating. */ hrStart: [number, number] /** * Files attributed to the plugin that first added them, when requested by a reporter. */ pluginFiles?: ReporterPluginFiles } /** * Render settings passed alongside the {@link GenerationResult}. These are not part of the run * data, such as the output verbosity. */ export type ReporterContext = { /** * Output verbosity. Use the `logLevel` constants exported from `@kubb/core` * (`silent`, `error`, `warn`, `info`, `verbose`). */ logLevel: ValueOf } /** * Host-facing reporter, as installed onto a run. Unlike a Logger (the live TUI view), a reporter * never sees the hook emitter. `report` runs once per config. `drain`, when present, runs once * after the last config. */ export type Reporter = { /** * Display name, matching a {@link ReporterName} for the built-ins. */ name: LiteralUnion /** * Called once per config with that config's result and the render context. */ report: (result: GenerationResult, context: ReporterContext) => void | Promise /** * Runs once after the run's last config, on `kubb:lifecycle:end`. Only a reporter that collects * its configs' reports into one document, such as `json`, has one. */ drain?: (context: ReporterContext) => void | Promise /** * Whether the host should collect files from `kubb:plugin:end` hooks. */ needsPluginFiles?: boolean } /** * Reporter definition passed to {@link createReporter}. `report` returns the value to collect for * 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 = { name: LiteralUnion /** * Whether the host should collect files from `kubb:plugin:end` hooks. */ needsPluginFiles?: boolean report: (result: GenerationResult, context: ReporterContext) => T | Promise drain?: (context: ReporterContext, reports: Array) => void | Promise } /** * Defines a reporter. The returned reporter buffers each value `report` returns in order and, when * the definition has a `drain`, hands the array to `drain` once and then clears it. Wiring the * reporter onto the run's hooks is the host's job, so the reporter only ever deals with a * {@link GenerationResult}. * * @example * ```ts * import { createReporter, Diagnostics } from '@kubb/core' * * export const jsonReporter = createReporter({ * name: 'json', * report(result) { * return { status: Diagnostics.hasError(result.diagnostics) ? 'failed' : 'success', diagnostics: result.diagnostics } * }, * drain(context, reports) { * process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`) * }, * }) * ``` */ export function createReporter(reporter: UserReporter): Reporter { const { name, needsPluginFiles, drain } = reporter const reports: Array = [] return { name, needsPluginFiles, async report(result, context) { const report = await reporter.report(result, context) if (drain) reports.push(report) }, ...(drain && { async drain(context: ReporterContext) { await drain(context, reports.splice(0)) }, }), } }