modestbench 0.1.0 → 0.3.0

package/src/cli/index.ts

@@ -7,8 +7,6 @@
  * global options, help generation, and dependency injection setup.
  */
 
-import type { Argv } from 'yargs';
-
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
@@ -17,13 +15,24 @@ import { hideBin } from 'yargs/helpers';
 import type {
   BenchmarkEngine,
   ConfigurationManager,
+  Engine,
   HistoryStorage,
   ProgressManager,
   ReporterRegistry,
 } from '../types/index.js';
 
 import { bootstrap } from '../bootstrap.js';
+import {
+  ABORT_TIMEOUT,
+  DEFAULT_ENGINE,
+  DEFAULT_REPORTER,
+  Engines,
+  ErrorCodes,
+  ExitCodes,
+  Reporters,
+} from '../constants.js';
 import { AccurateEngine, TinybenchEngine } from '../core/engines/index.js';
+import { isError } from '../errors/base.js';
 import { isModestBenchError, UnknownError } from '../errors/index.js';
 import {
   CsvReporter,
@@ -32,9 +41,30 @@ import {
   SimpleReporter,
 } from '../reporters/index.js';
 // Import commands
-import { handleHistoryCommand as historyCommand } from './commands/history.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 {
+  RUN_COMMAND_DEFAULTS,
+  handleRunCommand as runCommand,
+} from './commands/run.js';
 
 /**
  * CLI context with initialized services
@@ -56,28 +86,15 @@ interface GlobalOptions {
   /** Configuration file path */
   config?: string | undefined;
   /** Working directory */
-  cwd: string;
+  cwd?: string;
   /** JSON output for machine parsing */
-  json: boolean;
+  json?: boolean;
   /** Disable colored output */
-  noColor: boolean;
+  noColor?: boolean;
   /** Enable verbose output */
-  verbose: boolean;
+  verbose?: boolean;
 }
 
-/**
- * Exit codes for the CLI
- */
-export const ExitCodes = {
-  BENCHMARK_FAILURES: 1,
-  CONFIG_ERROR: 2,
-  DISCOVERY_ERROR: 3,
-  RUNTIME_ERROR: 5,
-  SUCCESS: 0,
-  UNKNOWN_ERROR: 99,
-  VALIDATION_ERROR: 4,
-} as const;
-
 /**
  * Initialize and run the CLI
  */
