Motivation

There is sometimes a need to add more explanations and information about an error than will fit in just the diagnostic message. It can also be helpful to include information about the error message itself. For example, information about why an error message was emitted and/or how to turn it off.

Prior art

miette diagnostics (which oxc_diagnostics is based on) is heavily inspired by the rustc compiler diagnostics. The rustc compiler has support for a note field for diagnostics similar to how we support a help field. It simply changes the name of the label, but provides a distinct place to put additional information.

Here are some examples of notes in rustc:

warning: unused variable: `y`
 --> src/main.rs:4:9
  |
4 |     let y = x;
  |         ^ help: if this is intentional, prefix it with an underscore: `_y`
  |
  = note: `#[warn(unused_variables)]` (part of `#[warn(unused)]`) on by default

error[E0382]: use of moved value: `x`
 --> src/main.rs:4:13
  |
2 |     let x = "hello world".to_string();
  |         - move occurs because `x` has type `String`, which does not implement the `Copy` trait
3 |     f(x);
  |       - value moved here
4 |     let y = x;
  |             ^ value used here after move
  |
note: consider changing this parameter type in function `f` to borrow instead if owning the value isn't necessary

error[E0283]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let x = "hello world".into();
  |         ^                 ---- type must be known at this point
  |
  = note: cannot satisfy `_: From<&str>`
  = note: required for `&str` to implement `Into<_>`
help: consider giving `x` an explicit type
  |
2 |     let x: /* Type */ = "hello world".into();
  |          ++++++++++++

Proposal

We add a new note field to the OxcDiagnosticInner struct:

#[derive(Debug, Clone, Eq, PartialEq)]
pub struct OxcDiagnosticInner {
    pub message: Cow<'static, str>,
    pub labels: Option<Vec<LabeledSpan>>,
    pub help: Option<Cow<'static, str>>,
+   pub note: Option<Cow<'static, str>>,
    pub severity: Severity,
    pub code: OxcCode,
    pub url: Option<Cow<'static, str>>,
}

As well as additional helper methods to use the field:

• OxcDiagnostic.with_note()
• OxcDiagnostic.note()

Use cases

I don't have any specific use cases in mind yet for this field, but we can use this issue to start collecting them. I think there are many lint rules that could benefit from this field as a way of providing more context.