willitbite 0.1.0__py3-none-any.whl

willitbite/__init__.py

@@ -0,0 +1,3 @@
+"""Decide which ruff warnings can actually reach you at runtime."""
+
+__version__ = "0.1.0"

willitbite/callsites.py

@@ -0,0 +1,187 @@
+"""Who calls this, and do any of them leave the argument out?
+
+A function that mutates its own mutable default is wrong. That is a property of
+the function and it does not depend on anybody else. Whether the wrongness can
+reach you is a property of the program, and it turns on one thing: some caller
+has to omit the argument. If every call site passes an explicit value, the
+shared default is never the object being mutated and the bug sits there waiting
+for a caller who does not yet exist.
+
+Both facts are worth reporting, and they are different facts. So this produces a
+second verdict of its own and the first one stays visible underneath it.
+
+**Matching is by name, and it is deliberately generous.** Resolving ``x.send()``
+to a definition properly needs type inference, which this does not have. So a
+call is counted whenever the called name matches, wherever it appears. That
+over-matches: an unrelated ``send`` in another module is counted too. The
+over-matching is in the safe direction, because an extra caller can only ever
+add an omission and an omission is the answer that keeps the warning.
+
+**Everything unresolvable stays unresolved.** A ``**kwargs`` splat might be
+carrying the argument, a ``*args`` splat might be filling the position, and a
+function with no visible caller at all might be a public entry point that half
+the internet calls. None of those is evidence of safety, so each of them leaves
+the verdict where it was. The only thing that downgrades a warning here is a
+complete set of call sites that every one of them supplies the argument.
+"""
+
+import ast
+import os
+from collections import defaultdict
+from dataclasses import dataclass
+
+#: Directories that are never the project's own source. Scanning them wastes
+#: time and, worse, a vendored copy of the same function invents call sites the
+#: project does not have.
+SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".tox",
+        ".nox",
+        ".venv",
+        "venv",
+        "env",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "__pycache__",
+        "node_modules",
+        "site-packages",
+        "build",
+        "dist",
+    }
+)
+
+
+@dataclass(frozen=True)
+class Call:
+    """One call, remembered well enough to answer questions about its arguments."""
+
+    filename: str
+    line: int
+    node: ast.Call
+    attribute: bool  #: written as ``x.name(...)`` rather than ``name(...)``
+
+
+def python_files(root):
+    """Every ``.py`` file under ``root``, skipping the directories above."""
+    root = str(root)
+    if os.path.isfile(root):
+        yield root
+        return
+    for folder, subfolders, names in os.walk(root):
+        subfolders[:] = [d for d in subfolders if d not in SKIP_DIRS]
+        for name in names:
+            if name.endswith(".py"):
+                yield os.path.join(folder, name)
+
+
+def index(root):
+    """Map every called name under ``root`` to the calls that use it.
+
+    A file that cannot be read or parsed is skipped rather than fatal. The index
+    is a source of evidence, and missing evidence is already handled: it leaves
+    warnings where they are.
+    """
+    found = defaultdict(list)
+    for filename in python_files(root):
+        # Closed explicitly rather than left to the collector: this runs once
+        # per file across a whole source tree, and a few thousand open handles
+        # is its own kind of failure.
+        try:
+            with open(filename, encoding="utf-8") as handle:
+                tree = ast.parse(handle.read())
+        except (OSError, SyntaxError, ValueError, UnicodeDecodeError):
+            continue
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            callee = node.func
+            if isinstance(callee, ast.Name):
+                found[callee.id].append(Call(filename, node.lineno, node, False))
+            elif isinstance(callee, ast.Attribute):
+                found[callee.attr].append(Call(filename, node.lineno, node, True))
+    return found
+
+
+def position(fn, name):
+    """Where ``name`` sits in the signature, or None if it is keyword-only."""
+    positional = fn.args.posonlyargs + fn.args.args
+    for i, arg in enumerate(positional):
+        if arg.arg == name:
+            return i
+    return None
+
+
+def binds_self(fn):
+    """Does a bound call to this function consume the first parameter?
+
+    Reading the decorator list is enough here: ``staticmethod`` takes no
+    receiver, and ``classmethod`` takes one exactly as an instance method does.
+    A module-level function whose first parameter is called ``self`` would be
+    misread, which is rare enough to be worth the simplicity, and the misreading
+    lands on the conservative side.
+    """
+    first = (fn.args.posonlyargs + fn.args.args)[:1]
+    if not first or first[0].arg not in ("self", "cls"):
+        return False
+    for decorator in fn.decorator_list:
+        label = decorator.id if isinstance(decorator, ast.Name) else getattr(decorator, "attr", "")
+        if label == "staticmethod":
+            return False
+    return True
+
+
+def supplies(call, name, index_in_signature, drop_self):
+    """Does this call site pass the parameter? True, False, or None for unknown."""
+    for keyword in call.node.keywords:
+        if keyword.arg == name:
+            return True
+    if any(keyword.arg is None for keyword in call.node.keywords):
+        return None  # a **splat could be carrying it
+    if index_in_signature is None:
+        return False  # keyword-only, and no keyword of that name was given
+    if any(isinstance(arg, ast.Starred) for arg in call.node.args):
+        return None  # a *splat could be filling the position
+    wanted = index_in_signature - 1 if (drop_self and call.attribute) else index_in_signature
+    if wanted < 0:
+        return None
+    return len(call.node.args) > wanted
+
+
+@dataclass(frozen=True)
+class Reach:
+    """What the call sites collectively say about one parameter."""
+
+    supplying: int
+    omitting: tuple
+    unknown: tuple
+
+    @property
+    def total(self):
+        return self.supplying + len(self.omitting) + len(self.unknown)
+
+    @property
+    def unreachable(self):
+        """True only when every call site was resolved and all of them supply it."""
+        return self.total > 0 and not self.omitting and not self.unknown
+
+
+def reach(fn, name, calls):
+    """Read the call sites of ``fn`` for what they do with ``name``."""
+    sites = calls.get(fn.name, ())
+    where = position(fn, name)
+    drop_self = binds_self(fn)
+
+    supplying, omitting, unknown = 0, [], []
+    for site in sites:
+        answer = supplies(site, name, where, drop_self)
+        if answer is True:
+            supplying += 1
+        elif answer is False:
+            omitting.append(site)
+        else:
+            unknown.append(site)
+    return Reach(supplying, tuple(omitting), tuple(unknown))

