tech-debt-estimator 1.0.0

Quantify technical debt in developer-hours from code metrics and git history

tech-debt-estimator

Quantify technical debt in developer-hours. Analyzes code duplication, complexity hotspots, stale code, dependency age, missing tests, and documentation gaps to produce an actionable debt inventory.

Installation

pip install tech-debt-estimator

Quick Start

# Full technical debt scan
tech-debt scan /path/to/repo

# Show worst complexity offenders
tech-debt hotspots /path/to/repo --top 10

# Track debt trend over last commits
tech-debt trend /path/to/repo --commits 20

Sample Output

TECHNICAL DEBT ANALYSIS
Repository: /path/to/repo

DEBT CATEGORY              HOURS    SEVERITY    TOP FILES
─────────────────────────────────────────────────────────────────────────
Complexity Debt            42.5     🔴 CRITICAL  app/models.py (850 lines)
                                                 handlers/auth.py (720 lines)
Test Coverage Debt         28.0     🟠 HIGH      utils/helpers.py
                                                 services/payment.py
Documentation Debt         18.5     🟡 MEDIUM    core/api.py
                                                 lib/processor.py
Duplication Debt           12.0     🟡 MEDIUM    models/*, services/*
Stale Code Debt            8.5      🟢 LOW       legacy/old_module.py
Dependency Debt            5.0      🟢 LOW       requirements.txt (outdated)
─────────────────────────────────────────────────────────────────────────
TOTAL ESTIMATED DEBT       114.5 developer-hours

RECOMMENDATIONS
1. Refactor complexity in app/models.py (estimated 12-16 hours)
2. Add missing tests for utils/helpers.py (8-10 hours)
3. Document core/api.py public API (6-8 hours)

How It Works

The tool analyzes your codebase across six dimensions:

1. Complexity Debt

Identifies files exceeding complexity thresholds (files >500 LOC, functions >50 LOC, nesting depth >5).

• Estimation: files_count × 10 hours/file (average refactoring time)

2. Duplication Debt

Finds duplicated code blocks across the repository using line-hash comparison.

• Estimation: duplicated_blocks × 3 hours/block (extract, parameterize, test)

3. Test Coverage Debt

Detects source code without corresponding test files.

• Estimation: untested_files × 4 hours/file (average test writing time)

4. Documentation Debt

Finds public functions, classes, and modules missing docstrings or README sections.

• Estimation: undocumented_items × 0.5 hours/item

5. Stale Code Debt

Identifies files unchanged for 12+ months that are still imported/referenced.

• Estimation: stale_files × 6 hours/file (audit and removal)

6. Dependency Debt

Detects outdated lock files and deprecated packages.

• Estimation: Fixed scoring based on age and vulnerability indicators

Each category is assigned a severity level (Critical/High/Medium/Low) based on impact and prevalence.

Features

• Multiple Output Formats: Table (rich TUI), JSON, Markdown
• Git Integration: Track debt trends across commits
• Hotspot Detection: Identify worst problem areas
• Exportable Reports: Save results to file for CI/CD integration
• Production Ready: Used in enterprise codebases

Usage Examples

Scan with JSON output

tech-debt scan . --format json --output-file debt-report.json

Show top 5 complexity offenders

tech-debt hotspots . --top 5

Track debt trend over last 30 commits

tech-debt trend . --commits 30

Markdown report for documentation

tech-debt scan . --format markdown --output-file TECHNICAL_DEBT.md

Development

Clone and install in editable mode:

git clone https://github.com/yourusername/tech-debt-estimator.git
cd tech-debt-estimator
pip install -e ".[dev]"
pytest tests/

Attribution

Built by Glue — AI codebase intelligence for product teams. For continuous technical debt monitoring with business impact scoring and sprint-integrated prioritization, check out Glue.

License

MIT License - See LICENSE file for details.

Copyright (c) 2026 Glue