ghostbuster-cli 0.1.0__py3-none-any.whl

ghostbuster/core/orphan_files.py

@@ -0,0 +1,298 @@
+"""Orphan File Scanner — detects files/folders that should be in .gitignore.
+
+Identifies large files, common build artifacts, dependency directories,
+and other items that are tracked by git but shouldn't be.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+
+from ghostbuster.core.models import Ghost, GhostCategory, Severity
+
+# Directories that should almost always be in .gitignore
+IGNORABLE_DIRS: dict[str, str] = {
+    "node_modules": "Node.js dependencies directory",
+    "venv": "Python virtual environment",
+    ".venv": "Python virtual environment",
+    "env": "Python virtual environment",
+    ".env": "Python virtual environment",
+    "__pycache__": "Python bytecode cache",
+    ".pytest_cache": "Pytest cache",
+    ".mypy_cache": "Mypy cache",
+    ".ruff_cache": "Ruff cache",
+    ".tox": "Tox environments",
+    ".nox": "Nox environments",
+    "dist": "Build distribution directory",
+    "build": "Build output directory",
+    ".eggs": "Python eggs directory",
+    "*.egg-info": "Python egg-info directory",
+    "htmlcov": "Coverage HTML report",
+    ".coverage": "Coverage data file",
+    ".hypothesis": "Hypothesis testing cache",
+    "bower_components": "Bower dependencies",
+    ".next": "Next.js build output",
+    ".nuxt": "Nuxt.js build output",
+    ".cache": "Generic cache directory",
+    ".parcel-cache": "Parcel bundler cache",
+    ".turbo": "Turborepo cache",
+}
+
+# File patterns that are commonly forgotten
+IGNORABLE_PATTERNS: dict[str, str] = {
+    ".pyc": "Python bytecode",
+    ".pyo": "Python optimized bytecode",
+    ".DS_Store": "macOS metadata",
+    "Thumbs.db": "Windows thumbnail cache",
+    ".env": "Environment variables file (may contain secrets)",
+    ".env.local": "Local environment variables",
+}
+
+# Size threshold for flagging large files (10 MB)
+LARGE_FILE_THRESHOLD = 10 * 1024 * 1024
+
+# File extensions that are commonly large and shouldn't be in repos
+LARGE_FILE_EXTENSIONS: set[str] = {
+    ".h5",
+    ".hdf5",  # ML model files
+    ".pkl",
+    ".pickle",  # Pickled data
+    ".pt",
+    ".pth",  # PyTorch models
+    ".onnx",  # ONNX models
+    ".bin",  # Generic binary
+    ".db",
+    ".sqlite",  # Databases
+    ".sqlite3",
+    ".csv",  # Data files (when large)
+    ".parquet",
+    ".zip",
+    ".tar",
+    ".gz",  # Archives
+    ".tar.gz",
+    ".tgz",
+    ".rar",
+    ".7z",
+    ".mp4",
+    ".avi",  # Video files
+    ".mov",
+    ".mkv",
+    ".iso",  # Disk images
+}
+
+
+class OrphanFileScanner:
+    """Detects files and directories that should be in .gitignore."""
+
+    name = "orphan-file"
+
+    def scan(self, path: Path) -> list[Ghost]:
+        """Scan a project directory for orphan files."""
+        ghosts: list[Ghost] = []
+        gitignore_patterns = self._load_gitignore(path)
+
+        # Check for ignorable directories
+        ghosts.extend(self._check_ignorable_dirs(path, gitignore_patterns))
+
+        # Check for large files
+        ghosts.extend(self._check_large_files(path))
+
+        # Check for common forgotten files
+        ghosts.extend(self._check_forgotten_files(path, gitignore_patterns))
+
+        return ghosts
+
+    def _load_gitignore(self, path: Path) -> set[str]:
+        """Load patterns from .gitignore file."""
+        gitignore = path / ".gitignore"
+        if not gitignore.exists():
+            return set()
+
+        patterns: set[str] = set()
+        try:
+            for line in gitignore.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    # Normalize: remove trailing slashes for directory matching
+                    patterns.add(line.rstrip("/"))
+            return patterns
+        except OSError:
+            return set()
+
+    def _is_in_gitignore(self, name: str, patterns: set[str]) -> bool:
+        """Check if a name matches any gitignore pattern (simplified check)."""
+        # Simple check: exact match or glob pattern
+        if name in patterns:
+            return True
+        if name + "/" in patterns:
+            return True
+        if "/" + name in patterns:
+            return True
+        # Check wildcard patterns like *.pyc
+        for pattern in patterns:
+            if pattern.startswith("*") and name.endswith(pattern[1:]):
+                return True
+            if pattern.endswith("*") and name.startswith(pattern[:-1]):
+                return True
+            if pattern.endswith("/") and name == pattern[:-1]:
+                return True
+        return False
+
+    def _check_ignorable_dirs(self, path: Path, gitignore_patterns: set[str]) -> list[Ghost]:
+        """Check for directories that should be in .gitignore."""
+        ghosts: list[Ghost] = []
+
+        for item in path.iterdir():
+            if not item.is_dir():
+                continue
+
+            dir_name = item.name
+
+            # Check known ignorable directories
+            if dir_name in IGNORABLE_DIRS and not self._is_in_gitignore(
+                dir_name, gitignore_patterns
+            ):
+                # Calculate directory size for impact assessment
+                size = self._get_dir_size(item)
+                size_str = self._format_size(size)
+                ghosts.append(
+                    Ghost(
+                        category=GhostCategory.ORPHAN_FILE,
+                        name=dir_name,
+                        message=(
+                            f"Directory '{dir_name}/' ({size_str}) is "
+                            f"{IGNORABLE_DIRS[dir_name]} and should be in .gitignore"
+                        ),
+                        file_path=item,
+                        severity=Severity.HIGH if size > LARGE_FILE_THRESHOLD else Severity.MEDIUM,
+                        fixable=True,
+                        suggestion=f"Add '{dir_name}/' to .gitignore",
+                    )
+                )
+
+            # Check for egg-info directories
+            if dir_name.endswith(".egg-info") and not self._is_in_gitignore(
+                "*.egg-info", gitignore_patterns
+            ):
+                ghosts.append(
+                    Ghost(
+                        category=GhostCategory.ORPHAN_FILE,
+                        name=dir_name,
+                        message=f"Directory '{dir_name}/' is a build artifact and should be in .gitignore",
+                        file_path=item,
+                        severity=Severity.MEDIUM,
+                        fixable=True,
+                        suggestion="Add '*.egg-info/' to .gitignore",
+                    )
+                )
+
+        return ghosts
+
+    def _check_large_files(self, path: Path) -> list[Ghost]:
+        """Check for files that exceed the size threshold."""
+        ghosts: list[Ghost] = []
+
+        for item in path.rglob("*"):
+            if not item.is_file():
+                continue
+
+            # Skip .git directory
+            try:
+                rel = item.relative_to(path)
+            except ValueError:
+                continue
+
+            parts = rel.parts
+            if any(p in {".git", "node_modules", "venv", ".venv", "__pycache__"} for p in parts):
+                continue
+
+            try:
+                size = item.stat().st_size
+            except OSError:
+                continue
+
+            # Flag files with suspicious extensions regardless of size
+            suffix = item.suffix.lower()
+            if suffix in LARGE_FILE_EXTENSIONS and size > 1024 * 1024:  # > 1MB
+                size_str = self._format_size(size)
+                ghosts.append(
+                    Ghost(
+                        category=GhostCategory.ORPHAN_FILE,
+                        name=item.name,
+                        message=f"Large file '{rel}' ({size_str}) should probably not be in the repository",
+                        file_path=item,
+                        severity=Severity.HIGH if size > LARGE_FILE_THRESHOLD else Severity.MEDIUM,
+                        fixable=True,
+                        suggestion=f"Add '{item.name}' to .gitignore and use Git LFS or external storage",
+                    )
+                )
+            elif size > LARGE_FILE_THRESHOLD:
+                size_str = self._format_size(size)
+                ghosts.append(
+                    Ghost(
+                        category=GhostCategory.ORPHAN_FILE,
+                        name=item.name,
+                        message=f"File '{rel}' ({size_str}) exceeds {self._format_size(LARGE_FILE_THRESHOLD)} threshold",
+                        file_path=item,
+                        severity=Severity.HIGH,
+                        fixable=False,
+                        suggestion=f"Consider adding '{item.name}' to .gitignore or using Git LFS",
+                    )
+                )
+
+        return ghosts
+
+    def _check_forgotten_files(self, path: Path, gitignore_patterns: set[str]) -> list[Ghost]:
+        """Check for common files that should be gitignored."""
+        ghosts: list[Ghost] = []
+
+        for item in path.iterdir():
+            if not item.is_file():
+                continue
+
+            name = item.name
+
+            # Check specific filenames
+            if name in IGNORABLE_PATTERNS and not self._is_in_gitignore(name, gitignore_patterns):
+                ghosts.append(
+                    Ghost(
+                        category=GhostCategory.ORPHAN_FILE,
+                        name=name,
+                        message=f"File '{name}' ({IGNORABLE_PATTERNS[name]}) should be in .gitignore",
+                        file_path=item,
+                        severity=Severity.LOW
+                        if name in {".DS_Store", "Thumbs.db"}
+                        else Severity.MEDIUM,
+                        fixable=True,
+                        suggestion=f"Add '{name}' to .gitignore",
+                    )
+                )
+
+        return ghosts
+
+    def _get_dir_size(self, path: Path, max_depth: int = 3) -> int:
+        """Calculate approximate directory size (limited depth for speed)."""
+        total = 0
+        depth = 0
+        try:
+            for item in path.rglob("*"):
+                if item.is_file():
+                    with contextlib.suppress(OSError):
+                        total += item.stat().st_size
+                # Simple depth tracking
+                depth += 1
+                if depth > 10000:  # Safety limit
+                    break
+        except OSError:
+            pass
+        return total
+
+    @staticmethod
+    def _format_size(size: int) -> str:
+        """Format a file size in human-readable format."""
+        for unit in ("B", "KB", "MB", "GB"):
+            if size < 1024:
+                return f"{size:.1f} {unit}"
+            size //= 1024
+        return f"{size:.1f} TB"

ghostbuster/core/phantom_env.py

@@ -0,0 +1,196 @@
+"""Phantom Env Scanner — detects env vars referenced but never set.
+
+Scans Python files for os.environ / os.getenv usage and checks if the
+referenced environment variables are defined in .env files or the system.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import re
+from pathlib import Path
+
+from ghostbuster.core.models import Ghost, GhostCategory, Severity
+
+
+class PhantomEnvScanner:
+    """Detects environment variables referenced in code but not set anywhere."""
+
+    name = "phantom-env"
+
+    def scan(self, path: Path) -> list[Ghost]:
+        """Scan a project directory for phantom environment variables."""
+        # Collect all env vars referenced in code
+        referenced = self._find_referenced_env_vars(path)
+        if not referenced:
+            return []
+
+        # Collect all env vars that are defined
+        defined = self._find_defined_env_vars(path)
+
+        # Find phantoms: referenced but not defined
+        ghosts: list[Ghost] = []
+        for env_var, locations in referenced.items():
+            if env_var not in defined:
+                # Use the first location for the ghost
+                first_file, first_line = locations[0]
+
+                locations_str = ", ".join(f"{f.name}:{l}" for f, l in locations[:3])
+                if len(locations) > 3:
+                    locations_str += f" (+{len(locations) - 3} more)"
+
+                ghosts.append(
+                    Ghost(
+                        category=GhostCategory.PHANTOM_ENV,
+                        name=env_var,
+                        message=(
+                            f"Environment variable '{env_var}' is referenced "
+                            f"at {locations_str} but never defined"
+                        ),
+                        file_path=first_file,
+                        line_number=first_line,
+                        severity=Severity.HIGH,
+                        fixable=True,
+                        suggestion=f"Add '{env_var}=' to your .env file or set it in your environment",
+                    )
+                )
+
+        return ghosts
+
+    def _find_referenced_env_vars(self, path: Path) -> dict[str, list[tuple[Path, int]]]:
+        """Find all env var references in Python files via AST + regex.
+
+        Returns mapping of env_var_name -> list of (file_path, line_number).
+        """
+        env_vars: dict[str, list[tuple[Path, int]]] = {}
+
+        for py_file in path.rglob("*.py"):
+            parts = py_file.relative_to(path).parts
+            if any(
+                p
+                in {
+                    "venv",
+                    ".venv",
+                    "node_modules",
+                    ".git",
+                    "__pycache__",
+                    ".tox",
+                    ".nox",
+                    "build",
+                    "dist",
+                }
+                for p in parts
+            ):
+                continue
+
+            try:
+                source = py_file.read_text(encoding="utf-8", errors="ignore")
+                tree = ast.parse(source, filename=str(py_file))
+            except (SyntaxError, OSError):
+                continue
+
+            # AST-based detection
+            for node in ast.walk(tree):
+                env_name = self._extract_env_var_from_node(node)
+                if env_name:
+                    env_vars.setdefault(env_name, []).append((py_file, getattr(node, "lineno", 0)))
+
+        return env_vars
+
+    def _extract_env_var_from_node(self, node: ast.AST) -> str | None:
+        """Extract an env var name from an AST node if it's an env access pattern.
+
+        Detects:
+        - os.environ["KEY"]
+        - os.environ.get("KEY")
+        - os.getenv("KEY")
+        """
+        # Pattern: os.environ["KEY"] or os.environ.get("KEY")
+        if (
+            isinstance(node, ast.Subscript)
+            and self._is_os_environ(node.value)
+            and isinstance(node.slice, ast.Constant)
+            and isinstance(node.slice.value, str)
+        ):
+            return node.slice.value
+
+        # Pattern: os.environ.get("KEY", ...) or os.getenv("KEY", ...)
+        if isinstance(node, ast.Call):
+            func = node.func
+
+            # os.getenv("KEY")
+            if (
+                isinstance(func, ast.Attribute)
+                and func.attr == "getenv"
+                and isinstance(func.value, ast.Name)
+                and func.value.id == "os"
+            ):
+                return self._get_first_str_arg(node)
+
+            # os.environ.get("KEY")
+            if (
+                isinstance(func, ast.Attribute)
+                and func.attr == "get"
+                and self._is_os_environ(func.value)
+            ):
+                return self._get_first_str_arg(node)
+
+        return None
+
+    def _is_os_environ(self, node: ast.AST) -> bool:
+        """Check if a node represents 'os.environ'."""
+        return (
+            isinstance(node, ast.Attribute)
+            and node.attr == "environ"
+            and isinstance(node.value, ast.Name)
+            and node.value.id == "os"
+        )
+
+    def _get_first_str_arg(self, node: ast.Call) -> str | None:
+        """Get the first string argument from a call node."""
+        if (
+            node.args
+            and isinstance(node.args[0], ast.Constant)
+            and isinstance(node.args[0].value, str)
+        ):
+            return node.args[0].value
+        return None
+
+    def _find_defined_env_vars(self, path: Path) -> set[str]:
+        """Find env vars that are actually defined.
+
+        Checks:
+        - Current process environment
+        - .env file
+        - .env.example file
+        - .env.sample file
+        """
+        defined: set[str] = set()
+
+        # System environment
+        defined.update(os.environ.keys())
+
+        # .env files
+        for env_filename in (".env", ".env.example", ".env.sample", ".env.template", ".env.local"):
+            env_file = path / env_filename
+            if env_file.exists():
+                defined.update(self._parse_env_file(env_file))
+
+        return defined
+
+    def _parse_env_file(self, filepath: Path) -> set[str]:
+        """Parse a .env file and return all defined variable names."""
+        env_vars: set[str] = set()
+        try:
+            for line in filepath.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                # Match KEY=value or export KEY=value
+                match = re.match(r"^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=", line)
+                if match:
+                    env_vars.add(match.group(1))
+        except OSError:
+            pass
+        return env_vars

