modestbench 0.2.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,6 +41,17 @@ import {
   SimpleReporter,
 } from '../reporters/index.js';
 // Import commands
+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,
@@ -41,7 +61,10 @@ import {
   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
@@ -63,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
  */
@@ -110,6 +120,7 @@ export const main = async (
     const cli = yargs(args);
 
     // Configure global options and commands
+
     await cli
       .scriptName('modestbench')
       .option('config', {
@@ -120,34 +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()
@@ -155,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',
@@ -176,20 +187,13 @@ 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',
@@ -197,7 +201,7 @@ export const main = async (
               type: 'string',
             })
             .option('output-file', {
-              alias: 'of',
+              alias: ['of', 'file'],
               description:
                 'Custom filename for reporter output (use with single reporter only)',
               requiresArg: true,
@@ -214,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)',
@@ -226,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',
@@ -249,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',
@@ -294,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,
@@ -312,7 +306,7 @@ 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,
@@ -321,8 +315,8 @@ export const main = async (
             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,
@@ -331,13 +325,13 @@ export const main = async (
           process.exit(exitCode);
         },
       )
-      .command('history', 'View and manage benchmark history', (yargs) => {
-        return yargs
+      .command('history', 'View and manage benchmark history', (yargs) =>
+        yargs
           .command(
             'list',
             'List recent benchmark runs',
-            (yargs) => {
-              return yargs
+            (yargs) =>
+              yargs
                 .option('since', {
                   description:
                     'Show runs since date (ISO 8601 or relative like "1 week ago")',
@@ -352,18 +346,20 @@ export const main = async (
                   description: 'Filter by benchmark name pattern',
                   type: 'string',
                 })
-                .option('tags', {
+                .option('tag', {
+                  alias: 't',
+                  array: true,
                   description: 'Filter by tags (comma-separated)',
-                  type: 'array',
+                  type: 'string',
                 })
                 .option('limit', {
-                  default: 10,
+                  defaultDescription: '10',
                   description: 'Maximum number of results',
                   type: 'number',
                 })
                 .option('format', {
                   choices: ['human', 'json', 'csv'] as const,
-                  default: 'human' as const,
+                  defaultDescription: 'human' as const,
                   description: 'Output format',
                   type: 'string',
                 })
@@ -375,8 +371,7 @@ export const main = async (
                   ],
                   ['$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, {
@@ -384,9 +379,8 @@ export const main = async (
                 format: argv.format,
                 limit: argv.limit,
                 pattern: argv.pattern,
-                quiet: Boolean(argv.quiet),
                 since: argv.since,
-                tags: argv.tags as string[] | undefined,
+                tags: argv.tag,
                 until: argv.until,
                 verbose: argv.verbose,
               });
@@ -396,15 +390,16 @@ export const main = async (
           .command(
             'show <run-id>',
             'Show detailed results for a specific run',
-            (yargs) => {
-              return yargs
+            (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,
-                  default: 'human' as const,
+                  defaultDescription: 'human' as const,
                   description: 'Output format',
                   type: 'string',
                 })
@@ -417,15 +412,13 @@ export const main = async (
                     '$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']),
+                runId: argv['run-id'],
                 verbose: argv.verbose,
               });
               process.exit(exitCode);
@@ -434,19 +427,21 @@ export const main = async (
           .command(
             'compare <run-id1> <run-id2>',
             'Compare two benchmark runs',
-            (yargs) => {
-              return yargs
+            (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,
-                  default: 'human' as const,
+                  defaultDescription: 'human' as const,
                   description: 'Output format',
                   type: 'string',
                 })
@@ -456,16 +451,14 @@ export const main = async (
                     '$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']),
+                runId1: argv['run-id1'],
+                runId2: argv['run-id2'],
                 verbose: argv.verbose,
               });
               process.exit(exitCode);
@@ -474,8 +467,8 @@ export const main = async (
           .command(
             'trends [pattern]',
             'Show performance trends over time',
-            (yargs) => {
-              return yargs
+            (yargs) =>
+              yargs
                 .positional('pattern', {
                   describe: 'Filter by benchmark name pattern',
                   type: 'string',
@@ -490,9 +483,11 @@ export const main = async (
                     'Show trends until date (ISO 8601 or relative like "1 day ago")',
                   type: 'string',
                 })
-                .option('tags', {
+                .option('tag', {
+                  alias: 't',
+                  array: true,
                   description: 'Filter by tags (comma-separated)',
-                  type: 'array',
+                  type: 'string',
                 })
                 .option('limit', {
                   description: 'Maximum number of runs to analyze',
@@ -500,13 +495,13 @@ export const main = async (
                 })
                 .option('all', {
                   alias: 'a',
-                  default: false,
+                  defaultDescription: 'false',
                   description: 'Analyze all runs (ignore limit)',
                   type: 'boolean',
                 })
                 .option('format', {
                   choices: ['human', 'json'] as const,
-                  default: 'human' as const,
+                  defaultDescription: 'human' as const,
                   description: 'Output format',
                   type: 'string',
                 })
@@ -527,19 +522,17 @@ export const main = async (
                     '$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),
+                all: 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,
+                tags: argv.tag,
                 until: argv.until,
                 verbose: argv.verbose,
               });
@@ -549,8 +542,8 @@ export const main = async (
           .command(
             'clean',
             'Clean up old benchmark history',
-            (yargs) => {
-              return yargs
+            (yargs) =>
+              yargs
                 .option('max-age', {
                   description: 'Remove runs older than this many days',
                   type: 'number',
@@ -563,11 +556,16 @@ export const main = async (
                   description: 'Keep history under this size in bytes',
                   type: 'number',
                 })
-                .option('confirm', {
-                  default: false,
+                .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'] &&
@@ -582,7 +580,7 @@ export const main = async (
                 })
                 .example([
                   [
-                    '$0 history clean --max-runs 50 --confirm',
+                    '$0 history clean --max-runs 50 --yes',
                     'Keep only latest 50 runs',
                   ],
                   [
@@ -593,17 +591,16 @@ export const main = async (
                     '$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,
+                confirm: argv.yes,
                 cwd: argv.cwd,
                 maxAge: argv['max-age'],
                 maxRuns: argv['max-runs'],
                 maxSize: argv['max-size'],
-                quiet: Boolean(argv.quiet),
+                quiet: argv.quiet,
                 verbose: argv.verbose,
               });
               process.exit(exitCode);
@@ -612,11 +609,11 @@ export const main = async (
           .command(
             'export',
             'Export benchmark history to a file',
-            (yargs) => {
-              return yargs
+            (yargs) =>
+              yargs
                 .option('format', {
                   choices: ['json', 'csv'] as const,
-                  default: 'json' as const,
+                  defaultDescription: 'json' as const,
                   description: 'Export format',
                   type: 'string',
                 })
@@ -647,8 +644,7 @@ export const main = async (
                     '$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, {
@@ -660,7 +656,7 @@ export const main = async (
                 until: argv.until,
                 verbose: argv.verbose,
               });
-              process.exit(exitCode);
+              process.exitCode = exitCode;
             },
           )
           .demandCommand(1, 'You must specify a history subcommand')
@@ -672,6 +668,196 @@ export const main = async (
             ['$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(
@@ -681,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',
             })
@@ -732,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;
         },
       )
-      .fail((msg: string, err: Error, yargsInstance: Argv) => {
+      .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, 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);
@@ -757,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);
         }
       })
@@ -780,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,
@@ -846,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...`);
@@ -861,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
@@ -918,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);
 };