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

bubble/propagation.py

@@ -39,10 +39,20 @@ class PropagatedRaise:
 
 @dataclass
 class ExceptionFlow:
-    """The computed exception flow for a function or entrypoint."""
+    """The computed exception flow for a function or entrypoint.
+
+    Categories:
+    - caught_locally: Caught by try/except in the function
+    - caught_by_global: Caught by a global handler in the same file as the entrypoint
+    - caught_by_remote_global: Caught by a global handler in a different file
+    - caught_by_generic: Caught by a generic handler (@errorhandler(Exception))
+    - uncaught: No handler found
+    - framework_handled: Converted to HTTP response by framework (e.g., HTTPException)
+    """
 
     caught_locally: dict[str, list[RaiseSite]] = field(default_factory=dict)
     caught_by_global: dict[str, list[RaiseSite]] = field(default_factory=dict)
+    caught_by_remote_global: dict[str, list[RaiseSite]] = field(default_factory=dict)
     caught_by_generic: dict[str, list[RaiseSite]] = field(default_factory=dict)
     uncaught: dict[str, list[RaiseSite]] = field(default_factory=dict)
     framework_handled: dict[str, list[tuple[RaiseSite, str]]] = field(default_factory=dict)
@@ -61,14 +71,79 @@ class PropagationResult:
     )
 
 
+def _build_func_name_index(model: ProgramModel) -> dict[str, list[str]]:
+    """Build an index from function name suffixes to qualified keys."""
+    index: dict[str, list[str]] = {}
+    for key in model.functions:
+        if "::" in key:
+            func_name = key.split("::")[-1]
+        elif ":" in key:
+            func_name = key.split(":")[-1]
+        else:
+            func_name = key
+        if func_name not in index:
+            index[func_name] = []
+        index[func_name].append(key)
+    return index
+
+
+_normalize_cache: dict[str, str] = {}
+
+
+def _normalize_callee_to_file_format(
+    callee_qualified: str,
+    model: ProgramModel,
+    func_index: dict[str, list[str]] | None = None,
+) -> str:
+    """Normalize a module-dot callee to file::function format.
+
+    Converts: blueprints.orchestrators.CallbackOrchestrators.BalanceCallbackOrchestrator.run
+    To:       blueprints/orchestrators/CallbackOrchestrators.py::BalanceCallbackOrchestrator.run
+    """
+    if "::" in callee_qualified:
+        return callee_qualified
+
+    if callee_qualified in _normalize_cache:
+        return _normalize_cache[callee_qualified]
+
+    parts = callee_qualified.split(".")
+    for i in range(len(parts) - 1, 0, -1):
+        module_path = "/".join(parts[:i]) + ".py"
+        func_name = ".".join(parts[i:])
+
+        for sep in ("::", ":"):
+            candidate_key = f"{module_path}{sep}{func_name}"
+            if candidate_key in model.functions:
+                normalized = f"{module_path}::{func_name}"
+                _normalize_cache[callee_qualified] = normalized
+                return normalized
+
+        if func_index is not None:
+            candidates = func_index.get(func_name, [])
+            module_normalized = module_path.replace("/", ".").replace(".py", "")
+            for key in candidates:
+                if module_normalized in key.replace("/", "."):
+                    file_part = key.split(":")[0]
+                    result = f"{file_part}::{func_name}"
+                    _normalize_cache[callee_qualified] = result
+                    return result
+
+    _normalize_cache[callee_qualified] = callee_qualified
+    return callee_qualified
+
+
 def build_forward_call_graph(model: ProgramModel) -> dict[str, set[str]]:
     """Build a map from caller to callees."""
     graph: dict[str, set[str]] = {}
+    func_index = _build_func_name_index(model)
 
     for call_site in model.call_sites:
         caller = call_site.caller_qualified or f"{call_site.file}::{call_site.caller_function}"
         callee = call_site.callee_qualified or call_site.callee_name
 
