shadow-debugger 0.1.0__py3-none-any.whl

shadow_debugger/core.py

@@ -0,0 +1,244 @@
+"""Background engine: bounded queue + worker threads that never block the host application."""
+
+from __future__ import annotations
+
+import atexit
+import dataclasses
+import logging
+import queue
+import threading
+import time
+from types import TracebackType
+from typing import Any, Dict, List, Optional, Type
+
+from .analyzer import AIAnalyzer
+from .config import ShadowConfig
+from .inspector import capture_exception_context, compute_fingerprint, fingerprint_exception
+from .patch_check import check_patch_syntax
+from .providers import ProviderError
+from .redaction import Redactor
+from .reporter import ReportManager
+from .throttler import ErrorThrottler
+
+logger = logging.getLogger("shadow_debugger")
+
+_CAPTURED_FLAG = "__shadow_debugger_captured__"
+
+
+class ShadowCore:
+    """Owns the analysis pipeline. Usually created through :func:`shadow_debugger.init`.
+
+    Accepts either a :class:`ShadowConfig` or the same keyword arguments::
+
+        ShadowCore(provider="ollama", max_queue_size=10)
+    """
+
+    def __init__(self, config: Optional[ShadowConfig] = None, **overrides: Any) -> None:
+        if "verify_patches" in overrides:
+            vp = overrides.pop("verify_patches")
+            overrides.setdefault("check_patch_syntax", bool(vp))
+        if config is None:
+            config = ShadowConfig(**overrides)
+        elif overrides:
+            config = dataclasses.replace(config, **overrides)
+        self.config = config
+
+        self.redactor = Redactor(config.redact_keys, config.redact_patterns)
+        self.analyzer = AIAnalyzer(
+            provider=config.provider,
+            model=config.model,
+            api_key=config.api_key,
+            base_url=config.base_url,
+            timeout=config.request_timeout,
+            fallback_models=config.fallback_models,
+        )
+        self.reporter = ReportManager(output_dir=config.output_dir, print_to_console=config.print_to_console)
+        self.throttler = ErrorThrottler(config.cooldown_seconds, config.max_tracked_errors)
+
+        # Bounded queue: an error flood can never exhaust memory.
+        self.queue: "queue.Queue[Dict[str, Any]]" = queue.Queue(maxsize=config.max_queue_size)
+        self._lock = threading.Lock()
+        self._dropped = 0
+        self._closed = False
+        self._stop = threading.Event()
+        self._threads: List[threading.Thread] = []
+        for i in range(config.max_workers):
+            t = threading.Thread(target=self._worker_loop, name=f"ShadowDebugger-{i}", daemon=True)
+            t.start()
+            self._threads.append(t)
+
+        atexit.register(self._atexit)
+
+    @property
+    def dropped_incidents(self) -> int:
+        with self._lock:
+            return self._dropped
+
+    @property
+    def _dropped_incidents_count(self) -> int:
+        return self.dropped_incidents
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    def capture(
+        self,
+        exc_type: Type[BaseException],
+        exc_value: BaseException,
+        exc_tb: Optional[TracebackType],
+        extra_metadata: Optional[Dict[str, Any]] = None,
+    ) -> Optional[str]:
+        """Hot-path entry point. Returns the error fingerprint, or None if ignored.
+
+        Never raises: a bug in the debugger must never break the host application.
+        """
+        try:
+            if self._closed:
+                return None
+            if getattr(exc_value, _CAPTURED_FLAG, False):
+                return None  # already captured by an inner layer (decorator + middleware)
+            try:
+                setattr(exc_value, _CAPTURED_FLAG, True)
+            except Exception:
+                pass
+
+            # Throttle BEFORE the expensive part (locals serialization, source reading).
+            fingerprint = fingerprint_exception(exc_type, exc_tb)
+            should_analyze, count = self.throttler.hit(fingerprint)
+            if not should_analyze:
+                logger.debug("Throttled duplicate %s (seen %d times, %s)", exc_type.__name__, count, fingerprint)
+                return fingerprint
+
+            context = capture_exception_context(
+                exc_type,
+                exc_value,
+                exc_tb,
+                extra_metadata,
+                redactor=self.redactor,
+                context_lines=self.config.context_lines,
+                include_source=self.config.send_source_code,
+                include_locals=self.config.send_locals,
+            )
+            context["occurrence_count"] = count
+            self._enqueue(context)
+            return fingerprint
+        except Exception:  # pragma: no cover - defensive
+            logger.exception("Shadow Debugger failed to capture an exception")
+            return None
+
+    def capture_exception(
+        self, exc: BaseException, extra_metadata: Optional[Dict[str, Any]] = None
+    ) -> Optional[str]:
+        return self.capture(type(exc), exc, exc.__traceback__, extra_metadata)
+
+    def submit_incident(self, error_context: Dict[str, Any]) -> None:
+        """Queue a pre-built incident dict (advanced use). Applies throttling."""
+        fingerprint = error_context.get("fingerprint") or compute_fingerprint(
+            type(str(error_context.get("exception_type", ""))),  # type: ignore[arg-type]
+            str(error_context.get("file", "")),
+            int(error_context.get("line", -1) or -1),
+        )
+        should_analyze, count = self.throttler.hit(fingerprint)
+        if not should_analyze:
+            return
+        error_context = {**error_context, "fingerprint": fingerprint, "occurrence_count": count}
+        self._enqueue(error_context)
+
+    def flush(self, timeout: Optional[float] = None) -> bool:
+        """Block until all queued incidents are processed. Returns False on timeout."""
+        deadline = None if timeout is None else time.monotonic() + timeout
+        with self.queue.all_tasks_done:
+            while self.queue.unfinished_tasks:
+                if deadline is None:
+                    self.queue.all_tasks_done.wait()
+                    continue
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return False
+                self.queue.all_tasks_done.wait(remaining)
+        return True
+
+    def shutdown(self, timeout: Optional[float] = None, wait: Optional[bool] = None) -> bool:
+        """Stop accepting incidents, wait up to ``timeout`` s for pending ones, stop workers.
+
+        ``timeout=None`` uses ``config.shutdown_timeout``. Returns True if everything finished.
+        """
+        if self._closed:
+            return True
+        self._closed = True
+        if wait is False:
+            timeout = 0.0
+        elif timeout is None:
+            timeout = self.config.shutdown_timeout
+        finished = self.flush(timeout) if timeout > 0 else (self.queue.unfinished_tasks == 0)
+        if not finished:
+            logger.warning(
+                "Shadow Debugger shutdown: %d incident(s) were still being analyzed after %.1fs and were abandoned.",
+                self.queue.unfinished_tasks,
+                timeout,
+            )
+        self._stop.set()
+        for t in self._threads:
+            t.join(timeout=1.0)
+        try:
+            atexit.unregister(self._atexit)
+        except Exception:  # pragma: no cover
+            pass
+        return finished
+
+    def _atexit(self) -> None:
+        pending = self.queue.unfinished_tasks
+        if pending:
+            logger.warning(
+                "Shadow Debugger: waiting up to %.0fs for %d pending diagnosis(es) before exit...",
+                self.config.shutdown_timeout,
+                pending,
+            )
+        self.shutdown()
+
+    def _enqueue(self, context: Dict[str, Any]) -> None:
+        try:
+            self.queue.put_nowait(context)
+        except queue.Full:
+            with self._lock:
+                self._dropped += 1
+                dropped = self._dropped
+            if dropped == 1 or dropped % 100 == 0:
+                logger.warning(
+                    "Shadow Debugger queue is full (%d). Dropped incident %s; total dropped: %d",
+                    self.queue.maxsize,
+                    context.get("exception_type", "?"),
+                    dropped,
+                )
+
+    def _worker_loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                context = self.queue.get(timeout=0.25)
+            except queue.Empty:
+                continue
+            try:
+                self._process(context)
+            except Exception:  # pragma: no cover - defensive
+                logger.exception("Shadow Debugger worker crashed while processing an incident")
+            finally:
+                self.queue.task_done()
+
+    def _process(self, context: Dict[str, Any]) -> None:
+        try:
+            analysis = self.analyzer.analyze(context)
+        except ProviderError as exc:
+            logger.error("Shadow Debugger could not analyze %s: %s", context.get("exception_type"), exc)
+            return
+        except Exception:
+            logger.exception("Shadow Debugger: unexpected provider failure")
+            return
+
+        context["model"] = self.analyzer.model
+        if self.config.check_patch_syntax:
+            context["patch_check"] = check_patch_syntax(analysis).to_dict()
+        try:
+            self.reporter.report(context, analysis)
+        except Exception:
+            logger.exception("Shadow Debugger failed to write the report")

