feat(health): error-handling maintainability biomarker (#453)

Surface swallowed-exception and unsafe-unwrap anti-patterns as a bounded
maintainability finding: empty/trivial catch or except bodies across
Python/JS/TS/Java/Kotlin/C#/C++, Python catch-all except, Rust
unwrap/expect/panic-family macros, and Go empty if-err blocks or
blank-identifier discards of a call result.

- complexity walker: whole-tree anti-pattern pass emitting per-hit line
  anchors (precision-first; unsupported language or parse failure yields
  no signal, never a guess)
- new error_handling biomarker: one LOW finding per occurrence
- scoring: own error_handling category capped at 0.5 with a floored 0.5
  weight (0.15 per finding), so the deduction is advisory and can never
  squeeze the calibrated predictive categories; deliberately excluded
  from the defect-weight calibration roster
- 24 detector fixtures across 11 languages ported as unit tests, plus
  scoring snapshot updates and doc updates

Validated by re-scoring the cached 21-repo / 9-language T0 defect
benchmark with the new findings: corpus AUC delta +0.0000 [-0.0036,
+0.0037] under keyword labels and +0.0004 [-0.0037, +0.0038] under SZZ
labels (neutral by design), no per-language regression beyond noise,
max per-file score movement exactly the 0.5 cap. Health perf gate and
full unit suite pass.

Author: RaghavChamadiya

docs/CODE_HEALTH.md

@@ -35,8 +35,9 @@ most:
 | Size & complexity      | −1.5  | complex_method, large_method, primitive_obsession |
 | Duplication            | −1.0  | dry_violation |
 | Test quality           | −0.5  | large_assertion_block, duplicated_assertion_block |
+| Error handling         | −0.5  | error_handling |
 
-Twenty-five biomarkers across the categories above. `function_hotspot` and
+Twenty-six biomarkers across the categories above. `function_hotspot` and
 `code_age_volatility` are blame-based and sit in the organizational bucket —
 both are tier-aware and stay silent on ESSENTIAL-tier repos until the per-line
 blame index is built.
@@ -227,6 +228,19 @@ that overlap an assertion block on a test file. A change to the asserted
 behaviour then has to be edited in several places — and usually isn't, so the
 copies drift.
 
+**error_handling** — Swallowed-exception and unsafe-unwrap anti-patterns: an
+empty or comment-only `catch`/`except` body, a Python catch-all `except:` /
+`except Exception:`, Rust `.unwrap()` / `.expect()` / `panic!`-family macros,
+and Go's empty `if err != nil {}` or blank-identifier discard of a call's
+error. Detection is precision-first — only the unambiguous shapes fire, and an
+unsupported language or parse failure yields no signal rather than a guess.
+Each occurrence is a LOW finding anchored to its line, and the whole category
+is capped at −0.5 per file: this is an advisory maintainability flag (every
+linter is expected to surface `except: pass`), deliberately not a calibrated
+defect predictor — on the 21-repo benchmark it is AUC-neutral, so it is
+excluded from the weight calibration and bounded so it can never move a file's
+score by more than half a point.
+
 ## Test coverage
 
 Pass coverage reports straight into the analyzer:
@@ -332,7 +346,7 @@ Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: payments/processor.ts)
 
 | Feature                          | Repowise | CodeScene | DeepSource | Sourcery |
 |----------------------------------|:--:|:--:|:--:|:--:|
-| Code health score (1–10)         | ✅ 25 biomarkers | ✅ 25–30 | ❌ | ❌ |
+| Code health score (1–10)         | ✅ 26 biomarkers | ✅ 25–30 | ❌ | ❌ |
 | Brain Method detection           | ✅ | ✅ | ❌ | ❌ |
 | Low cohesion (LCOM4) / god class  | ✅ | ✅ | ❌ | ❌ |
 | Test coverage intelligence       | ✅ LCOV/Cobertura/Clover/JSON | ❌ | ❌ | ❌ |

docs/architecture/code-health.md

@@ -110,7 +110,8 @@ analysis/health/
     ├── ownership_risk.py
     ├── churn_risk.py
     ├── change_entropy.py
