[ty] Add a diagnostic for Final without assignment (#23001)

## Summary

Closes astral-sh/ty#872.

Author: charliermarsh

crates/ty/docs/rules.md

@@ -468,7 +468,7 @@ class A: ...
 class B(A): ...
 
 class C[T]:
-    x: Final[T]
+    x: Final[T]  # error: [final-without-value]
 
 static_assert(is_subtype_of(C[B], C[A]))
 static_assert(not is_subtype_of(C[A], C[B]))

crates/ty_python_semantic/resources/mdtest/generics/pep695/variance.md

@@ -23,6 +23,9 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/type_qualifiers/final.md
  8 | from _stat import ST_INO
  9 | 
 10 | ST_INO = 1  # error: [invalid-assignment]
+11 | from typing import Final
+12 | 
+13 | UNINITIALIZED: Final[int]  # error: [final-without-value]
 ```
 
 # Diagnostics
@@ -54,7 +57,21 @@ error[invalid-assignment]: Reassignment of `Final` symbol `ST_INO` is not allowe
  9 |
 10 | ST_INO = 1  # error: [invalid-assignment]
    | ^^^^^^^^^^ Reassignment of `Final` symbol
+11 | from typing import Final
    |
 info: rule `invalid-assignment` is enabled by default
 
 ```
+
+```
+error[final-without-value]: `Final` symbol `UNINITIALIZED` is not assigned a value
+  --> src/mdtest_snippet.py:13:1
+   |
+11 | from typing import Final
+12 |
+13 | UNINITIALIZED: Final[int]  # error: [final-without-value]
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+info: rule `final-without-value` is enabled by default
+
+```

crates/ty_python_semantic/resources/mdtest/snapshots/final.md_-_`typing.Final`_-_Full_diagnostics_(174fdd8134fb325b).snap

@@ -463,23 +463,149 @@ DECLARED_THEN_BOUND = 1
 ```py
 from typing import Final
 
-# TODO: This should be an error
-NO_ASSIGNMENT_A: Final
-# TODO: This should be an error
-NO_ASSIGNMENT_B: Final[int]
+NO_ASSIGNMENT_A: Final  # error: [final-without-value] "`Final` symbol `NO_ASSIGNMENT_A` is not assigned a value"
+NO_ASSIGNMENT_B: Final[int]  # error: [final-without-value] "`Final` symbol `NO_ASSIGNMENT_B` is not assigned a value"
 
 class C:
-    # TODO: This should be an error
-    NO_ASSIGNMENT_A: Final
-    # TODO: This should be an error
-    NO_ASSIGNMENT_B: Final[int]
+    NO_ASSIGNMENT_A: Final  # error: [final-without-value] "`Final` symbol `NO_ASSIGNMENT_A` is not assigned a value"
+    NO_ASSIGNMENT_B: Final[int]  # error: [final-without-value] "`Final` symbol `NO_ASSIGNMENT_B` is not assigned a value"
 
     DEFINED_IN_INIT: Final[int]
 
     def __init__(self):
         self.DEFINED_IN_INIT = 1
 ```
 
+### Function-local `Final` without value
+
+```py
+from typing import Final
+
+def f():
+    x: Final[int]  # error: [final-without-value] "`Final` symbol `x` is not assigned a value"
+```
+
+### `typing_extensions.Final` without value
+
+```py
+from typing_extensions import Final
+
+TEXF_NO_VALUE: Final[str]  # error: [final-without-value] "`Final` symbol `TEXF_NO_VALUE` is not assigned a value"
+```
+
+### `Annotated[Final[...], ...]` without value
+
+```py
+from typing import Annotated, Final
+
+ANNOTATED_FINAL: Annotated[  # error: [final-without-value] "`Final` symbol `ANNOTATED_FINAL` is not assigned a value"
+    Final[int], "metadata"
+]
+```
+
+### Imported `Final` symbol
+
+Importing a symbol that is declared `Final` in its source module should not trigger
+`final-without-value`, because the import itself provides the binding.
+
+`module.py`:
+
+```py
+from typing import Final
+
+MODULE_FINAL: Final[int] = 1
+```
+
+`test.py`:
+
+```py
+from module import MODULE_FINAL
+```
+
+Even if the imported symbol is later deleted (a common pattern to clean up module namespaces), it
+should not trigger the diagnostic.
+
+`test_del.py`:
+
+```py
+from module import MODULE_FINAL
+
+_ = MODULE_FINAL
+
+del MODULE_FINAL
+```
+
+### Stub file `Final` without value
+
+In stub files, `Final` declarations without a value are permitted, at both module and class scope.
+
+`stub.pyi`:
+
+```pyi
+from typing import Final
+
+STUB_FINAL: Final[int]
+
+class StubClass:
+    STUB_ATTR: Final[str]
+```
+
+### Conditional assignment in `__init__`
+
+A `Final` attribute declared in the class body and conditionally assigned in `__init__` should not
+trigger `final-without-value`, since at least one path provides a binding.
+
+```py
+from typing import Final
+
+class C:
+    x: Final[int]
+
+    def __init__(self, flag: bool):
+        if flag:
+            self.x = 1
+        else:
+            self.x = 2
+
+class D:
+    y: Final[int]
+
+    def __init__(self, flag: bool):
+        if flag:
+            self.y = 1
+        # No else: y may be unbound at runtime, but there is still an assignment path
+```
+
+### Assignment in non-`__init__` method
+
+Per the typing spec, a `Final` attribute declared in a class body without a value must be
+initialized in `__init__`. Assignment in other methods does not satisfy the requirement.
+
+```py
+from typing import Final
+
+class E:
+    x: Final[int]  # error: [final-without-value] "`Final` symbol `x` is not assigned a value"
+
+    def setup(self):
+        # error: [invalid-assignment] "Cannot assign to final attribute `x`"
+        self.x = 1  # Too late: not __init__
+```
+
+### Dataclass with `Final` field
+
+Dataclass-like classes do not report `final-without-value` because the `__init__` is synthesized by
+the framework.
+
+```py
+from dataclasses import dataclass
+from typing import Final
+
+@dataclass
+class D:
+    x: Final[int]  # No error: dataclass generates __init__
+```
+
 ## Final attributes with Self annotation in `__init__`
 
 Issue #1409: Final instance attributes should be assignable in `__init__` even when using `Self`
@@ -566,7 +692,7 @@ class DeclareAndAssignInInit:
 
 # Case 6: Assignment outside __init__ should still fail
 class AssignmentOutsideInit:
-    attr6: Final[int]
+    attr6: Final[int]  # error: [final-without-value] "`Final` symbol `attr6` is not assigned a value"
 
     def other_method(self):
         # error: [invalid-assignment] "Cannot assign to final attribute `attr6`"
@@ -634,4 +760,12 @@ from _stat import ST_INO
 ST_INO = 1  # error: [invalid-assignment]
 ```
 
+`Final` declaration without value:
+
+```py
+from typing import Final
+
+UNINITIALIZED: Final[int]  # error: [final-without-value]
+```
+
 [`typing.final`]: https://docs.python.org/3/library/typing.html#typing.Final

crates/ty_python_semantic/resources/mdtest/type_qualifiers/final.md

@@ -117,6 +117,7 @@ pub(crate) fn register_lints(registry: &mut LintRegistryBuilder) {
     registry.register_lint(&SUBCLASS_OF_FINAL_CLASS);
     registry.register_lint(&OVERRIDE_OF_FINAL_METHOD);
     registry.register_lint(&INEFFECTIVE_FINAL);
+    registry.register_lint(&FINAL_WITHOUT_VALUE);
     registry.register_lint(&ABSTRACT_METHOD_IN_FINAL_CLASS);
     registry.register_lint(&TYPE_ASSERTION_FAILURE);
     registry.register_lint(&ASSERT_TYPE_UNSPELLABLE_SUBTYPE);
@@ -2056,6 +2057,33 @@ declare_lint! {
     }
 }
 
+declare_lint! {
+    /// ## What it does
+    /// Checks for `Final` symbols that are declared without a value and are never
+    /// assigned a value in their scope.
+    ///
+    /// ## Why is this bad?
+    /// A `Final` symbol must be initialized with a value at the time of declaration
+    /// or in a subsequent assignment. At module or function scope, the assignment must
+    /// occur in the same scope. In a class body, the assignment may occur in `__init__`.
+    ///
+    /// ## Examples
+    /// ```python
+    /// from typing import Final
+    ///
+    /// # Error: `Final` symbol without a value
+    /// MY_CONSTANT: Final[int]
+    ///
+    /// # OK: `Final` symbol with a value
+    /// MY_CONSTANT: Final[int] = 1
+    /// ```
+    pub(crate) static FINAL_WITHOUT_VALUE = {
+        summary: "detects `Final` declarations without a value",
+        status: LintStatus::stable("0.0.15"),
+        default_level: Level::Error,
+    }
+}
+
 declare_lint! {
     /// ## What it does
     /// Checks for `@final` classes that have unimplemented abstract methods.