modestbench 0.1.0 → 0.3.0

package/src/{reporters/registry.ts → services/reporter-registry.ts}

@@ -33,74 +33,10 @@ export abstract class BaseReporter implements Reporter {
     this.options = options;
   }
 
-  /**
-   * Get reporter name
-   */
-  getName(): string {
-    return this.name;
-  }
-
-  /**
-   * Get reporter options
-   */
-  getOptions(): Record<string, unknown> {
-    return { ...this.options };
-  }
-
-  /**
-   * Called when benchmark run completes
-   */
-  abstract onEnd(run: BenchmarkRun): Promise<void> | void;
-
-  /**
-   * Called when an error occurs
-   */
-  abstract onError(error: Error): Promise<void> | void;
-
-  /**
-   * Called when a file completes
-   */
-  abstract onFileEnd(result: FileResult): Promise<void> | void;
-
-  /**
-   * Called when a file starts execution
-   */
-  abstract onFileStart(file: string): Promise<void> | void;
-
-  /**
-   * Called for progress updates
-   */
-  abstract onProgress(state: ProgressState): Promise<void> | void;
-
-  /**
-   * Called when benchmark run starts
-   */
-  abstract onStart(run: BenchmarkRun): Promise<void> | void;
-
-  /**
-   * Called when a suite completes
-   */
-  abstract onSuiteEnd(result: SuiteResult): Promise<void> | void;
-
-  /**
-   * Called when a suite starts execution
-   */
-  abstract onSuiteStart(suite: string): Promise<void> | void;
-
-  /**
-   * Called when a task completes
-   */
-  abstract onTaskResult(result: TaskResult): Promise<void> | void;
-
-  /**
-   * Called when a task starts execution
-   */
-  abstract onTaskStart(task: string): Promise<void> | void;
-
   /**
    * Utility method to format duration in human-readable format
    */
