blockpath 0.1.0__py3-none-any.whl

blockpath/runtime/monitor.py

@@ -0,0 +1,157 @@
+"""Which of the project's own functions actually executed while a loop was running.
+
+Built on ``sys.monitoring`` (PEP 669, hence Python 3.12+, ADR 0001). The shape of the
+instrumentation matters more than it looks:
+
+* A ``PY_START`` callback is registered globally, but the *first* time it sees a code object
+  from outside the project it returns ``sys.monitoring.DISABLE``, which permanently stops events
+  for that code object. Third-party and stdlib code therefore costs one event each, once, and
+  nothing thereafter. Measured on a call-heavy workload: 1.09x baseline, against 1.29x for the
+  same callback without ``DISABLE``. That is the difference between a verifier you can leave on
+  during a test suite and one nobody runs twice.
+* The tool id is 3 by default, not the reserved 0/1/2/5 (debugger, coverage, profiler,
+  optimizer). Checked empirically on 3.13 with ``COVERAGE_CORE=sysmon``: coverage.py holds id 1
+  and blockpath holds id 3 in the same process, both receiving their events. ``sys.monitoring``
+  multiplexes by tool id, so running under coverage is not a conflict.
+
+Recording is gated on :func:`blockpath.runtime.predicate.on_event_loop`, so a project function
+that runs in a worker thread (``to_thread``) is correctly *not* recorded as having run on the
+loop.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from types import CodeType
+
+from blockpath.runtime.predicate import on_event_loop
+
+#: Default tool id. 0/1/2/5 are reserved for debugger / coverage / profiler / optimizer.
+DEFAULT_TOOL_ID = 3
+_FALLBACK_TOOL_IDS = (4, 3)
+
+
+@dataclass(frozen=True, slots=True)
+class Observation:
+    """A project function seen entering while a loop ran in that thread."""
+
+    path: str
+    qualname: str
+    line: int
+    count: int
+
+
+class MonitorError(RuntimeError):
+    pass
+
+
+class Monitor:
+    """Records project functions that execute while an event loop runs in the same thread."""
+
+    def __init__(self, project_root: Path, tool_id: int | None = None) -> None:
+        self._root = project_root.resolve()
+        self._requested_id = tool_id
+        self._tool_id: int | None = None
+        self._seen: Counter[tuple[str, str, int]] = Counter()
+        self._started = False
+
+    # -- lifecycle ----------------------------------------------------------------------------
+
+    def start(self) -> None:
+        if self._started:
+            return
+        self._tool_id = self._claim_tool_id()
+        mon = sys.monitoring
+        mon.register_callback(self._tool_id, mon.events.PY_START, self._on_py_start)
+        mon.set_events(self._tool_id, mon.events.PY_START)
+        self._started = True
+
+    def stop(self) -> None:
+        if not self._started or self._tool_id is None:
+            return
+        mon = sys.monitoring
+        mon.set_events(self._tool_id, 0)
+        mon.register_callback(self._tool_id, mon.events.PY_START, None)
+        mon.free_tool_id(self._tool_id)
+        self._tool_id = None
+        self._started = False
+
+    def __enter__(self) -> Monitor:
+        self.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.stop()
+
+    def _claim_tool_id(self) -> int:
+        candidates = (
+            (self._requested_id,)
+            if self._requested_id is not None
+            else (DEFAULT_TOOL_ID, *_FALLBACK_TOOL_IDS)
+        )
+        for candidate in candidates:
+            if sys.monitoring.get_tool(candidate) is None:
+                sys.monitoring.use_tool_id(candidate, "blockpath")
+                return candidate
+        holders = {i: sys.monitoring.get_tool(i) for i in range(6)}
+        raise MonitorError(
+            f"no free sys.monitoring tool id; currently held: {holders}. "
+            "Another tool (a debugger, coverage in sysmon mode, a profiler) holds them all."
+        )
+
+    # -- the hot path -------------------------------------------------------------------------
+
+    def _on_py_start(self, code: CodeType, instruction_offset: int) -> object:
+        if not self._is_project(code.co_filename):
+            # permanently stop events for this code object: third-party and stdlib cost one
+            # event each, once, and nothing afterwards
+            return sys.monitoring.DISABLE
+        if not on_event_loop():
+            # project code, but not on a loop right now; it may be later, so keep watching it
+            return None
+        self._seen[(code.co_filename, code.co_qualname, code.co_firstlineno)] += 1
+        return None
+
+    def _is_project(self, filename: str) -> bool:
+        if not filename or filename.startswith("<"):
+            return False
+        try:
+            return Path(filename).resolve().is_relative_to(self._root)
+        except (OSError, ValueError):
+            return False
+
+    # -- results ------------------------------------------------------------------------------
+
+    @property
+    def observations(self) -> list[Observation]:
+        out = [
+            Observation(
+                path=self._relative(path),
+                qualname=qualname,
+                line=line,
+                count=count,
+            )
+            for (path, qualname, line), count in sorted(self._seen.items())
+        ]
+        return out
+
+    def _relative(self, filename: str) -> str:
+        try:
+            return Path(filename).resolve().relative_to(self._root).as_posix()
+        except (OSError, ValueError):
+            return filename
+
+    def dump(self, path: Path) -> None:
+        payload = {
+            "version": 1,
+            "root": str(self._root),
+            "observations": [
+                {"path": o.path, "qualname": o.qualname, "line": o.line, "count": o.count}
+                for o in self.observations
+            ],
+        }
+        path.write_text(json.dumps(payload, indent=2))

blockpath/runtime/predicate.py

@@ -0,0 +1,39 @@
+"""The one predicate the whole runtime layer rests on: is a loop running in *this* thread?
+
+Three lines, and the reason they are these three lines rather than a walk over frame
+``co_flags`` is worth stating, because the frame version looks equivalent and is not (ADR 0004):
+
+* ``loop.call_soon(blocking_fn)`` runs a *synchronous* callback. There is no coroutine anywhere
+  on the stack, yet the loop is stalled for the duration. ``co_flags`` says "not async" and
+  misses it entirely -- and this is the single most common way a blocking call sneaks onto a
+  loop that someone has already audited for ``async def`` bodies.
+* A coroutine running in *another* thread's loop puts ``CO_COROUTINE`` on that thread's stack.
+  It stalls that loop, not this one. ``co_flags`` cannot tell the threads apart.
+* Synchronous code inside ``run_in_executor`` has a coroutine above it in the calling thread,
+  but executes in a worker thread where no loop runs. ``co_flags`` gives a false positive --
+  precisely the offloaded case the tool must stay quiet about.
+
+``asyncio.get_running_loop()`` asks exactly the right question, and asks it per-thread, which is
+what the question was in the first place. Frames are used only to report *where* something
+happened, never to decide *whether* it was on the loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+
+def on_event_loop() -> bool:
+    """True when an asyncio event loop is running in the calling thread."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return False
+    return True
+
+
+def running_loop_thread_id() -> int | None:
+    """The id of the thread whose loop is running here, or None when there is no loop."""
+    import threading
+
+    return threading.get_ident() if on_event_loop() else None

blockpath/runtime/verify.py

@@ -0,0 +1,177 @@
+"""``blockpath verify -- <command>`` and ``blockpath compare``.
+
+``verify`` runs the project's own test suite (or any command) with the monitor attached, and
+records which of the project's functions actually executed while a loop was running. The monitor
+has to live *inside* that process, so a ``sitecustomize`` shim is put on ``PYTHONPATH`` -- the
+same mechanism coverage uses to measure subprocesses -- and it dumps its observations at exit.
+
+``compare`` puts the static findings next to those observations and sorts them into three piles:
+
+* **confirmed** -- static said this function reaches a blocking call, and the runtime saw the
+  function run on the loop.
+* **unexercised** -- static said so, but the tests never ran that function. This says nothing
+  about whether the finding is right; it says the suite does not cover it.
+* **missed** -- the runtime saw a function run on the loop, that function contains a blocking
+  call, and static did *not* report it. Each of these is a proven hole in the analysis.
+
+The ratio confirmed / (confirmed + missed) is a **lower bound on recall**, and nothing else. The
+runtime only ever sees paths the tests happened to execute, so it can prove a miss and can never
+prove completeness -- and it says nothing whatsoever about precision, which only hand
+adjudication can establish.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from blockpath.check import check
+from blockpath.config import Config
+from blockpath.model import Finding
+
+_SHIM = '''\
+"""Injected by `blockpath verify`: start the monitor before the target runs."""
+import atexit
+import os
+from pathlib import Path
+
+try:
+    from blockpath.runtime.monitor import Monitor
+except Exception:  # blockpath not importable in this interpreter: stay out of the way
+    pass
+else:
+    _root = os.environ.get("BLOCKPATH_ROOT")
+    _out = os.environ.get("BLOCKPATH_OUT")
+    if _root and _out:
+        _monitor = Monitor(Path(_root))
+        try:
+            _monitor.start()
+        except Exception:
+            pass
+        else:
+            @atexit.register
+            def _dump() -> None:
+                try:
+                    _monitor.stop()
+                    _monitor.dump(Path(_out))
+                except Exception:
+                    pass
+'''
+
+
+@dataclass(frozen=True, slots=True)
+class VerifyResult:
+    exit_code: int
+    observations_path: Path
+    observed: int
+
+
+def run_verify(command: tuple[str, ...], root: Path, out_path: Path) -> VerifyResult:
+    """Run ``command`` with the monitor attached; write observations to ``out_path``."""
+    root = root.resolve()
+    with tempfile.TemporaryDirectory(prefix="blockpath-shim-") as shim_dir:
+        (Path(shim_dir) / "sitecustomize.py").write_text(_SHIM)
+        env = os.environ.copy()
+        existing = env.get("PYTHONPATH", "")
+        env["PYTHONPATH"] = shim_dir + (os.pathsep + existing if existing else "")
+        env["BLOCKPATH_ROOT"] = str(root)
+        env["BLOCKPATH_OUT"] = str(out_path)
+        proc = subprocess.run(command, env=env, cwd=root, check=False)
+    observed = 0
+    if out_path.is_file():
+        try:
+            observed = len(json.loads(out_path.read_text()).get("observations", []))
+        except (OSError, json.JSONDecodeError):
+            observed = 0
+    return VerifyResult(exit_code=proc.returncode, observations_path=out_path, observed=observed)
+
+
+@dataclass(frozen=True, slots=True)
+class Comparison:
+    confirmed: tuple[Finding, ...]
+    unexercised: tuple[Finding, ...]
+    missed: tuple[tuple[str, str], ...]  # (path, qualname) observed on the loop but not reported
+
+    @property
+    def recall_lower_bound(self) -> float | None:
+        denominator = len(self.confirmed) + len(self.missed)
+        if denominator == 0:
+            return None
+        return len(self.confirmed) / denominator
+
+
+def _simple(qualname: str) -> str:
+    return qualname.rsplit(".", 1)[-1]
+
+
+def load_observations(path: Path) -> set[tuple[str, str]]:
+    """(relpath, simple function name) pairs seen executing while a loop ran."""
+    data = json.loads(path.read_text())
+    return {(item["path"], _simple(str(item["qualname"]))) for item in data.get("observations", [])}
+
+
+def compare(root: Path, observations: set[tuple[str, str]], config: Config) -> Comparison:
+    """Sort static findings against what the runtime actually saw execute.
+
+    Functions are matched on (relative path, simple function name). That is a heuristic: two
+    functions of the same name in one file collide. It is documented rather than hidden, and it
+    only ever affects which pile a finding lands in, never the finding itself.
+    """
+    root = root.resolve()
+    result = check(root, config)
+
+    confirmed: list[Finding] = []
+    unexercised: list[Finding] = []
+    for finding in result.findings:
+        leaf = finding.leaf
+        rel = _rel(leaf.position.path, root)
+        name = _simple(leaf.qualname)
+        if (rel, name) in observations:
+            confirmed.append(finding)
+        else:
+            unexercised.append(finding)
+
+    reported = {
+        (_rel(f.leaf.position.path, root), _simple(f.leaf.qualname)) for f in result.findings
+    }
+    missed = tuple(sorted(observations - reported - _clean_functions(root, config, observations)))
+    return Comparison(tuple(confirmed), tuple(unexercised), missed)
+
+
+def _clean_functions(
+    root: Path, config: Config, observations: set[tuple[str, str]]
+) -> set[tuple[str, str]]:
+    """Observed functions that contain no blocking call at all, so their absence is correct."""
+    from blockpath.callgraph import EdgeKind, build_call_graph
+    from blockpath.collect import collect
+    from blockpath.oracle import Oracle
+    from blockpath.resolve import External, Resolver
+    from blockpath.symbols import analyze
+
+    collection = collect(root)
+    analyses = {m.qualname: analyze(m) for m in collection.modules}
+    resolver = Resolver(collection, {q: a.symbols for q, a in analyses.items()})
+    graph = build_call_graph(collection, analyses, resolver)
+    oracle = Oracle.load()
+
+    blocking_owners: set[tuple[str, str]] = set()
+    for edge in graph.edges:
+        if edge.kind is not EdgeKind.CALL or not isinstance(edge.target, External):
+            continue
+        if oracle.blocks(edge.target.dotted, config.enabled_tiers) is None:
+            continue
+        node = graph.nodes.get(edge.source)
+        if node is not None:
+            blocking_owners.add((_rel(node.position.path, root), _simple(edge.source)))
+    return observations - blocking_owners
+
+
+def _rel(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root).as_posix()
+    except ValueError:
+        return str(path)

