[ty] Custom concise diagnostic messages (#21498)

## Summary

This PR proposes that we add a new `set_concise_message` functionality
to our `Diagnostic` construction API. When used, the concise message
that is otherwise auto-generated from the main diagnostic message and
the primary annotation will be overwritten with the custom message.

To understand why this is desirable, let's look at the `invalid-key`
diagnostic. This is how I *want* the full diagnostic to look like:

<img width="620" height="282" alt="image"
src="https://github.com/user-attachments/assets/3bf70f52-9d9f-4817-bc16-fb0ebf7c2113"
/>

However, without the change in this PR, the concise message would have
the following form:

```
error[invalid-key]: Unknown key "Age" for TypedDict `Person`: Unknown key "Age" - did you mean "age"?
```

This duplication is why the full `invalid-key` diagnostic used a main
diagnostic message that is only "Invalid key for TypedDict `Person`", to
make that bearable:

```
error[invalid-key] Invalid key for TypedDict `Person`: Unknown key "Age" - did you mean "age"?
```

This is still less than ideal, *and* we had to make the "full"
diagnostic worse. With the new API here, we have to make no such
compromises. We need to do slightly more work (provide one additional
custom-designed message), but we get to keep the "full" diagnostic that
we actually want, and we can make the concise message more terse and
readable:

```
error[invalid-key] Unknown key "Age" for TypedDict `Person` - did you mean "age"?
```

Similar problems exist for other diagnostics as well (I really want this
for #21476). In this PR, I only
changed `invalid-key` and `type-assertion-failure`.

The PR here is somewhat related to the discussion in
astral-sh/ty#1418, but note that we are
solving a problem that is unrelated to sub-diagnostics.

## Test Plan

Updated tests

Author: sharkdp

crates/ruff_db/src/diagnostic/mod.rs

@@ -64,6 +64,7 @@ impl Diagnostic {
             id,
             severity,
             message: message.into_diagnostic_message(),
+            custom_concise_message: None,
             annotations: vec![],
             subs: vec![],
             fix: None,
@@ -213,6 +214,10 @@ impl Diagnostic {
     /// cases, just converting it to a string (or printing it) will do what
     /// you want.
     pub fn concise_message(&self) -> ConciseMessage<'_> {
+        if let Some(custom_message) = &self.inner.custom_concise_message {
+            return ConciseMessage::Custom(custom_message.as_str());
+        }
+
         let main = self.inner.message.as_str();
         let annotation = self
             .primary_annotation()
@@ -226,6 +231,15 @@ impl Diagnostic {
         }
     }
 
+    /// Set a custom message for the concise formatting of this diagnostic.
+    ///
+    /// This overrides the default behavior of generating a concise message
+    /// from the main diagnostic message and the primary annotation.
+    pub fn set_concise_message(&mut self, message: impl IntoDiagnosticMessage) {
+        Arc::make_mut(&mut self.inner).custom_concise_message =
+            Some(message.into_diagnostic_message());
+    }
+
     /// Returns the severity of this diagnostic.
     ///
     /// Note that this may be different than the severity of sub-diagnostics.
@@ -532,6 +546,7 @@ struct DiagnosticInner {
     id: DiagnosticId,
     severity: Severity,
     message: DiagnosticMessage,
+    custom_concise_message: Option<DiagnosticMessage>,
     annotations: Vec<Annotation>,
     subs: Vec<SubDiagnostic>,
     fix: Option<Fix>,
@@ -1520,6 +1535,8 @@ pub enum ConciseMessage<'a> {
     /// This indicates that the diagnostic is probably using the old
     /// model.
     Empty,
+    /// A custom concise message has been provided.
+    Custom(&'a str),
 }
 
 impl std::fmt::Display for ConciseMessage<'_> {
@@ -1535,6 +1552,9 @@ impl std::fmt::Display for ConciseMessage<'_> {
                 write!(f, "{main}: {annotation}")
             }
             ConciseMessage::Empty => Ok(()),
+            ConciseMessage::Custom(message) => {
+                write!(f, "{message}")
+            }
         }
     }
 }

crates/ty_python_semantic/resources/mdtest/assignment/annotations.md

@@ -458,12 +458,12 @@ b: TD | None = f([{"x": 0}, {"x": 1}])
 reveal_type(b)  # revealed: TD
 
 # error: [missing-typed-dict-key] "Missing required key 'x' in TypedDict `TD` constructor"
