python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/jsonc.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+"""JSON with comments (`//`, `/* */`) and trailing commas, for the files constricter reads.
+
+Comments and trailing commas become spaces (newlines kept), so every position the JSON parser reports
+is still the original file's. What constricter writes stays plain JSON.
+"""
+
+import json
+import re
+from typing import TypeGuard, cast
+
+# A string (left alone), or a comment.
+_COMMENT: re.Pattern[str] = re.compile(r'"(?:\\.|[^"\\])*"|//[^\n]*|/\*.*?\*/', re.DOTALL)
+# A string (left alone), or a comma with only whitespace before the `]` or `}` it trails.
+_TRAILING: re.Pattern[str] = re.compile(r'"(?:\\.|[^"\\])*"|,(?=\s*[\]}])')
+
+
+def _blank(match: re.Match[str]) -> str:
+    text: str = match.group()
+    return text if text.startswith('"') else re.sub(r"[^\n]", " ", text)
+
+
+def as_text(value: str | bytes) -> str:
+    """Decode `value` if it's bytes.
+
+    Returns:
+      It, as text.
+
+    """
+    return value.decode("utf-8") if isinstance(value, bytes) else value
+
+
+def is_int(value: object) -> TypeGuard[int]:
+    """Check whether `value` is a plain whole number, not a `bool` (a `bool` is an `int` in Python).
+
+    Returns:
+      Whether it is.
+
+    """
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def loads(text: str | bytes) -> object:
+    """Parse JSON that may have comments and trailing commas.
+
+    Returns:
+      The value. Raises `ValueError` as `json.loads` does.
+
+    """
+    return cast("object", json.loads(_TRAILING.sub(_blank, _COMMENT.sub(_blank, as_text(text)))))

constricter/noqa.py

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+"""`# noqa` comments, read the same way by the CLI and the pylint plugin (flake8 reads its own)."""
+
+import io
+import re
+from collections.abc import Sequence
+
+from constricter.offences import Offence
+
+_NOQA: re.Pattern[str] = re.compile(
+    r"#\s*noqa(?::\s*(?P<codes>[A-Z]+[0-9]+(?:[,\s]+[A-Z]+[0-9]+)*))?",
+    re.IGNORECASE,
+)
+
+
+def lines(text: str) -> list[str]:
+    """Split `text` into lines as Python does (LF, CRLF or CR).
+
+    Returns:
+      The lines, each keeping its ending.
+
+    """
+    return io.StringIO(text, newline="").readlines()
+
+
+def suppressed(line: str, code: str) -> bool:
+    """Check `line` for a `# noqa` covering `code`: a bare one, or one naming it.
+
+    Returns:
+      Whether it has one.
+
+    """
+    match_: re.Match[str] | None
+    if (match_ := _NOQA.search(line)) is None:
+        return False
+    codes: str | None = match_.group("codes")
+    return codes is None or code in re.split(r"[,\s]+", codes.upper())
+
+
+def unsuppressed(offences: Sequence[Offence], source: Sequence[str]) -> list[Offence]:
+    """Apply the `# noqa` comments in `source`'s lines.
+
+    Returns:
+      The offences none on their line suppresses.
+
+    """
+    return [o for o in offences if not (o.line <= len(source) and suppressed(source[o.line - 1], o.code))]

