modestbench 0.7.0 → 0.8.0

package/dist/services/reporter-loader.cjs

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * ModestBench Reporter Loader
+ *
+ * Service for loading third-party reporter plugins from file paths or npm
+ * packages. Supports multiple export patterns: plain objects, classes, and
+ * factory functions (sync or async).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadReporter = exports.isFilePath = exports.isBuiltInReporter = exports.createReporterContext = exports.PLUGIN_API_VERSION = void 0;
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const constants_js_1 = require("../constants.cjs");
+const reporter_js_1 = require("../errors/reporter.cjs");
+const package_js_1 = require("../utils/package.cjs");
+const reporter_utils_js_1 = require("../utils/reporter-utils.cjs");
+/**
+ * Current plugin API version
+ *
+ * Increment this when making breaking changes to the plugin API.
+ */
+exports.PLUGIN_API_VERSION = 1;
+/**
+ * Set of built-in reporter names
+ */
+const BUILT_IN_REPORTERS = new Set(Object.values(constants_js_1.Reporters));
+/**
+ * Required methods that all reporters must implement
+ */
+const REQUIRED_REPORTER_METHODS = [
+    'onStart',
+    'onEnd',
+    'onError',
+    'onTaskResult',
+];
+/**
+ * Default logger implementation using console
+ *
+ * This provides a simple console-based logger for reporter plugins.
+ */
+const defaultLogger = {
+    debug: (message, ...args) => console.debug(message, ...args),
+    error: (message, ...args) => console.error(message, ...args),
+    info: (message, ...args) => console.info(message, ...args),
+    trace: (message, ...args) => console.trace(message, ...args),
+    warn: (message, ...args) => console.warn(message, ...args),
+};
+/**
+ * Create a ReporterContext for passing to plugins
+ *
+ * @param logger - Optional logger to use (defaults to console-based logger)
+ * @returns ReporterContext with version info and utilities
+ */
+const createReporterContext = (logger) => {
+    return {
+        logger: logger ?? defaultLogger,
+        pluginApiVersion: exports.PLUGIN_API_VERSION,
+        utils: reporter_utils_js_1.reporterUtils,
+        version: (0, package_js_1.getPackageVersion)(),
+    };
+};
+exports.createReporterContext = createReporterContext;
+/**
+ * Get the list of missing required methods from a reporter object
+ *
+ * @param obj - Object to check
+ * @returns Array of missing method names
+ */
+const getMissingMethods = (obj) => {
+    if (typeof obj !== 'object' || obj === null) {
+        return [...REQUIRED_REPORTER_METHODS];
+    }
+    return REQUIRED_REPORTER_METHODS.filter((method) => typeof obj[method] !== 'function');
+};
+/**
+ * Check if a specifier refers to a built-in reporter
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier is a built-in reporter name
+ */
+const isBuiltInReporter = (specifier) => {
+    return BUILT_IN_REPORTERS.has(specifier);
+};
+exports.isBuiltInReporter = isBuiltInReporter;
+/**
+ * Check if a function is a class constructor
+ *
+ * Uses heuristics to distinguish classes from regular functions:
+ *
+ * - Classes have a non-writable prototype property
+ * - Class syntax produces different toString() output
+ *
+ * @param func - Function to check
+ * @returns True if the function appears to be a class constructor
+ */
+const isClass = (func) => {
+    if (typeof func !== 'function') {
+        return false;
+    }
+    // Classes have a non-writable prototype
+    const protoDescriptor = Object.getOwnPropertyDescriptor(func, 'prototype');
+    if (!protoDescriptor || protoDescriptor.writable) {
+        return false;
+    }
+    // Check if it uses class syntax (handles both 'class Foo' and 'class{')
+    const funcStr = func.toString();
+    return /^class\b/.test(funcStr);
+};
+/**
+ * Check if a specifier looks like a file path
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier appears to be a file path
+ */
+const isFilePath = (specifier) => {
+    return (specifier.startsWith('.') ||
+        specifier.startsWith('/') ||
+        // isAbsolute handles Windows paths like 'C:\path\to\file.js'
+        (0, node_path_1.isAbsolute)(specifier));
+};
+exports.isFilePath = isFilePath;
+/**
+ * Check if an object implements the Reporter interface
+ *
+ * Validates that all required methods are present and are functions.
+ *
+ * @param obj - Object to validate
+ * @returns True if the object has all required reporter methods
+ */
+const isReporterObject = (obj) => {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    return REQUIRED_REPORTER_METHODS.every((method) => typeof obj[method] === 'function');
+};
+/**
+ * Load a reporter from a file path or npm package name
+ *
+ * Supports multiple export patterns:
+ *
+ * 1. Plain Reporter object (simplest, no options support)
+ * 2. Class constructor (instantiated with options and context)
+ * 3. Factory function (called with options and context, can be async)
+ *
+ * @example
+ *
+ * ```typescript
+ * // Load from file path
+ * const reporter = await loadReporter('./my-reporter.js', {
+ *   verbose: true,
+ * });
+ *
+ * // Load from npm package
+ * const reporter = await loadReporter('@company/custom-reporter', {
+ *   apiKey: 'xxx',
+ * });
+ * ```
+ *
+ * @param specifier - File path (relative or absolute) or npm package name
+ * @param options - Options to pass to the reporter factory/constructor
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Loaded reporter instance
+ * @throws ReporterLoadError if the module cannot be loaded
+ * @throws ReporterValidationError if the module doesn't implement Reporter
+ */
+const loadReporter = async (specifier, options = {}, cwd = process.cwd()) => {
+    const context = (0, exports.createReporterContext)();
+    const resolvedSpecifier = resolveSpecifier(specifier, cwd);
+    let module;
+    try {
+        module = await Promise.resolve(`${__rewriteRelativeImportExtension(resolvedSpecifier)}`).then(s => __importStar(require(s)));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new reporter_js_1.ReporterLoadError(message, specifier, { cause: error });
+    }
+    // Handle ESM/CJS interop - get default export if present
+    const exported = module.default ?? module;
+    // Case 1: Already a Reporter object (plain object export)
+    if (isReporterObject(exported)) {
+        return exported;
+    }
+    // Case 2: Class constructor
+    if (isClass(exported)) {
+        let instance;
+        try {
+            instance = new exported(options, context);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new reporter_js_1.ReporterLoadError(`Constructor threw error: ${message}`, specifier, { cause: error });
+        }
+        validateReporter(instance, specifier);
+        return instance;
+    }
+    // Case 3: Factory function (sync or async)
+    if (typeof exported === 'function') {
+        let result;
+        try {
+            result = await exported(options, context);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new reporter_js_1.ReporterLoadError(`Factory function threw error: ${message}`, specifier, { cause: error });
+        }
+        validateReporter(result, specifier);
+        return result;
+    }
+    // None of the above - could be an object with missing methods or invalid type
+    if (typeof exported === 'object' && exported !== null) {
+        // It's an object but missing required methods
+        const missing = getMissingMethods(exported);
+        throw new reporter_js_1.ReporterValidationError('Module does not implement Reporter interface.', specifier, missing);
+    }
+    // Completely invalid export type
+    throw new reporter_js_1.ReporterValidationError('Module must export a Reporter object, class, or factory function.', specifier);
+};
+exports.loadReporter = loadReporter;
+/**
+ * Resolve a specifier to an importable URL or module name
+ *
+ * @param specifier - File path or npm package name
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Resolved module specifier
+ */
+const resolveSpecifier = (specifier, cwd) => {
+    if ((0, exports.isFilePath)(specifier)) {
+        const absolutePath = (0, node_path_1.resolve)(cwd, specifier);
+        return (0, node_url_1.pathToFileURL)(absolutePath).href;
+    }
+    // npm package name - return as-is for dynamic import
+    return specifier;
+};
+const validateReporter = (obj, specifier) => {
+    const missing = getMissingMethods(obj);
+    if (missing.length > 0) {
+        throw new reporter_js_1.ReporterValidationError('Module does not implement Reporter interface.', specifier, missing);
+    }
+};
+//# sourceMappingURL=reporter-loader.js.map

