@kubb/core 5.0.0-beta.4 → 5.0.0-beta.41

package/src/mocks.ts

@@ -1,16 +1,22 @@
-import { resolve } from 'node:path'
-import type { FileNode, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
+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 { PluginDriver } from './PluginDriver.ts'
-import { applyHookResult } from './renderNode.ts'
-import type { Adapter, AdapterFactoryOptions, Config, Generator, GeneratorContext, NormalizedPlugin, PluginFactoryOptions } from './types.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'
 
 /**
 
  * Creates a minimal `PluginDriver` mock for unit tests.
  */
-export function createMockedPluginDriver(options: { name?: string; plugin?: NormalizedPlugin; config?: Config } = {}): PluginDriver {
+export function createMockedPluginDriver(options: { name?: string; plugin?: NormalizedPlugin; config?: Config } = {}): KubbDriver {
+  const fileManager = new FileManager()
+
   return {
     config: options?.config ?? {
       root: '.',
@@ -22,29 +28,45 @@ export function createMockedPluginDriver(options: { name?: string; plugin?: Norm
       return options?.plugin
     },
     getResolver: (_pluginName: string) => options?.plugin?.resolver,
-    fileManager: new FileManager(),
-  } as unknown as PluginDriver
+    fileManager,
+    async dispatch({ result, renderer }: { result: unknown; renderer?: RendererFactory | null }): Promise<void> {
+      if (!result) return
+
+      if (Array.isArray(result)) {
+        fileManager.upsert(...(result as Array<FileNode>))
+        return
+      }
+
+      if (!renderer) return
+
+      using instance = renderer()
+      if (instance.stream) {
+        for (const file of instance.stream(result)) fileManager.upsert(file)
+        return
+      }
+
+      await instance.render(result)
+      fileManager.upsert(...instance.files)
+    },
+  } as unknown as KubbDriver
 }
 
 /**
  * Creates a minimal `Adapter` mock for unit tests.
- * `parse` returns an empty `InputNode` by default; override via `options.parse`.
+ * `parse` returns an empty `InputNode` by default. Override via `options.parse`.
  * `getImports` returns `[]` by default.
  */
 export function createMockedAdapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions>(
   options: {
     name?: TOptions['name']
     resolvedOptions?: TOptions['resolvedOptions']
-    inputNode?: Adapter<TOptions>['inputNode']
     parse?: Adapter<TOptions>['parse']
     getImports?: Adapter<TOptions>['getImports']
   } = {},
 ): Adapter<TOptions> {
-  const inputNode = options.inputNode ?? null
   return {
     name: (options.name ?? 'oas') as TOptions['name'],
     options: (options.resolvedOptions ?? {}) as TOptions['resolvedOptions'],
-    inputNode,
     parse: options.parse ?? (async () => ({ kind: 'Input' as const, schemas: [], operations: [] })),
     getImports: options.getImports ?? ((_node: SchemaNode, _resolve: (schemaName: string) => { name: string; path: string }) => []),
   } as Adapter<TOptions>
@@ -76,7 +98,8 @@ export function createMockedPlugin<TOptions extends PluginFactoryOptions = Plugi
 type RenderGeneratorOptions<TOptions extends PluginFactoryOptions> = {
   config: Config
   adapter: Adapter
-  driver: PluginDriver
+  meta?: InputMeta
+  driver: KubbDriver
   plugin: NormalizedPlugin<TOptions>
   options: TOptions['resolvedOptions']
   resolver: TOptions['resolver']
@@ -88,20 +111,19 @@ function createMockedPluginContext<TOptions extends PluginFactoryOptions>(opts:
   return {
     config: opts.config,
     root,
-    getMode: (output: { path: string }) => PluginDriver.getMode(resolve(root, output.path)),
+    getMode: (output: { path: string }) => KubbDriver.getMode(resolve(root, output.path)),
     adapter: opts.adapter,
     resolver: opts.resolver,
     plugin: opts.plugin,
     driver: opts.driver,
     getResolver: (name: string) => opts.driver.getResolver(name),
-    inputNode: { kind: 'Input', schemas: [], operations: [] },
+    meta: opts.meta ?? { circularNames: [], enumNames: [] },
     addFile: async (...files: Array<FileNode>) => opts.driver.fileManager.add(...files),
     upsertFile: async (...files: Array<FileNode>) => opts.driver.fileManager.upsert(...files),
     hooks: opts.driver.hooks ?? ({} as never),
     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'>
 }
 
@@ -126,7 +148,7 @@ export async function renderGeneratorSchema<TOptions extends PluginFactoryOption
     ...context,
     options: opts.options,
   })
-  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+  await opts.driver.dispatch({ result, renderer: generator.renderer })
 }
 
 /**
@@ -150,7 +172,7 @@ export async function renderGeneratorOperation<TOptions extends PluginFactoryOpt
     ...context,
     options: opts.options,
   })
-  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+  await opts.driver.dispatch({ result, renderer: generator.renderer })
 }
 
 /**
@@ -174,5 +196,56 @@ export async function renderGeneratorOperations<TOptions extends PluginFactoryOp
     ...context,
     options: opts.options,
   })
-  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+  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`)
+  },
+})

package/src/reporters/report.ts

@@ -0,0 +1,85 @@
+import { resolve } from 'node:path'
+import { getElapsedMs } from '@internals/utils'
+import type { GenerationResult } from '../createReporter.ts'
+import { Diagnostics, type SerializedDiagnostic } from '../diagnostics.ts'
+
+/**
+ * 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(Diagnostics.isProblem)
+  const timings = diagnostics
+    .filter(Diagnostics.isPerformance)
+    .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/storages/fsStorage.ts

@@ -4,13 +4,6 @@ import { join, resolve } from 'node:path'
 import { clean, write } from '@internals/utils'
 import { createStorage } from '../createStorage.ts'
 
-/**
- * Detects the filesystem error used to indicate that a path does not exist.
- */
-function isMissingPathError(error: unknown): error is NodeJS.ErrnoException {
-  return typeof error === 'object' && error !== null && 'code' in error && (error as NodeJS.ErrnoException).code === 'ENOENT'
-}
-
 /**
  * Built-in filesystem storage driver.
  *
@@ -42,27 +35,15 @@ export const fsStorage = createStorage(() => ({
     try {
       await access(resolve(key))
       return true
-    } catch (error) {
-      if (isMissingPathError(error)) {
-        return false
-      }
-
-      throw new Error(`Failed to access storage item "${key}"`, {
-        cause: error as Error,
-      })
+    } catch (_error) {
+      return false
     }
   },
   async getItem(key: string) {
     try {
       return await readFile(resolve(key), 'utf8')
-    } catch (error) {
-      if (isMissingPathError(error)) {
-        return null
-      }
-
-      throw new Error(`Failed to read storage item "${key}"`, {
-        cause: error as Error,
-      })
+    } catch (_error) {
+      return null
     }
   },
   async setItem(key: string, value: string) {
@@ -72,36 +53,31 @@ export const fsStorage = createStorage(() => ({
     await rm(resolve(key), { force: true })
   },
   async getKeys(base?: string) {
-    const keys: Array<string> = []
     const resolvedBase = resolve(base ?? process.cwd())
 
-    async function walk(dir: string, prefix: string): Promise<void> {
+    async function* walk(dir: string, prefix: string): AsyncGenerator<string, void, undefined> {
       let entries: Array<Dirent>
       try {
         entries = (await readdir(dir, {
           withFileTypes: true,
         })) as Array<Dirent>
-      } catch (error) {
-        if (isMissingPathError(error)) {
-          return
-        }
-
-        throw new Error(`Failed to list storage keys under "${resolvedBase}"`, {
-          cause: error as Error,
-        })
+      } catch (_error) {
+        return
       }
       for (const entry of entries) {
         const rel = prefix ? `${prefix}/${entry.name}` : entry.name
         if (entry.isDirectory()) {
-          await walk(join(dir, entry.name), rel)
+          yield* walk(join(dir, entry.name), rel)
         } else {
-          keys.push(rel)
+          yield rel
         }
       }
     }
 
-    await walk(resolvedBase, '')
-
+    const keys: Array<string> = []
+    for await (const key of walk(resolvedBase, '')) {
+      keys.push(key)
+    }
     return keys
   },
   async clear(base?: string) {