-# error: [invalid-key] "Invalid key for TypedDict `TD`: Unknown key "y""
+# error: [invalid-key] "Unknown key "y" for TypedDict `TD`"
 # error: [invalid-assignment] "Object of type `Unknown | dict[Unknown | str, Unknown | int]` is not assignable to `TD`"
 c: TD = f([{"y": 0}, {"x": 1}])
 
 # error: [missing-typed-dict-key] "Missing required key 'x' in TypedDict `TD` constructor"
-# error: [invalid-key] "Invalid key for TypedDict `TD`: Unknown key "y""
+# error: [invalid-key] "Unknown key "y" for TypedDict `TD`"
 # error: [invalid-assignment] "Object of type `Unknown | dict[Unknown | str, Unknown | int]` is not assignable to `TD | None`"
 c: TD | None = f([{"y": 0}, {"x": 1}])
 ```

crates/ty_python_semantic/resources/mdtest/directives/assert_never.md

@@ -80,7 +80,7 @@ def if_else_isinstance_error(obj: A | B):
     elif isinstance(obj, C):
         pass
     else:
-        # error: [type-assertion-failure] "Argument does not have asserted type `Never`"
+        # error: [type-assertion-failure] "Type `B & ~A & ~C` is not equivalent to `Never`"
         assert_never(obj)
 
 def if_else_singletons_success(obj: Literal[1, "a"] | None):
@@ -101,7 +101,7 @@ def if_else_singletons_error(obj: Literal[1, "a"] | None):
     elif obj is None:
         pass
     else:
-        # error: [type-assertion-failure] "Argument does not have asserted type `Never`"
+        # error: [type-assertion-failure] "Type `Literal["a"]` is not equivalent to `Never`"
         assert_never(obj)
 
 def match_singletons_success(obj: Literal[1, "a"] | None):
@@ -125,7 +125,9 @@ def match_singletons_error(obj: Literal[1, "a"] | None):
             pass
         case _ as obj:
             # TODO: We should emit an error here, but the message should
-            # show the type `Literal["a"]` instead of `@Todo(…)`.
-            # error: [type-assertion-failure] "Argument does not have asserted type `Never`"
+            # show the type `Literal["a"]` instead of `@Todo(…)`. We only
+            # assert on the first part of the message because the `@Todo`
+            # message is not available in release mode builds.
+            # error: [type-assertion-failure] "Type `@Todo"
             assert_never(obj)
 ```

crates/ty_python_semantic/resources/mdtest/directives/assert_type.md

@@ -41,11 +41,11 @@ from typing_extensions import assert_type
 
 # Subtype does not count
 def _(x: bool):
-    assert_type(x, int)  # error: [type-assertion-failure]
+    assert_type(x, int)  # error: [type-assertion-failure] "Type `int` does not match asserted type `bool`"
 
 def _(a: type[int], b: type[Any]):
-    assert_type(a, type[Any])  # error: [type-assertion-failure]
-    assert_type(b, type[int])  # error: [type-assertion-failure]
+    assert_type(a, type[Any])  # error: [type-assertion-failure] "Type `type[Any]` does not match asserted type `type[int]`"
+    assert_type(b, type[int])  # error: [type-assertion-failure] "Type `type[int]` does not match asserted type `type[Any]`"
 
 # The expression constructing the type is not taken into account
 def _(a: type[int]):

crates/ty_python_semantic/resources/mdtest/enums.md

@@ -901,7 +901,7 @@ def color_name_misses_one_variant(color: Color) -> str:
     elif color is Color.GREEN:
         return "Green"
     else:
-        assert_never(color)  # error: [type-assertion-failure] "Argument does not have asserted type `Never`"
+        assert_never(color)  # error: [type-assertion-failure] "Type `Literal[Color.BLUE]` is not equivalent to `Never`"
 
 class Singleton(Enum):
     VALUE = 1
@@ -956,7 +956,7 @@ def color_name_misses_one_variant(color: Color) -> str:
         case Color.GREEN:
             return "Green"
         case _:
-            assert_never(color)  # error: [type-assertion-failure] "Argument does not have asserted type `Never`"
+            assert_never(color)  # error: [type-assertion-failure] "Type `Literal[Color.BLUE]` is not equivalent to `Never`"
 
 class Singleton(Enum):
     VALUE = 1

crates/ty_python_semantic/resources/mdtest/snapshots/assignment_diagnosti…_-_Subscript_assignment…_-_Misspelled_key_for_`…_(7cf0fa634e2a2d59).snap

