python-vibe-guard 0.7.1__py3-none-any.whl

pyvibe/rules/httpx_sync.py

@@ -0,0 +1,52 @@
+import ast
+from typing import List
+from pyvibe.rules.base import Violation, AsyncBlockingCallVisitor
+
+HTTPX_BLOCKING = {"get", "post", "put", "patch", "delete", "request", "stream"}
+
+
+class HttpxSyncRule(AsyncBlockingCallVisitor):
+    """
+    PYVIBE-010 — httpx top-level sync methods inside async def
+
+    httpx exposes both a synchronous API (httpx.get, httpx.post, …) and an
+    async API (httpx.AsyncClient). AI-generated code frequently uses the sync
+    top-level functions inside async handlers, blocking the OS thread for the
+    full HTTP round-trip.
+
+    httpx.AsyncClient() has attr='AsyncClient' — outside HTTPX_BLOCKING —
+    so it is never matched by this rule.
+
+    Fix: async with httpx.AsyncClient() as client: response = await client.get(url)
+    """
+
+    RULE_ID = "PYVIBE-010"
+    SEVERITY = "CRITICAL"
+
+    def visit_Call(self, node: ast.Call):
+        if self._current_async_func is None:
+            self.generic_visit(node)
+            return
+
+        method = self._get_httpx_method(node)
+        if method:
+            self.violations.append(Violation(
+                rule_id=self.RULE_ID,
+                severity=self.SEVERITY,
+                line=node.lineno,
+                function_name=self._current_async_func,
+                message=f"httpx.{method}() is synchronous — blocks the event loop for the full HTTP round-trip",
+                evidence=f"Use `async with httpx.AsyncClient() as client: await client.{method}(url)`",
+            ))
+
+        self.generic_visit(node)
+
+    def _get_httpx_method(self, node: ast.Call):
+        if (
+            isinstance(node.func, ast.Attribute)
+            and node.func.attr in HTTPX_BLOCKING
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id == "httpx"
+        ):
+            return node.func.attr
+        return None

pyvibe/rules/loop_run_until_complete.py

@@ -0,0 +1,37 @@
+import ast
+from pyvibe.rules.base import Violation, AsyncBlockingCallVisitor
+
+
+class LoopRunUntilCompleteRule(AsyncBlockingCallVisitor):
+    """
+    PYVIBE-015 — loop.run_until_complete() inside async def
+
+    run_until_complete() blocks the calling OS thread until the coroutine
+    finishes. Calling it from inside an already-running async function raises
+    RuntimeError at runtime ("This event loop is already running") and defeats
+    the entire purpose of async/await. AI-generated code that wraps existing
+    sync code often makes this mistake when trying to "bridge" sync and async.
+
+    Fix: replace `loop.run_until_complete(coro())` with `await coro()` directly.
+    """
+
+    RULE_ID = "PYVIBE-015"
+    SEVERITY = "CRITICAL"
+
+    def visit_Call(self, node: ast.Call):
+        if self._current_async_func and self._is_run_until_complete(node):
+            self.violations.append(Violation(
+                rule_id=self.RULE_ID,
+                severity=self.SEVERITY,
+                line=node.lineno,
+                function_name=self._current_async_func,
+                message="loop.run_until_complete() inside async def — raises RuntimeError at runtime (event loop already running)",
+                evidence="Replace with `await coro()` directly; the enclosing async function is already on the event loop",
+            ))
+        self.generic_visit(node)
+
+    def _is_run_until_complete(self, node: ast.Call) -> bool:
+        return (
+            isinstance(node.func, ast.Attribute)
+            and node.func.attr == "run_until_complete"
+        )

pyvibe/rules/open_async.py

