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.

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.py
index 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.py
index 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) -> ErrorHandli
or (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 None
and _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.py
index 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 None
assert 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) + 1
assert 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