waddling-errors 0.6.0

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

### Generated Documentation


![Error Documentation Screenshot](docs/images/error-docs-screenshot.png)
*Auto-generated role-based error documentation with severity filtering, search, and detailed hints*

### Key Features


- ✅ **Type-safe** - Define your own component/primary enums with compile-time checking
- ✅ **Zero runtime dependencies** - Pure Rust with optional features (proc macros are compile-time only)
- ✅ **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


### Macro Approach (Recommended)


Minimal boilerplate with automatic documentation generation:

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

// Define your error structure
component! { Auth { value: "AUTH", docs: "Authentication" } }
primary! { Token { value: "TOKEN", docs: "Token errors" } }

// Define diagnostics with auto-registration
diag! {
    <json, html>,  // Auto-register for doc generation
    
    E.AUTH.TOKEN.EXPIRED: {
        message: "JWT token expired at {{timestamp}}",
        fields: [timestamp],
        
        'CR 'Pub description: "Your session has expired. Please log in again.",
        'CR 'Dev hints: ["Check token refresh logic", "Verify server time sync"],
        
        'R role: "Public",
        'R tags: ["auth", "security"],
    },
}

// Use in your code
let error = E_AUTH_TOKEN_EXPIRED;
println!("{}", error.runtime.full_code());  // "E.AUTH.TOKEN.EXPIRED"
```

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

### Manual Approach (Full Control)


For maximum flexibility, use the core trait-based approach:

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

---

## 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 automatic registration:

### Step 1: Define Errors with Auto-Registration


```rust
// src/errors/mod.rs
use waddling_errors_macros::diag;

diag! {
    <json, html>,  // Auto-register when loaded
    
    E.AUTH.TOKEN.MISSING: {
        message: "JWT token missing",
        'CR 'Pub description: "Authorization header not found",
        'CR 'Dev hints: ["Include Authorization: Bearer <token>"],
        'R role: "Public",
    },
}
```

### Step 2: Create Doc Generation Binary


```rust
// src/bin/doc_gen.rs
use my_app::errors::*;  // Loads errors, triggers auto-registration
use waddling_errors::doc_generator::{DocRegistry, HtmlRenderer, JsonRenderer};
use waddling_errors::registry;

fn main() {
    let mut doc_registry = DocRegistry::new(
        env!("CARGO_PKG_NAME"),
        env!("CARGO_PKG_VERSION")
    );
    
    // Auto-registered diagnostics are loaded into global registry
    registry::register_all_with_doc_gen(&mut doc_registry);
    
    // Generate documentation
    doc_registry.render_all_roles(
        vec![Box::new(HtmlRenderer::new()), Box::new(JsonRenderer)],
        "target/docs"
    ).unwrap();
    
    println!("✅ Documentation generated in target/docs/");
}
```

### Step 3: Configure in Cargo.toml


```toml
[[bin]]
name = "doc-gen"
path = "src/bin/doc_gen.rs"
required-features = ["doc-gen", "auto-register"]
```

### Step 4: Generate Documentation


```bash
cargo run --bin doc-gen --features doc-gen,auto-register
```

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

**Key Benefits:**
- ✅ Zero boilerplate - auto-registration handles everything
- ✅ Separate binary - no doc-gen overhead in production
- ✅ Clean main - no error imports polluting your app

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