solar-interface 0.2.0

//! Diagnostics implementation.
//!
//! Modified from [`rustc_errors`](https://github.com/rust-lang/rust/blob/520e30be83b4ed57b609d33166c988d1512bf4f3/compiler/rustc_errors/src/diagnostic.rs).

use crate::{SourceMap, Span};
use anstyle::{AnsiColor, Color};
use std::{
    borrow::Cow,
    fmt::{self, Write},
    hash::{Hash, Hasher},
    iter,
    ops::Deref,
    panic::Location,
};

mod builder;
pub use builder::{DiagBuilder, EmissionGuarantee};

mod context;
pub use context::{DiagCtxt, DiagCtxtFlags};

mod emitter;
pub use emitter::{
    DynEmitter, Emitter, HumanBufferEmitter, HumanEmitter, InMemoryEmitter, LocalEmitter,
    SilentEmitter,
};
#[cfg(feature = "json")]
pub use emitter::{JsonEmitter, Severity, SolcDiagnostic, SourceLocation};

mod message;
pub use message::{DiagMsg, MultiSpan, SpanLabel};

/// Represents all the diagnostics emitted up to a certain point.
///
/// Returned by [`DiagCtxt::emitted_diagnostics`].
pub struct EmittedDiagnostics(pub(crate) String);

impl fmt::Debug for EmittedDiagnostics {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

impl fmt::Display for EmittedDiagnostics {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

impl std::error::Error for EmittedDiagnostics {}

impl EmittedDiagnostics {
    /// Returns `true` if no diagnostics have been emitted.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

/// Useful type to use with [`Result`] indicate that an error has already been reported to the user,
/// so no need to continue checking.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ErrorGuaranteed(());

impl fmt::Debug for ErrorGuaranteed {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("ErrorGuaranteed")
    }
}

impl ErrorGuaranteed {
    /// Creates a new `ErrorGuaranteed`.
    ///
    /// Use of this method is discouraged.
    #[inline]
    pub const fn new_unchecked() -> Self {
        Self(())
    }
}

/// Marker type which enables implementation of `create_bug` and `emit_bug` functions for
/// bug diagnostics.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct BugAbort;

/// Signifies that the compiler died with an explicit call to `.bug` rather than a failed assertion,
/// etc.
pub struct ExplicitBug;

/// Marker type which enables implementation of fatal diagnostics.
pub struct FatalAbort;

/// Diag ID.
///
/// Use [`error_code!`](crate::error_code) to create an error code diagnostic ID.
///
/// # Examples
///
/// ```
/// # use solar_interface::{diagnostics::DiagId, error_code};
/// let id: DiagId = error_code!(1234);
/// ```
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct DiagId {
    s: Cow<'static, str>,
}

impl DiagId {
    /// Creates a new diagnostic ID from a number.
    ///
    /// This should be used for custom lints. For solc-like error codes, use
    /// the [`error_code!`](crate::error_code) macro.
    pub fn new_str(s: impl Into<Cow<'static, str>>) -> Self {
        Self { s: s.into() }
    }

    /// Creates an error code diagnostic ID.
    ///
    /// Use [`error_code!`](crate::error_code) instead.
    #[doc(hidden)]
    #[cfg_attr(debug_assertions, track_caller)]
    pub fn new_from_macro(id: u32) -> Self {
        debug_assert!((1..=9999).contains(&id), "error code must be in range 0001-9999");
        Self { s: Cow::Owned(format!("{id:04}")) }
    }

    /// Returns the diagnostic ID as a string slice.
    pub fn as_str(&self) -> &str {
        &self.s
    }
}

/// Used for creating an error code. The input must be exactly 4 decimal digits.
///
/// # Examples
///
/// ```
/// # use solar_interface::{diagnostics::DiagId, error_code};
/// let code: DiagId = error_code!(1234);
/// ```
#[macro_export]
macro_rules! error_code {
    ($id:literal) => {
        $crate::diagnostics::DiagId::new_from_macro($id)
    };
}

/// Diag level.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Level {
    /// For bugs in the compiler. Manifests as an ICE (internal compiler error) panic.
    ///
    /// Its `EmissionGuarantee` is `BugAbort`.
    Bug,

    /// An error that causes an immediate abort. Used for things like configuration errors,
    /// internal overflows, some file operation errors.
    ///
    /// Its `EmissionGuarantee` is `FatalAbort`.
    Fatal,

    /// An error in the code being compiled, which prevents compilation from finishing. This is the
    /// most common case.
    ///
    /// Its `EmissionGuarantee` is `ErrorGuaranteed`.
    Error,

    /// A warning about the code being compiled. Does not prevent compilation from finishing.
    ///
    /// Its `EmissionGuarantee` is `()`.
    Warning,

    /// A message giving additional context. Rare, because notes are more commonly attached to
    /// other diagnostics such as errors.
    ///
    /// Its `EmissionGuarantee` is `()`.
    Note,

    /// A note that is only emitted once. Rare, mostly used in circumstances relating to lints.
    ///
    /// Its `EmissionGuarantee` is `()`.
    OnceNote,

    /// A message suggesting how to fix something. Rare, because help messages are more commonly
    /// attached to other diagnostics such as errors.
    ///
    /// Its `EmissionGuarantee` is `()`.
    Help,

    /// A help that is only emitted once. Rare.
    ///
    /// Its `EmissionGuarantee` is `()`.
    OnceHelp,

    /// Similar to `Note`, but used in cases where compilation has failed. Rare.
    ///
    /// Its `EmissionGuarantee` is `()`.
    FailureNote,

    /// Only used for lints.
    ///
    /// Its `EmissionGuarantee` is `()`.
    Allow,
}

impl Level {
    /// Returns the string representation of the level.
    pub fn to_str(self) -> &'static str {
        match self {
            Self::Bug => "error: internal compiler error",
            Self::Fatal | Self::Error => "error",
            Self::Warning => "warning",
            Self::Note | Self::OnceNote => "note",
            Self::Help | Self::OnceHelp => "help",
            Self::FailureNote => "failure-note",
            Self::Allow
            // | Self::Expect(_)
            => unreachable!(),
        }
    }

