ghostbuster-cli 0.1.0__py3-none-any.whl

ghostbuster/config.py

@@ -0,0 +1,116 @@
+"""Configuration loading for ghostbuster.
+
+Supports configuration from:
+- .ghostbuster.toml (project root)
+- pyproject.toml [tool.ghostbuster] section
+- CLI flags (highest priority)
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class GhostbusterConfig:
+    """Configuration for a ghostbuster scan.
+
+    All fields have sensible defaults so ghostbuster works with zero config.
+    """
+
+    # Directories to exclude from scanning
+    exclude_dirs: list[str] = field(
+        default_factory=lambda: [
+            "venv",
+            ".venv",
+            "node_modules",
+            ".git",
+            "__pycache__",
+            ".tox",
+            ".nox",
+            "build",
+            "dist",
+            ".eggs",
+            "migrations",
+        ]
+    )
+
+    # File patterns to exclude from scanning
+    exclude_patterns: list[str] = field(default_factory=list)
+
+    # Categories to scan (empty = all)
+    categories: list[str] = field(default_factory=list)
+
+    # Packages to ignore in dead-import scanning
+    ignore_packages: list[str] = field(default_factory=list)
+
+    # Env vars to ignore in phantom-env scanning
+    ignore_env_vars: list[str] = field(default_factory=list)
+
+    # Functions/classes to ignore in zombie-code scanning
+    ignore_names: list[str] = field(default_factory=list)
+
+    # Large file threshold in bytes (default: 10MB)
+    large_file_threshold: int = 10 * 1024 * 1024
+
+    @staticmethod
+    def load(path: Path) -> GhostbusterConfig:
+        """Load configuration from project files.
+
+        Priority:
+        1. .ghostbuster.toml
+        2. pyproject.toml [tool.ghostbuster]
+        3. Defaults
+        """
+        config = GhostbusterConfig()
+
+        # Try .ghostbuster.toml first
+        ghostbuster_toml = path / ".ghostbuster.toml"
+        if ghostbuster_toml.exists():
+            data = _load_toml(ghostbuster_toml)
+            config = _apply_config(config, data)
+            return config
+
+        # Try pyproject.toml [tool.ghostbuster]
+        pyproject = path / "pyproject.toml"
+        if pyproject.exists():
+            data = _load_toml(pyproject)
+            tool_config = data.get("tool", {}).get("ghostbuster", {})
+            if tool_config:
+                config = _apply_config(config, tool_config)
+
+        return config
+
+
+def _load_toml(filepath: Path) -> dict:
+    """Load a TOML file and return its contents as a dict."""
+    try:
+        if sys.version_info >= (3, 11):
+            import tomllib
+        else:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        return tomllib.loads(filepath.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _apply_config(config: GhostbusterConfig, data: dict) -> GhostbusterConfig:
+    """Apply a dict of config values to a GhostbusterConfig."""
+    if "exclude_dirs" in data:
+        config.exclude_dirs = data["exclude_dirs"]
+    if "exclude_patterns" in data:
+        config.exclude_patterns = data["exclude_patterns"]
+    if "categories" in data:
+        config.categories = data["categories"]
+    if "ignore_packages" in data:
+        config.ignore_packages = data["ignore_packages"]
+    if "ignore_env_vars" in data:
+        config.ignore_env_vars = data["ignore_env_vars"]
+    if "ignore_names" in data:
+        config.ignore_names = data["ignore_names"]
+    if "large_file_threshold" in data:
+        config.large_file_threshold = data["large_file_threshold"]
+    return config

ghostbuster/core/__init__.py

@@ -0,0 +1 @@
+"""Core scanning and analysis engine — no CLI/UI dependencies."""

ghostbuster/core/dead_imports.py

@@ -0,0 +1,273 @@
+"""Dead Import Scanner — detects dependencies declared but never imported.
+
+Checks requirements.txt, pyproject.toml, and setup.cfg for declared
+dependencies, then walks all Python files to see which are actually imported.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from pathlib import Path
+
+from ghostbuster.core.models import Ghost, GhostCategory, Severity
+
+# Mapping from PyPI package names to their actual import names.
+# Many packages have different install names vs import names.
+PACKAGE_TO_IMPORT: dict[str, str | list[str]] = {
+    "pillow": "PIL",
+    "scikit-learn": "sklearn",
+    "scikit-image": "skimage",
+    "opencv-python": "cv2",
+    "opencv-python-headless": "cv2",
+    "python-dateutil": "dateutil",
+    "pyyaml": "yaml",
+    "beautifulsoup4": "bs4",
+    "python-dotenv": "dotenv",
+    "pymysql": "pymysql",
+    "attrs": "attr",
+    "google-cloud-storage": "google.cloud.storage",
+    "google-auth": "google.auth",
+    "python-jose": "jose",
+    "python-multipart": "multipart",
+    "ujson": "ujson",
+    "msgpack": "msgpack",
+    "setuptools": ["setuptools", "pkg_resources"],
+    "typing-extensions": "typing_extensions",
+    "importlib-metadata": "importlib_metadata",
+    "importlib-resources": "importlib_resources",
+}
+
+# Packages that are commonly used as CLI tools or plugins, not imported directly.
+# These should not be flagged as dead imports.
+TOOL_PACKAGES: set[str] = {
+    "pip",
+    "setuptools",
+    "wheel",
+    "build",
+    "twine",
+    "ruff",
+    "black",
+    "isort",
+    "flake8",
+    "mypy",
+    "pytest",
+    "pytest-cov",
+    "pytest-xdist",
+    "pytest-asyncio",
+    "pre-commit",
+    "tox",
+    "nox",
+    "sphinx",
+    "ipython",
+    "ipdb",
+    "debugpy",
+    "hatchling",
+    "hatch",
+    "poetry",
+    "flit",
+    "pdm",
+    "autopep8",
+    "pyright",
+    "pylint",
+    "bandit",
+    "safety",
+    "coverage",
+}
+
+
+class DeadImportScanner:
+    """Detects dependencies declared in config but never imported in code."""
+
+    name = "dead-import"
+
+    def scan(self, path: Path) -> list[Ghost]:
+        """Scan a project directory for dead imports."""
+        declared = self._find_declared_dependencies(path)
+        if not declared:
+            return []
+
+        imported = self._find_all_imports(path)
+        ghosts: list[Ghost] = []
+
+        for dep_name, source_file in declared:
+            normalized = self._normalize_package_name(dep_name)
+
+            # Skip known tool-only packages
+            if normalized in TOOL_PACKAGES:
+                continue
+
+            # Get possible import names for this package
+            import_names = self._get_import_names(normalized)
+
+            # Check if any of the possible import names are actually used
+            is_used = any(
+                self._import_matches(imp, name) for imp in imported for name in import_names
+            )
+
+            if not is_used:
+                ghosts.append(
+                    Ghost(
+                        category=GhostCategory.DEAD_IMPORT,
+                        name=dep_name,
+                        message=f"Package '{dep_name}' is declared in {source_file} but never imported",
+                        file_path=path / source_file,
+                        severity=Severity.MEDIUM,
+                        fixable=True,
+                        suggestion=f"Remove '{dep_name}' from {source_file}",
+                    )
+                )
+
+        return ghosts
+
+    def _normalize_package_name(self, name: str) -> str:
+        """Normalize a package name: lowercase, hyphens to underscores, strip extras."""
+        # Remove version specifiers and extras
+        name = re.split(r"[>=<!\[;]", name)[0].strip()
+        return name.lower().replace("-", "_")
+
+    def _get_import_names(self, normalized: str) -> list[str]:
+        """Get all possible import names for a normalized package name."""
+        # Check our known mapping
+        original = normalized.replace("_", "-")
+        if original in PACKAGE_TO_IMPORT:
+            mapping = PACKAGE_TO_IMPORT[original]
+            if isinstance(mapping, list):
+                return [m.lower().replace("-", "_") for m in mapping]
+            return [mapping.lower().replace("-", "_")]
+
+        if normalized in PACKAGE_TO_IMPORT:
+            mapping = PACKAGE_TO_IMPORT[normalized]
+            if isinstance(mapping, list):
+                return [m.lower().replace("-", "_") for m in mapping]
+            return [mapping.lower().replace("-", "_")]
+
+        # Default: the normalized name itself is the import name
+        return [normalized]
+
+    def _import_matches(self, imported: str, expected: str) -> bool:
+        """Check if an imported module matches an expected package name."""
+        imported_lower = imported.lower().replace("-", "_")
+        expected_lower = expected.lower().replace("-", "_")
+        # Exact match or sub-module import (e.g., "google.cloud.storage" matches "google")
+        return imported_lower == expected_lower or imported_lower.startswith(expected_lower + ".")
+
+    def _find_declared_dependencies(self, path: Path) -> list[tuple[str, str]]:
+        """Find all declared dependencies from project config files.
+
+        Returns list of (package_name, source_file) tuples.
+        """
+        deps: list[tuple[str, str]] = []
+
+        # Check requirements.txt
+        req_file = path / "requirements.txt"
+        if req_file.exists():
+            deps.extend(self._parse_requirements_txt(req_file))
+
+        # Check pyproject.toml
+        pyproject = path / "pyproject.toml"
+        if pyproject.exists():
+            deps.extend(self._parse_pyproject_toml(pyproject))
+
+        return deps
+
+    def _parse_requirements_txt(self, filepath: Path) -> list[tuple[str, str]]:
+        """Parse a requirements.txt file for package names."""
+        deps: list[tuple[str, str]] = []
+        try:
+            for line in filepath.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                # Skip comments, empty lines, and options
+                if not line or line.startswith("#") or line.startswith("-"):
+                    continue
+                # Extract package name (before any version specifier)
+                name = re.split(r"[>=<!\[;@]", line)[0].strip()
+                if name:
+                    deps.append((name, "requirements.txt"))
+        except OSError:
+            pass
+        return deps
+
+    def _parse_pyproject_toml(self, filepath: Path) -> list[tuple[str, str]]:
+        """Parse pyproject.toml for declared dependencies."""
+        deps: list[tuple[str, str]] = []
+        try:
+            if sys.version_info >= (3, 11):
+                import tomllib
+            else:
+                import tomli as tomllib  # type: ignore[no-redef]
+
+            data = tomllib.loads(filepath.read_text(encoding="utf-8"))
+            project_deps = data.get("project", {}).get("dependencies", [])
+            for dep in project_deps:
+                name = re.split(r"[>=<!\[;@]", dep)[0].strip()
+                if name:
+                    deps.append((name, "pyproject.toml"))
+
+            # Also check optional dependencies
+            optional = data.get("project", {}).get("optional-dependencies", {})
+            for group_name, group_deps in optional.items():
+                for dep in group_deps:
+                    name = re.split(r"[>=<!\[;@]", dep)[0].strip()
+                    if name:
+                        deps.append((name, f"pyproject.toml [optional: {group_name}]"))
+
+            # Support Poetry: [tool.poetry.dependencies]
+            poetry_deps = data.get("tool", {}).get("poetry", {}).get("dependencies", {})
+            if isinstance(poetry_deps, dict):
+                for dep_name in poetry_deps:
+                    if dep_name.lower() != "python":
+                        deps.append((dep_name, "pyproject.toml [poetry.dependencies]"))
+
+            # Support Poetry groups: [tool.poetry.group.<group>.dependencies]
+            poetry_groups = data.get("tool", {}).get("poetry", {}).get("group", {})
+            if isinstance(poetry_groups, dict):
+                for group_name, group_data in poetry_groups.items():
+                    if isinstance(group_data, dict):
+                        g_deps = group_data.get("dependencies", {})
+                        if isinstance(g_deps, dict):
+                            for dep_name in g_deps:
+                                if dep_name.lower() != "python":
+                                    deps.append(
+                                        (dep_name, f"pyproject.toml [poetry.group.{group_name}]")
+                                    )
+
+        except (OSError, Exception):
+            pass
+        return deps
+
+    def _find_all_imports(self, path: Path) -> set[str]:
+        """Walk all .py files and collect all imported module names via AST."""
+        imports: set[str] = set()
+        for py_file in path.rglob("*.py"):
+            # Skip common non-source directories
+            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))
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.Import):
+                        for alias in node.names:
+                            imports.add(alias.name)
+                    elif isinstance(node, ast.ImportFrom) and node.module:
+                        imports.add(node.module)
+            except (SyntaxError, OSError):
+                continue
+        return imports

