Section 6.1Source:
server/src/analytics/health/CalculateHealthIndex.tsHealth Index & Scoring Formula
A continuous, multi-metric structural scoring framework that distills 6 independent graph measurements into a unified 0–100 health index.
Source:
server/src/analytics/health/CalculateHealthIndex.tsThe Weighted Aggregation Formula
The Health Index ($H$) combines 6 normalized structural scores ($0 \dots 100$) using calibrated weights that sum to exactly $1.00$:
H = (0.28 · C) + (0.23 · Co) + (0.18 · Fo) + (0.14 · Fi) + (0.10 · D) + (0.07 · M)
| Metric | Symbol | What It Measures | Weight | Key Driver |
|---|---|---|---|---|
| Cycle Health | C | Circular file imports & mutual recursion | 28% | Constrains build order & introduces undefined runtime imports. |
| Coupling Health | Co | Average total structural degree (in + out) | 23% | Broadest measure of repository interconnectedness. |
| Fan-Out Health | Fo | RMS outgoing relationship concentration | 18% | Penalizes hotspot files/symbols with excessive outgoing coupling. |
| Fan-In Health | Fi | RMS incoming relationship concentration | 14% | Identifies fragile high-blast-radius hub symbols. |
| Dependency Health | D | External npm dependency density per file | 10% | External package exposure and supply-chain blast radius. |
| Module Health | M | Proportion of unresolved module entities | 7% | Measures external imports that CodeGraph failed to resolve to local files or declared dependencies (Node.js built-ins or unlisted imports). |
The 3-Phase Pipeline: Measure → Normalize → Aggregate
- Phase 1: Raw Measurement: Extracts raw graph quantities (for example,
RMS fan-out = 1.45,cycle count = 0). - Phase 2: Normalization: Converts unbounded raw values into a standardized 0–100 scale using continuous reciprocal decay:score = 100 / (1 + k · x)or bounded linear ratios:score = 100 · (1 - risk)
- Phase 3: Weighted Aggregation: Sums the weighted individual metric scores into the final unified repository index.
Score Interpretation Bands
| Score Range | Classification | Architectural Assessment |
|---|---|---|
| 90 – 100 | Very Healthy | Clean modular structure with minimal architectural risk and zero/few cycles. |
| 75 – 89 | Generally Healthy | Standard structural complexity typical of actively growing repositories. |
| 50 – 74 | Moderate Complexity | Noticeable coupling or hotspot outliers that warrant refactoring. |
| 25 – 49 | Elevated Risk | High circularity, heavy God-node concentration, or extreme fan-out. |
| 0 – 24 | Severe Degradation | Pervasive structural tangling across both file and symbol layers. |