Introduction

Debtmap is a code complexity sensor for AI-assisted development. It identifies technical debt hotspots and provides the structured data AI coding tools need to understand and fix them.

What is Debtmap?

Debtmap is different from traditional static analysis tools. Instead of telling you what to fix, it provides signals that AI assistants can use to make informed decisions:

1. Where to look - Prioritized list of debt items with exact file locations
2. What to read - Context suggestions (callers, callees, test files)
3. What signals matter - Complexity, coverage, coupling metrics

The key insight: AI coding assistants are great at fixing code, but they need guidance on where to focus and what to read. Debtmap provides that guidance.

The AI Sensor Model

Debtmap is a sensor, not a prescriber. It measures and reports; it doesn’t tell you what to do.

What Debtmap provides:

• Quantified complexity signals (cyclomatic, cognitive, nesting)
• Test coverage gaps with risk prioritization
• Context suggestions for AI consumption
• Structured output (JSON, LLM-markdown) for machine consumption

What Debtmap doesn’t provide:

• “Fix this by doing X” recommendations
• “You should consider Y” advice
• Template-based refactoring suggestions

This design is intentional. AI assistants can consider business context, team preferences, and constraints that Debtmap can’t know. The AI decides what to do; Debtmap tells it where to look.

Quick Start

# Install
cargo install debtmap

# Analyze and pipe to Claude Code
debtmap analyze . --format markdown --top 3 | claude "Fix the top item"

# Get structured signals for your AI workflow
debtmap analyze . --format json --top 10 > debt.json

# With coverage data for accurate risk assessment
cargo llvm-cov --lcov --output-path coverage.lcov
debtmap analyze . --lcov coverage.lcov --format markdown

Key Features

Signal Generation

• Complexity signals - Cyclomatic, cognitive, nesting depth, lines of code
• Coverage signals - Line coverage, branch coverage, function coverage
• Coupling signals - Fan-in, fan-out, call graph depth
• Quality signals - Entropy (false positive reduction), purity (testability)

For a complete list of metrics and their formulas, see the Metrics Reference.

AI-Optimized Output

• LLM markdown format - Minimal tokens, maximum information
• Context suggestions - File ranges the AI should read
• Structured JSON - Stable schema for programmatic access
• Deterministic output - Same input = same output

Analysis Capabilities

• Rust-first analysis - Full AST parsing, macro expansion, trait resolution
• Coverage integration - Native LCOV support for risk assessment
• Debt pattern detection - God objects, boilerplate code, error handling anti-patterns
• Entropy analysis - Reduces false positives from repetitive code
• Parallel processing - Fast analysis (10-100x faster than Java/Python tools)

Workflow Integration

• Direct piping - Pipe output to Claude, Cursor, or custom agents
• CI/CD gates - Validate debt thresholds with the validate command
• Progress tracking - Compare debt across commits with compare and validate-improvement commands

Current Status

Debtmap focuses exclusively on Rust. This focused approach allows us to:

• Build deep Rust-specific analysis (macros, traits, lifetimes)
• Perfect core algorithms before expanding
• Deliver the best possible AI sensor for Rust

Multi-language support (Python, JavaScript/TypeScript, Go) is planned for future releases.

Target Audience

Debtmap is designed for:

• AI-assisted developers - Get signals that help AI assistants make better decisions
• Development teams - Prioritize debt remediation with quantified metrics
• CI/CD engineers - Enforce quality gates with coverage-aware thresholds
• Legacy codebase maintainers - Identify where AI can help most

Getting Started

Ready to start? Check out:

• Getting Started - Installation and first analysis
• LLM Integration - AI workflow patterns
• Why Debtmap? - The AI sensor model explained
• TUI Guide - Interactive exploration with the terminal UI

Quick tip: Start with debtmap analyze . --format markdown --top 5 to see the top priority items with context suggestions.

Why Debtmap?

Debtmap is a code complexity sensor designed for AI-assisted development workflows. It identifies technical debt hotspots and provides the structured data AI coding tools need to understand and fix them.

The AI Development Paradox

AI coding assistants like Claude Code, GitHub Copilot, and Cursor are transforming software development. They can write code faster than ever before. But this creates a paradox:

AI creates technical debt faster than humans can manage it.

When an AI generates hundreds of lines of code per hour, traditional code review and refactoring processes break down. Teams accumulate debt faster than they can pay it down.

At the same time, AI assistants struggle to fix the debt they create:

• Limited context window - They can’t see the entire codebase at once
• No test awareness - They don’t know which code is tested vs untested
• No prioritization - They can’t identify what matters most
• Wasted tokens - They read irrelevant code while missing critical context

What AI Coding Tools Need

For an AI assistant to effectively fix technical debt, it needs:

1. Prioritized Targets

Not “here are 500 complex functions,” but “here are the 10 functions that matter most, ranked by severity.”

Debtmap provides a severity score (0-10) that combines:

• Complexity metrics (cyclomatic, cognitive, nesting)
• Test coverage gaps
• Coupling and dependency impact
• Pattern-based false positive reduction

2. Context Suggestions

Not “this function is complex,” but “read lines 38-85 of parser.rs, plus lines 100-120 of handler.rs where it’s called, and lines 50-75 of the test file.”

Debtmap’s context suggestions tell the AI exactly which code to read:

CONTEXT:
├─ Primary: src/parser.rs:38-85 (the debt item)
├─ Caller: src/handler.rs:100-120 (usage context)
└─ Tests: tests/parser_test.rs:50-75 (expected behavior)

3. Quantified Signals

Not “this code is bad,” but “cyclomatic complexity: 12, cognitive complexity: 18, test coverage: 0%, called by 8 functions.”

These signals let the AI make informed decisions about the best approach:

• High complexity + good coverage = risky to refactor
• Low complexity + no coverage = easy test target
• High coupling + high complexity = incremental approach needed

4. Structured Output

Not free-form text, but JSON and markdown optimized for LLM consumption:

• Consistent structure across all debt items
• Minimal tokens for maximum information
• Deterministic output for reproducible workflows
• Stable IDs for referencing items across runs

What Debtmap Provides

Complexity Signals

Coverage Signals

Coupling Signals

Quality Signals

What Debtmap Doesn’t Do

Debtmap is a sensor, not a prescriber. It measures and reports; it doesn’t tell you what to do.

No Fix Suggestions

Debtmap doesn’t say “split this function into 5 modules” or “add 8 unit tests.” Those decisions require understanding the business context, architectural constraints, and team preferences that only humans (or AI with proper context) can evaluate.

No “Should” Statements

Debtmap doesn’t say “you should refactor this” or “consider extracting a helper function.” It reports facts: “complexity: 18, coverage: 0%, called by 12 functions.” The AI or developer decides what to do with that information.

No Impact Predictions

Debtmap doesn’t claim “refactoring this will reduce bugs by 40%.” Such predictions are speculative. Debtmap reports what it can measure accurately and leaves interpretation to the consumer.

Comparison with Alternatives

vs Static Analysis Tools (SonarQube, CodeClimate)

Traditional tools are designed for human code review workflows. Debtmap is designed for AI-assisted development.

vs Linters (Clippy, ESLint)

Linters catch code style issues. Debtmap identifies complexity hotspots. Use both.

vs Coverage Tools (Tarpaulin, pytest-cov)

Coverage tools tell you what’s tested. Debtmap tells you what untested code is most risky.

How Debtmap Fits in Your Workflow

AI-Assisted Development

# Generate debt signals
debtmap analyze . --format markdown --lcov coverage.lcov

# Pipe to AI
cat debt.md | claude "Fix the top item, read the suggested context first"

CI/CD Integration

# Fail build if debt exceeds thresholds
debtmap validate . --max-debt-density 10.0

# Generate report for PR review
debtmap analyze . --format json --output debt-report.json

Exploratory Analysis

# Quick overview
debtmap analyze . --top 10

# Deep dive with coverage
debtmap analyze . --lcov coverage.lcov --format terminal -vv

Key Insights

1. Debtmap is a sensor - It measures, it doesn’t prescribe
2. AI does the thinking - Debtmap provides data, AI decides action
3. Context is key - Knowing what to read is as valuable as what to fix
4. Signals over interpretations - Raw metrics, not template advice
5. Speed matters - Fast enough for local development loops

Next Steps

Ready to try it? Head to Getting Started to install debtmap and run your first analysis.

Want to integrate with your AI workflow? See LLM Integration for detailed guidance.

Want to understand how it works under the hood? See Architecture for the analysis pipeline.

Getting Started

This guide will help you install Debtmap and run your first analysis in just a few minutes.

Prerequisites

Before installing Debtmap, you’ll need:

• For pre-built binaries: No prerequisites! The install script handles everything.
• For cargo install or building from source:
  • Rust toolchain (rustc and cargo)
  • Supported platforms: Linux, macOS, Windows
  • Rust edition 2021 or later

Optional (for coverage-based risk analysis):

• Rust projects: cargo-tarpaulin or cargo-llvm-cov for coverage data

Installation

Quick Install (Recommended)

Install the latest release with a single command:

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

Or with wget:

wget -qO- https://raw.githubusercontent.com/iepathos/debtmap/master/install.sh | bash

This will:

• Automatically detect your OS and architecture
• Download the appropriate pre-built binary from the latest GitHub release
• Install debtmap to ~/.cargo/bin if it exists, otherwise ~/.local/bin
• Offer to automatically add the install directory to your PATH if needed

Using Cargo

If you have Rust installed:

cargo install debtmap

From Source

For the latest development version:

# Clone the repository
git clone https://github.com/iepathos/debtmap.git
cd debtmap

# Build and install
cargo install --path .

Verify Installation

After installation, verify Debtmap is working:

# Check version
debtmap --version

# See available commands
debtmap --help

Quick Start

Here are the most common commands to get you started:

# Basic analysis (simplest command)
debtmap analyze .

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

# Pipe directly to Claude Code
debtmap analyze . --format markdown --top 3 | claude "Fix the top item"

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

# With coverage data for accurate risk assessment
cargo llvm-cov --lcov --output-path coverage.lcov
debtmap analyze . --lcov coverage.lcov

# Show only critical/high priority items
debtmap analyze . --min-priority high --top 10

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

First Analysis

Let’s run your first analysis! Navigate to a project directory and run:

debtmap analyze .

What happens during analysis:

1. File Discovery - Debtmap scans your project for source files (currently Rust .rs with full analysis; Python .py file detection only)
2. Parsing - Each file is parsed into an Abstract Syntax Tree (AST)
3. Metric Extraction - Complexity, coverage gaps, and coupling are measured
4. Prioritization - Results are ranked by severity (CRITICAL, HIGH, MEDIUM, LOW, MINIMAL)
5. Context Generation - File ranges are suggested for each debt item
6. Output - Results are displayed in your chosen format

Expected timing: Analyzing a 10,000 LOC project typically takes 2-5 seconds.

Example Output

When you run debtmap analyze . --format markdown, you’ll see output like this:

# Technical Debt Analysis

## Summary
- Total items: 47
- Critical: 3, High: 12, Moderate: 20, Low: 12

## #1 [CRITICAL] parse_complex_input
**Location:** src/parser.rs:38-85
**Score:** 8.9/10

**Signals:**
| Metric | Value |
|--------|-------|
| Cyclomatic | 12 |
| Cognitive | 18 |
| Coverage | 0% |
| Nesting | 4 |

**Context:**
- Primary: src/parser.rs:38-85
- Caller: src/handler.rs:100-120
- Test: tests/parser_test.rs:50-75

Understanding the Output

Priority Tiers

Key Signals

Complexity signals:

• Cyclomatic: Decision points (if, match, loop)
• Cognitive: How hard code is to understand
• Nesting: Indentation depth
• Lines: Function length

Coverage signals:

• Line coverage: % of lines executed by tests
• Branch coverage: % of branches taken

Coupling signals:

• Fan-in: Functions that call this function
• Fan-out: Functions this function calls

Context Suggestions

Each debt item includes file ranges the AI should read:

Context:
├─ Primary: src/parser.rs:38-85 (the debt item)
├─ Caller: src/handler.rs:100-120 (usage context)
└─ Test: tests/parser_test.rs:50-75 (expected behavior)

These suggestions help AI assistants understand the code before making changes.

Output Formats

Markdown (for AI workflows)

debtmap analyze . --format markdown

Optimized for minimal token usage while providing all necessary context.

JSON (for programmatic access)

debtmap analyze . --format json --output debt.json

Structured data for CI/CD integration and custom tooling.

Terminal (for human exploration)

debtmap analyze . --format terminal

Color-coded, interactive output for manual review.

Adding Coverage Data

Coverage data enables accurate risk assessment:

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

# Or with cargo-tarpaulin
cargo tarpaulin --out lcov --output-dir target/coverage

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

With coverage data:

• Complex code with good tests = lower priority
• Simple code with no tests = higher priority
• Untested error paths are identified

AI Workflow Examples

Claude Code

# Direct piping
debtmap analyze . --format markdown --top 3 | claude "Fix the top item"

# With coverage
cargo llvm-cov --lcov --output-path coverage.lcov
debtmap analyze . --format markdown --lcov coverage.lcov --top 1 | \
  claude "Add tests for this function"

Cursor

# Generate report for Cursor to reference
debtmap analyze . --format markdown --top 10 > debt-report.md

# In Cursor: @debt-report.md Fix the top critical item

Custom Pipelines

# Get JSON for programmatic processing
debtmap analyze . --format json --top 5 | \
  jq '.items[0].context.primary' | \
  xargs -I {} echo "Read {}"

Configuration

Create a project-specific configuration:

debtmap init

This creates .debtmap.toml:

[thresholds]
complexity = 10
duplication = 40

[tiers]
critical = 9.0
high = 7.0
medium = 5.0

[ignore]
patterns = ["**/target/**", "**/tests/**"]

CLI Options Reference

Analysis Options

Verbosity Options

Performance Options

Troubleshooting

Installation Issues

• Binary not in PATH: Add ~/.cargo/bin or ~/.local/bin to your PATH

  export PATH="$HOME/.cargo/bin:$PATH"  # Add to ~/.bashrc or ~/.zshrc
  

• Permission issues: Run the install script with your current user (don’t use sudo)
• Cargo not found: Install Rust from https://rustup.rs

Analysis Issues

• Empty output: Check that your project contains supported source files (.rs for Rust, .py for Python)
• Parser failures: Run with -vv for debug output
• Performance issues: Limit parallel jobs with --jobs 4
• Large codebase slowness: Use --streaming mode for O(1) memory overhead

Coverage Issues

• Coverage not applied: Verify LCOV file path is correct
• Low coverage detected: Ensure tests actually run during coverage generation
• Coverage debugging: Use debtmap diagnose-coverage <file.lcov> to validate coverage file parsing

What’s Next?

Now that you’ve run your first analysis:

• Integrate with AI: See LLM Integration for AI workflow patterns
• Understand metrics: See Metrics Reference for signal definitions
• Configure thresholds: See Configuration for customization
• CI/CD integration: See Prodigy Integration for automation

Need help? Report issues at https://github.com/iepathos/debtmap/issues

LLM Integration Guide

How to use debtmap output in AI coding workflows.

Overview

Debtmap is designed to provide AI coding assistants with the signals they need to understand and fix technical debt. This guide covers:

1. Output formats optimized for LLMs
2. Context suggestions and how to use them
3. Example workflows for different AI tools
4. Interpreting signals for effective prompts

Output Formats

Markdown (Recommended)

The markdown format is specifically designed for LLM consumption:

debtmap analyze . --format markdown --top 5

Output structure:

# Technical Debt Analysis

## Summary
- Total items: 47
- Critical: 3
- High: 12
- Moderate: 20
- Low: 12

## Top Priority Items

### #1 [CRITICAL] parse_complex_input
**Location:** src/parser.rs:38-85
**Score:** 8.9/10

**Signals:**
| Metric | Value | Threshold |
|--------|-------|-----------|
| Cyclomatic | 12 | 10 |
| Cognitive | 18 | 15 |
| Coverage | 0% | 80% |
| Nesting | 4 | 3 |

**Context to read:**
- Primary: src/parser.rs:38-85
- Caller: src/handler.rs:100-120
- Caller: src/api.rs:45-60
- Test: tests/parser_test.rs:50-75

---

### #2 [CRITICAL] validate_auth
...

Why this format works:

• Consistent structure across all items
• Tables for easy metric comparison
• Context suggestions inline
• Minimal tokens for maximum information

JSON

For programmatic access and CI/CD integration:

debtmap analyze . --format json --output debt.json

Structure:

{
  "version": "1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "summary": {
    "total_items": 47,
    "by_tier": {
      "critical": 3,
      "high": 12,
      "moderate": 20,
      "low": 12
    },
    "total_loc": 15420
  },
  "items": [
    {
      "rank": 1,
      "id": "parse_complex_input_38",
      "tier": "critical",
      "score": 8.9,
      "location": {
        "file": "src/parser.rs",
        "line_start": 38,
        "line_end": 85,
        "function": "parse_complex_input"
      },
      "metrics": {
        "cyclomatic": 12,
        "cognitive": 18,
        "nesting": 4,
        "loc": 47
      },
      "coverage": {
        "line_percent": 0.0,
        "branch_percent": 0.0
      },
      "context": {
        "primary": "src/parser.rs:38-85",
        "callers": [
          {"file": "src/handler.rs", "lines": "100-120", "calls": 12},
          {"file": "src/api.rs", "lines": "45-60", "calls": 8}
        ],
        "tests": [
          {"file": "tests/parser_test.rs", "lines": "50-75"}
        ]
      }
    }
  ]
}

Terminal

For human exploration (not recommended for AI piping):

debtmap analyze . --format terminal

Context Suggestions

Each debt item includes a context field that tells the AI exactly what code to read:

CONTEXT:
├─ Primary: src/parser.rs:38-85 (the debt item)
├─ Caller: src/handler.rs:100-120 (understands usage)
├─ Caller: src/api.rs:45-60 (understands usage)
├─ Callee: src/tokenizer.rs:15-40 (understands dependencies)
└─ Test: tests/parser_test.rs:50-75 (understands expected behavior)

Context Types

Using Context Effectively

Minimal context (fastest):

# Just get the primary location
debtmap analyze . --format json | jq '.items[0].location'

Full context (most accurate):

# Read all suggested files
debtmap analyze . --format markdown --top 1
# Then have the AI read each file in the context section

Example Workflows

Claude Code Integration

Direct piping:

debtmap analyze . --format markdown --top 3 | claude "Fix the top item. Read the context files first."

Two-step workflow:

# Step 1: Get the analysis
debtmap analyze . --format markdown --lcov coverage.lcov --top 5 > debt.md

# Step 2: Send to Claude with context
cat debt.md | claude "
Read the context files for item #1 before making changes.
Then fix the debt item following these rules:
1. Add tests first
2. Refactor only after tests pass
3. Keep functions under 20 lines
"

Focused fix with coverage:

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

# Analyze with coverage
debtmap analyze . --format markdown --lcov coverage.lcov --top 1

# Send the top item to Claude
debtmap analyze . --format markdown --lcov coverage.lcov --top 1 | \
  claude "Add tests for this function to reach 80% coverage"

Cursor Integration

Cursor works best with file-based context:

# Generate debt report
debtmap analyze . --format markdown --top 10 > .cursor/debt-report.md

# In Cursor, reference the report:
# @debt-report.md Fix the top critical item

Custom Agent Workflow

For building your own AI pipeline:

import json
import subprocess

# Run debtmap analysis
result = subprocess.run(
    ["debtmap", "analyze", ".", "--format", "json", "--top", "10"],
    capture_output=True,
    text=True
)
debt_data = json.loads(result.stdout)

# Process each item
for item in debt_data["items"]:
    # Extract context files
    context_files = []
    context_files.append(item["context"]["primary"])
    context_files.extend([c["file"] for c in item["context"].get("callers", [])])

    # Read context files
    context_content = ""
    for file_spec in context_files:
        file_path, lines = parse_file_spec(file_spec)
        context_content += read_file_lines(file_path, lines)

    # Build prompt
    prompt = f"""
    Fix this technical debt item:

    Location: {item["location"]["file"]}:{item["location"]["line_start"]}
    Function: {item["location"]["function"]}
    Score: {item["score"]}/10

    Signals:
    - Cyclomatic complexity: {item["metrics"]["cyclomatic"]}
    - Test coverage: {item["coverage"]["line_percent"]}%

    Context code:
    {context_content}

    Instructions:
    1. Add tests first
    2. Refactor to reduce complexity
    3. Keep the same public API
    """

    # Send to your LLM
    response = call_llm(prompt)

CI/CD Integration

GitHub Actions example:

name: Debt Analysis

