ghostbuster-cli 0.1.0__py3-none-any.whl

ghostbuster_cli-0.1.0.dist-info/METADATA

@@ -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>

ghostbuster_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+ghostbuster/__init__.py,sha256=DjoP35psoqdgS63xrsEHDnTZH86WuMfkESRWdSm5VJI,94
+ghostbuster/__main__.py,sha256=lNt1TC6uQmJeWfsEjeVSdtWp3zXGPgvepc6GCdm_NPk,112
+ghostbuster/config.py,sha256=eTp21FTGQa4UdDEe7rgj3P9y1EbJWQtoZKk9U2NDVZM,3516
+ghostbuster/cli/__init__.py,sha256=Q4QzQCH5WEZ8gs4WSAwPLLChXkW6srvGr2DNM-sw8kE,58
+ghostbuster/cli/app.py,sha256=nWUVYXBfmRiDhb4k7y9KA1H5qgAYWwyd6PGluT_jG2E,2018
+ghostbuster/cli/bust.py,sha256=sc7aBE0uMEvhrKHWIcDQVr-QRzoS4guIK4gcw-jZhO8,3484
+ghostbuster/cli/display.py,sha256=9P8CRKFhcgGtzjU-Gr-kQc8VxiEtlLNIzYwgs0WIJD8,8459
+ghostbuster/cli/scan.py,sha256=f06buxk6Z_c3CBIq35Z4fXsANwVxD_ecxCnCNpXwUvM,3885
+ghostbuster/core/__init__.py,sha256=mCcFCQAs6q5Qch1yffLAK38YcFn0NmpRdc-e8F6_vcw,68
+ghostbuster/core/dead_imports.py,sha256=KqL5e2VZYpG8tXKf0p-9Rgznsmh3H3al9iQOSicfYww,10024
+ghostbuster/core/models.py,sha256=lVsFcJo6hpK1Nlf7VGCrkhvGU4f-GXWoIBhK4Jj-0ps,4191
+ghostbuster/core/orphan_files.py,sha256=Pwl5Dh8W86F9HK3NuHDljUosVk8Up80rT0QZc4jAxhs,10691
+ghostbuster/core/phantom_env.py,sha256=8avf6nGRU6YoasgAq1Eew4SSSW91nB6eOVF6K-3Hpe0,6690
+ghostbuster/core/scanner.py,sha256=kXEPUPPXnlOMBtCAhwzWU6-Dd7xgRxMKd-4H4OqNVNY,3640
+ghostbuster/core/scoring.py,sha256=80XJC2OBWMrRQNsgwGkvJncGjNLdCkKMXvaoVNvFIMU,2836
+ghostbuster/core/zombie_code.py,sha256=b8mkq5e7VbWb-iPgqfP3NoaVGykt2KvuZCm4sh2cI7Y,10080
+ghostbuster/fixers/__init__.py,sha256=NM1-7IPmSGoBlp7Qo-XFufOA3jF0QbzQxjvrUFDvvZY,53
+ghostbuster/fixers/import_fixer.py,sha256=BpY1skPxIVhpEKgBcol5K3tY90YsvKx7o7DJcOckZmc,5386
+ghostbuster_cli-0.1.0.dist-info/METADATA,sha256=pQiSi1plgRspjDPM3bV8FJMJ5XyoYlc4Ihn6VRZc-r8,8173
+ghostbuster_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+ghostbuster_cli-0.1.0.dist-info/entry_points.txt,sha256=WbdyzM-b1ECGON6TXnuVe5LgF4EmL_fN5Pkq95L4oOw,56
+ghostbuster_cli-0.1.0.dist-info/licenses/LICENSE,sha256=lGYPL1xowMCD0T-_FgH3xW-_6F6tfpUfVpPXqxFIU3Y,1081
+ghostbuster_cli-0.1.0.dist-info/RECORD,,

ghostbuster_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ghostbuster_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ghostbuster = ghostbuster.cli.app:app

ghostbuster_cli-0.1.0.dist-info/licenses/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.