@kubb/cli 5.0.0-beta.6 → 5.0.0-beta.61

package/src/loggers/clackLogger.ts

@@ -2,49 +2,52 @@ import { relative } from 'node:path'
 import process from 'node:process'
 import { styleText } from 'node:util'
 import * as clack from '@clack/prompts'
-import { formatMs, formatMsWithColor, getIntro, toCause } from '@internals/utils'
-import { defineLogger, logLevel as logLevelMap } from '@kubb/core'
-import { getSummary } from '../utils/getSummary.ts'
-import { runHook } from '../utils/runHook.ts'
-import { ClackWritable } from '../utils/Writables.ts'
-import { buildProgressLine, formatCommandWithArgs, formatMessage } from './utils.ts'
+import { formatMsWithColor, getElapsedMs, getIntro, toCause } from '@internals/utils'
+import { Diagnostics, type KubbHooks, logLevel as logLevelMap } from '@kubb/core'
+import { defineLogger } from './defineLogger.ts'
+import { buildProgressLine, createProgressCounters, formatCommandWithArgs, formatMessage, recordPluginResult, resetProgressCounters } from './utils.ts'
 
 /**
- * TTY logger with beautiful UI and progress indicators for local development.
+ * TTY logger for local development, with spinners and progress bars.
  */
 export const clackLogger = defineLogger({
   name: 'clack',
   install(context, options) {
     const logLevel = options?.logLevel ?? logLevelMap.info
     const state = {
-      totalPlugins: 0,
-      completedPlugins: 0,
-      failedPlugins: 0,
-      totalFiles: 0,
-      processedFiles: 0,
-      hrStart: process.hrtime(),
+      ...createProgressCounters(),
       spinner: clack.spinner(),
       isSpinning: false,
+      runningPlugins: new Set<string>(),
       activeProgress: new Map<string, { interval?: NodeJS.Timeout; progressBar: clack.ProgressResult }>(),
+      activeHookLogs: new Map<string, { taskLog: ReturnType<typeof clack.taskLog>; hrStart: [number, number] }>(),
     }
 
-    function reset() {
-      for (const [_key, active] of state.activeProgress) {
+    // Clear every active progress bar's interval, stop it, and drop the map.
+    function stopActiveProgress() {
+      for (const [, active] of state.activeProgress) {
         if (active.interval) {
           clearInterval(active.interval)
         }
         active.progressBar?.stop()
       }
+      state.activeProgress.clear()
+    }
 
-      state.totalPlugins = 0
-      state.completedPlugins = 0
-      state.failedPlugins = 0
-      state.totalFiles = 0
-      state.processedFiles = 0
-      state.hrStart = process.hrtime()
+    function reset() {
+      stopActiveProgress()
+
+      resetProgressCounters(state)
       state.spinner = clack.spinner()
       state.isSpinning = false
-      state.activeProgress.clear()
+      state.runningPlugins.clear()
+      state.activeHookLogs.clear()
+    }
+
+    // Label for the shared plugin bar, listing the plugins currently generating.
+    function pluginProgressText(): string {
+      const running = [...state.runningPlugins].map((name) => styleText('bold', name))
+      return getMessage(running.length > 0 ? `Generating ${running.join(', ')}` : 'Generating plugins')
     }
 
     function showProgressStep() {
@@ -62,12 +65,20 @@ export const clackLogger = defineLogger({
       return formatMessage(message, logLevel)
     }
 
-    function startSpinner(text?: string) {
-      state.spinner.start(text)
-      state.isSpinning = true
+    // Registers a handler that prints a fixed step message, skipped at silent level.
+    function onStep<E extends keyof KubbHooks>(event: E, message: string): void {
+      context.on(event, () => {
+        if (logLevel <= logLevelMap.silent) {
+          return
+        }
+        clack.log.step(getMessage(message))
+      })
     }
 
     function stopSpinner(text?: string) {
+      if (!state.isSpinning) {
+        return
+      }
       state.spinner.stop(text)
       state.isSpinning = false
     }
@@ -77,13 +88,13 @@ export const clackLogger = defineLogger({
         return
       }
 
-      const text = getMessage([styleText('blue', 'ℹ'), message, styleText('dim', info)].join(' '))
+      const text = getMessage([styleText('blue', 'ℹ'), message, info ? styleText('dim', info) : undefined].filter(Boolean).join(' '))
 
       if (state.isSpinning) {
         state.spinner.message(text)
-      } else {
-        clack.log.info(text)
+        return
       }
+      clack.log.info(text)
     })
 
     context.on('kubb:success', ({ message, info = '' }) => {
@@ -95,9 +106,9 @@ export const clackLogger = defineLogger({
 
       if (state.isSpinning) {
         stopSpinner(text)
-      } else {
-        clack.log.success(text)
+        return
       }
+      clack.log.success(text)
     })
 
     context.on('kubb:warn', ({ message, info }) => {
@@ -119,12 +130,12 @@ export const clackLogger = defineLogger({
 
       if (state.isSpinning) {
         stopSpinner(getMessage(text))
-      } else {
-        clack.log.error(getMessage(text))
+        return
       }
+      clack.log.error(getMessage(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) {
           clack.log.message(getMessage(styleText('dim', frame.trim())))
@@ -141,14 +152,21 @@ export const clackLogger = defineLogger({
       }
     })
 
-    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
       }
 
-      try {
+      stopSpinner()
+
+      // Stop any lingering progress UI so the multi-line block renders cleanly.
+      stopActiveProgress()
+
+      // The version-update notice keeps its own framed box instead of the diagnostic gutter.
+      if (Diagnostics.isUpdate(diagnostic)) {
         clack.box(
-          `\`v${currentVersion}\` → \`v${latestVersion}\`
+          `\`v${diagnostic.currentVersion}\` → \`v${diagnostic.latestVersion}\`
 Run \`npm install -g @kubb/cli\` to update`,
           'Update available for `Kubb`',
           {
@@ -160,37 +178,21 @@ Run \`npm install -g @kubb/cli\` to update`,
             titleAlign: 'center',
           },
         )
-      } catch {
-        console.log(`Update available for Kubb: v${currentVersion} → v${latestVersion}`)
-        console.log('Run `npm install -g @kubb/cli` to update')
-      }
-    })
 
-    context.on('kubb:lifecycle:start', async ({ version }) => {
-      console.log(`\n${getIntro({ title: 'The ultimate toolkit for working with APIs', description: 'Ready to start', version, areEyesOpen: true })}\n`)
-
-      reset()
-    })
-
-    context.on('kubb:config:start', () => {
-      if (logLevel <= logLevelMap.silent) {
         return
       }
 
-      const text = getMessage('Configuration started')
-
-      clack.intro(text)
-      startSpinner(getMessage('Configuration loading'))
+      // Hand the severity glyph to clack as the gutter `symbol`, then let it draw the
+      // bar on each detail line via the default `secondarySymbol`. The headline and
+      // details carry their own colors, so clack only owns the gutter.
+      const { symbol, headline, details } = Diagnostics.format(diagnostic)
+      clack.log.message([headline, ...details], { symbol })
     })
 
-    context.on('kubb:config:end', () => {
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
-
-      const text = getMessage('Configuration completed')
+    context.on('kubb:lifecycle:start', async ({ version }) => {
+      console.log(`\n${getIntro({ title: 'The meta framework for code generation', description: 'Ready to start', version, areEyesOpen: true })}\n`)
 
-      clack.outro(text)
+      reset()
     })
 
     context.on('kubb:generation:start', ({ config }) => {
@@ -199,11 +201,17 @@ Run \`npm install -g @kubb/cli\` to update`,
       // Initialize progress tracking for this generation
       state.totalPlugins = config.plugins?.length ?? 0
 
+      if (logLevel <= logLevelMap.silent) {
+        return
+      }
+
       const text = getMessage(['Generation started', config.name ? `for ${styleText('dim', config.name)}` : undefined].filter(Boolean).join(' '))
 
       clack.intro(text)
     })
 
+    // Plugins run concurrently, so they share a single progress bar. A bar per plugin
+    // would make clack render them side by side and pile up keypress listeners.
     context.on('kubb:plugin:start', ({ plugin }) => {
       if (logLevel <= logLevelMap.silent) {
         return
@@ -211,50 +219,44 @@ Run \`npm install -g @kubb/cli\` to update`,
 
       stopSpinner()
 
+      state.runningPlugins.add(plugin.name)
+
+      const active = state.activeProgress.get('plugins')
+      if (active) {
+        active.progressBar.advance(0, pluginProgressText())
+        return
+      }
+
       const progressBar = clack.progress({
         style: 'block',
-        max: 100,
+        max: Math.max(state.totalPlugins, 1),
         size: 30,
       })
-      const text = getMessage(`Generating ${styleText('bold', plugin.name)}`)
-      progressBar.start(text)
-
-      const interval = setInterval(() => {
-        progressBar.advance()
-      }, 100)
-
-      state.activeProgress.set(plugin.name, { progressBar, interval })
+      progressBar.start(pluginProgressText())
+      // Catch up to plugins already finished before this bar opened.
+      progressBar.advance(state.completedPlugins + state.failedPlugins, pluginProgressText())
+      state.activeProgress.set('plugins', { progressBar })
     })
 
-    context.on('kubb:plugin:end', ({ plugin, duration, success }) => {
+    context.on('kubb:plugin:end', ({ plugin, success }) => {
       stopSpinner()
 
-      const active = state.activeProgress.get(plugin.name)
+      const active = state.activeProgress.get('plugins')
 
       if (!active || logLevel === logLevelMap.silent) {
         return
       }
 
-      clearInterval(active.interval)
+      state.runningPlugins.delete(plugin.name)
+      recordPluginResult(state, success)
+      active.progressBar.advance(1, pluginProgressText())
 
-      if (success) {
-        state.completedPlugins++
-      } else {
-        state.failedPlugins++
+      // Close the bar once nothing is generating, then print the progress step.
+      if (state.runningPlugins.size === 0) {
+        active.progressBar.stop(getMessage('Plugins generated'))
+        state.activeProgress.delete('plugins')
+        showProgressStep()
       }
-
-      const durationStr = formatMsWithColor(duration)
-      const text = getMessage(
-        success
-          ? `${styleText('bold', plugin.name)} completed in ${durationStr}`
-          : `${styleText('bold', plugin.name)} failed in ${styleText('red', formatMs(duration))}`,
-      )
-
-      active.progressBar.stop(text)
-      state.activeProgress.delete(plugin.name)
-
-      // Show progress step after each plugin
-      showProgressStep()
     })
 
     context.on('kubb:files:processing:start', ({ files }) => {
@@ -279,23 +281,20 @@ Run \`npm install -g @kubb/cli\` to update`,
       state.activeProgress.set('files', { progressBar })
     })
 
-    context.on('kubb:file:processing:update', ({ file, config }) => {
+    context.on('kubb:files:processing:update', ({ files }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
 
       stopSpinner()
 
-      state.processedFiles++
-
-      const text = `Writing ${relative(config.root, file.path)}`
       const active = state.activeProgress.get('files')
-
-      if (!active) {
-        return
+      for (const { file, config } of files) {
+        state.processedFiles++
+        if (active) {
+          active.progressBar.advance(undefined, `Writing ${relative(config.root, file.path)}`)
+        }
       }
-
-      active.progressBar.advance(undefined, text)
     })
     context.on('kubb:files:processing:end', () => {
       if (logLevel <= logLevelMap.silent) {
@@ -319,135 +318,70 @@ Run \`npm install -g @kubb/cli\` to update`,
     })
 
     context.on('kubb:generation:end', ({ config }) => {
+      stopSpinner()
+
       const text = getMessage(config.name ? `Generation completed for ${styleText('dim', config.name)}` : 'Generation completed')
 
       clack.outro(text)
     })
 
-    context.on('kubb:format:start', () => {
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
-
-      const text = getMessage('Format started')
-
-      clack.intro(text)
-    })
-
-    context.on('kubb:format:end', () => {
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
-
-      const text = getMessage('Format completed')
-
-      clack.outro(text)
-    })
+    onStep('kubb:format:start', 'Formatting')
+    onStep('kubb:lint:start', 'Linting')
+    onStep('kubb:hooks:start', 'Running hooks')
 
-    context.on('kubb:lint:start', () => {
-      if (logLevel <= logLevelMap.silent) {
+    context.on('kubb:hook:start', ({ id, command, args }) => {
+      if (logLevel <= logLevelMap.silent || !id) {
         return
       }
 
-      const text = getMessage('Lint started')
-
-      clack.intro(text)
-    })
-
-    context.on('kubb:lint:end', () => {
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
+      stopSpinner()
 
-      const text = getMessage('Lint completed')
+      const commandWithArgs = formatCommandWithArgs(command, args)
+      const title = getMessage(`Running ${styleText('dim', commandWithArgs)}`)
+      const taskLog = clack.taskLog({ title })
 
-      clack.outro(text)
+      state.activeHookLogs.set(id, { taskLog, hrStart: process.hrtime() })
     })
 
-    context.on('kubb:hook:start', async ({ id, command, args }) => {
-      const commandWithArgs = formatCommandWithArgs(command, args)
-      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
+    // Registered only when not silent, so its presence is what tells the runner to stream
+    // (`kubb:hook:line` listenerCount). At silent level the listener is absent, so no streaming happens.
+    if (logLevel > logLevelMap.silent) {
+      context.on('kubb:hook:line', ({ id, line }) => {
+        const active = state.activeHookLogs.get(id)
+        active?.taskLog.message(styleText('dim', line))
+      })
+    }
 
-      // Skip hook execution if no id is provided (e.g., during benchmarks or tests)
+    context.on('kubb:hook:end', ({ id, command, args, success, error, stdout, stderr }) => {
       if (!id) {
         return
       }
 
       if (logLevel <= logLevelMap.silent) {
-        await runHook({
-          id,
-          command,
-          args,
-          commandWithArgs,
-          context,
-          sink: {
-            onStderr: (s) => console.error(s),
-            onStdout: (s) => console.log(s),
-          },
-        })
+        // Even when silent, surface a failed hook's captured output.
+        if (!success) {
+          if (stdout) console.log(stdout)
+          if (stderr) console.error(stderr)
+        }
         return
       }
 
-      clack.intro(text)
-
-      const logger = clack.taskLog({
-        title: getMessage(['Executing hook', logLevel >= logLevelMap.info ? styleText('dim', commandWithArgs) : undefined].filter(Boolean).join(' ')),
-      })
-
-      const writable = new ClackWritable(logger)
-
-      await runHook({
-        id,
-        command,
-        args,
-        commandWithArgs,
-        context,
-        stream: true,
-        sink: {
-          onLine: (line) => writable.write(line),
-          onStderr: (s) => logger.error(s),
-          onStdout: (s) => logger.message(s),
-        },
-      })
-    })
-
-    context.on('kubb:hook:end', ({ command, args }) => {
-      if (logLevel <= logLevelMap.silent) {
+      const active = state.activeHookLogs.get(id)
+      if (!active) {
         return
       }
+      state.activeHookLogs.delete(id)
 
       const commandWithArgs = formatCommandWithArgs(command, args)
-      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} successfully executed`)
-
-      clack.outro(text)
-    })
+      const duration = formatMsWithColor(getElapsedMs(active.hrStart))
 
-    context.on('kubb:generation:summary', ({ config, pluginTimings, failedPlugins, filesCreated, status, hrStart }) => {
-      const summary = getSummary({
-        failedPlugins,
-        filesCreated,
-        config,
-        status,
-        hrStart,
-        pluginTimings: logLevel >= logLevelMap.verbose ? pluginTimings : undefined,
-      })
-      const title = config.name || ''
-
-      summary.unshift('\n')
-      summary.push('\n')
-
-      const borderColor = status === 'success' ? 'green' : 'red'
-      try {
-        clack.box(summary.join('\n'), getMessage(title), {
-          width: 'auto',
-          formatBorder: (s: string) => styleText(borderColor, s),
-          rounded: true,
-          withGuide: false,
-          contentAlign: 'left',
-          titleAlign: 'center',
-        })
-      } catch {
-        console.log(summary.join('\n'))
+      if (success) {
+        active.taskLog.success(getMessage(`${styleText('dim', commandWithArgs)} completed in ${duration}`))
+      } else {
+        // The hook's output already reached the taskLog live via `kubb:hook:line`, so `showLog`
+        // replays it here. `kubb:hook:end` carries no captured output on the streaming path.
+        const reason = error?.message ? ` (${error.message})` : ''
+        active.taskLog.error(getMessage(`${styleText('dim', commandWithArgs)} failed${reason}`), { showLog: true })
       }
     })
 

package/src/loggers/defineLogger.ts

@@ -0,0 +1,59 @@
+import type { AsyncEventEmitter } from '@internals/utils'
+import type { KubbHooks } from '@kubb/core'
+
+/**
+ * Options accepted by a logger's `install` callback.
+ */
+export type LoggerOptions = {
+  /**
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
+   */
+  logLevel: number
+}
+
+/**
+ * Event emitter handed to `Logger.install`. Use `.on('kubb:info', ...)` and
+ * friends to subscribe to build events.
+ */
+export type LoggerContext = AsyncEventEmitter<KubbHooks>
+
+/**
+ * Logger contract. A logger receives the build's event emitter and subscribes
+ * to whichever lifecycle events it wants to forward to its destination
+ * (console, file, remote service).
+ */
+export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
+  /**
+   * Display name used in diagnostics.
+   */
+  name: string
+  /**
+   * Called once per build with the shared event emitter. Subscribe to the
+   * lifecycle events the logger wants to forward to its destination.
+   */
+  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>
+}
+
+export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>
+
+/**
+ * Defines a typed logger. The `install` method subscribes to lifecycle events
+ * on the shared emitter and forwards them to the logger's destination.
+ *
+ * @example
+ * ```ts
+ * import { defineLogger } from '@kubb/cli'
+ *
+ * export const myLogger = defineLogger({
+ *   name: 'my-logger',
+ *   install(context) {
+ *     context.on('kubb:info', ({ message }) => console.log('ℹ', message))
+ *     context.on('kubb:error', ({ error }) => console.error('✗', error.message))
+ *   },
+ * })
+ * ```
+ */
+export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
+  return logger
+}