diagnostic

Make errors easy to understand.

Core Types

• Level: Fatal, Warning, Info
• Label: Source location with optional column range and message
• Diagnostic: The full error with code, title, description, labels, and advice

Snippet Helpers

use diagnostic::{format_snippet, format_snippet_from_file};

// From string
let lines = format_snippet("line1\nline2\nthe error here\nline4", 3, 5, 5);
// Output:
//   3 | the error here
//       ^^^^^

// From file
let lines = format_snippet_from_file(Path::new("src/main.rs"), 10, 1, 8)?;

Location Macros

use diagnostic::{here, label_here};

// Capture source location
let loc = here!();
println!("{}:{}:{}", loc.file, loc.line, loc.column);

// Create label at current location
let label = label_here!("something went wrong");

Git Version

use diagnostic::GIT_VERSION;
println!("Built from: {}", GIT_VERSION);

The Problem Pattern

Define domain-specific Problem enums and implement Into<Diagnostic>:

pub enum Problem {
    Io { path: PathBuf, message: String },
    Json { path: PathBuf, line: usize, message: String },
}

impl From<Problem> for Diagnostic {
    fn from(p: Problem) -> Diagnostic {
        match p {
            Problem::Io { path, message } => {
                Diagnostic::fatal("IO-001", "IO error")
                    .with_description(message)
                    .with_label(Label::new(path.display(), 1))
            }
            Problem::Json { path, line, message } => {
                Diagnostic::fatal("JSON-001", "JSON parse error")
                    .with_description(message)
                    .with_label(Label::new(path.display(), line))
            }
        }
    }
}

Full Example

use diagnostic::{Diagnostic, Label, format_snippet};

let source = r#"{"name": "test", invalid}"#;
let d = Diagnostic::fatal("JSON-001", "JSON parse error")
    .with_description("Expected ':' after property name")
    .with_label(Label::new("config.json", 1).with_column(18))
    .with_snippet(format_snippet(source, 1, 18, 7))
    .with_advice("Check for missing colons or commas in your JSON");

println!("{}", d);

Output:

config.json:1:18 - error JSON-001: JSON parse error

Expected ':' after property name

  1 | {"name": "test", invalid}
                       ^^^^^^^

Check for missing colons or commas in your JSON