python-constricter 0.2.2__tar.gz → 0.2.3__tar.gz

{python_constricter-0.2.2 → python_constricter-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-constricter
-Version: 0.2.2
+Version: 0.2.3
 Summary: Lint rules: every local variable is typed where it's first bound. A flake8 plugin, a pylint plugin and a standalone CLI.
 Author: Ivy Duggan
 Requires-Python: >=3.11
@@ -51,6 +51,8 @@ Import-Name: constricter
 
 [snake](https://www.asciiart.eu/art/595284d82d1f8d6d)
 
+<https://pypi.org/project/python-constricter/>
+
 ---
 
 Lint rules: every local variable is typed where it's first bound. Ships as a flake8 plugin, a pylint
@@ -89,27 +91,32 @@ class bodies too. Statements are read in source order, and only a name's first b
 | `LVA004` | with `all-scopes`: the same as `LVA001`, in a module or class body     | `name: T = ...` (`ClassVar[T]` in a dataclass) |
 | `LVA005` | an annotation with `Any`, `object` or a generic without its parameters | name the real type                             |
 | `LVA006` | an annotation nested `nesting` deep (5 by default)                     | a `type` alias for a part of it                |
+| `LVA007` | a name annotated again with the type it already has, in the same block | drop the second annotation                     |
 
 Exempt: comprehensions, `except ... as`, imports, `def`/`class`, `type` aliases, parameters,
 `global`/`nonlocal`, and `_`; in module and class bodies, dunder names (`__all__`, `__slots__`) and
-enum members (a class whose base's name ends in `Enum` or `Flag`).
+enum members (a base imported from `enum`, however it's aliased, or else whose name ends in `Enum`
+or `Flag`).
 
 A `# type:` comment (`x = 1  # type: int`, `with f() as x:  # type: T`) counts as an annotation with
 `type-comments`, or automatically in a module written to run on Python 2: one that imports
 `print_function`, `unicode_literals`, `absolute_import`, `division`, `with_statement`, `generators`
 or `nested_scopes` from `__future__`.
 
+`LVA007` compares a block on its own: an `if`'s body and its `orelse`, a `try`'s body and its
+`except`s, and the like, are different blocks, since they don't both run in the same pass.
+
 ## Levels
 
 Each level makes one more code an error. The rest are warnings: the CLI prints them (as `::warning`
 or SARIF `warning` in those formats) but exits 0; flake8 and pylint report errors only.
 
-| Level             | Errors                           | Warnings                               |
-| ----------------- | -------------------------------- | -------------------------------------- |
-| `relaxed` / `0`   | none                             | `LVA001`–`LVA004`                      |
-| `strict` / `1`    | `LVA001`, `LVA004` (the default) | `LVA002`, `LVA003`, `LVA005`, `LVA006` |
-| `constrict` / `2` | `LVA001`, `LVA004`, `LVA002`     | `LVA003`, `LVA005`, `LVA006`           |
-| `suffocate` / `3` | all                              | none                                   |
+| Level             | Errors                           | Warnings                              |
+| ----------------- | -------------------------------- | ------------------------------------- |
+| `relaxed` / `0`   | none                             | `LVA001`–`LVA004`, `LVA007`           |
+| `strict` / `1`    | `LVA001`, `LVA004` (the default) | `LVA002`, `LVA003`, `LVA005`–`LVA007` |
+| `constrict` / `2` | `LVA001`, `LVA004`, `LVA002`     | `LVA003`, `LVA005`–`LVA007`           |
+| `suffocate` / `3` | all                              | none                                  |
 
 `LVA005` and `LVA006` aren't reported at `relaxed`.
 
@@ -119,14 +126,14 @@ Python 3.11+, no runtime dependencies.
 
 | Tool   | Setup                                                 | Reports                         | Suppress                                         |
 | ------ | ----------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
-| CLI    | `constricter [PATH...] [--level L] [--format F] [-q]` | `LVA001`–`LVA006`               | `# noqa: LVA001`                                 |
-| flake8 | install it (on by default)                            | `LVA001`–`LVA006`               | `# noqa: LVA001`                                 |
-| pylint | `load-plugins = ["constricter.pylint_plugin"]`        | `C9101`–`C9106` (symbols below) | `# noqa: LVA001` or `# pylint: disable=<symbol>` |
-| ruff   | run the CLI after ruff; set `lint.external = ["LVA"]` | `LVA001`–`LVA006`               | `# noqa: LVA001`                                 |
+| CLI    | `constricter [PATH...] [--level L] [--format F] [-q]` | `LVA001`–`LVA007`               | `# noqa: LVA001`                                 |
+| flake8 | install it (on by default)                            | `LVA001`–`LVA007`               | `# noqa: LVA001`                                 |
+| pylint | `load-plugins = ["constricter.pylint_plugin"]`        | `C9101`–`C9107` (symbols below) | `# noqa: LVA001` or `# pylint: disable=<symbol>` |
+| ruff   | run the CLI after ruff; set `lint.external = ["LVA"]` | `LVA001`–`LVA007`               | `# noqa: LVA001`                                 |
 
 pylint symbols: `unannotated-local-variable`, `untyped-for-or-match-variable`,
 `comment-typed-for-variable`, `unannotated-module-or-class-variable`, `vague-annotation`,
-`deeply-nested-annotation`.
+`deeply-nested-annotation`, `redundant-annotation`.
 
 Options:
 
@@ -277,8 +284,9 @@ Trunk) pick the plugin up once it's installed alongside them.
 Without `lint.external`, ruff flags `# noqa: LVA00x` (RUF102) and `--fix` deletes it.
 
 The CLI defaults to `.`, checks `*.py` and `*.ipynb`, and skips hidden dirs, `__pycache__`, `venv`,
-`site-packages`, `build`, `dist` and `node_modules`. Exit codes: `0` no errors, `1` errors, `2` an
-unreadable or unparsable file, or a bad `pyproject.toml`.
+`site-packages`, `build`, `dist` and `node_modules` by directory name; `--exclude` adds more
+directory names (or globs) to skip the same way, on top of matching whole paths and file names. Exit
+codes: `0` no errors, `1` errors, `2` an unreadable or unparsable file, or a bad `pyproject.toml`.
 
 ```bash
 pip install python-constricter # once the first release is out; until then:
@@ -326,6 +334,7 @@ With [uv](https://docs.astral.sh/uv/) installed (CI pins 0.12.17):
 
 ```bash
 export UV_PROJECT_ENVIRONMENT=local/.venv
+uv venv --prompt constricter local/.venv # the prompt name; uv sync reuses this venv
 uv sync --locked --no-install-project --no-build # the dev group: hash-checked wheels from uv.lock
 uv pip install --python local/.venv --no-deps --no-build-isolation -e .
 ```
@@ -337,16 +346,18 @@ Checks (as CI runs them): `ruff check .` (every rule, preview included), `ruff f
 `constricter --coverage --all-scopes --fail-under=100 src tests`, `pytest --cov` (100% branch
 coverage). Everything generated goes in `local/`. Python is indented with 4 spaces.
 
-After editing the `dev` group, run `uv lock` (CI fails until you do). Dependabot updates `uv.lock`,
-the npm lock and the actions weekly.
+After editing a dependency group, run `uv lock` (CI fails until you do). Dependabot updates
+`uv.lock`, the npm lock and the actions weekly.
 
 Fuzzing (`tests/test_fuzz.py`) runs with the tests: hypothesmith generates valid Python, which must
 never crash the checker and must stay valid after `--fix`. For a large real codebase, run
 `local/.venv/bin/python tests/corpus.py [PATH]` by hand: it checks PATH (default: this Python's
-standard library, about 660 files in two seconds) at `suffocate` and prints the time, the offences
+standard library, about 730 files in a few seconds) at `suffocate` and prints the time, the offences
 per code, and any crash. `local/.venv/bin/python tests/corpus_fix.py [PATH]` runs
 `--fix --unsafe-fixes` on a copy of it (in `local/corpus-fix/`) and checks every file still compiles
-and a second pass has nothing left to fix (the standard library: about 3,800 fixes, none breaking).
+and a second pass has nothing left to fix. CI's Corpus job runs both against the standard library
+and, from the pinned `corpus` dependency group (`requests`, `flask`, `django`, `sqlalchemy` — a tiny
+HTTP client, two web frameworks and an ORM), the same way.
 
 CI also runs the tests on PyPy 3.11 and free-threaded Python 3.14, which install only the `test`
 dependency group: every dev tool doesn't have wheels for them, and the tests don't need them all.
@@ -371,7 +382,7 @@ Everything else is on. Some of these may be revisited.
 | typos              | the word `astroid`                                                                                                               | A real package name.                                                                                                                       |
 | harden-runner      | `egress-policy: audit` on macOS and Windows, in the release jobs (release.yml, build.yml), and in the weekly external-link check | harden-runner supports only audit on GitHub's macOS and Windows runners; the release jobs haven't run yet; external links can go anywhere. |
 | reuse              | `reuse lint` not run (the files still comply: `REUSE.toml` covers them)                                                          | No recent release ships a wheel for Python 3.11+, so installing it builds from source with an unpinned `poetry-core`.                      |
-| zizmor             | `self-repository` on the CI job that runs the repository's root action                                                           | zizmor wants `$/`, and actionlint rejects a bare `$/` (it has no path), so that one line uses `./`.                                        |
+| zizmor             | `self-repository` (`.github/zizmor.yml`)                                                                                         | Scorecard reads the `$/` form it wants as an unpinned third-party action, so local actions stay `./`.                                      |
 
 To apply the rulesets in `.github/rulesets/` (repo admin):
 
@@ -392,10 +403,8 @@ Done:
   (Docs), pytest on Linux, macOS and Windows × Python 3.11–3.14 (Test), and the sdist and wheel,
   `twine check` and a wheel smoke test (Build).
 - **security.yml** runs on pushes, PRs and weekly: CodeQL (Python and Actions), zizmor (pedantic),
-  actionlint (kjanat's fork, which reads the `$/` self-repository syntax the workflows use),
-  pip-audit on the lock, and dependency review on PRs.
-- **scorecard.yml** runs OpenSSF Scorecard on `main` and weekly. Its pin check misreads the `$/`
-  references as unpinned actions, so it flags them.
+  actionlint, pip-audit on the lock, and dependency review on PRs.
+- **scorecard.yml** runs OpenSSF Scorecard on `main` and weekly.
 - **release.yml** runs on `v*` tags: CI, then **build.yml** (a reusable workflow) builds the dists,
   checks the tag matches the version, and attests their provenance (SLSA v1 Build Level 3, as the
   build and attestation run in a reusable workflow), then PyPI (trusted publishing), then a GitHub
@@ -423,7 +432,7 @@ Done:
   badges this project's CI keeps true.
 - **Baselines**, a **smarter `--fix`** (containers, same-module return types), **notebooks**, and
   JSON with comments and trailing commas wherever constricter reads JSON.
-- **Fuzzing**, a manual **corpus run** (`tests/corpus.py`), an **adoption guide**, **`--fix` for
+- **Fuzzing**, a **corpus run** (`tests/corpus.py`), an **adoption guide**, **`--fix` for
   notebooks**, and **SLSA Build Level 3 provenance** (GitHub's artifact attestations, from a
   reusable build workflow) on each release.
 - **Python 3.11+**, the oldest version still maintained after 3.10's end of life in October 2026.
@@ -434,8 +443,107 @@ Done:
   Test jobs and Scorecard included.
 - **Stdin**, **`gitlab`, `junit` and `rdjson` output**, **safe and `--unsafe-fixes`**, **per-file
   ignores**, **`--exit-zero`** and **`--output-file`**, **tox and nox** snippets, **PyPy 3.11 and
-  free-threaded 3.14** in CI, and a manual **`--fix` corpus run** (`tests/corpus_fix.py`).
+  free-threaded 3.14** in CI, and a **`--fix` corpus run** (`tests/corpus_fix.py`).
 - **Cross-module `--fix`** in the CLI (the flake8 and pylint plugins see one file at a time).
+- **CI's Corpus job** runs `tests/corpus.py` and `tests/corpus_fix.py` against the runner's Python
+  standard library on every push and PR.
+- **`project.Index`** sorts modules by name so `calls` finds a module/submodule import by prefix
+  (`bisect`) instead of scanning every indexed module.
+- **Enum bases and factory calls resolve by import origin** (`annotations.factories`,
+  `checker._is_enum`'s `imported_from` check), so an aliased or re-exported `Enum`/`NamedTuple`/...
+  is still recognised; the bare-name lists remain a fallback for one imported some other way.
+- **A general path-exclusion mechanism**: `--exclude` globs also match a directory name during a
+  directory walk, folding the built-in skip list (`__pycache__`, `node_modules`, hidden dirs, ...)
+  into the same mechanism instead of a separate hardcoded check.
+- **`_FileRun` split** into `_CheckRun`, `_BaselineRun` and `_CoverageRun` (one per mode-group,
+  instead of one struct with fields only some modes populate), and `_check_path` and
+  `_baseline_path` share a `_read_checked` read-and-report-errors wrapper.
+- **LVA007: duplicate/redundant typing.** A name annotated again with the type it already has, in
+  the same straight-line block; a warning at every level, an error at `suffocate`.
+- **`--fix` infers more**: `not x` (always a real `bool`, unlike a comparison, which sqlalchemy's
+  own corpus data proves isn't safe to assume — it overloads `<`/`==` to build query expressions); a
+  table of builtins with a fixed, un-overloadable return type (`len`→`int`,
+  `isinstance`/`hasattr`/`callable`/`issubclass`→`bool`, `str`/`repr`/`chr`→`str`, `int`/`float`
+  →themselves, ...); and copying an already-known local's type for a plain `x = y` (from its own
+  annotation, an earlier fix in the same scope, or an annotated parameter) — a guessed source's type
+  copies too, marked just as guessed, so a chain of copies still converges in one `--fix` pass
+  instead of needing a second. Verified on the eighteen-codebase corpus below: fixed rose from
+  12,104 to 13,608 of the same 94,523 found (12.8% → 14.4%), no crashes, nothing left to fix on a
+  second pass anywhere, and `requests`' own test suite (not just its compile check) passed
+  identically — 617 passed, 15 skipped, 1 xfailed — before and after `--fix --unsafe-fixes` on its
+  source.
+- **`--fix` infers subscripts and attributes** of an already-typed local: `container[key]` (its
+  element type from a `list`, `dict` or homogeneous `tuple[T, ...]`; the same `list`/`str`/`bytes`
+  type back for a slice; nothing for a fixed-length heterogeneous tuple, since the element varies
+  with the index) and `obj.attr` (a class-level annotated attribute of a class defined in the same
+  module — not one only assigned in `__init__`, which would need dataflow across methods to see).
+  Both build on `_Scope.types`, so a guessed source's uncertainty carries through automatically, the
+  same as a plain copy. Re-verified on the corpus: no crashes, still converges in one `--fix` pass,
+  `requests`' test suite still passes identically, and fixed rose further (e.g. standard library
+  4,431 → 4,450, mypy 1,939 → 1,996, django 2,408 → 2,414, sqlalchemy 830 → 848, pydantic 434 →
+  447).
+- **A permanent, pinned corpus.** By hand (`tests/corpus.py`/`corpus_fix.py`,
+  `--unsafe-fixes --all-scopes`), against eighteen real packages, to choose it — OpenCV's Python
+  bindings (the original idea) turned out to be a poor fit, since they're mostly thin C bindings,
+  not hand-annotated Python:
+
+  | Codebase         | Version | Files | Left un-typed |      Fixed | LVA006 @5 | LVA007 |
+  | ---------------- | ------- | ----: | ------------: | ---------: | --------: | -----: |
+  | standard library | 3.11.16 |   732 |        24,173 |      3,828 |         0 |      0 |
+  | mypy             | 2.3.1   |   195 |         9,853 |      1,777 |         0 |      0 |
+  | pylint           | 4.0.8   |   178 |         3,609 |        486 |         0 |      0 |
+  | libcst           | 1.9.0   |   297 |         3,407 |      1,042 |       201 |      0 |
+  | uiautomator2     | 3.7.0   |    32 |           888 |         86 |         0 |      0 |
+  | requests         | 2.34.2  |    19 |           372 |         45 |         0 |      0 |
+  | flask            | 3.1.3   |    24 |           410 |         29 |         0 |      0 |
+  | click            | 8.5.0   |    17 |           567 |         86 |         0 |      0 |
+  | praw             | 8.0.3   |    89 |           602 |        114 |         0 |      0 |
+  | boto3            | 1.43.99 |    39 |           483 |         93 |         0 |      0 |
+  | django           | 6.1.1   |   907 |        15,648 |      2,248 |         0 |      0 |
+  | pydantic         | 2.13.5  |   105 |         2,998 |        367 |         0 |      0 |
+  | attrs            | 26.1.0  |    13 |           336 |         60 |         0 |      0 |
+  | aiohttp          | 3.14.3  |    55 |         1,590 |        217 |         0 |      0 |
+  | paramiko         | 5.0.0   |    41 |         1,272 |        241 |         0 |      0 |
+  | scrapy           | 2.19.0  |   179 |         1,814 |        389 |         1 |      0 |
+  | sqlalchemy       | 2.0.54  |   257 |        12,556 |        643 |         7 |      0 |
+  | rich             | 15.0.0  |   100 |         1,841 |        353 |         0 |      0 |
+  | **Total**        |         |       |    **82,419** | **12,104** |           |        |
+
+  No crashes on any of them, and `--unsafe-fixes` left nothing broken or nothing unfixed on a second
+  pass, on any of them; `--nesting`'s default (5) never fires on fourteen of the eighteen, and
+  LVA007 found nothing on any of them, at any nesting — strong evidence it isn't noisy
+  (`--nesting`'s default is still worth revisiting some day: `libcst`, deeply nested CST types, is
+  by far the most affected, `sqlalchemy` and `scrapy` are the only other two to hit it at all at the
+  default, and 3 already reported 124 times on sqlalchemy, 45 on mypy). Chose four to run
+  permanently in CI (see the Corpus job): **`requests`** (tiny, so a fast check; extremely stable
+  and widely known; the canonical "makes external API calls" library; unlike the dev tools,
+  representative of typical, lightly-typed real-world code), **`flask`** and **`django`** (two web
+  frameworks, more decorator/class-heavy than `requests`; `django` pinned to the 5.2 LTS, since 6.x
+  needs Python 3.12+) and **`sqlalchemy`** (an ORM, and the corpus most likely to exercise
+  `LVA006`). Each runs as its own Corpus (`package`) matrix job, from a new `corpus` dependency
+  group.
+
+  Also validated `requests` specifically: cloned `v2.34.2` (its source checkout, with its own test
+  suite, not just the installed wheel), ran `--fix --unsafe-fixes --all-scopes` on `src/requests/`,
+  and ran its own test suite before and after. Identical both times: 617 passed, 15 skipped, 1
+  xfailed — the inferred types changed nothing about its runtime behaviour. One found a real, if
+  inert, mistake in the "guessed" heuristic: `internetSettings = winreg.OpenKey(...)` (Windows-only,
+  guarded by `sys.platform == "win32"`, so untested by this run) got annotated
+  `internetSettings: winreg.OpenKey = ...` — `winreg.OpenKey` is a _function_, not a class, but its
+  PascalCase name (a Windows API convention, not Python's) fools the capitalised-name "constructs a
+  class" heuristic (`annotations._constructs`).
+
+- **`--fix` infers `self.attr` and `str`/`bytes` method calls.** `classes` (used for `obj.attr`) now
+  also collects `self.x: T = ...` from anywhere in a method's body, not just class-level
+  annotations; a method whose first parameter is literally named `self` has it typed as its class
+  (`_owners`, by the method's `id()`, not by name — a same-named method on an unrelated class isn't
+  confused with it), so `self.attr` resolves the same way `obj.attr` already did. Separately, a
+  fixed table of `str`/`bytes` methods whose return type doesn't depend on their arguments (`strip`,
+  `split`, `startswith`, `encode`, `decode`, ...) makes `some_str.strip()` on an already-typed local
+  as certain as a builtin function call — not a guess, unlike an arbitrary method call, which stays
+  guessed. Re-verified on the corpus: no crashes, still converges in one `--fix` pass on all six
+  re-checked (standard library, mypy, `requests`, `flask`, `django`, `sqlalchemy`), and fixed rose
+  further still (e.g. mypy 1,996 → 2,074, sqlalchemy 848 → 1,039, `requests` 52 → 57).
 
 Next:
 
@@ -443,6 +551,48 @@ Next:
    CPython 3.10 one).
 2. Revisit the [disabled rules](#disabled-rules) as tools change (last checked 2026-09-22: COM812,
    one-line DOC201/DOC402 and `max-args` came back on; the rest can't go yet).
+3. **Raise `--fix`'s auto-fix rate further.** Attributes, subscripts, `self.attr` and `str`/`bytes`
+   method calls are done (see Done, above); what's left: a method call on an arbitrary class's
+   instance (`x = obj.method()`, unlike `str`/`bytes` isn't resolvable without following the
+   method's own return annotation, the same as `classes` already does for a field, extended to
+   methods) and `list`/`dict` methods whose return is the receiver's own element type (`list.pop`,
+   `dict.pop`, ...), which need the same element-type parsing `_subscripted` already does, just
+   reached from a method call instead of a subscript. `BinOp` (`a + b`, ~5% of the original sample)
+   would need operand types plus knowing the operator isn't overloaded to something else — riskier,
+   lower value, likely skip.
+4. **LVA008: a type that could narrow.** A warning at `constrict`, an error at `suffocate`: a
+   declared type that every value assigned to the name (across its lifetime, not just its first
+   binding) is consistent with a strictly narrower one, e.g. a `str` only ever assigned `"0"` or
+   `"1"` (could be `bool`), or a `float` only ever incremented, never divided (could be `int`).
+   Needs whole-variable value-flow analysis across every reassignment in a scope, not just a first
+   binding, which is a different (and much bigger) kind of check than `LVA001`–`LVA007`; wants its
+   own design pass (what counts as "consistent with" a type, how far to follow calls and mutation,
+   false-positive risk on a codebase this analysis can't fully see) before it's worth building.
+5. **LVA009: a reassignment that changes the type.** An error: `count: int = 0` later reassigned
+   `count = "done"` in the same scope. A real, common bug class (mypy already treats this as a type
+   error by default), but needs the same value-flow machinery as `LVA008` (infer every
+   reassignment's type with `annotations.inferred`, not just the first binding's), plus real
+   subtyping awareness to avoid noise `LVA008` doesn't have to worry about: a declared `X | None`
+   later assigned a plain `X` is normal Optional narrowing, not a bug, so the check needs to know
+   that's consistent rather than comparing annotation text like `LVA007` does; a name reused for
+   genuinely unrelated purposes (a sentinel, a generic helper handling more than one type by design)
+   is a real, if rarer, source of false positives to design around. Depends on `LVA008`'s design
+   work (same value-flow pass could likely serve both checks).
+6. **LVA010: a declared union only one branch ever uses.** A warning: `x: int | str = 0` where every
+   value ever assigned across `x`'s lifetime is consistent with only `int`, never `str` — the union
+   is wider than the code actually exercises, and could narrow to `int`. The complement of `LVA008`
+   (inferring a narrower type from values with no declared type to compare against) and `LVA009` (a
+   reassignment that breaks a declared type, not just widens what's already declared as a union);
+   shares the same value-flow machinery and design questions as both.
+7. **Show how each fix was inferred.** `annotations.inferred` now decides a fix through one of
+   several mechanisms (a literal, a container of literals, a same/cross-module function's declared
+   return type, a fixed-return builtin, a class it constructs, a copy of an already-typed local, a
+   subscript or an attribute of one), but `Offence.fix` keeps only the resulting annotation text,
+   not which one produced it. Surfacing that (`--diff`, or a verbose/explain mode) would help trust
+   and debug a fix, especially a guessed one. Needs every inference helper (`_scalar`, `_container`,
+   `_called`, `_subscripted`, the copy and attribute checks in `inferred` itself) to report a reason
+   alongside the type, not just the type — a real (if mechanical) change through most of
+   `annotations.py`'s inference path, not a one-line addition.
 
 After the first release (these need it on PyPI, or a published tag):
 

{python_constricter-0.2.2 → python_constricter-0.2.3}/README.md

@@ -31,6 +31,8 @@
 
 [snake](https://www.asciiart.eu/art/595284d82d1f8d6d)
 
+<https://pypi.org/project/python-constricter/>
+
 ---
 
 Lint rules: every local variable is typed where it's first bound. Ships as a flake8 plugin, a pylint
@@ -69,27 +71,32 @@ class bodies too. Statements are read in source order, and only a name's first b
 | `LVA004` | with `all-scopes`: the same as `LVA001`, in a module or class body     | `name: T = ...` (`ClassVar[T]` in a dataclass) |
 | `LVA005` | an annotation with `Any`, `object` or a generic without its parameters | name the real type                             |
 | `LVA006` | an annotation nested `nesting` deep (5 by default)                     | a `type` alias for a part of it                |
+| `LVA007` | a name annotated again with the type it already has, in the same block | drop the second annotation                     |
 
 Exempt: comprehensions, `except ... as`, imports, `def`/`class`, `type` aliases, parameters,
 `global`/`nonlocal`, and `_`; in module and class bodies, dunder names (`__all__`, `__slots__`) and
-enum members (a class whose base's name ends in `Enum` or `Flag`).
+enum members (a base imported from `enum`, however it's aliased, or else whose name ends in `Enum`
+or `Flag`).
 
 A `# type:` comment (`x = 1  # type: int`, `with f() as x:  # type: T`) counts as an annotation with
 `type-comments`, or automatically in a module written to run on Python 2: one that imports
 `print_function`, `unicode_literals`, `absolute_import`, `division`, `with_statement`, `generators`
 or `nested_scopes` from `__future__`.
 
+`LVA007` compares a block on its own: an `if`'s body and its `orelse`, a `try`'s body and its
+`except`s, and the like, are different blocks, since they don't both run in the same pass.
+
 ## Levels
 
 Each level makes one more code an error. The rest are warnings: the CLI prints them (as `::warning`
 or SARIF `warning` in those formats) but exits 0; flake8 and pylint report errors only.
 
-| Level             | Errors                           | Warnings                               |
-| ----------------- | -------------------------------- | -------------------------------------- |
-| `relaxed` / `0`   | none                             | `LVA001`–`LVA004`                      |
-| `strict` / `1`    | `LVA001`, `LVA004` (the default) | `LVA002`, `LVA003`, `LVA005`, `LVA006` |
-| `constrict` / `2` | `LVA001`, `LVA004`, `LVA002`     | `LVA003`, `LVA005`, `LVA006`           |
-| `suffocate` / `3` | all                              | none                                   |
+| Level             | Errors                           | Warnings                              |
+| ----------------- | -------------------------------- | ------------------------------------- |
+| `relaxed` / `0`   | none                             | `LVA001`–`LVA004`, `LVA007`           |
+| `strict` / `1`    | `LVA001`, `LVA004` (the default) | `LVA002`, `LVA003`, `LVA005`–`LVA007` |
+| `constrict` / `2` | `LVA001`, `LVA004`, `LVA002`     | `LVA003`, `LVA005`–`LVA007`           |
+| `suffocate` / `3` | all                              | none                                  |
 
 `LVA005` and `LVA006` aren't reported at `relaxed`.
 
@@ -99,14 +106,14 @@ Python 3.11+, no runtime dependencies.
 
 | Tool   | Setup                                                 | Reports                         | Suppress                                         |
 | ------ | ----------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
-| CLI    | `constricter [PATH...] [--level L] [--format F] [-q]` | `LVA001`–`LVA006`               | `# noqa: LVA001`                                 |
-| flake8 | install it (on by default)                            | `LVA001`–`LVA006`               | `# noqa: LVA001`                                 |
-| pylint | `load-plugins = ["constricter.pylint_plugin"]`        | `C9101`–`C9106` (symbols below) | `# noqa: LVA001` or `# pylint: disable=<symbol>` |
-| ruff   | run the CLI after ruff; set `lint.external = ["LVA"]` | `LVA001`–`LVA006`               | `# noqa: LVA001`                                 |
+| CLI    | `constricter [PATH...] [--level L] [--format F] [-q]` | `LVA001`–`LVA007`               | `# noqa: LVA001`                                 |
+| flake8 | install it (on by default)                            | `LVA001`–`LVA007`               | `# noqa: LVA001`                                 |
+| pylint | `load-plugins = ["constricter.pylint_plugin"]`        | `C9101`–`C9107` (symbols below) | `# noqa: LVA001` or `# pylint: disable=<symbol>` |
+| ruff   | run the CLI after ruff; set `lint.external = ["LVA"]` | `LVA001`–`LVA007`               | `# noqa: LVA001`                                 |
 
 pylint symbols: `unannotated-local-variable`, `untyped-for-or-match-variable`,
 `comment-typed-for-variable`, `unannotated-module-or-class-variable`, `vague-annotation`,
-`deeply-nested-annotation`.
+`deeply-nested-annotation`, `redundant-annotation`.
 
 Options:
 
@@ -257,8 +264,9 @@ Trunk) pick the plugin up once it's installed alongside them.
 Without `lint.external`, ruff flags `# noqa: LVA00x` (RUF102) and `--fix` deletes it.
 
 The CLI defaults to `.`, checks `*.py` and `*.ipynb`, and skips hidden dirs, `__pycache__`, `venv`,
-`site-packages`, `build`, `dist` and `node_modules`. Exit codes: `0` no errors, `1` errors, `2` an
-unreadable or unparsable file, or a bad `pyproject.toml`.
+`site-packages`, `build`, `dist` and `node_modules` by directory name; `--exclude` adds more
+directory names (or globs) to skip the same way, on top of matching whole paths and file names. Exit
+codes: `0` no errors, `1` errors, `2` an unreadable or unparsable file, or a bad `pyproject.toml`.
 
 ```bash
 pip install python-constricter # once the first release is out; until then:
@@ -306,6 +314,7 @@ With [uv](https://docs.astral.sh/uv/) installed (CI pins 0.12.17):
 
 ```bash
 export UV_PROJECT_ENVIRONMENT=local/.venv
+uv venv --prompt constricter local/.venv # the prompt name; uv sync reuses this venv
 uv sync --locked --no-install-project --no-build # the dev group: hash-checked wheels from uv.lock
 uv pip install --python local/.venv --no-deps --no-build-isolation -e .
 ```
@@ -317,16 +326,18 @@ Checks (as CI runs them): `ruff check .` (every rule, preview included), `ruff f
 `constricter --coverage --all-scopes --fail-under=100 src tests`, `pytest --cov` (100% branch
 coverage). Everything generated goes in `local/`. Python is indented with 4 spaces.
 
-After editing the `dev` group, run `uv lock` (CI fails until you do). Dependabot updates `uv.lock`,
-the npm lock and the actions weekly.
+After editing a dependency group, run `uv lock` (CI fails until you do). Dependabot updates
+`uv.lock`, the npm lock and the actions weekly.
 
 Fuzzing (`tests/test_fuzz.py`) runs with the tests: hypothesmith generates valid Python, which must
 never crash the checker and must stay valid after `--fix`. For a large real codebase, run
 `local/.venv/bin/python tests/corpus.py [PATH]` by hand: it checks PATH (default: this Python's
-standard library, about 660 files in two seconds) at `suffocate` and prints the time, the offences
+standard library, about 730 files in a few seconds) at `suffocate` and prints the time, the offences
 per code, and any crash. `local/.venv/bin/python tests/corpus_fix.py [PATH]` runs
 `--fix --unsafe-fixes` on a copy of it (in `local/corpus-fix/`) and checks every file still compiles
-and a second pass has nothing left to fix (the standard library: about 3,800 fixes, none breaking).
+and a second pass has nothing left to fix. CI's Corpus job runs both against the standard library
+and, from the pinned `corpus` dependency group (`requests`, `flask`, `django`, `sqlalchemy` — a tiny
+HTTP client, two web frameworks and an ORM), the same way.
 
 CI also runs the tests on PyPy 3.11 and free-threaded Python 3.14, which install only the `test`
 dependency group: every dev tool doesn't have wheels for them, and the tests don't need them all.
@@ -351,7 +362,7 @@ Everything else is on. Some of these may be revisited.
 | typos              | the word `astroid`                                                                                                               | A real package name.                                                                                                                       |
 | harden-runner      | `egress-policy: audit` on macOS and Windows, in the release jobs (release.yml, build.yml), and in the weekly external-link check | harden-runner supports only audit on GitHub's macOS and Windows runners; the release jobs haven't run yet; external links can go anywhere. |
 | reuse              | `reuse lint` not run (the files still comply: `REUSE.toml` covers them)                                                          | No recent release ships a wheel for Python 3.11+, so installing it builds from source with an unpinned `poetry-core`.                      |
-| zizmor             | `self-repository` on the CI job that runs the repository's root action                                                           | zizmor wants `$/`, and actionlint rejects a bare `$/` (it has no path), so that one line uses `./`.                                        |
+| zizmor             | `self-repository` (`.github/zizmor.yml`)                                                                                         | Scorecard reads the `$/` form it wants as an unpinned third-party action, so local actions stay `./`.                                      |
 
 To apply the rulesets in `.github/rulesets/` (repo admin):
 
@@ -372,10 +383,8 @@ Done:
   (Docs), pytest on Linux, macOS and Windows × Python 3.11–3.14 (Test), and the sdist and wheel,
   `twine check` and a wheel smoke test (Build).
 - **security.yml** runs on pushes, PRs and weekly: CodeQL (Python and Actions), zizmor (pedantic),
-  actionlint (kjanat's fork, which reads the `$/` self-repository syntax the workflows use),
-  pip-audit on the lock, and dependency review on PRs.
-- **scorecard.yml** runs OpenSSF Scorecard on `main` and weekly. Its pin check misreads the `$/`
-  references as unpinned actions, so it flags them.
+  actionlint, pip-audit on the lock, and dependency review on PRs.
+- **scorecard.yml** runs OpenSSF Scorecard on `main` and weekly.
 - **release.yml** runs on `v*` tags: CI, then **build.yml** (a reusable workflow) builds the dists,
   checks the tag matches the version, and attests their provenance (SLSA v1 Build Level 3, as the
   build and attestation run in a reusable workflow), then PyPI (trusted publishing), then a GitHub
@@ -403,7 +412,7 @@ Done:
   badges this project's CI keeps true.
 - **Baselines**, a **smarter `--fix`** (containers, same-module return types), **notebooks**, and
   JSON with comments and trailing commas wherever constricter reads JSON.
-- **Fuzzing**, a manual **corpus run** (`tests/corpus.py`), an **adoption guide**, **`--fix` for
+- **Fuzzing**, a **corpus run** (`tests/corpus.py`), an **adoption guide**, **`--fix` for
   notebooks**, and **SLSA Build Level 3 provenance** (GitHub's artifact attestations, from a
   reusable build workflow) on each release.
 - **Python 3.11+**, the oldest version still maintained after 3.10's end of life in October 2026.
@@ -414,8 +423,107 @@ Done:
   Test jobs and Scorecard included.
 - **Stdin**, **`gitlab`, `junit` and `rdjson` output**, **safe and `--unsafe-fixes`**, **per-file
   ignores**, **`--exit-zero`** and **`--output-file`**, **tox and nox** snippets, **PyPy 3.11 and
-  free-threaded 3.14** in CI, and a manual **`--fix` corpus run** (`tests/corpus_fix.py`).
+  free-threaded 3.14** in CI, and a **`--fix` corpus run** (`tests/corpus_fix.py`).
 - **Cross-module `--fix`** in the CLI (the flake8 and pylint plugins see one file at a time).
+- **CI's Corpus job** runs `tests/corpus.py` and `tests/corpus_fix.py` against the runner's Python
+  standard library on every push and PR.
+- **`project.Index`** sorts modules by name so `calls` finds a module/submodule import by prefix
+  (`bisect`) instead of scanning every indexed module.
+- **Enum bases and factory calls resolve by import origin** (`annotations.factories`,
+  `checker._is_enum`'s `imported_from` check), so an aliased or re-exported `Enum`/`NamedTuple`/...
+  is still recognised; the bare-name lists remain a fallback for one imported some other way.
+- **A general path-exclusion mechanism**: `--exclude` globs also match a directory name during a
+  directory walk, folding the built-in skip list (`__pycache__`, `node_modules`, hidden dirs, ...)
+  into the same mechanism instead of a separate hardcoded check.
+- **`_FileRun` split** into `_CheckRun`, `_BaselineRun` and `_CoverageRun` (one per mode-group,
+  instead of one struct with fields only some modes populate), and `_check_path` and
+  `_baseline_path` share a `_read_checked` read-and-report-errors wrapper.
+- **LVA007: duplicate/redundant typing.** A name annotated again with the type it already has, in
+  the same straight-line block; a warning at every level, an error at `suffocate`.
+- **`--fix` infers more**: `not x` (always a real `bool`, unlike a comparison, which sqlalchemy's
+  own corpus data proves isn't safe to assume — it overloads `<`/`==` to build query expressions); a
+  table of builtins with a fixed, un-overloadable return type (`len`→`int`,
+  `isinstance`/`hasattr`/`callable`/`issubclass`→`bool`, `str`/`repr`/`chr`→`str`, `int`/`float`
+  →themselves, ...); and copying an already-known local's type for a plain `x = y` (from its own
+  annotation, an earlier fix in the same scope, or an annotated parameter) — a guessed source's type
+  copies too, marked just as guessed, so a chain of copies still converges in one `--fix` pass
+  instead of needing a second. Verified on the eighteen-codebase corpus below: fixed rose from
+  12,104 to 13,608 of the same 94,523 found (12.8% → 14.4%), no crashes, nothing left to fix on a
+  second pass anywhere, and `requests`' own test suite (not just its compile check) passed
+  identically — 617 passed, 15 skipped, 1 xfailed — before and after `--fix --unsafe-fixes` on its
+  source.
+- **`--fix` infers subscripts and attributes** of an already-typed local: `container[key]` (its
+  element type from a `list`, `dict` or homogeneous `tuple[T, ...]`; the same `list`/`str`/`bytes`
+  type back for a slice; nothing for a fixed-length heterogeneous tuple, since the element varies
+  with the index) and `obj.attr` (a class-level annotated attribute of a class defined in the same
+  module — not one only assigned in `__init__`, which would need dataflow across methods to see).
+  Both build on `_Scope.types`, so a guessed source's uncertainty carries through automatically, the
+  same as a plain copy. Re-verified on the corpus: no crashes, still converges in one `--fix` pass,
+  `requests`' test suite still passes identically, and fixed rose further (e.g. standard library
+  4,431 → 4,450, mypy 1,939 → 1,996, django 2,408 → 2,414, sqlalchemy 830 → 848, pydantic 434 →
+  447).
+- **A permanent, pinned corpus.** By hand (`tests/corpus.py`/`corpus_fix.py`,
+  `--unsafe-fixes --all-scopes`), against eighteen real packages, to choose it — OpenCV's Python
+  bindings (the original idea) turned out to be a poor fit, since they're mostly thin C bindings,
+  not hand-annotated Python:
+
+  | Codebase         | Version | Files | Left un-typed |      Fixed | LVA006 @5 | LVA007 |
+  | ---------------- | ------- | ----: | ------------: | ---------: | --------: | -----: |
+  | standard library | 3.11.16 |   732 |        24,173 |      3,828 |         0 |      0 |
+  | mypy             | 2.3.1   |   195 |         9,853 |      1,777 |         0 |      0 |
+  | pylint           | 4.0.8   |   178 |         3,609 |        486 |         0 |      0 |
+  | libcst           | 1.9.0   |   297 |         3,407 |      1,042 |       201 |      0 |
+  | uiautomator2     | 3.7.0   |    32 |           888 |         86 |         0 |      0 |
+  | requests         | 2.34.2  |    19 |           372 |         45 |         0 |      0 |
+  | flask            | 3.1.3   |    24 |           410 |         29 |         0 |      0 |
+  | click            | 8.5.0   |    17 |           567 |         86 |         0 |      0 |
+  | praw             | 8.0.3   |    89 |           602 |        114 |         0 |      0 |
+  | boto3            | 1.43.99 |    39 |           483 |         93 |         0 |      0 |
+  | django           | 6.1.1   |   907 |        15,648 |      2,248 |         0 |      0 |
+  | pydantic         | 2.13.5  |   105 |         2,998 |        367 |         0 |      0 |
+  | attrs            | 26.1.0  |    13 |           336 |         60 |         0 |      0 |
+  | aiohttp          | 3.14.3  |    55 |         1,590 |        217 |         0 |      0 |
+  | paramiko         | 5.0.0   |    41 |         1,272 |        241 |         0 |      0 |
+  | scrapy           | 2.19.0  |   179 |         1,814 |        389 |         1 |      0 |
+  | sqlalchemy       | 2.0.54  |   257 |        12,556 |        643 |         7 |      0 |
+  | rich             | 15.0.0  |   100 |         1,841 |        353 |         0 |      0 |
+  | **Total**        |         |       |    **82,419** | **12,104** |           |        |
+
+  No crashes on any of them, and `--unsafe-fixes` left nothing broken or nothing unfixed on a second
+  pass, on any of them; `--nesting`'s default (5) never fires on fourteen of the eighteen, and
+  LVA007 found nothing on any of them, at any nesting — strong evidence it isn't noisy
+  (`--nesting`'s default is still worth revisiting some day: `libcst`, deeply nested CST types, is
+  by far the most affected, `sqlalchemy` and `scrapy` are the only other two to hit it at all at the
+  default, and 3 already reported 124 times on sqlalchemy, 45 on mypy). Chose four to run
+  permanently in CI (see the Corpus job): **`requests`** (tiny, so a fast check; extremely stable
+  and widely known; the canonical "makes external API calls" library; unlike the dev tools,
+  representative of typical, lightly-typed real-world code), **`flask`** and **`django`** (two web
+  frameworks, more decorator/class-heavy than `requests`; `django` pinned to the 5.2 LTS, since 6.x
+  needs Python 3.12+) and **`sqlalchemy`** (an ORM, and the corpus most likely to exercise
+  `LVA006`). Each runs as its own Corpus (`package`) matrix job, from a new `corpus` dependency
+  group.
+
+  Also validated `requests` specifically: cloned `v2.34.2` (its source checkout, with its own test
+  suite, not just the installed wheel), ran `--fix --unsafe-fixes --all-scopes` on `src/requests/`,
+  and ran its own test suite before and after. Identical both times: 617 passed, 15 skipped, 1
+  xfailed — the inferred types changed nothing about its runtime behaviour. One found a real, if
+  inert, mistake in the "guessed" heuristic: `internetSettings = winreg.OpenKey(...)` (Windows-only,
+  guarded by `sys.platform == "win32"`, so untested by this run) got annotated
+  `internetSettings: winreg.OpenKey = ...` — `winreg.OpenKey` is a _function_, not a class, but its
+  PascalCase name (a Windows API convention, not Python's) fools the capitalised-name "constructs a
+  class" heuristic (`annotations._constructs`).
+
+- **`--fix` infers `self.attr` and `str`/`bytes` method calls.** `classes` (used for `obj.attr`) now
+  also collects `self.x: T = ...` from anywhere in a method's body, not just class-level
+  annotations; a method whose first parameter is literally named `self` has it typed as its class
+  (`_owners`, by the method's `id()`, not by name — a same-named method on an unrelated class isn't
+  confused with it), so `self.attr` resolves the same way `obj.attr` already did. Separately, a
+  fixed table of `str`/`bytes` methods whose return type doesn't depend on their arguments (`strip`,
+  `split`, `startswith`, `encode`, `decode`, ...) makes `some_str.strip()` on an already-typed local
+  as certain as a builtin function call — not a guess, unlike an arbitrary method call, which stays
+  guessed. Re-verified on the corpus: no crashes, still converges in one `--fix` pass on all six
+  re-checked (standard library, mypy, `requests`, `flask`, `django`, `sqlalchemy`), and fixed rose
+  further still (e.g. mypy 1,996 → 2,074, sqlalchemy 848 → 1,039, `requests` 52 → 57).
 
 Next:
 
@@ -423,6 +531,48 @@ Next:
    CPython 3.10 one).
 2. Revisit the [disabled rules](#disabled-rules) as tools change (last checked 2026-09-22: COM812,
    one-line DOC201/DOC402 and `max-args` came back on; the rest can't go yet).
+3. **Raise `--fix`'s auto-fix rate further.** Attributes, subscripts, `self.attr` and `str`/`bytes`
+   method calls are done (see Done, above); what's left: a method call on an arbitrary class's
+   instance (`x = obj.method()`, unlike `str`/`bytes` isn't resolvable without following the
+   method's own return annotation, the same as `classes` already does for a field, extended to
+   methods) and `list`/`dict` methods whose return is the receiver's own element type (`list.pop`,
+   `dict.pop`, ...), which need the same element-type parsing `_subscripted` already does, just
+   reached from a method call instead of a subscript. `BinOp` (`a + b`, ~5% of the original sample)
+   would need operand types plus knowing the operator isn't overloaded to something else — riskier,
+   lower value, likely skip.
+4. **LVA008: a type that could narrow.** A warning at `constrict`, an error at `suffocate`: a
+   declared type that every value assigned to the name (across its lifetime, not just its first
+   binding) is consistent with a strictly narrower one, e.g. a `str` only ever assigned `"0"` or
+   `"1"` (could be `bool`), or a `float` only ever incremented, never divided (could be `int`).
+   Needs whole-variable value-flow analysis across every reassignment in a scope, not just a first
+   binding, which is a different (and much bigger) kind of check than `LVA001`–`LVA007`; wants its
+   own design pass (what counts as "consistent with" a type, how far to follow calls and mutation,
+   false-positive risk on a codebase this analysis can't fully see) before it's worth building.
+5. **LVA009: a reassignment that changes the type.** An error: `count: int = 0` later reassigned
+   `count = "done"` in the same scope. A real, common bug class (mypy already treats this as a type
+   error by default), but needs the same value-flow machinery as `LVA008` (infer every
+   reassignment's type with `annotations.inferred`, not just the first binding's), plus real
+   subtyping awareness to avoid noise `LVA008` doesn't have to worry about: a declared `X | None`
+   later assigned a plain `X` is normal Optional narrowing, not a bug, so the check needs to know
+   that's consistent rather than comparing annotation text like `LVA007` does; a name reused for
+   genuinely unrelated purposes (a sentinel, a generic helper handling more than one type by design)
+   is a real, if rarer, source of false positives to design around. Depends on `LVA008`'s design
+   work (same value-flow pass could likely serve both checks).
+6. **LVA010: a declared union only one branch ever uses.** A warning: `x: int | str = 0` where every
+   value ever assigned across `x`'s lifetime is consistent with only `int`, never `str` — the union
+   is wider than the code actually exercises, and could narrow to `int`. The complement of `LVA008`
+   (inferring a narrower type from values with no declared type to compare against) and `LVA009` (a
+   reassignment that breaks a declared type, not just widens what's already declared as a union);
+   shares the same value-flow machinery and design questions as both.
+7. **Show how each fix was inferred.** `annotations.inferred` now decides a fix through one of
+   several mechanisms (a literal, a container of literals, a same/cross-module function's declared
+   return type, a fixed-return builtin, a class it constructs, a copy of an already-typed local, a
+   subscript or an attribute of one), but `Offence.fix` keeps only the resulting annotation text,
+   not which one produced it. Surfacing that (`--diff`, or a verbose/explain mode) would help trust
+   and debug a fix, especially a guessed one. Needs every inference helper (`_scalar`, `_container`,
+   `_called`, `_subscripted`, the copy and attribute checks in `inferred` itself) to report a reason
+   alongside the type, not just the type — a real (if mechanical) change through most of
+   `annotations.py`'s inference path, not a one-line addition.
 
 After the first release (these need it on PyPI, or a published tag):