Customize where the fix_title sub-diagnostic appears

Summary
--

This is a more general alternative to #23043 that more closely follows Micha's
[suggestion]. I sort of prefer this approach because it gives the diagnostic
author full control of the order of sub-diagnostics. On the other hand, it feels
a bit too "clever" for the current usage, which achieves the same effect as the
simpler #23043. So I'm curious to get others' thoughts.

I still think the ideal solution long-term would be to combine the diff
rendering with the sub-diagnostic holding the fix title, but that would be much
more involved than either of these PRs.

As I noted in the summary for #23043, the main motivation for the defer
machinery is that [RUF064] has a bunch of early returns mixed in with its `info`
additions, so it was a big pain to add a `help` diagnostic before each return.

We may at least want a `deferred_help` helper instead of the two closures used
here, if we do take this approach.

[suggestion]: https://github.com/astral-sh/ruff/pull/19900/changes/BASE..ab685c16a8c01bb33f054698d2f32bb023d07429#r2276500131
[RUF064]: https://github.com/astral-sh/ruff/blob/4a32a96740bb7327a3f554b7f6d6675cb2ea797e/crates/ruff_linter/src/rules/ruff/rules/non_octal_permissions.rs#L120-L145

Test Plan
--

Updated snapshots for `RUF064` and `ISC004`.

Author: ntBre

crates/ruff_linter/src/checkers/ast/mod.rs

@@ -27,6 +27,7 @@ use std::path::Path;
 use itertools::Itertools;
 use log::debug;
 use rustc_hash::{FxHashMap, FxHashSet};
+use smallvec::SmallVec;
 
 use ruff_db::diagnostic::{Annotation, Diagnostic, DiagnosticTag, IntoDiagnosticMessage, Span};
 use ruff_diagnostics::{Applicability, Fix, IsolationLevel};
@@ -421,6 +422,20 @@ impl<'a> Checker<'a> {
         self.context.report_diagnostic_if_enabled(kind, range)
     }
 
+    /// Return a [`DiagnosticGuard`] for reporting a diagnostic, along with its fix title to be
+    /// attached later.
+    ///
+    /// Prefer [`Checker::report_diagnostic`] unless you need to attach sub-diagnostics before the
+    /// fix title. See its documentation for more details.
+    #[must_use]
+    pub(crate) fn report_custom_diagnostic<'chk, T: Violation>(
+        &'chk self,
+        kind: T,
+        range: TextRange,
+    ) -> (DiagnosticGuard<'chk, 'a>, Option<String>) {
+        self.context.report_custom_diagnostic(kind, range)
+    }
+
     /// Adds a [`TextRange`] to the set of ranges of variable names
     /// flagged in `flake8-bugbear` violations so far.
     ///
@@ -3367,6 +3382,7 @@ impl<'a> LintContext<'a> {
             context: self,
             diagnostic: Some(kind.into_diagnostic(range, &self.source_file)),
             rule: T::rule(),
+            before_drop_fns: SmallVec::new(),
         }
     }
 
@@ -3386,12 +3402,46 @@ impl<'a> LintContext<'a> {
                 context: self,
                 diagnostic: Some(kind.into_diagnostic(range, &self.source_file)),
                 rule,
+                before_drop_fns: SmallVec::new(),
             })
         } else {
             None
         }
     }
 
+    /// Return a [`DiagnosticGuard`] for reporting a diagnostic, along with its fix title to be
+    /// attached later.
+    ///
+    /// Prefer [`LintContext::report_diagnostic`] unless you need to attach sub-diagnostics before
+    /// the fix title. See its documentation for more details.
+    #[expect(clippy::needless_pass_by_value)]
+    #[must_use]
+    pub(crate) fn report_custom_diagnostic<'chk, T: Violation>(
+        &'chk self,
+        kind: T,
+        range: TextRange,
+    ) -> (DiagnosticGuard<'chk, 'a>, Option<String>) {
+        let diagnostic = crate::message::create_lint_diagnostic(
+            kind.message(),
+            Option::<&'static str>::None,
+            range,
+            None,
+            None,
+            self.source_file.clone(),
+            None,
+            T::rule(),
+        );
+        (
+            DiagnosticGuard {
+                context: self,
+                diagnostic: Some(diagnostic),
+                rule: T::rule(),
+                before_drop_fns: SmallVec::new(),
+            },
+            kind.fix_title(),
+        )
+    }
+
     #[inline]
     pub(crate) const fn is_rule_enabled(&self, rule: Rule) -> bool {
         self.rules.enabled(rule)
@@ -3433,6 +3483,8 @@ impl<'a> LintContext<'a> {
     }
 }
 
+type BeforeDropFn = Box<dyn Fn(&mut Diagnostic)>;
+
 /// An abstraction for mutating a diagnostic.
 ///
 /// Callers can build this guard by starting with `Checker::report_diagnostic`.
@@ -3447,6 +3499,8 @@ pub(crate) struct DiagnosticGuard<'a, 'b> {
     ///
     /// This is always `Some` until the `Drop` (or `defuse`) call.
     diagnostic: Option<Diagnostic>,
+    /// Functions to call before dropping the guard and storing the diagnostic.
+    before_drop_fns: SmallVec<[BeforeDropFn; 1]>,
     rule: Rule,
 }
 
@@ -3508,6 +3562,28 @@ impl DiagnosticGuard<'_, '_> {
         let ann = self.primary_annotation_mut().unwrap();
         ann.push_tag(tag);
     }