@@ -0,0 +1,39 @@
+import ast
+from typing import List
+from pyvibe.rules.base import Violation, AsyncBlockingCallVisitor
+
+
+class OpenAsyncRule(AsyncBlockingCallVisitor):
+    """
+    PYVIBE-009 — open() builtin inside async def
+
+    The builtin open() performs synchronous file I/O. Each call blocks the
+    OS thread until the kernel completes the read/write, preventing the event
+    loop from scheduling other coroutines. AI-generated FastAPI code routinely
+    mixes open() with async endpoints.
+
+    aiofiles.open() is an ast.Attribute node — structurally different from the
+    bare ast.Name 'open', so it is never matched by this rule.
+
+    Fix: use `async with aiofiles.open(path) as f: content = await f.read()`.
+    """
+
+    RULE_ID = "PYVIBE-009"
+    SEVERITY = "CRITICAL"
+
+    def visit_Call(self, node: ast.Call):
+        if self._current_async_func is None:
+            self.generic_visit(node)
+            return
+
+        if isinstance(node.func, ast.Name) and node.func.id == "open":
+            self.violations.append(Violation(
+                rule_id=self.RULE_ID,
+                severity=self.SEVERITY,
+                line=node.lineno,
+                function_name=self._current_async_func,
+                message="open() performs synchronous file I/O — blocks the event loop",
+                evidence="Use `async with aiofiles.open(path) as f: content = await f.read()`",
+            ))
+
+        self.generic_visit(node)

pyvibe/rules/os_blocking.py

@@ -0,0 +1,49 @@
+import ast
+from typing import List
+from pyvibe.rules.base import Violation, AsyncBlockingCallVisitor
+
+OS_BLOCKING = {"system", "popen", "waitpid"}
+
+
+class OsBlockingRule(AsyncBlockingCallVisitor):
+    """
+    PYVIBE-011 — os.system / os.popen / os.waitpid inside async def
+
+    These OS calls block the thread until the child process or I/O completes.
+    Unlike subprocess, they have no direct async equivalent and are commonly
+    generated when AI migrates sync scripts to async without replacing the
+    OS interaction layer.
+
+    Fix: use asyncio.create_subprocess_shell() with await proc.communicate().
+    """
+
+    RULE_ID = "PYVIBE-011"
+    SEVERITY = "CRITICAL"
+
+    def visit_Call(self, node: ast.Call):
+        if self._current_async_func is None:
+            self.generic_visit(node)
+            return
+
+        method = self._get_os_blocking_method(node)
+        if method:
+            self.violations.append(Violation(
+                rule_id=self.RULE_ID,
+                severity=self.SEVERITY,
+                line=node.lineno,
+                function_name=self._current_async_func,
+                message=f"os.{method}() blocks the OS thread — no direct async equivalent",
+                evidence="Use `proc = await asyncio.create_subprocess_shell(cmd)` then `await proc.communicate()`",
+            ))
+
+        self.generic_visit(node)
+
+    def _get_os_blocking_method(self, node: ast.Call):
+        if (
+            isinstance(node.func, ast.Attribute)
+            and node.func.attr in OS_BLOCKING
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id == "os"
+        ):
+            return node.func.attr
+        return None

pyvibe/rules/queue_put_nowait.py

