facet-miette

facet-miette

Derive miette::Diagnostic for your error types using facet's plugin system. Get rich error reporting with source spans, error codes, help text, and more.

Usage

use facet::Facet;
use facet_miette as diagnostic;
use miette::SourceSpan;

#[derive(Facet, Debug)]
#[facet(derive(Error, facet_miette::Diagnostic))]
pub enum ParseError {
    /// Unexpected token in input
    #[facet(diagnostic::code = "parse::unexpected_token")]
    #[facet(diagnostic::help = "Check for typos or missing delimiters")]
    UnexpectedToken {
        #[facet(diagnostic::source_code)]
        src: String,
        #[facet(diagnostic::label = "this token was unexpected")]
        span: SourceSpan,
    },

    /// End of file reached unexpectedly
    #[facet(diagnostic::code = "parse::unexpected_eof")]
    UnexpectedEof,
}

Attributes

Container/Variant Level

• #[facet(diagnostic::code = "my_lib::error_code")] - Error code for this diagnostic
• #[facet(diagnostic::help = "Helpful message")] - Help text shown to user
• #[facet(diagnostic::url = "https://...")] - URL for more information
• #[facet(diagnostic::severity = "warning")] - Severity: "error", "warning", or "advice"

Field Level

• #[facet(diagnostic::source_code)] - Field containing the source text (must impl SourceCode)
• #[facet(diagnostic::label = "description")] - Field is a span to highlight with label
• #[facet(diagnostic::related)] - Field contains related diagnostics (iterator)

Integration with facet-error

Typically you'll use both Error and Diagnostic together:

use facet::Facet;
use facet_miette as diagnostic;

#[derive(Facet, Debug)]
#[facet(derive(Error, facet_miette::Diagnostic))]
pub enum MyError {
    /// Something went wrong while processing
    #[facet(diagnostic::code = "my_error::processing")]
    #[facet(diagnostic::help = "Try again with different input")]
    ProcessingError,
}

The Error derive (from facet-error) generates Display and Error implementations from doc comments, while Diagnostic adds miette's rich error reporting features.

LLM contribution policy

Sponsors

Thanks to all individual sponsors:

...along with corporate sponsors:

...without whom this work could not exist.

Special thanks

The facet logo was drawn by Misiasart.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.