Debtmap - Rust Technical Debt Analyzer

Fast code complexity and technical debt analyzer written in Rust

Links: GitHub | Crates.io | Documentation

Overview

#

Debtmap is a sophisticated technical debt analyzer that helps developers identify and prioritize code improvements through advanced complexity and risk assessment. Built in Rust for maximum performance, it answers two critical questions every development team faces:

1. “What should I refactor to reduce cognitive burden?” - Identifies overly complex code that slows down development
2. “What should I test first to reduce the most risk?” - Pinpoints untested complex code that threatens stability

Unlike traditional static analysis tools that simply flag complex code, Debtmap provides data-driven prioritization by combining complexity metrics with test coverage to identify genuinely risky code (high complexity + low coverage = critical risk).

The Problem

#

Teams struggle to prioritize refactoring and testing efforts effectively:

• Traditional static analysis generates too many false positives (flagging repetitive but simple code)
• No clear answer to “What should I refactor?” or “What should I test first?”
• Developers waste time on low-impact improvements while critical issues remain hidden
• Difficulty distinguishing genuinely complex code from pattern-based repetitive code

The Solution

#

Debtmap uses entropy-based complexity analysis that applies information theory to distinguish genuinely complex code from repetitive patterns. This approach reduces false positives by 60-75% compared to traditional cyclomatic complexity metrics.

How Entropy Analysis Works

#

Traditional tools flag code as “complex” based purely on cyclomatic complexity, but not all complexity is equal:

• Repetitive patterns (validation functions, dispatchers) have high cyclomatic complexity but low cognitive load
• Diverse logic (state machines, business rules) may have moderate cyclomatic complexity but high cognitive load

Debtmap uses Shannon entropy to measure the variety and unpredictability of code patterns, combined with:

• Token classification - Weights control flow and error handling higher than literals and identifiers
• Pattern repetition detection - Identifies repetitive structures in the AST
• Branch similarity analysis - Detects when conditional branches are nearly identical

This produces an effective complexity score that accurately reflects cognitive burden rather than just counting branches.

Key Features

#

Analysis Capabilities

#

Multi-Language Support:

• Full support: Rust (with advanced macro expansion and trait tracking)
• Partial support: Python, JavaScript, TypeScript

Entropy-Based Complexity Analysis:

• Distinguishes genuinely complex code from pattern-based repetitive code
• Advanced token classification with weighted entropy scoring
• 60-75% reduction in false positives compared to traditional cyclomatic complexity
• Threshold presets (strict, balanced, lenient) for different project types

Comprehensive Debt Detection: Identifies 30+ technical debt patterns including:

• Security vulnerabilities (5 types): hardcoded secrets, weak crypto, SQL injection risks, unsafe patterns
• Code organization (4 types): god objects, feature envy, primitive obsession, magic values
• Resource management (5 types): inefficient allocations, nested loops, blocking I/O
• Testing quality (3 types): test complexity, flaky patterns, assertion quality
• Error handling (4 types): missing error context, swallowed exceptions

Risk Analysis & Prioritization

#

Coverage-Risk Correlation:

• The only tool that combines complexity metrics with test coverage data
• Identifies truly risky code: high complexity + low coverage = critical risk
• Prioritizes testing efforts based on complexity-coverage correlation

Call Graph Analysis:

• Tracks upstream callers and downstream callees
• Understands dependency impact across the codebase
• Tiered prioritization surfaces critical architectural issues

Quantified Impact:

• Shows concrete metrics: “refactoring this will reduce complexity by 60%”
• Provides actionable guidance: “split this 80-line function into 3 smaller functions”
• Helps plan sprint work with data-backed recommendations

Performance & Usability

#

Blazing Fast Performance:

• 10-100x faster than Java/Python-based competitors
• Parallel processing with Rust and Rayon
• Intelligent caching with automatic pruning
• Configurable cache strategies (LRU, LFU, FIFO)

Flexible Output:

• JSON (legacy and unified structures)
• Markdown reports
• Human-readable terminal formats
• Configurable verbosity levels (-v, -vv, -vvv)

Configuration Options:

• .debtmap.toml, .debtmap.yml, or .debtmap.json
• Inline comment-based suppression
• Customizable thresholds matching your standards
• Test-friendly exclusion patterns

Commands

#

Debtmap provides four core commands for different workflows:

analyze

#

Comprehensive debt analysis with unified prioritization:

# Basic analysis
debtmap analyze .

# With coverage integration
cargo tarpaulin --out lcov --output-dir target/coverage
debtmap analyze . --lcov target/coverage/lcov.info

# Show top 20 issues
debtmap analyze . --top 20

# Output to JSON
debtmap analyze . --json-unified > results.json

validate

#

Enforce quality thresholds in CI/CD pipelines:

# Fail if any function exceeds complexity 15
debtmap validate . --threshold-complexity 15 --max-high 0

# Ensure no critical issues
debtmap validate . --max-critical 0

compare

#

Track improvements over time and verify refactoring goals:

# Compare current state with baseline
debtmap compare baseline.json current.json

# Track progress against implementation plan
debtmap compare --plan IMPLEMENTATION_PLAN.md

init

#

Generate configuration file with sensible defaults:

# Create .debtmap.toml
debtmap init

# Force overwrite existing config
debtmap init --force

Technical Highlights

#

• Language: Rust (for performance and safety)
• AST Parsing: syn (Rust), tree-sitter (Python/JS/TS), with macro expansion support
• Parallel Processing: Rayon for concurrent file analysis
• Analysis Method: Shannon entropy-based complexity with token classification
• Architecture: Modular design with pluggable analyzers and formatters

Real-World Impact

#

Debtmap helps teams make data-driven decisions about where to invest refactoring and testing effort:

• Development teams: Plan sprints with concrete metrics showing which refactoring will reduce complexity by 60% or which function needs 6 unit tests
• Engineering managers: Track quality trends over time with the compare command to monitor whether refactoring efforts improve codebase health
• Code reviewers: Focus reviews on high-risk areas (untested complex code) rather than simple utility functions
• Legacy codebase maintainers: Get actionable guidance like “extract nested conditions” or “split this 80-line function into 3 smaller functions”

By reducing false positives by 60-75%, Debtmap enables developers to focus on changes that truly matter.

Installation

#

# Quick install via script
curl -sSL https://raw.githubusercontent.com/iepathos/debtmap/master/install.sh | bash

# Or via Cargo
cargo install debtmap

Quick Start

#

# Initialize configuration
debtmap init

# Analyze current directory
debtmap analyze .

# With test coverage integration
cargo tarpaulin --out lcov --output-dir target/coverage
debtmap analyze . --lcov target/coverage/lcov.info

# Validate in CI/CD
debtmap validate . --threshold-complexity 15 --max-high 0

Example Output

#

HIGH PRIORITY (7):
└─ src/services/executor.rs:245-320: execute_workflow
   ├─ COMPLEXITY: cyclomatic=18, est_branches=12, cognitive=22, nesting=4
   ├─ COVERAGE: 45% (uncovered branches: 7)
   ├─ RISK: HIGH (complex + low coverage)
   └─ RECOMMENDATION: Split into 3 functions, add 7 test cases

Advanced Features

#

Prodigy Integration

#

Integrates with Prodigy workflows for AI-driven automated refactoring with iterative validation and testing.

God Object Detection

#

Identifies classes with too many responsibilities using specialized heuristics for better architectural insights.

Design Pattern Detection

#

Recognizes common design patterns (Observer, Factory, Singleton, Strategy) to provide context-aware recommendations.

Suppression Patterns

#

Flexible suppression via inline comments or configuration files to exclude specific code sections from analysis.

Links

#

• GitHub: github.com/iepathos/debtmap
• Documentation: iepathos.github.io/debtmap
• Crates.io: Available via cargo install debtmap

Project Status

#

Early Prototype - Active development with 2,151+ commits. APIs may change as the project evolves.

License: MIT (with LGPL-3.0 dependency note for Python parsing)

Roadmap:

• Additional language support (Go, C/C++, C#, Java)
• GitHub Actions and GitLab CI integrations
• IDE plugins (VS Code, IntelliJ, etc.)