on: [pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install debtmap
        run: cargo install debtmap

      - name: Generate coverage
        run: cargo llvm-cov --lcov --output-path coverage.lcov

      - name: Analyze debt
        run: |
          debtmap analyze . --format json --lcov coverage.lcov > debt.json

      - name: Check for critical items
        run: |
          CRITICAL=$(jq '.summary.by_tier.critical' debt.json)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "::warning::Found $CRITICAL critical debt items"
          fi

      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: debt-report
          path: debt.json

Interpreting Signals

Severity Score (0-10)

The severity score combines multiple signals:

Complexity Signals

Cyclomatic complexity:

• 1-5: Simple, easy to test
• 6-10: Moderate, manageable
• 11-20: Complex, consider splitting
• 21+: Very complex, high priority

Cognitive complexity:

• Measures how hard code is to understand
• Penalizes nesting more than cyclomatic
• Higher values = harder to reason about

Nesting depth:

• 1-2: Normal
• 3: Getting complex
• 4+: Strongly consider refactoring

Coverage Signals

Line coverage:

• 0%: Critical gap, no tests at all
• 1-50%: Poor coverage
• 51-80%: Moderate coverage
• 81%+: Good coverage

Branch coverage:

• More important than line coverage
• Missing branches = missing edge cases
• 0% branch = high risk

Coupling Signals

Fan-in (callers):

• High fan-in = many dependents
• Changes affect many places
• Higher priority for stability

Fan-out (callees):

• High fan-out = many dependencies
• Complex testing requirements
• Consider dependency injection

Best Practices

For Effective AI Prompts

1. Always include context files

   • AI makes better decisions with more context
   • Context suggestions are curated for relevance

2. Specify your constraints

   • “Keep the same public API”
   • “Add tests before refactoring”
   • “Functions must be under 20 lines”

3. One item at a time

   • Focus on top priority item
   • Complete fix before moving on
   • Re-run analysis after changes

4. Verify with coverage

   • Regenerate coverage after changes
   • Run debtmap again to confirm improvement
   • Track score reduction

For CI/CD Integration

1. Set appropriate thresholds

   • Don’t fail on existing debt
   • Fail on new critical items
   • Track trends over time

2. Cache analysis results

   • Use git-based caching
   • Only re-analyze changed files

3. Integrate with PR comments

   • Show debt impact of changes
   • Suggest focus areas for review

Troubleshooting

Empty context suggestions

Cause: Call graph analysis couldn’t resolve callers/callees

Solution: Ensure file parsing succeeded:

debtmap analyze . -vv  # Verbose mode shows parsing issues

Inconsistent scores between runs

Cause: Non-deterministic analysis (should not happen)

Solution: Report as a bug with reproducible example

Large context suggestions

Cause: High coupling in codebase

Solution: Use --max-context-lines to limit:

debtmap analyze . --format markdown --max-context-lines 300

API Reference

CLI Options for LLM Integration

JSON Schema

The JSON output follows a stable schema. See Output Formats for the complete schema definition.

Next Steps

• Configure analysis: See Configuration
• Understand metrics: See Metrics Reference
• View examples: See Examples

CLI Reference

Complete reference for Debtmap command-line interface.

Quick Start

# Basic analysis
debtmap analyze src/

# With coverage integration
debtmap analyze src/ --coverage-file coverage.lcov

# Generate JSON report
debtmap analyze . --format json --output report.json

# Show top 10 priority items only
debtmap analyze . --top 10 --min-priority high

# Initialize configuration and validate
debtmap init
debtmap validate . --config debtmap.toml

Global Options

Options that apply to all commands:

• --show-config-sources - Show where each configuration value came from (spec 201)
  • Displays the source of each configuration value (default, config file, environment, CLI)
  • Useful for debugging configuration precedence issues
• --config <PATH> - Custom config file path (overrides default locations)
  • Can also use DEBTMAP_CONFIG environment variable

Example:

# Show configuration sources
debtmap --show-config-sources analyze .

# Use custom config file
debtmap --config /path/to/debtmap.toml validate .

Commands

Debtmap provides seven main commands: five for analysis and validation, plus two debugging tools.

analyze

Analyze code for complexity and technical debt.

Usage:

debtmap analyze <PATH> [OPTIONS]

Arguments:

• <PATH> - Path to analyze (file or directory)

Description: Primary command for code analysis. Supports multiple output formats (json, markdown, terminal), coverage file integration, parallel processing, context-aware risk analysis, and comprehensive filtering options.

See Options section below for all available flags.

init

Initialize a Debtmap configuration file.

Usage:

debtmap init [OPTIONS]

Options:

• -f, --force - Force overwrite existing config

Description: Creates a .debtmap.toml configuration file in the current directory with default settings. Use --force to overwrite an existing configuration file.

validate

Validate code against thresholds defined in configuration file.

Usage:

debtmap validate <PATH> [OPTIONS]

Arguments:

• <PATH> - Path to analyze

Options:

Configuration & Output:

• -c, --config <CONFIG> - Configuration file path
• -f, --format <FORMAT> - Output format: json, markdown, terminal
• -o, --output <OUTPUT> - Output file path (defaults to stdout)

Coverage & Context:

• --coverage-file <PATH> / --lcov <PATH> - LCOV coverage file for risk analysis
• --context / --enable-context - Enable context-aware risk analysis
• --context-providers <PROVIDERS> - Context providers to use (comma-separated)
• --disable-context <PROVIDERS> - Disable specific context providers

Thresholds & Validation:

• --max-debt-density <N> - Maximum debt density allowed (per 1000 LOC)

Display Filtering:

• --top <N> / --head <N> - Show only top N priority items
• --tail <N> - Show only bottom N priority items
• -s, --summary - Use summary format with tiered priority display

Analysis Control:

• --semantic-off - Disable semantic analysis (fallback mode)

Performance Control:

• --no-parallel - Disable parallel call graph construction (enabled by default)
• -j, --jobs <N> - Number of threads for parallel processing (0 = use all cores)
  • Can also use DEBTMAP_JOBS environment variable

Debugging & Verbosity:

• -v, --verbose - Increase verbosity level (can be repeated: -v, -vv, -vvv)

Description: Similar to analyze but enforces thresholds defined in configuration file. Returns non-zero exit code if thresholds are exceeded, making it suitable for CI/CD integration.

The validate command supports a focused subset of analyze options, primarily for output control, coverage integration, context-aware analysis, and display filtering.

Note: The following analyze options are NOT available in the validate command:

• --threshold-complexity, --threshold-duplication, --threshold-preset (configure these in .debtmap.toml instead)
• --languages (language filtering)

Note: The --explain-score flag exists in the validate command but is deprecated (hidden). Use -v, -vv, or -vvv for verbosity instead.

Configure analysis thresholds in your .debtmap.toml configuration file for use with the validate command.

Exit Codes:

• 0 - Success (no errors, all thresholds passed)
• Non-zero - Failure (errors occurred or thresholds exceeded)

compare

Compare two analysis results and generate a diff report.

Usage:

debtmap compare --before <FILE> --after <FILE> [OPTIONS]

Required Options:

• --before <FILE> - Path to “before” analysis JSON
• --after <FILE> - Path to “after” analysis JSON

Optional Target Location:

• --plan <FILE> - Path to implementation plan (to extract target location)
• --target-location <LOCATION> - Target location in format file:function:line

Note: --plan and --target-location are mutually exclusive options. Using both together will cause a CLI error:

error: the argument '--plan <FILE>' cannot be used with '--target-location <LOCATION>'

Use one or the other to specify the target location.

Output Options:

• -f, --format <FORMAT> - Output format: json, markdown, terminal (default: json)
• -o, --output <OUTPUT> - Output file (defaults to stdout)

Description: Compares two analysis results and generates a diff showing improvements or regressions in code quality metrics.

validate-improvement

Validate that technical debt improvements meet quality thresholds.

Usage:

debtmap validate-improvement --comparison <FILE> [OPTIONS]

Required Options:

• --comparison <FILE> - Path to comparison JSON file (from debtmap compare)

Optional Options:

• -o, --output <FILE> - Output file path for validation results (default: .prodigy/debtmap-validation.json)
• --previous-validation <FILE> - Path to previous validation result for trend tracking
• --threshold <N> - Improvement threshold percentage (default: 75.0)
• -f, --format <FORMAT> - Output format: json, markdown, terminal (default: json)
• --quiet - Suppress console output (useful for automation)

Description: Validates improvement quality by analyzing comparison output from debtmap compare. Calculates a composite improvement score based on weighted components:

Composite Score Calculation:

1. Target Item Improvement (50% weight) - Measures direct improvement to the specific target item being fixed

   • Compares complexity, debt score, and other metrics before/after
   • Weight: 0.5 × (target improvement percentage)

2. Overall Project Health (30% weight) - Evaluates project-wide quality changes

   • Analyzes aggregate metrics across entire codebase
   • Considers new issues introduced, total debt changes
   • Weight: 0.3 × (project health percentage)

3. Absence of Regressions (20% weight) - Penalizes introduction of new technical debt

   • Checks for new high-priority issues in other parts of codebase
   • Ensures improvements don’t shift complexity elsewhere
   • Weight: 0.2 × (regression-free percentage)

Final Score: composite_score = (0.5 × target) + (0.3 × health) + (0.2 × no_regressions)

The default threshold (75%) requires strong improvement in the target item while maintaining overall project quality.

When --previous-validation is provided, tracks progress trends across multiple attempts and provides recommendations for continuing or adjusting the improvement approach.

Example:

# Basic validation
debtmap validate-improvement --comparison comparison.json

# With trend tracking and custom threshold
debtmap validate-improvement \
  --comparison .prodigy/comparison.json \
  --previous-validation .prodigy/validation.json \
  --output .prodigy/validation.json \
  --threshold 80.0

diagnose-coverage (Debugging)

Diagnose and validate LCOV coverage files.

Usage:

debtmap diagnose-coverage <COVERAGE_FILE> [OPTIONS]

Arguments:

• <COVERAGE_FILE> - Path to the LCOV coverage file to diagnose

Options:

• --format <FORMAT> - Output format: text or json (default: text)

Description: Validates and diagnoses LCOV coverage files with detailed analysis. This command helps identify issues with coverage data before using it with the analyze command. Use this when:

• Coverage data seems incorrect or incomplete
• You want to validate an LCOV file before integration
• Debugging coverage parsing issues

Example:

# Validate coverage file with text output
debtmap diagnose-coverage coverage.lcov

# Get JSON output for automation
debtmap diagnose-coverage lcov.info --format json

explain-coverage (Debugging)

Explain coverage detection for a specific function.

Usage:

debtmap explain-coverage <PATH> --coverage-file <FILE> --function <NAME> [OPTIONS]

Arguments:

• <PATH> - Path to the codebase to analyze

Required Options:

• --coverage-file <FILE> / --lcov <FILE> - LCOV coverage file
• --function <NAME> - Function name to explain (e.g., “create_auto_commit”)

Optional Options:

• --file <PATH> - File path containing the function (helps narrow search)
• -v, --verbose - Show all attempted matching strategies
• -f, --format <FORMAT> - Output format: text or json (default: text)

Description: Debugging tool that explains how coverage detection works for a specific function. Shows all attempted matching strategies and helps diagnose coverage mapping issues. This command is particularly useful when:

• Coverage appears incorrect for specific functions
• You need to understand why a function isn’t matched in coverage data
• Debugging LCOV line mapping issues

Example:

# Explain coverage for a specific function
debtmap explain-coverage src/ --coverage-file coverage.lcov --function "process_file"

# Narrow search to specific file with verbose output
debtmap explain-coverage . --lcov lcov.info --function "analyze_complexity" --file "src/analyzer.rs" -v

# JSON output for automation
debtmap explain-coverage . --coverage-file coverage.lcov --function "my_function" --format json

Options

Options are organized by category for clarity. Most options apply to the analyze command, with a subset available for validate.

Output Control

Control how analysis results are formatted and displayed.

Format Options:

• -f, --format <FORMAT> - Output format: json, markdown, terminal, html, dot (default: terminal for analyze)
  • json - JSON format for programmatic processing
  • markdown - Markdown format with comprehensive analysis (uses LLM-optimized writer)
  • terminal - Human-readable terminal output with colors and formatting
  • html - HTML format for web display
  • dot - Graphviz DOT format for dependency visualization
• -o, --output <OUTPUT> - Output file path (defaults to stdout)
• --plain - Plain output mode: ASCII-only, no colors, no emoji, machine-parseable

Display Filtering:

• --top <N> / --head <N> - Show only top N priority items
• --tail <N> - Show only bottom N priority items (lowest priority)
• -s, --summary - Use summary format with tiered priority display (compact output)
• -c, --compact - Use compact output format (minimal details, top metrics only). Conflicts with verbosity flags (-v, -vv, -vvv). Only available in analyze command (note: validate uses -c for --config)
• --min-priority <PRIORITY> - Minimum priority to display: low, medium, high, critical
• --min-score <N> - Minimum score threshold for filtering T3/T4 recommendations (default: 3.0)
  • T1 Critical Architecture and T2 Complex Untested items bypass this filter and are always shown
  • Overrides config file setting (Spec 193, 205)
• --show-filter-stats - Show filter statistics (how many items were filtered and why)
• --filter <CATEGORIES> - Filter by debt categories (comma-separated)
• --aggregate-only - Show only aggregated file-level scores
• --group-by-category - Group output by debt category

Progress Display:

• --no-tui - Disable TUI progress visualization (use simple progress bars instead)
• -q, --quiet - Suppress progress output (quiet mode)

Streaming Output:

• --streaming - Enable streaming output mode for large codebases (Spec 003)
  • Streams results to output as they’re generated with O(1) memory overhead
  • Useful for processing large codebases that would otherwise exhaust memory
• --stream-to <FILE> - Output file for streaming mode (requires –streaming)
  • Use “-” for stdout

Dependency Display Options:

• --show-dependencies - Show caller/callee information in output
• --no-dependencies - Hide dependency information (conflicts with –show-dependencies)
• --max-callers <N> - Maximum number of callers to display (default: 5)
• --max-callees <N> - Maximum number of callees to display (default: 5)
• --show-external-calls - Include external crate calls in dependencies
• --show-std-lib-calls - Include standard library calls in dependencies

Analysis Control

Configure analysis behavior, thresholds, and language selection.

Thresholds:

• --threshold-complexity <N> - Complexity threshold (default: 10) [analyze command]
• --threshold-duplication <N> - Duplication threshold in lines (default: 50) [analyze command]
• --threshold-preset <PRESET> - Complexity threshold preset: strict, balanced, lenient [analyze command]
  • strict - Strict thresholds for high code quality standards
  • balanced - Balanced thresholds for typical projects (default)
  • lenient - Lenient thresholds for legacy or complex domains
• --max-debt-density <N> - Maximum debt density allowed per 1000 LOC [validate command]

Note: Threshold options (--threshold-complexity, --threshold-duplication, --threshold-preset) are command-line options for the analyze command. For the validate command, these thresholds are configured via the --config file (.debtmap.toml) rather than as command-line flags.

Language Selection:

• --languages <LANGS> - Comma-separated list of languages to analyze
  • Example: --languages rust,python,javascript
  • Supported: rust, python, javascript, typescript

Analysis Modes:

• --semantic-off - Disable semantic analysis (fallback mode)
• --no-context-aware - Disable context-aware false positive reduction (enabled by default)
• --no-multi-pass - Disable multi-pass analysis (use single-pass for performance)
• --attribution - Show complexity attribution details (requires multi-pass, which is the default)

Functional Programming Analysis:

• --ast-functional-analysis - Enable AST-based functional composition analysis (spec 111)
  • Analyzes code for functional programming patterns and composition
  • Detects pure functions, immutability, and side effects
• --functional-analysis-profile <PROFILE> - Set functional analysis profile
  • strict - Strict functional purity requirements (for pure FP codebases)
  • balanced - Balanced analysis suitable for mixed paradigms (default)
  • lenient - Lenient thresholds for imperative codebases

Context & Coverage

Enable context-aware risk analysis and integrate test coverage data.

Context-Aware Risk Analysis:

• --context / --enable-context - Enable context-aware risk analysis
• --context-providers <PROVIDERS> - Context providers to use (comma-separated)
  • Available: critical_path, dependency, git_history
  • Example: --context-providers critical_path,git_history
• --disable-context <PROVIDERS> - Disable specific context providers (comma-separated)

Coverage Integration:

• --coverage-file <PATH> / --lcov <PATH> - LCOV coverage file for risk analysis
  • Coverage data dampens debt scores for well-tested code (multiplier = 1.0 - coverage)
  • Surfaces untested complex functions as higher priority
  • Total debt score with coverage ≤ score without coverage
• --validate-loc - Validate LOC consistency across analysis modes (with/without coverage)

Performance

Optimize analysis performance through parallelization.

Parallel Processing:

• --no-parallel - Disable parallel call graph construction (enabled by default)
• -j, --jobs <N> - Number of threads for parallel processing
  • 0 = use all available CPU cores (default)
  • Specify number to limit thread count

Other Performance:

• --max-files <N> - Maximum number of files to analyze (0 = no limit)

Profiling:

• --profile - Enable profiling to identify performance bottlenecks (Spec 001)
  • Outputs timing breakdown for each analysis phase when complete
• --profile-output <FILE> - Write profiling data to file in JSON format (requires –profile)
  • Use for post-analysis performance investigation

Debugging & Verbosity

Control diagnostic output and debugging information.

Verbosity Levels:

• -v, --verbose - Increase verbosity level (can be repeated: -v, -vv, -vvv)
  • -v - Show main score factors
  • -vv - Show detailed calculations
  • -vvv - Show all debug information

Specialized Debugging:

• --explain-metrics - Explain metric definitions and formulas (measured vs estimated)
• --verbose-macro-warnings - Show verbose macro parsing warnings (Rust analysis)
• --show-macro-stats - Show macro expansion statistics at end of analysis
• --detail-level <LEVEL> - Detail level for diagnostic reports
  • Options: summary, standard, comprehensive, debug (default: standard)

Call Graph Debugging:

• --debug-call-graph - Enable detailed call graph debugging with resolution information
• --trace-function <FUNCTIONS> - Trace specific functions during call resolution (comma-separated)
  • Example: --trace-function 'my_function,another_function'
• --call-graph-stats - Show only call graph statistics (no detailed failure list)
• --validate-call-graph - Validate call graph structure and report issues
• --debug-format <FORMAT> - Debug output format: text or json (default: text)
  • Use with call graph debugging flags to control output format

Aggregation

Control file-level aggregation and god object detection.

File Aggregation:

• --aggregate-only - Show only aggregated file-level scores
• --no-aggregation - Disable file-level aggregation
• --aggregation-method <METHOD> - File aggregation method (default: weighted_sum)
  • Options: sum, weighted_sum, logarithmic_sum, max_plus_average
• --min-problematic <N> - Minimum number of problematic functions for file aggregation
• --no-god-object - Disable god object detection

God Object Split Recommendations:

• --show-splits - Show detailed module split recommendations for god objects and large files (experimental)
  • Suggests how to decompose large files into smaller, focused modules
• --min-split-methods <N> - Minimum methods per god object split recommendation (default: 10)
• --min-split-lines <N> - Minimum lines per god object split recommendation (default: 150)

Dead Code Analysis:

• --no-public-api-detection - Disable public API detection heuristics for dead code analysis
• --public-api-threshold <N> - Public API confidence threshold (0.0-1.0, default: 0.7)
  • Functions above this threshold are considered public APIs

Pattern Detection:

• --no-pattern-detection - Disable pattern recognition
• --patterns <PATTERNS> - Enable specific patterns only (comma-separated)
  • Available patterns: observer, singleton, factory, strategy, callback, template_method
• --pattern-threshold <N> - Pattern confidence threshold (0.0-1.0, default: 0.7)
• --show-pattern-warnings - Show pattern warnings for uncertain detections

Option Aliases

Common option shortcuts and aliases for convenience:

• --lcov is alias for --coverage-file
• --enable-context is alias for --context
• --head is alias for --top
• -s is short form for --summary
• -v is short form for --verbose
• -f is short form for --format
• -o is short form for --output
• -c is short form for --config
• -j is short form for --jobs

Deprecated Options

The following options are deprecated and should be migrated:

• --explain-score (hidden) - Deprecated: use -v instead
  • Migration: Use -v, -vv, or -vvv for increasing verbosity levels

Configuration

Configuration File

Created via debtmap init command. The configuration file (.debtmap.toml) is used by the validate command for threshold enforcement and default settings.

Creating Configuration:

# Create new config
debtmap init

# Overwrite existing config
debtmap init --force

Environment Variables

• DEBTMAP_CONFIG - Custom config file path (same as --config global flag)

  • Example: export DEBTMAP_CONFIG=/path/to/debtmap.toml
  • Overrides default configuration file locations
  • Useful for CI/CD environments with centralized config
  • Source: src/cli.rs:45

• DEBTMAP_JOBS - Number of threads for parallel processing (same as --jobs / -j flag)

  • Example: export DEBTMAP_JOBS=8 # Same as --jobs 8
  • Use 0 to utilize all available CPU cores
  • Controls thread pool size for parallel call graph construction

• DEBTMAP_SINGLE_PASS - Disable multi-pass analysis globally (same as --no-multi-pass flag)

  • Example: export DEBTMAP_SINGLE_PASS=1 # Disable multi-pass analysis
  • Set to 1 or true to disable multi-pass analysis by default
  • Useful for CI/CD environments where performance is critical
  • Can be overridden by command-line flags

• PRODIGY_AUTOMATION - Enable automation mode for validate-improvement command

  • Example: export PRODIGY_AUTOMATION=true
  • Set to true to enable automation mode (suppresses interactive prompts)
  • Used in automated workflows for continuous improvement validation
  • Source: src/main.rs:549

• PRODIGY_VALIDATION - Alternative flag for automation mode (same effect as PRODIGY_AUTOMATION)

  • Example: export PRODIGY_VALIDATION=true
  • Set to true to enable automation mode
  • Provided for backward compatibility with existing workflows
  • Source: src/main.rs:552

Getting Help

Get help for any command:

# General help
debtmap --help

# Command-specific help
debtmap analyze --help
debtmap validate --help
debtmap compare --help
debtmap init --help

Common Workflows

Basic Analysis

Analyze a project and view results in terminal:

debtmap analyze src/

Generate JSON report for further processing:

debtmap analyze . --format json --output report.json

Generate Markdown report:

debtmap analyze . --format markdown --output report.md

Coverage-Integrated Analysis

Analyze with test coverage to surface untested complex code:

# Generate coverage file first (example for Rust)
cargo tarpaulin --out lcov

# Run analysis with coverage
debtmap analyze src/ --coverage-file lcov.info

Coverage dampens debt scores for well-tested code, making untested complex functions more visible.

Context-Aware Analysis

Enable context providers for risk-aware prioritization:

# Use all context providers
debtmap analyze . --context

# Use specific context providers
debtmap analyze . --context --context-providers critical_path,git_history

Context-aware analysis reduces false positives and prioritizes code based on:

• Critical execution paths
• Dependency relationships
• Git history (change frequency)

Filtered & Focused Analysis

Show only top priority items:

debtmap analyze . --top 10 --min-priority high

Filter by specific debt categories:

debtmap analyze . --filter complexity,duplication

Use summary mode for compact output:

debtmap analyze . --summary

Show only file-level aggregations:

debtmap analyze . --aggregate-only

Performance Tuning

Control parallelization:

# Use 8 threads
debtmap analyze . --jobs 8

# Disable parallel processing
debtmap analyze . --no-parallel

Limit analysis scope:

# Analyze maximum 100 files
debtmap analyze . --max-files 100

# Analyze specific languages only
debtmap analyze . --languages rust,python

CI/CD Integration

Use the validate command in CI/CD pipelines:

# Initialize configuration (one time)
debtmap init

# Edit debtmap.toml to set thresholds
# ...

# In CI pipeline: validate against thresholds
debtmap validate . --config debtmap.toml --max-debt-density 50

The validate command returns non-zero exit code if thresholds are exceeded, failing the build.

Comparison & Tracking

Compare analysis results before and after changes:

# Before changes
debtmap analyze . --format json --output before.json

# Make code changes...

# After changes
debtmap analyze . --format json --output after.json

# Generate comparison report
debtmap compare --before before.json --after after.json --format markdown

With implementation plan:

debtmap compare --before before.json --after after.json --plan IMPLEMENTATION_PLAN.md

Debugging Analysis

Increase verbosity to understand scoring:

# Show main score factors
debtmap analyze src/ -v

# Show detailed calculations
debtmap analyze src/ -vv

# Show all debug information
debtmap analyze src/ -vvv

Debug call graph resolution issues:

# Enable call graph debugging
debtmap analyze . --debug-call-graph

# Trace specific functions
debtmap analyze . --debug-call-graph --trace-function 'problematic_function'

# Validate call graph structure
debtmap analyze . --validate-call-graph --debug-format json

Show macro expansion statistics (Rust):

debtmap analyze . --show-macro-stats --verbose-macro-warnings

Use detailed diagnostic reports:

debtmap analyze . --detail-level comprehensive

Analyze functional programming patterns:

# Enable functional analysis
debtmap analyze . --ast-functional-analysis

# Use strict profile for pure FP codebases
debtmap analyze . --ast-functional-analysis --functional-analysis-profile strict

Examples

Basic Analysis

# Analyze current directory
debtmap analyze .

# Analyze specific directory
debtmap analyze src/

# Generate JSON output
debtmap analyze . --format json --output report.json

With Coverage

# Analyze with LCOV coverage file
debtmap analyze src/ --coverage-file coverage.lcov

# Alternative alias
debtmap analyze src/ --lcov coverage.lcov

Context-Aware Analysis

# Enable all context providers
debtmap analyze . --context

# Use specific context providers
debtmap analyze . --context --context-providers critical_path,git_history

# Disable specific providers
debtmap analyze . --context --disable-context dependency

Filtered Output

# Top 10 priority items only
debtmap analyze . --top 10

# High priority and above
debtmap analyze . --min-priority high

# Specific categories
debtmap analyze . --filter complexity,duplication

# Summary format
debtmap analyze . --summary

# Group by category
debtmap analyze . --group-by-category

Performance Tuning

# Use 8 threads
debtmap analyze . --jobs 8

# Disable parallelization
debtmap analyze . --no-parallel

# Limit file count
debtmap analyze . --max-files 100

Validation

# Initialize config
debtmap init --force

# Validate against config
debtmap validate . --config debtmap.toml

# With max debt density threshold
debtmap validate . --max-debt-density 50

Comparison

# Compare two analyses
debtmap compare --before before.json --after after.json

# With markdown output
debtmap compare --before before.json --after after.json --format markdown

# With implementation plan
debtmap compare --before before.json --after after.json --plan IMPLEMENTATION_PLAN.md

# With target location
debtmap compare --before before.json --after after.json --target-location "src/main.rs:process_file:42"

Language Selection

# Analyze only Rust files
debtmap analyze . --languages rust

# Multiple languages
debtmap analyze . --languages rust,python,javascript

Threshold Configuration

# Custom complexity threshold
debtmap analyze . --threshold-complexity 15

# Use preset
debtmap analyze . --threshold-preset strict

# Custom duplication threshold
debtmap analyze . --threshold-duplication 100

Plain/Machine-Readable Output

# Plain output (no colors, no emoji)
debtmap analyze . --plain

# Combine with JSON for CI
debtmap analyze . --format json --plain --output report.json

Advanced Debugging

# Call graph debugging with detailed information
debtmap analyze . --debug-call-graph --debug-format json

# Trace specific functions during call resolution
debtmap analyze . --debug-call-graph --trace-function 'process_file,analyze_complexity'

# Validate call graph structure
debtmap analyze . --validate-call-graph

# Show only call graph statistics
debtmap analyze . --debug-call-graph --call-graph-stats

# Functional programming analysis with strict profile
debtmap analyze . --ast-functional-analysis --functional-analysis-profile strict

# Explain metric definitions
debtmap analyze . --explain-metrics -v

Command Compatibility Matrix

Note: The validate command supports output control (--format, --output), coverage integration (--coverage-file), context-aware analysis (--context), display filtering (--top, --tail, --summary, --show-splits), performance control (--jobs, --no-parallel), and verbosity options (--verbose) from the analyze command. Analysis thresholds (--threshold-complexity, --threshold-duplication, --threshold-preset) are configured via the --config file rather than as command-line options. Debugging features like call graph debugging, functional analysis, profiling, and pattern detection are specific to the analyze command. The diagnose-coverage and explain-coverage commands are specialized debugging tools for diagnosing coverage issues and have their own unique options.

Troubleshooting

Performance Issues

Problem: Analysis is slow on large codebases

Solutions:

# Use more threads (if you have CPU cores available)
debtmap analyze . --jobs 16

# Limit analysis scope
debtmap analyze . --max-files 500 --languages rust

Memory Issues

Problem: Analysis runs out of memory

Solutions:

# Disable parallelization
debtmap analyze . --no-parallel

# Limit file count
debtmap analyze . --max-files 100

# Analyze in batches by language
debtmap analyze . --languages rust
debtmap analyze . --languages python

Output Issues

Problem: Terminal output has garbled characters

Solution:

# Use plain mode
debtmap analyze . --plain

Problem: Want machine-readable output

Solution:

# Use JSON with plain mode
debtmap analyze . --format json --plain --output report.json

Threshold Issues

Problem: Too many items flagged

Solutions:

# Use lenient preset
debtmap analyze . --threshold-preset lenient

# Increase threshold
debtmap analyze . --threshold-complexity 20

# Filter to high priority only
debtmap analyze . --min-priority high

Problem: Not enough items flagged

Solutions:

# Use strict preset
debtmap analyze . --threshold-preset strict

# Lower threshold
debtmap analyze . --threshold-complexity 5

# Show all items
debtmap analyze . --min-priority low

Best Practices

Regular Analysis

Run analysis regularly to track code quality trends:

# Daily in CI
debtmap validate . --config debtmap.toml

# Weekly deep analysis with coverage
debtmap analyze . --coverage-file coverage.lcov --format json --output weekly-report.json

Performance Optimization

For large codebases:

# Use maximum parallelization
debtmap analyze . --jobs 0  # 0 = all cores

# Focus on changed files in CI
# (implement via custom scripts to analyze git diff)

Integration with Coverage

Always analyze with coverage when available:

# Rust example
cargo tarpaulin --out lcov
debtmap analyze src/ --coverage-file lcov.info

# Python example
pytest --cov --cov-report=lcov
debtmap analyze . --coverage-file coverage.lcov

Coverage integration helps prioritize untested complex code.

Additional Tools

prodigy-validate-debtmap-improvement

Specialized validation tool for Prodigy workflow integration.

Description: This binary is part of the Prodigy workflow system and provides specialized validation for Debtmap improvement workflows.

Usage: See Prodigy documentation for detailed usage instructions.

See Also

• Configuration Format - Detailed configuration file format
• Output Formats - Understanding JSON, Markdown, and Terminal output
• Coverage Integration - Integrating test coverage data
• Context Providers - Understanding context-aware analysis
• Examples - More comprehensive usage examples

Analysis Guide

This guide explains Debtmap’s analysis capabilities, metrics, and methodologies in depth. Use this to understand what Debtmap measures, how it scores technical debt, and how to interpret analysis results for maximum impact.

Subsections

This chapter is organized into the following subsections:

• Overview - Introduction to analysis capabilities and overall approach
• Complexity Metrics - Comprehensive coverage of cyclomatic, cognitive, and entropy-based complexity with extensive examples
• Debt Patterns - Detailed documentation of all debt pattern types with detection criteria
• Risk Scoring - Risk calculation methodology, scoring formulas, and prioritization strategies
• Interpreting Results - Result interpretation, action strategies, and detailed examples
• Analyzer Types - Documentation of different analyzer modes and their use cases
• Advanced Features - Advanced analysis capabilities and techniques
• Example Outputs - Real-world output examples and interpretation guidance

Overview

Debtmap analyzes code through multiple lenses to provide a comprehensive view of technical health. The goal is to move beyond simple problem identification to evidence-based prioritization - showing what to fix first based on risk scores, test coverage gaps, and ROI calculations, with actionable recommendations backed by impact metrics.

Supported Languages

• Rust - Full analysis support with AST-based parsing via syn
• Python - File detection only; analysis not yet implemented (language enum defined for future expansion)

Source: src/organization/language.rs:4-7 (Language enum), src/analyzers/implementations.rs:185-186 (analysis status)

Analysis Capabilities

Complexity Metrics

Calculates multiple dimensions of code complexity:

• Cyclomatic Complexity - Measures linearly independent paths through code (control flow branching)
• Cognitive Complexity - Quantifies human comprehension difficulty beyond raw paths
• Nesting Depth - Tracks maximum indentation levels
• Function Length - Lines of code per function
• Parameter Count - Number of function parameters
• Entropy Score - Pattern-based complexity adjustment that reduces false positives by up to 70%
• Purity Level - Functional purity classification (StrictlyPure, LocallyPure, ReadOnly, Impure)

Source: src/core/mod.rs:62-92 (FunctionMetrics struct)

See Complexity Metrics for detailed explanations and examples.

Debt Patterns

Identifies 35 types of technical debt across 4 major categories:

Testing Issues (6 types):

• Testing gaps in complex code
• Complex test code requiring refactoring
• Test duplication and flaky patterns
• Over-complex assertions

Architectural Problems (7 types):

• God objects and god modules
• Feature envy and primitive obsession
• Scattered type implementations
• Orphaned functions and utilities sprawl

Performance Issues (8 types):

• Async/await misuse and blocking I/O
• Collection inefficiencies and nested loops
• Memory allocation problems
• Suboptimal data structures

Code Quality Issues (6 types):

• Complexity hotspots without test coverage
• Dead code and duplication
• Error swallowing and magic values

Source: src/priority/debt_types.rs:47 (DebtType enum)

See Debt Patterns for detailed detection rules and examples.

Risk Scoring

Combines complexity, test coverage, coupling, and change frequency through a multi-factor risk model:

Risk Categories:

• Critical - High complexity (>15) + low coverage (<30%)
• High - High complexity (>10) + moderate coverage (<60%)
• Medium - Moderate complexity (>5) + low coverage (<50%)
• Low - Low complexity or high coverage
• WellTested - High complexity with high coverage (good examples to learn from)

Coverage Penalty Calculation:

• Untested code receives a 2.0x multiplier
• Partially tested code receives a 1.5x multiplier
• Coverage gaps are penalized exponentially

Risk Score Weights (configurable):

#![allow(unused)]
fn main() {
coverage:          0.5   // Coverage weight
complexity:        0.3   // Cyclomatic weight
cognitive:         0.45  // Cognitive weight
debt:              0.2   // Debt factor weight
untested_penalty:  2.0   // Multiplier for untested code
}

Source: src/risk/mod.rs:36-42, src/risk/strategy.rs:8-28

See Risk Scoring for detailed scoring algorithms.

Prioritization

Uses a multi-stage pipeline to assign priority tiers and estimate test writing impact:

1. Evidence Collection - Gather complexity, coverage, and coupling metrics
2. Context Enrichment - Add architectural context and change frequency
3. Baseline Scoring - Calculate initial risk scores using multi-factor model
4. ROI Calculation - Estimate return on investment for test writing
5. Final Priority - Assign priority tiers with risk reduction impact estimates

Recommendation Tiers (based on strategic value):

• T1 Critical Architecture - God objects, excessive complexity; must address before adding features
• T2 Complex Untested - High complexity with no tests; risk of bugs in critical paths
• T3 Testing Gaps - Moderate complexity without tests; improve coverage to prevent future issues
• T4 Maintenance - Low-complexity issues; address opportunistically

Source: src/priority/tiers/mod.rs:29-45 (RecommendationTier enum)

See Interpreting Results for guidance on using priority rankings.

How It Works

Debtmap uses a functional, multi-layered architecture for accurate and performant analysis:

Three-Phase Analysis Pipeline

Phase 1: Parallel Parsing

• Language-specific AST generation using tree-sitter (Rust via syn)
• Pure functional transformation: source code → AST
• Files parsed once, ASTs cached and cloned for reuse (44% faster)
• Runs in parallel using Rayon for CPU-intensive parsing

Phase 2: Parallel Analysis with Batching

• Data flow graph construction (O(1) lookups via multi-index)
• Purity analysis tracking pure vs impure functions
• Pattern detection with entropy analysis
• Metrics computation through pure functions
• Default batch size: 100 items (configurable via --batch-size)

Phase 3: Sequential Aggregation

• Combine parallel results into unified analysis
• Apply multi-dimensional scoring (complexity + coverage + coupling)
• Priority ranking and tier classification
• Generate actionable recommendations with impact metrics

Source: ARCHITECTURE.md, src/builders/parallel_unified_analysis.rs:21-87

Key Architectural Patterns

Functional Core, Imperative Shell:

• Pure functions for all metric calculations
• I/O isolated to file reading and output formatting
• Enables easy testing and parallelization

Multi-Index Call Graph (O(1) lookups):

• Primary index: exact function ID lookup
• Fuzzy index: name + file matching for generics
• Name index: cross-file function resolution
• Memory overhead: ~7MB for 10,000 functions

Parallel Processing with Rayon:

• CPU-bound work runs in parallel
• Sequential aggregation maintains consistency
• Adaptive batching optimizes memory usage

Source: ARCHITECTURE.md:120-200

See Architecture for detailed design documentation.

Key Differentiators

What makes debtmap effective:

• Pattern-Based Complexity Adjustment - Entropy analysis reduces false positives by identifying boilerplate patterns
• Multi-Pass Analysis - Compares raw vs normalized complexity for accurate attribution
• Coverage-Risk Correlation - Finds genuinely risky code, not just complex code
• Functional Purity Tracking - Identifies side effects and pure functions for targeted refactoring
• Context-Aware Detection - Considers architectural context, not just isolated metrics
• Evidence-Based Prioritization - ROI-driven recommendations backed by multiple signals

Performance

Debtmap achieves high throughput through parallel processing:

Source: ARCHITECTURE.md:100-106

See Parallel Processing for optimization details.

Complexity Metrics

Debtmap measures complexity using multiple complementary approaches. Each metric captures a different aspect of code difficulty.

Cyclomatic Complexity

Measures the number of linearly independent paths through code - essentially counting decision points.

How it works:

• Start with a base complexity of 1
• Add 1 for each: if, else if, match arm, while, for, &&, ||, ? operator
• Does NOT increase for else (it’s the alternate path, not a new decision)

Thresholds:

• 1-5: Simple, easy to test - typically needs 1-3 test cases
• 6-10: Moderate complexity - needs 4-8 test cases
• 11-20: Complex, consider refactoring - needs 9+ test cases
• 20+: Very complex, high risk - difficult to test thoroughly

Example:

#![allow(unused)]
fn main() {
fn validate_user(age: u32, has_license: bool, country: &str) -> bool {
    // Complexity: 4
    // Base (1) + if (1) + && (1) + match (1) = 4
    if age >= 18 && has_license {
        match country {
            "US" | "CA" => true,
            _ => false,
        }
    } else {
        false
    }
}
}

Cognitive Complexity

Measures how difficult code is to understand by considering nesting depth and control flow interruptions.

How it differs from cyclomatic:

• Nesting increases weight (deeply nested code is harder to understand)
• Linear sequences don’t increase complexity (easier to follow)
• Breaks and continues add complexity (interrupt normal flow)

Calculation:

• Each structure (if, loop, match) gets a base score
• Nesting increases weight linearly: Each nesting level adds to the complexity score
  • Base level (no nesting): weight = 1
  • First nesting level: weight = 2
  • Second nesting level: weight = 3
  • Formula: complexity = 1 + nesting_level (from src/complexity/cognitive.rs:167)
• Break/continue/return in middle of function adds cognitive load

Example:

#![allow(unused)]
fn main() {
// Cyclomatic: 5, Cognitive: 8
fn process_items(items: Vec<Item>) -> Vec<Result> {
    let mut results = vec![];

    for item in items {                    // +1 cognitive
        if item.is_valid() {               // +2 (nested in loop)
            match item.type {              // +3 (nested 2 levels)
                Type::A => results.push(process_a(item)),
                Type::B => {
                    if item.priority > 5 { // +4 (nested 3 levels)
                        results.push(process_b_priority(item));
                    }
                }
                _ => continue,             // +1 (control flow interruption)
            }
        }
    }

    results
}
}

Thresholds:

• 0-5: Trivial - anyone can understand
• 6-10: Simple - straightforward logic
• 11-20: Moderate - requires careful reading
• 21-40: Complex - difficult to understand
• 40+: Very complex - needs refactoring

Entropy-Based Complexity Analysis

Uses information theory to distinguish genuinely complex code from pattern-based repetitive code. This dramatically reduces false positives for validation functions, dispatchers, and configuration parsers.

How it works:

1. Token Entropy (0.0-1.0): Measures variety in code tokens

   • High entropy (0.7+): Diverse logic, genuinely complex
   • Low entropy (0.0-0.4): Repetitive patterns, less complex than it appears

2. Pattern Repetition (0.0-1.0): Detects repetitive structures in AST

   • High repetition (0.7+): Similar blocks repeated (validation checks, case handlers)
   • Low repetition: Unique logic throughout

3. Branch Similarity (0.0-1.0): Analyzes similarity between conditional branches

   • High similarity (0.8+): Branches do similar things (consistent handling)
   • Low similarity: Each branch has unique logic

4. Token Classification: Categorizes tokens by type with weighted importance (src/complexity/entropy_core.rs:267-277)

   • Token categories and weights (from src/complexity/entropy_traits.rs:24-44):
     • ControlFlow (1.2): if, match, for, while - highest weight for control structures
     • Keyword (1.0): language keywords like fn, let, pub
     • FunctionCall (0.9): method calls and API usage
     • Operator (0.8): +, -, *, ==, etc.
     • Identifier (0.5): variable and function names
     • Literal (0.3): string, number, boolean literals - lowest weight
   • Higher weights emphasize structural complexity over superficial differences
   • Focuses entropy calculation on control flow and logic rather than data values

Dampening logic: Dampening is applied when multiple factors indicate repetitive patterns:

• Low token entropy (< 0.4) indicates simple, repetitive patterns
• High pattern repetition (> 0.6) shows similar code blocks (measured via PatternMetrics)
• High branch similarity (> 0.7) indicates consistent branching logic

Pattern detection (src/complexity/entropy_core.rs:279-308):

• PatternMetrics tracks intermediate calculations:
  • total_patterns: Total number of code patterns detected
  • unique_patterns: Count of distinct patterns
  • repetition_ratio: Calculated as 1.0 - (unique_patterns / total_patterns)
• High repetition ratio indicates validation functions, dispatchers, and configuration parsers

When these conditions are met:

effective_complexity = entropy × pattern_factor × similarity_factor

Note on metrics (src/complexity/entropy_core.rs:228-265):

• token_entropy: Measures unpredictability of code tokens (0.0-1.0), used for pattern detection
• effective_complexity: Final composite score after applying dampening adjustments
• These are distinct metrics - effective_complexity combines multiple factors, while token_entropy is a single entropy measurement

Dampening cap: The dampening factor is clamped between 0.5 and 1.0 (src/complexity/entropy_core.rs:114), allowing a maximum of 50% complexity reduction. The configuration option max_combined_reduction (default 0.30) provides additional control over the maximum allowed reduction. This prevents over-correction of pattern-based code while still providing meaningful adjustments for repetitive structures.

Example:

#![allow(unused)]
fn main() {
// Without entropy: Cyclomatic = 15 (appears very complex)
// With entropy: Effective = 8 (pattern-based, dampened ~47%)
fn validate_config(config: &Config) -> Result<(), ValidationError> {
    if config.name.is_empty() { return Err(ValidationError::EmptyName); }
    if config.port == 0 { return Err(ValidationError::InvalidPort); }
    if config.host.is_empty() { return Err(ValidationError::EmptyHost); }
    if config.timeout == 0 { return Err(ValidationError::InvalidTimeout); }
    // ... 11 more similar checks
    Ok(())
}
}

Enable in .debtmap.toml:

[entropy]
enabled = true                 # Enable entropy analysis (default: true)
weight = 0.5                  # Weight in adjustment (0.0-1.0)
use_classification = true     # Advanced token classification
pattern_threshold = 0.7       # Pattern detection threshold
entropy_threshold = 0.4       # Entropy below this triggers dampening
branch_threshold = 0.8        # Branch similarity threshold
max_combined_reduction = 0.3  # Maximum 30% reduction

Output fields in EntropyScore:

• unique_variables: Count of distinct variables in the function (measures variable diversity)
• max_nesting: Maximum nesting depth detected (contributes to dampening calculation)
• dampening_applied: Actual dampening factor applied to the complexity score

Nesting Depth

Maximum level of indentation in a function. Deep nesting makes code hard to follow.

Thresholds:

• 1-2: Flat, easy to read
• 3-4: Moderate nesting
• 5+: Deep nesting, consider extracting functions

Example:

#![allow(unused)]
fn main() {
// Nesting depth: 4 (difficult to follow)
fn process(data: Data) -> Result<Output> {
    if data.is_valid() {                    // Level 1
        for item in data.items {            // Level 2
            if item.active {                // Level 3
                match item.type {           // Level 4
                    Type::A => { /* ... */ }
                    Type::B => { /* ... */ }
                }
            }
        }
    }
}
}

Refactored:

#![allow(unused)]
fn main() {
// Nesting depth: 2 (much clearer)
fn process(data: Data) -> Result<Output> {
    if !data.is_valid() {
        return Err(Error::Invalid);
    }

    data.items
        .iter()
        .filter(|item| item.active)
        .map(|item| process_item(item))     // Extract to separate function
        .collect()
}
}

Function Length

Number of lines in a function. Long functions often violate single responsibility principle.

Thresholds:

• 1-20 lines: Good - focused, single purpose
• 21-50 lines: Acceptable - may have multiple steps
• 51-100 lines: Long - consider breaking up
• 100+ lines: Very long - definitely needs refactoring

Why length matters:

• Harder to understand and remember
• Harder to test thoroughly
• Often violates single responsibility
• Difficult to reuse

Constructor Detection

Debtmap identifies constructor functions using AST-based analysis (Spec 122), which goes beyond simple name-based detection to catch non-standard constructor patterns.

Detection Strategy:

1. Return Type Analysis: Functions returning Self, Result<Self>, or Option<Self>
2. Body Pattern Analysis: Struct initialization or simple field assignments
3. Complexity Check: Low cyclomatic complexity (≤5), no loops, minimal branching

Why AST-based detection?

Name-based detection (looking for new, new_*, from_*) misses non-standard constructors:

#![allow(unused)]
fn main() {
// Caught by name-based detection
fn new() -> Self {
    Self { timeout: 30 }
}

// Missed by name-based, caught by AST detection
pub fn create_default_client() -> Self {
    Self { timeout: Duration::from_secs(30) }
}

pub fn initialized() -> Self {
    Self::new()
}
}

Builder vs Constructor:

AST analysis distinguishes between constructors and builder methods:

#![allow(unused)]
fn main() {
// Constructor: creates new instance
pub fn new(timeout: u32) -> Self {
    Self { timeout }
}

// Builder method: modifies existing instance (NOT a constructor)
pub fn set_timeout(mut self, timeout: Duration) -> Self {
    self.timeout = timeout;
    self  // Returns modified self, not new instance
}
}

Detection Criteria:

A function is classified as a constructor if:

• Returns Self, Result<Self>, or Option<Self>
• Contains struct initialization (Self { ... }) without loops
• OR delegates to another constructor (Self::new()) with minimal logic

Fallback Behavior:

If AST parsing fails (syntax errors, unsupported language), Debtmap gracefully falls back to name-based detection (Spec 117):

• new, new_*
• try_new*
• from_*

This ensures analysis always completes, even on partially broken code.

Performance:

AST-based detection adds < 5% overhead compared to name-only detection. See benchmarks:

cargo bench --bench constructor_detection_bench

Why it matters:

Accurately identifying constructors helps:

• Exclude them from complexity thresholds (constructors naturally have high complexity)
• Focus refactoring on business logic, not initialization code
• Understand initialization patterns across the codebase

Debt Patterns

Debtmap detects 35 types of technical debt, organized into 4 strategic categories. Each debt type is mapped to a category that guides prioritization and remediation strategies.

The 35 debt types consist of:

• 26 priority-specific variants: Specialized debt patterns with detailed diagnostic data
• 9 legacy variants: Backward-compatible types from earlier versions (prefer specialized variants)

Source: DebtType enum defined in src/priority/debt_types.rs:47-205, category mappings in src/priority/mod.rs:216-254

Debt Type Enum

The DebtType enum defines all specific debt patterns that Debtmap can detect.

Note: Each DebtType variant carries structured diagnostic data specific to that pattern. For example, ComplexityHotspot includes cyclomatic and cognitive fields that provide detailed metrics for the detected issue. This structured data enables precise prioritization.

Source: DebtType structure defined in src/priority/debt_types.rs:47-205

Priority-Specific Debt Types (26 types)

These are the primary debt types with specialized detection logic and detailed diagnostic data.

Testing Debt (6 types):

• TestingGap - Functions with insufficient test coverage (fields: coverage, cyclomatic, cognitive)
• TestTodo - TODO comments in test code (fields: priority, reason)
• TestDuplication - Duplicated code in test files (fields: instances, total_lines, similarity)
• TestComplexityHotspot - Complex test logic that’s hard to maintain (fields: cyclomatic, cognitive, threshold)
• AssertionComplexity - Complex test assertions (fields: assertion_count, complexity_score)
• FlakyTestPattern - Non-deterministic test behavior (fields: pattern_type, reliability_impact)

Architecture Debt (6 types):

• GodObject - Unified variant for classes/files/modules with too many responsibilities (fields: methods, fields, responsibilities, god_object_score, lines). The detection type (GodClass, GodFile, GodModule) is determined by god_object_indicators.detection_type in the parent structure.
• FeatureEnvy - Using more data from other objects than own (fields: external_class, usage_ratio)
• PrimitiveObsession - Overusing basic types instead of domain objects (fields: primitive_type, domain_concept)
• ScatteredType - Types with methods scattered across multiple files (fields: type_name, total_methods, file_count, severity as String)
• OrphanedFunctions - Functions that should be methods on a type (fields: target_type, function_count, file_count)
• UtilitiesSprawl - Utility modules with poor cohesion (fields: function_count, distinct_types)

Performance Debt (8 types):

• AllocationInefficiency - Inefficient memory allocations (fields: pattern, impact)
• StringConcatenation - Inefficient string building in loops (fields: loop_type, iterations)
• NestedLoops - Multiple nested iterations O(n²) or worse (fields: depth, complexity_estimate)
• BlockingIO - Blocking I/O in async contexts (fields: operation, context)
• SuboptimalDataStructure - Wrong data structure for access pattern (fields: current_type, recommended_type)
• AsyncMisuse - Improper async/await usage (fields: pattern, performance_impact)
• ResourceLeak - Resources not properly released (fields: resource_type, cleanup_missing)
• CollectionInefficiency - Inefficient collection operations (fields: collection_type, inefficiency_type)

Code Quality Debt (6 types):

• ComplexityHotspot - Functions exceeding complexity thresholds (fields: cyclomatic, cognitive)
• DeadCode - Unreachable or unused code (fields: visibility, cyclomatic, cognitive, usage_hints)
• MagicValues - Unexplained literal values (fields: value, occurrences)
• Risk - High-risk code combining complexity + poor test coverage (fields: risk_score, factors)
• Duplication - Duplicated code blocks (fields: instances, total_lines)
• ErrorSwallowing - Errors caught but ignored (fields: pattern, context)

Legacy Debt Types (9 types)

These variants are maintained for backward compatibility. For new analysis, prefer the specialized priority-specific variants listed above.

Source: Legacy variants defined in src/priority/debt_types.rs:48-77

Note: Legacy types are categorized under CodeQuality by default (see src/priority/mod.rs:251-252).

Debt Categories

The DebtCategory enum groups debt types into strategic categories:

Source: src/priority/mod.rs:196-213

#![allow(unused)]
fn main() {
pub enum DebtCategory {
    Architecture,  // Structure, design, complexity
    Testing,       // Coverage, test quality
    Performance,   // Speed, memory, efficiency
    CodeQuality,   // Maintainability, readability
}
}

Category Mapping

Source: Category assignment logic in src/priority/mod.rs:216-254

Note: GodObject is a unified variant that handles all god object detection types (GodClass, GodFile, GodModule). There is no separate GodModule debt type in the enum.

Language-Specific Debt Patterns:

Some debt patterns only apply to languages with specific features:

• BlockingIO, AsyncMisuse: Async-capable languages (Rust)
• AllocationInefficiency, ResourceLeak: Languages with manual memory management (Rust)
• Error handling patterns: Vary by language error model (Result in Rust)

Debtmap automatically applies only the relevant debt patterns during analysis.

Examples by Category

Architecture Debt

GodObject (unified variant for GodClass/GodFile/GodModule): Too many responsibilities

Source: src/priority/debt_types.rs:143-154

#![allow(unused)]
fn main() {
// God module: handles parsing, validation, storage, notifications
mod user_service {
    fn parse_user() { /* ... */ }
    fn validate_user() { /* ... */ }
    fn save_user() { /* ... */ }
    fn send_email() { /* ... */ }
    fn log_activity() { /* ... */ }
    // ... 20+ more functions
}
}

The GodObject debt type captures all god object patterns through a unified variant. The specific detection type (GodClass, GodFile, or GodModule) is stored in the parent UnifiedDebtItem.god_object_indicators.detection_type field:

When detected: Complexity-weighted scoring system (see detailed explanation below) Action: Split into focused modules (parser, validator, repository, notifier)

Complexity-Weighted God Object Detection

Debtmap uses complexity-weighted scoring for god object detection to reduce false positives on well-refactored code. This ensures that a file with 100 simple helper functions doesn’t rank higher than a file with 10 complex functions.

The Problem:

Traditional god object detection counts methods:

• File A: 100 methods (average complexity: 1.5) → Flagged as god object
• File B: 10 methods (average complexity: 17.0) → Not flagged

But File A might be a well-organized utility module with many small helpers, while File B is truly problematic with highly complex functions that need refactoring.

The Solution:

Debtmap weights each function by its cyclomatic complexity using this formula:

weight = (max(1, complexity) / 3)^1.5

Weight Examples:

• Simple helper (complexity 1): weight ≈ 0.19
• Baseline function (complexity 3): weight = 1.0
• Moderate function (complexity 9): weight ≈ 5.2
• Complex function (complexity 17): weight ≈ 13.5
• Critical function (complexity 33): weight ≈ 36.5

God Object Score Calculation:

weighted_method_count = sum(weight for each function)
complexity_penalty = 0.7 if avg_complexity < 3, 1.0 if 3-10, 1.5 if > 10

god_object_score = (
    (weighted_method_count / threshold) * 40% +
    (field_count / threshold) * 20% +
    (responsibility_count / threshold) * 15% +
    (lines_of_code / 500) * 25%
) * complexity_penalty

Threshold: God object detected if score >= 70.0

Real-World Example:

shared_cache.rs:
  - 100 functions, average complexity: 1.5
  - Weighted score: ~19.0 (100 * 0.19)
  - God object score: 45.2
  - Result: Not a god object ✓

legacy_parser.rs:
  - 10 functions, average complexity: 17.0
  - Weighted score: ~135.0 (10 * 13.5)
  - God object score: 87.3
  - Result: God object detected ✓

Benefits:

• Reduces false positives on utility modules with many simple functions
• Focuses attention on truly problematic complex modules
• Rewards good refactoring - breaking large functions into small helpers improves score
• Aligns with reality - complexity matters more than count for maintainability

How to View:

When Debtmap detects a god object, the output includes:

• Raw method count
• Weighted method count
• Average complexity
• God object score
• Recommended module splits based on responsibility clustering

Type Organization Debt

Source: Type organization patterns defined in src/priority/debt_types.rs:189-205 (Spec 187), detection logic in src/organization/codebase_type_analyzer.rs

These patterns detect issues with how types and their associated functions are organized across the codebase.

ScatteredType: Type with methods scattered across multiple files

#![allow(unused)]
fn main() {
// Type definition in types/user.rs
pub struct User {
    id: UserId,
    name: String,
}

// Methods scattered across files:
// In modules/auth.rs:
impl User {
    fn authenticate(&self) -> Result<Session> { /* ... */ }
}

// In modules/validation.rs:
impl User {
    fn validate_email(&self) -> Result<()> { /* ... */ }
}

// In modules/persistence.rs:
impl User {
    fn save(&self) -> Result<()> { /* ... */ }
}

// Problem: User methods spread across 4+ files!
}

When detected: Type has methods in 2+ files Severity levels: Stored as String field derived from file_count:

• Low = 2 files
• Medium = 3-5 files
• High = 6+ files

Action: Consolidate methods into primary file or create focused trait implementations

Source: Detection criteria from src/organization/codebase_type_analyzer.rs:46-47, type definition in src/priority/debt_types.rs:190-195

OrphanedFunctions: Functions that should be methods on a type

#![allow(unused)]
fn main() {
// Bad: Orphaned functions operating on User
fn validate_user_email(user: &User) -> Result<()> {
    // Email validation logic
}

fn calculate_user_age(user: &User) -> u32 {
    // Age calculation from birthdate
}

fn format_user_display(user: &User) -> String {
    // Display formatting
}

// Good: Functions converted to methods
impl User {
    fn validate_email(&self) -> Result<()> { /* ... */ }
    fn age(&self) -> u32 { /* ... */ }
    fn display(&self) -> String { /* ... */ }
}
}

When detected: Multiple functions with shared type parameter pattern (e.g., all take &User) Action: Convert functions to methods on the target type

Source: Detection in src/organization/codebase_type_analyzer.rs:58-71, type definition in src/priority/debt_types.rs:196-200

UtilitiesSprawl: Utility module with poor cohesion

#![allow(unused)]
fn main() {
// Bad: utils.rs with mixed responsibilities
mod utils {
    fn parse_date(s: &str) -> Date { /* ... */ }
    fn validate_email(s: &str) -> bool { /* ... */ }
    fn calculate_hash(data: &[u8]) -> Hash { /* ... */ }
    fn format_currency(amount: f64) -> String { /* ... */ }
    fn send_notification(msg: &str) { /* ... */ }
    // ... 20+ more unrelated functions
}

// Good: Focused modules
mod date_utils { fn parse(s: &str) -> Date { /* ... */ } }
mod validators { fn email(s: &str) -> bool { /* ... */ } }
mod crypto { fn hash(data: &[u8]) -> Hash { /* ... */ } }
mod formatters { fn currency(amount: f64) -> String { /* ... */ } }
mod notifications { fn send(msg: &str) { /* ... */ } }
}

When detected: Utility module has many functions operating on diverse types with low cohesion Action: Split into focused modules based on domain or responsibility

Source: Detection in src/organization/codebase_type_analyzer.rs:74-80, type definition in src/priority/debt_types.rs:201-204

Testing Debt

TestingGap: Functions with insufficient test coverage

#![allow(unused)]
fn main() {
// 0% coverage - critical business logic untested
fn calculate_tax(amount: f64, region: &str) -> f64 {
    // Complex tax calculation logic
    // No tests exist for this function!
}
}

When detected: Coverage data shows function has < 80% line coverage Action: Add unit tests to cover all branches and edge cases

TestComplexity: Test functions too complex

#![allow(unused)]
fn main() {
#[test]
fn complex_test() {
    // Cyclomatic: 12 (too complex for a test)
    for input in test_cases {
        if input.is_special() {
            match input.type {
                /* complex test logic */
            }
        }
    }
}
}

When detected: Test functions with cyclomatic > 10 or cognitive > 15 Action: Split into multiple focused tests, use test fixtures

FlakyTestPattern: Non-deterministic tests

#![allow(unused)]
fn main() {
#[test]
fn flaky_test() {
    let result = async_operation().await;  // Timing-dependent
    thread::sleep(Duration::from_millis(100));  // Race condition!
    assert_eq!(result.status, "complete");
}
}

When detected: Pattern analysis for timing dependencies, random values Action: Use mocks, deterministic test data, proper async test utilities

Performance Debt

AllocationInefficiency: Excessive allocations

#![allow(unused)]
fn main() {
// Bad: Allocates on every iteration
fn process_items(items: &[Item]) -> Vec<String> {
    let mut results = Vec::new();
    for item in items {
        results.push(item.name.clone());  // Unnecessary clone
    }
    results
}

// Good: Pre-allocate, avoid clones
fn process_items(items: &[Item]) -> Vec<&str> {
    items.iter().map(|item| item.name.as_str()).collect()
}
}

BlockingIO: Blocking operations in async contexts

#![allow(unused)]
fn main() {
// Bad: Blocks async runtime
async fn load_data() -> Result<Data> {
    let file = std::fs::read_to_string("data.json")?;  // Blocking!
    parse_json(&file)
}

// Good: Async I/O
async fn load_data() -> Result<Data> {
    let file = tokio::fs::read_to_string("data.json").await?;
    parse_json(&file)
}
}

NestedLoops: O(n²) or worse complexity

#![allow(unused)]
fn main() {
// Bad: O(n²) nested loops
fn find_duplicates(items: &[Item]) -> Vec<(Item, Item)> {
    let mut dupes = vec![];
    for i in 0..items.len() {
        for j in i+1..items.len() {
            if items[i] == items[j] {
                dupes.push((items[i].clone(), items[j].clone()));
            }
        }
    }
    dupes
}

// Good: O(n) with HashSet
fn find_duplicates(items: &[Item]) -> Vec<Item> {
    let mut seen = HashSet::new();
    items.iter().filter(|item| !seen.insert(item)).cloned().collect()
}
}

Code Quality Debt

ComplexityHotspot: Functions exceeding complexity thresholds

Source: Type definition in src/priority/debt_types.rs:84-87, categorized as CodeQuality in src/priority/mod.rs:245

#![allow(unused)]
fn main() {
// Cyclomatic: 22, Cognitive: 35
fn process_transaction(tx: Transaction, account: &mut Account) -> Result<Receipt> {
    if tx.amount <= 0 {
        return Err(Error::InvalidAmount);
    }
    if account.balance < tx.amount {
        if account.overdraft_enabled {
            if account.overdraft_limit >= tx.amount {
                // More nested branches...
            }
        } else {
            return Err(Error::InsufficientFunds);
        }
    }
    // ... deeply nested logic with many branches
    Ok(receipt)
}
}

Fields captured: cyclomatic: u32, cognitive: u32 When detected: Cyclomatic > 10 OR Cognitive > 15 (configurable) Action: Break into smaller functions, extract validation, simplify control flow

DeadCode: Unreachable or unused code

Source: Type definition in src/priority/debt_types.rs:88-93, categorized as CodeQuality in src/priority/mod.rs:246

#![allow(unused)]
fn main() {
// Private function never called within module
fn obsolete_calculation(x: i32) -> i32 {
    x * 2 + 5  // Dead code - no callers
}

// Public function but no external usage
pub fn deprecated_api(data: &str) -> Result<()> {
    // Unreachable in practice
    Ok(())
}
}

When detected: Function visibility analysis + call graph shows no callers Action: Remove dead code or document if intentionally kept for future use

MagicValues: Unexplained literal values

Source: Type definition in src/priority/debt_types.rs:163-166, categorized as CodeQuality in src/priority/mod.rs:250

#![allow(unused)]
fn main() {
// Bad: Magic numbers
fn calculate_price(quantity: u32) -> f64 {
    quantity as f64 * 19.99 + 5.0  // What are these numbers?
}

// Good: Named constants
const UNIT_PRICE: f64 = 19.99;
const SHIPPING_COST: f64 = 5.0;
fn calculate_price(quantity: u32) -> f64 {
    quantity as f64 * UNIT_PRICE + SHIPPING_COST
}
}

When detected: Numeric or string literals without clear context (excludes 0, 1, common patterns) Action: Extract to named constants or configuration

Duplication: Duplicated code blocks

#![allow(unused)]
fn main() {
// File A:
fn process_user(user: User) -> Result<()> {
    validate_email(&user.email)?;
    validate_age(user.age)?;
    save_to_database(&user)?;
    send_welcome_email(&user.email)?;
    Ok(())
}

// File B: Duplicated validation
fn process_admin(admin: Admin) -> Result<()> {
    validate_email(&admin.email)?;  // Duplicated
    validate_age(admin.age)?;       // Duplicated
    save_to_database(&admin)?;
    grant_admin_privileges(&admin)?;
    Ok(())
}
}

When detected: Similar code blocks > 50 lines (configurable) Action: Extract shared code into reusable functions

ErrorSwallowing: Errors caught but ignored

#![allow(unused)]
fn main() {
// Bad: Error swallowed, no context
match risky_operation() {
    Ok(result) => process(result),
    Err(_) => {}, // Silent failure!
}

// Good: Error handled with context
match risky_operation() {
    Ok(result) => process(result),
    Err(e) => {
        log::error!("Risky operation failed: {}", e);
        return Err(e.into());
    }
}
}

When detected: Empty catch blocks, ignored Results Action: Add proper error logging and propagation

Risk: High-risk code (complex + poorly tested)

#![allow(unused)]
fn main() {
// Cyclomatic: 18, Coverage: 20%, Risk Score: 47.6 (HIGH)
fn process_payment(tx: Transaction) -> Result<Receipt> {
    // Complex payment logic with minimal testing
    // High risk of bugs in production
}
}

When detected: Combines complexity metrics with coverage data Action: Either add comprehensive tests OR refactor to reduce complexity

Debt Scoring Formula

Each debt item gets a score based on priority and type:

debt_score = priority_weight × type_weight

Priority weights:

• Low = 1
• Medium = 3
• High = 5
• Critical = 10

Combined examples:

• Low Todo = 1 × 1 = 1
• Medium Fixme = 3 × 2 = 6
• High Complexity = 5 × 5 = 25
• Critical Complexity = 10 × 5 = 50

Total debt score = Sum of all debt item scores

Lower is better. Track over time to measure improvement.

Risk Scoring

Debtmap’s risk scoring identifies code that is both complex AND poorly tested - the true risk hotspots.

Unified Scoring System

Debtmap uses a unified scoring system (0-10 scale) as the primary prioritization mechanism. This multi-factor approach balances complexity, test coverage, and dependency impact, adjusted by function role.

Source: src/priority/unified_scorer.rs:97-144 (UnifiedScore struct)

Score Scale and Priority Classifications

Functions receive scores from 0 (minimal risk) to 10 (critical risk):

Scoring Formula

The unified score combines three weighted factors:

Base Score = (Complexity Factor × Weight) + (Coverage Factor × Weight) + (Dependency Factor × Weight)

Final Score = Base Score × Role Multiplier × Purity Adjustment

Source: src/priority/unified_scorer.rs:300-325 (calculate_unified_priority_with_debt)

Dynamic Weight Adjustment

IMPORTANT: Weights are dynamically adjusted based on coverage data availability.

When coverage data is available (default):

• Complexity: ~35-40% (via complexity_factor)
• Coverage: ~35-40% (via coverage multiplier dampening)
• Dependency: ~20-25%

When coverage data is NOT available:

• Complexity: 50%
• Dependency: 25%
• Debt patterns: 25% (reserved for additive adjustments)

Source:

• With coverage: src/priority/scoring/calculation.rs:68-82 (calculate_base_score_with_coverage_multiplier)
• Without coverage: src/priority/scoring/calculation.rs:119-129 (calculate_base_score_no_coverage)

These weights can be adjusted in .debtmap.toml to match your team’s priorities.

Factor Calculations

Complexity Factor (0-10 scale):

#![allow(unused)]
fn main() {
// Source: src/priority/scoring/calculation.rs:54-59
Complexity Factor = (raw_complexity / 2.0).clamp(0.0, 10.0)

// Where raw_complexity is weighted combination:
// Default: 30% cyclomatic + 70% cognitive
// For orchestrators: 25% cyclomatic + 75% cognitive
}

Maps normalized complexity (0-20 range) to 0-10 scale. Uses configurable weights that prioritize cognitive complexity (70%) over cyclomatic complexity (30%) as it correlates better with defect density. See Complexity Metrics for detailed explanations of cyclomatic vs cognitive complexity.

Source: src/config/scoring.rs:221-267 (ComplexityWeightsConfig)

Coverage Factor (0-10 scale):

#![allow(unused)]
fn main() {
// Source: src/priority/scoring/calculation.rs:8-21
Coverage Multiplier = 1.0 - coverage_percentage

// Applied as dampening:
Base Score × Coverage Multiplier
}

Coverage acts as a dampening multiplier:

• 0% coverage → multiplier = 1.0 (no dampening)
• 50% coverage → multiplier = 0.5 (50% reduction)
• 100% coverage → multiplier = 0.0 (maximum dampening)

Uncovered complex code scores higher than uncovered simple code. Well-tested code gets lower scores.

Dependency Factor (0-10 scale):

#![allow(unused)]
fn main() {
// Source: src/priority/scoring/calculation.rs:61-66
Dependency Factor = (upstream_caller_count / 2.0).min(10.0)
}

Based on call graph analysis with linear scaling:

• 0-1 upstream callers → score 0-0.5 (low impact)
• 2-4 upstream callers → score 1.0-2.0 (moderate impact)
• 5+ upstream callers → score 2.5-10.0 (high impact, capped at 10.0)

Critical path bonus: Functions on critical paths from entry points receive additional dependency weight.

Role-Based Prioritization

The unified score is multiplied by a role multiplier based on the function’s semantic classification.

Source: src/priority/semantic_classifier/mod.rs:24-33 (FunctionRole enum)

Role Multipliers

Source:

• Multiplier values: src/priority/unified_scorer.rs:624-635 (calculate_role_multiplier)
• Configuration defaults: src/config/scoring.rs:147-220 (RoleMultipliers)

Note: Configuration allows overriding these default multipliers via .debtmap.toml. See Configuration for details on customizing role weights.

Note: PureLogic has a dynamic multiplier that adjusts based on complexity. Simple business logic (≤ 5.0 complexity) gets baseline priority, while complex business logic (> 5.0) receives elevated priority (1.3×).

How Role Classification Works

Debtmap identifies function roles through a rule-based classifier with specific detection heuristics:

Source: src/priority/semantic_classifier/mod.rs:46-114 (classify_by_rules)

Detection Rules (in priority order):

1. EntryPoint - Detected by:

   • Name patterns: main, handle_*, run_*
   • Call graph analysis: no upstream callers (entry point to call graph)
   • Source: Line 54

2. Debug - Detected by:

   • Name patterns: debug_*, dump_*, log_*, print_*, display_*, trace_*, *_diagnostics, *_debug, *_stats
   • Complexity limit: cognitive ≤ 10
   • Source: Line 59, src/priority/semantic_classifier/classifiers.rs:14-65

3. Constructors (classified as PureLogic) - Detected by:

   • Name patterns: new, with_*, from_*, default, create_*, make_*, build_*
   • Complexity thresholds: cyclomatic ≤ 2, cognitive ≤ 3, length < 15, nesting ≤ 1
   • Source: Line 64, src/priority/semantic_classifier/classifiers.rs:67-115

4. Accessors (classified as IOWrapper) - Detected by:

   • Name patterns: get_*, is_*, has_*, can_*, should_*, as_*, to_*, single-word accessors (id, name, value, etc.)
   • Complexity thresholds: cyclomatic ≤ 2, cognitive ≤ 1, length < 10, nesting ≤ 1
   • Source: Line 77, src/priority/semantic_classifier/mod.rs:147-177 (is_accessor_method)

5. PatternMatch - Detected by:

   • Simple match/if-else chains
   • Low complexity relative to branch count
   • Source: Line 99

6. IOWrapper - Detected by:

   • Simple file/network/database operations
   • Thin wrapper around I/O primitives
   • Source: Line 104

7. Orchestrator - Detected by:

   • High delegation ratio (calls 5+ functions)
   • Low cognitive complexity relative to cyclomatic complexity
   • Coordinates other functions without complex logic
   • Source: Line 109

8. PureLogic (default) - Applied when:

   • None of the above patterns match
   • Assumed to be core business logic

Example: Same Complexity, Different Priorities

Consider a function with base score 8.0:

If classified as EntryPoint:
  Final Score = 8.0 × 1.5 = 12.0 (capped at 10.0) → CRITICAL priority

If classified as PureLogic (complex):
  Final Score = 8.0 × 1.3 = 10.4 (capped at 10.0) → CRITICAL priority

If classified as PureLogic (simple):
  Final Score = 8.0 × 1.0 = 8.0 → HIGH priority

If classified as Orchestrator:
  Final Score = 8.0 × 0.8 = 6.4 → MEDIUM priority

If classified as IOWrapper:
  Final Score = 8.0 × 0.5 = 4.0 → LOW priority

This ensures that complex code in critical paths gets higher priority than equally complex utility code.

Real Example from Codebase:

A payment processing function with cyclomatic complexity 18 and cognitive complexity 25:

• If it directly implements business logic → PureLogic (complex) → 1.3× multiplier
• If it mainly delegates to other payment functions → Orchestrator → 0.8× multiplier
• If it’s a thin wrapper around a payment API → IOWrapper → 0.5× multiplier

Coverage Propagation

Coverage impact flows through the call graph using transitive coverage and indirect coverage analysis.

Source: src/priority/coverage_propagation.rs:291-387

How It Works

Transitive coverage is calculated via call graph traversal with distance-based dampening:

#![allow(unused)]
fn main() {
// Source: src/priority/coverage_propagation.rs:342-364
Indirect Coverage = Σ(Caller Coverage × 0.7^distance)

Where:
- distance = hops from tested code (MAX_DEPTH = 3)
- DISTANCE_DISCOUNT = 0.7 (70% per hop)
- Well-tested threshold = 0.8 (80% coverage)
}

Implementation Details:

1. Transitive coverage is calculated via recursive call graph traversal
2. Results are stored in UnifiedDebtItem.transitive_coverage field (Source: src/priority/unified_scorer.rs:154)
3. Weights decay exponentially with call graph depth:
   • 1 hop away: contribution × 0.7
   • 2 hops away: contribution × 0.49 (0.7²)
   • 3 hops away: contribution × 0.343 (0.7³)
4. Used to adjust coverage factor in scoring, reducing false positives for utility functions

Coverage Urgency Calculation

The system calculates coverage urgency (0-10 scale) by blending direct and transitive coverage:

#![allow(unused)]
fn main() {
// Source: src/priority/coverage_propagation.rs:237-270
Effective Coverage = (Direct Coverage × 0.7) + (Transitive Coverage × 0.3)

Coverage Urgency = (1.0 - Effective Coverage) × Complexity Weight × 10.0
}

Complexity weighting uses logarithmic scaling to prioritize complex functions.

Example Scenarios

Scenario 1: Untested function with well-tested callers

Function A: 0% direct coverage
  Called by (1 hop):
    - handle_request (95% coverage): contributes 95% × 0.7 = 66.5%
    - process_payment (90% coverage): contributes 90% × 0.7 = 63%
    - validate_order (88% coverage): contributes 88% × 0.7 = 61.6%

Indirect coverage: ~66% (highest contributor)
Effective coverage: (0% × 0.7) + (66% × 0.3) = ~20%
Final priority: Lower than isolated 0% coverage function

Scenario 2: Untested function on critical path

Function B: 0% direct coverage
  Called by (1 hop):
    - main (0% coverage): contributes 0% × 0.7 = 0%
    - startup (10% coverage): contributes 10% × 0.7 = 7%

Indirect coverage: ~7% (minimal coverage benefit)
Effective coverage: (0% × 0.7) + (7% × 0.3) = ~2%
Final priority: Higher - on critical path with no safety net

Scenario 3: Multi-hop propagation

Function C: 0% direct coverage
  Called by utility_helper (40% coverage, 1 hop):
    utility_helper is called by:
      - api_handler (95% coverage, 2 hops): contributes 95% × 0.7² = 46.6%

Indirect coverage via 2-hop path: ~46%
Effective coverage: ~14%
Final priority: Moderate - benefits from indirect testing

Coverage propagation prevents false alarms about utility functions called only by well-tested code, while highlighting genuinely risky untested code on critical paths.

Unified Score Example

Updated example using actual implementation:

Function: process_payment
  Location: src/payments.rs:145

Metrics:
  - Cyclomatic complexity: 18
  - Cognitive complexity: 25
  - Test coverage: 20%
  - Upstream callers: 3
  - Classified role: PureLogic (complex, since complexity > 5.0)

Step 1: Calculate raw complexity
  Raw Complexity = (cyclomatic × 0.3) + (cognitive × 0.7)
                 = (18 × 0.3) + (25 × 0.7)
                 = 5.4 + 17.5
                 = 22.9

Step 2: Normalize to 0-10 scale
  Complexity Factor = (22.9 / 2.0).clamp(0.0, 10.0)
                    = 10.0 (capped)
  // Source: src/priority/scoring/calculation.rs:54-59

Step 3: Calculate coverage multiplier
  Coverage Multiplier = 1.0 - 0.20 = 0.80
  // Source: src/priority/scoring/calculation.rs:8-21

Step 4: Calculate dependency factor
  Dependency Factor = (3 / 2.0).min(10.0) = 1.5
  // Source: src/priority/scoring/calculation.rs:61-66

Step 5: Calculate base score (with dynamic weights)
  Base Score = (Complexity Factor × weight) + (Coverage dampening) + (Dependency Factor × weight)

  // Actual implementation uses coverage as dampening multiplier
  Base = ((10.0 × 0.35) + (1.5 × 0.20)) × 0.80
       = (3.5 + 0.3) × 0.80
       = 3.04
  // Source: src/priority/scoring/calculation.rs:68-82

Step 6: Apply role multiplier
  Role Multiplier = 1.3 (PureLogic with complexity > 5.0)
  // Source: src/priority/unified_scorer.rs:624-635

  Final Score = 3.04 × 1.3 = 3.95 → LOW priority

Note: The 20% coverage dampening significantly reduces the final score.
If this function had 0% coverage:
  Coverage Multiplier = 1.0 (no dampening)
  Base Score = 3.8
  Final Score = 3.8 × 1.3 = 4.94 → LOW priority

If this function had 0% coverage AND higher dependency (8 callers):
  Dependency Factor = (8 / 2.0).min(10.0) = 4.0
  Base Score = ((10.0 × 0.35) + (4.0 × 0.20)) × 1.0 = 4.3
  Final Score = 4.3 × 1.3 = 5.59 → MEDIUM priority

Key Insight: Coverage acts as a dampening multiplier, not an additive factor. The example in the original documentation overestimated risk by treating coverage as additive. The actual implementation properly dampens scores for tested code.

Legacy Risk Scoring (Pre-0.2.x)

Prior to the unified scoring system, Debtmap used a simpler additive risk formula. This is still available for compatibility but unified scoring is now the default and provides better prioritization.

Risk Categories

Note: The RiskLevel enum (Low, Medium, High, Critical) is used for legacy risk scoring compatibility. When using unified scoring (0-10 scale), refer to the priority classifications shown in the Unified Scoring System section above.

Legacy RiskLevel Enum

For legacy risk scoring, Debtmap classifies functions into four risk levels:

#![allow(unused)]
fn main() {
pub enum RiskLevel {
    Low,       // Score < 10
    Medium,    // Score 10-24
    High,      // Score 25-49
    Critical,  // Score ≥ 50
}
}

Critical (legacy score ≥ 50)

• High complexity (cyclomatic > 15) AND low coverage (< 30%)
• Untested code that’s likely to break and hard to fix
• Action: Immediate attention required - add tests or refactor

High (legacy score 25-49)

• High complexity (cyclomatic > 10) AND moderate coverage (< 60%)
• Risky code with incomplete testing
• Action: Should be addressed soon

Medium (legacy score 10-24)

• Moderate complexity (cyclomatic > 5) AND low coverage (< 50%)
• OR: High complexity with good coverage
• Action: Plan for next sprint

Low (legacy score < 10)

• Low complexity OR high coverage
• Well-managed code
• Action: Monitor, low priority

Unified Scoring Priority Levels

When using unified scoring (default), functions are classified using the 0-10 scale:

• Critical (9.0-10.0): Immediate attention
• High (7.0-8.9): Address this sprint
• Medium (5.0-6.9): Plan for next sprint
• Low (3.0-4.9): Monitor and address as time permits
• Minimal (0.0-2.9): Well-managed code

Well-tested complex code is an outcome in both systems, not a separate category:

• Complex function (cyclomatic 18, cognitive 25) with 95% coverage
• Unified score: ~2.5 (Minimal priority due to coverage dampening)
• Legacy risk score: ~8 (Low risk)
• Falls into low-priority categories because good testing mitigates complexity
• This is the desired state for inherently complex business logic

Legacy Risk Calculation

Note: The legacy risk calculation is still supported for compatibility but has been superseded by the unified scoring system (see above). Unified scoring provides better prioritization through its multi-factor, weighted approach with role-based adjustments.

The legacy risk score uses a simpler additive formula:

#![allow(unused)]
fn main() {
risk_score = complexity_factor + coverage_factor + debt_factor

where:
  complexity_factor = (cyclomatic / 5) + (cognitive / 10)
  coverage_factor = (1 - coverage_percentage) × 50
  debt_factor = debt_score / 10  // If debt data available
}

Note on debt_score: The debt_score comes from DebtAggregator which combines multiple debt dimensions:

• Testing debt (unwrap calls, untested error paths)
• Resource debt (unclosed files, memory leaks)
• Duplication debt (code clones)

Source: src/priority/debt_aggregator.rs

Example (legacy scoring):

Function: process_payment
  - Cyclomatic complexity: 18
  - Cognitive complexity: 25
  - Coverage: 20%
  - Debt score: 15 (from DebtAggregator)

Calculation:
  complexity_factor = (18 / 5) + (25 / 10) = 3.6 + 2.5 = 6.1
  coverage_factor = (1 - 0.20) × 50 = 40
  debt_factor = 15 / 10 = 1.5

  risk_score = 6.1 + 40 + 1.5 = 47.6 (HIGH RISK)

When to use legacy scoring:

• Comparing with historical data from older Debtmap versions
• Teams with existing workflows built around the old scale
• Gradual migration to unified scoring

Why unified scoring is better:

• Normalized 0-10 scale is more intuitive
• Dynamic weights adjust based on coverage data availability
• Role multipliers adjust priority based on function importance
• Coverage propagation reduces false positives for utility functions
• Purity adjustments reward functional programming patterns

Test Effort Assessment

Debtmap estimates testing difficulty based on complexity metrics using an advanced effort model.

Source: src/risk/roi/effort.rs (AdvancedEffortModel)

How Effort is Calculated

Test effort estimation involves two components:

1. Test case count: Estimated from cyclomatic complexity (branch coverage)

   • Each branch represents a code path that needs testing
   • Formula approximates test cases needed for comprehensive branch coverage

2. Time estimate: Calculated from cognitive complexity (comprehension difficulty)

   • Higher cognitive complexity means more time to understand and write tests
   • Includes setup cost, assertion cost, and complexity multipliers
   • Optional learning system can adjust estimates based on historical data

Difficulty Levels:

• Trivial (cognitive < 5): 1-2 test cases, < 1 hour
• Simple (cognitive 5-10): 3-5 test cases, 1-2 hours
• Moderate (cognitive 10-20): 6-10 test cases, 2-4 hours
• Complex (cognitive 20-40): 11-20 test cases, 4-8 hours
• VeryComplex (cognitive > 40): 20+ test cases, 8+ hours

Test Effort includes:

• Cognitive load: How hard to understand the function
• Branch count (cyclomatic): Number of paths to test
• Recommended test cases: Estimated from cyclomatic complexity
• Estimated hours: Derived from cognitive complexity with setup overhead

Risk Distribution

Debtmap provides codebase-wide risk metrics:

{
  "risk_distribution": {
    "critical_count": 12,
    "high_count": 45,
    "medium_count": 123,
    "low_count": 456,
    "minimal_count": 234,
    "total_functions": 870
  },
  "codebase_risk_score": 1247.5
}

Interpreting distribution:

• Healthy codebase: Most functions in Low/Minimal priority (unified scoring) or Low/WellTested (legacy)
• Needs attention: Many Critical/High priority functions
• Technical debt: High codebase risk score

Legacy vs Unified Risk Distribution Fields

IMPORTANT: The field names differ between legacy and unified scoring systems:

Sources:

• Unified priority tiers: src/priority/tiers/mod.rs
• Legacy RiskCategory enum: src/risk/mod.rs:36-42

Note on minimal_count:

In unified scoring (0-10 scale), minimal_count represents functions scoring 0-2.9, which includes:

• Simple utility functions with low complexity
• Helper functions with minimal risk
• Well-tested complex code that scores low due to coverage dampening

This is not a separate risk category but an outcome of the unified scoring system. Complex business logic with 95% test coverage appropriately receives a minimal score (0-2.9), reflecting that good testing mitigates complexity risk.

When using legacy scoring, there is NO minimal_count field. Instead, you’ll see well_tested_count which represents functions that are both complex and well-tested (the desired outcome).

Testing Recommendations

When coverage data is provided, Debtmap generates prioritized testing recommendations with ROI analysis.

Source: src/risk/roi/mod.rs:66-113

ROI Calculation

The ROI calculation is much richer than a simple risk/effort ratio. It includes cascade impacts, module multipliers, and complexity weighting:

#![allow(unused)]
fn main() {
// Source: src/risk/roi/mod.rs:66-113
ROI = ((Direct_Impact × Module_Multiplier) + (Cascade_Impact × Cascade_Weight))
      × Dependency_Factor × Complexity_Weight / Adjusted_Effort
}

Formula Components:

1. Direct Impact: Risk reduction from testing this function directly

2. Module Multiplier (based on module type):

   • EntryPoint = 2.0 (highest priority for user-facing code)
   • Core = 1.5 (domain logic)
   • Api = 1.2 (API endpoints)
   • Model = 1.1 (data models)
   • IO = 1.0 (baseline for I/O operations)

3. Cascade Impact: Risk reduction in dependent functions

   • Calculated using cascade analyzer
   • Cascade Weight: Configurable (default 0.5)
   • Max Cascade Depth: 3 hops (configurable)

4. Dependency Factor: Amplifies ROI based on number of dependents

   #![allow(unused)]
   fn main() {
   Dependency_Factor = 1.0 + min(dependent_count × 0.1, 1.0)
   }

   • Capped at 2.0× multiplier
   • Rewards testing functions with many dependents

5. Complexity Weight: Penalizes trivial delegation functions

   • (cyclomatic=1, cognitive=0-1): 0.1 (trivial delegation)
   • (cyclomatic=1, cognitive=2-3): 0.3 (very simple)
   • (cyclomatic=2-3, any): 0.5 (simple)
   • (cyclomatic=4-5, any): 0.7 (moderate)
   • Other: 1.0 (complex, full weight)

6. Adjusted Effort: Base effort adjusted by learning system (if enabled)

   • Learning system tracks historical test writing effort
   • Adjusts estimates based on actual time spent

ROI Scaling (for intuitive 0-10 scale):

• raw_roi > 20.0: 10.0 + ln(raw_roi - 20.0) (logarithmic dampening)
• 10.0 < raw_roi ≤ 20.0: 5.0 + (raw_roi - 20.0) × 0.5 (linear dampening)
• Otherwise: raw_roi (no scaling)

Sources:

• ROI model: src/risk/roi/models.rs:4-11
• Effort estimation: src/risk/roi/effort.rs
• Cascade impact: src/risk/roi/cascade.rs

Example ROI Output

{
  "function": "process_transaction",
  "file": "src/payments.rs",
  "line": 145,
  "current_risk": 47.6,
  "potential_risk_reduction": 35.2,
  "test_effort_estimate": {
    "estimated_difficulty": "Complex",
    "cognitive_load": 25,
    "branch_count": 18,
    "recommended_test_cases": 12,
    "estimated_hours": 6.5
  },
  "roi": 8.2,
  "roi_breakdown": {
    "direct_impact": 35.2,
    "module_multiplier": 1.5,
    "cascade_impact": 12.4,
    "cascade_weight": 0.5,
    "dependency_factor": 1.3,
    "complexity_weight": 1.0,
    "adjusted_effort": 6.5
  },
  "rationale": "High complexity with low coverage (20%) and 3 downstream dependencies. Testing will reduce risk by 74%. Cascade effect improves 8 dependent functions.",
  "dependencies": {
    "upstream_callers": ["handle_payment_request"],
    "downstream_callees": ["validate_amount", "check_balance", "record_transaction"],
    "dependent_count": 13
  },
  "confidence": 0.85
}

Interpreting ROI:

• ROI > 5.0: Excellent return on investment, prioritize highly
• ROI 3.0-5.0: Good return, address soon
• ROI 1.0-3.0: Moderate return, plan for future work
• ROI < 1.0: Low return, consider other priorities

Key Insight: The cascade impact calculation means that testing a critical utility function with many dependents can have higher ROI than testing a complex but isolated function. This helps identify “force multiplier” tests that improve coverage across multiple modules.

Interpreting Results

Interpreting Results

Understanding Output Formats

Debtmap provides four output formats:

Terminal (default): Human-readable with colors and tables

debtmap analyze .

JSON: Machine-readable for CI/CD integration

debtmap analyze . --format json --output report.json

Markdown: Documentation-friendly

debtmap analyze . --format markdown --output report.md

HTML: Interactive dashboard with visualizations

debtmap analyze . --format html --output report.html

Source: Output formats defined in src/io/writers/ (html.rs, markdown.rs, terminal.rs, json.rs)

JSON Structure

Debtmap uses a unified JSON format (spec 108) that provides consistent structure for all debt items. The output is generated by converting the internal UnifiedAnalysis to UnifiedOutput format (src/output/unified.rs).

Top-level JSON structure:

{
  "format_version": "1.0",
  "metadata": {
    "debtmap_version": "0.11.0",
    "generated_at": "2025-12-04T12:00:00Z",
    "project_root": "/path/to/project",
    "analysis_type": "full"
  },
  "summary": {
    "total_items": 45,
    "total_debt_score": 2847.3,
    "debt_density": 113.89,
    "total_loc": 25000,
    "by_type": {
      "File": 3,
      "Function": 42
    },
    "by_category": {
      "Architecture": 5,
      "Testing": 23,
      "Performance": 7,
      "CodeQuality": 10
    },
    "score_distribution": {
      "critical": 2,   // score >= 100
      "high": 8,       // score >= 50
      "medium": 18,    // score >= 20
      "low": 17        // score < 20
    },
    "cohesion": {                    // optional, spec 198
      "average": 0.72,               // codebase average (0.0-1.0)
      "high_cohesion_files": 15,     // >= 0.7
      "medium_cohesion_files": 8,    // 0.4-0.7
      "low_cohesion_files": 3        // < 0.4
    }
  },
  "items": [ /* array of UnifiedDebtItemOutput */ ]
}

Score Distribution Thresholds (Priority enum):

The score_distribution in JSON uses the Priority classification (src/output/unified/priority.rs:15-33):

Note: This differs from the Tier system used for terminal display (see Tiered Prioritization).

Cohesion Summary (optional, spec 198):

When cohesion analysis is enabled, the summary includes codebase-wide cohesion statistics (src/output/unified/cohesion.rs:64-73):

• average: Mean cohesion score across all files (0.0-1.0, higher = better)
• high_cohesion_files: Files with cohesion >= 0.7 (well-organized)
• medium_cohesion_files: Files with cohesion 0.4-0.7 (acceptable)
• low_cohesion_files: Files with cohesion < 0.4 (candidates for refactoring)

Individual debt item structure (function-level):

{
  "type": "Function",
  "score": 87.3,
  "category": "Testing",
  "priority": "high",
  "location": {
    "file": "src/main.rs",
    "line": 42,
    "function": "process_data"
  },
  "metrics": {
    "cyclomatic_complexity": 15,
    "cognitive_complexity": 22,
    "length": 68,
    "nesting_depth": 4,
    "coverage": 0.0,
    "uncovered_lines": [42, 43, 44, 45, 46],
    "entropy_score": 0.65
  },
  "debt_type": {
    "ComplexityHotspot": {
      "cyclomatic": 15,
      "cognitive": 22,
      "adjusted_cyclomatic": null
    }
  },
  "function_role": "BusinessLogic",
  "purity_analysis": {
    "is_pure": false,
    "confidence": 0.8,
    "side_effects": ["file_io", "network"]
  },
  "dependencies": {
    "upstream_count": 2,
    "downstream_count": 3,
    "upstream_callers": ["main", "process_request"],
    "downstream_callees": ["validate", "save", "notify"]
  },
  "recommendation": {
    "action": "Add test coverage for complex function",
    "priority": "High",
    "implementation_steps": [
      "Write unit tests covering all 15 branches",
      "Consider extracting validation logic to reduce complexity"
    ]
  },
  "impact": {
    "coverage_improvement": 0.85,
    "complexity_reduction": 12.0,
    "risk_reduction": 3.7
  },
  "adjusted_complexity": {
    "dampened_cyclomatic": 12.5,
    "dampening_factor": 0.83
  },
  "complexity_pattern": "validation",
  "pattern_type": "state_machine",
  "pattern_confidence": 0.72,
  "context": {                            // optional, spec 263
    "primary": {
      "file": "src/main.rs",
      "start_line": 35,
      "end_line": 110,
      "symbol": "process_data"
    },
    "related": [
      {
        "range": {
          "file": "src/validation.rs",
          "start_line": 10,
          "end_line": 45
        },
        "relationship": "calls",
        "reason": "Validation helper called by process_data"
      }
    ],
    "total_lines": 120,
    "completeness_confidence": 0.85
  },
  "git_history": {                        // optional, spec 264
    "change_frequency": 2.5,              // changes per month
    "bug_density": 0.15,                  // ratio of bug fixes to total commits
    "age_days": 180,                      // code age
    "author_count": 3,                    // unique contributors
    "stability": "Frequently Changed"     // stability classification
  }
}

Source: JSON structure defined in src/output/unified.rs:18-24 (UnifiedOutput), lines 66-71 (UnifiedDebtItemOutput enum), lines 156-183 (FunctionDebtItemOutput)

Note: The "type" field uses a tagged enum format where the value is either "Function" or "File". All items have consistent top-level fields (score, category, priority, location) regardless of type, simplifying filtering and sorting across mixed results.

Reading Function Metrics

Key fields in metrics object (src/output/unified/func_item.rs:340-373):

• cyclomatic_complexity: Decision points - guides test case count
• cognitive_complexity: Understanding difficulty - guides refactoring priority
• length: Lines of code - signals SRP violations
• nesting_depth: Indentation depth - signals need for extraction
• coverage: Test coverage percentage (0.0-1.0, optional if no coverage data)
• uncovered_lines: Array of line numbers not covered by tests (optional)
• entropy_score: Pattern analysis score for false positive reduction (0.0-1.0, optional)
• pattern_repetition: Repetition score (0.0-1.0, higher = more repetitive code) - optional, spec 264
• branch_similarity: Branch similarity score (0.0-1.0, higher = similar branches) - optional, spec 264
• entropy_adjusted_cognitive: Cognitive complexity adjusted for entropy patterns - optional, spec 264
• transitive_coverage: Coverage propagated from calling functions (0.0-1.0) - optional, spec 264

Fields at item level:

• function_role: Function importance ("EntryPoint", "BusinessLogic", "Utility", "TestHelper") - affects score multiplier (src/priority/mod.rs:231)
• purity_analysis: Whether function has side effects (optional) - affects testability assessment
  • is_pure: Boolean indicating no side effects
  • confidence: How certain (0.0-1.0)
  • side_effects: Array of detected side effect types (e.g., “file_io”, “network”, “mutation”)
• dependencies: Call graph relationships
  • upstream_count: Number of functions that call this one (impact radius)
  • downstream_count: Number of functions this calls (complexity)
  • upstream_callers: Names of calling functions (optional, included if count > 0)
  • downstream_callees: Names of called functions (optional, included if count > 0)

Complexity adjustment fields:

• adjusted_complexity: Entropy-based dampening applied (optional, included when dampening factor < 1.0)
  • dampened_cyclomatic: Reduced complexity after pattern analysis
  • dampening_factor: Multiplier applied (e.g., 0.83 = 17% reduction)
• complexity_pattern: Detected pattern name (e.g., “validation”, “dispatch”, “error_handling”)
• pattern_type: Pattern category (e.g., “state_machine”, “coordinator”) - high-level classification
• pattern_confidence: Confidence in pattern detection (0.0-1.0, shown if ≥ 0.5)

AI Agent Context fields (spec 263, src/output/unified/func_item.rs:78-83):

• context: AI agent context window suggestion (optional) - helps LLMs understand code
  • primary: Main code range containing the function
    • file: Source file path
    • start_line, end_line: Code range
    • symbol: Function/method name (optional)
  • related: Array of related code ranges (callees, callers, types)
    • range: File range with path and line numbers
    • relationship: How it relates (“calls”, “called_by”, “uses_type”, etc.)
    • reason: Human-readable explanation
  • total_lines: Estimated total lines for AI to read
  • completeness_confidence: Confidence that context is sufficient (0.0-1.0)

Git History fields (spec 264, src/output/unified/func_item.rs:476-520):

• git_history: Code stability analysis from git history (optional)
  • change_frequency: Average changes per month (higher = more active)
  • bug_density: Ratio of bug-fix commits to total commits (0.0-1.0)
  • age_days: Days since code was first introduced
  • author_count: Number of unique contributors
  • stability: Classification based on patterns:
    • "Highly Unstable": change_frequency > 5.0 and bug_density > 0.3
    • "Frequently Changed": change_frequency > 2.0
    • "Bug Prone": bug_density > 0.2
    • "Stable": Low change frequency and bug density
    • "Stale": age_days > 365 with minimal changes

Pattern detection and complexity adjustment:

Debtmap detects common code patterns that appear complex but are actually maintainable (src/complexity/entropy_analysis.rs). When detected with high confidence (≥ 0.5), complexity metrics are dampened:

Validation patterns - Repetitive input checking:

#![allow(unused)]
fn main() {
// Appears complex (cyclomatic = 15) but is repetitive
if field1.is_empty() { return Err(...) }
if field2.is_empty() { return Err(...) }
// ... repeated for many fields
}

Dampening: ~20-40% reduction if similarity is high

State machine patterns - Structured state transitions:

#![allow(unused)]
fn main() {
match state {
    State::Init => { /* transition logic */ }
    State::Running => { /* transition logic */ }
    // ... many similar cases
}
}

Dampening: ~30-50% reduction for consistent transition logic

Error handling patterns - Systematic error checking:

#![allow(unused)]
fn main() {
let x = operation1().map_err(|e| /* wrap error */)?;
let y = operation2().map_err(|e| /* wrap error */)?;
// ... repeated error wrapping
}

Dampening: ~15-30% reduction for consistent error propagation

When to trust adjusted_complexity:

• pattern_confidence ≥ 0.7: High confidence, use dampened_cyclomatic for priority decisions
• pattern_confidence 0.5-0.7: Moderate confidence, consider both original and dampened values
• pattern_confidence < 0.5 or missing: Use original cyclomatic_complexity

Entropy score interpretation:

• entropy_score ≥ 0.7: High entropy, genuinely complex code - prioritize refactoring
• entropy_score 0.4-0.7: Moderate entropy, some repetition - review manually
• entropy_score < 0.4: Low entropy, highly repetitive pattern - likely false positive if flagged complex

Prioritizing Work

Debtmap provides multiple prioritization strategies, with unified scoring (0-10 scale) as the recommended default for most workflows:

1. By Unified Score (default - recommended)

debtmap analyze . --top 10

Shows top 10 items by combined complexity, coverage, and dependency factors, weighted and adjusted by function role.

Why use unified scoring:

• Balances complexity (40%), coverage (40%), and dependency impact (20%)
• Adjusts for function importance (entry points prioritized over utilities)
• Normalized 0-10 scale is intuitive and consistent
• Reduces false positives through coverage propagation
• Best for sprint planning and function-level refactoring decisions

Example:

# Show top 20 critical items
debtmap analyze . --min-priority 7.0 --top 20

# Focus on high-impact functions (score >= 7.0)
debtmap analyze . --format json | jq '.functions[] | select(.unified_score >= 7.0)'

2. By Risk Category (legacy compatibility)

debtmap analyze . --min-priority high

Shows only HIGH and CRITICAL priority items using legacy risk scoring.

Note: Legacy risk scoring uses additive formulas and unbounded scales. Prefer unified scoring for new workflows.

3. By Debt Type

debtmap analyze . --filter Architecture,Testing

Focuses on specific categories:

• Architecture: God objects, complexity, dead code
• Testing: Coverage gaps, test quality
• Performance: Resource leaks, inefficiencies
• CodeQuality: Code smells, maintainability

4. By ROI (with coverage)

debtmap analyze . --lcov coverage.lcov --top 20

Prioritizes by return on investment for testing/refactoring. Combines unified scoring with test effort estimates to identify high-value work.

Choosing the right strategy:

• Sprint planning for developers: Use unified scoring (--top N)
• Architectural review: Use tiered prioritization (--summary)
• Category-focused work: Use debt type filtering (--filter)
• Testing priorities: Use ROI analysis with coverage data (--lcov)
• Historical comparisons: Use legacy risk scoring (for consistency with old reports)

Tiered Prioritization

Note: Tiered prioritization uses traditional debt scoring (additive, higher = worse) and is complementary to the unified scoring system (0-10 scale). Both systems can be used together:

• Unified scoring (0-10 scale): Best for function-level prioritization and sprint planning
• Tiered prioritization (debt tiers): Best for architectural focus and strategic debt planning

Use --summary for tiered view focusing on architectural issues, or default output for function-level unified scores.

Debtmap uses a tier-based system to map debt scores to actionable priority levels. Each tier includes effort estimates and strategic guidance for efficient debt remediation.

Tier vs Priority: Two Classification Systems

Important: Debtmap uses two different threshold systems for classifying debt items:

Why two systems?

• Tier is designed for terminal display and human-readable grouping. It uses tighter thresholds (90/70/50) to create more balanced visual categories when browsing results interactively.

• Priority is designed for JSON output and CI/CD integration. It uses wider thresholds (100/50/20) that align with typical CI gate requirements and allow for more granular filtering in automated pipelines.

Practical implications:

• A function with score 85 appears as HIGH tier in terminal output but has "priority": "high" in JSON (both treat it as high priority)
• A function with score 55 appears as MODERATE tier in terminal but has "priority": "high" in JSON (Priority uses >= 50 threshold)
• The score_distribution in JSON summary counts items using Priority thresholds, not Tier thresholds

When filtering:

# Terminal tier filtering (uses Tier thresholds)
debtmap analyze . --min-priority high  # Shows score >= 70

# JSON priority field (uses Priority thresholds)
debtmap analyze . --format json | jq '.items[] | select(.priority == "high")'  # Shows score >= 50

Tier Levels

The Tier enum defines four priority levels based on score thresholds (src/priority/mod.rs:372-386):

#![allow(unused)]
fn main() {
pub enum Tier {
    Critical,  // Score >= 90
    High,      // Score 70-89.9
    Moderate,  // Score 50-69.9
    Low,       // Score < 50
}
}

Score-to-Tier Mapping:

• Critical (>= 90): Immediate action required - blocks progress
• High (70-89.9): Should be addressed this sprint
• Moderate (50-69.9): Plan for next sprint
• Low (< 50): Background maintenance work

Effort Estimates Per Tier

Each tier includes estimated effort based on typical remediation patterns:

Effort calculation considers:

• Complexity metrics (cyclomatic, cognitive)
• Test coverage gaps
• Number of dependencies (upstream/downstream)
• Debt category (Architecture debt takes longer than CodeQuality)

Tiered Display Grouping

Note: TieredDisplay is an internal structure (src/priority/mod.rs:416-422) used for terminal output formatting and is not serialized to JSON. JSON output includes individual items with their priority field (critical, high, medium, low) based on Priority thresholds (100/50/20), not Tier thresholds (90/70/50). See Tier vs Priority above.

The internal TieredDisplay structure groups similar debt items for batch action recommendations in terminal output:

Grouping strategy:

• Groups items by tier (Critical/High/Moderate/Low) and similarity pattern
• Prevents grouping of god objects (always show individually)
• Prevents grouping of Critical items (each needs individual attention)
• Suggests batch actions for similar Low/Moderate items in terminal output

To view items by priority in JSON:

# Get all Critical items (priority: "critical", score >= 100)
debtmap analyze . --format json | jq '.items[] | select(.priority == "critical")'

# Get High priority items (score >= 50)
debtmap analyze . --format json | jq '.items[] | select(.priority == "high")'

# Count items by priority (uses Priority thresholds: 100/50/20)
debtmap analyze . --format json | jq '.summary.score_distribution'

The score_distribution in the summary provides counts using Priority thresholds (critical >= 100, high >= 50, medium >= 20, low < 20).

Using Tiered Prioritization

1. Start with Critical tier:

debtmap analyze . --min-priority critical

Focus on items with score ≥ 90. These typically represent:

• Complex functions with 0% coverage
• God objects blocking feature development
• Critical resource leaks or security issues

2. Plan High tier work:

debtmap analyze . --min-priority high --format json > sprint-plan.json

Schedule 2-4 hours per item for this sprint. Look for:

• Functions approaching complexity thresholds
• Moderate coverage gaps on important code paths
• Performance bottlenecks with clear solutions

3. Batch Moderate tier items:

debtmap analyze . --min-priority moderate

Review batch recommendations. Examples:

• “10 validation functions detected - extract common pattern”
• “5 similar test files with duplication - create shared fixtures”
• “8 functions with magic values - create constants module”

4. Schedule Low tier background work: Address during slack time or as warm-up tasks for new contributors.

Strategic Guidance by Tier

Critical Tier Strategy:

• Block new features until addressed
• Pair programming recommended for complex items
• Architectural review before major refactoring
• Comprehensive testing after changes

High Tier Strategy:

• Sprint planning priority
• Impact analysis before changes
• Code review from senior developers
• Integration testing after changes

Moderate Tier Strategy:

• Batch similar items for efficiency
• Extract patterns across multiple files
• Incremental improvement over multiple PRs
• Regression testing for affected areas

Low Tier Strategy:

• Good first issues for new contributors
• Documentation improvements
• Code cleanup during refactoring nearby code
• Technical debt gardening sessions

Categorized Debt Analysis

Note: CategorizedDebt is an internal analysis structure (src/priority/mod.rs:419) used for query operations and markdown formatting. It is not serialized to JSON output. The JSON output uses by_category in the summary section instead (see JSON Structure above).

Debtmap’s internal CategorizedDebt analysis groups debt items by category and identifies cross-category dependencies. This analysis powers the markdown output and internal query methods but is not directly exposed in JSON format.

CategorySummary

Each category gets a summary with metrics for planning:

#![allow(unused)]
fn main() {
pub struct CategorySummary {
    pub category: DebtCategory,
    pub total_score: f64,
    pub item_count: usize,
    pub estimated_effort_hours: f64,
    pub average_severity: f64,
    pub top_items: Vec<DebtItem>,  // Up to 5 highest priority
}
}

Effort estimation formulas:

• Architecture debt: complexity_score / 10 × 2 hours (structural changes take longer)
• Testing debt: complexity_score / 10 × 1.5 hours (writing tests)
• Performance debt: complexity_score / 10 × 1.8 hours (profiling + optimization)
• CodeQuality debt: complexity_score / 10 × 1.2 hours (refactoring)

Example category summary:

{
  "category": "Architecture",
  "total_score": 487.5,
  "item_count": 15,
  "estimated_effort_hours": 97.5,
  "average_severity": 32.5,
  "top_items": [
    {
      "debt_type": "GodObject",
      "file": "src/services/user_service.rs",
      "score": 95.0,
      "estimated_effort_hours": 16.0
    },
    {
      "debt_type": "ComplexityHotspot",
      "file": "src/payments/processor.rs",
      "score": 87.3,
      "estimated_effort_hours": 14.0
    }
  ]
}

Cross-Category Dependencies

CrossCategoryDependency identifies blocking relationships between different debt categories:

#![allow(unused)]
fn main() {
pub struct CrossCategoryDependency {
    pub from_category: DebtCategory,
    pub to_category: DebtCategory,
    pub blocking_items: Vec<(DebtItem, DebtItem)>,
    pub impact_level: ImpactLevel,  // Critical, High, Medium, Low
    pub recommendation: String,
}
}

Common dependency patterns:

1. Architecture blocks Testing:

• Pattern: God objects are too complex to test effectively
• Example: UserService has 50+ functions, making comprehensive testing impractical
• Impact: Critical - cannot improve test coverage without refactoring
• Recommendation: “Split god object into 4-5 focused modules before adding tests”

2. Async issues require Architecture changes:

• Pattern: Blocking I/O in async contexts requires architectural redesign
• Example: Sync database calls in async handlers
• Impact: High - performance problems require design changes
• Recommendation: “Introduce async database layer before optimizing handlers”

3. Complexity affects Testability:

• Pattern: High cyclomatic complexity makes thorough testing difficult
• Example: Function with 22 branches needs 22+ test cases
• Impact: High - testing effort grows exponentially with complexity
• Recommendation: “Reduce complexity to < 10 before writing comprehensive tests”

4. Performance requires Architecture:

• Pattern: O(n²) nested loops need different data structures
• Example: Linear search in loops should use HashMap
• Impact: Medium - optimization requires structural changes
• Recommendation: “Refactor data structure before micro-optimizations”

Example cross-category dependency:

{
  "from_category": "Architecture",
  "to_category": "Testing",
  "impact_level": "Critical",
  "blocking_items": [
    {
      "blocker": {
        "debt_type": "GodObject",
        "file": "src/services/user_service.rs",
        "functions": 52,
        "score": 95.0
      },
      "blocked": {
        "debt_type": "TestingGap",
        "file": "src/services/user_service.rs",
        "coverage": 15,
        "score": 78.0
      }
    }
  ],
  "recommendation": "Split UserService into focused modules (auth, profile, settings, notifications) before attempting to improve test coverage. Current structure makes comprehensive testing impractical.",
  "estimated_unblock_effort_hours": 16.0
}

Using Category-Based Analysis

View category distribution in JSON:

debtmap analyze . --format json | jq '.summary.by_category'

This shows item counts per category (Architecture, Testing, Performance, CodeQuality).

Filter items by category:

debtmap analyze . --format json | jq '.items[] | select(.category == "Architecture")'

Focus on specific category with CLI:

debtmap analyze . --filter Architecture --top 10

Generate markdown for detailed category analysis:

debtmap analyze . --format markdown --output report.md

The markdown format includes full CategorySummary details with effort estimates and cross-category dependency analysis.

Strategic planning workflow:

1. Review category summaries:

   • Identify which category has highest total score
   • Check estimated effort hours per category
   • Note average severity to gauge urgency

2. Check cross-category dependencies:

   • Find Critical and High impact blockers
   • Prioritize blockers before blocked items
   • Plan architectural changes before optimization

3. Plan remediation order:

   Example decision tree:
   - Architecture score > 400? → Address god objects first
   - Testing gap with low complexity? → Quick wins, add tests
   - Performance issues + architecture debt? → Refactor structure first
   - High code quality debt but good architecture? → Incremental cleanup
   

4. Use category-specific strategies:

   • Architecture: Pair programming, design reviews, incremental refactoring
   • Testing: TDD for new code, characterization tests for legacy
   • Performance: Profiling first, optimize hot paths, avoid premature optimization
   • CodeQuality: Code review focus, linting rules, consistent patterns

Note on output formats: CategorySummary and CrossCategoryDependency details are available in markdown format only. The JSON output provides category counts in summary.by_category and you can filter items by category using the category field on each item.

Debt Density Metric

Debt density normalizes technical debt scores across projects of different sizes, providing a per-1000-lines-of-code metric for fair comparison.

Formula

debt_density = (total_debt_score / total_lines_of_code) × 1000

Example calculation:

Project A:
  - Total debt score: 1,250
  - Total lines of code: 25,000
  - Debt density: (1,250 / 25,000) × 1000 = 50

Project B:
  - Total debt score: 2,500
  - Total lines of code: 50,000
  - Debt density: (2,500 / 50,000) × 1000 = 50

Projects A and B have equal debt density (50) despite B having twice the absolute debt, because B is also twice as large. They have proportionally similar technical debt.

Interpretation Guidelines

Use these thresholds to assess codebase health:

Context matters:

• Early-stage projects: Often have higher density (rapid iteration)
• Mature projects: Should trend toward lower density over time
• Legacy systems: May have high density, track trend over time
• Greenfield rewrites: Aim for density < 50

Using Debt Density

1. Compare projects fairly:

# Small microservice (5,000 LOC, debt = 250)
# Debt density: 50

# Large monolith (100,000 LOC, debt = 5,000)
# Debt density: 50

# Equal health despite size difference

2. Track improvement over time:

Sprint 1: 50,000 LOC, debt = 7,500, density = 150 (High)
Sprint 5: 52,000 LOC, debt = 6,500, density = 125 (Improving)
Sprint 10: 54,000 LOC, debt = 4,860, density = 90 (Moderate)

3. Set team goals:

Current density: 120
Target density: < 80 (by Q4)
Reduction needed: 40 points

Strategy:
- Fix 2-3 Critical items per sprint
- Prevent new debt (enforce thresholds)
- Refactor before adding features in high-debt modules

4. Benchmark across teams/projects:

{
  "team_metrics": [
    {
      "project": "auth-service",
      "debt_density": 45,
      "assessment": "Clean",
      "trend": "stable"
    },
    {
      "project": "billing-service",
      "debt_density": 95,
      "assessment": "Moderate",
      "trend": "improving"
    },
    {
      "project": "legacy-api",
      "debt_density": 165,
      "assessment": "Critical",
      "trend": "worsening"
    }
  ]
}

Limitations

Debt density doesn’t account for:

• Code importance: 100 LOC in payment logic ≠ 100 LOC in logging utils
• Complexity distribution: One 1000-line god object vs. 1000 simple functions
• Test coverage: 50% coverage on critical paths vs. low-priority features
• Team familiarity: New codebase vs. well-understood legacy system

Best practices:

• Use density as one metric among many
• Combine with category analysis and tiered prioritization
• Focus on trend (improving/stable/worsening) over absolute number
• Consider debt per module for more granular insights

Debt Density in CI/CD

Track density over time:

# Generate report with density
debtmap analyze . --format json --output debt-report.json

# Extract density for trending
DENSITY=$(jq '.debt_density' debt-report.json)

# Store in metrics database
echo "debtmap.density:${DENSITY}|g" | nc -u -w0 statsd 8125

Set threshold gates:

# .github/workflows/debt-check.yml
- name: Check debt density
  run: |
    DENSITY=$(debtmap analyze . --format json | jq '.debt_density')
    if (( $(echo "$DENSITY > 150" | bc -l) )); then
      echo "❌ Debt density too high: $DENSITY (limit: 150)"
      exit 1
    fi
    echo "✅ Debt density acceptable: $DENSITY"

Actionable Insights

Each recommendation includes:

ACTION: What to do

• “Add 6 unit tests for full coverage”
• “Refactor into 3 smaller functions”
• “Extract validation to separate function”

IMPACT: Expected improvement

• “Full test coverage, -3.7 risk”
• “Reduce complexity from 22 to 8”
• “Eliminate 120 lines of duplication”

WHY: Rationale

• “Business logic with 0% coverage, manageable complexity”
• “High complexity with low coverage threatens stability”
• “Repeated validation pattern across 5 files”

Example workflow:

1. Run analysis with coverage: debtmap analyze . --lcov coverage.lcov
2. Filter to CRITICAL items: --min-priority critical
3. Review top 5 recommendations
4. Start with highest ROI items
5. Rerun analysis to track progress

Common Patterns to Recognize

Pattern 1: High Complexity, Well Tested

Complexity: 25, Coverage: 95%, Risk: LOW

This is actually good! Complex but thoroughly tested code. Learn from this approach.

Pattern 2: Moderate Complexity, No Tests

Complexity: 12, Coverage: 0%, Risk: CRITICAL

Highest priority - manageable complexity, should be easy to test.

Pattern 3: Low Complexity, No Tests

Complexity: 3, Coverage: 0%, Risk: LOW

Low priority - simple code, less risky without tests.

Pattern 4: Repetitive High Complexity (Dampened)

Cyclomatic: 20, Effective: 7 (65% dampened), Risk: LOW

Validation or dispatch pattern - looks complex but is repetitive. Lower priority.

Pattern 5: God Object

File: services.rs, Functions: 50+, Responsibilities: 15+

Architectural issue - split before adding features.

See Also

• Complexity Metrics - Detailed explanation of cyclomatic, cognitive, and entropy metrics
• Risk Scoring - How debt scores and risk assessments are calculated
• CLI Reference - Complete command-line options for output formats and filtering
• Output Formats - Detailed documentation of JSON, Markdown, and HTML output

Analyzer Types

Overview

Debtmap is a Rust-only code analysis tool. As of specification 191, debtmap focuses exclusively on Rust codebases to provide deep, language-specific insights into code complexity, technical debt, and architectural patterns.

While the architecture supports extensibility through the Analyzer trait, only Rust is actively supported and maintained. Files in other programming languages are automatically filtered during discovery and never reach the analysis phase.

Source: Language enum at src/core/mod.rs:416-421, AnalyzerFactory at src/core/injection.rs:190-203

Rust Analyzer

Debtmap provides comprehensive analysis for Rust codebases using the syn crate for native AST parsing.

Core Capabilities

The Rust analyzer (src/analyzers/rust.rs) provides:

• Complexity Metrics: Cyclomatic complexity, cognitive complexity, and entropy analysis
• Purity Detection: Identifies pure functions with confidence scoring
• Call Graph Analysis: Tracks upstream callers and downstream callees with transitive relationships
• Trait Implementation Tracking: Monitors trait implementations across the codebase
• Macro Expansion Support: Analyzes complexity within macros accurately
• Pattern-Based Adjustments: Recognizes and adjusts for code generation patterns
• Visibility Tracking: Distinguishes pub, pub(crate), and private functions
• Test Module Detection: Identifies #[cfg(test)] modules and #[test] functions

Source: Capabilities verified in src/analyzers/rust.rs:1-100

Semantic Function Classification

The Rust analyzer automatically classifies functions by their role in the system. This classification feeds into the unified scoring system’s role multiplier for accurate technical debt assessment.

Classification Categories (src/analyzers/rust.rs):

• Entry Points: Functions named main, start, or public functions in bin/ modules
• Business Logic: Core domain functions containing complex algorithms and business rules
• Data Access: Functions performing database queries, file I/O, or network operations
• Infrastructure: Logging, configuration, monitoring, and error handling utilities
• Utilities: Helper functions, formatters, type converters, and validation functions
• Test Code: Functions in #[cfg(test)] modules or marked with #[test] attribute

These classifications are used to calculate role-based priority multipliers in the risk scoring system. See Risk Scoring for details on how semantic classification affects debt prioritization.

Language Support

Supported: Rust Only

Debtmap exclusively analyzes Rust source files (.rs extension). All analysis features, metrics, and debt detection patterns are designed specifically for Rust’s syntax and semantics.

Language Detection (src/core/mod.rs:435-440):

#![allow(unused)]
fn main() {
pub fn from_path(path: &std::path::Path) -> Self {
    path.extension()
        .and_then(|ext| ext.to_str())
        .map(Self::from_extension)
        .unwrap_or(Language::Unknown)
}
}

The Language enum (src/core/mod.rs:416-421) includes Rust, Python, and Unknown variants, but only Rust is actively processed:

#![allow(unused)]
fn main() {
pub enum Language {
    Rust,
    Python,  // Architectural placeholder, not supported
    Unknown,
}
}

File Filtering Behavior

During file discovery, debtmap filters files by extension:

1. Rust files (.rs): Parsed and analyzed
2. All other files: Silently filtered out—no warnings or errors generated
3. Unknown extensions: Mapped to Language::Unknown and filtered during discovery

Source: Language detection implemented in src/core/mod.rs:423-440

Example Usage:

# Analyze all Rust files in current directory
debtmap analyze .

# Analyze specific Rust file
debtmap analyze src/main.rs

# Python, JavaScript, and other files are ignored
# (no error messages, just skipped)

Extensibility

While debtmap currently focuses on Rust-only analysis, the architecture is designed to support additional languages in the future through the Analyzer trait.

Analyzer Trait

The core Analyzer trait defines the interface for language-specific analyzers (src/analyzers/mod.rs:40-44):

#![allow(unused)]
fn main() {
pub trait Analyzer: Send + Sync {
    fn parse(&self, content: &str, path: std::path::PathBuf) -> Result<Ast>;
    fn analyze(&self, ast: &Ast) -> FileMetrics;
    fn language(&self) -> crate::core::Language;
}
}

Note: There is also a generic Analyzer trait with associated types in src/core/traits.rs:11-16, used for internal abstractions. The trait shown above is the public extension point for language analyzers.

Current Implementation

The AnalyzerFactory (src/core/injection.rs:190-203) creates language-specific analyzers:

#![allow(unused)]
fn main() {
impl AnalyzerFactory {
    pub fn create_analyzer(&self, language: Language) -> Box<dyn Analyzer<...>> {
        match language {
            Language::Rust => Box::new(RustAnalyzerAdapter::new()),
            Language::Python => {
                panic!("Python analysis is not currently supported.
                       Debtmap is focusing exclusively on Rust analysis.")
            }
        }
    }
}
}

Adding Language Support (Future)

To add support for a new language:

1. Implement the Analyzer trait with language-specific parsing and analysis
2. Add the language variant to the Language enum (src/core/mod.rs:416-421)
3. Update from_extension() to recognize the file extension (src/core/mod.rs:423-433)
4. Register in AnalyzerFactory to instantiate your analyzer (src/core/injection.rs:190-203)

Reference Implementation: See src/analyzers/rust.rs for a complete example of implementing the Analyzer trait with full complexity analysis, purity detection, and call graph support.

See Also

• Overview - Analysis pipeline and workflow
• Complexity Metrics - Detailed metric calculations
• Risk Scoring - How semantic classification affects prioritization

Advanced Features

This section covers Debtmap’s advanced analysis capabilities: purity detection, data flow analysis, entropy-based complexity, and context-aware analysis.

Purity Detection

Debtmap detects pure functions - those without side effects that always return the same output for the same input.

What makes a function pure:

• No I/O operations (file, network, database)
• No mutable global state
• No random number generation
• No system calls
• Deterministic output

Purity detection is optional:

• Both is_pure and purity_confidence are Option types
• May be None for some functions or languages where detection is not available
• Rust has the most comprehensive purity detection support

Four-level purity classification: The PurityLevel enum (src/core/mod.rs:49-62) provides more nuanced classification than the binary is_pure:

• StrictlyPure: No mutations whatsoever - pure mathematical functions
• LocallyPure: Uses local mutations for efficiency but no external side effects (builder patterns, accumulators, owned mut self)
• ReadOnly: Reads external state but doesn’t modify it (constants, &self methods)
• Impure: Modifies external state or performs I/O (&mut self, statics, I/O)

This four-level classification enables better scoring for functions that use local mutations for efficiency but are functionally pure (referentially transparent). See Complexity Metrics for how purity affects scoring.

Confidence scoring (when available):

• 0.9-1.0: Very confident (no side effects detected)
• 0.7-0.8: Likely pure (minimal suspicious patterns)
• 0.5-0.6: Uncertain (some suspicious patterns)
• 0.0-0.4: Likely impure (side effects detected)

Example:

#![allow(unused)]
fn main() {
// Pure: confidence = 0.95
fn calculate_total(items: &[Item]) -> f64 {
    items.iter().map(|i| i.price).sum()
}

// Impure: confidence = 0.1 (I/O detected)
fn save_total(items: &[Item]) -> Result<()> {
    let total = items.iter().map(|i| i.price).sum();
    write_to_file(total)  // Side effect!
}
}

Benefits:

• Pure functions are easier to test
• Can be safely cached or memoized
• Safe to parallelize
• Easier to reason about

Data Flow Analysis

Debtmap builds a comprehensive DataFlowGraph that extends basic call graph analysis with variable dependencies, data transformations, I/O operations, and purity tracking.

Call Graph Foundation

Upstream callers - Who calls this function

• Indicates impact radius
• More callers = higher impact if it breaks

Downstream callees - What this function calls

• Indicates dependencies
• More callees = more integration testing needed

Example:

{
  "name": "process_payment",
  "upstream_callers": [
    "handle_checkout",
    "process_subscription",
    "handle_refund"
  ],
  "downstream_callees": [
    "validate_payment_method",
    "calculate_fees",
    "record_transaction",
    "send_receipt"
  ]
}

Variable Dependency Tracking

DataFlowGraph tracks which variables each function depends on (src/data_flow/mod.rs:119):

#![allow(unused)]
fn main() {
pub struct DataFlowGraph {
    // Maps function_id -> set of variable names used
    variable_deps: HashMap<FunctionId, HashSet<String>>,
    // ...
}
}

What it tracks:

• Function parameters (primary source via extraction adapters)
• Local variables accessed in function body
• Captured variables (closures)

Note: Variable dependency tracking stores variable names only (as HashSet<String>). It does not track mutability information - that analysis is handled separately by the purity detection system.

Benefits:

• Identify functions coupled through shared state
• Detect potential side effect chains
• Guide refactoring to reduce coupling

Example output:

{
  "function": "calculate_total",
  "variable_dependencies": ["items", "tax_rate", "discount", "total"],
  "parameter_count": 3,
  "local_var_count": 1
}

Data Transformation Patterns

DataFlowGraph tracks data transformations between functions. The TransformationType enum (src/organization/data_flow_analyzer.rs:35-46) classifies transformations by their input/output cardinality:

#![allow(unused)]
fn main() {
pub enum TransformationType {
    Direct,        // A → B (pure transformation)
    Aggregation,   // (A, B) → C (multiple inputs to single output)
    Decomposition, // A → (B, C) (single input to multiple outputs)
    Enrichment,    // A → Result<B> (validation/enrichment with Result/Option)
    Expansion,     // A → Vec<B> (single input to collection)
}
}

Classification logic (src/organization/data_flow_analyzer.rs:124-146):

• Multiple input parameters → Aggregation
• Return type is Result<T> or Option<T> → Enrichment
• Return type is Vec<T> → Expansion
• Return type is tuple → Decomposition
• Default → Direct

Example usage:

#![allow(unused)]
fn main() {
// Aggregation: (items, discount_rate) → f64
fn calculate_discounted_total(items: &[Item], discount_rate: f64) -> f64 {
    items.iter().map(|i| i.price).sum::<f64>() * (1.0 - discount_rate)
}

// Enrichment: Config → Result<ValidatedConfig>
fn validate_config(config: Config) -> Result<ValidatedConfig> {
    // ...
}

// Expansion: Order → Vec<LineItem>
fn extract_line_items(order: &Order) -> Vec<LineItem> {
    order.items.clone()
}
}

Note: The DataFlowGraph.data_transformations field (src/data_flow/mod.rs:149) stores transformation_type as a String, allowing flexible pattern descriptions beyond the enum variants.

I/O Operation Detection

Tracks functions performing I/O operations for purity and performance analysis:

I/O categories tracked:

• File I/O: std::fs, File::open, read_to_string
• Network I/O: HTTP requests, socket operations
• Database I/O: SQL queries, ORM operations
• System calls: Process spawning, environment access
• Blocking operations: thread::sleep, synchronous I/O in async

Example detection:

#![allow(unused)]
fn main() {
// Detected I/O operations: FileRead, FileWrite
fn save_config(config: &Config, path: &Path) -> Result<()> {
    let json = serde_json::to_string(config)?;  // No I/O
    std::fs::write(path, json)?;                 // FileWrite detected
    Ok(())
}
}

I/O metadata:

{
  "function": "save_config",
  "io_operations": ["FileWrite"],
  "is_blocking": true,
  "affects_purity": true,
  "async_safe": false
}

Purity Analysis Integration

DataFlowGraph integrates with purity detection to provide comprehensive side effect analysis:

Side effect tracking:

• I/O operations (file, network, console)
• Global state mutations
• Random number generation
• System time access
• Non-deterministic behavior

Purity confidence factors:

• 1.0: Pure mathematical function, no side effects
• 0.8: Pure with deterministic data transformations
• 0.5: Mixed - some suspicious patterns
• 0.2: Likely impure - I/O detected
• 0.0: Definitely impure - multiple side effects

Example analysis:

{
  "function": "calculate_discount",
  "is_pure": true,
  "purity_confidence": 0.95,
  "side_effects": [],
  "deterministic": true,
  "safe_to_parallelize": true,
  "safe_to_cache": true
}

Modification Impact Analysis

DataFlowGraph calculates the impact of modifying a function:

#![allow(unused)]
fn main() {
pub struct ModificationImpact {
    pub function_name: String,
    pub affected_functions: Vec<String>,  // Upstream callers
    pub dependency_count: usize,          // Downstream callees
    pub has_side_effects: bool,
    pub risk_level: RiskLevel,
}
}

Risk level calculation:

• Critical: Many upstream callers + side effects + low test coverage
• High: Many callers OR side effects with moderate coverage
• Medium: Few callers with side effects OR many callers with good coverage
• Low: Few callers, no side effects, or well-tested

Example impact analysis:

{
  "function": "validate_payment_method",
  "modification_impact": {
    "affected_functions": 4,
    "dependency_count": 8,
    "has_side_effects": true,
    "risk_level": "High"
  }
}

Note: The affected_functions field contains the count of upstream callers. The actual function names can be obtained from the upstream_callers field in the function metadata.

Using modification impact:

# Analyze impact before refactoring
debtmap analyze . --format json | jq '.functions[] | select(.name == "validate_payment_method") | .modification_impact'

Impact analysis uses:

• Refactoring planning: Understand blast radius before changes
• Test prioritization: Focus tests on high-impact functions
• Code review: Flag high-risk changes for extra scrutiny
• Dependency management: Identify tightly coupled components

DataFlowGraph Methods

Key methods for data flow analysis:

#![allow(unused)]
fn main() {
// Add function with its dependencies
pub fn add_function(&mut self, function_id: String, callees: Vec<String>)

// Track variable dependencies
pub fn add_variable_dependency(&mut self, function_id: String, var_name: String)

// Record I/O operations
pub fn add_io_operation(&mut self, function_id: String, io_type: IoType)

// Calculate modification impact
pub fn calculate_modification_impact(&self, function_id: &str) -> ModificationImpact

// Get all functions affected by a change
pub fn get_affected_functions(&self, function_id: &str) -> Vec<String>

// Find functions with side effects
pub fn find_functions_with_side_effects(&self) -> Vec<String>
}

Integration in analysis pipeline:

1. Parser builds initial call graph
2. DataFlowGraph extends with variable/I/O tracking
3. Purity analyzer adds side effect information
4. Modification impact calculated for each function
5. Results used in prioritization and risk scoring

Connection to Unified Scoring:

The dependency analysis from DataFlowGraph directly feeds into the unified scoring system’s dependency factor (20% weight):

• Dependency Factor Calculation: Functions with high upstream caller count or on critical paths from entry points receive higher dependency scores (8-10)
• Isolated Utilities: Functions with few or no callers score lower (1-3) on dependency factor
• Impact Prioritization: This helps prioritize functions where bugs have wider impact across the codebase
• Modification Risk: The modification impact analysis uses dependency data to calculate blast radius when changes are made

Example:

Function: validate_payment_method
  Upstream callers: 4 (high impact)
  → Dependency Factor: 8.0

Function: format_currency_string
  Upstream callers: 0 (utility)
  → Dependency Factor: 1.5

Both have same complexity, but validate_payment_method gets higher unified score
due to its critical role in the call graph.

This integration ensures that the unified scoring system considers not just internal function complexity and test coverage, but also the function’s importance in the broader codebase architecture.

Entropy-Based Complexity

Advanced pattern detection to reduce false positives.

Token Classification:

#![allow(unused)]
fn main() {
enum TokenType {
    Variable,     // Weight: 1.0
    Method,       // Weight: 1.5 (more important)
    Literal,      // Weight: 0.5 (less important)
    Keyword,      // Weight: 0.8
    Operator,     // Weight: 0.6
}
}

Shannon Entropy Calculation:

H(X) = -Σ p(x) × log₂(p(x))

where p(x) is the probability of each token type.

Dampening Decision:

#![allow(unused)]
fn main() {
if entropy_score.token_entropy < 0.4
   && entropy_score.pattern_repetition > 0.6
   && entropy_score.branch_similarity > 0.7
{
    // Apply dampening
    effective_complexity = base_complexity × (1 - dampening_factor);
}
}

Output explanation:

Function: validate_input
  Cyclomatic: 15 → Effective: 5
  Reasoning:
    - High pattern repetition detected (85%)
    - Low token entropy indicates simple patterns (0.32)
    - Similar branch structures found (92% similarity)
    - Complexity reduced by 67% due to pattern-based code

Entropy Analysis Caching

EntropyAnalyzer includes an LRU-style cache for performance optimization when analyzing large codebases or performing repeated analysis.

Cache Structure

#![allow(unused)]
fn main() {
struct CacheEntry {
    score: EntropyScore,
    timestamp: Instant,
    hit_count: usize,
}
}

Cache configuration:

• Default size: 1000 entries
• Eviction policy: LRU (Least Recently Used)
• Memory per entry: ~128 bytes
• Total memory overhead: ~128 KB for default size

Cache Statistics

The analyzer tracks cache performance:

#![allow(unused)]
fn main() {
pub struct CacheStats {
    pub hits: usize,
    pub misses: usize,
    pub evictions: usize,
    pub hit_rate: f64,
    pub memory_usage: usize,
}
}

Example stats output:

{
  "entropy_cache_stats": {
    "hits": 3427,
    "misses": 1573,
    "evictions": 573,
    "hit_rate": 0.685,
    "memory_usage": 128000
  }
}

Hit rate interpretation:

• > 0.7: Excellent - many repeated analyses, cache is effective
• 0.4-0.7: Good - moderate reuse, typical for incremental analysis
• < 0.4: Low - mostly unique functions, cache less helpful

Performance Benefits

Typical performance gains:

• Cold analysis: 100ms baseline (no cache benefit)
• Incremental analysis: 30-40ms (~60-70% faster) for unchanged functions
• Re-analysis: 15-20ms (~80-85% faster) for recently analyzed functions

Best for:

• Watch mode: Analyzing on file save (repeated analysis of same files)
• CI/CD: Comparing feature branch to main (overlap in functions)
• Large codebases: Many similar functions benefit from pattern caching

Memory estimation:

Total cache memory = entry_count × 128 bytes

Examples:
- 1,000 entries: ~128 KB (default)
- 5,000 entries: ~640 KB (large projects)
- 10,000 entries: ~1.25 MB (very large)

Cache Management

Automatic eviction:

• When cache reaches size limit, oldest entries evicted
• Hit count influences retention (frequently accessed stay longer)
• Timestamp used for LRU ordering

Cache invalidation:

• Function source changes invalidate entry
• Cache cleared between major analysis runs
• No manual invalidation needed

Configuration (if exposed in future):

[entropy.cache]
enabled = true
size = 1000           # Number of entries
ttl_seconds = 3600    # Optional: expire after 1 hour

Context-Aware Analysis

Debtmap adjusts analysis based on code context:

Pattern Recognition:

• Validation patterns (repetitive checks)
• Dispatcher patterns (routing logic)
• Builder patterns (fluent APIs)
• Configuration parsers (key-value processing)

Adjustment Strategies:

• Reduce false positives for recognized patterns
• Apply appropriate thresholds by pattern type
• Consider pattern confidence in scoring

Example:

#![allow(unused)]
fn main() {
// Recognized as "validation_pattern"
// Complexity dampening applied
fn validate_user_input(input: &UserInput) -> Result<()> {
    if input.name.is_empty() { return Err(Error::EmptyName); }
    if input.email.is_empty() { return Err(Error::EmptyEmail); }
    if input.age < 13 { return Err(Error::TooYoung); }
    // ... more similar validations
    Ok(())
}
}

Coverage Integration

Debtmap parses LCOV coverage data for risk analysis:

LCOV Support:

• Standard format from most coverage tools
• Line-level coverage tracking
• Function-level aggregation

Coverage Index:

• O(1) exact name lookups (~0.5μs)
• O(log n) line-based fallback (~5-8μs)
• ~200 bytes per function
• Thread-safe (Arc<CoverageIndex>)

Performance Characteristics

Index Build Performance:

• Index construction: O(n), approximately 20-30ms for 5,000 functions
• Memory usage: ~200 bytes per record (~2MB for 5,000 functions)
• Scales linearly with function count

Lookup Performance:

• Exact match (function name): O(1) average, ~0.5μs per lookup
• Line-based fallback: O(log n), ~5-8μs per lookup
• Cache-friendly data structure for hot paths

Analysis Overhead:

• Coverage integration overhead: ~2.5x baseline analysis time
• Target overhead: ≤3x (maintained through optimizations)
• Example timing: 53ms baseline → 130ms with coverage (2.45x overhead)
• Overhead includes index build + lookups + coverage propagation

When to use coverage integration:

• Skip coverage (faster iteration): For rapid development iteration or quick local checks, omit --lcov to get baseline results 2.5x faster
• Include coverage (comprehensive analysis): Use coverage integration for final validation, sprint planning, and CI/CD gates where comprehensive risk analysis is needed

Thread Safety:

• Coverage index wrapped in Arc<CoverageIndex> for lock-free parallel access
• Multiple analyzer threads can query coverage simultaneously
• No contention on reads, suitable for parallel analysis pipelines

Memory Footprint:

Total memory = (function_count × 200 bytes) + index overhead

Examples:
- 1,000 functions: ~200 KB
- 5,000 functions: ~2 MB
- 10,000 functions: ~4 MB

Scalability:

• Tested with codebases up to 10,000 functions
• Performance remains predictable and acceptable
• Memory usage stays bounded and reasonable

Generating coverage:

# Rust (using cargo-tarpaulin)
cargo tarpaulin --out lcov --output-dir target/coverage

# Or using cargo-llvm-cov
cargo llvm-cov --lcov --output-path target/coverage/lcov.info

Using with Debtmap:

debtmap analyze . --lcov target/coverage/lcov.info

Coverage dampening: When coverage data is provided, debt scores are dampened for well-tested code:

final_score = base_score × (1 - coverage_percentage)

This ensures well-tested complex code gets lower priority than untested simple code.

See Also

• Complexity Metrics - Detailed metrics used in analysis
• Risk Scoring - How advanced features influence risk scores
• Interpreting Results - Using analysis results effectively

Example Outputs

This page demonstrates realistic examples of debtmap’s terminal and JSON output formats using the unified format (spec 108).

High Complexity Function (Needs Refactoring)

Terminal Output:

#1 SCORE: 9.2 [CRITICAL]
├─ COMPLEXITY: ./src/payments/processor.rs:145 process_transaction()
├─ ACTION: Refactor into 4 smaller functions
├─ IMPACT: Reduce complexity from 25 to 8, improve testability
├─ COMPLEXITY: cyclomatic=25, branches=25, cognitive=38, nesting=5, lines=120
├─ DEPENDENCIES: 3 upstream, 8 downstream
└─ WHY: Exceeds all complexity thresholds, difficult to test and maintain

JSON Output (Unified Format):

{
  "type": "Function",
  "score": 92.5,
  "category": "CodeQuality",
  "priority": "critical",
  "location": {
    "file": "src/payments/processor.rs",
    "line": 145,
    "function": "process_transaction"
  },
  "metrics": {
    "cyclomatic_complexity": 25,
    "cognitive_complexity": 38,
    "length": 120,
    "nesting_depth": 5,
    "coverage": 0.15,
    "uncovered_lines": [145, 147, 152, 158, 165, 172, 180, 185]
  },
  "debt_type": {
    "ComplexityHotspot": {
      "cyclomatic": 25,
      "cognitive": 38,
      "adjusted_cyclomatic": null
    }
  },
  "function_role": "Orchestrator",
  "purity_analysis": {
    "is_pure": false,
    "confidence": 0.15,
    "side_effects": ["mutates_state", "io_operations", "database_access"]
  },
  "dependencies": {
    "upstream_count": 3,
    "downstream_count": 8,
    "upstream_callers": [
      "handle_payment",
      "handle_subscription",
      "handle_refund"
    ],
    "downstream_callees": [
      "validate",
      "calculate_fees",
      "record_transaction",
      "send_receipt",
      "update_balance",
      "log_transaction",
      "check_fraud",
      "notify_user"
    ]
  },
  "recommendation": {
    "action": "Refactor into 4 smaller, focused functions",
    "implementation_steps": [
      "Extract validation logic into validate_payment_request",
      "Create calculate_payment_totals for fee calculation",
      "Move side effects to separate transaction recorder",
      "Keep process_transaction as thin orchestrator"
    ]
  },
  "impact": {
    "coverage_improvement": 0.55,
    "complexity_reduction": 68.0,
    "risk_reduction": 7.8
  },
  "scoring_details": {
    "coverage_score": 45.0,
    "complexity_score": 38.5,
    "dependency_score": 9.0,
    "base_score": 92.5,
    "role_multiplier": 1.0,
    "final_score": 92.5
  }
}

Source: Structure from src/output/unified/func_item.rs:FunctionDebtItemOutput (lines 50-84)

Key Fields Explained:

• type: Always "Function" for function-level debt items
• score: Unified debt score (same path for File and Function items)
• category: One of CodeQuality, Architecture, Testing, Performance
• priority: Derived from score (critical >= 100, high >= 50, medium >= 20, low < 20)
• location: Unified location structure with file, line, and function name
• function_role: Classification from FunctionRole enum (see below)
• debt_type: Tagged enum with variant-specific data

Function Role Classification

The function_role field helps prioritize testing and refactoring efforts based on the function’s architectural purpose.

Source: src/priority/semantic_classifier/mod.rs:25-33

{
  "function_role": "PureLogic"
}

Available Roles:

• PureLogic - Business logic, high test priority
• Orchestrator - Coordinates other functions (like the example above)
• IOWrapper - Thin I/O layer, lower test priority
• EntryPoint - Main entry points (main, CLI handlers)
• PatternMatch - Pattern matching function (often low complexity)
• Debug - Debug/diagnostic functions (low test priority)
• Unknown - Cannot classify automatically

File-Level Debt (God Object)

Terminal Output:

#2 SCORE: 8.7 [HIGH]
├─ GOD OBJECT: ./src/services/user_manager.rs
├─ ACTION: Split into 4 focused modules
├─ METRICS: 1250 lines, 45 functions, avg complexity 12.3
├─ INDICATORS: High responsibility count (8), excessive dependencies
└─ WHY: File has too many responsibilities, difficult to maintain

JSON Output (Unified Format):

{
  "type": "File",
  "score": 87.0,
  "category": "Architecture",
  "priority": "high",
  "location": {
    "file": "src/services/user_manager.rs"
  },
  "metrics": {
    "lines": 1250,
    "functions": 45,
    "classes": 3,
    "avg_complexity": 12.3,
    "max_complexity": 28,
    "total_complexity": 554,
    "coverage": 0.62,
    "uncovered_lines": 125
  },
  "god_object_indicators": {
    "responsibility_count": 8,
    "data_class_count": 12,
    "method_groups": [
      "authentication",
      "authorization",
      "profile_management",
      "session_handling",
      "notification_preferences",
      "audit_logging",
      "password_management",
      "role_management"
    ],
    "coupling_score": 0.78,
    "cohesion_score": 0.34
  },
  "recommendation": {
    "action": "Split into focused modules by responsibility",
    "implementation_steps": [
      "Extract authentication into auth_service.rs",
      "Move authorization to permission_service.rs",
      "Create profile_service.rs for user data management",
      "Separate audit concerns into audit_logger.rs"
    ]
  },
  "impact": {
    "complexity_reduction": 45.0,
    "maintainability_improvement": 0.68,
    "test_effort": 8.5
  }
}

Source: Structure from src/output/unified/file_item.rs:FileDebtItemOutput and src/priority/file_metrics.rs:GodObjectIndicators

Test Gap (Needs Testing)

Terminal Output:

#3 SCORE: 8.9 [CRITICAL]
├─ TEST GAP: ./src/analyzers/rust_call_graph.rs:38 add_function_to_graph()
├─ ACTION: Add 6 unit tests for full coverage
├─ IMPACT: Full test coverage, -3.7 risk reduction
├─ COMPLEXITY: cyclomatic=6, branches=6, cognitive=8, nesting=2, lines=32
├─ DEPENDENCIES: 0 upstream, 11 downstream
├─ TEST EFFORT: Simple (2-3 hours)
└─ WHY: Business logic with 0% coverage, manageable complexity (cyclo=6, cog=8)
    High impact - 11 functions depend on this

JSON Output (Unified Format):

{
  "type": "Function",
  "score": 89.0,
  "category": "Testing",
  "priority": "critical",
  "location": {
    "file": "src/analyzers/rust_call_graph.rs",
    "line": 38,
    "function": "add_function_to_graph"
  },
  "metrics": {
    "cyclomatic_complexity": 6,
    "cognitive_complexity": 8,
    "length": 32,
    "nesting_depth": 2,
    "coverage": 0.0,
    "uncovered_lines": [38, 39, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66]
  },
  "debt_type": {
    "TestingGap": {
      "coverage": 0.0,
      "cyclomatic": 6,
      "cognitive": 8
    }
  },
  "function_role": "PureLogic",
  "purity_analysis": {
    "is_pure": false,
    "confidence": 0.65
  },
  "dependencies": {
    "upstream_count": 0,
    "downstream_count": 11,
    "downstream_callees": [
      "get_function_name",
      "extract_parameters",
      "parse_return_type",
      "add_to_registry",
      "update_call_sites",
      "resolve_types",
      "track_visibility",
      "record_location",
      "increment_counter",
      "validate_signature",
      "log_registration"
    ]
  },
  "recommendation": {
    "action": "Add unit tests for core business logic",
    "implementation_steps": [
      "Test happy path with valid function definition",
      "Test error cases: null input, invalid syntax",
      "Test edge cases: complex generics, lifetimes",
      "Test integration with registry updates",
      "Verify correct handling of visibility modifiers",
      "Test type resolution edge cases"
    ]
  },
  "impact": {
    "coverage_improvement": 1.0,
    "complexity_reduction": 0.0,
    "risk_reduction": 3.7
  }
}

Source: Structure from src/output/unified/func_item.rs:FunctionDebtItemOutput with debt_type from src/priority/debt_types.rs:DebtType

Entropy-Dampened Validation Function

This example shows how debtmap’s entropy analysis reduces false positives for repetitive code patterns.

Terminal Output:

Function: validate_config
  File: src/config/validator.rs:23
  Cyclomatic: 20 → Effective: 7 (65% dampened)
  Risk: LOW

  Entropy Analysis:
    ├─ Token Entropy: 0.28 (low variety - repetitive patterns)
    ├─ Pattern Repetition: 0.88 (high similarity between checks)
    ├─ Branch Similarity: 0.91 (consistent validation structure)
    └─ Reasoning: Complexity reduced by 65% due to pattern-based code

  This appears complex but is actually a repetitive validation pattern.
  Lower priority for refactoring.

JSON Output (Unified Format):

{
  "type": "Function",
  "score": 15.2,
  "category": "CodeQuality",
  "priority": "low",
  "location": {
    "file": "src/config/validator.rs",
    "line": 23,
    "function": "validate_config"
  },
  "metrics": {
    "cyclomatic_complexity": 20,
    "cognitive_complexity": 18,
    "length": 85,
    "nesting_depth": 3,
    "coverage": 0.95,
    "entropy_score": 0.28
  },
  "debt_type": {
    "ComplexityHotspot": {
      "cyclomatic": 20,
      "cognitive": 18,
      "adjusted_cyclomatic": 7
    }
  },
  "adjusted_complexity": {
    "dampened_cyclomatic": 7.0,
    "dampening_factor": 0.65
  },
  "function_role": "PatternMatch",
  "recommendation": {
    "action": "Low priority - repetitive validation pattern"
  },
  "impact": {
    "coverage_improvement": 0.05,
    "complexity_reduction": 0.0,
    "risk_reduction": 0.8
  },
  "scoring_details": {
    "coverage_score": 2.5,
    "complexity_score": 7.0,
    "dependency_score": 0.0,
    "base_score": 43.5,
    "entropy_dampening": 0.65,
    "role_multiplier": 0.35,
    "final_score": 15.2
  }
}

Source: adjusted_complexity from src/output/unified/func_item.rs:AdjustedComplexity, entropy dampening spec 182

Key Points:

• adjusted_cyclomatic: Entropy-dampened complexity value (7 vs original 20)
• dampening_factor: Amount of reduction applied (0.65 = 65% reduction)
• entropy_score: Low value (0.28) indicates repetitive patterns
• Score reduced from 43.5 to 15.2 due to entropy analysis

Pattern Detection Example

When debtmap detects a specific complexity pattern, it includes pattern metadata.

JSON Output:

{
  "type": "Function",
  "score": 65.0,
  "category": "CodeQuality",
  "priority": "high",
  "location": {
    "file": "src/state/workflow_executor.rs",
    "line": 78,
    "function": "execute_transition"
  },
  "pattern_type": "state_machine",
  "pattern_confidence": 0.87,
  "pattern_details": {
    "state_count": 12,
    "transition_count": 34,
    "branch_entropy": 0.82,
    "state_cohesion": 0.91
  },
  "complexity_pattern": "State machine with 12 states, high cohesion"
}

Source: pattern_type and pattern_confidence from src/output/unified/func_item.rs:FunctionDebtItemOutput

Available Pattern Types:

• state_machine - State transition logic
• coordinator - Function orchestrating multiple operations
• Pattern detection threshold: 0.7 confidence (from src/io/writers/pattern_display.rs:PATTERN_CONFIDENCE_THRESHOLD)

Test File Detection

Debtmap automatically labels test files using the file_context_label field (spec 166).

JSON Output:

{
  "type": "Function",
  "location": {
    "file": "tests/integration/payment_test.rs",
    "line": 45,
    "function": "test_payment_processing",
    "file_context_label": "TEST FILE"
  }
}

Labels:

• "TEST FILE" - File is definitively a test file
• "PROBABLE TEST" - File likely contains tests but not confirmed

Source: file_context_label from src/output/unified/location.rs:UnifiedLocation

Summary Statistics

The unified format includes summary statistics at the top level.

JSON Output:

{
  "format_version": "1.0.0",
  "metadata": {
    "debtmap_version": "0.5.0",
    "generated_at": "2025-12-04T22:15:00Z",
    "project_root": "/home/user/myproject",
    "analysis_type": "full"
  },
  "summary": {
    "total_items": 127,
    "total_debt_score": 2845.6,
    "debt_density": 0.18,
    "total_loc": 15823,
    "by_type": {
      "File": 8,
      "Function": 119
    },
    "by_category": {
      "CodeQuality": 67,
      "Architecture": 12,
      "Testing": 42,
      "Performance": 6
    },
    "score_distribution": {
      "critical": 15,
      "high": 34,
      "medium": 58,
      "low": 20
    }
  },
  "items": []
}

Source: UnifiedOutput structure from src/output/unified/types.rs:14-20 and DebtSummary from lines 32-44

Key Summary Fields:

• debt_density: Total debt score per 1000 lines of code
• by_type: Count of File vs Function debt items
• by_category: Count by debt category
• score_distribution: Count of items by priority level

Before/After Refactoring Comparison

Before:

Function: process_order
  Cyclomatic: 22
  Cognitive: 35
  Coverage: 15%
  Risk Score: 52.3 (CRITICAL)
  Debt Score: 50 (Critical Complexity)

After:

Function: process_order (refactored)
  Cyclomatic: 5
  Cognitive: 6
  Coverage: 92%
  Risk Score: 2.1 (LOW)
  Debt Score: 0 (no debt)

Extracted functions:
  - validate_order (Cyclomatic: 4, Coverage: 100%)
  - calculate_totals (Cyclomatic: 3, Coverage: 95%)
  - apply_discounts (Cyclomatic: 6, Coverage: 88%)
  - finalize_order (Cyclomatic: 4, Coverage: 90%)

Impact:
  ✓ Complexity reduced by 77%
  ✓ Coverage improved by 513%
  ✓ Risk reduced by 96%
  ✓ Created 4 focused, testable functions

Well-Tested Complex Function (Good Example)

Not all complexity is bad. This example shows a legitimately complex function with excellent test coverage.

Terminal Output:

Function: calculate_tax (WELL TESTED - Good Example!)
  File: src/tax/calculator.rs:78
  Complexity: Cyclomatic=18, Cognitive=22
  Coverage: 98%
  Risk: LOW

  Why this is good:
  - High complexity is necessary (tax rules are complex)
  - Thoroughly tested with 45 test cases
  - Clear documentation of edge cases
  - Good example to follow for other complex logic

Next Steps

• Output Formats - Complete JSON schema and format documentation
• Configuration - Customize thresholds and analysis behavior
• Advanced Features - Purity analysis, entropy dampening, pattern detection

For questions or issues, visit GitHub Issues.

Compare Analysis

The compare command enables you to track technical debt changes over time by comparing two analysis results. This is essential for validating refactoring efforts, detecting regressions in pull requests, and monitoring project health trends.

Implementation Status

All Features Available Now:

• ✅ Target location tracking with intelligent fuzzy matching
• ✅ Detailed improvement percentage calculations (per-item)
• ✅ Multiple output formats (JSON, Markdown, Terminal, HTML)
• ✅ Implementation plan parsing for target extraction
• ✅ Four match strategies (Exact, FunctionLevel, ApproximateName, FileLevel)
• ✅ Resolved items tracking (debt eliminated)
• ✅ Improved items detection (score reduction ≥ 30%)
• ✅ New critical items detection (regressions)
• ✅ Project health metrics and trends
• ✅ CI/CD integration support

Overview

The compare command analyzes differences between “before” and “after” debtmap analyses, providing:

• Target location tracking - Monitor specific code locations through refactoring with fuzzy matching
• Validation tracking - Verify debt items are resolved or improved
• Project health metrics - Track overall debt trends across your codebase
• Regression detection - Identify new critical debt items introduced (score ≥ 60.0)
• Improvement tracking - Measure and celebrate debt reduction with detailed per-item metrics
• CI/CD integration - Automate quality gates in your pipeline

Basic Usage

Command Syntax

debtmap compare \
  --before path/to/before.json \
  --after path/to/after.json \
  --output validation.json

Command-Line Options

All comparison features are available now, including target location tracking, fuzzy matching, and multiple output formats.

Target Location Tracking

Target location tracking allows you to monitor specific code locations through refactoring changes. The compare command uses intelligent fuzzy matching to find your target even when code is moved or renamed.

Location Format

Target locations use the format: file:function:line

Examples:

• src/main.rs:complex_function:42
• lib/parser.rs:parse_expression:156
• api/handler.rs:process_request:89

Location Format Variations (src/comparison/location_matcher.rs:12-19):

The file:*:line format is useful when you want to target a specific line number regardless of the function name, which is helpful when function names change during refactoring.

Specifying Target Locations

Option 1: Via Implementation Plan

Create an IMPLEMENTATION_PLAN.md file with a target location section:

# Implementation Plan

## Target Item
**Location**: ./src/example.rs:complex_function:45
**Current Debt Score**: 85.5
**Severity**: critical

## Problem Analysis
The `complex_function` has high cognitive complexity...

## Proposed Solution
1. Extract nested conditionals into separate functions
2. Use early returns to reduce nesting depth
3. Add comprehensive unit tests

Then run compare with the plan:

debtmap compare --before before.json --after after.json --plan IMPLEMENTATION_PLAN.md

Option 2: Manual Target Location

Specify the target directly via command-line:

debtmap compare \
  --before before.json \
  --after after.json \
  --target-location "src/example.rs:complex_function:45"

Matching Strategies

Debtmap uses intelligent matching to find your target item even when code changes. The matcher tries multiple strategies in order, using the most precise match available:

The comparison result includes the match strategy and confidence score used, along with the count of matched items (useful when fuzzy matching finds multiple candidates).

Target Status Values

After comparing, the target item will have one of these statuses:

• Resolved - Item no longer exists in after analysis (debt eliminated!)
• Improved - Item exists but with lower debt score
• Unchanged - Item exists with similar metrics (within 5%)
• Regressed - Item exists but got worse
• NotFoundBefore - Item didn’t exist in before analysis
• NotFound - Item not found in either analysis

Project Health Metrics

The compare command tracks project-wide health metrics to show overall trends.

Tracked Metrics

{
  "project_health": {
    "before": {
      "total_debt_score": 450.5,
      "total_items": 25,
      "critical_items": 5,
      "high_priority_items": 12,
      "average_score": 18.02
    },
    "after": {
      "total_debt_score": 380.2,
      "total_items": 22,
      "critical_items": 3,
      "high_priority_items": 10,
      "average_score": 17.28
    },
    "changes": {
      "debt_score_change": -70.3,
      "debt_score_change_pct": -15.6,
      "items_change": -3,
      "critical_items_change": -2
    }
  }
}

Understanding Metrics

• total_debt_score - Sum of all debt item scores
• total_items - Total number of debt items detected
• critical_items - Items with score ≥ 60.0 (critical threshold)
• high_priority_items - Items with score ≥ 40.0 (high priority threshold)
• average_score - Mean debt score across all items
• debt_score_change - Absolute change in total debt
• debt_score_change_pct - Percentage change in total debt

Debt Trends

The comparison calculates an overall debt trend based on the percentage change:

• Improving - Debt decreased by more than 5%
• Stable - Debt changed by less than 5% (within normal variance)
• Regressing - Debt increased by more than 5%

Regression Detection

Regressions are new critical debt items (score ≥ 60.0) that appear in the after analysis.

What Counts as a Regression

A regression is detected when:

1. An item exists in the after analysis
2. The item does NOT exist in the before analysis
3. The item has a debt score ≥ 60.0 (critical severity threshold)

Regression Output

The compare command returns a ComparisonResult with detailed regression information:

{
  "regressions": [
    {
      "location": "src/new_feature.rs:process_data:23",
      "score": 65.5,
      "debt_type": "high_complexity",
      "description": "Function has cyclomatic complexity of 12 and cognitive complexity of 15"
    }
  ]
}

Each regression item includes:

• location - Full path with function and line number
• score - Debt score (≥ 60.0 for regressions)
• debt_type - Type of debt detected (e.g., “high_complexity”, “god_object”)
• description - Human-readable explanation of the issue

Using Regressions in CI/CD

Fail your CI build if regressions are detected:

# Run comparison
debtmap compare --before before.json --after after.json --output result.json

# Check for regressions
REGRESSION_COUNT=$(jq '.regressions | length' result.json)

if [ "$REGRESSION_COUNT" -gt 0 ]; then
  echo "❌ Regression detected - $REGRESSION_COUNT new critical debt items found"
  jq '.regressions[]' result.json
  exit 1
fi

# Check overall debt trend
TREND=$(jq -r '.summary.overall_debt_trend' result.json)
if [ "$TREND" = "Regressing" ]; then
  echo "⚠️ Warning: Overall debt is increasing"
fi

Improvement Tracking

The compare command tracks improvements as a list of ImprovementItem objects with detailed before/after metrics.

Improvement Types

The ImprovementType enum (src/comparison/types.rs:121-126) defines four improvement categories:

• Resolved - Debt item completely eliminated (no longer in after analysis) ✓ Auto-detected
• ScoreReduced - Overall debt score reduced significantly (≥ 30% reduction) ✓ Auto-detected
• ComplexityReduced - Cyclomatic or cognitive complexity decreased (defined but not auto-classified)
• CoverageImproved - Test coverage increased (defined but not auto-classified)

Note: Currently, the comparator automatically detects and classifies Resolved and ScoreReduced improvements (src/comparison/comparator.rs:134-191). The ComplexityReduced and CoverageImproved types are defined in the type system but not yet auto-assigned during comparison. Future versions may extend auto-detection to classify complexity and coverage improvements.

Improvement Items Structure

{
  "improvements": [
    {
      "location": "src/example.rs:complex_function:45",
      "before_score": 68.5,
      "after_score": 35.2,
      "improvement_type": "ScoreReduced"
    },
    {
      "location": "src/legacy.rs:old_code:120",
      "before_score": 72.0,
      "after_score": null,
      "improvement_type": "Resolved"
    },
    {
      "location": "src/utils.rs:helper_function:88",
      "before_score": 45.0,
      "after_score": 28.0,
      "improvement_type": "ComplexityReduced"
    }
  ]
}

Each improvement item includes:

• location - Full path with function and line number
• before_score - Original debt score
• after_score - New debt score (null if resolved)
• improvement_type - Type of improvement achieved

Before/After Metrics

When you specify a target location (via --plan or --target-location), the compare command provides detailed before/after metrics for that specific code location.

Target Item Comparison

{
  "target_item": {
    "location": "src/example.rs:complex_function:45",
    "match_strategy": "Exact",
    "match_confidence": 1.0,
    "matched_items_count": 1,
    "before": {
      "score": 68.5,
      "cyclomatic_complexity": 8,
      "cognitive_complexity": 15,
      "coverage": 45.0,
      "function_length": 120,
      "nesting_depth": 4
    },
    "after": {
      "score": 35.1,
      "cyclomatic_complexity": 3,
      "cognitive_complexity": 5,
      "coverage": 85.0,
      "function_length": 45,
      "nesting_depth": 2
    },
    "improvements": {
      "score_reduction_pct": 48.8,
      "complexity_reduction_pct": 66.7,
      "coverage_improvement_pct": 88.9
    },
    "status": "Improved"
  }
}

Target Metrics Fields

Each TargetMetrics object (before/after) includes:

• score - Unified debt score
• cyclomatic_complexity - Cyclomatic complexity metric
• cognitive_complexity - Cognitive complexity metric
• coverage - Test coverage percentage
• function_length - Lines of code in function
• nesting_depth - Maximum nesting depth

Improvement Percentages

The improvements object provides percentage improvements:

• score_reduction_pct - Percentage reduction in overall debt score
• complexity_reduction_pct - Reduction in cyclomatic/cognitive complexity
• coverage_improvement_pct - Increase in test coverage

Metric Aggregation

When multiple items match the target location (due to fuzzy matching), metrics are aggregated:

• score - Average across matched items
• cyclomatic_complexity - Average
• cognitive_complexity - Average
• coverage - Average
• function_length - Average
• nesting_depth - Maximum (worst case)

The matched_items_count field tells you how many items were aggregated.

Validating Refactoring Success

Use the comparison output to verify your refactoring:

# Check target status
STATUS=$(jq -r '.target_item.status' result.json)
SCORE_REDUCTION=$(jq '.target_item.improvements.score_reduction_pct' result.json)

echo "Target Status: $STATUS"
echo "Score Reduction: ${SCORE_REDUCTION}%"

# Check for improvements
IMPROVEMENT_COUNT=$(jq '.improvements | length' result.json)
echo "Improvements: $IMPROVEMENT_COUNT items"

# Verify no regressions
REGRESSION_COUNT=$(jq '.regressions | length' result.json)
if [ "$REGRESSION_COUNT" -eq 0 ]; then
  echo "✅ No regressions detected!"
else
  echo "⚠️ $REGRESSION_COUNT new critical items"
fi

Output Formats

JSON Format

The default JSON format provides complete comparison results:

debtmap compare --before before.json --after after.json --output result.json

The ComparisonResult JSON output (src/comparison/types.rs:3-22) includes:

• metadata - Comparison metadata (timestamp, file paths, target location)
• target_item - Target item comparison with before/after metrics (if specified)
• project_health - Project-wide health metrics comparison
• regressions - List of new critical items (score ≥ 60.0)
• improvements - List of improved/resolved items (≥30% score reduction or resolved)
• summary - Summary statistics and overall debt trend

Example output:

{
  "metadata": {
    "comparison_date": "2024-01-15T10:30:00Z",
    "before_file": "before.json",
    "after_file": "after.json",
    "target_location": "src/example.rs:complex_function:45"
  },
  "target_item": {
    "status": "Improved",
    "improvements": {
      "score_reduction_pct": 48.8
    }
  },
  "summary": {
    "target_improved": true,
    "new_critical_count": 0,
    "resolved_count": 3,
    "overall_debt_trend": "Improving"
  }
}

Markdown Format

Generate human-readable markdown reports for pull request comments:

debtmap compare --before before.json --after after.json --format markdown

Implementation: src/io/writers/markdown/mod.rs, src/main.rs:1027-1072

The markdown output is suitable for:

• Pull request comments
• Documentation
• Email reports
• Team dashboards

Terminal Format

Display colorized output directly in the terminal:

debtmap compare --before before.json --after after.json --format terminal

Implementation: src/io/writers/terminal.rs, src/main.rs:1011

The terminal format provides:

• Color-coded status indicators
• Formatted tables for metrics
• Human-readable summaries
• Easy scanning of results

HTML Format

Generate HTML reports with structured styling:

debtmap compare --before before.json --after after.json --format html

Implementation: src/io/writers/html.rs

The HTML format is suitable for:

• Web-based dashboards
• Archived reports
• Integration with documentation sites

CI/CD Integration

GitHub Actions Example

name: Technical Debt Check

on: [pull_request]

jobs:
  debt-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Need history for before/after

      - name: Install debtmap
        run: cargo install debtmap

      - name: Analyze main branch
        run: |
          git checkout main
          debtmap analyze --output before.json

      - name: Analyze PR branch
        run: |
          git checkout ${{ github.head_ref }}
          debtmap analyze --output after.json

      - name: Compare analyses
        run: |
          debtmap compare \
            --before before.json \
            --after after.json \
            --output comparison.json

      - name: Check comparison result
        run: |
          TREND=$(jq -r '.summary.overall_debt_trend' comparison.json)
          REGRESSION_COUNT=$(jq '.regressions | length' comparison.json)
          IMPROVEMENT_COUNT=$(jq '.improvements | length' comparison.json)

          echo "Debt Trend: $TREND"
          echo "Regressions: $REGRESSION_COUNT"
          echo "Improvements: $IMPROVEMENT_COUNT"

          # Fail on regression
          if [ "$REGRESSION_COUNT" -gt 0 ]; then
            echo "❌ Regression detected"
            jq '.regressions[]' comparison.json
            exit 1
          fi

          # Warn if debt is increasing
          if [ "$TREND" = "Regressing" ]; then
            echo "⚠️ Warning: Overall debt is increasing"
          fi

      - name: Post comparison to PR
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const comparison = JSON.parse(fs.readFileSync('comparison.json', 'utf8'));

            const body = `## Technical Debt Comparison

            **Overall Trend:** ${comparison.summary.overall_debt_trend}
            **Regressions:** ${comparison.summary.new_critical_count}
            **Improvements:** ${comparison.summary.resolved_count}

            ${comparison.improvements.length > 0 ? `
            ### Improvements
            ${comparison.improvements.map(i => `- ${i.location}: ${i.before_score.toFixed(1)} → ${i.after_score ? i.after_score.toFixed(1) : 'resolved'}`).join('\n')}
            ` : ''}

            ${comparison.regressions.length > 0 ? `
            ### ⚠️ Regressions
            ${comparison.regressions.map(r => `- ${r.location}: ${r.score.toFixed(1)} (${r.debt_type})`).join('\n')}
            ` : ''}`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });

GitLab CI Example

debt_check:
  stage: test
  script:
    # Analyze main branch
    - git fetch origin main
    - git checkout origin/main
    - debtmap analyze --output before.json

    # Analyze current branch
    - git checkout $CI_COMMIT_SHA
    - debtmap analyze --output after.json

    # Compare and check status
    - debtmap compare --before before.json --after after.json --output comparison.json
    - |
      TREND=$(jq -r '.summary.overall_debt_trend' comparison.json)
      REGRESSION_COUNT=$(jq '.regressions | length' comparison.json)

      echo "Debt Trend: $TREND"
      echo "Regressions: $REGRESSION_COUNT"

      if [ "$REGRESSION_COUNT" -gt 0 ]; then
        echo "Failed: Regression detected"
        jq '.regressions[]' comparison.json
        exit 1
      fi
  artifacts:
    paths:
      - before.json
      - after.json
      - comparison.json
    expire_in: 1 week

Best Practices for CI/CD

1. Store analyses as artifacts - Keep before/after JSON for debugging
2. Check status field - Use status to determine pass/fail
3. Track completion percentage - Monitor progress toward debt resolution
4. Review improvements - Celebrate and document successful refactorings
5. Act on remaining issues - Create follow-up tasks for unresolved items
6. Set completion thresholds - Require minimum completion percentage for merges