@@ -0,0 +1,98 @@
+import ast
+from typing import List, Optional
+from pyvibe.rules.base import Violation
+
+
+def _catches_queuefull(handlers: list) -> bool:
+    """True if any handler catches asyncio.QueueFull, QueueFull, bare except, or Exception."""
+    for h in handlers:
+        t = h.type
+        if t is None:  # bare except — catches everything
+            return True
+        if isinstance(t, ast.Name) and t.id in ("QueueFull", "Exception"):
+            return True
+        if isinstance(t, ast.Attribute) and t.attr in ("QueueFull", "Exception"):
+            return True
+        if isinstance(t, ast.Tuple):  # except (QueueFull, ...) — tuple of types
+            for elt in t.elts:
+                if isinstance(elt, ast.Name) and elt.id in ("QueueFull", "Exception"):
+                    return True
+                if isinstance(elt, ast.Attribute) and elt.attr in ("QueueFull", "Exception"):
+                    return True
+    return False
+
+
+class QueuePutNowaitRule(ast.NodeVisitor):
+    """
+    PYVIBE-020 — put_nowait() without asyncio.QueueFull handler
+
+    asyncio.Queue.put_nowait() raises asyncio.QueueFull immediately when the
+    queue is at maxsize. Unless caught, the exception propagates and the item
+    is silently lost — no log, no retry, no metric. This affects any queue
+    with maxsize > 0 (unbounded queues never raise, but maxsize is often set
+    later or injected).
+
+    Fix: wrap in try/except asyncio.QueueFull and decide explicitly what to
+    do — log and drop, or switch to `await queue.put()` to block instead.
+
+    Fires in any function context (sync and async). The guard is the absence
+    of an enclosing try/except that catches asyncio.QueueFull or Exception.
+    """
+
+    RULE_ID = "PYVIBE-020"
+    SEVERITY = "WARNING"
+
+    def __init__(self):
+        self.violations: List[Violation] = []
+        self._current_func: Optional[str] = None
+        self._protected_depth: int = 0  # try/except with QueueFull handler nesting depth
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        prev = self._current_func
+        self._current_func = node.name
+        self.generic_visit(node)
+        self._current_func = prev
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
+        prev = self._current_func
+        self._current_func = node.name
+        self.generic_visit(node)
+        self._current_func = prev
+
+    def visit_Try(self, node: ast.Try):
+        protected = _catches_queuefull(node.handlers)
+        if protected:
+            self._protected_depth += 1
+        for stmt in node.body:
+            self.visit(stmt)
+        if protected:
+            self._protected_depth -= 1
+        # handlers, orelse, finalbody are NOT covered by this try's own handlers
+        for handler in node.handlers:
+            self.visit(handler)
+        for stmt in node.orelse:
+            self.visit(stmt)
+        for stmt in node.finalbody:
+            self.visit(stmt)
+
+    def visit_Call(self, node: ast.Call):
+        if (
+            isinstance(node.func, ast.Attribute)
+            and node.func.attr == "put_nowait"
+            and self._protected_depth == 0
+        ):
+            self.violations.append(Violation(
+                rule_id=self.RULE_ID,
+                severity=self.SEVERITY,
+                line=node.lineno,
+                function_name=self._current_func or "<module>",
+                message=(
+                    "put_nowait() without asyncio.QueueFull handler — "
+                    "raises silently if queue is full, item is lost"
+                ),
+                evidence=(
+                    "Wrap in `try/except asyncio.QueueFull:` and log or handle explicitly, "
+                    "or use `await queue.put()` to block until space is available"
+                ),
+            ))
+        self.generic_visit(node)

pyvibe/rules/retry_no_backoff.py

