Diagnostic::suggestion -> first_help_text, update docs

Author: ntBre

crates/ruff/src/cache.rs

@@ -454,7 +454,7 @@ impl LintCacheData {
                 CacheMessage {
                     rule,
                     body: msg.body().to_string(),
-                    suggestion: msg.suggestion().map(ToString::to_string),
+                    suggestion: msg.first_help_text().map(ToString::to_string),
                     range: msg.expect_range(),
                     parent: msg.parent(),
                     fix: msg.fix().cloned(),

crates/ruff_db/src/diagnostic/mod.rs

@@ -384,10 +384,14 @@ impl Diagnostic {
         self.primary_message()
     }
 
-    /// Returns the fix suggestion for the violation.
-    pub fn suggestion(&self) -> Option<&str> {
+    /// Returns the message of the first sub-diagnostic with a `Help` severity.
+    ///
+    /// Note that this is used as the fix title/suggestion for some of Ruff's output formats, but in
+    /// general this is not the guaranteed meaning of such a message.
+    pub fn first_help_text(&self) -> Option<&str> {
         self.sub_diagnostics()
-            .first()
+            .iter()
+            .find(|sub| matches!(sub.inner.severity, Severity::Help))
             .map(|sub| sub.inner.message.as_str())
     }
 

crates/ruff_db/src/diagnostic/render/json.rs

@@ -87,7 +87,7 @@ pub(super) fn diagnostic_to_json<'a>(
 
     let fix = diagnostic.fix().map(|fix| JsonFix {
         applicability: fix.applicability(),
-        message: diagnostic.suggestion(),
+        message: diagnostic.first_help_text(),
         edits: ExpandedEdits {
             edits: fix.edits(),
             notebook_index,

crates/ruff_linter/src/message/text.rs

@@ -186,7 +186,7 @@ pub(super) struct MessageCodeFrame<'a> {
 
 impl Display for MessageCodeFrame<'_> {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        let suggestion = self.message.suggestion();
+        let suggestion = self.message.first_help_text();
         let footers = if let Some(suggestion) = suggestion {
             vec![Level::Help.title(suggestion)]
         } else {

crates/ruff_linter/src/test.rs

@@ -272,7 +272,7 @@ Either ensure you always emit a fix or change `Violation::FIX_AVAILABILITY` to e
             }
 
             assert!(
-                !(fixable && diagnostic.suggestion().is_none()),
+                !(fixable && diagnostic.first_help_text().is_none()),
                 "Diagnostic emitted by {rule:?} is fixable but \
                 `Violation::fix_title` returns `None`"
             );

crates/ruff_server/src/lint.rs

@@ -238,7 +238,7 @@ fn to_lsp_diagnostic(
     let name = diagnostic.name();
     let body = diagnostic.body().to_string();
     let fix = diagnostic.fix();
-    let suggestion = diagnostic.suggestion();
+    let suggestion = diagnostic.first_help_text();
     let code = diagnostic.secondary_code();
 
     let fix = fix.and_then(|fix| fix.applies(Applicability::Unsafe).then_some(fix));

crates/ruff_wasm/src/lib.rs

@@ -234,7 +234,7 @@ impl Workspace {
                 start_location: source_code.line_column(msg.expect_range().start()).into(),
                 end_location: source_code.line_column(msg.expect_range().end()).into(),
                 fix: msg.fix().map(|fix| ExpandedFix {
-                    message: msg.suggestion().map(ToString::to_string),
+                    message: msg.first_help_text().map(ToString::to_string),
                     edits: fix
                         .edits()
                         .iter()