Practical Examples

Example 1: Basic Comparison

Compare two analyses to track debt changes:

# Run before analysis
debtmap analyze --output before.json

# Make changes to codebase...

# Run after analysis
debtmap analyze --output after.json

# Compare
debtmap compare --before before.json --after after.json --output comparison.json

# Check results
cat comparison.json | jq '.'
# Output shows: target_item, project_health, regressions, improvements, summary

Example 2: Validating Function Refactoring

Validate your refactoring work with target location tracking:

# Run before analysis
debtmap analyze --output before.json

# Identify critical items to fix
jq '.items[] | select(.unified_score.final_score >= 60.0)' before.json

# Refactor the high-priority functions...

# Run after analysis
debtmap analyze --output after.json

# Compare and validate with target location
debtmap compare \
  --before before.json \
  --after after.json \
  --target-location "src/example.rs:complex_function:45" \
  --output comparison.json

# Check target status
STATUS=$(jq -r '.target_item.status' comparison.json)
SCORE_REDUCTION=$(jq '.target_item.improvements.score_reduction_pct' comparison.json)

echo "Target Status: $STATUS"
echo "Score Reduction: ${SCORE_REDUCTION}%"

# Review all improvements
jq '.improvements[]' comparison.json

Example 3: Detecting PR Regressions