ghostbuster/core/scanner.py

@@ -0,0 +1,112 @@
+"""Scanner protocol and orchestrator for running all ghost detectors."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from ghostbuster.core.models import Ghost, GhostCategory, ScanResult, Severity
+from ghostbuster.core.scoring import calculate_score
+
+
+@runtime_checkable
+class Scanner(Protocol):
+    """Protocol that all ghost scanners must implement.
+
+    Each scanner is responsible for detecting one category of ghosts.
+    Scanners must be pure logic — no CLI/UI side effects.
+    """
+
+    name: str
+
+    def scan(self, path: Path) -> list[Ghost]:
+        """Scan the given path and return a list of found ghosts."""
+        ...
+
+
+class ScanOrchestrator:
+    """Runs all registered scanners and aggregates results.
+
+    Usage::
+
+        orchestrator = ScanOrchestrator()
+        orchestrator.register(DeadImportScanner())
+        orchestrator.register(OrphanFileScanner())
+        result = orchestrator.run(Path("."))
+    """
+
+    def __init__(self) -> None:
+        self._scanners: list[Scanner] = []
+
+    def register(self, scanner: Scanner) -> None:
+        """Register a scanner to be run during scan."""
+        self._scanners.append(scanner)
+
+    @property
+    def scanner_names(self) -> list[str]:
+        """Return names of all registered scanners."""
+        return [s.name for s in self._scanners]
+
+    def run(
+        self,
+        path: Path,
+        categories: list[str] | None = None,
+    ) -> ScanResult:
+        """Run all registered scanners (or filtered subset) on the given path.
+
+        Args:
+            path: Root directory to scan.
+            categories: Optional list of category names to filter scanners.
+                        If None, all scanners are run.
+
+        Returns:
+            Aggregated ScanResult with all ghosts found and a score.
+        """
+        start = time.perf_counter()
+        all_ghosts: list[Ghost] = []
+
+        scanners_to_run = self._scanners
+        if categories:
+            scanners_to_run = [s for s in self._scanners if s.name in categories]
+
+        for scanner in scanners_to_run:
+            try:
+                ghosts = scanner.scan(path)
+                all_ghosts.extend(ghosts)
+            except Exception as exc:
+                # Don't let one scanner crash the entire run.
+                # In debug mode, the CLI layer will re-raise.
+                all_ghosts.append(
+                    Ghost(
+                        category=GhostCategory.DEAD_IMPORT,
+                        name=f"scanner-error-{scanner.name}",
+                        message=f"Scanner '{scanner.name}' failed: {exc}",
+                        severity=Severity.LOW,
+                    )
+                )
+
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        score = calculate_score(all_ghosts)
+
+        return ScanResult(
+            ghosts=all_ghosts,
+            score=score,
+            scanned_path=path,
+            duration_ms=elapsed_ms,
+        )
+
+
+def create_default_orchestrator() -> ScanOrchestrator:
+    """Create an orchestrator with all built-in scanners registered."""
+    from ghostbuster.core.dead_imports import DeadImportScanner
+    from ghostbuster.core.orphan_files import OrphanFileScanner
+    from ghostbuster.core.phantom_env import PhantomEnvScanner
+    from ghostbuster.core.zombie_code import ZombieCodeScanner
+
+    orchestrator = ScanOrchestrator()
+    orchestrator.register(DeadImportScanner())
+    orchestrator.register(OrphanFileScanner())
+    orchestrator.register(ZombieCodeScanner())
+    orchestrator.register(PhantomEnvScanner())
+    return orchestrator

ghostbuster/core/scoring.py

@@ -0,0 +1,83 @@
+"""Ghost Score calculation — the signature viraliy metric.
+
+Computes a 0-100 "hauntedness" score based on ghost findings.
+Designed to be provocative enough to screenshot and share.
+"""
+
+from __future__ import annotations
+
+from ghostbuster.core.models import Ghost, GhostCategory, GhostScore, Severity
+
+# Weight multipliers per category (reflects real-world severity impact)
+CATEGORY_WEIGHTS: dict[GhostCategory, int] = {
+    GhostCategory.DEAD_IMPORT: 5,  # Common, moderate waste
+    GhostCategory.ORPHAN_FILE: 8,  # Disk space, clone time
+    GhostCategory.ZOMBIE_CODE: 3,  # Confusing but usually harmless
+    GhostCategory.PHANTOM_ENV: 10,  # Can cause runtime crashes
+}
+
+# Bonus weight for high-severity ghosts
+SEVERITY_MULTIPLIER: dict[Severity, float] = {
+    Severity.LOW: 0.5,
+    Severity.MEDIUM: 1.0,
+    Severity.HIGH: 1.5,
+}
+
+# Score thresholds and their labels
+SCORE_LABELS: list[tuple[int, str]] = [
+    (0, "No ghosts detected. Your codebase is clean!"),
+    (10, "Almost clean - just a few minor issues."),
+    (20, "Mildly affected. Nothing a quick cleanup cannot fix."),
+    (35, "Multiple issues detected. Time for cleanup."),
+    (50, "Noticeable technical debt detected."),
+    (70, "Seriously affected. Your codebase needs significant cleanup."),
+    (85, "Extremely cluttered with unused code and files."),
+    (100, "Severe technical debt detected across multiple categories."),
+]
+
+
+def calculate_score(ghosts: list[Ghost]) -> GhostScore:
+    """Calculate the Ghost Score from a list of ghost findings.
+
+    The score is a weighted sum of ghosts, capped at 100.
+    Each ghost contributes its category weight × severity multiplier.
+
+    Args:
+        ghosts: List of Ghost findings from all scanners.
+
+    Returns:
+        GhostScore with value (0-100), label, and per-category breakdown.
+    """
+    if not ghosts:
+        return GhostScore(
+            value=0,
+            label=SCORE_LABELS[0][1],
+            breakdown={cat: 0 for cat in GhostCategory},
+        )
+
+    # Calculate raw score with weighted contributions
+    raw_score = 0.0
+    breakdown: dict[GhostCategory, int] = {cat: 0 for cat in GhostCategory}
+
+    for ghost in ghosts:
+        weight = CATEGORY_WEIGHTS.get(ghost.category, 3)
+        multiplier = SEVERITY_MULTIPLIER.get(ghost.severity, 1.0)
+        contribution = weight * multiplier
+        raw_score += contribution
+        breakdown[ghost.category] = breakdown.get(ghost.category, 0) + 1
+
+    # Cap at 100
+    final_score = min(int(raw_score), 100)
+
+    # Find the appropriate label
+    label = SCORE_LABELS[-1][1]  # Default to worst
+    for threshold, score_label in SCORE_LABELS:
+        if final_score <= threshold:
+            label = score_label
+            break
+
+    return GhostScore(
+        value=final_score,
+        label=label,
+        breakdown=breakdown,
+    )