deadpush 0.2.0__py3-none-any.whl

deadpush/reachability.py

@@ -0,0 +1,183 @@
+"""
+Reachability analysis for dead code detection.
+
+Given the (partial) call graph built from language plugins, compute
+what is reachable from the entry point roots.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .graph import CallGraph
+
+
+@dataclass
+class ReachabilityResult:
+    reachable: set[str] = field(default_factory=set)
+    unreachable: set[str] = field(default_factory=set)
+    uncertain: set[str] = field(default_factory=set)  # dynamic / risk / unresolved calls
+
+
+def compute_reachability(
+    graph: CallGraph,
+    roots: list[str],
+    config: Any,
+) -> ReachabilityResult:
+    """
+    Naive but effective DFS/BFS reachability.
+
+    Because call sites from plugins currently record raw callee *text*, we do
+    fuzzy matching to symbol names. Real prod would do proper name resolution.
+    """
+    reachable: set[str] = set()
+    uncertain: set[str] = set()
+
+    # Build quick name -> ids index (last wins for simplicity, or collect)
+    name_to_ids: dict[str, list[str]] = {}
+    for sid, sym in graph.symbols.items():
+        name_to_ids.setdefault(sym.name, []).append(sid)
+        # also basename of path for file symbols etc
+        base = Path(sym.path).name
+        if base != sym.name:
+            name_to_ids.setdefault(base, []).append(sid)
+
+    from collections import deque
+    q = deque(roots)
+    for r in roots:
+        reachable.add(r)
+
+    # Also add edges if they were added (future proof)
+    adj: dict[str, list[str]] = {sid: [] for sid in graph.symbols}
+    for edge in getattr(graph, "edges", []):
+        if edge.src in adj:
+            adj[edge.src].append(edge.dst)
+
+    # Prefer rich resolved call_edges from the new BlastRadius-style graph assembly
+    rich_edges = getattr(graph, "call_edges", []) or []
+    for e in rich_edges:
+        src = str(e.get("caller_id") or e.get("src") or "")
+        dst = e.get("callee_id") or e.get("dst")
+        if src and dst and src in adj:
+            adj.setdefault(src, [])
+            if dst not in adj[src]:
+                adj[src].append(str(dst))
+
+    visited = set(reachable)
+
+    def resolve_callee(callee_text: str) -> list[str]:
+        """Very heuristic resolution of a raw callee string to symbol ids."""
+        c = callee_text.strip().strip("()[]{}; ")
+        if not c:
+            return []
+        # direct name match
+        if c in name_to_ids:
+            return name_to_ids[c]
+        # last segment after . (method calls)
+        last = c.split(".")[-1].split("(")[0]
+        if last in name_to_ids:
+            return name_to_ids[last]
+        # bare function
+        bare = c.split("(")[0].split("::")[-1]
+        if bare in name_to_ids:
+            return name_to_ids[bare]
+        return []
+
+    # Traverse from graph edges first (if present)
+    while q:
+        cur = q.popleft()
+        # explicit edges
+        for dst in adj.get(cur, []):
+            if dst not in visited:
+                visited.add(dst)
+                reachable.add(dst)
+                q.append(dst)
+
+        # also from symbols that have outgoing? we didn't populate many edges yet
+        sym = graph.get_symbol(cur)
+        if not sym:
+            continue
+
+    # Second pass: use the raw call_sites that were collected in plugins but not wired.
+    # In current cli the calls are parsed but not added to graph; we simulate here using all known calls.
+    # To make plugins contribute, we scan again? For now do a global pass using symbols.
+    # Simpler: consider every symbol that is called by a reachable one.
+    # We do this by iterating call data? Since calls aren't stored on graph, we re-walk? Skip for perf.
+    # For integration, we mark high dynamic_risk symbols as uncertain even if named match.
+
+    # Second pass: use stored raw call edges (from plugins) to reach more symbols.
+    # We do fuzzy name resolution on the dst side.
+    name_index: dict[str, list[str]] = {}
+    for sid, s in graph.symbols.items():
+        name_index.setdefault(s.name, []).append(sid)
+        base = Path(s.path).stem
+        name_index.setdefault(base, []).append(sid)
+
+    def _resolve(dst: str) -> list[str]:
+        d = dst.strip().strip("()[]{};, ")
+        if not d:
+            return []
+        if d in name_index:
+            return name_index[d]
+        last = d.split(".")[-1].split("::")[-1].split("(")[0]
+        if last in name_index:
+            return name_index[last]
+        return []
+
+    # Walk the call edges recorded in the graph (prefer rich resolved ones)
+    rich_edges = getattr(graph, "call_edges", []) or []
+    for e in rich_edges:
+        src = str(e.get("caller_id") or e.get("src") or "")
+        if src in reachable:
+            dst = e.get("callee_id") or e.get("dst") or e.get("callee_name")
+            if dst:
+                for target in _resolve(str(dst)):
+                    if target not in visited:
+                        visited.add(target)
+                        reachable.add(target)
+                        q.append(target)
+
+    for edge in getattr(graph, "edges", []):
+        if edge.src in reachable:
+            for target in _resolve(edge.dst):
+                if target not in visited:
+                    visited.add(target)
+                    reachable.add(target)
+                    q.append(target)  # continue DFS from here
+
+    # Drain any newly enqueued from raw calls
+    while q:
+        cur = q.popleft()
+        for edge in getattr(graph, "edges", []):
+            if edge.src == cur:
+                for target in _resolve(edge.dst):
+                    if target not in visited:
+                        visited.add(target)
+                        reachable.add(target)
+                        q.append(target)
+
+    # Now compute unreachable
+    all_sym_ids = set(graph.symbols.keys())
+    unreachable = all_sym_ids - reachable
+
+    # Promote some to uncertain if they had dynamic risk or were only reachable via raw text that didn't resolve cleanly
+    for sid in list(unreachable):
+        sym = graph.get_symbol(sid)
+        if sym and sym.dynamic_risk > 0.3:
+            uncertain.add(sid)
+            unreachable.discard(sid)
+
+    # Files themselves are rarely "dead" unless whole module
+    for sid in list(unreachable):
+        sym = graph.get_symbol(sid)
+        if sym and sym.kind == "file":
+            # don't report the file as dead code usually
+            unreachable.discard(sid)
+
+    return ReachabilityResult(
+        reachable=reachable,
+        unreachable=unreachable,
+        uncertain=uncertain,
+    )

deadpush/registration.py

@@ -0,0 +1,280 @@
+"""Registration pattern detection for dead code analysis.
+
+Scans source files for common framework registration patterns that would
+make a symbol "alive" even if not directly called in the call graph:
+- Decorator registrations (@register, @route, @app.get, etc.)
+- Dict/list registrations (plugin registries, handler maps)
+- String references that match symbol names in registry contexts
+- Framework-specific registries (Django urlpatterns, Flask routes, Click groups)
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+from typing import Any
+
+_KNOWN_FRAMEWORK_OBJECTS: set[str] = {
+    "app", "application", "router", "bp", "blueprint", "api",
+    "route", "routes", "site", "server", "web",
+}
+
+_DECORATOR_PATTERNS: dict[str, float] = {
+    "register": 0.9,
+    "route": 0.8,
+    "command": 0.8,
+    "group": 0.8,
+    "click_command": 0.8,
+    "click_group": 0.8,
+    "app_route": 0.9,
+    "router_route": 0.8,
+    "bp_route": 0.8,
+    "get": 0.7,
+    "post": 0.7,
+    "put": 0.7,
+    "delete": 0.7,
+    "patch": 0.7,
+    "hookimpl": 0.8,
+    "hookspec": 0.7,
+    "signal": 0.7,
+    "receiver": 0.7,
+    "listen": 0.7,
+    "on_event": 0.7,
+    "task": 0.6,
+    "periodic_task": 0.7,
+    "background_task": 0.7,
+    "entrypoint": 0.8,
+    "console_script": 0.8,
+    "setuptools_entry": 0.8,
+    "expose": 0.7,
+    "action": 0.7,
+    "filter": 0.6,
+    "template_filter": 0.7,
+    "context_processor": 0.7,
+    "extension": 0.6,
+    "middleware": 0.6,
+    "errorhandler": 0.7,
+    "before_request": 0.6,
+    "after_request": 0.6,
+    "teardown_request": 0.6,
+    "on_message": 0.7,
+    "subscribe": 0.7,
+    "publish": 0.6,
+    "event_handler": 0.7,
+    "model": 0.5,
+    "table": 0.5,
+    "collection": 0.5,
+    "resource": 0.5,
+    "service": 0.5,
+    "provider": 0.5,
+    "factory": 0.5,
+    "component": 0.5,
+    "inject": 0.6,
+    "implement": 0.6,
+    "override": 0.5,
+    "implements": 0.6,
+    "dataclass": 0.3,
+}
+
+_REGISTRY_VARIABLE_PATTERNS: list[re.Pattern] = [
+    re.compile(r"(?:handlers|routes|urls|urlpatterns|views|controllers|actions|commands|tasks|workers|plugins|extensions|providers|services|maps|mappings|registry|registries|middlewares|filters|signals|events|listeners|consumers|producers|sinks|sources|adapters|ports|drivers|brokers|queues|schedules|jobs|crons|blueprints|modules|resources|endpoints|patterns)"),
+    re.compile(r".*_registry$"),
+    re.compile(r".*_handlers$"),
+    re.compile(r".*_routes$"),
+    re.compile(r".*_commands$"),
+    re.compile(r".*_tasks$"),
+    re.compile(r".*_listeners$"),
+    re.compile(r".*_events$"),
+    re.compile(r".*_plugins$"),
+    re.compile(r".*_services$"),
+]
+
+_ENTRY_POINT_FILE_PATTERNS: list[re.Pattern] = [
+    re.compile(r"(?:main|app|server|cli|cmd|entry|index|wsgi|asgi|manage|setup|run|launch|start|boot|bootstrap|kernel|router|routes|urls|views|api|graphql|rest|grpc|consumer|worker|scheduler)\.py$", re.IGNORECASE),
+    re.compile(r"(?:manage|setup|wsgi|asgi|cli)\.py$", re.IGNORECASE),
+    re.compile(r"__main__\.py$"),
+    re.compile(r"conftest\.py$"),
+    re.compile(r"__init__\.py$"),
+]
+
+
+class RegistrationDetector:
+    """Detect symbols registered via decorators, dict entries, or string refs.
+
+    Scans all source files once and caches results.
+    """
+
+    def __init__(self, file_paths: list[Path], repo_root: Path):
+        self.repo_root = repo_root
+        self._registered: set[str] = set()
+        self._scores: dict[str, float] = {}
+        self._entry_point_files: set[str] = set()
+        self._string_refs: dict[str, list[str]] = {}
+        self._custom_patterns: list[str] = []
+        self._scan(file_paths)
+
+    def add_custom_pattern(self, pattern: str) -> None:
+        self._custom_patterns.append(pattern)
+
+    def _scan(self, file_paths: list[Path]) -> None:
+        for fp in file_paths:
+            rel = self._rel_path(fp)
+            if rel in self._entry_point_files:
+                continue
+            for pat in _ENTRY_POINT_FILE_PATTERNS:
+                if pat.search(fp.name):
+                    self._entry_point_files.add(rel)
+                    break
+            try:
+                text = fp.read_text(encoding="utf-8", errors="ignore")
+            except Exception:
+                continue
+
+            self._scan_decorators(text, rel)
+            self._scan_dict_registrations(text, rel)
+            self._scan_string_refs(text, rel)
+
+        for custom in self._custom_patterns:
+            try:
+                cre = re.compile(custom)
+                for fp in file_paths:
+                    rel = self._rel_path(fp)
+                    try:
+                        text = fp.read_text(encoding="utf-8", errors="ignore")
+                    except Exception:
+                        continue
+                    for m in cre.finditer(text):
+                        name = m.group(1) if m.lastindex and m.lastindex >= 1 else m.group(0)
+                        sym_id = f"{rel}::{name}"
+                        self._registered.add(sym_id)
+                        self._scores[sym_id] = max(self._scores.get(sym_id, 0), 0.5)
+            except re.error:
+                pass
+
+    def _rel_path(self, path: Path) -> str:
+        try:
+            return str(path.relative_to(self.repo_root))
+        except ValueError:
+            return str(path)
+
+    def _scan_decorators(self, text: str, rel: str) -> None:
+        try:
+            tree = ast.parse(text)
+        except SyntaxError:
+            return
+
+        for node in ast.walk(tree):
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                continue
+            for dec in node.decorator_list:
+                weight = self._decorator_weight(dec)
+                if weight > 0:
+                    sym_id = f"{rel}::{node.name}"
+                    self._registered.add(sym_id)
+                    self._scores[sym_id] = max(self._scores.get(sym_id, 0), weight)
+
+    @staticmethod
+    def _namespace_for_attr(dec: ast.expr) -> str | None:
+        """Extract the leftmost name from an attribute chain (e.g. app.get → 'app')."""
+        if isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute):
+            return RegistrationDetector._namespace_for_attr(dec.func)
+        if isinstance(dec, ast.Attribute):
+            if isinstance(dec.value, ast.Name):
+                return dec.value.id.lower()
+            if isinstance(dec.value, ast.Attribute):
+                return RegistrationDetector._namespace_for_attr(dec.value)
+        return None
+
+    def _decorator_weight(self, dec: ast.expr) -> float:
+        if isinstance(dec, (ast.Call, ast.Attribute)):
+            if isinstance(dec, ast.Call):
+                func = dec.func
+            else:
+                func = dec
+            if isinstance(func, ast.Attribute):
+                attr_name = func.attr.lower()
+                weight = _DECORATOR_PATTERNS.get(attr_name, 0.0)
+                namespace = self._namespace_for_attr(dec)
+                if weight > 0 and namespace and namespace not in _KNOWN_FRAMEWORK_OBJECTS:
+                    weight *= 0.3
+                return weight
+            if isinstance(func, ast.Name):
+                return _DECORATOR_PATTERNS.get(func.id.lower(), 0.0)
+            return 0.0
+        if isinstance(dec, ast.Name):
+            return _DECORATOR_PATTERNS.get(dec.id.lower(), 0.0)
+        return 0.0
+
+    def _scan_dict_registrations(self, text: str, rel: str) -> None:
+        try:
+            tree = ast.parse(text)
+        except SyntaxError:
+            return
+
+        def _var_matches(name: str) -> bool:
+            return any(p.search(name) for p in _REGISTRY_VARIABLE_PATTERNS)
+
+        def _scan_value(val: ast.expr) -> None:
+            if isinstance(val, ast.Dict):
+                for v in val.values:
+                    self._check_registry_value(v, rel)
+            elif isinstance(val, ast.List):
+                for elt in val.elts:
+                    self._check_registry_value(elt, rel)
+            elif isinstance(val, ast.Call):
+                for kw in val.keywords:
+                    self._check_registry_value(kw.value, rel)
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    var_name = None
+                    if isinstance(target, ast.Name):
+                        var_name = target.id
+                    elif isinstance(target, ast.Subscript) and isinstance(target.value, ast.Name):
+                        var_name = target.value.id
+                    if var_name and _var_matches(var_name):
+                        _scan_value(node.value)
+                        break
+            elif isinstance(node, ast.AugAssign):
+                if isinstance(node.target, ast.Name) and _var_matches(node.target.id):
+                    _scan_value(node.value)
+
+    def _check_registry_value(self, val: ast.expr, rel: str) -> None:
+        if isinstance(val, ast.Name):
+            weight = 0.3
+            sym_id = f"{rel}::{val.id}"
+            self._registered.add(sym_id)
+            self._scores[sym_id] = max(self._scores.get(sym_id, 0), weight)
+        elif isinstance(val, ast.Attribute):
+            weight = 0.25
+            sym_id = f"{rel}::{val.attr}"
+            self._registered.add(sym_id)
+            self._scores[sym_id] = max(self._scores.get(sym_id, 0), weight)
+        elif isinstance(val, ast.Constant) and isinstance(val.value, str):
+            weight = 0.2
+            sym_id = f"{rel}::{val.value}"
+            self._registered.add(sym_id)
+            self._scores[sym_id] = max(self._scores.get(sym_id, 0), weight)
+
+    def _scan_string_refs(self, text: str, rel: str) -> None:
+        for m in re.finditer(r'["\'](\w+)["\']\s*[:=]\s*["\'](\w+)["\']', text):
+            key, val = m.group(1), m.group(2)
+            for name in (key, val):
+                sym_id = f"{rel}::{name}"
+                self._registered.add(sym_id)
+                current = self._scores.get(sym_id, 0)
+                self._scores[sym_id] = max(current, 0.15)
+
+    def score(self, sym_id: str) -> float:
+        return self._scores.get(sym_id, 0.0)
+
+    def is_registered(self, sym_id: str) -> bool:
+        return sym_id in self._registered
+
+    def is_entry_point_file(self, path: str) -> bool:
+        return path in self._entry_point_files
+
+    def get_all_registered(self) -> set[str]:
+        return self._registered.copy()

