Crate waddling_errors 

Ultra-minimal diagnostic code system for the Waddling ecosystem

Provides a standardized 4-part diagnostic code format:

Format: SEVERITY.COMPONENT.PRIMARY.SEQUENCE E.CRYPTO.SALT.001

Quick Start

Using Macros (Recommended)

use waddling_errors_macros::{component, diag, primary, sequence, setup};

pub mod components {
    use waddling_errors_macros::component;
    component! { Auth { docs: "Authentication" } }
}

pub mod primaries {
    use waddling_errors_macros::primary;
    primary! { Token { docs: "Token errors" } }
}

pub mod sequences {
    use waddling_errors_macros::sequence;
    sequence! { EXPIRED(17) { description: "Token expired" } }
}

setup! {
    components = crate::components,
    primaries = crate::primaries,
    sequences = crate::sequences,
}

diag! {
    <json, html>, // Auto-register for doc generation
    E.Auth.Token.EXPIRED: {
        message: "JWT token expired at {{timestamp}}",
        fields: [timestamp],
        'CR 'Pub description: "Session expired. Please log in again.",
        'R role: "Public",
    },
}

See waddling-errors-macros for complete macro documentation.

Manual Approach (Full Control)

Define your component and primary enums:

use waddling_errors::prelude::*;

#[derive(Debug, Copy, Clone)]
enum Component { Crypto, Network }

impl ComponentId for Component {
    fn as_str(&self) -> &'static str {
        match self {
            Component::Crypto => "CRYPTO",
            Component::Network => "NETWORK",
        }
    }
}

#[derive(Debug, Copy, Clone)]
enum Primary { Salt, Key, Timeout }

impl PrimaryId for Primary {
    fn as_str(&self) -> &'static str {
        match self {
            Primary::Salt => "SALT",
            Primary::Key => "KEY",
            Primary::Timeout => "TIMEOUT",
        }
    }
}

const ERR_SALT: Code<Component, Primary> = error(Component::Crypto, Primary::Salt, 1);
assert_eq!(ERR_SALT.code(), "E.CRYPTO.SALT.001");

Sequence Conventions

The Waddling ecosystem uses semantic sequence numbers:

Sequence	Meaning	Example
001	MISSING	Required item not provided
002	MISMATCH	Values don’t match expected type
003	INVALID	Format/validation failed
021	NOTFOUND	Resource not found
025	CORRUPTED	Data corruption detected
031-897	(project)	Domain-specific sequences
999	COMPLETE	Full completion

See docs/SEQUENCE-CONVENTIONS.md for complete list.

Error Registry Pattern

// errors.rs - Project error registry
use waddling_errors::prelude::*;

#[derive(Debug, Copy, Clone)]
pub enum Component { Crypto, Parse }

impl ComponentId for Component {
    fn as_str(&self) -> &'static str {
        match self {
            Component::Crypto => "CRYPTO",
            Component::Parse => "PARSE",
        }
    }
}

#[derive(Debug, Copy, Clone)]
pub enum Primary { Salt, Length, Depr }

impl PrimaryId for Primary {
    fn as_str(&self) -> &'static str {
        match self {
            Primary::Salt => "SALT",
            Primary::Length => "LENGTH",
            Primary::Depr => "DEPR",
        }
    }
}

pub const SALT_MISSING: Code<Component, Primary> = error(Component::Crypto, Primary::Salt, 1);
pub const KEY_LENGTH: Code<Component, Primary> = error(Component::Crypto, Primary::Length, 2);
pub const DEPRECATED_SYNTAX: Code<Component, Primary> = warning(Component::Parse, Primary::Depr, 1);

Re-exports

pub use traits::ComponentId;

pub use traits::ComponentIdDocumented;

pub use traits::ErrorMetadata;

pub use traits::FieldMeta;

pub use traits::PrimaryId;

pub use traits::PrimaryIdDocumented;

pub use traits::Role;

Modules

prelude

Commonly used types and functions

traits

Trait-based extensibility for error code components and primaries

Macros

component

Define component enums with automatic ComponentId trait implementation.

component_location

Register a component location without attaching to a module.

diag

Define complete diagnostic metadata with full 4-part error codes.

doc_gen_register

Generates documentation registration function for a diagnostic.

primary

Define primary enums with automatic PrimaryId trait implementation.

sequence

Define sequence constants with rich metadata.

setup

Configure module paths for waddling-errors definitions.

Structs

Code

Waddling diagnostic code: SEVERITY.COMPONENT.PRIMARY.SEQUENCE

Enums

Severity

Diagnostic severity level (single-character prefix for 4-part codes)

Functions

blocked

Create a blocked code

completed

Create a completed code

critical

Create a critical code

error

Create an error code

help

Create a help code

info

Create an info code

success

Create a success code

trace

Create a trace code

warning

Create a warning code

Attribute Macros

doc_gen

Attribute macro for automatic documentation generation

in_component

Mark modules or files as belonging to a specific component.