Skip to main content

Module code_health

codelore_lib::analyses

Module code_health 

Expand description

Code Health composite analysis.

codehealth(entity) = 100 × (1
    - w_sr · structural_risk(biomarkers)
    - w_cn · normalize(churn_rate)
    - w_au · normalize(author_fragmentation_FV)
)

defaults: w_sr = 0.50, w_cn = 0.30, w_au = 0.20

structural_risk is a weighted sum over the per-file biomarker table of eight smells (weights in SMELL_WEIGHTS, ordered by defect-correlation strength):

  • complex-method (0.22) — per-file MAX cyclomatic
  • god-class (0.18) — cognitive × (fan-in + fan-out)
  • large-method (0.12) — per-file MAX LOC
  • dry (0.12) — clone count
  • shotgun-surgery (0.12) — Fisher-significant coupling-partner count
  • deep-nesting (0.10) — per-file MAX nesting depth
  • many-args (0.07) — per-file MAX argument count
  • complex-conditional (0.07) — per-file MAX boolean-operator count

Each biomarker carries an intensity ∈ [0,1]. The complexity-driven ones (complex-method, large-method, god-class, dry, deep-nesting, many-args, complex-conditional) are a per-language PERCENT_RANK of the file’s worst value over the full file set; shotgun-surgery is a PERCENT_RANK over the coupled-file set only (no language partition). The per-smell weights sum to 1.0, so structural_risk stays in [0,1] and spreads across the file distribution. Smells absent for a file contribute 0, so co-occurrence is implicit — a file flagged by more smells accumulates more weighted terms. Coupling centrality (Fisher-significant pairs from coupling::run_coupling) enters once, as the shotgun-surgery biomarker; it is deliberately not also a separate behavioral term. Score range: [0, 100]; higher = healthier. Band (red/yellow/green) is derived from structural_risk thresholds; percentile is the per-language PERCENT_RANK of structural_risk (Alves, Ypma & Visser 2010).

Research basis: see docs/research-foundations.md entry “code-health” (composite signal developed in CodeLore; underlying inputs cite cyclomatic complexity and LOC biomarker intensities (Campbell 2018), churn (Nagappan & Ball 2005), ownership fragmentation (Mockus & Herbsleb 2002), and coupling centrality (Tornhill 2018)).

Structs§

CodeHealthRow
HealthScanCtx
What revision / sources a code-health scan runs against. head() resolves to today’s HEAD tables so existing behaviour is byte-identical.

Enums§

CloneSource
Where the DRY biomarker sources its per-file clone-family counts. The standalone scan and the gate PROJECTION fingerprint the live working tree; the gate BASELINE reads HEAD-faithful counts from the ingested clones table so a working-tree-introduced duplicate no longer appears in both runs and cancels out of the delta.

Functions§

run_code_health
run_code_health_scoped
Code health against the sources named by cx. cx = HealthScanCtx::head() reproduces the HEAD analysis byte-for-byte.