Tech Debt Scanner#

Find, categorize, and prioritize technical debt in any codebase. Produces an actionable report with effort estimates, risk scores, and remediation suggestions — not just a list of problems.

Use when: "scan for tech debt", "find code smells", "audit code quality", "what should we refactor first", "technical debt report", or before sprint planning to identify cleanup candidates.

Commands#

1. scan — Full Tech Debt Audit#

Run all detectors and produce a prioritized report.

Step 1: Detect TODO/FIXME/HACK Comments

bash

# Find all debt markers with context
rg -n "TODO|FIXME|HACK|XXX|TEMP|WORKAROUND|DEPRECATED|NOCOMMIT" \
  --type-not binary \
  -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!.git' \
  --stats 2>&1

Categorize each hit:

• TODO: Feature incomplete — low risk, track in backlog
• FIXME: Known bug — medium risk, prioritize
• HACK/WORKAROUND: Fragile code — high risk, refactor soon
• DEPRECATED: API sunset — high risk if external dependency
• NOCOMMIT: Should never have been merged — critical

Count totals per category. Flag any older than 6 months (check git blame):

bash

# Age of oldest TODO/FIXME (sample first 10)
rg -l "TODO|FIXME|HACK" -g '!node_modules' -g '!vendor' | head -10 | while read f; do
  echo "=== $f ==="
  git log -1 --format="%ai %an" -- "$f" 2>/dev/null
done

Step 2: Detect Complexity Hotspots

bash

# Largest source files (often the most complex)
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \
  -not -path '*/node_modules/*' -not -path '*/vendor/*' -not -path '*/dist/*' -not -path '*/.git/*' \
  -exec wc -l {} + 2>/dev/null | sort -rn | head -20

# Functions with high nesting (proxy for cyclomatic complexity)
rg -n "^\s{12,}(if|for|while|switch|case|catch)" \
  --type-not binary \
  -g '!node_modules' -g '!vendor' -g '!dist' \
  --stats 2>&1 | tail -5

Flag files >500 lines as candidates for splitting. Flag functions with >4 levels of nesting as complexity hotspots.

Step 3: Detect Outdated Patterns

bash

# JavaScript/TypeScript: var usage (should be let/const)
rg -c "^\s*var\s+" -g '*.{js,ts,jsx,tsx}' -g '!node_modules' 2>/dev/null | sort -t: -k2 -rn | head -10

# JavaScript: callback hell (nested callbacks)
rg -c "function\s*\(" -g '*.{js,ts}' -g '!node_modules' 2>/dev/null | sort -t: -k2 -rn | head -10

# Python: old-style string formatting
rg -c '% ["\x27(]' -g '*.py' -g '!vendor' 2>/dev/null | sort -t: -k2 -rn | head -10

# Python: bare except
rg -n "except:" -g '*.py' -g '!vendor' 2>/dev/null

# Deprecated React patterns
rg -n "componentWillMount|componentWillReceiveProps|componentWillUpdate|React\.createClass|mixins\s*:" \
  -g '*.{jsx,tsx,js,ts}' -g '!node_modules' 2>/dev/null

Step 4: Detect Missing or Weak Tests

bash

# Test file ratio
SRC_COUNT=$(find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" \) \
  -not -path '*/node_modules/*' -not -path '*/vendor/*' -not -path '*/test*' -not -path '*/__test*' \
  -not -path '*/*.test.*' -not -path '*/*.spec.*' -not -path '*/dist/*' | wc -l)
TEST_COUNT=$(find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -name "*_test.*" \) \
  -not -path '*/node_modules/*' | wc -l)
echo "Source files: $SRC_COUNT, Test files: $TEST_COUNT, Ratio: $(echo "scale=1; $TEST_COUNT * 100 / ($SRC_COUNT + 1)" | bc)%"

# Source files with no corresponding test
find . -type f -name "*.ts" -not -name "*.test.*" -not -name "*.spec.*" \
  -not -path '*/node_modules/*' -not -path '*/dist/*' | while read f; do
  BASE=$(basename "$f" .ts)
  if ! find . -type f \( -name "${BASE}.test.ts" -o -name "${BASE}.spec.ts" -o -name "test_${BASE}*" \) \
    -not -path '*/node_modules/*' 2>/dev/null | grep -q .; then
    echo "NO TEST: $f"
  fi
done | head -20

Step 5: Detect Dependency Issues

bash

