Diagnostics Development

Use crates/biome_diagnostics/CONTRIBUTING.md as the canonical API and design guide. Inspect current diagnostics in the same subsystem before choosing an advice type or derive shape.

Choose the Diagnostic API

Use RuleDiagnostic for lint and assist rules. Use a standalone type deriving Diagnostic when a parser, service, CLI, configuration, or infrastructure boundary needs its own structured diagnostic.

Do not introduce a standalone type solely to wrap a one-line lint message. Do not force a complex diagnostic with locations, sub-diagnostics, or conditional advice into a RuleDiagnostic chain when an owned type expresses the contract more clearly.

Three Questions

A complete diagnostic answers:

1. What condition was found?
2. Why does it matter?
3. What can the user do?

Keep those jobs separate: