Rewrite tests in Markdown

Justfile

@@ -5,7 +5,7 @@ run *args:
     uv run auto-typing-final {{ args }}
 
 install:
-    uv lock
+    uv lock --upgrade
     uv sync
 
 lint:

README.md

@@ -14,10 +14,10 @@ Auto-fixer for Python code that adds `typing.Final` annotation to variable assig
 
 Basically, this, but handles different operations (like usage of `nonlocal`, augmented assignments: `+=`, etc) as well.
 
-- Keeps mypy happy.
+- Keeps type checker happy.
 - Adds global import if it's not imported yet (`import typing`/`from typing import Final`).
 - Inspects one file at a time.
-- Is careful with global variables: adds Final only for uppercase variables, ignores variable that are referenced in `global` statement inside functions in current file, and avoids removing Final when it already was set.
+- Is careful with global variables: adds Final only for uppercase variables, ignores variable that are referenced in `global` statement inside functions in current file, and avoids removing Final when it already was set ([docs](docs/global_vars_enabled.md)).
 - Ignores class variables: it is common to use `typing.ClassVar` instead of `typing.Final`.
 
 ## How To Use
@@ -59,7 +59,7 @@ auto-typing-final . --ignore-global-vars
 
 ### Ignore comment
 
-You can ignore variables by adding `# auto-typing-final: ignore` comment to the line.
+You can ignore variables by adding `# auto-typing-final: ignore` comment to the line ([docs](docs/ignore_comment.md)).
 
 ### VS Code Extension
 

auto_typing_final/main.py

@@ -10,7 +10,7 @@
 from auto_typing_final.transform import IMPORT_STYLES_TO_IMPORT_CONFIGS, ImportConfig, ImportStyle, make_replacements
 
 
-def transform_file_content(source: str, import_config: ImportConfig, ignore_global_vars: bool) -> str:  # noqa: FBT001
+def transform_file_content(source: str, import_config: ImportConfig, ignore_global_vars: bool) -> str:
     root: Final = SgRoot(source, "python").root()
     result: Final = make_replacements(root, import_config, ignore_global_vars)
     new_text: Final = root.commit_edits(

auto_typing_final/transform.py

@@ -97,7 +97,7 @@ def _should_skip_global_variable(definition: Definition) -> bool:
     )
 
 
-def _make_operation_from_definitions_of_one_name(nodes: list[SgNode], ignore_global_vars: bool) -> Operation | None:  # noqa: FBT001
+def _make_operation_from_definitions_of_one_name(nodes: list[SgNode], ignore_global_vars: bool) -> Operation | None:
     value_definitions: Final[list[Definition]] = []
     has_node_inside_loop = False
     has_global_scope_definition = False
@@ -215,7 +215,7 @@ class MakeReplacementsResult:
     import_text: str | None
 
 
-def make_replacements(root: SgNode, import_config: ImportConfig, ignore_global_vars: bool) -> MakeReplacementsResult:  # noqa: FBT001
+def make_replacements(root: SgNode, import_config: ImportConfig, ignore_global_vars: bool) -> MakeReplacementsResult:
     replacements: Final = []
     has_added_final = False
     imports_result: Final = find_imports_of_identifier_in_scope(root, module_name="typing", identifier_name="Final")

docs/README.md

@@ -0,0 +1,9 @@
+Human-readable tests.
+
+How to interpret them:
+- `# insert` indicates where Final should be added
+- `# remove` indicates where Final should be removed
+
+Tests will assert that lines are changed according to this comments. If unexpected fix applied, tests will fail. This means that these tests are documentation as well!
+
+Most headings are AI-generated.

docs/function_vars.md

