modestbench 0.7.0 → 0.8.0

package/dist/utils/reporter-utils.cjs

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * ModestBench Reporter Utilities
+ *
+ * Formatting functions for benchmark data, exported for use by third-party
+ * reporter plugins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reporterUtils = exports.formatPercentage = exports.formatOpsPerSecond = exports.formatDuration = exports.formatBytes = void 0;
+/**
+ * Format bytes in human-readable format
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 GB", "256 MB", "1.2 KB")
+ */
+const formatBytes = (bytes) => {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(1)} ${units[unitIndex]}`;
+};
+exports.formatBytes = formatBytes;
+/**
+ * Format duration in human-readable format
+ *
+ * @param nanoseconds - Duration in nanoseconds
+ * @returns Formatted string (e.g., "1.23ms", "456.78μs", "789.00ns")
+ */
+const formatDuration = (nanoseconds) => {
+    if (nanoseconds < 1000) {
+        return `${nanoseconds.toFixed(2)}ns`;
+    }
+    else if (nanoseconds < 1_000_000) {
+        return `${(nanoseconds / 1000).toFixed(2)}μs`;
+    }
+    else if (nanoseconds < 1_000_000_000) {
+        return `${(nanoseconds / 1_000_000).toFixed(2)}ms`;
+    }
+    else {
+        return `${(nanoseconds / 1_000_000_000).toFixed(2)}s`;
+    }
+};
+exports.formatDuration = formatDuration;
+/**
+ * Format operations per second in human-readable format
+ *
+ * @param opsPerSecond - Operations per second
+ * @returns Formatted string (e.g., "1.2M ops/sec", "456K ops/sec")
+ */
+const formatOpsPerSecond = (opsPerSecond) => {
+    if (opsPerSecond < 1000) {
+        return `${opsPerSecond.toFixed(2)} ops/sec`;
+    }
+    else if (opsPerSecond < 1_000_000) {
+        return `${(opsPerSecond / 1000).toFixed(2)}K ops/sec`;
+    }
+    else if (opsPerSecond < 1_000_000_000) {
+        return `${(opsPerSecond / 1_000_000).toFixed(2)}M ops/sec`;
+    }
+    else {
+        return `${(opsPerSecond / 1_000_000_000).toFixed(2)}B ops/sec`;
+    }
+};
+exports.formatOpsPerSecond = formatOpsPerSecond;
+/**
+ * Format percentage value
+ *
+ * @param value - Percentage value (e.g., 12.345 for 12.345%)
+ * @returns Formatted string (e.g., "12.35%")
+ */
+const formatPercentage = (value) => {
+    return `${value.toFixed(2)}%`;
+};
+exports.formatPercentage = formatPercentage;
+/**
+ * Reporter utilities object implementing the ReporterUtils interface
+ *
+ * This object is provided to reporter plugins via the ReporterContext.
+ */
+exports.reporterUtils = {
+    formatBytes: exports.formatBytes,
+    formatDuration: exports.formatDuration,
+    formatOpsPerSecond: exports.formatOpsPerSecond,
+    formatPercentage: exports.formatPercentage,
+};
+//# sourceMappingURL=reporter-utils.js.map

package/dist/utils/reporter-utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter-utils.js","sourceRoot":"","sources":["../../src/utils/reporter-utils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIH;;;;;GAKG;AACI,MAAM,WAAW,GAAG,CAAC,KAAa,EAAU,EAAE;IACnD,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,OAAO,IAAI,IAAI,IAAI,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,IAAI,CAAC;QACb,SAAS,EAAE,CAAC;IACd,CAAC;IAED,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;AAClD,CAAC,CAAC;AAXW,QAAA,WAAW,eAWtB;AAEF;;;;;GAKG;AACI,MAAM,cAAc,GAAG,CAAC,WAAmB,EAAU,EAAE;IAC5D,IAAI,WAAW,GAAG,IAAI,EAAE,CAAC;QACvB,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;SAAM,IAAI,WAAW,GAAG,SAAS,EAAE,CAAC;QACnC,OAAO,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;SAAM,IAAI,WAAW,GAAG,aAAa,EAAE,CAAC;QACvC,OAAO,GAAG,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,CAAC,WAAW,GAAG,aAAa,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACxD,CAAC;AACH,CAAC,CAAC;AAVW,QAAA,cAAc,kBAUzB;AAEF;;;;;GAKG;AACI,MAAM,kBAAkB,GAAG,CAAC,YAAoB,EAAU,EAAE;IACjE,IAAI,YAAY,GAAG,IAAI,EAAE,CAAC;QACxB,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IAC9C,CAAC;SAAM,IAAI,YAAY,GAAG,SAAS,EAAE,CAAC;QACpC,OAAO,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IACxD,CAAC;SAAM,IAAI,YAAY,GAAG,aAAa,EAAE,CAAC;QACxC,OAAO,GAAG,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IAC7D,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,CAAC,YAAY,GAAG,aAAa,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IACjE,CAAC;AACH,CAAC,CAAC;AAVW,QAAA,kBAAkB,sBAU7B;AAEF;;;;;GAKG;AACI,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAU,EAAE;IACxD,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AAChC,CAAC,CAAC;AAFW,QAAA,gBAAgB,oBAE3B;AAEF;;;;GAIG;AACU,QAAA,aAAa,GAAkB;IAC1C,WAAW,EAAX,mBAAW;IACX,cAAc,EAAd,sBAAc;IACd,kBAAkB,EAAlB,0BAAkB;IAClB,gBAAgB,EAAhB,wBAAgB;CACjB,CAAC"}

package/dist/utils/reporter-utils.d.cts

@@ -0,0 +1,42 @@
+/**
+ * ModestBench Reporter Utilities
+ *
+ * Formatting functions for benchmark data, exported for use by third-party
+ * reporter plugins.
+ */
+import type { ReporterUtils } from "../types/plugin.cjs";
+/**
+ * Format bytes in human-readable format
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 GB", "256 MB", "1.2 KB")
+ */
+export declare const formatBytes: (bytes: number) => string;
+/**
+ * Format duration in human-readable format
+ *
+ * @param nanoseconds - Duration in nanoseconds
+ * @returns Formatted string (e.g., "1.23ms", "456.78μs", "789.00ns")
+ */
+export declare const formatDuration: (nanoseconds: number) => string;
+/**
+ * Format operations per second in human-readable format
+ *
+ * @param opsPerSecond - Operations per second
+ * @returns Formatted string (e.g., "1.2M ops/sec", "456K ops/sec")
+ */
+export declare const formatOpsPerSecond: (opsPerSecond: number) => string;
+/**
+ * Format percentage value
+ *
+ * @param value - Percentage value (e.g., 12.345 for 12.345%)
+ * @returns Formatted string (e.g., "12.35%")
+ */
+export declare const formatPercentage: (value: number) => string;
+/**
+ * Reporter utilities object implementing the ReporterUtils interface
+ *
+ * This object is provided to reporter plugins via the ReporterContext.
+ */
+export declare const reporterUtils: ReporterUtils;
+//# sourceMappingURL=reporter-utils.d.ts.map

package/dist/utils/reporter-utils.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter-utils.d.ts","sourceRoot":"","sources":["../../src/utils/reporter-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,4BAA2B;AAExD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAW3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,KAAG,MAUpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,cAAc,MAAM,KAAG,MAUzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MAEhD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,aAK3B,CAAC"}

package/dist/utils/reporter-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ModestBench Reporter Utilities
+ *
+ * Formatting functions for benchmark data, exported for use by third-party
+ * reporter plugins.
+ */
+import type { ReporterUtils } from "../types/plugin.js";
+/**
+ * Format bytes in human-readable format
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 GB", "256 MB", "1.2 KB")
+ */
+export declare const formatBytes: (bytes: number) => string;
+/**
+ * Format duration in human-readable format
+ *
+ * @param nanoseconds - Duration in nanoseconds
+ * @returns Formatted string (e.g., "1.23ms", "456.78μs", "789.00ns")
+ */
+export declare const formatDuration: (nanoseconds: number) => string;
+/**
+ * Format operations per second in human-readable format
+ *
+ * @param opsPerSecond - Operations per second
+ * @returns Formatted string (e.g., "1.2M ops/sec", "456K ops/sec")
+ */
+export declare const formatOpsPerSecond: (opsPerSecond: number) => string;
+/**
+ * Format percentage value
+ *
+ * @param value - Percentage value (e.g., 12.345 for 12.345%)
+ * @returns Formatted string (e.g., "12.35%")
+ */
+export declare const formatPercentage: (value: number) => string;
+/**
+ * Reporter utilities object implementing the ReporterUtils interface
+ *
+ * This object is provided to reporter plugins via the ReporterContext.
+ */
+export declare const reporterUtils: ReporterUtils;
+//# sourceMappingURL=reporter-utils.d.ts.map

package/dist/utils/reporter-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter-utils.d.ts","sourceRoot":"","sources":["../../src/utils/reporter-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,2BAA2B;AAExD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAW3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,KAAG,MAUpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,cAAc,MAAM,KAAG,MAUzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MAEhD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,aAK3B,CAAC"}

package/dist/utils/reporter-utils.js

@@ -0,0 +1,83 @@
+/**
+ * ModestBench Reporter Utilities
+ *
+ * Formatting functions for benchmark data, exported for use by third-party
+ * reporter plugins.
+ */
+/**
+ * Format bytes in human-readable format
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 GB", "256 MB", "1.2 KB")
+ */
+export const formatBytes = (bytes) => {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(1)} ${units[unitIndex]}`;
+};
+/**
+ * Format duration in human-readable format
+ *
+ * @param nanoseconds - Duration in nanoseconds
+ * @returns Formatted string (e.g., "1.23ms", "456.78μs", "789.00ns")
+ */
+export const formatDuration = (nanoseconds) => {
+    if (nanoseconds < 1000) {
+        return `${nanoseconds.toFixed(2)}ns`;
+    }
+    else if (nanoseconds < 1_000_000) {
+        return `${(nanoseconds / 1000).toFixed(2)}μs`;
+    }
+    else if (nanoseconds < 1_000_000_000) {
+        return `${(nanoseconds / 1_000_000).toFixed(2)}ms`;
+    }
+    else {
+        return `${(nanoseconds / 1_000_000_000).toFixed(2)}s`;
+    }
+};
+/**
+ * Format operations per second in human-readable format
+ *
+ * @param opsPerSecond - Operations per second
+ * @returns Formatted string (e.g., "1.2M ops/sec", "456K ops/sec")
+ */
+export const formatOpsPerSecond = (opsPerSecond) => {
+    if (opsPerSecond < 1000) {
+        return `${opsPerSecond.toFixed(2)} ops/sec`;
+    }
+    else if (opsPerSecond < 1_000_000) {
+        return `${(opsPerSecond / 1000).toFixed(2)}K ops/sec`;
+    }
+    else if (opsPerSecond < 1_000_000_000) {
+        return `${(opsPerSecond / 1_000_000).toFixed(2)}M ops/sec`;
+    }
+    else {
+        return `${(opsPerSecond / 1_000_000_000).toFixed(2)}B ops/sec`;
+    }
+};
+/**
+ * Format percentage value
+ *
+ * @param value - Percentage value (e.g., 12.345 for 12.345%)
+ * @returns Formatted string (e.g., "12.35%")
+ */
+export const formatPercentage = (value) => {
+    return `${value.toFixed(2)}%`;
+};
+/**
+ * Reporter utilities object implementing the ReporterUtils interface
+ *
+ * This object is provided to reporter plugins via the ReporterContext.
+ */
+export const reporterUtils = {
+    formatBytes,
+    formatDuration,
+    formatOpsPerSecond,
+    formatPercentage,
+};
+//# sourceMappingURL=reporter-utils.js.map

