apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/parsing/python/cbv_extractor.py

@@ -0,0 +1,606 @@
+"""
+Class-Based View (CBV) extractor for FastAPI/Starlette applications.
+
+This module handles:
+1. fastapi-utils CBV pattern: @cbv(router) class UserAPI
+2. Starlette HTTPEndpoint: class UserEndpoint(HTTPEndpoint)
+3. Generic REST resource classes
+4. ViewSet patterns (Django-REST-Framework style)
+5. Custom base class inheritance
+
+CRITICAL: Enterprise applications often use CBV for:
+- Grouping related endpoints
+- Shared dependencies across endpoints
+- Inheritance-based authorization
+- RESTful resource patterns
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..base import ParsedClass, ParsedDecorator, ParsedFile, ParsedFunction
+
+
+# =============================================================================
+# Data Types
+# =============================================================================
+
+
+@dataclass
+class CBVRoute:
+    """A route extracted from a class-based view."""
+
+    # Route info
+    path: str
+    method: str  # GET, POST, etc.
+
+    # Handler info
+    handler_method: str  # Method name (e.g., "list", "create")
+    handler_class: str  # Class name
+    handler_qualified: str  # Fully qualified name
+
+    # Location
+    file_path: Path
+    line: int
+
+    # CBV type
+    cbv_type: str  # "cbv_decorator", "http_endpoint", "viewset", "generic"
+
+    # Additional metadata
+    is_async: bool = False
+    dependencies: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+
+    # Confidence
+    confidence: float = 0.8
+
+
+@dataclass
+class CBVClass:
+    """A class-based view definition."""
+
+    name: str
+    qualified_name: str
+    file_path: Path
+    line: int
+
+    # Type of CBV
+    cbv_type: str  # "cbv_decorator", "http_endpoint", "viewset", "generic"
+
+    # Associated router (for @cbv(router) pattern)
+    router_var: str | None = None
+
+    # Base path (from decorator or class attribute)
+    base_path: str = ""
+
+    # HTTP method handlers
+    routes: list[CBVRoute] = field(default_factory=list)
+
+    # Class-level dependencies
+    dependencies: list[str] = field(default_factory=list)
+
+    # Confidence
+    confidence: float = 0.8
+
+
+# =============================================================================
+# Method Patterns
+# =============================================================================
+
+
+# HTTP method names that correspond to routes
+HTTP_METHOD_PATTERNS = {
+    # Direct method names (HTTPEndpoint style)
+    "get": "GET",
+    "post": "POST",
+    "put": "PUT",
+    "patch": "PATCH",
+    "delete": "DELETE",
+    "head": "HEAD",
+    "options": "OPTIONS",
+    # CRUD-style names
+    "list": "GET",
+    "retrieve": "GET",
+    "create": "POST",
+    "update": "PUT",
+    "partial_update": "PATCH",
+    "destroy": "DELETE",
+    # Action-style names
+    "index": "GET",
+    "show": "GET",
+    "new": "GET",
+    "edit": "GET",
+    "store": "POST",
+}
+
+# Base classes that indicate CBV
+CBV_BASE_CLASSES = {
+    # Starlette
+    "HTTPEndpoint",
+    "WebSocketEndpoint",
+    "starlette.endpoints.HTTPEndpoint",
+    "starlette.endpoints.WebSocketEndpoint",
+    # fastapi-utils
+    "Resource",
+    "CRUDResource",
+    # Generic patterns
+    "APIView",
+    "ViewSet",
+    "ModelViewSet",
+    "GenericViewSet",
+    "GenericAPIView",
+}
+
+
+# =============================================================================
+# CBV Extractor
+# =============================================================================
+
+
+class CBVExtractor:
+    """
+    Extracts routes from class-based views.
+
+    Handles multiple CBV patterns:
+
+    1. fastapi-utils @cbv decorator:
+        @cbv(router)
+        class UserAPI:
+            @router.get("/")
+            def list(self): ...
+
+    2. Starlette HTTPEndpoint:
+        class UserEndpoint(HTTPEndpoint):
+            async def get(self, request): ...
+            async def post(self, request): ...
+
+    3. ViewSet pattern:
+        class UserViewSet(ViewSet):
+            def list(self, request): ...
+            def retrieve(self, request, pk): ...
+
+    Usage:
+        extractor = CBVExtractor()
+
+        for parsed in parsed_files:
+            extractor.process_file(parsed)
+
+        cbv_classes = extractor.get_all_cbv_classes()
+        routes = extractor.get_all_routes()
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the extractor."""
+        self._project_root = project_root
+        self._cbv_classes: dict[str, CBVClass] = {}
+        self._routes: list[CBVRoute] = []
+        self._router_vars: dict[Path, set[str]] = {}
+
+    def process_file(self, parsed: ParsedFile) -> None:
+        """Process a parsed file to extract CBV routes."""
+        if not parsed.success:
+            return
+
+        file_path = parsed.path
+        self._router_vars[file_path] = set()
+
+        # Identify router variables
+        self._identify_routers(parsed)
+
+        # Process each class
+        for cls in parsed.classes:
+            cbv = self._analyze_class(cls, parsed)
+            if cbv:
+                self._cbv_classes[cbv.qualified_name] = cbv
+                self._routes.extend(cbv.routes)
+
+    def _identify_routers(self, parsed: ParsedFile) -> None:
+        """Identify router variables in the file."""
+        file_path = parsed.path
+
+        for assign in parsed.assignments:
+            if assign.source_type == "call":
+                called = assign.source_call or ""
+                if "Router" in called or "FastAPI" in called:
+                    self._router_vars[file_path].add(assign.target)
+
+    def _analyze_class(
+        self,
+        cls: ParsedClass,
+        parsed: ParsedFile,
+    ) -> CBVClass | None:
+        """Analyze a class to determine if it's a CBV."""
+
+        # Check 1: @cbv decorator
+        cbv_decorator = self._find_cbv_decorator(cls)
+        if cbv_decorator:
+            return self._extract_cbv_decorated_class(cls, cbv_decorator, parsed)
+
+        # Check 2: HTTPEndpoint base class
+        if self._is_http_endpoint(cls):
+            return self._extract_http_endpoint_class(cls, parsed)
+
+        # Check 3: ViewSet base class
+        if self._is_viewset(cls):
+            return self._extract_viewset_class(cls, parsed)
+
+        # Check 4: Generic CBV patterns — only if the class looks like a view
+        if self._has_http_methods(cls) and self._looks_like_view_class(cls):
+            return self._extract_generic_cbv_class(cls, parsed)
+
+        return None
+
+    def _find_cbv_decorator(self, cls: ParsedClass) -> ParsedDecorator | None:
+        """Find @cbv decorator on a class."""
+        for dec in cls.decorators:
+            if dec.name == "cbv" or dec.name.endswith(".cbv"):
+                return dec
+        return None
+
+    def _is_http_endpoint(self, cls: ParsedClass) -> bool:
+        """Check if class inherits from HTTPEndpoint."""
+        return any(base in CBV_BASE_CLASSES or "HTTPEndpoint" in base for base in cls.base_classes)
+
+    def _is_viewset(self, cls: ParsedClass) -> bool:
+        """Check if class is a ViewSet."""
+        return any("ViewSet" in base or "APIView" in base for base in cls.base_classes)
+
+    def _has_http_methods(self, cls: ParsedClass) -> bool:
+        """Check if class has methods named after HTTP methods."""
+        http_methods = {"get", "post", "put", "patch", "delete", "head", "options"}
+        return any(method.name.lower() in http_methods for method in cls.methods)
+
+    _VIEW_CLASS_SUFFIXES = ("View", "Endpoint", "Resource", "Handler", "Controller", "API")
+    _VIEW_RELATED_BASES = frozenset(
+        {
+            "HTTPEndpoint",
+            "WebSocketEndpoint",
+            "APIView",
+            "ViewSet",
+            "ModelViewSet",
+            "GenericViewSet",
+            "GenericAPIView",
+            "Resource",
+            "CRUDResource",
+            "View",
+            "MethodView",
+            "BaseHTTPHandler",
+        }
+    )
+    _VIEW_DECORATOR_INDICATORS = ("route", "cbv", "register", "api_view")
+
+    def _looks_like_view_class(self, cls: ParsedClass) -> bool:
+        """Return True only if the class has structural signals of being an HTTP view.
+
+        Checks class name suffix, base classes, and decorators.  This prevents
+        service/plugin/repository classes from being treated as route handlers.
+        """
+        if cls.name.endswith(self._VIEW_CLASS_SUFFIXES):
+            return True
+
+        for base in cls.base_classes:
+            short = base.rsplit(".", 1)[-1]
+            if short in self._VIEW_RELATED_BASES:
+                return True
+
+        for dec in cls.decorators:
+            dec_lower = dec.name.lower()
+            if any(ind in dec_lower for ind in self._VIEW_DECORATOR_INDICATORS):
+                return True
+
+        return False
+
+    # =========================================================================
+    # CBV Decorated Class Extraction
+    # =========================================================================
+
+    def _extract_cbv_decorated_class(
+        self,
+        cls: ParsedClass,
+        cbv_decorator: ParsedDecorator,
+        parsed: ParsedFile,
+    ) -> CBVClass:
+        """Extract routes from @cbv decorated class."""
+        file_path = parsed.path
+        self._router_vars.get(file_path, set())
+
+        # Get router variable from decorator
+        router_var = None
+        if cbv_decorator.positional_args:
+            router_var = str(cbv_decorator.positional_args[0])
+
+        cbv = CBVClass(
+            name=cls.name,
+            qualified_name=cls.qualified_name.full,
+            file_path=file_path,
+            line=cls.location.line,
+            cbv_type="cbv_decorator",
+            router_var=router_var,
+            confidence=0.95,
+        )
+
+        # Extract routes from decorated methods
+        for method in cls.methods:
+            route = self._extract_decorated_method_route(method, cls, router_var, parsed)
+            if route:
+                cbv.routes.append(route)
+
+        return cbv
+
+    def _extract_decorated_method_route(
+        self,
+        method: ParsedFunction,
+        cls: ParsedClass,
+        router_var: str | None,
+        parsed: ParsedFile,
+    ) -> CBVRoute | None:
+        """Extract route from a decorated method in CBV."""
+        file_path = parsed.path
+
+        # Look for route decorator
+        for dec in method.decorators:
+            route_info = self._parse_route_decorator(dec, router_var)
+            if route_info:
+                path, http_method = route_info
+
+                return CBVRoute(
+                    path=path,
+                    method=http_method,
+                    handler_method=method.name,
+                    handler_class=cls.name,
+                    handler_qualified=f"{cls.qualified_name.full}.{method.name}",
+                    file_path=file_path,
+                    line=method.location.line,
+                    cbv_type="cbv_decorator",
+                    is_async=method.is_async,
+                    confidence=0.95,
+                )
+
+        return None
+
+    def _parse_route_decorator(
+        self,
+        dec: ParsedDecorator,
+        router_var: str | None,
+    ) -> tuple[str, str] | None:
+        """Parse a route decorator to extract path and method."""
+        dec_name = dec.name.lower()
+        full_name = dec.qualified_name.full if dec.qualified_name else dec.name
+
+        # HTTP methods
+        http_methods = {"get", "post", "put", "patch", "delete", "head", "options"}
+
+        # Direct method decorator
+        if dec_name in http_methods:
+            path = self._extract_path_from_decorator(dec)
+            return (path, dec_name.upper())
+
+        # router.method pattern
+        parts = full_name.split(".")
+        if len(parts) >= 2:
+            method_name = parts[-1].lower()
+            var_name = parts[-2]
+
+            if method_name in http_methods:
+                if router_var is None or var_name == router_var:
+                    path = self._extract_path_from_decorator(dec)
+                    return (path, method_name.upper())
+
+        return None
+
+    def _extract_path_from_decorator(self, dec: ParsedDecorator) -> str:
+        """Extract path from route decorator."""
+        if dec.positional_args:
+            first = dec.positional_args[0]
+            if isinstance(first, str):
+                return first
+
+        if "path" in dec.arguments:
+            return str(dec.arguments["path"])
+
+        return "/"
+
+    # =========================================================================
+    # HTTPEndpoint Class Extraction
+    # =========================================================================
+
+    def _extract_http_endpoint_class(
+        self,
+        cls: ParsedClass,
+        parsed: ParsedFile,
+    ) -> CBVClass:
+        """Extract routes from HTTPEndpoint class."""
+        file_path = parsed.path
+
+        cbv = CBVClass(
+            name=cls.name,
+            qualified_name=cls.qualified_name.full,
+            file_path=file_path,
+            line=cls.location.line,
+            cbv_type="http_endpoint",
+            confidence=0.9,
+        )
+
+        # HTTP methods are methods named get, post, etc.
+        for method in cls.methods:
+            method_name = method.name.lower()
+
+            if method_name in HTTP_METHOD_PATTERNS:
+                http_method = HTTP_METHOD_PATTERNS[method_name]
+
+                cbv.routes.append(
+                    CBVRoute(
+                        path="{endpoint_path}",  # Determined by routing
+                        method=http_method,
+                        handler_method=method.name,
+                        handler_class=cls.name,
+                        handler_qualified=f"{cls.qualified_name.full}.{method.name}",
+                        file_path=file_path,
+                        line=method.location.line,
+                        cbv_type="http_endpoint",
+                        is_async=method.is_async,
+                        confidence=0.9,
+                    )
+                )
+
+        return cbv
+
+    # =========================================================================
+    # ViewSet Class Extraction
+    # =========================================================================
+
+    def _extract_viewset_class(
+        self,
+        cls: ParsedClass,
+        parsed: ParsedFile,
+    ) -> CBVClass:
+        """Extract routes from ViewSet class."""
+        file_path = parsed.path
+
+        cbv = CBVClass(
+            name=cls.name,
+            qualified_name=cls.qualified_name.full,
+            file_path=file_path,
+            line=cls.location.line,
+            cbv_type="viewset",
+            confidence=0.85,
+        )
+
+        # Extract standard CRUD actions
+        for method in cls.methods:
+            method_name = method.name.lower()
+
+            if method_name in HTTP_METHOD_PATTERNS:
+                http_method = HTTP_METHOD_PATTERNS[method_name]
+
+                # Determine path based on method name
+                path = self._viewset_method_to_path(method_name)
+
+                cbv.routes.append(
+                    CBVRoute(
+                        path=path,
+                        method=http_method,
+                        handler_method=method.name,
+                        handler_class=cls.name,
+                        handler_qualified=f"{cls.qualified_name.full}.{method.name}",
+                        file_path=file_path,
+                        line=method.location.line,
+                        cbv_type="viewset",
+                        is_async=method.is_async,
+                        confidence=0.8,
+                    )
+                )
+
+        return cbv
+
+    def _viewset_method_to_path(self, method_name: str) -> str:
+        """Convert viewset method name to path."""
+        if method_name in {"list", "create", "index", "store"}:
+            return "/"
+        elif method_name in {
+            "retrieve",
+            "show",
+            "update",
+            "partial_update",
+            "destroy",
+            "delete",
+            "edit",
+        }:
+            return "/{id}"
+        else:
+            return "/"
+
+    # =========================================================================
+    # Generic CBV Extraction
+    # =========================================================================
+
+    def _extract_generic_cbv_class(
+        self,
+        cls: ParsedClass,
+        parsed: ParsedFile,
+    ) -> CBVClass:
+        """Extract routes from generic class with HTTP methods."""
+        file_path = parsed.path
+
+        cbv = CBVClass(
+            name=cls.name,
+            qualified_name=cls.qualified_name.full,
+            file_path=file_path,
+            line=cls.location.line,
+            cbv_type="generic",
+            confidence=0.6,  # Lower confidence for generic detection
+        )
+
+        for method in cls.methods:
+            method_name = method.name.lower()
+
+            if method_name in HTTP_METHOD_PATTERNS:
+                http_method = HTTP_METHOD_PATTERNS[method_name]
+
+                cbv.routes.append(
+                    CBVRoute(
+                        path="{class_path}",
+                        method=http_method,
+                        handler_method=method.name,
+                        handler_class=cls.name,
+                        handler_qualified=f"{cls.qualified_name.full}.{method.name}",
+                        file_path=file_path,
+                        line=method.location.line,
+                        cbv_type="generic",
+                        is_async=method.is_async,
+                        confidence=0.6,
+                    )
+                )
+
+        return cbv
+
+    # =========================================================================
+    # Query Methods
+    # =========================================================================
+
+    def get_all_cbv_classes(self) -> dict[str, CBVClass]:
+        """Get all detected CBV classes."""
+        return dict(self._cbv_classes)
+
+    def get_all_routes(self) -> list[CBVRoute]:
+        """Get all detected CBV routes."""
+        return list(self._routes)
+
+    def get_routes_for_class(self, class_name: str) -> list[CBVRoute]:
+        """Get routes for a specific class."""
+        return [r for r in self._routes if r.handler_class == class_name]
+
+    def get_classes_for_file(self, file_path: Path) -> list[CBVClass]:
+        """Get CBV classes in a specific file."""
+        return [c for c in self._cbv_classes.values() if c.file_path == file_path]
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def extract_cbv_routes(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+) -> tuple[list[CBVRoute], dict[str, CBVClass]]:
+    """
+    Extract CBV routes from parsed files.
+
+    Args:
+        parsed_files: List of successfully parsed files
+        project_root: Optional project root
+
+    Returns:
+        Tuple of (routes, cbv_classes)
+    """
+    extractor = CBVExtractor(project_root)
+
+    for parsed in parsed_files:
+        extractor.process_file(parsed)
+
+    return extractor.get_all_routes(), extractor.get_all_cbv_classes()