bubble-analysis 0.2.0__py3-none-any.whl → 0.3.4__py3-none-any.whl

bubble/integrations/flask/detector.py

@@ -6,6 +6,8 @@ from libcst.metadata import MetadataWrapper, PositionProvider
 from bubble.enums import EntrypointKind, Framework
 from bubble.integrations.base import Entrypoint, GlobalHandler
 
+HTTP_METHODS = {"get", "post", "put", "delete", "patch", "head", "options"}
+
 
 class FlaskRouteVisitor(cst.CSTVisitor):
     """
@@ -157,21 +159,185 @@ class FlaskErrorHandlerVisitor(cst.CSTVisitor):
         return ""
 
 
+class FlaskRESTfulVisitor(cst.CSTVisitor):
+    """
+    Detects Flask-RESTful Resource classes and add_resource() registrations.
+
+    Supports:
+    - api.add_resource(ResourceClass, "/path")
+    - api.add_resource(ResourceClass, "/path1", "/path2")
+    - Custom methods like api.add_org_resource()
+    """
+
+    METADATA_DEPENDENCIES = (PositionProvider,)
+
+    ADD_RESOURCE_METHODS = {"add_resource", "add_org_resource"}
+
+    def __init__(self, file_path: str) -> None:
+        self.file_path = file_path
+        self.entrypoints: list[Entrypoint] = []
+        self.resource_classes: dict[str, dict[str, int]] = {}
+        self.resource_registrations: list[tuple[str, list[str], int]] = []
+
+    def visit_ClassDef(self, node: cst.ClassDef) -> bool:
+        methods_found: dict[str, int] = {}
+        for item in node.body.body:
+            if isinstance(item, cst.FunctionDef):
+                method_name = item.name.value.lower()
+                if method_name in HTTP_METHODS and not self._has_route_decorator(item):
+                    pos = self.get_metadata(PositionProvider, item)
+                    methods_found[method_name.upper()] = pos.start.line
+
+        if methods_found:
+            self.resource_classes[node.name.value] = methods_found
+
+        return True
+
+    def _has_route_decorator(self, node: cst.FunctionDef) -> bool:
+        """Check if a function has a route decorator like @expose, @route."""
+        for decorator in node.decorators:
+            dec = decorator.decorator
+            if isinstance(dec, cst.Call):
+                if isinstance(dec.func, cst.Attribute):
+                    if dec.func.attr.value in ("route", "expose"):
+                        return True
+                elif isinstance(dec.func, cst.Name):
+                    if dec.func.value in ("route", "expose"):
+                        return True
+            elif isinstance(dec, cst.Attribute):
+                if dec.attr.value in ("route", "expose"):
+                    return True
+            elif isinstance(dec, cst.Name):
+                if dec.value in ("route", "expose"):
+                    return True
+        return False
+
+    def visit_Call(self, node: cst.Call) -> bool:
+        if not isinstance(node.func, cst.Attribute):
+            return True
+
+        method_name = node.func.attr.value
+        if method_name not in self.ADD_RESOURCE_METHODS:
+            return True
+
+        if len(node.args) < 2:
+            return True
+
+        first_arg = node.args[0].value
+        resource_name = self._get_name_from_expr(first_arg)
+        if not resource_name:
+            return True
+
+        urls: list[str] = []
+        for arg in node.args[1:]:
+            if arg.keyword is not None:
+                continue
+            url = self._extract_string(arg.value)
+            if url:
+                urls.append(url)
+
+        if urls:
+            pos = self.get_metadata(PositionProvider, node)
+            self.resource_registrations.append((resource_name, urls, pos.start.line))
+
+        return True
+
+    def leave_Module(self, original_node: cst.Module) -> None:
+        registered_classes: set[str] = set()
+
+        for resource_name, urls, reg_line in self.resource_registrations:
+            registered_classes.add(resource_name)
+            methods = self.resource_classes.get(resource_name, {})
+            if not methods:
+                methods = {"GET": reg_line}
+
+            for url in urls:
+                for method, method_line in methods.items():
+                    self.entrypoints.append(
+                        Entrypoint(
+                            file=self.file_path,
+                            function=f"{resource_name}.{method.lower()}",
+                            line=method_line,
+                            kind=EntrypointKind.HTTP_ROUTE,
+                            metadata={
+                                "http_method": method,
+                                "http_path": url,
+                                "framework": Framework.FLASK,
+                                "flask_restful": True,
+                            },
+                        )
+                    )
+
+        for class_name, methods in self.resource_classes.items():
+            if class_name in registered_classes:
+                continue
+
+            for method, method_line in methods.items():
+                self.entrypoints.append(
+                    Entrypoint(
+                        file=self.file_path,
+                        function=f"{class_name}.{method.lower()}",
+                        line=method_line,
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        metadata={
+                            "http_method": method,
+                            "http_path": f"<flask-restful:{class_name}>",
+                            "framework": Framework.FLASK,
+                            "flask_restful": True,
+                        },
+                    )
+                )
+
+    def _get_name_from_expr(self, expr: cst.BaseExpression) -> str:
+        if isinstance(expr, cst.Name):
+            return expr.value
+        elif isinstance(expr, cst.Attribute):
+            return expr.attr.value
+        return ""
+
+    def _extract_string(self, node: cst.BaseExpression) -> str | None:
+        if isinstance(node, cst.SimpleString):
+            return node.evaluated_value
+        elif isinstance(node, cst.ConcatenatedString):
+            parts = []
+            for part in (node.left, node.right):
+                if isinstance(part, cst.SimpleString):
+                    val = part.evaluated_value
+                    if val:
+                        parts.append(val)
+            return "".join(parts) if parts else None
+        return None
+
+
 def detect_flask_entrypoints(source: str, file_path: str) -> list[Entrypoint]:
-    """Detect Flask route entrypoints in a Python source file."""
+    """Detect Flask route entrypoints in a Python source file.
+
+    Detects both decorator-based routes (@app.route) and
+    Flask-RESTful call-based routes (api.add_resource).
+    """
     try:
         module = cst.parse_module(source)
     except Exception:
         return []
 
+    entrypoints: list[Entrypoint] = []
     wrapper = MetadataWrapper(module)
-    visitor = FlaskRouteVisitor(file_path)
 
+    route_visitor = FlaskRouteVisitor(file_path)
     try:
-        wrapper.visit(visitor)
-        return visitor.entrypoints
+        wrapper.visit(route_visitor)
+        entrypoints.extend(route_visitor.entrypoints)
     except Exception:
-        return []
+        pass
+
+    restful_visitor = FlaskRESTfulVisitor(file_path)
+    try:
+        wrapper.visit(restful_visitor)
+        entrypoints.extend(restful_visitor.entrypoints)
+    except Exception:
+        pass
+
+    return entrypoints
 
 
 def detect_flask_global_handlers(source: str, file_path: str) -> list[GlobalHandler]:
@@ -189,3 +355,75 @@ def detect_flask_global_handlers(source: str, file_path: str) -> list[GlobalHand
         return visitor.handlers
     except Exception:
         return []
+
+
+def correlate_flask_restful_entrypoints(entrypoints: list[Entrypoint]) -> list[Entrypoint]:
+    """Correlate Flask-RESTful entrypoints across files.
+
+    Flask-RESTful apps often define Resource classes in one file and register
+    them with api.add_resource() in another. This function merges information
+    from both sources:
+    - Class definitions have correct methods but placeholder paths
+    - Registrations have correct paths but fallback methods
+
+    Same-file cases (already fully resolved) are passed through unchanged.
+    Only placeholder entries trigger cross-file correlation.
+
+    Returns a new list with correlated entrypoints.
+    """
+    placeholder_classes: dict[str, list[Entrypoint]] = {}
+    real_path_entries: dict[str, list[Entrypoint]] = {}
+    non_flask_restful: list[Entrypoint] = []
+
+    for ep in entrypoints:
+        if not ep.metadata.get("flask_restful"):
+            non_flask_restful.append(ep)
+            continue
+
+        path = ep.metadata.get("http_path", "")
+
+        if path.startswith("<flask-restful:") and path.endswith(">"):
+            class_name = path[15:-1]
+            if class_name not in placeholder_classes:
+                placeholder_classes[class_name] = []
+            placeholder_classes[class_name].append(ep)
+        else:
+            parts = ep.function.rsplit(".", 1)
+            if len(parts) == 2:
+                class_name = parts[0]
+                if class_name not in real_path_entries:
+                    real_path_entries[class_name] = []
+                real_path_entries[class_name].append(ep)
+            else:
+                non_flask_restful.append(ep)
+
+    result: list[Entrypoint] = list(non_flask_restful)
+
+    for class_name, class_eps in placeholder_classes.items():
+        if class_name in real_path_entries:
+            reg_eps = real_path_entries[class_name]
+            paths_from_registrations = list({ep.metadata.get("http_path") for ep in reg_eps})
+
+            for class_ep in class_eps:
+                for reg_path in paths_from_registrations:
+                    result.append(
+                        Entrypoint(
+                            file=class_ep.file,
+                            function=class_ep.function,
+                            line=class_ep.line,
+                            kind=class_ep.kind,
+                            metadata={
+                                **class_ep.metadata,
+                                "http_path": reg_path,
+                            },
+                        )
+                    )
+
+            del real_path_entries[class_name]
+        else:
+            result.extend(class_eps)
+
+    for class_name, eps in real_path_entries.items():
+        result.extend(eps)
+
+    return result

bubble/integrations/formatters.py

@@ -53,6 +53,13 @@ def audit(
                         ]
                         for exc_type, raises_list in issue.caught_by_generic.items()
                     },
+                    "caught_by_remote": {
+                        exc_type: [
+                            {"file": r.file, "line": r.line, "function": r.function}
+                            for r in raises_list
+                        ]
+                        for exc_type, raises_list in issue.caught_by_remote.items()
+                    },
                 }
                 for issue in result.issues
             ],

bubble/integrations/models.py

@@ -22,11 +22,19 @@ class IntegrationData:
 
 @dataclass
 class AuditIssue:
-    """An entrypoint with uncaught or poorly-handled exceptions."""
+    """An entrypoint with uncaught or poorly-handled exceptions.
+
+    Fields:
+    - uncaught: Exceptions with no handler at all
+    - caught_by_generic: Caught by generic handler (@errorhandler(Exception))
+    - caught_by_remote: Caught by a handler in a different file (may indicate missing local handler)
+    - caught: Caught by a handler in the same file
+    """
 
     entrypoint: Entrypoint
     uncaught: dict[str, list["RaiseSite"]]
     caught_by_generic: dict[str, list["RaiseSite"]]
+    caught_by_remote: dict[str, list["RaiseSite"]]
     caught: dict[str, list["RaiseSite"]]
 
 

bubble/integrations/queries.py

@@ -3,6 +3,8 @@
 Shared audit/entrypoint logic that all integrations use.
 """
 
