deadpush 0.2.0__py3-none-any.whl

deadpush/comments.py

@@ -0,0 +1,265 @@
+"""
+Stale Comment Detection — finds docstrings that reference non-existent parameters.
+
+AI agents frequently write verbose documentation that drifts from the actual
+implementation. This module compares documented parameters in docstrings with
+actual function signatures, flagging mismatches.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+PARAM_SECTION_PATTERNS = [
+    re.compile(r'Args:\s*', re.MULTILINE),
+    re.compile(r'Params?:\s*', re.MULTILINE),
+    re.compile(r'Parameters\s*[-:]\s*', re.MULTILINE),
+    re.compile(r'Keyword\s+Args?:\s*', re.MULTILINE),
+    re.compile(r'Keyword\s+Parameters:\s*', re.MULTILINE),
+    re.compile(r'Attributes:\s*', re.MULTILINE),
+    re.compile(r'Fields:\s*', re.MULTILINE),
+]
+
+DOC_PARAM_PATTERN = re.compile(r'^\s{4}(\w+)\s*[(:]', re.MULTILINE)
+PARAM_TAG_PATTERN = re.compile(r'@param\s+\{?\w*\}?\s*(\w+)')
+COLON_PARAM_PATTERN = re.compile(r':param\s+(\w+)\s*:')
+RETURN_TAG_PATTERN = re.compile(r'@returns?\s+\{?\w*\}?\s*(.*)')
+RETURN_SECTION_PATTERN = re.compile(r'Returns:\s*\n((?:\s{4}.+\n?)*)', re.MULTILINE)
+
+
+@dataclass
+class StaleDocIssue:
+    """A documentation mismatch issue."""
+    file: str
+    line: int
+    function: str
+    issue_type: str  # "missing_doc" | "stale_param" | "missing_return_doc"
+    description: str
+    confidence: float = 0.85
+
+
+class StaleCommentDetector:
+    """Detects stale documentation by comparing docstrings with actual code."""
+
+    # ------------------------------------------------------------------
+    # Python: AST-based analysis
+    # ------------------------------------------------------------------
+    def _extract_python_params(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+        """Extract actual parameter names from a function definition."""
+        params: set[str] = set()
+        for arg in node.args.args:
+            if arg.arg not in ("self", "cls"):
+                params.add(arg.arg)
+        if node.args.vararg:
+            params.add(f"*{node.args.vararg.arg}")
+        if node.args.kwarg:
+            params.add(f"**{node.args.kwarg.arg}")
+        for arg in node.args.kwonlyargs:
+            params.add(arg.arg)
+        for arg in node.args.posonlyargs:
+            if arg.arg not in ("self", "cls"):
+                params.add(arg.arg)
+        return params
+
+    def _extract_doc_params_python(self, docstring: str) -> set[str]:
+        """Extract documented parameter names from a Python docstring."""
+        doc_params: set[str] = set()
+
+        # Google-style: Args:\n    param_name: description
+        for section_pat in PARAM_SECTION_PATTERNS:
+            section_match = section_pat.search(docstring)
+            if section_match:
+                rest = docstring[section_match.end():]
+                for m in DOC_PARAM_PATTERN.finditer(rest):
+                    doc_params.add(m.group(1))
+
+        # RST-style: :param name: description
+        doc_params.update(COLON_PARAM_PATTERN.findall(docstring))
+
+        # Epydoc/Google: @param name: description
+        doc_params.update(PARAM_TAG_PATTERN.findall(docstring))
+
+        return doc_params
+
+    def _check_python_file(self, path: Path, rel_path: str) -> list[StaleDocIssue]:
+        """Analyze a single Python file for stale docstring issues."""
+        issues: list[StaleDocIssue] = []
+        try:
+            source = path.read_text(encoding="utf-8", errors="ignore")
+            tree = ast.parse(source, filename=str(path))
+        except (SyntaxError, Exception):
+            return issues
+
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                docstring = ast.get_docstring(node) or ""
+                actual_params = self._extract_python_params(node)
+                doc_params = self._extract_doc_params_python(docstring) if docstring else set()
+
+                if not docstring and node.name != "__init__":
+                    # Only flag public functions without docs
+                    if not node.name.startswith("_"):
+                        issues.append(StaleDocIssue(
+                            file=rel_path,
+                            line=node.lineno,
+                            function=node.name,
+                            issue_type="missing_doc",
+                            description=f"Function '{node.name}' has no docstring",
+                            confidence=0.80,
+                        ))
+                    continue
+
+                if not docstring:
+                    continue
+
+                # Stale params: documented but not in actual signature
+                stale = doc_params - actual_params
+                for param in stale:
+                    issues.append(StaleDocIssue(
+                        file=rel_path,
+                        line=node.lineno,
+                        function=node.name,
+                        issue_type="stale_param",
+                        description=f"Parameter '{param}' documented in '{node.name}' but not in actual signature",
+                        confidence=0.90,
+                    ))
+
+                # Missing docs: actual params not documented (only for non-trivial functions)
+                if actual_params and not node.name.startswith("_"):
+                    undocumented = actual_params - doc_params
+                    if undocumented and len(actual_params) > 1:
+                        issues.append(StaleDocIssue(
+                            file=rel_path,
+                            line=node.lineno,
+                            function=node.name,
+                            issue_type="missing_doc",
+                            description=f"Parameters undocumented in '{node.name}': {', '.join(sorted(undocumented))}",
+                            confidence=0.75,
+                        ))
+
+                # Check return documentation
+                has_return = any(
+                    isinstance(child, (ast.Return, ast.Yield, ast.YieldFrom))
+                    for child in ast.walk(node)
+                )
+                if has_return and docstring:
+                    returns_doc = (
+                        "@return" in docstring
+                        or "@returns" in docstring
+                        or "Returns:" in docstring
+                        or ":return:" in docstring
+                    )
+                    if not returns_doc and node.name != "__init__":
+                        issues.append(StaleDocIssue(
+                            file=rel_path,
+                            line=node.lineno,
+                            function=node.name,
+                            issue_type="missing_return_doc",
+                            description=f"Function '{node.name}' has return statement(s) but no @return documented",
+                            confidence=0.78,
+                        ))
+
+        return issues
+
+    # ------------------------------------------------------------------
+    # JS/TS: regex-based analysis
+    # ------------------------------------------------------------------
+    def _check_js_like_file(self, path: Path, rel_path: str) -> list[StaleDocIssue]:
+        """Analyze JS/TS file for stale JSDoc issues using regex."""
+        issues: list[StaleDocIssue] = []
+        try:
+            source = path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            return issues
+
+        # Find function definitions with JSDoc comments
+        # Pattern: /** ... */ then function name(...)
+        func_pattern = re.compile(
+            r'/\*\*\s*\n((?:[^*]|\*[^/])*)\*/\s*\n(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\('
+        )
+        arrow_pattern = re.compile(
+            r'/\*\*\s*\n((?:[^*]|\*[^/])*)\*/\s*\n(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:function\s*)?\('
+        )
+        method_pattern = re.compile(
+            r'/\*\*\s*\n((?:[^*]|\*[^/])*)\*/\s*\n\s*(\w+)\s*\(\s*[^)]*\)\s*\{'
+        )
+
+        for pattern, label in [(func_pattern, "function"), (arrow_pattern, "arrow"), (method_pattern, "method")]:
+            for match in pattern.finditer(source):
+                jsdoc = match.group(1)
+                func_name = match.group(2) if label != "method" else match.group(2)
+                if not func_name:
+                    continue
+
+                # Extract @param tags from JSDoc
+                doc_params = set(PARAM_TAG_PATTERN.findall(jsdoc))
+
+                # We can't easily get actual params from regex, so just flag stale @param names
+                # that are misspelled or don't match common patterns
+                # For JS/TS, we look for @param names that are very short or unusual
+                for param in doc_params:
+                    if len(param) <= 1:
+                        issues.append(StaleDocIssue(
+                            file=rel_path,
+                            line=source[:match.start()].count("\n") + 1,
+                            function=func_name,
+                            issue_type="stale_param",
+                            description=f"Suspicious @param '{param}' in JSDoc for '{func_name}' — very short name",
+                            confidence=0.70,
+                        ))
+                    elif not re.match(r'^[a-z_]\w*$', param, re.IGNORECASE):
+                        issues.append(StaleDocIssue(
+                            file=rel_path,
+                            line=source[:match.start()].count("\n") + 1,
+                            function=func_name,
+                            issue_type="stale_param",
+                            description=f"Unusual @param '{param}' in JSDoc for '{func_name}'",
+                            confidence=0.65,
+                        ))
+
+                # Check for @returns
+                has_return_tag = bool(RETURN_TAG_PATTERN.search(jsdoc))
+                if not has_return_tag and "function" in label:
+                    # Estimate if function has return by checking for 'return' keyword
+                    func_body_start = match.end()
+                    func_body = source[func_body_start:func_body_start + 500]
+                    if "return " in func_body and not has_return_tag:
+                        issues.append(StaleDocIssue(
+                            file=rel_path,
+                            line=source[:match.start()].count("\n") + 1,
+                            function=func_name,
+                            issue_type="missing_return_doc",
+                            description=f"Function '{func_name}' has 'return' but no @returns in JSDoc",
+                            confidence=0.74,
+                        ))
+
+        return issues
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def analyze_file(self, path: Path, rel_path: str) -> list[StaleDocIssue]:
+        """Analyze a single file for stale documentation."""
+        if path.suffix == ".py":
+            return self._check_python_file(path, rel_path)
+        elif path.suffix in (".js", ".jsx", ".ts", ".tsx", ".mjs", ".mts", ".cjs", ".cts"):
+            return self._check_js_like_file(path, rel_path)
+        return []
+
+    def analyze_batch(self, files: list[Any]) -> list[StaleDocIssue]:
+        """Analyze all source files for stale documentation issues."""
+        all_issues: list[StaleDocIssue] = []
+        for f in files:
+            if not getattr(f, "is_text", True):
+                continue
+            try:
+                issues = self.analyze_file(f.path, str(getattr(f, "rel_path", f.path)))
+                all_issues.extend(issues)
+            except Exception:
+                pass
+        return all_issues

deadpush/complexity.py

@@ -0,0 +1,254 @@
+"""
+Complexity Gate — tracks cyclomatic complexity per file and alerts on spikes.
+
+Vibe coding sessions can silently balloon complexity as AI agents add features
+without considering maintainability. This module computes McCabe cyclomatic
+complexity per file, caches a baseline, and warns when complexity increases
+beyond a threshold (default: 20%).
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import math
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+
+COMPLEXITY_CACHE_FILE = Path.home() / ".deadpush" / "complexity_cache.json"
+COMPLEXITY_CACHE_MAX_AGE = 604800  # 1 week
+DEFAULT_THRESHOLD_PCT = 20
+
+
+# ---------------------------------------------------------------------------
+# Cyclomatic Complexity Calculators
+# ---------------------------------------------------------------------------
+
+def _compute_python_complexity(source: str) -> int:
+    """Compute McCabe cyclomatic complexity for Python source using AST."""
+    complexity = 1  # base
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return 0
+
+    for node in ast.walk(tree):
+        # Decision points
+        if isinstance(node, (ast.If, ast.While, ast.For, ast.AsyncFor, ast.With, ast.AsyncWith)):
+            complexity += 1
+        elif isinstance(node, ast.ExceptHandler):
+            complexity += 1
+        elif isinstance(node, ast.Assert):
+            complexity += 1
+        # Boolean operators increase paths
+        elif isinstance(node, ast.BoolOp):
+            complexity += len(node.values) - 1
+        # ternary / if-expressions
+        elif isinstance(node, ast.IfExp):
+            complexity += 1
+        # match/case (Python 3.10+)
+        elif isinstance(node, ast.Match):
+            complexity += len(node.cases)
+        # comprehensions
+        elif isinstance(node, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+            complexity += len(node.generators)
+
+    return complexity
+
+
+def _compute_js_like_complexity(source: str) -> int:
+    """Compute approximate complexity for JS/TS using regex pattern counting."""
+    complexity = 1
+    patterns = [
+        r'\bif\s*\(', r'\belse\s+if\b', r'\belse\b',
+        r'\bfor\s*\(', r'\bwhile\s*\(', r'\bdo\s*\{',
+        r'\bswitch\s*\(', r'\bcase\s+',
+        r'\bcatch\s*\(', r'\bfinally\b',
+        r'\b&&\b', r'\b\|\|\b',
+        r'\?.*:.*',
+    ]
+    for p in patterns:
+        complexity += len(re.findall(p, source))
+    return complexity
+
+
+def _compute_go_complexity(source: str) -> int:
+    complexity = 1
+    patterns = [
+        r'\bif\b', r'\belse\b', r'\bfor\b', r'\brange\b',
+        r'\bswitch\b', r'\bcase\b', r'\bselect\b',
+    ]
+    for p in patterns:
+        complexity += len(re.findall(p, source))
+    return complexity
+
+
+def _compute_rust_complexity(source: str) -> int:
+    complexity = 1
+    patterns = [
+        r'\bif\b', r'\belse\b', r'\bfor\b', r'\bwhile\b',
+        r'\bmatch\b', r'=>', r'\bif let\b', r'\bwhile let\b',
+    ]
+    for p in patterns:
+        complexity += len(re.findall(p, source))
+    return complexity
+
+
+def _compute_cpp_complexity(source: str) -> int:
+    complexity = 1
+    patterns = [
+        r'\bif\s*\(', r'\belse\b', r'\bfor\s*\(', r'\bwhile\s*\(',
+        r'\bswitch\s*\(', r'\bcase\b', r'\bcatch\s*\(',
+        r'\b&&\b', r'\b\|\|\b', r'\?',
+    ]
+    for p in patterns:
+        complexity += len(re.findall(p, source))
+    return complexity
+
+
+def _compute_java_complexity(source: str) -> int:
+    complexity = 1
+    patterns = [
+        r'\bif\s*\(', r'\belse\b', r'\bfor\s*\(', r'\bwhile\s*\(',
+        r'\bdo\s*\{', r'\bswitch\s*\(', r'\bcase\b',
+        r'\bcatch\s*\(', r'\bfinally\b', r'\b&&\b', r'\b\|\|\b',
+        r'\?', r'\binstanceof\b',
+    ]
+    for p in patterns:
+        complexity += len(re.findall(p, source))
+    return complexity
+
+
+_COMPLEXITY_FUNCS: dict[str, Any] = {
+    ".py": _compute_python_complexity,
+    ".js": _compute_js_like_complexity,
+    ".jsx": _compute_js_like_complexity,
+    ".mjs": _compute_js_like_complexity,
+    ".cjs": _compute_js_like_complexity,
+    ".ts": _compute_js_like_complexity,
+    ".tsx": _compute_js_like_complexity,
+    ".mts": _compute_js_like_complexity,
+    ".cts": _compute_js_like_complexity,
+    ".go": _compute_go_complexity,
+    ".rs": _compute_rust_complexity,
+    ".c": _compute_cpp_complexity,
+    ".cpp": _compute_cpp_complexity,
+    ".cc": _compute_cpp_complexity,
+    ".cxx": _compute_cpp_complexity,
+    ".h": _compute_cpp_complexity,
+    ".hpp": _compute_cpp_complexity,
+    ".java": _compute_java_complexity,
+    ".kt": _compute_java_complexity,
+}
+
+
+def compute_complexity(path: Path) -> int | None:
+    """Compute cyclomatic complexity for a source file. Returns None on failure."""
+    suffix = path.suffix.lower()
+    func = _COMPLEXITY_FUNCS.get(suffix)
+    if func is None:
+        return None
+    try:
+        source = path.read_text(encoding="utf-8", errors="ignore")
+        return func(source)
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Complexity Tracker
+# ---------------------------------------------------------------------------
+
+class ComplexityTracker:
+    """Tracks complexity baseline per file and detects significant increases."""
+
+    def __init__(self, threshold_pct: int = DEFAULT_THRESHOLD_PCT):
+        self.threshold_pct = threshold_pct
+        self.cache_file = COMPLEXITY_CACHE_FILE
+        self._cache: dict[str, dict[str, Any]] = {}
+        self._load_cache()
+
+    def _load_cache(self):
+        if self.cache_file.exists():
+            try:
+                data = json.loads(self.cache_file.read_text(encoding="utf-8"))
+                now = time.time()
+                self._cache = {
+                    k: v for k, v in data.items()
+                    if now - v.get("baseline_at", 0) < COMPLEXITY_CACHE_MAX_AGE
+                }
+            except Exception:
+                self._cache = {}
+
+    def _save_cache(self):
+        try:
+            self.cache_file.parent.mkdir(parents=True, exist_ok=True)
+            self.cache_file.write_text(
+                json.dumps(self._cache, indent=2, default=str),
+                encoding="utf-8",
+            )
+        except Exception:
+            pass
+
+    def get_baseline(self, file_path: str) -> int | None:
+        """Get cached baseline complexity for a file."""
+        entry = self._cache.get(file_path)
+        if entry:
+            return entry.get("complexity")
+        return None
+
+    def check_complexity(self, file_path: str, path: Path) -> dict[str, Any] | None:
+        """Check file complexity against baseline. Returns alert dict if threshold exceeded."""
+        current = compute_complexity(path)
+        if current is None:
+            return None
+
+        baseline = self.get_baseline(file_path)
+
+        if baseline is not None and baseline > 0:
+            increase = current - baseline
+            pct_increase = (increase / baseline) * 100
+            increase_ratio = current / baseline
+
+            if pct_increase >= self.threshold_pct:
+                return {
+                    "file": file_path,
+                    "baseline": baseline,
+                    "current": current,
+                    "increase": increase,
+                    "pct_increase": round(pct_increase, 1),
+                    "threshold_pct": self.threshold_pct,
+                    "exceeded": True,
+                }
+        else:
+            # First time seeing this file — set baseline
+            self._cache[file_path] = {
+                "complexity": current,
+                "baseline_at": time.time(),
+            }
+            self._save_cache()
+
+            if current > 30:
+                return {
+                    "file": file_path,
+                    "baseline": None,
+                    "current": current,
+                    "increase": None,
+                    "pct_increase": None,
+                    "threshold_pct": self.threshold_pct,
+                    "exceeded": False,
+                    "note": f"Initial complexity is high ({current}). Consider refactoring.",
+                }
+
+        return None
+
+    def update_baseline(self, file_path: str, complexity: int):
+        """Update baseline after confirming the change is intentional."""
+        self._cache[file_path] = {
+            "complexity": complexity,
+            "baseline_at": time.time(),
+        }
+        self._save_cache()