    /// Returns `true` if this level is an error.
    #[inline]
    pub fn is_error(self) -> bool {
        match self {
            Self::Bug | Self::Fatal | Self::Error | Self::FailureNote => true,

            Self::Warning
            | Self::Note
            | Self::OnceNote
            | Self::Help
            | Self::OnceHelp
            | Self::Allow => false,
        }
    }

    /// Returns `true` if this level is a note.
    #[inline]
    pub fn is_note(self) -> bool {
        match self {
            Self::Note | Self::OnceNote => true,

            Self::Bug
            | Self::Fatal
            | Self::Error
            | Self::FailureNote
            | Self::Warning
            | Self::Help
            | Self::OnceHelp
            | Self::Allow => false,
        }
    }

    pub fn is_failure_note(&self) -> bool {
        matches!(*self, Self::FailureNote)
    }

    /// Returns the style of this level.
    #[inline]
    pub const fn style(self) -> anstyle::Style {
        anstyle::Style::new().fg_color(self.color()).bold()
    }

    /// Returns the color of this level.
    #[inline]
    pub const fn color(self) -> Option<Color> {
        match self.ansi_color() {
            Some(c) => Some(Color::Ansi(c)),
            None => None,
        }
    }

    /// Returns the ANSI color of this level.
    #[inline]
    pub const fn ansi_color(self) -> Option<AnsiColor> {
        // https://github.com/rust-lang/rust/blob/99472c7049783605444ab888a97059d0cce93a12/compiler/rustc_errors/src/lib.rs#L1768
        match self {
            Self::Bug | Self::Fatal | Self::Error => Some(AnsiColor::BrightRed),
            Self::Warning => {
                Some(if cfg!(windows) { AnsiColor::BrightYellow } else { AnsiColor::Yellow })
            }
            Self::Note | Self::OnceNote => Some(AnsiColor::BrightGreen),
            Self::Help | Self::OnceHelp => Some(AnsiColor::BrightCyan),
            Self::FailureNote | Self::Allow => None,
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Style {
    MainHeaderMsg,
    HeaderMsg,
    LineAndColumn,
    LineNumber,
    Quotation,
    UnderlinePrimary,
    UnderlineSecondary,
    LabelPrimary,
    LabelSecondary,
    NoStyle,
    Level(Level),
    Highlight,
    Addition,
    Removal,
}

impl Style {
    /// Converts the style to an [`anstyle::Style`].
    pub const fn to_color_spec(self, level: Level) -> anstyle::Style {
        use AnsiColor::*;

        /// On Windows, BRIGHT_BLUE is hard to read on black. Use cyan instead.
        ///
        /// See [rust-lang/rust#36178](https://github.com/rust-lang/rust/pull/36178).
        const BRIGHT_BLUE: Color = Color::Ansi(if cfg!(windows) { BrightCyan } else { BrightBlue });
        const GREEN: Color = Color::Ansi(BrightGreen);
        const MAGENTA: Color = Color::Ansi(BrightMagenta);
        const RED: Color = Color::Ansi(BrightRed);
        const WHITE: Color = Color::Ansi(BrightWhite);

        let s = anstyle::Style::new();
        match self {
            Self::Addition => s.fg_color(Some(GREEN)),
            Self::Removal => s.fg_color(Some(RED)),
            Self::LineAndColumn => s,
            Self::LineNumber => s.fg_color(Some(BRIGHT_BLUE)).bold(),
            Self::Quotation => s,
            Self::MainHeaderMsg => if cfg!(windows) { s.fg_color(Some(WHITE)) } else { s }.bold(),
            Self::UnderlinePrimary | Self::LabelPrimary => s.fg_color(level.color()).bold(),
            Self::UnderlineSecondary | Self::LabelSecondary => s.fg_color(Some(BRIGHT_BLUE)).bold(),
            Self::HeaderMsg | Self::NoStyle => s,
            Self::Level(level2) => s.fg_color(level2.color()).bold(),
            Self::Highlight => s.fg_color(Some(MAGENTA)).bold(),
        }
    }
}

/// Whether the original and suggested code are the same.
pub fn is_different(sm: &SourceMap, suggested: &str, sp: Span) -> bool {
    let found = match sm.span_to_snippet(sp) {
        Ok(snippet) => snippet,
        Err(e) => {
            warn!(error = ?e, "Invalid span {:?}", sp);
            return true;
        }
    };
    found != suggested
}

/// Whether the original and suggested code are visually similar enough to warrant extra wording.
pub fn detect_confusion_type(sm: &SourceMap, suggested: &str, sp: Span) -> ConfusionType {
    let found = match sm.span_to_snippet(sp) {
        Ok(snippet) => snippet,
        Err(e) => {
            warn!(error = ?e, "Invalid span {:?}", sp);
            return ConfusionType::None;
        }
    };

    let mut has_case_confusion = false;
    let mut has_digit_letter_confusion = false;

    if found.len() == suggested.len() {
        let mut has_case_diff = false;
        let mut has_digit_letter_confusable = false;
        let mut has_other_diff = false;

        let ascii_confusables = &['c', 'f', 'i', 'k', 'o', 's', 'u', 'v', 'w', 'x', 'y', 'z'];

        let digit_letter_confusables = [('0', 'O'), ('1', 'l'), ('5', 'S'), ('8', 'B'), ('9', 'g')];

        for (f, s) in iter::zip(found.chars(), suggested.chars()) {
            if f != s {
                if f.eq_ignore_ascii_case(&s) {
                    // Check for case differences (any character that differs only in case)
                    if ascii_confusables.contains(&f) || ascii_confusables.contains(&s) {
                        has_case_diff = true;
                    } else {
                        has_other_diff = true;
                    }
                } else if digit_letter_confusables.contains(&(f, s))
                    || digit_letter_confusables.contains(&(s, f))
                {
                    // Check for digit-letter confusables (like 0 vs O, 1 vs l, etc.)
                    has_digit_letter_confusable = true;
                } else {
                    has_other_diff = true;
                }
            }
        }

        // If we have case differences and no other differences
        if has_case_diff && !has_other_diff && found != suggested {
            has_case_confusion = true;
        }
        if has_digit_letter_confusable && !has_other_diff && found != suggested {
            has_digit_letter_confusion = true;
        }
    }

    match (has_case_confusion, has_digit_letter_confusion) {
        (true, true) => ConfusionType::Both,
        (true, false) => ConfusionType::Case,
        (false, true) => ConfusionType::DigitLetter,
        (false, false) => ConfusionType::None,
    }
}

/// Represents the type of confusion detected between original and suggested code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConfusionType {
    /// No confusion detected
    None,
    /// Only case differences (e.g., "hello" vs "Hello")
    Case,
    /// Only digit-letter confusion (e.g., "0" vs "O", "1" vs "l")
    DigitLetter,
    /// Both case and digit-letter confusion
    Both,
}

impl ConfusionType {
    /// Returns the appropriate label text for this confusion type.
    pub fn label_text(&self) -> &'static str {
        match self {
            Self::None => "",
            Self::Case => " (notice the capitalization)",
            Self::DigitLetter => " (notice the digit/letter confusion)",
            Self::Both => " (notice the capitalization and digit/letter confusion)",
        }
    }

    /// Combines two confusion types. If either is `Both`, the result is `Both`.
    /// If one is `Case` and the other is `DigitLetter`, the result is `Both`.
    /// Otherwise, returns the non-`None` type, or `None` if both are `None`.
    pub fn combine(self, other: Self) -> Self {
        match (self, other) {
            (Self::None, other) => other,
            (this, Self::None) => this,
            (Self::Both, _) | (_, Self::Both) => Self::Both,
            (Self::Case, Self::DigitLetter) | (Self::DigitLetter, Self::Case) => Self::Both,
            (Self::Case, Self::Case) => Self::Case,
            (Self::DigitLetter, Self::DigitLetter) => Self::DigitLetter,
        }
    }

    /// Returns true if this confusion type represents any kind of confusion.
    pub fn has_confusion(&self) -> bool {
        *self != Self::None
    }
}

/// Indicates the confidence in the correctness of a suggestion.
///
/// All suggestions are marked with an `Applicability`. Tools use the applicability of a suggestion
/// to determine whether it should be automatically applied or if the user should be consulted
/// before applying the suggestion.
#[cfg_attr(feature = "json", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "json", serde(rename_all = "kebab-case"))]
#[derive(Copy, Clone, Debug, Default, Hash, PartialEq, Eq, PartialOrd, Ord)]
pub enum Applicability {
    /// The suggestion is definitely what the user intended, or maintains the exact meaning of the
    /// code. This suggestion should be automatically applied.
    ///
    /// In case of multiple `MachineApplicable` suggestions (whether as part of
    /// the same `multipart_suggestion` or not), all of them should be
    /// automatically applied.
    MachineApplicable,

