bubble-analysis 0.2.0__py3-none-any.whl

bubble/config.py

@@ -0,0 +1,52 @@
+"""Configuration loading for flow analysis."""
+
+import fnmatch
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+ResolutionMode = Literal["strict", "default", "aggressive"]
+
+
+@dataclass
+class FlowConfig:
+    """Configuration for flow analysis."""
+
+    resolution_mode: ResolutionMode = "default"
+    exclude: list[str] = field(default_factory=list)
+    handled_base_classes: list[str] = field(default_factory=list)
+    async_boundaries: list[str] = field(default_factory=list)
+
+    def is_async_boundary(self, callee_name: str) -> bool:
+        """Check if a callee matches an async boundary pattern."""
+        for pattern in self.async_boundaries:
+            if fnmatch.fnmatch(callee_name, pattern):
+                return True
+            if "." in callee_name:
+                method_name = callee_name.split(".")[-1]
+                if fnmatch.fnmatch(method_name, pattern.lstrip("*.")):
+                    return True
+        return False
+
+
+def load_config(directory: Path) -> FlowConfig:
+    """Load configuration from .flow/config.yaml if it exists."""
+    config_path = directory / ".flow" / "config.yaml"
+    if not config_path.exists():
+        return FlowConfig()
+
+    with open(config_path) as f:
+        data = yaml.safe_load(f) or {}
+
+    mode = data.get("resolution_mode", "default")
+    if mode not in ("strict", "default", "aggressive"):
+        mode = "default"
+
+    return FlowConfig(
+        resolution_mode=mode,
+        exclude=data.get("exclude", []),
+        handled_base_classes=data.get("handled_base_classes", []),
+        async_boundaries=data.get("async_boundaries", []),
+    )

bubble/detectors.py

@@ -0,0 +1,90 @@
+"""Framework detectors for identifying entrypoints and patterns.
+
+This module uses the generic detector with framework-specific configurations.
+The generic detector produces identical results to the old framework-specific
+detectors but with a single, configurable implementation.
+"""
+
+from bubble.integrations.base import Entrypoint, GlobalHandler
+from bubble.integrations.cli_scripts.detector import (
+    CLIEntrypointVisitor,
+    detect_cli_entrypoints,
+)
+from bubble.integrations.django.detector import (
+    DjangoExceptionHandlerVisitor,
+    DjangoViewVisitor,
+)
+from bubble.integrations.django.semantics import (
+    EXCEPTION_RESPONSES as DJANGO_EXCEPTION_RESPONSES,
+)
+from bubble.integrations.fastapi.detector import (
+    FastAPIExceptionHandlerVisitor,
+    FastAPIRouteVisitor,
+)
+from bubble.integrations.fastapi.semantics import (
+    EXCEPTION_RESPONSES as FASTAPI_EXCEPTION_RESPONSES,
+)
+from bubble.integrations.flask.detector import (
+    FlaskErrorHandlerVisitor,
+    FlaskRouteVisitor,
+)
+from bubble.integrations.flask.semantics import (
+    EXCEPTION_RESPONSES as FLASK_EXCEPTION_RESPONSES,
+)
+from bubble.integrations.generic import (
+    detect_entrypoints as generic_detect_entrypoints,
+)
+from bubble.integrations.generic import (
+    detect_global_handlers as generic_detect_global_handlers,
+)
+from bubble.integrations.generic.frameworks import (
+    DJANGO_CONFIG,
+    FASTAPI_CONFIG,
+    FLASK_CONFIG,
+)
+
+FRAMEWORK_EXCEPTION_RESPONSES: dict[str, dict[str, str]] = {
+    "django": DJANGO_EXCEPTION_RESPONSES,
+    "fastapi": FASTAPI_EXCEPTION_RESPONSES,
+    "flask": FLASK_EXCEPTION_RESPONSES,
+}
+
+
+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.
+    """
+    entrypoints: list[Entrypoint] = []
+    entrypoints.extend(generic_detect_entrypoints(source, file_path, FLASK_CONFIG))
+    entrypoints.extend(generic_detect_entrypoints(source, file_path, FASTAPI_CONFIG))
+    entrypoints.extend(generic_detect_entrypoints(source, file_path, DJANGO_CONFIG))
+    entrypoints.extend(detect_cli_entrypoints(source, file_path))
+    return entrypoints
+
+
+def detect_global_handlers(source: str, file_path: str) -> list[GlobalHandler]:
+    """Detect global exception handlers in a Python source file.
+
+    Uses the generic detector with Flask, FastAPI, and Django configurations.
+    """
+    handlers: list[GlobalHandler] = []
+    handlers.extend(generic_detect_global_handlers(source, file_path, FLASK_CONFIG))
+    handlers.extend(generic_detect_global_handlers(source, file_path, FASTAPI_CONFIG))
+    handlers.extend(generic_detect_global_handlers(source, file_path, DJANGO_CONFIG))
+    return handlers
+
+
+__all__ = [
+    "FRAMEWORK_EXCEPTION_RESPONSES",
+    "FlaskRouteVisitor",
+    "FlaskErrorHandlerVisitor",
+    "FastAPIRouteVisitor",
+    "FastAPIExceptionHandlerVisitor",
+    "DjangoViewVisitor",
+    "DjangoExceptionHandlerVisitor",
+    "CLIEntrypointVisitor",
+    "detect_entrypoints",
+    "detect_global_handlers",
+]

bubble/enums.py

@@ -0,0 +1,65 @@
+"""Typed enums for code flow analysis.
+
+Centralizes all enum types to prevent magic string comparisons throughout the codebase.
+All enums inherit from (str, Enum) to support JSON serialization and string comparison.
+"""
+
+from enum import Enum
+
+
+class EntrypointKind(str, Enum):
+    """Types of entrypoints where external input enters the program."""
+
+    HTTP_ROUTE = "http_route"
+    QUEUE_HANDLER = "queue_handler"
+    CLI_SCRIPT = "cli_script"
+    SCHEDULED_JOB = "scheduled_job"
+    TEST = "test"
+    UNKNOWN = "unknown"
+
+
+class OutputFormat(str, Enum):
+    """Output format for CLI commands."""
+
+    JSON = "json"
+    TEXT = "text"
+
+
+class ConfidenceLevel(str, Enum):
+    """Confidence level for exception propagation paths."""
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class Framework(str, Enum):
+    """Supported web frameworks."""
+
+    FLASK = "flask"
+    FASTAPI = "fastapi"
+    CLI = "cli"
+
+
+class ResolutionMode(str, Enum):
+    """Resolution mode for call graph analysis."""
+
+    STRICT = "strict"
+    DEFAULT = "default"
+    AGGRESSIVE = "aggressive"
+
+
+class ResolutionKind(str, Enum):
+    """How a call site was resolved to its target."""
+
+    IMPORT = "import"
+    SELF = "self"
+    CONSTRUCTOR = "constructor"
+    RETURN_TYPE = "return_type"
+    MODULE_ATTRIBUTE = "module_attribute"
+    NAME_FALLBACK = "name_fallback"
+    POLYMORPHIC = "polymorphic"
+    STUB = "stub"
+    UNRESOLVED = "unresolved"
+    FASTAPI_DEPENDS = "fastapi_depends"
+    IMPLICIT_DISPATCH = "implicit_dispatch"