How the Health Score Is Actually Computed

Every ArchSetu report leads with one number: a health score from 0 to 100, and a letter grade. It's tempting to treat that as a black box - a vibe, or worse, something an AI model quietly decided. It isn't either. It's six measured ratios, each normalized to 0-100, combined with fixed weights that never change based on which repo you're looking at.

The six inputs

Here is the actual weighting, taken directly from the scoring function:

deadCodeRatio:      0.25   // confidently-dead functions / total functions
avgComplexity:      0.25   // average cyclomatic complexity across all functions
highComplexityRatio: 0.15  // fraction of functions at "critical" complexity (>20)
testFileRatio:       0.15  // test files / total files, capped at 100
duplicationRatio:    0.10  // estimated near-duplicate code blocks
oversizedFileRatio:  0.10  // files over 300 lines / total files

Each ratio is normalized into a 0-100 sub-score, multiplied by its weight, and summed. The result is rounded to a whole number and mapped to a letter: 90+ is A+, 80+ is A, 70+ is B, 60+ is C, 50+ is D, and anything below that is F. That mapping is fixed too - there's no curve, no "relative to similar repos" adjustment. A score of 82 means the same thing whether the repo is a weekend project or a payments system.

Why dead code and complexity carry the most weight

Dead code and complexity are weighted highest (0.25 each) because they're the two signals most directly tied to what actually makes a codebase hard to work in: code nobody calls anymore that still has to be read and reasoned about, and functions dense enough that a small change carries real risk of breaking something unrelated. Test coverage and file size matter, but they're weighted lower because they're proxies for quality, not quality itself - a file can be under 300 lines and still be badly structured, and a repo can have a healthy test-file ratio while testing the wrong things.

A real bug this formula used to have

The complexity sub-score didn't always work the way it does now. The original version computed it directly from the single highest-complexity function in the entire repo: 100 - maxComplexity * 2. That formula has an obvious failure mode once you actually run it against a large codebase: one outlier function can zero out the entire sub-score, regardless of how large the repo is or how clean everything else looks.

We found this the direct way - by running ArchSetu against torvalds/linux. The Linux kernel parsed out to 768,117 functions, with an average complexity of 4.4 - genuinely healthy by any normal reading. But a single hardware register table function came in at a complexity of 1,136. Under the old formula, that one function - out of 768,117 - was enough to drag the complexity sub-score to zero, because 100 - 1136 * 2 is a deeply negative number, clamped to zero.

The general lesson generalizes past this one metric: any score built from a single worst-case value instead of a ratio across the whole population will misrepresent large, real-world codebases, which almost always contain at least one legitimately gnarly function (a generated table, a big dispatch switch) even when the rest of the code is fine. A ratio-based score scales with how prevalent a problem actually is, not with whether one exists at all.

What this means when you read a score

A health score is a starting point for asking "which of these six things is dragging this down," not a verdict. Every report shows the full breakdown - all six sub-scores, not just the final number - specifically so a low score points you somewhere concrete instead of just feeling bad.