diagnostics-development

name	diagnostics-development
description	Guide for creating high-quality, user-friendly diagnostics in Biome. Use when creating diagnostics for lint rules, adding helpful advice to error messages, implementing code frame displays, or improving diagnostic quality.
compatibility	Designed for coding agents working on the Biome codebase (github.com/biomejs/biome).

Purpose

Use this skill when creating diagnostics - the error messages, warnings, and hints shown to users. Covers the Diagnostic trait, advice types, and best practices for clear, actionable messages.

Prerequisites

1. Read crates/biome_diagnostics/CONTRIBUTING.md for concepts
2. Understand Biome's Technical Principles
3. Follow the "show don't tell" philosophy

Diagnostic Principles

1. Explain what - State what the error is (diagnostic message)
2. Explain why - Explain why it's an error (advice notes)
3. Tell how to fix - Provide actionable fixes (code actions, diff advice, command advice)

Follow Technical Principles:

• Informative: Explain, don't just state
• Concise: Short messages, rich context via advices
• Actionable: Always suggest how to fix
• Show don't tell: Prefer code frames over textual explanations

Common Workflows

Create a Diagnostic Type

Use the #[derive(Diagnostic)] macro:

use biome_diagnostics::{Diagnostic, category};

#[derive(Debug, Diagnostic)]
#[diagnostic(
    severity = Error,
    category = "lint/correctness/noVar"
)]
struct NoVarDiagnostic {
    #[location(span)]
    span: TextRange,

    #[message]
    #[description]
    message: MessageAndDescription,

    #[advice]
    advice: NoVarAdvice,
}

#[derive(Debug)]
struct MessageAndDescription;

impl fmt::Display for MessageAndDescription {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Use 'let' or 'const' instead of 'var'")
    }
}

Implement Advices

Create advice types that implement Advices trait:

use biome_diagnostics::{Advices, Visit};
use biome_console::markup;

struct NoVarAdvice {
    is_const_candidate: bool,
}

impl Advices for NoVarAdvice {
    fn record(&self, visitor: &mut dyn Visit) -> std::io::Result<()> {
        if self.is_const_candidate {
            visitor.record_log(
                LogCategory::Info,
                &markup! {
                    "This variable is never reassigned, use 'const' instead."
                }
            )?;
        } else {
            visitor.record_log(
                LogCategory::Info,
                &markup! {
                    "Variables declared with 'var' are function-scoped, use 'let' for block-scoping."
                }
            )?;
        }
        Ok(())
    }
}

Use Built-in Advice Types

use biome_diagnostics::{LogAdvice, CodeFrameAdvice, DiffAdvice, CommandAdvice, LogCategory};

// Log advice - simple text message
LogAdvice {
    category: LogCategory::Info,
    text: markup! { "Consider using arrow functions." },
}

// Code frame advice - highlight code location
// Fields: path (AsResource), span (AsSpan), source_code (AsSourceCode)
CodeFrameAdvice {
    path: "file.js",
    span: node.text_range(),
    source_code: ctx.source_code(),
}

// Diff advice - show a TextEdit diff
DiffAdvice {
    diff: text_edit,  // must implement AsRef<TextEdit>
}

// Command advice - suggest CLI command
CommandAdvice {
    command: "biome check --write",
}

In practice, most lint rules use the RuleDiagnostic builder pattern instead of constructing advice types directly. See the Add Diagnostic to Rule section below.

Add Diagnostic to Rule

use biome_analyze::{Rule, RuleDiagnostic};

impl Rule for NoVar {
    fn diagnostic(ctx: &RuleContext<Self>, state: &Self::State) -> Option<RuleDiagnostic> {
        let node = ctx.query();

        Some(
            RuleDiagnostic::new(
                rule_category!(),
                node.range(),
                markup! {
                    "Using "<Emphasis>"var"</Emphasis>" is not recommended."
                },
            )
            .note(markup! {
                "Variables declared with "<Emphasis>"var"</Emphasis>" are function-scoped, not block-scoped, which means they can leak outside of loops and conditionals and cause unexpected behavior."
            })
            .note(markup! {
                "Consider using "<Emphasis>"let"</Emphasis>" or "<Emphasis>"const"</Emphasis>" instead."
            })
        )
    }
}

Use Markup for Rich Text

Biome supports rich markup in diagnostic messages:

use biome_console::markup;

markup! {
    // Emphasis (bold/colored)
    "Use "<Emphasis>"const"</Emphasis>" instead."

    // Code/identifiers
    "The variable "<Emphasis>{variable_name}</Emphasis>" is never used."

    // Hyperlinks
    "See the "<Hyperlink href="https://example.com">"documentation"</Hyperlink>"."

    // Interpolation
    "Found "{count}" issues."
}

