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

bubble/detectors.py

@@ -13,6 +13,7 @@ from bubble.integrations.cli_scripts.detector import (
 from bubble.integrations.django.detector import (
     DjangoExceptionHandlerVisitor,
     DjangoViewVisitor,
+    detect_django_entrypoints,
 )
 from bubble.integrations.django.semantics import (
     EXCEPTION_RESPONSES as DJANGO_EXCEPTION_RESPONSES,
@@ -26,7 +27,9 @@ from bubble.integrations.fastapi.semantics import (
 )
 from bubble.integrations.flask.detector import (
     FlaskErrorHandlerVisitor,
+    FlaskRESTfulVisitor,
     FlaskRouteVisitor,
+    detect_flask_entrypoints,
 )
 from bubble.integrations.flask.semantics import (
     EXCEPTION_RESPONSES as FLASK_EXCEPTION_RESPONSES,
@@ -53,13 +56,13 @@ FRAMEWORK_EXCEPTION_RESPONSES: dict[str, dict[str, str]] = {
 def detect_entrypoints(source: str, file_path: str) -> list[Entrypoint]:
     """Detect entrypoints in a Python source file (HTTP routes and CLI scripts).
 
-    Uses the generic detector with Flask, FastAPI, and Django configurations,
-    plus CLI script detection.
+    Uses framework-specific detectors for Flask and Django (with HTTP method detection),
+    the generic detector for FastAPI, plus CLI script detection.
     """
     entrypoints: list[Entrypoint] = []
-    entrypoints.extend(generic_detect_entrypoints(source, file_path, FLASK_CONFIG))
+    entrypoints.extend(detect_flask_entrypoints(source, file_path))
     entrypoints.extend(generic_detect_entrypoints(source, file_path, FASTAPI_CONFIG))
-    entrypoints.extend(generic_detect_entrypoints(source, file_path, DJANGO_CONFIG))
+    entrypoints.extend(detect_django_entrypoints(source, file_path))
     entrypoints.extend(detect_cli_entrypoints(source, file_path))
     return entrypoints
 

bubble/extractor.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
     pass
 
 from bubble.detectors import detect_entrypoints, detect_global_handlers
+from bubble.integrations.flask import correlate_flask_restful_entrypoints
 from bubble.enums import ResolutionKind
 from bubble.loader import load_detectors
 from bubble.models import (
@@ -440,13 +441,19 @@ class CodeExtractor(cst.CSTVisitor):
         return True
 
     def _get_current_qualified_name(self) -> str:
-        """Get the fully qualified name of the current context."""
-        parts = [self.relative_path]
+        """Get the fully qualified name of the current context.
+
+        Returns format: file.py::Class.method (matches canonical format from CLAUDE.md)
+        """
         if self._class_stack:
-            parts.append(".".join(self._class_stack))
-        if self._function_stack:
-            parts.append(self._function_stack[-1])
-        return "::".join(parts) if len(parts) > 1 else parts[0]
+            if self._function_stack:
+                qualified = ".".join(self._class_stack + [self._function_stack[-1]])
+            else:
+                qualified = ".".join(self._class_stack)
+            return f"{self.relative_path}::{qualified}"
+        elif self._function_stack:
+            return f"{self.relative_path}::{self._function_stack[-1]}"
+        return self.relative_path
 
     def _extract_depends_calls(
         self,
@@ -615,13 +622,14 @@ def extract_from_file(file_path: Path, relative_path: str | None = None) -> File
     result.return_types = extractor.return_types
     result.detected_frameworks = extractor.detected_frameworks
 
+    detection_path = relative_path if relative_path else str(file_path)
     try:
-        result.entrypoints = detect_entrypoints(source, str(file_path))
+        result.entrypoints = detect_entrypoints(source, detection_path)
     except Exception:
         pass
 
     try:
-        result.global_handlers = detect_global_handlers(source, str(file_path))
+        result.global_handlers = detect_global_handlers(source, detection_path)
     except Exception:
         pass
 
@@ -664,6 +672,10 @@ def _inject_drf_dispatch_calls(model: ProgramModel) -> None:
     When a DRF view class is detected as an entrypoint, this creates CallSite
     entries from the view class to each HTTP method handler (get, post, etc.)
     that exists on the class.
+
+    Handles both:
+    - Class-level entrypoints: "UserAPIView" -> creates edges to get, post, etc.
+    - Method-level entrypoints: "UserAPIView.get" -> creates edge to that method
     """
     drf_view_entrypoints = [
         ep
@@ -671,18 +683,32 @@ def _inject_drf_dispatch_calls(model: ProgramModel) -> None:
         if ep.metadata.get("framework") == "django" and ep.metadata.get("view_type") == "class"
     ]
 
+    seen_edges: set[tuple[str, str]] = set()
+
     for entrypoint in drf_view_entrypoints:
-        view_class = entrypoint.function
+        view_function = entrypoint.function
         view_file = entrypoint.file
         view_line = entrypoint.line
 
+        if "." in view_function:
+            view_class, method_name = view_function.rsplit(".", 1)
+            methods_to_inject = [method_name] if method_name in DRF_DISPATCH_METHODS else []
+        else:
+            view_class = view_function
+            methods_to_inject = list(DRF_DISPATCH_METHODS)
+
         for _func_key, func_def in model.functions.items():
             if not func_def.is_method:
                 continue
             if func_def.class_name != view_class:
                 continue
-            if func_def.name not in DRF_DISPATCH_METHODS:
+            if func_def.name not in methods_to_inject:
+                continue
+
+            edge_key = (view_class, func_def.name)
+            if edge_key in seen_edges:
                 continue
+            seen_edges.add(edge_key)
 
             relative_file = view_file
             if "/" in relative_file or "\\" in relative_file:
@@ -824,6 +850,7 @@ def extract_from_directory(
     if cache:
         cache.close()
 
+    model.entrypoints = correlate_flask_restful_entrypoints(model.entrypoints)
     _inject_drf_dispatch_calls(model)
 
     return model

bubble/formatters.py

@@ -694,7 +694,13 @@ def catches(
 
     total = len(result.local_catches) + len(result.global_handlers)
     if total == 0:
-        console.print(f"[yellow]No catch sites found for {result.exception_type}[/yellow]")
+        if result.raise_site_count == 0:
+            console.print(
+                f"[yellow]No catch sites found for {result.exception_type}[/yellow]\n"
+                f"[dim]  (this exception is not raised anywhere in the codebase)[/dim]"
+            )
+        else:
+            console.print(f"[yellow]No catch sites found for {result.exception_type}[/yellow]")
         return
 
     subclass_note = " (and subclasses)" if result.include_subclasses else ""

bubble/integrations/cli_scripts/cli.py

@@ -16,6 +16,7 @@ from bubble.integrations.queries import (
     trace_routes_to_exception,
 )
 from bubble.models import ProgramModel
+from bubble.stubs import load_stubs
 
 app = typer.Typer(
     name="cli",
@@ -57,7 +58,10 @@ def audit(
     directory = directory.resolve()
     model = _build_model(directory, use_cache=not no_cache)
     entrypoints = _get_cli_entrypoints(model)
-    result = audit_integration(model, integration, entrypoints, [])
+    stub_library = load_stubs(directory)
+    result = audit_integration(
+        model, integration, entrypoints, [], stub_library=stub_library
+    )
     formatters.audit(result, OutputFormat(output_format), directory, console)
 
 

bubble/integrations/django/cli.py

@@ -40,8 +40,28 @@ def _get_django_entrypoints_and_handlers(model: ProgramModel) -> tuple[list, lis
     return entrypoints, handlers
 
 
+def _filter_entrypoints(
+    entrypoints: list, filter_arg: str | None, directory: Path
+) -> list:
+    """Filter entrypoints by file path or route path."""
+    if not filter_arg:
+        return entrypoints
+
+    if filter_arg.startswith("/"):
+        return [e for e in entrypoints if e.metadata.get("http_path") == filter_arg]
+
+    filter_path = Path(filter_arg)
+    if not filter_path.is_absolute():
+        filter_path = directory / filter_path
+
+    return [e for e in entrypoints if Path(directory / e.file).resolve() == filter_path.resolve()]
+
+
 @app.command()
 def audit(
+    filter_arg: Annotated[
+        str | None, typer.Argument(help="Filter by file path or route (e.g., /users)")
+    ] = None,
     directory: Annotated[
         Path, typer.Option("--directory", "-d", help="Directory to analyze")
     ] = Path("."),
@@ -50,22 +70,35 @@ def audit(
 ) -> None:
     """Check Django views for escaping exceptions.
 
-    Scans every Django view (APIView, ViewSet, @api_view), reports which have uncaught exceptions.
+    Scans Django views (APIView, ViewSet, @api_view) and reports which have uncaught exceptions.
 
-    Example:
-        flow django audit
-        flow django audit -d /path/to/project
+    Examples:
+        bubble django audit                          # All views
+        bubble django audit /users                   # Views matching /users
+        bubble django audit views/users.py           # Views in specific file
     """
     directory = directory.resolve()
     config = load_config(directory)
     model = _build_model(directory, use_cache=not no_cache)
     entrypoints, handlers = _get_django_entrypoints_and_handlers(model)
+    entrypoints = _filter_entrypoints(entrypoints, filter_arg, directory)
+
+    if filter_arg and not entrypoints:
+        if filter_arg.startswith("/"):
+            console.print(f"[yellow]No Django views found matching {filter_arg}[/yellow]")
+        else:
+            console.print(f"[yellow]No Django views found in {filter_arg}[/yellow]")
+        return
+
     result = audit_integration(model, integration, entrypoints, handlers, config=config)
     formatters.audit(result, output_format, directory, console)
 
 
 @app.command(name="entrypoints")
 def list_views(
+    filter_arg: Annotated[
+        str | None, typer.Argument(help="Filter by file path or route (e.g., /users)")
+    ] = None,
     directory: Annotated[
         Path, typer.Option("--directory", "-d", help="Directory to analyze")
     ] = Path("."),
@@ -74,12 +107,15 @@ def list_views(
 ) -> None:
     """List Django views (APIView, ViewSet, @api_view).
 
-    Example:
-        flow django entrypoints
+    Examples:
+        bubble django entrypoints                    # All views
+        bubble django entrypoints /users             # Views matching /users
+        bubble django entrypoints views/users.py     # Views in specific file
     """
     directory = directory.resolve()
     model = _build_model(directory, use_cache=not no_cache)
     entrypoints, _ = _get_django_entrypoints_and_handlers(model)
+    entrypoints = _filter_entrypoints(entrypoints, filter_arg, directory)
     result = list_integration_entrypoints(integration, entrypoints)
     formatters.entrypoints(result, output_format, directory, console)
 

bubble/integrations/django/detector.py

@@ -23,6 +23,17 @@ DRF_BASE_CLASSES = {
     "RetrieveUpdateDestroyAPIView",
 }
 
+DRF_HTTP_METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}
+DRF_ACTION_METHODS = {"list", "create", "retrieve", "update", "partial_update", "destroy"}
+DRF_METHOD_TO_HTTP = {
+    "list": "GET",
+    "create": "POST",
+    "retrieve": "GET",
+    "update": "PUT",
+    "partial_update": "PATCH",
+    "destroy": "DELETE",
+}
+
 DRF_GENERICS_QUALIFIERS = {
     "generics",
     "rest_framework.generics",
@@ -51,31 +62,65 @@ class DjangoViewVisitor(cst.CSTVisitor):
         self._in_class: str | None = None
         self._class_is_view = False
         self._class_line: int = 0
+        self._class_methods: dict[str, int] = {}
 
     def visit_ClassDef(self, node: cst.ClassDef) -> bool:
         self._in_class = node.name.value
         self._class_is_view = self._is_view_class(node)
+        self._class_methods = {}
         if self._class_is_view:
             pos = self.get_metadata(PositionProvider, node)
             self._class_line = pos.start.line
-            self.entrypoints.append(
-                Entrypoint(
-                    file=self.file_path,
-                    function=node.name.value,
-                    line=self._class_line,
-                    kind="http_route",
-                    metadata={
-                        "framework": "django",
-                        "view_type": "class",
-                    },
-                )
-            )
+        return True
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:
+        if self._class_is_view and self._in_class:
+            method_name = node.name.value.lower()
+            if method_name in DRF_HTTP_METHODS or method_name in DRF_ACTION_METHODS:
+                pos = self.get_metadata(PositionProvider, node)
+                self._class_methods[method_name] = pos.start.line
         return True
 
     def leave_ClassDef(self, node: cst.ClassDef) -> None:
+        if self._class_is_view and self._in_class:
+            class_name = self._in_class
+            if self._class_methods:
+                for method_name, line in self._class_methods.items():
+                    http_method = DRF_METHOD_TO_HTTP.get(method_name, method_name.upper())
+                    self.entrypoints.append(
+                        Entrypoint(
+                            file=self.file_path,
+                            function=f"{class_name}.{method_name}",
+                            line=line,
+                            kind="http_route",
+                            metadata={
+                                "framework": "django",
+                                "view_type": "class",
+                                "http_method": http_method,
+                                "http_path": f"<drf:{class_name}>",
+                            },
+                        )
+                    )
+            else:
+                self.entrypoints.append(
+                    Entrypoint(
+                        file=self.file_path,
+                        function=class_name,
+                        line=self._class_line,
+                        kind="http_route",
+                        metadata={
+                            "framework": "django",
+                            "view_type": "class",
+                            "http_method": "ANY",
+                            "http_path": f"<drf:{class_name}>",
+                        },
+                    )
+                )
+
         self._in_class = None
         self._class_is_view = False
         self._class_line = 0
+        self._class_methods = {}
 
     def _is_view_class(self, node: cst.ClassDef) -> bool:
         """Check if a class inherits from a Django/DRF view base class."""

bubble/integrations/fastapi/cli.py

@@ -16,6 +16,7 @@ from bubble.integrations.queries import (
     trace_routes_to_exception,
 )
 from bubble.models import ProgramModel
+from bubble.stubs import load_stubs
 
 app = typer.Typer(
     name="fastapi",
@@ -40,8 +41,28 @@ def _get_fastapi_entrypoints_and_handlers(model: ProgramModel) -> tuple[list, li
     return entrypoints, handlers
 
 
+def _filter_entrypoints(
+    entrypoints: list, filter_arg: str | None, directory: Path
+) -> list:
+    """Filter entrypoints by file path or route path."""
+    if not filter_arg:
+        return entrypoints
+
+    if filter_arg.startswith("/"):
+        return [e for e in entrypoints if e.metadata.get("http_path") == filter_arg]
+
+    filter_path = Path(filter_arg)
+    if not filter_path.is_absolute():
+        filter_path = directory / filter_path
+
+    return [e for e in entrypoints if Path(directory / e.file).resolve() == filter_path.resolve()]
+
+
 @app.command()
 def audit(
+    filter_arg: Annotated[
+        str | None, typer.Argument(help="Filter by file path or route (e.g., /users)")
+    ] = None,
     directory: Annotated[
         Path, typer.Option("--directory", "-d", help="Directory to analyze")
     ] = Path("."),
@@ -50,21 +71,37 @@ def audit(
 ) -> None:
     """Check FastAPI routes for escaping exceptions.
 
-    Scans every FastAPI HTTP route, reports which have uncaught exceptions.
+    Scans FastAPI HTTP routes and reports which have uncaught exceptions.
 
-    Example:
-        flow fastapi audit
-        flow fastapi audit -d /path/to/project
+    Examples:
+        bubble fastapi audit                         # All routes
+        bubble fastapi audit /users                  # Routes matching /users
+        bubble fastapi audit routers/users.py        # Routes in specific file
     """
     directory = directory.resolve()
     model = _build_model(directory, use_cache=not no_cache)
     entrypoints, handlers = _get_fastapi_entrypoints_and_handlers(model)
-    result = audit_integration(model, integration, entrypoints, handlers)
+    entrypoints = _filter_entrypoints(entrypoints, filter_arg, directory)
+
+    if filter_arg and not entrypoints:
+        if filter_arg.startswith("/"):
+            console.print(f"[yellow]No FastAPI routes found matching {filter_arg}[/yellow]")
+        else:
+            console.print(f"[yellow]No FastAPI routes found in {filter_arg}[/yellow]")
+        return
+
+    stub_library = load_stubs(directory)
+    result = audit_integration(
+        model, integration, entrypoints, handlers, stub_library=stub_library
+    )
     formatters.audit(result, OutputFormat(output_format), directory, console)
 
 
 @app.command(name="entrypoints")
 def list_routes(
+    filter_arg: Annotated[
+        str | None, typer.Argument(help="Filter by file path or route (e.g., /users)")
+    ] = None,
     directory: Annotated[
         Path, typer.Option("--directory", "-d", help="Directory to analyze")
     ] = Path("."),
@@ -73,12 +110,15 @@ def list_routes(
 ) -> None:
     """List FastAPI HTTP routes.
 
-    Example:
-        flow fastapi entrypoints
+    Examples:
+        bubble fastapi entrypoints                   # All routes
+        bubble fastapi entrypoints /users            # Routes matching /users
+        bubble fastapi entrypoints routers/users.py  # Routes in specific file
     """
     directory = directory.resolve()
     model = _build_model(directory, use_cache=not no_cache)
     entrypoints, _ = _get_fastapi_entrypoints_and_handlers(model)
+    entrypoints = _filter_entrypoints(entrypoints, filter_arg, directory)
     result = list_integration_entrypoints(integration, entrypoints)
     formatters.entrypoints(result, OutputFormat(output_format), directory, console)
 

bubble/integrations/flask/__init__.py

@@ -5,7 +5,9 @@ import typer
 from bubble.integrations.base import Entrypoint, GlobalHandler
 from bubble.integrations.flask.detector import (
     FlaskErrorHandlerVisitor,
+    FlaskRESTfulVisitor,
     FlaskRouteVisitor,
+    correlate_flask_restful_entrypoints,
     detect_flask_entrypoints,
     detect_flask_global_handlers,
 )
@@ -50,8 +52,10 @@ class FlaskIntegration:
 __all__ = [
     "FlaskIntegration",
     "FlaskRouteVisitor",
+    "FlaskRESTfulVisitor",
     "FlaskErrorHandlerVisitor",
     "EXCEPTION_RESPONSES",
+    "correlate_flask_restful_entrypoints",
     "detect_flask_entrypoints",
     "detect_flask_global_handlers",
 ]

bubble/integrations/flask/cli.py

@@ -16,6 +16,7 @@ from bubble.integrations.queries import (
     trace_routes_to_exception,
 )
 from bubble.models import ProgramModel
+from bubble.stubs import load_stubs
 
 app = typer.Typer(
     name="flask",
@@ -40,8 +41,28 @@ def _get_flask_entrypoints_and_handlers(model: ProgramModel) -> tuple[list, list
     return entrypoints, handlers
 
 
+def _filter_entrypoints(
+    entrypoints: list, filter_arg: str | None, directory: Path
+) -> list:
+    """Filter entrypoints by file path or route path."""
+    if not filter_arg:
+        return entrypoints
+
+    if filter_arg.startswith("/"):
+        return [e for e in entrypoints if e.metadata.get("http_path") == filter_arg]
+
+    filter_path = Path(filter_arg)
+    if not filter_path.is_absolute():
+        filter_path = directory / filter_path
+
+    return [e for e in entrypoints if Path(directory / e.file).resolve() == filter_path.resolve()]
+
+
 @app.command()
 def audit(
+    filter_arg: Annotated[
+        str | None, typer.Argument(help="Filter by file path or route (e.g., /balance)")
+    ] = None,
     directory: Annotated[
         Path, typer.Option("--directory", "-d", help="Directory to analyze")
     ] = Path("."),
@@ -50,21 +71,37 @@ def audit(
 ) -> None:
     """Check Flask routes for escaping exceptions.
 
-    Scans every Flask HTTP route, reports which have uncaught exceptions.
+    Scans Flask HTTP routes and reports which have uncaught exceptions.
 
-    Example:
-        flow flask audit
-        flow flask audit -d /path/to/project
+    Examples:
+        bubble flask audit                           # All routes
+        bubble flask audit /balance                  # Routes matching /balance
+        bubble flask audit blueprints/api.py         # Routes in specific file
     """
     directory = directory.resolve()
     model = _build_model(directory, use_cache=not no_cache)
     entrypoints, handlers = _get_flask_entrypoints_and_handlers(model)
-    result = audit_integration(model, integration, entrypoints, handlers)
+    entrypoints = _filter_entrypoints(entrypoints, filter_arg, directory)
+
+    if filter_arg and not entrypoints:
+        if filter_arg.startswith("/"):
+            console.print(f"[yellow]No Flask routes found matching {filter_arg}[/yellow]")
+        else:
+            console.print(f"[yellow]No Flask routes found in {filter_arg}[/yellow]")
+        return
+
+    stub_library = load_stubs(directory)
+    result = audit_integration(
+        model, integration, entrypoints, handlers, stub_library=stub_library
+    )
     formatters.audit(result, OutputFormat(output_format), directory, console)
 
 
 @app.command(name="entrypoints")
 def list_routes(
+    filter_arg: Annotated[
+        str | None, typer.Argument(help="Filter by file path or route (e.g., /balance)")
+    ] = None,
     directory: Annotated[
         Path, typer.Option("--directory", "-d", help="Directory to analyze")
     ] = Path("."),
@@ -73,12 +110,15 @@ def list_routes(
 ) -> None:
     """List Flask HTTP routes.
 
-    Example:
-        flow flask entrypoints
+    Examples:
+        bubble flask entrypoints                     # All routes
+        bubble flask entrypoints /users              # Routes matching /users
+        bubble flask entrypoints blueprints/api.py   # Routes in specific file
     """
     directory = directory.resolve()
     model = _build_model(directory, use_cache=not no_cache)
     entrypoints, _ = _get_flask_entrypoints_and_handlers(model)
+    entrypoints = _filter_entrypoints(entrypoints, filter_arg, directory)
     result = list_integration_entrypoints(integration, entrypoints)
     formatters.entrypoints(result, OutputFormat(output_format), directory, console)