modestbench 0.9.1 → 0.9.2

package/src/cli/parsers/analyze.ts

@@ -0,0 +1,61 @@
+/**
+ * Analyze Command Parser
+ *
+ * Parser for the `analyze` command (aliased as `profile`) which profiles code
+ * execution to identify benchmark candidates.
+ *
+ * @packageDocumentation
+ */
+
+import { camelCaseValues, map, merge, opt, pos } from '@boneskull/bargs';
+
+/**
+ * Base parser for `analyze` command options and positionals
+ */
+const analyzeParserBase = merge(
+  opt.options({
+    'filter-file': opt.string({
+      description: 'Filter functions by file glob pattern',
+    }),
+    'group-by-file': opt.boolean({
+      description: 'Group results by file',
+    }),
+    input: opt.string({
+      aliases: ['i'],
+      description: 'Path to existing *.cpuprofile file',
+    }),
+    'min-percent': opt.number({
+      aliases: ['m', 'min'],
+      default: 0.5,
+      description: 'Minimum execution percentage to show',
+    }),
+    top: opt.number({
+      aliases: ['n'],
+      default: 25,
+      description: 'Number of top functions to show',
+    }),
+  }),
+  pos.positionals(
+    pos.string({
+      description: 'Command to analyze (e.g., "npm test")',
+      name: 'command',
+    }),
+  ),
+);
+
+/**
+ * Parser for `analyze` command with validation and camelCase values
+ *
+ * Validates that either a command or --input is provided. Uses camelCaseValues
+ * transform for cleaner property access.
+ */
+export const analyzeParser = map(
+  map(analyzeParserBase, ({ positionals, values }) => {
+    const [command] = positionals;
+    if (!command && !values.input) {
+      throw new Error('Either [command] or --input must be provided');
+    }
+    return { positionals, values };
+  }),
+  camelCaseValues,
+);

package/src/cli/parsers/baseline.ts

@@ -0,0 +1,92 @@
+/**
+ * Baseline Command Parsers
+ *
+ * Parsers for the `baseline` command and its subcommands: set, list, show,
+ * delete, and analyze.
+ *
+ * @packageDocumentation
+ */
+
+import { camelCaseValues, map, merge, opt, pos } from '@boneskull/bargs';
+
+/**
+ * Parser for `baseline set` command
+ *
+ * Uses camelCaseValues transform for cleaner property access.
+ */
+export const baselineSetParser = map(
+  merge(
+    opt.options({
+      branch: opt.string({
+        description: 'Git branch name',
+      }),
+      commit: opt.string({
+        description: 'Git commit SHA (40 characters)',
+      }),
+      default: opt.boolean({
+        description: 'Set as default baseline',
+      }),
+      'run-id': opt.string({
+        description: 'Specific run ID to save (default: most recent)',
+      }),
+    }),
+    pos.positionals(
+      pos.string({
+        description: 'Name for the baseline',
+        name: 'name',
+        required: true,
+      }),
+    ),
+  ),
+  camelCaseValues,
+);
+
+/**
+ * Parser for `baseline list` command
+ */
+export const baselineListParser = opt.options({
+  format: opt.enum(['human', 'json'] as const, {
+    description: 'Output format',
+  }),
+});
+
+/**
+ * Parser for `baseline show` command
+ */
+export const baselineShowParser = merge(
+  opt.options({
+    format: opt.enum(['human', 'json'] as const, {
+      description: 'Output format',
+    }),
+  }),
+  pos.positionals(
+    pos.string({
+      description: 'Baseline name to show',
+      name: 'name',
+      required: true,
+    }),
+  ),
+);
+
+/**
+ * Parser for `baseline delete` command
+ */
+export const baselineDeleteParser = pos.positionals(
+  pos.string({
+    description: 'Baseline name to delete',
+    name: 'name',
+    required: true,
+  }),
+);
+
+/**
+ * Parser for `baseline analyze` command
+ */
+export const baselineAnalyzeParser = opt.options({
+  confidence: opt.number({
+    description: 'Confidence level (0.5-0.999, default 0.95)',
+  }),
+  runs: opt.number({
+    description: 'Number of recent runs to analyze',
+  }),
+});

