debt-pulse

Your codebase's credit score. Track tech debt, not just TODOs.

debt-pulse scans for TODO/FIXME/HACK markers, calculates cyclomatic complexity, ages each item via git blame, and produces a single health score (0-100) with trend tracking. Like a credit score, but for your code.

Why debt-pulse?

TODOs pile up. Nobody tracks them. Six months later you have 400 FIXMEs from people who left the company, functions with cyclomatic complexity of 47, and no idea if things are getting better or worse.

debt-pulse gives you:

• A single score (0-100) with letter grade
• Aging via git blame (know WHO wrote it and WHEN)
• Trend tracking in SQLite (is debt growing or shrinking?)
• Complexity analysis per function
• CI integration (fail builds if score drops below threshold)

Install

pip install debt-pulse

Quick Start

# Scan and show score
debt-pulse scan .

# Track score over time
debt-pulse scan . --track

# View trend
debt-pulse trend

# Show worst offenders
debt-pulse worst . --limit 20

# CI gate: fail if score < 60
debt-pulse score . --min-score 60

# Generate HTML report with Chart.js trend graph
debt-pulse report . --format html -o report.html --track

Score breakdown

Factor	Weight	What it measures
Density	40%	Debt items per 1000 lines of code
Age	20%	Average age of debt markers
Priority	20%	Ratio of FIXME/HACK/BUG (high priority)
Complexity	20%	Average cyclomatic complexity

90-100: A (Excellent)    60-79: C (Needs work)
80-89:  B (Good)         40-59: D (Concerning)
                          0-39: F (Critical)

Detected markers

Marker	Priority	Meaning
FIXME	High	Known bug, needs fixing
HACK	High	Ugly workaround
BUG	High	Known defect
XXX	High	Danger zone
TODO	Normal	Planned work
TEMP	Normal	Temporary code
WORKAROUND	Normal	Intentional workaround
REFACTOR	Normal	Needs cleanup
OPTIMIZE	Low	Performance opportunity

Reports

• terminal -- Rich table with score bar chart
• json -- Machine-readable for CI pipelines
• markdown -- With shields.io badge for READMEs
• html -- Full dashboard with Chart.js trend graph

CI Integration

# GitHub Actions
- name: Debt check
  run: |
    pip install debt-pulse
    debt-pulse score . --min-score 60

Exit code 1 if score is below the threshold.

License

MIT