constricter/notebook.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+"""Jupyter notebooks: their code cells, joined into one module, and where each line came from."""
+
+import json
+import re
+from collections.abc import Sequence
+from typing import Final, NamedTuple, TypeAlias, cast
+
+from constricter import jsonc
+from constricter.fix.core import fixes
+from constricter.offences import Offence
+
+SUFFIX: Final = ".ipynb"
+_Json: TypeAlias = "str | int | float | bool | list[_Json] | dict[str, _Json] | None"
+_CODE: Final = "code"  # a code cell's `cell_type`
+_SOURCE: Final = "source"  # its lines
+# IPython syntax that isn't Python: line magics, shell escapes (`!ls`), and help (`obj?`, `?obj`).
+_MAGIC: re.Pattern[str] = re.compile(r"\s*([%!?]|[\w.]+\?{1,2}\s*$)")
+
+
+class Line(NamedTuple):
+    """Where a line of the joined module is in the notebook: its cell (from 1) and line in it."""
+
+    cell: int
+    line: int
+
+
+class Cell(NamedTuple):
+    """A cell `fix` changed: its number (from 1), and its lines before and after."""
+
+    number: int
+    old: list[str]
+    new: list[str]
+
+
+def _text(source: _Json) -> str:
+    """Join a cell's source, which a notebook keeps as a string or a list of lines.
+
+    Returns:
+      The source, as one string.
+
+    """
+    return "".join(str(part) for part in source) if isinstance(source, list) else str(source)
+
+
+def _cell_lines(source: _Json) -> list[str]:
+    """Split a cell into lines; IPython-only lines become blank.
+
+    Returns:
+      The lines, each ending in a newline.
+
+    """
+    lines: list[str] = _text(source).splitlines()
+    if lines and lines[0].lstrip().startswith("%%"):  # a cell magic: the whole cell isn't Python
+        return ["\n"] * len(lines)
+    return ["\n" if _MAGIC.match(line) else f"{line}\n" for line in lines]
+
+
+def parse(raw: str, name: str) -> tuple[str, list[Line]]:
+    """Return notebook JSON's code cells as one module, and where each of its lines came from.
+
+    Returns:
+      The module's source, and a `Line` for each of its lines.
+
+    Raises:
+      ValueError: It isn't a notebook (JSON with a `cells` list).
+
+    """
+    document: _Json = cast("_Json", jsonc.loads(raw))
+    cells: list[_Json]
+    match document:
+        case {"cells": list() as cells}:
+            pass
+        case _:
+            message: str = f"{name}: not a Jupyter notebook"
+            raise ValueError(message)
+    joined: list[str] = []
+    where: list[Line] = []
+    number: int
+    cell: _Json
+    for number, cell in enumerate(cells, start=1):
+        if isinstance(cell, dict) and cell.get("cell_type") == _CODE and _SOURCE in cell:
+            lines: list[str] = _cell_lines(cell[_SOURCE])
+            joined += lines
+            where += [Line(number, line) for line in range(1, len(lines) + 1)]
+    return "".join(joined), where
+
+
+def fix(raw: str, offences: Sequence[Offence]) -> tuple[str, list[Cell]]:
+    """Add each fixable offence's annotation in its cell of the notebook JSON `raw`.
+
+    Returns:
+      The notebook's new JSON (its indent, key order and final newline kept), and each changed
+      cell's number and old and new lines.
+
+    """
+    document: dict[str, _Json] = cast("dict[str, _Json]", jsonc.loads(raw))
+    cells: list[_Json] = cast("list[_Json]", document["cells"])
+    by_cell: dict[int, list[Offence]] = {}
+    o: Offence
+    for o in offences:
+        if o.edit is not None and o.cell is not None:
+            by_cell.setdefault(o.cell, []).append(o)
+    changed: list[Cell] = []
+    number: int
+    for number in sorted(by_cell):
+        cell: dict[str, _Json] = cast("dict[str, _Json]", cells[number - 1])
+        source: _Json = cell["source"]
+        old: list[str] = _text(source).splitlines(keepends=True)
+        new: list[str] = fixes.apply(old, by_cell[number])
+        cell["source"] = list[_Json](new) if isinstance(source, list) else "".join(new)
+        changed.append(Cell(number, old, new))
+    indent: re.Match[str] | None = re.match(r"\{\r?\n( +)", raw)
+    text: str = json.dumps(document, indent=len(indent.group(1)) if indent else 1, ensure_ascii=False)
+    return text + ("\n" if raw.endswith("\n") else ""), changed

constricter/offences.py

