blast-scope 0.3.0__py3-none-any.whl

blast_scope/__init__.py

@@ -0,0 +1,3 @@
+"""blast-scope: contextual blast radius scoring for shell commands."""
+
+__version__ = "0.1.0"

blast_scope/centrality.py

@@ -0,0 +1,117 @@
+"""Weighted PageRank over the dependency graph — pure Python, no numpy/scipy.
+
+Raw in-degree (how many edges point at a file) is a shallow proxy for blast
+radius: a file imported by two leaf scripts looks identical to one imported by
+two hub modules that the whole app routes through. PageRank fixes this — a node
+is important if *important* nodes depend on it, computed transitively over the
+whole graph.
+
+Edges run ``source → target`` meaning "source depends on target" (``a.py``
+``IMPORTS_FROM`` ``b.py`` is an edge ``a → b``). So importance accumulates on
+the depended-upon ``target`` side, which is exactly the blast-radius signal we
+want: deleting a high-PageRank file breaks a lot.
+
+Edge kinds are weighted — a runtime ``IMPORTS_FROM`` carries more structural
+consequence than a ``TESTED_BY`` or ``CONTAINS`` edge.
+"""
+
+from __future__ import annotations
+
+# Structural significance of each edge kind. Higher = a heavier dependency.
+EDGE_WEIGHTS: dict[str, float] = {
+    "IMPORTS_FROM": 1.0,
+    "DEPENDS_ON": 1.0,
+    "INHERITS": 0.9,
+    "IMPLEMENTS": 0.9,
+    "CALLS": 0.8,
+    "REFERENCES": 0.5,
+    "CONTAINS": 0.3,
+    "TESTED_BY": 0.2,
+}
+DEFAULT_EDGE_WEIGHT: float = 0.5
+
+
+def edge_weight(kind: str) -> float:
+    """Return the structural weight for an edge kind.
+
+    Example::
+
+        >>> edge_weight("IMPORTS_FROM")
+        1.0
+        >>> edge_weight("MYSTERY_EDGE")
+        0.5
+    """
+    return EDGE_WEIGHTS.get(kind, DEFAULT_EDGE_WEIGHT)
+
+
+def pagerank(
+    edges: list[tuple[str, str, str]],
+    *,
+    damping: float = 0.85,
+    max_iter: int = 100,
+    tol: float = 1.0e-6,
+) -> dict[str, float]:
+    """Compute weighted PageRank over a dependency graph.
+
+    Args:
+        edges: ``(source, target, kind)`` triples. ``source`` depends on
+            ``target``; importance flows toward ``target``.
+        damping: Probability of following an edge vs. teleporting (classic 0.85).
+        max_iter: Hard cap on power-iteration steps.
+        tol: L1-convergence threshold for early stopping.
+
+    Returns:
+        ``{qualified_name: score}`` with scores normalized so the most central
+        node is ``1.0``. Returns ``{}`` for an empty graph.
+
+    Example::
+
+        >>> pr = pagerank([("a", "c", "IMPORTS_FROM"), ("b", "c", "IMPORTS_FROM")])
+        >>> max(pr, key=pr.get)
+        'c'
+    """
+    if not edges:
+        return {}
+
+    # Build node set and weighted outgoing adjacency.
+    nodes: set[str] = set()
+    out: dict[str, list[tuple[str, float]]] = {}
+    out_weight: dict[str, float] = {}
+    for source, target, kind in edges:
+        nodes.add(source)
+        nodes.add(target)
+        w = edge_weight(kind)
+        out.setdefault(source, []).append((target, w))
+        out_weight[source] = out_weight.get(source, 0.0) + w
+
+    n = len(nodes)
+    if n == 0:
+        return {}
+
+    base = (1.0 - damping) / n
+    rank: dict[str, float] = {node: 1.0 / n for node in nodes}
+
+    for _ in range(max_iter):
+        # Dangling nodes (no outgoing edges) redistribute their mass uniformly.
+        dangling = sum(rank[node] for node in nodes if out_weight.get(node, 0.0) == 0.0)
+        dangling_share = damping * dangling / n
+
+        new_rank: dict[str, float] = {node: base + dangling_share for node in nodes}
+        for source, targets in out.items():
+            src_rank = rank[source]
+            total_w = out_weight[source]
+            if total_w == 0.0:
+                continue
+            contribution = damping * src_rank / total_w
+            for target, w in targets:
+                new_rank[target] += contribution * w
+
+        delta = sum(abs(new_rank[node] - rank[node]) for node in nodes)
+        rank = new_rank
+        if delta < tol:
+            break
+
+    peak = max(rank.values())
+    if peak <= 0.0:
+        return {node: 0.0 for node in nodes}
+    return {node: score / peak for node, score in rank.items()}

