modestbench 0.9.1 → 0.9.2

package/src/cli/builder.ts

@@ -0,0 +1,387 @@
+/**
+ * CLI Builder
+ *
+ * Constructs the CLI using bargs, registering all commands, subcommands, and
+ * their handlers.
+ *
+ * @packageDocumentation
+ */
+
+import { bargs } from '@boneskull/bargs';
+
+import type { CliContext } from './context.js';
+
+import {
+  handleAnalyzeCommand as analyzeCommand,
+  type AnalyzeOptions,
+} from './commands/analyze.js';
+import {
+  handleAnalyzeCommand as handleBaselineAnalyzeCommand,
+  handleDeleteCommand as handleBaselineDeleteCommand,
+  handleListCommand as handleBaselineListCommand,
+  handleSetCommand as handleBaselineSetCommand,
+  handleShowCommand as handleBaselineShowCommand,
+} from './commands/baseline.js';
+import {
+  handleCleanCommand,
+  handleCompareCommand,
+  handleExportCommand,
+  handleListCommand,
+  handleShowCommand,
+  handleTrendsCommand,
+} from './commands/history.js';
+import { handleInitCommand as initCommand } from './commands/init.js';
+import { handleRunCommand as runCommand } from './commands/run.js';
+import {
+  handleTestCommand as testCommand,
+  type TestOptions,
+} from './commands/test.js';
+import { createCliContext } from './context.js';
+import {
+  analyzeParser,
+  baselineAnalyzeParser,
+  baselineDeleteParser,
+  baselineListParser,
+  baselineSetParser,
+  baselineShowParser,
+  globalOptions,
+  historyCleanParser,
+  historyCompareParser,
+  historyExportParser,
+  historyListParser,
+  historyShowParser,
+  historyTrendsParser,
+  initParser,
+  quietOption,
+  runParser,
+  testParser,
+} from './parsers/index.js';
+import { synthwaveTheme } from './theme.js';
+
+/**
+ * Create the CLI builder with all commands registered
+ *
+ * @param abortController - Controller for aborting benchmark runs
+ * @returns Configured bargs CLI builder
+ */
+export const createCli = (abortController: AbortController) => {
+  return bargs('modestbench', {
+    description: 'A modern benchmark runner for Node.js',
+    theme: synthwaveTheme,
+  })
+    .globals(globalOptions)
+    .command(
+      'run',
+      runParser,
+      async ({ positionals, values }) => {
+        const [pattern] = positionals;
+        const context = await createCliContext(
+          values,
+          abortController,
+          values.engine,
+        );
+        const exitCode = await runCommand(context, {
+          bail: values.bail,
+          config: values.config,
+          cwd: values.cwd,
+          engine: values.engine,
+          exclude: values.exclude,
+          excludeTags: values.excludeTag,
+          iterations: values.iterations,
+          json: values.json,
+          jsonPretty: values.jsonPretty,
+          noColor: values.noColor,
+          outputDir: values.output,
+          outputFile: values.outputFile,
+          pattern,
+          progress: values.progress,
+          quiet: values.quiet,
+          reporters: values.reporter,
+          tags: values.tag,
+          time: values.time,
+          timeout: values.timeout,
+          verbose: values.verbose,
+          warmup: values.warmup,
+        });
+        process.exitCode = exitCode;
+      },
+      'Run benchmark files',
+    )
+    .command(
+      'history',
+      (history) =>
+        history
+          .globals(quietOption)
+          .command(
+            'list',
+            historyListParser,
+            async ({ values }) => {
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleListCommand(context, {
+                cwd: values.cwd,
+                format: values.format,
+                limit: values.limit,
+                pattern: values.pattern,
+                since: values.since,
+                tags: values.tag,
+                until: values.until,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'List recent benchmark runs',
+          )
+          .command(
+            'show',
+            historyShowParser,
+            async ({ positionals, values }) => {
+              const [runId] = positionals;
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleShowCommand(context, {
+                cwd: values.cwd,
+                format: values.format,
+                runId,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Show detailed results for a specific run',
+          )
+          .command(
+            'compare',
+            historyCompareParser,
+            async ({ positionals, values }) => {
+              const [runId1, runId2] = positionals;
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleCompareCommand(context, {
+                cwd: values.cwd,
+                format: values.format,
+                runId1,
+                runId2,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Compare two benchmark runs',
+          )
+          .command(
+            'trends',
+            historyTrendsParser,
+            async ({ positionals, values }) => {
+              const [pattern] = positionals;
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleTrendsCommand(context, {
+                all: values.all,
+                cwd: values.cwd,
+                format: values.format,
+                limit: values.limit,
+                pattern,
+                since: values.since,
+                tags: values.tag,
+                until: values.until,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Show performance trends over time',
+          )
+          .command(
+            'clean',
+            historyCleanParser,
+            async ({ values }) => {
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleCleanCommand(context, {
+                confirm: values.yes,
+                cwd: values.cwd,
+                maxAge: values.maxAge,
+                maxRuns: values.maxRuns,
+                maxSize: values.maxSize,
+                quiet: values.quiet,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Clean up old benchmark history',
+          )
+          .command(
+            'export',
+            historyExportParser,
+            async ({ values }) => {
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleExportCommand(context, {
+                cwd: values.cwd,
+                format: values.format,
+                outputPath: values.output,
+                quiet: Boolean(values.quiet),
+                since: values.since,
+                until: values.until,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Export benchmark history to a file',
+          ),
+      'View and manage benchmark history',
+    )
+    .command(
+      'baseline',
+      (baseline) =>
+        baseline
+          .globals(quietOption)
+          .command(
+            'set',
+            baselineSetParser,
+            async ({ positionals, values }) => {
+              const [name] = positionals;
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleBaselineSetCommand(context, {
+                branch: values.branch,
+                commit: values.commit,
+                cwd: values.cwd,
+                default: values.default,
+                name,
+                quiet: Boolean(values.quiet),
+                runId: values.runId,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Save a benchmark run as a baseline',
+          )
+          .command(
+            'list',
+            baselineListParser,
+            async ({ values }) => {
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleBaselineListCommand(context, {
+                cwd: values.cwd,
+                format: values.format,
+                quiet: Boolean(values.quiet),
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'List all saved baselines',
+          )
+          .command(
+            'show',
+            baselineShowParser,
+            async ({ positionals, values }) => {
+              const [name] = positionals;
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleBaselineShowCommand(context, {
+                cwd: values.cwd,
+                format: values.format,
+                name,
+                quiet: Boolean(values.quiet),
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Show baseline details',
+          )
+          .command(
+            'delete',
+            baselineDeleteParser,
+            async ({ positionals, values }) => {
+              const [name] = positionals;
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleBaselineDeleteCommand(context, {
+                cwd: values.cwd,
+                name,
+                quiet: Boolean(values.quiet),
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Delete a baseline',
+          )
+          .command(
+            'analyze',
+            baselineAnalyzeParser,
+            async ({ values }) => {
+              const context = await createCliContext(values, abortController);
+              const exitCode = await handleBaselineAnalyzeCommand(context, {
+                confidence: values.confidence,
+                cwd: values.cwd,
+                quiet: Boolean(values.quiet),
+                runs: values.runs,
+                verbose: values.verbose,
+              });
+              process.exitCode = exitCode;
+            },
+            'Analyze history and suggest performance budgets',
+          ),
+      'Manage performance baselines',
+    )
+    .command(
+      'init',
+      initParser,
+      async ({ positionals, values }) => {
+        const [type] = positionals;
+        const context = await createCliContext(values, abortController);
+        const exitCode = await initCommand(context, {
+          configType: values.configType,
+          cwd: values.cwd,
+          examples: values.examples,
+          force: values.force,
+          quiet: values.quiet,
+          type,
+          verbose: values.verbose,
+          yes: values.yes,
+        });
+        process.exitCode = exitCode;
+      },
+      'Initialize a new benchmark project',
+    )
+    .command(
+      'analyze',
+      analyzeParser,
+      async ({ positionals, values }) => {
+        const [command] = positionals;
+        // Context not needed for analyze command currently
+        const context = {} as CliContext;
+
+        const options: AnalyzeOptions = {
+          color: !values.noColor,
+          command,
+          cwd: values.cwd || process.cwd(),
+          filterFile: values.filterFile,
+          groupByFile: values.groupByFile,
+          input: values.input,
+          minPercent: values.minPercent,
+          top: values.top,
+        };
+
+        process.exitCode = await analyzeCommand(context, options);
+      },
+      {
+        aliases: ['profile'],
+        description: 'Analyze code execution and identify benchmark candidates',
+      },
+    )
+    .command(
+      'test',
+      testParser,
+      async ({ positionals, values }) => {
+        const [framework, files] = positionals;
+        const context = await createCliContext(values, abortController);
+        const options: TestOptions = {
+          bail: values.bail,
+          cwd: values.cwd,
+          framework,
+          iterations: values.iterations,
+          json: values.json,
+          noColor: values.noColor,
+          pattern: files,
+          quiet: values.quiet,
+          verbose: values.verbose,
+          warmup: values.warmup,
+        };
+        const exitCode = await testCommand(context, options);
+        process.exitCode = exitCode;
+      },
+      'Run test files as benchmarks',
+    )
+    .defaultCommand('run');
+};

package/src/cli/commands/baseline.ts

@@ -11,6 +11,10 @@ import type { CliContext } from '../index.js';
 
 import { BaselineStorageService } from '../../services/baseline-storage.js';
 import { createTaskId } from '../../types/index.js';
+import {
+  formatDuration,
+  formatOpsPerSecond,
+} from '../../utils/reporter-utils.js';
 
 /**
  * Options for baseline analyze command
@@ -62,38 +66,6 @@ interface BaselineShowOptions extends BaselineBaseOptions {
   name: string;
 }
 
-/**
- * Format duration in human-readable format
- */
-const formatDuration = (nanoseconds: number): string => {
-  if (nanoseconds < 1000) {
-    return `${nanoseconds.toFixed(2)}ns`;
-  }
-  if (nanoseconds < 1_000_000) {
-    return `${(nanoseconds / 1000).toFixed(2)}μs`;
-  }
-  if (nanoseconds < 1_000_000_000) {
-    return `${(nanoseconds / 1_000_000).toFixed(2)}ms`;
-  }
-  return `${(nanoseconds / 1_000_000_000).toFixed(2)}s`;
-};
-
-/**
- * Format operations per second
- */
-const formatOpsPerSec = (ops: number): string => {
-  if (ops < 1000) {
-    return `${ops.toFixed(2)} ops/sec`;
-  }
-  if (ops < 1_000_000) {
-    return `${(ops / 1000).toFixed(2)}K ops/sec`;
-  }
-  if (ops < 1_000_000_000) {
-    return `${(ops / 1_000_000).toFixed(2)}M ops/sec`;
-  }
-  return `${(ops / 1_000_000_000).toFixed(2)}B ops/sec`;
-};
-
 /**
  * Format date in readable format
  */
@@ -337,7 +309,9 @@ export const handleShowCommand = async (
         for (const [taskId, data] of tasks) {
           console.log(`    ${taskId}`);
           console.log(`      Mean:    ${formatDuration(data.mean)}`);
-          console.log(`      Ops/sec: ${formatOpsPerSec(data.opsPerSecond)}`);
+          console.log(
+            `      Ops/sec: ${formatOpsPerSecond(data.opsPerSecond)}`,
+          );
           if (data.p99) {
             console.log(`      P99:     ${formatDuration(data.p99)}`);
           }

package/src/cli/commands/history.ts

@@ -22,6 +22,7 @@ import {
   parseDate,
 } from '../../services/history/query.js';
 import { TrendAnalysisService } from '../../services/history/trend-analysis.js';
+import { formatBytes } from '../../utils/reporter-utils.js';
 
 /**
  * Base options shared by all history subcommands
@@ -94,22 +95,6 @@ interface HistoryTrendsOptions extends BaseHistoryOptions {
   until?: string | undefined;
 }
 
-/**
- * Format bytes in human-readable format
- */
-const formatBytes = (bytes: number): string => {
-  const units = ['B', 'KB', 'MB', 'GB'];
-  let size = bytes;
-  let unitIndex = 0;
-
-  while (size >= 1024 && unitIndex < units.length - 1) {
-    size /= 1024;
-    unitIndex++;
-  }
-
-  return `${size.toFixed(1)} ${units[unitIndex]}`;
-};
-
 /**
  * Resolve a partial run ID to a full ID by checking prefix match
  *

package/src/cli/context.ts

@@ -0,0 +1,117 @@
+/**
+ * CLI Context
+ *
+ * Provides dependency injection container for CLI commands, including
+ * configuration manager, benchmark engine, history storage, and reporters.
+ *
+ * @packageDocumentation
+ */
+
+import type { InferParserValues } from '@boneskull/bargs';
+
+import type {
+  BenchmarkEngine,
+  ConfigurationManager,
+  Engine,
+  HistoryStorage,
+  ProgressManager,
+  ReporterRegistry,
+} from '../types/index.js';
+import type { globalOptions } from './parsers/global.js';
+
+import { bootstrap } from '../bootstrap.js';
+import { DEFAULT_ENGINE, Engines, ExitCodes, Reporters } from '../constants.js';
+import { AccurateEngine, TinybenchEngine } from '../core/engines/index.js';
+import {
+  CsvReporter,
+  HumanReporter,
+  JsonReporter,
+  NyanReporter,
+  SimpleReporter,
+} from '../reporters/index.js';
+
+/**
+ * CLI context with initialized services
+ */
+export interface CliContext {
+  readonly abortController: AbortController;
+  readonly configManager: ConfigurationManager;
+  readonly engine: BenchmarkEngine;
+  readonly historyStorage: HistoryStorage;
+  readonly options: InferParserValues<typeof globalOptions>;
+  readonly progressManager: ProgressManager;
+  readonly reporterRegistry: ReporterRegistry;
+}
+
+/**
+ * Create CLI context with dependency injection
+ */
+export const createCliContext = async (
+  options: InferParserValues<typeof globalOptions>,
+  abortController: AbortController,
+  engineType: Engine = DEFAULT_ENGINE,
+): Promise<CliContext> => {
+  try {
+    const dependencies = bootstrap();
+
+    // Select engine based on type
+    const engine =
+      engineType === Engines.ACCURATE
+        ? new AccurateEngine(dependencies)
+        : new TinybenchEngine(dependencies);
+
+    // Register built-in reporters
+    engine.registerReporter(
+      Reporters.HUMAN,
+      new HumanReporter({
+        color: !options.noColor,
+        verbose: options.verbose,
+      }),
+    );
+
+    engine.registerReporter(
+      'json',
+      new JsonReporter({
+        prettyPrint: false,
+      }),
+    );
+
+    engine.registerReporter(
+      'csv',
+      new CsvReporter({
+        includeHeaders: true,
+        includeMetadata: true,
+      }),
+    );
+
+    engine.registerReporter(
+      'simple',
+      new SimpleReporter({
+        verbose: options.verbose,
+      }),
+    );
+
+    engine.registerReporter(
+      'nyan',
+      new NyanReporter({
+        color: !options.noColor,
+      }),
+    );
+
+    return {
+      abortController,
+      configManager: engine.configManager,
+      engine,
+      historyStorage: engine.historyStorage,
+      options,
+      progressManager: engine.progressManager,
+      reporterRegistry: engine.reporterRegistry,
+    };
+  } catch (error) {
+    console.error(
+      'Failed to initialize ModestBench:',
+      error instanceof Error ? error.message : String(error),
+    );
+    process.exit(ExitCodes.CONFIG_ERROR);
+  }
+};

package/src/cli/handlers.ts

@@ -0,0 +1,76 @@
+/**
+ * CLI Signal Handlers
+ *
+ * Handles process signals (SIGINT, SIGTERM, etc.) and uncaught errors for
+ * graceful shutdown of benchmark runs.
+ *
+ * @packageDocumentation
+ */
+
+import { ABORT_TIMEOUT, ExitCodes } from '../constants.js';
+import { isModestBenchError, UnknownError } from '../errors/index.js';
+import { isError } from '../utils/type-guards.js';
+
+/**
+ * Handle process signals gracefully
+ */
+export const setupSignalHandlers = (abortController: AbortController): void => {
+  let abortRequested = false;
+
+  const handleSignal = (signal: NodeJS.Signals) => {
+    if (abortRequested) {
+      // Second signal, force exit
+      console.log(`\nReceived ${signal} again, forcing exit...`);
+      process.exit(computeExitCode(signal));
+    }
+
+    console.log(`\nReceived ${signal}, aborting benchmarks...`);
+    abortRequested = true;
+    abortController.abort();
+
+    // Give a short grace period for cleanup, then exit
+    setTimeout(() => {
+      console.log('\nBenchmark aborted.');
+      process.exit(computeExitCode(signal));
+    }, ABORT_TIMEOUT);
+  };
+
+  process
+    .once('SIGINT', handleSignal)
+    .once('SIGQUIT', handleSignal)
+    .once('SIGTERM', handleSignal)
+    .once('uncaughtException', (error) => {
+      // Wrap non-ModestBench errors with UnknownError
+      const wrappedError: Error = isModestBenchError(error)
+        ? error
+        : new UnknownError(error.message, { cause: error });
+      console.error(`${wrappedError}`);
+      process.exit(ExitCodes.RUNTIME_ERROR);
+    })
+    .once('unhandledRejection', (reason) => {
+      const wrappedError: Error = isModestBenchError(reason)
+        ? reason
+        : new UnknownError(isError(reason) ? reason.message : String(reason), {
+            cause: reason,
+          });
+      console.error(`${wrappedError}`);
+      process.exit(ExitCodes.RUNTIME_ERROR);
+    });
+};
+
+/**
+ * Compute the exit code based on the signal
+ *
+ * @param signal - The signal that caused the exit
+ * @returns The exit code
+ */
+const computeExitCode = (signal: NodeJS.Signals): number => {
+  switch (signal) {
+    case 'SIGINT':
+      return 130; // 128 + 2
+    case 'SIGQUIT':
+      return 131; // 128 + 3
+    default:
+      return 143; // 128 + 15 (SIGTERM)
+  }
+};