sdforge 0.3.1

// Copyright (c) 2026 Kirky.X
// SPDX-License-Identifier: MIT
//! Structured logging utilities for SDForge
//!
//! This module provides structured logging capabilities with support for:
//! - JSON-formatted logs
//! - Log levels (Trace, Debug, Info, Warn, Error)
//! - Contextual fields
//! - Asynchronous writing
//! - Log rotation

use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::fmt;
use std::io::{self, Write};
use std::sync::Arc;
use tokio::sync::mpsc;

/// Log level enumeration
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum LogLevel {
    /// Trace level - most detailed debugging information
    Trace,
    /// Debug level - detailed debugging information
    Debug,
    /// Info level - general informational messages
    Info,
    /// Warn level - warning messages
    Warn,
    /// Error level - error messages
    Error,
}

impl fmt::Display for LogLevel {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            LogLevel::Trace => write!(f, "TRACE"),
            LogLevel::Debug => write!(f, "DEBUG"),
            LogLevel::Info => write!(f, "INFO"),
            LogLevel::Warn => write!(f, "WARN"),
            LogLevel::Error => write!(f, "ERROR"),
        }
    }
}

/// Structured log entry
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LogEntry {
    /// Timestamp in RFC 3339 format
    pub timestamp: String,
    /// Log level
    pub level: LogLevel,
    /// Target module or component
    pub target: String,
    /// Log message
    pub message: String,
    /// Additional contextual fields (ordered for consistent output)
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub fields: BTreeMap<String, serde_json::Value>,
}

impl LogEntry {
    /// Create a new log entry
    pub fn new(level: LogLevel, target: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            timestamp: chrono::Utc::now().to_rfc3339(),
            level,
            target: target.into(),
            message: message.into(),
            fields: BTreeMap::new(),
        }
    }

    /// Add a field to the log entry
    pub fn with_field(
        mut self,
        key: impl Into<String>,
        value: impl Into<serde_json::Value>,
    ) -> Self {
        self.fields.insert(key.into(), value.into());
        self
    }

    /// Add multiple fields
    pub fn with_fields(mut self, fields: Vec<(String, serde_json::Value)>) -> Self {
        for (key, value) in fields {
            self.fields.insert(key, value);
        }
        self
    }
}

/// Logger configuration
#[derive(Debug, Clone)]
pub struct LoggerConfig {
    /// Minimum log level to emit
    pub min_level: LogLevel,
    /// Output format (JSON or plain text)
    pub format: LogFormat,
    /// Whether to include ANSI colors in terminal output
    pub colored: bool,
    /// Maximum log file size in bytes (for file logging)
    pub max_file_size: u64,
    /// Number of rotated files to keep
    pub max_files: u32,
}

impl Default for LoggerConfig {
    fn default() -> Self {
        Self {
            min_level: LogLevel::Info,
            format: LogFormat::Json,
            colored: true,
            max_file_size: 10 * 1024 * 1024, // 10 MB
            max_files: 5,
        }
    }
}

/// Log output format
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LogFormat {
    /// JSON format - structured logging for production environments
    Json,
    /// Text format - human-readable logging for development
    Text,
}

/// Structured logger
pub struct StructuredLogger {
    config: LoggerConfig,
    tx: mpsc::Sender<LogEntry>,
    handle: Option<tokio::task::JoinHandle<()>>,
}

impl StructuredLogger {
    /// Create and initialize a new structured logger
    pub fn new(config: LoggerConfig) -> Self {
        let (tx, mut rx) = mpsc::channel::<LogEntry>(1000);

        // Spawn async writer task
        let handle = tokio::spawn(async move {
            let stdout = io::stdout();
            while let Some(entry) = rx.recv().await {
                let mut handle = stdout.lock();
                let _ = write_log_entry(&mut handle, &entry, config.format, config.colored);
                let _ = writeln!(handle);
            }
        });

        Self {
            config,
            tx,
            handle: Some(handle),
        }
    }

    /// Log a message at the specified level
    pub fn log(
        &self,
        level: LogLevel,
        target: &str,
        message: &str,
        fields: Vec<(String, serde_json::Value)>,
    ) {
        if level >= self.config.min_level {
            let entry = LogEntry::new(level, target, message).with_fields(fields);
            let _ = self.tx.try_send(entry);
        }
    }