@@ -0,0 +1,436 @@
+# SPDX-License-Identifier: MIT
+"""The codes, their messages and levels, and the `Offence` and `Checks` types every module shares."""
+
+import ast
+from dataclasses import dataclass, field
+from enum import IntEnum, StrEnum
+from typing import Final, NamedTuple
+
+from constricter.rules.flow import Narrower
+
+UNANNOTATED: Final = "LVA001"
+UNTYPED_TARGET: Final = "LVA002"
+COMMENT_TYPED_TARGET: Final = "LVA003"
+UNANNOTATED_MEMBER: Final = "LVA004"
+VAGUE_TYPE: Final = "LVA005"
+NESTED_TYPE: Final = "LVA006"
+REDUNDANT_TYPE: Final = "LVA007"
+NARROWABLE_TYPE: Final = "LVA008"
+MISMATCHED_TYPE: Final = "LVA009"
+UNUSED_UNION_MEMBER: Final = "LVA010"
+LONG_TUPLE: Final = "LVA011"
+CAN_BE_FINAL: Final = "LVA012"
+MESSAGES: dict[str, str] = {
+    UNANNOTATED: "local variable {name} is not annotated where it's first bound",
+    UNTYPED_TARGET: "for/match variable {name} is untyped; declare it before the statement",
+    COMMENT_TYPED_TARGET: "for variable {name} is typed only by a type comment; declare it before the loop",
+    UNANNOTATED_MEMBER: "module or class variable {name} is not annotated where it's first bound",
+    VAGUE_TYPE: "the annotation of {name} is vague: Any, object, or a generic without its parameters",
+    NESTED_TYPE: "the annotation of {name} nests too deeply; name a part of it with a `type` alias",
+    REDUNDANT_TYPE: "{name} is annotated again with the type it already has, in the same block",
+    NARROWABLE_TYPE: "{name} only ever holds `{detail}`; its annotation could narrow to that",
+    MISMATCHED_TYPE: "{name} is bound to `{detail}` here, which doesn't fit its annotation",
+    UNUSED_UNION_MEMBER: "{name}'s annotation allows `{detail}`, which no value it's bound to ever is",
+    LONG_TUPLE: "the annotation of {name} lists a tuple of {detail} elements; name them (a NamedTuple)",
+    CAN_BE_FINAL: "{name} is bound once and never rebound; it could be `Final`",
+}
+# Codes reported only when selected by their full code (`--select LVA012`), never by a prefix.
+OPT_IN: Final = frozenset({CAN_BE_FINAL})
+# Each way `--fix` can decide an annotation, by its stable id (`--show-fixes`, `fix-select`).
+FIX_KINDS: dict[str, str] = {
+    "literal": "a literal, an f-string, `not x`, or `x in y` or `x is y`",
+    "container": "a list, set, tuple or dict display whose elements' types agree",
+    "joined": "a list, set or dict display whose elements' types differ, as their union (a guess)",
+    "copy": "a copy of a local whose type is known",
+    "subscript": "a subscript of a known container",
+    "attribute": "an attribute of a class the module defines",
+    "method": "a method with a fixed or declared return type, on a known local",
+    "builtin": "a builtin with a fixed return type (`len`, `str`, ...)",
+    "call": "a function that declares its return type (this module's, or another checked file's)",
+    "constructor": "a call to a capitalised name, taken to construct one (a guess)",
+    "conditional": "both sides of `a if c else b`, or one side and `None`",
+    "boolean": "`a or b` or `a and b`, its operands of one type",
+    "arithmetic": "arithmetic on builtin scalars",
+    "compare": "a comparison of builtin values (`n < 3`), always a `bool`",
+    "comprehension": "a list, set or dict comprehension's elements",
+    "builder": "`sorted`, `list`, `set`, `frozenset` or `tuple` of known elements",
+    "await": "`await` of a checked file's `async def`, a function or a method",
+    "cast": "`typing.cast(T, x)`: its `T`",
+    "stdlib": "a standard-library function with a builtin result or class (`time.time`, `uuid4`)",
+    "optional": "`x = None`, then only ever a value of one known type `T`: `T | None`",
+    "rebound": "a name later bound to a wider type: the type every value fits (`int`, then `float`)",
+    "filled": "an empty container, then only what the function adds to it (a guess)",
+    "returned": "an unannotated function's own `return`s (a method's: a guess)",
+    "assigned": "an unannotated instance attribute's every `self.x = value` in its class (a guess)",
+    "callers": "an unannotated parameter every call in the checked files passes one type (a guess)",
+    "member": "a plain class's variable, by its value in the class's body (a guess)",
+    "fixture": "a test's parameter, by its pytest fixture's value or its `parametrize` literals (a guess)",
+    "alias": "a module's type alias, a subscript or a union of types: `TypeAlias`",
+    "callable": "a function or a bound method bound to a name, by what its call gives",
+    "final": "LVA012's `Final`: around its annotation, or with LVA001's type (`Final[int]`)",
+    "checker": "a type checker's inferred type, from its inlay hints (`--infer-with`; a guess)",
+    "traced": "what a traced run bound the name to (`--infer-from`; a guess)",
+    "open": "`open(path, mode)`'s file object, by its literal mode (`io.TextIOWrapper`, ...)",
+    "loop": "what a loop (or `sorted`, `list`, ...) iterates over",
+    "unpack": "an unpacking, split over its names",
+    "narrow": "LVA008's or LVA010's narrower annotation (a guess)",
+    "comment": "LVA003: the loop's own `# type:` comment, as a declaration",
+    "redundant": "LVA007: the repeated annotation, dropped",
+    "untyped-parameters": "what comes of a parameter no annotation types: `Any`, marked (`fix-widen`)",
+    "unions": "a name bound to values of two or three types: their union, marked (`fix-widen`; a guess)",
+    "vague": "a type vaguer than `vague` allows, written anyway, marked (`fix-widen`; a guess)",
+    "empty-containers": "an empty container nothing in sight fills: `list[Any]`, marked (`fix-widen`)",
+    "mixed-containers": "a display of mixed or unknown elements: `list[Any]`, marked (`fix-widen`)",
+    "untyped-calls": "a call of a checked file's function declaring no return: `Any`, marked (`fix-widen`)",
+    "unknown-calls": "any other call of no known type: `Any`, marked (`fix-widen`)",
+}
+UNTYPED_PARAMETERS: Final = "untyped-parameters"
+UNIONS: Final = "unions"
+VAGUE_KIND: Final = "vague"
+EMPTY_CONTAINERS: Final = "empty-containers"
+MIXED_CONTAINERS: Final = "mixed-containers"
+UNTYPED_CALLS: Final = "untyped-calls"
+UNKNOWN_CALLS: Final = "unknown-calls"
+# The kinds that write a wider type than the value's own, each offered only where `fix-widen` names it.
+WIDEN_KINDS: Final = frozenset(
+    {
+        UNTYPED_PARAMETERS,
+        UNIONS,
+        VAGUE_KIND,
+        EMPTY_CONTAINERS,
+        MIXED_CONTAINERS,
+        UNTYPED_CALLS,
+        UNKNOWN_CALLS,
+    },
+)
+# What ends a line a widening wrote: its annotation is `--fix`'s to replace, and isn't LVA005.
+MARK: Final = "# constricter: auto"
+CONSTRUCTOR: Final = "constructor"
+MEMBER: Final = "member"
+NARROW: Final = "narrow"
+NESTING: Final = 3  # LVA006's default depth
+MAX_LENGTH: Final = 4  # LVA011's default: the longest fixed-length tuple an annotation may list
+VAGUE: Final = -1  # LVA005's default level: no vague part at all (see `annotations.vague_fits`)
+STARRED_SUBSCRIPTS: Final = (3, 11)  # the first Python to parse `tuple[int, *Ts]`
+# The guesses `--likely` applies: each a whole set of mechanisms, measured (see docs/LIKELY.md).
+LIKELY: Final = frozenset(
+    {
+        frozenset({"arithmetic", "copy"}),
+        frozenset({"arithmetic", "copy", "literal"}),
+        frozenset({"arithmetic", "literal"}),
+        frozenset({"arithmetic", "literal", "stdlib"}),
+        frozenset({"assigned"}),
+        frozenset({"assigned", "loop"}),
+        frozenset({"assigned", "method"}),
+        frozenset({"assigned", "method", "unpack"}),
+        frozenset({"assigned", "stdlib"}),
+        frozenset({"assigned", "subscript"}),
+        frozenset({"attribute"}),
+        frozenset({"attribute", "constructor"}),
+        frozenset({"attribute", "loop"}),
+        frozenset({"attribute", "rebound"}),
+        frozenset({"attribute", "subscript"}),
+        frozenset({"builtin", "copy"}),
+        frozenset({"call"}),
+        frozenset({"call", "constructor"}),
+        frozenset({"call", "constructor", "container", "copy"}),
+        frozenset({"call", "constructor", "container", "literal"}),
+        frozenset({"call", "container", "copy"}),
+        frozenset({"call", "container", "literal"}),
+        frozenset({"call", "copy"}),
+        frozenset({"call", "rebound"}),
+        frozenset({"comprehension", "constructor"}),
+        frozenset({"comprehension", "constructor", "copy", "loop"}),
+        frozenset({"conditional", "literal"}),
+        frozenset({"constructor"}),
+        frozenset({"constructor", "container"}),
+        frozenset({"constructor", "container", "literal"}),
+        frozenset({"constructor", "copy"}),
+        frozenset({"constructor", "filled"}),
+        frozenset({"constructor", "fixture"}),
+        frozenset({"constructor", "joined"}),
+        frozenset({"constructor", "method"}),
+        frozenset({"constructor", "method", "rebound"}),
+        frozenset({"constructor", "optional"}),
+        frozenset({"constructor", "rebound"}),
+        frozenset({"constructor", "returned"}),
+        frozenset({"constructor", "unpack"}),
+        frozenset({"container", "copy", "literal"}),
+        frozenset({"container", "copy", "loop"}),
+        frozenset({"container", "joined", "literal"}),
+        frozenset({"container", "joined", "literal", "loop"}),
+        frozenset({"container", "literal", "rebound"}),
+        frozenset({"copy"}),
+        frozenset({"copy", "filled"}),
+        frozenset({"copy", "literal"}),
+        frozenset({"copy", "loop"}),
+        frozenset({"copy", "stdlib"}),
+        frozenset({"copy", "unpack"}),
+        frozenset({"filled", "literal"}),
+        frozenset({"literal", "rebound", "unpack"}),
+        frozenset({"loop", "member"}),
+        frozenset({"loop", "rebound"}),
+        frozenset({"method"}),
+        frozenset({"method", "rebound", "unpack"}),
+        frozenset({"method", "unpack"}),
+        frozenset({"rebound", "returned"}),
+        frozenset({"rebound", "stdlib"}),
+        frozenset({"returned", "unpack"}),
+    },
+)
+UNION_SYNTAX: Final = (3, 10)  # the first Python where `int | None` is a type
+BUILTIN_GENERICS: Final = (3, 9)  # and where `list[int]` is
+
+
+class Level(IntEnum):
+    """How strict: each level makes one more code an error rather than a warning."""
+
+    RELAXED = 0
+    STRICT = 1
+    CONSTRICT = 2
+    SUFFOCATE = 3
+
+
+# Each level by name and by number, as the options take it.
+LEVELS: dict[str, Level] = {key: level for level in Level for key in (level.name.lower(), str(level.value))}
+_ERROR_FROM: dict[str, Level] = {
+    UNANNOTATED: Level.STRICT,
+    UNTYPED_TARGET: Level.CONSTRICT,
+    COMMENT_TYPED_TARGET: Level.SUFFOCATE,
+    UNANNOTATED_MEMBER: Level.STRICT,
+    VAGUE_TYPE: Level.SUFFOCATE,
+    NESTED_TYPE: Level.SUFFOCATE,
+    REDUNDANT_TYPE: Level.SUFFOCATE,
+    NARROWABLE_TYPE: Level.SUFFOCATE,
+    MISMATCHED_TYPE: Level.CONSTRICT,
+    UNUSED_UNION_MEMBER: Level.SUFFOCATE,
+    LONG_TUPLE: Level.SUFFOCATE,
+    CAN_BE_FINAL: Level.SUFFOCATE,
+}
+# Codes reported only from a level up (the rest are reported at every level).
+_REPORTED_FROM: dict[str, Level] = {
+    VAGUE_TYPE: Level.STRICT,
+    NESTED_TYPE: Level.STRICT,
+    LONG_TUPLE: Level.STRICT,
+    NARROWABLE_TYPE: Level.CONSTRICT,
+    UNUSED_UNION_MEMBER: Level.CONSTRICT,
+}
+
+
+class Edit(StrEnum):
+    """Where a `Fix` writes its annotation."""
+
+    ANNOTATE = "annotate"  # `: T` after the offence's name
+    REPLACE = "replace"  # over an annotation already there (`Fix.span`: its start and end column)
+    DECLARE = "declare"  # `name: T` on a line of its own before a statement (`Fix.span`: its line and column)
+
+
+class Fix(NamedTuple):
+    """The annotation `--fix` would write for an offence, how its value decided it, and where."""
+
+    annotation: str
+    reason: str = ""  # `--show-fixes`
+    unsafe: bool = False  # a guess, applied only with `--unsafe-fixes`
+    edit: Edit = Edit.ANNOTATE
+    span: tuple[int, int] = (0, 0)  # see `Edit`; columns count UTF-8 bytes, as `ast`'s do
+    kinds: frozenset[str] = frozenset()  # every `FIX_KINDS` mechanism that decided it
+    # The columns to delete too: with `Edit.DECLARE`, on the statement's line (the type comment it
+    # replaces); with `Edit.REPLACE`, on line `mark` (the `MARK` of the widening it replaces).
+    drop: tuple[int, int] | None = None
+    imports: tuple[str, ...] = ()  # statements the annotation needs added (`from io import BytesIO`)
+    after: int = 0  # the line they go after (see `fix.core.imports.plan`)
+    guarded: tuple[str, ...] = ()  # statements the annotation needs added under `if TYPE_CHECKING:`
+    guard: str = ""  # how the module names `TYPE_CHECKING`, for a new such block
+    block: tuple[int, int] = (0, 0)  # the first and last line of the body of one there is (see `ImportPlan`)
+    # The line whose end a widening's `MARK` goes at (see `WIDEN_KINDS`), or its replacement's is
+    # dropped from: its statement's last, where that isn't the offence's own (0).
+    mark: int = 0
+
+
+class Tier(StrEnum):
+    """How far a fix is trusted: what `--fix` applies it with."""
+
+    CERTAIN = "certain"  # always
+    LIKELY = "likely"  # a guess `--likely` applies too
+    GUESS = "guess"  # one only `--unsafe-fixes` does
+
+    @classmethod
+    def of(cls, *, unsafe: bool, likely: bool) -> "Tier":
+        """Name the tier of a fix that's a guess or not (`unsafe`), of a likely set or not.
+
+        Returns:
+          It.
+
+        """
+        return cls.CERTAIN if not unsafe else cls.LIKELY if likely else cls.GUESS
+
+
+class FixPolicy(NamedTuple):
+    """Which `FIX_KINDS` `--fix` offers (`select`, empty for all, less `ignore`), and which guesses it trusts.
+
+    A guess is certain when every guessing mechanism it rests on (`constructor`, `narrow`, through
+    any guessed local it copies) is in `unsafe_select`, as ruff's `extend-safe-fixes` does. A
+    widening (see `WIDEN_KINDS`) is offered only if it's in `widen`.
+    """
+
+    select: frozenset[str] = frozenset()
+    ignore: frozenset[str] = frozenset()
+    unsafe_select: frozenset[str] = frozenset()
+    widen: frozenset[str] = frozenset()
+
+    def allows(self, kinds: frozenset[str]) -> bool:
+        """Check whether a fix decided by `kinds` is offered.
+
+        Returns:
+          Whether every one is selected, none ignored, and each widening asked for.
+
+        """
+        return (
+            (not self.select or kinds <= self.select)
+            and not kinds & self.ignore
+            and kinds & WIDEN_KINDS <= self.widen
+        )
+
+    def trusts(self, origins: frozenset[str]) -> bool:
+        """Check whether a guess resting on `origins` is promoted to certain.
+
+        Returns:
+          Whether it rests on something, and all of it is in `unsafe_select`.
+
+        """
+        return bool(origins) and origins <= self.unsafe_select
+
+
+@dataclass(frozen=True, order=True)
+class Offence:
+    """One untyped first binding; `col` is 0-based."""
+
+    line: int
+    col: int
+    name: str
+    code: str = UNANNOTATED
+    # What `--fix` would write, where the value makes it unambiguous (or, if `unsafe`, a guess).
+    edit: Fix | None = field(default=None, compare=False)
+    # In a notebook, the cell (from 1); `line` is then the line in that cell.
+    cell: int | None = field(default=None, compare=False)
+    # What the message names besides the variable: LVA008's to LVA010's type, LVA011's length.
+    detail: str = field(default="", compare=False)
+
+    @property
+    def fix(self) -> str | None:
+        """The annotation `--fix` would write, if any."""
+        return None if self.edit is None else self.edit.annotation
+
+    @property
+    def unsafe(self) -> bool:
+        """Whether the fix is a guess, applied only with `--unsafe-fixes` (or `--likely`, if `likely`)."""
+        return self.edit is not None and self.edit.unsafe
+
+    @property
+    def tier(self) -> Tier | None:
+        """The fix's tier, a guess likely where its mechanisms are a set of `LIKELY`; `None` with no fix."""
+        if self.edit is None:
+            return None
+        return Tier.of(unsafe=self.edit.unsafe, likely=self.edit.kinds in LIKELY)
+
+    @property
+    def likely(self) -> bool:
+        """Whether the fix is a guess `--likely` applies."""
+        return self.tier is Tier.LIKELY
+
+    @property
+    def reason(self) -> str:
+        """How the value decided the fix (`--show-fixes`)."""
+        return "" if self.edit is None else self.edit.reason
+
+    @property
+    def message(self) -> str:
+        """The report text."""
+        return MESSAGES[self.code].format(name=repr(self.name), detail=self.detail)
+
+    def is_error(self, level: Level) -> bool:
+        """Check this offence's severity at `level`.
+
+        Returns:
+          Whether it's an error rather than a warning.
+
+        """
+        return errs(self.code, level)
+
+    def is_reported(self, level: Level) -> bool:
+        """Check whether `level` reports this offence.
+
+        Returns:
+          Whether it does at all.
+
+        """
+        return reports(self.code, level)
+
+
+def errs(code: str, level: Level) -> bool:
+    """Check whether an offence of `code` is an error at `level`.
+
+    Returns:
+      Whether it is: a warning otherwise.
+
+    """
+    return level >= _ERROR_FROM[code]
+
+
+def reports(code: str, level: Level) -> bool:
+    """Check whether `level` reports an offence of `code`.
+
+    Returns:
+      Whether it does at all.
+
+    """
+    return level >= _REPORTED_FROM.get(code, Level.RELAXED)
+
+
+# Bases whose class bodies `--fix` annotates as a plain class's (`fix-plain-bases` adds to them): a
+# class, or a package for every class in it; `!` leaves one out. Django reads no annotation in a class
+# body, but its `Choices` are enums, whose members a type checker won't have annotated.
+PLAIN_BASES: Final = (
+    "django",
+    "!django.db.models.Choices",
+    "!django.db.models.IntegerChoices",
+    "!django.db.models.TextChoices",
+    "!django.db.models.enums",
+)
+
+
+class Checks(NamedTuple):
+    """What to check, beyond the defaults.
+
+    With `type_comments`, `x = 1  # type: int` counts as annotated; with `all_scopes`, module and
+    class bodies are checked too (LVA004); an annotation nested `nesting` deep is LVA006, and one
+    listing a fixed-length tuple longer than `max_length` is LVA011. `min_python`: the oldest Python
+    the code runs on (`None`: not known), whose syntax a fix is written in. `vague`: how vague an
+    annotation may be before it's LVA005, and a fix isn't offered (see `annotations.vague_fits`).
+    `plain_bases`: the bases a plain class may have besides the builtin ones (see `PLAIN_BASES`).
+    """
+
+    type_comments: bool = False
+    all_scopes: bool = False
+    nesting: int = NESTING
+    max_length: int = MAX_LENGTH
+    # A project's own type hierarchy, for LVA008-LVA010: each type and the types it's narrower than.
+    narrower: tuple[Narrower, ...] = ()
+    fixes: FixPolicy = FixPolicy()  # which fixes `--fix` offers; it never changes what's reported
+    final: bool = False  # look for LVA012 (opt-in: see `OPT_IN`)
+    min_python: tuple[int, int] | None = None
+    vague: int = VAGUE
+    plain_bases: tuple[str, ...] = PLAIN_BASES
+
+
+DEFAULT_CHECKS: Final = Checks()
+
+
+def at(node: ast.expr | ast.pattern | ast.stmt) -> tuple[int, int]:
+    """Find where `node` starts, as an offence is placed.
+
+    Returns:
+      Its line and (0-based) column.
+
+    """
+    return node.lineno, node.col_offset

constricter/overrides.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+"""`typing.override`, which is Python 3.12+, on 3.11 too: what type checkers see, and nothing at run time.
+
+Apart from the modules mypyc compiles, which takes the code under `if TYPE_CHECKING:` for the code
+that runs, and so this `else` for code no run reaches.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import override
+else:
+
+    def override(func: object) -> object:
+        """Mark an override (for type checkers only).
+
+        Returns:
+          `func`, unchanged.
+
+        """
+        return func
+
+
+__all__ = ["override"]

constricter/plugins/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""The rules as linter plugins: flake8's (an entry point) and pylint's (`load-plugins`)."""