+
+    /// Register a function to call before dropping the guard.
+    ///
+    /// This is intended for use with the [`Checker::report_custom_diagnostic`]
+    /// or [`LintContext::report_custom_diagnostic`] methods in cases where a
+    /// fix title should be added as a `help` diagnostic after all other
+    /// sub-diagnostics. For example:
+    ///
+    /// ```ignore
+    /// let (mut diagnostic, fix_title) = checker.report_custom_diagnostic(MyViolation, range);
+    /// diagnostic.before_drop(move |diag| {
+    ///     if let Some(fix_title) = &fix_title {
+    ///         diag.help(fix_title);
+    ///     }
+    /// });
+    /// ```
+    pub(crate) fn before_drop<F>(&mut self, f: F)
+    where
+        F: Fn(&mut Diagnostic) + 'static,
+    {
+        self.before_drop_fns.push(Box::new(f));
+    }
 }
 
 impl DiagnosticGuard<'_, '_> {
@@ -3592,7 +3668,10 @@ impl Drop for DiagnosticGuard<'_, '_> {
             return;
         }
 
-        if let Some(diagnostic) = self.diagnostic.take() {
+        if let Some(mut diagnostic) = self.diagnostic.take() {
+            for f in &self.before_drop_fns {
+                f(&mut diagnostic);
+            }
             self.context.diagnostics.borrow_mut().push(diagnostic);
         }
     }

crates/ruff_linter/src/rules/flake8_implicit_str_concat/rules/collection_literal.rs

@@ -90,10 +90,15 @@ pub(crate) fn implicit_string_concatenation_in_collection_literal(
             continue;
         }
 
-        let mut diagnostic = checker.report_diagnostic(
+        let (mut diagnostic, fix_title) = checker.report_custom_diagnostic(
             ImplicitStringConcatenationInCollectionLiteral,
             string_like.range(),
         );
+        diagnostic.before_drop(move |diag| {
+            if let Some(fix_title) = &fix_title {
+                diag.help(fix_title);
+            }
+        });
         diagnostic.help("Did you forget a comma?");
         diagnostic.set_fix(Fix::unsafe_edits(
             Edit::insertion("(".to_string(), string_like.range().start()),

crates/ruff_linter/src/rules/flake8_implicit_str_concat/snapshots/ruff_linter__rules__flake8_implicit_str_concat__tests__ISC004_ISC004.py.snap

@@ -11,8 +11,8 @@ ISC004 [*] Unparenthesized implicit string concatenation in collection
   | |______________________________________________________________^
 6 |   )
   |
-help: Wrap implicitly concatenated strings in parentheses
 help: Did you forget a comma?
+help: Wrap implicitly concatenated strings in parentheses
 1 | facts = (
 2 |     "Lobsters have blue blood.",
 3 |     "The liver is the only human organ that can fully regenerate itself.",
@@ -35,8 +35,8 @@ ISC004 [*] Unparenthesized implicit string concatenation in collection
    | |______________________________________________________________^
 13 |   ]
    |
-help: Wrap implicitly concatenated strings in parentheses
 help: Did you forget a comma?
+help: Wrap implicitly concatenated strings in parentheses
 8  | facts = [
 9  |     "Lobsters have blue blood.",
 10 |     "The liver is the only human organ that can fully regenerate itself.",
@@ -59,8 +59,8 @@ ISC004 [*] Unparenthesized implicit string concatenation in collection
    | |______________________________________________________________^
 20 |   }
    |
-help: Wrap implicitly concatenated strings in parentheses
 help: Did you forget a comma?
+help: Wrap implicitly concatenated strings in parentheses
 15 | facts = {
 16 |     "Lobsters have blue blood.",
 17 |     "The liver is the only human organ that can fully regenerate itself.",
@@ -83,8 +83,8 @@ ISC004 [*] Unparenthesized implicit string concatenation in collection
    | |_________________________^
 33 |   )
    |
-help: Wrap implicitly concatenated strings in parentheses
 help: Did you forget a comma?
+help: Wrap implicitly concatenated strings in parentheses
 27 | }
 28 | 
 29 | facts = (
@@ -108,8 +108,8 @@ ISC004 [*] Unparenthesized implicit string concatenation in collection
    | |_________________________^
 39 |   ]
    |
-help: Wrap implicitly concatenated strings in parentheses
 help: Did you forget a comma?
+help: Wrap implicitly concatenated strings in parentheses
 33 | )
 34 | 
 35 | facts = [
@@ -133,8 +133,8 @@ ISC004 [*] Unparenthesized implicit string concatenation in collection
    | |_________________________^
 45 |   }
    |
-help: Wrap implicitly concatenated strings in parentheses
 help: Did you forget a comma?
+help: Wrap implicitly concatenated strings in parentheses
 39 | ]
 40 | 
 41 | facts = {

crates/ruff_linter/src/rules/ruff/rules/non_octal_permissions.rs

@@ -111,7 +111,13 @@ pub(crate) fn non_octal_permissions(checker: &Checker, call: &ExprCall) {
         return;
     }
 
-    let mut diagnostic = checker.report_diagnostic(NonOctalPermissions, mode_arg.range());
+    let (mut diagnostic, fix_title) =
+        checker.report_custom_diagnostic(NonOctalPermissions, mode_arg.range());
+    diagnostic.before_drop(move |diag| {
+        if let Some(fix_title) = &fix_title {
+            diag.help(fix_title);
+        }
+    });
 
     let Some(mode) = int.as_u16() else {
         return;