[pyflakes] Add secondary annotation showing previous definition (F811) (#19900)

## Summary

This is a second attempt at a first use of a new diagnostic feature
after #19886. I'll blame rustc for this one because it also has a
similar diagnostic:

<img width="735" height="335" alt="image"
src="https://github.com/user-attachments/assets/572fe1c3-1742-4ce4-b575-1d9196ff0932"
/>

We end up with a very similar diagnostic:

<img width="764" height="401" alt="image"
src="https://github.com/user-attachments/assets/01eaf0c7-2567-467b-a5d8-a27206b2c74c"
/>

## Test Plan

New snapshots and manual tests above

Author: ntBre

crates/ruff/tests/lint.rs

@@ -5588,15 +5588,15 @@ fn cookiecutter_globbing() -> Result<()> {
                 .args(STDIN_BASE_OPTIONS)
                 .arg("--select=F811")
                 .current_dir(tempdir.path()), @r"
-			success: false
-			exit_code: 1
-			----- stdout -----
-			{{cookiecutter.repo_name}}/tests/maintest.py:3:8: F811 [*] Redefinition of unused `foo` from line 1
-			Found 1 error.
-			[*] 1 fixable with the `--fix` option.
+        success: false
+        exit_code: 1
+        ----- stdout -----
+        {{cookiecutter.repo_name}}/tests/maintest.py:3:8: F811 [*] Redefinition of unused `foo` from line 1: `foo` redefined here
+        Found 1 error.
+        [*] 1 fixable with the `--fix` option.
 
-			----- stderr -----
-		");
+        ----- stderr -----
+        ");
     });
 
     Ok(())

crates/ruff_db/src/diagnostic/mod.rs

@@ -254,6 +254,11 @@ impl Diagnostic {
             .find(|ann| ann.is_primary)
     }
 
+    /// Returns a mutable borrow of all annotations of this diagnostic.
+    pub fn annotations_mut(&mut self) -> impl Iterator<Item = &mut Annotation> {
+        Arc::make_mut(&mut self.inner).annotations.iter_mut()
+    }
+
     /// Returns the "primary" span of this diagnostic if one exists.
     ///
     /// When there are multiple primary spans, then the first one that was
@@ -310,6 +315,11 @@ impl Diagnostic {
         &self.inner.subs
     }
 