deadpush/report.py

@@ -0,0 +1,113 @@
+"""
+Report generators (markdown + json) for deadpush scan results.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .graph import DeadSymbol, DebrisFile
+
+
+def generate_markdown_report(
+    dead_symbols: list[DeadSymbol],
+    debris: list[DebrisFile],
+    repo_root: Path,
+    roots: list[str] | None = None,
+) -> str:
+    lines: list[str] = []
+    lines.append("# deadpush Report")
+    lines.append(f"Generated: {datetime.now(timezone.utc).isoformat()}")
+    lines.append(f"Repo: {repo_root}")
+    lines.append("")
+
+    lines.append("## Summary")
+    lines.append(f"- Dead symbols: {len(dead_symbols)}")
+    lines.append(f"- Debris items: {len(debris)}")
+    blocking = [d for d in debris if getattr(d, "block_push", False)]
+    lines.append(f"- Blocking debris: {len(blocking)}")
+    lines.append("")
+
+    if dead_symbols:
+        lines.append("## Dead Code")
+        by_file: dict[str, list[DeadSymbol]] = {}
+        for ds in dead_symbols:
+            by_file.setdefault(ds.symbol.path, []).append(ds)
+        for fpath in sorted(by_file):
+            lines.append(f"\n### {fpath}")
+            for ds in sorted(by_file[fpath], key=lambda x: x.symbol.line):
+                tier = ds.tier.upper()
+                lines.append(
+                    f"- **{ds.symbol.name}** (line {ds.symbol.line}) — {tier} "
+                    f"({ds.confidence*100:.0f}%) — safe={ds.safe_to_delete}"
+                )
+                for r in ds.reasons[:3]:
+                    lines.append(f"  - {r}")
+    else:
+        lines.append("## Dead Code\n\nNo dead code found. Great!")
+
+    lines.append("\n## Debris")
+    if debris:
+        for d in sorted(debris, key=lambda x: (not x.block_push, x.category, x.path)):
+            flag = "🚫 BLOCK" if d.block_push else "warn"
+            lines.append(f"- {d.path} [{d.category}] {flag} conf={d.confidence:.0%}")
+            if d.suggestion:
+                lines.append(f"  → {d.suggestion}")
+    else:
+        lines.append("No semantic debris detected.")
+
+    if roots:
+        lines.append("\n## Entry Points Used")
+        for r in roots[:20]:
+            lines.append(f"- {r}")
+
+    lines.append("\n---\n*Report by deadpush — keep your vibe coding safe.*")
+    return "\n".join(lines)
+
+
+def generate_json_report(
+    dead_symbols: list[DeadSymbol],
+    debris: list[DebrisFile],
+    repo_root: Path,
+    roots: list[str] | None = None,
+) -> dict[str, Any]:
+    return {
+        "version": "0.2",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "repo_root": str(repo_root),
+        "summary": {
+            "dead_count": len(dead_symbols),
+            "debris_count": len(debris),
+            "blocking_debris": len([d for d in debris if getattr(d, "block_push", False)]),
+            "entry_points": len(roots or []),
+        },
+        "dead_symbols": [
+            {
+                "id": ds.symbol.id,
+                "name": ds.symbol.name,
+                "kind": ds.symbol.kind,
+                "path": ds.symbol.path,
+                "line": ds.symbol.line,
+                "tier": ds.tier,
+                "confidence": ds.confidence,
+                "reasons": ds.reasons,
+                "safe_to_delete": ds.safe_to_delete,
+            }
+            for ds in dead_symbols
+        ],
+        "debris": [
+            {
+                "path": d.path,
+                "category": d.category,
+                "confidence": d.confidence,
+                "block_push": d.block_push,
+                "suggestion": d.suggestion,
+                "reasons": d.reasons,
+            }
+            for d in debris
+        ],
+        "roots": roots or [],
+    }