    /// The suggestion may be what the user intended, but it is uncertain. The suggestion should
    /// compile if it is applied.
    MaybeIncorrect,

    /// The suggestion contains placeholders like `(...)` or `{ /* fields */ }`. The suggestion
    /// cannot be applied automatically because it will fail to compile. The user will need to fill
    /// in the placeholders.
    HasPlaceholders,

    /// The applicability of the suggestion is unknown.
    #[default]
    Unspecified,
}

#[derive(Debug, Default, PartialEq, Eq, Clone, Copy, Hash)]
pub enum SuggestionStyle {
    /// Hide the suggested code when displaying this suggestion inline.
    HideCodeInline,
    /// Always hide the suggested code but display the message.
    HideCodeAlways,
    /// Do not display this suggestion in the cli output, it is only meant for tools.
    CompletelyHidden,
    /// Always show the suggested code.
    /// This will *not* show the code if the suggestion is inline *and* the suggested code is
    /// empty.
    #[default]
    ShowCode,
    /// Always show the suggested code independently.
    ShowAlways,
}

impl SuggestionStyle {
    fn hide_inline(&self) -> bool {
        !matches!(*self, Self::ShowCode)
    }
}

/// Represents the help messages seen on a diagnostic.
#[derive(Clone, Debug, PartialEq, Hash)]
pub enum Suggestions {
    /// Indicates that new suggestions can be added or removed from this diagnostic.
    ///
    /// `DiagInner`'s new_* methods initialize the `suggestions` field with
    /// this variant. Also, this is the default variant for `Suggestions`.
    Enabled(Vec<CodeSuggestion>),
    /// Indicates that suggestions cannot be added or removed from this diagnostic.
    ///
    /// Gets toggled when `.seal_suggestions()` is called on the `DiagInner`.
    Sealed(Box<[CodeSuggestion]>),
    /// Indicates that no suggestion is available for this diagnostic.
    ///
    /// Gets toggled when `.disable_suggestions()` is called on the `DiagInner`.
    Disabled,
}

impl Suggestions {
    /// Returns the underlying list of suggestions.
    pub fn unwrap_tag(&self) -> &[CodeSuggestion] {
        match self {
            Self::Enabled(suggestions) => suggestions,
            Self::Sealed(suggestions) => suggestions,
            Self::Disabled => &[],
        }
    }
}

impl Default for Suggestions {
    fn default() -> Self {
        Self::Enabled(vec![])
    }
}

impl Deref for Suggestions {
    type Target = [CodeSuggestion];

