modestbench 0.1.0 → 0.2.0

package/src/cli/commands/run.ts

@@ -11,6 +11,7 @@ import type { BenchmarkRun } from '../../types/index.js';
 import type { CliContext } from '../index.js';
 
 import { ErrorCodes } from '../../constants.js';
+import { resolveOutputPath } from '../../core/output-path-resolver.js';
 import {
   InvalidArgumentError,
   type ModestBenchError,
@@ -32,6 +33,7 @@ interface RunOptions {
   json?: boolean | undefined;
   noColor?: boolean | undefined;
   outputDir?: string | undefined;
+  outputFile?: string | undefined;
   pattern: string[];
   progress?: boolean | undefined;
   quiet?: boolean | undefined;
@@ -61,6 +63,18 @@ export const handleRunCommand = async (
   const showCliMessages = verbose && !options.quiet;
 
   try {
+    // Validate --output-file usage
+    if (
+      options.outputFile &&
+      options.reporters &&
+      options.reporters.length > 1
+    ) {
+      throw new InvalidArgumentError(
+        '--output-file can only be used with a single reporter. ' +
+          'Use --output <dir> for multiple reporters.',
+      );
+    }
+
     // Step 1: Load and merge configuration
     if (showCliMessages) {
       console.error('Loading configuration...');
@@ -79,6 +93,7 @@ export const handleRunCommand = async (
       showCliMessages,
       options.quiet ?? false,
       options.outputDir,
+      options.outputFile,
       options.progress,
     );
 
@@ -161,10 +176,13 @@ export const handleRunCommand = async (
 
     return handleResults(executionResult, options, shouldBeQuiet);
   } catch (error) {
-    // Re-throw FileDiscoveryError so yargs fail handler can show help
+    // Re-throw CLI errors so yargs fail handler can show help
     if ((error as ModestBenchError).code === ErrorCodes.FILE_DISCOVERY_FAILED) {
       throw error;
     }
+    if ((error as ModestBenchError).code === ErrorCodes.CLI_INVALID_ARGUMENT) {
+      throw error;
+    }
 
     if (!shouldBeQuiet) {
       console.error(
@@ -298,6 +316,7 @@ const setupReporters = async (
   showCliMessages: boolean,
   explicitQuiet: boolean,
   explicitOutputDir?: string,
+  explicitOutputFile?: string,
   progressOption?: boolean,
 ) => {
   try {
@@ -328,17 +347,27 @@ const setupReporters = async (
           verbose: isVerbose,
         });
       } else if (reporterName === 'json') {
+        const outputPath = resolveOutputPath(
+          outputDir,
+          explicitOutputFile,
+          'results.json',
+        );
         reporter = new JsonReporter({
-          ...(outputDir ? { outputPath: `${outputDir}/results.json` } : {}),
+          ...(outputPath ? { outputPath } : {}),
           prettyPrint: true,
           quiet: shouldBeQuiet, // JSON uses shouldBeQuiet to avoid polluting stdout
           verbose: isVerbose,
         });
       } else if (reporterName === 'csv') {
+        const outputPath = resolveOutputPath(
+          outputDir,
+          explicitOutputFile,
+          'results.csv',
+        );
         reporter = new CsvReporter({
           includeHeaders: true,
           includeMetadata: true,
-          ...(outputDir ? { outputPath: `${outputDir}/results.csv` } : {}),
+          ...(outputPath ? { outputPath } : {}),
           quiet: explicitQuiet, // Only applies explicit --quiet flag; CSV output can coexist with progress messages on different streams
           verbose: isVerbose,
         });

package/src/cli/index.ts

@@ -32,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';
 
@@ -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',

package/src/core/engine.ts

@@ -6,6 +6,8 @@
  * architecture.
  */
 
+import { randomBytes } from 'node:crypto';
+
 import type {
   BenchmarkDefinition,
   BenchmarkEngine,
@@ -697,9 +699,15 @@ export abstract class ModestBenchEngine implements BenchmarkEngine {
 
   /**
    * Generate a unique run ID
+   *
+   * Uses crypto.randomBytes for cryptographically random 7-character IDs.
+   * Format: 7 lowercase alphanumeric characters (e.g., "k3m9x2p")
    */
   private generateRunId(): string {
-    return `run-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+    // Generate random bytes, convert to hex, then to base36, take first 7 chars
+    const hex = randomBytes(4).toString('hex');
+    const num = parseInt(hex, 16);
+    return num.toString(36).padStart(7, '0').substring(0, 7);
   }
 
   /**

package/src/core/output-path-resolver.ts

@@ -0,0 +1,38 @@
+import { isAbsolute, join, resolve } from 'node:path';
+
+/**
+ * Resolves the final output path for a reporter
+ *
+ * @param outputDir - Optional output directory from --output flag
+ * @param outputFile - Optional output filename from --output-file flag
+ * @param defaultFilename - Default filename to use if none specified
+ * @returns Resolved output path, or undefined if no output to file requested
+ */
+export const resolveOutputPath = (
+  outputDir?: string,
+  outputFile?: string,
+  defaultFilename?: string,
+): string | undefined => {
+  // If outputFile is provided
+  if (outputFile) {
+    // If outputFile is absolute, use as-is
+    if (isAbsolute(outputFile)) {
+      return outputFile;
+    }
+
+    // If outputDir specified, join them
+    if (outputDir) {
+      return join(outputDir, outputFile);
+    }
+
+    // Otherwise, resolve relative to cwd
+    return resolve(process.cwd(), outputFile);
+  }
+
+  // Fall back to default behavior
+  if (outputDir && defaultFilename) {
+    return join(outputDir, defaultFilename);
+  }
+
+  return undefined;
+};