modestbench 0.2.0 → 0.3.1

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

@@ -0,0 +1,194 @@
+/**
+ * Profile Parser Service
+ *
+ * Parses Chrome DevTools CPU profile format (*.cpuprofile files) generated by
+ * Node.js --cpu-prof flag. Extracts JavaScript function execution data
+ * including file paths, line numbers, hit counts, and percentages.
+ *
+ * @packageDocumentation
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type {
+  ProfiledFunction,
+  ProfileSummary,
+  RawProfileData,
+} from '../../types/profiler.js';
+
+interface CallFrame {
+  columnNumber: number;
+  functionName: string;
+  lineNumber: number;
+  scriptId: string;
+  url: string;
+}
+
+/**
+ * Chrome DevTools CPU profile format
+ */
+interface CpuProfile {
+  endTime: number;
+  nodes: ProfileNode[];
+  samples?: number[];
+  startTime: number;
+}
+
+interface ProfileNode {
+  callFrame: CallFrame;
+  children?: number[];
+  hitCount?: number;
+  id: number;
+}
+
+/**
+ * Parse a CPU profile file
+ *
+ * @param profilePath - Path to *.cpuprofile file
+ * @returns Parsed profile data
+ */
+export const parseProfile = async (
+  profilePath: string,
+): Promise<RawProfileData> => {
+  // Read and parse JSON profile
+  const content = await readFile(profilePath, 'utf-8');
+  const profile: CpuProfile = JSON.parse(content) as CpuProfile;
+
+  // Extract functions and calculate statistics
+  return parseCpuProfile(profile, profilePath);
+};
+
+/**
+ * Parse CPU profile data structure
+ */
+const parseCpuProfile = (
+  profile: CpuProfile,
+  profilePath: string,
+): RawProfileData => {
+  const functions: ProfiledFunction[] = [];
+  let totalTicks = 0;
+
+  // Calculate total ticks from all node hit counts
+  for (const node of profile.nodes) {
+    totalTicks += node.hitCount || 0;
+  }
+
+  // Extract function information from nodes with hit counts
+  for (const node of profile.nodes) {
+    const hitCount = node.hitCount || 0;
+    if (hitCount === 0) {
+      continue; // Skip nodes with no samples
+    }
+
+    const { callFrame } = node;
+    const percentage = totalTicks > 0 ? (hitCount / totalTicks) * 100 : 0;
+
+    // Parse file path from URL
+    const filePath = parseFileUrl(callFrame.url);
+
+    // Determine category based on URL
+    const category = determineCategory(callFrame.url);
+
+    functions.push({
+      category,
+      file: filePath,
+      line: callFrame.lineNumber >= 0 ? callFrame.lineNumber + 1 : null, // DevTools uses 0-based line numbers
+      name: callFrame.functionName || '(anonymous)',
+      percentage,
+      ticks: hitCount,
+    });
+  }
+
+  // Calculate summary statistics
+  const javascriptTicks = functions
+    .filter((fn) => fn.category === 'JavaScript')
+    .reduce((sum, fn) => sum + fn.ticks, 0);
+
+  const cppTicks = functions
+    .filter((fn) => fn.category === 'C++')
+    .reduce((sum, fn) => sum + fn.ticks, 0);
+
+  const summary: ProfileSummary = {
+    cppTicks,
+    gcTicks: 0, // CPU profiles don't separate GC
+    javascriptTicks,
+    sharedLibraryTicks: 0,
+    totalTicks,
+  };
+
+  return {
+    functions,
+    logPath: profilePath,
+    summary,
+    totalTicks,
+  };
+};
+
+/**
+ * Parse file URL from call frame
+ */
+const parseFileUrl = (url: string): string => {
+  if (!url) {
+    return '<unknown>';
+  }
+
+  // Handle file:// URLs
+  if (url.startsWith('file://')) {
+    try {
+      return fileURLToPath(url);
+    } catch {
+      // Fallback if URL is malformed
+      return path.normalize(url.replace('file://', ''));
+    }
+  }
+
+  // Handle node: internal modules
+  if (url.startsWith('node:')) {
+    return url;
+  }
+
+  // Handle plain paths
+  return path.normalize(url);
+};
+
+/**
+ * Determine function category based on URL
+ */
+const determineCategory = (
+  url: string,
+): 'C++' | 'GC' | 'JavaScript' | 'Unknown' => {
+  if (!url) {
+    return 'Unknown';
+  }
+
+  // Node.js internals and native modules
+  if (url.startsWith('node:') || url.includes('[native code]')) {
+    return 'C++';
+  }
+
+  // eval'd code is JavaScript
+  if (url === '[eval]') {
+    return 'JavaScript';
+  }
+
+  // JavaScript files
+  if (
+    url.endsWith('.js') ||
+    url.endsWith('.mjs') ||
+    url.endsWith('.cjs') ||
+    url.endsWith('.ts') ||
+    url.endsWith('.mts') ||
+    url.endsWith('.cts')
+  ) {
+    return 'JavaScript';
+  }
+
+  // Default to JavaScript for file:// URLs
+  if (url.startsWith('file://')) {
+    return 'JavaScript';
+  }
+
+  return 'Unknown';
+};

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

