Every repository in the public record carries a health index: a single integer between 1 and 100 that summarizes publicly visible engineering, maintenance, security, and governance practice. The index exists so that a library can be compared with its alternatives at a glance — but it is the top of a fully transparent hierarchy, never a black box.
The three-level hierarchy
The index rolls up through three documented levels:
- Components — individual observable facts (a license file exists, the latest release shipped 40 days ago, the bus factor is 3). Each component carries a fixed weight inside its metric.
- Metrics — weighted sums of components, each an integer in 1–100. Examples: development activity, maintainer resilience, security posture.
- Categories — weighted means of their metrics, also in 1–100. The six weighted categories are Vitality, Community & Adoption, Sustainability & Governance, Engineering Quality, Security, and — at a deliberately small weight — AI Readiness.
The overall health index starts as the weighted mean of the available categories:
| Category | Weight in overall |
|---|---|
| Sustainability & Governance | 23% |
| Vitality | 21% |
| Engineering Quality | 19% |
| Community & Adoption | 17% |
| Security | 16% |
| AI Readiness | 4% |
A metric's effective weight in the overall index is category weight × within-category weight. Every report shows this figure on each metric card, and every published value maps to one of seven rating bands.
Calibration to the public record
The weighted mean is then calibrated onto the published index scale through a fixed monotone curve anchored to the empirical distribution of the public record. Calibration is what gives the bands their percentile meaning — Exceptional is genuinely the record's top tier — and it lets the index use the whole 1–100 range instead of crowding half the record into twenty points of it. The curve saturates at the top: a raw weighted mean of 91 or above publishes as 100, which is also why a repository with no AI Readiness signals (4% of the raw weight) can still reach 100/100. The raw weighted mean stays visible in every report's overall.inputs.weighted_overall_raw, so the arithmetic remains fully auditable. Category and metric values are published uncalibrated — the curve describes, and is fitted to, the overall index only.
Red flags cap the index
Four policies stand outside the weighted mean. None of them rewards a clean result — a repository with no finding simply keeps its calibrated index — but a confirmed finding multiplies the published value and, in the gravest cases, holds it under a stated ceiling:
| Policy | Applies to | Ceiling |
|---|---|---|
| Malicious dependencies | security posture and the overall index | 19 — top of Critical |
| Abandonment | the overall index | 34 when likely, 19 when declared |
| High-Risk Jurisdiction Exposure | security posture and the overall index | 34 — top of At Risk |
| Growth authenticity | the stars and forks components of popularity | none |
Since methodology v1.13.0 the policies do not compound. The strictest one that fires governs alone and the others are reported without moving the value again: a multiplier states how serious a finding is, and a value multiplied twice is a number no policy chose and none can explain. Repositories whose evidence cannot answer a policy's question read unverified and are never penalized for the gap.
Missing data is never a zero
If a component's underlying data is unavailable — a registry publishes no download figures, the contributor list cannot be sampled — the component is excluded and the remaining weights renormalized. The same rule applies one level up: a metric with no data becomes null and its category redistributes the weight; a category with no scorable metric is dropped from the overall.
This rule is central to fairness. A project is measured only on what can actually be observed, and absence of evidence is reported as absence — the metric's note field records every renormalization, so a reader always knows what was and was not measured.
Reading a report
- Read the profile, not just the number. A 74 built on balanced categories is a different proposition from a 74 masking a Security value of 25. The report's radar chart makes spike-and-crater profiles visible immediately.
- Check the bands. Values map to seven standardized bands from
exceptionaltocritical; band thresholds are part of the versioned methodology. - Recompute anything. Every metric echoes its inputs and per-component points in the report, so any published value can be verified by hand from the
datasection of the JSON report. - Read candidates against each other. An index is only meaningful next to the alternatives actually under consideration. The comparison view puts up to six records on one set of axes — category profile, growth trajectory, and every underlying figure — so the spread between them is visible rather than inferred.
Versioning
Formulas, weights, and band thresholds are versioned as a whole. Any change bumps the metrics version recorded in every report, and the full history is public — see methodology versions. Parts of the methodology can be switched off per scan; the report then documents exactly what was disabled — see scan configuration.
Related: rating bands · certification levels · software classification · signals, not warranties · methodology versions