+    /// Returns a mutable borrow of the sub-diagnostics of this diagnostic.
+    pub fn sub_diagnostics_mut(&mut self) -> impl Iterator<Item = &mut SubDiagnostic> {
+        Arc::make_mut(&mut self.inner).subs.iter_mut()
+    }
+
     /// Returns the fix for this diagnostic if it exists.
     pub fn fix(&self) -> Option<&Fix> {
         self.inner.fix.as_ref()
@@ -621,6 +631,11 @@ impl SubDiagnostic {
         &self.inner.annotations
     }
 
+    /// Returns a mutable borrow of the annotations of this sub-diagnostic.
+    pub fn annotations_mut(&mut self) -> impl Iterator<Item = &mut Annotation> {
+        self.inner.annotations.iter_mut()
+    }
+
     /// Returns a shared borrow of the "primary" annotation of this diagnostic
     /// if one exists.
     ///

crates/ruff_db/src/diagnostic/render.rs

@@ -264,7 +264,12 @@ impl<'a> ResolvedDiagnostic<'a> {
             .annotations
             .iter()
             .filter_map(|ann| {
-                let path = ann.span.file.path(resolver);
+                let path = ann
+                    .span
+                    .file
+                    .relative_path(resolver)
+                    .to_str()
+                    .unwrap_or_else(|| ann.span.file.path(resolver));
                 let diagnostic_source = ann.span.file.diagnostic_source(resolver);
                 ResolvedAnnotation::new(path, &diagnostic_source, ann, resolver)
             })

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

@@ -28,7 +28,7 @@ use itertools::Itertools;
 use log::debug;
 use rustc_hash::{FxHashMap, FxHashSet};
 
-use ruff_db::diagnostic::Diagnostic;
+use ruff_db::diagnostic::{Annotation, Diagnostic, IntoDiagnosticMessage, Span};
 use ruff_diagnostics::{Applicability, Fix, IsolationLevel};
 use ruff_notebook::{CellOffsets, NotebookIndex};
 use ruff_python_ast::helpers::{collect_import_from_member, is_docstring_stmt, to_module_path};
@@ -3305,6 +3305,17 @@ impl DiagnosticGuard<'_, '_> {
             Err(err) => log::debug!("Failed to create fix for {}: {}", self.name(), err),
         }
     }
+
+    /// Add a secondary annotation with the given message and range.
+    pub(crate) fn secondary_annotation<'a>(
+        &mut self,
+        message: impl IntoDiagnosticMessage + 'a,
+        range: impl Ranged,
+    ) {
+        let span = Span::from(self.context.source_file.clone()).with_range(range.range());
+        let ann = Annotation::secondary(span).message(message);
+        self.diagnostic.as_mut().unwrap().annotate(ann);
+    }
 }
 
 impl std::ops::Deref for DiagnosticGuard<'_, '_> {

crates/ruff_linter/src/rules/pyflakes/rules/redefined_while_unused.rs

@@ -183,14 +183,24 @@ pub(crate) fn redefined_while_unused(checker: &Checker, scope_id: ScopeId, scope
     // Create diagnostics for each statement.
     for (source, entries) in &redefinitions {
         for (shadowed, binding) in entries {
+            let name = binding.name(checker.source());
             let mut diagnostic = checker.report_diagnostic(
                 RedefinedWhileUnused {
-                    name: binding.name(checker.source()).to_string(),
+                    name: name.to_string(),
                     row: checker.compute_source_row(shadowed.start()),
                 },
                 binding.range(),
             );
 
+            diagnostic.secondary_annotation(
+                format_args!("previous definition of `{name}` here"),
+                shadowed,
+            );
+
+            if let Some(ann) = diagnostic.primary_annotation_mut() {
+                ann.set_message(format_args!("`{name}` redefined here"));
+            }
+
             if let Some(range) = binding.parent_range(checker.semantic()) {
                 diagnostic.set_parent(range.start());
             }

crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F811_F811_0.py.snap

@@ -5,7 +5,14 @@ F811 Redefinition of unused `bar` from line 6
   --> F811_0.py:10:5
    |
 10 | def bar():
-   |     ^^^
+   |     ^^^ `bar` redefined here
 11 |     pass
    |
+  ::: F811_0.py:6:5
+   |
+ 5 | @foo
+ 6 | def bar():
+   |     --- previous definition of `bar` here
+ 7 |     pass
+   |
 help: Remove definition: `bar`

crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F811_F811_1.py.snap

@@ -2,9 +2,11 @@
 source: crates/ruff_linter/src/rules/pyflakes/mod.rs
 ---
 F811 Redefinition of unused `FU` from line 1
- --> F811_1.py:1:25
+ --> F811_1.py:1:14
   |
 1 | import fu as FU, bar as FU
-  |                         ^^
+  |              --         ^^ `FU` redefined here
+  |              |
+  |              previous definition of `FU` here
   |
 help: Remove definition: `FU`

crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F811_F811_12.py.snap

@@ -2,12 +2,16 @@
 source: crates/ruff_linter/src/rules/pyflakes/mod.rs
 ---
 F811 Redefinition of unused `mixer` from line 2
- --> F811_12.py:6:20
+ --> F811_12.py:2:20
   |
+1 | try:
+2 |     from aa import mixer
+  |                    ----- previous definition of `mixer` here
+3 | except ImportError:
 4 |     pass
 5 | else:
 6 |     from bb import mixer
-  |                    ^^^^^
+  |                    ^^^^^ `mixer` redefined here
 7 | mixer(123)
   |
 help: Remove definition: `mixer`

crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F811_F811_15.py.snap

@@ -5,7 +5,12 @@ F811 Redefinition of unused `fu` from line 1
  --> F811_15.py:4:5
   |
 4 | def fu():
-  |     ^^
+  |     ^^ `fu` redefined here
 5 |     pass
   |
+ ::: F811_15.py:1:8
+  |
+1 | import fu
+  |        -- previous definition of `fu` here
+  |
 help: Remove definition: `fu`

crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F811_F811_16.py.snap

@@ -7,7 +7,14 @@ F811 Redefinition of unused `fu` from line 3
 6 | def bar():
 7 |     def baz():
 8 |         def fu():
-  |             ^^
+  |             ^^ `fu` redefined here
 9 |             pass
   |
+ ::: F811_16.py:3:8
+  |
+1 | """Test that shadowing a global with a nested function generates a warning."""
+2 |
+3 | import fu
+  |        -- previous definition of `fu` here
+  |
 help: Remove definition: `fu`