@@ -0,0 +1,121 @@
+/**
+ * Profile Runner Service
+ *
+ * Executes commands with Node.js CPU profiling enabled and captures profiler
+ * output to *.cpuprofile files in .modestbench/profiles/.
+ *
+ * @packageDocumentation
+ */
+
+import { glob } from 'glob';
+import { spawn } from 'node:child_process';
+import { mkdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Options for running with profiling
+ */
+interface RunOptions {
+  /** Working directory */
+  cwd?: string;
+
+  /** Environment variables */
+  env?: NodeJS.ProcessEnv;
+
+  /** Timeout in milliseconds */
+  timeout?: number;
+}
+
+/**
+ * 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
+ */
+export const runWithProfiling = async (
+  command: string,
+  options: RunOptions = {},
+): Promise<string> => {
+  const cwd = options.cwd || process.cwd();
+
+  // Create profiles directory
+  const profilesDir = join(cwd, '.modestbench', 'profiles');
+  await mkdir(profilesDir, { recursive: true });
+
+  // Run command with NODE_OPTIONS="--cpu-prof --cpu-prof-dir=..."
+  const proc = spawn(command, {
+    cwd,
+    env: {
+      ...process.env,
+      ...options.env,
+      NODE_OPTIONS: `--cpu-prof --cpu-prof-dir=${profilesDir}`,
+    },
+    shell: true,
+    stdio: 'inherit',
+  });
+
+  // Wait for process to complete
+  await new Promise<void>((resolve, reject) => {
+    const timeout = options.timeout
+      ? setTimeout(() => {
+          proc.kill();
+          reject(
+            new Error(`Profile command timed out after ${options.timeout}ms`),
+          );
+        }, options.timeout)
+      : null;
+
+    proc.on('close', (code) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      if (code === 0 || code === null) {
+        resolve();
+      } else {
+        reject(new Error(`Profile command exited with code ${code}`));
+      }
+    });
+
+    proc.on('error', (err) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      reject(err);
+    });
+  });
+
+  // Find generated *.cpuprofile file in profiles directory
+  const profileFiles = await glob('*.cpuprofile', { cwd: profilesDir });
+
+  if (profileFiles.length === 0) {
+    throw new Error(
+      'No CPU profile generated. Ensure the command runs Node.js code.',
+    );
+  }
+
+  // Return most recent profile file
+  return await getMostRecentFile(profileFiles, profilesDir);
+};
+
+/**
+ * Get the most recently modified file from a list
+ */
+const getMostRecentFile = async (
+  files: string[],
+  cwd: string,
+): Promise<string> => {
+  let mostRecent = files[0];
+  let mostRecentTime = (await stat(`${cwd}/${mostRecent}`)).mtimeMs;
+
+  for (const file of files.slice(1)) {
+    const filePath = `${cwd}/${file}`;
+    const fileTime = (await stat(filePath)).mtimeMs;
+    if (fileTime > mostRecentTime) {
+      mostRecent = file;
+      mostRecentTime = fileTime;
+    }
+  }
+
+  return `${cwd}/${mostRecent}`;
+};

package/src/services/progress-manager.ts

@@ -32,12 +32,16 @@ interface ProgressMetrics {
 export class ModestBenchProgressManager implements ProgressManager {
   private callbacks: ProgressCallback[] = [];
 
+  private lastMetricsUpdate = 0;
+
   private lastUpdate = 0;
 
   private readonly maxRecentTimings = 10;
 
   private metrics: null | ProgressMetrics = null;
 
+  private readonly metricsUpdateThrottleMs = 1000; // Throttle ETA calculations (1 second)
+
   private state: ProgressState;
 
   private readonly updateThrottleMs = 100; // Limit updates to avoid spam
@@ -53,6 +57,8 @@ export class ModestBenchProgressManager implements ProgressManager {
     this.callbacks = [];
     this.metrics = null;
     this.state = this.createInitialState();
+    this.lastUpdate = 0;
+    this.lastMetricsUpdate = 0;
   }
 
   /**
@@ -240,6 +246,7 @@ export class ModestBenchProgressManager implements ProgressManager {
     };
 
     this.lastUpdate = Date.now();
+    this.lastMetricsUpdate = Date.now();
     this.notifyCallbacks();
   }
 
@@ -314,8 +321,11 @@ export class ModestBenchProgressManager implements ProgressManager {
       percentage: this.calculatePercentage(updates),
     };
 
-    // Update metrics for completion estimation
-    this.updateMetrics(now);
+    // Update metrics for completion estimation (throttled separately for ETA)
+    if (now - this.lastMetricsUpdate >= this.metricsUpdateThrottleMs) {
+      this.updateMetrics(now);
+      this.lastMetricsUpdate = now;
+    }
 
     this.lastUpdate = now;
     this.notifyCallbacks();

package/src/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);