@@ -0,0 +1,255 @@
+import ast
+from typing import List, Optional
+from pyvibe.rules.base import Violation
+
+# Loop variable names that signal retry intent.
+# Excluded: i, j, n, count, idx, chunk_start, page_num, dpynum — index/iteration variables.
+_RETRY_VAR_NAMES = frozenset({"_"})
+_RETRY_VAR_PREFIXES = ("attempt", "retry", "retries")
+
+
+def _ends_with_retry(body: list) -> bool:
+    """True if the except body ends with continue.
+
+    `pass` alone is intentionally NOT counted. CLEANUP_PASS analysis (jun 2026)
+    showed 97/186 hits (52.2%) were pass-only handlers in cleanup blocks — all false
+    positives. `pass` lets the enclosing loop continue by fall-through rather than
+    expressing explicit retry intent.
+    """
+    if not body:
+        return False
+    last = body[-1]
+    return isinstance(last, ast.Continue)
+
+
+def _is_retry_loop(node: ast.For) -> bool:
+    """True if the for loop is a bounded retry: for _ in range(N) or for attempt in range(N).
+
+    Two conditions required:
+    1. Iterable must be range() — bounded count of attempts.
+    2. Loop variable must be anonymous (_) or carry retry-intent semantics
+       (name contains 'attempt', 'retry', or 'retries').
+
+    Excluded: for i/j/n/count/idx in range(N) — these are index variables used to
+    iterate over elements, not retry counters. Analysis of 30 for-range hits showed
+    the 'i'-named group was 100% RANGE_FOREACH false positives.
+    """
+    if not (
+        isinstance(node.iter, ast.Call)
+        and isinstance(node.iter.func, ast.Name)
+        and node.iter.func.id == "range"
+    ):
+        return False
+    target = node.target
+    if not isinstance(target, ast.Name):
+        return False
+    varname = target.id.lower()
+    return varname in _RETRY_VAR_NAMES or any(p in varname for p in _RETRY_VAR_PREFIXES)
+
+
+def _is_sleep_call(func_node) -> bool:
+    """True if func_node is asyncio.sleep, time.sleep, or bare sleep() (direct import)."""
+    if isinstance(func_node, ast.Attribute):
+        return (
+            func_node.attr == "sleep"
+            and isinstance(func_node.value, ast.Name)
+            and func_node.value.id in ("asyncio", "time")
+        )
+    # Bare name: `from time import sleep; sleep(N)` — no module prefix
+    if isinstance(func_node, ast.Name):
+        return func_node.id == "sleep"
+    return False
+
+
+def _has_backoff_name(func_node) -> bool:
+    """True if the callable signals backoff/sleep delay.
+
+    Detects:
+    - Function/method name contains 'backoff' or 'jitter'
+    - Method name is 'asleep' (Backoff class async-sleep pattern: await backoff.asleep())
+    - Receiver object name contains 'backoff' or 'jitter' (e.g. backoff.sleep())
+    """
+    if isinstance(func_node, ast.Name):
+        name = func_node.id.lower()
+        return "backoff" in name or "jitter" in name
+    if isinstance(func_node, ast.Attribute):
+        attr = func_node.attr.lower()
+        if "backoff" in attr or "jitter" in attr or attr == "asleep":
+            return True
+        # Receiver object named after a backoff helper: backoff.sleep(), jitter.wait()
+        if isinstance(func_node.value, ast.Name):
+            receiver = func_node.value.id.lower()
+            return "backoff" in receiver or "jitter" in receiver
+    return False
+
+
+def _body_has_backoff(stmts: list) -> bool:
+    """True if any statement contains a sleep or backoff/jitter call."""
+    for stmt in stmts:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call):
+                if _is_sleep_call(node.func):
+                    return True
+                if _has_backoff_name(node.func):
+                    return True
+    return False
+
+
+def _body_has_escalation(stmts: list) -> bool:
+    """True if any if-block in the except body contains raise or break (escalation pattern)."""
+    for stmt in stmts:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.If):
+                for child in ast.walk(node):
+                    if isinstance(child, (ast.Raise, ast.Break)):
+                        return True
+    return False
+
+
+def _is_timeout_only_handler(handler: ast.ExceptHandler) -> bool:
+    """True if the handler catches ONLY asyncio.TimeoutError or bare TimeoutError.
+
+    Handlers that catch TimeoutError exclusively are very likely polling loops
+    (e.g. `await asyncio.wait_for(event.wait(), timeout=N)`) rather than retries.
+    Tuple handlers like `except (asyncio.TimeoutError, ConnectionError)` return False
+    because the presence of other exception types indicates genuine error handling.
+    """
+    typ = handler.type
+    if typ is None:
+        return False
+    if isinstance(typ, ast.Name) and typ.id == "TimeoutError":
+        return True
+    return (
+        isinstance(typ, ast.Attribute)
+        and typ.attr == "TimeoutError"
+        and isinstance(typ.value, ast.Name)
+        and typ.value.id == "asyncio"
+    )
+
+
+def _try_body_has_timeout_kwarg(stmts: list) -> bool:
+    """True if any call in the try body uses a 'timeout' keyword argument.
+
+    Combined with _is_timeout_only_handler, this identifies the POLL_LOOP pattern:
+        try:
+            await asyncio.wait_for(event.wait(), timeout=N)  ← timeout= here
+        except asyncio.TimeoutError:                          ← TimeoutError only
+            continue                                          ← not a retry
+
+    A genuine network retry would either catch Exception (not TimeoutError only)
+    or would catch asyncio.TimeoutError without any explicit timeout= in the try body.
+    """
+    for stmt in stmts:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call):
+                for kw in node.keywords:
+                    if kw.arg == "timeout":
+                        return True
+    return False
+
+
+class RetryNoBackoffRule(ast.NodeVisitor):
+    """
+    PYVIBE-019 — retry loop without backoff inside async def
+
+    Scope (v3, jun 2026): exclusively `for _ in range(N)` or `for attempt in range(N)`
+    loops inside async functions. While loops are out of scope (FP rate ~90% due to
+    CLEANUP_PASS, MEM_PARSE, and MISSED_BACKOFF patterns; not reducible with AST alone).
+
+    Fires when:
+    - Loop iterates over range() with anonymous (_) or retry-intent variable name
+    - Handler body ends with `continue` (explicit retry)
+    - No sleep or backoff call detected in the handler body
+
+    Not flagged when the except handler contains:
+    - asyncio.sleep(N) or time.sleep(N) or bare sleep(N)
+    - await backoff.asleep() or any call with 'backoff'/'jitter'/'asleep' in the name
+    - An escalation pattern (if-block leading to raise or break)
+    - Catches only asyncio.TimeoutError AND try body has timeout= kwarg (POLL_LOOP pattern)
+
+    Fix: add `await asyncio.sleep(2 ** attempt)` before continue, or use
+    tenacity / backoff library.
+    """
+
+    RULE_ID = "PYVIBE-019"
+    SEVERITY = "WARNING"
+
+    def __init__(self):
+        self.violations: List[Violation] = []
+        self._current_async_func: Optional[str] = None
+        # Stack: True = enclosing loop is a qualifying retry loop (for _ in range(N)).
+        # Innermost value determines firing — `continue` resumes the innermost loop.
+        self._retry_loop_stack: List[bool] = []
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
+        prev_func = self._current_async_func
+        prev_stack = self._retry_loop_stack
+        self._current_async_func = node.name
+        self._retry_loop_stack = []
+        self.generic_visit(node)
+        self._current_async_func = prev_func
+        self._retry_loop_stack = prev_stack
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        prev_func = self._current_async_func
+        prev_stack = self._retry_loop_stack
+        self._current_async_func = None
+        self._retry_loop_stack = []
+        self.generic_visit(node)
+        self._current_async_func = prev_func
+        self._retry_loop_stack = prev_stack
+
+    def visit_Lambda(self, node: ast.Lambda):
+        prev_func = self._current_async_func
+        prev_stack = self._retry_loop_stack
+        self._current_async_func = None
+        self._retry_loop_stack = []
+        self.generic_visit(node)
+        self._current_async_func = prev_func
+        self._retry_loop_stack = prev_stack
+
+    def visit_For(self, node: ast.For):
+        self._retry_loop_stack.append(_is_retry_loop(node))
+        self.generic_visit(node)
+        self._retry_loop_stack.pop()
+
+    def visit_While(self, node: ast.While):
+        # While loops are explicitly out of scope for PYVIBE-019 v3.
+        # Push False so nested for-range retry loops can still be detected.
+        self._retry_loop_stack.append(False)
+        self.generic_visit(node)
+        self._retry_loop_stack.pop()
+
+    def visit_Try(self, node: ast.Try):
+        if (self._current_async_func
+                and self._retry_loop_stack
+                and self._retry_loop_stack[-1]):
+            for handler in node.handlers:
+                self._check_handler(handler, node.body)
+        self.generic_visit(node)
+
+    def _check_handler(self, handler: ast.ExceptHandler, try_body: list):
+        body = handler.body
+        if not _ends_with_retry(body):
+            return
+        if _body_has_backoff(body):
+            return
+        if _body_has_escalation(body):
+            return
+        # POLL_LOOP exclusion: `except asyncio.TimeoutError` + `timeout=` kwarg in try body
+        # is the canonical asyncio.wait_for polling pattern — not a retry.
+        if _is_timeout_only_handler(handler) and _try_body_has_timeout_kwarg(try_body):
+            return
+        self.violations.append(Violation(
+            rule_id=self.RULE_ID,
+            severity=self.SEVERITY,
+            line=handler.lineno,
+            function_name=self._current_async_func,
+            message=(
+                "retry loop without backoff — except retries immediately with no delay"
+            ),
+            evidence=(
+                "Add `await asyncio.sleep(2 ** attempt)` before continue, "
+                "or use tenacity / backoff library"
+            ),
+        ))