Check if a pull request introduces new critical debt:

# Analyze base branch
git checkout main
debtmap analyze --output main.json

# Analyze PR branch
git checkout feature/new-feature
debtmap analyze --output feature.json

# Compare
debtmap compare \
  --before main.json \
  --after feature.json \
  --output comparison.json

# Check for regressions
REGRESSION_COUNT=$(jq '.regressions | length' comparison.json)
TREND=$(jq -r '.summary.overall_debt_trend' comparison.json)

echo "Regressions: $REGRESSION_COUNT"
echo "Debt Trend: $TREND"

# Example output structure:
jq '.' comparison.json
# {
#   "summary": {
#     "overall_debt_trend": "Improving",  // or "Regressing"
#     "new_critical_count": 0,
#     "resolved_count": 3
#   },
#   "regressions": [],
#   "improvements": [...],
#   "project_health": {...}
# }

Example 4: Monitoring Project Health Over Releases

Track overall project health across releases:

# Analyze release v1.0
git checkout v1.0
debtmap analyze --output v1.0.json

# Analyze release v1.1
git checkout v1.1
debtmap analyze --output v1.1.json

# Compare
debtmap compare \
  --before v1.0.json \
  --after v1.1.json \
  --output v1.0-to-v1.1.json

# Check project health metrics
echo "Before (v1.0):"
jq '.project_health.before' v1.0-to-v1.1.json