-    └── co_change_scatter.py
+    ├── co_change_scatter.py
+    └── error_handling.py
 ```
 
 ### Persistence
@@ -317,7 +318,7 @@ higher than dormant ones.
 
 ---
 
-## 5. The 25 biomarkers and their categories
+## 5. The 26 biomarkers and their categories
 
 Each biomarker is a stateless class implementing the `Biomarker` Protocol
 from `biomarkers/base.py`:
@@ -338,6 +339,7 @@ class Biomarker(Protocol):
 | Size & complexity      | −1.5 | complex_method, large_method, primitive_obsession |
 | Duplication            | −1.0 | dry_violation |
 | Test quality           | −0.5 | large_assertion_block, duplicated_assertion_block |
+| Error handling         | −0.5 | error_handling |
 
 `large_assertion_block` and `duplicated_assertion_block` are the two
 **test-quality** smells (see §5.3). They fire only on test files and sit in
@@ -431,6 +433,23 @@ references (a static utility, or an unmapped language) reports `lcom4 = 1`
 turn signal on — never produce a false-positive flood. See
 `complexity/README.md` for the full heuristic and its limits.
 
+`error_handling` is the **advisory maintainability** biomarker: swallowed
+catches (an empty/comment-only `catch` / `except: pass` body), Python
+catch-all `except:` / `except Exception:`, Rust `.unwrap()` / `.expect()` /
+panic-family macros, and Go's empty `if err != nil {}` or blank-identifier
+discard of a call's error. The walker collects each occurrence (with its
+line) in a whole-tree pass — module-level code included — reusing the
+`LanguageNodeMap` catch kinds for the seven catch-shaped languages and
+dedicated recognizers for Rust/Go; an unsupported language or parse failure
+yields no hits ("no signal", never a guess). The biomarker emits one LOW
+finding per occurrence (0.15 after its floored 0.5 weight) in its own
+`error_handling` category capped at −0.5, mirroring `test_quality`'s
+advisory framing. It is deliberately **excluded from the defect-weight
+calibration**: on the 21-repo / 9-language T0 benchmark it is AUC-neutral
+(OOF delta ≈ 0, CI crosses zero) but size-orthogonal and the least redundant
+signal tested, and it ships because users expect `except: pass` flagged —
+bounded so it can never move a file by more than half a point.
+
 ### 5.3 Assertion-block walker metrics (test-quality)
 
 The same single walker pass records `assertion_blocks` on each

packages/core/src/repowise/core/analysis/health/biomarkers/README.md

@@ -9,7 +9,7 @@ class Biomarker(Protocol):
     def detect(self, ctx: FileContext) -> list[BiomarkerResult]: ...
 ```
 
-## Registered detectors (24)
+## Registered detectors (26)
 
 Structural complexity (cap −2.5):
 - `brain_method` — symbols simultaneously long, complex, and central. The
@@ -83,6 +83,20 @@ Test quality (cap −0.5, test files only):
 - `duplicated_assertion_block` — copy-pasted assertion runs across tests,
   found by intersecting the clone detector with assertion spans.
 