+        if call_site.callee_qualified and "::" not in call_site.callee_qualified:
+            callee = _normalize_callee_to_file_format(call_site.callee_qualified, model, func_index)
+
         if caller not in graph:
             graph[caller] = set()
         graph[caller].add(callee)
@@ -76,6 +151,59 @@ def build_forward_call_graph(model: ProgramModel) -> dict[str, set[str]]:
     return graph
 
 
+def compute_forward_reachability(
+    start_func: str,
+    model: ProgramModel,
+    forward_graph: dict[str, set[str]] | None = None,
+) -> set[str]:
+    """Compute all functions reachable from a starting function via forward calls.
+
+    Unlike compute_reachable_functions, this doesn't require propagation results,
+    making it suitable for scoping propagation before it runs.
+
+    Returns both qualified names and simple names for efficient scope checking.
+    """
+    if forward_graph is None:
+        forward_graph = build_forward_call_graph(model)
+
+    simple_to_qualified: dict[str, list[str]] = {}
+    for key in forward_graph:
+        simple = key.split("::")[-1].split(".")[-1] if "::" in key else key.split(".")[-1]
+        if simple not in simple_to_qualified:
+            simple_to_qualified[simple] = []
+        simple_to_qualified[simple].append(key)
+
+    reachable: set[str] = set()
+    start_simple = start_func.split("::")[-1].split(".")[-1] if "::" in start_func else start_func.split(".")[-1]
+    worklist = [start_func] + simple_to_qualified.get(start_simple, [])
+
+    while worklist:
+        current = worklist.pop()
+        if current in reachable:
+            continue
+        reachable.add(current)
+
+        current_simple = (
+            current.split("::")[-1].split(".")[-1] if "::" in current else current.split(".")[-1]
+        )
+        reachable.add(current_simple)
+
+        callees = forward_graph.get(current, set())
+        if not callees:
+            for qualified_key in simple_to_qualified.get(current_simple, []):
+                if qualified_key not in reachable:
+                    callees = forward_graph.get(qualified_key, set())
+                    if callees:
+                        reachable.add(qualified_key)
+                        break
+
+        for callee in callees:
+            if callee not in reachable:
+                worklist.append(callee)
+
+    return reachable
+
+
 def build_name_to_qualified(propagation: PropagationResult) -> dict[str, list[str]]:
     """Build a map from simple function names to their qualified names."""
     name_to_qualified: dict[str, list[str]] = {}
