modestbench 0.5.1 → 0.7.0

package/src/adapters/jest-hooks.ts

@@ -0,0 +1,82 @@
+/**
+ * ModestBench Jest Loader Hooks
+ *
+ * ES module loader hooks that intercept `@jest/globals` imports and return our
+ * capturing mock from globalThis.
+ *
+ * Usage: node --import modestbench/jest test-file.js
+ *
+ * This loader exports async `resolve` and `load` hooks that get registered via
+ * module.register() when imported through jest-register.ts.
+ */
+
+import type { LoadHook, ResolveHook } from 'node:module';
+
+/**
+ * Generate the mock module source code
+ *
+ * Uses top-level await to conditionally get mock or real module. Note: Uses
+ * '@jest/globals?passthrough' to bypass our hook when falling back.
+ *
+ * Security: The globalThis mock is only installed by our own adapter code, so
+ * the generated source is safe. No user input is interpolated into this
+ * template.
+ */
+const generateMockSource = (): string => `
+const mock = globalThis.__MODESTBENCH_JEST_MOCK__;
+
+// If no mock installed, fall through to real @jest/globals
+// The '?passthrough' query tells our hook to not intercept this import
+const source = mock ?? await import('@jest/globals?passthrough');
+
+export const describe = source.describe;
+export const fdescribe = source.fdescribe ?? source.describe?.only;
+export const xdescribe = source.xdescribe ?? source.describe?.skip;
+export const test = source.test;
+export const it = source.it ?? source.test;
+export const fit = source.fit ?? source.test?.only;
+export const xit = source.xit ?? source.test?.skip;
+export const xtest = source.xtest ?? source.test?.skip;
+export const expect = source.expect;
+export const jest = source.jest;
+export const beforeAll = source.beforeAll;
+export const afterAll = source.afterAll;
+export const beforeEach = source.beforeEach;
+export const afterEach = source.afterEach;
+export default source;
+`;
+
+/**
+ * Resolve hook - intercepts @jest/globals specifier
+ *
+ * Uses query param '?passthrough' to prevent infinite recursion when falling
+ * back to real @jest/globals (when no mock is installed).
+ */
+export const resolve: ResolveHook = async (specifier, context, nextResolve) => {
+  // Only intercept bare '@jest/globals', not '@jest/globals?passthrough'
+  if (specifier === '@jest/globals') {
+    return {
+      shortCircuit: true,
+      url: 'modestbench://capture/jest',
+    };
+  }
+  // Strip passthrough query to resolve real @jest/globals
+  if (specifier === '@jest/globals?passthrough') {
+    return nextResolve('@jest/globals', context);
+  }
+  return nextResolve(specifier, context);
+};
+
+/**
+ * Load hook - returns mock module for our custom URL
+ */
+export const load: LoadHook = async (url, context, nextLoad) => {
+  if (url === 'modestbench://capture/jest') {
+    return {
+      format: 'module',
+      shortCircuit: true,
+      source: generateMockSource(),
+    };
+  }
+  return nextLoad(url, context);
+};

package/src/adapters/jest-register.ts

@@ -0,0 +1,16 @@
+/**
+ * ModestBench Jest Loader Registration
+ *
+ * Registers the Jest ESM loader hooks via module.register().
+ *
+ * Usage: node --import modestbench/jest your-test.js
+ *
+ * This file registers the hooks module which intercepts '@jest/globals'
+ * imports.
+ */
+
+import { register } from 'node:module';
+
+register('./jest-hooks.js', {
+  parentURL: import.meta.url,
+});

package/src/adapters/types.ts

@@ -20,6 +20,10 @@ export interface CapturedSuite {
   readonly hooks: SuiteHooks;
   /** Suite name */
   readonly name: string;
+  /** Whether this suite is marked .only */
+  readonly only?: boolean;
+  /** Whether this suite is marked .skip */
+  readonly skip?: boolean;
   /** Tests in this suite */
   readonly tests: CapturedTest[];
 }