    fn deref(&self) -> &Self::Target {
        self.unwrap_tag()
    }
}

/// A structured suggestion for code changes.
/// Based on rustc's CodeSuggestion structure.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct CodeSuggestion {
    /// Each substitute can have multiple variants due to multiple
    /// applicable suggestions
    ///
    /// `foo.bar` might be replaced with `a.b` or `x.y` by replacing
    /// `foo` and `bar` on their own:
    ///
    /// ```ignore (illustrative)
    /// vec![
    ///     Substitution { parts: vec![(0..3, "a"), (4..7, "b")] },
    ///     Substitution { parts: vec![(0..3, "x"), (4..7, "y")] },
    /// ]
    /// ```
    ///
    /// or by replacing the entire span:
    ///
    /// ```ignore (illustrative)
    /// vec![
    ///     Substitution { parts: vec![(0..7, "a.b")] },
    ///     Substitution { parts: vec![(0..7, "x.y")] },
    /// ]
    /// ```
    pub substitutions: Vec<Substitution>,
    pub msg: DiagMsg,
    /// Visual representation of this suggestion.
    pub style: SuggestionStyle,
    /// Whether or not the suggestion is approximate
    ///
    /// Sometimes we may show suggestions with placeholders,
    /// which are useful for users but not useful for
    /// tools like rustfix
    pub applicability: Applicability,
}

/// A single part of a substitution, indicating a specific span to replace with a snippet.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct SubstitutionPart {
    pub span: Span,
    pub snippet: DiagMsg,
}

impl SubstitutionPart {
    pub fn is_addition(&self) -> bool {
        self.span.lo() == self.span.hi() && !self.snippet.is_empty()
    }

    pub fn is_deletion(&self) -> bool {
        self.span.lo() != self.span.hi() && self.snippet.is_empty()
    }

    pub fn is_replacement(&self) -> bool {
        self.span.lo() != self.span.hi() && !self.snippet.is_empty()
    }
}

/// A substitution represents a single alternative fix consisting of multiple parts.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct Substitution {
    pub parts: Vec<SubstitutionPart>,
}

/// A "sub"-diagnostic attached to a parent diagnostic.
/// For example, a note attached to an error.
#[derive(Clone, Debug, PartialEq, Hash)]
pub struct SubDiagnostic {
    pub level: Level,
    pub messages: Vec<(DiagMsg, Style)>,
    pub span: MultiSpan,
}

impl SubDiagnostic {
    /// Formats the diagnostic messages into a single string.
    pub fn label(&self) -> Cow<'_, str> {
        self.label_with_style(false)
    }

    /// Formats the diagnostic messages into a single string with ANSI color codes if applicable.
    pub fn label_with_style(&self, supports_color: bool) -> Cow<'_, str> {
        flatten_messages(&self.messages, supports_color, self.level)
    }
}

/// A compiler diagnostic.
#[must_use]
#[derive(Clone, Debug)]
pub struct Diag {
    pub(crate) level: Level,

    pub messages: Vec<(DiagMsg, Style)>,
    pub span: MultiSpan,
    pub children: Vec<SubDiagnostic>,
    pub code: Option<DiagId>,
    pub suggestions: Suggestions,

    pub created_at: &'static Location<'static>,
}

impl PartialEq for Diag {
    fn eq(&self, other: &Self) -> bool {
        self.keys() == other.keys()
    }
}

impl Hash for Diag {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.keys().hash(state);
    }
}

impl Diag {
    /// Creates a new `Diag` with a single message.
    #[track_caller]
    pub fn new<M: Into<DiagMsg>>(level: Level, msg: M) -> Self {
        Self::new_with_messages(level, vec![(msg.into(), Style::NoStyle)])
    }

    /// Creates a new `Diag` with multiple messages.
    #[track_caller]
    pub fn new_with_messages(level: Level, messages: Vec<(DiagMsg, Style)>) -> Self {
        Self {
            level,
            messages,
            code: None,
            span: MultiSpan::new(),
            children: vec![],
            suggestions: Suggestions::default(),
            // args: Default::default(),
            // sort_span: DUMMY_SP,
            // is_lint: false,
            created_at: Location::caller(),
        }
    }

    /// Returns `true` if this diagnostic is an error.
    #[inline]
    pub fn is_error(&self) -> bool {
        self.level.is_error()
    }

    /// Returns `true` if this diagnostic is a note.
    #[inline]
    pub fn is_note(&self) -> bool {
        self.level.is_note()
    }

    /// Formats the diagnostic messages into a single string.
    pub fn label(&self) -> Cow<'_, str> {
        flatten_messages(&self.messages, false, self.level)
    }

    /// Formats the diagnostic messages into a single string with ANSI color codes if applicable.
    pub fn label_with_style(&self, supports_color: bool) -> Cow<'_, str> {
        flatten_messages(&self.messages, supports_color, self.level)
    }

    /// Returns the messages of this diagnostic.
    pub fn messages(&self) -> &[(DiagMsg, Style)] {
        &self.messages
    }

    /// Returns the level of this diagnostic.
    pub fn level(&self) -> Level {
        self.level
    }

    /// Returns the code of this diagnostic as a string slice.
    pub fn id(&self) -> Option<&str> {
        self.code.as_ref().map(|code| code.as_str())
    }

    /// Fields used for `PartialEq` and `Hash` implementations.
    fn keys(&self) -> impl PartialEq + std::hash::Hash {
        (
            &self.level,
            &self.messages,
            &self.code,
            &self.span,
            &self.children,
            &self.suggestions,
            // self.args().collect(),
            // omit self.sort_span
            // &self.is_lint,
            // omit self.created_at
        )
    }
}

/// Setters.
impl Diag {
    /// Sets the span of this diagnostic.
    pub fn span(&mut self, span: impl Into<MultiSpan>) -> &mut Self {
        self.span = span.into();
        self
    }

    /// Sets the code of this diagnostic.
    pub fn code(&mut self, code: impl Into<DiagId>) -> &mut Self {
        self.code = Some(code.into());
        self
    }

    /// Adds a span/label to be included in the resulting snippet.
    ///
    /// This is pushed onto the [`MultiSpan`] that was created when the diagnostic
    /// was first built. That means it will be shown together with the original
    /// span/label, *not* a span added by one of the `span_{note,warn,help,suggestions}` methods.
    ///
    /// This span is *not* considered a ["primary span"][`MultiSpan`]; only
    /// the `Span` supplied when creating the diagnostic is primary.
    pub fn span_label(&mut self, span: Span, label: impl Into<DiagMsg>) -> &mut Self {
        self.span.push_span_label(span, label);
        self
    }