@@ -218,6 +346,23 @@ def _build_call_site_lookup(
     return lookup
 
 
+def _build_is_method_lookup(model: ProgramModel) -> dict[tuple[str, str], bool]:
+    """Build a lookup for is_method_call by (caller, callee) pairs.
+
+    This is always needed for correct fallback resolution, even when
+    skip_evidence=True. When a call is in the form obj.method(), we
+    should prefer matching methods over standalone functions.
+    """
+    lookup: dict[tuple[str, str], bool] = {}
+    for cs in model.call_sites:
+        caller = cs.caller_qualified or f"{cs.file}::{cs.caller_function}"
+        callee = cs.callee_qualified or cs.callee_name
+        key = (caller, callee)
+        if key not in lookup:
+            lookup[key] = cs.is_method_call
+    return lookup
+
+
 def _build_raise_site_lookup(
     model: ProgramModel,
 ) -> dict[tuple[str, str, int], RaiseSite]:
@@ -278,9 +423,7 @@ def _scoped_fallback_lookup(
     candidates = name_to_qualified.get(fallback_key, [])
 
     if not candidates:
-        result = ([], "none")
-        _fallback_cache[cache_key] = result
-        return result
+        return ([], "none")
 
     same_file = [c for c in candidates if c.startswith(f"{caller_file}::")]
     if same_file:
@@ -314,6 +457,7 @@ def propagate_exceptions(
     resolution_mode: ResolutionMode = ResolutionMode.DEFAULT,
     stub_library: StubLibrary | None = None,
     skip_evidence: bool = False,
+    scope: set[str] | None = None,
 ) -> PropagationResult:
     """
     Propagate exceptions through the call graph.
@@ -324,6 +468,8 @@ def propagate_exceptions(
     Args:
         skip_evidence: If True, skip building evidence paths for faster propagation.
                        Use for audit commands where only exception types matter.
+        scope: If provided, only propagate through functions in this set.
+               Use compute_forward_reachability() to get the scope for a single function.
 
     Resolution modes:
     - strict: Only follow resolved calls (no name_fallback or polymorphic)
@@ -332,21 +478,35 @@ def propagate_exceptions(
     """
     from bubble import timing
 
-    cache_key = (
-        id(model),
-        resolution_mode,
-        id(stub_library) if stub_library else None,
-        skip_evidence,
-    )
+    if scope is not None:
+        cache_key = None
+    else:
+        cache_key = (
+            id(model),
+            resolution_mode,
+            id(stub_library) if stub_library else None,
+            skip_evidence,
+        )
 
-    if cache_key in _propagation_cache:
-        return _propagation_cache[cache_key]
+        if cache_key in _propagation_cache:
+            return _propagation_cache[cache_key]
 
     with timing.timed("propagation_setup"):
         direct_raises = compute_direct_raises(model)
         catches_by_function = compute_catches_by_function(model)
-        forward_graph = build_forward_call_graph(model)
+        full_forward_graph = build_forward_call_graph(model)
+
+        if scope is not None:
+            forward_graph = {}
+            for caller, callees in full_forward_graph.items():
+                caller_simple = caller.split("::")[-1].split(".")[-1] if "::" in caller else caller.split(".")[-1]
+                if caller in scope or caller_simple in scope:
+                    forward_graph[caller] = callees
+        else:
+            forward_graph = full_forward_graph
+
         call_site_lookup = _build_call_site_lookup(model) if not skip_evidence else {}
+        is_method_lookup = _build_is_method_lookup(model)
 
     propagated: dict[str, set[str]] = {}
     propagated_evidence: dict[str, dict[tuple[str, str, int], PropagatedRaise]] = {}
@@ -418,7 +578,7 @@ def propagate_exceptions(
                                 if "::" in expanded_callee
                                 else expanded_callee.split(".")[-1]
                             )
-                            is_method = call_site.is_method_call if call_site else False
+                            is_method = is_method_lookup.get((caller, callee), False)
                             caller_file = caller.split("::")[0] if "::" in caller else caller
                             import_map = model.import_maps.get(caller_file, {})
 
@@ -533,7 +693,8 @@ def propagate_exceptions(
         propagated_with_evidence=propagated_evidence,
     )
 
-    _propagation_cache[cache_key] = result
+    if cache_key is not None:
+        _propagation_cache[cache_key] = result
     return result
 
 

bubble/queries.py

@@ -7,11 +7,12 @@ and returns a typed result dataclass. No formatting here.
 from difflib import get_close_matches
 
 from bubble.enums import EntrypointKind, Framework, ResolutionMode
-from bubble.models import Entrypoint, ProgramModel
+from bubble.models import CatchSite, ClassHierarchy, Entrypoint, ProgramModel, RaiseSite
 from bubble.propagation import (
     build_forward_call_graph,
     build_reverse_call_graph,
     compute_exception_flow,
+    compute_forward_reachability,
     propagate_exceptions,
 )
 from bubble.results import (
@@ -309,7 +310,15 @@ def find_escapes(
             entrypoint = e
             break
 
-    propagation = propagate_exceptions(model, resolution_mode=resolution_mode)
+    forward_graph = build_forward_call_graph(model)
+    scope = compute_forward_reachability(function_name, model, forward_graph)
+
+    propagation = propagate_exceptions(
+        model,
+        resolution_mode=resolution_mode,
+        skip_evidence=True,
+        scope=scope,
+    )
     flow = compute_exception_flow(function_name, model, propagation)
 
     return EscapesResult(
@@ -320,28 +329,110 @@ def find_escapes(
     )
 
 
+def _compute_reverse_reachability(
+    raise_sites: list[RaiseSite],
+    qualified_graph: dict[str, set[str]],
+    name_graph: dict[str, set[str]],
+) -> set[str]:
+    """Compute all functions that can transitively call the raise site functions."""
+    reachable: set[str] = set()
+
+    for raise_site in raise_sites:
+        func_key = f"{raise_site.file}::{raise_site.function}"
+        worklist = [func_key]
+        visited: set[str] = set()
+
+        while worklist:
+            current = worklist.pop()
+            if current in visited:
+                continue
+            visited.add(current)
+            reachable.add(current)
+
+            simple_name = (
+                current.split("::")[-1].split(".")[-1]
+                if "::" in current
+                else current.split(".")[-1]
+            )
+            reachable.add(simple_name)
+
+            for caller in qualified_graph.get(current, set()):
+                if caller not in visited:
+                    worklist.append(caller)
+
+            for caller in name_graph.get(simple_name, set()):
+                if caller not in visited:
+                    worklist.append(caller)
+
+    return reachable
+
+
+def _catch_site_catches_exception(
+    catch_site: CatchSite,
+    types_to_find: set[str],
+    hierarchy: ClassHierarchy,
+) -> bool:
+    """Check if a catch site would catch the given exception type."""
+    if catch_site.has_bare_except:
+        return True
+
+    for caught_type in catch_site.caught_types:
+        caught_simple = caught_type.split(".")[-1]
+
+        if caught_type in types_to_find or caught_simple in types_to_find:
+            return True
+
+        if caught_simple in ("Exception", "BaseException"):
+            return True
+
+        for t in types_to_find:
+            t_simple = t.split(".")[-1]
+            if hierarchy.is_subclass_of(t_simple, caught_simple):
+                return True
+
+    return False
+
+
 def find_catches(
     model: ProgramModel,
     exception_type: str,
     include_subclasses: bool = False,
 ) -> CatchesResult:
-    """Find all places where an exception is caught."""
+    """Find catch sites that are in the call path from where the exception is raised."""
     types_to_find: set[str] = {exception_type}
     if include_subclasses:
         subclasses = model.exception_hierarchy.get_subclasses(exception_type)
         types_to_find.update(subclasses)
 
-    matching_catches = []
+    raises_result = find_raises(model, exception_type, include_subclasses)
+
+    if not raises_result.matches:
+        return CatchesResult(
+            exception_type=exception_type,
+            include_subclasses=include_subclasses,
+            types_searched=types_to_find,
+            local_catches=[],
+            global_handlers=[],
+            raise_site_count=0,
+        )
+
+    qualified_graph, name_graph = build_reverse_call_graph(model)
+    reachable_functions = _compute_reverse_reachability(
+        raises_result.matches, qualified_graph, name_graph
+    )
+
+    matching_catches: list[CatchSite] = []
     for catch_site in model.catch_sites:
-        for caught_type in catch_site.caught_types:
-            caught_simple = caught_type.split(".")[-1]
-            if caught_type in types_to_find or caught_simple in types_to_find:
-                matching_catches.append(catch_site)
-                break
-            for t in types_to_find:
-                if model.exception_hierarchy.is_subclass_of(t, caught_simple):
-                    matching_catches.append(catch_site)
-                    break
+        catch_func_key = f"{catch_site.file}::{catch_site.function}"
+        catch_func_simple = catch_site.function.split(".")[-1]
+
+        if catch_func_key not in reachable_functions and catch_func_simple not in reachable_functions:
+            continue
+
+        if _catch_site_catches_exception(
+            catch_site, types_to_find, model.exception_hierarchy
+        ):
+            matching_catches.append(catch_site)
 
     global_handlers = [
         h
@@ -360,6 +451,7 @@ def find_catches(
         types_searched=types_to_find,
         local_catches=matching_catches,
         global_handlers=global_handlers,
+        raise_site_count=len(raises_result.matches),
     )
 
 

bubble/results.py

@@ -118,6 +118,7 @@ class CatchesResult:
     types_searched: set[str]
     local_catches: list[CatchSite]
     global_handlers: list[GlobalHandler]
+    raise_site_count: int = 0
 
 
 @dataclass

{bubble_analysis-0.2.0.dist-info → bubble_analysis-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bubble-analysis
-Version: 0.2.0
+Version: 0.3.4
 Summary: Static analysis tool for tracing exception flow through Python codebases
 Author-email: Ian McLaughlin <ianm199@github.com>
 License-Expression: MIT
@@ -13,13 +13,14 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: libcst>=1.1.0
@@ -33,11 +34,11 @@ Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Dynamic: license-file
 
-# flow
+# Bubble
 
 Static analysis tool for tracing exception flow through Python codebases.
 
-**What can escape from my API endpoints?** Flow answers this by parsing your code, building a call graph, and computing which exceptions propagate to each entrypoint.
+**What can escape from my API endpoints?** Bubble answers this by parsing your code, building a call graph, and computing which exceptions propagate to each entrypoint.
 
 ## Quick Start
 
@@ -61,10 +62,10 @@ bubble trace create_user -d /path/to/project
 
 ## What It Does
 
-Flow finds your HTTP routes and CLI scripts, traces the call graph, and reports which exceptions can escape:
+Bubble finds your HTTP routes and CLI scripts, traces the call graph, and reports which exceptions can escape:
 
 ```
-$ flow flask audit
+$ bubble flask audit
 
 Scanning 23 flask entrypoints...
 
@@ -83,7 +84,7 @@ Scanning 23 flask entrypoints...
 For a specific endpoint, see the full picture:
 
 ```
-$ flow escapes create_user
+$ bubble escapes create_user
 
 Exceptions that can escape from POST /users:
 
@@ -105,7 +106,7 @@ Exceptions that can escape from POST /users:
 Visualize as a tree:
 
 ```
-$ flow trace create_user
+$ bubble trace create_user
 
 POST /users  → escapes: ValidationError, ConnectionError
 ├── validate_input()  → ValidationError
@@ -117,6 +118,7 @@ POST /users  → escapes: ValidationError, ConnectionError
 
 ## Features
 
+- **Extensible**: Adapt to any framework or custom pattern ([see extending guide](docs/EXTENDING.md))
 - **Entrypoint detection**: Flask routes, FastAPI routes, CLI scripts (`if __name__ == "__main__"`)
 - **Global handler awareness**: Understands `@errorhandler`, `add_exception_handler`
 - **Exception hierarchy**: Knows that catching `AppError` also catches `ValidationError` if it's a subclass
@@ -124,9 +126,10 @@ POST /users  → escapes: ValidationError, ConnectionError
 - **Framework-handled exceptions**: Detects HTTPException, ValidationError → HTTP responses
 - **Confidence levels**: Shows high/medium/low confidence based on resolution quality
 - **Resolution modes**: `--strict` for precision, `--aggressive` for recall
-- **Exception stubs**: Declare what external libraries can raise (requests, sqlalchemy, etc.)
+- **Exception stubs**: Built-in stubs for requests, sqlalchemy, httpx, redis, boto3
 - **JSON output**: All commands support `-f json` for CI/automation
 - **Caching**: SQLite-based caching for fast repeated analysis
+- **Python 3.10+**: Supports Python 3.10, 3.11, 3.12, and 3.13
 
 ## Commands
 
@@ -179,39 +182,55 @@ The `escapes` command accepts additional flags:
 - Celery tasks
 - Scheduled jobs (APScheduler, etc.)
 
-Custom patterns can be added via `.flow/detectors/` (run `bubble init` to set up).
+Custom patterns can be added via `.flow/detectors/`.
 
-## Adding Custom Detectors
+## Extending Bubble
 
-Flow is designed to be extended with AI coding agents. The detector interface is intentionally simple: implement a protocol that returns entrypoints and handlers from parsed code.
+> **Bubble is designed to be adapted to your codebase.** The core engine handles exception propagation—you just tell it where your entrypoints are.
 
-To add support for a new framework (Django, Celery, your internal RPC layer, etc.):
+Every codebase has its own patterns: internal RPC frameworks, custom decorators, queue handlers, scheduled jobs. Bubble's extension system lets you teach it your patterns without modifying the core.
 
-1. Run `bubble init` to create the `.flow/` directory structure
-2. Point your AI agent at `flow/protocols.py` to see the `EntrypointDetector` interface
-3. Ask it to implement a detector for your framework in `.flow/detectors/`
+**Full guide: [docs/EXTENDING.md](docs/EXTENDING.md)**
 
-Example prompt for an AI agent:
+### What You Can Extend
 
-```
-Read flow/protocols.py and flow/detectors.py to understand how entrypoint
-detection works. Then implement a detector for Django that finds:
-- Views decorated with @api_view
-- Class-based views inheriting from APIView
-- URL patterns in urls.py
+| Pattern | Example | How to add |
+|---------|---------|------------|
+| Custom entrypoints | Celery tasks, Django views, gRPC handlers | `EntrypointDetector` |
+| Custom error handlers | Middleware, decorators | `GlobalHandlerDetector` |
+| Full framework | Django REST Framework, Airflow | `Integration` protocol |
+
+### Quick Example
+
+Drop a detector in `.flow/detectors/` and bubble auto-loads it:
 
-Put the implementation in .flow/detectors/django.py
+```python
+# .flow/detectors/celery.py
+from bubble.protocols import EntrypointDetector
+from bubble.integrations.base import Entrypoint
+from bubble.enums import EntrypointKind
+
+class CeleryTaskDetector(EntrypointDetector):
+    def detect(self, source: str, file_path: str) -> list[Entrypoint]:
+        # Find @app.task decorators, return Entrypoint objects
+        ...
 ```
 
-The detector just needs to implement:
-- `detect_entrypoints(functions, classes, ...)` → list of `Entrypoint`
-- `detect_global_handlers(...)` → list of `GlobalHandler`
+### AI-Friendly Design
 
-Flow will automatically load any `.py` files in `.flow/detectors/` and use them alongside the built-in Flask/FastAPI detectors.
+The protocol is intentionally simple for LLMs. Give your agent:
+
+```
+Read bubble/protocols.py and bubble/integrations/flask/detector.py.
+Implement a detector for [YOUR FRAMEWORK] that finds [PATTERNS].
+Put it in .flow/detectors/[framework].py
+```
+
+See **[docs/EXTENDING.md](docs/EXTENDING.md)** for complete examples including Celery, Django REST Framework, and custom decorator patterns.
 
 ## Configuration
 
-Flow can be configured via `.flow/config.yaml`:
+Bubble can be configured via `.flow/config.yaml`:
 
 ```yaml
 resolution_mode: default  # "strict", "default", or "aggressive"
@@ -222,13 +241,15 @@ exclude:
 
 ### Exception Stubs
 
-Flow includes built-in stubs for common libraries (requests, sqlalchemy, httpx, redis, boto3). These declare what exceptions external library functions can raise.
+Bubble includes built-in stubs for common libraries (requests, sqlalchemy, httpx, redis, boto3). These declare what exceptions external library functions can raise.
 
 Add custom stubs in `.flow/stubs/`:
 
 ```yaml
 # .flow/stubs/mylib.yaml
-mylib:
+module: mylib
+
+functions:
   do_thing:
     - MyLibError
     - TimeoutError
@@ -253,10 +274,10 @@ Manage stubs with `bubble stubs list` and `bubble stubs validate`.
 ## Development
 
 ```bash
-git clone https://github.com/ianm199/flow
-cd flow
-pip install -e ".[dev]"
-pytest
+git clone https://github.com/ianm199/bubble-analysis
+cd bubble-analysis
+uv pip install -e ".[dev]"
+uv run pytest
 ```
 
 ## License