Excavate
Back to Blog

Excavate CLI for Engineering Teams: Technical Debt Analysis That Drives Action

A practical breakdown of Excavate’s scoring model, HTML reports, CI gating, and workflow for improving code quality and architecture over time.

•5 min read
Technical DebtCode ArchitectureTypeScriptJavaScriptCode QualityDeveloper Tools

Why Technical Debt Feels Invisible Until It Hurts

Every codebase has files people avoid touching.

You open one for a small bug fix, then lose hours tracing side effects across unrelated modules. Shipping slows down, review cycles get noisy, and simple changes become risky.

That is technical debt in motion, not just untidy code style.

Many tools catch syntax and formatting issues. Fewer tools answer the higher-value question:

Where is structural risk actually concentrated in this repository?

Excavate is designed for that exact problem.

What Excavate Does

Excavate is a zero-config CLI that scans JavaScript and TypeScript repositories and assigns each file a debt score from 0 to 100.

It combines six weighted signals:

  • churn (25%): how unstable a file is over time
  • coverage (25%): untested code risk
  • complexity (20%): cyclomatic complexity
  • knowledge (15%): ownership concentration and bus-factor pressure
  • docs (10%): comment density plus TODO/FIXME/HACK indicators
  • deps (5%): circular dependencies, stale packages, CVEs

It then maps files into four debt levels:

  • bedrock (70–100): high-risk legacy layers
  • deep (40–70): long-accumulated debt
  • surface (20–40): manageable recent buildup
  • clear (0–20): low-friction code

Quick run:

npx excavate

Why This Matters for Code, Architecture, and Design

Debt cleanup fails when teams guess where to start.

Excavate gives a ranked backlog in seconds, which improves three areas:

  1. Code quality: prioritize files with high churn and low test coverage.
  2. Architecture: detect coupling and brittle hotspots before they spread.
  3. System design: sequence refactors with measurable impact instead of gut feeling.

This turns debt discussions from opinions into trackable engineering decisions.

Key Features Worth Using

Excavate’s core value is not just scoring. It also gives context for action:

  • health grade (A–F) with trend direction
  • debt archetypes (time bomb, load-bearing wall, black box, and others)
  • temporal coupling (files that often change together)
  • orphan file detection and dead export hints
  • HTML report with per-file metadata and prompt-ready refactor context
npx excavate --report
open excavate-report/index.html

The HTML report includes:

  • D3 treemap (size by LOC, color by debt level)
  • sortable file table with archetype, coupling, ownership metadata
  • trend chart after multiple scans
  • per-file action drawer with signal explanations

Everything runs locally with no server setup.

How to Use It in a Real Team Workflow

Use this simple loop:

  1. Scan the repo and capture baseline debt.
  2. Pick top bedrock files for sprint-level refactoring.
  3. Add tests where coverage is the main risk driver.
  4. Re-scan and compare against previous snapshots.
  5. Add CI guardrails to prevent debt spikes.

For CI gating:

npx excavate --fail-above 70 --json

If average score crosses your threshold, CI exits with code 1.

Rollout Plan for Teams

If you want this to stick beyond one demo scan, run a phased rollout:

  1. Week 1: Baseline only. No gates. Share the top 15 files and review risk drivers.
  2. Week 2: Pick 3 files with high score and high business impact. Refactor with tests.
  3. Week 3: Enable dashboard review in weekly engineering sync.
  4. Week 4: Add --fail-above at a conservative threshold and tighten gradually.

This avoids noisy policy changes while building confidence in the scoring model.

Interpreting Scores Without Overreacting

A high score is a prioritization signal, not a verdict on developer quality.

Use this quick interpretation model:

  • High churn + low coverage: stabilize with tests first, then refactor.
  • High complexity + high coupling: split modules and reduce hidden side effects.
  • High knowledge risk: rotate ownership and document fragile flows.
  • High deps risk: isolate risky integration points before broad rewrites.

Treat the score as a triage entry point, then confirm with local code context.

Common Mistakes During Debt Cleanup

Teams often lose momentum for predictable reasons:

  1. Refactoring too many files at once.
  2. Optimizing low-risk files because they look cleaner to fix.
  3. Ignoring tests, then shipping regressions after structural edits.
  4. Skipping re-scan, so improvements are not measured.

A smaller loop with visible deltas beats a massive one-time cleanup sprint.

Excavate and LLMs: Better Together

LLMs are strong at rewriting code once the target file is known.

Excavate is strong at choosing the target file with repository-wide evidence.

Best workflow:

  1. Use Excavate for ranking and risk detection.
  2. Use an LLM for focused refactor execution.
  3. Re-run Excavate to validate debt reduction.

Quick Start

# Scan current project
npx excavate
 
# Show top risk files
npx excavate --top 10
 
# Restrict git window to last 30 days
npx excavate --since 30
 
# Machine-readable output
npx excavate --json

Requirements:

  • Node.js >= 18
  • Git repository

FAQ

Does Excavate require configuration?

No. It works out of the box and can be tuned later using .excavaterc.

Can it work in CI/CD?

Yes. Use --fail-above to enforce a debt threshold in pull request pipelines.

Is code sent to external servers?

Core analysis runs locally. Dependency vulnerability checks rely on npm audit data.

Final Verdict

Excavate is a practical technical debt analysis tool for teams that want fast visibility into code health and architecture risk.

If your repository feels harder to change every sprint, this gives you a concrete starting point in one command.