Frequently Asked Questions

Common questions about debtmap’s features, usage, and AI integration.

AI Integration

How does debtmap work with AI coding assistants?

Debtmap is designed as a sensor that provides structured data for AI consumption. Instead of telling you what to fix, it tells AI assistants:

Where to look - Prioritized list of debt items with file locations
What to read - Context suggestions (callers, callees, tests)
What signals matter - Complexity, coverage, coupling metrics

Example workflow:

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

What output format is best for AI?

Use --format markdown for AI workflows. This format:

Minimizes tokens while maximizing information
Includes context suggestions inline
Uses consistent structure for reliable parsing
Avoids verbose descriptions that waste context window

debtmap analyze . --format markdown --top 5

Does debtmap provide fix suggestions?

No. Debtmap is a sensor, not a prescriber. It provides signals (metrics, coverage, coupling) and lets the AI decide how to fix issues.

This design is intentional:

AI can consider business context you provide
Different situations require different approaches
Template recommendations are often wrong

How do I use 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)

Tell your AI to read these files before making changes:

debtmap analyze . --format markdown --top 1 | \
  claude "Read the context files first, then fix the top item"

Can I integrate debtmap with Cursor?

Yes. Generate a report file and reference it in Cursor:

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

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

Features & Capabilities

What’s the difference between measured and estimated metrics?

Measured Metrics - Precise values from AST analysis:

cyclomatic_complexity: Exact count of decision points
cognitive_complexity: Weighted readability measure
nesting_depth: Maximum nesting levels
loc: Lines of code

Estimated Metrics - Heuristic approximations:

est_branches: Estimated execution paths (formula-based)

Use measured metrics for thresholds and gates. Use estimated metrics for prioritization.

What is entropy-based complexity analysis?

Entropy analysis uses information theory to distinguish between genuinely complex code and repetitive pattern-based code.

A function with 20 identical if/return validation checks has the same cyclomatic complexity as a function with 20 diverse conditional branches. Entropy analysis gives the validation function a much lower effective complexity score because it follows a simple, repetitive pattern.

Result: 60-75% reduction in false positives compared to traditional complexity metrics.

What languages are supported?

Currently supported:

Rust - Full support with AST parsing, macro expansion, and trait resolution

Planned:

Python, JavaScript/TypeScript, Go (after Rust analysis is mature)

Why is debtmap Rust-only right now?

We’re taking a focused approach to deliver the best possible Rust code analyzer before expanding. This allows us to:

Perfect core algorithms with one language
Build Rust-specific features (macros, traits, lifetimes)
Establish trust in the Rust community
Apply learnings to future languages

How does coverage integration work?

Debtmap reads LCOV format coverage data and maps it to functions:

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

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

Coverage affects prioritization:

Complex function with good coverage = lower priority
Simple function with no coverage = higher priority
High complexity + zero coverage = critical priority

Usage & Configuration

How do I exclude test files from analysis?

By default, debtmap excludes common test directories. To customize:

# .debtmap.toml
[analysis]
exclude_patterns = [
    "**/tests/**",
    "**/*_test.rs",
    "**/target/**",
]

Can I customize the complexity thresholds?

Yes. Configure in .debtmap.toml:

[thresholds]
cyclomatic_complexity = 10
nesting_depth = 3
loc = 200

[tiers]
critical = 8.0
high = 5.0
moderate = 2.0

Does debtmap integrate with CI/CD?

Yes. Use the validate command:

debtmap validate . --max-debt-density 10.0

Exit codes:

0 = validation passed
1 = validation failed (debt exceeds thresholds)
2 = analysis error

GitHub Actions example:

- name: Check technical debt
  run: |
    cargo llvm-cov --lcov --output-path coverage.lcov
    debtmap validate . --lcov coverage.lcov --max-debt-density 10.0

What if debtmap reports false positives?

Verify entropy analysis is enabled (default):
```
[analysis]
enable_entropy_analysis = true
```

Adjust thresholds for your project:

[thresholds]
cyclomatic_complexity = 15

Use ignore comments for specific functions:

#![allow(unused)]
fn main() {
// debtmap:ignore - acceptable validation pattern
fn validate_many_fields() { ... }
}

Report issues - If you believe analysis is incorrect, open an issue with a code example.

How accurate is the risk scoring?

Risk scores are relative prioritization metrics, not absolute measures. They help you answer “which code should I focus on first?” rather than “exactly how risky is this code?”

Use risk scores for prioritization, but apply your domain knowledge when deciding what to fix.

Comparison with Other Tools

How is debtmap different from SonarQube?

Aspect	Debtmap	SonarQube
Output	Signals for AI	Recommendations
Speed	Seconds	Minutes
Coverage	Built-in	Enterprise only
Entropy	Yes	No
Setup	Single binary	Server required

When to use SonarQube: Multi-language enterprise dashboards. When to use debtmap: AI-assisted Rust development.

Should I replace clippy with debtmap?

No—use both. They serve different purposes:

clippy:

Rust idioms and patterns
Common mistakes
Runs in milliseconds

debtmap:

Technical debt prioritization
Coverage-based risk
Context for AI

cargo clippy -- -D warnings
debtmap analyze . --lcov coverage.lcov --top 10

[analysis]
exclude_patterns = ["**/target/**", "**/vendor/**"]

Analyze specific directories:
```
debtmap analyze src/
```
Reduce parallelism:
```
debtmap analyze . --jobs 4
```

Coverage data isn’t being applied

Check:

LCOV file path is correct
LCOV file contains data: grep -c "^SF:" coverage.lcov
Source paths match between LCOV and project

Debtmap reports “No functions found”