@@ -24,12 +24,12 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/subscript/assignment_dia
 # Diagnostics
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Config`
+error[invalid-key]: Unknown key "Retries" for TypedDict `Config`
  --> src/mdtest_snippet.py:7:5
   |
 6 | def _(config: Config) -> None:
 7 |     config["Retries"] = 30.0  # error: [invalid-key]
-  |     ------ ^^^^^^^^^ Unknown key "Retries" - did you mean "retries"?
+  |     ------ ^^^^^^^^^ Did you mean "retries"?
   |     |
   |     TypedDict `Config`
   |

crates/ty_python_semantic/resources/mdtest/snapshots/assignment_diagnosti…_-_Subscript_assignment…_-_Unknown_key_for_all_…_(1c685d9d10678263).snap

@@ -30,13 +30,13 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/subscript/assignment_dia
 # Diagnostics
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Person`
+error[invalid-key]: Unknown key "surname" for TypedDict `Person`
   --> src/mdtest_snippet.py:13:5
    |
 11 |     # error: [invalid-key]
 12 |     # error: [invalid-key]
 13 |     being["surname"] = "unknown"
-   |     ----- ^^^^^^^^^ Unknown key "surname" - did you mean "name"?
+   |     ----- ^^^^^^^^^ Did you mean "name"?
    |     |
    |     TypedDict `Person` in union type `Person | Animal`
    |
@@ -45,13 +45,13 @@ info: rule `invalid-key` is enabled by default
 ```
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Animal`
+error[invalid-key]: Unknown key "surname" for TypedDict `Animal`
   --> src/mdtest_snippet.py:13:5
    |
 11 |     # error: [invalid-key]
 12 |     # error: [invalid-key]
 13 |     being["surname"] = "unknown"
-   |     ----- ^^^^^^^^^ Unknown key "surname" - did you mean "name"?
+   |     ----- ^^^^^^^^^ Did you mean "name"?
    |     |
    |     TypedDict `Animal` in union type `Person | Animal`
    |

crates/ty_python_semantic/resources/mdtest/snapshots/assignment_diagnosti…_-_Subscript_assignment…_-_Unknown_key_for_one_…_(b515711c0a451a86).snap

@@ -28,7 +28,7 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/subscript/assignment_dia
 # Diagnostics
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Person`
+error[invalid-key]: Unknown key "legs" for TypedDict `Person`
   --> src/mdtest_snippet.py:11:5
    |
 10 | def _(being: Person | Animal) -> None:

crates/ty_python_semantic/resources/mdtest/snapshots/typed_dict.md_-_`TypedDict`_-_Diagnostics_(e5289abf5c570c29).snap

@@ -57,12 +57,12 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/typed_dict.md
 # Diagnostics
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Person`
+error[invalid-key]: Unknown key "naem" for TypedDict `Person`
   --> src/mdtest_snippet.py:8:5
    |
  7 | def access_invalid_literal_string_key(person: Person):
  8 |     person["naem"]  # error: [invalid-key]
-   |     ------ ^^^^^^ Unknown key "naem" - did you mean "name"?
+   |     ------ ^^^^^^ Did you mean "name"?
    |     |
    |     TypedDict `Person`
  9 |
@@ -73,7 +73,7 @@ info: rule `invalid-key` is enabled by default
 ```
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Person`
+error[invalid-key]: Unknown key "naem" for TypedDict `Person`
   --> src/mdtest_snippet.py:13:5
    |
 12 | def access_invalid_key(person: Person):
@@ -130,12 +130,12 @@ info: rule `invalid-assignment` is enabled by default
 ```
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Person`
+error[invalid-key]: Unknown key "naem" for TypedDict `Person`
   --> src/mdtest_snippet.py:22:5
    |
 21 | def write_to_non_existing_key(person: Person):
 22 |     person["naem"] = "Alice"  # error: [invalid-key]
-   |     ------ ^^^^^^ Unknown key "naem" - did you mean "name"?
+   |     ------ ^^^^^^ Did you mean "name"?
    |     |
    |     TypedDict `Person`
 23 |
@@ -160,7 +160,7 @@ info: rule `invalid-key` is enabled by default
 ```
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Person`
+error[invalid-key]: Unknown key "unknown" for TypedDict `Person`
   --> src/mdtest_snippet.py:29:21
    |
 27 | def create_with_invalid_string_key():
@@ -178,7 +178,7 @@ info: rule `invalid-key` is enabled by default
 ```
 
 ```
-error[invalid-key]: Invalid key for TypedDict `Person`
+error[invalid-key]: Unknown key "unknown" for TypedDict `Person`
   --> src/mdtest_snippet.py:32:11
    |
 31 |     # error: [invalid-key]