willitbite/cli.py

@@ -0,0 +1,189 @@
+"""The command line: run ruff, decide every warning, report what can bite."""
+
+import argparse
+import ast
+import io
+import json
+import sys
+from collections import defaultdict
+
+from . import __version__, callsites, escape, mutation, ruffrun
+from .verdict import BITES, CALLEE, LATENT, ORDER, SAFE, Verdict
+
+ANALYSERS = {"B023": escape.analyse, "B006": mutation.analyse}
+
+RULE_TITLES = {
+    "B023": "closures capturing a loop variable",
+    "B006": "mutable default arguments",
+}
+
+
+def decide(findings, root=None):
+    """Attach a verdict to every finding, parsing each file once.
+
+    The call-site pass is a second look, not a first one. Reading every Python
+    file under ``root`` costs real time on a large tree, and it can only ever
+    change a B006 answer that already came back BITES, which on the codebases
+    this was built against was one warning in a hundred and thirty-three. So
+    the index is built only if there is something for it to decide, and a run
+    that finds nothing biting never pays for it at all.
+    """
+    by_file = defaultdict(list)
+    for finding in findings:
+        by_file[finding["filename"]].append(finding)
+
+    trees = {}
+    decided = []
+    for filename, group in by_file.items():
+        try:
+            source = io.open(filename, encoding="utf-8").read()
+            tree = ast.parse(source)
+        except (OSError, SyntaxError) as exc:
+            for finding in group:
+                decided.append({**finding, "verdict": Verdict(CALLEE, f"unreadable: {exc}")})
+            continue
+        trees[filename] = tree
+        parents = escape.parent_map(tree)
+        for finding in group:
+            analyse = ANALYSERS.get(finding["code"])
+            if analyse is None:
+                continue
+            decided.append(
+                {**finding, "verdict": analyse(tree, finding["line"], parents)}
+            )
+
+    if root is not None:
+        pending = [
+            row
+            for row in decided
+            if row["code"] == "B006" and row["verdict"].kind == BITES
+        ]
+        if pending:
+            calls = callsites.index(root)
+            for row in pending:
+                tree = trees.get(row["filename"])
+                if tree is None:
+                    continue
+                row["verdict"] = mutation.analyse(tree, row["line"], calls=calls)
+    return decided
+
+
+def _counts(rows):
+    tally = defaultdict(int)
+    for row in rows:
+        tally[row["verdict"].kind] += 1
+    return tally
+
+
+def render(decided, show_all=False):
+    """Human-readable report. Returns the lines."""
+    lines = []
+    by_rule = defaultdict(list)
+    for row in decided:
+        by_rule[row["code"]].append(row)
+
+    total_bites = 0
+    total_latent = 0
+    for code in sorted(by_rule):
+        rows = by_rule[code]
+        tally = _counts(rows)
+        total_bites += tally[BITES]
+        total_latent += tally[LATENT]
+        lines.append(f"{code}  {RULE_TITLES.get(code, '')}")
+        # The latent column is omitted when it is empty rather than printed as a
+        # permanent zero, since only B006 can produce one.
+        latent = f"{tally[LATENT]} latent   " if tally[LATENT] else ""
+        lines.append(
+            f"  {len(rows)} warning(s)   {tally[BITES]} can bite   {latent}"
+            f"{tally[CALLEE]} depend on a callee   {tally[SAFE]} safe"
+        )
+        wanted = ORDER if show_all else (BITES, LATENT, CALLEE)
+        for kind in wanted:
+            for row in sorted(rows, key=lambda r: (r["filename"], r["line"])):
+                if row["verdict"].kind != kind:
+                    continue
+                lines.append(f"    [{kind}] {row['filename']}:{row['line']}")
+                lines.append(f"           {row['verdict'].reason}")
+        lines.append("")
+
+    tail = f", {total_latent} latent" if total_latent else ""
+    if not decided:
+        lines.append("No B006 or B023 warnings found.")
+    elif total_bites == 0:
+        lines.append(
+            f"Nothing here can bite today. {len(decided)} warning(s), "
+            f"0 reachable defects{tail}."
+        )
+    else:
+        lines.append(
+            f"{total_bites} of {len(decided)} warning(s) can actually bite{tail}."
+        )
+    return lines
+
+
+def as_json(decided):
+    return json.dumps(
+        {
+            "warnings": len(decided),
+            "bites": sum(1 for r in decided if r["verdict"].kind == BITES),
+            "latent": sum(1 for r in decided if r["verdict"].kind == LATENT),
+            "results": [
+                {
+                    "code": r["code"],
+                    "filename": r["filename"],
+                    "line": r["line"],
+                    "verdict": r["verdict"].kind,
+                    "reason": r["verdict"].reason,
+                }
+                for r in decided
+            ],
+        },
+        indent=2,
+    )
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="willitbite",
+        description=(
+            "Decide which of ruff's loop-closure and mutable-default warnings "
+            "can actually reach you at runtime."
+        ),
+    )
+    parser.add_argument("path", nargs="?", default=".", help="file or directory to inspect")
+    parser.add_argument("--version", action="version", version=f"willitbite {__version__}")
+    parser.add_argument(
+        "--json", dest="json_in", metavar="FILE",
+        help="read ruff's JSON output from FILE instead of running ruff",
+    )
+    parser.add_argument("--json-out", action="store_true", help="print results as JSON")
+    parser.add_argument("--all", action="store_true", help="list the safe warnings too")
+    parser.add_argument(
+        "--exit-zero", action="store_true",
+        help="always exit 0, even when something can bite",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.json_in:
+            findings = ruffrun.parse(io.open(args.json_in, encoding="utf-8").read())
+        else:
+            findings = ruffrun.run(args.path)
+    except (ruffrun.RuffMissing, RuntimeError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    decided = decide(findings, root=args.path)
+
+    if args.json_out:
+        print(as_json(decided))
+    else:
+        print("\n".join(render(decided, show_all=args.all)))
+
+    if args.exit_zero:
+        return 0
+    return 1 if any(r["verdict"].kind == BITES for r in decided) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

willitbite/escape.py

@@ -0,0 +1,215 @@
+"""B023: does a closure that captures a loop variable outlive its iteration?
+
+Ruff flags every closure inside a loop that reads the loop variable. That is a
+description of a shape, not of a bug. The bug is late binding: if the closure is
+still callable after the loop moves on, every copy of it sees the loop
+variable's final value. If the closure is built and consumed inside the same
+iteration, it sees the value it was written next to.
+
+So the question here is never "does it capture". Ruff answered that. It is
+"can this closure still be called once the loop variable has changed".
+
+For a nested ``def NAME``, the evidence is what the loop body does with NAME:
+
+    every reference is ``NAME(...)``          -> SAFE, it runs in its own iteration
+    a bare reference that is stored           -> BITES
+    a bare reference passed to ``f(NAME)``    -> CALLEE, depends on f
+
+For a ``lambda``, the evidence is the construct that owns it: an argument to
+``sorted`` runs now; ``.append`` and ``functools.partial`` keep it for later.
+"""
+
+import ast
+
+from .verdict import BITES, CALLEE, SAFE, Verdict
+
+LOOPS = (ast.For, ast.AsyncFor, ast.While)
+
+#: Builtins that call the closure and drop it before the expression finishes.
+CONSUMING = frozenset(
+    {"sorted", "min", "max", "sum", "any", "all", "sort", "nlargest", "nsmallest"}
+)
+
+#: Builtins that return a lazy iterator holding the closure. Safe only if the
+#: result is consumed in the same iteration, which is a separate question.
+LAZY = frozenset({"map", "filter", "groupby"})
+
+#: Attribute calls whose whole purpose is to keep the callable for later.
+KEEPING_ATTRS = frozenset(
+    {
+        "append",
+        "add",
+        "insert",
+        "extend",
+        "submit",
+        "apply_async",
+        "put",
+        "add_done_callback",
+        "connect",
+        "register",
+        "subscribe",
+        "schedule",
+        "create_task",
+        "run_in_executor",
+        "call_later",
+        "call_soon",
+        "setdefault",
+    }
+)
+
+#: Constructors and helpers that store the callable in the object they return.
+KEEPING_CALLS = frozenset(
+    {"partial", "Thread", "Timer", "Process", "create_task", "ensure_future"}
+)
+
+
+def parent_map(tree):
+    """Map every node to its parent. ast exposes children only."""
+    parents = {}
+    for node in ast.walk(tree):
+        for child in ast.iter_child_nodes(node):
+            parents[child] = node
+    return parents
+
+
+def innermost_closure(tree, line):
+    """The lambda or def enclosing ``line``, innermost when several do.
+
+    Ruff points at the captured name, not at the closure, so the closure has to
+    be found by span. The one that starts latest is the innermost.
+    """
+    holding = [
+        n
+        for n in ast.walk(tree)
+        if isinstance(n, (ast.Lambda, ast.FunctionDef, ast.AsyncFunctionDef))
+        and n.lineno <= line <= getattr(n, "end_lineno", n.lineno)
+    ]
+    return max(holding, key=lambda n: n.lineno) if holding else None
+
+
+def enclosing_loop(node, parents):
+    cur = node
+    while cur in parents:
+        cur = parents[cur]
+        if isinstance(cur, LOOPS):
+            return cur
+    return None
+
+
+def _callee_name(call):
+    fn = call.func
+    if isinstance(fn, ast.Name):
+        return fn.id
+    if isinstance(fn, ast.Attribute):
+        return fn.attr
+    return None
+
+
+def classify_def(fn, loop, parents):
+    """A nested def: what does the loop body do with its name?"""
+    if loop is None:
+        return Verdict(CALLEE, f"`{fn.name}` is not inside a loop in this file")
+
+    name = fn.name
+    called = 0
+    stored = []
+    passed = []
+    for node in ast.walk(loop):
+        if not isinstance(node, ast.Name) or node.id != name:
+            continue
+        if not isinstance(node.ctx, ast.Load):
+            continue
+        up = parents.get(node)
+        if isinstance(up, ast.Call) and up.func is node:
+            called += 1
+        elif isinstance(up, ast.Call):
+            passed.append(_callee_name(up) or "a call")
+        else:
+            stored.append(type(up).__name__)
+
+    if stored:
+        where = ", ".join(sorted(set(stored)))
+        return Verdict(
+            BITES,
+            f"`{name}` is stored rather than called ({where}), so it can run "
+            f"after the loop variable has changed",
+        )
+    keepers = sorted({p for p in passed if p in KEEPING_ATTRS or p in KEEPING_CALLS})
+    if keepers:
+        who = ", ".join(keepers)
+        return Verdict(
+            BITES,
+            f"`{name}` is stored rather than called: it is handed to {who}(), "
+            f"which keeps it past the end of the iteration",
+        )
+    if passed:
+        runners = {p for p in passed if p in CONSUMING}
+        rest = sorted(set(passed) - runners)
+        if not rest:
+            who = ", ".join(sorted(runners))
+            return Verdict(
+                SAFE, f"`{name}` is only ever an argument to {who}(), which runs it now"
+            )
+        who = ", ".join(rest)
+        return Verdict(
+            CALLEE,
+            f"`{name}` is handed to {who}(), so it bites only if {who} keeps it "
+            f"instead of calling it",
+        )
+    if called:
+        return Verdict(
+            SAFE,
+            f"`{name}` is only ever called directly, {called} time(s) in the "
+            f"same iteration",
+        )
+    return Verdict(
+        BITES,
+        f"`{name}` is never used inside the loop, so whatever holds it outlives "
+        f"the iteration",
+    )
+
+
+def classify_lambda(node, parents):
+    """A lambda: which construct owns it?"""
+    cur = node
+    while cur in parents:
+        up = parents[cur]
+        if isinstance(up, (ast.Assign, ast.AnnAssign, ast.NamedExpr)):
+            return Verdict(BITES, "the lambda is bound to a name, so it is called later")
+        if isinstance(up, (ast.Dict, ast.List, ast.Set, ast.Tuple)):
+            return Verdict(BITES, "the lambda is stored in a container")
+        if isinstance(up, ast.Return):
+            return Verdict(BITES, "the lambda is returned out of the function")
+        if isinstance(up, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+            return Verdict(BITES, "the lambda is collected by a comprehension")
+        if isinstance(up, ast.Call):
+            name = _callee_name(up)
+            if name in KEEPING_ATTRS or name in KEEPING_CALLS:
+                return Verdict(BITES, f"the lambda is handed to {name}(), which keeps it")
+            if name in CONSUMING:
+                return Verdict(
+                    SAFE, f"the lambda is an argument to {name}(), which runs it now"
+                )
+            if name in LAZY:
+                return Verdict(
+                    CALLEE,
+                    f"the lambda is an argument to {name}(), which is lazy, so it is "
+                    f"safe only if the result is consumed in this iteration",
+                )
+            return Verdict(
+                CALLEE,
+                f"the lambda is handed to {name}(), so it bites only if {name} keeps it",
+            )
+        cur = up
+    return Verdict(CALLEE, "the owning construct could not be identified")
+
+
+def analyse(tree, line, parents=None):
+    """Decide one B023 warning reported at ``line``."""
+    parents = parent_map(tree) if parents is None else parents
+    closure = innermost_closure(tree, line)
+    if closure is None:
+        return Verdict(CALLEE, "no closure found at this line")
+    if isinstance(closure, ast.Lambda):
+        return classify_lambda(closure, parents)
+    return classify_def(closure, enclosing_loop(closure, parents), parents)

willitbite/mutation.py

@@ -0,0 +1,268 @@
+"""B006: is a mutable default argument ever actually mutated?
+
+A mutable default is evaluated once, at definition time, and shared by every
+call that omits the argument. That is only a bug when the function changes it,
+because the change is then visible to the next caller. A default that is only
+read behaves exactly like the immutable one the author probably imagined.
+
+So the decisive question is mutation, and there is one trap in asking it. A
+great many functions open with ``items = items or []`` or ``items = list(items)``,
+which rebinds the name to a fresh object before anything is appended. The shared
+default is never touched. Mutation that happens after a rebind is mutation of
+the new object, so position matters and a plain "does the name appear on the
+left of an append" is not enough.
+"""
+
+import ast
+
+from .callsites import reach
+from .verdict import BITES, CALLEE, LATENT, SAFE, Verdict
+
+#: Methods that change the receiver in place.
+MUTATORS = frozenset(
+    {
+        "append",
+        "extend",
+        "insert",
+        "add",
+        "update",
+        "setdefault",
+        "pop",
+        "popitem",
+        "remove",
+        "clear",
+        "sort",
+        "discard",
+    }
+)
+
+#: Calls that cannot change what they are given: they either only read it, or
+#: they build a new object from it. Passing the default to one of these is not
+#: an escape, so they must be excluded or every read looks like a risk.
+NON_MUTATING = frozenset(
+    {
+        # build a copy
+        "list", "dict", "set", "tuple", "frozenset", "copy", "deepcopy", "sorted",
+        # read only
+        "len", "any", "all", "sum", "min", "max", "enumerate", "iter", "reversed",
+        "bool", "str", "repr", "print", "isinstance", "join", "format", "next",
+    }
+)
+
+#: Factories that produce a mutable object, so ``x=dict()`` is as shared as ``x={}``.
+MUTABLE_FACTORIES = frozenset(
+    {"list", "dict", "set", "defaultdict", "Counter", "OrderedDict", "deque"}
+)
+
+
+def mutable_defaults(fn):
+    """Parameter names whose default is a mutable object.
+
+    Ruff reports the offending default's position, but recovering the parameter
+    name from that is fiddlier than reading the signature directly, and the
+    signature is what a reader checks the verdict against.
+    """
+    if not isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return []
+
+    args = fn.args
+    names = []
+
+    positional = args.posonlyargs + args.args
+    if args.defaults:
+        paired = zip(positional[len(positional) - len(args.defaults) :], args.defaults)
+        for arg, default in paired:
+            if _is_mutable(default):
+                names.append(arg.arg)
+
+    for arg, default in zip(args.kwonlyargs, args.kw_defaults):
+        if default is not None and _is_mutable(default):
+            names.append(arg.arg)
+
+    return names
+
+
+def _is_mutable(node):
+    if isinstance(node, (ast.List, ast.Dict, ast.Set)):
+        return True
+    if isinstance(node, ast.Call):
+        fn = node.func
+        name = fn.id if isinstance(fn, ast.Name) else getattr(fn, "attr", "")
+        return name in MUTABLE_FACTORIES
+    return False
+
+
+def _rebind_line(fn, name):
+    """First line where ``name`` is assigned, or None.
+
+    After a rebind the name refers to a new object, so anything done to it from
+    that point on cannot reach the shared default.
+    """
+    augmented = {
+        node.target
+        for node in ast.walk(fn)
+        if isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name)
+    }
+    lines = [
+        node.lineno
+        for node in ast.walk(fn)
+        if isinstance(node, ast.Name)
+        and node.id == name
+        and isinstance(node.ctx, ast.Store)
+        # ``items += [1]`` on a list calls __iadd__, which extends in place. It
+        # is a Store node but it does not produce a new object, so counting it
+        # as a rebind would hide the very mutation it performs.
+        and node not in augmented
+    ]
+    return min(lines) if lines else None
+
+
+def _mutations(fn, name):
+    """Every in-place change to ``name``, as (line, description)."""
+    found = []
+    for node in ast.walk(fn):
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            receiver = node.func.value
+            if isinstance(receiver, ast.Name) and receiver.id == name:
+                if node.func.attr in MUTATORS:
+                    found.append((node.lineno, f"{name}.{node.func.attr}()"))
+        elif isinstance(node, ast.Subscript) and isinstance(node.value, ast.Name):
+            if node.value.id == name and isinstance(node.ctx, (ast.Store, ast.Del)):
+                verb = "assigned" if isinstance(node.ctx, ast.Store) else "deleted"
+                found.append((node.lineno, f"{name}[...] {verb}"))
+        elif isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name):
+            if node.target.id == name:
+                found.append((node.lineno, f"{name} += ..."))
+    return found
+
+
+def _escapes_unchanged(fn, name):
+    """Is the default handed to something that could keep or mutate it?
+
+    A default that is only read inside the function can still be mutated a frame
+    down if it is passed on by reference. Calls that provably cannot change it
+    are excluded, or every ``len(items)`` would look like a risk.
+    """
+    for node in ast.walk(fn):
+        if not isinstance(node, ast.Call):
+            continue
+        callee = node.func
+        callee_name = (
+            callee.id if isinstance(callee, ast.Name) else getattr(callee, "attr", None)
+        )
+        if callee_name in NON_MUTATING:
+            continue
+        for arg in node.args:
+            if isinstance(arg, ast.Name) and arg.id == name:
+                return callee_name or "a call"
+        for kw in node.keywords:
+            if isinstance(kw.value, ast.Name) and kw.value.id == name:
+                return callee_name or "a call"
+    return None
+
+
+def _reaching_mutations(fn, name):
+    """The mutations that touch the shared default, and the rebind line if any."""
+    rebound = _rebind_line(fn, name)
+    mutations = _mutations(fn, name)
+    return [m for m in mutations if rebound is None or m[0] < rebound], rebound, mutations
+
+
+def _defect_clause(name, reaching):
+    """The half of the reason that describes the defect itself.
+
+    Shared by BITES and LATENT so the two answers never drift into describing
+    the same defect differently. Only what follows this clause changes.
+    """
+    where = ", ".join(f"{what} on line {line}" for line, what in sorted(reaching))
+    return f"`{name}` is mutated before it is rebound ({where})"
+
+
+def analyse_param(fn, name):
+    """Decide one parameter of one function, from its body alone."""
+    reaching, rebound, mutations = _reaching_mutations(fn, name)
+
+    if reaching:
+        return Verdict(
+            BITES,
+            f"{_defect_clause(name, reaching)}, so every call that omits it sees "
+            f"the previous call's changes",
+        )
+
+    if rebound is not None:
+        detail = " before any mutation" if mutations else ""
+        return Verdict(
+            SAFE,
+            f"`{name}` is rebound on line {rebound}{detail}, so the shared default "
+            f"is never touched",
+        )
+
+    escapee = _escapes_unchanged(fn, name)
+    if escapee:
+        return Verdict(
+            CALLEE,
+            f"`{name}` is never mutated here but is passed to {escapee}(), which "
+            f"could mutate it a frame down",
+        )
+
+    return Verdict(SAFE, f"`{name}` is never mutated, so sharing it is harmless")
+
+
+def _with_call_sites(fn, name, verdict, calls):
+    """Ask the callers whether the defect in ``fn`` can currently fire.
+
+    Only a complete answer changes anything. If every call site was resolved and
+    every one of them passes the argument, the shared default is never the
+    object being mutated and the defect is waiting rather than happening. Any
+    other shape leaves the verdict alone: an unresolved splat, a caller that
+    omits it, or no caller at all are each a reason to keep looking, not a
+    reason to clear it.
+    """
+    if calls is None:
+        return verdict
+
+    found = reach(fn, name, calls)
+    reaching, _, _ = _reaching_mutations(fn, name)
+    clause = _defect_clause(name, reaching)
+
+    if found.total == 0:
+        return Verdict(
+            BITES,
+            f"{clause}, and no call site of `{fn.name}()` was found under this path, "
+            f"so nothing here shows that callers pass it",
+        )
+    if found.unreachable:
+        plural = "" if found.total == 1 else "s"
+        return Verdict(
+            LATENT,
+            f"{clause}, but all {found.total} call site{plural} of `{fn.name}()` pass "
+            f"it explicitly, so the shared default is never the one being changed",
+        )
+    return verdict
+
+
+def analyse(tree, line, parents=None, calls=None):
+    """Decide one B006 warning reported at ``line``.
+
+    ``calls`` is the optional call index from :mod:`willitbite.callsites`.
+    Without it the answer is about the function; with it the answer is about
+    the program, which is a strictly narrower and more useful claim.
+    """
+    from .escape import innermost_closure
+
+    fn = innermost_closure(tree, line)
+    if fn is None or isinstance(fn, ast.Lambda):
+        return Verdict(CALLEE, "no function definition found at this line")
+
+    names = mutable_defaults(fn)
+    if not names:
+        return Verdict(CALLEE, f"no mutable default found in the signature of `{fn.name}`")
+
+    decided = [(n, analyse_param(fn, n)) for n in names]
+    for name, verdict in decided:
+        if verdict.kind == BITES:
+            return _with_call_sites(fn, name, verdict, calls)
+    for _, verdict in decided:
+        if verdict.kind == CALLEE:
+            return verdict
+    return decided[0][1]

willitbite/ruffrun.py

@@ -0,0 +1,102 @@
+"""Get the warnings from ruff, or from a file ruff already wrote.
+
+This does not reimplement the rules. Ruff decides what is a candidate and does
+it faster and more correctly than a hand-rolled matcher would; the value here is
+entirely in what happens to the list afterwards. Two consequences follow.
+
+Ruff is invoked with ``--isolated`` so the answer does not depend on whether the
+project being inspected happens to enable these rules. A team that has not
+adopted B006 and B023 yet is exactly the team that wants this, and their config
+would otherwise return nothing.
+
+Ruff is not a dependency. It is looked up as a subprocess and its absence is
+reported as the ordinary situation it is, with the ``--json`` route available
+for anyone who would rather run their own ruff and pipe the result in.
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+
+#: The rules this tool can decide. Adding one means adding an analyser.
+SUPPORTED = ("B006", "B023")
+
+
+class RuffMissing(RuntimeError):
+    """ruff is not on PATH."""
+
+
+def ruff_available():
+    return shutil.which("ruff") is not None or _module_available()
+
+
+def _module_available():
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "ruff", "--version"],
+            capture_output=True,
+            check=True,
+        )
+        return True
+    except (subprocess.CalledProcessError, OSError):
+        return False
+
+
+def _ruff_command():
+    if shutil.which("ruff"):
+        return ["ruff"]
+    if _module_available():
+        return [sys.executable, "-m", "ruff"]
+    raise RuffMissing(
+        "ruff was not found. Install it with `pip install ruff`, or run ruff "
+        "yourself and pass its output with --json."
+    )
+
+
+def run(path, rules=SUPPORTED):
+    """Run ruff over ``path`` and return its findings for ``rules``."""
+    command = _ruff_command() + [
+        "check",
+        # The project's own configuration is deliberately ignored: the people
+        # who need this are the ones who have not enabled these rules yet.
+        "--isolated",
+        "--select",
+        ",".join(rules),
+        "--output-format",
+        "json",
+        str(path),
+    ]
+    # A non-zero exit only means ruff found something, which is the normal case
+    # here, so the return code is not checked. A real failure shows up as
+    # unparseable output and is reported as that.
+    finished = subprocess.run(command, capture_output=True, text=True)
+    if not finished.stdout.strip():
+        if finished.returncode not in (0, 1):
+            raise RuntimeError(finished.stderr.strip() or "ruff failed")
+        return []
+    return parse(finished.stdout)
+
+
+def parse(text):
+    """Parse ruff's JSON output into the shape the analysers want."""
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"could not read ruff output as JSON: {exc}") from exc
+
+    findings = []
+    for item in raw:
+        code = item.get("code")
+        if code not in SUPPORTED:
+            continue
+        location = item.get("location") or {}
+        findings.append(
+            {
+                "code": code,
+                "filename": item.get("filename", ""),
+                "line": location.get("row", 0),
+                "message": item.get("message", ""),
+            }
+        )
+    return findings

