What is a repo health score?

A repo health score can be useful, but only when it helps you decide what to review next.

If a score hides its logic, it becomes decoration. If it explains itself clearly, it becomes an operational tool.

If you are asking what a Repo Watch health score actually means in practice, the useful version is one that shows how signals were gathered and what evidence was captured.

How Repo Watch scans and captures repo health

In Repo Watch results, you can move from score to evidence quickly: section explainers describe inputs, top findings show impact, and recommendations show what to do next.

What a useful score should measure

Codebase health is not one number. It is the combination of several dimensions that can drift independently.

Dependency health

• dependency count parsed from lockfiles across all major ecosystems
• dependency volume relative to source file count as a footprint signal
• heavy footprint ratios flagged as a Code Quality deduction

Repo Watch does not currently scan for version staleness or known vulnerabilities — only the count and footprint ratio.

$ cat package-lock.json | jq '.packages | length'
487

$ cat package.json | jq '.dependencies | length'
34

# 487 resolved packages for 34 declared dependencies

# in a project with 12 source files

Test confidence

• test file count relative to source file count (structural ratio only)
• ratio bands map directly to a section score (e.g. ratio below 0.03 scores 15; above 0.40 scores 90)
• no test execution, no coverage file parsing, no assertion quality inspection

src/
auth/         4 files
api/          9 files
utils/        6 files
models/       5 files

tests/
auth.test.ts 1 file

# 24 source files, 1 test file

# test-to-source ratio: 0.04

Code quality structure

The Code Quality section is a structural hygiene score, not a style analysis. It measures:

• README present/missing
• lockfile present/missing
• CI config detected (e.g. .github/workflows)
• test-to-source ratio (reward ≥ 0.20, penalise < 0.05)
• source footprint size (penalises very small repos under 5 source files)
• dependency footprint relative to source files

Things like naming consistency, comment style, or abstraction quality are not measured here — those remain manual review signals.

Security hygiene

• secret exposure indicators
• risky patterns in static checks
• depth of validation posture

# Semgrep finding (severity: HIGH)
rule: tainted-sql-string
file: src/api/search.ts
line: 42
message: >
User-controlled input flows into a SQL string without parameterization.
This may allow SQL injection.
guidance: Use parameterized queries or a query builder. Never interpolate
request values directly into SQL strings.

AI-risk indicators

• structure-based signals associated with generated code batches
• AI tooling config files detected in the repository
• thin test coverage co-occurring with high structural fragmentation

Each signal chip on the card maps directly to a contribution row in the score explainer. The computed total is shown so you can verify the arithmetic rather than trusting an opaque label.

Note that AI-Risk Indicators carry a 10% weight in the overall score — it is intentionally a supporting signal, not the dominant factor.

Where this helps most

A health score is useful when review time is constrained:

• hiring take-home assessments
• open-source adoption decisions
• acquisition due diligence
• inherited internal systems

It gives reviewers a better starting point than random file sampling.

What it cannot replace

A static score does not replace architecture review, production readiness checks, incident posture, or team ownership maturity.

Treat it as triage. Use it to focus attention. Then apply engineering judgment.

A practical standard

If you are evaluating tooling, look for three things:

1. Explainers for every section and major deduction
2. Evidence that maps findings to concrete files or artifacts
3. Fast turnaround so teams actually use it in workflow

That combination turns a score from marketing into process support.