# charon-error - Project Instructions
## Overview
`charon-error` is a Rust library crate for structured error handling. It provides `ErrorReport` (error chains with frames), `ResultExt` (extension trait for Result/Option), sensitivity labels for data classification, panic hooks with issue submission, and tracing integration.
Crate name: `charon-error` (Rust identifier: `charon_error`)
License: MIT OR Apache-2.0
Repository: https://gitlab.com/ralpha9/charon-error
## Architecture
```
src/
lib.rs # Crate root, public API re-exports, ResultER type alias
prelude.rs # Convenience imports (use charon_error::prelude::*)
errors/
mod.rs # Error types module
string_error.rs # StringError - simple string-based error type
report/
mod.rs # Core report module
error_report.rs # ErrorReport - the main error chain type
error_frame.rs # ErrorFrame, ErrorAttachment, ErrorSensitivityLabel
error_formating/
mod.rs # Formatting module
error_fmt.rs # ErrorFmt trait, ErrorFormatObj, ErrorFmtSettings, macros
attachments.rs # ErrorFmt impl for attachment HashMap
chrono.rs # ErrorFmt impl for DateTime
span.rs # ErrorFmt impl for SpanTrace
submit/
mod.rs # Issue submission module
submit_error_report.rs # SubmitErrorReport trait
gitlab_error_report.rs # GitLab implementation + GitLabERGlobalSettings
utils/
mod.rs # Utilities module
source_location.rs # SourceLocation, LinkDebugIde
panic_hook.rs # setup_panic! and setup_panic_simple! macros
```
## Data Flow
### Error Creation Flow
1. An error occurs (std::io::Error, custom error, etc.)
2. `ResultExt::change_context()` wraps it in an `ErrorReport` with an `ErrorFrame`
3. Each frame captures: error, source location, backtrace, tracing span, timestamp
4. Additional `.change_context()` calls push more frames onto the chain
5. `.error_attach()` adds key-value data with sensitivity labels to the latest frame
### Error Display Flow
1. `ErrorReport` implements `ErrorFmt` trait
2. `create_format_obj()` builds an `ErrorFormatObj` tree (JSON-like IR)
3. `ErrorFmtSettings` controls what fields appear at each detail level
4. `stringify()` converts the tree to a formatted string with indentation and color
### Panic Hook Flow
1. `setup_panic!` macro installs a `panic::set_hook` handler
2. On panic: extracts message from payload (supports &str, String, anyhow::Error, ErrorReport)
3. Checks if known error via user-provided function
4. If unknown: creates ErrorReport, generates GitLab issue URL, prints to stderr
5. Debug vs release builds show different levels of detail
## Development Commands
```bash
cargo check # Type check
cargo clippy # Lint
cargo fmt # Format code
cargo test # Run tests
cargo doc --no-deps # Generate documentation
```
## Key Conventions
- `#![forbid(unsafe_code)]` — No unsafe code in this crate
- `#![deny(clippy::all)]` — All clippy warnings are errors
- Uses `#[track_caller]` extensively to capture accurate source locations
- Uses `#[instrument]` from tracing for span capture
- `ErrorSensitivityLabel` wraps all user-facing data to control sharing
- `IndexMap` used instead of `HashMap` for deterministic key ordering in format output
- Macros (`setup_panic!`, `map!`, `format_string!`) are `#[macro_export]`
- The `prelude` module is the recommended import for users
- `ResultER<T>` is the standard return type (alias for `Result<T, ErrorReport>`)