    /// Trace level log
    pub fn trace(&self, target: &str, message: &str, fields: Vec<(String, serde_json::Value)>) {
        self.log(LogLevel::Trace, target, message, fields);
    }

    /// Debug level log
    pub fn debug(&self, target: &str, message: &str, fields: Vec<(String, serde_json::Value)>) {
        self.log(LogLevel::Debug, target, message, fields);
    }

    /// Info level log
    pub fn info(&self, target: &str, message: &str, fields: Vec<(String, serde_json::Value)>) {
        self.log(LogLevel::Info, target, message, fields);
    }

    /// Warn level log
    pub fn warn(&self, target: &str, message: &str, fields: Vec<(String, serde_json::Value)>) {
        self.log(LogLevel::Warn, target, message, fields);
    }

    /// Error level log
    pub fn error(&self, target: &str, message: &str, fields: Vec<(String, serde_json::Value)>) {
        self.log(LogLevel::Error, target, message, fields);
    }

    /// Flush pending logs
    pub async fn flush(&self) {
        // Channel will be flushed when dropped
    }

    /// Shutdown the logger
    pub async fn shutdown(self) {
        drop(self.tx);
        if let Some(handle) = self.handle {
            let _ = handle.await;
        }
    }
}

/// Write a log entry to the specified writer
fn write_log_entry<W: Write>(
    writer: &mut W,
    entry: &LogEntry,
    format: LogFormat,
    colored: bool,
) -> io::Result<()> {
    match format {
        LogFormat::Json => {
            let json = serde_json::to_string(entry)?;

            if colored {
                let color = get_level_color(entry.level);
                write!(writer, "{}", color)?;
                write!(writer, "{}", json)?;
                write!(writer, "\x1b[0m")?;
            } else {
                write!(writer, "{}", json)?;
            }
        }
        LogFormat::Text => {
            if colored {
                let color = get_level_color(entry.level);
                write!(writer, "{}{}", color, entry.timestamp)?;
                write!(writer, " {:<5}", entry.level)?;
                write!(writer, "\x1b[0m")?;
                write!(writer, " [{}]", entry.target)?;
                write!(writer, " {}", entry.message)?;

                if !entry.fields.is_empty() {
                    write!(writer, " {{")?;
                    for (i, (k, v)) in entry.fields.iter().enumerate() {
                        if i > 0 {
                            write!(writer, ", ")?;
                        }
                        write!(writer, "{}={}", k, v)?;
                    }
                    write!(writer, "}}")?;
                }
            } else {
                write!(
                    writer,
                    "{} {:<5} [{}] {}",
                    entry.timestamp, entry.level, entry.target, entry.message
                )?;

                if !entry.fields.is_empty() {
                    write!(writer, " {{")?;
                    for (i, (k, v)) in entry.fields.iter().enumerate() {
                        if i > 0 {
                            write!(writer, ", ")?;
                        }
                        write!(writer, "{}={}", k, v)?;
                    }
                    write!(writer, "}}")?;
                }
            }
        }
    }
    Ok(())
}

/// Get ANSI color code for log level
fn get_level_color(level: LogLevel) -> &'static str {
    match level {
        LogLevel::Trace => "\x1b[90m", // Bright Black
        LogLevel::Debug => "\x1b[36m", // Cyan
        LogLevel::Info => "\x1b[32m",  // Green
        LogLevel::Warn => "\x1b[33m",  // Yellow
        LogLevel::Error => "\x1b[31m", // Red
    }
}

/// Global logger instance
static GLOBAL_LOGGER: once_cell::sync::OnceCell<Arc<StructuredLogger>> =
    once_cell::sync::OnceCell::new();

/// Initialize the global logger
pub fn init_global_logger(config: LoggerConfig) -> Result<(), LoggerError> {
    let logger = Arc::new(StructuredLogger::new(config));
    GLOBAL_LOGGER
        .set(logger)
        .map_err(|_| LoggerError::AlreadyInitialized)?;
    Ok(())
}

/// Get the global logger
pub fn get_global_logger() -> Option<Arc<StructuredLogger>> {
    GLOBAL_LOGGER.get().cloned()
}

/// Logger initialization error
#[derive(Debug, thiserror::Error)]
pub enum LoggerError {
    /// Error when attempting to initialize an already-initialized logger
    #[error("Logger already initialized")]
    AlreadyInitialized,
}