Register Diagnostic Category

Add new categories to crates/biome_diagnostics_categories/src/categories.rs:

define_categories! {
    // Existing categories...

    "lint/correctness/noVar": "https://biomejs.dev/linter/rules/no-var",
    "lint/style/useConst": "https://biomejs.dev/linter/rules/use-const",
}

Create Multi-Advice Diagnostics

#[derive(Debug, Diagnostic)]
#[diagnostic(severity = Warning)]
struct ComplexDiagnostic {
    #[location(span)]
    span: TextRange,

    #[message]
    message: &'static str,

    // Multiple advices
    #[advice]
    first_advice: LogAdvice<MarkupBuf>,

    #[advice]
    code_frame: CodeFrameAdvice<String, TextRange, String>,

    #[verbose_advice]
    verbose_help: LogAdvice<MarkupBuf>,
}

Add Tags to Diagnostics

#[derive(Debug, Diagnostic)]
#[diagnostic(
    severity = Warning,
    tags(FIXABLE, DEPRECATED_CODE)  // Add diagnostic tags
)]
struct MyDiagnostic {
    // ...
}

Available tags:

• FIXABLE - Diagnostic has fix information
• INTERNAL - Internal error in Biome
• UNNECESSARY_CODE - Code is unused
• DEPRECATED_CODE - Code uses deprecated features

Best Practices

Message Guidelines

Good messages:

// Good - specific and actionable
"Use 'let' or 'const' instead of 'var'"

// Good - explains why
"This variable is never reassigned, consider using 'const'"

// Good - shows what to do
"Remove the unused import statement"

Bad messages:

// Bad - too vague
"Invalid syntax"

// Bad - just states the obvious
"Variable declared with 'var'"

// Bad - no guidance
"This code has a problem"

Advice Guidelines

Show, don't tell:

// Good - shows code frame
CodeFrameAdvice {
    path: "file.js",
    span: node.text_range(),
    source_code: source,
}

// Less helpful - just text
LogAdvice {
    category: LogCategory::Info,
    text: markup! { "The expression at line 5 is always truthy" },
}

Provide actionable fixes:

// Good - shows exact change
DiffAdvice {
    diff: text_edit,  // AsRef<TextEdit>
}

// Less helpful - describes change
LogAdvice {
    category: LogCategory::Info,
    text: markup! { "Change 'var' to 'const'" },
}

Severity Levels

Choose appropriate severity:

// Fatal - Biome can't continue
severity = Fatal

// Error - Must be fixed (correctness, security, a11y)
severity = Error

// Warning - Should be fixed (suspicious code)
severity = Warning

// Information - Style suggestions
severity = Information

// Hint - Minor improvements
severity = Hint

Common Patterns

// Pattern 1: Simple diagnostic with note
RuleDiagnostic::new(
    rule_category!(),
    node.range(),
    markup! { "Main message" },
)
.note(markup! { "Additional context" })

// Pattern 2: Diagnostic with code frame
RuleDiagnostic::new(
    rule_category!(),
    node.range(),
    markup! { "Main message" },
)
.detail(
    node.syntax().text_range(),
    markup! { "This part is problematic" }
)

// Pattern 3: Diagnostic with link
RuleDiagnostic::new(
    rule_category!(),
    node.range(),
    markup! { "Main message" },
)
.note(markup! {
    "See "<Hyperlink href="https://biomejs.dev/linter">"documentation"</Hyperlink>"."
})

// Pattern 4: Conditional advice
impl Advices for MyAdvice {
    fn record(&self, visitor: &mut dyn Visit) -> std::io::Result<()> {
        if self.show_hint {
            visitor.record_log(
                LogCategory::Info,
                &markup! { "Hint: ..." }
            )?;
        }
        Ok(())
    }
}

Tips

• Category format: Use area/group/ruleName format (e.g., lint/correctness/noVar)
• Markup formatting: Use markup! macro for all user-facing text
• Hyperlinks: Always link to documentation for more details
• Code frames: Include for spatial context when helpful
• Multiple advices: Chain multiple pieces of information
• Verbose advices: Use for extra details users can opt into
• Description vs Message: Description for plain text contexts (IDE popover), message for rich display
• Register categories: Don't forget to add to categories.rs

References

• Full guide: crates/biome_diagnostics/CONTRIBUTING.md
• Technical principles: https://biomejs.dev/internals/philosophy/#technical
• Diagnostic trait: crates/biome_diagnostics/src/diagnostic.rs
• Advice types: crates/biome_diagnostics/src/advice.rs
• Examples: Search for #[derive(Diagnostic)] in codebase