Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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, dot
  • -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)

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, dot (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, dot (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, 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
    • 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

Progress Display:

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

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,typescript,go
    • Supported: rust, python, javascript, typescript, go
    • Aliases include common extensions plus golang for Go

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

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

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

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

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

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

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

Optionanalyzevalidatecompareinitdiagnose-coverageexplain-coverage
<PATH> argument✓✓✗✗✓✓
--format✓✓✓✗✓✓
--output✓✓✓✗✗✗
--coverage-file✓✓✗✗✗✓
--context✓✓✗✗✗✗
--threshold-*✓✗✗✗✗✗
--top / --tail✓✓✗✗✗✗
--min-score✓✗✗✗✗✗
--show-filter-stats✓✗✗✗✗✗
--quiet✓✗✗✗✗✗
--no-tui✓✗✗✗✗✗
--jobs✓✓✗✗✗✗
--no-parallel✓✓✗✗✗✗
--profile✓✗✗✗✗✗
--profile-output✓✗✗✗✗✗
--verbose✓✓✗✗✗✓
--show-splits✓✓✗✗✗✗
--explain-metrics✓✗✗✗✗✗
--debug-call-graph✓✗✗✗✗✗
--trace-function✓✗✗✗✗✗
--call-graph-stats✓✗✗✗✗✗
--validate-call-graph✓✗✗✗✗✗
--debug-format✓✗✗✗✗✗
--ast-functional-analysis✓✗✗✗✗✗
--functional-analysis-profile✓✗✗✗✗✗
--function✗✗✗✗✗✓
--file✗✗✗✗✗✓
--config✗✓✗✗✗✗
--before / --after✗✗✓✗✗✗
--force✗✗✗✓✗✗

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