# The health index

> How inspect.software computes the 1–100 open-source health index — components, metrics, weighted categories, and the rules for missing data.


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](/compare) at a glance — but it
is the *top* of a fully transparent hierarchy, never a black box.

<div class="md-callout"><span class="md-callout-icon">◇</span><div><b>Signals, not warranties.</b> A high index reflects publicly visible good practice. It is not a code audit and not a security guarantee — see <a href="/wiki/signals-not-warranties">how to read the results</a>.</div></div>

## The three-level hierarchy

The index rolls up through three documented levels:

1. **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.
2. **Metrics** — weighted sums of components, each an integer in 1–100.
   Examples: [development activity](/wiki/development-activity),
   [maintainer resilience](/wiki/maintainer-resilience),
   [security posture](/wiki/security-posture).
3. **Categories** — weighted means of their metrics, also in 1–100. The five
   weighted categories are [Vitality](/wiki/vitality),
   [Community & Adoption](/wiki/community-adoption),
   [Sustainability & Governance](/wiki/sustainability-governance),
   [Engineering Quality](/wiki/engineering-quality), and
   [Security](/wiki/security). A sixth, [AI Readiness](/wiki/ai-readiness),
   is an independent badge with weight 0.

The **overall health index** is the weighted mean of the available categories:

| Category | Weight in overall |
| -------- | ----------------- |
| [Sustainability & Governance](/wiki/sustainability-governance) | 24% |
| [Vitality](/wiki/vitality) | 22% |
| [Engineering Quality](/wiki/engineering-quality) | 20% |
| [Community & Adoption](/wiki/community-adoption) | 18% |
| [Security](/wiki/security) | 16% |
| [AI Readiness](/wiki/ai-readiness) | 0% — independent badge |

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 five [rating bands](/wiki/scoring-bands).

## 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 five standardized bands from `excellent`
  to `critical`; 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 `data` section of the JSON report.
- **Read candidates against each other.** An index is only meaningful next to
  the alternatives actually under consideration. The
  [comparison view](/compare) 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](/wiki/methodology-versions). Parts of the
methodology can be switched off per scan; the report then documents exactly
what was disabled — see [scan configuration](/wiki/scan-configuration).