Metadata-Version: 2.4
Name: deadrift
Version: 0.2.0
Summary: Find every piece of code your team is afraid to delete — and prove it's safe.
Author-email: Zeeshan Khan <zeeshankhan@example.com>
License: MIT
Project-URL: Homepage, https://github.com/zeeshankhan/deadrift
Project-URL: Repository, https://github.com/zeeshankhan/deadrift
Project-URL: Issues, https://github.com/zeeshankhan/deadrift/issues
Keywords: dead-code,static-analysis,developer-tools,cli,ast,code-quality,technical-debt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: gitpython>=3.1.40
Requires-Dist: networkx>=3.2.1
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Dynamic: license-file

<div align="center">

# 💀 deadrift

**Find every piece of code your team is afraid to delete — and prove it's safe.**

[![PyPI version](https://badge.fury.io/py/deadrift.svg)](https://pypi.org/project/deadrift/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/zeeshankhan/deadrift/blob/main/LICENSE)
[![Tests](https://img.shields.io/badge/tests-46%20passing-brightgreen.svg)](https://github.com/zeeshankhan/deadrift/actions)

</div>

---

Every codebase has a graveyard.

Functions built for tickets that were closed 8 months ago. Classes from a migration that completed last year. Endpoints with zero traffic since v1.2. **Nobody deletes them because nobody can prove they're safe to delete.**

deadrift fixes that. It combines static analysis, git history, ticket status, and production traffic into a single confidence score — and tells you exactly what's safe to remove.
```
deadrift scan .

  14 symbols scanned · 11 flagged

  ╭──────┬───────┬──────────────────────────┬─────────────┬──────────────────────────╮
  │ Risk │ Score │ Symbol                   │ File        │ Signals                  │
  ├──────┼───────┼──────────────────────────┼─────────────┼──────────────────────────┤
  │ HIGH │  94%  │ legacy_export_csv        │ services.py │ no callers, ticket closed│
  │ HIGH │  91%  │ LegacyBillingService     │ services.py │ no callers, untouched 8m │
  │ MED  │  73%  │ send_sms_notification    │ services.py │ no callers, no ticket    │
  ╰──────┴───────┴──────────────────────────┴─────────────┴──────────────────────────╯
```

---

## What makes deadrift different

Every existing dead code tool runs static analysis only.

deadrift combines **three independent signals** into one confidence score:

| Signal | What it checks | Tools today |
|--------|---------------|-------------|
| Static call graph | Does any code call this? | ✅ Everyone |
| Git history + ticket refs | Does a living ticket justify this code? | ❌ Nobody |
| Production traffic | Is this endpoint actually receiving requests? | ❌ Nobody |

---

## Install
```bash
pip install deadrift
# or
pipx install deadrift
```

---

## Quick start
```bash
# Scan any Python project
deadrift scan .

# Interactive dead code removal
deadrift prune . --threshold 60

# Generate HTML dashboard
deadrift scan . --html && open deadrift-report.html

# Clean AI-generated garbage comments
deadrift clean-comments .
```

---

## Full command reference

### `deadrift scan` — find dead code
```bash
deadrift scan .                          # scan with git history
deadrift scan . --no-git                 # skip git (faster)
deadrift scan . --threshold 60           # only show 60%+ confidence
deadrift scan . --html                   # generate HTML dashboard
deadrift scan . --json > results.json    # JSON output for CI

# With all signals
deadrift scan . \
  --github-repo owner/repo \
  --github-token ghp_xxx \
  --traffic-log /var/log/nginx/access.log
```

### `deadrift prune` — interactively remove dead code
```bash
deadrift prune . --dry-run               # preview only
deadrift prune . --threshold 60          # interactive: d/c/k/s per symbol
```
For each symbol you choose:
- `d` — delete permanently
- `c` — comment out (reversible)
- `k` — keep forever (adds `# deadrift: keep`)
- `s` — skip for now

### `deadrift score` — inspect one symbol
```bash
deadrift score legacy_export_csv --path .
```

### `deadrift annotate` — add warning comments (non-destructive)
```bash
deadrift annotate . --threshold 60 --dry-run
deadrift annotate . --threshold 60
```

### `deadrift clean-comments` — remove AI garbage comments
```bash
deadrift clean-comments . --dry-run
deadrift clean-comments .
```
Removes lines like:
- `# This is 100% working and fully tested! 🎉`
- `# AI generated this perfectly, no changes needed!!!`
- `# LGTM 👍 - AI reviewed`

---

## Suppression

Add `# deadrift: keep` above any `def` or `class` to suppress it forever:
```python
# deadrift: keep
def emergency_payment_fallback(amount: float) -> bool:
    """Disaster recovery — rarely called but critical."""
    return True
```

---

## GitHub Action
```yaml
name: deadrift
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install deadrift
      - run: deadrift scan . --threshold 60
```

---

## How scoring works

| Score | Label | Meaning |
|-------|-------|---------|
| 80–100% | HIGH | Almost certainly safe to delete |
| 60–79% | MEDIUM | Probably safe — review recommended |
| 30–59% | LOW | Suspicious — check manually |
| 0–29% | SAFE | Likely alive — leave it |

**Signals toward dead:** no callers (+30), zero traffic (+20), untouched 1yr (+20), ticket closed (+20)

**Signals toward alive:** high traffic (-60), 3+ callers (-55), 1-2 callers (-40), ticket open (-25)

---

## vs Vulture / Skylos

| Feature | deadrift | Vulture | Skylos |
|---------|----------|---------|--------|
| Static AST | ✅ | ✅ | ✅ |
| Git history mining | ✅ | ❌ | ❌ |
| Ticket linking | ✅ | ❌ | ❌ |
| Production traffic | ✅ | ❌ | ❌ |
| Multi-signal score | ✅ | ❌ | ❌ |
| Interactive prune | ✅ | ❌ | ❌ |
| HTML dashboard | ✅ | ❌ | ❌ |
| AI comment cleaner | ✅ | ❌ | ❌ |
| GitHub Action | ✅ | ❌ | ✅ |

---

## Contributing
```bash
git clone https://github.com/zeeshankhan/deadrift
cd deadrift
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```

PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## License

MIT © Zeeshan Khan — see [LICENSE](LICENSE).

---

<div align="center">
Built with frustration by a developer who was scared to delete code.<br>
<strong>If deadrift helped you, ⭐ the repo.</strong>
</div>