+Error handling (cap −0.5, own category `error_handling`):
+- `error_handling` — swallowed-exception / unsafe-unwrap anti-patterns: an
+  empty or trivial `catch`/`except` body (Python/JS/TS/Java/Kotlin/C#/C++), a
+  Python catch-all `except:` / `except Exception:`, Rust `.unwrap()` /
+  `.expect()` / panic-family macros, and Go's empty `if err != nil {}` or
+  blank-identifier discard of a call's error. One LOW finding per occurrence
+  (0.15 after the floored 0.5 weight), bounded at 0.5/file by the category
+  cap. **A maintainability flag, not a defect predictor** — AUC-neutral on
+  the 21-repo T0 benchmark and deliberately excluded from the defect
+  calibration roster; it ships because developers expect a health tool to
+  flag `except: pass`. Detection is precision-first (unambiguous shapes only;
+  unsupported language / parse failure ⇒ no signal) and runs as a whole-tree
+  pass in the complexity walker, so module-level code is covered too.
+
 Caps were recalibrated to lift `organizational` (was −1.0) and de-rate
 `size_and_complexity` / `duplication` per plan §3.1. A per-biomarker
 weight multiplier in `scoring._BIOMARKER_WEIGHT_MULTIPLIER` lets the
@@ -110,6 +124,8 @@ table alone would allow.
   graph; `None` on test fixtures that didn't construct a graph.
 - `repo_commit_counts` — `dict[path, commit_count_total]` populated once
   per `analyze` call so co-change detectors can look up partner totals.
+- `error_handling_hits` — `list[ErrorHandlingHit]` (kind + line) from the
+  walker's whole-tree anti-pattern pass; empty means "no signal".
 
 ## Outputs
 

packages/core/src/repowise/core/analysis/health/biomarkers/base.py

@@ -6,7 +6,7 @@
 from typing import Any, Protocol
 
 from ....ingestion.git_indexer.function_blame import BlameIndex
-from ..complexity import ClassComplexity, FunctionComplexity
+from ..complexity import ClassComplexity, ErrorHandlingHit, FunctionComplexity
 from ..duplication import ClonePair
 from ..models import Severity
 
@@ -95,6 +95,12 @@ class FileContext:
     # ownership findings are downgraded to informational severity unless
     # corroborated (issue #361).
     repo_active_contributors_90d: int | None = None
+    # Error-handling anti-pattern occurrences (swallowed catch, bare
+    # except, unsafe unwrap, discarded Go error) collected by the
+    # complexity walker's whole-tree pass. Empty when the language is
+    # unsupported or parsing failed — the documented "no signal" outcome.
+    # Consumed by the ``error_handling`` biomarker.
+    error_handling_hits: list[ErrorHandlingHit] = field(default_factory=list)
 
 
 # A repo whose trailing-90-day window has at most this many active human

packages/core/src/repowise/core/analysis/health/biomarkers/error_handling.py

@@ -0,0 +1,56 @@
+"""Error Handling — swallowed-exception / unsafe-unwrap anti-patterns.
+
+Surfaces the error-handling smells every linter is expected to flag: an
+empty ``catch`` / ``except: pass``, a Python catch-all ``except:``, a
+Rust ``.unwrap()`` / ``panic!``, a Go error checked-then-ignored or
+discarded via the blank identifier. One LOW finding per occurrence, each
+anchored to its line.
+
+This is a bounded maintainability signal, NOT a defect predictor: on the
+21-repo / 9-language T0 benchmark it is AUC-neutral (OOF delta ~0, CI
+crosses zero) but size-orthogonal and the least redundant signal tested
+(max |rho| ~0.21 vs the calibrated roster; churn rho ~0.02). It therefore
+ships in its own ``error_handling`` category with an advisory 0.5 cap and
+a floored 0.5 weight, and is excluded from the defect-calibration roster.
+
+Detection happens in the complexity walker's whole-tree pass (see
+``complexity.walker._collect_error_handling``); this detector just lifts
+the pre-collected hits into findings. Precision-first: unsupported
+languages and parse failures yield zero hits, never a false positive.
+"""
+
+from __future__ import annotations
+
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+_REASONS: dict[str, str] = {
+    "swallowed_catch": "caught exception is swallowed without any handling",
+    "bare_except": "catch-all except hides every error, including KeyboardInterrupt",
+    "unsafe_unwrap": "unwrap/expect/panic turns a recoverable error into a crash",
+    "go_swallow": "error value is checked then ignored, or discarded via the blank identifier",
+}
+
+
+class ErrorHandlingDetector:
+    name = "error_handling"
+    category = "error_handling"
+
+    def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+        out: list[BiomarkerResult] = []
+        for hit in ctx.error_handling_hits:
+            out.append(
+                BiomarkerResult(
+                    biomarker_type=self.name,
+                    severity=Severity.LOW,
+                    function_name=None,
+                    line_start=hit.line,
+                    line_end=hit.line,
+                    details={"kind": hit.kind},
+                    reason=_REASONS.get(hit.kind, hit.kind),
+                )
+            )
+        return out
+
+
+BIOMARKER = ErrorHandlingDetector()

packages/core/src/repowise/core/analysis/health/biomarkers/registry.py

@@ -25,6 +25,7 @@
 from .developer_congestion import DeveloperCongestionDetector
 from .dry_violation import DryViolationDetector
 from .duplicated_assertion_block import DuplicatedAssertionBlockDetector
+from .error_handling import ErrorHandlingDetector
 from .function_hotspot import FunctionHotspotDetector
 from .god_class import GodClassDetector
 from .hidden_coupling import HiddenCouplingDetector
@@ -64,6 +65,7 @@
     PriorDefectDetector,  # type: ignore[list-item]
     LargeAssertionBlockDetector,  # type: ignore[list-item]
     DuplicatedAssertionBlockDetector,  # type: ignore[list-item]
+    ErrorHandlingDetector,  # type: ignore[list-item]
 ]
 
 

packages/core/src/repowise/core/analysis/health/complexity/__init__.py

@@ -5,6 +5,7 @@
 from .walker import (
     ClassComplexity,
     ConditionComplexity,
+    ErrorHandlingHit,
     FileComplexity,
     FunctionComplexity,
     walk_file,
@@ -14,6 +15,7 @@
 __all__ = [
     "ClassComplexity",
     "ConditionComplexity",
+    "ErrorHandlingHit",
     "FileComplexity",
     "FunctionComplexity",
     "walk_file",