How the score works
Mjölnir reports one number — WORTHINESS, 0–100 — and it is fully transparent: a deduction table, a normalization step, and three ceilings. No model, no weights you can't see.
The formula
rate = totalDeductions / (testDeclarations + 1)
score = 100 − min(100, rate × 5)The denominator is the number of test declarations (it(, test(, def test_, @Test, [Test]) — the count of behaviors that claim to be verified. It is not the file count: adding empty spec files used to raise the score without adding any verification. Inflating a declaration count requires writing real tests.
The + 1 is a Laplace smoothing constant so a tiny suite with one finding doesn't collapse to zero.
The demo repo's own arithmetic, step by step:
Where a score lands:
A repo with no tests scores nothing — null, never a fake 100. Full derivation in docs/SCORING.md.
Worked example
In the demo scan, 32 deduction points across 7 test declarations produce:
rate = 32 / (7 + 1) = 4
score = 100 - min(100, 4 × 5) = 80 → WORTHYThe three ceilings below can further limit the result. Adding empty spec files does not raise the score because normalization uses test declarations.
Per-finding deductions
| Severity | Base points |
|---|---|
| error | 8 |
| warning | 3 |
| info | 1 |
These three numbers are public API — changing them takes a changelog entry and a version bump.
Evidence weighting
Every finding carries an evidence level that scales its deduction, so a heuristic match costs less than a structural proof:
| Level | Meaning | Deduction | Example |
|---|---|---|---|
| E2 | Deterministic defect | Full | .only committed — structurally provable |
| E1 | Heuristic pattern | Half (round down) | regex-matched sleep() — strong signal, not proof |
| E0 | Observation | Zero (info only) | reported, never gates or deducts |
Most rules are E1. Evidence level is what "trust" means here in practice: E2 findings are structural proof; E1 findings are correctly-positioned warnings, not formal proofs.
How far a finding can be trusted
Evidence level says how sure the analysis is. Trust level says something stricter: whether anything was ever observed to run.
- L0observation onlystatic
- L1heuristic staticstatic
- L2deterministic staticstatic
- L3the finding's file executedneeds a real run
- L4the finding's test executedneeds a real run
- L5the run verdict corroboratesneeds a real run
L3 and above require runtime evidence. Static analysis can never claim them, however certain it is — that is what the gap in the ladder is.
The two are related but not the same. A finding can be E2 — deterministic, structurally provable — and still sit at L2, because proving a defect exists in the source is not the same as watching it happen. Nothing Mjölnir derives from source text alone can climb past L2; L3 and above need the artifacts of a run that already finished.
Three ceilings, applied in order
- Honesty guard — if any deduction was charged at all, the score is capped at 99. A perfect 100 is reserved for zero deductions, so a rounded-up finding can never read as "nothing found".
- Error-severity floor — if any error-level finding with a non-zero deduction exists, the score is capped at 95. Ten errors in a 10,000-declaration repo would otherwise round to 100. You cannot outgrow a categorical defect by adding tests.
- Suite-invalidating override — a committed
.only(or a-kfilter) makes the runner skip everything else; the green result is not evidence about the rest of the suite. Rules that detect this cap the score at 49 — straight into UNWORTHY — regardless of suite size.
Verdict bands
| Score | Verdict |
|---|---|
| 100 | ⚡ FORGED |
| 80 – 99 | ✓ WORTHY |
| 50 – 79 | ⚠ NEEDS WORK |
| < 50 | ✖ UNWORTHY |
An empty repo scores null, never a fake 100. FORGED is the premium 100-state — zero deductions, zero findings, the suite is clean.
Transparency
The terminal prints the numerator and denominator next to the gauge. JSON output carries rawDeductions, testDeclarationCount and testFileCount so any consumer can recompute the score independently.
Calibration status
NORMALIZATION_K = 5 produces the correct verdict on every known data point but is not yet fitted against the OSS corpus — that needs the corpus audit to persist per-repo declaration counts first. When the fit lands, K changes and the CHANGELOG records it as a behavioral break. The full calibration history and the reasoning behind every constant is in docs/SCORING.md.