waddling-errors 0.5.1

# waddling-errors 🦆


**Type-safe diagnostic code system with structured error codes**

[![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 structured diagnostic codes with a consistent 4-part format:

```
SEVERITY.COMPONENT.PRIMARY.SEQUENCE
```

```rust
E.AUTH.TOKEN.001    // Error in Auth component, Token category, sequence 001
W.PARSER.SYNTAX.003 // Warning in Parser component, Syntax category, sequence 003
S.BUILD.DONE.999    // Success in Build component, Done category, sequence 999
```

### Key Features


- ✅ **Type-safe** - Define your own component/primary enums with compile-time checking
- ✅ **Zero dependencies by default** - Modular features (doc-gen, hash, serde)
- ✅ **Semantic methods** - `is_blocking()`, `is_positive()`, `priority()` for intelligent error handling
- ✅ **Documentation generation** - Auto-generate JSON/HTML/Catalog docs with role-based filtering
- ✅ **Hash codes** - Optional 5-character base62 hashes for compact logging
- ✅ **Network efficiency** - Catalog renderer for 80% smaller payloads (IoT/mobile)
- ✅ **`no_std` compatible** - Works in embedded and WASM environments

---

## Installation


```toml
[dependencies]
# Default (no_std + alloc compatible, includes macros)

waddling-errors = "0.5"

# With documentation generation (requires std)

waddling-errors = { version = "0.5", features = ["std", "doc-gen", "hash", "serde"] }

# Pure no_std (no allocator)

waddling-errors = { version = "0.5", default-features = false }

# For procedural macros separately

waddling-errors-macros = "0.5"
```

**Default features:** `["macros"]` - Works in `no_std + alloc` environments.

See [docs/FEATURE_FLAGS.md](docs/FEATURE_FLAGS.md) for detailed feature information.

---

## Quick Start


### Manual Approach (Core Library)


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

// 1. Define your error structure
#[derive(Debug, Copy, Clone)]

enum Component { Auth, Parser, Database }

impl ComponentId for Component {
    fn as_str(&self) -> &'static str {
        match self {
            Component::Auth => "AUTH",
            Component::Parser => "PARSER",
            Component::Database => "DB",
        }
    }
}

#[derive(Debug, Copy, Clone)]

enum Primary { Token, Syntax, Connection }

impl PrimaryId for Primary {
    fn as_str(&self) -> &'static str {
        match self {
            Primary::Token => "TOKEN",
            Primary::Syntax => "SYNTAX",
            Primary::Connection => "CONN",
        }
    }
}

// 2. Create error codes
const ERR_TOKEN_MISSING: Code<Component, Primary> = 
    Code::error(Component::Auth, Primary::Token, 1);

// 3. Use them
fn authenticate(token: Option<&str>) -> Result<(), Code<Component, Primary>> {
    token.ok_or(ERR_TOKEN_MISSING)?;
    Ok(())
}

fn main() {
    println!("{}", ERR_TOKEN_MISSING.code());  // "E.AUTH.TOKEN.001"
    println!("Priority: {}", ERR_TOKEN_MISSING.severity().priority());  // 8
    println!("Blocking? {}", ERR_TOKEN_MISSING.severity().is_blocking());  // true
}
```

### Macro Approach (Recommended)


For less boilerplate, use `waddling-errors-macros`:

```rust
use waddling_errors_macros::{component, primary, diag};

component! { Auth { value: "AUTH", docs: "Authentication" } }
primary! { Token { value: "TOKEN", docs: "Token errors" } }

diag! {
    E.AUTH.TOKEN.EXPIRED: {
        message: "JWT token expired at {timestamp}",
        fields: [timestamp],
        'CR 'Pub description: "Your session has expired. Please log in again.",
    }
}

let error = E_AUTH_TOKEN_EXPIRED;
```

See [waddling-errors-macros](../waddling-errors-macros/README.md) for macro documentation.

---

## Severity Levels


Nine severity levels with semantic methods:

| Severity     | Code | Priority | Blocking | Use Case                          |
|--------------|------|----------|----------|-----------------------------------|
| **Error**    | `E`  | 8        | Yes      | Invalid input, logic errors       |
| **Blocked**  | `B`  | 7        | Yes      | Deadlock, I/O wait, network down  |
| **Critical** | `C`  | 6        | No       | Data corruption, resource exhaustion |
| **Warning**  | `W`  | 5        | No       | Deprecated API, edge cases        |
| **Help**     | `H`  | 4        | No       | Helpful suggestions, tips         |
| **Success**  | `S`  | 3        | No       | Operation succeeded               |
| **Completed**| `K`  | 2        | No       | Task/phase finished               |
| **Info**     | `I`  | 1        | No       | Events, milestones, status        |
| **Trace**    | `T`  | 0        | No       | Execution traces, probes, timing  |

```rust
let severity = Severity::Error;

severity.is_blocking();   // true - stops execution
severity.is_negative();   // true - indicates failure
severity.is_positive();   // false
severity.priority();      // 8 (0-8 scale)
```

Optional emoji/ANSI color support available with features. See [FEATURE_FLAGS.md](docs/FEATURE_FLAGS.md).

---

## Documentation Generation


Generate searchable HTML and JSON documentation with role-based filtering:

```rust
use waddling_errors::doc_generator::{DocRegistry, JsonRenderer, HtmlRenderer};
use waddling_errors::Role;

let mut registry = DocRegistry::new("My API", "1.0.0");

