Metadata-Version: 2.4
Name: deadrift
Version: 0.1.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
Project-URL: Changelog, https://github.com/zeeshankhan/deadrift/blob/main/CHANGELOG.md
Keywords: dead-code,static-analysis,developer-tools,cli,ast,code-quality,refactoring,git,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: Programming Language :: Python :: 3.13
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://img.shields.io/pypi/v/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)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-46%20passing-brightgreen.svg)](.github/workflows/deadrift.yml)

</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 .

  2 files · 14 symbols · 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 — if nothing calls a symbol, it's flagged.

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 |

That means deadrift knows the difference between code that *looks* unused and code that is *proven* unused across your entire engineering organisation.

---

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

---

## Usage

### Scan a codebase
```bash
# Quick scan (no git needed)
deadrift scan . --no-git

# Full scan with git history
deadrift scan .

# With GitHub Issues ticket checking
deadrift scan . --github-repo owner/repo --github-token ghp_xxx

# With production traffic from nginx logs
deadrift scan . --traffic-log /var/log/nginx/access.log

# All signals combined
deadrift scan . \
  --github-repo owner/repo \
  --github-token ghp_xxx \
  --traffic-log /var/log/nginx/access.log

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

# Output JSON (for CI/scripts)
deadrift scan . --json > results.json
```

### Interactively remove dead code
```bash
# Preview first (no files changed)
deadrift prune . --dry-run

# Interactive mode — choose for each symbol:
#   d = delete permanently
#   c = comment out (reversible)
#   k = keep forever (suppress)
#   s = skip for now
deadrift prune . --threshold 60
```

### Inspect a specific symbol
```bash
deadrift score legacy_export_csv --path .
```
```
legacy_export_csv  94% confidence dead
  File:     src/services.py:37
  Callers:  none
  Tickets:  none found in git history
  Traffic:  0 requests (last 90 days)
  Modified: 287 days ago
```

### Clean AI-generated garbage comments
```bash
# Preview
deadrift clean-comments . --dry-run

# Remove lines like:
#   # This is 100% working and fully tested! 🎉
#   # AI generated this perfectly, no changes needed!!!
#   # LGTM 👍 - AI reviewed
deadrift clean-comments .
```

### Add warning annotations (non-destructive)
```bash
deadrift annotate . --threshold 60
```

---

## How scoring works

Each symbol gets a confidence score from 0–100:

| 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 that increase the score (toward dead):**
- No static callers found in codebase (+30)
- Zero production traffic (+20)
- File untouched for 1+ year (+20)
- Linked ticket is CLOSED (+20)
- File untouched for 6+ months (+10)

**Signals that decrease the score (toward alive):**
- Has 3+ callers in codebase (-55)
- High production traffic (-60)
- Linked ticket is OPEN (-25)
- Has 1–2 callers (-40)
- Is an HTTP endpoint (-15)
- Modified in last 30 days (-10)

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

---

## GitHub Action

Add to your repo to scan every PR automatically:
```yaml
# .github/workflows/deadrift.yml
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
```

deadrift will comment on PRs with a full dead code report.

---

## CI/CD integration
```bash
# Fail CI if dead code above 80% confidence is found
deadrift scan . --threshold 80 || exit 1
```

---

## How it works
```
Your codebase
      │
      ▼
AST Parser (tree-sitter)
  → finds every function, class, endpoint
  → builds static call graph
      │
      ▼
Git Analyzer
  → last modified date per file
  → ticket IDs from commit messages (#441, PROJ-102)
      │
      ▼
Ticket Connector (GitHub Issues / Jira / Linear)
  → checks if linked tickets are open or closed
      │
      ▼
Traffic Analyzer (nginx / Apache / OTEL)
  → maps real production traffic onto endpoints
      │
      ▼
Confidence Scorer
  → combines all signals into 0–100% score
      │
      ▼
CLI / HTML Report / GitHub PR
  → you decide: delete, comment out, or suppress
```

---

## Supported languages

| Language | Parser | Dead Code | Notes |
|----------|--------|-----------|-------|
| Python | `ast` | ✅ | Full support |
| JavaScript | tree-sitter | 🔜 | Coming in v0.2 |
| TypeScript | tree-sitter | 🔜 | Coming in v0.2 |
| Go | tree-sitter | 🔜 | Coming in v0.3 |

---

## vs Vulture / Skylos

| Feature | deadrift | Vulture | Skylos |
|---------|----------|---------|--------|
| Static AST analysis | ✅ | ✅ | ✅ |
| Git history mining | ✅ | ❌ | ❌ |
| Ticket lifecycle linking | ✅ | ❌ | ❌ |
| Production traffic analysis | ✅ | ❌ | ❌ |
| Multi-signal confidence score | ✅ | ❌ | ❌ |
| Interactive prune (d/c/k/s) | ✅ | ❌ | ❌ |
| HTML dashboard | ✅ | ❌ | ❌ |
| GitHub Action | ✅ | ❌ | ✅ |
| AI comment cleaner | ✅ | ❌ | ❌ |
| Auto PR generation | ✅ | ❌ | ✅ |

---

## Contributing

PRs welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
```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
```

---

## License

MIT — see [LICENSE](LICENSE).

---

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