@daghis/teamcity-mcp 0.1.2

package/src/utils/error-logger.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Error logger tests
+ */
+import { MCPToolError } from '@/middleware/error';
+import { error as logError, info as logInfo, warn as logWarn } from '@/utils/logger';
+
+import { ComponentErrorLogger, ErrorLogger, errorLogger, logStructured } from './error-logger';
+
+// Mock the logger utilities
+jest.mock('@/utils/logger', () => ({
+  error: jest.fn(),
+  warn: jest.fn(),
+  info: jest.fn(),
+}));
+
+const mockLogError = logError as jest.MockedFunction<typeof logError>;
+const mockLogWarn = logWarn as jest.MockedFunction<typeof logWarn>;
+const mockLogInfo = logInfo as jest.MockedFunction<typeof logInfo>;
+
+describe('ErrorLogger', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getInstance', () => {
+    it('should return singleton instance', () => {
+      const instance1 = ErrorLogger.getInstance();
+      const instance2 = ErrorLogger.getInstance();
+      expect(instance1).toBe(instance2);
+    });
+  });
+
+  describe('logError', () => {
+    it('should log error with context', () => {
+      const logger = ErrorLogger.getInstance();
+      const testError = new Error('Test error');
+      const context = { requestId: 'req-123', operation: 'test' };
+
+      const result = logger.logError('Test message', testError, context);
+
+      expect(result.message).toBe('Test message');
+      expect(result.stack).toBe(testError.stack);
+      expect(result.context).toEqual(context);
+      expect(result.timestamp).toBeDefined();
+      expect(mockLogError).toHaveBeenCalledWith('Test message', testError, context);
+    });
+
+    it('should handle MCP tool errors', () => {
+      const logger = ErrorLogger.getInstance();
+      const mcpError = new MCPToolError('MCP error', 'TEST_CODE', 400, { test: 'data' });
+      const context = { requestId: 'req-123' };
+
+      const result = logger.logError('MCP test', mcpError, context);
+
+      expect(result.code).toBe('TEST_CODE');
+      expect(result.context).toEqual({
+        requestId: 'req-123',
+        statusCode: 400,
+        errorData: { test: 'data' },
+      });
+    });
+
+    it('should handle non-Error objects', () => {
+      const logger = ErrorLogger.getInstance();
+      const context = { operation: 'test' };
+
+      const result = logger.logError('String error', 'some error', context);
+
+      expect(result.message).toBe('String error');
+      expect(result.stack).toBeUndefined();
+      expect(result.context).toEqual(context);
+    });
+  });
+
+  describe('logWarning', () => {
+    it('should log warning with context', () => {
+      const logger = ErrorLogger.getInstance();
+      const context = { component: 'test-component' };
+
+      logger.logWarning('Warning message', context);
+
+      expect(mockLogWarn).toHaveBeenCalledWith('Warning message', context);
+    });
+  });
+
+  describe('logInfo', () => {
+    it('should log info with context', () => {
+      const logger = ErrorLogger.getInstance();
+      const context = { operation: 'info-op' };
+
+      logger.logInfo('Info message', context);
+
+      expect(mockLogInfo).toHaveBeenCalledWith('Info message', context);
+    });
+  });
+
+  describe('forComponent', () => {
+    it('should create component logger', () => {
+      const logger = ErrorLogger.getInstance();
+      const componentLogger = logger.forComponent('TestComponent');
+
+      expect(componentLogger).toBeInstanceOf(ComponentErrorLogger);
+    });
+  });
+});
+
+describe('ComponentErrorLogger', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should log error with component context', () => {
+    const componentLogger = errorLogger.forComponent('TestComponent');
+    const testError = new Error('Component error');
+    const context = { operation: 'test-op' };
+
+    componentLogger.logError('Component message', testError, context);
+
+    expect(mockLogError).toHaveBeenCalledWith('Component message', testError, {
+      operation: 'test-op',
+      component: 'TestComponent',
+    });
+  });
+
+  it('should log warning with component context', () => {
+    const componentLogger = errorLogger.forComponent('TestComponent');
+    const context = { metadata: { key: 'value' } };
+
+    componentLogger.logWarning('Component warning', context);
+
+    expect(mockLogWarn).toHaveBeenCalledWith('Component warning', {
+      metadata: { key: 'value' },
+      component: 'TestComponent',
+    });
+  });
+
+  it('should log info with component context', () => {
+    const componentLogger = errorLogger.forComponent('TestComponent');
+
+    componentLogger.logInfo('Component info');
+
+    expect(mockLogInfo).toHaveBeenCalledWith('Component info', { component: 'TestComponent' });
+  });
+});
+
+describe('logStructured', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should log error level', () => {
+    const testError = new Error('Structured error');
+    const context = { requestId: 'req-123' };
+
+    logStructured('error', 'Structured message', testError, context);
+
+    expect(mockLogError).toHaveBeenCalledWith('Structured message', testError, context);
+  });
+
+  it('should log warning level', () => {
+    const context = { component: 'test' };
+
+    logStructured('warn', 'Warning message', undefined, context);
+
+    expect(mockLogWarn).toHaveBeenCalledWith('Warning message', context);
+  });
+
+  it('should log info level', () => {
+    logStructured('info', 'Info message');
+
+    expect(mockLogInfo).toHaveBeenCalledWith('Info message', undefined);
+  });
+});

