blockpath 0.1.0__py3-none-any.whl

blockpath/__init__.py

@@ -0,0 +1,22 @@
+"""blockpath: find blocking calls reachable from a coroutine, and print the whole path.
+
+Public API is deliberately tiny: run ``check`` over a project root, read the ``Finding`` objects
+it returns. The command-line interface in ``blockpath.cli`` is a thin wrapper over this.
+"""
+
+from __future__ import annotations
+
+from blockpath.check import check
+from blockpath.config import Config
+from blockpath.model import CheckResult, Code, Finding, Frame, Position, Severity
+
+__all__ = [
+    "CheckResult",
+    "Code",
+    "Config",
+    "Finding",
+    "Frame",
+    "Position",
+    "Severity",
+    "check",
+]

blockpath/analysis.py

@@ -0,0 +1,329 @@
+"""Layer 6: three breadth-first searches, and deliberately nothing cleverer.
+
+The diagnostic is the *intersection* of two independent reachability questions, and that
+intersection is the whole reason the tool can be quiet:
+
+1. **Backward** from every blocking leaf: which functions can reach a blocking call at all?
+   Formally ``blocking(v) := oracle(v) or exists edge v->w with blocking(w)`` -- a boolean join
+   on a lattice of height two, which is exactly backward reachability, so one reverse BFS
+   computes it. Cycles are absorbed by a visited set.
+2. **Forward** from every async entry point: which functions can a coroutine reach?
+3. **Forward again**, restricted to the intersection and carrying parent pointers, to recover the
+   witness: the actual chain of call sites from the coroutine down to the blocking call.
+
+Without step 2 the tool would shout about ``time.sleep`` in a synchronous CLI script in the same
+repository and be switched off within a day. Without step 1 the search would wander through
+every clean subtree a coroutine can reach.
+
+No Tarjan, no SCC condensation, no fixpoint iteration: naive iteration is O(V*E), a reverse BFS
+is O(V+E) and three times simpler, and the condensation buys nothing for a height-two join
+(ADR 0002). Only CALL edges are traversed; a function merely passed as a value is not chased
+(ADR 0007).
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+from blockpath.callgraph import CallGraph, Edge, EdgeKind, FuncNode
+from blockpath.config import Config
+from blockpath.model import Code, Finding, Frame, Position, Severity
+from blockpath.oracle import Oracle
+from blockpath.resolve import External, Internal
+
+
+@lru_cache(maxsize=256)
+def _lines(path: Path) -> tuple[str, ...]:
+    try:
+        return tuple(path.read_text(encoding="utf-8").splitlines())
+    except (OSError, UnicodeDecodeError):
+        return ()
+
+
+def _source_line(position: Position) -> str:
+    lines = _lines(position.path)
+    if 1 <= position.line <= len(lines):
+        return lines[position.line - 1].strip()
+    return ""
+
+
+@dataclass(frozen=True, slots=True)
+class _BlockingLeaf:
+    """A call site that blocks: the function containing it, and what it calls."""
+
+    owner: str
+    edge: Edge
+    dotted: str
+    category: str
+    severity: Severity
+    hint_note: str
+
+
+def _is_entry(node: FuncNode, config: Config) -> str:
+    """Why this node is an async entry point, or "" if it is not one."""
+    if node.is_async:
+        return "async def"
+    for decorator in node.decorators:
+        for configured in config.entry_decorators:
+            if decorator == configured or decorator.endswith(f".{configured}"):
+                return f"@{decorator}"
+    return ""
+
+
+def analyse(graph: CallGraph, oracle: Oracle, config: Config) -> tuple[Finding, ...]:
+    """Find every blocking call a coroutine can reach, with the path that gets there."""
+    call_edges = [e for e in graph.edges if e.kind is EdgeKind.CALL]
+
+    # --- the blocking leaves: external calls the oracle says stall the loop -------------------
+    leaves: list[_BlockingLeaf] = []
+    for edge in call_edges:
+        if not isinstance(edge.target, External):
+            continue
+        entry = oracle.blocks(edge.target.dotted, config.enabled_tiers)
+        if entry is None:
+            continue
+        leaves.append(
+            _BlockingLeaf(
+                owner=edge.source,
+                edge=edge,
+                dotted=entry.name,
+                category=entry.category,
+                severity=entry.severity,
+                hint_note=entry.note,
+            )
+        )
+
+    # --- 1. backward BFS: which functions can reach a blocking call --------------------------
+    callers: dict[str, set[str]] = {}
+    outgoing: dict[str, list[tuple[str, Edge]]] = {}
+    for edge in call_edges:
+        if isinstance(edge.target, Internal) and edge.target.qualname in graph.nodes:
+            callers.setdefault(edge.target.qualname, set()).add(edge.source)
+            outgoing.setdefault(edge.source, []).append((edge.target.qualname, edge))
+
+    blocking: set[str] = set()
+    queue: deque[str] = deque()
+    for leaf in leaves:
+        if leaf.owner not in blocking:
+            blocking.add(leaf.owner)
+            queue.append(leaf.owner)
+    while queue:
+        current = queue.popleft()
+        for caller in callers.get(current, ()):
+            if caller not in blocking:
+                blocking.add(caller)
+                queue.append(caller)
+
+    # --- 2 and 3. forward BFS from the entry points, restricted to the intersection ----------
+    # Restricting to `blocking` is what makes the recovered path a *witness*: every hop on it is
+    # itself on a route to a blocking call, so the trace never wanders into a clean subtree.
+    entry_reason: dict[str, str] = {}
+    for qualname, node in graph.nodes.items():
+        reason = _is_entry(node, config)
+        if reason:
+            entry_reason[qualname] = reason
+
+    parent: dict[str, tuple[str, Edge]] = {}
+    reachable: set[str] = set()
+    frontier: deque[str] = deque()
+    for qualname in entry_reason:
+        if qualname in blocking and qualname not in reachable:
+            reachable.add(qualname)
+            frontier.append(qualname)
+    while frontier:
+        current = frontier.popleft()
+        for nxt, edge in outgoing.get(current, ()):
+            # every node on a path to a blocking owner is itself in `blocking` (the backward BFS
+            # put it there), so this restriction prunes clean subtrees without losing a witness
+            if nxt in blocking and nxt not in reachable:
+                reachable.add(nxt)
+                parent[nxt] = (current, edge)
+                frontier.append(nxt)
+
+    # --- build the findings -------------------------------------------------------------------
+    findings: list[Finding] = []
+    for leaf in leaves:
+        if leaf.owner not in reachable:
+            continue
+        witness = _witness(leaf, parent, entry_reason, graph)
+        if witness is None:
+            continue
+        findings.append(
+            Finding(
+                code=Code.BLK001,
+                severity=leaf.severity,
+                callee=leaf.dotted,
+                category=leaf.category,
+                witness=witness,
+                hint=_hint(witness),
+            )
+        )
+
+    # Plain reachability from the coroutines, unrestricted by `blocking`. The three searches
+    # above answer "where does a block hide"; this one only scopes the two diagnostics below to
+    # code a coroutine can actually get to.
+    from_coroutines: set[str] = set(entry_reason)
+    plain: deque[str] = deque(from_coroutines)
+    while plain:
+        current = plain.popleft()
+        for nxt, _edge in outgoing.get(current, ()):
+            if nxt not in from_coroutines:
+                from_coroutines.add(nxt)
+                plain.append(nxt)
+
+    findings.extend(_blk002(call_edges, oracle, entry_reason, from_coroutines))
+    if config.strict:
+        findings.extend(_blk003(graph.edges, oracle, entry_reason, from_coroutines, config))
+    findings.sort(key=lambda f: (str(f.leaf.position.path), f.leaf.position.line, f.callee))
+    return tuple(findings)
+
+
+def _witness(
+    leaf: _BlockingLeaf,
+    parent: dict[str, tuple[str, Edge]],
+    entry_reason: dict[str, str],
+    graph: CallGraph,
+) -> tuple[Frame, ...] | None:
+    """Walk parent pointers from the blocking call back to the entry, then read the chain down.
+
+    Each frame is a *call site*: the function it names, and the position within that function
+    where control passes to the next frame. The last frame is the blocking call itself.
+    """
+    chain: list[tuple[str, Edge]] = []  # (function, the edge by which it calls the next hop)
+    current = leaf.owner
+    guard = 0
+    while current not in entry_reason:
+        step = parent.get(current)
+        if step is None:
+            return None  # not actually reachable from an entry
+        previous, edge = step
+        chain.append((previous, edge))
+        current = previous
+        guard += 1
+        if guard > len(graph.nodes) + 1:
+            return None  # defensive: a malformed parent chain must not spin
+    chain.reverse()
+
+    frames: list[Frame] = []
+    for index, (qualname, edge) in enumerate(chain):
+        frames.append(
+            Frame(
+                qualname=qualname,
+                position=edge.position,
+                source_line=_source_line(edge.position),
+                entry_reason=entry_reason.get(qualname, "") if index == 0 else "",
+            )
+        )
+    frames.append(
+        Frame(
+            qualname=leaf.owner,
+            position=leaf.edge.position,
+            source_line=_source_line(leaf.edge.position),
+            entry_reason=entry_reason.get(leaf.owner, "") if not frames else "",
+        )
+    )
+    return tuple(frames)
+
+
+def _hint(witness: tuple[Frame, ...]) -> str:
+    """A remediation naming the first hop off the coroutine, which is where to_thread belongs."""
+    if len(witness) < 2:
+        return "await asyncio.to_thread(...)  # move the blocking call off the loop"
+    handoff = witness[1].qualname.rsplit(".", 1)[-1]
+    return f"await asyncio.to_thread({handoff}, ...)"
+
+
+def _blk003(
+    edges: list[Edge],
+    oracle: Oracle,
+    entry_reason: dict[str, str],
+    from_coroutines: set[str],
+    config: Config,
+) -> list[Finding]:
+    """Strict mode: a blocking callable handed to a callee we cannot follow.
+
+    ``dispatch(time.sleep)`` -- we can see a blocking function escaping into something the
+    resolver could not pin down, so it may well be invoked on the loop. We cannot prove it, which
+    is exactly why this is silent by default and only surfaces under ``--strict``. References
+    consumed by a known thread-offload primitive are excluded: those provably run elsewhere.
+    """
+    out: list[Finding] = []
+    for edge in edges:
+        if edge.kind is not EdgeKind.REF or not isinstance(edge.target, External):
+            continue
+        entry = oracle.blocks(edge.target.dotted, config.enabled_tiers)
+        if entry is None or edge.source not in from_coroutines:
+            continue
+        if oracle.offload_for(edge.consumer) is not None:
+            continue  # handed to a thread on purpose: correct code
+        frame = Frame(
+            qualname=edge.source,
+            position=edge.position,
+            source_line=_source_line(edge.position),
+            entry_reason=entry_reason.get(edge.source, ""),
+        )
+        out.append(
+            Finding(
+                code=Code.BLK003,
+                severity=entry.severity,
+                callee=entry.name,
+                category=entry.category,
+                witness=(frame,),
+                hint=(
+                    f"{entry.name} is passed to {edge.consumer or 'an unresolved callee'}; "
+                    "blockpath cannot tell whether it runs on the loop"
+                ),
+            )
+        )
+    return out
+
+
+def _blk002(
+    call_edges: list[Edge],
+    oracle: Oracle,
+    entry_reason: dict[str, str],
+    from_coroutines: set[str],
+) -> list[Finding]:
+    """``run_in_executor(None, fetch())`` -- the callable slot was called, not passed.
+
+    The parentheses run ``fetch`` on the loop before the executor ever sees it, which is the
+    exact inverse of the intended fix. Reported only inside a coroutine, which is the only place
+    the offload primitives are used, so the diagnostic cannot fire on ordinary sync code.
+    """
+    out: list[Finding] = []
+    for edge in call_edges:
+        if oracle.blk002(edge.consumer, edge.arg_index) is None:
+            continue
+        if edge.source not in from_coroutines:
+            continue
+        called = (
+            edge.target.qualname
+            if isinstance(edge.target, Internal)
+            else edge.target.dotted
+            if isinstance(edge.target, External)
+            else edge.source_text
+        )
+        frame = Frame(
+            qualname=edge.source,
+            position=edge.position,
+            source_line=_source_line(edge.position),
+            entry_reason=entry_reason.get(edge.source, ""),
+        )
+        short = called.rsplit(".", 1)[-1]
+        out.append(
+            Finding(
+                code=Code.BLK002,
+                severity=Severity.ERROR,
+                callee=short,
+                category="offload",
+                witness=(frame,),
+                hint=f"pass the function, do not call it: {edge.consumer}(..., {short})",
+            )
+        )
+    return out
+
+
+__all__ = ["analyse"]

blockpath/callgraph.py

@@ -0,0 +1,298 @@
+"""Layer 4: the call graph -- who calls whom, and who merely *hands off* whom.
+
+A node is every ``def`` / ``async def`` / ``lambda`` (nested ones too, so a closure is a real
+node, which is what makes offloading fall out of the graph structure). Two kinds of edge:
+
+* **CALL** -- ``f(...)`` executes ``f`` in the caller's frame, on the caller's thread. This is
+  the edge reachability follows.
+* **REF** -- ``f`` is passed as a *value*: ``run_in_executor(None, f)``, ``sorted(xs, key=f)``,
+  ``loop.call_soon(f)``. Whether that reference ever runs, and on which thread, depends entirely
+  on what received it -- so a REF edge records its *consumer* (the callee it was an argument to)
+  and its argument position, and the oracle (layer 5) decides which REF edges to cut (a thread
+  offload) and which to keep (a synchronous ``key=`` / ``call_soon`` that runs on the loop).
+
+The single pair of parentheses that flips a bug into correct code lives here: ``to_thread(f)``
+is a REF (offloaded), ``to_thread(f())`` is a CALL of ``f`` in the coroutine (a real block, the
+BLK002 shape). The graph records both faithfully; the oracle reads the difference.
+
+Only calls *by name* are resolved. An attribute call on a value (``self.session.get()``) is not
+resolved in v1 (ADR 0003); every call site is tallied by how it resolved, so the price of that
+cut is a measured number, not a hand-wave.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections import Counter
+from dataclasses import dataclass, field
+from enum import Enum
+
+from blockpath.collect import Collection, Module
+from blockpath.model import Position
+from blockpath.resolve import External, Internal, Resolver, Target, Unresolved
+from blockpath.symbols import Analysis, ModuleScopes, ModuleSymbols, ScopeNode
+
+MODULE_OWNER = "<module>"
+
+
+class EdgeKind(Enum):
+    CALL = "call"
+    REF = "ref"
+
+
+@dataclass(frozen=True, slots=True)
+class FuncNode:
+    qualname: str
+    position: Position
+    is_async: bool
+    is_lambda: bool
+    #: dotted decorator expressions as written (``router.message`` for ``@router.message()``), so
+    #: a framework can mark a handler as an async entry point even when it is a plain ``def``
+    decorators: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class Edge:
+    """One call-graph edge. ``target`` is the resolver's verdict, kept whole so the analysis can
+    treat Internal / External / Unresolved differently."""
+
+    source: str
+    target: Target
+    kind: EdgeKind
+    position: Position
+    source_text: str
+    #: if this call or reference is itself an argument to another call, the dotted callee of that
+    #: enclosing call (best effort, e.g. "loop.run_in_executor", "asyncio.to_thread"); else None
+    consumer: str | None = None
+    #: positional index of this argument within the consumer call, or None if a keyword/not-an-arg
+    arg_index: int | None = None
+
+
+@dataclass(slots=True)
+class ModuleGraph:
+    nodes: dict[str, FuncNode]
+    edges: list[Edge]
+    #: how every call site resolved: by_name / attribute / dynamic / to a lambda / ...
+    resolution: Counter[str] = field(default_factory=Counter)
+
+
+@dataclass(slots=True)
+class CallGraph:
+    nodes: dict[str, FuncNode]
+    edges: list[Edge]
+    resolution: Counter[str]
+
+
+def _dotted_of(expr: ast.expr) -> str | None:
+    parts: list[str] = []
+    cur: ast.expr = expr
+    while isinstance(cur, ast.Attribute):
+        parts.append(cur.attr)
+        cur = cur.value
+    if not isinstance(cur, ast.Name):
+        return None
+    parts.append(cur.id)
+    return ".".join(reversed(parts))
+
+
+class _ModuleBuilder:
+    """Walks one module's AST, creating nodes and edges. Owners are tracked as AST nodes so the
+    right scope table can be consulted for each call."""
+
+    def __init__(self, module: Module, analysis: Analysis, resolver: Resolver) -> None:
+        self._module = module
+        self._symbols: ModuleSymbols = analysis.symbols
+        self._scopes: ModuleScopes = analysis.scopes
+        self._resolver = resolver
+        self._lambda_counter = 0
+        self.nodes: dict[str, FuncNode] = {}
+        self.edges: list[Edge] = []
+        self.resolution: Counter[str] = Counter()
+
+    def build(self) -> ModuleGraph:
+        for stmt in self._module.tree.body:
+            self._visit(
+                stmt,
+                owner=MODULE_OWNER,
+                owner_node=None,
+                prefix=self._module.qualname,
+                ctx="module",
+            )
+        return ModuleGraph(self.nodes, self.edges, self.resolution)
+
+    def _add_node(self, qual: str, node: ScopeNode, is_lambda: bool) -> None:
+        decorators: tuple[str, ...] = ()
+        if not isinstance(node, ast.Lambda):
+            names = []
+            for dec in node.decorator_list:
+                expr = dec.func if isinstance(dec, ast.Call) else dec
+                dotted = _dotted_of(expr)
+                if dotted:
+                    names.append(dotted)
+            decorators = tuple(names)
+        self.nodes[qual] = FuncNode(
+            qualname=qual,
+            position=Position(self._module.path, node.lineno, node.col_offset),
+            is_async=isinstance(node, ast.AsyncFunctionDef),
+            is_lambda=is_lambda,
+            decorators=decorators,
+        )
+
+    def _pos(self, node: ast.expr) -> Position:
+        return Position(self._module.path, node.lineno, node.col_offset)
+
+    def _visit(
+        self,
+        node: ast.AST,
+        owner: str,
+        owner_node: ScopeNode | None,
+        prefix: str,
+        ctx: str,
+        arg_of: tuple[str | None, int | None] | None = None,
+    ) -> None:
+        """``arg_of`` is set when ``node`` is itself an argument to an enclosing call: (consumer
+        dotted callee, positional index or None for a keyword). It tags the edge this node makes
+        so the oracle can read the offload / BLK002 context, and it is consumed at one level."""
+        match node:
+            case ast.FunctionDef() | ast.AsyncFunctionDef():
+                for dec in node.decorator_list:
+                    self._visit(dec, owner, owner_node, prefix, ctx)
+                for dflt in [*node.args.defaults, *(d for d in node.args.kw_defaults if d)]:
+                    self._visit(dflt, owner, owner_node, prefix, ctx)
+                qual = (
+                    f"{prefix}.{node.name}"
+                    if ctx in ("module", "class")
+                    else f"{owner}.<def:{node.name}@{node.lineno}:{node.col_offset}>"
+                )
+                self._add_node(qual, node, is_lambda=False)
+                for stmt in node.body:
+                    self._visit(stmt, qual, node, qual, "function")
+
+            case ast.Lambda():
+                for dflt in [*node.args.defaults, *(d for d in node.args.kw_defaults if d)]:
+                    self._visit(dflt, owner, owner_node, prefix, ctx)
+                self._lambda_counter += 1
+                qual = f"{owner}.<lambda@{node.lineno}:{node.col_offset}#{self._lambda_counter}>"
+                self._add_node(qual, node, is_lambda=True)
+                self._visit(node.body, qual, node, qual, "function")
+
+            case ast.ClassDef():
+                for dec in node.decorator_list:
+                    self._visit(dec, owner, owner_node, prefix, ctx)
+                for base in [*node.bases, *(kw.value for kw in node.keywords)]:
+                    self._visit(base, owner, owner_node, prefix, ctx)
+                cprefix = (
+                    f"{prefix}.{node.name}"
+                    if ctx in ("module", "class")
+                    else f"{owner}.<class:{node.name}@{node.lineno}>"
+                )
+                for stmt in node.body:
+                    self._visit(stmt, owner, owner_node, cprefix, "class")
+
+            case ast.Call():
+                self._emit_call(node, owner, owner_node, arg_of)
+                # the call's own arguments are visited with THIS call as their consumer, so a
+                # reference or a nested call in argument position is tagged; the callee and the
+                # rest get no argument context.
+                self._visit(node.func, owner, owner_node, prefix, ctx)
+                consumer = _dotted_of(node.func)
+                for index, arg in enumerate(node.args):
+                    self._visit(arg, owner, owner_node, prefix, ctx, arg_of=(consumer, index))
+                for kw in node.keywords:
+                    self._visit(kw.value, owner, owner_node, prefix, ctx, arg_of=(consumer, None))
+
+            case ast.Name() | ast.Attribute() if arg_of is not None:
+                # a function reference passed as an argument: a REF edge (passed, not called)
+                self._emit_ref(node, owner, owner_node, arg_of)
+
+            case _:
+                for child in ast.iter_child_nodes(node):
+                    self._visit(child, owner, owner_node, prefix, ctx)
+
+    def _emit_call(
+        self,
+        call: ast.Call,
+        owner: str,
+        owner_node: ScopeNode | None,
+        arg_of: tuple[str | None, int | None] | None,
+    ) -> None:
+        scope = self._scopes.info(owner_node) if owner_node is not None else None
+        target = self._resolver.resolve_callee(self._symbols, call.func, scope)
+        self._tally(call.func, target)
+        consumer, arg_index = arg_of if arg_of is not None else (None, None)
+        self.edges.append(
+            Edge(
+                source=owner,
+                target=target,
+                kind=EdgeKind.CALL,
+                position=self._pos(call),
+                source_text=_unparse(call),
+                consumer=consumer,
+                arg_index=arg_index,
+            )
+        )
+
+    def _emit_ref(
+        self,
+        ref: ast.expr,
+        owner: str,
+        owner_node: ScopeNode | None,
+        arg_of: tuple[str | None, int | None],
+    ) -> None:
+        scope = self._scopes.info(owner_node) if owner_node is not None else None
+        target = self._resolver.resolve_callee(self._symbols, ref, scope)
+        if isinstance(target, Internal | External):
+            consumer, arg_index = arg_of
+            self.edges.append(
+                Edge(
+                    source=owner,
+                    target=target,
+                    kind=EdgeKind.REF,
+                    position=self._pos(ref),
+                    source_text=_unparse(ref),
+                    consumer=consumer,
+                    arg_index=arg_index,
+                )
+            )
+
+    def _tally(self, callee: ast.expr, target: Target) -> None:
+        self.resolution["total"] += 1
+        if isinstance(callee, ast.Name):
+            shape = "by_name"
+        elif isinstance(callee, ast.Attribute):
+            shape = "attribute"
+        else:
+            shape = "dynamic"
+        self.resolution[f"shape_{shape}"] += 1
+        match target:
+            case Internal():
+                self.resolution["resolved_internal"] += 1
+            case External():
+                self.resolution["resolved_external"] += 1
+            case Unresolved(reason=reason):
+                self.resolution[f"unresolved_{reason}"] += 1
+
+
+def _unparse(node: ast.expr) -> str:
+    try:
+        return ast.unparse(node)
+    except (ValueError, RecursionError):
+        return "<unparseable>"
+
+
+def build_call_graph(
+    collection: Collection, analyses: dict[str, Analysis], resolver: Resolver
+) -> CallGraph:
+    """Assemble the whole-project call graph from every module's nodes and edges."""
+    nodes: dict[str, FuncNode] = {}
+    edges: list[Edge] = []
+    resolution: Counter[str] = Counter()
+    for module in collection.modules:
+        analysis = analyses.get(module.qualname)
+        if analysis is None:
+            continue
+        graph = _ModuleBuilder(module, analysis, resolver).build()
+        nodes.update(graph.nodes)
+        edges.extend(graph.edges)
+        resolution.update(graph.resolution)
+    return CallGraph(nodes=nodes, edges=edges, resolution=resolution)

