waddling-errors 0.2.0

# waddling-errors 🦆

**Ultra-minimal diagnostic code system**

[![Crates.io](https://img.shields.io/crates/v/waddling-errors.svg)](https://crates.io/crates/waddling-errors)
[![Documentation](https://docs.rs/waddling-errors/badge.svg)](https://docs.rs/waddling-errors)
[![License](https://img.shields.io/crates/l/waddling-errors.svg)](LICENSE)

---

## Overview

`waddling-errors` provides a **super ergonomic diagnostic code system** with consistent error code format generation.

### Key Features

- ✅ **Tiny** - Modular design, only include what you need
- ✅ **Zero dependencies by default** - Optional features for extended functionality
- ✅ **Semantic methods** - `is_blocking()`, `is_positive()`, `priority()`, etc.
- ✅ **Visual representation** - Emojis (🔥⚠️✅) and ANSI colors for terminal UIs
- ✅ **Serialization** - Optional Serde support for JSON/etc.
- ✅ **`no_std` compatible** - Works in embedded and WASM environments
- ✅ **Const-friendly** - Error codes can be defined as constants

---

## Why This Exists

Projects need **consistent error code formats** for diagnostic tooling integration.

### Standard Format

**4-Part Format** - consistent diagnostic codes:
```
SEVERITY.COMPONENT.PRIMARY.SEQUENCE → E.CRYPTO.SALT.001
```

Where SEVERITY can be:

| Severity     | Code | Emoji | Use Case                          |
|--------------|------|-------|-----------------------------------|
| **Error**    | `E`  | ❌    | Invalid input, logic errors       |
| **Warning**  | `W`  | ⚠️    | Deprecated API, edge cases        |
| **Critical** | `C`  | 🔥    | Data corruption, security breach  |
| **Blocked**  | `B`  | 🚫    | Deadlock, I/O wait, network down  |
| **Success**  | `S`  | ✅    | Operation succeeded               |
| **Completed**| `K`  | ✔️    | Task/phase finished               |
| **Info**     | `I`  | ℹ️    | Events, milestones, status        |
| **Trace**    | `T`  | 🔍    | Execution traces, probes, timing  |

**Solution:** `waddling-errors` provides a **single, minimal, flexible** implementation.

---

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
# Minimal (no optional features)
waddling-errors = { version = "0.1", default-features = false }

# With base62 hashing
waddling-errors = { version = "0.1", features = ["hash"] }

# With ANSI terminal colors
waddling-errors = { version = "0.1", features = ["ansi-colors"] }

# With emoji support
waddling-errors = { version = "0.1", features = ["emoji"] }

# With Serde serialization
waddling-errors = { version = "0.1", features = ["serde"] }

# All features
waddling-errors = { version = "0.1", features = ["hash", "ansi-colors", "emoji", "serde"] }
```

---

## Quick Start

```rust
use waddling_errors::prelude::*;

// Ultra-clean error definitions
const ERR_SALT: Code = error("CRYPTO", "SALT", 1);
const WARN_DEPRECATED: Code = warning("API", "FUNC", 10);
const SUCCESS_BUILD: Code = success("BUILD", "DONE", 999);

fn validate(data: &[u8]) -> Result<(), Code> {
    if data.is_empty() {
        return Err(ERR_SALT);
    }
    Ok(())
}

fn main() {
    println!("{}", ERR_SALT.code()); // "E.CRYPTO.SALT.001"
    
    // Semantic methods
    println!("Is blocking? {}", ERR_SALT.severity().is_blocking()); // true
    println!("Priority: {}", ERR_SALT.severity().priority()); // 7 (highest)
    
    // Visual representation
    println!("{} Error occurred!", ERR_SALT.severity().emoji()); // "❌ Error occurred!"
}
```

---

## Usage Patterns

waddling-errors provides **multiple API styles** - choose what fits your project:

### 1. Convenience Functions (Recommended)

The cleanest, most ergonomic approach:

```rust
use waddling_errors::prelude::*;

// All 8 severity levels
const ERR: Code = error("CRYPTO", "SALT", 1);
const WARN: Code = warning("API", "FUNC", 10);
const CRIT: Code = critical("MEM", "CORRUPT", 23);
const BLOCK: Code = blocked("THREAD", "LOCK", 24);
const SUCCESS: Code = success("BUILD", "DONE", 999);
const COMPLETE: Code = completed("PARSE", "DONE", 999);
const INFO: Code = info("SERVER", "START", 1);
const TRACE: Code = trace("PROBE", "THREAD", 1);
```

### 2. Method Style

Object-oriented approach:

```rust
use waddling_errors::Code;

const ERR: Code = Code::error("CRYPTO", "SALT", 1);
const WARN: Code = Code::warning("API", "FUNC", 10);
```

### 3. Explicit Severity

Full control when needed:

```rust
use waddling_errors::{Code, Severity};

const ERR: Code = Code::new(Severity::Error, "CRYPTO", "SALT", 1);
```

### Standalone Usage (No Dependencies)

Return diagnostic codes directly:

```rust
use waddling_errors::prelude::*;

const ERR_INVALID_SALT: Code = error("CRYPTO", "SALT", 1);

fn validate(data: &[u8]) -> Result<(), Code> {
    if data.is_empty() {
        return Err(ERR_INVALID_SALT);
    }
    Ok(())
}

// Or wrap in your own error type
#[derive(Debug)]
struct MyError {
    code: Code,
    message: String,
}

impl std::fmt::Display for MyError {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "[MYAPP.{}] {}", self.code.code(), self.message)
    }
}
```

See `examples/standalone.rs` for a complete example with no external dependencies.

---

### Error Registry Pattern (Recommended)

For larger projects, create a central error 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);
    
    // Build success (S.BUILD.*)
    pub const BUILD_COMPLETE: Code = success("BUILD", "DONE", 999);
}

// Use across your project
use errors::SALT_MISSING;

fn validate_salt(salt: &[u8]) -> Result<(), Code> {
    if salt.len() != 32 {
        return Err(SALT_MISSING);
    }
    Ok(())
}
```

**Benefits:**
- ✅ Centralized error definitions
- ✅ Easy to document and maintain
- ✅ Prevents duplicate sequence numbers
- ✅ IDE autocomplete for all error codes

---

## Semantic Methods

`Severity` provides rich semantic methods for intelligent error handling:

### Categorization

```rust
use waddling_errors::Severity;

// Check if execution should stop
if severity.is_blocking() {
    return Err(diagnostic);  // Error or Blocked
}

// Categorize outcomes
if severity.is_positive() {
    println!("✅ Success!");  // Success or Completed
} else if severity.is_negative() {
    println!("⚠️ Issue detected");  // Error, Warning, Critical, Blocked
} else {
    println!("ℹ️ Info");  // Info or Trace
}
```

### Priority Ordering

```rust
use waddling_errors::Severity;

// Sort diagnostics by priority (0=lowest, 7=highest)
diagnostics.sort_by_key(|d| d.severity.priority());

// Filter by severity level
let critical_issues: Vec<_> = diagnostics
    .iter()
    .filter(|d| d.severity >= Severity::Warning)
    .collect();
```

### Metadata

```rust
use waddling_errors::Severity;

let sev = Severity::Error;
println!("Char: {}", sev.as_char());        // "E"
println!("Name: {}", sev.as_str());         // "Error"
println!("Desc: {}", sev.description());    // "Operation failed"
println!("Priority: {}", sev.priority());   // 7
```

---

## Visual Representation

### Emojis (Feature Flag)

Perfect for modern terminal UIs and logs (requires `emoji` feature):

```rust
use waddling_errors::prelude::*;

println!("{} Build failed!", error("BUILD", "FAIL", 1).severity().emoji());
// Output: ❌ Build failed!

println!("{} Warning: deprecated API", warning("API", "DEPR", 1).severity().emoji());
// Output: ⚠️ Warning: deprecated API

println!("{} All tests passed!", success("TEST", "PASS", 1).severity().emoji());
// Output: ✅ All tests passed!
```

**Full emoji set:**
- ❌ Error
- 🚫 Blocked
- 🔥 Critical (stands out from warning!)
- ⚠️ Warning
- ✅ Success
- ✔️ Completed
- ℹ️ Info
- 🔍 Trace

### ANSI Colors (Feature Flag)

Enable with `features = ["ansi-colors"]`:

```rust
use waddling_errors::Severity;

let severity = Severity::Error;
println!(
    "{}Error: Operation failed{}",
    severity.ansi_color(),
    Severity::ANSI_RESET
);
// Output: Error in bold red

// Combine with emojis for maximum clarity
println!(
    "{}{} {}{}",
    severity.ansi_color(),
    severity.emoji(),
    "Critical failure",
    Severity::ANSI_RESET
);
// Output: ❌ Critical failure (in red)
```

---

## Serialization

Enable with `features = ["serde"]`:

```rust
use waddling_errors::prelude::*;
use serde_json;

let codes = vec![
    error("CRYPTO", "SALT", 1),
    warning("API", "DEPR", 10),
];

// Serialize to JSON
let json = serde_json::to_string(&codes)?;
// [{"severity":"Error","component":"CRYPTO","primary":"SALT","sequence":1}, ...]

// Severities support full round-trip
let severity = Severity::Error;
let json = serde_json::to_string(&severity)?;
let restored: Severity = serde_json::from_str(&json)?;
```

---

## Sequence Conventions

The Waddling ecosystem uses **semantic sequence numbers** for common patterns:

| 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                   |

**Benefits:** `.001` always means "missing" across ALL Waddling projects.

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

---

## Examples

Run the examples to see features in action:

```bash
# Basic emoji support
cargo run --example emoji_demo --features emoji

# ANSI colored terminal output
cargo run --example ansi_colors_demo --features ansi-colors

# Serde serialization
cargo run --example serde_demo --features serde

# Complete severity matrix
cargo run --example severity_matrix
```

---

## Documentation

- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
- **[docs/FEATURE_FLAGS.md](docs/FEATURE_FLAGS.md)** - Comprehensive feature guide
- **[API Documentation](https://docs.rs/waddling-errors)** - Full API reference on docs.rs

---

## License

Dual-licensed under MIT or Apache-2.0.