Metadata-Version: 2.4
Name: debtpilot
Version: 0.5.0
Summary: Track technical debt before it blows up in production
License-Expression: MIT
Project-URL: Homepage, https://github.com/Bitxn/debtpilot
Project-URL: Issues, https://github.com/Bitxn/debtpilot/issues
Keywords: technical-debt,code-quality,developer-tools,cli,linting
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: oneport-account>=0.1.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: daemon
Requires-Dist: websockets>=12.0; extra == "daemon"
Requires-Dist: watchdog>=4.0; extra == "daemon"
Provides-Extra: notify
Requires-Dist: win10toast>=0.9; platform_system == "Windows" and extra == "notify"
Requires-Dist: plyer>=2.1; extra == "notify"
Provides-Extra: polyglot
Requires-Dist: tree-sitter>=0.21; extra == "polyglot"
Requires-Dist: tree-sitter-language-pack>=1.0; extra == "polyglot"
Provides-Extra: full
Requires-Dist: debtpilot[daemon,notify,polyglot]; extra == "full"
Dynamic: license-file

#  DebtPilot

> Track technical debt before it blows up in production.

Every IDE catches syntax errors. DebtPilot does something no IDE can —
it knows that `payments/stripe.js` has been edited 30 times by 4 different
developers, has a TODO from 8 months ago, and a complexity score of 24.
That combination is your next production incident.

---

## Install

pip install debtpilot

Full install (file watcher + live notifications):

pip install "debtpilot[full]"

---

## Quickstart — 4 commands, done

1. Scan your project
debtpilot scan .

2. See the report
debtpilot report

3. Block bad commits automatically
debtpilot hook --install

4. Start live background watching
debtpilot start --dir .

---

## What it does

| Command | What happens |
|---|---|
| `debtpilot scan .` | Scores every file 0-100 for technical debt |
| `debtpilot report` | Shows top debt files in a ranked table |
| `debtpilot file <path>` | Deep breakdown of one file |
| `debtpilot ai <path>` | AI explains exactly what to fix (needs Gemini key) |
| `debtpilot predict` | Predicts which file will cause your next bug |
| `debtpilot dashboard` | Generates an HTML dashboard — open in browser |
| `debtpilot report-pdf` | Generates a print-ready PDF report |
| `debtpilot alerts` | Shows active danger alerts |
| `debtpilot todos` | Lists stale TODOs by age |
| `debtpilot hook --install` | Blocks commits above the debt threshold |
| `debtpilot start` | Starts live file watcher + WebSocket server |
| `debtpilot status` | Full health check of your DebtPilot setup |
| `debtpilot digest --send` | Sends weekly email summary to your team |

---

## Debt Score (0-100)

| Grade | Score | Meaning |
|-------|-------|---------|
| A | 0-25 | Healthy |
| B | 26-45 | Watch |
| C | 46-65 | Concerning |
| D | 66-80 | Dangerous |
| F | 81-100 | Critical — fix before next deploy |

Score = weighted combination of: git churn (30%) + complexity (25%) +
lint issues (20%) + stale TODOs (15%) + staleness (10%).

Complexity is measured exactly for Python (AST) and estimated for other code
languages (JS/TS, Java, Go, Ruby, Rust, PHP, C/C++, C#, Kotlin, Swift…). A
language DebtPilot can't analyse is marked **unmeasured** and its weight is
redistributed — a file is never scored as "zero complexity = healthy" just
because we couldn't read it.

---

## Configuration & CI policy (`debtpilot.toml`)

Scaffold a per-repo policy and commit it:

```bash
debtpilot init-config
```

```toml
ignore = ["**/generated/**", "**/vendor/**"]   # top-level keys come first

[weights]                 # renormalised automatically
churn = 0.30
complexity = 0.25
lint = 0.20
todo = 0.15
staleness = 0.10

[thresholds]
alert = 65                # daemon alert level
fail  = 80                # `debtpilot cicd run` fails a file at/above this

[grades]                  # score <= value -> grade
A = 25
B = 45
C = 65
D = 80

[[waiver]]                # approved, time-boxed exceptions
path    = "legacy/importer.py"
reason  = "scheduled rewrite in Q3"
expires = "2026-12-31"    # after this, the gate fails again automatically
```

**CI gate** — fail on absolute debt, or ratchet so debt can't grow:

```bash
debtpilot cicd run --write-baseline          # record current scores
debtpilot cicd run --ratchet                 # fail if a file rose above baseline
debtpilot cicd run --fail-threshold 70       # or fail any file >= 70
debtpilot cicd run --sarif debt.sarif        # SARIF 2.1.0 for code scanning
```

Waived files stay in the report (marked, and *suppressed* in SARIF) but never
fail the gate.

---

## Where your data lives

Scan results are stored **per project**, in a `.debtpilot/` folder at your
project root (found the same way git finds its root). Two different projects
scanned on the same machine never share data. The folder self-ignores via its
own `.gitignore`, so you'll never accidentally commit your scan database.

Your global settings (Gemini API key, email digest config) live separately in
`~/.debtpilot/config.json` — those are per-user, not per-project.

---

## AI Fix Suggestions (optional)

0-BYOK — no API keys. The AI advisor runs on OnePort's managed models, metered
against your account. Get a token at https://www.oneport.co.in/console, then:

onp account login <op_live_...>
debtpilot ai src/payments.py

DebtPilot sends only the file context through the OnePort backend (metered to
your account) and gets back exact fix suggestions with code examples and effort
estimates. Static debt scoring works fully offline with no account.

---

## Weekly Email Digest

debtpilot config --gmail you@gmail.com --gmail-password YOUR_APP_PASS --recipients team@company.com
debtpilot digest --send

Use a Gmail App Password from: myaccount.google.com/apppasswords

---

## Auto-start on Windows login

debtpilot autostart --install --dir .

DebtPilot will start silently in the background every time Windows starts.
No manual debtpilot start needed.

---

## Requirements

- Python 3.10 or higher
- git in PATH
- pylint / mypy / eslint — optional, for richer lint scores

---

## License

MIT
