@kubb/core 4.11.1 → 4.11.2

package/src/build.ts

@@ -1,4 +1,5 @@
 import { join, relative, resolve } from 'node:path'
+import { performance } from 'node:perf_hooks'
 import type { KubbFile } from '@kubb/fabric-core/types'
 import type { Fabric } from '@kubb/react-fabric'
 import { createFabric } from '@kubb/react-fabric'
@@ -12,6 +13,7 @@ import type { Logger } from './logger.ts'
 import { createLogger } from './logger.ts'
 import { PluginManager } from './PluginManager.ts'
 import type { Config, Output, Plugin, UserConfig } from './types.ts'
+import { getDiagnosticInfo } from './utils/diagnostics.ts'
 import { URLPath } from './utils/URLPath.ts'
 
 type BuildOptions = {
@@ -27,15 +29,12 @@ type BuildOutput = {
   fabric: Fabric
   files: Array<KubbFile.ResolvedFile>
   pluginManager: PluginManager
-  // TODO check if we can remove error
-  /**
-   * Only for safeBuild,
-   * @deprecated
-   */
+  pluginTimings: Map<string, number>
   error?: Error
 }
 
 type SetupResult = {
+  logger: Logger
   fabric: Fabric
   pluginManager: PluginManager
 }
@@ -43,20 +42,50 @@ type SetupResult = {
 export async function setup(options: BuildOptions): Promise<SetupResult> {
   const { config: userConfig, logger = createLogger() } = options
 
+  const diagnosticInfo = getDiagnosticInfo()
+
   if (Array.isArray(userConfig.input)) {
     console.warn(pc.yellow('This feature is still under development — use with caution'))
   }
 
+  logger.emit('debug', {
+    date: new Date(),
+    category: 'setup',
+    logs: [
+      'Configuration:',
+      `  • Name: ${userConfig.name || 'unnamed'}`,
+      `  • Root: ${userConfig.root || process.cwd()}`,
+      `  • Output: ${userConfig.output?.path || 'not specified'}`,
+      `  • Plugins: ${userConfig.plugins?.length || 0}`,
+      'Output Settings:',
+      `  • Write: ${userConfig.output?.write !== false ? 'enabled' : 'disabled'}`,
+      `  • Formater: ${userConfig.output?.format || 'none'}`,
+      `  • Linter: ${userConfig.output?.lint || 'none'}`,
+      'Environment:',
+      Object.entries(diagnosticInfo)
+        .map(([key, value]) => `  • ${key}: ${value}`)
+        .join('\n'),
+    ],
+  })
+
   try {
     if (isInputPath(userConfig) && !new URLPath(userConfig.input.path).isURL) {
       await exists(userConfig.input.path)
+
+      logger.emit('debug', {
+        date: new Date(),
+        category: 'setup',
+        logs: [`✓ Input file validated: ${userConfig.input.path}`],
+      })
     }
   } catch (e) {
     if (isInputPath(userConfig)) {
+      const error = e as Error
+
       throw new Error(
         `Cannot read file/URL defined in \`input.path\` or set with \`kubb generate PATH\` in the CLI of your Kubb config ${userConfig.input.path}`,
         {
-          cause: e,
+          cause: error,
         },
       )
     }
@@ -78,6 +107,11 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   }
 
   if (definedConfig.output.clean) {
+    logger.emit('debug', {
+      date: new Date(),
+      category: 'setup',
+      logs: ['Cleaning output directories', `  • Output: ${definedConfig.output.path}`, '  • Cache: .kubb'],
+    })
     await clean(definedConfig.output.path)
     await clean(join(definedConfig.root, '.kubb'))
   }
@@ -86,16 +120,122 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   fabric.use(fsPlugin, { dryRun: !definedConfig.output.write })
   fabric.use(typescriptParser)
 
+  fabric.context.on('process:start', ({ files }) => {
+    logger.emit('progress_start', { id: 'files', size: files.length, message: 'Writing files ...' })
+    logger.emit('debug', {
+      date: new Date(),
+      category: 'file',
+      logs: [`Writing ${files.length} files...`],
+    })
+  })
+
+  fabric.context.on('process:progress', async ({ file, source }) => {
+    const message = file ? `Writing ${relative(definedConfig.root, file.path)}` : ''
+    logger.emit('progressed', { id: 'files', message })
+
+    if (source) {
+      await write(file.path, source, { sanity: false })
+    }
+  })
+
+  fabric.context.on('process:end', () => {
+    logger.emit('progress_stop', { id: 'files' })
+    logger.emit('debug', {
+      date: new Date(),
+      category: 'file',
+      logs: ['✓ File write process completed'],
+    })
+  })
+
+  logger.emit('debug', {
+    date: new Date(),
+    category: 'setup',
+    logs: [
+      '✓ Fabric initialized',
+      `  • File writing: ${definedConfig.output.write ? 'enabled' : 'disabled (dry-run)'}`,
+      `  • Barrel type: ${definedConfig.output.barrelType || 'none'}`,
+    ],
+  })
+
   const pluginManager = new PluginManager(definedConfig, { fabric, logger, concurrency: 5 })
 
+  pluginManager.on('executing', ({ plugin, hookName, strategy, parameters }) => {
+    logger.emit('debug', {
+      date: new Date(),
+      category: 'hook',
+      pluginName: plugin.name,
+      logs: [`Executing hook: ${hookName}`, `  • Strategy: ${strategy}`, '  • Parameters:', JSON.stringify(parameters, null, 2)],
+    })
+  })
+
+  pluginManager.on('executed', ({ plugin, hookName, duration, parameters }) => {
+    let message = ''
+    if (hookName === 'resolvePath') {
+      const [path] = parameters || []
+      message = `Resolving path '${path}'`
+    }
+
+    if (hookName === 'resolveName') {
+      const [name, type] = parameters || []
+      message = `Resolving name '${name}' and type '${type}'`
+    }
+
+    logger.emit('progressed', {
+      id: hookName,
+      message: `${plugin.name}: ${message}`,
+    })
+    logger.emit('debug', {
+      date: new Date(),
+      category: 'hook',
+      pluginName: plugin.name,
+      logs: [`✓ Completed in ${duration}ms`],
+    })
+  })
+
+  pluginManager.on('progress_start', ({ hookName, plugins }) => {
+    logger.emit('progress_start', { id: hookName, size: plugins.length, message: 'Running plugins...' })
+  })
+
+  pluginManager.on('progress_stop', ({ hookName }) => {
+    logger.emit('progress_stop', { id: hookName })
+  })
+
+  pluginManager.on('error', (error, { plugin, strategy, duration, parameters, hookName }) => {
+    const text = `${error.message} (plugin: ${plugin?.name || 'unknown'}, hook: ${hookName || 'unknown'})`
+
+    logger.emit('error', text, error)
+
+    logger.emit('debug', {
+      date: new Date(),
+      category: 'error',
+      pluginName: plugin.name,
+      logs: [
+        `✗ Hook '${hookName}' failed after ${duration}ms`,
+        `  • Strategy: ${strategy}`,
+        `  • Error: ${error.constructor.name} - ${error.message}`,
+        '  • Stack Trace:',
+        error.stack || 'No stack trace available',
+        '  • Parameters:',
+        JSON.stringify(parameters, null, 2),
+      ],
+    })
+  })
+
+  logger.emit('debug', {
+    date: new Date(),
+    category: 'setup',
+    logs: ['✓ PluginManager initialized', '  • Concurrency: 5', `  • Total plugins: ${pluginManager.plugins.length}`],
+  })
+
   return {
+    logger,
     fabric,
     pluginManager,
   }
 }
 
 export async function build(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const { fabric, files, pluginManager, failedPlugins, error } = await safeBuild(options, overrides)
+  const { fabric, files, pluginManager, failedPlugins, pluginTimings, error } = await safeBuild(options, overrides)
 
   if (error) {
     throw error
@@ -106,14 +246,16 @@ export async function build(options: BuildOptions, overrides?: SetupResult): Pro
     fabric,
     files,
     pluginManager,
+    pluginTimings,
     error,
   }
 }
 
 export async function safeBuild(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const { fabric, pluginManager } = overrides ? overrides : await setup(options)
+  const { fabric, pluginManager, logger } = overrides ? overrides : await setup(options)
 
   const failedPlugins = new Set<{ plugin: Plugin; error: Error }>()
+  const pluginTimings = new Map<string, number>()
   const config = pluginManager.config
 
   try {
@@ -123,9 +265,69 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       const installer = plugin.install.bind(context)
 
       try {
+        const startTime = performance.now()
+        const timestamp = new Date()
+
+        // Start plugin group
+        logger.emit('debug', {
+          date: timestamp,
+          pluginGroupMarker: 'start',
+          pluginName: plugin.name,
+          logs: [],
+        })
+
+        logger.emit('debug', {
+          date: timestamp,
+          category: 'plugin',
+          pluginName: plugin.name,
+          logs: ['Installing plugin...', `  • Plugin Key: ${JSON.stringify(plugin.key)}`],
+        })
+
         await installer(context)
+
+        const duration = Math.round(performance.now() - startTime)
+        pluginTimings.set(plugin.name, duration)
+
+        logger.emit('debug', {
+          date: new Date(),
+          category: 'plugin',
+          pluginName: plugin.name,
+          logs: [`✓ Plugin installed successfully (${duration}ms)`],
+        })
+
+        // End plugin group
+        logger.emit('debug', {
+          date: new Date(),
+          pluginGroupMarker: 'end',
+          pluginName: plugin.name,
+          logs: [],
+        })
       } catch (e) {
-        failedPlugins.add({ plugin, error: e as Error })
+        const error = e as Error
+        const errorTimestamp = new Date()
+
+        logger.emit('debug', {
+          date: errorTimestamp,
+          category: 'error',
+          pluginName: plugin.name,
+          logs: [
+            '✗ Plugin installation failed',
+            `  • Plugin Key: ${JSON.stringify(plugin.key)}`,
+            `  • Error: ${error.constructor.name} - ${error.message}`,
+            '  • Stack Trace:',
+            error.stack || 'No stack trace available',
+          ],
+        })
+
+        // End plugin group even on error
+        logger.emit('debug', {
+          date: errorTimestamp,
+          pluginGroupMarker: 'end',
+          pluginName: plugin.name,
+          logs: [],
+        })
+
+        failedPlugins.add({ plugin, error })
       }
     }
 
@@ -133,10 +335,20 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       const root = resolve(config.root)
       const rootPath = resolve(root, config.output.path, 'index.ts')
 
+      logger.emit('debug', {
+        date: new Date(),
+        logs: ['Generating barrel file', `  • Type: ${config.output.barrelType}`, `  • Path: ${rootPath}`],
+      })
+
       const barrelFiles = fabric.files.filter((file) => {
         return file.sources.some((source) => source.isIndexable)
       })
 
+      logger.emit('debug', {
+        date: new Date(),
+        logs: [`Found ${barrelFiles.length} indexable files for barrel export`],
+      })
+
       const rootFile: KubbFile.File = {
         path: rootPath,
         baseName: 'index.ts',
@@ -175,24 +387,14 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       }
 
       await fabric.upsertFile(rootFile)
-    }
-
-    fabric.context.on('process:start', ({ files }) => {
-      pluginManager.logger.emit('progress_start', { id: 'files', size: files.length, message: 'Writing files ...' })
-    })
-
-    fabric.context.on('process:progress', async ({ file, source }) => {
-      const message = file ? `Writing ${relative(config.root, file.path)}` : ''
-      pluginManager.logger.emit('progressed', { id: 'files', message })
 
-      if (source) {
-        await write(file.path, source, { sanity: false })
-      }
-    })
+      logger.emit('debug', {
+        date: new Date(),
+        category: 'file',
+        logs: [`✓ Generated barrel file (${rootFile.exports?.length || 0} exports)`],
+      })
+    }
 
-    fabric.context.on('process:end', () => {
-      pluginManager.logger.emit('progress_stop', { id: 'files' })
-    })
     const files = [...fabric.files]
 
     await fabric.write({ extension: config.output.extension })
@@ -202,6 +404,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       fabric,
       files,
       pluginManager,
+      pluginTimings,
     }
   } catch (e) {
     return {
@@ -209,6 +412,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       fabric,
       files: [],
       pluginManager,
+      pluginTimings,
       error: e as Error,
     }
   }

