debtmap 0.16.7

Code complexity and technical debt analyzer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332

# Quick Fixes

If you're experiencing problems with debtmap, try these quick solutions before diving into detailed troubleshooting.

## Slow Analysis

**Problem**: Analysis takes too long to complete

**Quick Solutions**:

```bash
# Use all available CPU cores (default)
debtmap analyze . --jobs 0

# Disable multi-pass analysis for faster single-pass
debtmap analyze . --no-multi-pass

# Use faster fallback mode (less accurate but much faster)
debtmap analyze . --semantic-off

# Limit files for testing
debtmap analyze . --max-files 100

# Analyze a specific subdirectory only
debtmap analyze src/specific/module
```

**Source**: CLI flags defined in `src/cli/args.rs:227-240`

**When to use each approach**:
- `--jobs 0`: Default, maximum performance on dedicated machine
- `--no-multi-pass`: CI/CD pipelines, large codebases (>100k LOC)
- `--semantic-off`: Quick complexity checks during development
- `--max-files`: Testing configuration before full analysis

See [Debug Mode](debug-mode.md) for performance monitoring options.

## Parse Errors

**Problem**: "Parse error in file:line:column" messages

**Quick Solutions**:

```bash
# Try fallback mode without semantic analysis
debtmap analyze . --semantic-off

# For Rust macro issues, see detailed warnings
debtmap analyze . --verbose-macro-warnings --show-macro-stats

# Exclude problematic files via configuration
# Add to .debtmap/config.toml:
# exclude = ["path/to/problematic/file.rs"]
```

**Source**: Verbose macro flags in `src/cli/args.rs:317-326`

**Common causes**:
- Unsupported language syntax or version
- Complex macro expansions (Rust)
- Type inference edge cases (Python, TypeScript)

See [Error Messages Reference](error-messages.md) for detailed parse error explanations.

## No Output

**Problem**: Running debtmap produces no output or results

**Quick Solutions**:

```bash
# Increase verbosity to see what's happening
debtmap analyze . -v

# Lower the minimum priority threshold
debtmap analyze . --min-priority low

# Lower the minimum score threshold
debtmap analyze . --min-score 0

# Check if files are being analyzed
debtmap analyze . -vv 2>&1 | grep "Processing"

# Use lenient threshold preset
debtmap analyze . --threshold-preset lenient

# Show all items without filtering
debtmap analyze . --min-priority low --top 100
```

**Source**: Filtering options in `src/cli/args.rs:143-163`

**Common causes**:
- Threshold preset too strict (try `--threshold-preset lenient`)
- Category filters excluding all results
- Min-priority too high
- Min-score too high

## Inconsistent Results

**Problem**: Results differ between runs

**Quick Solutions**:

```bash
# Check if coverage file changed
debtmap analyze . --coverage-file coverage.info -v

# Disable context providers for consistent baseline
debtmap analyze . --no-context-aware

# Compare runs with debug output
debtmap analyze . -vv > run1.txt
debtmap analyze . -vv > run2.txt
diff run1.txt run2.txt
```

**Source**: Context-aware flag in `src/cli/args.rs:202-204`

**Common causes**:
- Coverage file changed between runs
- Context providers enabled/disabled (`--context`)
- Git history changes affecting git_history provider
- Different threshold settings

## Coverage Data Not Matching Functions

**Problem**: Coverage data not being applied to functions

**Quick Solutions**:

```bash
# Debug coverage data parsing for a specific function
debtmap explain-coverage . \
  --coverage-file coverage.lcov \
  --function "process_file"

# See detailed function matching diagnostics
debtmap explain-coverage . \
  --coverage-file coverage.lcov \
  --function "process_file" \
  -v

# Narrow search to specific file
debtmap explain-coverage . \
  --coverage-file coverage.lcov \
  --function "calculate_score" \
  --file src/scoring.rs
```

**Source**: `explain-coverage` command in `src/commands/explain_coverage/mod.rs`

**Example output**:
```
Coverage Detection Explanation
==============================

Function: process_file
File: src/processor.rs

Matched: suffix_match
Coverage: 87.5%
```

See [Context Provider Issues](context-providers.md) for detailed coverage troubleshooting.

## Too Many Low-Priority Warnings

**Problem**: Results overwhelmed with low-priority items

**Quick Solutions**:

```bash
# Increase minimum score threshold
debtmap analyze . --min-score 5.0

# Use stricter threshold preset
debtmap analyze . --threshold-preset strict

# Filter by specific debt categories
debtmap analyze . --filter "complexity,debt"

# Limit output to top N items
debtmap analyze . --top 20

# Use summary mode for compact output
debtmap analyze . --summary
```