willitbite/verdict.py

@@ -0,0 +1,50 @@
+"""The answers this tool gives, and why there are more than two.
+
+A linter has two states, warned and silent. Reachability needs more, because
+twice over the honest answer is neither.
+
+CALLEE exists because deciding whether a closure escapes sometimes depends on a
+function this tool cannot see into. LATENT exists because a function can be
+genuinely wrong and still be unreachable: a mutable default that the function
+mutates is a defect, but it only fires when some caller omits the argument, and
+sometimes no caller does. Collapsing either case into "safe" or "bites" would be
+a guess presented as an answer, so each gets its own verdict and names the thing
+the reader has to look at.
+"""
+
+from dataclasses import dataclass
+
+BITES = "BITES"
+LATENT = "LATENT"
+SAFE = "SAFE"
+CALLEE = "CALLEE"
+
+#: Report order: the reader wants the actionable ones first.
+ORDER = (BITES, LATENT, CALLEE, SAFE)
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """One warning, decided.
+
+    kind:   BITES, LATENT, CALLEE or SAFE.
+    reason: a sentence a reader can check against the source without rerunning
+            anything. Never a restatement of the rule.
+    """
+
+    kind: str
+    reason: str
+
+    @property
+    def actionable(self) -> bool:
+        """Can this reach you as the code stands today?
+
+        LATENT is deliberately excluded. It is a real defect and it is reported
+        as one, but nothing calls it in a way that triggers it, so failing a
+        build on it would fail every build until somebody rewrote code that
+        currently works.
+        """
+        return self.kind == BITES
+
+    def __str__(self) -> str:
+        return f"{self.kind}: {self.reason}"

