modestbench 0.0.3 → 0.2.0

package/src/cli/index.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 /**
  * ModestBench CLI Entry Point
  *
@@ -16,7 +17,6 @@ import { hideBin } from 'yargs/helpers';
 import type {
   BenchmarkEngine,
   ConfigurationManager,
-  ErrorManager,
   HistoryStorage,
   ProgressManager,
   ReporterRegistry,
@@ -24,6 +24,7 @@ import type {
 
 import { bootstrap } from '../bootstrap.js';
 import { AccurateEngine, TinybenchEngine } from '../core/engines/index.js';
+import { isModestBenchError, UnknownError } from '../errors/index.js';
 import {
   CsvReporter,
   HumanReporter,
@@ -31,7 +32,14 @@ import {
   SimpleReporter,
 } from '../reporters/index.js';
 // Import commands
-import { handleHistoryCommand as historyCommand } from './commands/history.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';
 
@@ -42,7 +50,6 @@ export interface CliContext {
   readonly abortController: AbortController;
   readonly configManager: ConfigurationManager;
   readonly engine: BenchmarkEngine;
-  readonly errorManager: ErrorManager;
   readonly historyStorage: HistoryStorage;
   readonly options: GlobalOptions;
   readonly progressManager: ProgressManager;
@@ -104,6 +111,7 @@ export const main = async (
 
     // Configure global options and commands
     await cli
+      .scriptName('modestbench')
       .option('config', {
         alias: 'c',
         description: 'Path to configuration file',
@@ -137,6 +145,7 @@ export const main = async (
       })
       .option('cwd', {
         default: process.cwd(),
+        defaultDescription: '.',
         description: 'Working directory',
         global: true,
         type: 'string',
@@ -187,6 +196,13 @@ export const main = async (
               description: 'Output directory for reports',
               type: 'string',
             })
+            .option('output-file', {
+              alias: 'of',
+              description:
+                'Custom filename for reporter output (use with single reporter only)',
+              requiresArg: true,
+              type: 'string',
+            })
             .option('iterations', {
               alias: 'i',
               description: 'Number of iterations per benchmark',
@@ -301,6 +317,7 @@ export const main = async (
             json: argv.json,
             noColor: argv.noColor,
             outputDir: argv.output,
+            outputFile: argv['output-file'],
             pattern: argv.pattern,
             progress: argv.progress,
             quiet: argv.quiet,
@@ -314,111 +331,349 @@ export const main = async (
           process.exit(exitCode);
         },
       )
-      .command(
-        'history <subcommand> [args..]',
-        'View and manage benchmark history',
-        (yargs) => {
-          return yargs
-            .positional('subcommand', {
-              choices: [
-                'list',
-                'show',
-                'compare',
-                'trends',
-                'clean',
-                'export',
-              ] as const,
-              demandOption: true,
-              describe: 'History subcommand',
-              type: 'string',
-            })
-            .positional('args', {
-              array: true,
-              describe: 'Additional arguments for the subcommand',
-              type: 'string',
-            })
-            .option('since', {
-              description:
-                'Show runs since date (ISO 8601 or relative like "1 week ago")',
-              type: 'string',
-            })
-            .option('until', {
-              description:
-                'Show runs until date (ISO 8601 or relative like "1 day ago")',
-              type: 'string',
-            })
-            .option('pattern', {
-              description: 'Filter by benchmark name pattern',
-              type: 'string',
-            })
-            .option('tags', {
-              description: 'Filter by tags',
-              type: 'array',
-            })
-            .option('limit', {
-              default: 10,
-              description: 'Maximum number of results',
-              type: 'number',
-            })
-            .option('format', {
-              choices: ['human', 'json', 'csv'] as const,
-              default: 'human' as const,
-              description: 'Output format',
-              type: 'string',
-            })
-            .option('maxAge', {
-              description: 'Maximum age in days for cleanup',
-              type: 'number',
-            })
-            .option('maxRuns', {
-              description: 'Maximum number of runs to keep',
-              type: 'number',
-            })
-            .option('maxSize', {
-              description: 'Maximum storage size in bytes',
-              type: 'number',
-            })
-            .option('confirm', {
-              default: false,
-              description: 'Confirm cleanup operations',
-              type: 'boolean',
-            })
-            .option('output', {
-              description: 'Output file path',
-              type: 'string',
-            })
-            .example([
-              ['$0 history list', 'List recent benchmark runs'],
-              ['$0 history show <run-id>', 'Show detailed results for run'],
-              ['$0 history compare <run-id1> <run-id2>', 'Compare two runs'],
-              ['$0 history trends [pattern]', 'Show performance trends'],
-              ['$0 history clean --max-runs 50', 'Keep only latest 50 runs'],
-              ['$0 history export --format csv', 'Export to CSV'],
-            ]);
-        },
-        async (argv) => {
-          const context = await createCliContext(argv, abortController!);
-          const exitCode = await historyCommand(context, {
-            args: argv.args,
-            confirm: argv.confirm,
-            cwd: argv.cwd,
-            format: argv.format,
-            limit: argv.limit,
-            maxAge: argv.maxAge,
-            maxRuns: argv.maxRuns,
-            maxSize: argv.maxSize,
-            outputDir: argv.output,
-            pattern: argv.pattern,
-            quiet: Boolean(argv.quiet),
-            since: argv.since,
-            subcommand: argv.subcommand,
-            tags: argv.tags as string[] | undefined,
-            until: argv.until,
-            verbose: argv.verbose,
-          });
-          process.exit(exitCode);
-        },
-      )
+      .command('history', 'View and manage benchmark history', (yargs) => {
+        return yargs
+          .command(
+            'list',
+            'List recent benchmark runs',
+            (yargs) => {
+              return yargs
+                .option('since', {
+                  description:
+                    'Show runs since date (ISO 8601 or relative like "1 week ago")',
+                  type: 'string',
+                })
+                .option('until', {
+                  description:
+                    'Show runs until date (ISO 8601 or relative like "1 day ago")',
+                  type: 'string',
+                })
+                .option('pattern', {
+                  description: 'Filter by benchmark name pattern',
+                  type: 'string',
+                })
+                .option('tags', {
+                  description: 'Filter by tags (comma-separated)',
+                  type: 'array',
+                })
+                .option('limit', {
+                  default: 10,
+                  description: 'Maximum number of results',
+                  type: 'number',
+                })
+                .option('format', {
+                  choices: ['human', 'json', 'csv'] as const,
+                  default: 'human' as const,
+                  description: 'Output format',
+                  type: 'string',
+                })
+                .example([
+                  ['$0 history list', 'List recent benchmark runs'],
+                  [
+                    '$0 history list --since "1 week ago"',
+                    'List runs from last week',
+                  ],
+                  ['$0 history list --limit 20', 'List 20 most recent runs'],
+                  ['$0 history list --format json', 'List runs in JSON format'],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleListCommand(context, {
+                cwd: argv.cwd,
+                format: argv.format,
+                limit: argv.limit,
+                pattern: argv.pattern,
+                quiet: Boolean(argv.quiet),
+                since: argv.since,
+                tags: argv.tags as string[] | undefined,
+                until: argv.until,
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'show <run-id>',
+            'Show detailed results for a specific run',
+            (yargs) => {
+              return yargs
+                .positional('run-id', {
+                  describe: 'ID of the benchmark run to show',
+                  type: 'string',
+                })
+                .option('format', {
+                  choices: ['human', 'json', 'csv'] as const,
+                  default: 'human' as const,
+                  description: 'Output format',
+                  type: 'string',
+                })
+                .example([
+                  [
+                    '$0 history show abc123',
+                    'Show detailed results for run abc123',
+                  ],
+                  [
+                    '$0 history show abc123 --format json',
+                    'Show run in JSON format',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleShowCommand(context, {
+                cwd: argv.cwd,
+                format: argv.format,
+                quiet: Boolean(argv.quiet),
+                runId: String(argv['run-id']),
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'compare <run-id1> <run-id2>',
+            'Compare two benchmark runs',
+            (yargs) => {
+              return yargs
+                .positional('run-id1', {
+                  describe: 'ID of the first benchmark run',
+                  type: 'string',
+                })
+                .positional('run-id2', {
+                  describe: 'ID of the second benchmark run',
+                  type: 'string',
+                })
+                .option('format', {
+                  choices: ['human', 'json'] as const,
+                  default: 'human' as const,
+                  description: 'Output format',
+                  type: 'string',
+                })
+                .example([
+                  ['$0 history compare abc123 def456', 'Compare two runs'],
+                  [
+                    '$0 history compare abc123 def456 --format json',
+                    'Compare in JSON format',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleCompareCommand(context, {
+                cwd: argv.cwd,
+                format: argv.format,
+                quiet: Boolean(argv.quiet),
+                runId1: String(argv['run-id1']),
+                runId2: String(argv['run-id2']),
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'trends [pattern]',
+            'Show performance trends over time',
+            (yargs) => {
+              return yargs
+                .positional('pattern', {
+                  describe: 'Filter by benchmark name pattern',
+                  type: 'string',
+                })
+                .option('since', {
+                  description:
+                    'Show trends since date (ISO 8601 or relative like "1 week ago")',
+                  type: 'string',
+                })
+                .option('until', {
+                  description:
+                    'Show trends until date (ISO 8601 or relative like "1 day ago")',
+                  type: 'string',
+                })
+                .option('tags', {
+                  description: 'Filter by tags (comma-separated)',
+                  type: 'array',
+                })
+                .option('limit', {
+                  description: 'Maximum number of runs to analyze',
+                  type: 'number',
+                })
+                .option('all', {
+                  alias: 'a',
+                  default: false,
+                  description: 'Analyze all runs (ignore limit)',
+                  type: 'boolean',
+                })
+                .option('format', {
+                  choices: ['human', 'json'] as const,
+                  default: 'human' as const,
+                  description: 'Output format',
+                  type: 'string',
+                })
+                .example([
+                  [
+                    '$0 history trends',
+                    'Show performance trends for all benchmarks',
+                  ],
+                  [
+                    '$0 history trends --since "1 month ago"',
+                    'Show trends from last month',
+                  ],
+                  [
+                    '$0 history trends "array-*"',
+                    'Show trends for array benchmarks',
+                  ],
+                  [
+                    '$0 history trends --format json',
+                    'Output trends in JSON format',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleTrendsCommand(context, {
+                all: Boolean(argv.all),
+                cwd: argv.cwd,
+                format: argv.format,
+                limit: argv.limit,
+                pattern: argv.pattern,
+                quiet: Boolean(argv.quiet),
+                since: argv.since,
+                tags: argv.tags as string[] | undefined,
+                until: argv.until,
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'clean',
+            'Clean up old benchmark history',
+            (yargs) => {
+              return yargs
+                .option('max-age', {
+                  description: 'Remove runs older than this many days',
+                  type: 'number',
+                })
+                .option('max-runs', {
+                  description: 'Keep only this many most recent runs',
+                  type: 'number',
+                })
+                .option('max-size', {
+                  description: 'Keep history under this size in bytes',
+                  type: 'number',
+                })
+                .option('confirm', {
+                  default: false,
+                  description: 'Confirm cleanup without prompting',
+                  type: 'boolean',
+                })
+                .check((argv) => {
+                  if (
+                    !argv['max-age'] &&
+                    !argv['max-runs'] &&
+                    !argv['max-size']
+                  ) {
+                    throw new Error(
+                      'At least one cleanup criterion must be specified (--max-age, --max-runs, or --max-size)',
+                    );
+                  }
+                  return true;
+                })
+                .example([
+                  [
+                    '$0 history clean --max-runs 50 --confirm',
+                    'Keep only latest 50 runs',
+                  ],
+                  [
+                    '$0 history clean --max-age 30',
+                    'Preview removing runs older than 30 days',
+                  ],
+                  [
+                    '$0 history clean --max-size 10485760',
+                    'Keep history under 10MB',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleCleanCommand(context, {
+                confirm: argv.confirm,
+                cwd: argv.cwd,
+                maxAge: argv['max-age'],
+                maxRuns: argv['max-runs'],
+                maxSize: argv['max-size'],
+                quiet: Boolean(argv.quiet),
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'export',
+            'Export benchmark history to a file',
+            (yargs) => {
+              return yargs
+                .option('format', {
+                  choices: ['json', 'csv'] as const,
+                  default: 'json' as const,
+                  description: 'Export format',
+                  type: 'string',
+                })
+                .option('output', {
+                  alias: 'o',
+                  demandOption: true,
+                  description: 'Output file path',
+                  type: 'string',
+                })
+                .option('since', {
+                  description: 'Export runs since date',
+                  type: 'string',
+                })
+                .option('until', {
+                  description: 'Export runs until date',
+                  type: 'string',
+                })
+                .example([
+                  [
+                    '$0 history export -o history.json',
+                    'Export all history to JSON',
+                  ],
+                  [
+                    '$0 history export -o history.csv --format csv',
+                    'Export to CSV',
+                  ],
+                  [
+                    '$0 history export -o recent.json --since "1 week ago"',
+                    'Export recent runs',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleExportCommand(context, {
+                cwd: argv.cwd,
+                format: argv.format,
+                outputPath: argv.output,
+                quiet: Boolean(argv.quiet),
+                since: argv.since,
+                until: argv.until,
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .demandCommand(1, 'You must specify a history subcommand')
+          .strict()
+          .example([
+            ['$0 history list', 'List recent benchmark runs'],
+            ['$0 history show <run-id>', 'Show detailed results'],
+            ['$0 history compare <run-id1> <run-id2>', 'Compare two runs'],
+            ['$0 history trends', 'Show performance trends'],
+            ['$0 history clean --max-runs 50', 'Keep only latest 50 runs'],
+            ['$0 history export -o data.json', 'Export history'],
+          ]);
+      })
       .command(
         'init [type]',
         'Initialize a new benchmark project',
@@ -571,7 +826,6 @@ const createCliContext = async (
       abortController,
       configManager: engine.configManager,
       engine,
-      errorManager: engine.errorManager,
       historyStorage: engine.historyStorage,
       options,
       progressManager: engine.progressManager,
@@ -596,9 +850,7 @@ const setupSignalHandlers = (abortController: AbortController): void => {
     if (abortRequested) {
       // Second signal, force exit
       console.log(`\nReceived ${signal} again, forcing exit...`);
-      process.exit(
-        128 + (signal === 'SIGINT' ? 2 : signal === 'SIGQUIT' ? 3 : 15),
-      );
+      process.exit(computeExitCode(signal));
     }
 
     console.log(`\nReceived ${signal}, aborting benchmarks...`);
@@ -608,9 +860,7 @@ const setupSignalHandlers = (abortController: AbortController): void => {
     // Give a short grace period for cleanup, then exit
     setTimeout(() => {
       console.log('\nBenchmark aborted.');
-      process.exit(
-        128 + (signal === 'SIGINT' ? 2 : signal === 'SIGQUIT' ? 3 : 15),
-      );
+      process.exit(computeExitCode(signal));
     }, 100);
   };
 
@@ -618,13 +868,27 @@ const setupSignalHandlers = (abortController: AbortController): void => {
   process.on('SIGQUIT', () => handleSignal('SIGQUIT'));
   process.on('SIGTERM', () => handleSignal('SIGTERM'));
 
-  process.on('uncaughtException', (error) => {
-    console.error('Uncaught exception:', error);
+  process.once('uncaughtException', (error) => {
+    // Wrap non-ModestBench errors with UnknownError
+    const wrappedError: Error = isModestBenchError(error)
+      ? error
+      : new UnknownError(
+          error instanceof Error ? error.message : String(error),
+          { cause: error },
+        );
+    console.error(wrappedError.toString());
     process.exit(ExitCodes.RUNTIME_ERROR);
   });
 
-  process.on('unhandledRejection', (reason, promise) => {
-    console.error('Unhandled rejection at:', promise, 'reason:', reason);
+  process.once('unhandledRejection', (reason) => {
+    // Wrap non-ModestBench errors with UnknownError
+    const wrappedError: Error = isModestBenchError(reason)
+      ? (reason as Error)
+      : new UnknownError(
+          reason instanceof Error ? reason.message : String(reason),
+          { cause: reason },
+        );
+    console.error(wrappedError.toString());
     process.exit(ExitCodes.RUNTIME_ERROR);
   });
 };
@@ -647,3 +911,13 @@ try {
     cli();
   }
 }
+
+/**
+ * Compute the exit code based on the signal
+ *
+ * @param signal - The signal that caused the exit
+ * @returns The exit code
+ */
+const computeExitCode = (signal: string): number => {
+  return 128 + (signal === 'SIGINT' ? 2 : signal === 'SIGQUIT' ? 3 : 15);
+};