package/src/cli/parsers/global.ts

@@ -0,0 +1,51 @@
+/**
+ * Global CLI Options
+ *
+ * Options shared across all commands (verbose, config, cwd, etc.) and common
+ * option fragments used by subcommands.
+ *
+ * @packageDocumentation
+ */
+
+import { camelCaseValues, map, opt } from '@boneskull/bargs';
+
+/**
+ * Global options available to all commands
+ *
+ * Uses camelCaseValues transform so handlers can use `values.noColor` instead
+ * of `values['no-color']`.
+ */
+export const globalOptions = map(
+  opt.options({
+    config: opt.string({
+      aliases: ['c'],
+      description: 'Path to configuration file',
+    }),
+    cwd: opt.string({
+      description: 'Working directory',
+    }),
+    json: opt.boolean({
+      description: 'Output results in JSON format',
+    }),
+    'no-color': opt.boolean({
+      description: 'Disable colored output',
+    }),
+    progress: opt.boolean({
+      description: 'Show animated progress bar',
+    }),
+    verbose: opt.boolean({
+      aliases: ['v'],
+      description: 'Enable verbose output',
+    }),
+  }),
+  camelCaseValues,
+);
+
+/**
+ * Additional global options for history and baseline subcommands
+ */
+export const quietOption = opt.options({
+  quiet: opt.boolean({
+    description: 'Minimal output',
+  }),
+});

package/src/cli/parsers/history.ts

@@ -0,0 +1,168 @@
+/**
+ * History Command Parsers
+ *
+ * Parsers for the `history` command and its subcommands: list, show, compare,
+ * trends, clean, and export.
+ *
+ * @packageDocumentation
+ */
+
+import { camelCaseValues, map, merge, opt, pos } from '@boneskull/bargs';
+
+/**
+ * Parser for `history list` command
+ */
+export const historyListParser = opt.options({
+  format: opt.enum(['human', 'json', 'csv'] as const, {
+    description: 'Output format',
+  }),
+  limit: opt.number({
+    description: 'Maximum number of results',
+  }),
+  pattern: opt.string({
+    description: 'Filter by benchmark name pattern',
+  }),
+  since: opt.string({
+    description:
+      'Show runs since date (ISO 8601 or relative like "1 week ago")',
+  }),
+  tag: opt.array('string', {
+    aliases: ['t'],
+    description: 'Filter by tags',
+  }),
+  until: opt.string({
+    description: 'Show runs until date (ISO 8601 or relative like "1 day ago")',
+  }),
+});
+
+/**
+ * Parser for `history show` command
+ */
+export const historyShowParser = merge(
+  opt.options({
+    format: opt.enum(['human', 'json', 'csv'] as const, {
+      description: 'Output format',
+    }),
+  }),
+  pos.positionals(
+    pos.string({
+      description: 'ID of the benchmark run to show',
+      name: 'run-id',
+      required: true,
+    }),
+  ),
+);
+
+/**
+ * Parser for `history compare` command
+ */
+export const historyCompareParser = merge(
+  opt.options({
+    format: opt.enum(['human', 'json'] as const, {
+      description: 'Output format',
+    }),
+  }),
+  pos.positionals(
+    pos.string({
+      description: 'ID of the first benchmark run',
+      name: 'run-id1',
+      required: true,
+    }),
+    pos.string({
+      description: 'ID of the second benchmark run',
+      name: 'run-id2',
+      required: true,
+    }),
+  ),
+);
+
+/**
+ * Parser for `history trends` command
+ */
+export const historyTrendsParser = merge(
+  opt.options({
+    all: opt.boolean({
+      aliases: ['a'],
+      description: 'Analyze all runs (ignore limit)',
+    }),
+    format: opt.enum(['human', 'json'] as const, {
+      description: 'Output format',
+    }),
+    limit: opt.number({
+      description: 'Maximum number of runs to analyze',
+    }),
+    since: opt.string({
+      description:
+        'Show trends since date (ISO 8601 or relative like "1 week ago")',
+    }),
+    tag: opt.array('string', {
+      aliases: ['t'],
+      description: 'Filter by tags',
+    }),
+    until: opt.string({
+      description:
+        'Show trends until date (ISO 8601 or relative like "1 day ago")',
+    }),
+  }),
+  pos.positionals(
+    pos.string({
+      description: 'Filter by benchmark name pattern',
+      name: 'pattern',
+    }),
+  ),
+);
+
+/**
+ * Parser for `history clean` command
+ *
+ * Includes validation requiring at least one cleanup criterion. Uses
+ * camelCaseValues transform for cleaner property access.
+ */
+export const historyCleanParser = map(
+  map(
+    opt.options({
+      'max-age': opt.number({
+        description: 'Remove runs older than this many days',
+      }),
+      'max-runs': opt.number({
+        description: 'Keep only this many most recent runs',
+      }),
+      'max-size': opt.number({
+        description: 'Keep history under this size in bytes',
+      }),
+      yes: opt.boolean({
+        aliases: ['y'],
+        description: 'Confirm cleanup without prompting',
+      }),
+    }),
+    ({ positionals, values }) => {
+      if (!values['max-age'] && !values['max-runs'] && !values['max-size']) {
+        throw new Error(
+          'At least one cleanup criterion must be specified (--max-age, --max-runs, or --max-size)',
+        );
+      }
+      return { positionals, values };
+    },
+  ),
+  camelCaseValues,
+);
+
+/**
+ * Parser for `history export` command
+ */
+export const historyExportParser = opt.options({
+  format: opt.enum(['json', 'csv'] as const, {
+    description: 'Export format',
+  }),
+  output: opt.string({
+    aliases: ['o'],
+    description: 'Output file path',
+    required: true,
+  }),
+  since: opt.string({
+    description: 'Export runs since date',
+  }),
+  until: opt.string({
+    description: 'Export runs until date',
+  }),
+});