blockpath/check.py

@@ -0,0 +1,33 @@
+"""The top-level entry point: analyse a project tree, return its findings.
+
+Six layers, in order: walk and parse (collect), name tables and scopes (symbols), resolve names
+to functions (resolve), build the call graph (callgraph), decide what blocks (oracle), and
+intersect the two reachabilities to produce witnesses (analysis).
+
+The project's own code is never imported or executed. A project that needs a database to import
+is analysed exactly like any other.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from blockpath.analysis import analyse
+from blockpath.callgraph import build_call_graph
+from blockpath.collect import collect
+from blockpath.config import DEFAULT, Config
+from blockpath.model import CheckResult
+from blockpath.oracle import Oracle
+from blockpath.resolve import Resolver
+from blockpath.symbols import analyze
+
+
+def check(root: Path, config: Config = DEFAULT, oracle: Oracle | None = None) -> CheckResult:
+    """Statically analyse the project rooted at ``root`` and return its findings."""
+    collection = collect(root)
+    analyses = {module.qualname: analyze(module) for module in collection.modules}
+    symbols = {qualname: item.symbols for qualname, item in analyses.items()}
+    resolver = Resolver(collection, symbols, max_depth=config.max_import_depth)
+    graph = build_call_graph(collection, analyses, resolver)
+    findings = analyse(graph, oracle or Oracle.load(), config)
+    return CheckResult(findings=findings, unparsed=collection.unparsed)