# DebtMap — Technical Debt Intelligence

> Connect code quality to business impact. Only 7% of engineers use ANY tool for technical debt measurement. DebtMap is the tool for the other 93%.

## What It Does

DebtMap scans your codebase and produces actionable intelligence:

- **7 analyzers**: Complexity, coupling, duplication, dead code, test gaps, dependency age, documentation gaps
- **Business impact scoring**: Connects code issues to incidents, velocity, and dollar cost
- **ROI prioritization**: "Fix this module first — saves $X/month in engineering time"
- **Trend tracking**: Is your debt improving or degrading over time?
- **Executive reports**: Share with leadership in a format they understand

## Install

```bash
pip install autoai-debtmap
```

For MCP server support:
```bash
pip install 'autoai-debtmap[mcp]'
```

## CLI Usage

```bash
# Full scan
debtmap scan /path/to/repo

# Get prioritized fix list
debtmap prioritize /path/to/repo

# Generate executive report
debtmap report /path/to/repo

# Find worst hotspots
debtmap hotspots /path/to/repo

# Estimate $ cost of debt
debtmap cost /path/to/repo --hourly-rate 100 --team-size 8

# Track trends over time
debtmap trend /path/to/repo
```

## Quick Start -- MCP Server

Add to your Claude Code or Cursor MCP config:

```json
{
  "mcpServers": {
    "debtmap": {
      "command": "uvx",
      "args": ["autoai-debtmap-mcp"],
      "description": "DebtMap — Scan your codebase for technical debt with ROI-ranked fix lists"
    }
  }
}
```

That's it. No signup. No API key. No data leaves your machine.

### MCP Tools

| Tool | Description |
|------|-------------|
| `debt_scan` | Scan a codebase for technical debt |
| `debt_hotspots` | Find worst code hotspots |
| `debt_prioritize` | ROI-ranked fix list |
| `debt_cost` | Estimate $ cost of debt |
| `debt_trend` | Debt trend over time |
| `debt_report` | Executive-ready report |
| `debt_compare` | Compare branches/releases |

## Analyzers

### Cyclomatic Complexity
Parses Python AST to calculate real cyclomatic complexity. Counts `if`, `elif`, `for`, `while`, `except`, `with`, `and`, `or`, `assert`, ternary expressions, and comprehensions.

### Module Coupling
Builds an import dependency graph and calculates afferent/efferent coupling and instability metrics. Detects circular dependencies.

### Code Duplication
Uses content-hash fingerprinting with normalization (whitespace, string/number literals) to detect near-duplicate code blocks.

### Dead Code Detection
Identifies unused functions, unused imports, and unreachable code after return/raise/break/continue statements.

### Test Coverage Gaps
Cross-references source module public APIs with test files to find untested functions, classes, and methods.

### Dependency Age
Parses requirements.txt and pyproject.toml, queries PyPI for latest versions, and classifies outdatedness severity.

### Documentation Gaps
Finds public functions, classes, methods, and modules missing docstrings.

## License

Apache 2.0