package/src/cli/parsers/index.ts

@@ -0,0 +1,28 @@
+/**
+ * CLI Parsers
+ *
+ * Re-exports all bargs parser definitions for CLI commands.
+ *
+ * @packageDocumentation
+ */
+
+export { analyzeParser } from './analyze.js';
+export {
+  baselineAnalyzeParser,
+  baselineDeleteParser,
+  baselineListParser,
+  baselineSetParser,
+  baselineShowParser,
+} from './baseline.js';
+export { globalOptions, quietOption } from './global.js';
+export {
+  historyCleanParser,
+  historyCompareParser,
+  historyExportParser,
+  historyListParser,
+  historyShowParser,
+  historyTrendsParser,
+} from './history.js';
+export { initParser } from './init.js';
+export { runParser } from './run.js';
+export { testParser } from './test.js';

package/src/cli/parsers/init.ts

@@ -0,0 +1,45 @@
+/**
+ * Init Command Parser
+ *
+ * Parser for the `init` command which initializes a new benchmark project.
+ *
+ * @packageDocumentation
+ */
+
+import { camelCaseValues, map, merge, opt, pos } from '@boneskull/bargs';
+
+/**
+ * Parser for `init` command
+ *
+ * Uses camelCaseValues transform for cleaner property access.
+ */
+export const initParser = map(
+  merge(
+    opt.options({
+      'config-type': opt.enum(['json', 'yaml', 'js', 'ts'] as const, {
+        description: 'Configuration file format',
+      }),
+      examples: opt.boolean({
+        description: 'Include example benchmark files',
+      }),
+      force: opt.boolean({
+        description: 'Overwrite existing files',
+      }),
+      quiet: opt.boolean({
+        aliases: ['q'],
+        description: 'Minimal output',
+      }),
+      yes: opt.boolean({
+        aliases: ['y'],
+        description: 'Accept all prompts automatically',
+      }),
+    }),
+    pos.positionals(
+      pos.enum(['basic', 'advanced', 'library'] as const, {
+        description: 'Type of project to initialize',
+        name: 'type',
+      }),
+    ),
+  ),
+  camelCaseValues,
+);

