blockpath 0.1.0__py3-none-any.whl

blockpath/oracle.yaml

@@ -0,0 +1,222 @@
+# Which external calls stall an event loop.
+#
+# Data, not code: every entry is a claim that calling this name from a coroutine blocks the loop
+# thread, and each claim is small enough to argue with. Kept deliberately short -- roughly forty
+# entries -- because a list of 120 is a list nobody has checked. Wildcards are not used: a
+# wildcard is a claim about names that do not exist yet.
+#
+# Severity tiers:
+#   error    stalls the loop for an unbounded time (network, subprocess, a synchronous DB round
+#            trip, an explicit sleep). On by default; these fail CI.
+#   warning  stalls the loop for a bounded but real time, usually CPU-bound by design.
+#            Off by default, enable with --tier warning.
+#   off      local disk I/O. Off by default on purpose: turn it on and every
+#            `json.load(open(config))` fires, the signal drowns, and the tool gets switched off
+#            the first day. Enable deliberately with --tier off.
+#
+# Only module-level functions appear here. `requests.Session().get` and `self.session.get` are
+# attribute calls on a value, which v1 does not resolve at all (ADR 0003) -- listing them would
+# be theatre.
+
+version: 1
+
+entries:
+  # --- sleep -------------------------------------------------------------------------------
+  - name: time.sleep
+    category: sleep
+    severity: error
+    note: the canonical loop-stall; ruff ASYNC251 catches it only in the coroutine body
+
+  # --- synchronous HTTP --------------------------------------------------------------------
+  - name: requests.get
+    category: http
+    severity: error
+  - name: requests.post
+    category: http
+    severity: error
+  - name: requests.put
+    category: http
+    severity: error
+  - name: requests.patch
+    category: http
+    severity: error
+  - name: requests.delete
+    category: http
+    severity: error
+  - name: requests.head
+    category: http
+    severity: error
+  - name: requests.options
+    category: http
+    severity: error
+  - name: requests.request
+    category: http
+    severity: error
+  - name: httpx.get
+    category: http
+    severity: error
+    note: the sync API; httpx.AsyncClient is fine
+  - name: httpx.post
+    category: http
+    severity: error
+  - name: httpx.put
+    category: http
+    severity: error
+  - name: httpx.patch
+    category: http
+    severity: error
+  - name: httpx.delete
+    category: http
+    severity: error
+  - name: httpx.request
+    category: http
+    severity: error
+  - name: httpx.stream
+    category: http
+    severity: error
+  - name: urllib.request.urlopen
+    category: http
+    severity: error
+  - name: urllib.request.urlretrieve
+    category: http
+    severity: error
+
+  # --- sockets, DNS, legacy protocol clients -----------------------------------------------
+  - name: socket.create_connection
+    category: socket
+    severity: error
+  - name: socket.getaddrinfo
+    category: socket
+    severity: error
+    note: blocking DNS; a slow resolver stalls the loop for seconds
+  - name: socket.gethostbyname
+    category: socket
+    severity: error
+  - name: socket.gethostbyname_ex
+    category: socket
+    severity: error
+  - name: smtplib.SMTP
+    category: socket
+    severity: error
+    note: the constructor opens the connection
+  - name: smtplib.SMTP_SSL
+    category: socket
+    severity: error
+  - name: ftplib.FTP
+    category: socket
+    severity: error
+  - name: ftplib.FTP_TLS
+    category: socket
+    severity: error
+
+  # --- subprocess --------------------------------------------------------------------------
+  # subprocess.Popen is deliberately absent: it forks and returns. It is .wait() / .communicate()
+  # that block, and those are attribute calls on a value, which v1 does not resolve.
+  - name: subprocess.run
+    category: subprocess
+    severity: error
+  - name: subprocess.call
+    category: subprocess
+    severity: error
+  - name: subprocess.check_call
+    category: subprocess
+    severity: error
+  - name: subprocess.check_output
+    category: subprocess
+    severity: error
+  - name: subprocess.getoutput
+    category: subprocess
+    severity: error
+  - name: subprocess.getstatusoutput
+    category: subprocess
+    severity: error
+  - name: os.system
+    category: subprocess
+    severity: error
+  - name: os.popen
+    category: subprocess
+    severity: error
+  - name: os.waitpid
+    category: subprocess
+    severity: error
+
+  # --- synchronous database drivers ---------------------------------------------------------
+  # The connect call itself performs a round trip (or, for sqlite, touches the filesystem and
+  # takes locks). Queries run through cursor objects, which are attribute calls v1 cannot see.
+  - name: sqlite3.connect
+    category: db
+    severity: error
+    note: arguable -- local file, not network -- but it is a synchronous driver entry point and
+      it takes locks; the single most common finding on the survey corpus
+  - name: psycopg2.connect
+    category: db
+    severity: error
+  - name: psycopg.connect
+    category: db
+    severity: error
+  - name: pymysql.connect
+    category: db
+    severity: error
+  - name: MySQLdb.connect
+    category: db
+    severity: error
+  - name: pyodbc.connect
+    category: db
+    severity: error
+  - name: oracledb.connect
+    category: db
+    severity: error
+  - name: cx_Oracle.connect
+    category: db
+    severity: error
+  - name: clickhouse_driver.Client
+    category: db
+    severity: error
+
+  # --- CPU-bound by design (warning tier) ----------------------------------------------------
+  - name: hashlib.pbkdf2_hmac
+    category: cpu
+    severity: warning
+    note: deliberately slow key derivation; hundreds of milliseconds is the point
+  - name: hashlib.scrypt
+    category: cpu
+    severity: warning
+  - name: bcrypt.hashpw
+    category: cpu
+    severity: warning
+  - name: bcrypt.checkpw
+    category: cpu
+    severity: warning
+
+  # --- local disk I/O (off tier) --------------------------------------------------------------
+  - name: open
+    category: disk
+    severity: "off"
+    note: on by default this fires on every json.load(open(config)) and the tool gets disabled
+  - name: shutil.copy
+    category: disk
+    severity: "off"
+  - name: shutil.copytree
+    category: disk
+    severity: "off"
+  - name: shutil.rmtree
+    category: disk
+    severity: "off"
+
+# Primitives that hand a callable to another thread. A function *referenced* here runs off the
+# loop, which the analysis already handles by not traversing REF edges (ADR 0007). They are
+# listed because the reverse mistake -- CALLING the function instead of passing it -- is a real
+# bug with its own diagnostic (BLK002): `run_in_executor(None, fetch())` evaluates fetch() on the
+# loop before the executor ever sees it.
+#
+# `func_arg` is the positional index of the callable argument.
+offloads:
+  - match: [asyncio.to_thread, to_thread]
+    func_arg: 0
+  - match: [run_in_executor]
+    func_arg: 1
+    note: always a method on the loop, so matched on the attribute name alone
+  - match: [anyio.to_thread.run_sync, to_thread.run_sync, run_sync]
+    func_arg: 0
+  - match: [concurrent.futures.Executor.submit, submit]
+    func_arg: 0

