waddling-errors 0.7.3

# 🦆 waddling-errors

Core library for the [Waddling Diagnostic Protocol (WDP)](https://gitlab.com/AshutoshMahala/wdp-specs).

[![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)

## What This Library Provides

- **Core types**: `Code<C, P>`, `Severity`, `ComponentId`, `PrimaryId` traits
- **Doc generation**: HTML, JSON, and catalog renderers
- **Catalog formats**: Full, Compact, Minimal (WDP Part 9a compliant)
- **Custom renderers**: Implement `Renderer` trait for your own formats
- **Role-based filtering**: Control what documentation each audience sees

For an easier API with compile-time validation, see [waddling-errors-macros](https://crates.io/crates/waddling-errors-macros). The macros let you define your own module structure—`components`, `primaries`, `sequences` are just conventions, not requirements.

## Installation

```toml
[dependencies]
waddling-errors = "0.7"
```

For documentation generation:
```toml
waddling-errors = { version = "0.7", features = ["doc-gen"] }
```

## Core Usage

Define components and primaries, then create codes:

```rust
use waddling_errors::{Code, ComponentId, PrimaryId};

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

impl ComponentId for Component {
    fn as_str(&self) -> &'static str { "Auth" }
}

#[derive(Debug, Copy, Clone)]
enum Primary { Token }

impl PrimaryId for Primary {
    fn as_str(&self) -> &'static str { "Token" }
}

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

println!("{}", EXPIRED.code());  // E.Auth.Token.001
```

## Documentation Generation

Generate HTML docs, JSON, or WDP-compliant catalogs:

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

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

// Register errors, components, primaries...
registry.add_error(/* ... */);

// Generate outputs
registry.generate("./docs", &HtmlRenderer::default())?;
registry.generate("./docs", &JsonRenderer)?;
registry.generate("./docs", &CatalogRenderer::compact())?;
```

### Catalog Formats

```rust
use waddling_errors::doc_generator::CatalogRenderer;

CatalogRenderer::new()       // Full - all fields, for development
CatalogRenderer::compact()   // Compact - smaller, for production
CatalogRenderer::minimal()   // Minimal - smallest, hash-to-code only
```

### Custom Renderers

Implement the `Renderer` trait:

```rust
use waddling_errors::doc_generator::{Renderer, DocRegistry, ErrorDoc};

struct XmlRenderer;

impl Renderer for XmlRenderer {
    fn format_name(&self) -> &str { "xml" }

    fn render(
        &self,
        registry: &DocRegistry,
        errors: &[&ErrorDoc],
        output_path: &std::path::Path,
        filter_role: Option<waddling_errors::Role>,
    ) -> std::io::Result<()> {
        // Generate your format
        Ok(())
    }
}
```

### HTML Customization

```rust
use waddling_errors::doc_generator::{HtmlRenderer, HtmlCustomization};

let renderer = HtmlRenderer::new()
    .with_customization(
        HtmlCustomization::new()
            .with_logo("https://example.com/logo.png", Some("My Project"))
            .with_accent_color("#3498db")
            .with_footer("© 2024 My Company")
    );
```

## Feature Flags

| Feature | Description | Default |
|---------|-------------|---------|
| `macros` | Re-export macros | Yes |
| `std` | Standard library | No |
| `doc-gen` | Documentation generation (requires std) | No |
| `metadata` | Compile-time metadata | No |
| `serde` | Serialization | No |

Default: `no_std + alloc`. For bare metal: `default-features = false`.

## Documentation

- [Feature Flags](docs/FEATURE_FLAGS.md)
- [Catalog Guide](docs/CATALOG_GUIDE.md)
- [API Reference](https://docs.rs/waddling-errors)

## License

MIT or Apache-2.0.