Metadata-Version: 2.4
Name: autoai-debtmap
Version: 0.1.0
Summary: Technical Debt Intelligence — connect code quality to business impact
Author-email: AutoAI Labs <info@autoailabs.co.uk>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: code-quality,mcp,static-analysis,technical-debt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# 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
