Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(health): tighten code-health docs, name CodeScene, shift internals to architecture doc (#618)
Raghav Chamadiyab097c3ebdd94
diff --git a/README.md b/README.mdindex 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> · <strong>ROC AUC 0.74 across 21 repos</strong> · <strong>2.3×</strong> the commercial market leader under a fixed review budget<br/>+ <strong>code health that predicts real bugs</strong> · <strong>ROC AUC 0.74 across 21 repos</strong> · <strong>2.3×</strong> CodeScene's defects under a fixed review budget<br/><strong>graph-aware refactoring plans</strong> your agent can execute · <strong>up to −96% context tokens</strong> · <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**: thedefect-calibrated, bug-predictive score in the table below. From the samebiomarker 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 fixin 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.mA health score tells you a file is in trouble. Every other tool stops there, orprints the same static sentence for every god class in every repo. repowise namesthe **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)** · fullreference: **[docs/REFACTORING.md](docs/REFACTORING.md)**---diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.mdindex 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` andare tier-aware and stay silent on ESSENTIAL-tier repos until the per-line blameindex 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.mdindex 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 twoknown-fixture scores. A retune intentionally requires updating thesnapshot 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).---