Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Code Health: Architecture & Internals
How the code health layer works, for contributors. What it does and how to use it:
docs/layers/CODE_HEALTH.md.
1. Layer overview
Code Health is the fifth intelligence layer, beside Graph, Git, Docs and Decisions: a deterministic pipeline where tree-sitter walks every file once, markers vote, and scores aggregate per category into four SQLAlchemy tables. It reads Graph and Git without modifying them.
Ingestion (parsed_files, git_meta_map, community_labels)
-> HealthAnalyzer (engine.py) -> HealthReport
-> delete/upsert -> SQLite: health_findings, health_file_metrics, health_snapshots, coverage_files
-> CLI (health, status, health --trend) | MCP (get_health, get_risk, get_context, get_overview)
| dashboard (/repos/[id]/code-health, tabs by ?tab=)
Rules: zero LLM (every marker is AST, git or coverage math); no JSON caches or intermediate files (SQLite is the one source the CLI, MCP server and Next.js dashboard read); no new runtime dependencies (pure Python over tree-sitter: no lizard, jscpd or Node).
2. Where things live
packages/core/src/repowise/core/analysis/health/ |
Holds |
|---|---|
__init__.py, engine.py, file_evaluator.py |
HealthAnalyzer, HealthReport; walker → biomarkers → scorer; one file's context, detectors and score |
scoring.py, shape_curve.py, ranking.py, aggregation.py, grading.py |
Aggregation, caps, KPIs; the saturating curve; worst-first key; rollups; the five bands |
crap.py, governance.py, finding_identity.py, defect_accuracy.py |
CRAP score; governance findings; stable ids; self-validation |
trends.py, signals.py, churn_complexity.py, suggestions.py, config.py, models.py |
Alerts and series; per-file signals; churn × complexity; refactoring text; HealthConfig; dataclasses |
fix_first/, worth.py, queue/, perf/ |
Fix first (§6.3); performance opportunities (§6.4) |
complexity/, coverage/, duplication/ |
tree-sitter walker (walker.py, languages.py); stdlib report parsers and the test-file heuristic; Rabin-Karp clones (64-bit rolling hash, co-change weighting). Each has a README.md |
biomarkers/ |
base.py (Protocol, FileContext, BiomarkerResult), registry.py (detect_all()), one <id>.py per detector (§5) |
| Elsewhere | Holds |
|---|---|
core/persistence/models.py, core/persistence/crud/analysis/health/ |
The four ORM tables; save_ / upsert_ / get_ functions |
packages/core/alembic/versions/0019_code_health.py |
Created the tables; later health migrations add columns |
core/pipeline/phases/analysis.py, core/pipeline/persist/ |
_run_health_analysis(); persist_pipeline_result() |
cli/.../commands/health_cmd/, status_cmd.py, update_cmd/ |
CLI (§11) |
server/.../mcp_server/tool_health/, tool_risk/, tool_context/, tool_overview/; server/.../routers/code_health/ |
MCP (§12); REST (§13) |
packages/ui/src/health/, packages/web/src/app/repos/[id]/code-health/ |
Shared React components (web and hosted frontend); the page (§14) |
tests/unit/health/, tests/integration/test_health_* |
Tests (§18) |
3. The pipeline (init path)
run_pipeline() (core/pipeline/orchestrator.py) calls _run_health_analysis() between
_run_dead_code_analysis() and _run_decision_extraction(). It:
- maps
{file_path: community label}soHealthFileMetric.moduleis never NULL; - loads
.repowise/health-rules.json(HealthConfig.load, a no-op when absent) into per-file disabled sets (to_analyzer_config()); - builds
HealthAnalyzerfrom the NetworkX graph,git_meta_map(hotspot bit, owners, co-change, bus factor),parsed_filesand the module map; - runs
analyze_async()(worker threads; tree-sitter releases the GIL) at>= 500parsed files, elseanalyze().
core/pipeline/persist/ writes PipelineResult.health_report in one session:
save_health_metrics, save_health_findings (when there are findings) and
save_health_snapshot (the KPIs, a {path: score} map, and {path: total_deduction}
for floored files). trends.snapshot_file_maps builds both maps for every snapshot
writer (also health --recompute and update --full), so history depth never depends on
the last writer.
4. Inside HealthAnalyzer.analyze()
Per file:
- Walk (
_walk,walk_file): eachFunctionComplexitycarries name, line range, nloc, ccn, max nesting, cognitive complexity, bumps and params; eachClassComplexitycarries method count and list, total nloc, LCOM4, max method ccn and field count. A nested function gets its own entry; a lambda counts toward its holder. - Symbol complexity (
_populate_symbol_complexity):max(ccn)intoSymbol.complexity_estimatefor theContextAssemblerranker. - Evaluate (
FileEvaluator.evaluate): aFileContext(nloc,has_test_file, module, metrics,git_meta, in-degree asdependents_count, the repo p80 in-degree, coverage, the clone slice), thendetect_all(),score_file()and per-finding impacts.
compute_kpis() then gives the hotspot, average (both NLOC-weighted) and worst KPIs.
Duplication runs once up-front; dry_violation ranks clone pairs by co-change
(co_change_partners_json), so active clones rank above dormant ones.
5. The markers and their categories
Each marker is a stateless class implementing the Biomarker Protocol
(biomarkers/base.py): name, category (scoring.CATEGORY_CAPS) and
detect(ctx: FileContext) -> list[BiomarkerResult]. biomarkers/registry.py is an
explicit list, so order is deterministic and tests inject extras via
registered_biomarkers(extra=...).
The full roster
biomarkers/registry.py registers 59 detectors; counting the three governance
findings written by the additive pass (governance.py) there are 62 marker ids. They
divide by what each is permitted to affect:
| Group | Count | Scores into |
|---|---|---|
| Defect-scoring | 23 | defect (9 of them also maintainability) |
| Performance | 22 | performance only |
| SQL | 3 | maintainability only |
| Governance | 3 | nothing: the finding surfaces, the score is untouched |
| Advisory | 11 | nothing: measured by construction, out of impact-ranked lists unless requested |
The authority is scoring._BIOMARKER_DIMENSIONS. An unlisted biomarker defaults into
defect, so every sql_* and performance name is listed explicitly: an omission would
silently break the defect golden guarantee (§6).
Thresholds are the minimum for the default severity (medium unless stated), then the bands above it; "judged" CCN and nesting follow the dispatch rule (§5.5). Scoring gives the defect weight (§6.1), "maint" the maintainability and "perf" the performance weight.
id |
Category | Flags | Threshold | Scoring |
|---|---|---|---|---|
brain_method |
Structural | A long, complex, central function | NLOC 70, judged CCN 9, file dependents ≥ min(8, max(repo p80, 3)); high at CCN 14 or NLOC 120; critical at CCN 20 and NLOC 150 | Advisory |
low_cohesion |
Structural | A class split into unrelated method groups | LCOM4 2 and 5 methods; high at LCOM4 3 or 20 methods; critical at LCOM4 4 and 15 methods | 0.5; maint 1.0 |
god_class |
Structural | A large class hiding a brain method | 200 NLOC, 15 methods, one method at NLOC 70 and CCN 9; high at 300 NLOC or 20 methods; critical at 400 and 25 | 1.13; maint 1.0 |
nested_complexity |
Structural | Deep nesting in a function | Judged depth 4; high at 5; critical at 7 | 1.34; maint 1.0 |
repeated_nesting |
Structural | Several blocks at one nesting depth | 3 bumps (low) and judged CCN 5; medium at 4 bumps, high at 5 | Advisory |
complex_conditional |
Structural | A boolean expression with many operators | 3 operators (low); medium 4, high 5, critical 6; a flat chain (one operator, no negation) is not flagged | 1.33; maint 1.0 |
complex_method |
Size | High cyclomatic complexity | Judged CCN 9; high 15; critical 25 | 1.21; maint 1.0 |
large_method |
Size | A long function | 60 code lines (low) and judged CCN 3; medium 90, high 120, critical 200 | 1.25; maint 1.0 |
primitive_obsession |
Size | A long list of scalar parameters | 5 parameters (constructors 7), over half the typed ones primitive, file at 60 NLOC, not a test (low); medium at threshold + 2, high at + 4 | 0.5; maint 1.0 |
dry_violation |
Duplication | A cross-file clone | File duplication 8% and a clone of 6 lines (low); medium with active co-change (3) or 25% duplication; high with both | 0.5; maint 1.0; hidden by default |
error_handling |
Error handling | Swallowed or catch-all handler, Rust unwrap/panic, discarded Go error |
Low, one per occurrence | 0.5; maint 1.0 |
untested_hotspot |
Test coverage | A depended-on hotspot with weak test evidence | Hotspot, 4 dependents, coverage under 40% (no report: no paired or reaching test); high at ≤ 15% or 10 dependents; critical at both | 1.3 |
coverage_gap |
Test coverage | A large uncovered surface (needs a report) | Under 30% with 50 coverable lines (high at 100 uncovered); under 60% with 25 uncovered is low | 1.0 |
untested_complexity |
Test coverage | A complex function tests barely run | CRAP 30; high 50 and critical 100 on measured coverage only | Advisory |
coverage_gradient |
Coverage gradient | Uncovered share of a file (needs a report) | 4.0 × (1 − line_coverage_pct/100) points; label high under 40%, medium under 70% |
1.0, continuous |
developer_congestion |
History | Many authors, no owner, high churn | 5 contributors, top quarter of churn, 3 commits in 90 days, nobody owns half (low); medium at 7 contributors or 12 commits; high at 10 and 20 | 0.5 |
knowledge_loss |
History | A changing file whose sole real author (bus factor 1) is gone or under 20% of recent commits | Low; medium when the owner is gone and under 20% of recent commits; high on a hotspot; low on a small team (≤ 3 contributors) off a hotspot | 0.4 |
hidden_coupling |
History | Files that co-change with no import edge | 5 commits each side, correlation 0.5; high 0.65 (with 8 co-changes), critical 0.8; at most 3 per file; tests skipped | Advisory |
function_hotspot |
History | A complex function changed often | Changes ≥ max(repo p80, 5) with CCN 10 or nesting 3; high at 2× the bar or CCN 15; critical at 3× and CCN 20 | 1.16 |
code_age_volatility |
History | A dormant function changed again | Median line age 365 days and 2 changes in 30 days; high at 730 days or 5 changes; critical at both | 1.1 |
ownership_risk |
History | Many minor contributors or no dominant owner | 5 commits and 3 minor contributors (each under 5%) or no author above 40% (low when only that arm fires); medium at 3 minors, high at 5 (3 on a hotspot), critical at 6 on a hotspot; low under 40 code lines or on a small team off a hotspot | 1.38 |
churn_risk |
History | Rewrote much of its own lines in 90 days | 5 commits in 90 days, top quarter of churn, relative churn 1.0 (low); medium 1.5, high 2.5, critical 4 on a hotspot | 1.2 |
change_entropy |
History | Scattered, noisy changes | Entropy percentile 0.80, 3 commits in 90 days; high 0.90; critical 0.95 on a hotspot | 1.51 |
co_change_scatter |
History | Coupled to many files (shotgun surgery) | Percentile 0.80, 3 commits in 90 days, not a test or barrel; high at 0.95 | 1.8 |
prior_defect |
History | Recent bug-fix commits | 1 fix in 180 days at percentile 0.80 (low); medium 2, high 3-4 (critical on a hotspot), critical 5 | 1.0 |
ungoverned_hotspot |
History | A hotspot no decision governs | Medium; from the decisions layer | Governance 0.7; never deducts |
stale_governance |
History | A governing decision gone stale | High; from the decisions layer | Governance 0.9; never deducts |
contradictory_decision |
History | Decisions that contradict each other | High; from the decisions layer | Governance 1.0; never deducts |
large_assertion_block |
Test quality | One test asserting many behaviours | 15 consecutive assertions; high at 30; test files only | 1.0 |
duplicated_assertion_block |
Test quality | Copy-pasted assertion runs | 5 real checks per block; test files only | 1.0; hidden by default |
assertion_free_test |
Test quality | A test that checks nothing | Low; Python, JavaScript, TypeScript, TSX | Advisory |
mock_saturated_test |
Test quality | Mock setup dwarfs the assertions | 6 mock setups at 3 per assertion (low); medium at 8; Python, JavaScript, TypeScript | Advisory |
sql_high_complexity |
SQL | A complex SQL routine | CCN 10; high at CCN 20 | maint 0.7 |
sql_select_star |
SQL | SELECT * |
Low | maint 0.7 |
sql_update_delete_without_where |
SQL | UPDATE or DELETE with no WHERE |
Medium | maint 0.7 |
sql_cartesian_join |
Performance | A cartesian join in SQL | Medium | perf 0.6 |
apex_soql_injection |
Apex | A String from outside the method spliced into a quoted literal of a dynamic query, unescaped | High; non-test Apex | Advisory |
apex_missing_sharing |
Apex | A top-level class with queries or updates and no sharing keyword | Medium; not subclasses, inner or test classes | Advisory |
apex_hardcoded_id |
Apex | A record Id as a string literal | Medium; 18 chars with a valid checksum or 15 on a standard prefix; non-test Apex | Advisory |
apex_see_all_data |
Apex | @IsTest(SeeAllData=true) |
Low | Advisory |
cobol_unstructured_flow |
COBOL | A paragraph or section with ALTER, GO TO ... DEPENDING ON, or a GO TO that is not a forward jump to an ...EXIT paragraph of its own PERFORM THRU range |
Low; one finding per paragraph | Advisory |
io_in_loop |
Performance | I/O per loop iteration (N+1), across functions | Medium | perf 1.0 |
string_concat_in_loop |
Performance | += of a provable string in a loop |
Low | perf 0.7 |
blocking_sync_in_async |
Performance | A sync blocking call in async def |
Medium; Python, Rust, C#, Kotlin, Scala | perf 0.7 |
regex_compile_in_loop |
Performance | A static regex compiled per iteration | Medium; Java, Go, Rust, C++, Kotlin, Ruby, Scala | perf 0.6 |
defer_in_loop |
Performance | defer inside a loop |
Medium; Go | perf 0.6 |
resource_construction_in_loop |
Performance | A client built per iteration | Medium | perf 0.7 |
lock_in_loop |
Performance | A lock taken each iteration | Low | perf 0.5 |
serial_await_in_loop |
Performance | Awaited I/O run serially in a loop | Low | perf 0.4 |
membership_test_against_list_in_loop |
Performance | x in list (or .includes) on a provable list in a loop |
Low | perf 0.7 |
unbounded_read_reduced_in_memory |
Performance | An unlimited query reduced per key in code | Low; Python | perf 0.4 |
lazy_load_in_loop |
Performance | An ORM lazy relation read per iteration | Low; SQLAlchemy, Django | perf 0.4 (Django 0.7) |
nested_loop_with_io |
Performance | I/O in a loop nested two deep | Medium | perf 0.5 |
nested_loop_quadratic |
Performance | A quadratic nested loop, widely called | Low; centrality gated | perf 0.4 |
hot_path_sync_io |
Performance | Sync I/O in a widely called function | Low; centrality gated | perf 0.5 |
blocking_io_under_lock |
Performance | Blocking I/O while holding a lock | Medium | perf 0.6 |
list_insert_zero_in_loop |
Performance | list.insert(0, x) in a loop |
Medium; Python | perf 0.6 |
pd_concat_in_loop |
Performance | pd.concat accumulating in a loop |
Medium; Python | perf 0.6 |
pandas_iterrows_in_loop |
Performance | df.iterrows() |
Medium; Python | perf 0.6 |
json_parse_in_loop |
Performance | A JSON.parse(JSON.stringify(x)) deep clone per iteration |
Low; JavaScript, TypeScript | perf 0.4 |
array_spread_in_reduce |
Performance | [...acc] inside reduce |
Medium; JavaScript, TypeScript | perf 0.5 |
goroutine_in_unbounded_loop |
Performance | A goroutine per range element | Medium; Go | perf 0.4 |
Notes:
biomarker_names.pymaps the legacy idbumpy_roadtorepeated_nesting.- "Hidden by default":
analysis/finding_registry.pykeeps the type off every default surface (overview, priorities, MCP, REST lists) until a re-measurement clears its precision; it is still computed, stored and scored. - Performance markers with no language listed run in every perf dialect that models the construct (§6.4, PERFORMANCE.md).
Defect categories and caps
| Category | Defect cap | Maintainability cap |
|---|---|---|
| Organizational (history and governance) | 3.5‡ | none |
| Structural complexity | 2.5 | 4.0 |
| Test coverage | 2.0 | none |
| Test coverage gradient | 2.0 | none |
| Size & complexity | 1.5 | 2.0 |
| Duplication | 1.0 | 2.0 |
| Test quality | 0.5 | none |
| Error handling | 0.5 | 2.0 |
| SQL | none | 2.0 |
- Maintainability caps (
_MAINTAINABILITY_CATEGORY) and the singleperformancecategory (2.0) are hard caps. Governance findings are written after scoring and never touchHealthFileMetric.score. - ‡ History is a hard cap,
history_cap(structure) = min(3.5, 1.0 + structure), wherestructureis the file's settled deduction from every other defect category. Before it,destackedcounts the largest history finding whole and the rest at 0.25. - Every other defect category saturates (
shape_curve.py): raw totalRdeductsA * (1 - exp(-R / A))withA = 3.09 x cap, so no category deducts more than 3.09 times its cap. The 3.09 is fitted so the corpus mean matches the hard-capped score; the curve is AUC-neutral on the 66-repo corpus. - Function-shape findings (
FUNCTION_SHAPE_MARKERS) on one function count the largest whole and the rest at 0.25. A criticalcomplex_method,large_methodornested_complexitydeducts2.0 x value / threshold(CCN 25, 200 lines, nesting 7), so halving a CCN-50 function pays while it stays critical.
Marker notes
- Git process markers read indexer fields:
ownership_risk(Bird et al.;top_authors_json),churn_risk(size-normalized, Nagappan-Ball;lines_added_90d,churn_percentile),change_entropy(Hassan; §5.1),co_change_scatter(D'Ambros;co_change_partners_json),prior_defect(Ostrand-Weyuker, Kim's "bug cache";prior_defect_count).knowledge_lossis activity-gated, so abandoned-but-stable files (the survivor effect) stay silent. prior_defectcounts non-merge fix commits in the trailing ~6 months, classified by the same keyword rule the defect benchmark labels with (_constants.is_fix_commit) and anchored to the index'sas_of(the indexed commit's date), so a T0 checkout never sees post-T0 fixes. Its neutral 1.0 weight is by design: correlation ≈ +0.59 withchange_entropyand +0.38 with churn, coefficient ≈ +0.02, Popt gain within noise. It ships for its explanatory value and catches a few files the others miss.coverage_gradientmakes coverage continuous: the binary gates fire only below ≈40-60%, blind to the 85-99% files where the uncovered share still predicts defects. Itsdeductionoverride onBiomarkerResultkeeps it linear and per-finding attributable (2.0 points at 50% uncovered), in its own category so it neither squeezes nor is squeezed by the gates. It is silent without a report (line_coverage_pct is None), skips tests and, likecoverage_gap, files of only a docstring, imports and__all__(an__init__.pyorindex.tsbarrel). It adds +0.043 corpus AUC [95% CI +0.023, +0.061] on the covered subset (≈65% of the continuous-feature ceiling), Popt-neutral, and zero without coverage.- Class-level:
low_cohesionandgod_classreadctx.class_metrics(§5.2).brain_method's gate is language-agnostic: the repo's top quintile of connected files (repo_dependents_p80, once per analyze) or the absolute hub bar of 8, so sparse graphs (TS barrels, Rust) are not silent. large_methodneeds judged CCN ≥ 3, so a long-but-flat body (a data literal, a dispatch of one-line arms) reads as layout. In.tsx/.jsxa line of only JSX tags, attributes or text is markup; a{...}expression is code. Its reason reads "N lines of code (M with blanks and comments)", with M indetails.span.complex_methodreports the judged CCN, plus the raw CCN when they differ.error_handling(advisory maintainability) flags empty or comment-onlycatch/except: pass, Pythonexcept:/except Exception:, Rust.unwrap()/.expect()/ panic macros, and Go's emptyif err != nil {}or blank-identifier error discard. A whole-tree walker pass (module code included) reuses the catch kinds of the seven catch-shaped languages plus Rust and Go recognizers; unsupported or unparsable is "no signal". One LOW finding per occurrence (0.15 after the 0.5 floor); its 0.5-cap category deducts at most 3.09 × 0.5 ≈ 1.5. It is excluded from calibration: AUC-neutral on the 21-repo / 9-language T0 benchmark (OOF delta ≈ 0) but size-orthogonal and the least redundant signal tested; users expectexcept: passflagged.- Test quality: the two assertion-block markers (§5.3) fire only on test files, in a small category so a noisy test can't dominate its score.
5.1 Change-entropy git-layer fields
Computed in the single FULL-tier co-change walk
(ingestion/git_indexer/co_change.py::compute_co_changes_and_entropy), no extra
git log. A commit touching 2 ≤ |F| ≤ 30 tracked files has entropy log2(|F|) (wider
ones are noise, Hassan's filter), spread 1/|F| per file and decayed with co-change's
τ=180d half-life into git_meta["change_entropy"]. enrich.compute_percentiles ranks
only positive-entropy files into change_entropy_pct; zero-entropy files (the
ESSENTIAL tier, files only ever changed alone) keep 0.0. Both live on git_metadata
(migration 0025), back-filled on legacy DBs by additive reconcile.
5.2 Class-level walker metrics (LCOM4)
Languages with non-empty LanguageNodeMap.class_kinds (Python, TS/JS, Java, Kotlin, Rust
impl, C++, C#; Go has no grouping node) get a ClassComplexity per class. LCOM4 counts
connected components of the class's methods, linked by a shared instance field or a call,
found via self/this/$this member access. Safety valve: no detected member
references (a static utility, an unmapped language) gives lcom4 = 1 ("no signal"), so a
new language can only turn signal on. Details: complexity/README.md.
5.3 Assertion-block walker metrics (test-quality)
The walker records assertion_blocks per FunctionComplexity: runs of ≥ 2 consecutive
assertions as (start_line, end_line, count). An assertion is a bare assert
(assert_kinds) or a call (assert_call_kinds) whose callee starts with assert or
expect (assertEqual, assert_eq!, expect(...).toBe(...)). All nine full-tier
languages (Python, TS/JS, Java, Kotlin, Go, Rust, C++, C#) are mapped; a language mapping neither field emits none. Both block markers
gate on coverage.is_test_file(path); duplicated_assertion_block intersects the clone
report with assertion spans.
5.4 Advisory markers and their precision record
advisory is not in DIMENSIONS, so no weight, category or cap table can key on it. A
marker must be in both _BIOMARKER_DIMENSIONS and _ADVISORY_HOME, or it still deducts.
Advisory findings carry health_impact == 0.0, never count toward a change's
introduced/worsened totals or make a review blocking, and stay out of impact-ranked lists
unless named. A marker earns weight at roughly 70% hand-labelled precision, measured per
language because it does not transfer:
mock_saturated_test: 67% Python (32 findings), 40% TypeScript (30), each the full population at the shipped gate and a ceiling (later oracle shapes only suppress). It waits on two false-positive families,Fake*builders passed into real logic and boundary isolation where the assertion reads a real artifact: a dataflow question.assertion_free_test: ≥ 71% TypeScript (31, the full population of two corpora; a floor, three false-positive families closed after labelling), 86% Python (29 labelled, a systematic sample of 172); not Go or Java. A helper's oracle resolves by name in the file and via the call graph across files; a mock verification counts as an oracle, the opposite ofmock_saturated_test(tiers incomplexity/assertions.py).hidden_coupling: near-chance alone (AUC about 0.55); a pre-registered test on 12 repositories no earlier health study used found the score non-inferior without it.brain_method: fires only wherecomplex_methodandlarge_methodalready charge; dropping it left defect AUC unchanged on the 66-repo corpus.repeated_nesting: 29% in a blind study (7 of 24 findings), mostly short functions with a few simple loops; dropping it with four other weak markers cost 0.004 defect AUC.untested_complexity: complexity and coverage already deduct elsewhere (user guide).- The four
apex_*markers: every finding on 13 Salesforce repos hand-read, none wrong; no defect corpus covers Apex yet.
5.5 Worked example: the dispatch rule
nested_complexity adds a level per if / for / while / try / switch; a case
arm adds none. A
function mostly one dispatch on one value (a switch, match or same-subject if chain
with ≥ 60% of its decision points) is judged by the code around it plus its heaviest arm:
nested_complexity skips the dispatch's level and the loop it usually sits in, and complex_method,
brain_method and repeated_nesting read the outer CCN plus the worst arm's.
TypeScript and JavaScript ternaries
A ternary opens no level as an arm of a chain (a ? x : b ? y : z), inside JSX markup, or
with a JSX branch: one decision per arm (still +CCN and a flat +1 cognitive, like
else if). Still nesting: a ternary in another's consequence, in a call argument or
object literal inside JSX ({fmt(a ? b : c)}), with a non-JSX branch
(cond ? c2 && <A/> : x), and every if / for / try in a JSX handler.
6. Scoring (scoring.py)
Every file starts at 10.0 and is clamped to [1.0, 10.0]. A finding deducts its
severity (low=0.3, medium=0.7, high=1.2, critical=2.0) times its weight (§6.1);
score_file() sums per category and settles each total (§5); each finding is then scaled
by settled/raw, so the parts still sum to the category and HealthFinding.health_impact
(via attach_impacts(), defect pillar only, the dashboard's "−2.0") stays honest.
test_scoring_snapshot.py locks caps, severity deductions, the marker-to-category map
and two fixture scores, so a retune updates it in the same PR.
6.1 Calibrated weight multipliers
scoring._BIOMARKER_WEIGHT_MULTIPLIER (values in the full roster) is
calibrated offline, not hand-tuned: files scored at T0, an L2-logistic regression with
NLOC as a control fits each marker's lift beyond size, and only the constants ship
(benchmark report).
- Strongest:
co_change_scatter(strongest),change_entropy(second),ownership_risk,nested_complexity(strongest structural). - Prior weights kept:
untested_hotspot,churn_risk,code_age_volatility, which are coverage-dependent or rare, so the corpus could not fairly measure them. - Floored at 0.5:
developer_congestion,dry_violation,low_cohesion,primitive_obsessionfire widely but proved weak under leakage-free scoring;knowledge_lossis de-rated to 0.4, the weakest.error_handlingis not fitted.
Maintainability uses an independent expert-set table (floored smells at full weight) and
performance its own bounded category; the three share one kernel and never feed each
other. The headline stays the defect score: test_scoring_dimensions locks
score_file(...)["defect"] byte-for-byte to the pre-split score, and blending pillars
would need a written rationale and a recalibration corpus.
6.2 Validation and calibration
Headline results (jEdit 4.0 / 4.1 held out with no git history, structural markers only): layer page and BENCHMARKS.md.
- Protocol. Files scored at a commit T0 before the bug window, in a detached worktree whose history stops at T0; labels are the next six months of fix commits; L2-regularized logistic regression with an NLOC control and leave-one-repo-out cross-validation.
- Leakage both ways. HEAD scoring lets fix commits manufacture the churn and
congestion process markers "detect"; naive T0 scoring silences recency windows, so they
anchor to the worktree's own HEAD (
as_of).developer_congestionshipped at 1.5 under HEAD scoring and came back at coefficient -0.08, hence its floor. - Rejected. PageRank, code naturalness, change bursts and error-handling density were equivalent to null by bootstrap TOST. Size-relative scoring (−0.07 to −0.12 AUC), function-level prediction (Popt at or below random) and SZZ labels (lower out-of-fold AUC) were refuted.
- Corpora. 21 repositories, 9 languages, 2,826 files (379 defect-bearing); the commercial-tool comparison and band separation (16.9x raw, 2.18x size-normalized) use the 2,770 both tools scored. Intervals: two-stage repo-cluster bootstrap (2,000 seeded replicates).
- More results. +0.100 AUC over recent churn (DeLong p = 5e-10) and +0.117 over prior defects (p = 3e-15); per repo 0.55 (axios) to 0.86 (zod). LOC alone: delta -0.001 (p = 0.92); Popt +0.134 (95% CI +0.080 to +0.198). NLOC quartiles 0.525 / 0.572 / 0.593 / 0.718, with a positive control recovered at power 0.998 to 1.000, so the collapse is the score's. A prior-defects baseline beats it on Popt by 0.085 (95% CI 0.035 to 0.141).
- Paired vs the commercial tool: Popt 0.607 vs 0.462, size-normalized density 2.18x vs 0.56x (both p = 0.003); AUC 0.731 vs 0.705 (p = 0.054); raw density 16.9x vs 14.2x (p = 0.65); precision 0.580 vs 0.636 (p = 0.64); partial rho beyond size -0.148 vs -0.137. It flags 27 files at its most severe level where Repowise flags 132 At risk (a more conservative point); its published -0.58 correlation with issue-resolution time (proprietary Jira data) was -0.09 (95% CI -0.19 to +0.14) on open GitHub data, and six queue-independent effort signals were flat.
- In-product check (
defect_accuracy.py): an association, sinceprior_defectis an input. Data: repowise-bench/health-defect (COMPARISON_REPORT.md).
6.3 Fix first ranking (fix_first/, worth.py)
fix_first/build.py builds Fix first once from stored rows (index and update save it and
Do next); get_health, repowise health, the dashboard and the generated CLAUDE.md
render it unchanged. Each excluded unit is counted in totals.excluded under one reason,
decided with the performance queue's in analysis/health/queue/:
| Reason | What it leaves out |
|---|---|
test, tooling, generated, vendored, docs_example |
Path roles (notes below) |
unknown, expected, no_strategy, no_plan |
Performance causes: no classified context, expected repetition, no strategy, no safe plan (PERFORMANCE.md) |
below_min_worth |
Under MIN_WORTH (0.5) recovered, or no steps |
unmeasured_cost, cold_role, background_unproven, unconfirmed_cost |
Dropped by the default queue, or not confirmed by perf_confident_verdict (registry or cold-path growth only, or no role and no reaching entry point) |
history_only |
Only git-history findings |
deprecated |
Deprecated functions |
gated_off |
Dormant: switched off by a same-file constant-false flag (complexity/gating.py) |
unreachable |
An open dead-code finding (confidence 0.8+ or safe to delete) covers the file, the symbol's lines, or its name |
inherent_dispatch |
One dispatch holds ≥ 60% of decision points (8 of 9 labelled rows rejected), unless a duplicate sits in it |
small_function |
Under 30 code lines and CCN 15 (on 67 labelled rows: drops 13 rejected, 4 accepted) |
no_concrete_step |
No first edit with a file and line or a named group |
low_value_kind |
Low cohesion (0 of 46 accepted), long method (0 of 10), long parameter lists (0 of 2) |
kind_unaudited |
Extract Class (0 of 14) or Move Method (0 of 34) plans, until a per-language audit passes |
terminal_flow |
≥ 25% of calls print or prompt (complexity/terminal.py): status reports, checklists, wizards |
moderate_quiet |
Under CCN 80 and 200 lines, outside the top fifth by churn (or changed once), no prior_defect in the file, no function_hotspot on it |
Path-role and dormant-function details
- Tooling includes Dart's
tool/scripts and build files by type anywhere: Gradle, CMake, Makefiles, Bazel, MSBuild props/targets, rootsetup.py,noxfile.py, crate-rootbuild.rs, bundler configs. - Docs means a root
docs/ordocs_src/tree, or one beside a docs-site config; a product'sapp/docs/route is production. - Test helpers named for a module's tests (
bot.test-harness.ts,card-test-helpers.ts,test-support.mjs) are test support and*.bundle.jsis generated; worst-file lists say how many they left out and why. - Dormant: the body opens with
if not FLAG: return ...or is oneif FLAG:block, andFLAGis a module-levelFalse,0orNone(const FLAG = falsein TS/JS) the file never reassigns. Only the file is read: an imported flag, or one flipped bysetattror a monkeypatch, still reads as off.totals.dormantcounts distinct functions; for performance it is stateexpected, reasongated_off.
Order
- Value: the larger of health recovered and size (CCN 20/40/80/150, lines 100/200/400/800, nesting 5/6/8, a critical or brain-method finding), one step more on a hot file (a function under 5% of its file's lines is credited that share of the importers). A performance fix's value is its cost; production, entry-reachable, data-growing DB or network calls are the top band.
- Tier
now/next/later; at mostHEAD_PER_KIND(3) of the firstHEAD(5) per kind. - Inside a band: complexity removed × reach (a 4,000-line loop outranks a long print
routine) ×
1 + ln(1 + n)for thencommits that changed the lead function (git_function_blame); with no function history, a file too large to blame, no lead function, or a performance cause, a top-fifth-churn file weighs 1.25.
worth.py marks later: under CCN 40, 200 lines and nesting 6 (nesting under 8 counts
only from 100 lines) and not both CCN 25 and nesting 5; a dominant dispatch; nesting that
is one else-if or ternary chain; long but CCN under 20 and nesting under 5; a single
complex condition or error site. CCN 80, 400 lines or nesting 8 is worth doing
regardless; the hot-file bonus orders but never lifts out of later. Items carry up to
MAX_TESTS (5) tests. The findings list uses the same rule (lower_priority on the
rest; class-design and history-only findings, and performance unless production code
runs it over growing data).
Fix first steps
- A "Break up" reason says what splitting buys: smaller, easier parts, and less
duplication when part is a copy. "Due" means
nowornext. - A finding whose first step borrows a plan that still leaves a function above the bar keeps its tier, and the step says so.
- An Extract Method step finds its lines by their start and end text (line numbers move with the first edit); if that text repeats in the file, it says to stay inside the function.
- An Extract Method step carries the plan's
notes. A stage that takes the shared parameter object shows the object's declaration above its helper and the line building it above its call. A plan missing either is not offered as a Fix first step, since its call would name a variable that does not exist.
6.4 Performance opportunities (perf/)
User guide (states, default queue, exclusions): PERFORMANCE.md.
- Sinks.
io_in_loopresolves a loop call through the graph's resolver against the I/O lexicon (io_boundaries.py: db, network, filesystem, subprocess, lock): real round-trips only, never a query-builder chain. Non-local sinks are found up to three hops back (crossfn.py) with thecaller -> ... -> sinkpath. - Gates. Two markers fire only at or above the 80th percentile of distinct direct
callers, never under two (how widely called, not request reachability).
blocking_sync_in_asyncskips tests, tooling, examples, generated and vendored code. - Grouping. One opportunity per intervention site per cost family and boundary
(
<file>::__module__for top-level code); members are sinks, call sites and same-family co-signals (io_in_loopwithnested_loop_with_io), keyed by the sink's line. All-cold groups (perf/cold_paths.py) areexpected/cold_pathwith or without a strategy;gated_offwins.execution_contextstays path-only. - Queue. Ranked by
rank_score, exclusions counted indefault_queue. Fix first, Do next and the lead take only queuedplan_readycausesqueue.eligibility.perf_confident_verdictconfirms (growth_source = loop); advisory causes measured 0 true of 14 on three repositories. - Plans. Proven means the transformation: awaits against a DB or network client are
advisory with a
bounded_concurrencyprerequisite; a chunked loop isloop_already_chunked;io_in_loopandserial_await_in_loopon one call name each other insiblings. Edits aremechanicalonly when proven and name the call they repeat (details.sink_call, or the entered helper).buffer_string_accumulationandreplace_membership_collectiontake one step per loop and variable (details.subject), which effort counts. Tests come from coverage, call graph, import graph, thenvia: "name-match"; aperformance_fixplan links only by exactopportunity_id. - Dataflow promotion.
serial_await_in_loopandnested_loop_quadraticgetdataflow_verified: truewhen a def/use pass proves iterations independent (wording, not score). - ORM lazy loads.
lazy_load_in_loopneeds rows resolving to one model via the cross-file model index and a lazy relation the query does not eager-load. Its weight comes fromdetails.orm(_PERFORMANCE_ORM_WEIGHT): Django 0.7 (29/32, 90.6% held out), SQLAlchemy 0.4 (under 30 labels). - Dialects.
perf/dialects/has 12 dialects over 19 language tags (TS/JS also cover Vue, Svelte and Astro scripts; C# covers Razor); C shares the C++ grammar but has no dialect, so it emits nothing. - Soundness. No call edge for dynamic dispatch, monkeypatching or callbacks-as-values; ORM lazy loads are seen only where rows can be typed; chains beyond three hops are not followed; an unmodelled library has no sinks. Benchmarks: repowise-bench/perf-detection.
7. KPIs
compute_kpis() (§4) writes Hotspot Health, Average Health and Worst Performer into
HealthSnapshot rows; they feed the status line, get_overview() and the dashboard cards.
8. Trends (trends.py)
State-free over an oldest-first snapshot list; alerts run on each metric in
_ALERT_METRICS (hotspot health, the composite headline, maintainability) a snapshot
recorded.
- Declining Health: ≥
DECLINE_THRESHOLD(0.5) below the snapshotDECLINE_LOOKBACK(5) back, so from the 6th snapshot. - Predicted Decline: three snapshots in a row each strictly lower; direction, not magnitude.
history_drag: either, as a thirdkind, when the headline fell withdriverhistoryand the structure half held: nothing in the code to act on, so not error red. Maintainability never softens.
recent_kpis(history, limit=10) is the newest-first view for the CLI and
get_health(include=["trend"]).
Per-file trajectory
file_score_series(history, path)readsper_file_scores_json: oldest-firstFileTrendPoints,[]below two points. The PR bot reuses it for its sparkline.file_trend(history, path)addscurrent/previous/deltaanddeclining(threshold below the lookback point, orPREDICTED_DECLINE_CONSECUTIVEdrops);snapshot_counttells a young repo from a file missing in older snapshots. Served via_file_trend_to_dictin the file block, the breakdown and the trend route (§13).
Below the floor
Files 12.9 and 9.1 points deep both store 1.0 ([SCORE_FLOOR, SCORE_MAX]).
per_file_deductions_json keeps the pre-clamp deduction for floored files only, and each
point's unclamped_score (SCORE_MAX - deduction, else score) feeds
_file_declining, so a file worsening below the floor trips declining. Snapshots
without the map stay flat: the depth was never measured.
Per-file signals (signals.py)
file_signals(git_meta, degrees) joins one GitMetadata row and the graph degree into
FileSignals, no recompute: Process (prior_defect_count, change_entropy_pct as
0-100, 90-day line churn, age_days), People (recent vs all-time owner and share),
Topology (in_degree / out_degree). A field is None only when its source row
is absent (never imputed; a real 0 stays). Served via _file_signals_to_dict (§13),
null-dropped in get_context (§12), typed as FileSignals in
@repowise-dev/types/health, drawn by file-signals-panel.tsx.
9. Incremental analysis: the repowise update path
With changed_files, duplication still runs repo-wide (a clone partner may be
unchanged), other files are skipped, and KPIs are not recomputed (the dashboard
derives them from merged rows). update_cmd/ takes the set from
change_detector.get_changed_files() and upserts (upsert_health_metrics,
upsert_health_findings); full init deletes and inserts (save_health_*).
10. Persistence schema
Four tables in .repowise/wiki.db, keyed to repositories.id with ON DELETE CASCADE.
health_findings
One row per hit; lifecycle open → acknowledged | resolved | false_positive (as Dead
Code). Columns: id (UUID), repository_id, file_path (indexed), biomarker_type,
severity, nullable function_name / line_start / line_end, details_json,
health_impact, reason, status, created_at, updated_at. Open rows are rewritten
on init and per changed file on update.
Identity (finding_identity.py): finding_<digest> from the enclosing function or
class plus the line offset (absolute lines at file level), so edits above keep it; only
detail keys that tell findings apart (a coupling partner, an error kind) count, never
metric values. A re-detected triaged row gets fresh evidence: acknowledged and
false_positive stay, resolved reopens.
health_file_metrics
One row per (repository_id, file_path): score; nullable defect_score,
maintainability_score, performance_score; structure_deduction and
history_deduction (null on rows before the split, reported unscored under
counts=code_shape, never a ten); is_test (so scope is one row filter); max_ccn,
max_nesting, nloc; nullable duplication_pct; has_test_file; nullable
line_coverage_pct, branch_coverage_pct; module (community label, else top-level
dir); updated_at.
health_snapshots and coverage_files
Snapshots keep the latest 50 per repo (HEALTH_SNAPSHOT_RETENTION,
crud/analysis/health/snapshots.py). coverage_files is overwritten per coverage add;
its covered_lines_json lets coverage_gap name the exact uncovered surface.
11. CLI surface
commands/health_cmd/ mirrors the dead-code command's Click structure; every flag is in
CLI_REFERENCE.md.
repowise health --file path/to/x.py # one file; --module, --refactoring-targets, --trend
repowise coverage add coverage.xml --format cobertura
repowise status # Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: ...)
repowise update silently re-scores changed files only.
12. MCP surface
get_health(targets?, include?, repo?, limit?)
tool_health/tool.py dispatches per mode and block.
- Dashboard (
targets=None): KPIs withband,distribution,worst_files,top_findings,modules. - Targeted: full
metrics+findingsand atrendsblock for targets with two or more snapshots;module:fooexpands to that module. includeadds blocks and picks the ranked-list dimensions (defect,maintainability,advisory; default defect + maintainability). Flags: MCP_TOOLS.md;request.py::_KNOWN_INCLUDESis the authority (add one inrequest.py,loading.py,blocks.py).
Enrichments on existing tools
get_risk(targets): health_score, top_biomarkers, line_coverage_pct,
branch_coverage_pct. get_context(include=["health"]): score, max_ccn,
max_nesting, nloc, module, duplication_pct, top 2 markers with a suggestion,
coverage and signals. get_overview(): code_health with avg, band, hotspot, worst,
open finding count and files per band. All carry _meta via build_meta().
13. REST surface
server/.../routers/code_health/: one module per surface sharing scope.py, counts.py,
file_filters.py, statuses.py; routes under /api/repos/{repo_id}/health/, auth by
verify_api_key (server/deps.py) at the router.
| Route | Returns |
|---|---|
overview |
summary with band, distribution, worst files, top findings, modules |
badge.svg, badge.json |
flat SVG (N.N/10, no letter); Shields.io payload (schemaVersion/label/message/color/band) |
files, files/breakdown, files/trend |
per-file metrics; one file's breakdown, suggestions, trend, signals; one file's series (?file_path=) |
trend |
KPI history, alerts, last-two-snapshot per-file deltas |
findings |
filter by biomarker_type, file_path, dimension, status, severity or min_severity; performance and advisory only when named or include_zero_impact=true |
coverage (GET, POST) |
summary and rows; ingest a report |
refactoring-targets |
queue by total_impact / effort_bucket (open findings only); findings filters plus search, module, only_hotspots / only_untested / only_failing, limit + offset, total and finding_total |
churn-complexity, modules |
commit_count_90d, max_ccn, nloc, score, churn_percentile per churned file; NLOC-weighted rollup |
| Also | fix-first (and /{fix_id}), map, impact-effort, related-work, tests-reaching, performance-opportunities (and /{opportunity_id}, /findings), coverage/patch, findings/{id} |
ScopeQuery / CountsQuery parse scope and counts wherever they change a figure and
echo them; an unknown value falls back to the default. counts=code_shape projects from
structure_deduction, drops history-derived findings, recomputes totals and rankings,
counts split-less rows in unscored_files, and writes nothing.
14. Web dashboard
packages/web/src/app/repos/[id]/code-health/page.tsx: a map whose lens shows health,
maintainability, performance or churn (paired with ChurnComplexityQuadrant from
churn-complexity), scope and counts controls, and four tabs by ?tab= (tabs.ts): Map
(default, leads with Fix first; triage, heatmap, hotspots, modules, trend alias
to it), Findings, Performance, Dead code. Tests and Security are pages, Doc drift a Docs
view and blast radius the Commits page's "Review a change"; old tab ids (coverage,
security, doc-drift, impact) and /repos/[id]/health/* redirect. Sub-pages:
coverage, refactoring-targets, trend. The file Health tab has the "Functions by
churn" table. Primitives in packages/ui/src/health/ let the hosted frontend/ repo
reuse them.
15. CLAUDE.md integration
The generated CLAUDE.md gets a short ## Code health section
(core/generation/editor_files/data.py, templates/_editor_block.j2) keeping only:
score ≤ 5.0 on a hotspot, a Brain Method with > 10 dependents, any Untested Hotspot, DRY
violations > 70 % similar, a > 1.0 drop over 5 snapshots.
16. Configuration: .repowise/health-rules.json
User-authored (the layer's only JSON file), loaded by HealthConfig.load; globs use
path (aliases path_glob, glob) over repo-relative POSIX paths, every match applies
and disabled sets union; to_analyzer_config() feeds FileEvaluator.evaluate(). Schema:
user guide.
17. Performance
Budget < 30 s on a 3,000-file synthetic repo (test_health_perf_benchmark.py,
-m slow or make health-bench). analyze_async() uses asyncio.gather +
asyncio.to_thread. Duplication is O(total_tokens); scoring is O(findings); the walker
re-parses (~1 ms per file) because ParsedFile keeps no tree-sitter Tree, which a
shared parse cache would remove.
18. Testing
make health-check runs tests/unit/health/, tests/unit/server/test_mcp.py and a
health report. Key suites: test_complexity_walker.py (per-language CCN, nesting,
cognitive); test_<biomarker>.py with test_biomarkers.py, test_structural_biomarkers.py,
test_coverage_biomarkers.py, test_organizational_biomarkers.py,
test_dry_violation.py (two languages positive, one negative); test_duplication.py;
test_coverage_parsers.py; test_scoring.py; test_scoring_snapshot.py (the
stability guard); test_scoring_dimensions.py; test_trends.py; test_signals.py
(no-signal vs real zero, entropy 0-1 to 0-100, owner handoff); test_churn_complexity.py
(no-churn omission, danger-product sort, percentile scaling); test_suggestions.py;
test_health_config.py. Integration: test_health_coverage_integration.py (LCOV ->
coverage_gap) and the perf benchmark.
19. Extension points
- Marker:
biomarkers/<id>.pyimplementingBiomarker.- Append to
_DETECTOR_FACTORIES(registry.py). - List in
scoring._BIOMARKER_DIMENSIONS(unlisted defaults into defect). - Add to its tables:
_BIOMARKER_CATEGORY/_BIOMARKER_WEIGHT_MULTIPLIER,_MAINTAINABILITY_*,_PERFORMANCE_WEIGHT_MULTIPLIER, or_ADVISORY_HOME. - A label in
BIOMARKER_LABELSand a template insuggestions._TEMPLATES. - Three tests: two languages positive, one negative.
- A row in the full roster and
biomarkers/README.md.
- Walker language: one
LanguageNodeMapincomplexity/languages.pymapping node types toBRANCH/LOOP/TRY/BOOLEAN_OP, plus a fixture intests/fixtures/lang_samples/<lang>/; no.scmfiles. - Coverage format: a stdlib-only parser in
coverage/returning aCoverageReport, routed fromcoverage/detector.parse. - Rules key: extend
HealthConfigthroughto_analyzer_config()toFileEvaluator.evaluate(). - Retune:
scoring.CATEGORY_CAPS/_SEVERITY_DEDUCTION(update the snapshot); alerts intrends.DECLINE_THRESHOLD/DECLINE_LOOKBACK; a new entry point callsHealthAnalyzer.analyze()and upserts when incremental.
20. Where the layer deliberately stops
- No LLM in scoring or suggestions:
suggestions.pyis templates; code generation only behind--generate-codeand the opt-ingenerate_refactoring_codetool. - No symbol-level score: files are the refactor unit; symbol CCN feeds it via
all_functions. - No
complexity_estimatebackfill until a re-index. - No predictive ML on trends; commit-level risk is
analysis/change_risk/(repowise risk, a calibrated logistic model). - No letter grade: the 1–10 score and the five bands (
grading.py) are the only scales, and every band word or colour reads that vocabulary.
See also
packages/core/src/repowise/core/analysis/health/README.mdand thecomplexity/,coverage/,duplication/,biomarkers/READMEs.docs/architecture/graph-algorithms.md: the graph layer health depends on.