-  protected formatDuration(nanoseconds: number): string {
+  protected static formatDuration(this: void, nanoseconds: number): string {
     if (nanoseconds < 1000) {
       return `${nanoseconds.toFixed(2)}ns`;
     } else if (nanoseconds < 1000000) {
@@ -115,7 +51,10 @@ export abstract class BaseReporter implements Reporter {
   /**
    * Utility method to format operations per second
    */
-  protected formatOpsPerSecond(opsPerSecond: number): string {
+  protected static formatOpsPerSecond(
+    this: void,
+    opsPerSecond: number,
+  ): string {
     if (opsPerSecond < 1000) {
       return `${opsPerSecond.toFixed(2)} ops/sec`;
     } else if (opsPerSecond < 1000000) {
@@ -130,23 +69,43 @@ export abstract class BaseReporter implements Reporter {
   /**
    * Utility method to format percentage
    */
-  protected formatPercentage(value: number): string {
+  protected static formatPercentage(this: void, value: number): string {
     return `${value.toFixed(2)}%`;
   }
 
   /**
-   * Utility method to safely handle async operations
+   * Get reporter name
    */
-  protected async safeAsync<T>(operation: () => Promise<T>): Promise<null | T> {
-    try {
-      return await operation();
-    } catch (error) {
-      await this.onError(
-        error instanceof Error ? error : new Error(String(error)),
-      );
-      return null;
-    }
+  getName(): string {
+    return this.name;
+  }
+
+  /**
+   * Get reporter options
+   */
+  getOptions(): Record<string, unknown> {
+    return { ...this.options };
   }
+
+  /**
+   * Called when benchmark run completes
+   */
+  abstract onEnd(run: BenchmarkRun): Promise<void> | void;
+
+  /**
+   * Called when an error occurs
+   */
+  abstract onError(error: Error): Promise<void> | void;
+
+  /**
+   * Called when benchmark run starts
+   */
+  abstract onStart(run: BenchmarkRun): Promise<void> | void;
+
+  /**
+   * Called when a task completes
+   */
+  abstract onTaskResult(result: TaskResult): Promise<void> | void;
 }
 
 /**
@@ -162,6 +121,8 @@ export class CompositeReporter extends BaseReporter {
 
   /**
    * Add a reporter to the composite
+   *
+   * Intended for programmatic usage.
    */
   addReporter(reporter: Reporter): void {
     this.reporters.push(reporter);
@@ -169,16 +130,18 @@ export class CompositeReporter extends BaseReporter {
 
   /**
    * Get all reporters in the composite
+   *
+   * Intended for programmatic usage.
    */
   getReporters(): Reporter[] {
     return [...this.reporters];
   }
 
-  async onEnd(run: BenchmarkRun): Promise<void> {
+  override async onEnd(run: BenchmarkRun): Promise<void> {
     await this.broadcastAsync('onEnd', run);
   }
 
-  async onError(error: Error): Promise<void> {
+  override async onError(error: Error): Promise<void> {
     await this.broadcastAsync('onError', error);
   }
 
@@ -194,7 +157,7 @@ export class CompositeReporter extends BaseReporter {
     await this.broadcastAsync('onProgress', state);
   }
 
-  async onStart(run: BenchmarkRun): Promise<void> {
+  override async onStart(run: BenchmarkRun): Promise<void> {
     await this.broadcastAsync('onStart', run);
   }
 
@@ -206,7 +169,7 @@ export class CompositeReporter extends BaseReporter {
     await this.broadcastAsync('onSuiteStart', suite);
   }
 
-  async onTaskResult(result: TaskResult): Promise<void> {
+  override async onTaskResult(result: TaskResult): Promise<void> {
     await this.broadcastAsync('onTaskResult', result);
   }
 
@@ -216,6 +179,8 @@ export class CompositeReporter extends BaseReporter {
 
   /**
    * Remove a reporter from the composite
+   *
+   * Intended for programmatic usage.
    */
   removeReporter(reporter: Reporter): boolean {
     const index = this.reporters.indexOf(reporter);

package/src/types/budgets.ts

@@ -0,0 +1,180 @@
+/**
+ * Performance budget types for benchmark thresholds
+ *
+ * @module types/budgets
+ */
+
+/**
+ * Absolute performance budgets (time-based)
+ */
+export interface AbsoluteBudget {
+  /** Maximum 99th percentile in nanoseconds */
+  readonly maxP99?: number;
+
+  /** Maximum mean execution time in nanoseconds */
+  readonly maxTime?: number;
+
+  /** Minimum operations per second */
+  readonly minOpsPerSec?: number;
+}
+
+/**
+ * Named baseline reference
+ */
+export interface BaselineReference {
+  /** Git branch (if available) */
+  readonly branch?: string;
+
+  /** Git commit (if available) */
+  readonly commit?: string;
+
+  /** Date baseline was created */
+  readonly date: Date;
+
+  /** Baseline name */
+  readonly name: string;
+
+  /** Run ID this baseline points to */
+  readonly runId: RunId;
+
+  /** Summary of benchmark results for quick comparison */
+  readonly summary: Record<TaskId, BaselineSummaryData>;
+}
+
+/**
+ * Baseline storage file format
+ */
+export interface BaselineStorage {
+  /** Named baselines */
+  readonly baselines: Record<string, BaselineReference>;
+
+  /** Default baseline name (optional) */
+  readonly default?: string;
+
+  /** Schema version */
+  readonly version: string;
+}
+
+/**
+ * Baseline summary data for a single task
+ */
+export interface BaselineSummaryData {
+  /** Mean execution time in nanoseconds */
+  readonly mean: number;
+
+  /** Operations per second */
+  readonly opsPerSecond: number;
+
+  /** 99th percentile (if available) */
+  readonly p99?: number;
+}
+
+/**
+ * Complete budget definition
+ */
+export interface Budget {
+  /** Absolute thresholds */
+  readonly absolute?: AbsoluteBudget;
+
+  /** Relative thresholds */
+  readonly relative?: RelativeBudget;
+}
+
+/**
+ * Budget evaluation result for a single task
+ */
+export interface BudgetResult {
+  /** Actual measured values */
+  readonly actual: {
+    readonly mean: number;
+    readonly opsPerSecond: number;
+    readonly p99?: number;
+  };
+
+  /** Baseline values (if relative budget) */
+  readonly baseline?: {
+    readonly mean: number;
+    readonly opsPerSecond: number;
+    readonly p99?: number;
+  };
+
+  /** Budget that was checked */
+  readonly budget: Budget;
+
+  /** Whether budget passed */
+  readonly passed: boolean;
+
+  /** Task identifier (file/suite/task) */
+  readonly taskId: TaskId;
+
+  /** Violations (what thresholds were exceeded) */
+  readonly violations: BudgetViolation[];
+}
+
+/**
+ * Budget evaluation summary for entire run
+ */
+export interface BudgetSummary {
+  /** Number failed */
+  readonly failed: number;
+
+  /** Number passed */
+  readonly passed: number;
+
+  /** Individual results */
+  readonly results: BudgetResult[];
+
+  /** Total budgets checked */
+  readonly total: number;
+}
+
+/**
+ * Specific budget violation
+ */
+export interface BudgetViolation {
+  /** Actual measured value */
+  readonly actual: number;
+
+  /** How much over/under threshold (as decimal, e.g., 0.15 = 15% over) */
+  readonly delta: number;
+
+  /** Human-readable message */
+  readonly message: string;
+
+  /** Expected threshold */
+  readonly threshold: number;
+
+  /** Type of budget that was violated */
+  readonly type: 'maxP99' | 'maxRegression' | 'maxTime' | 'minOpsPerSec';
+}
+
+/**
+ * Relative performance budgets (comparison-based)
+ */
+export interface RelativeBudget {
+  /** Name of baseline to compare against */
+  readonly baseline?: string;
+
+  /** Maximum performance regression as decimal (0.10 = 10%) */
+  readonly maxRegression?: number;
+}
+
+/**
+ * Branded type for benchmark run identifiers
+ *
+ * RunId is a 7-character alphanumeric string that uniquely identifies a
+ * benchmark run. Using a branded type prevents accidental mixing with regular
+ * strings or TaskIds.
+ */
+export type RunId = string & { readonly __brand: 'RunId' };
+
+/**
+ * Branded type for task identifiers
+ *
+ * TaskId follows the format: `{filePath}/{suiteName}/{taskName}` Example:
+ * `benchmarks/array.bench.js/Array Operations/Array.push()`
+ *
+ * Using a branded type prevents accidental mixing with regular strings or
+ * RunIds.
+ */
+export type TaskId = string & { readonly __brand: 'TaskId' };

package/src/types/cli.ts

@@ -5,17 +5,9 @@
  * definitions, argument parsing, and CLI-specific configuration structures.
  */
 
-/**
- * Exit codes used by the CLI
- */
-export const ExitCodes = {
-  ConfigurationError: 2,
-  ExecutionError: 5,
-  FileDiscoveryError: 3,
-  GeneralError: 1,
-  Success: 0,
-  ValidationError: 4,
-} as const;
+import { ExitCodes } from '../constants.js';
+
+export { ExitCodes };
 
 /**
  * CLI argument specification for a command
@@ -39,56 +31,6 @@ export interface ArgumentSpec {
   readonly validate?: (value: unknown) => boolean | string;
 }
 
-/**
- * Base command interface
- */
-export interface CliCommand {
-  /** Command aliases */
-  readonly aliases?: string[];
-  /** Command description */
-  readonly description: string;
-  /** Execute the command */
-  execute(args: CommandArguments): Promise<ExitCode>;
-  /** Command name */
-  readonly name: string;
-}
-
-/**
- * CLI configuration
- */
-export interface CliConfig {
-  /** Available commands */
-  readonly commands: CommandSpec[];
-  /** Application description */
-  readonly description: string;
-  /** Global options */
-  readonly globalOptions: ArgumentSpec[];
-  /** Application name */
-  readonly name: string;
-  /** Application version */
-  readonly version: string;
-}
-
-/**
- * Color theme for CLI output
- */
-export interface ColorTheme {
-  /** Error color */
-  readonly error: string;
-  /** Highlight color */
-  readonly highlight: string;
-  /** Info color */
-  readonly info: string;
-  /** Muted/secondary text color */
-  readonly muted: string;
-  /** Primary color for branding */
-  readonly primary: string;
-  /** Success color */
-  readonly success: string;
-  /** Warning color */
-  readonly warning: string;
-}
-
 /**
  * Parsed command-line arguments
  */
@@ -119,118 +61,9 @@ export interface CommandSpec {
   readonly subcommands?: CommandSpec[];
 }
 
-export type ExitCode = (typeof ExitCodes)[keyof typeof ExitCodes];
-
-/**
- * Global CLI options available to all commands
- */
-export interface GlobalOptions {
-  readonly c?: string;
-  /** Configuration file */
-  readonly config?: string;
-  /** Working directory */
-  readonly cwd?: string;
-  readonly h?: boolean;
-  /** Help flag */
-  readonly help?: boolean;
-  /** Log level */
-  readonly logLevel?: 'debug' | 'error' | 'info' | 'silent' | 'warn';
-  /** No color output */
-  readonly noColor?: boolean;
-  /** Version flag */
-  readonly version?: boolean;
-}
-
-/**
- * CLI help information
- */
-export interface HelpInfo {
-  /** Command name */
-  readonly command: string;
-  /** Command description */
-  readonly description: string;
-  /** Examples */
-  readonly examples?: string[];
-  /** Available options */
-  readonly options: Array<{
-    readonly default?: string;
-    readonly description: string;
-    readonly flags: string;
-  }>;
-  /** Available subcommands */
-  readonly subcommands?: Array<{
-    readonly description: string;
-    readonly name: string;
-  }>;
-  /** Usage string */
-  readonly usage: string;
-}
-
-/**
- * Arguments for the history command
- */
-export interface HistoryCommandArgs extends CommandArguments {
-  readonly f?: 'csv' | 'json' | 'table';
-  /** Output format */
-  readonly format?: 'csv' | 'json' | 'table';
-  readonly l?: number;
-  /** Limit number of results */
-  readonly limit?: number;
-  /** Pattern to match */
-  readonly pattern?: string;
-  /** Run IDs for show/compare commands */
-  readonly runIds?: string[];
-  /** Filter by date */
-  readonly since?: string;
-  /** History subcommand */
-  readonly subcommand?: 'clean' | 'compare' | 'list' | 'show' | 'trends';
-  /** Tags to filter by */
-  readonly tags?: string | string[];
-}
-
-/**
- * Arguments for the init command
- */
-export interface InitCommandArgs extends CommandArguments {
-  /** Configuration file type */
-  readonly configType?: 'js' | 'json' | 'ts' | 'yaml';
-  /** Create example files */
-  readonly examples?: boolean;
-  /** Force overwrite existing files */
-  readonly force?: boolean;
-}
-
-/**
- * Output formatting options
- */
-export interface OutputFormat {
-  /** Compact output mode */
-  readonly compact: boolean;
-  /** Progress display options */
-  readonly progress: ProgressDisplayOptions;
-  /** Color theme */
-  readonly theme: ColorTheme;
-  /** Use colors in output */
-  readonly useColors: boolean;
-  /** Use Unicode symbols */
-  readonly useUnicode: boolean;
-}
+export type Engine = 'accurate' | 'tinybench';
 
-/**
- * CLI parser result
- */
-export interface ParseResult {
-  /** Parsed arguments */
-  readonly args: CommandArguments;
-  /** Parsed command name */
-  readonly command: string;
-  /** Parsing errors */
-  readonly errors: string[];
-  /** Whether help was requested */
-  readonly help: boolean;
-  /** Whether version was requested */
-  readonly version: boolean;
-}
+export type ExitCode = (typeof ExitCodes)[keyof typeof ExitCodes];
 
 /**
  * Progress display options
@@ -247,66 +80,3 @@ export interface ProgressDisplayOptions {
   /** Update interval in milliseconds */
   readonly updateInterval: number;
 }
-
-/**
- * Arguments for the run command
- */
-export interface RunCommandArgs extends CommandArguments {
-  /** Stop on first failure */
-  readonly bail?: boolean;
-  readonly c?: string;
-  /** Configuration file path */
-  readonly config?: string;
-  readonly e?: 'accurate' | 'tinybench';
-  /** Benchmark engine to use */
-  readonly engine?: 'accurate' | 'tinybench';
-  /** Files to exclude */
-  readonly exclude?: string | string[];
-  /** Tags to exclude */
-  readonly excludeTags?: string | string[];
-  readonly i?: number;
-  /** Number of iterations */
-  readonly iterations?: number;
-  /** How to limit benchmark execution */
-  readonly limitBy?: 'all' | 'any' | 'iterations' | 'time';
-  readonly o?: string;
-  /** Output directory */
-  readonly output?: string;
-  /** Pattern for discovering benchmark files */
-  readonly pattern?: string;
-  readonly q?: boolean;
-  /** Quiet output */
-  readonly quiet?: boolean;
-  readonly r?: string | string[];
-  /** Reporters to use */
-  readonly reporters?: string | string[];
-  readonly t?: number;
-  /** Tags to include */
-  readonly tags?: string | string[];
-  /** Time limit in milliseconds */
-  readonly time?: number;
-  /** Timeout per task */
-  readonly timeout?: number;
-  readonly v?: boolean;
-  /** Verbose output */
-  readonly verbose?: boolean;
-  readonly w?: number;
-  /** Warmup iterations */
-  readonly warmup?: number;
-}
-
-/**
- * Terminal capabilities
- */
-export interface TerminalCapabilities {
-  /** Terminal height in rows */
-  readonly height: number;
-  /** Terminal supports interactive features */
-  readonly interactive: boolean;
-  /** Terminal supports colors */
-  readonly supportsColor: boolean;
-  /** Terminal supports Unicode characters */
-  readonly supportsUnicode: boolean;
-  /** Terminal width in columns */
-  readonly width: number;
-}