Skip to content

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:

100FORGED80 – 99WORTHY50 – 79NEEDS WORK< 50UNWORTHY

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:

text
rate  = 32 / (7 + 1) = 4
score = 100 - min(100, 4 × 5) = 80 → WORTHY

The 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 ​

SeverityBase points
error8
warning3
info1

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:

LevelMeaningDeductionExample
E2Deterministic defectFull.only committed — structurally provable
E1Heuristic patternHalf (round down)regex-matched sleep() — strong signal, not proof
E0ObservationZero (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.

Trust level — how far a finding can climb
  1. L0observation onlystatic
  2. L1heuristic staticstatic
  3. L2deterministic staticstatic
  4. L3the finding's file executedneeds a real run
  5. L4the finding's test executedneeds a real run
  6. 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 ​

  1. 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".
  2. 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.
  3. Suite-invalidating override — a committed .only (or a -k filter) 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 ​

ScoreVerdict
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.

Released under the MIT License.