waddling_errors/

lib.rs

//! Ultra-minimal diagnostic code system for the Waddling ecosystem
//!
//! This crate provides a standardized 4-part diagnostic code format:
//!
//! **Format**: `SEVERITY.COMPONENT.PRIMARY.SEQUENCE` → `E.CRYPTO.SALT.001`
//!
//! # Quick Start
//!
//! ```rust
//! use waddling_errors::prelude::*;
//!
//! // Ergonomic convenience functions
//! const ERR_SALT: Code = error("CRYPTO", "SALT", 1);
//!
//! assert_eq!(ERR_SALT.code(), "E.CRYPTO.SALT.001");
//! ```
//!
//! # Alternative API Styles
//!
//! ```rust
//! use waddling_errors::{Code, Severity};
//!
//! // Method style
//! const ERR: Code = Code::error("CRYPTO", "SALT", 1);
//!
//! // Explicit severity
//! const WARN: Code = Code::new(Severity::Warning, "CRYPTO", "WEAK", 1);
//! ```
//!
//! # Sequence Conventions
//!
//! The Waddling ecosystem uses **semantic sequence numbers** for common error patterns:
//!
//! | Sequence | Meaning       | Example                                  |
//! |----------|---------------|------------------------------------------|
//! | 001      | MISSING       | Required item not provided               |
//! | 002      | MISMATCH      | Values don't match expected type/length  |
//! | 003      | INVALID       | Format/validation failed                 |
//! | 021      | NOTFOUND      | Resource not found                       |
//! | 025      | CORRUPTED     | Data corrupted/integrity check failed    |
//! | 031-897  | (project)     | Domain-specific sequences                |
//! | 999      | COMPLETE      | Full completion                          |
//!
//! **Benefits**: `.001` always means "missing" across ALL Waddling projects,
//! enabling instant recognition and cross-project consistency.
//!
//! ```rust
//! use waddling_errors::prelude::*;
//!
//! // Following conventions (recommended)
//! const ERR_MISSING_SALT: Code = error("CRYPTO", "SALT", 1);  // .001 = MISSING
//!
//! const ERR_LENGTH_MISMATCH: Code = error("CRYPTO", "LENGTH", 2);  // .002 = MISMATCH
//!
//! // Domain-specific (031-897 range for project logic)
//! const ERR_HMAC_COMPUTE: Code = error("CRYPTO", "HMAC", 31);
//! ```
//!
//! These conventions are **SHOULD** guidelines (RFC 2119), not requirements.
//! See repository docs/SEQUENCE-CONVENTIONS.md for complete list and enforcement strategies.
//!
//! # Error Registry Pattern
//!
//! For larger projects, create a central registry:
//!
//! ```rust
//! // errors.rs - Your project's error registry
//! pub mod errors {
//!     use waddling_errors::prelude::*;
//!     
//!     // Crypto errors (E.CRYPTO.*)
//!     pub const SALT_MISSING: Code = error("CRYPTO", "SALT", 1);
//!     pub const KEY_LENGTH: Code = error("CRYPTO", "LENGTH", 2);
//!     pub const HMAC_INVALID: Code = error("CRYPTO", "HMAC", 3);
//!     
//!     // Parser warnings (W.PARSE.*)
//!     pub const DEPRECATED_SYNTAX: Code = warning("PARSE", "DEPR", 1);
//! }
//! ```

#![no_std]
#![forbid(unsafe_code)]

#[cfg(feature = "std")]
extern crate std;

#[cfg(not(feature = "std"))]
extern crate alloc;

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

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

use core::fmt;

// ============================================================================
// Top-level convenience functions
// ============================================================================

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

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

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

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

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

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

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

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

// ============================================================================
// Prelude module
// ============================================================================

/// Prelude module for convenient imports
pub mod prelude {
    pub use crate::{Code, Severity};
    pub use crate::{blocked, completed, critical, error, info, success, trace, warning};
}

// ============================================================================
// Backward compatibility
// ============================================================================

/// Backward compatibility alias for `Code`
pub type ErrorCode = Code;

/// Backward compatibility alias for `Code`
pub type DiagnosticCode = Code;

// ============================================================================
// Severity (for 4-part format)
// ============================================================================

