feat(scripts): add heuristics to audit_exception_handling for review pass patterns (10 new heuristics + tests)

2026-06-17 16:15:16 -04:00
parent 8b954ee180
commit f26091941c
2 changed files with 500 additions and 0 deletions
@@ -453,11 +453,205 @@ class ExceptionVisitor(ast.NodeVisitor):
    f"Compliant: stdlib I/O exception {exc_name} caught in our own code is acceptable (per convention, file/network errors are converted to ErrorInfo).",
   )

+  # 11-17. Heuristics added by result_migration_review_pass_20260617
+  # These cover the 7 most common compliant patterns the review pass found.
+  # Each heuristic inspects the try body + except body together.
+  compliant = self._try_compliant_pattern(try_node, handler, exc_name)
+  if compliant is not None:
+   return compliant
+
  return (
   "UNCLEAR",
   f"Manual review: catches {exc_name}; not obviously boundary or violation. Check whether the except site is converting to ErrorInfo (good) or hiding the error (bad).",
  )

+ def _has_call_with_attr(self, stmts: list[ast.stmt], attr_name: str) -> bool:
+  """True if any statement contains a call to `.attr_name(...)` (e.g. list.index, dict.get)."""
+  for s in stmts:
+   for node in ast.walk(s):
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == attr_name:
+     return True
+  return False
+
+ def _has_keyword_true_call(self, stmts: list[ast.stmt], attr_name: str, kw_name: str) -> bool:
+  """True if any statement contains a call `.attr_name(..., kw_name=True)`."""
+  for s in stmts:
+   for node in ast.walk(s):
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == attr_name:
+     for kw in node.keywords:
+      if kw.arg == kw_name and isinstance(kw.value, ast.Constant) and kw.value.value is True:
+       return True
+  return False
+
+ def _has_print_call(self, stmts: list[ast.stmt]) -> bool:
+  """True if any statement is an `Expr(Call(Name('print'), ...))`."""
+  for s in stmts:
+   if isinstance(s, ast.Expr) and isinstance(s.value, ast.Call):
+    f = s.value.func
+    if isinstance(f, ast.Name) and f.id == "print":
+     return True
+  return False
+
+ def _has_import_stmt(self, stmts: list[ast.stmt]) -> bool:
+  """True if any statement is an `Import` or `ImportFrom`."""
+  for s in stmts:
+   if isinstance(s, (ast.Import, ast.ImportFrom)):
+    return True
+  return False
+
+ def _try_compliant_pattern(self, try_node: ast.Try, handler: ast.ExceptHandler, exc_name: str) -> tuple[str, str] | None:
+  """Detect one of the 7 common compliant patterns found by the review pass.
+
+  Returns (category, hint) if the pattern is compliant, else None.
+  """
+  try_body = try_node.body
+  except_body = handler.body
+  exc_set = {e.strip() for e in exc_name.replace("(", "").replace(")", "").split(",") if e.strip()}
+
+  # 11. list.index(x) with ValueError fallback to default index
+  if exc_set & {"ValueError"} and self._has_call_with_attr(try_body, "index") and len(except_body) > 0:
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: list.index(x); except ({', '.join(sorted(exc_set))}): ...` is the canonical combo-box fallback pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 12. dict[x] or get_capabilities(...) with KeyError fallback to default
+  if exc_set == {"KeyError"} and len(except_body) > 0 and len(try_body) > 0:
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: <lookup>; except KeyError: ...` is the canonical lookup-miss-with-default pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 13. datetime.fromisoformat(s) with ValueError: None
+  if exc_set == {"ValueError"} and self._has_call_with_attr(try_body, "fromisoformat"):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: datetime.fromisoformat(s); except ValueError: ...` is the canonical lenient-deserialization pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 14. Path.resolve(strict=True) with (OSError, ValueError) fallback
+  if exc_set == {"OSError", "ValueError"} and self._has_keyword_true_call(try_body, "resolve", "strict"):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: Path(p).resolve(strict=True); except (OSError, ValueError): ...` is the canonical graceful-path-resolution pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 15. Path.relative_to with ValueError: pass / return False
+  if exc_set == {"ValueError"} and self._has_call_with_attr(try_body, "relative_to"):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: rp.relative_to(base); except ValueError: ...` is the canonical subpath-check pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 16. asyncio.get_running_loop() with RuntimeError: asyncio.run(...)
+  if exc_set == {"RuntimeError"} and self._has_call_with_attr(try_body, "get_running_loop") and self._has_call_with_attr(except_body, "run"):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: get_running_loop(); except RuntimeError: asyncio.run(...)` is the canonical sync/async bridge pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 17. import with (ImportError, ModuleNotFoundError, AttributeError) + fallback stub
+  if exc_set & {"ImportError", "ModuleNotFoundError", "AttributeError"} and self._has_import_stmt(try_body) and len(except_body) > 0:
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: import ...; except ({', '.join(sorted(exc_set))}): <stub>` is the canonical graceful-degradation pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 18. JSON parse with (json.JSONDecodeError, KeyError) and print() for CLI-style input
+  if "JSONDecodeError" in exc_name and self._has_call_with_attr(try_body, "loads") and self._has_print_call(except_body):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: json.loads(...); except json.JSONDecodeError: print(...)` is the canonical CLI-style JSON input parser pattern (per result_migration_review_pass_20260617).",
+   )
+  if exc_set == {"KeyError"} and self._has_call_with_attr(try_body, "loads") and self._has_print_call(except_body):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: json.loads(...); except KeyError: print(...)` is the canonical CLI-style JSON input parser pattern (per result_migration_review_pass_20260617).",
+   )
+
+  # 19. Narrow except + log (sys.stderr.write or logging.*) for defer-not-catch or retry-then-give-up
+  if len(except_body) > 0 and self._has_log_call(except_body) and not exc_set & {"Exception", "BaseException", ""}:
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: ...; except ({', '.join(sorted(exc_set))}): <log>` is the canonical catch+log pattern (defer-not-catch or retry-then-give-up) (per result_migration_review_pass_20260617).",
+   )
+
+  # 20. ImGui scope cleanup guard (narrow except + imgui.end_* call)
+  if exc_set & {"TypeError", "AttributeError", "RuntimeError"} and self._has_imgui_end_call(except_body):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: ...; except ({', '.join(sorted(exc_set))}): imgui.end_*()` is the canonical ImGui scope cleanup guard (per result_migration_review_pass_20260617).",
+   )
+
+  # 21. MCP tool boundary (broad except Exception + return string in str-returning function)
+  enclosing_func = self._current_func_node()
+  if enclosing_func is not None and enclosing_func.returns is not None and ast.unparse(enclosing_func.returns) == "str" and exc_set & {"Exception", "BaseException"} and self._has_string_return(except_body):
+   return (
+    "INTERNAL_COMPLIANT",
+    f"Compliant: `try: ...; except Exception: return <string>` in a `-> str` tool function is the canonical MCP tool boundary pattern (per result_migration_review_pass_20260617).",
+   )
+
+  return None
+
+ def _has_string_return(self, stmts: list[ast.stmt]) -> bool:
+  """True if any statement is a `return <f-string or string constant>`."""
+  for s in stmts:
+   if isinstance(s, ast.Return) and s.value is not None:
+    if isinstance(s.value, ast.Constant) and isinstance(s.value.value, str):
+     return True
+    if isinstance(s.value, ast.JoinedStr):
+     return True
+  return False
+
+ def _has_log_call(self, stmts: list[ast.stmt]) -> bool:
+  """True if any statement is a log call (sys.stderr.write, logging.*, print)."""
+  for s in stmts:
+   for node in ast.walk(s):
+    if isinstance(node, ast.Call):
+     f = node.func
+     if isinstance(f, ast.Attribute) and f.attr in ("write", "error", "warning", "info", "debug", "exception"):
+      return True
+     if isinstance(f, ast.Name) and f.id == "print":
+      return True
+  return False
+
+ def _has_imgui_end_call(self, stmts: list[ast.stmt]) -> bool:
+  """True if any statement is a call to an imgui.end_* function."""
+  for s in stmts:
+   for node in ast.walk(s):
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr.startswith("end_"):
+     return True
+  return False
+
+ def _enclosing_if_is_none_guard(self) -> bool:
+  """True if the current raise is inside an `if <var> is None:` block (validation pattern)."""
+  # The _func_stack holds the function context; we don't track the if-stack.
+  # Walk the AST of the current function and check if the raise is inside
+  # an `if <var> is None:` block.
+  enclosing_func = self._current_func_node()
+  if enclosing_func is None:
+   return False
+  for node in ast.walk(enclosing_func):
+   if node is enclosing_func:
+    continue
+   if isinstance(node, ast.If):
+    test = node.test
+    if isinstance(test, ast.Compare) and isinstance(test.ops[0], ast.Is) and any(isinstance(c, ast.Constant) and c.value is None for c in test.comparators):
+     for child in ast.walk(node):
+      if isinstance(child, ast.Raise) and child is not node:
+       return True
+  return False
+
+ def _function_body_is_just_this_raise(self, node: ast.Raise) -> bool:
+  """True if the function body is just this raise (abstract method pattern)."""
+  enclosing_func = self._current_func_node()
+  if enclosing_func is None:
+   return False
+  body = enclosing_func.body
+  if len(body) != 1:
+   return False
+  return body[0] is node
+
 def _extract_raise_name(self, node: ast.expr) -> str:
  """Extract the exception class name from a raise expression.

@@ -512,6 +706,21 @@ class ExceptionVisitor(ast.NodeVisitor):
     "INTERNAL_PROGRAMMER_RAISE",
     f"Compliant: `{exc_short}` for an impossible state / precondition check. The styleguide reserves `raise` for programmer errors.",
    )
+   # Heuristic added by result_migration_review_pass_20260617:
+   # NotImplementedError as the entire function body = abstract method pattern.
+   if exc_short == "NotImplementedError" and self._function_body_is_just_this_raise(node):
+    return (
+     "INTERNAL_PROGRAMMER_RAISE",
+     f"Compliant: `raise NotImplementedError()` as the entire function body is the canonical abstract-method pattern (per result_migration_review_pass_20260617).",
+    )
+
+  # Heuristic added by result_migration_review_pass_20260617:
+  # `if <var> is None: raise ImportError(...)` = validation raise (precondition check).
+  if exc_short in {"ImportError", "RuntimeError", "ValueError", "KeyError"} and self._enclosing_if_is_none_guard():
+   return (
+    "INTERNAL_PROGRAMMER_RAISE",
+    f"Compliant: `raise {exc_short}` inside `if <var> is None:` is the canonical validation/precondition-check pattern (per result_migration_review_pass_20260617).",
+   )

  return (
   "INTERNAL_RETHROW",