deadpush 0.2.0__py3-none-any.whl

deadpush/rules.py

@@ -0,0 +1,190 @@
+"""
+Runtime configuration for deadpush — agent-configurable rules.
+
+Agents can modify guardrail behavior at runtime via MCP tools.
+Changes persist in .deadpush/rules.json and survive server restarts.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+RULES_FILE = ".deadpush/rules.json"
+
+GUARDRAIL_LEVELS = ["off", "warn", "block"]
+
+DEFAULT_RULES: dict[str, Any] = {
+    "allowed_patterns": [],
+    "ignored_paths": [],
+    "guardrail_levels": {
+        "prompt_injection": "block",
+        "secret": "block",
+        "security": "block",
+        "layer": "block",
+        "sensitive": "block",
+        "destructive": "warn",
+        "debris": "warn",
+        "dependency": "warn",
+    },
+}
+
+
+class RuntimeConfig:
+    """Persistent runtime configuration for agent-customizable guardrails.
+
+    Stored in .deadpush/rules.json. Survives server restarts.
+    Merged with base config (pyproject.toml) at load time.
+    """
+
+    def __init__(self, repo_root: Path):
+        self.repo_root = repo_root
+        self.rules_path = repo_root / RULES_FILE
+        self._data: dict[str, Any] = {}
+        self._compiled: list[tuple[re.Pattern, str]] = []  # (compiled_regex, description)
+        self._load()
+
+    @classmethod
+    def from_dict(cls, repo_root: Path, data: dict[str, Any]) -> RuntimeConfig:
+        """Create a RuntimeConfig from a dict without file I/O (primarily for tests)."""
+        rc = cls.__new__(cls)
+        rc.repo_root = repo_root
+        rc.rules_path = repo_root / RULES_FILE
+        rc._data = copy.deepcopy(data)
+        rc._merge_defaults()
+        rc._rebuild_cache()
+        return rc
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+    def _load(self):
+        if self.rules_path.exists():
+            try:
+                self._data = json.loads(self.rules_path.read_text(encoding="utf-8"))
+            except Exception:
+                self._data = {}
+        self._merge_defaults()
+        self._rebuild_cache()
+
+    def _save(self):
+        self.rules_path.parent.mkdir(parents=True, exist_ok=True)
+        self.rules_path.write_text(json.dumps(self._data, indent=2, default=str), encoding="utf-8")
+
+    def _merge_defaults(self):
+        defaults = copy.deepcopy(DEFAULT_RULES)
+        for key, default_val in defaults.items():
+            if key not in self._data:
+                self._data[key] = default_val
+            elif isinstance(default_val, dict):
+                for subkey, subval in default_val.items():
+                    if subkey not in self._data[key]:
+                        self._data[key][subkey] = subval
+
+    def _rebuild_cache(self):
+        self._compiled = []
+        for entry in self._data.get("allowed_patterns", []):
+            pattern = entry.get("pattern", "")
+            desc = entry.get("description", "")
+            try:
+                self._compiled.append((re.compile(pattern), desc))
+            except re.error:
+                pass
+
+    # ------------------------------------------------------------------
+    # Allowlist — patterns to skip during guardrail checks
+    # ------------------------------------------------------------------
+    def is_allowed(self, matched_text: str) -> bool:
+        """Check if a matched pattern is in the allowlist."""
+        for compiled_re, _ in self._compiled:
+            if compiled_re.search(matched_text):
+                return True
+        return False
+
+    def add_allowed_pattern(self, pattern: str, description: str = "") -> None:
+        """Add a regex pattern to the allowlist."""
+        # Validate the regex
+        re.compile(pattern)
+        patterns = self._data.setdefault("allowed_patterns", [])
+        # Avoid duplicates
+        for entry in patterns:
+            if entry.get("pattern") == pattern:
+                entry["description"] = description
+                self._rebuild_cache()
+                self._save()
+                return
+        patterns.append({"pattern": pattern, "description": description})
+        self._rebuild_cache()
+        self._save()
+
+    def remove_allowed_pattern(self, pattern: str) -> bool:
+        """Remove a pattern from the allowlist. Returns True if found."""
+        patterns = self._data.get("allowed_patterns", [])
+        before = len(patterns)
+        self._data["allowed_patterns"] = [p for p in patterns if p.get("pattern") != pattern]
+        if len(self._data["allowed_patterns"]) != before:
+            self._rebuild_cache()
+            self._save()
+            return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Path ignore list
+    # ------------------------------------------------------------------
+    def is_path_ignored(self, rel_path: str) -> bool:
+        """Check if a relative path is in the ignore list."""
+        ignored = self._data.get("ignored_paths", [])
+        for ign in ignored:
+            if ign.endswith("*") and rel_path.startswith(ign.rstrip("*")):
+                return True
+            if rel_path == ign:
+                return True
+        return False
+
+    def ignore_path(self, rel_path: str) -> None:
+        """Add a path to the ignore list."""
+        ignored = self._data.setdefault("ignored_paths", [])
+        if rel_path not in ignored:
+            ignored.append(rel_path)
+            self._save()
+
+    def remove_ignored_path(self, rel_path: str) -> bool:
+        """Remove a path from the ignore list."""
+        ignored = self._data.get("ignored_paths", [])
+        if rel_path in ignored:
+            self._data["ignored_paths"] = [p for p in ignored if p != rel_path]
+            self._save()
+            return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Guardrail levels
+    # ------------------------------------------------------------------
+    def get_guardrail_level(self, category: str) -> str:
+        """Get the level for a guardrail category: off, warn, block."""
+        return self._data.get("guardrail_levels", {}).get(category, "block")
+
+    def set_guardrail_level(self, category: str, level: str) -> None:
+        """Set the level for a guardrail category."""
+        if level not in GUARDRAIL_LEVELS:
+            raise ValueError(f"Level must be one of: {', '.join(GUARDRAIL_LEVELS)}")
+        levels = self._data.setdefault("guardrail_levels", {})
+        levels[category] = level
+        self._save()
+
+    # ------------------------------------------------------------------
+    # Full state
+    # ------------------------------------------------------------------
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._data)
+
+    def reset(self) -> None:
+        """Reset all runtime config to defaults."""
+        self._data = {}
+        self._merge_defaults()
+        self._rebuild_cache()
+        self._save()

deadpush/sarif.py

@@ -0,0 +1,123 @@
+"""
+Enhanced SARIF v2.1.0 generator for deadpush.
+
+Production-ready output for IDEs and GitHub Advanced Security.
+"""
+
+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_sarif(
+    dead_symbols: list[DeadSymbol],
+    debris: list[DebrisFile],
+    repo_root: Path,
+) -> dict[str, Any]:
+    results = []
+
+    for d in debris:
+        level = "error" if d.block_push else "warning"
+        results.append({
+            "ruleId": f"deadpush/debris/{d.category}",
+            "level": level,
+            "message": {
+                "text": d.suggestion,
+                "markdown": f"**Category:** {d.category}\n\n{d.suggestion}\n\n**Reasons:**\n" +
+                            "\n".join(f"- {r}" for r in d.reasons)
+            },
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {
+                        "uri": d.path,
+                        "uriBaseId": "%SRCROOT%"
+                    }
+                }
+            }],
+            "properties": {
+                "deadpush_category": d.category,
+                "confidence": round(d.confidence, 3),
+                "block_push": d.block_push
+            }
+        })
+
+    for ds in dead_symbols:
+        level = "warning" if ds.tier in ("definite", "probable") else "note"
+        results.append({
+            "ruleId": f"deadpush/deadcode/{ds.tier}",
+            "level": level,
+            "message": {
+                "text": f"{ds.symbol.name} is {ds.tier} dead code",
+                "markdown": f"**Symbol:** `{ds.symbol.name}`\n**Tier:** {ds.tier}\n**Confidence:** {ds.confidence*100:.0f}%\n\n" +
+                            "\n".join(f"- {r}" for r in ds.reasons)
+            },
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {
+                        "uri": str(Path(ds.symbol.path).relative_to(repo_root)),
+                        "uriBaseId": "%SRCROOT%"
+                    },
+                    "region": {
+                        "startLine": ds.symbol.line,
+                        "startColumn": 1
+                    }
+                }
+            }],
+            "properties": {
+                "deadpush_tier": ds.tier,
+                "confidence": round(ds.confidence, 3),
+                "kind": ds.symbol.kind,
+                "safe_to_delete": ds.safe_to_delete,
+                "delete_order": ds.delete_order
+            }
+        })
+
+    sarif = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name": "deadpush",
+                    "version": "0.3.0",
+                    "informationUri": "https://github.com/harris-ahmad/deadpush",
+                    "rules": [
+                        {
+                            "id": "deadpush/debris/llm_context_file",
+                            "name": "LLM Context File",
+                            "shortDescription": {"text": "AI coding assistant context/instructions file committed to repository"},
+                            "defaultConfiguration": {"level": "error"}
+                        },
+                        {
+                            "id": "deadpush/deadcode/definite",
+                            "name": "Definite Dead Code",
+                            "shortDescription": {"text": "Code unreachable from any production entry point"},
+                            "defaultConfiguration": {"level": "warning"}
+                        },
+                        {
+                            "id": "deadpush/deadcode/ai_regenerated_duplicate",
+                            "name": "AI Regenerated Duplicate",
+                            "shortDescription": {"text": "File structurally similar to another (likely LLM-regenerated)"},
+                            "defaultConfiguration": {"level": "warning"}
+                        }
+                    ]
+                }
+            },
+            "results": results,
+            "invocations": [{
+                "executionSuccessful": True,
+                "startTimeUtc": datetime.now(timezone.utc).isoformat()
+            }]
+        }]
+    }
+    return sarif
+
+
+def write_sarif(sarif_data: dict[str, Any], output_path: Path) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(sarif_data, indent=2), encoding="utf-8")

deadpush/scorer.py

@@ -0,0 +1,151 @@
+"""
+Scoring + classification of dead symbols using multi-factor deadness analysis.
+
+Integrates:
+- MultiFactorDeadnessScorer (6-factor analysis)
+- reachability info
+- per-symbol dynamic_risk from language plugins
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .config import Config
+from .graph import CallGraph, DeadSymbol, Symbol
+from .deadness import DeadnessResult, MultiFactorDeadnessScorer
+from .registration import RegistrationDetector
+from .importgraph import ImportAnalyzer
+
+
+def score_symbol(
+    sym: Symbol,
+    graph: CallGraph,
+    reachability: Any,
+    config: Config,
+    scorer: MultiFactorDeadnessScorer | None = None,
+) -> DeadSymbol | None:
+    """Return a DeadSymbol wrapper or None if we decide not to report it."""
+    if sym.kind == "file":
+        return None
+
+    reasons: list[str] = []
+    tier = "uncertain"
+    confidence = 0.6
+    safe = True
+    order = 10
+    alive_score = 0.0
+    factor_breakdown: dict[str, float] = {}
+
+    # Multi-factor scoring first (if available)
+    if scorer is not None:
+        result = scorer.score(sym)
+        if result is None:
+            return None  # abstention
+
+        alive_score = result.alive_score
+        factor_breakdown = result.factors
+        if result.reasons:
+            reasons.extend(result.reasons)
+
+        # Map deadness tier to legacy tier
+        match result.tier:
+            case "high":
+                tier = "definite"
+                confidence = 0.95
+                order = 1
+                safe = True
+            case "medium":
+                tier = "probable"
+                confidence = 0.85
+                order = 3
+                safe = True
+            case "low":
+                tier = "suspicious"
+                confidence = 0.65
+                order = 5
+                safe = True
+            case "uncertain":
+                tier = "uncertain"
+                confidence = 0.4
+                order = 10
+                safe = False
+
+    # If no scorer (legacy path), fall through to reachability-based logic
+    else:
+        sid = sym.id
+        if sid in getattr(reachability, "unreachable", set()):
+            tier = "definite"
+            confidence = 0.92
+            reasons.append("No path from any detected entry point")
+            order = 1
+        elif sid in getattr(reachability, "uncertain", set()):
+            tier = "suspicious"
+            confidence = 0.65
+            reasons.append("Only reachable via dynamic or hard-to-resolve call")
+        else:
+            return None
+
+    # Boost with language plugin risk signal
+    if sym.dynamic_risk > 0.4:
+        confidence = min(0.98, confidence + 0.15)
+        reasons.append(f"High dynamic risk ({sym.dynamic_risk:.0%}) from language analysis")
+        if sym.dynamic_risk > 0.7:
+            tier = "probable" if tier == "definite" else tier
+            safe = False
+
+    # Kind-based
+    if sym.kind in ("method", "function") and "test" in sym.name.lower():
+        confidence *= 0.6
+        reasons.append("Likely test/helper (low priority)")
+
+    if sym.kind == "class" and confidence > 0.8:
+        order = 2
+
+    low_quality_names = {"foo", "bar", "baz", "temp", "tmp", "unused", "deadcode", "placeholder"}
+    if sym.name.lower() in low_quality_names:
+        confidence = min(0.99, confidence + 0.1)
+        reasons.append("Suspicious placeholder name often seen in generated code")
+
+    ds = DeadSymbol(
+        symbol=sym,
+        tier=tier,
+        confidence=round(confidence, 3),
+        reasons=reasons or ["Unreachable from entry points"],
+        safe_to_delete=safe,
+        delete_order=order,
+        alive_score=round(alive_score, 3),
+        tier_new=result.tier if scorer is not None else "uncertain",
+        factor_breakdown=factor_breakdown,
+    )
+    return ds
+
+
+def build_scorer(
+    config: Config,
+    graph: CallGraph,
+    roots: set[str],
+    all_file_paths: list[Path],
+    custom_registrations: list[str] | None = None,
+    test_file_paths: list[Path] | None = None,
+) -> MultiFactorDeadnessScorer:
+    """Build a MultiFactorDeadnessScorer from analysis context."""
+    registration = RegistrationDetector(all_file_paths, config.repo_root)
+    if custom_registrations:
+        for pat in custom_registrations:
+            registration.add_custom_pattern(pat)
+
+    imports = ImportAnalyzer(all_file_paths, config.repo_root)
+
+    scorer = MultiFactorDeadnessScorer(
+        config=config,
+        repo_root=config.repo_root,
+        graph=graph,
+        registration=registration,
+        imports=imports,
+        roots=roots,
+        all_file_paths=all_file_paths,
+        test_file_paths=test_file_paths,
+    )
+    return scorer

