Introduction

🚧 Early Prototype - This project is under active development and APIs may change

Debtmap is a Rust code analyzer that identifies which code to refactor for maximum cognitive debt reduction and which code to test for maximum risk reduction.

What is Debtmap?

Unlike traditional static analysis tools that simply flag complex code, Debtmap answers two critical questions:

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

Debtmap analyzes Rust codebases to identify complexity hotspots, technical debt patterns, and architectural risks with full AST parsing, macro expansion, and trait tracking.

Current Status

Debtmap currently focuses exclusively on Rust codebases. Our goal is to perfect Rust analysis before expanding to other languages. This focused approach allows us to:

• Build deep Rust-specific analysis (macro expansion, trait resolution, lifetime awareness)
• Perfect our core algorithms and metrics
• Establish a stable API and user experience
• Build a strong user community

Multi-language support (Python, JavaScript/TypeScript, Go, etc.) is planned for future releases once Rust analysis reaches maturity.

What Makes Debtmap Different:

• Coverage-Risk Correlation: Combines complexity metrics with test coverage to identify genuinely risky code (high complexity + low coverage = critical risk)
• Multi-Factor Analysis: Analyzes complexity, coverage, dependencies, and call graphs for comprehensive prioritization
• Reduced False Positives: Uses entropy analysis and pattern detection to distinguish genuinely complex code from repetitive patterns, significantly reducing false positives compared to traditional complexity-only analyzers. This is achieved through an advanced token classification system that categorizes code tokens and applies weighted entropy to accurately assess complexity.
• Actionable Guidance: Provides specific recommendations like “extract nested conditions” or “split this 80-line function” with quantified impact metrics
• Performance: 10-100x faster than Java/Python-based competitors (written in Rust with parallel processing providing 70-90% speedup on multi-core systems)

Why Use Debtmap?

Debtmap helps you make data-driven decisions about where to focus your refactoring and testing efforts:

• Identify Complexity - Find complex functions and modules that need refactoring, with concrete metrics showing which changes will have the most impact
• Detect Technical Debt - Discover 30+ debt patterns including code smells, security vulnerabilities, resource management issues, and architectural problems
• Assess Risk - Prioritize improvements based on sophisticated risk scoring that combines complexity, test coverage, and dependency impact
• Track Quality - Monitor code quality metrics over time with the compare command to verify that refactoring efforts achieved their goals (can optionally extract target locations from implementation plan files for focused tracking)
• Get Actionable Recommendations - Receive specific guidance like “refactoring this will reduce complexity by 60%” or “testing this will reduce risk by 5%”
• Automated Debt Reduction - Integrates with Prodigy workflows for AI-driven automated refactoring with iterative validation and testing (via external integration)

Key Features

Analysis Capabilities

• Rust-first analysis - Deep Rust support with AST parsing, macro expansion, trait resolution, and lifetime awareness
• Reduced false positives - Uses entropy analysis and pattern detection to distinguish genuinely complex code from repetitive patterns (significantly reduces false positives compared to traditional analyzers)
• Threshold presets - Quick setup with strict, balanced (default), or lenient presets matching different project types and quality standards
• Comprehensive debt detection - Identifies 30+ technical debt patterns across security (5 types), code organization (god objects, feature envy, magic values), resource management (5 types), testing quality (3 types), and error handling (4 types: error swallowing, poor error propagation, panic patterns, inadequate exception handling)
• God object detection - Identifies large classes with multiple responsibilities and provides concrete module split recommendations based on responsibility inference, method clustering, and cohesion analysis
• Boilerplate detection - Finds repetitive patterns suitable for macro-ification, including trait implementation boilerplate, builder patterns, and delegation patterns
• Functional programming analysis - Detects function purity (functions without side effects), tracks effects (I/O, mutation, panic), and identifies higher-order functions and functional patterns
• Security vulnerability detection - Finds hardcoded secrets, weak crypto, SQL injection risks, and unsafe code patterns
• Resource management analysis - Identifies inefficient allocations, nested loops, and blocking I/O patterns
• Code organization analysis - Detects god objects, feature envy, primitive obsession, and magic values
• Testing quality assessment - Analyzes test complexity, flaky patterns, and assertion quality
• File-level aggregation - Multiple aggregation methods (sum, weighted, logarithmic) for identifying files needing organizational refactoring
• Context-aware analysis - Reduces false positives through intelligent context detection (enabled by default)
• Call graph debugging - Validate and debug call graph construction with detailed diagnostics

Risk Analysis & Prioritization

• Coverage-based risk analysis - Correlates complexity with test coverage to identify truly risky code
• Risk-driven testing recommendations - Prioritizes testing efforts based on complexity-coverage correlation and dependency impact
• Call graph analysis - Tracks upstream callers and downstream callees to understand dependency impact
• Tiered prioritization - Multi-stage pipeline (zero coverage, complexity-risk, critical path, dependency impact, effort optimization) surfaces critical architectural issues above simple testing gaps
• Quantified impact - Shows concrete metrics like “refactoring this will reduce complexity by 60%”

Performance & Output

• Parallel processing - Built with Rust and Rayon for blazing-fast analysis (70-90% speedup on multi-core systems, 10-100x faster than Java/Python-based tools)
• Multiple output formats - JSON (legacy and unified structures), Markdown, and human-readable terminal formats for different tool integration needs
• Configurable thresholds - Customize complexity and duplication thresholds to match your standards
• Verbosity controls - Multiple verbosity levels (-v, -vv, -vvv) for progressive detail

Configuration & Customization

• Flexible suppression - Inline comment-based suppression for specific code sections
• Configuration file - .debtmap.toml or debtmap.toml (TOML/JSON/YAML formats supported) for project-specific settings
• Test-friendly - Easily exclude test fixtures and example code from debt analysis
• Macro expansion support - Handles Rust macro expansions with configurable warnings

Commands

• analyze - Comprehensive debt analysis with unified prioritization
• validate - Enforce quality thresholds in CI/CD pipelines
• validate-improvement - Validate refactoring improvements against quality thresholds (automates verification that changes actually improved code quality)
• compare - Track improvements over time and verify refactoring goals
• explain-coverage - Debug coverage data parsing and function name matching (helps troubleshoot coverage detection issues)
• init - Generate configuration file with sensible defaults (–force to overwrite)

Target Audience

Debtmap is designed for:

• Development teams - Get concrete metrics for planning sprints. Know exactly which refactoring will reduce complexity by 60% or which function needs 6 unit tests for full coverage.
• Engineering managers - Track quality trends over time with the compare command. Monitor whether refactoring efforts are actually improving codebase health.
• Code reviewers - Focus reviews on high-risk areas identified by Debtmap. Prioritize reviewing untested complex code over simple utility functions.
• CI/CD engineers - Enforce quality gates with validate command. Automate refactoring verification with validate-improvement for continuous quality monitoring in pipelines.
• Developers refactoring legacy codebases - Receive actionable guidance like “extract nested conditions”, “split this 80-line function into 3 smaller functions”, or “add error handling for this catch block”.

Getting Started

Ready to analyze your codebase? Check out:

• Getting Started - Installation and first analysis
• Analysis Guide - Understanding the metrics and output
• Output Formats - JSON, Markdown, and terminal formats

Tip: Start with debtmap analyze . --summary for a quick overview, or use --top 10 to focus on highest-priority items. Use threshold presets for quick configuration: --threshold-preset strict for high code quality standards, balanced (default) for typical projects, or lenient for legacy or complex domains.