blockpath/report.py

@@ -0,0 +1,140 @@
+"""Turning findings into something a human acts on, or a machine parses.
+
+The text reporter prints the *path*, not the fact. Anyone can say "there is a requests.get in
+clients/nominatim.py"; the point of this tool is the four lines above it that explain how a
+coroutine gets there, so a reader can see which hop to move off the loop. The witness is printed
+as a descending trace with the entry point and the blocking leaf both called out, and a hint
+naming the first hop -- the place ``asyncio.to_thread`` actually belongs.
+
+The JSON reporter emits the same content as a stable object per finding, for CI and for the
+runtime comparison in stage 7.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.text import Text
+
+from blockpath.model import CheckResult, Code, Finding, Severity
+
+_HEADLINE = {
+    Code.BLK001: "blocking call reachable from a coroutine",
+    Code.BLK002: "function called where it should have been passed to the executor",
+    Code.BLK003: "blocking call handed to an unresolved callee (strict)",
+}
+
+_SEVERITY_STYLE = {
+    Severity.ERROR: "bold red",
+    Severity.WARNING: "bold yellow",
+    Severity.OFF: "dim",
+}
+
+
+def _rel(path: Path, root: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+#: Source lines longer than this are elided; a trace that wraps is a trace nobody reads.
+_MAX_SOURCE = 88
+
+
+def render_text(result: CheckResult, root: Path, console: Console | None = None) -> None:
+    """Print findings as descending traces. Colour is dropped automatically when piped."""
+    out = console or Console()
+    for finding in result.findings:
+        # soft_wrap keeps a frame on one line: wrapping a call site mid-token makes the path
+        # unreadable, which defeats the entire point of printing the path.
+        out.print(_finding_text(finding, root), soft_wrap=True)
+        out.print()
+    out.print(_summary(result), soft_wrap=True)
+
+
+def _elide(source: str) -> str:
+    if len(source) <= _MAX_SOURCE:
+        return source
+    return source[: _MAX_SOURCE - 1] + "..."
+
+
+def _finding_text(finding: Finding, root: Path) -> Text:
+    text = Text()
+    text.append(str(finding.code), style=_SEVERITY_STYLE.get(finding.severity, "bold"))
+    text.append(f" {_HEADLINE[finding.code]}\n")
+
+    width = max(
+        (
+            len(f"{_rel(frame.position.path, root)}:{frame.position.line}")
+            for frame in finding.witness
+        ),
+        default=0,
+    )
+    last = len(finding.witness) - 1
+    for index, frame in enumerate(finding.witness):
+        where = f"{_rel(frame.position.path, root)}:{frame.position.line}"
+        indent = "  " + "  " * index
+        text.append(f"{indent}{where:<{width}}  ", style="dim")
+        text.append(_elide(frame.source_line) or frame.qualname.rsplit(".", 1)[-1])
+        if frame.entry_reason:
+            text.append(f"   <- entry: {frame.entry_reason}", style="cyan")
+        elif index == last:
+            text.append("   <- blocks the event loop", style="red")
+        text.append("\n")
+
+    if finding.hint:
+        text.append("  hint: ", style="dim")
+        text.append(finding.hint, style="green")
+        text.append("\n")
+    return text
+
+
+def _summary(result: CheckResult) -> Text:
+    text = Text()
+    if not result.findings:
+        text.append("no blocking calls reachable from a coroutine", style="bold green")
+    else:
+        counts: dict[str, int] = {}
+        for finding in result.findings:
+            counts[str(finding.code)] = counts.get(str(finding.code), 0) + 1
+        parts = ", ".join(f"{count} {code}" for code, count in sorted(counts.items()))
+        text.append(f"{len(result.findings)} finding(s): {parts}", style="bold red")
+    if result.unparsed:
+        text.append(
+            f"\n{len(result.unparsed)} file(s) could not be parsed and were skipped", style="yellow"
+        )
+    return text
+
+
+def render_json(result: CheckResult, root: Path) -> str:
+    """A stable machine-readable rendering: one object per finding, witness frames in order."""
+    payload = {
+        "version": 1,
+        "findings": [
+            {
+                "code": str(finding.code),
+                "severity": finding.severity.value,
+                "callee": finding.callee,
+                "category": finding.category,
+                "depth": finding.depth,
+                "hint": finding.hint,
+                "witness": [
+                    {
+                        "qualname": frame.qualname,
+                        "path": _rel(frame.position.path, root),
+                        "line": frame.position.line,
+                        "col": frame.position.col,
+                        "source": frame.source_line,
+                        "entry_reason": frame.entry_reason,
+                    }
+                    for frame in finding.witness
+                ],
+            }
+            for finding in result.findings
+        ],
+        "unparsed": [_rel(path, root) for path in result.unparsed],
+    }
+    return json.dumps(payload, indent=2)

blockpath/resolve.py

@@ -0,0 +1,192 @@
+"""Layer 3: resolve a name to the project function it denotes, or say why it cannot.
+
+This is the part the project lives or dies on, and the part that is routinely underestimated:
+resolving imports statically, without importing anything. ``resolve_dotted`` answers "what does
+``app.services.geo.locate`` point at" the way Python's own import machinery would -- walking
+``import`` bindings, unwinding re-exports through ``__init__.py``, honouring relative imports and
+src-layout -- and ``resolve_callee`` answers the caller's real question, "what does ``foo()`` or
+``self.session.get()`` in *this* function call", using the scope table to tell a shadow from a
+real reference.
+
+Three outcomes, and the third is a first-class citizen, not a failure:
+
+* :class:`Internal` -- a function defined in this project. This becomes a call-graph edge.
+* :class:`External` -- a name outside the project root (stdlib, a third-party package). The
+  oracle decides whether it blocks.
+* :class:`Unresolved` -- an attribute call on a value, a name bound two ways, a star-imported
+  name, a computed callee. The tool does not guess; by default these paths stay silent, and only
+  ``--strict`` surfaces them (BLK003). Guessing is how a linter earns its way into ``# noqa``.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+from dataclasses import dataclass
+from typing import Literal
+
+from blockpath.collect import Collection
+from blockpath.symbols import ImportBinding, ModuleSymbols, ScopeInfo
+
+_BUILTINS: frozenset[str] = frozenset(dir(builtins))
+
+UnresolvedReason = Literal[
+    "local_shadow",
+    "ambiguous_name",
+    "unknown_name",
+    "star_import",
+    "attribute_on_value",
+    "computed_callee",
+    "class_call",
+    "attribute_chain",
+    "ambiguous_module",
+    "chain_limit",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Internal:
+    qualname: str
+
+
+@dataclass(frozen=True, slots=True)
+class External:
+    dotted: str
+
+
+@dataclass(frozen=True, slots=True)
+class Unresolved:
+    reason: UnresolvedReason
+
+
+Target = Internal | External | Unresolved
+
+
+class Resolver:
+    def __init__(
+        self,
+        collection: Collection,
+        symbols: dict[str, ModuleSymbols],
+        *,
+        max_depth: int = 8,
+    ) -> None:
+        self._modules = collection.by_alias
+        self._ambiguous_modules = collection.ambiguous_aliases
+        self._internal_roots = collection.internal_roots
+        self._symbols = symbols
+        self._max_depth = max_depth
+
+    # -- dotted-name resolution (the unit the property test pins against importlib) ----------
+
+    def resolve_dotted(
+        self, dotted: str, _depth: int = 0, _seen: frozenset[str] = frozenset()
+    ) -> Target:
+        """Resolve a fully-qualified dotted name to the project function it ultimately denotes."""
+        if _depth > self._max_depth or dotted in _seen:
+            return Unresolved("chain_limit")
+
+        parts = dotted.split(".")
+        for i in range(len(parts) - 1, 0, -1):
+            module_name = ".".join(parts[:i])
+            if module_name in self._ambiguous_modules:
+                return Unresolved("ambiguous_module")
+            module = self._modules.get(module_name)
+            if module is None:
+                continue
+            attr = parts[i:]
+            if len(attr) > 1:
+                return Unresolved("attribute_chain")  # mod.Class.method: not resolved in v1
+            return self._resolve_in_module(module.qualname, attr[0], _depth, _seen | {dotted})
+
+        root = parts[0]
+        if root not in self._internal_roots:
+            return External(dotted)
+        return Unresolved("ambiguous_module")
+
+    def _resolve_in_module(
+        self, module_qualname: str, name: str, depth: int, seen: frozenset[str]
+    ) -> Target:
+        symbols = self._symbols.get(module_qualname)
+        if symbols is None:
+            return Unresolved("unknown_name")
+        if name in symbols.ambiguous:
+            return Unresolved("ambiguous_name")
+        sym = symbols.top_level.get(name)
+        if sym is None:
+            return Unresolved("star_import" if symbols.has_star_import else "unknown_name")
+        if isinstance(sym, ImportBinding):
+            return self.resolve_dotted(sym.target, depth + 1, seen)
+        if sym.kind == "class":
+            return Unresolved("class_call")
+        return Internal(sym.qualname)
+
+    # -- callee resolution (what callgraph actually asks) ------------------------------------
+
+    def resolve_callee(
+        self, module_symbols: ModuleSymbols, callee: ast.expr, scope: ScopeInfo | None
+    ) -> Target:
+        """Resolve the callee of a call expression in a given module and function scope."""
+        if scope is not None and scope.shadow_all:
+            # a scope we could not map: every name might be local, so resolve nothing
+            return (
+                Unresolved("local_shadow")
+                if isinstance(callee, ast.Name | ast.Attribute)
+                else Unresolved("computed_callee")
+            )
+        shadows = scope.shadows if scope is not None else frozenset()
+        local_imports = scope.local_imports if scope is not None else {}
+
+        if isinstance(callee, ast.Name):
+            name = callee.id
+            if name in local_imports:
+                return self.resolve_dotted(local_imports[name])
+            if name in shadows:
+                return Unresolved("local_shadow")
+            return self._resolve_bare_name(module_symbols, name)
+
+        if isinstance(callee, ast.Attribute):
+            dotted = _dotted_of(callee)
+            if dotted is None:
+                return Unresolved("computed_callee")
+            root, _, rest = dotted.partition(".")
+            if root in local_imports:
+                return self.resolve_dotted(f"{local_imports[root]}.{rest}")
+            if root in shadows:
+                return Unresolved("attribute_on_value")
+            if root in module_symbols.ambiguous:
+                return Unresolved("ambiguous_name")
+            sym = module_symbols.top_level.get(root)
+            if isinstance(sym, ImportBinding) and sym.target:
+                return self.resolve_dotted(f"{sym.target}.{rest}")
+            return Unresolved("attribute_on_value")
+
+        return Unresolved("computed_callee")
+
+    def _resolve_bare_name(self, module_symbols: ModuleSymbols, name: str) -> Target:
+        if name in module_symbols.ambiguous:
+            return Unresolved("ambiguous_name")
+        sym = module_symbols.top_level.get(name)
+        if sym is None:
+            if name in _BUILTINS:
+                return External(name)
+            return Unresolved("star_import" if module_symbols.has_star_import else "unknown_name")
+        if isinstance(sym, ImportBinding):
+            if not sym.target:
+                return Unresolved("ambiguous_name")
+            return self.resolve_dotted(sym.target)
+        if sym.kind == "class":
+            return Unresolved("class_call")
+        return Internal(sym.qualname)
+
+
+def _dotted_of(expr: ast.expr) -> str | None:
+    """``a.b.c`` -> "a.b.c"; a computed base (``foo().bar``) -> 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))

blockpath/runtime/__init__.py

@@ -0,0 +1,22 @@
+"""Runtime verification: what the static analysis claims, checked against what actually ran.
+
+Two different measurements, deliberately kept apart because they answer different questions:
+
+* :mod:`blockpath.runtime.watchdog` measures **impact** -- how long the event loop was actually
+  stalled, and what the loop thread was doing at the time.
+* :mod:`blockpath.runtime.monitor` measures **execution** -- which of the project's own functions
+  really ran while a loop was running in that thread. This is what gives a *lower bound* on the
+  static analysis's recall: the runtime only ever sees code the tests happened to execute, so it
+  can prove a miss but can never prove completeness, and it says nothing at all about precision.
+
+Both rest on one predicate -- "is a loop running in this thread right now" -- answered by
+``asyncio.get_running_loop()`` and never by inspecting frame ``co_flags`` (ADR 0004).
+"""
+
+from __future__ import annotations
+
+from blockpath.runtime.monitor import Monitor, Observation
+from blockpath.runtime.predicate import on_event_loop
+from blockpath.runtime.watchdog import LoopWatchdog, Stall
+
+__all__ = ["LoopWatchdog", "Monitor", "Observation", "Stall", "on_event_loop"]