package/dist/services/reporter-loader.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter-loader.js","sourceRoot":"","sources":["../../src/services/reporter-loader.ts"],"names":[],"mappings":"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"}

package/dist/services/reporter-loader.d.cts

@@ -0,0 +1,67 @@
+/**
+ * ModestBench Reporter Loader
+ *
+ * Service for loading third-party reporter plugins from file paths or npm
+ * packages. Supports multiple export patterns: plain objects, classes, and
+ * factory functions (sync or async).
+ */
+import type { Logger, Reporter, ReporterContext } from "../types/index.cjs";
+/**
+ * Current plugin API version
+ *
+ * Increment this when making breaking changes to the plugin API.
+ */
+export declare const PLUGIN_API_VERSION = 1;
+/**
+ * Create a ReporterContext for passing to plugins
+ *
+ * @param logger - Optional logger to use (defaults to console-based logger)
+ * @returns ReporterContext with version info and utilities
+ */
+export declare const createReporterContext: (logger?: Logger) => ReporterContext;
+/**
+ * Check if a specifier refers to a built-in reporter
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier is a built-in reporter name
+ */
+export declare const isBuiltInReporter: (specifier: string) => boolean;
+/**
+ * Check if a specifier looks like a file path
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier appears to be a file path
+ */
+export declare const isFilePath: (specifier: string) => boolean;
+/**
+ * Load a reporter from a file path or npm package name
+ *
+ * Supports multiple export patterns:
+ *
+ * 1. Plain Reporter object (simplest, no options support)
+ * 2. Class constructor (instantiated with options and context)
+ * 3. Factory function (called with options and context, can be async)
+ *
+ * @example
+ *
+ * ```typescript
+ * // Load from file path
+ * const reporter = await loadReporter('./my-reporter.js', {
+ *   verbose: true,
+ * });
+ *
+ * // Load from npm package
+ * const reporter = await loadReporter('@company/custom-reporter', {
+ *   apiKey: 'xxx',
+ * });
+ * ```
+ *
+ * @param specifier - File path (relative or absolute) or npm package name
+ * @param options - Options to pass to the reporter factory/constructor
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Loaded reporter instance
+ * @throws ReporterLoadError if the module cannot be loaded
+ * @throws ReporterValidationError if the module doesn't implement Reporter
+ */
+export declare const loadReporter: (specifier: string, options?: Record<string, unknown>, cwd?: string) => Promise<Reporter>;
+//# sourceMappingURL=reporter-loader.d.ts.map

