errpath 0.1.0__py3-none-any.whl

errpath/analyse.py

@@ -0,0 +1,1035 @@
+"""AST walker: Python Result railways → Report IR."""
+
+from __future__ import annotations
+
+import ast
+import builtins
+from collections.abc import Iterable, Iterator
+from dataclasses import replace
+from pathlib import Path
+from typing import TypeGuard
+
+from errpath.ir import (
+    CATCH_ANY,
+    NO_PANIC,
+    NO_SWALLOW,
+    SCHEMA_VERSION,
+    Arm,
+    Block,
+    Branch,
+    Catch,
+    Confidence,
+    Coverage,
+    ErrorSource,
+    Fail,
+    Finding,
+    Function,
+    Jump,
+    Loop,
+    Node,
+    Panic,
+    ParseFailure,
+    Recover,
+    Report,
+    Returns,
+    ReturnsOther,
+    ReturnsResult,
+    Scope,
+    Step,
+    Succeed,
+    Swallow,
+    Unanalysed,
+    error_members,
+    escaping,
+)
+
+_TryNode = ast.Try | ast.TryStar  # try/except* has the same fields as try/except
+
+
+def _ann_name(node: ast.expr | None) -> str | None:
+    if node is None:
+        return None
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _subscript_args(node: ast.expr) -> list[ast.expr]:
+    if not isinstance(node, ast.Subscript):
+        return []
+    sl = node.slice
+    if isinstance(sl, ast.Tuple):
+        return list(sl.elts)
+    return [sl]
+
+
+def _error_name(node: ast.expr) -> str:
+    """Error type annotation as ``A | B``: also for ``Union[A, B]`` and ``mod.A | mod.B``."""
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+        return f"{_error_name(node.left)} | {_error_name(node.right)}"
+    if isinstance(node, ast.Subscript) and _ann_name(node.value) == "Union":
+        return " | ".join(_error_name(arg) for arg in _subscript_args(node))
+    return _ann_name(node) or ast.unparse(node)
+
+
+def parse_returns(annotation: ast.expr | None) -> Returns:
+    if annotation is None:
+        return ReturnsOther()
+    # Result[T, E] or errpath.Result[T, E]
+    if isinstance(annotation, ast.Subscript):
+        base = _ann_name(annotation.value)
+        if base == "Result":
+            args = _subscript_args(annotation)
+            if len(args) >= 2:
+                err = _error_name(args[1])
+                return ReturnsResult(error=err)
+            return ReturnsResult(error="Exception")
+    name = _ann_name(annotation)
+    if name == "Result":
+        return ReturnsResult(error="Exception")
+    return ReturnsOther()
+
+
+def _call_name(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Call):
+        return _call_name(node.func)
+    return None
+
+
+def _unawait(node: ast.expr) -> ast.expr:
+    return node.value if isinstance(node, ast.Await) else node
+
+
+def _attr_root(node: ast.expr) -> ast.expr:
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return node
+
+
+def _imported_names(tree: ast.AST) -> set[str]:
+    """Names bound by imports; ``mod.f()`` is only a Result call when ``mod`` is one of them."""
+    out: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            out.update(a.asname or a.name.split(".")[0] for a in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            out.update(a.asname or a.name for a in node.names)
+    return out
+
+
+def _is_unwrap_call(node: ast.expr) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "unwrap"
+        and not node.args
+        and not node.keywords
+    )
+
+
+def _unwrap_receiver(node: ast.Call) -> ast.expr | None:
+    if isinstance(node.func, ast.Attribute):
+        return node.func.value
+    return None
+
+
+def _is_ok_call(node: ast.expr) -> bool:
+    return isinstance(node, ast.Call) and _call_name(node) == "Ok"
+
+
+def _is_err_call(node: ast.expr) -> bool:
+    return isinstance(node, ast.Call) and _call_name(node) == "Err"
+
+
+def _err_ctor_name(node: ast.expr) -> str:
+    """Best-effort error type name from ``Err(...)`` or ``Err(Foo(...))``."""
+    if not isinstance(node, ast.Call) or not node.args:
+        return "Error"
+    arg = node.args[0]
+    name = _call_name(arg) if isinstance(arg, ast.Call) else _ann_name(arg)
+    return name or "Error"
+
+
+class _SignatureCollector(ast.NodeVisitor):
+    """First pass: map callee name → error type from Result return.
+
+    Functions are keyed by bare name, methods by ``.name``, so ``d.update()``
+    only matches a Result-returning method, never a function called ``update``.
+    """
+
+    def __init__(self) -> None:
+        self.signatures: dict[str, str] = {}
+        self.bases: dict[str, list[str]] = {}
+        self._in_class = False
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.bases[node.name] = [n for n in map(_ann_name, node.bases) if n]
+        prev = self._in_class
+        self._in_class = True
+        self.generic_visit(node)
+        self._in_class = prev
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._record(node)
+        self._visit_body(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._record(node)
+        self._visit_body(node)
+
+    def _visit_body(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        prev = self._in_class
+        self._in_class = False  # functions nested in a method are plain functions
+        self.generic_visit(node)
+        self._in_class = prev
+
+    def _record(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        returns = parse_returns(node.returns)
+        # @safe_with(A, B) makes any function return Result[..., A | B]
+        error = returns.error if isinstance(returns, ReturnsResult) else _safe_error(node)
+        if error is not None:
+            key = f".{node.name}" if self._in_class else node.name
+            self.signatures[key] = error
+
+
+def _collect(tree: ast.AST) -> _SignatureCollector:
+    collector = _SignatureCollector()
+    collector.visit(tree)
+    return collector
+
+
+_CATCH_ALL = {"BaseException"}  # `except Exception` misses KeyboardInterrupt, SystemExit, ...
+
+
+def _is_subclass(error: str, target: str, bases: dict[str, list[str]]) -> bool:
+    """``error`` is ``target`` or inherits from it, via user classes or builtin exceptions."""
+    target_cls = getattr(builtins, target, None)
+    todo, seen = [error], set()
+    while todo:
+        name = todo.pop()
+        if name == target:
+            return True
+        if name in seen:
+            continue
+        seen.add(name)
+        cls = getattr(builtins, name, None)
+        if isinstance(cls, type) and isinstance(target_cls, type) and issubclass(cls, target_cls):
+            return True
+        todo.extend(bases.get(name, []))
+    return False
+
+
+def _outside_exception(error: str, bases: dict[str, list[str]]) -> bool:
+    """Known to derive from BaseException but not Exception (KeyboardInterrupt, SystemExit, ...)."""
+    todo, seen = [error], set()
+    while todo:
+        name = todo.pop()
+        if name in seen:
+            continue
+        seen.add(name)
+        cls = getattr(builtins, name, None)
+        if isinstance(cls, type) and issubclass(cls, BaseException):
+            if not issubclass(cls, Exception):
+                return True
+            continue
+        todo.extend(bases.get(name, []))
+    return False
+
+
+# Base classes that make a class data, not an exception.
+_DATA_BASES = {"BaseModel", "Enum", "StrEnum", "IntEnum", "TypedDict", "NamedTuple", "Protocol"}
+
+
+def _is_exception(name: str, bases: dict[str, list[str]]) -> bool | None:
+    """Whether ``name`` is an exception class: True, False, or None when it can't tell.
+
+    False means sure: a builtin like ``str``, a class here with no base, or one built on
+    BaseModel/Enum/TypedDict. An imported class with an unknown hierarchy gives None.
+    """
+    cls = getattr(builtins, name, None)
+    if isinstance(cls, type):
+        return issubclass(cls, BaseException)
+    if name in _DATA_BASES:
+        return False
+    if name not in bases:
+        return None
+    parents = [_is_exception(base, bases) for base in bases[name] if base != name]
+    if any(p is True for p in parents):
+        return True
+    if all(p is False for p in parents):  # also true for a class with no bases
+        return False
+    return None
+
+
+def _raised_by_unwrap(error: str | None, bases: dict[str, list[str]]) -> str | None:
+    """What ``.unwrap()`` raises for ``error``: itself, or RuntimeError for non-exceptions."""
+    members = error_members(error)
+    if not members:
+        return error
+    raised = ["RuntimeError" if _is_exception(m, bases) is False else m for m in members]
+    return " | ".join(dict.fromkeys(raised))  # dedupe, keep order
+
+
+def _handler_catches(names: list[str], error: str, bases: dict[str, list[str]]) -> bool:
+    """``except <names>`` catches ``error``.
+
+    A type whose hierarchy is unknown (say, imported from a library) is assumed
+    to be an ``Exception``, as Result errors almost always are.
+    """
+    if "Exception" in names and not _outside_exception(error, bases):
+        return True
+    return any(_is_subclass(error, n, bases) for n in names)
+
+
+def _handler_label(handler: ast.ExceptHandler) -> str:
+    return f"except {ast.unparse(handler.type)}" if handler.type is not None else "except"
+
+
+def _handler_types(handler: ast.ExceptHandler) -> tuple[list[str], bool]:
+    """(type names in ``except <types>``, whether it catches everything)."""
+    if handler.type is None:
+        return [], True
+    elts = handler.type.elts if isinstance(handler.type, ast.Tuple) else [handler.type]
+    names = [n for n in map(_ann_name, elts) if n]
+    return names, bool(set(names) & _CATCH_ALL)
+
+
+class _BodyWalker:
+    def __init__(
+        self,
+        *,
+        file: str,
+        function_id: str,
+        enclosing_error: str | None,
+        signatures: dict[str, str],
+        bases: dict[str, list[str]],
+        modules: set[str],
+        in_safe: bool,
+        findings: list[Finding],
+    ) -> None:
+        self.file = file
+        self.function_id = function_id
+        self.enclosing_error = enclosing_error
+        self.signatures = signatures
+        self.bases = bases
+        self.tries = 0
+        self.modules = modules
+        self.in_safe = in_safe
+        self.findings = findings
+        self.seen: set[int] = set()  # ids of the Result calls the walker modelled
+
+    def _callee_error(self, call: ast.Call) -> str | None:
+        """Error type when ``call`` is a known Result-returning callee, else None."""
+        func = call.func
+        if isinstance(func, ast.Name):
+            return self.signatures.get(func.id)
+        if isinstance(func, ast.Attribute):
+            if f".{func.attr}" in self.signatures:
+                return self.signatures[f".{func.attr}"]
+            root = _attr_root(func.value)
+            if isinstance(root, ast.Name) and root.id in self.modules:
+                return self.signatures.get(func.attr)
+        return None
+
+    def walk_stmts(self, stmts: list[ast.stmt]) -> list[Node]:
+        nodes: list[Node] = []
+        for stmt in stmts:
+            nodes.extend(self.walk_stmt(stmt))
+        return nodes
+
+    def walk_stmt(self, stmt: ast.stmt) -> list[Node]:
+        if isinstance(stmt, ast.Return):
+            return self._return(stmt)
+        if isinstance(stmt, ast.Assign):
+            return self._assign(stmt)
+        if isinstance(stmt, ast.AnnAssign):
+            return self._ann_assign(stmt)
+        if isinstance(stmt, ast.Expr):
+            return self._expr_stmt(stmt)
+        if isinstance(stmt, (ast.If,)):
+            return [self._if(stmt)]
+        if isinstance(stmt, ast.Match):
+            return [self._match(stmt)]
+        if isinstance(stmt, (ast.For, ast.AsyncFor)):
+            return [self._for(stmt)]
+        if isinstance(stmt, ast.While):
+            return [self._while(stmt)]
+        if isinstance(stmt, (ast.Break, ast.Continue)):
+            name = "break" if isinstance(stmt, ast.Break) else "continue"
+            return [Jump(name=name, line=stmt.lineno)]
+        if isinstance(stmt, (ast.With, ast.AsyncWith)):
+            return self.walk_stmts(stmt.body)
+        if isinstance(stmt, _TryNode):
+            return self._try(stmt)
+        if isinstance(stmt, ast.Raise):
+            return [self._raise(stmt)]
+        return []
+
+    def _raise(self, stmt: ast.Raise) -> Panic:
+        """``raise X(...)`` exits with X; ``@safe`` or a matching ``except`` may catch it."""
+        exc = stmt.exc
+        error: str | None = None
+        if isinstance(exc, ast.Call):
+            error = _call_name(exc)
+        elif exc is not None:
+            name = _ann_name(exc)
+            error = name if name and name[0].isupper() else None  # `raise e`: type unknown
+        return Panic(
+            name=f"raise {error}" if error else "raise",
+            terminal=True,
+            line=stmt.lineno,
+            error=error,
+        )
+
+    def _return(self, stmt: ast.Return) -> list[Node]:
+        if stmt.value is None:
+            return [Succeed()]
+        return self._returned(stmt.value, stmt.lineno)
+
+    def _returned(self, value: ast.expr, line: int) -> list[Node]:
+        value = _unawait(value)
+        if isinstance(value, ast.IfExp):  # return Ok(x) if cond else Err(e)
+            return [
+                Branch(
+                    label=f"if {ast.unparse(value.test)}",
+                    arms=[
+                        Arm(label="yes", body=self._returned(value.body, line)),
+                        Arm(label="no", body=self._returned(value.orelse, line)),
+                    ],
+                )
+            ]
+        if _is_err_call(value):
+            return [Fail(error=_err_ctor_name(value), line=line)]
+        # unwrap is itself a Call, so it must be checked before the generic Call case
+        if _is_unwrap_call(value):
+            return [*self._unwrap_nodes(value, line), Succeed()]
+        if isinstance(value, ast.Call) and self._callee_error(value) is not None:
+            return [self._step_from_call(value, line), Succeed()]
+        return [Succeed()]
+
+    def _assign(self, stmt: ast.Assign) -> list[Node]:
+        return self._binding(stmt.value, stmt.targets, stmt.lineno)
+
+    def _ann_assign(self, stmt: ast.AnnAssign) -> list[Node]:
+        if stmt.value is None:
+            return []
+        return self._binding(stmt.value, [stmt.target], stmt.lineno)
+
+    def _binding(self, value: ast.expr, targets: list[ast.expr], line: int) -> list[Node]:
+        value = _unawait(value)
+        # `_ = fallible()` swallow
+        if (
+            len(targets) == 1
+            and isinstance(targets[0], ast.Name)
+            and targets[0].id == "_"
+            and isinstance(value, ast.Call)
+            and self._callee_error(value) is not None
+        ):
+            self.seen.add(id(value))
+            name = _call_name(value) or "call"
+            node = Swallow(
+                name=name,
+                how="discard",
+                confidence=Confidence.LIKELY,
+                line=line,
+            )
+            self._finding(
+                NO_SWALLOW,
+                line,
+                f"`_ =` drops the error from `{name}`",
+            )
+            return [node]
+
+        if _is_unwrap_call(value):
+            return self._unwrap_nodes(value, line)
+
+        # x = f() where f returns Result — treat as step if known Result callee
+        if isinstance(value, ast.Call):
+            if self._callee_error(value) is not None:
+                return [self._step_from_call(value, line)]
+            # chained .and_then(...)
+            if isinstance(value.func, ast.Attribute) and value.func.attr in {
+                "and_then",
+                "map",
+                "map_err",
+            }:
+                return self._chain(value, line)
+
+        return []
+
+    def _expr_stmt(self, stmt: ast.Expr) -> list[Node]:
+        value = _unawait(stmt.value)
+        if _is_unwrap_call(value):
+            return self._unwrap_nodes(value, stmt.lineno)
+        if isinstance(value, ast.Call):
+            name = _call_name(value)
+            if name and self._callee_error(value) is not None:
+                self.seen.add(id(value))
+                node = Swallow(
+                    name=name,
+                    how="unused",
+                    confidence=Confidence.POSSIBLE,
+                    line=stmt.lineno,
+                )
+                self._finding(
+                    NO_SWALLOW,
+                    stmt.lineno,
+                    f"unused Result from `{name}`",
+                    confidence=Confidence.POSSIBLE,
+                )
+                return [node]
+        return []
+
+    def _unwrap_nodes(self, call: ast.Call, line: int) -> list[Node]:
+        self.seen.add(id(call))
+        recv = _unwrap_receiver(call)
+        if recv is not None:
+            recv = _unawait(recv)  # (await f()).unwrap()
+        name = "unwrap"
+        step_call: ast.Call | None = None
+        if recv is not None:
+            if isinstance(recv, ast.Call):
+                step_call = recv
+                name = _call_name(recv) or "call"
+            elif isinstance(recv, ast.Name):
+                name = recv.id
+
+        if not self.in_safe:
+            error = self._callee_error(step_call) if step_call is not None else None
+            error = _raised_by_unwrap(error, self.bases)
+            panic = Panic(name=f"{name}.unwrap", terminal=False, line=line, error=error)
+            self._finding(
+                NO_PANIC,
+                line,
+                f"`{name}.unwrap` can raise",
+            )
+            nodes: list[Node] = []
+            if step_call is not None:
+                nodes.append(self._raising_step(step_call, line))
+            nodes.append(panic)
+            return nodes
+
+        if step_call is not None:
+            return [self._raising_step(step_call, line)]
+        return [
+            Step(
+                name=name,
+                error=_raised_by_unwrap(self.enclosing_error, self.bases),
+                source=ErrorSource.ENCLOSING if self.enclosing_error else ErrorSource.UNKNOWN,
+                line=line,
+                raises=True,
+            )
+        ]
+
+    def _raising_step(self, call: ast.Call, line: int) -> Step:
+        """A step whose error is raised by ``.unwrap()``; a str or model error raises RuntimeError."""
+        step = self._step_from_call(call, line)
+        return replace(step, raises=True, error=_raised_by_unwrap(step.error, self.bases))
+
+    def _step_from_call(self, call: ast.Call, line: int) -> Step:
+        self.seen.add(id(call))
+        name = _call_name(call) or "call"
+        error = self._callee_error(call)
+        source = ErrorSource.UNKNOWN
+        if error is not None:
+            source = ErrorSource.CALLEE
+        elif self.enclosing_error:
+            error = self.enclosing_error
+            source = ErrorSource.ENCLOSING
+        return Step(name=name, error=error, source=source, line=line)
+
+    def _chain(self, call: ast.Call, line: int) -> list[Node]:
+        nodes: list[Node] = []
+        cur: ast.expr = call
+        parts: list[ast.Call] = []
+        while isinstance(cur, ast.Call) and isinstance(cur.func, ast.Attribute):
+            parts.append(cur)
+            cur = _unawait(cur.func.value)
+        if isinstance(cur, ast.Call):
+            nodes.append(self._step_from_call(cur, line))
+        for part in reversed(parts):
+            assert isinstance(part.func, ast.Attribute)
+            attr = part.func.attr
+            if attr == "and_then" and part.args:
+                arg = part.args[0]
+                name = _call_name(arg) or "and_then"
+                err = self.signatures.get(name)
+                source = (
+                    ErrorSource.CALLEE
+                    if err
+                    else (ErrorSource.ENCLOSING if self.enclosing_error else ErrorSource.UNKNOWN)
+                )
+                nodes.append(
+                    Step(
+                        name=name,
+                        error=err or self.enclosing_error,
+                        source=source,
+                        line=line,
+                    )
+                )
+            elif attr in {"map_err", "map"}:
+                nodes.append(
+                    Step(
+                        name=attr,
+                        error=self.enclosing_error,
+                        source=ErrorSource.ENCLOSING
+                        if self.enclosing_error
+                        else ErrorSource.UNKNOWN,
+                        conversions=[ast.unparse(part.args[0])] if part.args else [],
+                        line=line,
+                    )
+                )
+        return nodes
+
+    def _if(self, stmt: ast.If) -> Branch:
+        test = ast.unparse(stmt.test)
+        then_arm = Arm(label="yes", body=self.walk_stmts(stmt.body))
+        else_body = stmt.orelse
+        # elif chain
+        if len(else_body) == 1 and isinstance(else_body[0], ast.If):
+            else_arm = Arm(label="no", body=[self._if(else_body[0])])
+        else:
+            else_arm = Arm(label="no", body=self.walk_stmts(else_body))
+        return Branch(label=f"if {test}", arms=[then_arm, else_arm])
+
+    def _match(self, stmt: ast.Match) -> Branch:
+        arms: list[Arm] = []
+        for case in stmt.cases:
+            label = ast.unparse(case.pattern)
+            arms.append(Arm(label=label, body=self.walk_stmts(case.body)))
+        return Branch(label=f"match {ast.unparse(stmt.subject)}", arms=arms)
+
+    def _for(self, stmt: ast.For | ast.AsyncFor) -> Loop:
+        target = ast.unparse(stmt.target)
+        iter_ = ast.unparse(stmt.iter)
+        return Loop(
+            label=f"for {target} in {iter_}",
+            can_skip=True,
+            body=self.walk_stmts(stmt.body),
+        )
+
+    def _while(self, stmt: ast.While) -> Loop:
+        return Loop(
+            label=f"while {ast.unparse(stmt.test)}",
+            can_skip=True,
+            body=self.walk_stmts(stmt.body),
+        )
+
+    def _try(self, stmt: _TryNode) -> list[Node]:
+        self.tries += 1
+        tag = f"try{self.tries}"
+        # Errors raised in the body (not else) go to the first matching handler.
+        body = self._catch(self.walk_stmts(stmt.body), stmt.handlers, tag)
+        # Handlers are alternatives to the normal path, not steps after it.
+        arms = [Arm(label="ok", body=body + self.walk_stmts(stmt.orelse))]
+        for handler in stmt.handlers:
+            how = _handler_label(handler)
+            recover = Recover(name="try", how=how, arms=[how], line=handler.lineno)
+            arms.append(Arm(label=how, body=[recover, *self.walk_stmts(handler.body)]))
+        finally_nodes = self.walk_stmts(stmt.finalbody)
+        if finally_nodes:
+            arms = [Arm(arm.label, _before_exits(arm.body, finally_nodes)) for arm in arms]
+        return [Branch(label="try", arms=arms, tag=tag), *finally_nodes]
+
+    def _catch(self, nodes: list[Node], handlers: list[ast.ExceptHandler], tag: str) -> list[Node]:
+        """Point each raising step not already caught at the first handler that catches it."""
+        out: list[Node] = []
+        for node in nodes:
+            if isinstance(node, (Step, Panic)):
+                node = replace(
+                    node,
+                    cleanup=self._catch(node.cleanup, handlers, tag),
+                    caught_by={
+                        k: replace(c, cleanup=self._catch(c.cleanup, handlers, tag))
+                        for k, c in node.caught_by.items()
+                    },
+                )
+                raises = node.raises if isinstance(node, Step) else True
+                if raises and escaping(node.error, node.caught_by) is not None:
+                    node = replace(node, caught_by=self._route(node, handlers, tag))
+            elif isinstance(node, Branch):
+                node = replace(
+                    node, arms=[Arm(a.label, self._catch(a.body, handlers, tag)) for a in node.arms]
+                )
+            elif isinstance(node, Loop):
+                node = replace(node, body=self._catch(node.body, handlers, tag))
+            out.append(node)
+        return out
+
+    def _route(
+        self, node: Step | Panic, handlers: list[ast.ExceptHandler], tag: str
+    ) -> dict[str, Catch]:
+        """Add this try's handlers to ``node``'s routing; the first match per exception type wins."""
+        caught = dict(node.caught_by)
+        members = error_members(node.error)
+        for i, handler in enumerate(handlers, start=1):
+            names, catch_all = _handler_types(handler)
+            catch = Catch(
+                handler=f"{tag}#{i}", how=_handler_label(handler), cleanup=list(node.cleanup)
+            )
+            if members:
+                for m in members:
+                    if m not in caught and (catch_all or _handler_catches(names, m, self.bases)):
+                        caught[m] = catch
+            elif CATCH_ANY not in caught:
+                # Unknown type: a catch-all (or Exception: Result errors are Exceptions)
+                # surely catches it; a typed handler only might.
+                if catch_all or "Exception" in names:
+                    caught[CATCH_ANY] = catch
+                else:
+                    for n in names:
+                        caught.setdefault(n, catch)
+        return caught
+
+    def _finding(
+        self,
+        rule: str,
+        line: int,
+        message: str,
+        *,
+        confidence: Confidence = Confidence.CERTAIN,
+    ) -> None:
+        self.findings.append(
+            Finding(
+                rule=rule,
+                file=self.file,
+                line=line,
+                message=message,
+                confidence=confidence,
+                function=self.function_id,
+            )
+        )
+
+
+def _before_exits(nodes: list[Node], fin: list[Node], *, jumps: bool = True) -> list[Node]:
+    """Put ``fin`` before every exit in ``nodes``: Python runs ``finally`` on return,
+    break, continue and on errors raised inside the ``try``.
+
+    If ``fin`` itself ends in a return, the emitters stop there, so its exit wins, as in Python.
+    """
+    out: list[Node] = []
+    for node in nodes:
+        if isinstance(node, (Succeed, Fail)) or (jumps and isinstance(node, Jump)):
+            out.extend(fin)
+        elif isinstance(node, (Step, Panic)):
+            cleanup = _before_exits(node.cleanup, fin, jumps=False)
+            if escaping(node.error, node.caught_by) is not None:
+                # Error leaves the try: inner cleanup first, then this finally, then the error.
+                cleanup = [*cleanup, *fin]
+            caught_by = {
+                k: replace(c, cleanup=_before_exits(c.cleanup, fin, jumps=False))
+                for k, c in node.caught_by.items()
+            }
+            node = replace(node, cleanup=cleanup, caught_by=caught_by)
+        elif isinstance(node, Branch):
+            node = replace(
+                node,
+                arms=[Arm(a.label, _before_exits(a.body, fin, jumps=jumps)) for a in node.arms],
+            )
+        elif isinstance(node, Loop):
+            # break/continue inside a nested loop stay in that loop, so they skip finally
+            node = replace(node, body=_before_exits(node.body, fin, jumps=False))
+        out.append(node)
+    return out
+
+
+def _safe_error(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str | None:
+    """The error type a @safe-family decorator gives ``node``, or None if it has none."""
+    for dec in node.decorator_list:
+        if isinstance(dec, ast.Call) and _call_name(dec) in {"safe_with", "safe_async_with"}:
+            names = [_ann_name(arg) or ast.unparse(arg) for arg in dec.args]
+            return " | ".join(names) if names else "Exception"
+        if not isinstance(dec, ast.Call) and _ann_name(dec) in {"safe", "safe_async"}:
+            return "Exception"
+    return None
+
+
+def _has_safe_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return _safe_error(node) is not None
+
+
+def _calls(node: ast.AST, deferred: bool = False) -> Iterator[tuple[ast.Call, bool]]:
+    """Calls in ``node``, outermost first, each with whether it runs later (in a lambda).
+
+    A nested function or class body is its own scope (analysed on its own), so its calls
+    never count against the enclosing function; what runs while defining it (decorators,
+    defaults, class bases) does. A lambda's body may or may not run here, so its calls
+    come back marked deferred.
+    """
+    children: Iterable[ast.AST]
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+        args = node.args
+        decorators = [] if isinstance(node, ast.Lambda) else node.decorator_list
+        children = [*decorators, *args.defaults, *filter(None, args.kw_defaults)]
+    elif isinstance(node, ast.ClassDef):
+        children = [*node.decorator_list, *node.bases, *(k.value for k in node.keywords)]
+    else:
+        children = ast.iter_child_nodes(node)
+    for child in children:
+        if isinstance(child, ast.Call):
+            yield child, deferred
+        yield from _calls(child, deferred)
+    if isinstance(node, ast.Lambda):
+        if isinstance(node.body, ast.Call):
+            yield node.body, True
+        yield from _calls(node.body, True)
+
+
+def _module_name(path: Path, root: Path) -> str:
+    try:
+        rel = path.relative_to(root)
+    except ValueError:
+        return path.stem
+    parts = list(rel.with_suffix("").parts)
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _is_support_path(path: Path) -> bool:
+    parts = set(path.parts)
+    return bool(parts & {"tests", "test", "benches", "examples", ".venv", "venv"})
+
+
+class _FunctionExtractor(ast.NodeVisitor):
+    def __init__(
+        self,
+        *,
+        file: str,
+        module: str,
+        signatures: dict[str, str],
+        bases: dict[str, list[str]],
+        modules: set[str],
+        report: Report,
+    ) -> None:
+        self.file = file
+        self.module = module
+        self.signatures = signatures
+        self.bases = bases
+        self.modules = modules
+        self.report = report
+        self._class: str | None = None
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        prev = self._class
+        self._class = node.name
+        self.generic_visit(node)
+        self._class = prev
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._extract(node)
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._extract(node)
+        self.generic_visit(node)
+
+    def _qid(self, name: str) -> str:
+        if self._class:
+            return f"{self.module}.{self._class}.{name}" if self.module else f"{self._class}.{name}"
+        return f"{self.module}.{name}" if self.module else name
+
+    def _extract(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        returns = parse_returns(node.returns)
+        # Only analyse Result-returning or @safe functions
+        in_safe = _has_safe_decorator(node)
+        if not isinstance(returns, ReturnsResult) and not in_safe:
+            return
+
+        enclosing = returns.error if isinstance(returns, ReturnsResult) else None
+        if not isinstance(returns, ReturnsResult):
+            returns = ReturnsResult(error=_safe_error(node) or "Exception")
+        fid = self._qid(node.name)
+        walker = _BodyWalker(
+            file=self.file,
+            function_id=fid,
+            enclosing_error=enclosing,
+            signatures=self.signatures,
+            bases=self.bases,
+            modules=self.modules,
+            in_safe=in_safe,
+            findings=self.report.findings,
+        )
+        nodes: list[Node] = walker.walk_stmts(node.body)
+        if not nodes:
+            nodes = [Succeed()]
+        self._report_unanalysed(node, walker, fid, in_safe)
+
+        self.report.functions.append(
+            Function(
+                id=fid,
+                name=node.name,
+                file=self.file,
+                line=node.lineno,
+                returns=returns,
+                nodes=nodes,
+            )
+        )
+
+    def _report_unanalysed(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        walker: _BodyWalker,
+        fid: str,
+        in_safe: bool,
+    ) -> None:
+        """Say where errpath couldn't follow a Result, instead of silently drawing less."""
+        for stmt in node.body:
+            for call, deferred in _calls(stmt):
+                if id(call) in walker.seen:
+                    continue
+                is_unwrap = _is_unwrap_call(call)
+                if not is_unwrap and walker._callee_error(call) is None:
+                    continue
+                receiver = _unwrap_receiver(call) if is_unwrap else None
+                if isinstance(receiver, ast.Call):
+                    walker.seen.add(id(receiver))  # one note for `f().unwrap()`, not two
+                code = ast.unparse(call)
+                self.report.unanalysed.append(
+                    Unanalysed(
+                        file=self.file,
+                        line=call.lineno,
+                        function=fid,
+                        code=code if len(code) <= 60 else code[:57] + "...",
+                        reason="Result used inside a lambda; errpath can't tell when it runs"
+                        if deferred
+                        else "Result used inside an expression; its error path isn't drawn",
+                    )
+                )
+                if (
+                    is_unwrap and not in_safe and not deferred
+                ):  # still a crash point the review must see
+                    name = _call_name(receiver) if isinstance(receiver, ast.Call) else "unwrap"
+                    walker._finding(NO_PANIC, call.lineno, f"`{name}.unwrap` can raise")
+
+
+def _count_coverage(report: Report) -> None:
+    cov = Coverage(functions=len(report.functions))
+    for fn in report.functions:
+        for node in _iter_nodes(fn.nodes):
+            if isinstance(node, Step):
+                cov.steps += 1
+                if node.source == ErrorSource.CALLEE:
+                    cov.error_from_callee += 1
+                elif node.source == ErrorSource.ENCLOSING:
+                    cov.error_from_enclosing += 1
+                else:
+                    cov.error_unknown += 1
+    cov.unanalysed = len(report.unanalysed)
+    report.coverage = cov
+
+
+def _iter_nodes(nodes: list[Node]) -> list[Node]:
+    out: list[Node] = []
+    for n in nodes:
+        out.append(n)
+        if isinstance(n, Branch):
+            for arm in n.arms:
+                out.extend(_iter_nodes(arm.body))
+        elif isinstance(n, Loop):
+            out.extend(_iter_nodes(n.head))
+            out.extend(_iter_nodes(n.body))
+        elif isinstance(n, (Scope, Block)):
+            out.extend(_iter_nodes(n.body))
+    return out
+
+
+def analyse_source(
+    source: str,
+    *,
+    file: str = "<string>",
+    module: str = "",
+    signatures: dict[str, str] | None = None,
+    bases: dict[str, list[str]] | None = None,
+) -> Report:
+    """Analyse one module. ``signatures`` and class ``bases`` default to those in ``source``."""
+    report = Report(schema_version=SCHEMA_VERSION)
+    try:
+        tree = ast.parse(source, filename=file)
+    except SyntaxError as e:
+        report.parse_failures.append(ParseFailure(file=file, message=str(e)))
+        return report
+
+    extractor = _FunctionExtractor(
+        file=file,
+        module=module,
+        signatures=_collect(tree).signatures if signatures is None else signatures,
+        bases=_collect(tree).bases if bases is None else bases,
+        modules=_imported_names(tree),
+        report=report,
+    )
+    extractor.visit(tree)
+    _count_coverage(report)
+    return report
+
+
+def _rel(path: Path, root: Path) -> str:
+    return str(path.relative_to(root)) if path.is_relative_to(root) else str(path)
+
+
+def analyse_file(path: Path, *, root: Path | None = None) -> Report:
+    root = root or path.parent
+    text = path.read_text(encoding="utf-8")
+    return analyse_source(text, file=_rel(path, root), module=_module_name(path, root))
+
+
+def analyse_path(root: Path) -> Report:
+    """Analyse a file or directory of ``.py`` sources."""
+    root = root.resolve()
+    merged = Report(schema_version=SCHEMA_VERSION)
+    if root.is_file():
+        files = [root]
+        base = root.parent
+    else:
+        # Skip tests, examples and virtualenvs when walking a tree; a single file is always analysed.
+        files = []
+        for p in sorted(root.rglob("*.py")):
+            if not p.is_file():
+                continue
+            if _is_support_path(p.relative_to(root)):
+                merged.support_files_skipped += 1
+            else:
+                files.append(p)
+        base = root
+
+    sources: dict[Path, str] = {}
+    for path in files:
+        try:
+            sources[path] = path.read_text(encoding="utf-8")
+        except OSError as e:
+            merged.parse_failures.append(ParseFailure(file=_rel(path, base), message=str(e)))
+
+    # Collect signatures across the tree first, so calls into other modules resolve
+    all_sigs: dict[str, str] = {}
+    all_bases: dict[str, list[str]] = {}
+    for path, text in sources.items():
+        try:
+            collected = _collect(ast.parse(text, filename=str(path)))
+            all_sigs.update(collected.signatures)
+            all_bases.update(collected.bases)
+        except SyntaxError:
+            pass  # reported by analyse_source below
+
+    for path, text in sources.items():
+        sub = analyse_source(
+            text,
+            file=_rel(path, base),
+            module=_module_name(path, base),
+            signatures=all_sigs,
+            bases=all_bases,
+        )
+        merged.functions.extend(sub.functions)
+        merged.findings.extend(sub.findings)
+        merged.parse_failures.extend(sub.parse_failures)
+        merged.unanalysed.extend(sub.unanalysed)
+
+    _count_coverage(merged)
+    return merged