echo "After (v1.1):"
jq '.project_health.after' v1.0-to-v1.1.json

# Check overall trend
TREND=$(jq -r '.summary.overall_debt_trend' v1.0-to-v1.1.json)
DEBT_CHANGE=$(jq '.project_health.changes.debt_score_change_pct' v1.0-to-v1.1.json)
echo "Debt Trend: $TREND"
echo "Debt Score Change: ${DEBT_CHANGE}%"

Example 5: Full CI/CD Workflow

Complete workflow for continuous debt monitoring:

#!/bin/bash
# ci-debt-check.sh

set -e

BEFORE="before.json"
AFTER="after.json"
COMPARISON="comparison.json"

# Step 1: Analyze baseline (main branch)
echo "📊 Analyzing baseline..."
git checkout main
debtmap analyze --output "$BEFORE"

# Step 2: Analyze current branch
echo "📊 Analyzing current branch..."
git checkout -
debtmap analyze --output "$AFTER"

# Step 3: Run comparison
echo "🔍 Running comparison..."
debtmap compare \
  --before "$BEFORE" \
  --after "$AFTER" \
  --output "$COMPARISON"

# Step 4: Extract metrics
TREND=$(jq -r '.summary.overall_debt_trend' "$COMPARISON")
REGRESSION_COUNT=$(jq '.regressions | length' "$COMPARISON")
IMPROVEMENT_COUNT=$(jq '.improvements | length' "$COMPARISON")
RESOLVED_COUNT=$(jq '.summary.resolved_count' "$COMPARISON")

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📈 Debt Comparison Results"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Trend: $TREND"
echo "Regressions: $REGRESSION_COUNT"
echo "Improvements: $IMPROVEMENT_COUNT"
echo "Resolved: $RESOLVED_COUNT"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

