debtmap 0.17.0

# CLI Reference

Complete reference for Debtmap command-line interface.

## Quick Start

```bash
# 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:**
```bash
# 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:**
```bash
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](#options) section below for all available flags.

### `init`

Initialize a Debtmap configuration file.

**Usage:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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`
  - 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

### 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:**
```bash
# 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:
```bash
# 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:
```bash
debtmap analyze src/
```

Generate JSON report for further processing:
```bash
debtmap analyze . --format json --output report.json
```

Generate Markdown report:
```bash
debtmap analyze . --format markdown --output report.md
```

### Coverage-Integrated Analysis

Analyze with test coverage to surface untested complex code:
```bash
# 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:
```bash
# 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:
```bash
debtmap analyze . --top 10 --min-priority high
```

Filter by specific debt categories:
```bash
debtmap analyze . --filter complexity,duplication
```

Use summary mode for compact output:
```bash
debtmap analyze . --summary
```

Show only file-level aggregations:
```bash
debtmap analyze . --aggregate-only
```

### Performance Tuning

Control parallelization:
```bash
# Use 8 threads
debtmap analyze . --jobs 8

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

Limit analysis scope:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
debtmap compare --before before.json --after after.json --plan IMPLEMENTATION_PLAN.md
```

### Debugging Analysis

Increase verbosity to understand scoring:
```bash
# 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:
```bash
# 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):
```bash
debtmap analyze . --show-macro-stats --verbose-macro-warnings
```

Analyze functional programming patterns:
```bash
# 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
```bash
# Analyze current directory
debtmap analyze .

# Analyze specific directory
debtmap analyze src/

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

### With Coverage
```bash
# Analyze with LCOV coverage file
debtmap analyze src/ --coverage-file coverage.lcov

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

### Context-Aware Analysis
```bash
# 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
```bash
# 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
```bash
# Use 8 threads
debtmap analyze . --jobs 8

# Disable parallelization
debtmap analyze . --no-parallel

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

### Validation
```bash
# 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
```bash
# 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
```bash
# Analyze only Rust files
debtmap analyze . --languages rust

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

### Threshold Configuration
```bash
# 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
```bash
# Plain output (no colors, no emoji)
debtmap analyze . --plain

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

### Advanced Debugging
```bash
# 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

| Option | analyze | validate | compare | init | diagnose-coverage | explain-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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Use plain mode
debtmap analyze . --plain
```

**Problem:** Want machine-readable output

**Solution:**
```bash
# Use JSON with plain mode
debtmap analyze . --format json --plain --output report.json
```

### Threshold Issues

**Problem:** Too many items flagged

**Solutions:**
```bash
# 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:**
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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](./configuration.md) - Detailed configuration file format
- [Output Formats](./output-formats.md) - Understanding JSON, Markdown, and Terminal output
- [Coverage Integration](./coverage-integration.md) - Integrating test coverage data
- [Context Providers](./context-providers.md) - Understanding context-aware analysis
- [Examples](./examples.md) - More comprehensive usage examples