package/src/utils/error-logger.ts

@@ -0,0 +1,145 @@
+/**
+ * Centralized error logging utility
+ * Provides structured, contextual error logging with proper formatting
+ */
+import { MCPToolError } from '@/middleware/error';
+import { error as logError, info as logInfo, warn as logWarn } from '@/utils/logger';
+
+export interface ErrorContext {
+  requestId?: string;
+  userId?: string;
+  operation?: string;
+  component?: string;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface LoggedError {
+  message: string;
+  stack?: string;
+  code?: string;
+  timestamp: string;
+  context?: ErrorContext;
+}
+
+/**
+ * Enhanced error logger with structured context
+ */
+export class ErrorLogger {
+  private static instance: ErrorLogger;
+
+  public static getInstance(): ErrorLogger {
+    if (ErrorLogger.instance == null) {
+      ErrorLogger.instance = new ErrorLogger();
+    }
+    return ErrorLogger.instance;
+  }
+
+  /**
+   * Log error with structured context
+   */
+  logError(message: string, error?: Error | unknown, context?: ErrorContext): LoggedError {
+    const loggedError: LoggedError = {
+      message,
+      timestamp: new Date().toISOString(),
+      context,
+    };
+
+    if (error instanceof Error) {
+      loggedError.stack = error.stack;
+
+      if (error instanceof MCPToolError) {
+        loggedError.code = error.code;
+        loggedError.context = {
+          ...context,
+          statusCode: error.statusCode,
+          errorData: error.data,
+        };
+      }
+    }
+
+    logError(message, error instanceof Error ? error : undefined, context);
+    return loggedError;
+  }
+
+  /**
+   * Log warning with context
+   */
+  logWarning(message: string, context?: ErrorContext): void {
+    logWarn(message, context);
+  }
+
+  /**
+   * Log info with context
+   */
+  logInfo(message: string, context?: ErrorContext): void {
+    logInfo(message, context);
+  }
+
+  /**
+   * Create error logger for a specific component
+   */
+  forComponent(componentName: string): ComponentErrorLogger {
+    return new ComponentErrorLogger(componentName, this);
+  }
+}
+
+/**
+ * Component-specific error logger
+ */
+export class ComponentErrorLogger {
+  constructor(
+    private readonly componentName: string,
+    private readonly errorLogger: ErrorLogger
+  ) {}
+
+  logError(
+    message: string,
+    error?: Error | unknown,
+    context?: Omit<ErrorContext, 'component'>
+  ): LoggedError {
+    return this.errorLogger.logError(message, error, {
+      ...context,
+      component: this.componentName,
+    });
+  }
+
+  logWarning(message: string, context?: Omit<ErrorContext, 'component'>): void {
+    this.errorLogger.logWarning(message, {
+      ...context,
+      component: this.componentName,
+    });
+  }
+
+  logInfo(message: string, context?: Omit<ErrorContext, 'component'>): void {
+    this.errorLogger.logInfo(message, {
+      ...context,
+      component: this.componentName,
+    });
+  }
+}
+
+// Export singleton instance
+export const errorLogger = ErrorLogger.getInstance();
+
+/**
+ * Helper function to replace console.log/console.error calls
+ */
+export function logStructured(
+  level: 'error' | 'warn' | 'info',
+  message: string,
+  error?: Error | unknown,
+  context?: ErrorContext
+): void {
+  switch (level) {
+    case 'error':
+      errorLogger.logError(message, error, context);
+      break;
+    case 'warn':
+      errorLogger.logWarning(message, context);
+      break;
+    case 'info':
+      errorLogger.logInfo(message, context);
+      break;
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,88 @@
+/**
+ * Utility Module Barrel Exports
+ *
+ * This file provides clean, organized exports for all utility modules,
+ * making it easy to import commonly used functions and types.
+ */
+// Logger exports - use new centralized logger
+// Import the required modules for the utilities object
+import * as asyncUtils from './async';
+import * as loggerUtils from './logger';
+import * as validationUtils from './validation';
+
+export * from './logger';
+export { getLogger, createLogger, info, error, warn, debug, child } from './logger';
+
+// Validation exports - use new validation utilities
+export * from './validation';
+export {
+  CommonSchemas,
+  validateWithSchema,
+  validateAndTransform,
+  createValidationMiddleware,
+  validateTeamCityUrl,
+  validateBuildConfigId,
+  validateBranchName,
+  validateBuildParameters,
+  sanitizeString,
+  createSanitizedStringSchema,
+  optional,
+  nullable,
+  createEnumSchema,
+} from './validation';
+export type { ValidationResult } from './validation';
+
+// Async utilities exports
+export * from './async';
+export {
+  asyncHandler,
+  safeAsyncHandler,
+  retry,
+  withTimeout,
+  sleep,
+  debounce,
+  asyncDebounce,
+  throttle,
+  parallelLimit,
+  circuitBreaker,
+  batchProcess,
+  measureTime,
+  asyncUtils,
+  CircuitBreaker,
+} from './async';
+export type {
+  RetryOptions,
+  TimeoutOptions,
+  CircuitBreakerOptions,
+  CircuitState,
+  AsyncResult,
+} from './async';
+
+// Re-export with deprecation warnings
+export * from './error-logger';
+export * from './lru-cache';
+
+// Add deprecation notice for legacy import pattern
+const warnLegacyImport = () => {
+  // Legacy import deprecation warning - removed as part of simplification
+};
+
+// Export warning function for consumers to call
+export { warnLegacyImport };
+
+// Common interface exports for better TypeScript experience
+export interface IUtilities {
+  logger: typeof loggerUtils;
+  validation: typeof validationUtils;
+  asyncUtils: typeof asyncUtils;
+}
+
+// Create a utilities object for convenient access
+export const utilities: IUtilities = {
+  logger: loggerUtils,
+  validation: validationUtils,
+  asyncUtils,
+};
+
+// Default export for convenience
+export default utilities;

package/src/utils/logger/index.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Tests for centralized logger utility
+ */
+import winston from 'winston';
+
+import { LogContext, LogLevel, TeamCityLogger, createLogger, getLogger } from './index';
+
+describe('TeamCityLogger', () => {
+  let mockLogger: jest.Mocked<winston.Logger>;
+
+  beforeEach(() => {
+    mockLogger = {
+      debug: jest.fn(),
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn(),
+      child: jest.fn(),
+      level: 'info',
+      end: jest.fn(),
+    } as unknown as jest.Mocked<winston.Logger>;
+
+    jest.spyOn(winston, 'createLogger').mockReturnValue(mockLogger);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('constructor', () => {
+    // Removed env-var dependent test: default configuration based on NODE_ENV/LOG_LEVEL
+
+    it('should create logger with custom configuration', () => {
+      const config = {
+        name: 'test-service',
+        level: 'debug' as LogLevel,
+        enableConsole: true,
+        enableFile: false,
+      };
+
+      new TeamCityLogger(config);
+
+      expect(winston.createLogger).toHaveBeenCalledWith(
+        expect.objectContaining({
+          level: 'debug',
+          defaultMeta: { service: 'test-service' },
+        })
+      );
+    });
+
+    // Removed env-var dependent test: LOG_LEVEL override from environment
+  });
+
+  describe('logging methods', () => {
+    let teamCityLogger: TeamCityLogger;
+
+    beforeEach(() => {
+      teamCityLogger = new TeamCityLogger();
+    });
+
+    it('should log debug messages', () => {
+      const context: LogContext = { toolName: 'test-tool', requestId: 'req-123' };
+
+      teamCityLogger.debug('Debug message', context);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith('Debug message', context);
+    });
+
+    it('should log info messages', () => {
+      const context: LogContext = { buildId: 'build-456' };
+
+      teamCityLogger.info('Info message', context);
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Info message', context);
+    });
+
+    it('should log warn messages', () => {
+      teamCityLogger.warn('Warning message');
+
+      expect(mockLogger.warn).toHaveBeenCalledWith('Warning message', {});
+    });
+
+    it('should log error messages with Error object', () => {
+      const error = new Error('Test error');
+      const context: LogContext = { projectId: 'proj-789' };
+
+      teamCityLogger.error('Error message', error, context);
+
+      expect(mockLogger.error).toHaveBeenCalledWith('Error message', {
+        ...context,
+        error: 'Test error',
+        stack: error.stack,
+      });
+    });
+
+    it('should log error messages with string error', () => {
+      teamCityLogger.error('Error message', 'String error');
+
+      expect(mockLogger.error).toHaveBeenCalledWith('Error message', {
+        error: 'String error',
+      });
+    });
+
+    it('should log error messages without error object', () => {
+      teamCityLogger.error('Error message');
+
+      expect(mockLogger.error).toHaveBeenCalledWith('Error message', {});
+    });
+  });
+
+  describe('utility methods', () => {
+    let teamCityLogger: TeamCityLogger;
+
+    beforeEach(() => {
+      teamCityLogger = new TeamCityLogger();
+    });
+
+    it('should generate unique request IDs', () => {
+      const id1 = teamCityLogger.generateRequestId();
+      const id2 = teamCityLogger.generateRequestId();
+
+      expect(id1).toBeDefined();
+      expect(id2).toBeDefined();
+      expect(id1).not.toBe(id2);
+      expect(id1).toMatch(/^\d+-\d+$/);
+    });
+
+    it('should create child logger', () => {
+      const childLogger = {} as winston.Logger;
+      mockLogger.child.mockReturnValue(childLogger);
+
+      const context: LogContext = { service: 'child-service' };
+      const result = teamCityLogger.child(context);
+
+      expect(mockLogger.child).toHaveBeenCalledWith(context);
+      expect(result).toBeInstanceOf(TeamCityLogger);
+    });
+
+    it('should log tool execution - success', () => {
+      const toolName = 'test-tool';
+      const args = { param1: 'value1' };
+      const result = { success: true };
+      const duration = 150;
+      const context: LogContext = { requestId: 'req-123' };
+
+      teamCityLogger.logToolExecution(toolName, args, result, duration, context);
+
+      expect(mockLogger.info).toHaveBeenCalledWith(`Tool executed successfully: ${toolName}`, {
+        ...context,
+        toolName,
+        duration,
+        args: JSON.stringify(args),
+        success: true,
+      });
+    });
+
+    it('should log tool execution - failure', () => {
+      const toolName = 'test-tool';
+      const args = { param1: 'value1' };
+      const result = { success: false, error: 'Tool failed' };
+      const duration = 75;
+
+      teamCityLogger.logToolExecution(toolName, args, result, duration);
+
+      expect(mockLogger.error).toHaveBeenCalledWith(`Tool execution failed: ${toolName}`, {
+        toolName,
+        duration,
+        args: JSON.stringify(args),
+        success: false,
+        error: 'Tool failed',
+      });
+    });
+
+    it('should log TeamCity API requests', () => {
+      const method = 'GET';
+      const url = '/api/builds';
+      const status = 200;
+      const duration = 250;
+      const context: LogContext = { requestId: 'req-456' };
+
+      teamCityLogger.logTeamCityRequest(method, url, status, duration, context);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(`TeamCity API request: ${method} ${url}`, {
+        ...context,
+        method,
+        url,
+        status,
+        duration,
+      });
+    });
+
+    it('should log failed TeamCity API requests', () => {
+      const method = 'POST';
+      const url = '/api/builds/trigger';
+      const status = 500;
+      const duration = 1000;
+
+      teamCityLogger.logTeamCityRequest(method, url, status, duration);
+
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        `TeamCity API request failed: ${method} ${url}`,
+        {
+          method,
+          url,
+          status,
+          duration,
+        }
+      );
+    });
+
+    it('should log lifecycle events', () => {
+      const event = 'server_start';
+      const details = { port: 3000, env: 'development' };
+
+      teamCityLogger.logLifecycle(event, details);
+
+      expect(mockLogger.info).toHaveBeenCalledWith(`Server lifecycle: ${event}`, {
+        lifecycle: event,
+        ...details,
+      });
+    });
+
+    it('should set and get log level', () => {
+      teamCityLogger.setLevel('debug');
+
+      expect(mockLogger.level).toBe('debug');
+      expect(teamCityLogger.getLevel()).toBe('debug');
+    });
+
+    it('should get Winston instance', () => {
+      const winston = teamCityLogger.getWinstonInstance();
+
+      expect(winston).toBe(mockLogger);
+    });
+  });
+});
+
+describe('factory functions', () => {
+  beforeEach(() => {
+    // Clear module cache to reset singleton
+    jest.clearAllMocks();
+  });
+
+  describe('createLogger', () => {
+    it('should create new logger instance', () => {
+      const logger = createLogger({ name: 'test-logger' });
+
+      expect(logger).toBeInstanceOf(TeamCityLogger);
+    });
+  });
+
+  describe('getLogger', () => {
+    it('should return singleton logger instance', () => {
+      const logger1 = getLogger();
+      const logger2 = getLogger();
+
+      expect(logger1).toBe(logger2);
+      expect(logger1).toBeInstanceOf(TeamCityLogger);
+    });
+
+    it('should create new instance with config', () => {
+      const config = { name: 'new-logger' };
+      const logger1 = getLogger();
+      const logger2 = getLogger(config);
+
+      expect(logger1).not.toBe(logger2);
+    });
+  });
+});
+
+// Convenience logger object tests removed - they're integration tests
+// The logger functionality is adequately tested through the class methods above