# Step 5: Quality gate
if [ "$REGRESSION_COUNT" -gt 0 ]; then
  echo "❌ FAILED: Regression detected"
  jq '.regressions[]' "$COMPARISON"
  exit 1
fi

if [ "$TREND" = "Regressing" ]; then
  echo "⚠️  WARNING: Overall debt is increasing"
  # Don't fail, just warn
fi

if [ "$RESOLVED_COUNT" -gt 0 ]; then
  echo "🎉 SUCCESS: $RESOLVED_COUNT debt items resolved!"
fi

echo "✅ PASSED: No regressions detected"

Example 6: Interpreting Comparison Results

Understanding the comparison output:

# Run comparison
debtmap compare --before before.json --after after.json --output comparison.json

# Check debt trend
TREND=$(jq -r '.summary.overall_debt_trend' comparison.json)
REGRESSION_COUNT=$(jq '.regressions | length' comparison.json)
IMPROVEMENT_COUNT=$(jq '.improvements | length' comparison.json)

case "$TREND" in
  "Improving")
    echo "🎉 Success! Debt is decreasing"
    echo "Improvements: $IMPROVEMENT_COUNT"
    jq '.improvements[] | "\(.location): \(.improvement_type)"' comparison.json
    ;;
  "Stable")
    echo "➡️  Stable - no significant debt change"
    echo "Improvements: $IMPROVEMENT_COUNT"
    echo "Regressions: $REGRESSION_COUNT"
    ;;
  "Regressing")
    echo "❌ Warning! Debt is increasing"
    echo "New critical items: $REGRESSION_COUNT"
    jq '.regressions[] | "\(.location): \(.score) (\(.debt_type))"' comparison.json
    ;;
esac

# Check if target improved (if target was specified)
if jq -e '.target_item' comparison.json > /dev/null; then
  TARGET_STATUS=$(jq -r '.target_item.status' comparison.json)
  echo "Target Status: $TARGET_STATUS"
fi

Troubleshooting

Understanding Debt Trends

Issue: Confused about what the debt trend means

Solution: Check the summary.overall_debt_trend field in comparison output:

• Improving - Total debt decreased by more than 5%
• Stable - Total debt changed by less than 5% (within normal variance)
• Regressing - Total debt increased by more than 5%

Check the trend:

TREND=$(jq -r '.summary.overall_debt_trend' comparison.json)
DEBT_CHANGE=$(jq '.project_health.changes.debt_score_change_pct' comparison.json)
echo "Debt Trend: $TREND (${DEBT_CHANGE}% change)"

No Improvements Detected

Issue: Made changes but comparison shows no improvements

Possible causes:

1. Changes didn’t reduce debt scores by ≥30% (improvement threshold)
2. Refactored items had scores <60.0 (not tracked as critical)
3. Changes were neutral (e.g., code moved but complexity unchanged)

Solution: Check the details:

# Compare before/after project health
jq '.project_health.before' result.json
jq '.project_health.after' result.json

# Look for critical items in before analysis
jq '.items[] | select(.unified_score.final_score >= 60.0)' before.json

JSON Parsing Errors

Problem: Error parsing JSON file

Solutions:

1. Verify the file is valid JSON: jq . before.json
2. Ensure the file is a debtmap analysis output
3. Check file permissions and path
4. Regenerate the analysis if corrupted

Understanding Target Status Values

Handling Missing Files

Problem: No such file or directory

Solutions:

# Verify files exist
ls -la before.json after.json

# Check current directory
pwd

# Use absolute paths if needed
debtmap compare \
  --before /absolute/path/to/before.json \
  --after /absolute/path/to/after.json

Interpreting Edge Cases

All Items Resolved:

{
  "summary": {
    "resolved_count": 25,
    "new_critical_count": 0,
    "overall_debt_trend": "Improving"
  },
  "project_health": {
    "after": {
      "total_items": 0,
      "critical_items": 0
    }
  }
}

All debt items resolved - excellent work!

New Project (Empty Before):

{
  "summary": {
    "new_critical_count": 15,
    "resolved_count": 0,
    "overall_debt_trend": "Stable"
  },
  "project_health": {
    "before": {
      "total_items": 0
    }
  }
}

New project or first analysis - establish baseline for future comparisons.

No Changes:

{
  "summary": {
    "overall_debt_trend": "Stable",
    "new_critical_count": 0,
    "resolved_count": 0
  },
  "improvements": [],
  "regressions": []
}

No changes detected - either no code changes or changes were neutral to debt.

Related Documentation

• Validation Gates - Quality gate thresholds and validation strategies
• Prodigy Integration - Automated refactoring workflows with compare validation
• Output Formats - Understanding analysis JSON structure and formatters
• Scoring Strategies - How debt scores are calculated (critical ≥ 60.0, high priority ≥ 40.0)
• Threshold Configuration - Configuring severity thresholds for your project

Summary

The compare command provides validation for refactoring efforts:

Current Capabilities:

• ✅ Target location tracking with intelligent fuzzy matching (4 strategies: Exact, FunctionLevel, ApproximateName, FileLevel)
• ✅ Detect regressions (new critical items with score ≥ 60.0)
• ✅ Track resolved items and improvements (≥30% score reduction, auto-detected)
• ✅ Detailed per-item improvement metrics with before/after scores
• ✅ Multiple output formats (JSON, Markdown, Terminal, HTML)
• ✅ Implementation plan parsing for target extraction (via --plan flag)
• ✅ Project-wide health metrics and debt trends
• ✅ Automate quality gates in CI/CD pipelines

Note: The compare command is fully implemented with all features available. For improvement classification, Resolved and ScoreReduced types are automatically detected; ComplexityReduced and CoverageImproved are defined for future use.

Use the compare command regularly to maintain visibility into your codebase’s technical health and ensure continuous improvement. All features are fully implemented and ready for production use.

Configuration

Debtmap is highly configurable through a TOML configuration file. This section covers all configuration options and best practices for tuning debtmap for your codebase.

Quick Start

Create a .debtmap.toml file in your project root:

[scoring]
coverage = 0.50
complexity = 0.35
dependency = 0.15

[thresholds]
complexity = 15
lines = 80
coverage = 0.8

[languages]
rust = true
python = true
javascript = true

Configuration Topics

• Scoring Configuration - Tune debt scoring weights and role multipliers
• Thresholds Configuration - Set complexity and coverage thresholds
• Language Configuration - Enable/disable language support and tune language-specific settings
• Display and Output - Configure output formats and display options
• Advanced Options - Advanced configuration for power users
• Best Practices - Guidelines for effective configuration

Configuration File Location

Debtmap searches for configuration in the following order:

1. Path specified with --config flag
2. .debtmap.toml in current directory
3. .debtmap.toml in git repository root
4. Built-in defaults

Validation

Debtmap validates your configuration on startup. Invalid configurations will produce clear error messages:

$ debtmap analyze .
Error: Invalid configuration
  - scoring.coverage + scoring.complexity + scoring.dependency must equal 1.0
  - Current sum: 1.10

Default Values

All configuration options have sensible defaults. You only need to specify values you want to override from the defaults documented in each section.

Scoring Configuration

Debtmap uses a weighted scoring model to calculate technical debt priority. This chapter explains how to configure scoring weights, role multipliers, and related settings that affect how functions and files are prioritized.

Quick Reference

Here’s a quick overview of all scoring defaults (from src/config/scoring.rs):

Scoring Weights

The [scoring] section controls how different factors contribute to the overall debt score. Debtmap uses a weighted sum model where weights must sum to 1.0.

[scoring]
coverage = 0.50      # Weight for test coverage gaps (default: 0.50)
complexity = 0.35    # Weight for code complexity (default: 0.35)
dependency = 0.15    # Weight for dependency criticality (default: 0.15)

Active weights (used in scoring):

• coverage - Prioritizes untested code (default: 0.50)
• complexity - Identifies complex areas (default: 0.35)
• dependency - Considers impact radius (default: 0.15)

Unused weights (reserved for future features):

• semantic - Not currently used (default: 0.00)
• security - Not currently used (default: 0.00)
• organization - Not currently used (default: 0.00)

Validation rules:

• All weights must be between 0.0 and 1.0
• Active weights (coverage + complexity + dependency) must sum to 1.0 (±0.001 tolerance)
• If weights don’t sum to 1.0, they will be automatically normalized

Example - Prioritize complexity over coverage:

[scoring]
coverage = 0.30
complexity = 0.55
dependency = 0.15

Source: src/config/scoring.rs:14-40 (ScoringWeights)

Complexity Weights

The [complexity_weights] section controls how cyclomatic and cognitive complexity are combined in the final scoring:

[complexity_weights]
cyclomatic = 0.3      # Weight for cyclomatic complexity (default: 0.3)
cognitive = 0.7       # Weight for cognitive complexity (default: 0.7)
max_cyclomatic = 50.0 # Maximum cyclomatic for normalization (default: 50.0)
max_cognitive = 100.0 # Maximum cognitive for normalization (default: 100.0)

Why cognitive complexity is weighted higher:

• Cognitive complexity correlates better with bug density
• Cyclomatic complexity is a proxy for test cases needed
• The 70/30 split balances maintainability with testability

Source: src/config/scoring.rs:335-381 (ComplexityWeightsConfig)

Role Multipliers

Role multipliers adjust complexity scores based on a function’s semantic role:

[role_multipliers]
pure_logic = 1.2        # Prioritize pure computation (default: 1.2)
orchestrator = 0.8      # Reduce for delegation functions (default: 0.8)
io_wrapper = 0.7        # Reduce for I/O wrappers (default: 0.7)
entry_point = 0.9       # Slight reduction for main/CLI (default: 0.9)
pattern_match = 0.6     # Reduce for pattern matching (default: 0.6)
debug = 0.3             # Debug/diagnostic functions (default: 0.3)
unknown = 1.0           # No adjustment (default: 1.0)

These multipliers help reduce false positives by recognizing that different function types have naturally different complexity levels. The debug role has the lowest multiplier (0.3) since debug and diagnostic functions typically have low testing priority.

Source: src/config/scoring.rs:206-333 (RoleMultipliers)

Role-Based Scoring Configuration

DebtMap uses a two-stage role adjustment mechanism to accurately score functions based on their architectural role and testing strategy. This section explains how to configure both stages.

Stage 1: Role Coverage Weights

The first stage adjusts how much coverage gaps penalize different function types. This recognizes that not all functions need the same level of unit test coverage.

Configuration (.debtmap.toml under [scoring.role_coverage_weights]):

[scoring.role_coverage_weights]
entry_point = 0.6       # Reduce coverage penalty (often integration tested)
orchestrator = 0.8      # Reduce coverage penalty (tested via higher-level tests)
pure_logic = 1.0        # Pure logic should have unit tests, no reduction (default: 1.0)
io_wrapper = 0.5        # I/O wrappers are integration tested (default: 0.5)
pattern_match = 1.0     # Standard penalty
debug = 0.3             # Debug functions have lowest coverage expectations (default: 0.3)
unknown = 1.0           # Standard penalty (default behavior)

Rationale:

Example Impact:

# Emphasize pure logic testing strongly
[scoring.role_coverage_weights]
pure_logic = 1.5        # 50% higher penalty for untested logic
entry_point = 0.5       # 50% lower penalty for untested entry points
io_wrapper = 0.4        # 60% lower penalty for untested I/O

# Conservative approach (smaller adjustments)
[scoring.role_coverage_weights]
pure_logic = 1.1        # Only 10% increase
entry_point = 0.9       # Only 10% decrease

How It Works:

When a function has 0% coverage:

• Entry Point (weight 0.6): Gets 60% penalty instead of 100% penalty
• Pure Logic (weight 1.0): Gets 100% penalty (standard emphasis on testing)
• I/O Wrapper (weight 0.5): Gets 50% penalty

This prevents entry points from dominating the priority list due to low unit test coverage while emphasizing the importance of testing pure business logic.

Source: src/config/scoring.rs:383-455 (RoleCoverageWeights)

Stage 2: Role Multiplier with Clamping

The second stage applies a final role-based multiplier to reflect architectural importance. This multiplier is clamped by default to prevent extreme score variations.

Configuration (.debtmap.toml under [scoring.role_multiplier]):

[scoring.role_multiplier]
clamp_min = 0.3           # Minimum multiplier (default: 0.3)
clamp_max = 1.8           # Maximum multiplier (default: 1.8)
enable_clamping = true    # Enable clamping (default: true)

Parameters:

Clamp Range Rationale:

Default [0.3, 1.8]: Balances differentiation with stability

• Lower bound (0.3): I/O wrappers still contribute 30% of their base score

  • Prevents them from becoming invisible in the priority list
  • Ensures simple wrappers aren’t completely ignored

• Upper bound (1.8): Critical functions get at most 180% of base score

  • Prevents one complex function from dominating the entire list
  • Maintains balanced prioritization across different issues

When to Adjust Clamp Range:

# Wider range for more differentiation
[scoring.role_multiplier]
clamp_min = 0.2           # Allow more reduction
clamp_max = 2.5           # Allow more emphasis

# Narrower range for more stability
[scoring.role_multiplier]
clamp_min = 0.5           # Less reduction
clamp_max = 1.5           # Less emphasis

# Disable clamping (not recommended for production)
[scoring.role_multiplier]
enable_clamping = false   # Allow unclamped multipliers
# Warning: May cause unstable prioritization

When to Disable Clamping:

• Prototyping: Testing extreme multiplier values for custom scoring strategies
• Special cases: Very specific project needs requiring wide multiplier ranges
• Not recommended for production use as it can lead to unstable prioritization

Example Impact:

Without clamping:

Function: critical_business_logic (Pure Logic)
  Base Score: 45.0
  Role Multiplier: 2.5 (unclamped)
  Final Score: 112.5 (dominates entire list)

With clamping (default):

Function: critical_business_logic (Pure Logic)
  Base Score: 45.0
  Role Multiplier: 1.8 (clamped from 2.5)
  Final Score: 81.0 (high priority, but balanced)

Source: src/config/scoring.rs:457-493 (RoleMultiplierConfig)

Complete Example Configuration

Here’s a complete example showing both stages configured together:

# Stage 1: Coverage weight adjustments
[scoring.role_coverage_weights]
pure_logic = 1.0        # Pure logic should have unit tests (default: 1.0)
entry_point = 0.6       # Reduce penalty for integration-tested entry points
orchestrator = 0.8      # Partially reduce penalty for orchestrators
io_wrapper = 0.5        # I/O wrappers are integration tested (default: 0.5)
pattern_match = 1.0     # Standard
debug = 0.3             # Debug functions have lowest coverage expectations (default: 0.3)
unknown = 1.0           # Standard

# Stage 2: Role multiplier with clamping
[scoring.role_multiplier]
clamp_min = 0.3         # I/O wrappers contribute at least 30%
clamp_max = 1.8         # Critical functions get at most 180%
enable_clamping = true  # Keep clamping enabled for stability

How the Two Stages Work Together

The two-stage approach ensures role-based coverage adjustments and architectural importance multipliers work independently:

Example Workflow:

1. Calculate base score from complexity (10) and dependencies (5)
   -> Base = 15.0

2. Stage 1: Apply coverage weight based on role (Entry Point, weight 0.6)
   -> Coverage penalty reduced from 1.0 to 0.4
   -> Preliminary score = 15.0 * 0.4 = 6.0

3. Stage 2: Apply clamped role multiplier (Entry Point, multiplier 1.2)
   -> Clamped to [0.3, 1.8] -> stays 1.2
   -> Final score = 6.0 * 1.2 = 7.2

Key Benefits:

• Coverage adjustments don’t interfere with role multiplier
• Both mechanisms contribute independently to final score
• Clamping prevents instability from extreme values
• Configuration flexibility for different project needs

Verification

To see how role-based adjustments affect your codebase:

# Show detailed scoring breakdown
debtmap analyze . --verbose

# Look for lines like:
#   Coverage Weight: 0.6 (Entry Point adjustment)
#   Adjusted Coverage Penalty: 0.4 (reduced from 1.0)
#   Role Multiplier: 1.2 (clamped from 1.5)

For more details on how role-based adjustments reduce false positives, see the Role-Based Adjustments section in the Scoring Strategies guide.

Score Normalization

The [normalization] section controls how raw scores are normalized to a 0-10 scale:

[normalization]
linear_threshold = 10.0         # Use linear scaling below this value
logarithmic_threshold = 100.0   # Use logarithmic scaling above this value
sqrt_multiplier = 3.33          # Multiplier for square root scaling
log_multiplier = 10.0           # Multiplier for logarithmic scaling
show_raw_scores = true          # Show both raw and normalized scores

Normalization ensures scores are comparable across different codebases and prevents extreme outliers from dominating the results.

Source: src/config/scoring.rs:557-610 (NormalizationConfig)

Context Multipliers

The [context_multipliers] section dampens scores for non-production code (spec 191):

[context_multipliers]
examples = 0.1              # 90% reduction for example files
tests = 0.2                 # 80% reduction for test files
benchmarks = 0.3            # 70% reduction for benchmarks
build_scripts = 0.3         # 70% reduction for build scripts
documentation = 0.1         # 90% reduction for documentation
enable_context_dampening = false  # Disabled by default (use --context flag)

When enabled with --context, these multipliers reduce false positive urgency scores for code that doesn’t represent production complexity.

Source: src/config/scoring.rs:612-676 (ContextMultipliers)

Data Flow Scoring

The [data_flow_scoring] section configures analysis of data flow patterns (spec 218):

[data_flow_scoring]
enabled = true              # Enable data flow scoring
purity_weight = 0.4         # Weight for function purity
refactorability_weight = 0.3 # Weight for refactorability
pattern_weight = 0.3        # Weight for pattern recognition

Data flow scoring rewards functions with:

• Pure data transformations (no side effects)
• High refactorability potential
• Recognized functional patterns (map, filter, fold)

Source: src/config/scoring.rs:678-724 (DataFlowScoringConfig)

Rebalanced Scoring Presets

The [rebalanced_scoring] section allows using predefined presets or custom weights (spec 136):

[rebalanced_scoring]
preset = "balanced"         # Preset: balanced, quality-focused, size-focused, test-coverage
# Or override with custom weights:
# complexity_weight = 0.35
# coverage_weight = 0.30
# structural_weight = 0.15
# size_weight = 0.10
# smell_weight = 0.10

Available Presets:

Source: src/config/scoring.rs:495-554 (RebalancedScoringConfig)

Related Documentation

• Scoring Strategies - In-depth explanation of scoring algorithms
• Role-Based Adjustments - How semantic roles affect scoring
• Thresholds Configuration - Configure when code is flagged as debt
• Tiered Prioritization - How scores map to priority tiers

Thresholds Configuration

This subsection covers threshold configuration in Debtmap, including basic thresholds, minimum thresholds for filtering, and validation thresholds for CI/CD pipelines.

Overview

Thresholds control what gets flagged as technical debt. Debtmap provides multiple threshold categories:

• Basic thresholds - Core complexity and size limits
• Minimum thresholds - Filter out trivial functions
• Validation thresholds - CI/CD quality gates
• Coverage expectations - Role-based test coverage requirements

Basic Thresholds

Basic thresholds define when code is flagged as technical debt. Configure them in the [thresholds] section of .debtmap.toml.

Source: src/config/thresholds.rs:83-118 (ThresholdsConfig)

[thresholds]
complexity = 10                # Cyclomatic complexity threshold (default: 10)
duplication = 50               # Duplication threshold in lines (default: 50)
max_file_length = 500          # Maximum lines per file (default: 500)
max_function_length = 50       # Maximum lines per function (default: 50)

Configuration Options

CLI Override

You can override basic thresholds from the command line:

# Override cyclomatic complexity threshold
debtmap analyze . --threshold-complexity 15

# Override duplication threshold
debtmap analyze . --threshold-duplication 30

# Combine multiple threshold flags
debtmap analyze . --threshold-complexity 15 --threshold-duplication 30

Minimum Thresholds

Minimum thresholds filter out trivial functions that aren’t significant technical debt. This helps focus analysis on meaningful issues.

Source: src/config/thresholds.rs:90-109 (ThresholdsConfig)

[thresholds]
# Filter items below these scores
minimum_debt_score = 2.0              # Only show debt score >= 2.0 (default: none)
minimum_risk_score = 2.0              # Only show risk score >= 2.0 (default: none)
min_score_threshold = 3.0             # Hide LOW severity items (default: 3.0)

# Complexity minimums (filter out simple functions)
minimum_cyclomatic_complexity = 3     # Ignore cyclomatic < 3 (default: none)
minimum_cognitive_complexity = 5      # Ignore cognitive < 5 (default: none)

Configuration Options

Use Cases

Focus on High-Priority Issues:

[thresholds]
minimum_debt_score = 5.0        # Only show significant debt
minimum_risk_score = 4.0        # Only show meaningful risk

Legacy Codebase (Reduce Noise):

[thresholds]
minimum_cyclomatic_complexity = 10   # Ignore moderate complexity
minimum_cognitive_complexity = 15    # Focus on worst offenders

Validation Thresholds

Validation thresholds are used by the debtmap validate command to enforce quality gates in CI/CD pipelines.

Source: src/config/thresholds.rs:120-196 (ValidationThresholds)

Primary Quality Metrics (Scale-Independent)

These metrics work for codebases of any size:

[thresholds.validation]
# Primary quality metrics
max_average_complexity = 10.0      # Maximum average complexity per function (default: 10.0)
max_debt_density = 50.0            # Debt items per 1000 LOC (default: 50.0)
max_codebase_risk_score = 7.0      # Overall risk score 0-10 (default: 7.0)

# Optional metrics
min_coverage_percentage = 0.0       # Minimum test coverage % (default: 0.0 - disabled)

# Safety net
max_total_debt_score = 10000        # Maximum total debt (default: 10000)

Configuration Options

Using Validation in CI/CD

# Run validation (exits with error if thresholds exceeded)
debtmap validate . --config .debtmap.toml

# Example CI/CD pipeline
debtmap analyze . --output report.json
debtmap validate . --config .debtmap.toml || exit 1

Deprecated Fields

The following fields are deprecated since v0.3.0 and will be removed in v1.0:

Migration Example:

# Old (deprecated)
[thresholds.validation]
max_debt_items = 100

# New (scale-independent)
[thresholds.validation]
max_debt_density = 50.0  # Works for any codebase size

Coverage Expectations

Coverage expectations define role-based test coverage requirements. Different function types have different testing strategies.

Source: src/priority/scoring/coverage_expectations.rs:103-173

# High expectations for pure functions
[coverage_expectations.pure]
min = 90.0                # Minimum acceptable coverage
target = 95.0             # Target/ideal coverage
max = 100.0               # Maximum meaningful coverage

# Moderate expectations for I/O operations
[coverage_expectations.io_operations]
min = 60.0
target = 70.0
max = 80.0

# Low expectations for debug/diagnostic code
[coverage_expectations.debug]
min = 20.0
target = 30.0
max = 40.0

Default Coverage Expectations by Role

Complete Coverage Configuration

# Strict quality standards
[coverage_expectations.pure]
min = 95.0
target = 98.0
max = 100.0

[coverage_expectations.business_logic]
min = 90.0
target = 95.0
max = 98.0

[coverage_expectations.validation]
min = 92.0
target = 96.0
max = 100.0

# More lenient for I/O
[coverage_expectations.io_operations]
min = 50.0
target = 65.0
max = 75.0

Complexity Thresholds

For fine-grained control over function complexity detection, use the [complexity_thresholds] section.

Source: src/complexity/threshold_manager.rs:16-58 (ComplexityThresholds)

[complexity_thresholds]
# Core complexity metrics
minimum_total_complexity = 8        # Sum of cyclomatic + cognitive (default: 8)
minimum_cyclomatic_complexity = 5   # Decision points (default: 5)
minimum_cognitive_complexity = 10   # Mental effort to understand (default: 10)

# Structural complexity metrics
minimum_match_arms = 4              # Maximum match/switch arms (default: 4)
minimum_if_else_chain = 3           # Maximum if-else chain length (default: 3)
minimum_function_length = 20        # Minimum lines before flagging (default: 20)

# Role-based multipliers (adjust thresholds by function role)
entry_point_multiplier = 1.5        # main(), handlers - more lenient (default: 1.5)
core_logic_multiplier = 1.0         # Business logic - standard (default: 1.0)
utility_multiplier = 0.8            # Getters, setters - stricter (default: 0.8)
test_function_multiplier = 2.0      # Test functions - most lenient (default: 2.0)

Threshold Presets

Use --threshold-preset to apply predefined configurations:

# Strict preset (new projects, libraries)
debtmap analyze . --threshold-preset strict

# Balanced preset (default - typical projects)
debtmap analyze . --threshold-preset balanced

# Lenient preset (legacy codebases)
debtmap analyze . --threshold-preset lenient

Preset Comparison:

Source: src/complexity/threshold_manager.rs:120-148 (from_preset)

Role-Based Multiplier Examples

Role multipliers adjust ALL thresholds for different function types:

Entry Point with Balanced preset (1.5x multiplier):

• Cyclomatic threshold: 7.5 (5 x 1.5)
• Cognitive threshold: 15 (10 x 1.5)
• Total threshold: 12 (8 x 1.5)

Utility function with Balanced preset (0.8x multiplier):

• Cyclomatic threshold: 4 (5 x 0.8)
• Cognitive threshold: 8 (10 x 0.8)
• Total threshold: 6.4 (8 x 0.8)

Validation Rules

Debtmap validates thresholds to prevent misconfiguration:

Source: src/complexity/threshold_manager.rs:191-217

• Core complexity metrics must be > 0
• Role multipliers must be positive (> 0)
• Invalid configurations fall back to defaults with a warning

File Size Thresholds

Context-aware file size limits vary by file type to avoid unrealistic recommendations.

Source: src/config/thresholds.rs:293-375 (FileSizeThresholds)

[thresholds.file_size]
business_logic = 400          # Strict limit for business logic (default: 400)
test_code = 650               # Moderate limit for tests (default: 650)
declarative_config = 1200     # Lenient for config files (default: 1200)
generated_code = 5000         # Very lenient for generated (default: 5000)
proc_macro = 500              # Moderate-strict for macros (default: 500)
build_script = 300            # Strict for build scripts (default: 300)
min_lines_per_function = 3.0  # Safety threshold (default: 3.0)

File-Specific Overrides

Use glob patterns for file-specific thresholds:

[thresholds.file_size.overrides]
"src/generated/*.rs" = 10000    # Allow large generated files
"src/migrations/*.rs" = 2000    # Allow larger migration files

Related Topics

• Configuration Overview - Full configuration reference
• Threshold Configuration Guide - Extended guide with examples
• Scoring Strategies - How thresholds affect scoring
• Validation and Quality Gates - CI/CD integration

Language Configuration

Configure language-specific analysis behavior in debtmap.

Overview

Debtmap analyzes source code for technical debt and complexity issues. Language configuration allows you to:

• Enable or disable specific languages
• Toggle analysis features per language
• Configure language-specific detection behavior

Supported Languages

Full Support (AST-Based Analysis):

• Rust - Full AST parsing with tree-sitter
• Python - Full AST parsing with tree-sitter

Source: src/core/types.rs:9-12 (Language enum) and src/organization/language.rs:4-7

The Language enum in the codebase currently supports:

#![allow(unused)]
fn main() {
// From src/core/types.rs:9-12
pub enum Language {
    Rust,
    Python,
}
}

Language Detection: Debtmap determines file language by extension:

• .rs files are analyzed as Rust
• .py and .pyw files are analyzed as Python

Source: src/organization/language.rs:10-17

#![allow(unused)]
fn main() {
pub fn from_path(path: &Path) -> Option<Language> {
    path.extension()
        .and_then(|ext| ext.to_str())
        .and_then(|ext| match ext {
            "rs" => Some(Language::Rust),
            "py" => Some(Language::Python),
            _ => None,
        })
}
}

Configuration Structure

The [languages] section in your debtmap.toml configures language analysis.

Source: src/config/languages.rs:4-22 (LanguagesConfig struct)

[languages]
enabled = ["rust", "python"]

[languages.rust]
detect_dead_code = false       # Disabled by default for Rust
detect_complexity = true
detect_duplication = true

[languages.python]
detect_dead_code = true
detect_complexity = true
detect_duplication = true

Language-Specific Features

Each language supports three configurable feature toggles:

Source: src/config/languages.rs:24-38 (LanguageFeatures struct)

Rust Configuration

[languages.rust]
detect_dead_code = false        # Disabled: rustc already reports unused code
detect_complexity = true
detect_duplication = true

Why dead code detection is disabled for Rust: The Rust compiler (rustc) already provides excellent unused code warnings via #[warn(dead_code)]. Enabling debtmap’s dead code detection would duplicate these warnings without adding value.

Source: src/config/accessors.rs:104-111

#![allow(unused)]
fn main() {
Language::Rust => {
    languages_config
        .and_then(|lc| lc.rust.clone())
        .unwrap_or(LanguageFeatures {
            detect_dead_code: false, // Rust dead code detection disabled by default
            detect_complexity: true,
            detect_duplication: true,
        })
}
}

Python Configuration

[languages.python]
detect_dead_code = true
detect_complexity = true
detect_duplication = true

All features enabled by default for Python. Dead code detection is valuable since Python lacks a compiler phase that catches unused code.

Source: src/config/accessors.rs:113-115

Enabling Languages

Specify which languages to analyze with the enabled array:

[languages]
enabled = ["rust", "python"]

Note: The configuration structure supports JavaScript and TypeScript entries (see src/config/languages.rs:15-21), but the core Language enum and detection logic only implement Rust and Python. JavaScript/TypeScript support may be planned for future releases.

Feature Defaults

Source: src/config/languages.rs:40-61

#![allow(unused)]
fn main() {
impl Default for LanguageFeatures {
    fn default() -> Self {
        Self {
            detect_dead_code: true,   // default_detect_dead_code()
            detect_complexity: true,  // default_detect_complexity()
            detect_duplication: true, // default_detect_duplication()
        }
    }
}
}

When no language-specific configuration is provided, debtmap uses these defaults (with the Rust dead code exception handled at the accessor level).

Using Language Configuration

Analyze Only Rust Code

[languages]
enabled = ["rust"]

[languages.rust]
detect_dead_code = false
detect_complexity = true
detect_duplication = true

Full Python Analysis

[languages]
enabled = ["python"]

[languages.python]
detect_dead_code = true
detect_complexity = true
detect_duplication = true

Multi-Language Projects

[languages]
enabled = ["rust", "python"]

# Different settings per language
[languages.rust]
detect_dead_code = false        # Trust rustc
detect_complexity = true
detect_duplication = true

[languages.python]
detect_dead_code = true         # Python needs this
detect_complexity = true
detect_duplication = false      # Skip if not needed

Complexity Calculations by Language

Debtmap uses language-specific complexity analyzers:

Source: src/complexity/languages/rust.rs and src/analyzers/implementations.rs

Rust Complexity

• Uses tree-sitter for AST parsing
• Calculates cyclomatic complexity from control flow
• Tracks cognitive complexity with nesting depth penalties
• Detects pattern match complexity with entropy analysis

Python Complexity

• Uses tree-sitter for AST parsing
• Handles Python-specific constructs (decorators, comprehensions)
• Tracks class method complexity
• Analyzes exception handling patterns

Integration with Other Configuration