shadow_debugger/inspector.py

@@ -0,0 +1,176 @@
+"""Collects a redacted snapshot of an exception: location, source, locals, traceback."""
+
+from __future__ import annotations
+
+import hashlib
+import linecache
+import os
+import platform
+import sys
+import sysconfig
+import traceback
+from types import FrameType, TracebackType
+from typing import Any, Dict, List, Optional, Tuple, Type
+
+from .redaction import Redactor
+
+MAX_TRACEBACK_CHARS = 8000
+MAX_MESSAGE_CHARS = 2000
+
+_DEFAULT_REDACTOR = Redactor()
+
+
+def redact_sensitive_data(key: str, value: Any, max_depth: int = 4) -> Any:
+    """Convenience wrapper around :class:`Redactor` for single-value sanitization."""
+    redactor = _DEFAULT_REDACTOR if max_depth == 4 else Redactor(max_depth=max_depth)
+    return redactor.sanitize(key, value)
+
+
+_PACKAGE_DIR = os.path.normcase(os.path.dirname(os.path.abspath(__file__)))
+
+
+def _library_prefixes() -> Tuple[str, ...]:
+    prefixes = set()
+    for name in ("stdlib", "platstdlib", "purelib", "platlib"):
+        path = sysconfig.get_paths().get(name)
+        if path:
+            prefixes.add(os.path.normcase(os.path.abspath(path)))
+    return tuple(prefixes)
+
+
+_LIBRARY_PREFIXES = _library_prefixes()
+
+
+def is_user_code(filename: str) -> bool:
+    """True if the file belongs to the application rather than stdlib/site-packages/us."""
+    if not filename or filename.startswith("<"):
+        return False
+    path = os.path.normcase(os.path.abspath(filename))
+    if path.startswith(_PACKAGE_DIR):
+        return False
+    if "site-packages" in path or "dist-packages" in path:
+        return False
+    return not any(path.startswith(prefix) for prefix in _LIBRARY_PREFIXES)
+
+
+def _walk(tb: Optional[TracebackType]) -> List[Tuple[FrameType, int]]:
+    frames = []
+    while tb is not None:
+        frames.append((tb.tb_frame, tb.tb_lineno))
+        tb = tb.tb_next
+    return frames
+
+
+def select_frame(tb: Optional[TracebackType]) -> Optional[Tuple[FrameType, int]]:
+    """The most relevant frame: the deepest one in user code, else the deepest overall."""
+    frames = _walk(tb)
+    if not frames:
+        return None
+    for frame, lineno in reversed(frames):
+        if is_user_code(frame.f_code.co_filename):
+            return frame, lineno
+    return frames[-1]
+
+
+def compute_fingerprint(exc_type: Type[BaseException], filename: str, lineno: int) -> str:
+    raw = f"{getattr(exc_type, '__qualname__', exc_type)}:{filename}:{lineno}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def fingerprint_exception(exc_type: Type[BaseException], exc_tb: Optional[TracebackType]) -> str:
+    """Cheap fingerprint (no locals, no source) used for throttling before full capture."""
+    selected = select_frame(exc_tb)
+    if selected is None:
+        return compute_fingerprint(exc_type, "", -1)
+    frame, lineno = selected
+    return compute_fingerprint(exc_type, frame.f_code.co_filename, lineno)
+
+
+def extract_code_context(filepath: str, lineno: int, context_lines: int = 5) -> str:
+    if not filepath or lineno <= 0:
+        return ""
+    start = max(1, lineno - context_lines)
+    lines = []
+    for i in range(start, lineno + context_lines + 1):
+        line = linecache.getline(filepath, i)
+        if not line and i > lineno:
+            break
+        marker = ">> " if i == lineno else "   "
+        lines.append(f"{marker}{i:4d}: {line.rstrip()}")
+    return "\n".join(lines)
+
+
+def capture_exception_context(
+    exc_type: Type[BaseException],
+    exc_value: BaseException,
+    exc_tb: Optional[TracebackType],
+    extra_metadata: Optional[Dict[str, Any]] = None,
+    redactor: Optional[Redactor] = None,
+    context_lines: int = 5,
+    include_source: bool = True,
+    include_locals: bool = True,
+) -> Dict[str, Any]:
+    """Build the (redacted) incident payload. Never raises."""
+    redactor = redactor or Redactor()
+
+    try:
+        formatted_tb = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+    except Exception:  # pragma: no cover - defensive
+        formatted_tb = f"{exc_type.__name__}: <traceback unavailable>"
+    if len(formatted_tb) > MAX_TRACEBACK_CHARS:
+        # Keep the tail: that's where the actual error is.
+        formatted_tb = "... (truncated)\n" + formatted_tb[-MAX_TRACEBACK_CHARS:]
+
+    try:
+        message = str(exc_value)
+    except Exception:
+        message = "<unprintable exception message>"
+
+    error_file, error_line, function = "", -1, ""
+    code_context = ""
+    locals_dict: Dict[str, Any] = {}
+
+    selected = select_frame(exc_tb)
+    if selected is not None:
+        frame, error_line = selected
+        error_file = frame.f_code.co_filename
+        function = frame.f_code.co_name
+        if include_source:
+            code_context = redactor.redact_text(extract_code_context(error_file, error_line, context_lines))
+        if include_locals:
+            for name, value in list(frame.f_locals.items()):
+                try:
+                    locals_dict[name] = redactor.sanitize(name, value)
+                except Exception:
+                    locals_dict[name] = f"<{type(value).__name__} (unserializable)>"
+
+    deepest = _walk(exc_tb)[-1] if exc_tb is not None else None
+    raised_in = None
+    if deepest is not None and selected is not None and deepest[0] is not selected[0]:
+        raised_in = f"{deepest[0].f_code.co_filename}:{deepest[1]} in {deepest[0].f_code.co_name}"
+
+    metadata: Dict[str, Any] = {}
+    for key, value in (extra_metadata or {}).items():
+        try:
+            metadata[str(key)] = redactor.sanitize(str(key), value)
+        except Exception:
+            metadata[str(key)] = "<unserializable>"
+
+    return {
+        "exception_type": getattr(exc_type, "__name__", str(exc_type)),
+        "exception_message": redactor.redact_text(message, limit=MAX_MESSAGE_CHARS),
+        "traceback": redactor.redact_text(formatted_tb),
+        "file": error_file,
+        "line": error_line,
+        "function": function,
+        "raised_in": raised_in,
+        "code_context": code_context,
+        "locals": locals_dict,
+        "extra_metadata": metadata,
+        "fingerprint": compute_fingerprint(exc_type, error_file, error_line),
+        "runtime": {
+            "python": platform.python_version(),
+            "implementation": platform.python_implementation(),
+            "platform": sys.platform,
+        },
+    }

