What Is an Excavate Score? A Practical Code Health Score for Technical Debt

What Is an Excavate Score?

Everyone knows which files are risky. Nobody can prove it.

That is the quiet problem inside most engineering teams. A senior engineer says, "Do not touch that file before release." A product leader asks why a sprint slipped. A CTO knows there is technical debt, but the discussion turns into stories, opinions, and memory.

The Excavate Score turns that invisible risk into a number.

An Excavate Score is a 0 to 100 code health score that ranks files by maintainability and delivery readiness. Higher is healthier. Lower means a file is more likely to slow delivery, hide defects, concentrate knowledge, or make routine changes fragile.

Think of it like a CIBIL score for your codebase. Or like a marksheet for software maintainability. One score does not explain the whole system, but it gives everyone the same starting point.

For leaders, that means fewer vague debates. For developers, it is a map of what to fix first.

What Does the Excavate Score Measure?

The Excavate Score measures delivery risk through churn, complexity, coverage gaps, knowledge concentration, documentation debt, dependency risk, and temporal coupling context.

Those signals answer one question: which files are most likely to make future work slower, riskier, or more expensive?

Churn: Constantly Changing Files Are Unstable by Definition

Churn measures how often a file changes in git history.

High churn is not automatically bad. The risk appears when that same file is hard to test, hard to understand, or owned by one person.

This matters because frequently changed files sit directly in the path of shipping. If they are brittle, every sprint pays a tax: merge conflicts, slower reviews, surprise regressions, and nervous release planning.

Excavate uses churn to separate quiet old debt from active delivery risk.

Complexity: Hard to Read Means Hard to Change Safely

Complexity measures how much reasoning a file demands before a safe change.

It catches tangled branches, nested conditions, long functions, and code paths that force too much context into one person's head.

Complexity matters because it makes estimates unreliable. A task looks small, then expands once the file reveals hidden paths. Reviewers slow down and senior developers become the bottleneck.

Coverage Gaps: Untested Code Hides Risk

Coverage measures how much automatic confidence the team has when a file changes.

Low coverage does not mean the code is broken. It means the team has less feedback when behavior changes.

A stable file with low coverage may be acceptable for a while. A frequently changed file with low coverage is a trap. Developers rely on manual testing, memory, or luck.

Excavate penalizes coverage gaps because tests make risky code changeable again.

Knowledge Concentration: One Owner on a Critical File Is a Cliff

Knowledge concentration measures whether a file depends too much on one person.

Some files are technically fine but socially risky. One engineer understands the edge cases, reviews every change, and becomes the unofficial maintainer.

This matters because software delivery risk is not only in the code. A critical file with one owner creates a knowledge cliff. Work waits for that person. Onboarding slows because context lives outside the repository.

The fix is not always a rewrite. Sometimes it is pairing, tests, documentation, or rotating ownership.

Documentation Debt: Missing Context Makes Every Change Slower

Documentation debt measures whether a file explains enough intent for future developers.

Good code should be readable, but some areas still need context: why a workaround exists, or why a risky path cannot be simplified yet.

Excavate also watches for TODO, FIXME, and HACK markers. They become debt when they accumulate without action.

This matters because missing context causes repeated rediscovery. Every new change forces someone to reconstruct the same history.

Temporal Coupling: Files That Always Change Together Are Telling You Something

Temporal coupling finds files that repeatedly change together even when the code does not clearly connect them.

Git history can reveal hidden architecture. Maybe two modules represent the same business concept. Maybe a UI component and API contract evolve together but live far apart.

This matters because hidden coupling creates surprise work. A developer changes one file, then discovers three other files must change too.

Excavate surfaces temporal coupling so teams can see where the repository behaves as one connected system.

Dependencies: Stale Packages and CVEs Sit in Your Delivery Path

Dependency risk measures problems from the dependency tree and module graph.

That includes stale packages, known vulnerabilities, circular dependencies, and internal edges that are hard to upgrade.

This matters because dependency debt compounds. A package falls one major version behind, then two. A vulnerability needs a patch, but the patch requires a framework upgrade.

How Is the Excavate Score Calculated?

Excavate calculates each file score from weighted signals and clamps the result between 0 and 100.

Signal	Weight	What It Penalizes
Churn	25%	Files that change frequently and create repeated delivery risk
Coverage	25%	Files with weak or missing test confidence
Complexity	20%	Hard-to-read logic, branching, and high reasoning cost
Knowledge	15%	Ownership concentration and bus-factor risk
Documentation	10%	Missing context, TODOs, FIXMEs, and HACKs
Dependencies	5%	Circular dependencies, stale packages, CVEs, and dependency risk

The default formula is:

score =
  churn * 0.25 +
  coverage * 0.25 +
  complexity * 0.20 +
  knowledge * 0.15 +
  docs * 0.10 +
  deps * 0.05

If a file scores low, the useful question is: which signal is dragging this down, and what is the smallest fix?

What Do the Score Levels Mean?

Level	Score Range	Meaning
Clear	70-100	Low-friction code that is easier to change
Surface	40-69	Manageable debt that should not be ignored
Deep	20-39	Serious accumulated debt that deserves planning
Bedrock	0-19	High-risk files nobody wants to touch

Clear files are healthiest and easiest to change. Surface files are early warnings. Deep files deserve planning. Bedrock files are the ones teams already whisper about.

How Does an Excavate Score Change Over Time?

An Excavate Score is more useful as a trend than as a one-time grade.

A score improves when the team adds tests, simplifies logic, spreads ownership, removes stale TODOs, or upgrades risky dependencies. A score degrades when a file keeps changing without tests or absorbs too many responsibilities.

Track it weekly. The goal is not perfection. The goal is to know whether the codebase is becoming easier or harder to change.

How Can Developers Run Excavate?

Run Excavate on a JavaScript or TypeScript repository in about 30 seconds:

npx excavate

Generate the visual HTML report:

npx excavate --report

Show the lowest-score files first:

npx excavate --top 10

Use it in CI:

npx excavate --fail-above 70 --json

Start with the lowest-score files. Pick one file tied to current work, then improve the weakest signal first.

What Should Leaders Do With the Score?

Use the Excavate Score to turn technical debt into a ranked fix list.

If a critical file scores low because of coverage, fund tests before rewriting. If it scores low because of complexity, schedule simplification around the next feature touching that area. If it scores low because of knowledge concentration, spread ownership before it becomes a staffing problem.

Use the score in sprint planning. Put one or two high-impact debt items next to feature work instead of creating a vague "tech debt sprint" that never happens.

Use it to justify refactoring budget. Leaders need evidence that a small investment will reduce delivery risk in files the team actually changes.

What Is an Excavate Score? A Practical Code Health Score for Technical Debt