Ghostbuster

Find and bust the ghosts haunting your codebase.

Unused dependencies, dead functions, orphan files, and phantom environment variables lurk in codebases - slowing down repos, confusing new contributors, and wasting CI minutes.

Ghostbuster finds them all in one command.

Quick Start

# Install
pip install ghostbuster-cli

# Scan your project
ghostbuster scan

# No config needed.

What It Finds

Ghostbuster detects 4 categories in your codebase:

Ghost Score

Every scan produces a Ghost Score (0-100) - the higher the score, the more technical debt in your codebase:

+----------------------- Ghost Score ------------------------+
|                                                            |
|    47 / 100                                                |
|                                                            |
|    #########################--------------------------     |
|                                                            |
|    Noticeable technical debt detected.                     |
|                                                            |
+------------------------------------------------------------+

Auto-Fix

Ghostbuster can also fix detected issues:

# Preview what would be fixed (safe, default)
ghostbuster bust

# Actually apply fixes
ghostbuster bust --confirm

Currently auto-fixes:

• Removes unused import statements from Python files
• Appends missing orphan files and directories to .gitignore
• Appends missing environment variable stubs (KEY=) to .env.example

Usage

Basic Scan

# Scan current directory
ghostbuster scan

# Scan a specific path
ghostbuster scan ./my-project

# Verbose mode (show locations and fix suggestions)
ghostbuster scan -v

Filtered Scan

# Only check for dead imports
ghostbuster scan --category dead-import

# Only check for zombie code
ghostbuster scan -c zombie-code

Output Formats

# Default: formatted terminal output
ghostbuster scan

# JSON (for CI pipelines and scripting)
ghostbuster scan --format json

# Markdown (for pasting into issues/PRs)
ghostbuster scan --format markdown

Pre-commit Hook Integration

Add Ghostbuster to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/adewanggar/ghostbuster-cli
    rev: v0.2.0
    hooks:
      - id: ghostbuster-scan

CI Integration

# .github/workflows/ghostbuster.yml
name: Ghost Check
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install ghostbuster-cli
      - run: ghostbuster scan --format json

Note: ghostbuster scan exits with code 1 if issues are found - ideal for CI gates.

Configuration

Ghostbuster works with zero config, but you can customize it:

pyproject.toml

[tool.ghostbuster]
exclude_dirs = ["migrations", "generated"]
ignore_packages = ["my-internal-lib"]
ignore_env_vars = ["CI", "GITHUB_ACTIONS"]
ignore_names = ["deprecated_helper"]
large_file_threshold = 5242880  # 5MB

.ghostbuster.toml

exclude_dirs = ["vendor", "third_party"]
categories = ["dead-import", "phantom-env"]  # Only run these scanners

How It Works

Ghostbuster uses pure AST analysis - no runtime imports, no code execution, no external services:

1. Dead Imports: Parses requirements.txt/pyproject.toml for declared dependencies, walks AST for imports, cross-references with a package-to-import mapping table.
2. Orphan Files: Walks the file tree checking for known ignorable patterns (node_modules/, venv/, __pycache__/, large binary files) and verifies they are covered by .gitignore.
3. Zombie Code: Collects all function/class definitions and references across the codebase, identifying definitions with zero references (skipping __init__, test_*, and decorated functions).
4. Phantom Env: Detects os.environ["KEY"], os.environ.get("KEY"), os.getenv("KEY") patterns via AST and checks against .env files and system environment.

Alternatives

Roadmap

• Node.js / TypeScript support (scan package.json, dead exports)
• Pre-commit hook integration
• GitHub Actions reporter (comment Ghost Score on PRs)
• Config inheritance for monorepos
• Ghost Score history tracking & trend chart

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

git clone https://github.com/adewanggar/ghostbuster-cli.git
cd ghostbuster-cli
pip install -e .
pip install pytest ruff mypy
pytest tests/ -v

License

MIT (c) Ghostbuster Contributors