/// Diagnostic message severity level (single-character prefix for 4-part codes)
///
/// Represents the severity/type of a diagnostic code. Each severity gets a
/// single-character prefix in the 4-part format: `SEVERITY.COMPONENT.PRIMARY.SEQUENCE`
///
/// # Available Severities
///
/// - **Error (E)** - Operation failed
/// - **Warning (W)** - Potential issue
/// - **Critical (C)** - Severe issue
/// - **Blocked (B)** - Execution blocked
/// - **Success (S)** - Operation succeeded
/// - **Completed (K)** - Task/phase finished
/// - **Info (I)** - Informational events
/// - **Trace (T)** - Execution traces, probes
///
/// # Examples
///
/// ```rust
/// use waddling_errors::{Code, Severity};
///
/// const ERR: Code = Code::new(Severity::Error, "io", "FILE", 1);
/// const WARN: Code = Code::new(Severity::Warning, "api", "DEPR", 1);
///
/// assert_eq!(ERR.severity().as_char(), 'E');
/// assert_eq!(WARN.severity().as_char(), 'W');
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum Severity {
    /// **Error (E)** - Operation failed
    ///
    /// Example: invalid input, parse error, type mismatch, auth failure
    Error = b'E',

    /// **Warning (W)** - Potential issue or caveat
    ///
    /// Example: deprecated API, performance concern, edge case
    Warning = b'W',

    /// **Critical (C)** - Severe issue requiring attention
    ///
    /// Example: data corruption, security breach, checksum fail
    Critical = b'C',

    /// **Blocked (B)** - Execution blocked/waiting
    ///
    /// Example: deadlock, I/O wait, network unavailable, resource locked
    Blocked = b'B',

    /// **Success (S)** - Operation succeeded
    ///
    /// Example: compilation successful, tests passed, deployment complete
    Success = b'S',

    /// **Completed (K)** - Task or phase completed
    ///
    /// Example: parsing complete, type-checking done, optimization finished
    Completed = b'K',

    /// **Info (I)** - General informational events
    ///
    /// Example: server started, config loaded, milestone reached, status updates
    Info = b'I',

    /// **Trace (T)** - Execution traces and instrumentation
    ///
    /// Example: probe data, function entry/exit, timing measurements, thread events
    Trace = b'T',
}

impl Severity {
    /// Get the single-character code (E, W, C, B, S, K, I, T)
    pub const fn as_char(self) -> char {
        self as u8 as char
    }

    /// Get the severity level as a number (for ordering/filtering)
    ///
    /// Higher numbers = more severe/important (Trace=0 ... Error=7)
    ///
    /// Note: Success/Completed are treated as low-priority (similar to Info/Trace)
    /// since they're positive outcomes that don't require immediate action.
    pub const fn level(self) -> u8 {
        match self {
            Severity::Trace => 0,
            Severity::Info => 1,
            Severity::Completed => 2,
            Severity::Success => 3,
            Severity::Warning => 4,
            Severity::Critical => 5,
            Severity::Blocked => 6,
            Severity::Error => 7,
        }
    }

    /// Check if this severity represents a **positive outcome** (success/completion)
    ///
    /// Returns `true` for Success and Completed severities.
    pub const fn is_positive(self) -> bool {
        matches!(self, Severity::Success | Severity::Completed)
    }
}

impl fmt::Display for Severity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.as_char())
    }
}

// ============================================================================
// Code (4-part: SEVERITY.COMPONENT.PRIMARY.SEQUENCE)
// ============================================================================

/// Waddling diagnostic code: `SEVERITY.COMPONENT.PRIMARY.SEQUENCE`
///
/// A lightweight, type-safe diagnostic code for the Waddling ecosystem.
/// Supports all severity levels (errors, warnings, success, info, traces).
///
/// # Format
///
/// `SEVERITY.COMPONENT.PRIMARY.SEQUENCE` → `E.CRYPTO.SALT.001`
///
/// Where SEVERITY is:
/// - `E` = Error (operation failed)
/// - `W` = Warning (potential issue)
/// - `C` = Critical (severe issue)
/// - `B` = Blocked (execution blocked)
/// - `S` = Success (operation succeeded)
/// - `K` = Completed (task finished)
/// - `I` = Info (informational events)
/// - `T` = Trace (execution traces, probes)
///
/// # Examples
///
/// ```rust
/// use waddling_errors::{Code, Severity};
///
/// // Using constructor methods (recommended)
/// const ERR_SALT: Code = Code::error("CRYPTO", "SALT", 1);
/// const WARN_DEPR: Code = Code::warning("API", "DEPR", 1);
/// const SUCCESS: Code = Code::success("BUILD", "DONE", 999);
///
/// assert_eq!(ERR_SALT.code(), "E.CRYPTO.SALT.001");
/// assert_eq!(WARN_DEPR.code(), "W.API.DEPR.001");
/// assert_eq!(SUCCESS.code(), "S.BUILD.DONE.999");
/// ```
///
/// # Using the prelude for ergonomic imports
///
/// ```rust
/// use waddling_errors::prelude::*;
///
/// const ERR_PARSE: Code = error("parser", "DOM", 1);
/// const WARN_API: Code = warning("api", "DEPR", 10);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Code {
    severity: Severity,
    component: &'static str,
    primary: &'static str,
    sequence: u16,
}

impl Code {
    /// Maximum length for component and primary strings
    const MAX_LEN: usize = 12;

    /// Minimum length for component and primary strings
    const MIN_LEN: usize = 2;

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

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