ghostbuster/core/models.py

@@ -0,0 +1,140 @@
+"""Data models for ghost findings, scan results, and scoring."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class GhostCategory(str, enum.Enum):
+    """Categories of ghosts that can haunt a codebase."""
+
+    DEAD_IMPORT = "dead-import"
+    ORPHAN_FILE = "orphan-file"
+    ZOMBIE_CODE = "zombie-code"
+    PHANTOM_ENV = "phantom-env"
+
+    @property
+    def emoji(self) -> str:
+        """Return category tag for display."""
+        return ""
+
+    @property
+    def label(self) -> str:
+        """Return a human-readable label for each category."""
+        return {
+            GhostCategory.DEAD_IMPORT: "Dead Import",
+            GhostCategory.ORPHAN_FILE: "Orphan File",
+            GhostCategory.ZOMBIE_CODE: "Zombie Code",
+            GhostCategory.PHANTOM_ENV: "Phantom Env",
+        }[self]
+
+    @property
+    def description(self) -> str:
+        """Return a short description for each category."""
+        return {
+            GhostCategory.DEAD_IMPORT: "Dependency declared but never imported",
+            GhostCategory.ORPHAN_FILE: "File/folder that should be in .gitignore",
+            GhostCategory.ZOMBIE_CODE: "Function or class that is never called",
+            GhostCategory.PHANTOM_ENV: "Env var referenced but never set",
+        }[self]
+
+
+class Severity(str, enum.Enum):
+    """How severe this finding is."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+    @property
+    def emoji(self) -> str:
+        return ""
+
+
+@dataclass(frozen=True)
+class Ghost:
+    """A single ghost finding in the codebase.
+
+    This is the atomic unit of a scan result. Each ghost represents one
+    specific issue found (e.g., one unused import, one orphan file).
+    """
+
+    category: GhostCategory
+    name: str
+    message: str
+    file_path: Path | None = None
+    line_number: int | None = None
+    severity: Severity = Severity.MEDIUM
+    fixable: bool = False
+    suggestion: str = ""
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize to a JSON-compatible dictionary."""
+        return {
+            "category": self.category.value,
+            "name": self.name,
+            "message": self.message,
+            "file_path": str(self.file_path) if self.file_path else None,
+            "line_number": self.line_number,
+            "severity": self.severity.value,
+            "fixable": self.fixable,
+            "suggestion": self.suggestion,
+        }
+
+
+@dataclass
+class GhostScore:
+    """The overall 'hauntedness' score for a codebase.
+
+    Score ranges from 0 (clean) to 100 (extremely haunted).
+    """
+
+    value: int
+    label: str
+    breakdown: dict[GhostCategory, int] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize to a JSON-compatible dictionary."""
+        return {
+            "score": self.value,
+            "label": self.label,
+            "breakdown": {k.value: v for k, v in self.breakdown.items()},
+        }
+
+
+@dataclass
+class ScanResult:
+    """Complete result of a ghostbuster scan."""
+
+    ghosts: list[Ghost] = field(default_factory=list)
+    score: GhostScore | None = None
+    scanned_path: Path | None = None
+    duration_ms: float = 0.0
+
+    @property
+    def ghost_count(self) -> int:
+        return len(self.ghosts)
+
+    @property
+    def fixable_count(self) -> int:
+        return sum(1 for g in self.ghosts if g.fixable)
+
+    def ghosts_by_category(self) -> dict[GhostCategory, list[Ghost]]:
+        """Group ghosts by their category."""
+        result: dict[GhostCategory, list[Ghost]] = {}
+        for ghost in self.ghosts:
+            result.setdefault(ghost.category, []).append(ghost)
+        return result
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize to a JSON-compatible dictionary."""
+        return {
+            "ghosts": [g.to_dict() for g in self.ghosts],
+            "ghost_count": self.ghost_count,
+            "fixable_count": self.fixable_count,
+            "score": self.score.to_dict() if self.score else None,
+            "scanned_path": str(self.scanned_path) if self.scanned_path else None,
+            "duration_ms": round(self.duration_ms, 2),
+        }