// Register components and errors
registry.register_component("AUTH", Some("Authentication system"), &[], &["security"])?;
registry.register_code_extended(
    &ERR_TOKEN_MISSING,
    "JWT token missing from Authorization header",
    &["Include Authorization: Bearer <token> header"],
    &["auth", "security"],
    Some(Role::Public),
    &[], None, &[],
)?;

// Generate documentation for all roles
registry.render_all_roles(
    vec![Box::new(JsonRenderer), Box::new(HtmlRenderer::new())],
    "target/docs"
)?;

// Generates:
//   myapp-pub.html, myapp-pub.json   - Public documentation
//   myapp-dev.html, myapp-dev.json   - Developer documentation
//   myapp-int.html, myapp-int.json   - Internal documentation
```

**Documentation Roles:**
- `Role::Public` - End-user facing errors (sanitized, safe)
- `Role::Developer` - For contributors (debugging context)
- `Role::Internal` - Full team visibility (sensitive details)

See [docs/DOC_GENERATION_GUIDE.md](docs/DOC_GENERATION_GUIDE.md) for complete guide.

---

## Network Efficiency (Catalog Renderer)


Generate compact catalogs for efficient error transmission:

```rust
use waddling_errors::doc_generator::{CatalogRenderer, CatalogFormat};

// Generate hash-to-error catalog
let catalog = CatalogRenderer::new(CatalogFormat::Compact);
registry.render(vec![Box::new(catalog)], "target/catalog")?;

// Server sends: {"h":"jGKFp","f":{"temp":"45.2"}}  (40 bytes)
// Client expands: "Temperature 45.2°C exceeds threshold"
```

**Benefits:**
- 80% smaller network payloads for IoT/mobile
- Multi-language support (same hash, different catalogs)
- Offline-first apps (cache catalog locally)

See [docs/CATALOG_GUIDE.md](docs/CATALOG_GUIDE.md) for complete guide.

---

## no_std Support


The library is `no_std` compatible by default and works in embedded/WASM environments:

**Default (no_std + alloc):**
```toml
[dependencies]
waddling-errors = "0.5"  # Works with allocator
```

**Pure no_std (no allocator):**
```toml
[dependencies]
waddling-errors = { version = "0.5", default-features = false }
```

**Example:**
```rust
#![no_std]

extern crate alloc;

use waddling_errors::prelude::*;

// Works without std!
const ERR: Code<Component, Primary> = Code::error(Component::Auth, Primary::Token, 1);
```

**For documentation generation (requires std):**
```toml
waddling-errors = { version = "0.5", features = ["std", "doc-gen", "metadata"] }
```

---

## Hash Codes


Enable 5-character base62 hashes for compact logging:

```toml
waddling-errors = { version = "0.5", features = ["hash"] }
```

```rust
const ERR: Code<Component, Primary> = Code::error(Component::Auth, Primary::Token, 1);

println!("{} → #{}", ERR.code(), ERR.hash());
// E.AUTH.TOKEN.001 → #jGKFp

// Use in logs for quick searches
log::error!("#{} Authentication failed", ERR.hash());
```

---

## Sequence Conventions


Semantic sequence numbers provide consistency across projects:

| Sequence | Meaning    | Example                           |
|----------|------------|-----------------------------------|
| 001      | MISSING    | Required item not provided        |
| 003      | INVALID    | Format/validation failed          |
| 007      | DUPLICATE  | Rate limit or duplicate entry     |
| 008      | DENIED     | Permission/access denied          |
| 021      | NOTFOUND   | Resource not found                |
| 025      | CORRUPTED  | Data corruption detected          |
| 999      | COMPLETE   | Full completion                   |

See [docs/SEQUENCE-CONVENTIONS.md](docs/SEQUENCE-CONVENTIONS.md) for the complete list.

---

## Examples


**Basic usage:**
```bash
cargo run --example trait_based_enums
```

**With documentation metadata:**
```bash
cargo run --example trait_based_documented
```

**Production pattern** (6 components, 31 errors, role-based docs):
```bash
cargo run --example complete_system --features "doc-gen,hash"
```

**HTML customization:**
```bash
cargo run --example html_customization_demo --features "doc-gen,metadata"
```

**no_std/WASM:**
```bash
# Pure no_std

cargo build --example wasm_minimal --target wasm32-unknown-unknown --no-default-features

# With no_std example

cargo run --example no_std_example --no-default-features
```

See [examples/](examples/) directory for all examples.

---

## Documentation


### User Guides

- [Feature Flags](docs/FEATURE_FLAGS.md) - Optional features and configuration
- [Sequence Conventions](docs/SEQUENCE-CONVENTIONS.md) - Semantic sequence patterns
- [Catalog Guide](docs/CATALOG_GUIDE.md) - Network efficiency & i18n
- [Doc Generation Guide](docs/DOC_GENERATION_GUIDE.md) - Documentation workflow
- [HTML Customization](docs/HTML_CUSTOMIZATION.md) - Branding your docs

### API Reference

- [API Documentation](https://docs.rs/waddling-errors) - Complete API reference on docs.rs

### Related Crates

- [waddling-errors-macros](../waddling-errors-macros/README.md) - Procedural macros (recommended)
- [waddling-errors-hash](../waddling-errors-hash/README.md) - Hash generation implementation

---

## License


Dual-licensed under MIT or Apache-2.0. See [LICENSE-MIT](../LICENSE-MIT) and [LICENSE-APACHE](../LICENSE-APACHE).