@machina.ai/openapi-contract-tester 2.1.0

package/dist/utils/errors.js

@@ -0,0 +1,257 @@
+/**
+ * Custom Error Classes for OpenAPI Contract Tester
+ *
+ * Provides semantic error types with error codes for better error handling
+ * and user-friendly error messages.
+ *
+ * @module utils/errors
+ */
+/**
+ * Error codes for different failure scenarios
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    // OpenAPI Parsing Errors (E001-E099)
+    ErrorCode["OPENAPI_PARSE_ERROR"] = "E001";
+    ErrorCode["OPENAPI_INVALID_SPEC"] = "E002";
+    ErrorCode["OPENAPI_UNSUPPORTED_VERSION"] = "E003";
+    ErrorCode["OPENAPI_MISSING_PATHS"] = "E004";
+    ErrorCode["OPENAPI_INVALID_SCHEMA"] = "E005";
+    // Test Generation Errors (E100-E199)
+    ErrorCode["TEST_GENERATION_FAILED"] = "E100";
+    ErrorCode["NO_ENDPOINTS_FOUND"] = "E101";
+    ErrorCode["INVALID_TEST_CATEGORY"] = "E102";
+    ErrorCode["DATA_GENERATION_FAILED"] = "E103";
+    // Test Execution Errors (E200-E299)
+    ErrorCode["TEST_EXECUTION_FAILED"] = "E200";
+    ErrorCode["HTTP_REQUEST_FAILED"] = "E201";
+    ErrorCode["TIMEOUT_ERROR"] = "E202";
+    ErrorCode["NETWORK_ERROR"] = "E203";
+    ErrorCode["AUTH_ERROR"] = "E204";
+    // Validation Errors (E300-E399)
+    ErrorCode["SCHEMA_VALIDATION_FAILED"] = "E300";
+    ErrorCode["RESPONSE_VALIDATION_FAILED"] = "E301";
+    ErrorCode["CONTRACT_VALIDATION_FAILED"] = "E302";
+    // Business Rules Errors (E400-E499)
+    ErrorCode["BUSINESS_RULES_PARSE_ERROR"] = "E400";
+    ErrorCode["BUSINESS_RULES_NOT_FOUND"] = "E401";
+    ErrorCode["BUSINESS_RULES_INVALID"] = "E402";
+    ErrorCode["DOCS_NOT_FOUND"] = "E403";
+    ErrorCode["RULES_EXTRACTION_FAILED"] = "E404";
+    // Pact Errors (E500-E599)
+    ErrorCode["PACT_GENERATION_FAILED"] = "E500";
+    ErrorCode["PACT_VERIFICATION_FAILED"] = "E501";
+    ErrorCode["PACT_BROKER_ERROR"] = "E502";
+    // MCP Server Errors (E600-E699)
+    ErrorCode["MCP_TOOL_NOT_FOUND"] = "E600";
+    ErrorCode["MCP_INVALID_ARGUMENTS"] = "E601";
+    ErrorCode["MCP_INTERNAL_ERROR"] = "E602";
+    // File System Errors (E700-E799)
+    ErrorCode["FILE_NOT_FOUND"] = "E700";
+    ErrorCode["FILE_READ_ERROR"] = "E701";
+    ErrorCode["FILE_WRITE_ERROR"] = "E702";
+    ErrorCode["DIRECTORY_NOT_FOUND"] = "E703";
+    // Generic Errors (E900-E999)
+    ErrorCode["UNKNOWN_ERROR"] = "E999";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Base error class with error code and user-friendly messages
+ */
+export class BaseError extends Error {
+    /**
+     * Error code for programmatic handling
+     */
+    code;
+    /**
+     * User-friendly error message
+     */
+    userMessage;
+    /**
+     * Additional context/metadata
+     */
+    context;
+    /**
+     * Whether this error is retryable
+     */
+    retryable;
+    constructor(code, message, userMessage, context, retryable = false) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.userMessage = userMessage;
+        this.context = context;
+        this.retryable = retryable;
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Converts error to JSON for logging/API responses
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.userMessage,
+            context: this.context,
+            retryable: this.retryable,
+        };
+    }
+}
+/**
+ * OpenAPI parsing and validation errors
+ */
+export class OpenAPIError extends BaseError {
+    constructor(code, message, userMessage, context) {
+        super(code, message, userMessage, context, false);
+    }
+}
+/**
+ * Test generation errors
+ */
+export class TestGenerationError extends BaseError {
+    constructor(code, message, userMessage, context) {
+        super(code, message, userMessage, context, false);
+    }
+}
+/**
+ * Test execution errors (potentially retryable)
+ */
+export class TestExecutionError extends BaseError {
+    constructor(code, message, userMessage, context, retryable = true) {
+        super(code, message, userMessage, context, retryable);
+    }
+}
+/**
+ * Validation errors
+ */
+export class ValidationError extends BaseError {
+    constructor(code, message, userMessage, context) {
+        super(code, message, userMessage, context, false);
+    }
+}
+/**
+ * Business rules errors
+ */
+export class BusinessRuleError extends BaseError {
+    constructor(code, message, userMessage, context) {
+        super(code, message, userMessage, context, false);
+    }
+}
+/**
+ * Pact contract testing errors
+ */
+export class PactError extends BaseError {
+    constructor(code, message, userMessage, context, retryable = false) {
+        super(code, message, userMessage, context, retryable);
+    }
+}
+/**
+ * MCP server errors
+ */
+export class MCPError extends BaseError {
+    constructor(code, message, userMessage, context) {
+        super(code, message, userMessage, context, false);
+    }
+}
+/**
+ * File system errors
+ */
+export class FileSystemError extends BaseError {
+    constructor(code, message, userMessage, context) {
+        super(code, message, userMessage, context, false);
+    }
+}
+/**
+ * Formats an error for user display (removes stack trace, sanitizes)
+ *
+ * @param error - Error to format
+ * @returns User-friendly error object
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // ... code
+ * } catch (error) {
+ *   const formatted = formatError(error);
+ *   return { success: false, error: formatted };
+ * }
+ * ```
+ */
+export function formatError(error) {
+    if (error instanceof BaseError) {
+        return {
+            code: error.code,
+            message: error.userMessage,
+            retryable: error.retryable,
+            context: error.context,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            code: ErrorCode.UNKNOWN_ERROR,
+            message: error.message,
+            retryable: false,
+        };
+    }
+    return {
+        code: ErrorCode.UNKNOWN_ERROR,
+        message: String(error),
+        retryable: false,
+    };
+}
+/**
+ * Type guard to check if error is retryable
+ *
+ * @param error - Error to check
+ * @returns True if error is retryable
+ */
+export function isRetryableError(error) {
+    return error instanceof BaseError && error.retryable;
+}
+/**
+ * Wraps a native error in appropriate custom error class
+ *
+ * @param error - Native error
+ * @param context - Additional context
+ * @returns Custom error instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fs.readFile('file.yml');
+ * } catch (error) {
+ *   throw wrapError(error, { file: 'file.yml' });
+ * }
+ * ```
+ */
+export function wrapError(error, context) {
+    if (error instanceof BaseError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        // Detect error type from message/name
+        const message = error.message.toLowerCase();
+        if (message.includes('enoent') || message.includes('file not found')) {
+            return new FileSystemError(ErrorCode.FILE_NOT_FOUND, error.message, 'The specified file could not be found', { ...context, originalError: error.name });
+        }
+        if (message.includes('timeout') || message.includes('timed out')) {
+            return new TestExecutionError(ErrorCode.TIMEOUT_ERROR, error.message, 'Request timed out. The server took too long to respond.', context, true // retryable
+            );
+        }
+        if (message.includes('network') || message.includes('econnrefused')) {
+            return new TestExecutionError(ErrorCode.NETWORK_ERROR, error.message, 'Network error occurred. Please check your connection.', context, true // retryable
+            );
+        }
+        if (message.includes('unauthorized') || message.includes('401')) {
+            return new TestExecutionError(ErrorCode.AUTH_ERROR, error.message, 'Authentication failed. Please check your credentials.', context, false // not retryable
+            );
+        }
+        // Generic unknown error
+        return new BaseError(ErrorCode.UNKNOWN_ERROR, error.message, 'An unexpected error occurred', { ...context, originalError: error.name }, false);
+    }
+    // Non-Error object thrown
+    return new BaseError(ErrorCode.UNKNOWN_ERROR, String(error), 'An unexpected error occurred', context, false);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Centralized Logger for OpenAPI Contract Tester
+ *
+ * Provides robust logging with support for:
+ * - MCP mode (writes to file, not stdout/stderr to avoid breaking STDIO protocol)
+ * - Standalone mode (uses console for development/testing)
+ * - Log levels (DEBUG, INFO, WARN, ERROR)
+ * - Structured logging (JSON format)
+ * - Automatic log rotation
+ *
+ * @module utils/logger
+ */
+/**
+ * Log levels in order of severity
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+/**
+ * Log entry structure
+ */
+export interface LogEntry {
+    /**
+     * ISO timestamp of when the log was created
+     */
+    timestamp: string;
+    /**
+     * Log level
+     */
+    level: 'debug' | 'info' | 'warn' | 'error';
+    /**
+     * Log message
+     */
+    message: string;
+    /**
+     * Optional metadata (error objects, request data, etc.)
+     */
+    meta?: unknown;
+    /**
+     * Source component that generated the log
+     */
+    source?: string;
+}
+/**
+ * Logger configuration options
+ */
+export interface LoggerConfig {
+    /**
+     * Minimum log level to record
+     * @default LogLevel.INFO
+     */
+    minLevel?: LogLevel;
+    /**
+     * Directory where log files will be stored
+     * @default './logs'
+     */
+    logDir?: string;
+    /**
+     * Base name for log files (will append date)
+     * @default 'mcp-server'
+     */
+    logFileName?: string;
+    /**
+     * Maximum log file size in bytes before rotation
+     * @default 10MB (10 * 1024 * 1024)
+     */
+    maxFileSize?: number;
+    /**
+     * Maximum number of rotated log files to keep
+     * @default 5
+     */
+    maxFiles?: number;
+    /**
+     * Whether to use console output (standalone mode)
+     * Set to false when running as MCP server
+     * @default true
+     */
+    useConsole?: boolean;
+    /**
+     * Whether to write to file
+     * @default true in MCP mode, false in standalone
+     */
+    writeToFile?: boolean;
+    /**
+     * Whether to include source location in logs
+     * @default true
+     */
+    includeSource?: boolean;
+}
+/**
+ * Centralized logger for the application
+ *
+ * @example
+ * ```typescript
+ * // Initialize for MCP mode (no console output)
+ * const logger = new Logger({
+ *   useConsole: false,
+ *   writeToFile: true,
+ *   minLevel: LogLevel.INFO
+ * });
+ *
+ * // Log messages
+ * logger.info('Server started', { port: 3000 });
+ * logger.error('Failed to parse spec', { error, file: 'api.yml' });
+ *
+ * // Log with source
+ * logger.warn('Endpoint not found', { endpoint: 'POST /users' }, 'business-rules-generator');
+ * ```
+ */
+export declare class Logger {
+    private config;
+    private currentLogFile;
+    private currentLogSize;
+    constructor(config?: LoggerConfig);
+    /**
+     * Logs a debug message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata
+     * @param source - Optional source component
+     */
+    debug(message: string, meta?: unknown, source?: string): void;
+    /**
+     * Logs an info message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata
+     * @param source - Optional source component
+     */
+    info(message: string, meta?: unknown, source?: string): void;
+    /**
+     * Logs a warning message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata
+     * @param source - Optional source component
+     */
+    warn(message: string, meta?: unknown, source?: string): void;
+    /**
+     * Logs an error message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata (can include Error object)
+     * @param source - Optional source component
+     */
+    error(message: string, meta?: unknown, source?: string): void;
+    /**
+     * Core logging method
+     * @internal
+     */
+    private log;
+    /**
+     * Writes log entry to console (for standalone mode)
+     * @internal
+     */
+    private writeToConsole;
+    /**
+     * Writes log entry to file (for MCP mode)
+     * @internal
+     */
+    private writeToFile;
+    /**
+     * Ensures log directory exists
+     * @internal
+     */
+    private ensureLogDirectory;
+    /**
+     * Gets the current log file path
+     * @internal
+     */
+    private getLogFilePath;
+    /**
+     * Rotates log files when max size is reached
+     * @internal
+     */
+    private rotateLogFile;
+    /**
+     * Removes old log files beyond maxFiles limit
+     * @internal
+     */
+    private cleanupOldLogs;
+    /**
+     * Flushes any pending logs (useful before shutdown)
+     */
+    flush(): void;
+}
+/**
+ * Global logger instance
+ *
+ * Configured from environment variables via config module:
+ * - MCP_MODE: Enable file logging (auto-detected from STDIO)
+ * - LOG_LEVEL: Minimum log level (debug, info, warn, error)
+ * - LOG_DIR or MCP_ROOT/logs: Log directory
+ * - MAX_LOG_FILE_SIZE: Maximum file size before rotation (bytes)
+ * - MAX_LOG_FILES: Number of rotated files to keep
+ */
+export declare const logger: Logger;
+/**
+ * Creates a logger with a specific source tag
+ *
+ * @param source - Source component name
+ * @returns Logger wrapper with source pre-set
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('business-rules-generator');
+ * log.info('Processing rules', { count: 20 });
+ * // Output: [2025-01-19T10:00:00Z] [INFO] [business-rules-generator] Processing rules
+ * ```
+ */
+export declare function createLogger(source: string): {
+    debug: (message: string, meta?: unknown) => void;
+    info: (message: string, meta?: unknown) => void;
+    warn: (message: string, meta?: unknown) => void;
+    error: (message: string, meta?: unknown) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;GAEG;AACH,oBAAY,QAAQ;IAClB,KAAK,IAAI;IACT,IAAI,IAAI;IACR,IAAI,IAAI;IACR,KAAK,IAAI;CACV;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAE3C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,cAAc,CAAK;gBAEf,MAAM,GAAE,YAAiB;IAmBrC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAI7D;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAI5D;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAI5D;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAI7D;;;OAGG;IACH,OAAO,CAAC,GAAG;IA8CX;;;OAGG;IACH,OAAO,CAAC,cAAc;IAgBtB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAwBnB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAKtB;;;OAGG;IACH,OAAO,CAAC,aAAa;IA0BrB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAwBtB;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd;AAoBD;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,QAOjB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;qBAEtB,MAAM,SAAS,OAAO;oBACvB,MAAM,SAAS,OAAO;oBACtB,MAAM,SAAS,OAAO;qBACrB,MAAM,SAAS,OAAO;EAE1C"}