package/dist/services/reporter-loader.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter-loader.d.ts","sourceRoot":"","sources":["../../src/services/reporter-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,2BAA0B;AAU3E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AA8BpC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,KAAG,eAOvD,CAAC;AAkBF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,WAAW,MAAM,KAAG,OAIrD,CAAC;AA+BF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,WAAW,MAAM,KAAG,OAO9C,CAAC;AAoBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY,GACvB,WAAW,MAAM,EACjB,UAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACrC,MAAK,MAAsB,KAC1B,OAAO,CAAC,QAAQ,CAmFlB,CAAC"}

package/dist/services/reporter-loader.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ModestBench Reporter Loader
+ *
+ * Service for loading third-party reporter plugins from file paths or npm
+ * packages. Supports multiple export patterns: plain objects, classes, and
+ * factory functions (sync or async).
+ */
+import type { Logger, Reporter, ReporterContext } from "../types/index.js";
+/**
+ * Current plugin API version
+ *
+ * Increment this when making breaking changes to the plugin API.
+ */
+export declare const PLUGIN_API_VERSION = 1;
+/**
+ * Create a ReporterContext for passing to plugins
+ *
+ * @param logger - Optional logger to use (defaults to console-based logger)
+ * @returns ReporterContext with version info and utilities
+ */
+export declare const createReporterContext: (logger?: Logger) => ReporterContext;
+/**
+ * Check if a specifier refers to a built-in reporter
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier is a built-in reporter name
+ */
+export declare const isBuiltInReporter: (specifier: string) => boolean;
+/**
+ * Check if a specifier looks like a file path
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier appears to be a file path
+ */
+export declare const isFilePath: (specifier: string) => boolean;
+/**
+ * Load a reporter from a file path or npm package name
+ *
+ * Supports multiple export patterns:
+ *
+ * 1. Plain Reporter object (simplest, no options support)
+ * 2. Class constructor (instantiated with options and context)
+ * 3. Factory function (called with options and context, can be async)
+ *
+ * @example
+ *
+ * ```typescript
+ * // Load from file path
+ * const reporter = await loadReporter('./my-reporter.js', {
+ *   verbose: true,
+ * });
+ *
+ * // Load from npm package
+ * const reporter = await loadReporter('@company/custom-reporter', {
+ *   apiKey: 'xxx',
+ * });
+ * ```
+ *
+ * @param specifier - File path (relative or absolute) or npm package name
+ * @param options - Options to pass to the reporter factory/constructor
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Loaded reporter instance
+ * @throws ReporterLoadError if the module cannot be loaded
+ * @throws ReporterValidationError if the module doesn't implement Reporter
+ */
+export declare const loadReporter: (specifier: string, options?: Record<string, unknown>, cwd?: string) => Promise<Reporter>;
+//# sourceMappingURL=reporter-loader.d.ts.map