shadow_debugger/integrations/__init__.py

@@ -0,0 +1,224 @@
+"""Web framework integrations: FastAPI / Starlette (pure ASGI), Flask, and Django.
+
+All integrations attach sanitized HTTP request metadata to the incident and re-raise the
+exception so the framework's normal error handling (status code, response body, logging)
+is preserved.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import parse_qsl, urlencode
+
+from ..core import ShadowCore
+
+_SENSITIVE_HEADER_NAMES = {
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-auth-token",
+    "x-csrf-token",
+    "x-xsrf-token",
+}
+
+
+def _resolve_core(core: Optional[ShadowCore]) -> Optional[ShadowCore]:
+    if core is not None:
+        return core
+    from .. import get_core
+
+    return get_core()
+
+
+def _sanitize_headers(raw_headers: Any) -> Dict[str, str]:
+    headers: Dict[str, str] = {}
+    try:
+        items = raw_headers.items() if hasattr(raw_headers, "items") else raw_headers
+        for k, v in items:
+            key = k.decode("latin-1") if isinstance(k, (bytes, bytearray)) else str(k)
+            val = v.decode("latin-1") if isinstance(v, (bytes, bytearray)) else str(v)
+            if key.lower() in _SENSITIVE_HEADER_NAMES:
+                headers[key] = "[REDACTED]"
+            else:
+                headers[key] = val[:200]
+    except Exception:
+        pass
+    return headers
+
+
+class ASGIWatcherMiddleware:
+    """Pure ASGI middleware compatible with FastAPI, Starlette, Litestar, Quart, etc.
+
+    Unlike Starlette's ``BaseHTTPMiddleware``, a pure ASGI middleware does not buffer
+    streaming responses, break ``contextvars``, or interfere with background tasks.
+    """
+
+    def __init__(self, app: Any, core: Optional[ShadowCore] = None) -> None:
+        self.app = app
+        self.core = core
+
+    async def __call__(self, scope: Dict[str, Any], receive: Callable, send: Callable) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        try:
+            await self.app(scope, receive, send)
+        except Exception as exc:
+            active_core = _resolve_core(self.core)
+            if active_core is not None:
+                http_meta = _extract_asgi_metadata(scope)
+                exc_type, exc_value, exc_tb = sys.exc_info()
+                if exc_type is not None and exc_value is not None:
+                    active_core.capture(
+                        exc_type,
+                        exc_value,
+                        exc_tb,
+                        extra_metadata={"http_request": http_meta},
+                    )
+                else:
+                    active_core.capture_exception(exc, extra_metadata={"http_request": http_meta})
+            raise
+
+
+# Alias kept for backward compatibility and clarity in FastAPI apps.
+FastAPIWatcherMiddleware = ASGIWatcherMiddleware
+
+
+def _extract_asgi_metadata(scope: Dict[str, Any]) -> Dict[str, Any]:
+    method = scope.get("method", "UNKNOWN")
+    scheme = scope.get("scheme", "http")
+    path = scope.get("path", "")
+    raw_qs = scope.get("query_string", b"")
+    qs = raw_qs.decode("latin-1", errors="replace") if isinstance(raw_qs, (bytes, bytearray)) else str(raw_qs)
+
+    headers = _sanitize_headers(scope.get("headers") or [])
+    host = headers.get("host") or headers.get("Host") or "localhost"
+    url = f"{scheme}://{host}{path}" + (f"?{qs}" if qs else "")
+
+    client = scope.get("client")
+    client_ip = client[0] if isinstance(client, (list, tuple)) and client else "unknown"
+    query_params = dict(parse_qsl(qs, keep_blank_values=True)) if qs else {}
+
+    return {
+        "framework": "ASGI/FastAPI",
+        "http_method": method,
+        "url": url,
+        "path": path,
+        "client_ip": client_ip,
+        "query_params": query_params,
+        "headers": headers,
+    }
+
+
+def init_flask(app: Any, core: Optional[ShadowCore] = None) -> None:
+    """Attach Shadow Debugger to a Flask app without breaking 404/4xx HTTPExceptions.
+
+    Usage::
+
+        app = Flask(__name__)
+        shadow_debugger.init_flask(app)
+    """
+    try:
+        from flask import got_request_exception, request
+    except ImportError as exc:
+        raise ImportError("Flask is not installed. Run: pip install 'shadow-debugger[flask]'") from exc
+
+    def _on_request_exception(sender: Any, exception: BaseException, **extra: Any) -> None:
+        # Ignore standard 4xx Werkzeug HTTPExceptions (404 Not Found, 405 Method Not Allowed, etc.)
+        status_code = getattr(exception, "code", None)
+        if isinstance(status_code, int) and status_code < 500:
+            return
+
+        active_core = _resolve_core(core)
+        if active_core is None:
+            return
+
+        try:
+            http_meta = {
+                "framework": "Flask",
+                "http_method": getattr(request, "method", "UNKNOWN"),
+                "url": getattr(request, "url", ""),
+                "path": getattr(request, "path", ""),
+                "endpoint": getattr(request, "endpoint", None),
+                "client_ip": getattr(request, "remote_addr", "unknown"),
+                "query_params": dict(getattr(request, "args", {}) or {}),
+                "headers": _sanitize_headers(getattr(request, "headers", {}) or {}),
+            }
+        except Exception:
+            http_meta = {"framework": "Flask"}
+
+        active_core.capture(
+            type(exception),
+            exception,
+            exception.__traceback__,
+            extra_metadata={"http_request": http_meta},
+        )
+
+    got_request_exception.connect(_on_request_exception, app, weak=False)
+
+
+class DjangoWatcherMiddleware:
+    """Django middleware that captures unhandled view exceptions (HTTP 500).
+
+    Add to ``MIDDLEWARE`` in ``settings.py``::
+
+        MIDDLEWARE = [
+            "shadow_debugger.integrations.DjangoWatcherMiddleware",
+            ...
+        ]
+    """
+
+    sync_capable = True
+    async_capable = False
+
+    def __init__(self, get_response: Callable, core: Optional[ShadowCore] = None) -> None:
+        self.get_response = get_response
+        self.core = core
+
+    def __call__(self, request: Any) -> Any:
+        return self.get_response(request)
+
+    def process_exception(self, request: Any, exception: BaseException) -> None:
+        # Skip Django's Http404 / PermissionDenied
+        exc_name = type(exception).__name__
+        if exc_name in ("Http404", "PermissionDenied", "SuspiciousOperation"):
+            return None
+
+        active_core = _resolve_core(self.core)
+        if active_core is None:
+            return None
+
+        try:
+            query_params = dict(getattr(request, "GET", {}) or {})
+            path = getattr(request, "path", "")
+            qs = urlencode(query_params, doseq=True) if query_params else ""
+            http_meta = {
+                "framework": "Django",
+                "http_method": getattr(request, "method", "UNKNOWN"),
+                "path": path,
+                "url": f"{path}?{qs}" if qs else path,
+                "query_params": query_params,
+                "user": str(getattr(request, "user", "anonymous")),
+            }
+        except Exception:
+            http_meta = {"framework": "Django"}
+
+        active_core.capture(
+            type(exception),
+            exception,
+            exception.__traceback__,
+            extra_metadata={"http_request": http_meta},
+        )
+        return None
+
+
+__all__ = [
+    "ASGIWatcherMiddleware",
+    "FastAPIWatcherMiddleware",
+    "init_flask",
+    "DjangoWatcherMiddleware",
+]

shadow_debugger/patch_check.py

@@ -0,0 +1,57 @@
+"""Syntax check for code snippets suggested by the model."""
+
+from __future__ import annotations
+
+import ast
+import re
+import textwrap
+import warnings
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, List
+
+_CODE_BLOCK = re.compile(r"```(?:python|py)[ \t]*\r?\n(.*?)```", re.DOTALL | re.IGNORECASE)
+_LINE_NUMBER_PREFIX = re.compile(r"^(?:>>)?\s*\d+:\s?")
+
+
+@dataclass
+class PatchCheckResult:
+    attempted: bool
+    success: bool
+    message: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+def extract_python_blocks(markdown: str) -> List[str]:
+    return [m.strip("\n") for m in _CODE_BLOCK.findall(markdown or "") if m.strip()]
+
+
+def _clean(snippet: str) -> str:
+    lines = snippet.splitlines()
+    if lines and all(_LINE_NUMBER_PREFIX.match(line) for line in lines if line.strip()):
+        lines = [_LINE_NUMBER_PREFIX.sub("", line, count=1) for line in lines]
+    return textwrap.dedent("\n".join(lines))
+
+
+def check_patch_syntax(ai_analysis: str) -> PatchCheckResult:
+    blocks = extract_python_blocks(ai_analysis)
+    if not blocks:
+        return PatchCheckResult(False, False, "No ```python block found in the analysis.")
+
+    errors: List[str] = []
+    for index, block in enumerate(blocks, start=1):
+        source = _clean(block)
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", SyntaxWarning)
+                ast.parse(source)
+        except SyntaxError as exc:
+            errors.append(f"block {index}, line {exc.lineno}: {exc.msg}")
+
+    if errors:
+        return PatchCheckResult(True, False, "Proposed code has syntax errors: " + "; ".join(errors))
+    noun = "snippet" if len(blocks) == 1 else "snippets"
+    return PatchCheckResult(
+        True, True, f"{len(blocks)} proposed {noun} parsed cleanly."
+    )