miette

To provide visual context for errors, use the #[source_code] attribute to attach a SourceCode (like a String or NamedSource) to your diagnostic. You can then use #[label] to highlight specific parts of that source using a SourceSpan.

Key features:

• Primary Labels: Use #[label(primary, "...")] to designate the main issue (only one allowed per diagnostic).
• Collections of Labels: Use #[label(collection, "...")] on a field containing an iterator (like Vec<SourceSpan> or Vec<LabeledSpan>) to render multiple highlights.
• Custom Text: Labels can have specific text, or use the default text provided in the attribute.

use miette::{Diagnostic, SourceSpan};
use thiserror::Error;

#[derive(Diagnostic, Debug, Error)]
#[error("oops!")]
struct MyError {
    #[source_code]
    src: String,

    #[label(primary, "main issue")]
    primary_span: SourceSpan,

    #[label("This is the highlight")]
    err_span: SourceSpan,

    #[label("This is bad")]
    snip2: (usize, usize), // (usize, usize) implements Into<SourceSpan>

    #[label(collection, "related to this")]
    other_spans: Vec<SourceSpan>,
}

When writing a library, it is best practice to define concrete error types using thiserror and implement the miette::Diagnostic trait. This ensures compatibility with std::error::Error for consumers who do not use miette. You can use #[diagnostic] attributes to add metadata like error codes, URLs, and help text. Use #[diagnostic(transparent)] to wrap another diagnostic without losing its labels, or #[diagnostic(forward(field_name))] to forward the diagnostic to a specific field.

// lib/error.rs
use miette::{Diagnostic, SourceSpan};
use thiserror::Error;

#[derive(Error, Diagnostic, Debug)]
pub enum MyLibError {
    #[error(transparent)]
    #[diagnostic(code(my_lib::io_error))]
    IoError(#[from] std::io::Error),

    #[error("Oops it blew up")]
    #[diagnostic(code(my_lib::bad_code))]
    BadThingHappened,

    #[error(transparent)]
    // Use `#[diagnostic(transparent)]` to wrap another `Diagnostic`. You won't see labels otherwise
    #[diagnostic(transparent)]
    AnotherError(#[from] AnotherError),

    /// Forward the diagnostic to a particular field.
    #[error("other error")]
    #[diagnostic(forward(the_actual_diagnostic))]
    EvenMoreData {
        unrelated_field_1: String,
        unrelated_field_2: usize,

        #[source]
        the_actual_diagnostic: AnotherError,
    }
}

#[derive(Error, Diagnostic, Debug)]
#[error("another error")]
pub struct AnotherError {
   #[label("here")]
   pub at: SourceSpan
}

To show users exactly where an error occurred, include a SourceSpan and a #[source_code] field in your diagnostic struct.

• SourceSpan: A lightweight type representing a byte offset and length. It can be created from ranges like (0..5).into().
• #[label]: Highlights a specific part of the source code. You can use primary to indicate the main issue, or collection to provide multiple spans.
• NamedSource: Used to associate a name (like a filename) with the source string.

use miette::{Diagnostic, SourceSpan, NamedSource};
use thiserror::Error;

#[derive(Diagnostic, Debug, Error)]
#[error("oops")]
#[diagnostic(code(my_lib::random_error))]
pub struct MyErrorType {
    #[source_code]
    src: NamedSource<String>,

    #[label = "This is the highlight"]
    err_span: SourceSpan,

    #[label("This is bad")]
    snip2: (usize, usize), // (start, end) works via Into<SourceSpan>
}

You can define rich, diagnostic-capable error types by combining thiserror with miette's Diagnostic derive macro. This allows you to attach error codes, URLs, help text, and source code snippets to your errors.

Key attributes for #[diagnostic]:

• code(CODE): A unique error code.
• url(URL_TYPE): A link to more info. Use docsrs to automatically link to your crate's documentation on docs.rs.
• help(TEXT): Provides guidance to the user.
• severity(LEVEL): Sets the error severity (e.g., Warning).
• source_code: Marks a field as the source for snippets.
• label(TEXT): Marks a field as a snippet highlight.
• transparent: Used to wrap another Diagnostic without showing extra labels.
• forward(FIELD): Forwards the diagnostic to a specific field.

use miette::{Diagnostic, NamedSource, SourceSpan};
use thiserror::Error;

#[derive(Error, Debug, Diagnostic)]
#[error("oops!")]
#[diagnostic(
    code(oops::my::bad),
    url(docsrs),
    help("try doing it better next time?")
)]
struct MyBad {
    #[source_code]
    src: NamedSource<String>,
    #[label("This bit here")]
    bad_bit: SourceSpan,
}

The GraphicalReportHandler uses internal logic to determine how FancySpan objects interact with specific lines of text to build the visual report.

Line Visibility

For a given Line, the following checks are performed:

• span_applies: Returns true if the span is visible on this line (either in the gutter or under the text).
• span_applies_gutter: Returns true if the span should be visible in the gutter. This excludes spans that start and end entirely within the same line.
• span_flyby: Returns true if the span is a 'flyby'—a multi-line span that covers this line but does not begin or end within it.

Span Boundaries

• span_starts: Returns true if the line contains the beginning of the span.
• span_ends: Returns true if the line contains the end of the span.

impl Line {
    fn span_line_only(&self, span: &FancySpan) -> bool {
        span.offset() >= self.offset && span.offset() + span.len() <= self.offset + self.length
    }

    fn span_applies(&self, span: &FancySpan) -> bool {
        let spanlen = if span.len() == 0 { 1 } else { span.len() };
        (span.offset() >= self.offset && span.offset() < self.offset + self.length)
            || (span.offset() < self.offset && span.offset() + spanlen > self.offset + self.length)
            || (span.offset() + spanlen > self.offset && span.offset() + spanlen <= self.offset + self.length)
    }

    fn span_applies_gutter(&self, span: &FancySpan) -> bool {
        let spanlen = if span.len() == 0 { 1 } else { span.len() };
        self.span_applies(span)
            && !(
                (span.offset() >= self.offset && span.offset() < self.offset + self.length)
                    && (span.offset() + spanlen > self.offset
                        && span.offset() + spanlen <= self.offset + self.length)
            )
    }

    fn span_flyby(&self, span: &FancySpan) -> bool {
        span.offset() < self.offset
            && span.offset() + span.len() > self.offset + self.length
    }

    fn span_starts(&self, span: &FancySpan) -> bool {
        span.offset() >= self.offset
    }

    fn span_ends(&self, span: &FancySpan) -> bool {
        span.offset() + span.len() >= self.offset
            && span.offset() + span.len() <= self.offset + self.length
    }
}