modestbench 0.0.1

package/src/reporters/index.ts

@@ -0,0 +1,10 @@
+/**
+ * ModestBench Reporters
+ *
+ * Export all available reporters and registry functionality.
+ */
+
+export { CsvReporter } from './csv.js';
+export { HumanReporter } from './human.js';
+export { JsonReporter } from './json.js';
+export { SimpleReporter } from './simple.js';

package/src/reporters/json.ts

@@ -0,0 +1,302 @@
+/**
+ * ModestBench JSON Reporter
+ *
+ * Outputs benchmark results in structured JSON format. Suitable for machine
+ * processing, CI/CD integration, and data analysis.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import type {
+  BenchmarkRun,
+  FileResult,
+  ProgressState,
+  SuiteResult,
+  TaskResult,
+} from '../types/index.js';
+
+import { BaseReporter } from './registry.js';
+
+/**
+ * JSON output structure for benchmark results
+ */
+interface JsonOutput {
+  /** ModestBench metadata */
+  readonly meta: {
+    readonly format: 'modestbench-json';
+    readonly timestamp: string;
+    readonly version: string;
+  };
+  /** Complete benchmark run data */
+  readonly run: BenchmarkRun;
+  /** Additional computed statistics */
+  statistics?: {
+    averageOpsPerSecond?: number;
+    fastestTask?: TaskResult;
+    slowestTask?: TaskResult;
+    totalIterations?: number;
+  };
+}
+
+/**
+ * JSON reporter for structured output
+ */
+export class JsonReporter extends BaseReporter {
+  private currentRun?: BenchmarkRun;
+
+  private readonly includeMetadata: boolean;
+
+  private readonly includeStatistics: boolean;
+
+  private readonly outputPath?: string | undefined;
+
+  private readonly prettyPrint: boolean;
+
+  private readonly quiet: boolean;
+
+  private statistics: {
+    fastestTask?: TaskResult;
+    slowestTask?: TaskResult;
+    taskCount: number;
+    totalIterations: number;
+    totalOpsPerSecond: number;
+  } = {
+    taskCount: 0,
+    totalIterations: 0,
+    totalOpsPerSecond: 0,
+  };
+
+  constructor(
+    options: {
+      includeMetadata?: boolean;
+      includeStatistics?: boolean;
+      outputPath?: string;
+      prettyPrint?: boolean;
+      quiet?: boolean;
+      verbose?: boolean;
+    } = {},
+  ) {
+    super('json', options);
+
+    this.outputPath = options.outputPath;
+    this.prettyPrint = options.prettyPrint ?? true;
+    this.includeStatistics = options.includeStatistics ?? true;
+    this.includeMetadata = options.includeMetadata ?? true;
+    this.quiet = options.quiet ?? false;
+  }
+
+  /**
+   * Check if statistics are included
+   */
+  areStatisticsIncluded(): boolean {
+    return this.includeStatistics;
+  }
+
+  /**
+   * Get the output path (if configured)
+   */
+  getOutputPath(): string | undefined {
+    return this.outputPath;
+  }
+
+  /**
+   * Check if metadata is included
+   */
+  isMetadataIncluded(): boolean {
+    return this.includeMetadata;
+  }
+
+  /**
+   * Check if pretty printing is enabled
+   */
+  isPrettyPrintEnabled(): boolean {
+    return this.prettyPrint;
+  }
+
+  async onEnd(run: BenchmarkRun): Promise<void> {
+    const output = this.buildJsonOutput(run);
+
+    if (this.outputPath) {
+      await this.writeToFile(output);
+    } else {
+      this.writeToStdout(output);
+    }
+  }
+
+  onError(error: Error): void {
+    // For JSON reporter, we'll include errors in the final output
+    // but we can also log to stderr for immediate feedback
+    console.error('JSON Reporter Error:', error.message);
+  }
+
+  onFileEnd(_result: FileResult): void {
+    // No-op for JSON reporter
+  }
+
+  onFileStart(_file: string): void {
+    // No-op for JSON reporter
+  }
+
+  onProgress(_state: ProgressState): void {
+    // No-op for JSON reporter - we don't output progress in JSON format
+  }
+
+  onStart(run: BenchmarkRun): void {
+    this.currentRun = run;
+    this.resetStatistics();
+  }
+
+  onSuiteEnd(_result: SuiteResult): void {
+    // No-op for JSON reporter
+  }
+
+  onSuiteStart(_suite: string): void {
+    // No-op for JSON reporter
+  }
+
+  onTaskResult(result: TaskResult): void {
+    if (!result.error) {
+      this.updateStatistics(result);
+    }
+  }
+
+  onTaskStart(_task: string): void {
+    // No-op for JSON reporter
+  }
+
+  /**
+   * Build the complete JSON output structure
+   */
+  private buildJsonOutput(run: BenchmarkRun): JsonOutput {
+    const output: JsonOutput = {
+      meta: {
+        format: 'modestbench-json',
+        timestamp: new Date().toISOString(),
+        version: '0.1.0', // TODO: Get from package.json
+      },
+      run: this.includeMetadata ? run : this.sanitizeRun(run),
+    };
+
+    if (this.includeStatistics) {
+      const stats = {
+        averageOpsPerSecond:
+          this.statistics.taskCount > 0
+            ? this.statistics.totalOpsPerSecond / this.statistics.taskCount
+            : 0,
+        totalIterations: this.statistics.totalIterations,
+        ...(this.statistics.fastestTask && {
+          fastestTask: this.statistics.fastestTask,
+        }),
+        ...(this.statistics.slowestTask && {
+          slowestTask: this.statistics.slowestTask,
+        }),
+      };
+
+      output.statistics = stats;
+    }
+
+    return output;
+  }
+
+  /**
+   * Reset statistics tracking
+   */
+  private resetStatistics(): void {
+    this.statistics = {
+      taskCount: 0,
+      totalIterations: 0,
+      totalOpsPerSecond: 0,
+    };
+  }
+
+  /**
+   * Remove potentially sensitive metadata from run data
+   */
+  private sanitizeRun(run: BenchmarkRun): BenchmarkRun {
+    let sanitized = {
+      ...run,
+      environment: {
+        ...run.environment,
+        env: {}, // Remove environment variables
+        hostname: 'redacted', // Remove hostname
+      },
+    } as BenchmarkRun;
+
+    if (run.git) {
+      sanitized = {
+        ...sanitized,
+        git: {
+          ...run.git,
+          author: 'redacted', // Remove author info
+        },
+      };
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Update running statistics with a task result
+   */
+  private updateStatistics(result: TaskResult): void {
+    this.statistics.totalIterations += result.iterations;
+    this.statistics.totalOpsPerSecond += result.opsPerSecond;
+    this.statistics.taskCount++;
+
+    // Track fastest task
+    if (
+      !this.statistics.fastestTask ||
+      result.mean < this.statistics.fastestTask.mean
+    ) {
+      this.statistics.fastestTask = result;
+    }
+
+    // Track slowest task
+    if (
+      !this.statistics.slowestTask ||
+      result.mean > this.statistics.slowestTask.mean
+    ) {
+      this.statistics.slowestTask = result;
+    }
+  }
+
+  /**
+   * Write JSON output to file
+   */
+  private async writeToFile(output: JsonOutput): Promise<void> {
+    if (!this.outputPath) {
+      throw new Error('Output path not specified');
+    }
+
+    try {
+      // Ensure directory exists
+      const dir = dirname(this.outputPath);
+      mkdirSync(dir, { recursive: true });
+
+      // Write JSON file
+      const jsonString = this.prettyPrint
+        ? JSON.stringify(output, null, 2)
+        : JSON.stringify(output);
+
+      writeFileSync(this.outputPath, jsonString, 'utf8');
+    } catch (error) {
+      throw new Error(
+        `Failed to write JSON output to ${this.outputPath}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  /**
+   * Write JSON output to stdout
+   */
+  private writeToStdout(output: JsonOutput): void {
+    // Always write to stdout when no output path is specified
+    // The quiet flag only affects progress messages (stderr), not data output
+    const jsonString = this.prettyPrint
+      ? JSON.stringify(output, null, 2)
+      : JSON.stringify(output);
+
+    console.log(jsonString);
+  }
+}

package/src/reporters/registry.ts

@@ -0,0 +1,349 @@
+/**
+ * ModestBench Reporter Registry
+ *
+ * Plugin-based system for managing benchmark output formatters. Supports
+ * registration, retrieval, and lifecycle management of reporters.
+ */
+
+import type {
+  BenchmarkRun,
+  FileResult,
+  ProgressState,
+  Reporter,
+  ReporterRegistry,
+  SuiteResult,
+  TaskResult,
+} from '../types/index.js';
+
+/**
+ * Base abstract reporter class providing common functionality
+ */
+export abstract class BaseReporter implements Reporter {
+  protected readonly name: string;
+
+  protected readonly options: Record<string, unknown>;
+
+  constructor(name: string, options: Record<string, unknown> = {}) {
+    this.name = name;
+    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 {
+    if (nanoseconds < 1000) {
+      return `${nanoseconds.toFixed(2)}ns`;
+    } else if (nanoseconds < 1000000) {
+      return `${(nanoseconds / 1000).toFixed(2)}μs`;
+    } else if (nanoseconds < 1000000000) {
+      return `${(nanoseconds / 1000000).toFixed(2)}ms`;
+    } else {
+      return `${(nanoseconds / 1000000000).toFixed(2)}s`;
+    }
+  }
+
+  /**
+   * Utility method to format operations per second
+   */
+  protected formatOpsPerSecond(opsPerSecond: number): string {
+    if (opsPerSecond < 1000) {
+      return `${opsPerSecond.toFixed(2)} ops/sec`;
+    } else if (opsPerSecond < 1000000) {
+      return `${(opsPerSecond / 1000).toFixed(2)}K ops/sec`;
+    } else if (opsPerSecond < 1000000000) {
+      return `${(opsPerSecond / 1000000).toFixed(2)}M ops/sec`;
+    } else {
+      return `${(opsPerSecond / 1000000000).toFixed(2)}B ops/sec`;
+    }
+  }
+
+  /**
+   * Utility method to format percentage
+   */
+  protected formatPercentage(value: number): string {
+    return `${value.toFixed(2)}%`;
+  }
+
+  /**
+   * Utility method to safely handle async operations
+   */
+  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;
+    }
+  }
+}
+
+/**
+ * Composite reporter that broadcasts events to multiple reporters
+ */
+export class CompositeReporter extends BaseReporter {
+  private readonly reporters: Reporter[];
+
+  constructor(reporters: Reporter[]) {
+    super('composite', {});
+    this.reporters = [...reporters];
+  }
+
+  /**
+   * Add a reporter to the composite
+   */
+  addReporter(reporter: Reporter): void {
+    this.reporters.push(reporter);
+  }
+
+  /**
+   * Get all reporters in the composite
+   */
+  getReporters(): Reporter[] {
+    return [...this.reporters];
+  }
+
+  async onEnd(run: BenchmarkRun): Promise<void> {
+    await this.broadcastAsync('onEnd', run);
+  }
+
+  async onError(error: Error): Promise<void> {
+    await this.broadcastAsync('onError', error);
+  }
+
+  async onFileEnd(result: FileResult): Promise<void> {
+    await this.broadcastAsync('onFileEnd', result);
+  }
+
+  async onFileStart(file: string): Promise<void> {
+    await this.broadcastAsync('onFileStart', file);
+  }
+
+  async onProgress(state: ProgressState): Promise<void> {
+    await this.broadcastAsync('onProgress', state);
+  }
+
+  async onStart(run: BenchmarkRun): Promise<void> {
+    await this.broadcastAsync('onStart', run);
+  }
+
+  async onSuiteEnd(result: SuiteResult): Promise<void> {
+    await this.broadcastAsync('onSuiteEnd', result);
+  }
+
+  async onSuiteStart(suite: string): Promise<void> {
+    await this.broadcastAsync('onSuiteStart', suite);
+  }
+
+  async onTaskResult(result: TaskResult): Promise<void> {
+    await this.broadcastAsync('onTaskResult', result);
+  }
+
+  async onTaskStart(task: string): Promise<void> {
+    await this.broadcastAsync('onTaskStart', task);
+  }
+
+  /**
+   * Remove a reporter from the composite
+   */
+  removeReporter(reporter: Reporter): boolean {
+    const index = this.reporters.indexOf(reporter);
+    if (index >= 0) {
+      this.reporters.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Broadcast an event to all reporters with error handling
+   */
+  private async broadcastAsync(
+    method: keyof Reporter,
+
+    ...args: any[]
+  ): Promise<void> {
+    const promises = this.reporters.map(async (reporter) => {
+      try {
+        const reporterMethod = reporter[method];
+        if (typeof reporterMethod === 'function') {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+          const result = (reporterMethod as any)(...args);
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+          if (result && typeof result.then === 'function') {
+            await result;
+          }
+        }
+      } catch (error) {
+        // Handle reporter-specific errors without affecting others
+        console.error(
+          `Reporter error in ${reporter.constructor.name}.${method}:`,
+          error,
+        );
+      }
+    });
+
+    await Promise.all(promises);
+  }
+}
+
+/**
+ * Reporter registry implementation for managing multiple reporters
+ */
+export class ModestBenchReporterRegistry implements ReporterRegistry {
+  private readonly reporters: Map<string, Reporter> = new Map();
+
+  /**
+   * Clear all registered reporters
+   */
+  clear(): void {
+    this.reporters.clear();
+  }
+
+  /**
+   * Get a reporter by name
+   */
+  get(name: string): Reporter | undefined {
+    return this.reporters.get(name);
+  }
+
+  /**
+   * Get all registered reporters
+   */
+  getAll(): Record<string, Reporter> {
+    const result: Record<string, Reporter> = {};
+    this.reporters.forEach((reporter, name) => {
+      result[name] = reporter;
+    });
+    return result;
+  }
+
+  /**
+   * Get multiple reporters by names
+   */
+  getByNames(names: string[]): Reporter[] {
+    const result: Reporter[] = [];
+    const missing: string[] = [];
+
+    for (const name of names) {
+      const reporter = this.reporters.get(name);
+      if (reporter) {
+        result.push(reporter);
+      } else {
+        missing.push(name);
+      }
+    }
+
+    if (missing.length > 0) {
+      throw new Error(
+        `Unknown reporters: ${missing.join(', ')}. Available: ${Array.from(this.reporters.keys()).join(', ')}`,
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Get list of registered reporter names
+   */
+  getNames(): string[] {
+    return Array.from(this.reporters.keys());
+  }
+
+  /**
+   * Check if a reporter is registered
+   */
+  has(name: string): boolean {
+    return this.reporters.has(name);
+  }
+
+  /**
+   * Register a reporter with a unique name
+   */
+  register(name: string, reporter: Reporter): void {
+    if (this.reporters.has(name)) {
+      throw new Error(`Reporter with name "${name}" is already registered`);
+    }
+    this.reporters.set(name, reporter);
+  }
+
+  /**
+   * Get count of registered reporters
+   */
+  size(): number {
+    return this.reporters.size;
+  }
+
+  /**
+   * Unregister a reporter
+   */
+  unregister(name: string): boolean {
+    return this.reporters.delete(name);
+  }
+}