**Source**: Filtering flags in `src/cli/args.rs:147-159`

**Min-score filter behavior** (spec 193, 205):
- T1 Critical Architecture and T2 Complex Untested items bypass the min-score filter
- T3 and T4 items are filtered by min-score threshold
- Default min-score is 3.0

## Call Graph Resolution Failures

**Problem**: Call graph shows incomplete or missing relationships

**Quick Solutions**:

```bash
# Enable debug output to see graph construction
debtmap analyze . --debug-call-graph -vv

# Validate the call graph consistency
debtmap analyze . --validate-call-graph

# Include external dependencies if relevant
debtmap analyze . --show-external-calls --show-std-lib-calls

# Trace specific functions to see their relationships
debtmap analyze . --trace-function "my_function" -vv

# Show only statistics, not the full graph
debtmap analyze . --call-graph-stats
```

**Source**: Call graph debug flags in `src/cli/args.rs:332-350`

See [Advanced Analysis Issues](advanced-analysis.md) for detailed call graph debugging.

## God Object False Positives

**Problem**: God object detection flagging legitimate large files

**Quick Solutions**:

```bash
# Disable god object detection entirely
debtmap analyze . --no-god-object

# See god object analysis with responsibility metrics
debtmap analyze . -vv

# Check specific file for god object patterns
debtmap analyze path/to/large/file.rs -vv
```

**Source**: God object flag in `src/cli/args.rs:242-244`

**When to disable**:
- Framework files with intentionally large aggregator classes
- Generated code files
- Files that are legitimately large due to single responsibility

See [Advanced Analysis Issues](advanced-analysis.md#god-object-detection) for god object configuration options.

## JSON Format Parsing Errors

**Problem**: JSON output parsing errors or unexpected structure

**Quick Solutions**:

```bash
# JSON output always uses the unified schema
debtmap analyze . --format json --output results.json

# Validate JSON output with jq
debtmap analyze . --format json | jq .

# Write to file for easier inspection
debtmap analyze . --format json --output results.json
```

**Source**: Output format options from CLI help

**Understanding the format**:

JSON output uses the unified schema. Each item includes a `type` discriminator such as `Function` or `File`, with common top-level `metadata`, `summary`, and `items` fields.

See [Output and Command Issues](output-issues.md) for detailed JSON format documentation.

## Context Provider Errors

**Problem**: Errors with critical_path, dependency, or git_history providers

**Quick Solutions**:

```bash
# Disable all context providers
debtmap analyze . --no-context-aware

# Disable specific problematic provider
debtmap analyze . --context --disable-context git_history

# Enable specific providers only
debtmap analyze . --context --context-providers critical_path,dependency

# Check context provider details
debtmap analyze . --context -vvv
```

**Source**: Context provider flags in `src/cli/args.rs:119-125`

**Provider-specific issues**:
- **git_history**: Requires git repository, fails outside git repos
- **dependency**: Complex import structures may not resolve
- **critical_path**: Requires valid call graph

See [Context Provider Issues](context-providers.md) for detailed troubleshooting.

## Quick Reference Table

| Problem | Quick Fix |
|---------|-----------|
| Slow analysis | `--no-multi-pass` or `--semantic-off` |
| Parse errors | `--semantic-off` or exclude files |
| No output | `--min-priority low` or `-v` |
| Coverage issues | `explain-coverage` command |
| Too many warnings | `--min-score 5.0` or `--top 20` |
| Call graph issues | `--debug-call-graph -vv` |
| God object false positives | `--no-god-object` |
| JSON parsing | `--format json | jq .` |
| Context errors | `--no-context-aware` |

## When Quick Fixes Don't Work

If these quick fixes don't resolve your issue, consult:

- [Debug Mode](debug-mode.md) - Detailed debugging options
- [Context Provider Issues](context-providers.md) - Provider-specific troubleshooting
- [Advanced Analysis Issues](advanced-analysis.md) - Complex analysis problems
- [Error Messages Reference](error-messages.md) - Error message explanations
- [FAQ](faq.md) - Common questions and answers

For issues not covered in this documentation, consider:

1. Running with maximum verbosity: `debtmap analyze . -vvv 2>&1 | tee debug.log`
2. Checking the [GitHub issues](https://github.com/anthropics/debtmap/issues)
3. Filing a bug report with the debug output