package/dist/services/reporter-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter-loader.d.ts","sourceRoot":"","sources":["../../src/services/reporter-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,0BAA0B;AAU3E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AA8BpC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,KAAG,eAOvD,CAAC;AAkBF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,WAAW,MAAM,KAAG,OAIrD,CAAC;AA+BF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,WAAW,MAAM,KAAG,OAO9C,CAAC;AAoBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY,GACvB,WAAW,MAAM,EACjB,UAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACrC,MAAK,MAAsB,KAC1B,OAAO,CAAC,QAAQ,CAmFlB,CAAC"}

package/dist/services/reporter-loader.js

@@ -0,0 +1,241 @@
+/**
+ * ModestBench Reporter Loader
+ *
+ * Service for loading third-party reporter plugins from file paths or npm
+ * packages. Supports multiple export patterns: plain objects, classes, and
+ * factory functions (sync or async).
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Reporters } from "../constants.js";
+import { ReporterLoadError, ReporterValidationError, } from "../errors/reporter.js";
+import { getPackageVersion } from "../utils/package.js";
+import { reporterUtils } from "../utils/reporter-utils.js";
+/**
+ * Current plugin API version
+ *
+ * Increment this when making breaking changes to the plugin API.
+ */
+export const PLUGIN_API_VERSION = 1;
+/**
+ * Set of built-in reporter names
+ */
+const BUILT_IN_REPORTERS = new Set(Object.values(Reporters));
+/**
+ * Required methods that all reporters must implement
+ */
+const REQUIRED_REPORTER_METHODS = [
+    'onStart',
+    'onEnd',
+    'onError',
+    'onTaskResult',
+];
+/**
+ * Default logger implementation using console
+ *
+ * This provides a simple console-based logger for reporter plugins.
+ */
+const defaultLogger = {
+    debug: (message, ...args) => console.debug(message, ...args),
+    error: (message, ...args) => console.error(message, ...args),
+    info: (message, ...args) => console.info(message, ...args),
+    trace: (message, ...args) => console.trace(message, ...args),
+    warn: (message, ...args) => console.warn(message, ...args),
+};
+/**
+ * Create a ReporterContext for passing to plugins
+ *
+ * @param logger - Optional logger to use (defaults to console-based logger)
+ * @returns ReporterContext with version info and utilities
+ */
+export const createReporterContext = (logger) => {
+    return {
+        logger: logger ?? defaultLogger,
+        pluginApiVersion: PLUGIN_API_VERSION,
+        utils: reporterUtils,
+        version: getPackageVersion(),
+    };
+};
+/**
+ * Get the list of missing required methods from a reporter object
+ *
+ * @param obj - Object to check
+ * @returns Array of missing method names
+ */
+const getMissingMethods = (obj) => {
+    if (typeof obj !== 'object' || obj === null) {
+        return [...REQUIRED_REPORTER_METHODS];
+    }
+    return REQUIRED_REPORTER_METHODS.filter((method) => typeof obj[method] !== 'function');
+};
+/**
+ * Check if a specifier refers to a built-in reporter
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier is a built-in reporter name
+ */
+export const isBuiltInReporter = (specifier) => {
+    return BUILT_IN_REPORTERS.has(specifier);
+};
+/**
+ * Check if a function is a class constructor
+ *
+ * Uses heuristics to distinguish classes from regular functions:
+ *
+ * - Classes have a non-writable prototype property
+ * - Class syntax produces different toString() output
+ *
+ * @param func - Function to check
+ * @returns True if the function appears to be a class constructor
+ */
+const isClass = (func) => {
+    if (typeof func !== 'function') {
+        return false;
+    }
+    // Classes have a non-writable prototype
+    const protoDescriptor = Object.getOwnPropertyDescriptor(func, 'prototype');
+    if (!protoDescriptor || protoDescriptor.writable) {
+        return false;
+    }
+    // Check if it uses class syntax (handles both 'class Foo' and 'class{')
+    const funcStr = func.toString();
+    return /^class\b/.test(funcStr);
+};
+/**
+ * Check if a specifier looks like a file path
+ *
+ * @param specifier - Reporter name or path
+ * @returns True if the specifier appears to be a file path
+ */
+export const isFilePath = (specifier) => {
+    return (specifier.startsWith('.') ||
+        specifier.startsWith('/') ||
+        // isAbsolute handles Windows paths like 'C:\path\to\file.js'
+        isAbsolute(specifier));
+};
+/**
+ * Check if an object implements the Reporter interface
+ *
+ * Validates that all required methods are present and are functions.
+ *
+ * @param obj - Object to validate
+ * @returns True if the object has all required reporter methods
+ */
+const isReporterObject = (obj) => {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    return REQUIRED_REPORTER_METHODS.every((method) => typeof obj[method] === 'function');
+};
+/**
+ * Load a reporter from a file path or npm package name
+ *
+ * Supports multiple export patterns:
+ *
+ * 1. Plain Reporter object (simplest, no options support)
+ * 2. Class constructor (instantiated with options and context)
+ * 3. Factory function (called with options and context, can be async)
+ *
+ * @example
+ *
+ * ```typescript
+ * // Load from file path
+ * const reporter = await loadReporter('./my-reporter.js', {
+ *   verbose: true,
+ * });
+ *
+ * // Load from npm package
+ * const reporter = await loadReporter('@company/custom-reporter', {
+ *   apiKey: 'xxx',
+ * });
+ * ```
+ *
+ * @param specifier - File path (relative or absolute) or npm package name
+ * @param options - Options to pass to the reporter factory/constructor
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Loaded reporter instance
+ * @throws ReporterLoadError if the module cannot be loaded
+ * @throws ReporterValidationError if the module doesn't implement Reporter
+ */
+export const loadReporter = async (specifier, options = {}, cwd = process.cwd()) => {
+    const context = createReporterContext();
+    const resolvedSpecifier = resolveSpecifier(specifier, cwd);
+    let module;
+    try {
+        module = await import(__rewriteRelativeImportExtension(resolvedSpecifier));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ReporterLoadError(message, specifier, { cause: error });
+    }
+    // Handle ESM/CJS interop - get default export if present
+    const exported = module.default ?? module;
+    // Case 1: Already a Reporter object (plain object export)
+    if (isReporterObject(exported)) {
+        return exported;
+    }
+    // Case 2: Class constructor
+    if (isClass(exported)) {
+        let instance;
+        try {
+            instance = new exported(options, context);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ReporterLoadError(`Constructor threw error: ${message}`, specifier, { cause: error });
+        }
+        validateReporter(instance, specifier);
+        return instance;
+    }
+    // Case 3: Factory function (sync or async)
+    if (typeof exported === 'function') {
+        let result;
+        try {
+            result = await exported(options, context);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ReporterLoadError(`Factory function threw error: ${message}`, specifier, { cause: error });
+        }
+        validateReporter(result, specifier);
+        return result;
+    }
+    // None of the above - could be an object with missing methods or invalid type
+    if (typeof exported === 'object' && exported !== null) {
+        // It's an object but missing required methods
+        const missing = getMissingMethods(exported);
+        throw new ReporterValidationError('Module does not implement Reporter interface.', specifier, missing);
+    }
+    // Completely invalid export type
+    throw new ReporterValidationError('Module must export a Reporter object, class, or factory function.', specifier);
+};
+/**
+ * Resolve a specifier to an importable URL or module name
+ *
+ * @param specifier - File path or npm package name
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Resolved module specifier
+ */
+const resolveSpecifier = (specifier, cwd) => {
+    if (isFilePath(specifier)) {
+        const absolutePath = resolve(cwd, specifier);
+        return pathToFileURL(absolutePath).href;
+    }
+    // npm package name - return as-is for dynamic import
+    return specifier;
+};
+const validateReporter = (obj, specifier) => {
+    const missing = getMissingMethods(obj);
+    if (missing.length > 0) {
+        throw new ReporterValidationError('Module does not implement Reporter interface.', specifier, missing);
+    }
+};
+//# sourceMappingURL=reporter-loader.js.map