deadpush/security.py

@@ -0,0 +1,187 @@
+"""
+Security Boundary Map — tracks security-sensitive functions and their test coverage.
+
+AI agents may introduce unsafe operations (eval, exec, raw SQL, crypto) without
+corresponding tests. This module identifies those boundaries and flags untested ones.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+SENSITIVE_PATTERNS: list[tuple[str, str, str]] = [
+    # (category, description, regex pattern for Python/JS source)
+    ("code_exec", "Dynamic code execution", r"\b(exec|eval)\s*\("),
+    ("command_injection", "Shell command execution", r"\b(subprocess\.(call|run|Popen|check_output|check_call)|os\.system|os\.popen|shlex)\s*\("),
+    ("file_write", "File write operation", r"\bopen\s*\(.*[rwab]+\s*\)"),
+    ("file_delete", "File deletion", r"\b(os\.remove|os\.unlink|shutil\.rmtree|Path\.unlink|Path\.rmdir)\s*\("),
+    ("crypto", "Cryptographic operation", r"\b(hashlib|hmac|Cryptodome|Crypto|nacl|bcrypt|argon2|passlib)\b"),
+    ("network", "Network I/O", r"\b(socket|requests\.(get|post|put|delete|patch)|urllib|aiohttp|httpx)\s*\("),
+    ("sql_injection", "SQL query construction", r"\bexecute\s*\(\s*['\"](SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER)"),
+    ("pickle", "Unsafe deserialization", r"\b(pickle\.loads|pickle\.load|jsonpickle|yaml\.load(?!_safe)|shelve)\s*\("),
+    ("insecure_import", "Insecure module import", r"\bimport\s+(pickle|shelve|marshal|subprocess|ctypes)\b"),
+    ("temp_file", "Temporary file", r"\b(tempfile|NamedTemporaryFile|mkstemp|mkdtemp)\b"),
+    ("permission", "Permission/chmod operation", r"\b(os\.chmod|os\.chown|os\.setuid|os\.setgid)\s*\("),
+    ("path_traversal", "Path traversal risk", r"\b(Path|os\.path\.join)\s*\(.*\+\s*"),
+]
+
+
+SENSITIVE_FUNCTION_NAMES: set[str] = {
+    # Python
+    "exec", "eval", "compile",
+    # Shell
+    "system", "popen",
+    # File
+    "remove", "unlink", "rmtree",
+    # Serialization
+    "loads", "load",
+    # Permissions
+    "chmod", "chown",
+}
+
+
+@dataclass
+class SecurityBoundary:
+    """A security-sensitive operation found in source code."""
+    file: str
+    line: int
+    category: str
+    description: str
+    matched_text: str
+    has_test: bool = False
+    test_file: str = ""
+
+
+@dataclass
+class SecurityReport:
+    """Full security boundary scan result."""
+    boundaries: list[SecurityBoundary] = field(default_factory=list)
+    untested: list[SecurityBoundary] = field(default_factory=list)
+    tested: list[SecurityBoundary] = field(default_factory=list)
+
+
+class SecurityScanner:
+    """Scans source files for security-sensitive operations and checks test coverage."""
+
+    def __init__(self, repo_root: Path | None = None):
+        self.repo_root = repo_root or Path.cwd()
+
+    MAX_FILE_SIZE = 50 * 1024 * 1024  # 50 MB
+
+    def scan_file(self, file_path: Path) -> list[SecurityBoundary]:
+        """Find security-sensitive operations in a single file."""
+        boundaries: list[SecurityBoundary] = []
+        try:
+            if file_path.stat().st_size > self.MAX_FILE_SIZE:
+                return boundaries
+            source = file_path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            return boundaries
+
+        rel_path = _relative(file_path, self.repo_root)
+
+        for category, desc, pattern in SENSITIVE_PATTERNS:
+            for m in re.finditer(pattern, source, re.IGNORECASE):
+                line_num = source[:m.start()].count("\n") + 1
+                # Determine context: extract the line
+                lines = source.splitlines()
+                context_line = lines[line_num - 1].strip() if line_num <= len(lines) else ""
+                boundaries.append(SecurityBoundary(
+                    file=rel_path,
+                    line=line_num,
+                    category=category,
+                    description=desc,
+                    matched_text=context_line[:80],
+                ))
+        return boundaries
+
+    def find_test_files(self) -> list[Path]:
+        """Find test files in the repository."""
+        test_files: list[Path] = []
+        for pattern in ("**/test_*.py", "**/*_test.py", "**/tests/**/*.py", "**/test_*.js", "**/*.test.js", "**/*.spec.js", "**/__tests__/**", "**/*.test.ts", "**/*.spec.ts"):
+            matches = list(self.repo_root.glob(pattern))
+            test_files.extend(matches)
+        # Deduplicate
+        seen: set[Path] = set()
+        deduped: list[Path] = []
+        for p in test_files:
+            resolved = p.resolve()
+            if resolved not in seen:
+                seen.add(resolved)
+                deduped.append(p)
+        return deduped
+
+    def find_calls_in_tests(self, target_name: str, test_files: list[Path]) -> list[tuple[Path, int]]:
+        """Find calls to a specific function name in test files."""
+        results: list[tuple[Path, int]] = []
+        try:
+            name_lower = target_name.lower()
+        except Exception:
+            return results
+
+        for tf in test_files:
+            try:
+                source = tf.read_text(encoding="utf-8", errors="ignore")
+                for m in re.finditer(rf'\b{re.escape(target_name)}\s*\(', source):
+                    line_num = source[:m.start()].count("\n") + 1
+                    results.append((tf, line_num))
+            except Exception:
+                pass
+        return results
+
+    def check_test_coverage(self, boundaries: list[SecurityBoundary]) -> SecurityReport:
+        """Check each boundary for test coverage."""
+        test_files = self.find_test_files()
+        report = SecurityReport()
+
+        for b in boundaries:
+            # Try to infer the function name from the matched text
+            func_name = _extract_func_name(b.matched_text)
+            if func_name:
+                calls = self.find_calls_in_tests(func_name, test_files)
+                if calls:
+                    b.has_test = True
+                    b.test_file = str(calls[0][0])
+                    report.tested.append(b)
+                else:
+                    report.untested.append(b)
+            else:
+                report.untested.append(b)
+
+            report.boundaries.append(b)
+
+        return report
+
+    def scan_and_report(self, files: list[Any]) -> SecurityReport:
+        """Scan a batch of files and check test coverage."""
+        all_boundaries: list[SecurityBoundary] = []
+        for f in files:
+            path = getattr(f, "path", None)
+            if path is None:
+                continue
+            all_boundaries.extend(self.scan_file(Path(path)))
+        return self.check_test_coverage(all_boundaries)
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def _extract_func_name(text: str) -> str | None:
+    """Extract the function/method name from matched source text."""
+    m = re.match(r'^.*?\b([\w.]+)\s*\(', text)
+    if m:
+        name = m.group(1)
+        # Remove module prefix for the last component
+        if "." in name:
+            name = name.rsplit(".", 1)[-1]
+        return name
+    return None