blast_scope/classes/__init__.py

@@ -0,0 +1,129 @@
+"""Consequence *classes* — per-command-class blast-radius analyzers.
+
+This generalizes the proven consequence-analyzer pattern (``vcs`` / ``infra`` /
+``config_refs``) into a registry of command *classes* (git, docker, pip/uv,
+SQL), each running two stages so the common case stays cheap:
+
+1. **triage** — a near-free check ("is this my class, and is it destructive?").
+   Pure string/flag inspection, *no* subprocess. The vast majority of commands
+   match nothing here and exit immediately.
+2. **assess** — run only for triaged candidates. Performs a strictly
+   side-effect-free *probe* when one is available, otherwise falls back to a
+   labeled heuristic estimate. Either way it returns a :class:`Consequence`
+   floor the scorer already knows how to consume.
+
+The eligibility filter is structural: a class is only allowed a live probe when
+both (a) a safe, side-effect-free read can observe the impact and (b) its
+reversibility is authorable in a static table. State-mutating probes are out of
+scope by construction — :meth:`ConsequenceClass.probe_commands` declares exactly
+what a class may run, and the test-suite asserts that surface is read-only.
+
+Adding a class = implement the protocol and list it in :func:`registry`.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from blast_scope.command_parser import ParsedCommand
+from blast_scope.consequences import Consequence
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """Stage-1 result: a destructive operation a class recognized in a command.
+
+    Example::
+
+        Candidate(cls="git", operation="reset_hard", raw="git reset --hard")
+    """
+
+    cls: str  # class name, e.g. "git"
+    operation: str  # class-specific op id, e.g. "reset_hard" | "volume_rm"
+    raw: str  # the original command segment (probes may re-derive operands)
+    operands: tuple[str, ...] = field(default_factory=tuple)
+
+
+@runtime_checkable
+class ConsequenceClass(Protocol):
+    """A command class that can triage and assess its destructive operations."""
+
+    name: str
+
+    def triage(self, raw: str, parsed: ParsedCommand) -> Candidate | None:
+        """Cheaply decide if ``raw`` is a destructive op of this class.
+
+        Must be near-free (no subprocess / network). Returns a
+        :class:`Candidate` for destructive matches, else ``None``.
+        """
+        ...
+
+    def probe_commands(self, candidate: Candidate) -> list[list[str]]:
+        """The exact, **read-only** operations ``assess`` may issue to probe impact.
+
+        Each entry is a token list — a shell command (``["docker", "ps", ...]``)
+        or a query (``["SELECT", "count(*) ..."]``). Declared separately so tests
+        can assert the probe surface never mutates state. A class that probes only
+        by reading files (no command/query) returns ``[]``.
+        """
+        ...
+
+    def assess(self, candidate: Candidate, cwd: Path) -> Consequence | None:
+        """Probe (if safe + available) or estimate; return a floor consequence.
+
+        Must never raise for an unavailable probe — degrade to a heuristic and
+        mark the result ``estimated=True``.
+        """
+        ...
+
+
+def registry() -> list[ConsequenceClass]:
+    """Return the registered consequence classes.
+
+    Imported lazily so the package stays import-cycle-free and classes that
+    shell out are only loaded when consequence analysis actually runs.
+    """
+    from blast_scope.classes.docker import DockerClass
+    from blast_scope.classes.git import GitClass
+    from blast_scope.classes.packages import PackagesClass
+    from blast_scope.classes.sql import SqlClass
+
+    return [GitClass(), DockerClass(), PackagesClass(), SqlClass()]
+
+
+def gather_classes(parsed: ParsedCommand, raw: str, cwd: Path | str) -> list[Consequence]:
+    """Triage every class against one command; assess only the matches.
+
+    This is the integration point ``consequences.gather`` calls. Triage is
+    cheap and runs for all classes; the (potentially probing) ``assess`` runs
+    only for triaged destructive candidates. Any class error degrades to
+    "no consequence" — analysis is advisory and must never block a command.
+
+    Example::
+
+        >>> gather_classes(parse_command("git reset --hard"), "git reset --hard", cwd)
+        [Consequence(domain='vcs', floor=0.6, ...)]
+    """
+    cwd_path = Path(cwd)
+    out: list[Consequence] = []
+    for cls in registry():
+        try:
+            candidate = cls.triage(raw, parsed)
+        except Exception:  # a triage bug must never break assessment
+            logger.debug("triage failed for class %s", getattr(cls, "name", cls), exc_info=True)
+            continue
+        if candidate is None:
+            continue
+        try:
+            consequence = cls.assess(candidate, cwd_path)
+        except Exception:  # probe/heuristic bug → degrade to silent for this class
+            logger.debug("assess failed for %s", candidate, exc_info=True)
+            continue
+        if consequence is not None:
+            out.append(consequence)
+    return out

blast_scope/classes/docker.py

@@ -0,0 +1,281 @@
+"""Docker consequence class — container/volume blast radius.
+
+Docker's destructive verbs split cleanly along reversibility:
+
+- **volumes** carry data with *no image to rebuild from* — ``docker volume rm``
+  or a ``system prune --volumes`` is irreversible.
+- **containers / images** are recreatable: ``docker rm -f`` drops a container
+  that its image can recreate; ``system prune -a`` removes images that are
+  re-pullable (a slow rebuild, not a loss).
+
+The safe probe is the read-only daemon API (``volume inspect`` / ``ps`` /
+``volume ls`` / ``images`` — see :meth:`DockerClass.probe_commands`). When the
+docker CLI is missing or the daemon is unreachable, the class degrades to a
+heuristic floor and labels it ``estimated``.
+"""
+
+from __future__ import annotations
+
+import logging
+import shlex
+import subprocess
+from pathlib import Path
+
+from blast_scope.classes import Candidate
+from blast_scope.command_parser import ParsedCommand
+from blast_scope.consequences import Consequence
+
+logger = logging.getLogger(__name__)
+
+_PROBE_TIMEOUT = 3.0
+_DOCKER_OBJECTS = frozenset({"volume", "system", "container", "image", "network"})
+
+
+class DockerClass:
+    """Consequence class for destructive docker operations."""
+
+    name = "docker"
+
+    # -- Stage 1: triage -----------------------------------------------------
+
+    def triage(self, raw: str, parsed: ParsedCommand) -> Candidate | None:
+        """Recognize ``docker volume rm`` / ``system prune`` / ``rm -f`` cheaply."""
+        if parsed.get("command") != "docker":
+            return None
+        spec = _parse_docker(raw)
+        if spec is None:
+            return None
+        op = _docker_op(spec)
+        if op is None:
+            return None
+        operation, operands = op
+        return Candidate(cls=self.name, operation=operation, raw=raw, operands=operands)
+
+    # -- declared read-only probe surface ------------------------------------
+
+    def probe_commands(self, candidate: Candidate) -> list[list[str]]:
+        """The read-only docker reads ``assess`` may run for this candidate."""
+        cmds: list[list[str]] = [["docker", "volume", "ls", "-q"]]
+        if candidate.operation == "volume_rm":
+            cmds += [
+                ["docker", "volume", "inspect", "<vol>"],
+                ["docker", "ps", "-a", "--filter", "volume=<vol>", "--format", "{{.Names}}"],
+            ]
+        elif candidate.operation in ("system_prune", "volume_prune"):
+            cmds += [
+                ["docker", "volume", "ls", "-f", "dangling=true", "-q"],
+                ["docker", "ps", "-a", "-q"],
+                ["docker", "images", "-q"],
+            ]
+        elif candidate.operation == "container_rm":
+            cmds += [["docker", "ps", "-a", "--filter", "name=<c>", "--format", "{{.Names}}"]]
+        return cmds
+
+    # -- Stage 2: assess -----------------------------------------------------
+
+    def assess(self, candidate: Candidate, cwd: Path) -> Consequence | None:
+        """Probe the daemon (if reachable) or estimate; return a floor."""
+        daemon = _daemon_up(cwd)
+        op = candidate.operation
+        if op == "volume_rm":
+            return _assess_volume_rm(candidate.operands, cwd, daemon)
+        if op == "volume_prune":
+            return _assess_volume_prune(cwd, daemon)
+        if op == "system_prune":
+            return _assess_system_prune(candidate.raw, cwd, daemon)
+        if op == "container_rm":
+            return _assess_container_rm(candidate.operands, cwd, daemon)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Parsing (pure)
+# ---------------------------------------------------------------------------
+
+
+def _parse_docker(raw: str) -> tuple[str, str, list[str], list[str]] | None:
+    """Split a docker command into (object, action, args, flags)."""
+    try:
+        tokens = shlex.split(raw)
+    except ValueError:
+        tokens = raw.split()
+    if not tokens:
+        return None
+    if tokens[0] == "sudo" and len(tokens) >= 2 and tokens[1] == "docker":
+        tokens = tokens[1:]
+    if not tokens or tokens[0] != "docker":
+        return None
+
+    rest = tokens[1:]
+    flags = [t for t in rest if t.startswith("-")]
+    positional = [t for t in rest if not t.startswith("-")]
+    if not positional:
+        return None
+
+    if positional[0] in _DOCKER_OBJECTS:
+        obj = positional[0]
+        action = positional[1] if len(positional) > 1 else ""
+        args = positional[2:]
+    else:
+        obj = ""
+        action = positional[0]
+        args = positional[1:]
+    return obj, action, args, flags
+
+
+def _docker_op(spec: tuple[str, str, list[str], list[str]]) -> tuple[str, tuple[str, ...]] | None:
+    """Map a parsed docker command to a destructive operation id, or ``None``."""
+    obj, action, args, flags = spec
+    force = any(f in ("-f", "--force") for f in flags)
+    if obj == "volume" and action == "rm":
+        return ("volume_rm", tuple(args))
+    if obj == "volume" and action == "prune":
+        return ("volume_prune", ())
+    if obj == "system" and action == "prune":
+        return ("system_prune", ())
+    if action == "rm" and force and obj in ("", "container"):
+        return ("container_rm", tuple(args))
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Probe helpers (read-only)
+# ---------------------------------------------------------------------------
+
+
+def _run_docker(cwd: Path, *args: str) -> tuple[bool, str]:
+    """Run a read-only docker command → (succeeded, stdout). Never raises."""
+    try:
+        result = subprocess.run(
+            ["docker", *args],
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            timeout=_PROBE_TIMEOUT,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return (False, "")
+    return (result.returncode == 0, result.stdout.strip())
+
+
+def _daemon_up(cwd: Path) -> bool:
+    """True if the docker CLI exists and the daemon answers a read-only call."""
+    return _run_docker(cwd, "volume", "ls", "-q")[0]
+
+
+def _count_lines(out: str) -> int:
+    return len([ln for ln in out.splitlines() if ln.strip()])
+
+
+# ---------------------------------------------------------------------------
+# Per-operation assessment
+# ---------------------------------------------------------------------------
+
+
+def _assess_volume_rm(volumes: tuple[str, ...], cwd: Path, daemon: bool) -> Consequence:
+    names = ", ".join(volumes) or "volume(s)"
+    if not daemon:
+        return Consequence(
+            "docker", 0.7,
+            f"removing docker volume(s) {names} — if they hold data this is "
+            f"irreversible (daemon unreachable, could not confirm)",
+            estimated=True,
+        )
+
+    existing: list[str] = []
+    in_use: list[str] = []
+    for v in volumes:
+        ok, out = _run_docker(cwd, "volume", "inspect", v)
+        if ok and out:
+            existing.append(v)
+            users_ok, users = _run_docker(
+                cwd, "ps", "-a", "--filter", f"volume={v}", "--format", "{{.Names}}"
+            )
+            if users_ok and users:
+                in_use.append(v)
+
+    if not existing:
+        return Consequence(
+            "docker", 0.1,
+            f"volume(s) {names} do not exist — nothing to remove",
+        )
+    floor = 0.9 if in_use else 0.85
+    suffix = f" (in use by {', '.join(in_use)})" if in_use else ""
+    return Consequence(
+        "docker", floor,
+        f"removing volume(s) {', '.join(existing)} permanently deletes their "
+        f"data{suffix} — a volume has no image to rebuild from",
+    )
+
+
+def _assess_volume_prune(cwd: Path, daemon: bool) -> Consequence:
+    if not daemon:
+        return Consequence(
+            "docker", 0.6,
+            "volume prune removes all unused volumes and their data — "
+            "irreversible (daemon unreachable)",
+            estimated=True,
+        )
+    ok, out = _run_docker(cwd, "volume", "ls", "-f", "dangling=true", "-q")
+    n = _count_lines(out) if ok else 0
+    if n == 0:
+        return Consequence("docker", 0.15, "no unused volumes to prune")
+    floor = min(0.85, 0.5 + 0.05 * n)
+    return Consequence(
+        "docker", floor,
+        f"volume prune would delete {n} unused volume(s) and their data (irreversible)",
+    )
+
+
+def _assess_system_prune(raw: str, cwd: Path, daemon: bool) -> Consequence:
+    spec = _parse_docker(raw)
+    flags = spec[3] if spec else []
+    has_volumes = "--volumes" in flags
+    has_all = any(f in ("-a", "--all") for f in flags)
+
+    if not daemon:
+        floor = 0.75 if has_volumes else (0.5 if has_all else 0.4)
+        extra = " including volumes and their data" if has_volumes else ""
+        return Consequence(
+            "docker", floor,
+            f"system prune removes all unused docker objects{extra} — "
+            f"images are re-pullable, volume data is not (daemon unreachable)",
+            estimated=True,
+        )
+
+    if has_volumes:
+        ok, out = _run_docker(cwd, "volume", "ls", "-f", "dangling=true", "-q")
+        nv = _count_lines(out) if ok else 0
+        if nv > 0:
+            return Consequence(
+                "docker", min(0.85, 0.6 + 0.05 * nv),
+                f"system prune --volumes would delete {nv} unused volume(s) and "
+                f"their data — irreversible",
+            )
+        return Consequence(
+            "docker", 0.4,
+            "system prune --volumes — no unused volumes; removes containers/images "
+            "(rebuildable)",
+        )
+    if has_all:
+        return Consequence(
+            "docker", 0.5,
+            "system prune -a removes every unused image — re-pullable, but a slow "
+            "rebuild; no volume data is touched",
+        )
+    return Consequence(
+        "docker", 0.4,
+        "system prune removes stopped containers, dangling images and build cache "
+        "— all rebuildable",
+    )
+
+
+def _assess_container_rm(containers: tuple[str, ...], cwd: Path, daemon: bool) -> Consequence:
+    names = ", ".join(containers) or "container(s)"
+    evidence = (
+        f"force-removes container(s) {names}; recreatable from their image "
+        f"(any in-container state not on a volume is lost)"
+    )
+    if not daemon:
+        return Consequence("docker", 0.4, evidence + " (daemon unreachable)", estimated=True)
+    return Consequence("docker", 0.4, evidence)