feat: add --output-file CLI option (#66)

Author: boneskull

README.md

@@ -243,6 +243,44 @@ modestbench --tags fast --exclude-tags experimental
 
 See [Tagging and Filtering](#tagging-and-filtering) for detailed examples.
 
+#### Output Options
+
+Control where and how benchmark results are saved:
+
+```bash
+# Write to a directory (creates results.json, results.csv, etc.)
+modestbench --reporters json,csv --output ./results
+
+# Custom filename for single reporter
+modestbench --reporters json --output-file my-benchmarks.json
+
+# Custom filename in specific directory
+modestbench --reporters json --output ./results --output-file benchmarks-2024.json
+
+# Custom filename with absolute path
+modestbench --reporters json --output-file /tmp/my-benchmarks.json
+
+# With subdirectories
+modestbench --reporters csv --output ./results --output-file reports/performance.csv
+
+# Short flag alias
+modestbench --reporters json --of custom.json
+```
+
+**Key Options:**
+
+- `--output <dir>`, `-o <dir>` - Directory to write output files (default: stdout)
+- `--output-file <filename>`, `--of <filename>` - Custom filename for output
+  - Works with absolute or relative paths
+  - Requires exactly one reporter (e.g., `--reporters json`)
+  - When used with `--output`, the filename is relative to that directory
+  - When used alone, the path is relative to current working directory
+
+**Limitations:**
+
+- `--output-file` only works with a single reporter
+- For multiple reporters, use `--output <dir>` (defaults to `results.json`, `results.csv`, etc.)
+
 ### History Management
 
 **modestbench** automatically tracks benchmark results over time in a local `.modestbench/` directory. This history enables you to:

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,
         });

src/cli/index.ts

@@ -196,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',
@@ -310,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,

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;
+};

src/types/cli.ts

@@ -270,8 +270,11 @@ export interface RunCommandArgs extends CommandArguments {
   /** How to limit benchmark execution */
   readonly limitBy?: 'all' | 'any' | 'iterations' | 'time';
   readonly o?: string;
+  readonly of?: string;
   /** Output directory */
   readonly output?: string;
+  /** Custom output filename (works with single reporter only) */
+  readonly outputFile?: string;
   /** Pattern for discovering benchmark files */
   readonly pattern?: string;
   readonly q?: boolean;

test/integration/configuration.test.ts

@@ -340,8 +340,11 @@ export default {
       );
 
       // Should report validation errors
+      expect(result.exitCode, 'to be greater than', 0);
       expect(
-        result.exitCode === 2 || result.stderr.includes('not found'),
+        result.stderr.includes('Configuration validation failed') ||
+          result.stderr.includes('Too small') ||
+          result.stderr.includes('Invalid input'),
         'to be truthy',
       );
     });