package/src/cli/parsers/run.ts

@@ -0,0 +1,118 @@
+/**
+ * Run Command Parser
+ *
+ * Parser for the `run` command which executes benchmark files.
+ *
+ * @packageDocumentation
+ */
+
+import { camelCaseValues, map, merge, opt, pos } from '@boneskull/bargs';
+
+import { DEFAULT_REPORTER, Engines, Reporters } from '../../constants.js';
+
+/**
+ * Base parser for `run` command options and positionals
+ */
+const runParserBase = merge(
+  opt.options({
+    bail: opt.boolean({
+      aliases: ['b'],
+      description: 'Stop on first failure',
+    }),
+    engine: opt.enum([Engines.TINYBENCH, Engines.ACCURATE] as const, {
+      aliases: ['e'],
+      description:
+        'Benchmark engine: tinybench (default) or accurate (requires --allow-natives-syntax)',
+    }),
+    exclude: opt.array('string', {
+      aliases: ['X'],
+      description: 'Exclude patterns',
+    }),
+    'exclude-tag': opt.array('string', {
+      aliases: ['T'],
+      description: 'Exclude benchmarks with any of these tags',
+    }),
+    iterations: opt.number({
+      aliases: ['i'],
+      description: 'Number of iterations per benchmark',
+    }),
+    'json-pretty': opt.boolean({
+      description: 'Pretty-print JSON output (only affects json reporter)',
+    }),
+    'limit-by': opt.enum(['time', 'iterations', 'any', 'all'] as const, {
+      aliases: ['l', 'limit'],
+      description:
+        'How to limit benchmarks: time (time budget), iterations (sample count), any (either threshold), all (both thresholds)',
+    }),
+    output: opt.string({
+      aliases: ['o'],
+      description: 'Output directory for reports',
+    }),
+    'output-file': opt.string({
+      aliases: ['of', 'file'],
+      description:
+        'Custom filename for reporter output (use with single reporter only)',
+    }),
+    quiet: opt.boolean({
+      aliases: ['q'],
+      description: 'Minimal output',
+    }),
+    reporter: opt.array(
+      [
+        Reporters.HUMAN,
+        Reporters.JSON,
+        Reporters.CSV,
+        Reporters.NYAN,
+        Reporters.SIMPLE,
+      ] as const,
+      {
+        aliases: ['r'],
+        default: [DEFAULT_REPORTER],
+        description: 'Output reporters to use (human,json,csv)',
+      },
+    ),
+    tag: opt.array('string', {
+      description: 'Include only benchmarks with any of these tags',
+    }),
+    time: opt.number({
+      aliases: ['t'],
+      description: 'Time budget per benchmark in milliseconds',
+    }),
+    timeout: opt.number({
+      description: 'Timeout per benchmark in milliseconds',
+    }),
+    warmup: opt.number({
+      aliases: ['w', 'warm'],
+      description: 'Number of warmup iterations',
+    }),
+  }),
+  pos.positionals(
+    pos.variadic('string', {
+      description:
+        'File paths, directory paths, or glob patterns for benchmark files',
+      name: 'pattern',
+    }),
+  ),
+);
+
+/**
+ * Parser for `run` command with validation and camelCase values
+ *
+ * Validates that --output-file is only used with a single reporter. Uses
+ * camelCaseValues transform for cleaner property access.
+ */
+export const runParser = map(
+  map(runParserBase, ({ positionals, values }) => {
+    if (
+      values.reporter &&
+      values.reporter.length > 1 &&
+      values['output-file']
+    ) {
+      throw new Error(
+        '--output-file can only be used with a single reporter. Use --output <dir> for multiple reporters.',
+      );
+    }
+    return { positionals, values };
+  }),
+  camelCaseValues,
+);

package/src/cli/parsers/test.ts

