debtmap

Debtmap analyzes your codebase and ranks technical debt by risk. Know exactly where to focus your refactoring effort - whether you're fixing it yourself or handing it to an AI assistant.

Why Debtmap?

Large codebases accumulate complexity. You know there's debt, but where do you start?

Debtmap answers that question by combining multiple signals into a single priority score:

• Complexity - cyclomatic, cognitive, nesting depth
• Coverage gaps - untested code with high complexity
• Git history - files with high churn and bug fix rates
• Coupling - functions with many dependencies
• Purity - side effects that make code harder to test

The result: a ranked list of what to fix first, with the context needed to understand why.

Quick Start

# Install
cargo install debtmap

# Explore issues interactively (default)
debtmap analyze .

# Terminal output for scripts and CI
debtmap analyze . --format terminal

# JSON for programmatic access
debtmap analyze . --format json --top 10 > debt.json

# Pipe to an LLM for automated fixes
debtmap analyze . --format markdown --top 1 | claude "Fix this"

How It Works

Debtmap combines static analysis with git history to score technical debt:

Signal	What It Measures	Why It Matters
Complexity	Cyclomatic, cognitive, nesting depth	How hard code is to understand
Coverage	Test coverage percentage per function	How risky changes are
Git History	Change frequency, bug fix rate, author count	Which code keeps breaking
Coupling	Dependencies, call graph depth	How changes ripple through the codebase
Purity	Side effects, I/O operations	How testable and predictable code is
Entropy	Pattern consistency	Reduces false positives from intentional complexity

These signals combine into a severity score (0-10). High scores mean high-complexity, poorly-tested, frequently-broken code.

Interactive TUI

Run debtmap analyze . to explore results interactively:

Features:

• Browse debt items sorted by severity
• Drill into score breakdowns to understand why code ranks high
• View git history, dependencies, and test coverage per function
• Copy context to clipboard for AI assistants
• Jump to code in your editor

LLM Integration

The --format markdown output is designed for AI coding assistants. It provides:

• Context suggestions - Specific file ranges the LLM should read to understand the problem
• Structured metadata - All scoring factors exposed so the LLM can reason about priorities
• Minimal tokens - Compact format that fits more context into the LLM's window
• Deterministic output - Same input produces same output for reproducible workflows

# Pipe directly to Claude Code
debtmap analyze . --format markdown --top 1 | claude "Fix this technical debt"

See LLM Integration Guide for details.

Output Formats

# Markdown (recommended for AI workflows)
debtmap analyze . --format markdown

# JSON for programmatic access
debtmap analyze . --format json

# Terminal for human exploration
debtmap analyze . --format terminal

With Coverage Data

# Generate coverage first
cargo llvm-cov --lcov --output-path coverage.lcov

# Analyze with coverage integration
debtmap analyze . --lcov coverage.lcov

Coverage data enables accurate risk assessment - complex code with good tests ranks lower than simple code with no tests.

CI/CD Integration

# .github/workflows/quality.yml
name: Code Quality
on: [push, pull_request]

jobs:
  debtmap:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: iepathos/debtmap-action@v1
        with:
          max-complexity-density: '10.0'
          fail-on-violation: 'true'

Documentation

Full Documentation — guides, examples, configuration reference

Quick links:

• Getting Started
• LLM Integration
• Configuration
• Metrics Reference

Performance Profiling

Debtmap includes built-in profiling to identify performance bottlenecks.

Built-in Timing

# Show timing breakdown for each analysis phase
debtmap analyze . --profile

# Write detailed timing data to JSON
debtmap analyze . --profile --profile-output timing.json

Example output:

=== Profiling Report ===
Total analysis time: 38.55s

Phase breakdown:
Operation                                    Duration        %      Count
------------------------------------------------------------------------
analyze_project                                27.94s    72.5%          1
  duplication_detection                        24.94s    64.7%          1
  parsing                                       2.57s     6.7%          1
unified_analysis                               10.75s    27.9%          1
  call_graph_building                           8.05s    20.9%          1
  debt_scoring                                  1.89s     4.9%          1

External Profilers

For CPU-level profiling, use sampling profilers with debug builds:

macOS (samply)

# Install samply
cargo install samply

# Build with debug symbols
cargo build --profile dev

# Profile debtmap
samply record ./target/debug/debtmap analyze /path/to/project

# Opens Firefox Profiler with flame graphs

macOS (Instruments)

# Build with debug symbols
cargo build --profile dev

# Profile with Instruments
xcrun xctrace record --template 'Time Profiler' --launch ./target/debug/debtmap analyze .

Linux (perf)

# Build with debug symbols
RUSTFLAGS="-C debuginfo=2" cargo build --release

# Record profile
perf record -g ./target/release/debtmap analyze /path/to/project

# View results
perf report

Tip: The --profile flag identifies what is slow; sampling profilers show why it's slow at the code level.

Roadmap

Current focus: Rust analysis excellence + AI workflow integration

• Cognitive + cyclomatic complexity
• Test coverage correlation
• Pattern-based false positive reduction
• LLM-optimized output format
• Context suggestions for AI
• Streaming output for large codebases
• Multi-language support (Go, Python, TypeScript)

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Good first issues:

• Improve Rust-specific analysis
• Add new complexity metrics
• Expand test coverage
• Documentation improvements

License

MIT — see LICENSE

---

Questions? Open an issue or check the documentation.