willitbite-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: willitbite
+Version: 0.1.0
+Summary: Tell which of ruff's loop-closure and mutable-default warnings can actually reach you at runtime
+Project-URL: Homepage, https://github.com/muhzuhaib/willitbite
+Project-URL: Issues, https://github.com/muhzuhaib/willitbite/issues
+Project-URL: Changelog, https://github.com/muhzuhaib/willitbite/blob/main/CHANGELOG.md
+Author: Muhammad Zuhaib Zahid
+License: MIT License
+        
+        Copyright (c) 2026 Muhammad Zuhaib Zahid
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,linting,python,ruff,static-analysis,triage
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# willitbite
+
+[![CI](https://github.com/muhzuhaib/willitbite/actions/workflows/ci.yml/badge.svg)](https://github.com/muhzuhaib/willitbite/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/willitbite.svg)](https://pypi.org/project/willitbite/)
+
+Ruff will tell you that 99 closures in your codebase capture a loop variable. It will not tell you
+that none of them can actually bite you.
+
+`willitbite` takes the two rules that produce most of the noise when a project first adopts ruff and
+asks the question the linter cannot: **can this one reach you at runtime?**
+
+Here it is on [ragflow](https://github.com/infiniflow/ragflow), 1,259 files of Python, at commit
+`0c28d59`:
+
+```
+$ willitbite .
+B006  mutable default arguments
+  34 warning(s)   0 can bite   1 latent   13 depend on a callee   20 safe
+    [LATENT] agent/component/message.py:159
+             `kwargs` is mutated before it is rebound (kwargs[...] assigned on line
+             181), but all 2 call sites of `get_kwargs()` pass it explicitly, so the
+             shared default is never the one being changed
+
+B023  closures capturing a loop variable
+  99 warning(s)   0 can bite   15 depend on a callee   84 safe
+
+Nothing here can bite today. 133 warning(s), 0 reachable defects, 1 latent.
+```
+
+133 warnings, ten seconds, and 29 of them are worth a person's time: the one latent
+defect and the 28 that turn on a function the tool cannot see into. The other 104 need nobody.
+
+## Why this exists
+
+Both rules describe a shape, and the shape is not the bug.
+
+**B023** flags every closure inside a loop that reads the loop variable. The bug it is looking for is
+late binding: if the closure is still callable after the loop moves on, every copy sees the loop
+variable's final value. A closure that is built and called inside the same iteration sees the value
+it was written next to, which is what the author meant.
+
+**B006** flags every mutable default argument. A mutable default is evaluated once and shared by
+every call that omits it, but that only matters if the function changes it. A default that is only
+read behaves exactly like the immutable one the author probably had in mind.
+
+So a team switching these rules on faces a few hundred warnings, most of which are fine, with no way
+to tell which is which except by reading all of them. That is the job this does.
+
+## Install and run
+
+```
+pip install willitbite
+willitbite ./src
+```
+
+Python 3.10 or newer. To work from a checkout instead:
+
+```
+git clone https://github.com/muhzuhaib/willitbite
+pip install ./willitbite
+```
+
+Ruff is called as a subprocess if it is on your PATH. If you would rather run your own:
+
+```
+ruff check --select B006,B023 --output-format json ./src > warnings.json
+willitbite --json warnings.json
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--all` | list the safe warnings too, not just the actionable ones |
+| `--json-out` | print results as JSON |
+| `--exit-zero` | always exit 0, for a first run that should not fail a build |
+
+Exit code is 1 when something can bite, 0 when nothing can, 2 when the tool could not run.
+
+## Design decisions
+
+**A linter has two states, warned and silent. This has four.** Two of the four exist because the
+honest answer is sometimes neither of the other two.
+
+`CALLEE` is for a closure handed to `run_with_retry(...)`, which is safe if that helper calls it and
+dangerous if it stores it. Guessing safe would clear a real defect. Guessing unsafe would raise a
+false alarm on every codebase this was built against. So it names the function you have to look at
+and stops there.
+
+`LATENT` is for a function that is genuinely wrong and that nothing currently calls in the way that
+would hurt. It has its own section below.
+
+**Ruff finds the candidates; this decides them.** Reimplementing the rules would be slower, less
+correct, and would drift from ruff's behaviour. Ruff is invoked with `--isolated` on purpose, so the
+answer does not depend on whether the project has enabled these rules: a team that has not adopted
+them yet is exactly the team that wants this.
+
+**Ruff is not a dependency.** A tool that reports on your linter should not pin a version of it.
+
+**Every verdict carries a reason you can check without rerunning anything.** The reason names the
+identifier and the line, never restates the rule. A verdict you have to take on trust is worth about
+as much as the warning it replaced.
+
+## Latent defects: real, but nothing calls them that way
+
+A function that mutates its own mutable default is wrong on its own terms. Whether the wrongness can
+reach you is a separate question, and it is answered in the callers: the shared default is only ever
+the object being mutated when somebody omits the argument.
+
+So B006 warnings that survive the first pass get a second one, across every `.py` file under the
+path you gave. If some caller omits the argument, the verdict stays `BITES`. If every caller passes
+it explicitly, the verdict becomes `LATENT`: still a defect, still reported, but nothing in the tree
+triggers it today.
+
+```
+B006  mutable default arguments
+  2 warning(s)   1 can bite   1 latent   0 depend on a callee   0 safe
+    [BITES] live.py:1
+           `cache` is mutated before it is rebound (cache[...] assigned on line 2),
+           so every call that omits it sees the previous call's changes
+    [LATENT] lib.py:1
+           `items` is mutated before it is rebound (items.append() on line 2), but all
+           2 call sites of `collect()` pass it explicitly, so the shared default is
+           never the one being changed
+```
+
+Those two functions have the same shape. Only their callers differ.
+
+**A latent defect does not fail the build.** The exit code answers "can this bite today", and this
+one cannot, so failing on it would fail every build until somebody rewrote code that currently
+works. It is in the report because it will bite the first caller who leaves the argument out.
+
+## Known boundary: which callers get matched
+
+Call sites are matched **by name**. Resolving `x.send()` to a definition properly needs type
+inference, which this does not do, so a call counts whenever the called name matches, wherever it
+appears. That over-matches, and the over-matching is deliberate: an unrelated `send` elsewhere can
+only add an omission, and an omission is the answer that keeps the warning.
+
+Three things count as no evidence at all, and each of them leaves a warning at `BITES`:
+
+- a `**kwargs` splat at the call site, which might be carrying the argument
+- a `*args` splat, which might be filling the position
+- **no caller anywhere**, which usually means a public entry point called from outside the tree you
+  scanned, and is the case most likely to bite a stranger
+
+The index is only built when something came back `BITES`, so a run that finds nothing reachable
+never pays for the scan.
+
+## Where this came from
+
+It was written while triaging 138 ruff warnings across two large open-source Python codebases by
+hand. All 99 loop-closure warnings turned out to be false alarms, as did every mutable-default
+warning that was actually reachable. Reading them one at a time to learn that took most of a day,
+which seemed like a poor way to spend the next one.
+
+## License
+
+MIT

willitbite-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+willitbite/__init__.py,sha256=FUpJ5MNR6noX2iHBhedkhyY9nVUQpvGv_PrKJc8NWkw,91
+willitbite/callsites.py,sha256=lMhP8WryZ_-VEW2PZ_UVDwXPrJMLGYfbPnCHNUrkS3k,6905
+willitbite/cli.py,sha256=i7zcjFtCKQsRK8rcELpXK2jMQ74Af7KmyiBpONoAdwY,6424
+willitbite/escape.py,sha256=z2pApKQafp--FblwzgSyEnNWl7sON3r6Mg9ONWA0nLU,7578
+willitbite/mutation.py,sha256=RRboicC-T5m_gAcFKEi09o-biC1E2kvMYtMs3PJOyYk,9818
+willitbite/ruffrun.py,sha256=jNzk6DVkhw7TcNmdLnvPeg5GQeA_ycn9dWf-ceygR3o,3322
+willitbite/verdict.py,sha256=zjEnrwSa--SLcq3rnOlholue92R03uIFun3RFB9Dvcw,1667
+willitbite-0.1.0.dist-info/METADATA,sha256=AMCHzdI17OTMZjqZkiUVMnPiRpOGdzymN-f_SmHEqtw,9487
+willitbite-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+willitbite-0.1.0.dist-info/entry_points.txt,sha256=W0qIMfC-7u2cL8lG6wel2vQheL7kCUdr7T-h3bB1Xm4,51
+willitbite-0.1.0.dist-info/licenses/LICENSE,sha256=18n8-_Lz8Si5JYibyhHrPuKT21C1_-muoU4gmhOWouc,1078
+willitbite-0.1.0.dist-info/RECORD,,

willitbite-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

willitbite-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+willitbite = willitbite.cli:main

willitbite-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Zuhaib Zahid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.