    /// Labels all the given spans with the provided label.
    /// See [`Self::span_label()`] for more information.
    pub fn span_labels(
        &mut self,
        spans: impl IntoIterator<Item = Span>,
        label: impl Into<DiagMsg>,
    ) -> &mut Self {
        let label = label.into();
        for span in spans {
            self.span_label(span, label.clone());
        }
        self
    }

    /// Adds a note with the location where this diagnostic was created and emitted.
    pub(crate) fn locations_note(&mut self, emitted_at: &Location<'_>) -> &mut Self {
        let msg = format!(
            "created at {},\n\
             emitted at {}",
            self.created_at, emitted_at
        );
        self.note(msg)
    }
}

/// Sub-diagnostics.
impl Diag {
    /// Add a warning attached to this diagnostic.
    pub fn warn(&mut self, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::Warning, msg, MultiSpan::new())
    }

    /// Prints the span with a warning above it.
    /// This is like [`Diag::warn()`], but it gets its own span.
    pub fn span_warn(&mut self, span: impl Into<MultiSpan>, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::Warning, msg, span)
    }

    /// Add a note to this diagnostic.
    pub fn note(&mut self, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::Note, msg, MultiSpan::new())
    }

    /// Prints the span with a note above it.
    /// This is like [`Diag::note()`], but it gets its own span.
    pub fn span_note(&mut self, span: impl Into<MultiSpan>, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::Note, msg, span)
    }

    pub fn highlighted_note(&mut self, messages: Vec<(impl Into<DiagMsg>, Style)>) -> &mut Self {
        self.sub_with_highlights(Level::Note, messages, MultiSpan::new())
    }

    /// Prints the span with a note above it.
    /// This is like [`Diag::note()`], but it gets emitted only once.
    pub fn note_once(&mut self, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::OnceNote, msg, MultiSpan::new())
    }

    /// Prints the span with a note above it.
    /// This is like [`Diag::note_once()`], but it gets its own span.
    pub fn span_note_once(
        &mut self,
        span: impl Into<MultiSpan>,
        msg: impl Into<DiagMsg>,
    ) -> &mut Self {
        self.sub(Level::OnceNote, msg, span)
    }

    /// Add a help message attached to this diagnostic.
    pub fn help(&mut self, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::Help, msg, MultiSpan::new())
    }

    /// Prints the span with a help above it.
    /// This is like [`Diag::help()`], but it gets its own span.
    pub fn help_once(&mut self, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::OnceHelp, msg, MultiSpan::new())
    }

    /// Add a help message attached to this diagnostic with a customizable highlighted message.
    pub fn highlighted_help(&mut self, msgs: Vec<(impl Into<DiagMsg>, Style)>) -> &mut Self {
        self.sub_with_highlights(Level::Help, msgs, MultiSpan::new())
    }

    /// Prints the span with some help above it.
    /// This is like [`Diag::help()`], but it gets its own span.
    pub fn span_help(&mut self, span: impl Into<MultiSpan>, msg: impl Into<DiagMsg>) -> &mut Self {
        self.sub(Level::Help, msg, span)
    }

    fn sub(
        &mut self,
        level: Level,
        msg: impl Into<DiagMsg>,
        span: impl Into<MultiSpan>,
    ) -> &mut Self {
        self.children.push(SubDiagnostic {
            level,
            messages: vec![(msg.into(), Style::NoStyle)],
            span: span.into(),
        });
        self
    }

    fn sub_with_highlights(
        &mut self,
        level: Level,
        messages: Vec<(impl Into<DiagMsg>, Style)>,
        span: MultiSpan,
    ) -> &mut Self {
        let messages = messages.into_iter().map(|(m, s)| (m.into(), s)).collect();
        self.children.push(SubDiagnostic { level, messages, span });
        self
    }
}

/// Suggestions.
impl Diag {
    /// Disallow attaching suggestions to this diagnostic.
    /// Any suggestions attached e.g. with the `span_suggestion_*` methods
    /// (before and after the call to `disable_suggestions`) will be ignored.
    pub fn disable_suggestions(&mut self) -> &mut Self {
        self.suggestions = Suggestions::Disabled;
        self
    }

    /// Prevent new suggestions from being added to this diagnostic.
    ///
    /// Suggestions added before the call to `.seal_suggestions()` will be preserved
    /// and new suggestions will be ignored.
    pub fn seal_suggestions(&mut self) -> &mut Self {
        if let Suggestions::Enabled(suggestions) = &mut self.suggestions {
            let suggestions_slice = std::mem::take(suggestions).into_boxed_slice();
            self.suggestions = Suggestions::Sealed(suggestions_slice);
        }
        self
    }

    /// Helper for pushing to `self.suggestions`.
    ///
    /// A new suggestion is added if suggestions are enabled for this diagnostic.
    /// Otherwise, they are ignored.
    fn push_suggestion(&mut self, suggestion: CodeSuggestion) {
        if let Suggestions::Enabled(suggestions) = &mut self.suggestions {
            suggestions.push(suggestion);
        }
    }

    /// Prints out a message with a suggested edit of the code.
    ///
    /// In case of short messages and a simple suggestion, rustc displays it as a label:
    ///
    /// ```text
    /// try adding parentheses: `(tup.0).1`
    /// ```
    ///
    /// The message
    ///
    /// * should not end in any punctuation (a `:` is added automatically)
    /// * should not be a question (avoid language like "did you mean")
    /// * should not contain any phrases like "the following", "as shown", etc.
    /// * may look like "to do xyz, use" or "to do xyz, use abc"
    /// * may contain a name of a function, variable, or type, but not whole expressions
    ///
    /// See [`CodeSuggestion`] for more information.
    pub fn span_suggestion(
        &mut self,
        span: Span,
        msg: impl Into<DiagMsg>,
        suggestion: impl Into<DiagMsg>,
        applicability: Applicability,
    ) -> &mut Self {
        self.span_suggestion_with_style(
            span,
            msg,
            suggestion,
            applicability,
            SuggestionStyle::ShowCode,
        );
        self
    }

