# Output Formats
Debtmap provides multiple output formats to suit different workflows, from interactive terminal reports to machine-readable JSON for CI/CD integration. This chapter covers all available formats and how to use them effectively.
## Format Selection
Select the output format using the `-f` or `--format` flag:
```bash
# Terminal output (default) - human-readable with colors
debtmap analyze .
# JSON output - machine-readable for tooling
debtmap analyze . --format json
# Markdown output - documentation and reports
debtmap analyze . --format markdown
# DOT output - Graphviz dependency visualization
debtmap analyze . --format dot
```
Available formats:
- **terminal** (default): Interactive output with colors, emoji, and formatting
- **json**: Structured data for programmatic processing and the [online dashboard](https://iepathos.github.io/debtmap/dashboard/)
- **markdown**: Reports suitable for documentation and PR comments
- **dot**: Graphviz DOT format for dependency graph visualization
> **Tip**: For visual exploration, generate JSON and use the [online dashboard](https://iepathos.github.io/debtmap/dashboard/) - see the [Visual Dashboard](dashboard.md) guide for details.
### Writing to Files
By default, output goes to stdout. Use `-o` or `--output` to write to a file:
```bash
# Write JSON to file
debtmap analyze . --format json -o report.json
# Write markdown report
debtmap analyze . --format markdown -o DEBT_REPORT.md
# Terminal output to file (preserves colors)
debtmap analyze . -o analysis.txt
```
## Terminal Output
The terminal format provides an interactive, color-coded report designed for developer workflows. It's the default format and optimized for readability.
### Output Structure
Terminal output is organized into five main sections:
1. **Header** - Analysis report title
2. **Codebase Summary** - High-level metrics and debt score
3. **Complexity Hotspots** - Top 5 most complex functions with refactoring guidance
4. **Technical Debt** - High-priority debt items requiring attention
5. **Pass/Fail Status** - Overall quality assessment
### Example Terminal Output
```
═══════════════════════════════════════════
DEBTMAP ANALYSIS REPORT
═══════════════════════════════════════════
📊 CODEBASE Summary
───────────────────────────────────────────
Files analyzed: 42
Total functions: 287
Average complexity: 6.3
Debt items: 15
Total debt score: 156 (threshold: 100)
⚠️ COMPLEXITY HOTSPOTS (Top 5)
───────────────────────────────────────────
1. src/analyzers/rust.rs:245 parse_function() - Cyclomatic: 18, Cognitive: 24
ACTION: Extract 3-5 pure functions using decompose-then-transform strategy
PATTERNS: Decompose into logical units, then apply functional patterns
BENEFIT: Pure functions are easily testable and composable
2. src/debt/smells.rs:196 detect_data_clumps() - Cyclomatic: 15, Cognitive: 20
↓ Entropy: 0.32, Repetition: 85%, Effective: 0.6x
High pattern repetition detected (85%)
🔧 TECHNICAL DEBT (15 items)
───────────────────────────────────────────
High Priority (5):
- src/risk/scoring.rs:142 - TODO: Implement caching for score calculations
- src/core/metrics.rs:89 - High complexity: cyclomatic=16
- src/debt/patterns.rs:201 - Code duplication: 65 lines duplicated
✓ Pass/Fail: PASS
```
### Color Coding and Symbols
The terminal output uses colors and symbols for quick visual scanning:
**Status Indicators:**
- ✓ Green: Passing, good, well-tested
- ⚠️ Yellow: Warning, moderate complexity
- ✗ Red: Failing, critical, high complexity
- 📊 Blue: Information, metrics
- 🔧 Orange: Technical debt items
- 🎯 Cyan: Recommendations
**Complexity Classification:**
- **LOW** (0-5): Green - Simple, easy to maintain
- **MODERATE** (6-10): Yellow - Consider refactoring
- **HIGH** (11-15): Orange - Should refactor
- **SEVERE** (>15): Red - Urgent refactoring needed
> **Note:** These levels match the `ComplexityLevel` enum in the implementation.
**Debt Score Thresholds:**
The default debt threshold is **100**. Scores are colored based on this threshold:
- **Green (≤50)**: Healthy - Below half threshold (score ≤ threshold/2)
- **Yellow (51-100)**: Attention needed - Between half and full threshold (threshold/2 < score ≤ threshold)
- **Red (>100)**: Action required - Exceeds threshold (score > threshold)
> **Note:** Boundary values use strict inequalities: 50 is Green, 100 is Yellow (not Red), 101+ is Red.
### Refactoring Guidance
For complex functions (cyclomatic complexity > 5), the terminal output provides actionable refactoring recommendations:
```
ACTION: Extract 3-5 pure functions using decompose-then-transform strategy
PATTERNS: Decompose into logical units, then apply functional patterns
BENEFIT: Pure functions are easily testable and composable
```
Guidance levels:
- **Moderate** (6-10): Extract 2-3 pure functions using direct functional transformation
- **High** (11-15): Extract 3-5 pure functions using decompose-then-transform strategy
- **Severe** (>15): Extract 5+ pure functions into modules with functional core/imperative shell
See the [Analysis Guide](./analysis-guide/index.md) for metric explanations.
### Plain Terminal Mode
For environments without color support or when piping to tools, use `--plain`:
```bash
# ASCII-only output, no colors
debtmap analyze . --plain
```
Plain mode:
- Removes ANSI color codes
- Uses ASCII box-drawing characters
- Machine-parseable structure
> **Note:** Terminal output formatting is controlled internally via `FormattingConfig` (found in `src/formatting` and `src/io/writers/terminal.rs`), which manages color mode settings. The `--plain` flag and environment variables provide user-facing control over these settings:
> - `--plain` flag - Disables colors and fancy formatting
> - `NO_COLOR=1` - Disables colors (per [no-color.org](https://no-color.org) standard)
> - `CLICOLOR=0` - Disables colors
> - `CLICOLOR_FORCE=1` - Forces colors even when output is not a terminal
>
> `FormattingConfig` is not directly exposed to CLI users but can be accessed when using debtmap as a library through `TerminalWriter::with_formatting`.
### Verbosity Levels
Control detail level with `-v` flags (can be repeated):
```bash
# Standard output
debtmap analyze .
# Level 1: Show main score factors
debtmap analyze . -v
# Level 2: Show detailed calculations
debtmap analyze . -vv
# Level 3: Show all debug information
debtmap analyze . -vvv
```
**Verbosity features:**
- `-v`: Show main score factors (complexity, coverage, dependency breakdown)
- `-vv`: Show detailed calculations with formulas and intermediate values
- `-vvv`: Show all debug information including entropy metrics and role detection
> **Note:** At `-vv`, JSON includes optional `scoring_details`. Default JSON omits those
> implementation details. Markdown verbosity also controls its rendered detail level.
Each level includes all information from the previous levels, progressively adding more detail to help understand how scores are calculated.
**Example Output Differences:**
Standard output shows basic metrics:
```
Total debt score: 156 (threshold: 100)
```
Level 1 (`-v`) adds score breakdowns:
```
Total debt score: 156 (threshold: 100)
Complexity contribution: 85 (54%)
Coverage gaps: 45 (29%)
Dependency issues: 26 (17%)
```
Level 2 (`-vv`) adds detailed calculations:
```
Total debt score: 156 (threshold: 100)
Complexity contribution: 85 (54%)
Formula: sum(cyclomatic_weight * severity_multiplier)
High complexity functions: 5 × 12 = 60
Medium complexity: 8 × 3 = 24
Base penalty: 1
Coverage gaps: 45 (29%)
Uncovered complex functions: 3 × 15 = 45
```
Level 3 (`-vvv`) adds all internal details:
```
Total debt score: 156 (threshold: 100)
... (all level 2 output) ...
Debug info:
Entropy metrics analyzed: 42/50 functions
Function role detection: PureLogic=12, IOWrapper=8, Unknown=5
Parse time: 245ms
```
### Understanding Metrics
To get detailed explanations of how metrics are calculated, use the `--explain-metrics` flag:
```bash
# Get explanations of metric definitions and formulas
debtmap analyze . --explain-metrics
```
This flag provides:
- **Metric definitions** - Detailed explanations of what each metric measures
- **Calculation formulas** - How scores are computed from raw data
- **Measured vs estimated** - Which metrics are exact and which are heuristic-based
- **Interpretation guidance** - How to understand and act on metric values
The explanations appear inline with the analysis output, helping you understand:
- What cyclomatic and cognitive complexity measure
- How debt scores are calculated
- What entropy metrics indicate
- How risk scores are determined
This is particularly useful when:
- Learning how debtmap evaluates code quality
- Understanding why certain functions have high scores
- Explaining analysis results to team members
- Tuning thresholds based on metric meanings
### Risk Analysis Output
When coverage data is provided via `--lcov`, terminal output includes a dedicated risk analysis section:
```
═══════════════════════════════════════════
RISK ANALYSIS REPORT
═══════════════════════════════════════════
📈 RISK Summary
───────────────────────────────────────────
Codebase Risk Score: 45.5 (MEDIUM)
Complexity-Coverage Correlation: -0.65
Risk Distribution:
Critical: 2 functions
High: 5 functions
Medium: 10 functions
Low: 15 functions
Well Tested: 20 functions
🎯 CRITICAL RISKS
───────────────────────────────────────────
1. src/core/parser.rs:142 parse_complex_ast()
Risk: 85.0 | Complexity: 15 | Coverage: 0%
Recommendation: Add 5 unit tests (est: 2-3 hours)
Impact: -40 risk reduction
💡 RECOMMENDATIONS (by ROI)
───────────────────────────────────────────
1. test_me() - ROI: 5.0x
Current Risk: 75 | Reduction: 40 | Effort: Moderate
Rationale: High risk function with low coverage
```
**Risk Level Classification:**
- **LOW** (<30): Green - score < 30.0
- **MEDIUM** (30-59): Yellow - 30.0 ≤ score < 60.0
- **HIGH** (≥60): Red - score ≥ 60.0
> **Note:** 60 is the start of HIGH risk level.
## JSON Output
JSON output provides complete analysis results in a machine-readable format, ideal for CI/CD pipelines, custom tooling, and programmatic analysis.
### Basic Usage
```bash
# Generate JSON output
debtmap analyze . --format json
# Save to file
debtmap analyze . --format json -o report.json
# Pretty-printed by default for readability
debtmap analyze . --format json | jq .
```
> **Note:** JSON output is automatically pretty-printed for readability.
> **Data handling:** JSON reports contain codebase metadata such as paths, symbols, call
> relationships, and git-derived aggregates. Review or redact reports before uploading them to
> external dashboards, artifacts, or webhooks.
### JSON Schema Structure
Debtmap emits the versioned unified JSON v3 contract. The authoritative schema and consumer guide
are checked into the repository:
- [`schemas/debtmap-output-v3.schema.json`](https://github.com/iepathos/debtmap/blob/master/schemas/debtmap-output-v3.schema.json)
- [`docs/json-output-v3.md`](https://github.com/iepathos/debtmap/blob/master/docs/json-output-v3.md)
The top-level envelope is:
```json
{
"format_version": "3.0",
"metadata": { ... },
"summary": { ... },
"items": [ ... ]
}
```
Consumers must reject unsupported `format_version` values. Items use a `type` discriminator of
`File` or `Function`, lowercase priority values, and nested `location` and `metrics` objects.
### Legacy pre-v3 example (historical)
The example below describes the removed pre-v3 output and is retained temporarily only to explain
older reports. Do not use these paths for new integrations; use the v3 schema and guide linked
above.
Here's a complete annotated JSON output example:
```json
{
// Project metadata
"project_path": "/Users/dev/myproject",
"timestamp": "2025-01-09T15:30:00Z",
// Complexity analysis results
"complexity": {
"metrics": [
{
"name": "calculate_risk_score",
"file": "src/risk/scoring.rs",
"line": 142,
"cyclomatic": 12,
"cognitive": 18,
"nesting": 4,
"length": 85,
"is_test": false,
"visibility": "pub",
"is_trait_method": false,
"in_test_module": false,
"entropy_score": {
"token_entropy": 0.65,
"pattern_repetition": 0.30,
"branch_similarity": 0.45,
"effective_complexity": 0.85
},
"is_pure": false,
"purity_confidence": 0.75,
"detected_patterns": ["nested_loops", "complex_conditionals"],
"upstream_callers": ["analyze_codebase", "generate_report"],
"downstream_callees": ["get_metrics", "apply_weights"]
}
],
"summary": {
"total_functions": 287,
"average_complexity": 6.3,
"max_complexity": 24,
"high_complexity_count": 12
}
},
// Technical debt items
"technical_debt": {
"items": [
{
"id": "debt_001",
"debt_type": "Complexity",
"priority": "High",
"file": "src/analyzers/rust.rs",
"line": 245,
"column": 5,
"message": "High cyclomatic complexity: 18",
"context": "Function parse_function has excessive branching"
},
{
"id": "debt_002",
"debt_type": "Todo",
"priority": "Medium",
"file": "src/core/cache.rs",
"line": 89,
"column": null,
"message": "TODO: Implement LRU eviction policy",
"context": null
}
],
"by_type": {
"Complexity": [ /* same structure as items */ ],
"Todo": [ /* ... */ ],
"Duplication": [ /* ... */ ]
},
"priorities": ["Low", "Medium", "High", "Critical"]
},
// Dependency analysis
"dependencies": {
"modules": [
{
"module": "risk::scoring",
"dependencies": ["core::metrics", "debt::patterns"],
"dependents": ["commands::analyze", "io::output"]
}
],
"circular": [
{
"cycle": ["module_a", "module_b", "module_c", "module_a"]
}
]
},
// Code duplication blocks
"duplications": [
{
"hash": "abc123def456",
"lines": 15,
"locations": [
{
"file": "src/parser/rust.rs",
"start_line": 42,
"end_line": 57
},
{
"file": "src/parser/python.rs",
"start_line": 89,
"end_line": 104
}
]
}
]
}
```
### Legacy field descriptions (pre-v3)
**FunctionMetrics Fields:**
- `name`: Function name
- `file`: Path to source file
- `line`: Line number where function is defined
- `cyclomatic`: Cyclomatic complexity score
- `cognitive`: Cognitive complexity score
- `nesting`: Maximum nesting depth
- `length`: Lines of code in function
- `is_test`: Whether this is a test function
- `visibility`: Rust visibility modifier (pub, pub(crate), or null)
- `is_trait_method`: Whether this implements a trait
- `in_test_module`: Whether inside #[cfg(test)]
- `entropy_score`: Optional entropy analysis with structure:
```json
{
"token_entropy": 0.65, "pattern_repetition": 0.30, "branch_similarity": 0.45, "effective_complexity": 0.85 }
```
**EntropyScore Fields:**
- `token_entropy`: Measures the variety and distribution of tokens in the function (0-1, higher = more variety)
- `pattern_repetition`: Detects repeated code patterns within the function (0-1, higher = more repetition)
- `branch_similarity`: Measures similarity between different code branches (0-1, higher = more similar)
- `effective_complexity`: The overall complexity multiplier adjusted for entropy effects
- `is_pure`: Whether function is pure (no side effects)
- `purity_confidence`: Confidence level (0.0-1.0)
- `detected_patterns`: List of detected code patterns
- `upstream_callers`: Functions that call this one
- `downstream_callees`: Functions this one calls
**DebtItem Fields:**
- `id`: Unique identifier
- `debt_type`: Type of debt (see DebtType enum below)
- `priority`: Priority level (Low, Medium, High, Critical)
- `file`: Path to file containing debt
- `line`: Line number
- `column`: Optional column number
- `message`: Human-readable description
- `context`: Optional additional context
**DebtType Enum:**
- `Todo`: TODO markers
- `Fixme`: FIXME markers
- `CodeSmell`: Code smell patterns
- `Duplication`: Duplicated code
- `Complexity`: Excessive complexity
- `Dependency`: Dependency issues
- `ErrorSwallowing`: Suppressed errors
- `ResourceManagement`: Resource management issues
- `CodeOrganization`: Organizational problems
- `TestComplexity`: Complex test code
- `TestTodo`: TODOs in tests
- `TestDuplication`: Duplicated test code
- `TestQuality`: Test quality issues
### Legacy risk insights JSON (pre-v3)
When coverage data is provided via `--lcov`, risk insights are included as part of the analysis output. The `write_risk_insights` method (found in `src/io/writers/json.rs`, `terminal.rs`, and `markdown/core.rs`) outputs risk analysis data in the following JSON structure:
```json
{
"items": [
{
"location": {
"file": "src/risk/scoring.rs",
"function": "calculate_priority",
"line": 66
},
"debt_type": "TestGap",
"unified_score": {
"complexity_factor": 3.2,
"coverage_factor": 10.0,
"dependency_factor": 2.5,
"role_multiplier": 1.2,
"final_score": 9.4
},
"function_role": "BusinessLogic",
"recommendation": {
"action": "Add unit tests",
"details": "Add 6 unit tests for full coverage",
"effort_estimate": "2-3 hours"
},
"expected_impact": {
"risk_reduction": 3.9,
"complexity_reduction": 0,
"coverage_improvement": 100
},
"upstream_dependencies": 0,
"downstream_dependencies": 3,
"nesting_depth": 1,
"function_length": 13
}
],
"call_graph": {
"total_functions": 1523,
"entry_points": 12,
"test_functions": 456,
"max_depth": 8
},
"overall_coverage": 82.3,
"total_impact": {
"risk_reduction": 45.2,
"complexity_reduction": 12.3,
"coverage_improvement": 18.5
}
}
```
## Markdown Output
Markdown format generates documentation-friendly reports suitable for README files, PR comments, and technical documentation.
### Basic Usage
```bash
# Generate markdown report
debtmap analyze . --format markdown
# Save to documentation
debtmap analyze . --format markdown -o docs/DEBT_REPORT.md
```
### Markdown Structure
Markdown output includes:
1. **Executive Summary** - High-level metrics and health dashboard
2. **Complexity Analysis** - Detailed complexity breakdown by file
3. **Technical Debt** - Categorized debt items with priorities
4. **Dependencies** - Module dependencies and circular references
5. **Recommendations** - Prioritized action items
### Example Markdown Output
```markdown
# Debtmap Analysis Report
**Generated:** 2025-01-09 15:30:00 UTC
**Project:** /Users/dev/myproject
## Executive Summary
- **Files Analyzed:** 42
- **Total Functions:** 287
- **Average Complexity:** 6.3
- **Total Debt Items:** 15
- **Debt Score:** 156/100 ⚠️
### Health Dashboard
| Complexity | 6.3 avg | ✅ Good |
| Debt Score | 156 | ⚠️ Attention |
| High Priority Items | 5 | ⚠️ Action Needed |
## Complexity Analysis
### Top 5 Complex Functions
| parse_function | src/analyzers/rust.rs:245 | 18 | 24 | High |
| detect_data_clumps | src/debt/smells.rs:196 | 15 | 20 | Medium |
| analyze_dependencies | src/core/deps.rs:89 | 14 | 18 | Medium |
### Refactoring Recommendations
**src/analyzers/rust.rs:245** - `parse_function()`
- **Complexity:** Cyclomatic: 18, Cognitive: 24
- **Action:** Extract 3-5 pure functions using decompose-then-transform strategy
- **Patterns:** Decompose into logical units, then apply functional patterns
- **Benefit:** Improved testability and maintainability
## Technical Debt
### High Priority (5 items)
- **src/risk/scoring.rs:142** - TODO: Implement caching for score calculations
- **src/core/metrics.rs:89** - High complexity: cyclomatic=16
- **src/debt/patterns.rs:201** - Code duplication: 65 lines duplicated
### Medium Priority (8 items)
...
## Dependencies
### Circular Dependencies
- `risk::scoring` → `core::metrics` → `risk::scoring`
## Recommendations
1. **Refactor parse_function** (High Priority)
- Reduce complexity from 18 to <10
- Extract helper functions
- Estimated effort: 4-6 hours
2. **Add tests for scoring module** (High Priority)
- Current coverage: 35%
- Target coverage: 80%
- Estimated effort: 2-3 hours
## Data Flow Analysis
When verbosity is enabled (`-v` or higher), detailed data flow analysis is included in markdown reports for top priority items. This section provides deep insights into mutations, I/O operations, and escape analysis.
### Mutation Analysis
Shows variable mutation patterns within functions:
**Example:**
```markdown
**Data Flow Analysis**
- Mutations: 10 total, 2 live, 2 dead stores
- **Opportunity**: Remove 2 dead store(s) to simplify code
- **Almost Pure**: Only 2 live mutation(s), consider extracting pure subset
```
**Mutation Metrics:**
- **Total Mutations:** Count of all variable assignments and mutations
- **Live Mutations:** Mutations where the new value is actually used
- **Dead Stores:** Assignments that are never read (can be removed)
**Refactoring Opportunities:**
- Functions with many dead stores can be simplified by removing unused assignments
- Functions with few live mutations relative to total mutations are "almost pure" and may benefit from extracting pure subsets
### I/O Operations
Detects and lists input/output operations within functions:
**Example:**
```markdown
- I/O Operations: 3 detected
- File Read at line 105
- Network Call at line 110
- Database Query at line 120
- **Recommendation**: Consider isolating I/O in separate functions
```
**Detected I/O Types:**
- File system operations (read, write, open, close)
- Network operations (HTTP, TCP, UDP)
- Database queries and updates
- Standard I/O (print, input)
- System calls
**Best Practices:**
- Isolate I/O operations in dedicated functions
- Keep business logic pure and separate from I/O
- Easier testing when I/O is at function boundaries
### Escape Analysis
Shows which variables escape the function scope or affect the return value:
**Example:**
```markdown
- Escape Analysis: 2 variables escape
- Return dependencies: result, accumulator
- **Insight**: These variables directly affect function output
```
**Escape Metrics:**
- **Escaping Variables:** Variables whose values leave the function scope
- **Return Dependencies:** Variables that contribute to the return value
**Implications:**
- Functions with many escaping variables have complex data flow
- Clear return dependencies indicate focused, single-purpose functions
- Excessive escaping may indicate the function is doing too much
### Purity Analysis
Indicates whether a function is pure and reasons for any impurity:
**Example:**
```markdown
- Purity: Not pure (95% confidence)
- Reasons: Mutates shared state, Performs I/O operations
- **Benefit**: Converting to pure functions improves testability
```
**Purity Assessment:**
- **Is Pure:** Boolean indicating if the function is pure (deterministic, no side effects)
- **Confidence Level:** Percentage confidence in the assessment (0-100%)
- **Impurity Reasons:** Specific reasons why the function is not pure
**Common Impurity Reasons:**
- Mutates shared or global state
- Performs I/O operations
- Calls other impure functions
- Uses random number generation
- Depends on system time or external state
**Value of Pure Functions:**
- Easier to test (no setup/teardown needed)
- Easier to reason about (same input always gives same output)
- Safe to parallelize and memoize
- More composable and reusable
### Enabling Data Flow Analysis
Data flow analysis appears in markdown output when using verbose mode:
```bash
# Include data flow analysis in markdown reports
debtmap analyze . --format markdown -v
# Higher verbosity includes more details
debtmap analyze . --format markdown -vv
```
The data flow section appears in the score breakdown for each of the top 3 priority items, providing actionable insights for refactoring.
```
### CLI vs Library Markdown Features
**CLI Markdown Output (`--format markdown`):**
When you use `debtmap analyze . --format markdown`, you get comprehensive reports that include:
- Executive summary with health dashboard
- Complexity analysis with refactoring recommendations
- Technical debt categorization by priority
- Dependency analysis with circular reference detection
- Actionable recommendations
This uses the base `MarkdownWriter` implementation and provides everything needed for documentation and PR comments.
**Enhanced Library Features:**
If you're using debtmap as a Rust library in your own tools, additional markdown capabilities are available:
- **`EnhancedMarkdownWriter` trait** (`src/io/writers/markdown/enhanced.rs`) - Provides advanced formatting and analysis features
- **Enhanced markdown modules** (`src/io/writers/enhanced_markdown/`) - Building blocks for custom visualizations including:
- Priority-based debt rankings with unified scoring
- Dead code detection and reporting
- Call graph insights and dependency visualization
- Testing recommendations with ROI analysis
To use enhanced features in your Rust code:
```rust
use debtmap::io::writers::markdown::enhanced::EnhancedMarkdownWriter;
use debtmap::io::writers::enhanced_markdown::*;
// Create custom reports with enhanced features
let mut writer = create_enhanced_writer(output)?;
writer.write_priority_rankings(&analysis)?;
writer.write_dead_code_analysis(&call_graph)?;
```
> **Note:** Enhanced markdown features are only available through the library API, not via the CLI. The CLI `--format markdown` output is comprehensive for most use cases.
### Rendering to HTML/PDF
Markdown reports can be converted to other formats:
```bash
# Generate markdown
debtmap analyze . --format markdown -o report.md
# Convert to HTML with pandoc
pandoc report.md -o report.html --standalone --css style.css
# Convert to PDF
pandoc report.md -o report.pdf --pdf-engine=xelatex
```
## Visual Dashboard
For interactive visualization of your analysis results, use the **[online dashboard](https://iepathos.github.io/debtmap/dashboard/)**.
### Quick Start
```bash
# Generate JSON output
debtmap analyze . --format json -o debtmap.json --lcov coverage.lcov --context
# Visit https://iepathos.github.io/debtmap/dashboard/
# Click "Load JSON File" and select your debtmap.json
```
The dashboard runs entirely in your browser - your data never leaves your machine.
### Dashboard Features
- **Risk Quadrant** - Functions plotted by complexity vs coverage gap
- **Top Debt Items** - Sortable table of highest priority issues
- **Module Flow** - Chord diagram showing debt relationships
- **Risk Radar** - Multi-dimensional comparison of top files
See the [Visual Dashboard](dashboard.md) guide for complete documentation.
## DOT Output
DOT format generates Graphviz-compatible output for visualizing file dependencies and technical debt as a graph. This is useful for understanding code architecture and identifying coupling patterns.
**Source:** `src/io/writers/dot.rs` (Spec 204)
### Basic Usage
```bash
# Generate DOT output for dependency visualization
debtmap analyze . --format dot
# Save to file
debtmap analyze . --format dot -o deps.dot
```
### Rendering the Graph
DOT files can be rendered using Graphviz tools:
```bash
# Generate SVG (recommended for web)
dot -Tsvg deps.dot -o deps.svg
# Generate PNG
dot -Tpng deps.dot -o deps.png
# Interactive exploration with xdot
xdot deps.dot
```
### Graph Features
The DOT output provides:
1. **File Nodes** - Each analyzed file appears as a node
2. **Dependency Edges** - Arrows show which files depend on which
3. **Color-Coded Debt Scores** - Node colors indicate debt severity:
- **Green** (#6BCB77): Low debt (<20)
- **Yellow** (#FFD93D): Medium debt (≥20)
- **Orange** (#FF8C00): High debt (≥50)
- **Red** (#FF6B6B): Critical debt (≥100)
4. **Module Clustering** - Files are grouped by directory/module
5. **Tooltips** - Hover for detailed metrics (score, functions, lines, coupling)
6. **Legend** - Built-in legend explains the color coding
### Example Output
```dot
digraph debtmap {
rankdir=TB;
node [shape=box, style=filled, fontname="Helvetica"];
edge [fontname="Helvetica", fontsize=10];
subgraph cluster_legend {
label="Debt Score Legend";
legend_critical [label="Critical (>=100)", fillcolor="#FF6B6B"];
legend_high [label="High (>=50)", fillcolor="#FF8C00"];
legend_medium [label="Medium (>=20)", fillcolor="#FFD93D"];
legend_low [label="Low (<20)", fillcolor="#6BCB77"];
}
subgraph cluster_io {
label="io";
"src_io_output_rs" [label="output.rs", fillcolor="#6BCB77"];
"src_io_writers_json_rs" [label="json.rs", fillcolor="#FFD93D"];
}
// Dependencies
"src_io_output_rs" -> "src_io_writers_json_rs";
}
```
### When to Use DOT Format
**Use DOT Format When:**
- Visualizing module dependencies and architecture
- Identifying tightly coupled file clusters
- Finding isolated or dead code modules
- Presenting architecture to team members
- Detecting circular dependency patterns
- Understanding code organization
**DOT vs Other Formats:**
- **DOT**: Best for dependency visualization and architecture understanding
- **JSON**: Best for programmatic processing and CI/CD integration
- **Dashboard**: Load JSON into the web dashboard for interactive metrics overview
- **Terminal/Markdown**: Best for readable reports and documentation
## Tool Integration
### CI/CD Pipelines
Debtmap JSON output integrates seamlessly with CI/CD systems.
#### GitHub Actions
```yaml
name: Code Quality
on: [pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install debtmap
run: cargo install debtmap
- name: Run analysis
run: |
debtmap analyze . \
--format json \
--output analysis.json \
--lcov coverage/lcov.info
- name: Check thresholds
run: |
DEBT_ITEMS=$(jq '.summary.total_items' analysis.json)
if [ "$DEBT_ITEMS" -gt 100 ]; then
echo "❌ Too many debt items: $DEBT_ITEMS"
exit 1
fi
- name: Comment on PR
uses: actions/github-script@v6
with:
script: |
const fs = require('fs');
const analysis = JSON.parse(fs.readFileSync('analysis.json'));
const summary = `## Debtmap Analysis
- **Debt Items:** ${analysis.summary.total_items}
- **Debt Score:** ${analysis.summary.total_debt_score}
- **High-priority Items:** ${analysis.summary.score_distribution.high}
`;
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: summary
});
```
#### GitLab CI
```yaml
code_quality:
stage: test
script:
- cargo install debtmap
- debtmap analyze . --format json --output gl-code-quality.json
- |
DEBT=$(jq '.summary.total_items' gl-code-quality.json)
if [ "$DEBT" -gt 50 ]; then
echo "Debt threshold exceeded"
exit 1
fi
artifacts:
paths:
- gl-code-quality.json
```
#### Jenkins Pipeline
```groovy
pipeline {
agent any
stages {
stage('Analyze') {
steps {
sh 'debtmap analyze . --format json -o report.json'
script {
def json = readJSON file: 'report.json'
def debtScore = json.summary.total_items
if (debtScore > 100) {
error("Debt score ${debtScore} exceeds threshold")
}
}
}
}
}
post {
always {
archiveArtifacts artifacts: 'report.json'
}
}
}
```
### Querying JSON with jq
Common jq queries for analyzing debtmap output:
```bash
# Get total debt items
jq '.summary.total_items' report.json
# Get high-priority items only
# Get functions with complexity > 10
# Get codebase debt density
jq '.summary.debt_density' report.json
# Get all TODO items
# Get top 5 complex functions
# Count debt items by type
# Get functions with 0% coverage (when using --lcov)
# Extract file paths with high debt
### Filtering and Transformation Examples
#### Python Script to Parse JSON
```python
#!/usr/bin/env python3
import json
import sys
def analyze_debtmap_output(json_file):
with open(json_file) as f:
data = json.load(f)
# Get high-priority items
high_priority = [
item for item in data['items']
if item['priority'] in ['high', 'critical']
]
# Group by file
by_file = {}
for item in high_priority:
file = item['location']['file']
if file not in by_file:
by_file[file] = []
by_file[file].append(item)
# Print summary
print(f"High-priority debt items: {len(high_priority)}")
print(f"Files affected: {len(by_file)}")
print("\nBy file:")
for file, items in sorted(by_file.items(), key=lambda x: -len(x[1])):
print(f" {file}: {len(items)} items")
return by_file
if __name__ == '__main__':
analyze_debtmap_output(sys.argv[1])
```
#### Shell Script for Threshold Checking
```bash
#!/bin/bash
set -e
REPORT="$1"
DEBT_THRESHOLD=100
DEBT_DENSITY_THRESHOLD=10
# Check debt score
DEBT_ITEMS=$(jq '.summary.total_items' "$REPORT")
if [ "$DEBT_ITEMS" -gt "$DEBT_THRESHOLD" ]; then
echo "❌ Debt items $DEBT_ITEMS exceeds threshold $DEBT_THRESHOLD"
exit 1
fi
# Check debt density
DEBT_DENSITY=$(jq '.summary.debt_density' "$REPORT")
if (( $(echo "$DEBT_DENSITY > $DEBT_DENSITY_THRESHOLD" | bc -l) )); then
echo "❌ Debt density $DEBT_DENSITY exceeds threshold $DEBT_DENSITY_THRESHOLD"
exit 1
fi
echo "✅ All quality checks passed"
echo " Debt items: $DEBT_ITEMS/$DEBT_THRESHOLD"
echo " Debt density: $DEBT_DENSITY"
```
### Editor Integration
#### VS Code Tasks
Create `.vscode/tasks.json`:
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Debtmap: Analyze",
"type": "shell",
"command": "debtmap",
"args": [
"analyze",
".",
"--format",
"terminal"
],
"problemMatcher": [],
"presentation": {
"reveal": "always",
"panel": "new"
}
},
{
"label": "Debtmap: Generate Report",
"type": "shell",
"command": "debtmap",
"args": [
"analyze",
".",
"--format",
"markdown",
"-o",
"DEBT_REPORT.md"
],
"problemMatcher": []
}
]
}
```
#### Problem Matcher for VS Code
Parse debtmap output in VS Code's Problems panel:
```json
{
"problemMatcher": {
"owner": "debtmap",
"fileLocation": "absolute",
"pattern": {
"regexp": "^(.+?):(\\d+):(\\d+)?\\s*-\\s*(.+)$",
"file": 1,
"line": 2,
"column": 3,
"message": 4
}
}
}
```
### Webhook Integration
Send debtmap results to webhooks for notifications:
```bash
#!/bin/bash
# Run analysis
debtmap analyze . --format json -o report.json
# Send to Slack
DEBT_SCORE=$(jq '.summary.total_debt_score' report.json)
curl -X POST "$SLACK_WEBHOOK_URL" \
-H 'Content-Type: application/json' \
-d "{\"text\": \"Debtmap Analysis Complete\n• Debt Score: $DEBT_SCORE\n• High Priority: $(jq '.summary.score_distribution.high' report.json)\"}"
# Send to custom webhook
curl -X POST "$CUSTOM_WEBHOOK_URL" \
-H 'Content-Type: application/json' \
-d @report.json
```
## Output Filtering
Debtmap provides several flags to filter and limit output:
> **Note:** Filtering options (`--top`, `--tail`, `--summary`, `--filter`) apply to all output formats (terminal, JSON, and markdown). The filtered data is applied at the analysis level before formatting, ensuring consistent results across all output types.
### Limiting Results
```bash
# Show only top 10 priority items
debtmap analyze . --top 10
# Show bottom 5 lowest priority items
debtmap analyze . --tail 5
```
### Priority Filtering
```bash
# Show only high and critical priority items
debtmap analyze . --min-priority high
# Filter by specific debt categories
debtmap analyze . --filter Architecture,Testing
```
Available categories:
- `Architecture`: God objects, complexity hotspots, dead code
- `Testing`: Testing gaps, coverage issues
- `Performance`: Resource leaks, inefficient patterns
- `CodeQuality`: Code smells, maintainability
### Grouping Output
```bash
# Combine filters for focused analysis
debtmap analyze . --filter Architecture --min-priority high --top 5
```
### Summary Mode
```bash
# Compact tiered priority display
debtmap analyze . --summary
# Combines well with filtering
debtmap analyze . --summary --min-priority medium
```
## Best Practices
### When to Use Each Format
**Use Terminal Format When:**
- Developing locally and reviewing code
- Getting quick feedback on changes
- Presenting results to team members
- Exploring complexity hotspots interactively
**Use JSON Format When:**
- Integrating with CI/CD pipelines
- Building custom analysis tools
- Tracking metrics over time
- Programmatically processing results
- Feeding into dashboards or monitoring systems
**Use Markdown Format When:**
- Generating documentation
- Creating PR comments
- Sharing reports with stakeholders
- Archiving analysis results
- Producing executive summaries
**Use Dashboard JSON When:**
- Viewing analysis in the web dashboard
- Sharing visual dashboards with stakeholders
- Publishing interactive reports for management review
- Embedding analysis results in web applications
### Quick Reference Table
| Terminal | Development | No | Yes | .txt |
| JSON | Automation | Yes | No | .json |
| Markdown | Documentation | Partially | Yes | .md |
| DOT | Architecture | Yes | Partially | .dot |
### Combining Formats
Use multiple formats for comprehensive workflows:
```bash
# Generate terminal output for review
debtmap analyze .
# Generate JSON for automation
debtmap analyze . --format json -o ci-report.json
# Generate markdown for documentation
debtmap analyze . --format markdown -o docs/DEBT.md
# Generate DOT for architecture visualization
debtmap analyze . --format dot -o deps.dot && dot -Tsvg deps.dot -o deps.svg
```
### Performance Considerations
- **Terminal format**: Fastest, minimal overhead
- **JSON format**: Fast serialization, efficient for large codebases
- **Markdown format**: Slightly slower due to formatting, but still performant
For very large codebases (>10,000 files), use `--top` or `--filter` to limit output size.
## Troubleshooting
### Common Issues
**Colors not showing in terminal:**
- Check if terminal supports ANSI colors
- Use `--plain` flag for ASCII-only output
- Some CI systems may not support color codes
**JSON parsing errors:**
- Ensure output is complete (check for errors during analysis)
- Validate JSON with `jq` or online validators
- Check for special characters in file paths
**Markdown rendering issues:**
- Some markdown renderers don't support all features
- Use standard markdown for maximum compatibility
- Test with pandoc or GitHub/GitLab preview
**File encoding problems:**
- Ensure UTF-8 encoding for all output files
- Use `--plain` for pure ASCII output
- Check locale settings (LC_ALL, LANG environment variables)
### Exit Codes
Current behavior (as verified in `src/main.rs`):
- `0`: Successful analysis completed without errors
- Non-zero: Error during analysis (invalid path, parsing error, etc.)
> **Note:** Threshold-based exit codes (where analysis succeeds but fails quality gates) are not currently implemented. The `analyze` command returns 0 on successful analysis regardless of debt scores or complexity thresholds.
To enforce quality gates based on thresholds, use the `validate` command or parse JSON output:
```bash
# Use validate command for threshold enforcement
debtmap validate . --config debtmap.toml
# Or parse JSON output for threshold checking
debtmap analyze . --format json -o report.json
DEBT_ITEMS=$(jq '.summary.total_items' report.json)
if [ "$DEBT_ITEMS" -gt 100 ]; then
echo "Debt threshold exceeded"
exit 1
fi
```
## See Also
- [Getting Started](./getting-started.md) - Basic usage and examples
- [Analysis Guide](./analysis-guide/index.md) - Understanding metrics and scores
- [Configuration](./configuration.md) - Customizing analysis behavior