python-constricter 0.3.3__py3-none-any.whl → 0.3.5__py3-none-any.whl

constricter/__init__.py

@@ -25,7 +25,7 @@ from constricter.offences import (
 )
 from constricter.rules.checker import Coverage, annotation_coverage, check_source, check_tree
 
-__version__ = "0.3.3"
+__version__ = "0.3.5"
 __all__ = [
     "COMMENT_TYPED_TARGET",
     "DEFAULT_CHECKS",

constricter/__main__.py

@@ -1,9 +1,26 @@
 # SPDX-License-Identifier: MIT
-"""`python -m constricter`."""
+"""`python -m constricter`, and the `constricter` script."""
 
+import contextlib
+import os
 import sys
 
 from constricter.cli.command import main
 
+
+def run() -> None:
+    """Run the command, and leave with its status at once.
+
+    Not by the interpreter's own exit, which frees every parsed file and the index an object at a
+    time: a fifth of a check of a thousand files. What the command wrote is flushed first; nothing
+    else waits on the exit (its workers have ended, its output file is closed).
+    """
+    status: int = main()
+    with contextlib.suppress(OSError, ValueError):  # a reader that left, a stream closed already
+        _ = sys.stdout.flush()
+        _ = sys.stderr.flush()
+    os._exit(status)
+
+
 if __name__ == "__main__":  # not when `--jobs` workers import it
-    sys.exit(main())
+    run()

constricter/cli/command.py

@@ -21,11 +21,11 @@ from constricter.cli.options import Mode, Options, Output
 from constricter.cli.paths import STDIN, python_files
 from constricter.cli.protocol import HintError
 from constricter.cli.report import Format, Result, fix_reasons, render, statistics
-from constricter.cli.runs import BaselineRun, CheckRun, CoverageRun, FileRun
-from constricter.cli.workers import Workers
+from constricter.cli.runs import Added, BaselineRun, CheckRun, CoverageRun, FileRun, merged
+from constricter.cli.workers import Workers, kept, started
 from constricter.fix.core import fixes
 from constricter.fix.core.known import Callee, Hints, Outside, Returns
-from constricter.fix.index import callers, decorated, installed, plain, project
+from constricter.fix.index import callers, decorated, installed, loose, plain, project
 from constricter.noqa import lines, unsuppressed
 from constricter.offences import (
     DEFAULT_CHECKS,
@@ -127,6 +127,7 @@ def _placed(offence: Offence, where: list[notebook.Line]) -> Offence:
 
 
 # One changed part of a fixed file (the file, or a notebook's cell): its label, old and new lines.
+_Hinted: TypeAlias = dict[Path, tuple[Hints, ...]]  # each file's hints, a checker's each
 _Change: TypeAlias = tuple[str, list[str], list[str]]
 # One JSON value a coverage report holds, and one file's row of them.
 _Scalar: TypeAlias = str | int | float
@@ -308,7 +309,29 @@ def _handled(path: Path, text: tuple[str, Path], offences: list[Offence], option
         return CheckRun(results, baselined, error=f"{name}: error: {message}")
     if fixed:
         _ = parsed.take(raw)  # the tree of the text it had: no check will ask for it again
-    return CheckRun(left, baselined, fixed)
+    return CheckRun(
+        left,
+        baselined,
+        fixed,
+        made=[r._replace(replacements=(), fixed=True) for r in results if r.offence in fixing],
+        rounds=(_added(raw, name, fixing),),
+    )
+
+
+def _added(raw: str, name: Path, fixing: Sequence[Offence]) -> Added:
+    """Find the lines fixing `fixing` adds to `raw`, the text of `name` (see `fixes.inserted`).
+
+    Returns:
+      Each one's cell (`None` outside a notebook) and the line it goes before; a notebook's cells
+      get declarations alone.
+
+    """
+    if name.suffix != notebook.SUFFIX:
+        return tuple((None, line) for line in fixes.inserted(lines(raw), fixing))
+    declared: list[tuple[int, int]] = [
+        (o.cell or 0, o.edit.span[0]) for o in fixing if o.edit is not None and o.edit.edit is Edit.DECLARE
+    ]
+    return tuple(sorted(declared))
 
 
 def _baseline_path(path: Path, outside: Outside, options: Options) -> BaselineRun:
@@ -340,6 +363,17 @@ def _cover_path(path: Path, _outside: Outside, options: Options) -> CoverageRun:
 
 
 def _check_all(options: Options) -> tuple[list[Path], list[FileRun]]:
+    """Check every file (see `_check_rounds`), its rounds by one set of worker processes.
+
+    Returns:
+      The names, and what each file found.
+
+    """
+    with kept():
+        return _check_rounds(options)
+
+
+def _check_rounds(options: Options) -> tuple[list[Path], list[FileRun]]:
     """Check every file (`--jobs` at a time), in order.
 
     With `--infer-with`, the type checker's server runs throughout: it's asked for every file's
@@ -401,7 +435,7 @@ def _check_all(options: Options) -> tuple[list[Path], list[FileRun]]:
             index: int
             run: FileRun
             for index, run in zip(again, redone, strict=True):
-                runs[index] = _merged(runs[index], run)
+                runs[index] = merged(runs[index], run)
             again = [index for index, run in zip(again, redone, strict=True) if cast("CheckRun", run).fixed]
         checker: str
         path: Path
@@ -447,7 +481,7 @@ def _called_again(
     calling = [
         at
         for at in calling
-        if project.returned(modules, paths[at], {}) != project.returned(before, paths[at], {})
+        if loose.returned(modules, paths[at], {}) != loose.returned(before, paths[at], {})
     ]
     return runs, _checked_more(paths, runs, calling, (check, options, session), modules)
 
@@ -473,7 +507,7 @@ def _checked_more(
     at: int
     run: FileRun
     for at, run in zip(which, redone, strict=True):
-        runs[at] = _merged(runs[at], run) if how[1].mode is Mode.FIX else run
+        runs[at] = merged(runs[at], run) if how[1].mode is Mode.FIX else run
     return modules
 
 
@@ -509,44 +543,29 @@ def _checked_all(
       What each file found, and the index of every file's module.
 
     """
-    hinted: dict[Path, tuple[Hints, ...]] = {} if session is None else session.hints(_texts(paths))
+    # Before a worker starts: one forked while the servers' threads run could wait on a lock one holds.
+    hinted: _Hinted = {} if session is None else session.hints(_texts(paths))
     if options.input.trace is not None:
         hinted = traced.merged(hinted, traced.load(options.input.trace), paths)
     coverage: bool = options.mode is Mode.COVERAGE  # needs nothing from the other files
-    stack: contextlib.ExitStack
-    with contextlib.ExitStack() as stack:
-        pool: Workers | None = None
-        if options.jobs != 1 and len(paths) > 1:
-            pool = stack.enter_context(Workers(paths, options.jobs))
-        if modules is None and pool:
-            modules = project.Index({}, []) if coverage else pool.index()
-        elif modules is None:
-            modules = project.Index({}, []) if coverage else project.index(paths)
-            collecting.indexed()
-        if not coverage:
-            modules = plain.settled(
-                decorated.passed(installed.with_installed(modules, installed.search_path())),
-                options.checks.plain_bases,
-            )
-        return schedule.checked(
-            paths,
-            check,
-            pool,
-            (modules, hinted),
-            _merged if options.mode is Mode.FIX else None,
+    pool: Workers | None = started(paths, options.jobs) if options.jobs != 1 and len(paths) > 1 else None
+    if modules is None and pool:
+        modules = project.Index({}, []) if coverage else pool.index()
+    elif modules is None:
+        modules = project.Index({}, []) if coverage else project.index(paths)
+        collecting.indexed()
+    if not coverage:
+        modules = plain.settled(
+            decorated.passed(installed.with_installed(modules, installed.search_path())),
+            options.checks.plain_bases,
         )
-
-
-def _merged(before: FileRun, after: FileRun) -> FileRun:
-    """Join a file's two `--fix` rounds' `CheckRun`s: what's left is the later's, what's fixed is both's.
-
-    Returns:
-      The joined run.
-
-    """
-    first: CheckRun = cast("CheckRun", before)
-    later: CheckRun = cast("CheckRun", after)
-    return replace(later, fixed=first.fixed + later.fixed)
+    return schedule.checked(
+        paths,
+        check,
+        pool,
+        (modules, hinted),
+        merged if options.mode is Mode.FIX else None,
+    )
 
 
 def _texts(paths: Sequence[Path]) -> dict[Path, str]:
@@ -579,10 +598,16 @@ def _report(options: Options, runs: Sequence[FileRun], files: int) -> int:
     results: list[Result] = [result for run in checked for result in run.results]
     output: Output = options.output
     text: bool = output.fmt in {Format.TEXT, Format.FULL}
+    # With `--show-fixes`, the fixes `--fix` made too: after the rest, as text or JSON.
+    shown: list[Result] = [*results, *(made for run in checked if output.show_fixes for made in run.made)]
     line: str
-    for line in statistics(results) if text and output.statistics else render(output.fmt, results):
+    for line in (
+        statistics(results)
+        if text and output.statistics
+        else render(output.fmt, shown if output.fmt is Format.JSON else results)
+    ):
         _ = sys.stdout.write(f"{line}\n")
-    for line in fix_reasons(results) if text and output.show_fixes else ():
+    for line in fix_reasons(shown) if text and output.show_fixes else ():
         _ = sys.stdout.write(f"{line}\n")
     errors: int = sum(r.offence.is_error(r.level) for r in results)
     if text and not output.quiet:
@@ -611,30 +636,53 @@ def _coverage(options: Options, paths: Sequence[Path], runs: Sequence[FileRun])
     counted: list[tuple[Path, Coverage]] = [
         (path, run.coverage) for path, run in zip(paths, covered, strict=True) if run.coverage is not None
     ]
-    total: Coverage = Coverage(sum(c.typed for _, c in counted), sum(c.total for _, c in counted))
+    total: Coverage = Coverage(
+        sum(c.typed for _, c in counted),
+        sum(c.total for _, c in counted),
+        sum(c.widened for _, c in counted),
+    )
     if options.output.fmt is Format.JSON:
         report: dict[str, _Scalar | list[_Row]] = {
-            "typed": total.typed,
-            "total": total.total,
-            "percent": round(total.percent, 1),
-            "files": [
-                {"path": str(path), "typed": c.typed, "total": c.total, "percent": round(c.percent, 1)}
-                for path, c in counted
-            ],
+            **_counts(total),
+            "files": [{"path": str(path), **_counts(c)} for path, c in counted],
         }
         _ = sys.stdout.write(json.dumps(report, indent=2) + "\n")
     else:
         path: Path
         c: Coverage
         for path, c in counted:
-            _ = sys.stdout.write(f"{path}: {c.typed}/{c.total} typed ({c.percent:.1f}%)\n")
-        _ = sys.stdout.write(
-            f"Total: {total.typed}/{total.total} typed ({total.percent:.1f}%) in {len(counted)} file(s).\n",
-        )
+            _ = sys.stdout.write(f"{path}: {_typed(c)}\n")
+        _ = sys.stdout.write(f"Total: {_typed(total)} in {len(counted)} file(s).\n")
     threshold: float | None = options.output.fail_under
     return EXIT_FOUND if threshold is not None and total.percent < threshold else EXIT_CLEAN
 
 
+def _counts(found: Coverage) -> _Row:
+    """Name a coverage's counts, for `--format=json`.
+
+    Returns:
+      Them, by name.
+
+    """
+    return {
+        "typed": found.typed,
+        "total": found.total,
+        "widened": found.widened,
+        "percent": round(found.percent, 1),
+    }
+
+
+def _typed(found: Coverage) -> str:
+    """Write a coverage as text: `3/4 typed (75.0%)`, then what a widening annotated, if anything.
+
+    Returns:
+      It.
+
+    """
+    wider: str = f", {found.widened} widened" if found.widened else ""
+    return f"{found.typed}/{found.total} typed ({found.percent:.1f}%){wider}"
+
+
 def _run(options: Options) -> int:
     """Check, fix, diff, count or baseline, printing what that finds.
 

constricter/cli/config.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Final, TypeAlias, cast
 
 from constricter.cli.protocol import SERVERS
 from constricter.jsonc import is_int
-from constricter.offences import FIX_KINDS, LEVELS, MESSAGES
+from constricter.offences import FIX_KINDS, LEVELS, MESSAGES, WIDEN_KINDS
 
 if TYPE_CHECKING:
     from datetime import date, datetime, time
@@ -32,6 +32,7 @@ def unknown_codes(codes: Sequence[str]) -> list[str]:
 
 DEFAULT_BASELINE: Final = "constricter-baseline.json"
 _MIN_PYTHON: Final = "min_python"
+_ALL_KINDS: Final = "all"  # `fix-widen`'s: every wider type
 _VERSION: Final = re.compile(r"\d+\.\d+")  # `min-python`'s: `3.11`
 # A lower bound among `requires-python`'s specifiers: `>=3.11`, `~=3.11`, `==3.11.*`, `>3.10`.
 _LOWER_BOUND: Final = re.compile(r"(?:>=|~=|==|>)\s*(\d+)(?:\.(\d+))?")
@@ -160,6 +161,31 @@ def unknown_fix_kinds(kinds: Sequence[str]) -> list[str]:
     return [kind for kind in kinds if kind not in FIX_KINDS]
 
 
+def unknown_widen_kinds(kinds: Sequence[str]) -> list[str]:
+    """Check `kinds` against `WIDEN_KINDS`' ids, and `all`.
+
+    Returns:
+      Those that aren't one.
+
+    """
+    return [kind for kind in kinds if kind not in WIDEN_KINDS | {_ALL_KINDS}]
+
+
+def widen_kinds(kinds: Sequence[str]) -> list[str]:
+    """Read `fix-widen`'s kinds, `all` as every one.
+
+    Returns:
+      Them.
+
+    """
+    return sorted(WIDEN_KINDS) if _ALL_KINDS in kinds else list(kinds)
+
+
+def _widen_kinds(value: _Toml) -> list[str] | None:
+    kinds: list[str] | None = [value] if isinstance(value, str) else _strings(value)
+    return None if kinds is None or unknown_widen_kinds(kinds) else widen_kinds(kinds)
+
+
 def _fix_kinds(value: _Toml) -> list[str] | None:
     kinds: list[str] | None = _strings(value)
     return None if kinds is None or unknown_fix_kinds(kinds) else kinds
@@ -246,6 +272,7 @@ _READERS: dict[str, Callable[[_Toml], Default | None]] = {
     "fix-select": _fix_kinds,
     "fix-ignore": _fix_kinds,
     "unsafe-fix-select": _fix_kinds,
+    "fix-widen": _widen_kinds,
     "fix-plain-bases": _strings,
     "type-comments": _flag,
     "all-scopes": _flag,

constricter/cli/hints.py

@@ -33,7 +33,7 @@ from functools import partial
 from pathlib import Path
 from typing import IO, Final, NamedTuple, Self, TypeAlias, cast
 
-from constricter.cli import edits, guard, protocol
+from constricter.cli import edits, guard, protocol, remembered
 from constricter.cli.protocol import SERVERS, HintError, HungError, Server
 from constricter.fix.core.known import Hints, Offered
 
@@ -47,8 +47,6 @@ _Task: TypeAlias = Callable[[], _Found]  # one server's work: the hints of each
 
 _BATCH: Final = 8  # files a free server takes at a time: few, so none is left with the slow ones
 MEMORY: Final = 8 << 30  # the most a checker's servers use together, by default (`--infer-memory`)
-_SERVER_MEMORY: Final = 600 << 20  # a server's memory, before the files (basedpyright's, measured)
-_MEMORY_PER_BYTE: Final = 130  # and for each byte of them: 1.2 GB for SQLAlchemy's 8 MB, 3.4 for pandas' 21
 _MEMINFO: Final = Path("/proc/meminfo")
 _FILES_PER_SERVER: Final = 32  # fewer files than this each don't pay for another server's start
 # Seconds without a word from a server before it's taken for hung. Not an answer's wait: pandas'
@@ -228,11 +226,10 @@ class Checker:
     """One checker's servers, and which of them has each file.
 
     It has as many as its files need (one per `_FILES_PER_SERVER`), up to the command's `--jobs`, the
-    checker's own most (`Server.most`: one for a checker that works in parallel itself), and as many
-    as fit in its memory: `--infer-memory` (never more than is available), or by default `MEMORY`
-    (never more than half what's available). Each server loads the whole program it checks, which
-    takes (as measured) about `_SERVER_MEMORY` plus `_MEMORY_PER_BYTE` for each byte of the files.
-    One server it always has, whatever the memory.
+    checker's own most (`Server.most`), and as many as fit in its memory: `--infer-memory` (never
+    more than is available), or by default `MEMORY` (never more than half what's available). Each
+    server loads the whole program it checks, or its share of it, by its checker's own measure (see
+    `Server.fitting`). One server it always has, whatever the memory.
 
     The files are handed out a few at a time (`_BATCH`), the biggest first, to whichever server is
     free: one file's analysis can take far longer than another's, and none waits on a busy one. A
@@ -244,7 +241,8 @@ class Checker:
         self.name: str = name
         self.root: Path = root
         self.command: list[str] = command(name)
-        self.most: int = max(1, min(servers, SERVERS[name].most))
+        self.server: Server = SERVERS[name]
+        self.most: int = max(1, min(servers, self.server.most))
         self.memory: int = budget(memory, available_memory())
         self.servers: list[Connection] = []
         self.assigned: dict[Path, int] = {}  # each file's server, by its place in `servers`
@@ -258,13 +256,14 @@ class Checker:
 
         """
         size: int = sum(len(text) for text in files.values())
-        fit: int = max(1, self.memory // (_SERVER_MEMORY + _MEMORY_PER_BYTE * size))
+        fit: int = max(1, self.server.fitting(self.memory, size))
         return max(len(self.servers), min(self.most, -(-len(files) // _FILES_PER_SERVER), fit))
 
     def tasks(self, files: Mapping[Path, str]) -> list[_Task]:
         """Make each server's work on `files`: its own files first, then new ones as it's free for them.
 
-        A file abandoned (see `_alone`) isn't asked about again.
+        A file abandoned (see `_alone`), in this run or an earlier one (see `remembered`), isn't
+        asked about again.
 
         Returns:
           A task per server, giving the hints of every file it was sent.
@@ -274,8 +273,14 @@ class Checker:
         path: Path
         for path in files.keys() & self.assigned.keys() - self.abandoned:
             own.setdefault(self.assigned[path], {})[path] = files[path]
+        # One it hung on in an earlier run, unchanged since: left without hints from the start.
+        self.abandoned.update(
+            path
+            for path in files.keys() - self.assigned.keys() - self.abandoned
+            if remembered.hung(self.name, self.command, files[path])
+        )
         fresh: list[Path] = sorted(
-            files.keys() - self.assigned.keys(),
+            files.keys() - self.assigned.keys() - self.abandoned,
             key=lambda new: (-len(files[new]), new),
         )
         batches: queue.SimpleQueue[dict[Path, str]] = queue.SimpleQueue()
@@ -352,6 +357,7 @@ class Checker:
                 found.update(server.answers(server.ask({path: text})))
             except HungError as hung:
                 self.abandoned.add(path)
+                remembered.remember(self.name, self.command, text)
                 if len(self.abandoned) > _MOST_ABANDONED:
                     error: str = f"{self.name} hung on {len(self.abandoned)} file(s), each asked about alone"
                     raise HintError(error) from hung

constricter/cli/options.py

@@ -18,6 +18,8 @@ from constricter.cli.config import (
     project_root,
     unknown_codes,
     unknown_fix_kinds,
+    unknown_widen_kinds,
+    widen_kinds,
 )
 from constricter.cli.explain import explain
 from constricter.cli.paths import STDIN, excluded
@@ -133,6 +135,24 @@ def _fix_kinds(text: str) -> list[str]:
     return kinds
 
 
+def _widen_kinds(text: str) -> list[str]:
+    """Read a comma-separated list of the wider types `--fix` may write (`untyped-parameters`), or `all`.
+
+    Returns:
+      Them.
+
+    Raises:
+      argparse.ArgumentTypeError: One isn't a widening's id.
+
+    """
+    kinds: list[str] = [kind.strip() for kind in text.split(",") if kind.strip()]
+    unknown: list[str]
+    if unknown := unknown_widen_kinds(kinds):
+        message: str = f"no wider type is called {', '.join(unknown)} (see docs/FIXES.md)"
+        raise argparse.ArgumentTypeError(message)
+    return widen_kinds(kinds)
+
+
 def _version(text: str) -> tuple[int, int]:
     """Read `--min-python`: a Python version (`3.11`).
 
@@ -333,6 +353,13 @@ def _parser() -> argparse.ArgumentParser:
         metavar="KINDS",
         help="treat guesses from these mechanisms (constructor, narrow) as certain",
     )
+    _ = parser.add_argument(
+        "--fix-widen",
+        type=_widen_kinds,
+        default=[],
+        metavar="KINDS",
+        help="also write these wider types, each marked (untyped-parameters, unions, ...; all: every one)",
+    )
     _ = parser.add_argument(
         "--fix-plain-bases",
         type=_listed,
@@ -367,7 +394,7 @@ def _parser() -> argparse.ArgumentParser:
     _ = parser.add_argument(
         "--show-fixes",
         action="store_true",
-        help="after the report, list each fix and how the value decided it (text)",
+        help="after the report, list each fix and how the value decided it; with --fix, those made too",
     )
     _ = parser.add_argument(
         "--statistics",
@@ -594,6 +621,7 @@ class Options:
                     frozenset(cast("list[str]", args.fix_select)),
                     frozenset(cast("list[str]", args.fix_ignore)),
                     frozenset(cast("list[str]", args.unsafe_fix_select)),
+                    frozenset(cast("list[str]", args.fix_widen)),
                 ),
                 min_python=cast("tuple[int, int] | None", args.min_python),
                 plain_bases=(*PLAIN_BASES, *cast("list[str]", args.fix_plain_bases)),

constricter/cli/protocol.py

@@ -33,21 +33,41 @@ class Server(NamedTuple):
     """A checker's language server: how it's started, and how many are worth running at once.
 
     Its executable, the arguments that start it over stdio, and the most of it to run (up to
-    `MAX_SERVERS`; one for a checker that works in parallel itself).
+    `MAX_SERVERS`). And the memory its servers take, as measured: `memory` bytes each before the
+    files, and `per_byte` more for each byte of them: each server's again where each holds the
+    `whole` program, once among them all where each holds what it's asked about.
     """
 
     executable: str
     args: tuple[str, ...]
     most: int
+    memory: int
+    per_byte: int
+    whole: bool = False
+
+    def fitting(self, budget: int, size: int) -> int:
+        """Count the servers that fit in `budget` bytes, for files of `size` bytes together.
+
+        Returns:
+          It: none where one doesn't fit.
+
+        """
+        if self.whole:
+            return budget // (self.memory + self.per_byte * size)
+        return max(0, budget - self.per_byte * size) // self.memory
 
 
 MAX_SERVERS: Final = 4  # a checker's, at most: each holds its own copy of the program it checks
 SERVERS: Final = {
     # One thread each: more servers check more at once (sqlalchemy's hints: 10.8s with one, 7.2s with four).
-    "basedpyright": Server("basedpyright-langserver", ("--stdio",), MAX_SERVERS),
-    # Parallel already: more servers only repeat its work (sqlalchemy's: 0.9s with one, 0.7s with four).
-    "ty": Server("ty", ("server",), 1),
-    "pyrefly": Server("pyrefly", ("lsp",), 1),  # parallel too
+    # Each holds the whole program: 1.2 GB for sqlalchemy's 8 MB, 3.4 for pandas's 21.
+    "basedpyright": Server("basedpyright-langserver", ("--stdio",), MAX_SERVERS, 600 << 20, 130, whole=True),
+    # Parallel itself, and still quicker shared out: a hinted check of pandas takes 36s with one, 25s
+    # with two, 22s with three and 21s with four (1.2 GB with one, 1.7 with two, 2.5 with four).
+    "ty": Server("ty", ("server",), MAX_SERVERS, 420 << 20, 38),
+    # Parallel too: pandas's takes 132s with one, 58s with two and 32s with four (2.8 GB, 3.2, 4.2);
+    # the standard library's 39 MB, 4.3 GB with one and 5.6 with four.
+    "pyrefly": Server("pyrefly", ("lsp",), MAX_SERVERS, 480 << 20, 120),
 }
 _PROBE: Final = "--version"  # quick for each; basedpyright-langserver's exits 1 all the same
 _PROBE_TIMEOUT: Final = 10.0  # seconds it may take

constricter/cli/remembered.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+"""The files a type checker's server hung on, remembered between runs.
+
+A server that hangs on a file costs the run its timeout twice, and a restart each time: once with
+the file among others, once with it alone. The file's text, with the checker and its executable as
+it was (its size and when it changed), names an empty file in the cache; while there's one, the
+file is left without hints from the start. A new version of the checker, or a changed file, is
+asked again.
+"""
+
+import contextlib
+import hashlib
+from collections.abc import Sequence
+from pathlib import Path
+
+from constricter.fix.index.installed import cache_directory
+
+
+def _marker(checker: str, command: Sequence[str], text: str) -> Path:
+    """Name what remembers that `checker`, started by `command`, hung on a file holding `text`.
+
+    Returns:
+      Its path in the cache.
+
+    """
+    version: str = ""
+    with contextlib.suppress(OSError):
+        version = _version(Path(command[0]))
+    key: str = "\0".join((checker, command[0], version, text))
+    return cache_directory().with_name("hung") / hashlib.sha256(key.encode("utf-8", "replace")).hexdigest()
+
+
+def _version(executable: Path) -> str:  # which build of it: its size and when it changed
+    return f"{executable.stat().st_size}:{executable.stat().st_mtime_ns}"
+
+
+def hung(checker: str, command: Sequence[str], text: str) -> bool:
+    """Check whether `checker` hung on a file holding `text`, in an earlier run.
+
+    Returns:
+      Whether it did.
+
+    """
+    return _marker(checker, command, text).exists()
+
+
+def remember(checker: str, command: Sequence[str], text: str) -> None:
+    """Remember that `checker` hung on a file holding `text`; nothing, where the cache can't be written."""
+    marker: Path = _marker(checker, command, text)
+    with contextlib.suppress(OSError):
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.touch()

constricter/cli/report.py

@@ -40,6 +40,7 @@ class Result(NamedTuple):
     level: Level
     source: str = ""  # the offending line, for `--format=full`
     replacements: tuple[Replacement, ...] = ()  # its fix as text edits, for SARIF and rdjson
+    fixed: bool = False  # `--fix` made its fix: listed with `--show-fixes`, on the line it was on
 
     @property
     def suggestions(self) -> tuple[Replacement, ...]:
@@ -208,6 +209,7 @@ def _json(results: Sequence[Result]) -> Iterator[str]:
                 "severity": r.severity,
                 "message": r.offence.message,
                 "cell": r.offence.cell,
+                "fixed": r.fixed,
                 "fix": None
                 if r.offence.fix is None
                 else {
@@ -360,11 +362,11 @@ def render(fmt: Format, results: Sequence[Result]) -> Iterator[str]:
 
 
 def fix_reasons(results: Sequence[Result]) -> Iterator[str]:
-    """List the annotation each fixable result would get, and how its value decided it.
+    """List the annotation each fixable result would get, or got, and how its value decided it.
 
     Yields:
-      A line each: where, the name, the annotation and its reason; a guess says it needs
-      `--unsafe-fixes`.
+      A line each: where, the name (`fixed`, for a fix `--fix` made), the annotation and its reason;
+      a guess left unmade says it needs `--unsafe-fixes`.
 
     """
     r: Result
@@ -372,11 +374,11 @@ def fix_reasons(results: Sequence[Result]) -> Iterator[str]:
         if r.offence.fix is not None:
             cell: str = "" if r.offence.cell is None else f"cell {r.offence.cell}:"
             where: str = f"{r.path}:{cell}{r.offence.line}:{r.offence.col + 1}"
-            guess: str = " (a guess: --unsafe-fixes)" if r.offence.unsafe else ""
+            guess: str = " (a guess: --unsafe-fixes)" if r.offence.unsafe and not r.fixed else ""
             kinds: str = ", ".join(sorted(r.offence.edit.kinds if r.offence.edit else ()))
             written: str = f"`{r.offence.fix}`" if r.offence.fix else "drop its annotation"
             decided: str = f"{written}, from {r.offence.reason} [{kinds}]"
-            yield f"{where}: fix {r.offence.name!r}: {decided}{guess}"
+            yield f"{where}: {'fixed' if r.fixed else 'fix'} {r.offence.name!r}: {decided}{guess}"
 
 
 def statistics(results: Sequence[Result]) -> Iterator[str]: