@gguf/coder 0.3.0 → 0.3.1

package/source/utils/logging/index.ts

@@ -0,0 +1,236 @@
+/**
+ * Main logging interface with facade pattern for backward compatibility
+ * Uses dependency injection pattern to avoid circular dependencies
+ */
+
+import {loggerProvider} from './logger-provider';
+import type {LogLevel, Logger, LoggerConfig} from './types';
+
+/**
+ * Initialize the logger with configuration
+ */
+export function initializeLogger(config?: Partial<LoggerConfig>): Logger {
+	return loggerProvider.initializeLogger(config);
+}
+
+/**
+ * Get the current logger instance
+ */
+export function getLogger(): Logger {
+	return loggerProvider.getLogger();
+}
+
+/**
+ * Get the current configuration
+ */
+export function getLoggerConfig(): LoggerConfig | null {
+	return loggerProvider.getLoggerConfig();
+}
+
+/**
+ * Create a child logger with additional context
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic bindings for logger context
+export function createChildLogger(bindings: Record<string, any>): Logger {
+	return loggerProvider.createChildLogger(bindings);
+}
+
+/**
+ * Check if a log level is enabled
+ */
+export function isLevelEnabled(level: LogLevel): boolean {
+	return loggerProvider.isLevelEnabled(level);
+}
+
+/**
+ * Convenience methods that match console.log API
+ */
+export const log = {
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for logger methods
+	fatal: (msg: string, ...args: any[]) => getLogger().fatal(msg, ...args),
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for logger methods
+	error: (msg: string, ...args: any[]) => getLogger().error(msg, ...args),
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for logger methods
+	warn: (msg: string, ...args: any[]) => getLogger().warn(msg, ...args),
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for logger methods
+	info: (msg: string, ...args: any[]) => getLogger().info(msg, ...args),
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for logger methods
+	http: (msg: string, ...args: any[]) => getLogger().http(msg, ...args),
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for logger methods
+	debug: (msg: string, ...args: any[]) => getLogger().debug(msg, ...args),
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for logger methods
+	trace: (msg: string, ...args: any[]) => getLogger().trace(msg, ...args),
+};
+
+/**
+ * Backward compatibility facade - wraps console during transition
+ * This will be gradually replaced with structured logging
+ */
+export const console = {
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for console compatibility
+	log: (...args: any[]) => {
+		// For now, use info level for console.log
+		log.info(args.join(' '));
+
+		// TODO: Add deprecation warning in development mode
+		if (process.env.NODE_ENV === 'development') {
+			process.stderr.write(
+				'\x1b[33m[DEPRECATED]\x1b[0m console.log() is deprecated. Use logger.info() instead.\n',
+			);
+		}
+	},
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for console compatibility
+	error: (...args: any[]) => {
+		log.error(args.join(' '));
+	},
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for console compatibility
+	warn: (...args: any[]) => {
+		log.warn(args.join(' '));
+	},
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for console compatibility
+	info: (...args: any[]) => {
+		log.info(args.join(' '));
+	},
+	// biome-ignore lint/suspicious/noExplicitAny: Variadic arguments for console compatibility
+	debug: (...args: any[]) => {
+		log.debug(args.join(' '));
+	},
+};
+
+/**
+ * Flush any pending logs
+ */
+export async function flush(): Promise<void> {
+	await loggerProvider.flush();
+}
+
+/**
+ * End the logger and close all streams
+ */
+export async function end(): Promise<void> {
+	await loggerProvider.end();
+}
+
+// Setup graceful shutdown handlers
+process.on('SIGTERM', () => {
+	void (async () => {
+		log.info('\n[LOGGER] Received SIGTERM, flushing logs...');
+		await flush();
+		await end();
+		log.info('[LOGGER] Graceful shutdown completed');
+	})();
+});
+
+process.on('SIGINT', () => {
+	void (async () => {
+		log.info('\n[LOGGER] Received SIGINT, flushing logs...');
+		await flush();
+		await end();
+		log.info('[LOGGER] Graceful shutdown completed');
+	})();
+});
+
+// Handle uncaught exceptions and unhandled rejections
+process.on('uncaughtException', err => {
+	void (async () => {
+		const logger = getLogger();
+		logger.fatal({err}, 'Uncaught exception');
+		await flush();
+		process.exit(1);
+	})();
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+	void (async () => {
+		const logger = getLogger();
+		logger.fatal({reason, promise}, 'Unhandled promise rejection');
+		await flush();
+		process.exit(1);
+	})();
+});
+
+// Re-export all modules for external use
+export type {Logger, LoggerConfig, LogLevel} from './types.js';
+
+// Export for testing purposes only
+export {
+	/** @internal */
+	createCorrelationFromHeaders,
+	/** @internal */
+	extractCorrelationId,
+	/** @internal */
+	formatCorrelationForLog,
+	/** @internal */
+	correlationMiddleware,
+} from './correlation.js';
+
+// Export correlation utilities
+export {
+	generateCorrelationId,
+	withNewCorrelationContext,
+	getCorrelationId,
+} from './correlation.js';
+
+// Export performance utilities
+export {
+	startMetrics,
+	endMetrics,
+	calculateMemoryDelta,
+	formatMemoryUsage,
+	/** @internal */
+	formatBytes,
+	/** @internal */
+	globalPerformanceMonitor,
+} from './performance.js';
+
+// Export configuration utilities
+export {
+	/** @internal */
+	getDefaultLogDirectory,
+	/** @internal */
+	getEnvironmentConfig,
+	/** @internal */
+	validateLogLevel,
+	/** @internal */
+	normalizeLogLevel,
+	/** @internal */
+	createConfig,
+} from './config.js';
+
+// Export transport utilities (used internally only)
+// No exports from transports.js as they are only used internally
+
+// Console facade exports (only used in tests)
+// No exports from console-facade.js as they are only used internally and in tests
+
+// Export request tracking utilities (specific instances used by other modules)
+export {healthChecks} from './health-monitor/index.js';
+
+// Internal exports that knip should ignore
+/** @internal */
+export {httpTracker} from './request-tracker.js';
+
+/** @internal */
+export {aiTracker} from './request-tracker.js';
+
+/** @internal */
+export {mcpTracker} from './request-tracker.js';
+
+export {globalRequestTracker} from './request-tracker.js';
+
+// Export log storage for tests
+export {globalLogStorage} from './log-query/index.js';
+
+// RequestTracker is only used internally as default export
+// No export needed here
+
+// Log query exports (not used in main codebase)
+// No exports from log-query.js as they are not used
+
+// Export health monitoring
+export {
+	type HealthCheckResult,
+	type HealthCheck,
+	type SystemMetrics,
+	type HealthCheckConfig,
+} from './health-monitor/index.js';

