ghostbuster-cli 0.1.0__tar.gz

ghostbuster_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+
+      - name: Ruff check
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Mypy type check
+        run: |
+          pip install -e ".[dev]" 2>/dev/null || pip install -e .
+          mypy src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest]
+        include:
+          - python-version: "3.12"
+            os: macos-latest
+          - python-version: "3.12"
+            os: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+  build:
+    name: Build check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Uncomment when ready to publish to PyPI
+  # publish:
+  #   name: Publish to PyPI
+  #   needs: [lint, test, build]
+  #   runs-on: ubuntu-latest
+  #   if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+  #   environment: pypi
+  #   permissions:
+  #     id-token: write  # Required for trusted publishing
+  #   steps:
+  #     - uses: actions/download-artifact@v4
+  #       with:
+  #         name: dist
+  #         path: dist/
+  #     - name: Publish to PyPI
+  #       uses: pypa/gh-action-pypi-publish@release/v1

ghostbuster_cli-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Environment
+.env
+.env.local

ghostbuster_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-29
+
+### Added
+
+- `ghostbuster scan` command with 4 built-in scanners
+- **Dead Import Scanner** - detects dependencies declared but never imported
+- **Orphan File Scanner** - finds files/dirs that should be in .gitignore
+- **Zombie Code Scanner** - detects functions/classes that are never called
+- **Phantom Env Scanner** - finds env vars referenced but not set
+- `ghostbuster bust` command with dry-run (default) and --confirm modes
+- **Ghost Score** - weighted 0-100 technical debt score
+- Formatted terminal output with tables, progress bars, and score cards
+- JSON and Markdown output formats (`--format json|markdown`)
+- Configuration via `.ghostbuster.toml` or `pyproject.toml [tool.ghostbuster]`
+- Full test suite with pytest
+- GitHub Actions CI (lint, test, build)

