Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs(health): tighten code-health docs, name CodeScene, shift internals to architecture doc (#618)

Raghav Chamadiyab097c3ebdd94
diff --git a/README.md b/README.md
index d4d9d83e4..befe114f1 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@
<p align="center">
<strong>measure, locate, and fix what your AI ships</strong><br/>
- <strong>code health that predicts real bugs</strong> &nbsp;·&nbsp; <strong>ROC AUC 0.74 across 21 repos</strong> &nbsp;·&nbsp; <strong>2.3×</strong> the commercial market leader under a fixed review budget<br/>
+ <strong>code health that predicts real bugs</strong> &nbsp;·&nbsp; <strong>ROC AUC 0.74 across 21 repos</strong> &nbsp;·&nbsp; <strong>2.3×</strong> CodeScene's defects under a fixed review budget<br/>
<strong>graph-aware refactoring plans</strong> your agent can execute &nbsp;·&nbsp; <strong>up to −96% context tokens</strong> &nbsp;·&nbsp; <strong>−70% agent tool calls</strong> at answer-quality parity
</p>
@@ -117,13 +117,12 @@ scatter, prior-defect history, test-quality smells, and more.
**Three signals, one index.** The headline 1–10 is **defect risk**: the
defect-calibrated, bug-predictive score in the table below. From the same
biomarker stream, repowise surfaces two co-equal companion views:
-**maintainability** (cohesion, brain methods, primitive obsession, DRY and
-god-class smells that raise change-cost without predicting bugs) and
-**performance** (static I/O-in-loop / N+1 risk, including cross-function cases
-caught through the call graph that file-local linters miss: standard linters
-found 0 of those cross-function cases on a 12k-file benchmark where repowise
-surfaced 557). The two companions are separate lenses, never blended into the
-defect headline, so the bug-predictive number stays clean.
+**maintainability** (cohesion, brain methods, DRY and god-class smells that
+raise change-cost without predicting bugs) and **performance** (static N+1 /
+I/O-in-loop risk, followed across files through the call graph: file-local
+linters found 0 of those cross-function cases on a 12k-file benchmark where
+repowise surfaced 557). They are separate lenses, never blended into the defect
+headline, so the bug-predictive number stays clean.
> **Zero LLM calls. Zero cloud requirement. Zero new runtime dependencies.**
> Pure Python over tree-sitter + git data, finishing in **under 30 seconds** on
@@ -144,20 +143,21 @@ in the terminal and on the dashboard: *"16/20 lowest-health files had a bug fix
in the last 6 months, 3.3x the 24% baseline"*. See
[Does the score find the bugs?](docs/CODE_HEALTH.md#does-the-score-find-the-bugs).
-**Does the score actually find bugs? Yes, and it out-ranks the leading
-commercial code-health tool.** On the **same 2,770 files across 9 languages**,
-scored at the same leakage-free commit against the same defect labels:
+**Does the score actually find bugs? Yes, and it out-ranks CodeScene**, the
+leading commercial code-health tool. On the **same 2,770 files across 9
+languages**, scored at the same leakage-free commit against the same defect
+labels:
-| Axis (head-to-head, paired tests) | repowise | Leading commercial tool |
+| Axis (head-to-head, paired tests) | repowise | CodeScene |
|---|---:|---:|
| **Recall @ 20%-of-lines budget** | **0.173** | 0.074 |
| **Effort-aware ranking (Popt)** | **0.607** | 0.462 |
| **Defect density, size-normalized (defects/KLOC, Alert:Healthy)** | **2.18×** | 0.56× |
-| Discrimination (ROC AUC) | **0.731** | 0.705 |
+| Discrimination (ROC AUC) | 0.731 | 0.705 |
Ranking by repowise health surfaces **2.3× the defects under a fixed review
-budget** (Popt Δ +0.144, recall Δ +0.098, density Δ p = 0.003, all paired and
-significant). [Full methodology & CIs →](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/COMPARISON_REPORT.md)
+budget** (Popt Δ +0.144, recall Δ +0.098, density Δ all p = 0.003, paired and
+significant; the ROC AUC edge is marginal). [Full methodology & CIs →](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/COMPARISON_REPORT.md)
User guide & per-biomarker reference: **[docs/CODE_HEALTH.md](docs/CODE_HEALTH.md)**
@@ -166,42 +166,27 @@ User guide & per-biomarker reference: **[docs/CODE_HEALTH.md](docs/CODE_HEALTH.m
A health score tells you a file is in trouble. Every other tool stops there, or
prints the same static sentence for every god class in every repo. repowise names
the **specific** fix, computed deterministically from the graph, the class model,
-and git co-change, the same data the score is built on:
-
-- **Extract Class**: split an incohesive class along its real cohesion groups
- (LCOM4 components): *"these methods + these fields belong together; these don't."*
-- **Extract Helper**: dedup a clone across its exact occurrences, with the
- shared helper placed at the community centroid of the files involved.
-- **Move Method**: relocate a feature-envy method to the class it actually talks
- to (Jaccard distance over the call graph), not the one it lives in.
-- **Break Cycle**: name the minimal set of import edges to invert to break a
- dependency cycle (greedy minimum feedback arc set over the real import graph).
-- **Split File**: decompose an oversized module into cohesive files (community
- detection over its intra-file symbol graph), naming the symbols that move to
- each new file and the import edits in every dependent.
-
-Every plan carries its **blast radius** (the callers and co-changing files that
-must move with it) and is ranked **graph-aware**: `impact × call-graph centrality
-× blast radius`, so a fix on a central hub outranks the same fix on a leaf. That
-is the wedge: the leading commercial tool ranks by churn alone, stays
-within-function, and ignores its own coupling signal when it generates code.
-
-The deterministic plan is the product; the optional LLM code-gen step never runs
-during indexing and fires only on an explicit request. Any plan can then be
-expanded into generated code plus a unified diff, fed the graph and co-change
-context a bare codegen tool throws away.
+and git co-change: **Extract Class**, **Extract Helper**, **Move Method**,
+**Break Cycle**, and **Split File**. Each plan names the exact methods, edges, or
+symbols that move, and carries its **blast radius** (the callers and co-changing
+files that must move with it). Ranking is **graph-aware** (`impact × call-graph
+centrality × blast radius`), so a fix on a central hub outranks the same fix on a
+leaf. That is the wedge: CodeScene's AI refactoring stays within a single
+function, where repowise names the cross-file move and the dependents it ripples
+to.
+
+The deterministic plan is the product; an optional LLM step (never in the
+indexing path, only on explicit request) expands any plan into generated code
+plus a unified diff, fed the graph and co-change context a bare codegen tool
+throws away.
```bash
-repowise health --refactoring-targets # ranked plans, biggest win for least effort
+repowise health --refactoring-targets # ranked plans; get_health(include=["refactoring"]) over MCP
```
-```python
-get_health(include=["refactoring"]) # the same structured plans over MCP
-```
-
-The web **Refactoring** tab renders each plan as a card (the split groups as a
-tree, the move arrow, the clone occurrences with line links) with a
-**copy-to-agent** button and the opt-in **Generate code** diff view. Full
+The web **Refactoring** tab renders each plan as a card with a **copy-to-agent**
+button and the opt-in **Generate code** diff view. Per-detector mechanics:
+**[docs/CODE_HEALTH.md](docs/CODE_HEALTH.md#refactoring-targets)** · full
reference: **[docs/REFACTORING.md](docs/REFACTORING.md)**
---
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.md
index 121287f69..ffe682cdc 100644
--- a/docs/CODE_HEALTH.md
+++ b/docs/CODE_HEALTH.md
@@ -60,23 +60,18 @@ Twenty-five biomarkers across the categories above. `function_hotspot` and
are tier-aware and stay silent on ESSENTIAL-tier repos until the per-line blame
index is built.
-Per-biomarker weight multipliers (see `scoring._BIOMARKER_WEIGHT_MULTIPLIER`)
-let the strongest empirical predictors deduct more than the uniform severity
-table alone allows. These weights are calibrated offline against a defect
-corpus, not hand-tuned: each file is scored at the pre-window commit (T0, no
-leakage) and an L2-logistic regression (with NLOC as an explicit control) fits
-each biomarker's defect lift beyond file size. The runtime stays deterministic;
-only the learned constants ship. The strongest calibrated predictors are
-`co_change_scatter` (1.8), `change_entropy` (1.51), `ownership_risk` (1.38), and
-`nested_complexity` (1.34); the remaining structural complexity and size
-biomarkers land around 1.1 to 1.33. Biomarkers that fire widely but proved weak
-under leakage-free scoring (`developer_congestion`, `dry_violation`,
-`low_cohesion`, `brain_method`, `primitive_obsession`, `bumpy_road`) are floored
-to 0.5, kept as maintainability and parity signals rather than disabled, and
-`knowledge_loss` stays de-rated at 0.4. Coverage-dependent and rarely-firing
-biomarkers (`untested_hotspot` 1.3, `code_age_volatility` 1.1, `churn_risk` 1.2)
-keep prior weights the corpus could not fairly measure. The full calibration,
-with confidence intervals, is published in the [benchmark report](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/BENCHMARK_REPORT.md).
+Per-biomarker weight multipliers let the strongest empirical predictors deduct
+more than the uniform severity table alone allows. The weights are **calibrated
+offline against a defect corpus, not hand-tuned**: each file is scored at the
+pre-window commit (T0, no leakage) and a logistic regression with NLOC as an
+explicit control fits each biomarker's defect lift beyond file size. The runtime
+stays deterministic; only the learned constants ship. The strongest predictors
+are `co_change_scatter`, `change_entropy`, `ownership_risk`, and
+`nested_complexity`; widely-firing smells that proved weak under leakage-free
+scoring are floored. The full per-biomarker table lives in the
+[architecture doc](architecture/code-health.md#61-calibrated-weight-multipliers),
+and the calibration with confidence intervals is in the
+[benchmark report](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/BENCHMARK_REPORT.md).
The final score is clamped to `[1.0, 10.0]`. The three repo-level KPIs:
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index ab98ca581..fbdacbdc2 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -138,8 +138,8 @@ core/alembic/versions/
```
core/pipeline/
-├── orchestrator.py # _run_health_analysis() — builds module_map, runs analyzer
-└── persist.py # persist_pipeline_result() — writes findings/metrics/snapshot
+├── orchestrator.py # _run_health_analysis(): builds module_map, runs analyzer
+└── persist.py # persist_pipeline_result(): writes findings/metrics/snapshot
```
### CLI
@@ -206,7 +206,7 @@ tests/unit/health/ # 99+ tests
├── test_duplication.py # tokenizer, hash, detector
├── test_coverage_parsers.py # LCOV/Cobertura/Clover/JSON
├── test_scoring.py # category caps, clamping
-├── test_scoring_snapshot.py # stability snapshot — locks caps + deductions
+├── test_scoring_snapshot.py # stability snapshot: locks caps + deductions
├── test_health_config.py # .repowise/health-rules.json
├── test_trends.py # diff_snapshots, declining/predicted alerts
├── test_signals.py # file_signals join + no-signal/normalization
@@ -223,128 +223,70 @@ tests/integration/
## 3. The pipeline (init path)
`repowise init` runs `run_pipeline()` in `core/pipeline/orchestrator.py`.
-Health analysis is a phase in that orchestrator, called between
-`_run_dead_code_analysis()` and `_run_decision_extraction()`:
-
-```python
-# orchestrator.py — simplified
-async def _run_health_analysis(graph_builder, git_meta_map, parsed_files, *, repo_path, progress):
- # 1. Build a {file_path → community label} map from the graph.
- # Used to populate HealthFileMetric.module so module rollups
- # aren't NULL.
- cd = graph_builder.community_detection()
- ci = graph_builder.community_info()
- module_map = {nid: ci[cid].label for nid, cid in cd.items() if ci.get(cid)}
-
- # 2. Load per-file override rules from .repowise/health-rules.json
- # (empty / no-op when the file doesn't exist).
- cfg = HealthConfig.load(repo_path)
- analyzer_config = cfg.to_analyzer_config([pf.file_info.path for pf in parsed_files])
-
- # 3. Construct the analyzer with all inputs it needs.
- analyzer = HealthAnalyzer(
- graph_builder.graph(), # NetworkX DiGraph for dependents
- git_meta_map=git_meta_map, # hotspot bit, owners, co-change, bus factor
- parsed_files=parsed_files, # ParsedFile objects from the AST phase
- module_map=module_map, # community labels
- )
-
- # 4. Pick sync vs parallel based on repo size. Tree-sitter releases the
- # GIL during parsing, so asyncio.gather + asyncio.to_thread gives
- # real wall-clock speedup on large repos.
- if len(parsed_files) >= 500:
- report = await analyzer.analyze_async(analyzer_config)
- else:
- report = await asyncio.to_thread(analyzer.analyze, analyzer_config)
-
- return report # carried on PipelineResult.health_report
-```
-
-Then `core/pipeline/persist.py` writes everything in one session:
-
-```python
-# persist.py — simplified
-if result.health_report:
- hr = result.health_report
- await save_health_metrics(session, repo_id, hr.metrics)
- if hr.findings:
- await save_health_findings(session, repo_id, hr.findings)
- # Snapshot for trend tracking — rolling 50-row window per repo.
- await save_health_snapshot(
- session,
- repo_id,
- hotspot_health=hr.kpis["hotspot_health"],
- average_health=hr.kpis["average_health"],
- worst_performer_path=hr.kpis["worst_performer_path"],
- worst_performer_score=hr.kpis["worst_performer_score"],
- per_file_scores={m.file_path: round(m.score, 2) for m in hr.metrics},
- )
-```
+`_run_health_analysis()` is a phase in that orchestrator, called between
+`_run_dead_code_analysis()` and `_run_decision_extraction()`. It does four
+things:
+
+1. Builds a `{file_path: community label}` map from the graph's community
+ detection so `HealthFileMetric.module` is populated (module rollups are
+ never NULL).
+2. Loads per-file override rules from `.repowise/health-rules.json` via
+ `HealthConfig.load(repo_path)` (a no-op when the file is absent) and
+ resolves them to per-file disabled sets with `to_analyzer_config()`.
+3. Constructs the `HealthAnalyzer` with everything it needs: the NetworkX
+ graph (for dependents), `git_meta_map` (hotspot bit, owners, co-change, bus
+ factor), the `parsed_files` from the AST phase, and the module map.
+4. Picks the sync or parallel path by repo size. tree-sitter releases the GIL
+ during parsing, so on repos with `>= 500` parsed files `analyze_async()`
+ (asyncio gather over worker threads) gives a real wall-clock speedup;
+ smaller repos run `analyze()` on a single thread.
+
+The returned report rides on `PipelineResult.health_report`. Then
+`core/pipeline/persist.py` writes it in one session: `save_health_metrics`,
+`save_health_findings` (only when there are findings), and a
+`save_health_snapshot` carrying the three KPIs plus a `{path: score}` map for
+trend tracking (rolling 50-row window per repo).
---
## 4. Inside `HealthAnalyzer.analyze()`
-Single pass over the parsed file list. For each file:
-
-```python
-# engine.py — pseudocode
-1. _walk(pf):
- source = read_bytes(pf.file_info.abs_path)
- walk_file(language, source) → FileComplexity(functions, classes)
- # Each FunctionComplexity carries: name, line range, nloc, ccn,
- # max_nesting, cognitive, bumps, param_count.
- # Each ClassComplexity carries: name, line range, method_count,
- # total_nloc, methods, lcom4, max_method_ccn, field_count.
-
-2. _populate_symbol_complexity(pf, fcx.functions):
- # Side effect: write max(ccn) into Symbol.complexity_estimate so
- # the ContextAssembler symbol ranker benefits even when callers
- # don't query the health tables directly.
-
-3. _evaluate_file(pf, fcx, ...):
- # Build a FileContext with:
- # - nloc, has_test_file, module
- # - function_metrics: dict[symbol_name → FunctionComplexity]
- # - class_metrics: list[ClassComplexity] (LCOM4 / god-class)
- # - git_meta: per-file dict (hotspot, owners, bus factor, ...)
- # - dependents_count: in_degree on the graph
- # - repo_dependents_p80: repo-wide p80 of in-degree (brain_method floor)
- # - line_coverage_pct, branch_coverage_pct, covered_lines (when ingested)
- # - clones, duplication_pct (from cross-file detect_clones())
- results = detect_all(ctx, disabled=file_disabled)
- score, deductions = score_file(results)
- findings = attach_impacts(results, deductions)
- metric = HealthFileMetricData(...)
-```
-
-After the loop:
-
-```python
-hotspot_paths = {p for p, meta in git_meta_map.items() if meta.get("is_hotspot")}
-kpis = compute_kpis(metrics, hotspot_paths)
-return HealthReport(findings=..., metrics=..., kpis=kpis)
-```
-
-Duplication runs **once up-front** (cross-file by nature). Each `FileContext`
-gets a slice of the global clone report. The `dry_violation` biomarker
-reads `ctx.clones` to rank pairs by co-change frequency from
-`git_meta_map[path]["co_change_partners_json"]`: active clones rank
-higher than dormant ones.
+A single pass over the parsed file list. For each file the analyzer:
+
+1. **Walks the AST** (`_walk`): `walk_file(language, source)` returns a
+ `FileComplexity` of functions and classes. Each `FunctionComplexity` carries
+ name, line range, nloc, ccn, max nesting, cognitive complexity, bumps, and
+ param count; each `ClassComplexity` carries method count, total nloc, the
+ method list, LCOM4, max method ccn, and field count.
+2. **Populates symbol complexity** (`_populate_symbol_complexity`): writes
+ `max(ccn)` into `Symbol.complexity_estimate` as a side effect, so the
+ `ContextAssembler` symbol ranker benefits even when a caller never touches
+ the health tables.
+3. **Evaluates the file** (`_evaluate_file`): builds a `FileContext` (nloc,
+ `has_test_file`, module, per-function and per-class metrics, the per-file
+ `git_meta`, graph in-degree as `dependents_count`, the repo-wide p80 of
+ in-degree used as the `brain_method` floor, coverage fields when ingested,
+ and the file's clone slice), runs `detect_all()`, scores with `score_file()`,
+ and attaches per-finding impacts.
+
+After the loop, `compute_kpis()` runs over the metrics and the set of hotspot
+paths (`git_meta_map[path]["is_hotspot"]`), and the analyzer returns a
+`HealthReport(findings, metrics, kpis)`.
+
+Duplication runs **once up-front** (it is cross-file by nature); each
+`FileContext` gets a slice of the global clone report. The `dry_violation`
+biomarker reads `ctx.clones` and ranks pairs by co-change frequency from
+`git_meta_map[path]["co_change_partners_json"]`, so active clones rank higher
+than dormant ones.
---
## 5. The 26 biomarkers and their categories
-Each biomarker is a stateless class implementing the `Biomarker` Protocol
-from `biomarkers/base.py`:
-
-```python
-class Biomarker(Protocol):
- name: str # "brain_method", "nested_complexity", ...
- category: str # see scoring.CATEGORY_CAPS
- def detect(self, ctx: FileContext) -> list[BiomarkerResult]: ...
-```
+Each biomarker is a stateless class implementing the `Biomarker` Protocol from
+`biomarkers/base.py`: a `name` (`"brain_method"`, `"nested_complexity"`, ...), a
+`category` (see `scoring.CATEGORY_CAPS`), and a `detect(ctx: FileContext)` method
+returning a list of `BiomarkerResult`s.
| Category | Cap | Biomarkers |
|------------------------|------|------------|
@@ -490,19 +432,14 @@ via `registered_biomarkers(extra=...)`.
## 6. Scoring (`scoring.py`)
Every file starts at **10.0**. Each finding contributes a per-severity
-deduction (`low=0.3, medium=0.7, high=1.2, critical=2.0`). Deductions are
-**capped per category**, so even ten critical structural findings can
-drive structural complexity down by at most 3.5 points, not 20.
-
-```python
-# scoring.py — score_file()
-1. Group findings by category.
-2. Sum raw deductions per category.
-3. If sum ≤ cap, accept; else scale every per-finding deduction
- proportionally so the total equals the cap. This keeps the UI
- "this finding cost you X points" honest after capping.
-4. Clamp the final score to [1.0, 10.0].
-```
+deduction (`low=0.3, medium=0.7, high=1.2, critical=2.0`), scaled by the
+biomarker's calibrated weight multiplier (§6.1). `score_file()` then groups the
+weighted findings by category, sums the raw deductions per category, and either
+accepts the sum or, when it exceeds the cap, scales every per-finding deduction
+in that category proportionally so the total equals the cap. This keeps the
+UI's "this finding cost you X points" honest after capping. The final score is
+clamped to `[1.0, 10.0]`. So even ten critical structural findings can drive
+structural complexity down by at most 3.5 points, not 20.
The per-finding scaled deduction lands on `HealthFinding.health_impact`
via `attach_impacts()`: that's what the dashboard's "−2.0" badge shows.
@@ -512,6 +449,38 @@ category caps, severity deductions, biomarker-to-category mapping, and two
known-fixture scores. A retune intentionally requires updating the
snapshot in the same PR.
+### 6.1 Calibrated weight multipliers
+
+`scoring._BIOMARKER_WEIGHT_MULTIPLIER` lets the strongest empirical predictors
+deduct more than the uniform severity table alone allows. The multipliers are
+**calibrated offline against a defect corpus, not hand-tuned**: each file is
+scored at the pre-window commit (T0, no leakage) and an L2-logistic regression,
+with NLOC as an explicit control, fits each biomarker's defect lift beyond file
+size. The runtime stays deterministic; only the learned constants ship. The
+full calibration, with confidence intervals, is published in the
+[benchmark report](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/BENCHMARK_REPORT.md)
+and reproduced by `local-stash/calibrate_health_weights.py`.
+
+| Weight | Biomarkers | Rationale |
+|---|---|---|
+| 1.8 | `co_change_scatter` | Strongest calibrated predictor. |
+| 1.51 | `change_entropy` | History Complexity Metric; second strongest. |
+| 1.38 | `ownership_risk` | Long-run minor-contributor dispersion. |
+| 1.34 | `nested_complexity` | Strongest structural predictor. |
+| 1.1–1.33 | remaining structural complexity / size biomarkers | Moderate calibrated lift. |
+| 1.3 / 1.2 / 1.1 | `untested_hotspot` / `churn_risk` / `code_age_volatility` | Coverage-dependent and rarely-firing; keep prior weights the corpus could not fairly measure. |
+| 1.0 | `prior_defect` | Neutral by design: largely redundant with the other process signals, kept for its explanatory value. |
+| 0.5 (floored) | `developer_congestion`, `dry_violation`, `low_cohesion`, `brain_method`, `primitive_obsession`, `bumpy_road` | Fire widely but proved weak under leakage-free scoring; kept as maintainability and parity signals, not disabled. |
+| 0.4 (de-rated) | `knowledge_loss` | Weakest of the floored set. |
+
+The same biomarker stream feeds the **maintainability** signal under an
+independent, expert-set weight table (the floored smells deduct at full weight
+there), and the **performance** signal under its own bounded `performance`
+category. The three signals share one scoring kernel against separate
+weight/category/cap tables and never feed back into each other; see the
+[user guide](../CODE_HEALTH.md#three-health-signals-defect-risk-maintainability-and-performance)
+for what each signal surfaces and why the overall score stays the defect score.
+
---
## 7. KPIs
@@ -587,34 +556,20 @@ as `FileSignals` in `@repowise-dev/types/health`; rendered by the shared
## 9. Incremental analysis: the `repowise update` path
-Full re-analysis would be wasteful on commit-sized diffs. `HealthAnalyzer`
-accepts `changed_files`:
-
-```python
-# engine.py
-def analyze(self, config=None, *, changed_files=None):
- # 1. Duplication still runs full-repo (a changed file's clone
- # partner may be unchanged).
- # 2. The per-file loop skips files not in changed_files.
- # 3. KPIs are NOT recomputed on incremental runs — they'd be biased
- # by the subset. The dashboard recomputes from the merged DB rows.
-```
+Full re-analysis would be wasteful on commit-sized diffs, so
+`HealthAnalyzer.analyze()` accepts a `changed_files` set. When it is present:
+duplication still runs full-repo (a changed file's clone partner may be
+unchanged); the per-file loop skips files not in `changed_files`; and the KPIs
+are **not** recomputed, since the subset would bias them. The dashboard
+recomputes KPIs from the merged DB rows instead.
`update_cmd.py` builds the changed-files set from
-`change_detector.get_changed_files()`, runs the analyzer, and calls a
-helper that uses the **upsert** variants (`upsert_health_findings`,
-`upsert_health_metrics`) so unchanged files keep their existing rows:
-
-```python
-async def _persist_partial_health(session, repo_id, report):
- changed_paths = sorted({m.file_path for m in report.metrics})
- await upsert_health_metrics(session, repo_id, report.metrics)
- await upsert_health_findings(session, repo_id, report.findings, file_paths=changed_paths)
-```
-
-The full-init writers (`save_health_findings`, `save_health_metrics`)
-still use delete-then-insert: simpler, and the cost is amortised across
-the whole `repowise init`.
+`change_detector.get_changed_files()`, runs the analyzer, and persists through a
+helper that uses the **upsert** variants (`upsert_health_metrics`,
+`upsert_health_findings`, scoped to the changed paths) so unchanged files keep
+their existing rows. The full-init writers (`save_health_findings`,
+`save_health_metrics`) still use delete-then-insert: simpler, and the cost is
+amortised across the whole `repowise init`.
---
@@ -809,29 +764,14 @@ agent in noise. The Jinja stanza lives in
## 16. Configuration: `.repowise/health-rules.json`
-User-authored (the **only** JSON file in the layer). Loaded by
-`HealthConfig.load(repo_path)`:
-
-```json
-{
- "disabled_biomarkers": ["primitive_obsession"],
- "rules": [
- {
- "path": "tests/**/*.py",
- "disabled_biomarkers": ["large_method", "complex_method"]
- },
- {
- "path": "src/legacy/**",
- "disabled_biomarkers": ["dry_violation"]
- }
- ]
-}
-```
-
-`path` is an fnmatch glob over the repo-relative POSIX path; `path_glob`
-and `glob` are accepted aliases. `to_analyzer_config(file_paths)` resolves
-globs to per-file disabled sets, which the engine honors in
-`_evaluate_file()`.
+`.repowise/health-rules.json` is user-authored (the **only** JSON file in the
+layer) and is loaded by `HealthConfig.load(repo_path)`. It carries repo-wide and
+per-path `disabled_biomarkers` and `severity_overrides`, keyed by an fnmatch
+glob over the repo-relative POSIX path (`path`, with `path_glob` and `glob` as
+accepted aliases). `to_analyzer_config(file_paths)` resolves the globs to
+per-file disabled sets, which the engine honors in `_evaluate_file()`. The
+schema and examples are in the
+[user guide](../CODE_HEALTH.md#configuration).
---