python-constricter 0.4.1__cp311-cp311-win_amd64.whl

constricter/rules/late.py

@@ -0,0 +1,969 @@
+# SPDX-License-Identifier: MIT
+"""A scope's late fixes: those that need the whole scope seen, run once it's checked (see `checker`).
+
+`optionals` (`None`, then one type), `rebinds` (a fix refitted to every later value), `extended`
+(a display widened to what's added to it later), `fills` (an empty container typed by what's added
+to it), `shadowed` (a fix naming a value of its own scope,
+dropped), `excused` (a fix of a name a `# type: ignore` line uses, dropped), `unchecked` (a guess
+its function's use of the name makes an error of, dropped), and `finals` (LVA012's `Final`).
+"""
+
+import ast
+import bisect
+import re
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import replace
+from functools import lru_cache
+from typing import TYPE_CHECKING, Final, TypeAlias, cast
+
+from constricter.fix.core.imports import imports_of
+from constricter.fix.core.known import ImportPlan, Inference
+from constricter.fix.values import callables, displays, hinted
+from constricter.fix.values import fills as filling
+from constricter.fix.values import unchecked as misused
+from constricter.fix.values.doubts import contains_inner, narrowing, spelled_self
+from constricter.fix.values.inference import RETURNED
+from constricter.fix.values.narrowed import narrowed_at
+from constricter.offences import (
+    CAN_BE_FINAL,
+    EMPTY_CONTAINERS,
+    MIXED_CONTAINERS,
+    UNANNOTATED,
+    UNANNOTATED_MEMBER,
+    UNIONS,
+    UNKNOWN_CALLS,
+    UNTYPED_CALLS,
+    UNTYPED_TARGET,
+    VAGUE_KIND,
+    WIDEN_KINDS,
+    Edit,
+    Fix,
+    Offence,
+    at,
+)
+from constricter.rules import widened
+from constricter.rules.annotations import node_name, roots
+from constricter.rules.flow import Binding, Lifetime, members
+from constricter.rules.rebinding import Refit, refit
+from constricter.rules.scope import FINAL_KIND, Scope, guesses_in
+from constricter.rules.syntax import FunctionDef
+from constricter.rules.walked import children
+
+if TYPE_CHECKING:
+    from constricter.rules.scoped import Late, Plain
+
+_DISCARD: Final = "_"
+_OPTIONAL: Final = "optional"  # the fix kind of a `None` default rebound to one type
+_DECLARING: Final = frozenset({UNANNOTATED, UNTYPED_TARGET})  # the codes whose fix declares a name's type
+_FILLED: Final = "filled"  # the fix kind (and guessing mechanism) of an empty container filled later
+_CONTAINER: Final = "container"  # the fix kind of a display
+_DICT: Final = "dict"
+_FILLABLE: Final = frozenset({"list", "set", _DICT})  # the displays `extended` widens
+# The builtin numbers, narrowest first: each takes the ones before it, as a type checker has it.
+_NUMBERS: Final = ("bool", "int", "float", "complex")
+_BAR: Final = " | "
+_CALLERS: Final = "callers"  # and of a parameter typed by what every call passes it
+_NONE: Final = "None"
+_FINAL: Final = "Final"
+_TYPING_FINAL: Final = "typing.Final"
+_FINALS: Final = frozenset({_TYPING_FINAL, "typing_extensions.Final"})
+_NO_ALIASES: Final = frozenset[str]()
+_INNER: Final = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)  # what reads a name later
+_IGNORE: Final = re.compile(r"#\s*type:\s*ignore")  # a comment excusing its line to a type checker
+_WORD: Final = re.compile(r"[A-Za-z_]\w*")
+# The guesses of a value a type checker takes for anything: held to no class until declared.
+_UNCHECKED: Final = hinted.KINDS | {RETURNED}
+# The wider types `widens` offers, once a scope's other fixes are settled.
+_LATE_WIDENINGS: Final = frozenset(
+    {VAGUE_KIND, EMPTY_CONTAINERS, MIXED_CONTAINERS, UNTYPED_CALLS, UNKNOWN_CALLS},
+)
+# The arms a binding is in: each branching statement around it (by `id()`), and which of its arms.
+_Arms: TypeAlias = tuple[tuple[int, int], ...]
+
+
+def optionals(scope: Scope) -> None:
+    """Offer `T | None` to a name first bound to `None`, then only ever to a known `T`.
+
+    Every later binding must have a type value flow is sure of (or `--fix` guessed, which makes
+    this a guess too), all the same one, not itself allowing `None`, and nothing in another scope
+    may write the name (`nonlocal`, `global`), nor read it: a function or lambda inside this one
+    reading it sees the declared `T | None`, where a type checker without it would see what the
+    name was narrowed to.
+    """
+    index: int
+    o: Offence
+    enclosed: frozenset[str] | None = None
+    for index, o in enumerate(scope.offences):
+        lifetime: Lifetime | None = scope.flow.get(o.name)
+        if o.code != UNANNOTATED or _fixed(o) or lifetime is None or lifetime.escaped:
+            continue
+        if enclosed is None:
+            function: FunctionDef | None = scope.kind.function
+            inside: bool = function is not None and contains_inner(function, scope.settings.facts.inner)
+            enclosed = _enclosed_reads(function) if function is not None and inside else frozenset()
+        if o.name in enclosed:
+            continue
+        first: Binding
+        rest: list[Binding]
+        first, *rest = lifetime.bindings
+        guesses: list[Late] = [
+            binding.guess for binding in rest if binding.value is None and binding.guess is not None
+        ]
+        types: set[str | None] = {binding.value or (binding.guess or (None,))[0] for binding in rest}
+        if first.at != (o.line, o.col) or first.value != _NONE or len(types) != 1:
+            continue
+        found: str | None = types.pop()
+        if found is None or _NONE in (members(found) or [found]):
+            continue
+        origins: frozenset[str] = frozenset[str]().union(*(rests for _, rests in guesses))
+        reason: str = f"`None`, then only `{found}`"
+        fix: Fix | None = scope.placed(
+            o.name,
+            Inference(f"{found} | None", reason, frozenset({_OPTIONAL}) | origins),
+            origins,
+            unsafe=bool(guesses),
+        )
+        scope.offences[index] = replace(o, edit=fix)
+        scope.inferred.late[o.name] = (f"{found} | None", origins)
+
+
+def rebinds(scope: Scope) -> None:
+    """Refit each first binding's fix to every value the name is bound to later (see `rebinding`).
+
+    A name something out of sight writes is left alone, and one bound again to a call on itself
+    whose type isn't known has no fix: a fifth of those guesses were wrong, on the packages measured.
+    Nor has one bound again to an empty display of another class (`flag = any(xs)`, then `flag = {}`),
+    or a loop's target bound again past the loop to a value whose type isn't known: another use of
+    the name, which the loop's values say nothing of.
+    """
+    index: int
+    o: Offence
+    plan: ImportPlan | None = scope.settings.known.names.plan
+    self_type: str | None = None if plan is None else spelled_self(plan)
+    for index, o in enumerate(scope.offences):
+        lifetime: Lifetime | None = scope.flow.get(o.name)
+        fix: Fix | None = o.edit
+        if o.code != CAN_BE_FINAL and fix is not None and lifetime is not None and FINAL_KIND in fix.kinds:
+            if len(lifetime.bindings) > 1:  # a constant's `Final` (see `_constant`): bound again, it's none
+                scope.offences[index] = replace(o, edit=None)
+            continue
+        # A widening's `Any` takes whatever the name is bound to later.
+        if (
+            o.code not in _DECLARING
+            or fix is None
+            or fix.kinds & WIDEN_KINDS
+            or lifetime is None
+            or lifetime.escaped
+        ):
+            continue
+        first: Binding
+        rest: list[Binding]
+        first, *rest = lifetime.bindings
+        if first.at != (o.line, o.col) or not rest:
+            continue
+        function: FunctionDef | None = scope.kind.function
+        if function is not None and any(
+            binding.value is None
+            and binding.guess is None
+            and (
+                binding.at in _converted(function)
+                or (fix.annotation in _NUMBERS and binding.at in _operated(function))
+                or _emptied(function).get(binding.at) not in {None, *_heads(fix.annotation)}
+            )
+            for binding in rest
+        ):
+            # Bound again to a call on itself, or a number by an operator with an operand, of a type
+            # that isn't known: a conversion, as often as not (`factor *= other`, a `Quantity` once
+            # `other` is one). A text or a container stays one by `+=`. Or to an empty display, whose
+            # class the fix doesn't name: a checker holds it to the fix's.
+            scope.offences[index] = replace(o, edit=None)
+            continue
+        if function is not None and any(
+            binding.value is None
+            and binding.guess is None
+            and (
+                _apart(function, first.at, binding.at)
+                or binding.at[0] > _looped(function).get(first.at, binding.at[0])
+            )
+            for binding in rest
+        ):
+            # Bound in one arm of an `if` to a known type, in another to one that isn't: a checker
+            # that knows the other's holds it to the first. Or a loop's target, past the loop.
+            scope.offences[index] = replace(o, edit=None)
+            continue
+        found: Refit | Fix | None = refit(
+            o,
+            fix,
+            rest,
+            scope.settings.hierarchy,
+            (self_type, _unites(scope, o.name)),
+        )
+        refitted: Fix | None = _offered(scope, found) if isinstance(found, Refit) else found
+        scope.offences[index] = replace(o, edit=refitted)
+
+
+def _offered(scope: Scope, found: Refit) -> Fix | None:
+    """Offer a refit fix, as the project's fix policy has it (see `offer`).
+
+    Returns:
+      The fix, or `None` if it isn't offered.
+
+    """
+    return scope.offer(found.found, found.origins, unsafe=found.unsafe, edit=found.edit, span=found.span)
+
+
+def extended(scope: Scope) -> None:
+    """Widen a display's fix to what its function adds to it later: `xs = [0]`, then `xs.append(0.5)`.
+
+    A display is typed by its elements, as a type checker types it; what's added later may be more.
+    Each added value's type joins the display's: numbers as the widest of them (`int` and `float`,
+    a `float`), any others as their union, a guess (`displays.JOINED`); an addition whose type isn't
+    known, or one a test around it narrows (see `_narrowed_addition`), leaves the name no fix. Not
+    where a nested scope sees it, out of this function's sight.
+    """
+    index: int
+    o: Offence
+    body: filling.Uses | None = None  # read once, for the first display to judge
+    for index, o in enumerate(scope.offences):
+        lifetime: Lifetime | None = scope.flow.get(o.name)
+        fix: Fix | None = o.edit
+        if o.code != UNANNOTATED or fix is None or _CONTAINER not in fix.kinds:
+            continue
+        parts: tuple[str, list[str]] | None = _contained(fix.annotation)
+        if parts is None or lifetime is None or lifetime.escaped or len(lifetime.bindings) != 1:
+            continue
+        body = body or filling.uses(scope.kind.body())
+        additions: list[filling.Fill] = filling.additions(body, o.name, parts[0])
+        if not additions or o.name in body.nested:
+            continue
+        rows: list[list[Inference | None]] = [
+            filling.added(fill, parts[0], scope.settings.known, scope.inferred.types) for fill in additions
+        ]
+        if any(part is None for row in rows for part in row) or any(
+            _narrowed_addition(scope, fill, row) for fill, row in zip(additions, rows, strict=True)
+        ):
+            scope.offences[index] = replace(o, edit=None)
+            continue
+        scope.offences[index] = replace(
+            o,
+            edit=_widened(scope, o.name, fix, parts, cast("list[list[Inference]]", rows)),
+        )
+
+
+def _narrowed_addition(scope: Scope, fill: filling.Fill, row: list[Inference | None]) -> bool:
+    """Check whether an addition is a read a test around it narrows: `d[k] = self.x` in `if self.x:`.
+
+    A checker adds the narrowed type (`str`, of a `str | None`), not the declared one `row` has.
+
+    Returns:
+      Whether its key or value is.
+
+    """
+    added: list[ast.expr] = [part for part in (fill.key, fill.value) if part is not None]
+    return not fill.spread and any(
+        narrowed_at(
+            scope.settings.facts.narrowed,
+            part,
+            part.lineno,
+            union=inferred is not None and len(members(inferred.annotation) or ()) > 1,
+        )
+        for part, inferred in zip(added, row, strict=False)
+    )
+
+
+def _widened(
+    scope: Scope,
+    name: str,
+    fix: Fix,
+    parts: tuple[str, list[str]],
+    rows: list[list[Inference]],
+) -> Fix | None:
+    """Widen a display's `fix` (split into `parts`) to what's added to it: `rows`, one per addition.
+
+    Returns:
+      The widened fix, `fix` itself if what's added doesn't widen it, or `None` where the types
+      can't be joined.
+
+    """
+    found: list[tuple[str, bool] | None] = [
+        _joined([own, *(row[at].annotation for row in rows)]) for at, own in enumerate(parts[1])
+    ]
+    if None in found:
+        return None
+    joins: list[tuple[str, bool]] = cast("list[tuple[str, bool]]", found)
+    annotation: str
+    if (annotation := f"{parts[0]}[{', '.join(text for text, _ in joins)}]") == fix.annotation:
+        return fix
+    union: bool = any(each for _, each in joins)
+    origins: frozenset[str] = frozenset({displays.JOINED}) if union else frozenset()
+    kinds: frozenset[str] = fix.kinds.union(origins, *(part.kinds for row in rows for part in row))
+    reason: str = f"its display, and what the function adds to it ({len(rows)})"
+    return scope.placed(name, Inference(annotation, reason, kinds), origins, unsafe=fix.unsafe or union)
+
+
+def _contained(annotation: str) -> tuple[str, list[str]] | None:
+    """Split a `list[T]`, `set[T]` or `dict[K, V]` into its container and its arguments.
+
+    Returns:
+      Them, or `None` for any other annotation.
+
+    """
+    node: ast.expr = ast.parse(annotation, mode="eval").body
+    kind: str
+    key: ast.expr
+    value: ast.expr
+    element: ast.expr
+    match node:
+        case ast.Subscript(value=ast.Name(id=kind), slice=ast.Tuple(elts=[key, value])) if kind == _DICT:
+            return kind, [ast.unparse(key), ast.unparse(value)]
+        case ast.Subscript(value=ast.Name(id=kind), slice=element) if kind in _FILLABLE - {_DICT}:
+            return kind, [ast.unparse(element)]
+        case _:
+            return None
+
+
+def _joined(types: Sequence[str]) -> tuple[str, bool] | None:
+    """Join a display's type for one argument with those of what's added there.
+
+    A union among them is its members: so `extended`, run again, keeps what it widened.
+
+    Returns:
+      The type, and whether it's a union of several; `None` where they can't be joined (see
+      `displays.union`).
+
+    """
+    distinct: list[str] = list(dict.fromkeys(member for each in types for member in each.split(_BAR)))
+    if len(distinct) == 1:
+        return distinct[0], False
+    if all(each in _NUMBERS for each in distinct):
+        return max(distinct, key=_NUMBERS.index), False
+    found: str | None = displays.union(distinct)
+    return None if found is None else (found, True)
+
+
+def fills(scope: Scope) -> None:
+    """Offer an empty container, bound nowhere else, the type of what its function adds to it.
+
+    A guess (see `constricter.fix.values.fills`), resting on `filled` for `unsafe-fix-select`. Not
+    where it's added a name its function tests (`isinstance(d, C)`, `d is None`, `if d`): a checker
+    takes the narrowed type for the elements'.
+    """
+    index: int
+    o: Offence
+    body: filling.Uses | None = None  # read once, for the first container to judge
+    for index, o in enumerate(scope.offences):
+        lifetime: Lifetime | None = scope.flow.get(o.name)
+        kind: str | None = scope.assignments.empty.get(o.name)
+        if o.code != UNANNOTATED or _fixed(o) or kind is None:
+            continue
+        if lifetime is None or lifetime.escaped or len(lifetime.bindings) != 1:
+            continue
+        body = body or filling.uses(scope.kind.body())
+        function: FunctionDef | None = scope.kind.function
+        if function is not None and filling.added_names(body, o.name, kind) & narrowing(function):
+            continue  # what's added is narrowed where it's added
+        found: Inference | None
+        if (
+            found := filling.filled(
+                body,
+                o.name,
+                kind,
+                scope.settings.known,
+                scope.inferred.types,
+            )
+        ) is None:
+            continue
+        fix: Fix | None = scope.placed(o.name, found, frozenset({_FILLED}), unsafe=True)
+        scope.offences[index] = replace(o, edit=fix)
+        # What the scope infers from it (its `return`s) knows its type, a guess.
+        scope.inferred.late[o.name] = (found.annotation, frozenset({_FILLED}))
+
+
+def lambdas(scope: Scope) -> None:
+    """Offer a lambda bound once to a name, whose body rests on its parameters, a `Callable[..., R]`.
+
+    By what every call of it in its function passes them (see `callables.called`): a guess, resting
+    on `callers`. Not where a call passes a local bound more than once, whose type there isn't known.
+    """
+    function: FunctionDef | None = scope.kind.function
+    index: int
+    o: Offence
+    body: filling.Uses | None = None  # read once, for the first lambda to judge
+    for index, o in enumerate(scope.offences):
+        bound: Plain | None = scope.assignments.plain.get(o.name)
+        lifetime: Lifetime | None = scope.flow.get(o.name)
+        if function is None or _fixed(o) or bound is None or not isinstance(bound[1], ast.Lambda):
+            continue
+        if lifetime is None or lifetime.escaped or len(lifetime.bindings) != 1:
+            continue
+        body = body or filling.uses(function.body)
+        found: tuple[Inference, list[ast.expr]] | None = callables.called(
+            bound[1],
+            o.name,
+            body,
+            scope.settings.known,
+            scope.inferred.types,
+        )
+        if found is None or any(
+            isinstance(node, ast.Name) and len(scope.lifetime(node.id).bindings) > 1
+            for arg in found[1]
+            for node in ast.walk(arg)
+        ):
+            continue
+        origins: frozenset[str] = frozenset({_CALLERS}) | guesses_in(scope, found[1])[1]
+        scope.offences[index] = replace(o, edit=scope.placed(o.name, found[0], origins, unsafe=True))
+        scope.inferred.late[o.name] = (found[0].annotation, origins)
+
+
+def widens(scope: Scope, tree: ast.Module) -> None:
+    """Offer a wider type to each name's first binding that still has no fix, where `fix-widen` asks.
+
+    A type vaguer than `vague` allows, written anyway (`vague`: a guess); `Any` for the elements
+    of an empty container nothing fills, or of a display of mixed or unknown ones (see
+    `widened.container`); `Any` for a call of no known type (see `widened.called`), whatever the
+    name is bound to later. A plain assignment's is marked where its statement ends; a loop's, an
+    unpacking's or a `with`'s name, typed vaguely or taken of such a call, is declared before its
+    statement.
+    """
+    widen: frozenset[str] = scope.settings.checks.fixes.widen
+    plan: ImportPlan | None = scope.settings.known.names.plan
+    if not widen & _LATE_WIDENINGS or plan is None or not scope.kind.fixable:
+        return
+    index: int
+    o: Offence
+    for index, o in enumerate(scope.offences):
+        bound: Plain | None = scope.assignments.plain.get(o.name)
+        lifetime: Lifetime | None = scope.flow.get(o.name)
+        if o.edit is not None or bound is None or at(bound[0]) != (o.line, o.col):
+            continue
+        if lifetime is None or lifetime.escaped:  # written out of sight
+            continue
+        known: Inference | None = bound[2]
+        found: Inference | None = None
+        fix: Fix | None
+        # Bound again, it may be anything else: a wider type that isn't `Any` could be wrong.
+        once: bool = len(lifetime.bindings) == 1
+        # What's declared before its statement isn't its value, but taken from it: no container's.
+        whole: bool = once and o.name not in scope.assignments.chained
+        if once and known is not None and VAGUE_KIND in widen and not scope.writable(known):
+            found = known._replace(kinds=known.kinds | {VAGUE_KIND})
+            fix = scope.placed(o.name, found, frozenset({VAGUE_KIND}), unsafe=True)
+        else:
+            if known is None:
+                found = (widened.container(bound[1], plan, widen) if whole else None) or widened.called(
+                    bound[1],
+                    widened.Caller(
+                        scope.settings.owners.get(id(scope.kind.function)),
+                        scope.declared,
+                        scope.settings.facts.untyped,
+                    ),
+                    widened.own(tree),
+                    plan,
+                    widen,
+                )
+            fix = None if found is None else scope.placed(o.name, found, frozenset(), unsafe=False)
+        if fix is not None:
+            scope.offences[index] = replace(o, edit=fix._replace(mark=bound[1].end_lineno or o.line))
+
+
+def shadowed(scope: Scope) -> None:
+    """Drop each fix whose annotation names a value its scope binds, which the name then is there.
+
+    In a function, a parameter or a local (`text: str = ""` under a parameter `str`); in any scope,
+    the name the fix annotates (`Row: type[Row] = load()`). A module body's other names may be types.
+    """
+    function: FunctionDef | None = scope.kind.function
+    values: frozenset[str] = frozenset(
+        () if function is None else (*scope.first, *_parameters(function.args)),
+    )
+    index: int
+    o: Offence
+    for index, o in enumerate(scope.offences):
+        if o.edit is not None and roots(o.edit.annotation) & (values | {o.name}):
+            scope.offences[index] = replace(o, edit=None)
+
+
+def excusing(lines: Sequence[str]) -> tuple[int, ...]:
+    """Find the lines a comment excuses to a type checker (`# type: ignore`), once for a module's scopes.
+
+    Returns:
+      Where each is, from 0, in order.
+
+    """
+    return tuple(index for index, line in enumerate(lines) if _IGNORE.search(line))
+
+
+def excused(scope: Scope) -> None:
+    """Drop each fix of a name a line of its function excuses to a type checker (`# type: ignore`).
+
+    `return text  # type: ignore[no-any-return]`: with `text` declared the line has nothing to
+    excuse, and a checker told to report unused comments reports that one. A module's or a class
+    body's name, by any line of the file: it's read everywhere.
+    """
+    on: tuple[int, ...]
+    if not (on := scope.settings.facts.excused):  # most modules: none of its lines is
+        return
+    function: FunctionDef | None = scope.kind.function
+    lines: Sequence[str] = scope.settings.lines
+    first: int = 0 if function is None else bisect.bisect_left(on, function.lineno - 1)
+    last: int = len(on) if function is None else bisect.bisect_left(on, function.end_lineno or len(lines))
+    excused_code: list[str]
+    if not (excused_code := [lines[line].partition("#")[0] for line in on[first:last]]):
+        return
+    index: int
+    o: Offence
+    for index, o in enumerate(scope.offences):
+        if o.edit is not None and any(o.name in _WORD.findall(code) for code in excused_code):
+            scope.offences[index] = replace(o, edit=None)
+
+
+def unchecked(scope: Scope, tree: ast.Module) -> None:
+    """Drop each guess that makes an error of what its function does with the name (see `misused`).
+
+    By an unannotated function's `return`s or a hint, which a checker held to nothing: a union,
+    bound once, of which an attribute or an item is taken where no test narrows it; a class of
+    the module's of which an attribute it hasn't is taken; and a name compared, formatted or stored
+    as its type doesn't allow. A certain fix too: a guess is one once a first pass has declared
+    what it rested on.
+    """
+    function: FunctionDef | None
+    if (function := scope.kind.function) is None:
+        return
+    index: int
+    o: Offence
+    for index, o in enumerate(scope.offences):
+        fix: Fix | None = o.edit
+        if fix is None or not fix.kinds & _UNCHECKED:
+            continue
+        lifetime: Lifetime | None = scope.flow.get(o.name)
+        union: frozenset[str] = members(fix.annotation) or frozenset()
+        once: bool = lifetime is not None and len(lifetime.bindings) == 1
+        if (
+            misused.lacks(tree, function, o.name, fix.annotation)
+            or misused.misused(function, o.name, fix.annotation)
+            or (
+                once
+                and len(union) > 1
+                and misused.unnarrowed(function, o.name, scope.settings.facts.narrowed)
+            )
+        ):
+            scope.offences[index] = replace(o, edit=None)
+
+
+def _parameters(args: ast.arguments) -> Iterator[str]:
+    """Name a function's parameters, `*args` and `**kwargs` too.
+
+    Yields:
+      Each.
+
+    """
+    arg: ast.arg | None
+    for arg in (*args.posonlyargs, *args.args, *args.kwonlyargs, args.vararg, args.kwarg):
+        if arg is not None:
+            yield arg.arg
+
+
+def finals(scope: Scope) -> list[Offence]:
+    """Find the names that could be `Final` (LVA012); run after `value_flow`, which marks escapes.
+
+    Returns:
+      An offence for each name bound exactly once, by a plain assignment outside any loop, and not
+      declared apart from it or already `Final`, nor written from another scope; with a fix
+      (see `_final`) where one is offered.
+
+    """
+    found: list[Offence] = []
+    plan: ImportPlan | None = scope.settings.known.names.plan
+    # What else the module calls `Final`: `from typing import Final as F`.
+    aliases: frozenset[str] = frozenset(
+        () if plan is None else (name for name, origin in plan.bound.items() if origin in _FINALS),
+    )
+    name: str
+    lifetime: Lifetime
+    for name, lifetime in scope.flow.items():
+        if (
+            name == _DISCARD
+            or lifetime.escaped
+            or scope.kind.unannotated == UNANNOTATED_MEMBER
+            or len(lifetime.bindings) != 1
+        ):
+            continue
+        where: tuple[int, int] = lifetime.bindings[0].at
+        if scope.assignments.found.get(name) == [(where, False)] and (
+            lifetime.declared is None
+            or (lifetime.declared_at == where and not is_final(lifetime.declared, aliases))
+        ):
+            found.append(Offence(*where, name, CAN_BE_FINAL, _final(scope, name, lifetime)))
+    return [scope.evaluated(o) for o in found]
+
+
+def _final(scope: Scope, name: str, lifetime: Lifetime) -> Fix | None:
+    """Offer LVA012's `Final`: around the annotation there (`Final[int]`), or as one (`: Final`).
+
+    An unannotated name LVA001 would annotate gets `Final[T]` with LVA001's type instead, and
+    LVA001's own fix is dropped: both write where the name is bound, and this one does for both.
+
+    Returns:
+      The fix, or `None` where the scope isn't fixed, the `final` kind isn't selected, an
+      annotation spans lines, or the module can't name `Final`.
+
+    """
+    plan: ImportPlan | None = scope.settings.known.names.plan
+    spelled: str | None = None if plan is None else plan.spell(_TYPING_FINAL)
+    kinds: frozenset[str] = frozenset({FINAL_KIND})
+    if (
+        plan is None
+        or spelled is None
+        or not scope.kind.fixable
+        or not scope.settings.checks.fixes.allows(kinds)
+    ):
+        return None
+    reason: str = "bound once, and never rebound"
+    if lifetime.declared is not None:
+        if lifetime.declared_span is None:
+            return None
+        line: int = lifetime.declared_at[0]
+        start: int
+        end: int
+        start, end = lifetime.declared_span
+        text: str = scope.settings.lines[line - 1].encode()[start:end].decode()
+        return _final_fix(
+            Fix(f"{spelled}[{text}]", reason, edit=Edit.REPLACE, span=(start, end), kinds=kinds),
+            plan,
+        )
+    index: int
+    o: Offence
+    for index, o in enumerate(scope.offences):
+        if o.name == name and o.code == UNANNOTATED and o.edit is not None and o.edit.edit == Edit.ANNOTATE:
+            scope.offences[index] = replace(o, edit=None)
+            return _final_fix(
+                o.edit._replace(annotation=f"{spelled}[{o.edit.annotation}]", kinds=o.edit.kinds | kinds),
+                plan,
+            )
+    return _final_fix(Fix(spelled, reason, kinds=kinds), plan)
+
+
+def is_final(annotation: str, aliases: frozenset[str] = _NO_ALIASES) -> bool:
+    """Check whether an annotation is `Final` (`Final[T]`, `typing.Final`, ...), or one of `aliases` for it.
+
+    Returns:
+      Whether it is.
+
+    """
+    # `annotation` is always `ast.unparse`'s own output, so it's always valid Python to parse back.
+    root: ast.expr = ast.parse(annotation, mode="eval").body
+    return node_name(root.value if isinstance(root, ast.Subscript) else root) in aliases | {_FINAL}
+
+
+def _final_fix(fix: Fix, plan: ImportPlan) -> Fix:
+    """Give a `Final` fix the imports its annotation needs.
+
+    Returns:
+      It, with them.
+
+    """
+    return fix._replace(imports=imports_of(fix.annotation, plan), after=plan.after)
+
+
+def _unites(scope: Scope, name: str) -> bool:
+    """Check whether `name`'s values of several types may be declared their union (`fix-widen`'s `unions`).
+
+    Returns:
+      Whether they may: where it's asked for, in a function, of a name it doesn't change in place
+      (`name += more`, which no union of its types need take).
+
+    """
+    function: FunctionDef | None = scope.kind.function
+    return (
+        UNIONS in scope.settings.checks.fixes.widen
+        and function is not None
+        and name not in _augmented(function)
+    )
+
+
+@lru_cache(maxsize=64)  # asked of each of a function's names bound again
+def _augmented(function: FunctionDef) -> frozenset[str]:
+    """Name what a function changes in place: `name += more`.
+
+    Returns:
+      Each such name.
+
+    """
+    return frozenset(
+        node.target.id
+        for node in ast.walk(function)
+        if isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name)
+    )
+
+
+@lru_cache(maxsize=1024)  # asked of each of a function's names bound again
+def _converted(function: FunctionDef) -> frozenset[tuple[int, int]]:
+    """Find where a function binds a name to a call on the name itself.
+
+    One that takes it (`item = proper(item)`) or is its method (`match = match.groupdict()`), alone
+    or as an operand of `or` or of a conditional expression (`code = table.get(code) or SYNTAX`).
+
+    Returns:
+      Where each such name is bound.
+
+    """
+    found: set[tuple[int, int]] = set()
+    node: ast.AST
+    target: ast.expr
+    for node in ast.walk(function):
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and _on_itself(target.id, node.value):
+                    found.add(at(target))
+    return frozenset(found)
+
+
+def _on_itself(name: str, value: ast.expr) -> bool:
+    """Check whether `value` is a call on `name` (see `_converted`), or an operand of one is.
+
+    Returns:
+      Whether it is.
+
+    """
+    values: list[ast.expr]
+    body: ast.expr
+    orelse: ast.expr
+    func: ast.expr
+    args: list[ast.expr]
+    keywords: list[ast.keyword]
+    match value:
+        case ast.BoolOp(values=values):
+            return any(_on_itself(name, each) for each in values)
+        case ast.IfExp(body=body, orelse=orelse):
+            return _on_itself(name, body) or _on_itself(name, orelse)
+        case ast.Call(func=func, args=args, keywords=keywords):
+            return any(
+                isinstance(each, ast.Name) and each.id == name
+                for each in (_base(func), *args, *(keyword.value for keyword in keywords))
+            )
+        case _:
+            return False
+
+
+def _base(node: ast.expr) -> ast.expr:
+    """Find what a chain of attributes is read from: `self` in `self.table.get`.
+
+    Returns:
+      It; `node` itself, if it isn't an attribute.
+
+    """
+    return _base(node.value) if isinstance(node, ast.Attribute) else node
+
+
+# The classes whose call with no arguments is an empty display.
+_EMPTY: Final = frozenset({"dict", "list", "set", "tuple"})
+
+
+@lru_cache(maxsize=1024)  # asked of each of a function's names bound again
+def _emptied(function: FunctionDef) -> Mapping[tuple[int, int], str]:
+    """Find where a function binds a name to an empty display: `{}`, `[]`, `()` or `set()`, `dict()`.
+
+    Returns:
+      Where each such name is bound, and the display's class.
+
+    """
+    found: dict[tuple[int, int], str] = {}
+    node: ast.AST
+    target: ast.expr
+    kind: str | None
+    for node in ast.walk(function):
+        if isinstance(node, ast.Assign) and (kind := _empty(node.value)) is not None:
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    found[at(target)] = kind
+    return found
+
+
+def _empty(value: ast.expr) -> str | None:
+    """Name the class of an empty display, or of a call of its class with no arguments.
+
+    Returns:
+      It, or `None` for any other value.
+
+    """
+    name: str
+    match value:
+        case ast.Dict(keys=[]):
+            return "dict"
+        case ast.List(elts=[]):
+            return "list"
+        case ast.Tuple(elts=[]):
+            return "tuple"
+        case ast.Call(func=ast.Name(id=name), args=[], keywords=[]) if name in _EMPTY:
+            return name
+        case _:
+            return None
+
+
+def _heads(annotation: str) -> frozenset[str]:
+    """Name the classes of an annotation's union's members: `dict` for `dict[str, int] | None`.
+
+    Returns:
+      Them; none, if it can't be read.
+
+    """
+    return frozenset(member.split("[", 1)[0] for member in members(annotation) or ())
+
+
+@lru_cache(maxsize=1024)  # asked of each of a function's names bound again
+def _operated(function: FunctionDef) -> frozenset[tuple[int, int]]:
+    """Find where a function binds a name by an augmented assignment: `factor *= other`.
+
+    Returns:
+      Where each such name is bound.
+
+    """
+    node: ast.AST
+    target: ast.Name
+    found: set[tuple[int, int]] = set()
+    for node in ast.walk(function):
+        match node:
+            case ast.AugAssign(target=ast.Name() as target):
+                found.add(at(target))
+            case _:
+                pass
+    return frozenset(found)
+
+
+@lru_cache(maxsize=1024)  # asked of each of a function's names bound again
+def _looped(function: FunctionDef) -> Mapping[tuple[int, int], int]:
+    """Find a function's loops' targets: `for name in names`, `for key, value in pairs`.
+
+    Returns:
+      Where each target name is bound, and its loop's last line.
+
+    """
+    found: dict[tuple[int, int], int] = {}
+    node: ast.AST
+    target: ast.AST
+    for node in ast.walk(function):
+        if isinstance(node, ast.For | ast.AsyncFor):
+            for target in ast.walk(node.target):
+                if isinstance(target, ast.Name):
+                    found[at(target)] = node.end_lineno or node.lineno
+    return found
+
+
+def _apart(function: FunctionDef, first: tuple[int, int], later: tuple[int, int]) -> bool:
+    """Check whether two bindings of a function's are in different arms of one statement.
+
+    Returns:
+      Whether they are: only one of them runs.
+
+    """
+    arms: Mapping[tuple[int, int], _Arms] = _arms(function)
+    taken: dict[int, int] = dict(arms.get(first, ()))
+    return any(taken.get(branch, arm) != arm for branch, arm in arms.get(later, ()))
+
+
+@lru_cache(maxsize=64)  # asked of each of a function's names bound again
+def _arms(function: FunctionDef) -> Mapping[tuple[int, int], _Arms]:
+    """Find, for each name a function's branches bind, the arms its binding is in.
+
+    An `if`'s body and its `else`, a `try`'s body and each handler, a `match`'s cases.
+
+    Returns:
+      Where each such name is bound, and each branching statement around it (by `id()`) with which
+      of its arms that's in.
+
+    """
+    found: dict[tuple[int, int], _Arms] = {}
+    # Each statement still to read, and the arms it's in; `None` ends it.
+    waiting: list[tuple[ast.stmt, _Arms] | None] = [
+        None,
+        *((stmt, ()) for stmt in function.body),
+    ]
+    stmt: ast.stmt
+    inside: _Arms
+    for stmt, inside in iter(waiting.pop, None):
+        if isinstance(stmt, (*_INNER, ast.ClassDef)):
+            continue
+        if inside:
+            found.update(
+                (at(name), inside)
+                for target in _targets(stmt)
+                for name in ast.walk(target)
+                if isinstance(name, ast.Name)
+            )
+        blocks: list[list[ast.stmt]] = _blocks(stmt)
+        arm: int
+        block: list[ast.stmt]
+        for arm, block in enumerate(blocks):
+            within: tuple[tuple[int, int], ...] = (
+                (*inside, (id(stmt), arm)) if _alternatives(stmt) else inside
+            )
+            waiting.extend([(child, within) for child in block])
+    return found
+
+
+def _alternatives(stmt: ast.stmt) -> bool:  # whether only one of its blocks runs, of those `_blocks` lists
+    return isinstance(stmt, ast.If | ast.Match | ast.Try | ast.TryStar)
+
+
+def _targets(stmt: ast.stmt) -> list[ast.expr]:  # what a statement assigns to
+    match stmt:
+        case ast.Assign():
+            return stmt.targets
+        case ast.AnnAssign() | ast.AugAssign():
+            return [stmt.target]
+        case _:
+            return []
+
+
+def _blocks(stmt: ast.stmt) -> list[list[ast.stmt]]:
+    """List a statement's blocks, those of which only one runs each as an arm.
+
+    Returns:
+      An `if`'s body and its `else`, a `try`'s body (with its `else`) and each handler's, a
+      `match`'s cases; any other statement's blocks.
+
+    """
+    match stmt:
+        case ast.If():
+            return [stmt.body, stmt.orelse]
+        case ast.Try() | ast.TryStar():
+            return [[*stmt.body, *stmt.orelse], *(handler.body for handler in stmt.handlers), stmt.finalbody]
+        case ast.Match():
+            return [case.body for case in stmt.cases]
+        case ast.For() | ast.AsyncFor() | ast.While():
+            return [stmt.body, stmt.orelse]
+        case ast.With() | ast.AsyncWith():
+            return [stmt.body]
+        case _:
+            return []
+
+
+@lru_cache(maxsize=1024)  # a function is finished twice: as it's checked, and with its module
+def _enclosed_reads(function: FunctionDef) -> frozenset[str]:
+    """Name what the functions and lambdas inside a function's body read.
+
+    Returns:
+      Each name read in one, however deep.
+
+    """
+    found: set[str] = set()
+    # Each node of the body, and whether it's inside a function or lambda there; `None` ends it.
+    waiting: list[tuple[ast.AST, bool] | None] = [None, *((stmt, False) for stmt in function.body)]
+    node: ast.AST
+    inside: bool
+    for node, inside in iter(waiting.pop, None):
+        if inside and isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+            found.add(node.id)
+        within: bool = inside or isinstance(node, _INNER)
+        waiting.extend([(child, within) for child in children(node)])
+    return frozenset(found)
+
+
+def _fixed(offence: Offence) -> bool:
+    """Check whether an offence already has a fix a late one (`optionals`, `fills`) mustn't replace.
+
+    Returns:
+      Whether it has one, other than a hint's (`--infer-with`, `--infer-from`), which one would.
+
+    """
+    return offence.edit is not None and not hinted.KINDS & offence.edit.kinds