ghostbuster_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing to Ghostbuster
+
+First off, thank you for considering contributing to Ghostbuster!
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Quick Start
+
+```bash
+# Clone the repo
+git clone https://github.com/adewanggar/ghostbuster-cli.git
+cd ghostbuster-cli
+
+# Create virtual environment & install in development mode
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e ".[dev]" 2>/dev/null || pip install -e .
+pip install pytest ruff mypy
+
+# Run the tool locally
+ghostbuster scan .
+
+# Run tests
+pytest tests/ -v
+
+# Run linter
+ruff check src/ tests/
+
+# Run type checker
+mypy src/
+```
+
+## Making Changes
+
+### Code Style
+
+- We use **Ruff** for linting and formatting.
+- All code must have **type hints**.
+- Follow the existing code patterns - especially the core/CLI separation.
+
+### Architecture Rules
+
+1. **`core/`** must NOT import from `cli/`, `rich`, or any UI library.
+2. **`cli/`** is the only layer that touches terminal I/O.
+3. Each scanner is a self-contained module implementing the `Scanner` protocol.
+4. All new scanners must be registered in `scanner.py:create_default_orchestrator()`.
+
+### Adding a New Scanner
+
+1. Create `src/ghostbuster/core/my_scanner.py`
+2. Implement the `Scanner` protocol (must have `name: str` and `scan(path) -> list[Ghost]`)
+3. Register in `create_default_orchestrator()`
+4. Add tests in `tests/test_my_scanner.py`
+5. Update the README feature list
+
+### Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_dead_imports.py -v
+
+# Run with coverage
+pip install pytest-cov
+pytest tests/ --cov=ghostbuster --cov-report=html
+```
+
+### Commit Messages
+
+Use conventional commit messages:
+
+```
+feat: add Node.js dependency scanner
+fix: handle missing pyproject.toml gracefully
+docs: update README with new scanner info
+test: add edge case for empty requirements.txt
+chore: bump ruff version
+```
+
+## Pull Request Process
+
+1. Fork the repo and create a feature branch from `main`.
+2. Make your changes with tests.
+3. Ensure all checks pass: `ruff check`, `mypy`, `pytest`.
+4. Open a PR with a clear description of what you changed and why.
+5. Wait for review - we aim to respond within 48 hours.
+
+## Reporting Bugs
+
+Open an issue with:
+- Your OS and Python version
+- The command you ran
+- Expected vs actual behavior
+- Minimal reproducible example (if possible)
+
+## Feature Requests
+
+Open an issue with:
+- What problem does it solve?
+- Who would use it?
+- Any implementation ideas?
+
+## Code of Conduct
+
+Be kind, be constructive, and respect other contributors.

ghostbuster_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ghostbuster Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghostbuster_cli-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: ghostbuster-cli
+Version: 0.1.0
+Summary: Find and bust the ghosts haunting your codebase - unused deps, dead code, orphan files, and phantom env vars.
+Project-URL: Homepage, https://github.com/adewanggar/ghostbuster-cli
+Project-URL: Documentation, https://github.com/adewanggar/ghostbuster-cli#readme
+Project-URL: Repository, https://github.com/adewanggar/ghostbuster-cli
+Project-URL: Issues, https://github.com/adewanggar/ghostbuster-cli/issues
+Project-URL: Changelog, https://github.com/adewanggar/ghostbuster-cli/blob/main/CHANGELOG.md
+Author: Ghostbuster Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,code-quality,dead-code,developer-tools,devtools,linter,unused-dependencies
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/readme_header.png" alt="Ghostbuster Header" width="100%" />
+
+# Ghostbuster
+
+**Find and bust the ghosts haunting your codebase.**
+
+[![PyPI version](https://img.shields.io/pypi/v/ghostbuster-cli?color=blue&label=PyPI)](https://pypi.org/project/ghostbuster-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/ghostbuster-cli)](https://pypi.org/project/ghostbuster-cli/)
+[![CI](https://github.com/adewanggar/ghostbuster-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/adewanggar/ghostbuster-cli/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://img.shields.io/pypi/dm/ghostbuster-cli)](https://pypi.org/project/ghostbuster-cli/)
+
+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.**
+
+</div>
+
+---
+
+## <img src="assets/terminal_icon.png" width="24" height="24" valign="middle" /> Quick Start
+
+```bash
+# Install
+pip install ghostbuster-cli
+
+# Scan your project
+ghostbuster scan
+
+# No config needed.
+```
+
+## What It Finds
+
+Ghostbuster detects **4 categories** in your codebase:
+
+| Category | Identifier | What It Detects |
+|:---------|:-----------|:----------------|
+| **Dead Import** | `dead-import` | Dependencies in `requirements.txt` / `pyproject.toml` that are never imported |
+| **Orphan File** | `orphan-file` | `node_modules/`, `venv/`, `.pyc`, large files that should be in `.gitignore` |
+| **Zombie Code** | `zombie-code` | Functions and classes that are defined but never called from anywhere |
+| **Phantom Env** | `phantom-env` | `os.environ["KEY"]` / `os.getenv("KEY")` where KEY is never set |
+
+## 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:
+
+```bash
+# Preview what would be fixed (safe, default)
+ghostbuster bust
+
+# Actually apply fixes
+ghostbuster bust --confirm
+```
+
+Currently auto-fixes:
+- Removes unused import statements
+- Suggests `.gitignore` additions for orphan files
+- Suggests `.env` additions for phantom env vars
+
+## Usage
+
+### Basic Scan
+
+```bash
+# 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
+
+```bash
+# Only check for dead imports
+ghostbuster scan --category dead-import
+
+# Only check for zombie code
+ghostbuster scan -c zombie-code
+```
+
+### Output Formats
+
+```bash
+# 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
+```
+
+### CI Integration
+
+```yaml
+# .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`
+
+```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`
+
+```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
+
+| Tool | Scope | Ghostbuster Advantage |
+|:-----|:------|:----------------------|
+| [Vulture](https://github.com/jendrikseipp/vulture) | Dead code only | Ghostbuster also covers dependencies, files, and env vars |
+| [deptry](https://deptry.com/) | Unused deps only | Ghostbuster is a superset with unified output |
+| [deadcode](https://github.com/albertas/deadcode) | Dead code only | Ghostbuster adds auto-fix and unified scoring |
+| [git-sizer](https://github.com/github/git-sizer) | Repo size | Ghostbuster checks .gitignore coverage |
+
+## Roadmap
+
+- <img src="assets/npm_package_icon.png" width="18" height="18" valign="middle" /> 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](CONTRIBUTING.md) for guidelines.
+
+```bash
+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
+
+---
+
+<div align="center">
+
+[Report Bug](https://github.com/adewanggar/ghostbuster-cli/issues) | [Request Feature](https://github.com/adewanggar/ghostbuster-cli/issues) | [Changelog](CHANGELOG.md)
+
+</div>