/// Convenience macro for structured logging
#[macro_export]
macro_rules! log_info {
    ($target:expr, $msg:expr $(, $key:expr => $val:expr)* $(,)?) => {{
        use $crate::logging::{get_global_logger, LogLevel};
        if let Some(logger) = get_global_logger() {
            let fields = vec![$(($key, $val.into())),*];
            logger.log(LogLevel::Info, $target, $msg, fields);
        }
    }};
}

/// Convenience macro for error logging
#[macro_export]
macro_rules! log_error {
    ($target:expr, $msg:expr $(, $key:expr => $val:expr)* $(,)?) => {{
        use $crate::logging::{get_global_logger, LogLevel};
        if let Some(logger) = get_global_logger() {
            let fields = vec![$(($key, $val.into())),*];
            logger.log(LogLevel::Error, $target, $msg, fields);
        }
    }};
}

/// Convenience macro for debug logging
#[macro_export]
macro_rules! log_debug {
    ($target:expr, $msg:expr $(, $key:expr => $val:expr)* $(,)?) => {{
        use $crate::logging::{get_global_logger, LogLevel};
        if let Some(logger) = get_global_logger() {
            let fields = vec![$(($key, $val.into())),*];
            logger.log(LogLevel::Debug, $target, $msg, fields);
        }
    }};
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_log_entry_creation() {
        let entry = LogEntry::new(LogLevel::Info, "test", "Test message")
            .with_field("user_id", "123")
            .with_field("action", "login");

        assert_eq!(entry.level, LogLevel::Info);
        assert_eq!(entry.target, "test");
        assert_eq!(entry.message, "Test message");
        assert_eq!(entry.fields.len(), 2);
    }

    #[test]
    fn test_log_level_display() {
        assert_eq!(format!("{}", LogLevel::Info), "INFO");
        assert_eq!(format!("{}", LogLevel::Error), "ERROR");
    }

    #[test]
    fn test_log_entry_serialization() {
        let entry = LogEntry::new(LogLevel::Warn, "auth", "Failed login attempt")
            .with_field("user", "admin")
            .with_field("ip", "192.168.1.1");

        let json = serde_json::to_string(&entry).unwrap();
        assert!(json.contains("\"level\":\"warn\""));
        assert!(json.contains("\"target\":\"auth\""));
        assert!(json.contains("\"message\":\"Failed login attempt\""));
    }

    /// Verify that `write_log_entry` with `LogFormat::Text` and `colored=false`
    /// produces the plain-text format (lines 252-256 — the non-colored text
    /// branch).
    #[test]
    fn test_write_log_entry_text_format_no_color() {
        let entry = LogEntry::new(LogLevel::Info, "test_target", "Test message")
            .with_field("key", "value");

        let mut output = Vec::new();
        let result = write_log_entry(&mut output, &entry, LogFormat::Text, false);

        assert!(result.is_ok());
        let written = String::from_utf8(output).unwrap();
        assert!(written.contains("INFO"), "Should contain log level");
        assert!(written.contains("test_target"), "Should contain target");
        assert!(written.contains("Test message"), "Should contain message");
        // serde_json::Value Display for a string includes quotes: key="value"
        assert!(written.contains(r#"key="value""#), "Should contain field");
    }

    #[tokio::test]
    async fn test_structured_logger() {
        let config = LoggerConfig {
            min_level: LogLevel::Debug,
            format: LogFormat::Json,
            colored: false,
            ..Default::default()
        };

        let logger = StructuredLogger::new(config);

        logger.info(
            "app",
            "Application started",
            vec![
                (
                    "version".to_string(),
                    serde_json::Value::String("0.1.0".to_string()),
                ),
                (
                    "env".to_string(),
                    serde_json::Value::String("test".to_string()),
                ),
            ],
        );

        logger.error(
            "db",
            "Connection failed",
            vec![
                (
                    "host".to_string(),
                    serde_json::Value::String("localhost".to_string()),
                ),
                ("port".to_string(), serde_json::Value::Number(5432.into())),
            ],
        );

        logger.flush().await;
        logger.shutdown().await;
    }

    #[test]
    fn test_logger_config_default_values() {
        let config = LoggerConfig::default();
        assert_eq!(config.min_level, LogLevel::Info);
        assert!(matches!(config.format, LogFormat::Json));
        assert!(config.colored);
        assert_eq!(config.max_file_size, 10 * 1024 * 1024);
        assert_eq!(config.max_files, 5);
    }

    #[test]
    fn test_write_log_entry_text_colored() {
        let entry = LogEntry::new(LogLevel::Error, "test", "Error msg");
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("ERROR"));
        assert!(output.contains("Error msg"));
        assert!(output.contains("test"));
        // Should contain ANSI escape codes
        assert!(output.contains("\x1b["));
    }

    #[test]
    fn test_write_log_entry_text_uncolored() {
        let entry = LogEntry::new(LogLevel::Info, "app", "Hello");
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Text, false).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("INFO"));
        assert!(output.contains("Hello"));
        assert!(!output.contains("\x1b["));
    }

    #[test]
    fn test_write_log_entry_text_uncolored_with_fields() {
        let entry = LogEntry::new(LogLevel::Warn, "auth", "Failed login")
            .with_field("ip", serde_json::json!("10.0.0.1"));
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Text, false).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("WARN"), "Should contain WARN level");
        assert!(output.contains("ip"), "Should contain field key");
        assert!(output.contains("10.0.0.1"), "Should contain field value");
    }

    #[test]
    fn test_write_log_entry_json_uncolored() {
        let entry =
            LogEntry::new(LogLevel::Debug, "api", "Request received").with_field("path", "/users");
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Json, false).unwrap();
        let output = String::from_utf8_lossy(&buf);
        let parsed: serde_json::Value = serde_json::from_str(output.trim()).unwrap();
        assert_eq!(parsed["level"], "debug");
        assert_eq!(parsed["target"], "api");
        assert_eq!(parsed["message"], "Request received");
        assert!(!output.contains("\x1b["));
    }

    #[test]
    fn test_write_log_entry_json_colored() {
        let entry = LogEntry::new(LogLevel::Trace, "db", "Query executed");
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Json, true).unwrap();
        let output = String::from_utf8_lossy(&buf);
        // Should contain ANSI escape codes at start
        assert!(output.contains("\x1b["));
        // The JSON content should be inside
        assert!(output.contains("trace"));
        assert!(output.contains("db"));
    }

    #[test]
    fn test_level_color_trace() {
        let mut buf = Vec::new();
        let entry = LogEntry::new(LogLevel::Trace, "t", "m");
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("\x1b[90m"));
    }

    #[test]
    fn test_level_color_debug() {
        let mut buf = Vec::new();
        let entry = LogEntry::new(LogLevel::Debug, "t", "m");
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("\x1b[36m"));
    }

    #[test]
    fn test_level_color_info() {
        let mut buf = Vec::new();
        let entry = LogEntry::new(LogLevel::Info, "t", "m");
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("\x1b[32m"));
    }

    #[test]
    fn test_level_color_warn() {
        let mut buf = Vec::new();
        let entry = LogEntry::new(LogLevel::Warn, "t", "m");
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("\x1b[33m"));
    }

    #[test]
    fn test_level_color_error() {
        let mut buf = Vec::new();
        let entry = LogEntry::new(LogLevel::Error, "t", "m");
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);
        assert!(output.contains("\x1b[31m"));
    }

    #[test]
    fn test_log_entry_with_fields_multiple() {
        let entry = LogEntry::new(LogLevel::Info, "test", "msg").with_fields(vec![
            ("a".to_string(), serde_json::json!(1)),
            ("b".to_string(), serde_json::json!("two")),
            ("c".to_string(), serde_json::json!(true)),
        ]);
        assert_eq!(entry.fields.len(), 3);
        assert_eq!(entry.fields.get("a"), Some(&serde_json::json!(1)));
    }

    #[test]
    fn test_log_entry_with_fields_empty() {
        let entry = LogEntry::new(LogLevel::Info, "test", "msg").with_fields(vec![]);
        assert_eq!(entry.fields.len(), 0);
    }

    #[test]
    fn test_log_entry_with_fields_overwrites() {
        let entry = LogEntry::new(LogLevel::Info, "test", "msg")
            .with_field("key", "first")
            .with_field("key", "second");
        assert_eq!(entry.fields.len(), 1);
        assert_eq!(entry.fields.get("key"), Some(&serde_json::json!("second")));
    }

    #[tokio::test]
    async fn test_structured_logger_trace_filtered_out() {
        let config = LoggerConfig {
            min_level: LogLevel::Info,
            format: LogFormat::Json,
            colored: false,
            ..Default::default()
        };
        let logger = StructuredLogger::new(config);
        logger.trace("test", "should be filtered", vec![]);
        logger.flush().await;
        logger.shutdown().await;
    }

    #[tokio::test]
    async fn test_structured_logger_debug_emitted() {
        let config = LoggerConfig {
            min_level: LogLevel::Debug,
            format: LogFormat::Json,
            colored: false,
            ..Default::default()
        };
        let logger = StructuredLogger::new(config);
        logger.debug("test", "debug msg", vec![]);
        logger.flush().await;
        logger.shutdown().await;
    }

    #[tokio::test]
    async fn test_structured_logger_warn_emitted() {
        let config = LoggerConfig {
            min_level: LogLevel::Warn,
            format: LogFormat::Json,
            colored: false,
            ..Default::default()
        };
        let logger = StructuredLogger::new(config);
        logger.warn("test", "warn msg", vec![]);
        logger.info("test", "should be filtered", vec![]);
        logger.flush().await;
        logger.shutdown().await;
    }

    #[test]
    fn test_log_level_ordering() {
        assert!(LogLevel::Trace < LogLevel::Debug);
        assert!(LogLevel::Debug < LogLevel::Info);
        assert!(LogLevel::Info < LogLevel::Warn);
        assert!(LogLevel::Warn < LogLevel::Error);
    }

    #[test]
    fn test_log_level_ordering_chained() {
        assert!(LogLevel::Trace < LogLevel::Info);
        assert!(LogLevel::Debug < LogLevel::Error);
    }

    #[test]
    fn test_log_level_equality() {
        assert_eq!(LogLevel::Info, LogLevel::Info);
        assert!(LogLevel::Info >= LogLevel::Info);
        assert!(LogLevel::Info <= LogLevel::Info);
    }

    #[test]
    fn test_log_level_serde_roundtrip() {
        let levels = [
            LogLevel::Trace,
            LogLevel::Debug,
            LogLevel::Info,
            LogLevel::Warn,
            LogLevel::Error,
        ];
        for level in levels {
            let json = serde_json::to_string(&level).unwrap();
            let restored: LogLevel = serde_json::from_str(&json).unwrap();
            assert_eq!(level, restored);
        }
    }

    #[test]
    fn test_log_level_serde_lowercase() {
        let json = serde_json::to_string(&LogLevel::Info).unwrap();
        assert!(json.contains("info"));
    }

    #[test]
    fn test_log_level_deserialize_lowercase() {
        let level: LogLevel = serde_json::from_str("\"warn\"").unwrap();
        assert_eq!(level, LogLevel::Warn);
    }

    #[test]
    fn test_log_level_display_all() {
        assert_eq!(format!("{}", LogLevel::Trace), "TRACE");
        assert_eq!(format!("{}", LogLevel::Debug), "DEBUG");
        assert_eq!(format!("{}", LogLevel::Info), "INFO");
        assert_eq!(format!("{}", LogLevel::Warn), "WARN");
        assert_eq!(format!("{}", LogLevel::Error), "ERROR");
    }

    #[test]
    fn test_logger_error_display() {
        let err = LoggerError::AlreadyInitialized;
        assert!(err.to_string().contains("already initialized"));
    }

    #[test]
    fn test_logger_error_debug() {
        let err = LoggerError::AlreadyInitialized;
        let debug_str = format!("{:?}", err);
        assert!(debug_str.contains("AlreadyInitialized"));
    }

    // ============================================================================
    // Text colored output WITH fields
    //
    // The existing test_write_log_entry_text_colored test uses an entry without
    // fields, so the `if !entry.fields.is_empty()` branch inside the colored
    // Text arm is not exercised. This test covers that branch.
    // ============================================================================

    #[test]
    fn test_write_log_entry_text_colored_with_fields() {
        let entry = LogEntry::new(LogLevel::Warn, "auth", "Failed login attempt")
            .with_field("user", serde_json::json!("admin"))
            .with_field("ip", serde_json::json!("10.0.0.1"));
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);

        // Colored output should contain ANSI escape codes
        assert!(
            output.contains("\x1b[33m"),
            "Should contain warn color code"
        );
        assert!(output.contains("\x1b[0m"), "Should contain reset code");
        // Should contain the fields in the {key=value} format
        assert!(output.contains("user"), "Should contain field key 'user'");
        assert!(
            output.contains("admin"),
            "Should contain field value 'admin'"
        );
        assert!(output.contains("ip"), "Should contain field key 'ip'");
        assert!(output.contains("10.0.0.1"), "Should contain field value");
        // Should contain the fields brace delimiter
        assert!(
            output.contains("{"),
            "Should contain opening brace for fields"
        );
        assert!(
            output.contains("}"),
            "Should contain closing brace for fields"
        );
    }

    #[test]
    fn test_write_log_entry_text_colored_with_multiple_fields() {
        // Test the loop iteration with multiple fields (i > 0 branch writes ", ")
        let entry = LogEntry::new(LogLevel::Error, "db", "Query failed")
            .with_field("query", serde_json::json!("SELECT *"))
            .with_field("duration_ms", serde_json::json!(150))
            .with_field("table", serde_json::json!("users"));
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);

        assert!(
            output.contains("\x1b[31m"),
            "Should contain error color code"
        );
        // Multiple fields should be comma-separated
        assert!(output.contains(", "), "Should contain field separator");
        assert!(output.contains("query"));
        assert!(output.contains("duration_ms"));
        assert!(output.contains("table"));
    }

    // ============================================================================
    // Global logger tests (init_global_logger / get_global_logger)
    //
    // GLOBAL_LOGGER is a process-wide OnceCell that can only be set once. These
    // tests use #[serial] to ensure they don't run concurrently with any other
    // test touching the global logger. Because the OnceCell may already be set
    // by another test, we handle both the "first init" and "already initialized"
    // paths defensively.
    // ============================================================================

    #[tokio::test]
    #[serial_test::serial]
    async fn test_global_logger_init_and_get() {
        // Attempt to initialize the global logger. If this is the first test
        // to call init_global_logger in this process, it will succeed and we
        // can verify get_global_logger returns Some. If another test already
        // initialized it, init will fail with AlreadyInitialized and we
        // verify get_global_logger returns Some (set by the earlier test).
        let config = LoggerConfig::default();
        let init_result = init_global_logger(config);

        match init_result {
            Ok(()) => {
                // First initialization succeeded — get_global_logger should
                // now return Some.
                assert!(
                    get_global_logger().is_some(),
                    "get_global_logger should return Some after successful init"
                );
            }
            Err(LoggerError::AlreadyInitialized) => {
                // Another test already initialized the logger —
                // get_global_logger should still return Some.
                assert!(
                    get_global_logger().is_some(),
                    "get_global_logger should return Some when already initialized"
                );
            }
        }
    }

    #[tokio::test]
    #[serial_test::serial]
    async fn test_global_logger_double_init_fails() {
        // The global logger can only be initialized once per process. After
        // the first successful init, subsequent calls must fail with
        // AlreadyInitialized. We call init twice; at least the second call
        // should fail (both fail if the logger was already set by a prior
        // test).
        let config = LoggerConfig::default();
        let _first = init_global_logger(config.clone());
        let second = init_global_logger(config);

        // The second call must always fail — either because the first call
        // succeeded, or because a prior test already initialized the logger.
        assert!(
            matches!(second, Err(LoggerError::AlreadyInitialized)),
            "Second init_global_logger call should fail with AlreadyInitialized"
        );
    }

    #[tokio::test]
    #[serial_test::serial]
    async fn test_get_global_logger_returns_some_after_init() {
        // Ensure the logger is initialized (may already be set by prior test)
        let _ = init_global_logger(LoggerConfig::default());
        // get_global_logger should return Some regardless of which test
        // performed the initialization.
        let logger = get_global_logger();
        assert!(
            logger.is_some(),
            "get_global_logger should return Some after initialization"
        );
    }

    // ============================================================================
    // Text uncolored output WITH multiple fields
    //
    // The existing test_write_log_entry_text_uncolored_with_fields test uses a
    // single field, so the `i > 0` separator branch (", ") inside the uncolored
    // Text arm is never hit. This test covers that separator branch.
    // ============================================================================

    /// Test text format uncolored with multiple fields exercises the `i > 0`
    /// separator branch (writes ", " between fields) in the uncolored Text
    /// code path.
    #[test]
    fn test_write_log_entry_text_uncolored_with_multiple_fields() {
        let entry = LogEntry::new(LogLevel::Info, "app", "multi fields")
            .with_field("a", serde_json::json!(1))
            .with_field("b", serde_json::json!("two"))
            .with_field("c", serde_json::json!(true));
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Text, false).unwrap();
        let output = String::from_utf8_lossy(&buf);

        assert!(output.contains("INFO"), "Should contain level");
        assert!(output.contains("app"), "Should contain target");
        assert!(output.contains("multi fields"), "Should contain message");
        assert!(output.contains(", "), "Should contain field separator");
        assert!(output.contains("a=1"), "Should contain field a");
        assert!(output.contains("b=\"two\""), "Should contain field b");
        assert!(output.contains("c=true"), "Should contain field c");
        assert!(!output.contains("\x1b["), "Should not contain ANSI codes");
    }

    /// Test text format colored with an empty entry (no fields) to verify the
    /// `if !entry.fields.is_empty()` false branch is taken in the colored path.
    #[test]
    fn test_write_log_entry_text_colored_without_fields() {
        let entry = LogEntry::new(LogLevel::Error, "db", "no fields here");
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Text, true).unwrap();
        let output = String::from_utf8_lossy(&buf);

        assert!(output.contains("\x1b[31m"), "Should contain error color");
        assert!(output.contains("no fields here"), "Should contain message");
        assert!(
            !output.contains("{") || output.contains("\x1b[0m"),
            "Should not emit fields block when empty"
        );
    }

    /// Test JSON format uncolored with multiple fields verifies the fields
    /// object is serialized correctly.
    #[test]
    fn test_write_log_entry_json_uncolored_with_multiple_fields() {
        let entry = LogEntry::new(LogLevel::Warn, "api", "request")
            .with_field("method", serde_json::json!("GET"))
            .with_field("status", serde_json::json!(200))
            .with_field("duration_ms", serde_json::json!(42));
        let mut buf = Vec::new();
        write_log_entry(&mut buf, &entry, LogFormat::Json, false).unwrap();
        let output = String::from_utf8_lossy(&buf);
        let parsed: serde_json::Value = serde_json::from_str(output.trim()).unwrap();
        assert_eq!(parsed["fields"]["method"], "GET");
        assert_eq!(parsed["fields"]["status"], 200);
        assert_eq!(parsed["fields"]["duration_ms"], 42);
    }

    /// Test LogEntry with_field accepts various JSON value types and stores
    /// them correctly in the fields BTreeMap.
    #[test]
    fn test_log_entry_with_field_various_value_types() {
        let entry = LogEntry::new(LogLevel::Debug, "test", "msg")
            .with_field("null_val", serde_json::Value::Null)
            .with_field("bool_val", serde_json::json!(true))
            .with_field("num_val", serde_json::json!(3.15))
            .with_field("arr_val", serde_json::json!([1, 2, 3]))
            .with_field("obj_val", serde_json::json!({"nested": "value"}));
        assert_eq!(entry.fields.len(), 5);
        assert_eq!(entry.fields.get("null_val"), Some(&serde_json::Value::Null));
        assert_eq!(
            entry.fields.get("arr_val"),
            Some(&serde_json::json!([1, 2, 3]))
        );
    }

    /// Test LoggerConfig clone produces an independent copy with all fields.
    #[test]
    fn test_logger_config_clone_independent() {
        let config = LoggerConfig {
            min_level: LogLevel::Debug,
            format: LogFormat::Text,
            colored: false,
            max_file_size: 5 * 1024 * 1024,
            max_files: 3,
        };
        let cloned = config.clone();
        assert_eq!(cloned.min_level, config.min_level);
        assert_eq!(cloned.format, config.format);
        assert_eq!(cloned.colored, config.colored);
        assert_eq!(cloned.max_file_size, config.max_file_size);
        assert_eq!(cloned.max_files, config.max_files);
    }

    /// Test LogFormat equality and inequality.
    #[test]
    fn test_log_format_equality() {
        assert_eq!(LogFormat::Json, LogFormat::Json);
        assert_eq!(LogFormat::Text, LogFormat::Text);
        assert_ne!(LogFormat::Json, LogFormat::Text);
    }
}