    /// [`Diag::span_suggestion()`] but you can set the [`SuggestionStyle`].
    pub fn span_suggestion_with_style(
        &mut self,
        span: Span,
        msg: impl Into<DiagMsg>,
        suggestion: impl Into<DiagMsg>,
        applicability: Applicability,
        style: SuggestionStyle,
    ) -> &mut Self {
        self.push_suggestion(CodeSuggestion {
            substitutions: vec![Substitution {
                parts: vec![SubstitutionPart { snippet: suggestion.into(), span }],
            }],
            msg: msg.into(),
            style,
            applicability,
        });
        self
    }

    /// Show a suggestion that has multiple parts to it.
    /// In other words, multiple changes need to be applied as part of this suggestion.
    pub fn multipart_suggestion(
        &mut self,
        msg: impl Into<DiagMsg>,
        substitutions: Vec<(Span, DiagMsg)>,
        applicability: Applicability,
    ) -> &mut Self {
        self.multipart_suggestion_with_style(
            msg,
            substitutions,
            applicability,
            SuggestionStyle::ShowCode,
        );
        self
    }

    /// [`Diag::multipart_suggestion()`] but you can set the [`SuggestionStyle`].
    pub fn multipart_suggestion_with_style(
        &mut self,
        msg: impl Into<DiagMsg>,
        substitutions: Vec<(Span, DiagMsg)>,
        applicability: Applicability,
        style: SuggestionStyle,
    ) -> &mut Self {
        self.push_suggestion(CodeSuggestion {
            substitutions: vec![Substitution {
                parts: substitutions
                    .into_iter()
                    .map(|(span, snippet)| SubstitutionPart { span, snippet })
                    .collect(),
            }],
            msg: msg.into(),
            style,
            applicability,
        });
        self
    }
}

/// Flattens diagnostic messages, applying ANSI styles if requested.
fn flatten_messages(messages: &[(DiagMsg, Style)], with_style: bool, level: Level) -> Cow<'_, str> {
    if with_style {
        match messages {
            [] => Cow::Borrowed(""),
            [(msg, Style::NoStyle)] => Cow::Borrowed(msg.as_str()),
            [(msg, style)] => {
                let mut res = String::new();
                write_fmt(&mut res, msg, style, level);
                Cow::Owned(res)
            }
            messages => {
                let mut res = String::new();
                for (msg, style) in messages {
                    match style {
                        Style::NoStyle => res.push_str(msg.as_str()),
                        _ => write_fmt(&mut res, msg, style, level),
                    }
                }
                Cow::Owned(res)
            }
        }
    } else {
        match messages {
            [] => Cow::Borrowed(""),
            [(message, _)] => Cow::Borrowed(message.as_str()),
            messages => messages.iter().map(|(msg, _)| msg.as_str()).collect(),
        }
    }
}

