# Debtmap

> Debtmap is a code complexity and technical debt analyzer for Rust, Python, JavaScript, and TypeScript codebases. It identifies complexity patterns, coverage gaps, coupling, purity issues, architectural hotspots, and other debt signals, then outputs prioritized recommendations with context for human or AI-assisted remediation.

Debtmap uses unified priority scoring with severity bands:

- Critical: score >= 100
- High: score >= 50
- Medium: score >= 20
- Low: score < 20

Scores combine complexity, coverage, dependency/call graph impact, purity, entropy, file context, and optional git-history risk signals. Coverage data dampens well-tested code and surfaces untested complex functions.

## Quick Start

Generate coverage and run analysis with markdown output optimized for LLM consumption:

```bash
cargo llvm-cov --lcov --output-path lcov.info
debtmap analyze . --lcov lcov.info --context --format markdown --top 5
```

For analysis without coverage data:

```bash
debtmap analyze . --format markdown --top 5
```

Analyze specific languages:

```bash
debtmap analyze . --languages rust,python,javascript,typescript
```

## Commands

- [analyze](book/src/cli-reference.md): Primary analysis command with complexity metrics, debt detection, dependency context, and prioritized recommendations
- [validate](book/src/validation-gates.md): CI/CD threshold enforcement, returns non-zero exit code when configured thresholds are exceeded
- [compare](book/src/compare-analysis.md): Compare before/after JSON snapshots to track debt improvements or regressions
- `validate-improvement`: Validate that comparison results meet an improvement threshold
- `diagnose-coverage`: Diagnose and validate LCOV coverage files
- `explain-coverage`: Explain how coverage was matched for a specific function
- [init](book/src/cli-reference.md): Create `.debtmap.toml` configuration file

## Key Options for AI Workflows

The `analyze` command supports these options for LLM integration:

- `--format markdown`: Structured report with prioritized items and context suggestions
- `--format json`: Unified machine-readable output for programmatic pipelines
- `--lcov <FILE>` / `--coverage-file <FILE>`: LCOV coverage file for risk-aware prioritization
- `--context`: Enable context-aware risk analysis
- `--context-providers critical_path,dependency,git_history`: Choose context providers
- `--show-dependencies`: Include callers and callees in output
- `--top N` / `--tail N`: Limit to highest or lowest priority items
- `--min-priority <TIER>`: Filter by priority tier (`critical`, `high`, `medium`, `low`)
- `--min-score <SCORE>`: Filter lower-scoring T3/T4 recommendations
- `--filter <CATEGORY>`: Filter by debt categories
- `--summary`: Compact health dashboard view
- `--plain`: ASCII-only output for automation

## Output Formats

- `terminal` (default): Interactive TUI/human-oriented terminal output
- `markdown`: LLM-friendly and documentation-friendly report
- `json`: Unified JSON schema for tools, CI, and dashboards
- `dot`: Graphviz dependency visualization

## Supported Languages

- **Rust**: Syn-based AST analysis, macro-aware parsing, trait/call graph analysis, purity, error handling, resource, and architectural debt detection
- **Python**: Tree-sitter analysis for functions, classes, decorators, comprehensions, purity, entropy, and Python-specific complexity patterns
- **JavaScript**: Tree-sitter analysis for ES modules, React/JSX patterns, callbacks, promises, async workflows, and frontend/server code
- **TypeScript**: Tree-sitter TS/TSX analysis, type-oriented patterns, async workflows, and modern frontend/server syntax

## Debt Categories

- **Code Quality**: Complexity hotspots, dead code, magic values, high nesting, long functions
- **Testing**: Coverage gaps, complex tests, assertion quality, flaky/timing patterns
- **Architecture**: God objects, large files, feature envy, coupling, cohesion, scattered responsibilities
- **Resource and Error Handling**: Panic patterns, swallowed errors, async error issues, blocking I/O, resource lifecycle risks
- **Duplication and Organization**: Duplicate logic, module split opportunities, boilerplate, semantic naming issues

## Optional Workflows

Fix top priority item with coverage:

```bash
cargo llvm-cov --lcov --output-path lcov.info
debtmap analyze . --lcov lcov.info --context --format markdown --top 1
# Fix the identified issue
debtmap analyze . --lcov lcov.info --format markdown --top 1
```

Track improvements over time:

```bash
debtmap analyze . --format json --output before.json
# Make changes
debtmap analyze . --format json --output after.json
debtmap compare --before before.json --after after.json --format json --output comparison.json
debtmap validate-improvement --comparison comparison.json
```

CI/CD validation:

```bash
debtmap validate . --config .debtmap.toml
```

Coverage debugging:

```bash
debtmap diagnose-coverage lcov.info
debtmap explain-coverage . --lcov lcov.info --function my_function --file src/lib.rs
```

## Context Suggestions

With `--context`, debtmap can include AI-oriented context ranges:

- **Primary**: The problematic function or file range
- **Related**: Caller, callee, dependency, test, or type context with relationship labels
- **Git history**: Change frequency, bug density, age, and author count when `git_history` context is enabled

## Documentation

- [Getting Started](book/src/getting-started.md): Getting started and common workflows
- [CLI Reference](book/src/cli-reference.md): Complete command documentation
- [Output Formats](book/src/output-formats.md): Terminal, JSON, Markdown, and DOT formats
- [Configuration](book/src/configuration/index.md): `.debtmap.toml` options and thresholds
- [Metrics Reference](book/src/metrics-reference.md): Complexity metrics and scoring algorithms
- [Debt Patterns](book/src/analysis-guide/debt-patterns.md): Detected debt patterns
