Coderot

Find your most dangerous technical debt — before it finds you.

coderot analyzes TypeScript and JavaScript codebases and ranks files by a weighted impact score that combines git churn history, static complexity, dependency centrality, and detected code issues. The result is a prioritized refactor roadmap: the files most likely to cause production incidents and slow your team down, sorted by risk.

Install

# No install — one-off scan
npx coderot-cli

# Global
npm install -g coderot-cli

Usage

coderot-cli [path] [options]
coderot-cli analyze [path] [options]

path defaults to the current directory. Both forms are equivalent — analyze is the default command.

Options

| Option | Default | Description | |---|---|---| | -f, --format <format> | table | Output format: table, json, or summary | | --ci | false | CI mode: suppress banner, exit 1 on CRITICAL issues | | --max-score <score> | — | Only show files with impact score ≥ this value | | --ignore <patterns...> | — | Additional glob patterns to exclude | | --top <n> | — | Show only the top N files | | --include-healthy | false | Include files with no detected issues | | -v, --version | | Print version |

Default ignores: node_modules/, dist/, *.d.ts, *.test.*, *.spec.*

Example Output

   ██████╗ ██████╗ ██████╗ ███████╗██████╗  ██████╗ ████████╗
   ...

   Find your most dangerous technical debt — before it finds you.

  coderot — Refactor Roadmap

┌──────────────────────────────┬───────┬──────┬────────────┬──────────┬────────────┬──────────────┬─────────┐
│ File                         │ Score │ LOC  │ Complexity │ Churn/wk │ Dependents │ Issues       │ Hotspot │
├──────────────────────────────┼───────┼──────┼────────────┼──────────┼────────────┼──────────────┼─────────┤
│ src/core/transformer.ts      │  78   │  842 │     47     │   2.30   │     12     │ 3 (CRITICAL) │  YES    │
│ src/utils/parser.ts          │  61   │  412 │     28     │   1.10   │      7     │ 2 (HIGH)     │  YES    │
│ src/api/handler.ts           │  44   │  234 │     15     │   0.50   │      4     │ 1 (MEDIUM)   │  no     │
└──────────────────────────────┴───────┴──────┴────────────┴──────────┴────────────┴──────────────┴─────────┘

  ─────────────────────────────────────────────
  Total files scanned:  47
  Files in roadmap:     3
  Critical issues:      1
  Git hotspots:         2
  Avg impact score:     61
  ─────────────────────────────────────────────

Impact Score (0–100)

Each file is scored across five factors:

| Factor | Weight | How it's measured | |---|---|---| | Dependents | 30% | Number of files that import this file | | Churn | 25% | Commits per week over the last 90 days | | Complexity | 20% | File-level cyclomatic complexity | | Issues | 15% | Severity-weighted count of detected issues | | Size | 10% | Lines of non-comment code |

Score interpretation: ≥ 70 critical risk (red), 40–69 moderate risk (yellow), < 40 low risk (green).

What It Detects

Static issues:

• Functions with cyclomatic complexity > 10 (HIGH) or > 20 (CRITICAL)
• Functions longer than 50 lines (MEDIUM) or 100 lines (HIGH)
• Nesting depth > 3 (MEDIUM) or > 5 (HIGH)
• Files over 500 LOC (HIGH) or 1000 LOC (CRITICAL)
• Files with > 15 imports (MEDIUM coupling warning)
• Parameters missing TypeScript type annotations (LOW)

Git signals:

• Commit frequency over last 90 days (churn rate)
• Hotspot detection (> 1 commit/week average)
• Author count per file

Dependency signals:

• Reverse dependency count (how many files import this one)
• Import graph mapping

CI Integration

Fail your pipeline if critical issues are present:

# .github/workflows/quality.yml
- name: Check for critical code rot
  run: npx coderot-cli --ci --format summary

# Pre-push hook — fail only on high-risk files
coderot-cli --ci --max-score 75

Exit codes:

• 0 — No CRITICAL issues in the roadmap
• 1 — At least one CRITICAL issue found (only in --ci mode)

JSON Output

coderot-cli --format json | jq '.roadmap[0]'

The JSON schema includes filePath, impactScore, issues[] (with severity, message, line, recipe), functions[], churnRate, dependents[], imports[], and more.

Security

coderot passed a full OWASP security audit and has been hardened accordingly:

• Runs 100% locally — no data ever leaves your machine
• Zero network calls — no telemetry, no analytics, no outbound connections
• 0 npm vulnerabilities — npm audit returns clean in all packages
• All CLI arguments are validated and sanitized before reaching any processing code
• File scanning guards against path traversal, binary files, and symlinks escaping the workspace
• The VS Code extension uses execFile (never exec) — shell injection is structurally impossible
• ignore-scripts=true in .npmrc — malicious postinstall scripts from dependencies cannot run

See SECURITY.md for the full security model and vulnerability reporting policy.

License

MIT © coderot