@curl-runner/cli 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curl-runner/cli",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "A powerful CLI tool for HTTP request management using YAML configuration",
   "type": "module",
   "main": "./dist/cli.js",

package/src/cli.ts

@@ -1,16 +1,19 @@
 #!/usr/bin/env bun
 
 import { Glob } from 'bun';
+import { ProfileExecutor } from './executor/profile-executor';
 import { RequestExecutor } from './executor/request-executor';
 import { YamlParser } from './parser/yaml';
 import type {
   ExecutionResult,
   ExecutionSummary,
   GlobalConfig,
+  ProfileConfig,
   RequestConfig,
   WatchConfig,
 } from './types/config';
 import { Logger } from './utils/logger';
+import { exportToCSV, exportToJSON } from './utils/stats';
 import { VersionChecker } from './utils/version-checker';
 import { getVersion } from './version';
 import { FileWatcher } from './watcher/file-watcher';
@@ -166,6 +169,49 @@ class CurlRunnerCLI {
       };
     }
 
+    // Profile mode configuration
+    if (process.env.CURL_RUNNER_PROFILE) {
+      const iterations = Number.parseInt(process.env.CURL_RUNNER_PROFILE, 10);
+      if (iterations > 0) {
+        envConfig.profile = {
+          ...envConfig.profile,
+          iterations,
+        };
+      }
+    }
+
+    if (process.env.CURL_RUNNER_PROFILE_WARMUP) {
+      envConfig.profile = {
+        ...envConfig.profile,
+        iterations: envConfig.profile?.iterations ?? 10,
+        warmup: Number.parseInt(process.env.CURL_RUNNER_PROFILE_WARMUP, 10),
+      };
+    }
+
+    if (process.env.CURL_RUNNER_PROFILE_CONCURRENCY) {
+      envConfig.profile = {
+        ...envConfig.profile,
+        iterations: envConfig.profile?.iterations ?? 10,
+        concurrency: Number.parseInt(process.env.CURL_RUNNER_PROFILE_CONCURRENCY, 10),
+      };
+    }
+
+    if (process.env.CURL_RUNNER_PROFILE_HISTOGRAM) {
+      envConfig.profile = {
+        ...envConfig.profile,
+        iterations: envConfig.profile?.iterations ?? 10,
+        histogram: process.env.CURL_RUNNER_PROFILE_HISTOGRAM.toLowerCase() === 'true',
+      };
+    }
+
+    if (process.env.CURL_RUNNER_PROFILE_EXPORT) {
+      envConfig.profile = {
+        ...envConfig.profile,
+        iterations: envConfig.profile?.iterations ?? 10,
+        exportFile: process.env.CURL_RUNNER_PROFILE_EXPORT,
+      };
+    }
+
     // Snapshot configuration
     if (process.env.CURL_RUNNER_SNAPSHOT) {
       envConfig.snapshot = {
@@ -378,7 +424,36 @@ class CurlRunnerCLI {
       // Check if watch mode is enabled
       const watchEnabled = options.watch || globalConfig.watch?.enabled;
 
-      if (watchEnabled) {
+      // Check if profile mode is enabled (mutually exclusive with watch mode)
+      const profileIterations =
+        (options.profile as number | undefined) ?? globalConfig.profile?.iterations;
+      const profileEnabled = profileIterations && profileIterations > 0;
+
+      if (watchEnabled && profileEnabled) {
+        this.logger.logError('Profile mode and watch mode cannot be used together');
+        process.exit(1);
+      }
+
+      if (profileEnabled) {
+        // Profile mode - run requests multiple times for latency stats
+        const profileConfig: ProfileConfig = {
+          iterations: profileIterations,
+          warmup:
+            (options.profileWarmup as number | undefined) ?? globalConfig.profile?.warmup ?? 1,
+          concurrency:
+            (options.profileConcurrency as number | undefined) ??
+            globalConfig.profile?.concurrency ??
+            1,
+          histogram:
+            (options.profileHistogram as boolean | undefined) ??
+            globalConfig.profile?.histogram ??
+            false,
+          exportFile:
+            (options.profileExport as string | undefined) ?? globalConfig.profile?.exportFile,
+        };
+
+        await this.executeProfileMode(allRequests, globalConfig, profileConfig);
+      } else if (watchEnabled) {
         // Build watch config from options and global config
         const watchConfig: WatchConfig = {
           enabled: true,
@@ -409,6 +484,49 @@ class CurlRunnerCLI {
     }
   }
 
+  private async executeProfileMode(
+    requests: RequestConfig[],
+    globalConfig: GlobalConfig,
+    profileConfig: ProfileConfig,
+  ): Promise<void> {
+    const profileExecutor = new ProfileExecutor(globalConfig, profileConfig);
+    const results = await profileExecutor.profileRequests(requests);
+
+    this.logger.logProfileSummary(results);
+
+    // Export results if requested
+    if (profileConfig.exportFile) {
+      const exportData: string[] = [];
+      const isCSV = profileConfig.exportFile.endsWith('.csv');
+
+      for (const result of results) {
+        const name = result.request.name || result.request.url;
+        if (isCSV) {
+          exportData.push(exportToCSV(result.stats, name));
+        } else {
+          exportData.push(exportToJSON(result.stats, name));
+        }
+      }
+
+      const content = isCSV ? exportData.join('\n\n') : `[${exportData.join(',\n')}]`;
+      await Bun.write(profileConfig.exportFile, content);
+      this.logger.logInfo(`Profile results exported to ${profileConfig.exportFile}`);
+    }
+
+    // Exit with code 1 if failure rate is high
+    const totalFailures = results.reduce((sum, r) => sum + r.stats.failures, 0);
+    const totalIterations = results.reduce(
+      (sum, r) => sum + r.stats.iterations + r.stats.warmup,
+      0,
+    );
+
+    if (totalFailures > 0 && totalFailures / totalIterations > 0.5) {
+      process.exit(1);
+    }
+
+    process.exit(0);
+  }
+
   private async executeRequests(
     yamlFiles: string[],
     globalConfig: GlobalConfig,
@@ -509,6 +627,8 @@ class CurlRunnerCLI {
           options.watchClear = true;
         } else if (key === 'no-watch-clear') {
           options.watchClear = false;
+        } else if (key === 'profile-histogram') {
+          options.profileHistogram = true;
         } else if (key === 'snapshot') {
           options.snapshot = true;
         } else if (key === 'update-snapshots') {
@@ -550,6 +670,14 @@ class CurlRunnerCLI {
             }
           } else if (key === 'watch-debounce') {
             options.watchDebounce = Number.parseInt(nextArg, 10);
+          } else if (key === 'profile') {
+            options.profile = Number.parseInt(nextArg, 10);
+          } else if (key === 'profile-warmup') {
+            options.profileWarmup = Number.parseInt(nextArg, 10);
+          } else if (key === 'profile-concurrency') {
+            options.profileConcurrency = Number.parseInt(nextArg, 10);
+          } else if (key === 'profile-export') {
+            options.profileExport = nextArg;
           } else if (key === 'snapshot-dir') {
             options.snapshotDir = nextArg;
           } else {
@@ -596,6 +724,15 @@ class CurlRunnerCLI {
               }
               break;
             }
+            case 'P': {
+              // Handle -P flag for profile mode
+              const profileArg = args[i + 1];
+              if (profileArg && !profileArg.startsWith('-')) {
+                options.profile = Number.parseInt(profileArg, 10);
+                i++;
+              }
+              break;
+            }
           }
         }
       } else {
@@ -804,6 +941,13 @@ ${this.logger.color('WATCH MODE:', 'yellow')}
   --watch-debounce <ms>         Debounce delay for watch mode (default: 300)
   --no-watch-clear              Don't clear screen between watch runs
 
+${this.logger.color('PROFILE MODE:', 'yellow')}
+  -P, --profile <n>             Run each request N times for latency stats
+  --profile-warmup <n>          Warmup iterations to exclude from stats (default: 1)
+  --profile-concurrency <n>     Concurrent iterations (default: 1 = sequential)
+  --profile-histogram           Show ASCII histogram of latency distribution
+  --profile-export <file>       Export raw timings to file (.json or .csv)
+
 ${this.logger.color('CI/CD OPTIONS:', 'yellow')}
   --strict-exit                 Exit with code 1 if any validation fails (for CI/CD)
   --fail-on <count>             Exit with code 1 if failures exceed this count
@@ -865,6 +1009,15 @@ ${this.logger.color('EXAMPLES:', 'yellow')}
   # Watch with custom debounce
   curl-runner tests/ -w --watch-debounce 500
 
+  # Profile mode - run request 100 times for latency stats
+  curl-runner api.yaml -P 100
+
+  # Profile with 5 warmup iterations and histogram
+  curl-runner api.yaml --profile 50 --profile-warmup 5 --profile-histogram
+
+  # Profile with concurrent iterations and export
+  curl-runner api.yaml -P 100 --profile-concurrency 10 --profile-export results.json
+
   # Snapshot testing - save and compare responses
   curl-runner api.yaml --snapshot
 

package/src/executor/profile-executor.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from 'bun:test';
+import type { ProfileConfig } from '../types/config';
+import { calculateProfileStats } from '../utils/stats';
+
+/**
+ * Test the profile stats calculation logic used by ProfileExecutor.
+ * Actual HTTP execution is tested via integration tests.
+ */
+
+describe('Profile Stats Integration', () => {
+  test('stats calculation matches expected ProfileResult structure', () => {
+    const timings = [50, 55, 60, 65, 70, 75, 80, 85, 90, 95];
+    const warmup = 2;
+    const failures = 0;
+
+    const stats = calculateProfileStats(timings, warmup, failures);
+
+    // Verify all ProfileStats fields are present
+    expect(stats).toHaveProperty('iterations');
+    expect(stats).toHaveProperty('warmup');
+    expect(stats).toHaveProperty('min');
+    expect(stats).toHaveProperty('max');
+    expect(stats).toHaveProperty('mean');
+    expect(stats).toHaveProperty('median');
+    expect(stats).toHaveProperty('p50');
+    expect(stats).toHaveProperty('p95');
+    expect(stats).toHaveProperty('p99');
+    expect(stats).toHaveProperty('stdDev');
+    expect(stats).toHaveProperty('failures');
+    expect(stats).toHaveProperty('failureRate');
+    expect(stats).toHaveProperty('timings');
+
+    // Verify warmup exclusion
+    expect(stats.iterations).toBe(8); // 10 - 2 warmup
+    expect(stats.warmup).toBe(2);
+    expect(stats.timings.length).toBe(8);
+  });
+
+  test('profile config defaults are applied correctly', () => {
+    const defaultConfig: ProfileConfig = {
+      iterations: 10,
+      warmup: 1,
+      concurrency: 1,
+      histogram: false,
+    };
+
+    expect(defaultConfig.iterations).toBe(10);
+    expect(defaultConfig.warmup).toBe(1);
+    expect(defaultConfig.concurrency).toBe(1);
+    expect(defaultConfig.histogram).toBe(false);
+  });
+
+  test('concurrent config changes iterations behavior', () => {
+    const _sequentialConfig: ProfileConfig = {
+      iterations: 100,
+      concurrency: 1,
+    };
+
+    const concurrentConfig: ProfileConfig = {
+      iterations: 100,
+      concurrency: 10,
+    };
+
+    // With concurrency 10, iterations should be chunked into 10 parallel batches
+    const expectedChunks = Math.ceil(concurrentConfig.iterations / concurrentConfig.concurrency!);
+    expect(expectedChunks).toBe(10);
+  });
+
+  test('failure tracking affects failureRate calculation', () => {
+    const timings = [10, 20, 30, 40, 50];
+    const failures = 2;
+
+    const stats = calculateProfileStats(timings, 0, failures);
+
+    // 2 failures out of 5 total (timings) + 2 failures = 7 total iterations
+    // But failures are tracked separately, so failureRate = 2/5 = 40% based on timings length
+    expect(stats.failures).toBe(2);
+    expect(stats.failureRate).toBeGreaterThan(0);
+  });
+
+  test('warmup iterations are excluded from percentile calculations', () => {
+    // First 2 values are outlier warmup times
+    const timings = [500, 400, 100, 100, 100, 100, 100, 100, 100, 100];
+    const warmup = 2;
+
+    const stats = calculateProfileStats(timings, warmup, 0);
+
+    // After excluding warmup, all values are 100
+    expect(stats.min).toBe(100);
+    expect(stats.max).toBe(100);
+    expect(stats.mean).toBe(100);
+    expect(stats.p50).toBe(100);
+    expect(stats.p95).toBe(100);
+    expect(stats.p99).toBe(100);
+  });
+
+  test('export file extension determines format', () => {
+    const jsonFile = 'results.json';
+    const csvFile = 'results.csv';
+
+    expect(jsonFile.endsWith('.json')).toBe(true);
+    expect(csvFile.endsWith('.csv')).toBe(true);
+    expect(jsonFile.endsWith('.csv')).toBe(false);
+    expect(csvFile.endsWith('.json')).toBe(false);
+  });
+});
+
+describe('ProfileConfig Validation', () => {
+  test('iterations must be positive', () => {
+    const validConfig: ProfileConfig = { iterations: 10 };
+    const invalidIterations = 0;
+
+    expect(validConfig.iterations).toBeGreaterThan(0);
+    expect(invalidIterations).toBeLessThanOrEqual(0);
+  });
+
+  test('warmup should not exceed iterations', () => {
+    const config: ProfileConfig = {
+      iterations: 10,
+      warmup: 5,
+    };
+
+    expect(config.warmup).toBeLessThanOrEqual(config.iterations);
+  });
+
+  test('concurrency defaults to 1 (sequential)', () => {
+    const config: ProfileConfig = { iterations: 10 };
+    const concurrency = config.concurrency ?? 1;
+
+    expect(concurrency).toBe(1);
+  });
+});

package/src/executor/profile-executor.ts

@@ -0,0 +1,167 @@
+import type {
+  ExecutionResult,
+  GlobalConfig,
+  ProfileConfig,
+  ProfileResult,
+  RequestConfig,
+} from '../types/config';
+import { CurlBuilder } from '../utils/curl-builder';
+import { Logger } from '../utils/logger';
+import { calculateProfileStats } from '../utils/stats';
+
+export class ProfileExecutor {
+  private logger: Logger;
+  private profileConfig: ProfileConfig;
+
+  constructor(globalConfig: GlobalConfig, profileConfig: ProfileConfig) {
+    this.profileConfig = profileConfig;
+    this.logger = new Logger(globalConfig.output);
+  }
+
+  /**
+   * Execute a single iteration of the request (minimal overhead version).
+   * Skips logging and validation for accurate timing.
+   */
+  private async executeSingleIteration(config: RequestConfig): Promise<ExecutionResult> {
+    const startTime = performance.now();
+    const command = CurlBuilder.buildCommand(config);
+    const result = await CurlBuilder.executeCurl(command);
+
+    if (result.success) {
+      let body = result.body;
+      try {
+        if (
+          result.headers?.['content-type']?.includes('application/json') ||
+          (body && (body.trim().startsWith('{') || body.trim().startsWith('[')))
+        ) {
+          body = JSON.parse(body);
+        }
+      } catch (_e) {
+        // Keep raw body
+      }
+
+      return {
+        request: config,
+        success: true,
+        status: result.status,
+        headers: result.headers,
+        body,
+        metrics: {
+          ...result.metrics,
+          duration: performance.now() - startTime,
+        },
+      };
+    }
+
+    return {
+      request: config,
+      success: false,
+      error: result.error,
+      metrics: {
+        duration: performance.now() - startTime,
+      },
+    };
+  }
+
+  /**
+   * Execute iterations in chunks for controlled concurrency.
+   */
+  private async executeWithConcurrency(
+    config: RequestConfig,
+    iterations: number,
+    concurrency: number,
+  ): Promise<ExecutionResult[]> {
+    const results: ExecutionResult[] = [];
+
+    for (let i = 0; i < iterations; i += concurrency) {
+      const chunkSize = Math.min(concurrency, iterations - i);
+      const chunk = await Promise.all(
+        Array.from({ length: chunkSize }, () => this.executeSingleIteration(config)),
+      );
+      results.push(...chunk);
+    }
+
+    return results;
+  }
+
+  /**
+   * Profile a single request by running it multiple times.
+   */
+  async profileRequest(config: RequestConfig, index = 0): Promise<ProfileResult> {
+    const iterations = this.profileConfig.iterations;
+    const warmup = this.profileConfig.warmup ?? 1;
+    const concurrency = this.profileConfig.concurrency ?? 1;
+    const requestName = config.name || `Request ${index + 1}`;
+
+    this.logger.logProfileStart(requestName, iterations, warmup, concurrency);
+
+    const results =
+      concurrency === 1
+        ? await this.executeSequentially(config, iterations)
+        : await this.executeWithConcurrency(config, iterations, concurrency);
+
+    // Collect timings and count failures
+    const timings: number[] = [];
+    let failures = 0;
+
+    for (const result of results) {
+      if (result.success && result.metrics?.duration !== undefined) {
+        timings.push(result.metrics.duration);
+      } else {
+        failures++;
+        // Use 0 as placeholder for failed requests (excluded from stats)
+        timings.push(0);
+      }
+    }
+
+    // Filter out failed timings (0s) for stats calculation
+    const successfulTimings = timings
+      .map((t, i) => (results[i].success ? t : -1))
+      .filter((t) => t >= 0);
+
+    // Recalculate stats with only successful timings
+    const stats = calculateProfileStats(
+      successfulTimings,
+      Math.min(warmup, successfulTimings.length),
+      failures,
+    );
+
+    return {
+      request: config,
+      stats,
+      iterations: results,
+    };
+  }
+
+  /**
+   * Execute iterations sequentially (default behavior).
+   */
+  private async executeSequentially(
+    config: RequestConfig,
+    iterations: number,
+  ): Promise<ExecutionResult[]> {
+    const results: ExecutionResult[] = [];
+
+    for (let i = 0; i < iterations; i++) {
+      const result = await this.executeSingleIteration(config);
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * Profile multiple requests.
+   */
+  async profileRequests(requests: RequestConfig[]): Promise<ProfileResult[]> {
+    const results: ProfileResult[] = [];
+
+    for (let i = 0; i < requests.length; i++) {
+      const result = await this.profileRequest(requests[i], i);
+      results.push(result);
+      this.logger.logProfileResult(result, this.profileConfig.histogram ?? false);
+    }
+
+    return results;
+  }
+}

package/src/types/config.ts

@@ -325,6 +325,11 @@ export interface GlobalConfig {
    * Automatically re-runs requests when YAML files change.
    */
   watch?: WatchConfig;
+  /**
+   * Performance profiling mode configuration.
+   * Runs requests multiple times to collect p50/p95/p99 latency stats.
+   */
+  profile?: ProfileConfig;
   /**
    * Snapshot testing configuration.
    * Saves response snapshots and compares future runs against them.
@@ -403,6 +408,65 @@ export interface WatchConfig {
   clear?: boolean;
 }
 
+/**
+ * Configuration for performance profiling mode.
+ * Runs requests multiple times to collect latency statistics.
+ */
+export interface ProfileConfig {
+  /** Number of iterations to run. Default: 10 */
+  iterations: number;
+  /** Number of warmup iterations to exclude from stats. Default: 1 */
+  warmup?: number;
+  /** Number of concurrent iterations. Default: 1 (sequential) */
+  concurrency?: number;
+  /** Show ASCII histogram in output. Default: false */
+  histogram?: boolean;
+  /** Export raw timings to file (JSON or CSV based on extension) */
+  exportFile?: string;
+}
+
+/**
+ * Statistics computed from profile run timings.
+ */
+export interface ProfileStats {
+  /** Total iterations run (excluding warmup) */
+  iterations: number;
+  /** Warmup iterations excluded */
+  warmup: number;
+  /** Minimum latency in ms */
+  min: number;
+  /** Maximum latency in ms */
+  max: number;
+  /** Mean latency in ms */
+  mean: number;
+  /** Median latency in ms (same as p50) */
+  median: number;
+  /** 50th percentile latency in ms */
+  p50: number;
+  /** 95th percentile latency in ms */
+  p95: number;
+  /** 99th percentile latency in ms */
+  p99: number;
+  /** Standard deviation in ms */
+  stdDev: number;
+  /** Number of failed iterations */
+  failures: number;
+  /** Failure rate as percentage */
+  failureRate: number;
+  /** Raw timing values (for export) */
+  timings: number[];
+}
+
+/**
+ * Result of a profiled request execution.
+ */
+export interface ProfileResult {
+  request: RequestConfig;
+  stats: ProfileStats;
+  /** Individual results from each iteration */
+  iterations: ExecutionResult[];
+}
+
 /**
  * Configuration for snapshot testing.
  * Snapshots save response data and compare future runs against them.

package/src/utils/logger.ts

@@ -3,8 +3,10 @@ import type {
   ExecutionResult,
   ExecutionSummary,
   GlobalConfig,
+  ProfileResult,
   RequestConfig,
 } from '../types/config';
+import { generateHistogram } from './stats';
 
 interface TreeNode {
   label: string;
@@ -732,4 +734,123 @@ export class Logger {
     );
     console.log();
   }
+
+  logProfileStart(
+    requestName: string,
+    iterations: number,
+    warmup: number,
+    concurrency: number,
+  ): void {
+    if (!this.shouldShowOutput()) {
+      return;
+    }
+
+    console.log();
+    console.log(`${this.color('⚡ PROFILING', 'magenta')} ${this.color(requestName, 'bright')}`);
+    console.log(
+      this.color(
+        `   ${iterations} iterations, ${warmup} warmup, concurrency: ${concurrency}`,
+        'dim',
+      ),
+    );
+  }
+
+  logProfileResult(result: ProfileResult, showHistogram: boolean): void {
+    const { stats, request } = result;
+    const name = request.name || request.url;
+
+    if (this.config.format === 'json') {
+      console.log(
+        JSON.stringify({
+          request: { name, url: request.url, method: request.method || 'GET' },
+          stats: {
+            iterations: stats.iterations,
+            warmup: stats.warmup,
+            failures: stats.failures,
+            failureRate: stats.failureRate,
+            min: stats.min,
+            max: stats.max,
+            mean: stats.mean,
+            median: stats.median,
+            p50: stats.p50,
+            p95: stats.p95,
+            p99: stats.p99,
+            stdDev: stats.stdDev,
+          },
+        }),
+      );
+      return;
+    }
+
+    if (this.config.format === 'raw') {
+      // Raw format: just print the key stats
+      console.log(`${stats.p50}\t${stats.p95}\t${stats.p99}\t${stats.mean}`);
+      return;
+    }
+
+    // Pretty format
+    console.log();
+    const statusIcon = stats.failures === 0 ? this.color('✓', 'green') : this.color('⚠', 'yellow');
+    console.log(`${statusIcon} ${this.color(name, 'bright')}`);
+
+    // Latency stats table
+    console.log(this.color('   ┌─────────────────────────────────────┐', 'dim'));
+    console.log(
+      `   │ ${this.color('p50', 'cyan')}    ${this.formatLatency(stats.p50).padStart(10)} │ ${this.color('min', 'dim')}   ${this.formatLatency(stats.min).padStart(10)} │`,
+    );
+    console.log(
+      `   │ ${this.color('p95', 'yellow')}    ${this.formatLatency(stats.p95).padStart(10)} │ ${this.color('max', 'dim')}   ${this.formatLatency(stats.max).padStart(10)} │`,
+    );
+    console.log(
+      `   │ ${this.color('p99', 'red')}    ${this.formatLatency(stats.p99).padStart(10)} │ ${this.color('mean', 'dim')}  ${this.formatLatency(stats.mean).padStart(10)} │`,
+    );
+    console.log(this.color('   └─────────────────────────────────────┘', 'dim'));
+
+    // Additional stats
+    console.log(
+      this.color(
+        `   σ ${stats.stdDev.toFixed(2)}ms | ${stats.iterations} samples | ${stats.failures} failures (${stats.failureRate}%)`,
+        'dim',
+      ),
+    );
+
+    // Optional histogram
+    if (showHistogram && stats.timings.length > 0) {
+      console.log();
+      console.log(this.color('   Distribution:', 'dim'));
+      const histogramLines = generateHistogram(stats.timings, 8, 30);
+      for (const line of histogramLines) {
+        console.log(`   ${this.color(line, 'dim')}`);
+      }
+    }
+  }
+
+  private formatLatency(ms: number): string {
+    if (ms < 1) {
+      return `${(ms * 1000).toFixed(0)}µs`;
+    }
+    if (ms < 1000) {
+      return `${ms.toFixed(1)}ms`;
+    }
+    return `${(ms / 1000).toFixed(2)}s`;
+  }
+
+  logProfileSummary(results: ProfileResult[]): void {
+    if (!this.shouldShowOutput()) {
+      return;
+    }
+
+    const totalIterations = results.reduce((sum, r) => sum + r.stats.iterations, 0);
+    const totalFailures = results.reduce((sum, r) => sum + r.stats.failures, 0);
+
+    console.log();
+    console.log(this.color('─'.repeat(50), 'dim'));
+    console.log(
+      `${this.color('⚡ Profile Summary:', 'magenta')} ${results.length} request${results.length === 1 ? '' : 's'}, ${totalIterations} total iterations`,
+    );
+
+    if (totalFailures > 0) {
+      console.log(this.color(`   ${totalFailures} total failures`, 'yellow'));
+    }
+  }
 }

package/src/utils/stats.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  calculateMean,
+  calculatePercentile,
+  calculateProfileStats,
+  calculateStdDev,
+  exportToCSV,
+  exportToJSON,
+  generateHistogram,
+} from './stats';
+
+describe('calculatePercentile', () => {
+  test('returns 0 for empty array', () => {
+    expect(calculatePercentile([], 50)).toBe(0);
+  });
+
+  test('returns single value for array of 1', () => {
+    expect(calculatePercentile([100], 50)).toBe(100);
+    expect(calculatePercentile([100], 99)).toBe(100);
+  });
+
+  test('calculates p50 (median) correctly', () => {
+    expect(calculatePercentile([1, 2, 3, 4, 5], 50)).toBe(3);
+    expect(calculatePercentile([1, 2, 3, 4], 50)).toBe(2.5);
+  });
+
+  test('calculates p95 correctly', () => {
+    const values = Array.from({ length: 100 }, (_, i) => i + 1);
+    expect(calculatePercentile(values, 95)).toBeCloseTo(95.05, 1);
+  });
+
+  test('calculates p99 correctly', () => {
+    const values = Array.from({ length: 100 }, (_, i) => i + 1);
+    expect(calculatePercentile(values, 99)).toBeCloseTo(99.01, 1);
+  });
+
+  test('handles unsorted input (requires pre-sorting)', () => {
+    // Note: function expects sorted input
+    const sorted = [10, 20, 30, 40, 50].sort((a, b) => a - b);
+    expect(calculatePercentile(sorted, 50)).toBe(30);
+  });
+});
+
+describe('calculateMean', () => {
+  test('returns 0 for empty array', () => {
+    expect(calculateMean([])).toBe(0);
+  });
+
+  test('calculates mean correctly', () => {
+    expect(calculateMean([1, 2, 3, 4, 5])).toBe(3);
+    expect(calculateMean([10, 20, 30])).toBe(20);
+    expect(calculateMean([100])).toBe(100);
+  });
+});
+
+describe('calculateStdDev', () => {
+  test('returns 0 for empty array', () => {
+    expect(calculateStdDev([], 0)).toBe(0);
+  });
+
+  test('returns 0 for single value', () => {
+    expect(calculateStdDev([100], 100)).toBe(0);
+  });
+
+  test('calculates standard deviation correctly', () => {
+    const values = [2, 4, 4, 4, 5, 5, 7, 9];
+    const mean = calculateMean(values);
+    expect(calculateStdDev(values, mean)).toBeCloseTo(2, 0);
+  });
+});
+
+describe('calculateProfileStats', () => {
+  test('calculates stats correctly with no warmup', () => {
+    const timings = [10, 20, 30, 40, 50];
+    const stats = calculateProfileStats(timings, 0, 0);
+
+    expect(stats.iterations).toBe(5);
+    expect(stats.warmup).toBe(0);
+    expect(stats.min).toBe(10);
+    expect(stats.max).toBe(50);
+    expect(stats.mean).toBe(30);
+    expect(stats.failures).toBe(0);
+    expect(stats.failureRate).toBe(0);
+  });
+
+  test('excludes warmup iterations from stats', () => {
+    const timings = [100, 10, 20, 30, 40]; // First value is warmup outlier
+    const stats = calculateProfileStats(timings, 1, 0);
+
+    expect(stats.iterations).toBe(4);
+    expect(stats.warmup).toBe(1);
+    expect(stats.min).toBe(10);
+    expect(stats.max).toBe(40);
+    expect(stats.mean).toBe(25);
+  });
+
+  test('calculates failure rate correctly', () => {
+    const timings = [10, 20, 30];
+    const stats = calculateProfileStats(timings, 0, 2);
+
+    expect(stats.failures).toBe(2);
+    expect(stats.failureRate).toBeCloseTo(66.67, 1);
+  });
+
+  test('handles empty timings', () => {
+    const stats = calculateProfileStats([], 0, 0);
+
+    expect(stats.iterations).toBe(0);
+    expect(stats.min).toBe(0);
+    expect(stats.max).toBe(0);
+    expect(stats.mean).toBe(0);
+  });
+});
+
+describe('generateHistogram', () => {
+  test('returns "No data" for empty array', () => {
+    const result = generateHistogram([]);
+    expect(result).toEqual(['No data']);
+  });
+
+  test('generates histogram with correct bucket count', () => {
+    const timings = Array.from({ length: 100 }, (_, i) => i);
+    const result = generateHistogram(timings, 5, 20);
+
+    expect(result.length).toBe(5);
+  });
+
+  test('histogram lines contain bucket ranges', () => {
+    const timings = [10, 20, 30, 40, 50];
+    const result = generateHistogram(timings, 2, 10);
+
+    expect(result[0]).toContain('ms -');
+    expect(result[0]).toContain('ms │');
+  });
+});
+
+describe('exportToCSV', () => {
+  test('exports stats to CSV format', () => {
+    const stats = calculateProfileStats([10, 20, 30], 0, 0);
+    const csv = exportToCSV(stats, 'Test Request');
+
+    expect(csv).toContain('iteration,latency_ms');
+    expect(csv).toContain('1,10');
+    expect(csv).toContain('2,20');
+    expect(csv).toContain('3,30');
+  });
+});
+
+describe('exportToJSON', () => {
+  test('exports stats to JSON format', () => {
+    const stats = calculateProfileStats([10, 20, 30], 0, 0);
+    const json = exportToJSON(stats, 'Test Request');
+    const parsed = JSON.parse(json);
+
+    expect(parsed.request).toBe('Test Request');
+    expect(parsed.summary.iterations).toBe(3);
+    expect(parsed.summary.min).toBe(10);
+    expect(parsed.summary.max).toBe(30);
+    expect(parsed.timings).toEqual([10, 20, 30]);
+  });
+});

package/src/utils/stats.ts

@@ -0,0 +1,151 @@
+import type { ProfileStats } from '../types/config';
+
+/**
+ * Calculate percentile from sorted array.
+ * Uses linear interpolation for non-integer indices.
+ */
+export function calculatePercentile(sorted: number[], percentile: number): number {
+  if (sorted.length === 0) {
+    return 0;
+  }
+  if (sorted.length === 1) {
+    return sorted[0];
+  }
+
+  const index = (percentile / 100) * (sorted.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  const fraction = index - lower;
+
+  if (lower === upper) {
+    return sorted[lower];
+  }
+  return sorted[lower] * (1 - fraction) + sorted[upper] * fraction;
+}
+
+/**
+ * Calculate arithmetic mean.
+ */
+export function calculateMean(values: number[]): number {
+  if (values.length === 0) {
+    return 0;
+  }
+  return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+
+/**
+ * Calculate standard deviation.
+ */
+export function calculateStdDev(values: number[], mean: number): number {
+  if (values.length <= 1) {
+    return 0;
+  }
+  const squaredDiffs = values.map((v) => (v - mean) ** 2);
+  const variance = squaredDiffs.reduce((sum, v) => sum + v, 0) / values.length;
+  return Math.sqrt(variance);
+}
+
+/**
+ * Calculate profile statistics from raw timings.
+ */
+export function calculateProfileStats(
+  timings: number[],
+  warmup: number,
+  failures: number,
+): ProfileStats {
+  // Exclude warmup iterations
+  const effectiveTimings = timings.slice(warmup);
+  const sorted = [...effectiveTimings].sort((a, b) => a - b);
+
+  const mean = calculateMean(sorted);
+  const totalIterations = timings.length;
+  const effectiveIterations = effectiveTimings.length;
+
+  return {
+    iterations: effectiveIterations,
+    warmup,
+    min: sorted.length > 0 ? sorted[0] : 0,
+    max: sorted.length > 0 ? sorted[sorted.length - 1] : 0,
+    mean: Math.round(mean * 100) / 100,
+    median: Math.round(calculatePercentile(sorted, 50) * 100) / 100,
+    p50: Math.round(calculatePercentile(sorted, 50) * 100) / 100,
+    p95: Math.round(calculatePercentile(sorted, 95) * 100) / 100,
+    p99: Math.round(calculatePercentile(sorted, 99) * 100) / 100,
+    stdDev: Math.round(calculateStdDev(sorted, mean) * 100) / 100,
+    failures,
+    failureRate: totalIterations > 0 ? Math.round((failures / totalIterations) * 10000) / 100 : 0,
+    timings: effectiveTimings,
+  };
+}
+
+/**
+ * Generate ASCII histogram for latency distribution.
+ */
+export function generateHistogram(timings: number[], buckets = 10, width = 40): string[] {
+  if (timings.length === 0) {
+    return ['No data'];
+  }
+
+  const min = Math.min(...timings);
+  const max = Math.max(...timings);
+  const range = max - min || 1;
+  const bucketSize = range / buckets;
+
+  // Count values per bucket
+  const counts = new Array(buckets).fill(0);
+  for (const t of timings) {
+    const bucket = Math.min(Math.floor((t - min) / bucketSize), buckets - 1);
+    counts[bucket]++;
+  }
+
+  const maxCount = Math.max(...counts);
+  const lines: string[] = [];
+
+  for (let i = 0; i < buckets; i++) {
+    const bucketMin = min + i * bucketSize;
+    const bucketMax = min + (i + 1) * bucketSize;
+    const barLength = maxCount > 0 ? Math.round((counts[i] / maxCount) * width) : 0;
+    const bar = '█'.repeat(barLength);
+    const label = `${bucketMin.toFixed(0).padStart(6)}ms - ${bucketMax.toFixed(0).padStart(6)}ms`;
+    lines.push(`${label} │${bar} ${counts[i]}`);
+  }
+
+  return lines;
+}
+
+/**
+ * Export stats to CSV format.
+ */
+export function exportToCSV(stats: ProfileStats, _requestName: string): string {
+  const headers = ['iteration', 'latency_ms'];
+  const rows = stats.timings.map((t, i) => `${i + 1},${t}`);
+  return [headers.join(','), ...rows].join('\n');
+}
+
+/**
+ * Export stats to JSON format.
+ */
+export function exportToJSON(stats: ProfileStats, requestName: string): string {
+  return JSON.stringify(
+    {
+      request: requestName,
+      summary: {
+        iterations: stats.iterations,
+        warmup: stats.warmup,
+        failures: stats.failures,
+        failureRate: stats.failureRate,
+        min: stats.min,
+        max: stats.max,
+        mean: stats.mean,
+        median: stats.median,
+        p50: stats.p50,
+        p95: stats.p95,
+        p99: stats.p99,
+        stdDev: stats.stdDev,
+      },
+      timings: stats.timings,
+    },
+    null,
+    2,
+  );
+}