@@ -0,0 +1,46 @@
+/**
+ * Test Command Parser
+ *
+ * Parser for the `test` command which runs test files as benchmarks.
+ *
+ * @packageDocumentation
+ */
+
+import { merge, opt, pos } from '@boneskull/bargs';
+
+/**
+ * Parser for `test` command
+ */
+export const testParser = merge(
+  opt.options({
+    bail: opt.boolean({
+      aliases: ['b'],
+      description: 'Stop on first failure',
+    }),
+    iterations: opt.number({
+      aliases: ['i'],
+      default: 100,
+      description: 'Number of iterations per test',
+    }),
+    quiet: opt.boolean({
+      aliases: ['q'],
+      description: 'Minimal output',
+    }),
+    warmup: opt.number({
+      aliases: ['w'],
+      default: 5,
+      description: 'Number of warmup iterations',
+    }),
+  }),
+  pos.positionals(
+    pos.enum(['ava', 'jest', 'mocha', 'node-test'] as const, {
+      description: 'Test framework to use',
+      name: 'framework',
+      required: true,
+    }),
+    pos.variadic('string', {
+      description: 'Test file paths or glob patterns',
+      name: 'files',
+    }),
+  ),
+);

package/src/cli/theme.ts

@@ -0,0 +1,33 @@
+/**
+ * CLI Theme Configuration
+ *
+ * Synthwave-inspired color theme for bargs help output, matching the retro
+ * aesthetic used throughout modestbench reporters.
+ *
+ * @packageDocumentation
+ */
+
+import { ansi } from '@boneskull/bargs';
+
+/**
+ * Synthwave-inspired theme for CLI help output
+ *
+ * Matches the retro aesthetic used in modestbench reporters
+ */
+export const synthwaveTheme = {
+  colors: {
+    command: ansi.brightMagenta,
+    defaultText: ansi.dim,
+    defaultValue: ansi.brightYellow,
+    description: ansi.brightWhite,
+    epilog: ansi.brightWhite,
+    example: ansi.cyan,
+    flag: ansi.brightCyan,
+    positional: ansi.brightMagenta,
+    scriptName: ansi.brightCyan + ansi.bold,
+    sectionHeader: ansi.magenta + ansi.bold,
+    type: ansi.brightWhite + ansi.dim,
+    url: ansi.brightCyan + ansi.underline,
+    usage: ansi.white,
+  },
+};

package/src/errors/base.ts

@@ -6,6 +6,7 @@
  */
 
 import { SITE_URL } from '../constants.js';
+import { isError } from '../utils/type-guards.js';
 
 /**
  * Base URL for error documentation
@@ -150,13 +151,3 @@ export const isModestBenchError = (
     (error as { code: string }).code.startsWith('ERR_MB_')
   );
 };
-
-/**
- * Type guard to check if an error is a standard Error
- *
- * @param error - The error to check
- * @returns `true` if the error is an `Error`
- */
-export const isError = (error: unknown): error is Error => {
-  return error instanceof Error;
-};

package/src/services/profiler/profile-runner.ts

@@ -26,17 +26,32 @@ interface RunOptions {
   timeout?: number;
 }
 
+/**
+ * Node.js major version number
+ */
+const nodeMajorVersion = Number(process.versions.node.split('.')[0]);
+
 /**
  * Run a command with Node.js profiling enabled
  *
  * @param command - Command to run (e.g., "npm test")
  * @param options - Execution options
  * @returns Path to generated *.cpuprofile file
+ * @throws Error if running on Node.js 20 (--cpu-prof not allowed in
+ *   NODE_OPTIONS)
  */
 export const runWithProfiling = async (
   command: string,
   options: RunOptions = {},
 ): Promise<string> => {
+  // Node.js 20 blocks --cpu-prof in NODE_OPTIONS for security reasons
+  if (nodeMajorVersion === 20) {
+    throw new Error(
+      'CPU profiling requires Node.js 22 or later. ' +
+        'Node.js 20 blocks --cpu-prof in NODE_OPTIONS for security reasons.',
+    );
+  }
+
   const cwd = options.cwd || process.cwd();
 
   // Create profiles directory