+from typing import TYPE_CHECKING
+
 from bubble.config import FlowConfig
 from bubble.integrations.base import Entrypoint, GlobalHandler, Integration
 from bubble.integrations.models import (
@@ -23,6 +25,9 @@ from bubble.propagation import (
     propagate_exceptions,
 )
 
+if TYPE_CHECKING:
+    from bubble.stubs import StubLibrary
+
 
 def _filter_async_boundaries(
     forward_graph: dict[str, set[str]], config: FlowConfig
@@ -51,6 +56,7 @@ def _compute_exception_flow_for_integration(
     forward_graph: dict[str, set[str]] | None = None,
     name_to_qualified: dict[str, list[str]] | None = None,
     config: FlowConfig | None = None,
+    entrypoint_file: str | None = None,
 ) -> ExceptionFlow:
     """Compute exception flow for a function with integration-specific handling.
 
@@ -134,9 +140,17 @@ def _compute_exception_flow_for_integration(
                     flow.caught_by_generic[exc_type] = []
                 flow.caught_by_generic[exc_type].extend(raise_sites)
             else:
-                if exc_type not in flow.caught_by_global:
-                    flow.caught_by_global[exc_type] = []
-                flow.caught_by_global[exc_type].extend(raise_sites)
+                is_same_file = (
+                    entrypoint_file is not None and caught_by_handler.file == entrypoint_file
+                )
+                if is_same_file:
+                    if exc_type not in flow.caught_by_global:
+                        flow.caught_by_global[exc_type] = []
+                    flow.caught_by_global[exc_type].extend(raise_sites)
+                else:
+                    if exc_type not in flow.caught_by_remote_global:
+                        flow.caught_by_remote_global[exc_type] = []
+                    flow.caught_by_remote_global[exc_type].extend(raise_sites)
             continue
 
         framework_response = integration.get_exception_response(exc_type)
@@ -181,6 +195,7 @@ def audit_integration(
     global_handlers: list[GlobalHandler],
     skip_evidence: bool = True,
     config: FlowConfig | None = None,
+    stub_library: "StubLibrary | None" = None,
 ) -> AuditResult:
     """Audit entrypoints for a specific integration.
 
@@ -188,6 +203,7 @@ def audit_integration(
         skip_evidence: Skip building evidence paths for faster auditing.
                        Set to False if you need path details.
         config: Optional FlowConfig with handled_base_classes and async_boundaries.
+        stub_library: Optional stub library for external library exceptions.
     """
     if not entrypoints:
         return AuditResult(
@@ -197,7 +213,9 @@ def audit_integration(
             clean_count=0,
         )
 
-    propagation = propagate_exceptions(model, skip_evidence=skip_evidence)
+    propagation = propagate_exceptions(
+        model, skip_evidence=skip_evidence, stub_library=stub_library
+    )
     reraise_patterns = {"Unknown", "e", "ex", "err", "exc", "error", "exception"}
 
     forward_graph = build_forward_call_graph(model)
@@ -218,12 +236,16 @@ def audit_integration(
             forward_graph,
             name_to_qualified,
             config,
+            entrypoint_file=entrypoint.file,
         )
 
         real_uncaught = {k: v for k, v in flow.uncaught.items() if k not in reraise_patterns}
         real_generic = {
             k: v for k, v in flow.caught_by_generic.items() if k not in reraise_patterns
         }
+        real_remote = {
+            k: v for k, v in flow.caught_by_remote_global.items() if k not in reraise_patterns
+        }
 
         if real_uncaught or real_generic:
             issues.append(
@@ -231,6 +253,7 @@ def audit_integration(
                     entrypoint=entrypoint,
                     uncaught=real_uncaught,
                     caught_by_generic=real_generic,
+                    caught_by_remote=real_remote,
                     caught=flow.caught_by_global,
                 )
             )
@@ -399,10 +422,14 @@ def _trace_to_entrypoints(
             return
         visited.add(current)
 
-        current_simple = current.split("::")[-1] if "::" in current else current
-        current_simple = current_simple.split(".")[-1]
+        current_qualified = current.split("::")[-1] if "::" in current else current
+        current_simple = current_qualified.split(".")[-1]
 
-        if current in entrypoint_functions or current_simple in entrypoint_functions:
+        if (
+            current in entrypoint_functions
+            or current_qualified in entrypoint_functions
+            or current_simple in entrypoint_functions
+        ):
             paths.append(list(path))
             return
 
@@ -411,13 +438,11 @@ def _trace_to_entrypoints(
             if len(paths) >= max_paths:
                 return
             if reachable_from_entrypoints is not None:
-                caller_simple = (
-                    caller.split("::")[-1].split(".")[-1]
-                    if "::" in caller
-                    else caller.split(".")[-1]
-                )
+                caller_qualified = caller.split("::")[-1] if "::" in caller else caller
+                caller_simple = caller_qualified.split(".")[-1]
                 if (
                     caller not in reachable_from_entrypoints
+                    and caller_qualified not in reachable_from_entrypoints
                     and caller_simple not in reachable_from_entrypoints
                 ):
                     continue
@@ -460,7 +485,9 @@ def trace_routes_to_exception(
                 endpoint = path[-1]
                 entrypoints_reached.add(endpoint)
                 if "::" in endpoint:
-                    entrypoints_reached.add(endpoint.split("::")[-1].split(".")[-1])
+                    qualified_part = endpoint.split("::")[-1]
+                    entrypoints_reached.add(qualified_part)
+                    entrypoints_reached.add(qualified_part.split(".")[-1])
 
         matching_entrypoints = [e for e in entrypoints if e.function in entrypoints_reached]