package/src/constants.ts

@@ -19,3 +19,63 @@ export const BENCHMARK_FILE_PATTERN = `.bench.{${Array.from(
 )
   .map((ext) => ext.slice(1))
   .join(',')}}`;
+
+/**
+ * Error codes for all ModestBench errors
+ *
+ * Use these constants to check error types instead of instanceof checks.
+ */
+export const ErrorCodes = {
+  //#region cli-errors
+  CLI_INVALID_ARGUMENT: 'ERR_MB_CLI_INVALID_ARGUMENT',
+  CLI_INVALID_DATE_FORMAT: 'ERR_MB_CLI_INVALID_DATE_FORMAT',
+  //#endregion
+
+  //#region config-errors
+  CONFIG_LOAD_FAILED: 'ERR_MB_CONFIG_LOAD_FAILED',
+  CONFIG_NOT_FOUND: 'ERR_MB_CONFIG_NOT_FOUND',
+  CONFIG_UNSUPPORTED_FORMAT: 'ERR_MB_CONFIG_UNSUPPORTED_FORMAT',
+  CONFIG_VALIDATION_FAILED: 'ERR_MB_CONFIG_VALIDATION_FAILED',
+  //#endregion
+
+  //#region execution-errors
+  EXECUTION_BENCHMARK_FAILED: 'ERR_MB_EXECUTION_BENCHMARK_FAILED',
+  EXECUTION_SETUP_FAILED: 'ERR_MB_EXECUTION_SETUP_FAILED',
+  EXECUTION_TASK_FAILED: 'ERR_MB_EXECUTION_TASK_FAILED',
+  EXECUTION_TEARDOWN_FAILED: 'ERR_MB_EXECUTION_TEARDOWN_FAILED',
+  EXECUTION_TIMEOUT: 'ERR_MB_EXECUTION_TIMEOUT',
+  EXECUTION_TOO_FAST: 'ERR_MB_EXECUTION_TOO_FAST',
+  //#endregion
+
+  //#region file-errors
+  FILE_DISCOVERY_FAILED: 'ERR_MB_FILE_DISCOVERY_FAILED',
+  FILE_LOAD_FAILED: 'ERR_MB_FILE_LOAD_FAILED',
+  FILE_NOT_FOUND: 'ERR_MB_FILE_NOT_FOUND',
+  FILE_PERMISSION_DENIED: 'ERR_MB_FILE_PERMISSION_DENIED',
+  FILE_UNSUPPORTED_EXTENSION: 'ERR_MB_FILE_UNSUPPORTED_EXTENSION',
+  //#endregion
+
+  //#region reporter-errors
+  REPORTER_ALREADY_REGISTERED: 'ERR_MB_REPORTER_ALREADY_REGISTERED',
+  REPORTER_OUTPUT_FAILED: 'ERR_MB_REPORTER_OUTPUT_FAILED',
+  REPORTER_UNKNOWN: 'ERR_MB_REPORTER_UNKNOWN',
+  //#endregion
+
+  //#region storage-errors
+  STORAGE_CORRUPTION: 'ERR_MB_STORAGE_CORRUPTION',
+  STORAGE_EXPORT_UNSUPPORTED: 'ERR_MB_STORAGE_EXPORT_UNSUPPORTED',
+  STORAGE_FAILED: 'ERR_MB_STORAGE_FAILED',
+  STORAGE_INDEX_CORRUPTION: 'ERR_MB_STORAGE_INDEX_CORRUPTION',
+  STORAGE_INSUFFICIENT_SPACE: 'ERR_MB_STORAGE_INSUFFICIENT_SPACE',
+  //#endregion
+
+  //#region misc-errors
+  UNKNOWN: 'ERR_MB_UNKNOWN',
+  //#endregion
+
+  //#region validation-errors
+  VALIDATION_SCHEMA_FAILED: 'ERR_MB_VALIDATION_SCHEMA_FAILED',
+  VALIDATION_STRUCTURE_INVALID: 'ERR_MB_VALIDATION_STRUCTURE_INVALID',
+  VALIDATION_TYPE_FAILED: 'ERR_MB_VALIDATION_TYPE_FAILED',
+  //#endregion
+} as const;