@@ -103,7 +120,9 @@ export const main = async (
     const cli = yargs(args);
 
     // Configure global options and commands
+
     await cli
+      .scriptName('modestbench')
       .option('config', {
         alias: 'c',
         description: 'Path to configuration file',
@@ -112,33 +131,34 @@ export const main = async (
       })
       .option('verbose', {
         alias: 'v',
-        default: false,
+        defaultDescription: String(RUN_COMMAND_DEFAULTS.verbose),
         description: 'Enable verbose output',
         global: true,
         type: 'boolean',
       })
       .option('no-color', {
-        default: false,
+        defaultDescription: 'false',
         description: 'Disable colored output',
         global: true,
         type: 'boolean',
       })
       .option('progress', {
-        default: true,
+        defaultDescription: 'true',
         description: 'Show animated progress bar',
         global: true,
         type: 'boolean',
       })
       .option('json', {
-        default: false,
+        defaultDescription: 'false',
         description: 'Output results in JSON format',
         global: true,
         type: 'boolean',
       })
       .option('cwd', {
-        default: process.cwd(),
+        defaultDescription: '.',
         description: 'Working directory',
         global: true,
+        normalize: true,
         type: 'string',
       })
       .help()
@@ -146,18 +166,18 @@ export const main = async (
       .version()
       .alias('version', 'V')
       .strict()
-      .demandCommand(1, 'You must specify a command')
+      .demandCommand(1)
       .recommendCommands()
       .completion()
       .wrap(Math.min(120, cli.terminalWidth()))
       .command(
         ['$0 [pattern..]', 'run [pattern..]'],
         'Run benchmark files',
-        (yargs) => {
-          return yargs
+        (yargs) =>
+          yargs
             .positional('pattern', {
               array: true,
-              default: ['./bench/**/*.bench.{js,mjs,cjs,ts}'],
+              defaultDescription: '(auto-discovered from bench/ directory)',
               describe:
                 'File paths, directory paths, or glob patterns for benchmark files',
               type: 'string',
@@ -167,26 +187,26 @@ export const main = async (
               description: 'Path to configuration file',
               type: 'string',
             })
-            .option('reporters', {
+            .option('reporter', {
               alias: 'r',
-              coerce: (value: string | string[]) => {
-                // Handle comma-separated values
-                if (Array.isArray(value)) {
-                  return value.flatMap((v) =>
-                    v.split(',').map((s) => s.trim()),
-                  );
-                }
-                return value.split(',').map((s) => s.trim());
-              },
-              default: ['human'],
+              array: true,
+              choices: Object.values(Reporters).sort(),
+              defaultDescription: DEFAULT_REPORTER,
               description: 'Output reporters to use (human,json,csv)',
-              type: 'array',
+              type: 'string',
             })
             .option('output', {
               alias: 'o',
               description: 'Output directory for reports',
               type: 'string',
             })
+            .option('output-file', {
+              alias: ['of', 'file'],
+              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',
@@ -198,11 +218,12 @@ export const main = async (
               type: 'number',
             })
             .option('warmup', {
-              alias: 'w',
+              alias: ['w', 'warm'],
               description: 'Number of warmup iterations',
               type: 'number',
             })
             .option('limit-by', {
+              alias: ['l', 'limit'],
               choices: ['time', 'iterations', 'any', 'all'],
               description:
                 'How to limit benchmarks: time (time budget), iterations (sample count), any (either threshold), all (both thresholds)',
@@ -210,22 +231,15 @@ export const main = async (
             })
             .option('bail', {
               alias: 'b',
-              default: false,
+              defaultDescription: String(RUN_COMMAND_DEFAULTS.bail),
               description: 'Stop on first failure',
               type: 'boolean',
             })
             .option('exclude', {
-              coerce: (value: string | string[]) => {
-                // Handle comma-separated values
-                if (Array.isArray(value)) {
-                  return value.flatMap((v) =>
-                    v.split(',').map((s) => s.trim()),
-                  );
-                }
-                return value.split(',').map((s) => s.trim());
-              },
+              alias: 'X',
+              array: true,
               description: 'Exclude patterns (comma-separated)',
-              type: 'array',
+              type: 'string',
             })
             .option('timeout', {
               description: 'Timeout per benchmark in milliseconds',
@@ -233,40 +247,25 @@ export const main = async (
             })
             .option('quiet', {
               alias: 'q',
-              default: false,
+              defaultDescription: String(RUN_COMMAND_DEFAULTS.quiet),
               description: 'Minimal output',
               type: 'boolean',
             })
-            .option('tags', {
-              coerce: (value: string | string[]) => {
-                // Handle comma-separated values
-                if (Array.isArray(value)) {
-                  return value.flatMap((v) =>
-                    v.split(',').map((s) => s.trim()),
-                  );
-                }
-                return value.split(',').map((s) => s.trim());
-              },
+            .option('tag', {
+              array: true,
               description: 'Include only benchmarks with any of these tags',
-              type: 'array',
+              type: 'string',
             })
-            .option('exclude-tags', {
-              coerce: (value: string | string[]) => {
-                // Handle comma-separated values
-                if (Array.isArray(value)) {
-                  return value.flatMap((v) =>
-                    v.split(',').map((s) => s.trim()),
-                  );
-                }
-                return value.split(',').map((s) => s.trim());
-              },
+            .option('exclude-tag', {
+              alias: 'T',
+              array: true,
               description: 'Exclude benchmarks with any of these tags',
-              type: 'array',
+              type: 'string',
             })
             .option('engine', {
               alias: 'e',
-              choices: ['tinybench', 'accurate'] as const,
-              default: 'tinybench' as const,
+              choices: Object.values(Engines),
+              defaultDescription: DEFAULT_ENGINE,
               description:
                 'Benchmark engine: tinybench (default) or accurate (requires --allow-natives-syntax)',
               type: 'string',
@@ -278,12 +277,23 @@ export const main = async (
               ['$0 run "src/**/*.bench.js"', 'Run specific glob pattern'],
               ['$0 run file1.bench.js file2.bench.js', 'Run specific files'],
               ['$0 run benchmarks/ tests/perf/', 'Run multiple directories'],
-              ['$0 run --reporters json,csv', 'Use multiple reporters'],
+              ['$0 run -r json -r csv', 'Use multiple reporters'],
               ['$0 run --iterations 1000', 'Set iteration count'],
               ['$0 run --engine accurate', 'Use high-accuracy engine'],
               ['$0 run --bail', 'Stop on first failure'],
-            ]);
-        },
+            ])
+            .check((argv) => {
+              if (
+                argv.reporter &&
+                argv.reporter.length > 1 &&
+                argv['output-file']
+              ) {
+                throw new Error(
+                  '--output-file can only be used with a single reporter. Use --output <dir> for multiple reporters.',
+                );
+              }
+              return true;
+            }),
         async (argv) => {
           const context = await createCliContext(
             argv,
@@ -296,16 +306,17 @@ export const main = async (
             cwd: argv.cwd,
             engine: argv.engine,
             exclude: argv.exclude,
-            excludeTags: argv['exclude-tags'],
+            excludeTags: argv['exclude-tag'],
             iterations: argv.iterations,
             json: argv.json,
             noColor: argv.noColor,
             outputDir: argv.output,
+            outputFile: argv['output-file'],
             pattern: argv.pattern,
             progress: argv.progress,
             quiet: argv.quiet,
-            reporters: argv.reporters,
-            tags: argv.tags,
+            reporters: argv.reporter,
+            tags: argv.tag,
             time: argv.time,
             timeout: argv.timeout,
             verbose: argv.verbose,
@@ -314,111 +325,541 @@ 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) =>
+        yargs
+          .command(
+            'list',
+            'List recent benchmark runs',
+            (yargs) =>
+              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('tag', {
+                  alias: 't',
+                  array: true,
+                  description: 'Filter by tags (comma-separated)',
+                  type: 'string',
+                })
+                .option('limit', {
+                  defaultDescription: '10',
+                  description: 'Maximum number of results',
+                  type: 'number',
+                })
+                .option('format', {
+                  choices: ['human', 'json', 'csv'] as const,
+                  defaultDescription: '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,
+                since: argv.since,
+                tags: argv.tag,
+                until: argv.until,
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'show <run-id>',
+            'Show detailed results for a specific run',
+            (yargs) =>
+              yargs
+                .positional('run-id', {
+                  demandOption: true,
+                  describe: 'ID of the benchmark run to show',
+                  type: 'string',
+                })
+                .option('format', {
+                  choices: ['human', 'json', 'csv'] as const,
+                  defaultDescription: '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,
+                runId: argv['run-id'],
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'compare <run-id1> <run-id2>',
+            'Compare two benchmark runs',
+            (yargs) =>
+              yargs
+                .positional('run-id1', {
+                  demandOption: true,
+                  describe: 'ID of the first benchmark run',
+                  type: 'string',
+                })
+                .positional('run-id2', {
+                  demandOption: true,
+                  describe: 'ID of the second benchmark run',
+                  type: 'string',
+                })
+                .option('format', {
+                  choices: ['human', 'json'] as const,
+                  defaultDescription: '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,
+                runId1: argv['run-id1'],
+                runId2: argv['run-id2'],
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'trends [pattern]',
+            'Show performance trends over time',
+            (yargs) =>
+              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('tag', {
+                  alias: 't',
+                  array: true,
+                  description: 'Filter by tags (comma-separated)',
+                  type: 'string',
+                })
+                .option('limit', {
+                  description: 'Maximum number of runs to analyze',
+                  type: 'number',
+                })
+                .option('all', {
+                  alias: 'a',
+                  defaultDescription: 'false',
+                  description: 'Analyze all runs (ignore limit)',
+                  type: 'boolean',
+                })
+                .option('format', {
+                  choices: ['human', 'json'] as const,
+                  defaultDescription: '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: argv.all,
+                cwd: argv.cwd,
+                format: argv.format,
+                limit: argv.limit,
+                pattern: argv.pattern,
+                since: argv.since,
+                tags: argv.tag,
+                until: argv.until,
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'clean',
+            'Clean up old benchmark history',
+            (yargs) =>
+              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('yes', {
+                  alias: 'y',
+                  description: 'Confirm cleanup without prompting',
+                  type: 'boolean',
+                })
+                .option('quiet', {
+                  default: false,
+                  description: 'Minimal output',
+                  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 --yes',
+                    '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.yes,
+                cwd: argv.cwd,
+                maxAge: argv['max-age'],
+                maxRuns: argv['max-runs'],
+                maxSize: argv['max-size'],
+                quiet: argv.quiet,
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'export',
+            'Export benchmark history to a file',
+            (yargs) =>
+              yargs
+                .option('format', {
+                  choices: ['json', 'csv'] as const,
+                  defaultDescription: '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.exitCode = 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('baseline', 'Manage performance baselines', (yargs) => {
+        return yargs
+          .command(
+            'set <name>',
+            'Save a benchmark run as a baseline',
+            (yargs) => {
+              return yargs
+                .positional('name', {
+                  describe: 'Name for the baseline',
+                  type: 'string',
+                })
+                .option('run-id', {
+                  description: 'Specific run ID to save (default: most recent)',
+                  type: 'string',
+                })
+                .option('commit', {
+                  description: 'Git commit SHA (40 characters)',
+                  type: 'string',
+                })
+                .option('branch', {
+                  description: 'Git branch name',
+                  type: 'string',
+                })
+                .option('default', {
+                  defaultDescription: 'false',
+                  description: 'Set as default baseline',
+                  type: 'boolean',
+                })
+                .example([
+                  [
+                    '$0 baseline set production-v1.0',
+                    'Save most recent run as baseline',
+                  ],
+                  ['$0 baseline set v1.0 --default', 'Save and set as default'],
+                  [
+                    '$0 baseline set v1.0 --commit abc123...',
+                    'Save with commit info',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleBaselineSetCommand(context, {
+                branch: argv.branch,
+                commit: argv.commit,
+                cwd: argv.cwd,
+                default: argv.default,
+                name: String(argv.name),
+                quiet: Boolean(argv.quiet),
+                runId: argv['run-id'],
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'list',
+            'List all saved baselines',
+            (yargs) => {
+              return yargs
+                .option('format', {
+                  choices: ['human', 'json'] as const,
+                  defaultDescription: 'human' as const,
+                  description: 'Output format',
+                  type: 'string',
+                })
+                .example([
+                  ['$0 baseline list', 'List all baselines'],
+                  ['$0 baseline list --format json', 'List in JSON format'],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleBaselineListCommand(context, {
+                cwd: argv.cwd,
+                format: argv.format,
+                quiet: Boolean(argv.quiet),
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'show <name>',
+            'Show baseline details',
+            (yargs) => {
+              return yargs
+                .positional('name', {
+                  describe: 'Baseline name to show',
+                  type: 'string',
+                })
+                .option('format', {
+                  choices: ['human', 'json'] as const,
+                  defaultDescription: 'human' as const,
+                  description: 'Output format',
+                  type: 'string',
+                })
+                .example([
+                  ['$0 baseline show production-v1.0', 'Show baseline details'],
+                  [
+                    '$0 baseline show v1.0 --format json',
+                    'Show in JSON format',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleBaselineShowCommand(context, {
+                cwd: argv.cwd,
+                format: argv.format,
+                name: String(argv.name),
+                quiet: Boolean(argv.quiet),
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'delete <name>',
+            'Delete a baseline',
+            (yargs) => {
+              return yargs
+                .positional('name', {
+                  describe: 'Baseline name to delete',
+                  type: 'string',
+                })
+                .example([
+                  ['$0 baseline delete old-baseline', 'Delete a baseline'],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleBaselineDeleteCommand(context, {
+                cwd: argv.cwd,
+                name: String(argv.name),
+                quiet: Boolean(argv.quiet),
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .command(
+            'analyze',
+            'Analyze history and suggest performance budgets',
+            (yargs) => {
+              return yargs
+                .option('runs', {
+                  defaultDescription: '10',
+                  description: 'Number of recent runs to analyze',
+                  type: 'number',
+                })
+                .option('confidence', {
+                  defaultDescription: '0.95',
+                  description: 'Confidence level (0.5-0.999, default 0.95)',
+                  type: 'number',
+                })
+                .example([
+                  [
+                    '$0 baseline analyze',
+                    'Analyze last 10 runs with 95% confidence',
+                  ],
+                  ['$0 baseline analyze --runs 20', 'Analyze last 20 runs'],
+                  [
+                    '$0 baseline analyze --confidence 0.90',
+                    'Use 90% confidence level',
+                  ],
+                ]);
+            },
+            async (argv) => {
+              const context = await createCliContext(argv, abortController!);
+              const exitCode = await handleBaselineAnalyzeCommand(context, {
+                confidence: argv.confidence,
+                cwd: argv.cwd,
+                quiet: Boolean(argv.quiet),
+                runs: argv.runs,
+                verbose: argv.verbose,
+              });
+              process.exit(exitCode);
+            },
+          )
+          .demandCommand(1, 'You must specify a baseline subcommand')
+          .strict()
+          .example([
+            ['$0 baseline set production-v1.0', 'Save current run as baseline'],
+            ['$0 baseline list', 'List all baselines'],
+            ['$0 baseline show production-v1.0', 'Show baseline details'],
+            ['$0 baseline delete old-baseline', 'Delete a baseline'],
+            ['$0 baseline analyze', 'Suggest budgets from history'],
+          ]);
+      })
       .command(
         'init [type]',
         'Initialize a new benchmark project',
@@ -426,35 +867,35 @@ export const main = async (
           return yargs
             .positional('type', {
               choices: ['basic', 'advanced', 'library'] as const,
-              default: 'basic' as const,
+              defaultDescription: 'basic' as const,
               describe: 'Type of project to initialize',
               type: 'string',
             })
             .option('examples', {
-              default: true,
+              defaultDescription: 'true',
               description: 'Include example benchmark files',
               type: 'boolean',
             })
             .option('config-type', {
               choices: ['json', 'yaml', 'js', 'ts'] as const,
-              default: 'json' as const,
+              defaultDescription: 'json' as const,
               description: 'Configuration file format',
               type: 'string',
             })
             .option('force', {
-              default: false,
+              defaultDescription: 'false',
               description: 'Overwrite existing files',
               type: 'boolean',
             })
             .option('yes', {
               alias: 'y',
-              default: false,
+              defaultDescription: 'false',
               description: 'Accept all prompts automatically',
               type: 'boolean',
             })
             .option('quiet', {
               alias: 'q',
-              default: false,
+              defaultDescription: 'false',
               description: 'Minimal output',
               type: 'boolean',
             })
@@ -477,24 +918,87 @@ export const main = async (
             cwd: argv.cwd,
             examples: argv.examples,
             force: argv.force,
-            quiet: Boolean(argv.quiet),
+            quiet: argv.quiet,
             type: argv.type,
             verbose: argv.verbose,
             yes: argv.yes,
           });
-          process.exit(exitCode);
+          process.exitCode = exitCode;
+        },
+      )
+      .command(
+        ['analyze [command]', 'profile [command]'],
+        'Analyze code execution and identify benchmark candidates',
+        (yargs) => {
+          return yargs
+            .positional('command', {
+              description: 'Command to analyze (e.g., "npm test")',
+              type: 'string',
+            })
+            .option('input', {
+              alias: 'i',
+              description: 'Path to existing *.cpuprofile file',
+              type: 'string',
+            })
+            .option('filter-file', {
+              description: 'Filter functions by file glob pattern',
+              type: 'string',
+            })
+            .option('min-percent', {
+              alias: ['m', 'min'],
+              default: 0.5,
+              description: 'Minimum execution percentage to show',
+              type: 'number',
+            })
+            .option('top', {
+              alias: 'n',
+              default: 25,
+              description: 'Number of top functions to show',
+              type: 'number',
+            })
+            .option('group-by-file', {
+              default: false,
+              description: 'Group results by file',
+              type: 'boolean',
+            })
+            .check((argv) => {
+              if (!argv.command && !argv.input) {
+                throw new Error('Either [command] or --input must be provided');
+              }
+              return true;
+            });
+        },
+        async (argv) => {
+          // Context not needed for analyze command currently
+          const context = {} as CliContext;
+
+          const options: AnalyzeOptions = {
+            color: !argv.noColor,
+            command: argv.command,
+            cwd: argv.cwd || process.cwd(),
+            filterFile: argv.filterFile,
+            groupByFile: argv.groupByFile,
+            input: argv.input,
+            minPercent: argv.minPercent,
+            top: argv.top,
+          };
+
+          process.exitCode = await analyzeCommand(context, options);
         },
       )
-      .fail((msg: string, err: Error, yargsInstance: Argv) => {
+      .fail((msg, err, yargs) => {
         if (err) {
           console.error('Error:', err.message);
           if (process.env.DEBUG) {
             console.error(err.stack);
           }
           // Show help for file discovery errors (similar to usage errors)
-          if (err.name === 'FileDiscoveryError') {
+          if (
+            isModestBenchError(err) &&
+            err.code === ErrorCodes.FILE_DISCOVERY_FAILED
+          ) {
             console.error();
-            yargsInstance.showHelp();
+            yargs.showHelp();
             process.exit(ExitCodes.DISCOVERY_ERROR);
           }
           process.exit(ExitCodes.RUNTIME_ERROR);
@@ -502,7 +1006,7 @@ export const main = async (
           // Show help for usage errors (unknown arguments, etc.)
           console.error(msg);
           console.error();
-          yargsInstance.showHelp();
+          yargs.showHelp();
           process.exit(ExitCodes.CONFIG_ERROR);
         }
       })
@@ -525,20 +1029,20 @@ export const main = async (
 const createCliContext = async (
   options: GlobalOptions,
   abortController: AbortController,
-  engineType: 'accurate' | 'tinybench' = 'tinybench',
+  engineType: Engine = DEFAULT_ENGINE,
 ): Promise<CliContext> => {
   try {
     const dependencies = bootstrap();
 
     // Select engine based on type
     const engine =
-      engineType === 'accurate'
+      engineType === Engines.ACCURATE
         ? new AccurateEngine(dependencies)
         : new TinybenchEngine(dependencies);
 
     // Register built-in reporters
     engine.registerReporter(
-      'human',
+      Reporters.HUMAN,
       new HumanReporter({
         color: !options.noColor,
         verbose: options.verbose,
@@ -591,7 +1095,7 @@ const createCliContext = async (
 const setupSignalHandlers = (abortController: AbortController): void => {
   let abortRequested = false;
 
-  const handleSignal = (signal: string) => {
+  const handleSignal = (signal: NodeJS.Signals) => {
     if (abortRequested) {
       // Second signal, force exit
       console.log(`\nReceived ${signal} again, forcing exit...`);
@@ -606,36 +1110,29 @@ const setupSignalHandlers = (abortController: AbortController): void => {
     setTimeout(() => {
       console.log('\nBenchmark aborted.');
       process.exit(computeExitCode(signal));
-    }, 100);
+    }, ABORT_TIMEOUT);
   };
 
-  process.on('SIGINT', () => handleSignal('SIGINT'));
-  process.on('SIGQUIT', () => handleSignal('SIGQUIT'));
-  process.on('SIGTERM', () => handleSignal('SIGTERM'));
-
-  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.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);
-  });
+  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 = new UnknownError(
+        isError(reason) ? reason.message : String(reason),
+        { cause: reason },
+      );
+      console.error(`${wrappedError}`);
+      process.exit(ExitCodes.RUNTIME_ERROR);
+    });
 };
 
 // Run CLI if this file is executed directly
@@ -663,6 +1160,6 @@ try {
  * @param signal - The signal that caused the exit
  * @returns The exit code
  */
-const computeExitCode = (signal: string): number => {
+const computeExitCode = (signal: NodeJS.Signals): number => {
   return 128 + (signal === 'SIGINT' ? 2 : signal === 'SIGQUIT' ? 3 : 15);
 };