ruff_diagnostics

The diagnostic data model shared by Ruff and ty. Source: crates/ruff_diagnostics/.

Purpose

Define the Diagnostic and Fix types every rule emits, with rich metadata for severity, applicability, and source spans. Pair with ruff_annotate_snippets for terminal rendering.

Key abstractions

Type	Purpose
Diagnostic	The unit of output. Carries kind (rule code or ty diagnostic id), span, message, optional fix, optional subdiagnostics.
DiagnosticKind	Lightweight description of the rule that emitted the diagnostic.
Fix	A list of Edits, an applicability, and an optional message.
Edit	A single text replacement (insertion, deletion, replace).
Applicability	Always (safe), Sometimes (unsafe; opt-in), DisplayOnly.
Severity	Error, Warning, Info. Most rules use Warning.

How diagnostics flow

1. A rule constructs a Diagnostic from a struct that implements the rule's Violation trait (Ruff side) or a LintRegistry key (ty side).
2. The diagnostic is collected into a per-file Vec<Diagnostic> by the checkers.
3. The CLI / LSP / WASM caller routes the diagnostic to the appropriate output:
   • Ruff CLI → crates/ruff/src/printer.rs
   • LSP → textDocument/publishDiagnostics
   • JSON formats → serde::Serialize

Fix safety

• Safe (Always) — applied whenever --fix is set.
• Unsafe (Sometimes) — only applied when --unsafe-fixes is also set. These risk semantic drift (e.g. removing imports that have side effects).
• Display-only (DisplayOnly) — never auto-applied; shown to the user as a suggestion.

The applicability is part of the rule's stable contract. Promoting an unsafe fix to safe (or demoting one) is treated as a behavior change.

Subdiagnostics

A diagnostic can carry secondary annotations and sub-diagnostics that show up in text output as additional note: lines. ty uses these heavily to point at "this argument was expected here, this overload was rejected because…" details without bloating the primary message.

Renderer

crates/ruff_annotate_snippets is a fork of annotate-snippets-rs that the renderer in Ruff and ty share. It owns line numbering, color, and underline drawing for the text output format.

Integration points

• Used by every rule and check in ruff_linter and ty_python_semantic.
• Serialized to JSON, SARIF, JUnit, and other formats by crates/ruff/src/printer.rs.
• Consumed by editor integrations through the LSP.

Modifying

• Adding a new applicability: update Applicability, the printer, the LSP, and the docs that describe what --fix / --unsafe-fixes apply.
• Adding new diagnostic metadata (e.g. tags): add the field, plumb through the renderer, and consider backward compatibility with the JSON output (which is documented public API).

See ruff_linter and ty_python_semantic for the producer side.