Logging System

/**
 * Log an error message
 * @param category - String identifier for the logging category
 * @param message - Primary message string (supports % formatting)
 * @param args - Additional arguments for message interpolation
 */
forge.log.error(category: string, message: string, ...args: any[]): void;

/**
 * Log a warning message
 * @param category - String identifier for the logging category
 * @param message - Primary message string (supports % formatting)
 * @param args - Additional arguments for message interpolation
 */
forge.log.warning(category: string, message: string, ...args: any[]): void;

/**
 * Log an informational message
 * @param category - String identifier for the logging category
 * @param message - Primary message string (supports % formatting)
 * @param args - Additional arguments for message interpolation
 */
forge.log.info(category: string, message: string, ...args: any[]): void;

/**
 * Log a debug message
 * @param category - String identifier for the logging category
 * @param message - Primary message string (supports % formatting)
 * @param args - Additional arguments for message interpolation
 */
forge.log.debug(category: string, message: string, ...args: any[]): void;

/**
 * Log a verbose message
 * @param category - String identifier for the logging category
 * @param message - Primary message string (supports % formatting)
 * @param args - Additional arguments for message interpolation
 */
forge.log.verbose(category: string, message: string, ...args: any[]): void;

// Basic logging
forge.log.info('myapp', 'Application started');
forge.log.error('network', 'Connection failed');

// Formatted logging with arguments
forge.log.debug('crypto', 'Generated key with %d bits', 2048);
forge.log.warning('validation', 'Invalid input: %s', inputValue);

/**
 * Create a custom logger with specified logging function
 * @param logFunction - Function that receives logger and message objects
 * @returns Logger instance with configurable level and flags
 */
forge.log.makeLogger(logFunction: (logger: Logger, message: LogMessage) => void): Logger;

/**
 * Set the maximum log level for a logger
 * @param logger - Target logger instance
 * @param level - Maximum level ('none', 'error', 'warning', 'info', 'debug', 'verbose', 'max')
 * @returns true if level was set successfully
 */
forge.log.setLevel(logger: Logger, level: string): boolean;

/**
 * Lock a logger at its current level to prevent changes
 * @param logger - Target logger instance
 * @param lock - Whether to lock (default: true) or unlock the level
 */
forge.log.lock(logger: Logger, lock?: boolean): void;

/**
 * Add a logger to the global logging system
 * @param logger - Logger instance to add
 */
forge.log.addLogger(logger: Logger): void;

interface Logger {
  level: string;        // Current log level
  flags: number;        // Logger configuration flags
  f: function;          // Logging function
}

interface LogMessage {
  timestamp: Date;      // When the message was created
  level: string;        // Message log level
  category: string;     // Message category
  message: string;      // Primary message content
  arguments: any[];     // Additional arguments
  standard?: string;    // Formatted standard message
  full?: string;        // Interpolated full message
}

// Lock the level at current value
forge.log.LEVEL_LOCKED: number;

// Always call log function regardless of level check
forge.log.NO_LEVEL_CHECK: number;

// Perform message interpolation with arguments
forge.log.INTERPOLATE: number;

// Available log levels in order of verbosity
forge.log.levels: string[]; // ['none', 'error', 'warning', 'info', 'debug', 'verbose', 'max']

// Built-in console logger (may be null if console unavailable)
forge.log.consoleLogger: Logger | null;

// Create a custom logger that writes to a file
const fileLogger = forge.log.makeLogger((logger, message) => {
  const formatted = `${message.timestamp.toISOString()} [${message.level.toUpperCase()}] ${message.category}: ${message.message}`;
  writeToLogFile(formatted);
});

// Set the logger to only show warnings and errors
forge.log.setLevel(fileLogger, 'warning');

// Add to the global logging system
forge.log.addLogger(fileLogger);

// Lock the console logger at debug level
if (forge.log.consoleLogger) {
  forge.log.setLevel(forge.log.consoleLogger, 'debug');
  forge.log.lock(forge.log.consoleLogger);
}

/**
 * Format message with standard prefix: "LEVEL [category] message"
 * @param message - Log message object to format
 */
forge.log.prepareStandard(message: LogMessage): void;

/**
 * Interpolate message arguments using % formatting
 * @param message - Log message object to interpolate
 */
forge.log.prepareFull(message: LogMessage): void;

/**
 * Apply both standard and full formatting
 * @param message - Log message object to format
 */
forge.log.prepareStandardFull(message: LogMessage): void;