fn write_fmt(output: &mut String, msg: &DiagMsg, style: &Style, level: Level) {
    let style = style.to_color_spec(level);
    let _ = write!(output, "{style}{}{style:#}", msg.as_str());
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{BytePos, ColorChoice, Span, source_map};
    #[cfg(feature = "json")]
    use snapbox::IntoData as _;
    use snapbox::{assert_data_eq, str};

    #[test]
    fn test_styled_messages() {
        let mut diag = Diag::new(Level::Note, "test");

        diag.highlighted_note(vec![
            ("plain text ", Style::NoStyle),
            ("removed", Style::Removal),
            (" middle ", Style::NoStyle),
            ("added", Style::Addition),
        ]);

        let sub = &diag.children[0];

        assert_data_eq!(&*sub.label(), str!["plain text removed middle added"]);

        assert_data_eq!(
            &*sub.label_with_style(true),
            str!["plain text removed middle added"]
        );
    }

    #[test]
    fn test_inline_suggestion() {
        let (var_span, var_sugg) = (Span::new(BytePos(66), BytePos(72)), "myVar");
        let mut diag = Diag::new(Level::Note, "mutable variables should use mixedCase");
        diag.span(var_span).span_suggestion(
            var_span,
            "mutable variables should use mixedCase",
            var_sugg,
            Applicability::MachineApplicable,
        );

        assert_eq!(diag.suggestions.len(), 1);
        assert_eq!(diag.suggestions[0].applicability, Applicability::MachineApplicable);
        assert_eq!(diag.suggestions[0].style, SuggestionStyle::ShowCode);

        assert_data_eq!(
            emit_human_diagnostics(diag),
            str![[r#"
note: mutable variables should use mixedCase
  ╭▸ <test.sol>:4:17
  │
4 │         uint256 my_var = 0;
  ╰╴                ━━━━━━ help: mutable variables should use mixedCase: `myVar`


"#]]
        );
    }

    #[test]
    fn test_emit_diagnostic_ref_preserves_inline_suggestion() {
        let (var_span, var_sugg) = (Span::new(BytePos(66), BytePos(72)), "myVar");
        let mut diag = Diag::new(Level::Note, "mutable variables should use mixedCase");
        diag.span(var_span).span_suggestion(
            var_span,
            "mutable variables should use mixedCase",
            var_sugg,
            Applicability::MachineApplicable,
        );

        let sm = std::sync::Arc::new(source_map::SourceMap::empty());
        sm.new_source_file(source_map::FileName::custom("test.sol"), CONTRACT.to_string()).unwrap();
        let mut emitter = HumanBufferEmitter::new(ColorChoice::Never).source_map(Some(sm));
        emitter.emit_diagnostic_ref(&diag);

        assert_eq!(diag.suggestions.len(), 1);
        assert_eq!(diag.suggestions[0].style, SuggestionStyle::ShowCode);
    }

    #[test]
    fn test_allowed_diagnostic_code_suppresses_warning() {
        let dcx = DiagCtxt::with_buffer_emitter(None, ColorChoice::Never)
            .with_allowed_diagnostic_codes(["1234".to_string()]);

        dcx.warn("suppressed warning").code(crate::error_code!(1234)).emit();
        dcx.warn("emitted warning").code(crate::error_code!(5678)).emit();

        let diagnostics = dcx.emitted_diagnostics().unwrap().to_string();
        assert_eq!(dcx.warn_count(), 1);
        assert!(diagnostics.contains("emitted warning"));
        assert!(!diagnostics.contains("suppressed warning"));
    }

    #[test]
    fn test_allowed_diagnostic_code_does_not_suppress_error() {
        let dcx = DiagCtxt::with_buffer_emitter(None, ColorChoice::Never)
            .with_allowed_diagnostic_codes(["1234".to_string()]);

        let _ = dcx.err("emitted error").code(crate::error_code!(1234)).emit();

        assert!(dcx.has_errors().is_err());
        assert!(dcx.emitted_diagnostics().unwrap().to_string().contains("emitted error"));
    }

    #[test]
    fn test_suggestion() {
        let (var_span, var_sugg) = (Span::new(BytePos(66), BytePos(72)), "myVar");
        let mut diag = Diag::new(Level::Note, "mutable variables should use mixedCase");
        diag.span(var_span).span_suggestion_with_style(
            var_span,
            "mutable variables should use mixedCase",
            var_sugg,
            Applicability::MachineApplicable,
            SuggestionStyle::ShowAlways,
        );

        assert_eq!(diag.suggestions.len(), 1);
        assert_eq!(diag.suggestions[0].applicability, Applicability::MachineApplicable);
        assert_eq!(diag.suggestions[0].style, SuggestionStyle::ShowAlways);

        assert_data_eq!(
            emit_human_diagnostics(diag),
            str![[r#"
note: mutable variables should use mixedCase
  ╭▸ <test.sol>:4:17
  │
4 │         uint256 my_var = 0;
  │                 ━━━━━━
  ╰╴
help: mutable variables should use mixedCase
  ╭╴
4 -         uint256 my_var = 0;
4 +         uint256 myVar = 0;
  ╰╴


"#]]
        );
    }

    #[test]
    fn test_suggestion_with_footer() {
        let (var_span, var_sugg) = (Span::new(BytePos(66), BytePos(72)), "myVar");
        let mut diag = Diag::new(Level::Note, "mutable variables should use mixedCase");
        diag.span(var_span)
            .span_suggestion_with_style(
                var_span,
                "mutable variables should use mixedCase",
                var_sugg,
                Applicability::MachineApplicable,
                SuggestionStyle::ShowAlways,
            )
            .help("some footer help msg that should be displayed at the very bottom");

        assert_eq!(diag.suggestions.len(), 1);
        assert_eq!(diag.suggestions[0].applicability, Applicability::MachineApplicable);
        assert_eq!(diag.suggestions[0].style, SuggestionStyle::ShowAlways);

        assert_data_eq!(
            emit_human_diagnostics(diag),
            str![[r#"
note: mutable variables should use mixedCase
  ╭▸ <test.sol>:4:17
  │
4 │         uint256 my_var = 0;
  │                 ━━━━━━
  │
  ╰ help: some footer help msg that should be displayed at the very bottom
help: mutable variables should use mixedCase
  ╭╴
4 -         uint256 my_var = 0;
4 +         uint256 myVar = 0;
  ╰╴


"#]]
        );
    }

    #[test]
    fn test_multispan_suggestion() {
        let (pub_span, pub_sugg) = (Span::new(BytePos(36), BytePos(42)), "external".into());
        let (view_span, view_sugg) = (Span::new(BytePos(43), BytePos(47)), "pure".into());
        let mut diag = Diag::new(Level::Warning, "inefficient visibility and mutability");
        diag.span(vec![pub_span, view_span]).multipart_suggestion(
            "consider changing visibility and mutability",
            vec![(pub_span, pub_sugg), (view_span, view_sugg)],
            Applicability::MaybeIncorrect,
        );

        assert_eq!(diag.suggestions[0].substitutions.len(), 1);
        assert_eq!(diag.suggestions[0].substitutions[0].parts.len(), 2);
        assert_eq!(diag.suggestions[0].applicability, Applicability::MaybeIncorrect);
        assert_eq!(diag.suggestions[0].style, SuggestionStyle::ShowCode);

        assert_data_eq!(
            emit_human_diagnostics(diag),
            str![[r#"
warning: inefficient visibility and mutability
  ╭▸ <test.sol>:3:20
  │
3 │     function foo() public view {
  │                    ━━━━━━ ━━━━
  ╰╴
help: consider changing visibility and mutability
  ╭╴
3 -     function foo() public view {
3 +     function foo() external pure {
  ╰╴


"#]]
        );
    }

    #[test]
    #[cfg(feature = "json")]
    fn test_json_suggestion() {
        let (var_span, var_sugg) = (Span::new(BytePos(66), BytePos(72)), "myVar");
        let mut diag = Diag::new(Level::Note, "mutable variables should use mixedCase");
        diag.span(var_span).span_suggestion(
            var_span,
            "mutable variables should use mixedCase",
            var_sugg,
            Applicability::MachineApplicable,
        );

        assert_eq!(diag.suggestions.len(), 1);
        assert_eq!(diag.suggestions[0].applicability, Applicability::MachineApplicable);
        assert_eq!(diag.suggestions[0].style, SuggestionStyle::ShowCode);

        assert_data_eq!(
            emit_json_diagnostics(diag),
            str![[r#"
{
  "$message_type": "diagnostic",
  "children": [
    {
      "children": [],
      "code": null,
      "level": "help",
      "message": "mutable variables should use mixedCase",
      "rendered": null,
      "spans": [
        {
          "byte_end": 72,
          "byte_start": 66,
          "column_end": 23,
          "column_start": 17,
          "file_name": "<test.sol>",
          "is_primary": true,
          "label": null,
          "line_end": 4,
          "line_start": 4,
          "suggested_replacement": "myVar",
          "text": [
            {
              "highlight_end": 23,
              "highlight_start": 17,
              "text": "        uint256 my_var = 0;"
            }
          ]
        }
      ]
    }
  ],
  "code": null,
  "level": "note",
  "message": "mutable variables should use mixedCase",
  "rendered": "note: mutable variables should use mixedCase\n  ╭▸ <test.sol>:4:17\n  │\n4 │         uint256 my_var = 0;\n  ╰╴                ━━━━━━ help: mutable variables should use mixedCase: `myVar`\n\n",
  "spans": [
    {
      "byte_end": 72,
      "byte_start": 66,
      "column_end": 23,
      "column_start": 17,
      "file_name": "<test.sol>",
      "is_primary": true,
      "label": null,
      "line_end": 4,
      "line_start": 4,
      "suggested_replacement": null,
      "text": [
        {
          "highlight_end": 23,
          "highlight_start": 17,
          "text": "        uint256 my_var = 0;"
        }
      ]
    }
  ]
}
"#]].is_json()
        );
    }

    #[test]
    #[cfg(feature = "json")]
    fn test_multispan_json_suggestion() {
        let (pub_span, pub_sugg) = (Span::new(BytePos(36), BytePos(42)), "external".into());
        let (view_span, view_sugg) = (Span::new(BytePos(43), BytePos(47)), "pure".into());
        let mut diag = Diag::new(Level::Warning, "inefficient visibility and mutability");
        diag.span(vec![pub_span, view_span]).multipart_suggestion(
            "consider changing visibility and mutability",
            vec![(pub_span, pub_sugg), (view_span, view_sugg)],
            Applicability::MaybeIncorrect,
        );

        assert_eq!(diag.suggestions[0].substitutions.len(), 1);
        assert_eq!(diag.suggestions[0].substitutions[0].parts.len(), 2);
        assert_eq!(diag.suggestions[0].applicability, Applicability::MaybeIncorrect);
        assert_eq!(diag.suggestions[0].style, SuggestionStyle::ShowCode);

        assert_data_eq!(
            emit_json_diagnostics(diag),
            str![[r#"
{
  "$message_type": "diagnostic",
  "children": [
    {
      "children": [],
      "code": null,
      "level": "help",
      "message": "consider changing visibility and mutability",
      "rendered": null,
      "spans": [
        {
          "byte_end": 42,
          "byte_start": 36,
          "column_end": 26,
          "column_start": 20,
          "file_name": "<test.sol>",
          "is_primary": true,
          "label": null,
          "line_end": 3,
          "line_start": 3,
          "suggested_replacement": "external",
          "text": [
            {
              "highlight_end": 26,
              "highlight_start": 20,
              "text": "    function foo() public view {"
            }
          ]
        },
        {
          "byte_end": 47,
          "byte_start": 43,
          "column_end": 31,
          "column_start": 27,
          "file_name": "<test.sol>",
          "is_primary": true,
          "label": null,
          "line_end": 3,
          "line_start": 3,
          "suggested_replacement": "pure",
          "text": [
            {
              "highlight_end": 31,
              "highlight_start": 27,
              "text": "    function foo() public view {"
            }
          ]
        }
      ]
    }
  ],
  "code": null,
  "level": "warning",
  "message": "inefficient visibility and mutability",
  "rendered": "warning: inefficient visibility and mutability\n  ╭▸ <test.sol>:3:20\n  │\n3 │     function foo() public view {\n  │                    ━━━━━━ ━━━━\n  ╰╴\nhelp: consider changing visibility and mutability\n  ╭╴\n3 -     function foo() public view {\n3 +     function foo() external pure {\n  ╰╴\n\n",
  "spans": [
    {
      "byte_end": 42,
      "byte_start": 36,
      "column_end": 26,
      "column_start": 20,
      "file_name": "<test.sol>",
      "is_primary": true,
      "label": null,
      "line_end": 3,
      "line_start": 3,
      "suggested_replacement": null,
      "text": [
        {
          "highlight_end": 26,
          "highlight_start": 20,
          "text": "    function foo() public view {"
        }
      ]
    },
    {
      "byte_end": 47,
      "byte_start": 43,
      "column_end": 31,
      "column_start": 27,
      "file_name": "<test.sol>",
      "is_primary": true,
      "label": null,
      "line_end": 3,
      "line_start": 3,
      "suggested_replacement": null,
      "text": [
        {
          "highlight_end": 31,
          "highlight_start": 27,
          "text": "    function foo() public view {"
        }
      ]
    }
  ]
}
"#]].is_json()
        );
    }

    // --- HELPERS -------------------------------------------------------------

    const CONTRACT: &str = r#"
contract Test {
    function foo() public view {
        uint256 my_var = 0;
    }
}"#;

    // Helper to setup the run the human-readable emitter.
    fn emit_human_diagnostics(diag: Diag) -> String {
        let sm = source_map::SourceMap::empty();
        sm.new_source_file(source_map::FileName::custom("test.sol"), CONTRACT.to_string()).unwrap();

        let dcx = DiagCtxt::with_buffer_emitter(Some(std::sync::Arc::new(sm)), ColorChoice::Never);
        let _ = dcx.emit_diagnostic(diag);

        dcx.emitted_diagnostics().unwrap().0
    }

    #[cfg(feature = "json")]
    use std::sync::{Arc, Mutex};

    #[cfg(feature = "json")]
    #[derive(Clone)]
    struct SharedWriter(Arc<Mutex<Vec<u8>>>);

    #[cfg(feature = "json")]
    impl std::io::Write for SharedWriter {
        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
            self.0.lock().unwrap().write(buf)
        }
        fn flush(&mut self) -> std::io::Result<()> {
            self.0.lock().unwrap().flush()
        }
    }

    #[cfg(feature = "json")]
    fn emit_json_diagnostics(diag: Diag) -> String {
        let sm = Arc::new(source_map::SourceMap::empty());
        sm.new_source_file(source_map::FileName::custom("test.sol"), CONTRACT.to_string()).unwrap();

        let writer = Arc::new(Mutex::new(Vec::new()));
        let emitter = JsonEmitter::new(Box::new(SharedWriter(writer.clone())), Arc::clone(&sm))
            .rustc_like(true);
        let dcx = DiagCtxt::new(Box::new(emitter));
        let _ = dcx.emit_diagnostic(diag);

        let buffer = writer.lock().unwrap();
        String::from_utf8(buffer.clone()).expect("JSON output was not valid UTF-8")
    }
}