pyvibe/rules/silent_except.py

@@ -0,0 +1,107 @@
+import ast
+import re
+from typing import List, Optional
+from pyvibe.rules.base import Violation
+
+_NOSEC_B110 = re.compile(r'#\s*nosec\b[^#\n]*\bB110\b')
+
+
+def _is_empty_body(body: list) -> bool:
+    """Return True if every statement is pass or ... (Ellipsis)."""
+    if not body:
+        return True
+    for stmt in body:
+        if isinstance(stmt, ast.Pass):
+            continue
+        if (
+            isinstance(stmt, ast.Expr)
+            and isinstance(stmt.value, ast.Constant)
+            and stmt.value.value is ...
+        ):
+            continue
+        return False
+    return True
+
+
+class SilentExceptRule(ast.NodeVisitor):
+    """
+    PYVIBE-017 — except Exception with empty body (silences errors)
+
+    A bare except or except Exception block whose body is only pass/... swallows
+    every exception without any record, making bugs invisible in production.
+    bare except also catches KeyboardInterrupt and SystemExit, preventing clean
+    shutdown.
+
+    Suppression: add `# nosec B110` on the `except` line to mark intentional
+    suppression (Bandit convention). Generic `# nosec` without B110 is NOT
+    honoured — specificity is required so that the opt-out is deliberate.
+
+    Fix: log the error, re-raise, or handle explicitly.
+    """
+
+    RULE_ID = "PYVIBE-017"
+    SEVERITY = "CRITICAL"
+
+    def __init__(self, source_lines: Optional[List[str]] = None):
+        self.violations: List[Violation] = []
+        self._current_func: Optional[str] = None
+        self._source_lines: List[str] = source_lines or []
+
+    def _is_suppressed(self, lineno: int) -> bool:
+        """Return True if the given 1-based line carries # nosec B110."""
+        if not self._source_lines:
+            return False
+        idx = lineno - 1
+        if 0 <= idx < len(self._source_lines):
+            return bool(_NOSEC_B110.search(self._source_lines[idx]))
+        return False
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        previous = self._current_func
+        self._current_func = node.name
+        self.generic_visit(node)
+        self._current_func = previous
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
+        previous = self._current_func
+        self._current_func = node.name
+        self.generic_visit(node)
+        self._current_func = previous
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler):
+        if not _is_empty_body(node.body):
+            self.generic_visit(node)
+            return
+
+        if self._is_suppressed(node.lineno):
+            self.generic_visit(node)
+            return
+
+        exc_type = node.type
+        if exc_type is None:
+            severity = "CRITICAL"
+            message = (
+                "bare except swallows all exceptions including "
+                "KeyboardInterrupt and SystemExit"
+            )
+        elif isinstance(exc_type, ast.Name) and exc_type.id == "Exception":
+            severity = "WARNING"
+            message = "except Exception with empty body silences all errors silently"
+        else:
+            # specific exception type — acceptable pattern
+            self.generic_visit(node)
+            return
+
+        self.violations.append(Violation(
+            rule_id=self.RULE_ID,
+            severity=severity,
+            line=node.lineno,
+            function_name=self._current_func or "<module>",
+            message=message,
+            evidence=(
+                "Log the error: `except Exception as e: logger.error(e)`, "
+                "or re-raise: `except Exception: raise`, "
+                "or handle explicitly"
+            ),
+        ))
+        self.generic_visit(node)