waddling_errors/

code.rs

//! Diagnostic code structure

use crate::Severity;
use core::fmt;

#[cfg(feature = "std")]
use std::{format, string::String};

#[cfg(not(feature = "std"))]
use alloc::{format, string::String};

/// Waddling diagnostic code: `SEVERITY.COMPONENT.PRIMARY.SEQUENCE`
///
/// Format: `E.CRYPTO.SALT.001`
///
/// # Examples
///
/// ```rust
/// use waddling_errors::{Code, Severity};
///
/// const ERR: Code = Code::error("CRYPTO", "SALT", 1);
/// assert_eq!(ERR.code(), "E.CRYPTO.SALT.001");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Code {
    severity: Severity,
    component: &'static str,
    primary: &'static str,
    sequence: u16,
}

impl Code {
    const MAX_LEN: usize = 12;
    const MIN_LEN: usize = 2;

    /// Create a new code with explicit severity
    ///
    /// # Panics
    ///
    /// Panics if sequence > 999, or component/primary length not in 2-12 range
    pub const fn new(
        severity: Severity,
        component: &'static str,
        primary: &'static str,
        sequence: u16,
    ) -> Self {
        assert!(sequence <= 999, "Sequence must be <= 999");

        let component_len = component.len();
        assert!(
            component_len >= Self::MIN_LEN && component_len <= Self::MAX_LEN,
            "Component must be 2-12 characters"
        );

        let primary_len = primary.len();
        assert!(
            primary_len >= Self::MIN_LEN && primary_len <= Self::MAX_LEN,
            "Primary must be 2-12 characters"
        );

        Self {
            severity,
            component,
            primary,
            sequence,
        }
    }

    /// Create an error code (E)
    pub const fn error(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Error, component, primary, sequence)
    }

    /// Create a warning code (W)
    pub const fn warning(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Warning, component, primary, sequence)
    }

    /// Create a critical code (C)
    pub const fn critical(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Critical, component, primary, sequence)
    }

    /// Create a blocked code (B)
    pub const fn blocked(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Blocked, component, primary, sequence)
    }

    /// Create a help code (H)
    pub const fn help(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Help, component, primary, sequence)
    }

    /// Create a success code (S)
    pub const fn success(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Success, component, primary, sequence)
    }

    /// Create a completed code (K)
    pub const fn completed(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Completed, component, primary, sequence)
    }

    /// Create an info code (I)
    pub const fn info(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Info, component, primary, sequence)
    }

    /// Create a trace code (T)
    pub const fn trace(component: &'static str, primary: &'static str, sequence: u16) -> Self {
        Self::new(Severity::Trace, component, primary, sequence)
    }

    /// Get the full error code (e.g., "E.CRYPTO.SALT.001")
    pub fn code(&self) -> String {
        format!(
            "{}.{}.{}.{:03}",
            self.severity.as_char(),
            self.component,
            self.primary,
            self.sequence
        )
    }

    /// Write error code to formatter without allocating
    ///
    /// Use in performance-critical paths to avoid String allocation.
    pub fn write_code(&self, f: &mut impl fmt::Write) -> fmt::Result {
        write!(
            f,
            "{}.{}.{}.{:03}",
            self.severity.as_char(),
            self.component,
            self.primary,
            self.sequence
        )
    }

    /// Get severity
    pub const fn severity(&self) -> Severity {
        self.severity
    }

    /// Get component
    pub const fn component(&self) -> &'static str {
        self.component
    }

    /// Get primary category
    pub const fn primary(&self) -> &'static str {
        self.primary
    }

    /// Get sequence number
    pub const fn sequence(&self) -> u16 {
        self.sequence
    }

    /// Get 5-character base62 hash (requires "hash" feature)
    ///
    /// Returns alphanumeric hash safe for all logging systems.
    /// Provides 916M combinations for collision resistance.
    #[cfg(feature = "hash")]
    pub fn hash(&self) -> String {
        crate::hash::compute_hash(&self.code())
    }
}

impl fmt::Display for Code {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{}.{}.{}.{:03}",
            self.severity.as_char(),
            self.component,
            self.primary,
            self.sequence
        )
    }
}

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

    #[cfg(feature = "std")]
    use std::string::ToString;

    #[cfg(not(feature = "std"))]
    use alloc::string::ToString;

    #[test]
    fn test_error_code_format() {
        const CODE: Code = Code::new(Severity::Error, "CRYPTO", "SALT", 1);
        assert_eq!(CODE.code(), "E.CRYPTO.SALT.001");
        assert_eq!(CODE.severity(), Severity::Error);
        assert_eq!(CODE.component(), "CRYPTO");
        assert_eq!(CODE.primary(), "SALT");
        assert_eq!(CODE.sequence(), 1);
    }

    #[test]
    fn test_error_code_display() {
        const CODE: Code = Code::new(Severity::Warning, "PATTERN", "PARSE", 5);
        assert_eq!(CODE.to_string(), "W.PATTERN.PARSE.005");
    }

    #[cfg(feature = "hash")]
    #[test]
    fn test_error_code_hash() {
        const CODE: Code = Code::new(Severity::Error, "CRYPTO", "SALT", 1);
        let hash1 = CODE.hash();
        let hash2 = CODE.hash();
        assert_eq!(hash1, hash2); // Deterministic
        assert_eq!(hash1.len(), 5);
        assert!(hash1.chars().all(|c| c.is_ascii_alphanumeric()));
    }

    #[test]
    fn test_length_validation() {
        const MIN: Code = Code::new(Severity::Error, "IO", "FS", 1);
        const MAX: Code = Code::new(Severity::Error, "LONGCOMPONNT", "LONGPRIMARY1", 1);
        assert_eq!(MIN.component(), "IO");
        assert_eq!(MAX.component(), "LONGCOMPONNT");
    }
}