@@ -0,0 +1,210 @@
+Tests for variables inside functions.
+
+### Variable Declaration with Type Annotation
+```python
+def foo():
+    a: int
+```
+
+### Variable Assignment with Inline Comment
+```python
+def foo():
+    a = 1  # insert
+```
+
+### Variable Declaration with Final Type Annotation
+```python
+def foo():
+    a: Final = 1
+```
+
+### Variable Declaration with Type Annotation and Assignment
+```python
+def foo():
+    a: int = 1   # insert
+```
+
+### Annotated Variable with Custom Metadata
+```python
+def foo():
+    a: typing.Annotated[int, 'hello'] = 1   # insert
+```
+
+### List Type Annotation and Assignment
+```python
+def foo():
+    a: list[int] = 1   # insert
+```
+
+### Variable Assignment with Previous Declaration
+```python
+def foo():
+    b = 1
+    a = 2  # insert
+    b = 3
+```
+
+### Variable Assignment with Reassignment of Another Variable
+```python
+def foo():
+    b = 1
+    b = 2
+    a = 3  # insert
+```
+
+### Variable Assignment with Later Reassignment
+```python
+def foo():
+    a = 1  # insert
+    b = 2
+    b = 3
+```
+
+### Reassignment of a Variable with Previous Assignment
+```python
+def foo():
+    a = 1
+    a = 2
+    b: int
+```
+
+### Variable Declaration After Assignment
+```python
+def foo():
+    a = 1
+    a: int
+```
+
+### Variable Declaration Before Assignment
+```python
+def foo():
+    a: int
+    a = 1
+```
+
+### Final Variable Declaration Before Assignment
+```python
+def foo():
+    a: Final
+    a = 1
+```
+
+### Redundant Type Annotation with Final
+```python
+def foo():
+    a: int
+    a: int = 1
+```
+
+### Simultaneous Variable Assignment
+```python
+def foo():
+    a, b = 1, 2
+```
+
+### Tuple Assignment with Parentheses
+```python
+def foo():
+    (a, b) = 1, 2
+```
+
+### Tuple Assignment from Function Return
+```python
+def foo():
+    (a, b) = t()
+```
+
+### List Assignment from Function Return
+```python
+def foo():
+    [a, b] = t()
+```
+
+### Single Element List Assignment
+```python
+def foo():
+    [a] = t()
+```
+
+### Multiple Variable Assignment in a Single Line
+```python
+def foo():
+    a = b = 1
+```
+
+### Chained Multiple Variable Assignment
+```python
+def foo():
+    a = b = c = 1
+```
+
+### Variable Assignment with Walrus Operator
+```python
+def foo():
+    a = (b := 1)  # insert
+```
+
+### Reassignment with Final Annotation
+```python
+def foo():
+    a = 1
+    a: Final[int] = 2  # remove
+```
+
+### Reassignment with Final Type Declaration
+```python
+def foo():
+    a = 1
+    a: Final = 2  # remove
+```
+
+### Reassignment with Final Type Declaration (No Space)
+```python
+def foo():
+    a = 1
+    a: Final=2  # remove
+```
+
+### Simple Variable Reassignment
+```python
+def foo():
+    a = 1
+    a =2
+```
+
+### Type Annotation Followed by Final Reassignment
+```python
+def foo():
+    a: int = 1
+    a: Final[int] = 2  # remove
+```
+
+### Final Reassignment After Int Type Annotation
+```python
+def foo():
+    a: int = 1
+    a: Final = 2  # remove
+```
+
+### Multiple Reassignments with Final and Type Annotation
+```python
+def foo():
+    a: Final = 1  # remove
+    a: Final = 2  # remove
+    a = 3
+    a: int = 4
+```
+
+### Final and Assignment in a Single Line
+```python
+def foo():
+    a: Final = b = 1
+```
+
+### Variable Assignment and Final Annotation
+```python
+def foo():
+    a = 1  # insert
+    b = 2
+    b: Final[int] = 3  # remove
+```

docs/global_vars_enabled.md

@@ -0,0 +1,115 @@
+Test for global variables for case when running **without** `ignore-global-vars`.
+
+### Constants and Variable Assignments
+```python
+MY_CONSTANT = 42  # insert
+MY_OTHER_CONSTANT = "hello"  # insert
+```
+
+### Debug Flag Assignment
+```python
+DEBUG = True  # insert
+```
+
+### Global vs. Local Variable Scope
+```python
+MY_CONSTANT = 42  # insert
+global_var = "hello"
+
+def foo():
+    local_var = 1  # insert
+```
+
+### Constants with Type Hints
+```python
+MY_CONSTANT: typing.Final = 42
+MY_OTHER_CONSTANT = "hello"  # insert
+```
+
+### Constants with Explicit Typing
+```python
+MY_CONSTANT: int = 42  # insert
+MY_OTHER_CONSTANT = "hello"  # insert
+```
+
+### Constant Shadowing in Function Scope
+```python
+MY_CONSTANT = 42  # insert
+
+def foo():
+    MY_CONSTANT = 1  # insert
+    local_var = 2  # insert
+```
+
+### Union Types for Constants
+```python
+FRUIT = Apple | Banana  # insert
+```
+
+### Code Examples with Header Improvements
+
+### Unchanged Global Assignment
+```python
+global_var = 42
+```
+
+### Simple Assignment
+```python
+myVar = "hello"
+```
+
+### Constant Assignment
+```python
+A = 42
+```
+
+### Constants with Global Statement
+
+```python
+MY_CONSTANT = 42
+
+def foo():
+    global MY_CONSTANT
+    MY_CONSTANT = 1
+```
+
+### Constants with Global Declaration
+```python
+from foo import MY_CONSTANT
+MY_CONSTANT = 42
+```
+
+### Final Assignment for Constants
+```python
+a: typing.Final = 1
+```
+
+### TypeVar Declaration for Generics
+```python
+_T = typing.TypeVar("_T")
+```
+
+### Final TypeVar Declaration
+```python
+_T: typing.Final = typing.TypeVar("_T")
+```
+
+### ParamSpec Declaration for Function Generics
+```python
+_P = typing.ParamSpec("_P")
+```
+
+### Final ParamSpec Declaration
+```python
+_P: typing.Final = typing.ParamSpec("_P")
+```
+
+### Union Types for Variables
+```python
+Fruit = Apple | Banana
+```
+
+### String Assignment for Constants
+```python
+A = "ParamSpec"
+```