modestbench 0.1.0 → 0.3.0

package/src/formatters/history/list.ts

@@ -0,0 +1,101 @@
+/**
+ * List Formatter
+ *
+ * Formats historical run listings in human, JSON, and CSV formats.
+ */
+
+import type { HistoryListResult } from '../../services/history/models.js';
+import type { HistoryFormatter } from './base.js';
+
+import { ansiChars, colorize } from '../../utils/ansi.js';
+
+/**
+ * Formatter for history list command
+ */
+export class HistoryListFormatter
+  implements HistoryFormatter<HistoryListResult>
+{
+  /**
+   * Format as CSV
+   */
+  formatCsv(data: HistoryListResult): string {
+    const lines: string[] = ['id,startTime,duration,files,tasks,passed,failed'];
+
+    for (const run of data.runs) {
+      lines.push(
+        `${run.id},${run.startTime.toISOString()},${run.duration},${run.summary.totalFiles},${run.summary.totalTasks},${run.summary.passedTasks},${run.summary.failedTasks}`,
+      );
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format as human-readable list
+   */
+  formatHuman(data: HistoryListResult): string {
+    if (data.runs.length === 0) {
+      return colorize('dim', 'No historical data found matching criteria.');
+    }
+
+    const lines: string[] = [
+      colorize('brightMagenta', colorize('bold', '\nRecent Benchmark Runs')),
+      '',
+    ];
+
+    for (const run of data.runs) {
+      const dateStr = run.startTime.toLocaleString();
+      const durationStr = `${(run.duration / 1000).toFixed(1)}s`;
+
+      // Status with colors and symbols
+      const hasFailures = run.summary.failedTasks > 0;
+      const statusIcon = hasFailures
+        ? colorize('brightRed', ansiChars.cross)
+        : colorize('brightCyan', ansiChars.checkmark);
+
+      const passedStr = colorize(
+        'brightCyan',
+        `${run.summary.passedTasks} passed`,
+      );
+      const statusStr = hasFailures
+        ? `${passedStr}, ${colorize('brightRed', `${run.summary.failedTasks} failed`)}`
+        : passedStr;
+
+      // Run ID in bright white and bold, date dimmed, duration in magenta
+      lines.push(
+        `  ${statusIcon} ${colorize('brightWhite', colorize('bold', run.id))} ${colorize('dim', ansiChars.bullet)} ${colorize('gray', dateStr)} ${colorize('dim', ansiChars.bullet)} ${colorize('brightMagenta', durationStr)}`,
+      );
+
+      // Files and tasks info
+      lines.push(
+        `     ${colorize('dim', `${run.summary.totalFiles} files, ${run.summary.totalTasks} tasks:`)} ${statusStr}`,
+      );
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format as JSON array
+   */
+  formatJson(data: HistoryListResult): string {
+    if (data.runs.length === 0) {
+      return '[]';
+    }
+
+    return JSON.stringify(
+      data.runs.map((run) => ({
+        duration: run.duration,
+        failed: run.summary.failedTasks,
+        files: run.summary.totalFiles,
+        id: run.id,
+        passed: run.summary.passedTasks,
+        startTime: run.startTime,
+        tasks: run.summary.totalTasks,
+      })),
+      null,
+      2,
+    );
+  }
+}

package/src/formatters/history/show.ts

@@ -0,0 +1,155 @@
+/**
+ * Show Formatter
+ *
+ * Formats detailed benchmark run display in human and JSON formats.
+ */
+
+import { relative } from 'node:path';
+
+import type { ShowResult } from '../../services/history/models.js';
+import type { HistoryFormatter } from './base.js';
+
+import { ansiChars, colorize } from '../../utils/ansi.js';
+
+/**
+ * Formatter for history show command
+ */
+export class HistoryShowFormatter implements HistoryFormatter<ShowResult> {
+  /**
+   * Format as human-readable detailed view
+   */
+  formatHuman(data: ShowResult): string {
+    const lines: string[] = [];
+
+    // Header with run ID
+    lines.push(
+      colorize(
+        'cyan',
+        colorize(
+          'bold',
+          `\nBenchmark Run: ${colorize('brightWhite', colorize('bold', data.id))}`,
+        ),
+      ),
+    );
+
+    // Run details (indented by 2 spaces)
+    lines.push(
+      `  ${colorize('brightCyan', ansiChars.bullet)} ${colorize('white', data.startTime.toLocaleString())}`,
+    );
+    lines.push(
+      `  ${colorize('brightCyan', ansiChars.bullet)} ${colorize('white', 'Duration:')} ${colorize('magenta', `${(data.duration / 1000).toFixed(1)}s`)}`,
+    );
+    lines.push(
+      `  ${colorize('brightCyan', ansiChars.bullet)} Node.js ${colorize('brightWhite', data.environment.nodeVersion)} on ${colorize('brightWhite', data.environment.platform)} (${colorize('brightWhite', data.environment.arch)})`,
+    );
+
+    // CPU and system info
+    lines.push(
+      `  ${colorize('brightCyan', ansiChars.bullet)} ${colorize('brightWhite', String(data.environment.cpu.cores))} cores @ ${colorize('brightWhite', `${data.environment.cpu.speed}MHz`)} on ${colorize('brightWhite', data.environment.cpu.model)}`,
+    );
+
+    if (data.git) {
+      lines.push(
+        `  ${colorize('brightCyan', ansiChars.bullet)} ${colorize('brightBlue', data.git.branch)}@${colorize('dim', data.git.commit.substring(0, 8))}`,
+      );
+    }
+
+    // Summary section
+    lines.push('');
+    lines.push(colorize('cyan', 'Summary'));
+    lines.push(
+      `  ${colorize('dim', ansiChars.smallSquare)} Files: ${colorize('brightWhite', String(data.summary.totalFiles))}`,
+    );
+    lines.push(
+      `  ${colorize('dim', ansiChars.smallSquare)} Suites: ${colorize('brightWhite', String(data.summary.totalSuites))}`,
+    );
+    lines.push(
+      `  ${colorize('dim', ansiChars.smallSquare)} Tasks: ${colorize('brightWhite', String(data.summary.totalTasks))}`,
+    );
+
+    lines.push(
+      `  ${colorize('dim', ansiChars.smallSquare)} Passed: ${colorize('brightCyan', String(data.summary.passedTasks))}`,
+    );
+
+    if (data.summary.failedTasks > 0) {
+      lines.push(
+        `  ${colorize('dim', ansiChars.smallSquare)} Failed: ${colorize('brightRed', colorize('bold', String(data.summary.failedTasks)))}`,
+      );
+    }
+
+    // Detailed results
+    lines.push('');
+    lines.push(colorize('cyan', 'Results'));
+    lines.push('');
+
+    for (const file of data.files) {
+      // Display filepath as relative if within cwd, otherwise absolute
+      const displayPath = relative(process.cwd(), file.filePath);
+      const finalPath = displayPath.startsWith('..')
+        ? file.filePath
+        : displayPath;
+
+      lines.push(
+        `${colorize('dim', ansiChars.bullet)} ${colorize('brightMagenta', colorize('bold', finalPath))}`,
+      );
+
+      for (const suite of file.suites) {
+        lines.push(
+          `  ${colorize('dim', ansiChars.bullet)} ${colorize('brightWhite', suite.name)}`,
+        );
+
+        for (const task of suite.tasks) {
+          const statusIcon = task.error
+            ? colorize('brightRed', ansiChars.cross)
+            : colorize('brightCyan', ansiChars.checkmark);
+
+          if (task.error) {
+            lines.push(
+              `    ${statusIcon} ${colorize('white', task.name)} ${colorize('dim', ansiChars.bullet)} ${colorize('brightRed', 'failed')}`,
+            );
+          } else {
+            const mean = formatTime(task.mean);
+            const opsStr = task.opsPerSecond.toLocaleString('en-US', {
+              maximumFractionDigits: 0,
+            });
+            const rmeStr = task.marginOfError.toFixed(2);
+
+            lines.push(
+              `    ${statusIcon} ${colorize('white', task.name)}: ${colorize('brightMagenta', mean)} ${colorize('dim', ansiChars.bullet)} ${colorize('brightBlue', `${ansiChars.plusMinus}${rmeStr}`)} ${colorize('dim', ansiChars.bullet)} ${colorize('magenta', opsStr)} ops/sec`,
+            );
+
+            if (task.iterations > 0) {
+              lines.push(
+                `      ${colorize('dim', `${task.iterations} iterations, cv: ${task.cv.toFixed(1)}%`)}`,
+              );
+            }
+          }
+        }
+      }
+
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format as complete JSON
+   */
+  formatJson(data: ShowResult): string {
+    return JSON.stringify(data, null, 2);
+  }
+}
+
+/**
+ * Format nanoseconds as a human-readable time string
+ */
+const formatTime = (ns: number): string => {
+  if (ns < 1000) {
+    return `${ns.toFixed(2)}ns`;
+  }
+  if (ns < 1000000) {
+    return `${(ns / 1000).toFixed(3)}µs`;
+  }
+  return `${(ns / 1000000).toFixed(3)}ms`;
+};

package/src/formatters/history/trends.ts

@@ -0,0 +1,281 @@
+/**
+ * Trends Formatter
+ *
+ * Formats performance trend analysis with visualizations in human and JSON
+ * formats.
+ */
+
+import { stripVTControlCharacters } from 'node:util';
+
+import type {
+  DistributionBucket,
+  TrendsResult,
+} from '../../services/history/models.js';
+import type { HistoryFormatter } from './base.js';
+
+import { colorize } from '../../utils/ansi.js';
+import { generateBarChart, generateSparkline } from './visualization.js';
+
+/**
+ * Nanoseconds per millisecond conversion constant
+ */
+const NS_PER_MS = 1_000_000;
+
+/**
+ * Nanoseconds per microsecond conversion constant
+ */
+const NS_PER_US = 1_000;
+
+/**
+ * Intelligently format a time range with appropriate precision Displays
+ * microseconds for small values (< 1ms) for better clarity
+ */
+const formatTimeRange = (minNs: number, maxNs: number): string => {
+  // If both values are below 1ms, show in microseconds for better precision
+  if (maxNs < NS_PER_MS) {
+    const minUs = minNs / NS_PER_US;
+    const maxUs = maxNs / NS_PER_US;
+    return `${minUs.toFixed(2)}-${maxUs.toFixed(2)}µs`;
+  }
+
+  // Otherwise show in milliseconds
+  const minMs = minNs / NS_PER_MS;
+  const maxMs = maxNs / NS_PER_MS;
+  return `${minMs.toFixed(3)}-${maxMs.toFixed(3)}ms`;
+};
+
+/**
+ * Calculate visible string length, stripping ANSI escape codes
+ */
+const getVisualLength = (str: string): number =>
+  stripVTControlCharacters(str).length;
+
+/**
+ * Formatter for history trends command
+ */
+export class HistoryTrendsFormatter implements HistoryFormatter<TrendsResult> {
+  /**
+   * Format as human-readable trends with visualizations
+   */
+  formatHuman(data: TrendsResult): string {
+    const lines: string[] = [];
+
+    lines.push(
+      colorize(
+        'brightMagenta',
+        colorize('bold', `\nPerformance Trends (${data.runs} runs)`),
+      ),
+    );
+
+    if (data.timespan.start && data.timespan.end) {
+      lines.push(
+        colorize(
+          'dim',
+          `Time range: ${data.timespan.start.toLocaleDateString()} to ${data.timespan.end.toLocaleDateString()}`,
+        ),
+      );
+    }
+    lines.push('');
+
+    // Summary statistics
+    lines.push(colorize('brightBlue', 'Summary:'));
+    lines.push(
+      `  ${colorize('brightCyan', '▲')} ${data.summary.improvingTasks} improving  ${colorize('brightRed', '▼')} ${data.summary.degradingTasks} degrading  ${colorize('dim', '→')} ${data.summary.stableTasks} stable`,
+    );
+    lines.push('');
+
+    // Task Performance Summary Table
+    lines.push(colorize('brightMagenta', 'Task Performance Summary:'));
+    lines.push('');
+
+    for (const trendData of data.trends) {
+      // Show top 20
+      const trendIcon =
+        trendData.trend === 'improving'
+          ? colorize('brightCyan', '▲')
+          : trendData.trend === 'degrading'
+            ? colorize('brightRed', '▼')
+            : colorize('dim', '→');
+
+      const changeColor =
+        trendData.percentChange < -5
+          ? 'brightCyan'
+          : trendData.percentChange > 5
+            ? 'brightRed'
+            : 'dim';
+
+      const changeSign = trendData.percentChange >= 0 ? '+' : '';
+      const changeStr = `${changeSign}${trendData.percentChange.toFixed(1)}%`;
+
+      // Generate sparkline - scale with number of data points (min 12, max 20)
+      const values = trendData.dataPoints.map((dp) => dp.mean);
+      const sparklineWidth = Math.min(20, Math.max(12, trendData.runs));
+      const sparkline = generateSparkline(values, sparklineWidth);
+      const sparklineColor =
+        trendData.trend === 'improving'
+          ? 'brightCyan'
+          : trendData.trend === 'degrading'
+            ? 'brightRed'
+            : 'cyan';
+
+      const taskName = colorize('white', trendData.task);
+      const percentDisplay = colorize(changeColor, changeStr.padStart(8));
+      const sparklineDisplay = colorize(sparklineColor, sparkline);
+
+      // Layout: icon (2) + task name + padding + percent (8) + spaces (2) + sparkline
+      // Position percent+graph at visual column 60 for consistent alignment
+      const prefix = `  ${trendIcon} ${taskName}`;
+      const prefixVisualLength = getVisualLength(prefix);
+      const targetColumn = 60;
+
+      if (prefixVisualLength > targetColumn) {
+        // Task name is too long, wrap to next line
+        lines.push(prefix);
+        lines.push(
+          `${' '.repeat(targetColumn)}${percentDisplay}  ${sparklineDisplay}`,
+        );
+      } else {
+        // Fit on one line with padding
+        const padding = Math.max(1, targetColumn - prefixVisualLength);
+        const paddingStr = ' '.repeat(padding);
+        lines.push(
+          `${prefix}${paddingStr}${percentDisplay}  ${sparklineDisplay}`,
+        );
+      }
+    }
+
+    // Show all trends (no limit)
+
+    lines.push('');
+
+    // Show regressions if any
+    if (data.regressions.length > 0) {
+      lines.push(
+        colorize('brightRed', colorize('bold', 'Regressions Detected:')),
+      );
+      lines.push('');
+
+      for (const regression of data.regressions) {
+        lines.push(
+          `  ${colorize('brightRed', '▼')} ${colorize('white', regression.task)}: ${colorize('brightRed', `${regression.percentChange.toFixed(1)}% slower`)} (${regression.runs} runs)`,
+        );
+      }
+
+      lines.push('');
+    }
+
+    // Show low-confidence regressions (insufficient data)
+    if (data.lowConfidenceRegressions.length > 0) {
+      lines.push(
+        colorize(
+          'brightYellow',
+          colorize('bold', '! Potential Regressions (insufficient data):'),
+        ),
+      );
+      lines.push('');
+
+      for (const regression of data.lowConfidenceRegressions) {
+        lines.push(
+          `  ${colorize('brightYellow', '!')} ${colorize('white', regression.task)}: ${colorize('brightYellow', `${regression.percentChange.toFixed(1)}% slower`)} (${regression.runs} run${regression.runs !== 1 ? 's' : ''})`,
+        );
+      }
+
+      lines.push('');
+    }
+
+    // Show performance distribution for most important task (highest RME) if we have enough data
+    // Find task with highest relative margin of error - the most variable/unreliable one
+    const mostImportantTrend = data.trends
+      .filter((t) => t.runs >= 5)
+      .sort((a, b) => {
+        const rmeA = (a.statistics.stdDeviation / a.statistics.mean) * 100;
+        const rmeB = (b.statistics.stdDeviation / b.statistics.mean) * 100;
+        return rmeB - rmeA; // Descending order (highest RME first)
+      })[0];
+
+    if (mostImportantTrend) {
+      lines.push(
+        colorize(
+          'brightMagenta',
+          'Performance Distribution (most variable task):',
+        ),
+      );
+      lines.push(colorize('white', mostImportantTrend.task));
+      const cv = (
+        (mostImportantTrend.statistics.stdDeviation /
+          mostImportantTrend.statistics.mean) *
+        100
+      ).toFixed(1);
+      lines.push(colorize('dim', `  Variability: ${cv}%`));
+      lines.push('');
+
+      // Create distribution buckets
+      const values = mostImportantTrend.dataPoints.map((dp) => dp.mean);
+      const min = Math.min(...values);
+      const max = Math.max(...values);
+      const range = max - min;
+      const numBuckets = Math.min(5, mostImportantTrend.runs);
+      const bucketSize = range / numBuckets;
+
+      const buckets: DistributionBucket[] = [];
+      for (let i = 0; i < numBuckets; i++) {
+        const bucketMin = min + i * bucketSize;
+        const bucketMax = min + (i + 1) * bucketSize;
+        const count = values.filter(
+          (v) =>
+            v >= bucketMin &&
+            (i === numBuckets - 1 ? v <= bucketMax : v < bucketMax),
+        ).length;
+
+        const label = formatTimeRange(bucketMin, bucketMax);
+
+        buckets.push({
+          count,
+          label,
+          max: bucketMax,
+          min: bucketMin,
+        });
+      }
+
+      // Filter out empty buckets for cleaner display
+      const nonEmptyBuckets = buckets.filter((b) => b.count > 0);
+      const chart = generateBarChart(nonEmptyBuckets, 25);
+      for (const line of chart) {
+        lines.push(colorize('brightCyan', line));
+      }
+
+      lines.push('');
+      lines.push(
+        colorize(
+          'dim',
+          `  Mean: ${(mostImportantTrend.statistics.mean / NS_PER_MS).toFixed(3)}ms  Median: ${(mostImportantTrend.statistics.median / NS_PER_MS).toFixed(3)}ms  StdDev: ${(mostImportantTrend.statistics.stdDeviation / NS_PER_MS).toFixed(3)}ms`,
+        ),
+      );
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format as JSON
+   */
+  formatJson(data: TrendsResult): string {
+    return JSON.stringify(
+      {
+        regressions: data.regressions,
+        summary: {
+          degradingTasks: data.summary.degradingTasks,
+          improvingTasks: data.summary.improvingTasks,
+          runs: data.runs,
+          stableTasks: data.summary.stableTasks,
+          timespan: data.timespan,
+          totalTasks: data.summary.totalTasks,
+        },
+        trends: data.trends,
+      },
+      null,
+      2,
+    );
+  }
+}

package/src/formatters/history/visualization.ts

@@ -0,0 +1,93 @@
+/**
+ * Visualization Utilities for History Formatters
+ *
+ * Pure functions for generating ASCII visualizations (sparklines, bar charts)
+ * for trend analysis and performance distribution displays.
+ */
+
+import type { DistributionBucket } from '../../services/history/models.js';
+
+/**
+ * Generate bar chart histogram from distribution buckets
+ *
+ * @param distribution - Array of distribution buckets with counts
+ * @param maxWidth - Maximum width of bars (default 20)
+ * @returns Array of formatted bar chart lines
+ */
+export const generateBarChart = (
+  distribution: DistributionBucket[],
+  maxWidth = 20,
+): string[] => {
+  if (distribution.length === 0) {
+    return [];
+  }
+
+  // Find maximum count for scaling
+  const maxCount = Math.max(...distribution.map((b) => b.count));
+
+  if (maxCount === 0) {
+    return distribution.map((bucket) => `  ${bucket.label} (0 runs)`);
+  }
+
+  // Block characters for bar visualization
+  const fullBlock = '█';
+  const lightBlock = '░';
+
+  return distribution.map((bucket) => {
+    const ratio = bucket.count / maxCount;
+    const barLength = Math.round(ratio * maxWidth);
+    const fullBlocks = fullBlock.repeat(barLength);
+    const emptyBlocks = lightBlock.repeat(maxWidth - barLength);
+
+    return `  ${fullBlocks}${emptyBlocks} ${bucket.label} (${bucket.count} run${bucket.count !== 1 ? 's' : ''})`;
+  });
+};
+
+/**
+ * Generate ASCII sparkline from values
+ *
+ * @param values - Array of numeric values to visualize
+ * @param width - Maximum width of sparkline (downsamples if needed)
+ * @returns ASCII sparkline string using block characters
+ */
+export const generateSparkline = (values: number[], width?: number): string => {
+  if (values.length === 0) {
+    return '';
+  }
+
+  // Sparkline characters from lowest to highest
+  const sparkChars = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+
+  // Downsample if width is specified and values exceed it
+  let processedValues = values;
+  if (width && values.length > width) {
+    const step = values.length / width;
+    processedValues = [];
+    for (let i = 0; i < width; i++) {
+      const idx = Math.floor(i * step);
+      processedValues.push(values[idx] ?? 0);
+    }
+  }
+
+  // Find min and max for scaling
+  const min = Math.min(...processedValues);
+  const max = Math.max(...processedValues);
+  const range = max - min;
+
+  // Handle case where all values are the same
+  if (range === 0) {
+    return (sparkChars[4] ?? '▄').repeat(processedValues.length); // Use middle character
+  }
+
+  // Map each value to a sparkline character
+  return processedValues
+    .map((value) => {
+      const normalized = (value - min) / range;
+      const index = Math.min(
+        Math.floor(normalized * sparkChars.length),
+        sparkChars.length - 1,
+      );
+      return sparkChars[index] ?? '▄';
+    })
+    .join('');
+};

package/src/index.ts

@@ -7,15 +7,11 @@
  */
 
 export { bootstrap as modestbench } from './bootstrap.js';
-// Configuration management
-export { ModestBenchConfigurationManager } from './config/manager.js';
 
-// Core engine and loader
+// Core engine
 export { ModestBenchEngine } from './core/engine.js';
 export { AccurateEngine, TinybenchEngine } from './core/engines/index.js';
 
-export { BenchmarkFileLoader } from './core/loader.js';
-
 // Statistical utilities
 export {
   calculateStatistics,
@@ -26,21 +22,30 @@ export {
 // Error classes
 export * from './errors/index.js';
 
-// Progress tracking
-export { ModestBenchProgressManager } from './progress/manager.js';
 // Reporters
 export { CsvReporter } from './reporters/csv.js';
 export { HumanReporter } from './reporters/human.js';
 export { JsonReporter } from './reporters/json.js';
-
+export { ProfileHumanReporter } from './reporters/profile-human.js';
+
+// Services
+export { ModestBenchConfigurationManager } from './services/config-manager.js';
+export { BenchmarkFileLoader } from './services/file-loader.js';
+export { FileHistoryStorage } from './services/history-storage.js';
+// Profiler services
+export { filterProfile } from './services/profiler/profile-filter.js';
+export { parseProfile } from './services/profiler/profile-parser.js';
+
+export { runWithProfiling } from './services/profiler/profile-runner.js';
+export { ModestBenchProgressManager } from './services/progress-manager.js';
 export {
   BaseReporter,
   CompositeReporter,
   ModestBenchReporterRegistry,
-} from './reporters/registry.js';
-
-// Storage
-export { FileHistoryStorage } from './storage/history.js';
+} from './services/reporter-registry.js';
 
 // Export all types
 export * from './types/index.js';
+
+// Utilities
+export { findPackageRoot } from './utils/package.js';