Frequently Asked Questions

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

General Usage

Can I use debtmap without AI tools?

Yes. debtmap analyze . is useful on its own for developers who want a prioritized view of complexity, coverage gaps, and coupling risk.

Common direct-use workflows:

Browse the default terminal/TUI output during local development
Export JSON to the dashboard for deeper visual analysis
Run validation in CI to enforce debt thresholds

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 via syn, macro expansion, and trait resolution
Python - Language-aware parsing with tree-sitter plus function, class, decorator, and comprehension analysis
JavaScript - Tree-sitter parsing with modern ES syntax, JSX support, and async pattern analysis
TypeScript - Tree-sitter parsing with TS/TSX syntax, type-oriented patterns, and modern module support

Planned:

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
Primary UX	CLI, TUI, JSON, dashboard	Server/dashboard
Speed	Seconds	Minutes
Coverage	Built-in	Enterprise-heavy workflows
Setup	Single binary	Server required
Supported-language fit	Strong within supported languages	Broader language coverage
AI handoff	First-class markdown/JSON	Less workflow-oriented

When to use SonarQube: You need a broader enterprise platform across many languages and centralized server workflows. When to use debtmap: You want a faster, lighter-weight replacement for supported languages, especially when developers work directly in terminal/TUI flows or want structured output for automation.

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”