package/source/utils/logging/integration.spec.ts

@@ -0,0 +1,441 @@
+import {existsSync, mkdirSync, rmSync, writeFileSync} from 'fs';
+import {tmpdir} from 'os';
+import {join} from 'path';
+import test from 'ava';
+
+console.log(`\nlogging/integration.spec.ts`);
+
+// Integration tests for the complete logging system
+import {
+	end,
+	flush,
+	getLogger,
+	globalLogStorage,
+	globalRequestTracker,
+	healthChecks,
+	initializeLogger,
+} from './index.js';
+
+// Import correlation functionality
+import {
+	generateCorrelationId,
+	getCorrelationId,
+	withNewCorrelationContext,
+} from './correlation.js';
+
+// Import redaction
+import {
+	createRedactionRules,
+	redactEmail,
+	redactLogEntry,
+	redactValue,
+} from './redaction.js';
+
+// Create a temporary test directory
+const testDir = join(tmpdir(), `coder-logging-integration-${Date.now()}`);
+
+test.before(() => {
+	mkdirSync(testDir, {recursive: true});
+	process.env.NODE_ENV = 'test';
+	process.env.CODER_LOG_LEVEL = 'debug';
+});
+
+test.after.always(async () => {
+	// Clean up
+	if (existsSync(testDir)) {
+		rmSync(testDir, {recursive: true, force: true});
+	}
+
+	// Reset logger state
+	await end();
+});
+
+test('end-to-end logging workflow', async t => {
+	// Initialize logger with test configuration
+	const logger = initializeLogger({
+		level: 'debug',
+		pretty: false,
+		correlation: true,
+		redact: ['apiKey', 'password'],
+	});
+
+	t.truthy(logger, 'Logger should be initialized');
+
+	// Test basic logging
+	logger.info('Integration test started');
+	logger.warn('Warning message', {code: 'TEST_WARNING'});
+	logger.error('Error message', {error: new Error('Test error')});
+
+	// Test correlation context
+	const correlationId = generateCorrelationId();
+	t.truthy(correlationId, 'Should generate correlation ID');
+
+	await withNewCorrelationContext(
+		async () => {
+			const contextCorrelationId = getCorrelationId();
+			t.truthy(contextCorrelationId, 'Should have correlation ID in context');
+
+			logger.info('Message with correlation context', {action: 'test'});
+		},
+		correlationId,
+		{userId: 'test-user'},
+	);
+
+	// Test redaction
+	const sensitiveData = {
+		username: 'testuser',
+		apiKey: 'secret-key-123',
+		password: 'secret-pass',
+		email: 'test@example.com',
+	};
+
+	// Test redactLogEntry with proper redaction rules
+	const rules = createRedactionRules(['apiKey', 'password']);
+	const redactedData = redactLogEntry(sensitiveData, rules) as any;
+	t.is(
+		redactedData.username,
+		'testuser',
+		'Should preserve non-sensitive fields',
+	);
+	t.true(
+		redactedData.apiKey === '[REDACTED]' || redactedData.apiKey.includes('*'),
+		'Should redact apiKey',
+	);
+	t.true(
+		redactedData.password === '[REDACTED]' ||
+			redactedData.password.includes('*'),
+		'Should redact password',
+	);
+	t.is(
+		sensitiveData.email,
+		'test@example.com',
+		'Should preserve non-redacted fields',
+	);
+
+	// Test PII detection
+	const piiData = {
+		email: 'user@domain.com',
+		phone: '+1-555-123-4567',
+		ssn: '123-45-6789',
+		normalField: 'safe data',
+	};
+
+	const redactedSsn = redactValue(piiData.ssn) as string;
+	const maskedEmail = redactEmail(piiData.email);
+	t.true(typeof maskedEmail === 'string', 'Should return masked email');
+	t.is(
+		redactedSsn,
+		'123-45-6789',
+		'Should preserve SSN (not in sensitive patterns)',
+	);
+	t.is(piiData.normalField, 'safe data', 'Should preserve safe data');
+
+	// Test log storage
+	globalLogStorage.addEntry({
+		timestamp: new Date().toISOString(),
+		level: 'info',
+		message: 'Test entry',
+		correlationId,
+		metadata: {test: true},
+	});
+
+	const logs = globalLogStorage.query({limit: 10});
+	t.true(logs.entries.length > 0, 'Should store log entries');
+
+	// Test request tracking
+	const requestId = globalRequestTracker.startRequest({
+		type: 'http',
+		method: 'GET',
+		endpoint: '/api/test',
+	});
+
+	t.truthy(requestId, 'Should start request tracking');
+
+	globalRequestTracker.completeRequest(requestId);
+	const stats = globalRequestTracker.getStats();
+	t.true(stats.totalRequests >= 1, 'Should track request statistics');
+
+	// Test health checks
+	const health = await healthChecks.quick();
+	t.true(health === 'healthy', 'Health check should pass');
+
+	const metrics = healthChecks.metrics();
+	t.truthy(metrics, 'Should return health metrics');
+
+	// Test logger cleanup
+	await flush();
+	await end();
+
+	t.pass('End-to-end workflow completed successfully');
+});
+
+test('logging system handles high volume gracefully', async t => {
+	const logger = initializeLogger({level: 'info', pretty: false});
+
+	const startTime = performance.now();
+	const messageCount = 1000;
+
+	// Generate high volume of logs
+	for (let i = 0; i < messageCount; i++) {
+		logger.info(`High volume test message ${i}`, {
+			batchId: 'test-batch',
+			index: i,
+			timestamp: new Date().toISOString(),
+		});
+	}
+
+	const endTime = performance.now();
+	const duration = endTime - startTime;
+	const avgTime = duration / messageCount;
+
+	// Should handle high volume efficiently (less than 1ms per log)
+	t.true(
+		avgTime < 1,
+		`Should handle high volume efficiently (${avgTime.toFixed(
+			4,
+		)}ms per message)`,
+	);
+
+	await end();
+});
+
+test('multiple concurrent logging contexts', async t => {
+	const logger = initializeLogger({
+		level: 'debug',
+		correlation: true,
+	});
+
+	const promises = [];
+	const contexts = 10;
+	const messagesPerContext = 50;
+
+	// Create multiple concurrent logging contexts
+	for (let ctx = 0; ctx < contexts; ctx++) {
+		promises.push(
+			withNewCorrelationContext(
+				async () => {
+					const correlationId = getCorrelationId();
+					t.truthy(correlationId, 'Each context should have correlation ID');
+
+					for (let msg = 0; msg < messagesPerContext; msg++) {
+						logger.info(`Context ${ctx} message ${msg}`, {
+							contextId: ctx,
+							messageId: msg,
+							batch: 'concurrent-test',
+						});
+					}
+				},
+				undefined,
+				{contextId: ctx},
+			),
+		);
+	}
+
+	await Promise.all(promises);
+
+	// Verify that all contexts completed by checking that no errors were thrown
+	// Note: globalLogStorage is not automatically populated by logger - it's a separate facility
+	t.pass('All concurrent logging contexts completed without errors');
+
+	await end();
+});
+
+test('error handling and recovery', async t => {
+	const logger = initializeLogger({level: 'info'});
+
+	// Test logging with circular references
+	const circular: any = {id: 1, data: 'test'};
+	circular.self = circular;
+
+	t.notThrows(() => {
+		logger.info('Circular reference test', circular);
+	}, 'Should handle circular references gracefully');
+
+	// Test logging with very large objects
+	const largeObject = {
+		data: 'x'.repeat(10000),
+		array: Array.from({length: 1000}, (_, i) => ({id: i, value: `item-${i}`})),
+	};
+
+	t.notThrows(() => {
+		logger.info('Large object test', {summary: largeObject});
+	}, 'Should handle large objects gracefully');
+
+	// Test logging with undefined/null values
+	t.notThrows(() => {
+		logger.info('Edge case test', {
+			nullValue: null,
+			undefinedValue: undefined,
+			emptyString: '',
+			zero: 0,
+			false: false,
+		});
+	}, 'Should handle edge case values gracefully');
+
+	await end();
+});
+
+test('child logger functionality', async t => {
+	const parentLogger = initializeLogger({level: 'debug', correlation: true});
+
+	// Create child logger with bindings
+	const childLogger = parentLogger.child({
+		module: 'test-module',
+		version: '1.0.0',
+	});
+
+	t.truthy(childLogger, 'Should create child logger');
+	t.not(parentLogger === childLogger, 'Child should be different instance');
+
+	// Test child logger with correlation
+	await withNewCorrelationContext(
+		async () => {
+			childLogger.info('Child logger message', {action: 'test'});
+
+			// Create grandchild
+			const grandchildLogger = childLogger.child({
+				subModule: 'test-submodule',
+			});
+
+			grandchildLogger.info('Grandchild message', {action: 'nested-test'});
+		},
+		undefined,
+		{requestId: 'req-123'},
+	);
+
+	t.pass('Child logger functionality working correctly');
+
+	await end();
+});
+
+test('performance metrics integration', async t => {
+	const logger = initializeLogger({
+		level: 'info',
+	});
+
+	// Simulate operations with performance tracking
+	const promises = [];
+
+	for (let i = 0; i < 5; i++) {
+		promises.push(
+			new Promise<void>(resolve => {
+				setTimeout(() => {
+					logger.info(`Performance test ${i}`, {
+						operation: `test-${i}`,
+						timestamp: Date.now(),
+					});
+					resolve();
+				}, Math.random() * 50);
+			}),
+		);
+	}
+
+	await Promise.all(promises);
+
+	// Get performance metrics if available
+	try {
+		const metrics = healthChecks.metrics();
+		t.truthy(metrics, 'Should return health metrics');
+
+		if (metrics && typeof metrics === 'object' && 'performance' in metrics) {
+			const perfMetrics = (metrics as any).performance;
+			t.truthy(typeof perfMetrics === 'object', 'Should have performance data');
+		}
+	} catch (error) {
+		// Performance metrics might not be available in test environment
+		t.pass('Performance metrics test skipped');
+	}
+
+	await end();
+});
+
+test('graceful shutdown and cleanup', async t => {
+	const logger = initializeLogger({
+		level: 'info',
+	});
+
+	// Log some messages
+	for (let i = 0; i < 100; i++) {
+		logger.info(`Shutdown test message ${i}`, {
+			batch: 'shutdown-test',
+			index: i,
+		});
+	}
+
+	// Test flush
+	await t.notThrowsAsync(async () => {
+		await flush();
+	}, 'Flush should complete without errors');
+
+	// Test end
+	await t.notThrowsAsync(async () => {
+		await end();
+	}, 'End should complete without errors');
+
+	// Verify logger can be reinitialized
+	const newLogger = initializeLogger({level: 'info'});
+	t.truthy(newLogger, 'Should reinitialize after shutdown');
+
+	await end();
+});
+
+test('structured data handling and serialization', async t => {
+	const logger = initializeLogger({
+		level: 'debug',
+		serialize: true,
+	});
+
+	// Test complex nested objects
+	const complexData = {
+		user: {
+			id: '123',
+			profile: {
+				name: 'Test User',
+				preferences: {
+					theme: 'dark',
+					language: 'en',
+					notifications: {
+						email: true,
+						push: false,
+						sms: null,
+					},
+				},
+			},
+			metadata: {
+				lastLogin: new Date().toISOString(),
+				sessions: [
+					{id: 1, duration: 3600},
+					{id: 2, duration: 1800},
+				],
+			},
+		},
+		request: {
+			headers: {
+				'user-agent': 'test-agent',
+				accept: 'application/json',
+				authorization: '[REDACTED]',
+			},
+		},
+	};
+
+	t.notThrows(() => {
+		logger.info('Complex data test', complexData);
+	}, 'Should handle complex nested objects');
+
+	// Test special characters and Unicode
+	const unicodeData = {
+		emoji: '🚀 🎉 ✅',
+		chinese: '中文测试',
+		arabic: 'اختبار العربية',
+		specialChars: '"quotes", \'apostrophes\', \n\t\r\\',
+		binary: Buffer.from('binary data').toString('base64'),
+	};
+
+	t.notThrows(() => {
+		logger.info('Unicode test', unicodeData);
+	}, 'Should handle Unicode and special characters');
+
+	await end();
+});
+
+console.log('Integration tests completed successfully!');