# Node.js: outdated dependencies
npm outdated 2>/dev/null || true
# Check for deprecated packages in package.json
cat package.json 2>/dev/null | python3 -c "
import json, sys
try:
    d = json.load(sys.stdin)
    deps = {**d.get('dependencies',{}), **d.get('devDependencies',{})}
    deprecated = ['request', 'node-uuid', 'nomnom', 'optimist', 'jade', 'istanbul', 'coffee-script', 'bower', 'grunt']
    for pkg in deprecated:
        if pkg in deps:
            print(f'DEPRECATED: {pkg}@{deps[pkg]}')
except: pass
"

# Python: check requirements age
cat requirements.txt 2>/dev/null | head -30
pip list --outdated 2>/dev/null | head -20

# Go: check go.sum for old versions
cat go.sum 2>/dev/null | wc -l

Step 6: Detect Code Duplication Indicators

bash

# Find suspiciously similar file names (copy-paste indicators)
find . -type f -name "*.ts" -not -path '*/node_modules/*' -not -path '*/dist/*' | \
  xargs -I{} basename {} | sort | uniq -d

# Find repeated import patterns (same large import block = shared code candidate)
rg -c "^import" -g '*.{ts,js,tsx,jsx}' -g '!node_modules' 2>/dev/null | \
  sort -t: -k2 -rn | head -10

# Find files with very similar line counts (heuristic for copies)
find . -type f \( -name "*.ts" -o -name "*.js" \) \
  -not -path '*/node_modules/*' -not -path '*/dist/*' \
  -exec wc -l {} + 2>/dev/null | sort -n | awk '{print $1}' | uniq -d | head -5

Step 7: Generate Report

Analyze all findings with AI reasoning. For each debt item, assess:

• Risk: How likely is this to cause bugs, outages, or slow development?
• Effort: T-shirt size (XS/S/M/L/XL) to fix
• Impact: What improves when fixed? (velocity, reliability, onboarding, security)

Produce a prioritized report:

markdown

# Tech Debt Report — [project name]
Generated: [date]

## Summary
- Total debt items: N
- Critical (fix now): N
- High (next sprint): N
- Medium (backlog): N
- Low (opportunistic): N

## Critical Items
1. [item] — Risk: critical | Effort: S | Impact: ...
   **Why:** [AI reasoning about the risk]
   **Fix:** [specific remediation steps]

## High Priority Items
...

## Metrics
- TODO/FIXME count: N (N are >6 months old)
- Test coverage ratio: N%
- Files >500 lines: N
- Deprecated dependencies: N
- Code duplication indicators: N hotspots

2. hotspots — Complexity Hotspot Map#

Run Steps 2 and 6 only. Output the top 10 files that are:

• Largest by line count
• Most frequently changed (git churn)
• Most complex (deep nesting)

bash

# Git churn — most frequently modified files in last 90 days
git log --since="90 days ago" --name-only --pretty=format: 2>/dev/null | \
  grep -v '^$' | sort | uniq -c | sort -rn | head -20

Cross-reference size × churn × nesting to find the "burning" hotspots — large, complex files that change often are the highest-ROI refactoring targets.

3. todos — TODO/FIXME Audit#

Run Step 1 only. Group by file, show git blame age for each, flag ancient ones.

Output format:

text

[CRITICAL] path/to/file.ts:42 — HACK: workaround for API bug (author, 2024-03-15)
[MEDIUM]   path/to/file.ts:87 — TODO: add validation (author, 2025-11-02)
[LOW]      path/to/other.py:12 — TODO: optimize later (author, 2026-04-01)

4. deps — Dependency Health#

Run Step 5 only. Show:

• Outdated packages with how far behind they are (major/minor/patch)
• Known deprecated packages
• Packages with known vulnerabilities (npm audit / pip-audit if available)

5. tests — Test Coverage Gaps#

Run Step 4 only. List source files without corresponding tests, sorted by:

1. Size (larger untested files = higher risk)
2. Git churn (frequently changed untested files = highest risk)

Output Formats#

• text (default): Human-readable report with sections and bullet points
• json: Machine-readable for CI/CD integration, structured as {summary, items: [{category, severity, file, line, message, effort, fix}]}
• markdown: Formatted report suitable for PR comments or wiki pages

CI Integration#

Exit codes:

• 0: No critical or high debt items
• 1: Critical items found (fail the build)
• 2: High items exceed threshold

Use with --max-critical 0 --max-high 10 to set thresholds.

Notes#

• Adapts detectors to the project's language (auto-detected from file extensions and config files)
• Git history required for churn and age analysis — works without git but reports are less useful
• Does not execute code or install dependencies — static analysis only
• Large monorepos: pass a subdirectory to scope the scan