        // Validate primary length
        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)
    ///
    /// # Examples
    ///
    /// ```rust
    /// use waddling_errors::Code;
    ///
    /// const ERR: Code = Code::error("CRYPTO", "SALT", 1);
    /// assert_eq!(ERR.code(), "E.CRYPTO.SALT.001");
    /// ```
    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 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 (e.g., "E.CRYPTO.SALT.001")
    ///
    /// Use this in performance-critical paths to avoid String allocation.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use waddling_errors::{ErrorCode, Severity};
    /// use std::fmt::Write;
    ///
    /// let code = ErrorCode::new(Severity::Error, "CRYPTO", "SALT", 1);
    /// let mut buf = String::new();
    /// code.write_code(&mut buf).unwrap();
    /// assert_eq!(buf, "E.CRYPTO.SALT.001");
    /// ```
    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 (e.g., `Severity::Error`)
    pub const fn severity(&self) -> Severity {
        self.severity
    }

    /// Get component (e.g., "CRYPTO")
    pub const fn component(&self) -> &'static str {
        self.component
    }

    /// Get primary category (e.g., "SALT")
    pub const fn primary(&self) -> &'static str {
        self.primary
    }

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

    /// Get 5-character base62 hash (requires "hash" feature)
    ///
    /// Returns alphanumeric hash (0-9, A-Z, a-z only) safe for all logging systems.
    /// Provides excellent collision resistance: 916M combinations.
    #[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
        )
    }
}

// ============================================================================
// Optional ahash hashing
// ============================================================================

#[cfg(feature = "hash")]
mod hash {
    use ahash::RandomState;
    use core::hash::{BuildHasher, Hash, Hasher};

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

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

    /// Compute a 5-character hash from input string using base62 encoding
    ///
    /// Uses ahash with "Waddling" salt and encodes as base62 (alphanumeric only).
    ///
    /// **Collision resistance:**
    /// - Hex (base16, 4 chars): 65,536 combinations
    /// - Base62 (5 chars): 916,132,832 combinations (~14,000x better!)
    ///
    /// Base62 uses only safe alphanumeric: 0-9, A-Z, a-z (no special chars that might break logging/parsing)
    pub(crate) fn compute_hash(input: &str) -> String {
        // Create a deterministic hasher with "Waddling" salt
        const SALT: &str = "Waddling";
        let state = RandomState::with_seeds(
            0x576164646c696e67, // "Waddling" as u64 (partial)
            0x0000000000000000,
            0x0000000000000000,
            0x0000000000000000,
        );

        let mut hasher = state.build_hasher();
        SALT.hash(&mut hasher);
        input.hash(&mut hasher);
        let result = hasher.finish();

        // Take first 5 bytes for excellent distribution
        let bytes = [
            (result >> 56) as u8,
            (result >> 48) as u8,
            (result >> 40) as u8,
            (result >> 32) as u8,
            (result >> 24) as u8,
        ];

        // Convert to base62 encoding (alphanumeric only - safe for all logging systems)
        // 0-9, A-Z, a-z (62 chars total)
        const BASE62_CHARS: &[u8] =
            b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
        const BASE: u64 = 62;

        // Convert bytes to u64 for base62 conversion
        let mut num = 0u64;
        for &byte in &bytes {
            num = (num << 8) | (byte as u64);
        }

        // Convert to base62 (5 chars)
        let mut result_chars = [0u8; 5];
        let mut n = num;

        for i in (0..5).rev() {
            result_chars[i] = BASE62_CHARS[(n % BASE) as usize];
            n /= BASE;
        }

        // Convert to String (all chars are valid ASCII alphanumeric)
        String::from_utf8(result_chars.to_vec()).expect("base62 encoding produces valid UTF-8")
    }
}

// ============================================================================
// Tests
// ============================================================================

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

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

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

    #[test]
    fn test_severity_ordering() {
        assert!(Severity::Trace.level() < Severity::Error.level());
        assert!(Severity::Warning.level() < Severity::Critical.level());
    }

    #[test]
    fn test_severity_positive() {
        // Positive outcomes
        assert!(Severity::Success.is_positive());
        assert!(Severity::Completed.is_positive());

        // Not positive
        assert!(!Severity::Error.is_positive());
        assert!(!Severity::Warning.is_positive());
        assert!(!Severity::Critical.is_positive());
        assert!(!Severity::Blocked.is_positive());
        assert!(!Severity::Info.is_positive());
        assert!(!Severity::Trace.is_positive());
    }

    #[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); // 5 base62 chars

        // Verify only alphanumeric chars (safe for logging)
        assert!(hash1.chars().all(|c| c.is_ascii_alphanumeric()));
    }

    #[test]
    fn test_length_validation() {
        // Valid lengths (2-12 chars)
        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");

        // These will fail at compile-time, not runtime, so we document them:
        // const TOO_SHORT_COMPONENT: Code = Code::new(Severity::Error, "X", "VALID", 1); // Compile error!
        // const TOO_LONG_COMPONENT: Code = Code::new(Severity::Error, "THISISSOTOOLONG", "VALID", 1); // Compile error!
        // const TOO_SHORT_PRIMARY: Code = Code::new(Severity::Error, "VALID", "Y", 1); // Compile error!
        // const TOO_LONG_PRIMARY: Code = Code::new(Severity::Error, "VALID", "WAYTOOLONGPRIM", 1); // Compile error!
    }
}