modestbench 0.0.3 → 0.1.0

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(

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);
   }

package/src/reporters/simple.ts

@@ -91,7 +91,7 @@ export class SimpleReporter extends BaseReporter {
       console.log(`${symbols.cross} Failed: ${totalFailed}`);
       console.log(`${symbols.checkmark} Passed: ${totalPassed}`);
     } else {
-      console.log(`${symbols.checkmark} All tests passed: ${totalPassed}`);
+      console.log(`${symbols.checkmark} All tasks passed: ${totalPassed}`);
     }
 
     console.log(`- Files: ${totalFiles}`);

package/src/storage/history.ts

@@ -23,6 +23,16 @@ import type {
   RetentionPolicy,
 } from '../types/index.js';
 
+import { ErrorCodes } from '../constants.js';
+import {
+  type ModestBenchError,
+  StorageCorruptionError,
+  StorageError,
+  StorageIndexError,
+  StorageSpaceError,
+  UnsupportedExportFormatError,
+} from '../errors/index.js';
+
 /**
  * Index entry for stored benchmark runs
  */
@@ -166,8 +176,9 @@ export class FileHistoryStorage implements HistoryStorage {
         removedRuns: entriesToRemove.length,
       };
     } catch (error) {
-      throw new Error(
+      throw new StorageError(
         `Failed to cleanup storage: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }
@@ -184,11 +195,21 @@ export class FileHistoryStorage implements HistoryStorage {
       } else if (format === 'csv') {
         return this.exportToCsv(runs);
       } else {
-        throw new Error(`Unsupported export format: ${format}`);
+        throw new UnsupportedExportFormatError(
+          `Unsupported export format: ${format}`,
+        );
       }
     } catch (error) {
-      throw new Error(
+      // Re-throw our custom errors
+      if (
+        (error as ModestBenchError).code ===
+        ErrorCodes.STORAGE_EXPORT_UNSUPPORTED
+      ) {
+        throw error;
+      }
+      throw new StorageError(
         `Failed to export data: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }
@@ -207,8 +228,9 @@ export class FileHistoryStorage implements HistoryStorage {
         summary: entry.summary,
       }));
     } catch (error) {
-      throw new Error(
+      throw new StorageIndexError(
         `Failed to get storage index: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }
@@ -286,13 +308,20 @@ export class FileHistoryStorage implements HistoryStorage {
 
       // Validate the loaded run
       if (!FileHistoryStorage.isValidBenchmarkRun(run)) {
-        throw new Error(`Invalid benchmark run data in file ${entry.filename}`);
+        throw new StorageCorruptionError(
+          `Invalid benchmark run data in file ${entry.filename}`,
+        );
       }
 
       return run;
     } catch (error) {
-      throw new Error(
+      // Re-throw our custom errors
+      if ((error as ModestBenchError).code === ErrorCodes.STORAGE_CORRUPTION) {
+        throw error;
+      }
+      throw new StorageError(
         `Failed to load benchmark run ${id}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }
@@ -362,8 +391,16 @@ export class FileHistoryStorage implements HistoryStorage {
 
       return runs;
     } catch (error) {
-      throw new Error(
+      // Re-throw our custom errors (from loadRun)
+      if (
+        error instanceof StorageError ||
+        error instanceof StorageCorruptionError
+      ) {
+        throw error;
+      }
+      throw new StorageError(
         `Failed to query benchmark runs: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }
@@ -384,7 +421,7 @@ export class FileHistoryStorage implements HistoryStorage {
 
       // Check file size limit
       if (Buffer.byteLength(data, 'utf8') > this.maxFileSize) {
-        throw new Error(
+        throw new StorageSpaceError(
           `Benchmark run data exceeds maximum file size of ${this.maxFileSize} bytes`,
         );
       }
@@ -395,8 +432,16 @@ export class FileHistoryStorage implements HistoryStorage {
       // Update the index
       await this.updateIndex(run, filename, Buffer.byteLength(data, 'utf8'));
     } catch (error) {
-      throw new Error(
+      // Re-throw our custom errors
+      if (
+        (error as ModestBenchError).code ===
+        ErrorCodes.STORAGE_INSUFFICIENT_SPACE
+      ) {
+        throw error;
+      }
+      throw new StorageError(
         `Failed to save benchmark run: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }
@@ -522,8 +567,9 @@ export class FileHistoryStorage implements HistoryStorage {
 
       return this.index; // We just assigned it, so it's not null
     } catch (error) {
-      throw new Error(
+      throw new StorageIndexError(
         `Failed to load storage index: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }
@@ -559,8 +605,9 @@ export class FileHistoryStorage implements HistoryStorage {
       const data = JSON.stringify(this.index, null, 2);
       writeFileSync(this.indexFile, data, 'utf8');
     } catch (error) {
-      throw new Error(
+      throw new StorageIndexError(
         `Failed to save storage index: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
       );
     }
   }

package/src/types/interfaces.ts

@@ -9,9 +9,6 @@
 import type {
   BenchmarkFile,
   BenchmarkRun,
-  ErrorContext,
-  ErrorStats,
-  ExecutionError,
   FileResult,
   ModestBenchConfig,
   SuiteResult,
@@ -102,46 +99,6 @@ export interface CsvReporter extends Reporter {
   readonly includeHeaders: boolean;
 }
 
-/**
- * Error management interface for handling execution errors
- */
-export interface ErrorManager {
-  /**
-   * Clear error history
-   */
-  clearStats(): void;
-
-  /**
-   * Format error for display
-   */
-  formatError(error: ExecutionError): string;
-
-  /**
-   * Get error code for a given error
-   */
-  getErrorCode(error: Error, context: ErrorContext): string;
-
-  /**
-   * Get error statistics
-   */
-  getStats(): ErrorStats;
-
-  /**
-   * Handle an execution error
-   */
-  handleError(error: Error, context: ErrorContext): ExecutionError;
-
-  /**
-   * Check if an error is recoverable
-   */
-  isRecoverable(error: ExecutionError): boolean;
-
-  /**
-   * Register error handler callback
-   */
-  onError(handler: (error: ExecutionError) => void): void;
-}
-
 /**
  * File loader interface for benchmark discovery and loading
  */