package/src/logger.ts

@@ -4,16 +4,43 @@ import { createConsola } from 'consola'
 import pc from 'picocolors'
 import seedrandom from 'seedrandom'
 import { write } from './fs/write.ts'
+import { endGroup, isGitHubActions, startGroup } from './utils/ciDetection.ts'
 import { EventEmitter } from './utils/EventEmitter.ts'
 
-type DebugEvent = { date: Date; logs: string[]; fileName?: string }
+type DebugEvent = {
+  date: Date
+  logs: string[]
+  fileName?: string
+  /**
+   * Category of the debug log, used for GitHub Actions grouping
+   * - 'setup': Initial configuration and environment setup
+   * - 'plugin': Plugin installation and execution
+   * - 'hook': Plugin hook execution details
+   * - 'schema': Schema parsing and generation
+   * - 'file': File operations (read/write/generate)
+   * - 'error': Error details and stack traces
+   * - undefined: Generic logs (always inline)
+   */
+  category?: 'setup' | 'plugin' | 'hook' | 'schema' | 'file' | 'error'
+  /**
+   * Plugin name for grouping plugin-specific logs together
+   */
+  pluginName?: string
+  /**
+   * Indicates if this is the start or end of a plugin's execution
+   * - 'start': Start of plugin execution group
+   * - 'end': End of plugin execution group
+   */
+  pluginGroupMarker?: 'start' | 'end'
+}
 
 type Events = {
   start: [message: string]
   success: [message: string]
-  error: [message: string, cause: Error]
+  error: [message: string, error: Error]
   warning: [message: string]
   debug: [DebugEvent]
+  verbose: [DebugEvent]
   info: [message: string]
   progress_start: [{ id: string; size: number; message?: string }]
   progressed: [{ id: string; message?: string }]
@@ -22,10 +49,15 @@ type Events = {
 
 export const LogMapper = {
   silent: Number.NEGATIVE_INFINITY,
+  error: 0,
+  warn: 1,
   info: 3,
-  debug: 4,
+  verbose: 4,
+  debug: 5,
 } as const
 
+const DEBUG_LOG_TITLE_MAX_LENGTH = 50 // Characters - max length for group titles
+
 export type Logger = {
   /**
    * Optional config name to show in CLI output
@@ -35,7 +67,7 @@ export type Logger = {
   consola?: ConsolaInstance
   on: EventEmitter<Events>['on']
   emit: EventEmitter<Events>['emit']
-  writeLogs: () => Promise<string[]>
+  writeLogs: () => Promise<void>
 }
 
 type Props = {
@@ -79,9 +111,54 @@ export function createLogger({ logLevel = 3, name, consola: _consola }: Props =
     consola.info(pc.yellow(message))
   })
 
+  events.on('verbose', (message) => {
+    if (logLevel >= LogMapper.verbose) {
+      const formattedLogs = message.logs.join('\n')
+      consola.log(pc.dim(formattedLogs))
+    }
+
+    cachedLogs.add(message)
+  })
+
   events.on('debug', (message) => {
-    if (message.logs.join('\n\n').length <= 100 && logLevel === LogMapper.debug) {
-      console.log(message.logs.join('\n\n'))
+    const fullLog = message.logs.join('\n')
+
+    if (logLevel >= LogMapper.debug) {
+      // Handle plugin group markers in GitHub Actions
+      if (isGitHubActions()) {
+        if (message.pluginGroupMarker === 'start') {
+          // Start a new plugin group
+          const title = message.pluginName || 'Plugin'
+          console.log(startGroup(title))
+
+          return undefined // Don't log the marker itself
+        }
+        if (message.pluginGroupMarker === 'end') {
+          // End the plugin group
+          console.log(endGroup())
+
+          return undefined // Don't log the marker itself
+        }
+
+        // For setup/file operations that aren't plugin-specific, create individual groups
+        if (!message.pluginName && message.category && ['setup', 'file'].includes(message.category)) {
+          const firstLine = message.logs[0] || 'Debug Details'
+          const title = firstLine.length > DEBUG_LOG_TITLE_MAX_LENGTH ? `${firstLine.substring(0, DEBUG_LOG_TITLE_MAX_LENGTH)}...` : firstLine
+
+          console.log(startGroup(title))
+          console.log(pc.dim(fullLog))
+          console.log(endGroup())
+        } else {
+          // Plugin-specific logs are shown inline within their plugin group
+          // Non-categorized logs are shown inline
+          consola.log(pc.dim(fullLog))
+        }
+      } else {
+        // Non-CI environments - show all logs inline (except group markers)
+        if (!message.pluginGroupMarker) {
+          consola.log(pc.dim(fullLog))
+        }
+      }
     }
 
     cachedLogs.add(message)
@@ -118,15 +195,16 @@ export function createLogger({ logLevel = 3, name, consola: _consola }: Props =
           files[fileName] = []
         }
 
-        files[fileName] = [...files[fileName], `[${log.date.toLocaleString()}]: ${log.logs.join('\n\n')}`]
+        if (log.logs.length) {
+          files[fileName] = [...files[fileName], `[${log.date.toLocaleString()}]: \n${log.logs.join('\n')}`]
+        }
       })
+
       await Promise.all(
         Object.entries(files).map(async ([fileName, logs]) => {
           return write(fileName, logs.join('\n'))
         }),
       )
-
-      return Object.keys(files)
     },
   }
 

package/src/utils/ciDetection.ts

@@ -0,0 +1,40 @@
+/**
+ * Detect if running in a CI environment
+ * Note: Currently exported for potential future use in plugins or extensions
+ */
+export function isCI(): boolean {
+  return !!(process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.BUILD_NUMBER || process.env.RUN_ID)
+}
+
+/**
+ * Detect if running in GitHub Actions
+ */
+export function isGitHubActions(): boolean {
+  return process.env.GITHUB_ACTIONS === 'true'
+}
+
+/**
+ * GitHub Actions group markers
+ */
+const GITHUB_ACTIONS_GROUP_START = '::group::'
+const GITHUB_ACTIONS_GROUP_END = '::endgroup::'
+
+/**
+ * Create a collapsible group marker for GitHub Actions logs
+ */
+export function startGroup(title: string): string {
+  if (isCI() && isGitHubActions()) {
+    return `${GITHUB_ACTIONS_GROUP_START}${title}`
+  }
+  return ''
+}
+
+/**
+ * End a collapsible group in GitHub Actions logs
+ */
+export function endGroup(): string {
+  if (isGitHubActions()) {
+    return GITHUB_ACTIONS_GROUP_END
+  }
+  return ''
+}

package/src/utils/diagnostics.ts

@@ -0,0 +1,15 @@
+import { version as nodeVersion } from 'node:process'
+import { version as KubbVersion } from '../../package.json'
+
+/**
+ * Get diagnostic information for debugging
+ */
+export function getDiagnosticInfo() {
+  return {
+    nodeVersion,
+    KubbVersion,
+    platform: process.platform,
+    arch: process.arch,
+    cwd: process.cwd(),
+  } as const
+}