package/dist/utils/reporter-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter-utils.js","sourceRoot":"","sources":["../../src/utils/reporter-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAa,EAAU,EAAE;IACnD,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,OAAO,IAAI,IAAI,IAAI,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,IAAI,CAAC;QACb,SAAS,EAAE,CAAC;IACd,CAAC;IAED,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,WAAmB,EAAU,EAAE;IAC5D,IAAI,WAAW,GAAG,IAAI,EAAE,CAAC;QACvB,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;SAAM,IAAI,WAAW,GAAG,SAAS,EAAE,CAAC;QACnC,OAAO,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;SAAM,IAAI,WAAW,GAAG,aAAa,EAAE,CAAC;QACvC,OAAO,GAAG,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,CAAC,WAAW,GAAG,aAAa,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACxD,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,YAAoB,EAAU,EAAE;IACjE,IAAI,YAAY,GAAG,IAAI,EAAE,CAAC;QACxB,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IAC9C,CAAC;SAAM,IAAI,YAAY,GAAG,SAAS,EAAE,CAAC;QACpC,OAAO,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IACxD,CAAC;SAAM,IAAI,YAAY,GAAG,aAAa,EAAE,CAAC;QACxC,OAAO,GAAG,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IAC7D,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,CAAC,YAAY,GAAG,aAAa,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IACjE,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAU,EAAE;IACxD,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AAChC,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,WAAW;IACX,cAAc;IACd,kBAAkB;IAClB,gBAAgB;CACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modestbench",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "A full-ass benchmarking framework for Node.js",
   "repository": {
@@ -94,7 +94,7 @@
     "clean": "rm -rf dist",
     "commitlint": "commitlint",
     "dev": "zshy --watch",
-    "docs:build": "run-s docs:copy astro:build",
+    "docs:build": "run-s build:schema docs:copy astro:build",
     "docs:copy": "tsx scripts/copy-docs.ts",
     "docs:dev": "run-s docs:copy astro:dev",
     "docs:preview": "astro preview --config astro.config.js",
@@ -144,7 +144,7 @@
     "@types/node": "24.10.3",
     "@types/wallabyjs": "0.0.15",
     "@types/yargs": "17.0.35",
-    "asciinema-player": "3.12.1",
+    "asciinema-player": "3.13.2",
     "astro": "5.16.5",
     "astro-broken-link-checker": "file:./vendor/astro-broken-link-checker",
     "ava": "6.4.1",
@@ -156,7 +156,7 @@
     "globals": "16.5.0",
     "husky": "9.1.7",
     "jest": "30.2.0",
-    "knip": "5.73.1",
+    "knip": "5.73.4",
     "lint-staged": "16.2.7",
     "markdownlint-cli2": "0.20.0",
     "markdownlint-cli2-formatter-pretty": "0.0.9",

package/src/cli/commands/run.ts

@@ -7,7 +7,11 @@
 
 import { resolve } from 'node:path';
 
-import type { BenchmarkRun, ModestBenchConfig } from '../../types/index.js';
+import type {
+  BenchmarkRun,
+  ModestBenchConfig,
+  Reporter,
+} from '../../types/index.js';
 import type { CliContext } from '../index.js';
 
 import { ErrorCodes, ExitCodes } from '../../constants.js';
@@ -15,6 +19,8 @@ import { resolveOutputPath } from '../../core/output-path-resolver.js';
 import {
   type BudgetExceededError,
   InvalidArgumentError,
+  ReporterLoadError,
+  ReporterValidationError,
   UnknownReporterError,
 } from '../../errors/index.js';
 import { CsvReporter } from '../../reporters/csv.js';
@@ -22,6 +28,11 @@ 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 {
+  isBuiltInReporter,
+  isFilePath,
+  loadReporter,
+} from '../../services/reporter-loader.js';
 import { hasErrorCode, isError } from '../../utils/type-guards.js';
 
 /**
@@ -106,7 +117,7 @@ export const handleRunCommand = async (
     if (showCliMessages) {
       console.error('Setting up reporters...');
     }
-    const reporters = setupReporters(
+    const reporters = await setupReporters(
       context,
       config,
       verbose,
@@ -370,19 +381,26 @@ const loadConfiguration = async (context: CliContext, options: RunOptions) => {
 
 /**
  * Setup and configure reporters based on configuration
+ *
+ * Supports built-in reporters, registry-based custom reporters, and external
+ * reporters loaded from file paths or npm packages.
  */
-const setupReporters = (
+const setupReporters = async (
   context: CliContext,
-  config: { outputDir?: string; reporters?: string[] },
+  config: {
+    outputDir?: string;
+    reporterConfig?: Record<string, unknown>;
+    reporters?: string[];
+  },
   isVerbose: boolean,
   showCliMessages: boolean,
   explicitQuiet: boolean,
   explicitOutputDir?: string,
   explicitOutputFile?: string,
   progressOption?: boolean,
-) => {
+): Promise<Reporter[]> => {
   try {
-    const reporters = [];
+    const reporters: Reporter[] = [];
     // Dedupe requested reporters
     const requestedReporters = [...new Set(config.reporters || ['human'])];
 
@@ -398,67 +416,103 @@ const setupReporters = (
     const builtInReporters = ['human', 'json', 'csv', 'nyan', 'simple'];
 
     for (const reporterName of requestedReporters) {
-      let reporter;
-
-      // Create reporter instances with output path configuration
-      switch (reporterName) {
-        case 'csv': {
-          const outputPath = resolveOutputPath(
-            outputDir,
-            explicitOutputFile,
-            'results.csv',
-          );
-          reporter = new CsvReporter({
-            includeHeaders: true,
-            includeMetadata: true,
-            ...(outputPath ? { outputPath } : {}),
-            quiet: explicitQuiet, // Only applies explicit --quiet flag; CSV output can coexist with progress messages on different streams
-            verbose: isVerbose,
-          });
-          break;
-        }
+      let reporter: Reporter;
+
+      // Check if this is a built-in reporter
+      if (isBuiltInReporter(reporterName)) {
+        // Create reporter instances with output path configuration
+        switch (reporterName) {
+          case 'csv': {
+            const outputPath = resolveOutputPath(
+              outputDir,
+              explicitOutputFile,
+              'results.csv',
+            );
+            reporter = new CsvReporter({
+              includeHeaders: true,
+              includeMetadata: true,
+              ...(outputPath ? { outputPath } : {}),
+              quiet: explicitQuiet,
+              verbose: isVerbose,
+            });
+            break;
+          }
 
-        case 'human':
-          reporter = new HumanReporter({
-            color: true,
-            progress: progressOption ?? true,
-            quiet: explicitQuiet, // Only applies explicit --quiet flag; JSON reporter forcing quiet mode does not affect HumanReporter progress output
-            verbose: isVerbose,
-          });
-          break;
-
-        case 'json': {
-          const outputPath = resolveOutputPath(
-            outputDir,
-            explicitOutputFile,
-            'results.json',
-          );
-          reporter = new JsonReporter({
-            ...(outputPath ? { outputPath } : {}),
-            prettyPrint: true,
-          });
-          break;
-        }
+          case 'human':
+            reporter = new HumanReporter({
+              color: true,
+              progress: progressOption ?? true,
+              quiet: explicitQuiet,
+              verbose: isVerbose,
+            });
+            break;
+
+          case 'json': {
+            const outputPath = resolveOutputPath(
+              outputDir,
+              explicitOutputFile,
+              'results.json',
+            );
+            reporter = new JsonReporter({
+              ...(outputPath ? { outputPath } : {}),
+              prettyPrint: true,
+            });
+            break;
+          }
 
-        case 'nyan':
-          reporter = new NyanReporter({
-            color: true,
-            quiet: explicitQuiet,
-          });
-          break;
-
-        case 'simple':
-          reporter = new SimpleReporter({
-            quiet: explicitQuiet,
-            verbose: isVerbose,
-          });
-          break;
-
-        default:
-          // Fall back to registry for custom reporters
-          reporter = context.reporterRegistry.get(reporterName);
-          if (!reporter) {
-            // Combine built-in reporters with registered custom reporters
+          case 'nyan':
+            reporter = new NyanReporter({
+              color: true,
+              quiet: explicitQuiet,
+            });
+            break;
+
+          case 'simple':
+            reporter = new SimpleReporter({
+              quiet: explicitQuiet,
+              verbose: isVerbose,
+            });
+            break;
+
+          default:
+            // TypeScript exhaustiveness check - should never reach here
+            throw new Error(`Unhandled built-in reporter: ${reporterName}`);
+        }
+      } else if (isFilePath(reporterName)) {
+        // External reporter from file path
+        const reporterOptions =
+          (config.reporterConfig?.[reporterName] as Record<string, unknown>) ??
+          {};
+        if (showCliMessages) {
+          console.error(`Loading external reporter: ${reporterName}`);
+        }
+        reporter = await loadReporter(reporterName, reporterOptions);
+      } else {
+        // Try registry first, then npm package
+        const registryReporter = context.reporterRegistry.get(reporterName);
+        if (registryReporter) {
+          reporter = registryReporter;
+        } else {
+          // Try loading as npm package
+          const reporterOptions =
+            (config.reporterConfig?.[reporterName] as Record<
+              string,
+              unknown
+            >) ?? {};
+          if (showCliMessages) {
+            console.error(`Loading reporter package: ${reporterName}`);
+          }
+          try {
+            reporter = await loadReporter(reporterName, reporterOptions);
+          } catch (error) {
+            // If loading fails and it's not a file path, provide helpful error
+            if (
+              error instanceof ReporterLoadError ||
+              error instanceof ReporterValidationError
+            ) {
+              throw error;
+            }
+            // Combine built-in reporters with registered custom reporters for error message
             const registeredReporters = Object.keys(
               context.reporterRegistry.getAll(),
             );
@@ -467,10 +521,11 @@ const setupReporters = (
               ...registeredReporters,
             ];
             throw new UnknownReporterError(
-              `Unknown reporter: ${reporterName}. Available: ${availableReporters.join(', ')}`,
+              `Unknown reporter: ${reporterName}. Available built-in reporters: ${availableReporters.join(', ')}. ` +
+                `For external reporters, use a file path (./my-reporter.js) or npm package name.`,
             );
           }
-          break;
+        }
       }
 
       reporters.push(reporter);
@@ -484,7 +539,11 @@ const setupReporters = (
   } catch (error) {
     // Re-throw our custom errors
     const errorCode = hasErrorCode(error) ? error.code : undefined;
-    if (errorCode === ErrorCodes.REPORTER_UNKNOWN) {
+    if (
+      errorCode === ErrorCodes.REPORTER_UNKNOWN ||
+      errorCode === ErrorCodes.REPORTER_LOAD_FAILED ||
+      errorCode === ErrorCodes.REPORTER_INVALID
+    ) {
       throw error;
     }
     throw new InvalidArgumentError(

package/src/constants.ts

@@ -110,6 +110,8 @@ export const ErrorCodes = {
 
   //#region reporter-errors
   REPORTER_ALREADY_REGISTERED: 'ERR_MB_REPORTER_ALREADY_REGISTERED',
+  REPORTER_INVALID: 'ERR_MB_REPORTER_INVALID',
+  REPORTER_LOAD_FAILED: 'ERR_MB_REPORTER_LOAD_FAILED',
   REPORTER_OUTPUT_FAILED: 'ERR_MB_REPORTER_OUTPUT_FAILED',
   REPORTER_UNKNOWN: 'ERR_MB_REPORTER_UNKNOWN',
   //#endregion

package/src/errors/index.ts

@@ -53,7 +53,9 @@ export {
 // Reporter errors
 export {
   ReporterAlreadyRegisteredError,
+  ReporterLoadError,
   ReporterOutputError,
+  ReporterValidationError,
   UnknownReporterError,
 } from './reporter.js';
 

package/src/errors/reporter.ts

@@ -16,6 +16,26 @@ export class ReporterAlreadyRegisteredError extends ModestBenchError {
   readonly code = 'ERR_MB_REPORTER_ALREADY_REGISTERED';
 }
 
+/**
+ * Reporter load failed
+ *
+ * Thrown when a reporter module cannot be loaded (file not found, syntax error,
+ * invalid module format, etc.).
+ */
+export class ReporterLoadError extends ModestBenchError {
+  readonly code = 'ERR_MB_REPORTER_LOAD_FAILED';
+
+  /**
+   * The specifier (file path or package name) that failed to load
+   */
+  readonly specifier: string;
+
+  constructor(message: string, specifier: string, options?: ErrorOptions) {
+    super(`Failed to load reporter "${specifier}": ${message}`, options);
+    this.specifier = specifier;
+  }
+}
+
 /**
  * Reporter output failed
  *
@@ -25,6 +45,41 @@ export class ReporterOutputError extends ModestBenchError {
   readonly code = 'ERR_MB_REPORTER_OUTPUT_FAILED';
 }
 
+/**
+ * Reporter validation failed
+ *
+ * Thrown when a loaded module does not implement the required Reporter
+ * interface methods.
+ */
+export class ReporterValidationError extends ModestBenchError {
+  readonly code = 'ERR_MB_REPORTER_INVALID';
+
+  /**
+   * The methods that are missing from the reporter
+   */
+  readonly missingMethods: string[];
+
+  /**
+   * The specifier (file path or package name) of the invalid reporter
+   */
+  readonly specifier: string;
+
+  constructor(
+    message: string,
+    specifier: string,
+    missingMethods: string[] = [],
+    options?: ErrorOptions,
+  ) {
+    const methodsInfo =
+      missingMethods.length > 0
+        ? ` Missing required methods: ${missingMethods.join(', ')}.`
+        : '';
+    super(`Invalid reporter "${specifier}": ${message}${methodsInfo}`, options);
+    this.specifier = specifier;
+    this.missingMethods = missingMethods;
+  }
+}
+
 /**
  * Unknown reporter
  *