@@ -79,7 +83,7 @@ export interface SuiteHooks {
 /**
  * Supported test frameworks
  */
-export type TestFramework = 'ava' | 'mocha' | 'node-test';
+export type TestFramework = 'ava' | 'jest' | 'mocha' | 'node-test';
 
 /**
  * Interface for test framework adapters

package/src/cli/commands/run.ts

@@ -10,7 +10,7 @@ import { resolve } from 'node:path';
 import type { BenchmarkRun, ModestBenchConfig } from '../../types/index.js';
 import type { CliContext } from '../index.js';
 
-import { ErrorCodes } from '../../constants.js';
+import { ErrorCodes, ExitCodes } from '../../constants.js';
 import { resolveOutputPath } from '../../core/output-path-resolver.js';
 import {
   type BudgetExceededError,
@@ -20,8 +20,8 @@ import {
 import { CsvReporter } from '../../reporters/csv.js';
 import { HumanReporter } from '../../reporters/human.js';
 import { JsonReporter } from '../../reporters/json.js';
+import { NyanReporter } from '../../reporters/nyan.js';
 import { SimpleReporter } from '../../reporters/simple.js';
-import { ExitCodes } from '../../types/cli.js';
 import { hasErrorCode, isError } from '../../utils/type-guards.js';
 
 /**
@@ -395,7 +395,7 @@ const setupReporters = (
         : undefined;
 
     // Built-in reporter names for error messages
-    const builtInReporters = ['human', 'json', 'csv', 'simple'];
+    const builtInReporters = ['human', 'json', 'csv', 'nyan', 'simple'];
 
     for (const reporterName of requestedReporters) {
       let reporter;
@@ -440,6 +440,13 @@ const setupReporters = (
           break;
         }
 
+        case 'nyan':
+          reporter = new NyanReporter({
+            color: true,
+            quiet: explicitQuiet,
+          });
+          break;
+
         case 'simple':
           reporter = new SimpleReporter({
             quiet: explicitQuiet,

package/src/cli/commands/test.ts

@@ -5,8 +5,7 @@
  * executing them through a lightweight benchmark runner.
  */
 
-import { hostname } from 'node:os';
-import { cpus, freemem, totalmem } from 'node:os';
+import { cpus, freemem, hostname, totalmem } from 'node:os';
 import { resolve } from 'node:path';
 import { performance } from 'node:perf_hooks';
 
@@ -21,6 +20,7 @@ import type {
 import type { CliContext } from '../index.js';
 
 import { AvaAdapter } from '../../adapters/ava-adapter.js';
+import { JestAdapter } from '../../adapters/jest-adapter.js';
 import { MochaAdapter } from '../../adapters/mocha-adapter.js';
 import { NodeTestAdapter } from '../../adapters/node-test-adapter.js';
 import {
@@ -30,7 +30,7 @@ import {
   type ConvertedBenchmarkSuite,
   type TestFramework,
 } from '../../adapters/types.js';
-import { ExitCodes } from '../../types/cli.js';
+import { ExitCodes } from '../../constants.js';
 import { createRunId } from '../../types/core.js';
 import { isError } from '../../utils/type-guards.js';
 
@@ -512,6 +512,8 @@ const selectAdapter = (framework: TestFramework) => {
   switch (framework) {
     case 'ava':
       return new AvaAdapter();
+    case 'jest':
+      return new JestAdapter();
     case 'mocha':
       return new MochaAdapter();
     case 'node-test':

package/src/cli/index.ts

@@ -39,6 +39,7 @@ import {
   CsvReporter,
   HumanReporter,
   JsonReporter,
+  NyanReporter,
   SimpleReporter,
 } from '../reporters/index.js';
 // Import commands
@@ -993,11 +994,11 @@ export const main = async (
       )
       .command(
         'test <framework> [files..]',
-        'Run test files as benchmarks (captures tests from Mocha, node:test, or AVA)',
+        'Run test files as benchmarks (captures tests from Jest, Mocha, node:test, or AVA)',
         (yargs) => {
           return yargs
             .positional('framework', {
-              choices: ['mocha', 'node-test', 'ava'] as const,
+              choices: ['ava', 'jest', 'mocha', 'node-test'] as const,
               demandOption: true,
               describe: 'Test framework to use',
               nargs: 1,
@@ -1151,6 +1152,13 @@ const createCliContext = async (
       }),
     );
 
+    engine.registerReporter(
+      'nyan',
+      new NyanReporter({
+        color: !options.noColor,
+      }),
+    );
+
     return {
       abortController,
       configManager: engine.configManager,

package/src/constants.ts

@@ -1,4 +1,4 @@
-import { type Engine } from './types/cli.js';
+import { type Engine } from './types/core.js';
 
 /**
  * Supported benchmark file extensions
@@ -60,6 +60,7 @@ export const Reporters = {
   CSV: 'csv',
   HUMAN: 'human',
   JSON: 'json',
+  NYAN: 'nyan',
   SIMPLE: 'simple',
 } as const;
 

package/src/index.ts

@@ -8,6 +8,9 @@
 
 export { bootstrap as modestbench } from './bootstrap.js';
 
+// Constants
+export { ExitCodes } from './constants.js';
+
 // Core engine
 export { ModestBenchEngine } from './core/engine.js';
 export { AccurateEngine, TinybenchEngine } from './core/engines/index.js';

package/src/reporters/index.ts

@@ -7,4 +7,5 @@
 export { CsvReporter } from './csv.js';
 export { HumanReporter } from './human.js';
 export { JsonReporter } from './json.js';
+export { NyanReporter } from './nyan.js';
 export { SimpleReporter } from './simple.js';

package/src/reporters/nyan.ts

@@ -0,0 +1,409 @@
+/**
+ * ModestBench Nyan Cat Reporter
+ *
+ * Because benchmarking should be more colorful. Displays an animated nyan cat
+ * flying through a rainbow trail as benchmarks complete.
+ *
+ * Based on Mocha's legendary nyan reporter, adapted for the glory of
+ * performance measurement.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  BenchmarkRun,
+  FileResult,
+  SuiteResult,
+  TaskResult,
+} from '../types/index.js';
+
+import { BaseReporter } from '../services/reporter-registry.js';
+import { colors } from '../utils/ansi.js';
+
+/**
+ * Nyan Cat reporter - because your benchmarks deserve rainbow power
+ */
+export class NyanReporter extends BaseReporter {
+  /** Index into rainbow colors for cycling */
+  private colorIndex = 0;
+
+  /** Current file being processed */
+  private currentFile = '';
+
+  /** Current suite being processed */
+  private currentSuite = '';
+
+  /** Total failed tasks */
+  private failed = 0;
+
+  /** Collected failures for summary */
+  private failures: Array<{
+    error: string;
+    file: string;
+    suite: string;
+    task: string;
+  }> = [];
+
+  /** Number of lines the cat occupies */
+  private readonly numberOfLines = 4;
+
+  /** Total passed tasks */
+  private passed = 0;
+
+  /** Whether the display is active */
+  private progressActive = false;
+
+  /** Quiet mode - suppress output */
+  private readonly quiet: boolean;
+
+  /** Generated rainbow color palette */
+  private rainbowColors: number[] = [];
+
+  /** Width of scoreboard */
+  private readonly scoreboardWidth = 5;
+
+  /** Start time for duration calculation */
+  private startTime = 0;
+
+  /** Animation tick (alternates between frames) */
+  private tick = false;
+
+  /** Rainbow trail storage - one trajectory per cat line */
+  private trajectories: string[][] = [[], [], [], []];
+
+  /** Maximum width of the rainbow trail */
+  private trajectoryWidthMax = 0;
+
+  /** Whether to use colors */
+  private readonly useColor: boolean;
+
+  constructor(
+    options: {
+      color?: boolean;
+      quiet?: boolean;
+    } = {},
+  ) {
+    super('nyan', options);
+
+    this.quiet = options.quiet ?? false;
+
+    // Auto-detect color support if not explicitly set
+    this.useColor =
+      options.color ??
+      (process.stdout.isTTY &&
+        process.env.FORCE_COLOR !== '0' &&
+        process.env.NO_COLOR == null);
+
+    // Generate the rainbow colors on construction
+    this.rainbowColors = this.generateColors();
+
+    // Calculate trajectory width based on terminal width
+    // Leave room for scoreboard (5) + cat (11) + some padding
+    const termWidth = process.stdout.columns || 80;
+    const nyanCatWidth = 11;
+    this.trajectoryWidthMax = Math.floor(termWidth * 0.75) - nyanCatWidth;
+  }
+
+  onEnd(run: BenchmarkRun): void {
+    if (this.quiet) {
+      return;
+    }
+
+    // Show cursor and move past the cat
+    this.showCursor();
+    for (let i = 0; i < this.numberOfLines; i++) {
+      process.stdout.write('\n');
+    }
+
+    // Print summary
+    this.printEpilogue(run);
+  }
+
+  onError(error: Error): void {
+    if (this.quiet) {
+      return;
+    }
+
+    // Make sure cursor is visible
+    this.showCursor();
+
+    console.error(`\n${colors.red}Error: ${error.message}${colors.reset}`);
+  }
+
+  onFileEnd(_result: FileResult): void {
+    // Just keep flying
+  }
+
+  onFileStart(file: string): void {
+    this.currentFile = file;
+  }
+
+  onStart(_run: BenchmarkRun): void {
+    this.startTime = Date.now();
+    this.passed = 0;
+    this.failed = 0;
+    this.failures = [];
+    this.colorIndex = 0;
+    this.tick = false;
+    this.trajectories = [[], [], [], []];
+
+    if (this.quiet) {
+      return;
+    }
+
+    // Hide cursor for cleaner animation
+    this.hideCursor();
+
+    // Initial draw
+    this.draw();
+    this.progressActive = true;
+  }
+
+  onSuiteEnd(_result: SuiteResult): void {
+    // Keep flying
+  }
+
+  onSuiteStart(suite: string): void {
+    this.currentSuite = suite;
+  }
+
+  onTaskResult(result: TaskResult): void {
+    if (result.error) {
+      this.failed++;
+      this.failures.push({
+        error: result.error.message || String(result.error),
+        file: this.currentFile,
+        suite: this.currentSuite,
+        task: result.name,
+      });
+    } else if (!result.aborted) {
+      this.passed++;
+    }
+
+    if (this.quiet) {
+      return;
+    }
+
+    this.draw();
+  }
+
+  onTaskStart(_task: string): void {
+    // The cat flies on results, not starts
+  }
+
+  /**
+   * Append a segment to the rainbow trail
+   */
+  private appendRainbow(): void {
+    const segment = this.tick ? '_' : '-';
+    const rainbowified = this.rainbowify(segment);
+
+    for (let index = 0; index < this.numberOfLines; index++) {
+      const trajectory = this.trajectories[index]!;
+      if (trajectory.length >= this.trajectoryWidthMax) {
+        trajectory.shift();
+      }
+      trajectory.push(rainbowified);
+    }
+  }
+
+  /**
+   * Move cursor down n lines
+   */
+  private cursorDown(n: number): void {
+    process.stdout.write(`\x1b[${n}B`);
+  }
+
+  /**
+   * Move cursor up n lines
+   */
+  private cursorUp(n: number): void {
+    process.stdout.write(`\x1b[${n}A`);
+  }
+
+  /**
+   * Draw the complete nyan cat scene
+   */
+  private draw(): void {
+    this.appendRainbow();
+    this.drawScoreboard();
+    this.drawRainbow();
+    this.drawNyanCat();
+    this.tick = !this.tick;
+  }
+
+  /**
+   * Draw the nyan cat ASCII art
+   */
+  private drawNyanCat(): void {
+    const startWidth = this.scoreboardWidth + this.trajectories[0]!.length;
+    const dist = `\x1b[${startWidth}C`;
+
+    process.stdout.write(dist);
+    process.stdout.write('_,------,');
+    process.stdout.write('\n');
+
+    process.stdout.write(dist);
+    const padding1 = this.tick ? '  ' : '   ';
+    process.stdout.write(`_|${padding1}/\\_/\\ `);
+    process.stdout.write('\n');
+
+    process.stdout.write(dist);
+    const padding2 = this.tick ? '_' : '__';
+    const tail = this.tick ? '~' : '^';
+    process.stdout.write(`${tail}|${padding2}${this.face()} `);
+    process.stdout.write('\n');
+
+    process.stdout.write(dist);
+    const padding3 = this.tick ? ' ' : '  ';
+    process.stdout.write(`${padding3}""  "" `);
+    process.stdout.write('\n');
+
+    this.cursorUp(this.numberOfLines);
+  }
+
+  /**
+   * Draw the rainbow trail
+   */
+  private drawRainbow(): void {
+    for (const line of this.trajectories) {
+      process.stdout.write(`\x1b[${this.scoreboardWidth}C`);
+      process.stdout.write(line.join(''));
+      process.stdout.write('\n');
+    }
+
+    this.cursorUp(this.numberOfLines);
+  }
+
+  /**
+   * Draw the scoreboard showing pass/fail counts
+   */
+  private drawScoreboard(): void {
+    const draw = (type: 'green' | 'red', n: number) => {
+      process.stdout.write(' ');
+      if (this.useColor) {
+        process.stdout.write(`${colors[type]}${n}${colors.reset}`);
+      } else {
+        process.stdout.write(String(n));
+      }
+      process.stdout.write('\n');
+    };
+
+    draw('green', this.passed);
+    draw('red', this.failed);
+    process.stdout.write('\n');
+    process.stdout.write('\n');
+
+    this.cursorUp(this.numberOfLines);
+  }
+
+  /**
+   * Get the nyan cat's face based on current state
+   */
+  private face(): string {
+    if (this.failed > 0) {
+      return '( x .x)';
+    } else if (this.passed > 0) {
+      return '( ^ .^)';
+    }
+    return '( - .-)';
+  }
+
+  /**
+   * Generate rainbow colors using sine wave color cycling
+   *
+   * Uses 256-color palette (colors 16-231 are a 6x6x6 color cube)
+   */
+  private generateColors(): number[] {
+    const colorList: number[] = [];
+
+    // Generate 42 colors (6 * 7) cycling through the spectrum
+    for (let i = 0; i < 6 * 7; i++) {
+      const pi3 = Math.floor(Math.PI / 3);
+      const n = i * (1.0 / 6);
+      const r = Math.floor(3 * Math.sin(n) + 3);
+      const g = Math.floor(3 * Math.sin(n + 2 * pi3) + 3);
+      const b = Math.floor(3 * Math.sin(n + 4 * pi3) + 3);
+      // Calculate 256-color code from RGB values (16 + 36*r + 6*g + b)
+      colorList.push(36 * r + 6 * g + b + 16);
+    }
+
+    return colorList;
+  }
+
+  /**
+   * Hide the cursor
+   */
+  private hideCursor(): void {
+    if (process.stdout.isTTY) {
+      process.stdout.write('\x1b[?25l');
+    }
+  }
+
+  /**
+   * Print the epilogue summary after the run
+   */
+  private printEpilogue(run: BenchmarkRun): void {
+    const duration = Date.now() - this.startTime;
+    const durationStr = BaseReporter.formatDuration(duration * 1000000);
+
+    console.log();
+    console.log(
+      `  ${this.useColor ? colors.green : ''}${this.passed} passing${this.useColor ? colors.reset : ''} ${this.useColor ? colors.gray : ''}(${durationStr})${this.useColor ? colors.reset : ''}`,
+    );
+
+    if (this.failed > 0) {
+      console.log(
+        `  ${this.useColor ? colors.red : ''}${this.failed} failing${this.useColor ? colors.reset : ''}`,
+      );
+      console.log();
+
+      // Print failure details
+      for (let i = 0; i < this.failures.length; i++) {
+        const failure = this.failures[i]!;
+        console.log(
+          `  ${i + 1}) ${failure.suite === 'default' ? '' : failure.suite + ' > '}${failure.task}`,
+        );
+        console.log(
+          `     ${this.useColor ? colors.red : ''}${failure.error}${this.useColor ? colors.reset : ''}`,
+        );
+        console.log();
+      }
+    }
+
+    // Show total files/suites for context
+    let totalSuites = 0;
+    for (const file of run.files) {
+      totalSuites += file.suites.length;
+    }
+
+    console.log();
+    console.log(
+      `  ${this.useColor ? colors.gray : ''}Files: ${run.files.length} | Suites: ${totalSuites} | Tasks: ${this.passed + this.failed}${this.useColor ? colors.reset : ''}`,
+    );
+  }
+
+  /**
+   * Apply rainbow coloring to a string
+   */
+  private rainbowify(str: string): string {
+    if (!this.useColor) {
+      return str;
+    }
+
+    const color =
+      this.rainbowColors[this.colorIndex % this.rainbowColors.length]!;
+    this.colorIndex += 1;
+
+    return `\x1b[38;5;${color}m${str}\x1b[0m`;
+  }
+
+  /**
+   * Show the cursor
+   */
+  private showCursor(): void {
+    if (process.stdout.isTTY) {
+      process.stdout.write('\x1b[?25h');
+    }
+  }
+}