modestbench 0.0.2 → 0.1.0

package/src/errors/base.ts

@@ -0,0 +1,152 @@
+/**
+ * ModestBench Custom Error System
+ *
+ * Base error classes providing structured error handling with error codes,
+ * documentation URLs, and consistent error display.
+ */
+
+/**
+ * Base URL for error documentation
+ */
+const ERROR_DOC_BASE_URL =
+  'https://boneskull.github.io/modestbench/reference/errors';
+
+/**
+ * Abstract base class for ModestBench aggregate errors
+ *
+ * Extends AggregateError to support multiple errors with ModestBench error
+ * system features.
+ */
+export abstract class ModestBenchAggregateError extends AggregateError {
+  /**
+   * Unique error code for this error type Must be in format:
+   * ERR_MB_CATEGORY_DESCRIPTION
+   */
+  abstract readonly code: string;
+
+  /**
+   * Error name (matches class name)
+   */
+  public override readonly name: string;
+
+  /**
+   * Create a new ModestBench aggregate error
+   *
+   * @param errors - Array of errors that occurred
+   * @param message - Human-readable error message
+   * @param options - Optional Error options (e.g., cause)
+   */
+  constructor(errors: unknown[], message: string, options?: ErrorOptions) {
+    super(errors, message, options);
+    this.name = this.constructor.name;
+  }
+
+  /**
+   * Get the documentation URL for this error
+   *
+   * Returns a URL to the error reference page with an anchor to the specific
+   * error.
+   *
+   * @returns Documentation URL
+   */
+  getDocUrl(): string {
+    // Use the error class name as the anchor (e.g., ConfigValidationError -> #configvalidationerror)
+    const anchor = this.name.toLowerCase();
+    return `${ERROR_DOC_BASE_URL}#${anchor}`;
+  }
+
+  /**
+   * Convert error to string with code, documentation URL, and nested errors
+   *
+   * @returns Formatted error string
+   */
+  override toString(): string {
+    let result = `${this.name} [${this.code}]: ${this.message}\n`;
+    result += `See: ${this.getDocUrl()}\n`;
+
+    if (this.errors.length > 0) {
+      result += `\nContains ${this.errors.length} error(s):\n`;
+      this.errors.forEach((err, index) => {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        result += `  ${index + 1}. ${errMsg}\n`;
+      });
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Abstract base class for all ModestBench errors
+ *
+ * Provides:
+ *
+ * - Unique error codes with ERR_MB_ prefix
+ * - Documentation URL generation
+ * - Consistent error display format
+ * - TypeScript type safety
+ */
+export abstract class ModestBenchError extends Error {
+  /**
+   * Unique error code for this error type Must be in format:
+   * ERR_MB_CATEGORY_DESCRIPTION
+   */
+  abstract readonly code: string;
+
+  /**
+   * Error name (matches class name)
+   */
+  public override readonly name: string;
+
+  /**
+   * Create a new ModestBench error
+   *
+   * @param message - Human-readable error message
+   * @param options - Optional Error options (e.g., cause)
+   */
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+
+  /**
+   * Get the documentation URL for this error
+   *
+   * Returns a URL to the error reference page with an anchor to the specific
+   * error.
+   *
+   * @returns Documentation URL
+   */
+  getDocUrl(): string {
+    // Use the error class name as the anchor (e.g., ConfigValidationError -> #configvalidationerror)
+    const anchor = this.name.toLowerCase();
+    return `${ERROR_DOC_BASE_URL}#${anchor}`;
+  }
+
+  /**
+   * Convert error to string with code and documentation URL
+   *
+   * @returns Formatted error string
+   */
+  override toString(): string {
+    return `${this.name} [${this.code}]: ${this.message}\nSee: ${this.getDocUrl()}`;
+  }
+}
+
+/**
+ * Type guard to check if an error is a ModestBench error
+ *
+ * @param error - The error to check
+ * @returns True if the error is a ModestBench error
+ */
+export const isModestBenchError = (
+  error: unknown,
+): error is ModestBenchError => {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    typeof (error as { code: unknown }).code === 'string' &&
+    (error as { code: string }).code.startsWith('ERR_MB_')
+  );
+};

package/src/errors/cli.ts

@@ -0,0 +1,59 @@
+/**
+ * CLI-related errors
+ *
+ * Errors that occur during command-line interface operations.
+ */
+
+import { ModestBenchError } from './base.js';
+
+/**
+ * Invalid CLI argument
+ *
+ * Thrown when a CLI argument is invalid or cannot be parsed.
+ */
+export class InvalidArgumentError extends ModestBenchError {
+  readonly code = 'ERR_MB_CLI_INVALID_ARGUMENT';
+}
+
+/**
+ * Invalid date format
+ *
+ * Thrown when a date string cannot be parsed into a valid date.
+ */
+export class InvalidDateFormatError extends ModestBenchError {
+  readonly code = 'ERR_MB_CLI_INVALID_DATE_FORMAT';
+}
+
+/**
+ * Unknown error
+ *
+ * Thrown at the CLI boundary to wrap unexpected errors that are not ModestBench
+ * errors. This ensures all errors have proper structure and documentation
+ * links.
+ */
+export class UnknownError extends ModestBenchError {
+  readonly code = 'ERR_MB_UNKNOWN';
+
+  /**
+   * Create a new UnknownError wrapping an unexpected error
+   *
+   * @param message - The error message (typically from the original error)
+   * @param options - Error options with the original error as the cause
+   */
+  constructor(message: string, options: ErrorOptions) {
+    super(message, options);
+  }
+
+  /**
+   * Override toString to show full details of the wrapped error
+   */
+  override toString(): string {
+    let result = super.toString();
+
+    if (this.cause instanceof Error && this.cause.stack) {
+      result += '\n\nOriginal error:\n' + this.cause.stack;
+    }
+
+    return result;
+  }
+}

package/src/errors/configuration.ts

@@ -0,0 +1,45 @@
+/**
+ * Configuration-related errors
+ *
+ * Errors that occur during configuration file loading, parsing, and validation.
+ */
+
+import { ModestBenchError } from './base.js';
+
+/**
+ * Failed to load configuration
+ *
+ * Thrown when configuration loading fails for reasons other than file not found
+ * (e.g., parse errors, module loading errors).
+ */
+export class ConfigLoadError extends ModestBenchError {
+  readonly code = 'ERR_MB_CONFIG_LOAD_FAILED';
+}
+
+/**
+ * Configuration file not found
+ *
+ * Thrown when a specified configuration file cannot be found.
+ */
+export class ConfigNotFoundError extends ModestBenchError {
+  readonly code = 'ERR_MB_CONFIG_NOT_FOUND';
+}
+
+/**
+ * Configuration validation failed
+ *
+ * Thrown when a configuration file or configuration options fail schema
+ * validation.
+ */
+export class ConfigValidationError extends ModestBenchError {
+  readonly code = 'ERR_MB_CONFIG_VALIDATION_FAILED';
+}
+
+/**
+ * Unsupported configuration format
+ *
+ * Thrown when attempting to use an unsupported configuration file format.
+ */
+export class UnsupportedConfigFormatError extends ModestBenchError {
+  readonly code = 'ERR_MB_CONFIG_UNSUPPORTED_FORMAT';
+}

package/src/errors/execution.ts

@@ -0,0 +1,62 @@
+/**
+ * Execution-related errors
+ *
+ * Errors that occur during benchmark execution, setup, and teardown.
+ */
+
+import { ModestBenchError } from './base.js';
+
+/**
+ * Benchmark execution failed
+ *
+ * Thrown when overall benchmark execution fails.
+ */
+export class BenchmarkExecutionError extends ModestBenchError {
+  readonly code = 'ERR_MB_EXECUTION_BENCHMARK_FAILED';
+}
+
+/**
+ * Operation too fast to measure
+ *
+ * Thrown when a benchmark operation executes so quickly that it cannot be
+ * reliably measured (typically < 1ns per operation).
+ */
+export class OperationTooFastError extends ModestBenchError {
+  readonly code = 'ERR_MB_EXECUTION_TOO_FAST';
+}
+
+/**
+ * Setup function failed
+ *
+ * Thrown when a benchmark setup function fails.
+ */
+export class SetupError extends ModestBenchError {
+  readonly code = 'ERR_MB_EXECUTION_SETUP_FAILED';
+}
+
+/**
+ * Task execution failed
+ *
+ * Thrown when a specific benchmark task fails during execution.
+ */
+export class TaskExecutionError extends ModestBenchError {
+  readonly code = 'ERR_MB_EXECUTION_TASK_FAILED';
+}
+
+/**
+ * Teardown function failed
+ *
+ * Thrown when a benchmark teardown function fails.
+ */
+export class TeardownError extends ModestBenchError {
+  readonly code = 'ERR_MB_EXECUTION_TEARDOWN_FAILED';
+}
+
+/**
+ * Execution timeout exceeded
+ *
+ * Thrown when a benchmark operation exceeds the configured timeout.
+ */
+export class TimeoutError extends ModestBenchError {
+  readonly code = 'ERR_MB_EXECUTION_TIMEOUT';
+}

package/src/errors/file.ts

@@ -0,0 +1,53 @@
+/**
+ * File-related errors
+ *
+ * Errors that occur during file discovery, loading, and access.
+ */
+
+import { ModestBenchError } from './base.js';
+
+/**
+ * File discovery failed
+ *
+ * Thrown when file discovery/glob pattern matching fails.
+ */
+export class FileDiscoveryError extends ModestBenchError {
+  readonly code = 'ERR_MB_FILE_DISCOVERY_FAILED';
+}
+
+/**
+ * Failed to load benchmark file
+ *
+ * Thrown when loading a benchmark file fails (e.g., import errors, syntax
+ * errors).
+ */
+export class FileLoadError extends ModestBenchError {
+  readonly code = 'ERR_MB_FILE_LOAD_FAILED';
+}
+
+/**
+ * Benchmark file not found
+ *
+ * Thrown when a benchmark file cannot be found or does not exist.
+ */
+export class FileNotFoundError extends ModestBenchError {
+  readonly code = 'ERR_MB_FILE_NOT_FOUND';
+}
+
+/**
+ * File permission denied
+ *
+ * Thrown when file access is denied due to insufficient permissions.
+ */
+export class FilePermissionError extends ModestBenchError {
+  readonly code = 'ERR_MB_FILE_PERMISSION_DENIED';
+}
+
+/**
+ * Unsupported file extension
+ *
+ * Thrown when attempting to load a file with an unsupported extension.
+ */
+export class UnsupportedFileExtensionError extends ModestBenchError {
+  readonly code = 'ERR_MB_FILE_UNSUPPORTED_EXTENSION';
+}

package/src/errors/index.ts

@@ -0,0 +1,71 @@
+/**
+ * ModestBench Error Classes
+ *
+ * Custom error classes for structured error handling throughout ModestBench.
+ * All errors extend ModestBenchError and include error codes and documentation
+ * URLs.
+ */
+
+// Base error classes and utilities
+export {
+  isModestBenchError,
+  ModestBenchAggregateError,
+  ModestBenchError,
+} from './base.js';
+
+// CLI errors
+export {
+  InvalidArgumentError,
+  InvalidDateFormatError,
+  UnknownError,
+} from './cli.js';
+
+// Configuration errors
+export {
+  ConfigLoadError,
+  ConfigNotFoundError,
+  ConfigValidationError,
+  UnsupportedConfigFormatError,
+} from './configuration.js';
+
+// Execution errors
+export {
+  BenchmarkExecutionError,
+  OperationTooFastError,
+  SetupError,
+  TaskExecutionError,
+  TeardownError,
+  TimeoutError,
+} from './execution.js';
+
+// File errors
+export {
+  FileDiscoveryError,
+  FileLoadError,
+  FileNotFoundError,
+  FilePermissionError,
+  UnsupportedFileExtensionError,
+} from './file.js';
+
+// Reporter errors
+export {
+  ReporterAlreadyRegisteredError,
+  ReporterOutputError,
+  UnknownReporterError,
+} from './reporter.js';
+
+// Storage errors
+export {
+  StorageCorruptionError,
+  StorageError,
+  StorageIndexError,
+  StorageSpaceError,
+  UnsupportedExportFormatError,
+} from './storage.js';
+
+// Validation errors
+export {
+  SchemaValidationError,
+  StructureValidationError,
+  TypeValidationError,
+} from './validation.js';

package/src/errors/reporter.ts

@@ -0,0 +1,35 @@
+/**
+ * Reporter-related errors
+ *
+ * Errors that occur during reporter operations.
+ */
+
+import { ModestBenchError } from './base.js';
+
+/**
+ * Reporter already registered
+ *
+ * Thrown when attempting to register a reporter with a name that is already in
+ * use.
+ */
+export class ReporterAlreadyRegisteredError extends ModestBenchError {
+  readonly code = 'ERR_MB_REPORTER_ALREADY_REGISTERED';
+}
+
+/**
+ * Reporter output failed
+ *
+ * Thrown when a reporter fails to write output.
+ */
+export class ReporterOutputError extends ModestBenchError {
+  readonly code = 'ERR_MB_REPORTER_OUTPUT_FAILED';
+}
+
+/**
+ * Unknown reporter
+ *
+ * Thrown when attempting to use a reporter that is not registered.
+ */
+export class UnknownReporterError extends ModestBenchError {
+  readonly code = 'ERR_MB_REPORTER_UNKNOWN';
+}

package/src/errors/storage.ts

@@ -0,0 +1,52 @@
+/**
+ * Storage-related errors
+ *
+ * Errors that occur during history storage operations.
+ */
+
+import { ModestBenchError } from './base.js';
+
+/**
+ * Storage data corruption
+ *
+ * Thrown when stored data is found to be corrupted or invalid.
+ */
+export class StorageCorruptionError extends ModestBenchError {
+  readonly code = 'ERR_MB_STORAGE_CORRUPTION';
+}
+
+/**
+ * Storage operation failed
+ *
+ * Thrown when a general storage operation fails.
+ */
+export class StorageError extends ModestBenchError {
+  readonly code = 'ERR_MB_STORAGE_FAILED';
+}
+
+/**
+ * Storage index corruption
+ *
+ * Thrown when the storage index is corrupted or cannot be read.
+ */
+export class StorageIndexError extends ModestBenchError {
+  readonly code = 'ERR_MB_STORAGE_INDEX_CORRUPTION';
+}
+
+/**
+ * Insufficient storage space
+ *
+ * Thrown when there is insufficient disk space for storage operations.
+ */
+export class StorageSpaceError extends ModestBenchError {
+  readonly code = 'ERR_MB_STORAGE_INSUFFICIENT_SPACE';
+}
+
+/**
+ * Unsupported export format
+ *
+ * Thrown when attempting to export data in an unsupported format.
+ */
+export class UnsupportedExportFormatError extends ModestBenchError {
+  readonly code = 'ERR_MB_STORAGE_EXPORT_UNSUPPORTED';
+}

package/src/errors/validation.ts

@@ -0,0 +1,35 @@
+/**
+ * Validation-related errors
+ *
+ * Errors that occur during benchmark file structure and data validation.
+ */
+
+import { ModestBenchError } from './base.js';
+
+/**
+ * Schema validation failed
+ *
+ * Thrown when data fails to validate against a Zod schema or other schema
+ * validation.
+ */
+export class SchemaValidationError extends ModestBenchError {
+  readonly code = 'ERR_MB_VALIDATION_SCHEMA_FAILED';
+}
+
+/**
+ * Invalid benchmark structure
+ *
+ * Thrown when a benchmark file has an invalid or unexpected structure.
+ */
+export class StructureValidationError extends ModestBenchError {
+  readonly code = 'ERR_MB_VALIDATION_STRUCTURE_INVALID';
+}
+
+/**
+ * Type validation failed
+ *
+ * Thrown when data fails type validation checks.
+ */
+export class TypeValidationError extends ModestBenchError {
+  readonly code = 'ERR_MB_VALIDATION_TYPE_FAILED';
+}

package/src/index.ts

@@ -14,9 +14,6 @@ export { ModestBenchConfigurationManager } from './config/manager.js';
 export { ModestBenchEngine } from './core/engine.js';
 export { AccurateEngine, TinybenchEngine } from './core/engines/index.js';
 
-// Error handling
-export { ModestBenchErrorManager } from './core/error-manager.js';
-
 export { BenchmarkFileLoader } from './core/loader.js';
 
 // Statistical utilities
@@ -26,6 +23,9 @@ export {
   type SampleStatistics,
 } from './core/stats-utils.js';
 
+// Error classes
+export * from './errors/index.js';
+
 // Progress tracking
 export { ModestBenchProgressManager } from './progress/manager.js';
 // Reporters

package/src/reporters/csv.ts

@@ -17,6 +17,7 @@ import type {
   TaskResult,
 } from '../types/index.js';
 
+import { ReporterOutputError } from '../errors/index.js';
 import { BaseReporter } from './registry.js';
 
 /**
@@ -340,7 +341,7 @@ export class CsvReporter extends BaseReporter {
    */
   private async writeToFile(csvContent: string): Promise<void> {
     if (!this.outputPath) {
-      throw new Error('Output path not specified');
+      throw new ReporterOutputError('Output path not specified');
     }
 
     try {
@@ -351,8 +352,9 @@ export class CsvReporter extends BaseReporter {
       // Write CSV file
       writeFileSync(this.outputPath, csvContent, 'utf8');
     } catch (error) {
-      throw new Error(
+      throw new ReporterOutputError(
         `Failed to write CSV output to ${this.outputPath}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }

package/src/reporters/human.ts

@@ -157,7 +157,7 @@ export class HumanReporter extends BaseReporter {
       );
     } else {
       this.printLine(
-        `${this.colorize('brightCyan', ansiChars.checkmark + ' All tests passed:')} ${this.colorize('brightWhite', String(totalPassed))}`,
+        `${this.colorize('brightCyan', ansiChars.checkmark + ' All tasks passed:')} ${this.colorize('brightWhite', String(totalPassed))}`,
       );
     }
     this.printLine(
@@ -317,7 +317,7 @@ export class HumanReporter extends BaseReporter {
     \x1b[48;5;0m \x1b[48;5;14m  \x1b[38;5;237;48;5;45m▄\x1b[38;5;14;48;5;23m▄\x1b[48;5;14m       \x1b[38;5;14;48;5;14m▄\x1b[38;5;53;48;5;38m▄\x1b[38;5;44;48;5;23m▄\x1b[38;5;198;48;5;238m▄\x1b[38;5;198;48;5;125m▄\x1b[38;5;23;48;5;14m▄\x1b[48;5;14m  \x1b[48;5;0m \x1b[m
     \x1b[48;5;0m \x1b[48;5;14m \x1b[38;5;30;48;5;38m▄\x1b[38;5;14;48;5;14m▄\x1b[48;5;14m      \x1b[38;5;45;48;5;14m▄\x1b[38;5;89;48;5;14m▄\x1b[38;5;89;48;5;89m▄\x1b[38;5;14;48;5;31m▄\x1b[48;5;14m \x1b[38;5;37;48;5;89m▄\x1b[48;5;198m \x1b[38;5;198;48;5;198m▄\x1b[38;5;31;48;5;14m▄\x1b[48;5;14m \x1b[48;5;0m \x1b[m \x1b[2mnode.js:\x1b[m \x1b[36m${run.environment.nodeVersion} \x1b[m
     \x1b[48;5;0m \x1b[48;5;14m \x1b[38;5;44;48;5;31m▄\x1b[48;5;14m      \x1b[38;5;126;48;5;38m▄\x1b[38;5;198;48;5;237m▄\x1b[38;5;237;48;5;37m▄\x1b[48;5;14m   \x1b[38;5;14;48;5;14m▄\x1b[38;5;162;48;5;198m▄▄\x1b[38;5;53;48;5;240m▄\x1b[48;5;14m \x1b[48;5;0m \x1b[m \x1b[2mplatform:\x1b[m \x1b[36m${run.environment.platform} ${run.environment.arch} \x1b[m
-    \x1b[48;5;0m \x1b[38;5;45;48;5;14m▄\x1b[48;5;14m       \x1b[38;5;14;48;5;37m▄\x1b[38;5;14;48;5;5m▄\x1b[38;5;14;48;5;44m▄\x1b[48;5;14m       \x1b[38;5;45;48;5;14m▄\x1b[48;5;0m \x1b[m \x1b[2mcpu:\x1b[m \x1b[36m${run.environment.cpu.model} \x1b[2m(\x1b[m\x1b[36m${run.environment.cpu.cores} cores) \x1b[m
+    \x1b[48;5;0m \x1b[38;5;45;48;5;14m▄\x1b[48;5;14m       \x1b[38;5;14;48;5;37m▄\x1b[38;5;14;48;5;5m▄\x1b[38;5;14;48;5;44m▄\x1b[48;5;14m       \x1b[38;5;45;48;5;14m▄\x1b[48;5;0m \x1b[m \x1b[2mcpu:\x1b[m \x1b[36m${run.environment.cpu.model} \x1b[2m(\x1b[m\x1b[36m${run.environment.cpu.cores} cores\x1b[2m) \x1b[m
     \x1b[49;38;5;0m▀▀\x1b[38;5;0;48;5;6m▄\x1b[38;5;232;48;5;14m▄\x1b[38;5;38;48;5;14m▄\x1b[48;5;14m           \x1b[38;5;30;48;5;14m▄\x1b[38;5;0;48;5;14m▄\x1b[38;5;0;48;5;23m▄\x1b[49;38;5;0m▀▀\x1b[m \x1b[2mmem:\x1b[m \x1b[36m${this.formatBytes(run.environment.memory.total)} \x1b[m
     \x1b[49m    \x1b[49;38;5;0m▀\x1b[38;5;0;48;5;236m▄\x1b[38;5;0;48;5;45m▄\x1b[38;5;23;48;5;14m▄\x1b[48;5;14m     \x1b[38;5;236;48;5;14m▄\x1b[38;5;0;48;5;44m▄\x1b[38;5;0;48;5;232m▄\x1b[49;38;5;0m▀\x1b[49m    \x1b[m
     \x1b[49m       \x1b[49;38;5;0m▀▀\x1b[38;5;0;48;5;37m▄\x1b[38;5;0;48;5;14m▄\x1b[38;5;0;48;5;30m▄\x1b[49;38;5;0m▀▀\x1b[49m       \x1b[m

package/src/reporters/json.ts

@@ -16,6 +16,7 @@ import type {
   TaskResult,
 } from '../types/index.js';
 
+import { ReporterOutputError } from '../errors/index.js';
 import { BaseReporter } from './registry.js';
 
 /**
@@ -266,7 +267,7 @@ export class JsonReporter extends BaseReporter {
    */
   private async writeToFile(output: JsonOutput): Promise<void> {
     if (!this.outputPath) {
-      throw new Error('Output path not specified');
+      throw new ReporterOutputError('Output path not specified');
     }
 
     try {
@@ -281,8 +282,9 @@ export class JsonReporter extends BaseReporter {
 
       writeFileSync(this.outputPath, jsonString, 'utf8');
     } catch (error) {
-      throw new Error(
+      throw new ReporterOutputError(
         `Failed to write JSON output to ${this.outputPath}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }

package/src/reporters/registry.ts

@@ -15,6 +15,11 @@ import type {
   TaskResult,
 } from '../types/index.js';
 
+import {
+  ReporterAlreadyRegisteredError,
+  UnknownReporterError,
+} from '../errors/index.js';
+
 /**
  * Base abstract reporter class providing common functionality
  */
@@ -301,7 +306,7 @@ export class ModestBenchReporterRegistry implements ReporterRegistry {
     }
 
     if (missing.length > 0) {
-      throw new Error(
+      throw new UnknownReporterError(
         `Unknown reporters: ${missing.join(', ')}. Available: ${Array.from(this.reporters.keys()).join(', ')}`,
       );
     }
@@ -328,7 +333,9 @@ export class ModestBenchReporterRegistry implements ReporterRegistry {
    */
   register(name: string, reporter: Reporter): void {
     if (this.reporters.has(name)) {
-      throw new Error(`Reporter with name "${name}" is already registered`);
+      throw new ReporterAlreadyRegisteredError(
+        `Reporter with name "${name}" is already registered`,
+      );
     }
     this.reporters.set(name, reporter);
   }