blockpath/runtime/watchdog.py

@@ -0,0 +1,117 @@
+"""How long the event loop was actually stalled, and what it was doing at the time.
+
+A thread outside the loop pings it with ``call_soon_threadsafe`` and times the reply. If the
+reply does not come back within the lag threshold the loop is, by definition, busy doing
+something synchronous -- so the watchdog snapshots the *loop thread's* stack right then, while
+the blocking call is still on it. That stack is the evidence: it names the file and line that is
+holding the loop, which is exactly the claim the static analysis makes in advance.
+
+This is the "impact" half of the runtime layer. It answers "the loop stalled 812 ms, here", where
+the monitor answers "this function ran while a loop was running". Neither substitutes for the
+other, and neither measures precision -- see the recall caveat in the package docstring.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+import time
+import traceback
+from asyncio import AbstractEventLoop
+from dataclasses import dataclass, field
+
+#: How often the watchdog pings the loop.
+DEFAULT_PING_INTERVAL = 0.010
+#: A reply slower than this means the loop was busy; snapshot it.
+DEFAULT_LAG_THRESHOLD = 0.050
+
+
+@dataclass(frozen=True, slots=True)
+class Stall:
+    """One observed stall: how long the loop failed to answer, and where it was."""
+
+    duration: float
+    #: innermost-last frames of the loop thread, captured while it was still blocked
+    stack: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def where(self) -> str:
+        return self.stack[-1] if self.stack else "<unknown>"
+
+
+class LoopWatchdog:
+    """Pings a running loop from another thread and records how long replies take.
+
+    Thresholds are constructor arguments rather than constants so a slow CI box or a chatty
+    service can be tuned without editing the source; the defaults (ping every 10 ms, complain
+    past 50 ms) are chosen so ordinary scheduling jitter does not register as a stall.
+    """
+
+    def __init__(
+        self,
+        loop: AbstractEventLoop,
+        *,
+        ping_interval: float = DEFAULT_PING_INTERVAL,
+        lag_threshold: float = DEFAULT_LAG_THRESHOLD,
+    ) -> None:
+        self._loop = loop
+        self._ping_interval = ping_interval
+        self._lag_threshold = lag_threshold
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._loop_thread_id: int | None = None
+        self.stalls: list[Stall] = []
+
+    def start(self) -> None:
+        # Learn which thread the loop runs on, so the snapshot targets the right stack.
+        done = threading.Event()
+
+        def note_thread() -> None:
+            self._loop_thread_id = threading.get_ident()
+            done.set()
+
+        self._loop.call_soon_threadsafe(note_thread)
+        done.wait(timeout=1.0)
+
+        self._thread = threading.Thread(target=self._run, name="blockpath-watchdog", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+            self._thread = None
+
+    def __enter__(self) -> LoopWatchdog:
+        self.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.stop()
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            answered = threading.Event()
+            sent = time.perf_counter()
+            try:
+                self._loop.call_soon_threadsafe(answered.set)
+            except RuntimeError:
+                return  # loop closed underneath us; nothing left to watch
+            if not answered.wait(self._lag_threshold):
+                # The loop owes us a reply and has not sent it: it is blocked right now, so this
+                # is the one moment the offending frame is still on its stack.
+                stack = self._snapshot()
+                answered.wait(timeout=30.0)
+                self.stalls.append(Stall(duration=time.perf_counter() - sent, stack=stack))
+            self._stop.wait(self._ping_interval)
+
+    def _snapshot(self) -> tuple[str, ...]:
+        if self._loop_thread_id is None:
+            return ()
+        frame = sys._current_frames().get(self._loop_thread_id)
+        if frame is None:
+            return ()
+        return tuple(
+            f"{entry.filename}:{entry.lineno} {entry.name}"
+            for entry in traceback.extract_stack(frame)
+        )