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
fix(health): skip cancellation catches and documented fallbacks in error_handling, state facts in idiom reasons (#4755)
Raghav Chamadiyaeb5ed4b7e3b2
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/error_handling.py b/packages/core/src/repowise/core/analysis/health/biomarkers/error_handling.pyindex 9ec4663aa..1a872f225 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/error_handling.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/error_handling.py@@ -33,25 +33,16 @@ _REASONS: dict[str, str] = {"go_swallow": "error value is checked then ignored, or discarded via the blank identifier",}-# Rust invariant assertions (``complexity.rust_unwrap``): true, idiomatic, low-# priority. They keep their kind (and so their id) but say what they are and-# deduct nothing from the score.+# Rust invariant assertions (``complexity.rust_unwrap``). They keep their kind+# (and so their id), state what the call asserts and deduct nothing, like the+# advisory markers._IDIOM_REASONS: dict[str, str] = {"lock_poison": (- "unwrapping a lock panics only if another thread panicked while holding it "- "(idiomatic poison propagation, low priority)"- ),- "thread_join": (- "unwrapping a thread join re-raises that thread's panic (idiomatic, low priority)"- ),- "invariant_expect": (- "expect panics with its stated message on failure, the usual form when "- "failure is a bug or makes start-up impossible (often idiomatic, low priority)"- ),- "unreachable": (- "unreachable! asserts this branch cannot run and panics only if it does "- "(often idiomatic, low priority)"+ "unwrapping a lock panics only if another thread panicked while holding it"),+ "thread_join": "unwrapping a thread join re-raises that thread's panic",+ "invariant_expect": "expect panics with its stated message on a None or Err",+ "unreachable": "unreachable! asserts this branch cannot run and panics only if it does",}diff --git a/packages/core/src/repowise/core/analysis/health/complexity/error_handling.py b/packages/core/src/repowise/core/analysis/health/complexity/error_handling.pyindex 248d9c533..6c797a340 100644--- a/packages/core/src/repowise/core/analysis/health/complexity/error_handling.py+++ b/packages/core/src/repowise/core/analysis/health/complexity/error_handling.py@@ -36,6 +36,25 @@ RUST_PANIC_MACROS = frozenset({"panic", "unreachable", "todo", "unimplemented"})#: Python handler types that catch every ordinary exception; only the second#: also catches the interpreter's exit signals.PY_CATCH_ALL = ("Exception", "BaseException")+# Cancellation is a stop signal, not an error: dropping it after cancelling a+# task is deliberate, so a handler catching only these is not swallowing.+_CANCEL_TYPES = {+ "python": frozenset({"CancelledError"}),+ "csharp": frozenset({"OperationCanceledException", "TaskCanceledException"}),+}+# A docstring or comment that states the handler's fallback: "best-effort",+# "never raises", "returns None on failure", "falls back to X if it cannot".+# The failure condition must follow within one clause, so "returns X if the key+# exists; raises on error" and "does not raise ValueError" do not match.+_FALLBACK_DOC_RE = re.compile(+ r"best[- ]effort"+ r"|\b(?:never|does\s+not|doesn't|will\s+not|won't)\s+raises?"+ r"(?=\s*(?:[.;,]|$|(?:an?|any)\s+(?:exception|error)))"+ r"|\b(?:returns?|returning|fall(?:s|ing)?\s+back)\b[^.;,]{0,60}?"+ r"(?:\b(?:on|upon)\s+(?:any\s+)?(?:failure|errors?|exceptions?)\b"+ r"|\b(?:if|when)\s+(?:\w+\s+){0,4}?(?:fails?|failed|cannot|can't|could\s+not|couldn't)\b)",+ re.IGNORECASE | re.MULTILINE,+)def _eh_text(node: Node) -> str:@@ -128,6 +147,88 @@ def _eh_catches_base(clause: Node) -> bool:return is_catch_all and name != PY_CATCH_ALL[0]+def _eh_csharp_caught_types(clause: Node) -> list[Node]:+ decl = next((c for c in clause.children if c.type == "catch_declaration"), None)+ typ = decl.child_by_field_name("type") if decl is not None else None+ return [typ] if typ is not None else []+++def _eh_caught_types(clause: Node, language: str) -> list[Node]:+ """The type nodes a Python ``except`` or C# ``catch`` clause names."""+ if language == "csharp":+ return _eh_csharp_caught_types(clause)+ types: list[Node] = []+ for node in _eh_named(clause):+ if node.type in _EH_BLOCK_KINDS or node.type == "comment":+ continue+ if node.type == "as_pattern" and _eh_named(node):+ node = _eh_named(node)[0]+ # ``(A, B)``, or the parenthesis-free ``except A, B:`` of Python 3.14.+ if node.type in ("tuple", "parenthesized_expression", "expression_list"):+ types += _eh_named(node)+ else:+ types.append(node)+ return types+++def _eh_catches_only_cancellation(clause: Node, language: str) -> bool:+ """``except asyncio.CancelledError`` / C# ``catch (OperationCanceledException)``."""+ names = _CANCEL_TYPES.get(language)+ if names is None:+ return False+ types = _eh_caught_types(clause, language)+ return bool(types) and all(_eh_text(t).rsplit(".", 1)[-1] in names for t in types)+++def _eh_docstring(func: Node) -> str:+ body = func.child_by_field_name("body")+ first = _eh_named(body)[0] if body is not None and _eh_named(body) else None+ if first is None or first.type != "expression_statement":+ return ""+ inner = _eh_named(first)+ return _eh_text(inner[0]) if inner and inner[0].type == "string" else ""+++def _eh_comments_above(stmt: Node) -> list[str]:+ """The run of comments directly above *stmt*."""+ sib = stmt.prev_sibling+ if sib is None and stmt.parent is not None:+ # A comment opening a block parses as a sibling of that block.+ sib = stmt.parent.prev_sibling+ texts: list[str] = []+ while sib is not None and sib.type == "comment":+ texts.append(_eh_text(sib))+ sib = sib.prev_sibling+ return texts+++def _eh_enclosing_docstring(node: Node) -> str:+ cur: Node | None = node+ while cur is not None and cur.type not in ("function_definition", "class_definition"):+ cur = cur.parent+ return _eh_docstring(cur) if cur is not None and cur.type == "function_definition" else ""+++def _eh_fallback_doc_texts(clause: Node, block: Node | None) -> list[str]:+ """Python text that can document a handler's fallback: comments on the+ ``except`` line and in its body, comments directly above the ``try``, and+ the enclosing function's docstring."""+ nodes = list(clause.children) + (list(block.children) if block is not None else [])+ texts = [_eh_text(c) for c in nodes if c.type == "comment"]+ if clause.parent is not None:+ texts += _eh_comments_above(clause.parent)+ texts.append(_eh_enclosing_docstring(clause))+ return texts+++def _eh_documented_fallback(clause: Node, block: Node | None) -> bool:+ """The handler ends in ``return`` and its fallback is documented."""+ real = _eh_real_stmts(block, "python") if block is not None else []+ if not real or real[-1].type != "return_statement":+ return False+ return any(_FALLBACK_DOC_RE.search(t) for t in _eh_fallback_doc_texts(clause, block))++def _eh_rust_attr_is_test(attr_text: str) -> bool:"""True when a Rust attribute marks test-only code.@@ -315,9 +416,12 @@ def _eh_swallow_allowed(noqa_codes: set[str] | None) -> bool:return noqa_codes is None or (len(noqa_codes) > 0 and "S110" not in noqa_codes)-def _eh_broad_except_hit(node: Node, noqa_codes: set[str] | None) -> ErrorHandlingHit | None:+def _eh_broad_except_hit(+ node: Node, block: Node | None, noqa_codes: set[str] | None+) -> ErrorHandlingHit | None:"""The bare/broad except hit for a Python clause that does not re-raise,- unless its noqa codes suppress that kind."""+ unless its noqa codes suppress that kind or, for ``except Exception``, the+ fallback it returns is documented."""# ``except:`` / ``except BaseException:`` also swallow# KeyboardInterrupt & SystemExit; ``except Exception:`` cannot.is_base = _eh_catches_base(node)@@ -327,7 +431,17 @@ def _eh_broad_except_hit(node: Node, noqa_codes: set[str] | None) -> ErrorHandlior (kind == "broad_except" and "BLE001" in noqa_codes)or (kind == "bare_except" and bool(noqa_codes & {"BLE001", "E722"})))- return None if suppress else ErrorHandlingHit(kind, node.start_point[0] + 1)+ if suppress or (kind == "broad_except" and _eh_documented_fallback(node, block)):+ return None+ return ErrorHandlingHit(kind, node.start_point[0] + 1)+++def _eh_swallow_expected(node: Node, language: str) -> bool:+ """An empty handler that is the intended landing spot: a Java/Apex test's+ expected throw, or a caught cancellation."""+ if language in ("java", "apex"):+ return _eh_java_try_ends_in_fail(node, language)+ return _eh_catches_only_cancellation(node, language)def _eh_catch_visit(node: Node, language: str, hits: list[ErrorHandlingHit]) -> None:@@ -339,7 +453,7 @@ def _eh_catch_visit(node: Node, language: str, hits: list[ErrorHandlingHit]) ->block is not Noneand _eh_body_is_swallowed(block, language)and swallowed_unsuppressed- and not (language in ("java", "apex") and _eh_java_try_ends_in_fail(node, language))+ and not _eh_swallow_expected(node, language)):hits.append(ErrorHandlingHit("swallowed_catch", node.start_point[0] + 1))if (@@ -347,7 +461,7 @@ def _eh_catch_visit(node: Node, language: str, hits: list[ErrorHandlingHit]) ->and _eh_is_bare_except(node)and not _eh_body_ends_in_raise(block, language)):- hit = _eh_broad_except_hit(node, noqa_codes)+ hit = _eh_broad_except_hit(node, block, noqa_codes)if hit is not None:hits.append(hit)diff --git a/tests/unit/health/test_error_handling.py b/tests/unit/health/test_error_handling.pyindex d6d492c83..60b7023e6 100644--- a/tests/unit/health/test_error_handling.py+++ b/tests/unit/health/test_error_handling.py@@ -358,7 +358,9 @@ def test_idiomatic_hit_is_labelled_and_not_scored():idiomatic, plain = ErrorHandlingDetector().detect(ctx)assert idiomatic.details == {"kind": "unsafe_unwrap", "idiom": "lock_poison", "deduction": 0.0}assert idiomatic.deduction == 0.0- assert "idiomatic" in idiomatic.reason+ assert idiomatic.reason == (+ "unwrapping a lock panics only if another thread panicked while holding it"+ )assert plain.details == {"kind": "unsafe_unwrap"}assert plain.deduction is Noneassert plain.reason == "unwrap/expect turns a recoverable error into a crash"@@ -430,3 +432,113 @@ def test_python_noqa_suppression(source: bytes, expected: dict, note: str):for h in hits:by_kind[h.kind] = by_kind.get(h.kind, 0) + 1assert by_kind == expected, f"{note}: expected {expected}, got {by_kind}"+++ ("language", "source", "expected", "note"),+ [+ ("python", b"try:\n x()\nexcept asyncio.CancelledError:\n pass\n", set(), "asyncio"),+ ("python", b"try:\n x()\nexcept CancelledError:\n pass\n", set(), "bare name"),+ (+ "python",+ b"try:\n x()\n"+ b"except (asyncio.CancelledError, concurrent.futures.CancelledError) as e:\n"+ b" pass\n",+ set(),+ "tuple of cancellations",+ ),+ (+ "python",+ b"try:\n x()\nexcept (asyncio.CancelledError, ValueError):\n pass\n",+ {"swallowed_catch"},+ "cancellation mixed with an error is still swallowed",+ ),+ (+ "python",+ b"try:\n x()\nexcept CancelledError, ValueError:\n pass\n",+ {"swallowed_catch"},+ "parenthesis-free list keeps every type",+ ),+ (+ "csharp",+ b"class A{ void M(){ try { Go(); } catch (OperationCanceledException) {} } }\n",+ set(),+ "C# OperationCanceledException",+ ),+ (+ "csharp",+ b"class A{ void M(){ try { Go(); } "+ b"catch (System.Threading.Tasks.TaskCanceledException e) {} } }\n",+ set(),+ "C# qualified TaskCanceledException",+ ),+ ],+)+def test_cancellation_catch_is_not_swallowed(+ language: str, source: bytes, expected: set, note: str+):+ assert {h.kind for h in _hits(language, source)} == expected, note+++_FALLBACK_BODY = b" try:\n return load()\n except Exception:\n return None\n"+++ ("source", "flagged", "note"),+ [+ (b'def f():\n """Return None on failure."""\n' + _FALLBACK_BODY, False, "docstring"),+ (b'def f():\n """Best-effort cache read."""\n' + _FALLBACK_BODY, False, "best-effort"),+ (b'def f():\n """Load it. Never raises."""\n' + _FALLBACK_BODY, False, "never raises"),+ (+ b'def f():\n """Falls back to an empty dict if the file cannot be read."""\n'+ + _FALLBACK_BODY,+ False,+ "falls back",+ ),+ (+ b"def f():\n # best-effort: a missing cache is fine\n" + _FALLBACK_BODY,+ False,+ "comment above try",+ ),+ (+ b"def f():\n try:\n return load()\n except Exception: # best-effort\n"+ b" return None\n",+ False,+ "comment on the except line",+ ),+ (b'def f():\n """Return the loaded config."""\n' + _FALLBACK_BODY, True, "undocumented"),+ (+ b'def f():\n """Returns the value if the key exists; raises on error."""\n'+ + _FALLBACK_BODY,+ True,+ "failure word in another clause",+ ),+ (+ b'def f():\n """Does not raise ValueError for blanks."""\n' + _FALLBACK_BODY,+ True,+ "a named exception it does not raise is no fallback",+ ),+ (+ b'def f():\n """Best-effort read."""\n try:\n load()\n'+ b" except Exception:\n log()\n",+ True,+ "documented but the handler does not return",+ ),+ (+ b'def f():\n """Best-effort read."""\n try:\n return load()\n'+ b" except:\n return None\n",+ True,+ "bare except still catches KeyboardInterrupt",+ ),+ (+ b'def f():\n """Return None on failure."""\n def g():\n """Return it."""\n'+ b" try:\n return load()\n except Exception:\n"+ b" return None\n",+ True,+ "only the nearest function's docstring counts",+ ),+ ],+)+def test_documented_fallback_is_not_broad_except(source: bytes, flagged: bool, note: str):+ kinds = {h.kind for h in _hits("python", source)}+ assert bool(kinds & {"broad_except", "bare_except"}) is flagged, note