bubble-analysis 0.2.0__py3-none-any.whl

bubble/results.py

@@ -0,0 +1,211 @@
+"""Result dataclasses for query functions.
+
+These define the contract between queries and formatters.
+All query functions return one of these typed results.
+"""
+
+from dataclasses import dataclass, field
+
+from bubble.models import (
+    CallSite,
+    CatchSite,
+    ClassHierarchy,
+    Entrypoint,
+    GlobalHandler,
+    RaiseSite,
+)
+from bubble.propagation import ExceptionFlow
+
+
+@dataclass
+class RaisesResult:
+    """Result of finding raise sites for an exception."""
+
+    exception_type: str
+    include_subclasses: bool
+    types_searched: set[str]
+    matches: list[RaiseSite]
+
+
+@dataclass
+class ExceptionClass:
+    """Info about an exception class."""
+
+    name: str
+    bases: list[str]
+    file: str | None
+    line: int | None
+
+
+@dataclass
+class ExceptionsResult:
+    """Result of listing exception hierarchy."""
+
+    classes: dict[str, ExceptionClass]
+    roots: set[str]
+    hierarchy: ClassHierarchy
+
+
+@dataclass
+class StatsResult:
+    """Result of codebase statistics."""
+
+    functions: int
+    classes: int
+    raise_sites: int
+    catch_sites: int
+    call_sites: int
+    entrypoints: int
+    http_routes: int
+    cli_scripts: int
+    global_handlers: int
+    imports: int
+
+
+@dataclass
+class CallersResult:
+    """Result of finding callers of a function."""
+
+    function_name: str
+    calls: list[CallSite]
+    suggestions: list[str] = field(default_factory=list)
+
+
+@dataclass
+class EntrypointTrace:
+    """A single raise site traced to its entrypoints."""
+
+    raise_site: RaiseSite
+    paths: list[list[str]]
+    entrypoints: list[Entrypoint]
+
+
+@dataclass
+class EntrypointsToResult:
+    """Result of tracing exception to entrypoints."""
+
+    exception_type: str
+    include_subclasses: bool
+    types_searched: set[str]
+    traces: list[EntrypointTrace]
+
+
+@dataclass
+class EntrypointsResult:
+    """Result of listing all entrypoints."""
+
+    http_routes: list[Entrypoint]
+    cli_scripts: list[Entrypoint]
+    other: dict[str, list[Entrypoint]]
+
+
+@dataclass
+class EscapesResult:
+    """Result of finding escaping exceptions."""
+
+    function_name: str
+    entrypoint: Entrypoint | None
+    flow: ExceptionFlow
+    global_handlers: list[GlobalHandler]
+
+
+@dataclass
+class CatchesResult:
+    """Result of finding catch sites for an exception."""
+
+    exception_type: str
+    include_subclasses: bool
+    types_searched: set[str]
+    local_catches: list[CatchSite]
+    global_handlers: list[GlobalHandler]
+
+
+@dataclass
+class AuditIssue:
+    """An entrypoint with uncaught exceptions."""
+
+    entrypoint: Entrypoint
+    uncaught: dict[str, list[RaiseSite]]
+    caught: dict[str, list[RaiseSite]]
+
+
+@dataclass
+class AuditResult:
+    """Result of auditing all entrypoints."""
+
+    total_entrypoints: int
+    issues: list[AuditIssue]
+    clean_count: int
+
+
+@dataclass
+class CacheStats:
+    """Result of cache statistics."""
+
+    file_count: int
+    size_bytes: int
+
+
+@dataclass
+class TraceNode:
+    """A node in the trace tree."""
+
+    function: str
+    qualified: str
+    direct_raises: list[str]
+    propagated_raises: list[str]
+    calls: list["TraceNode | PolymorphicNode"]
+
+
+@dataclass
+class PolymorphicNode:
+    """A polymorphic call with multiple implementations."""
+
+    function: str
+    implementations: list[TraceNode]
+    raises: list[str]
+
+
+@dataclass
+class TraceResult:
+    """Result of tracing exception flow."""
+
+    function_name: str
+    entrypoint: Entrypoint | None
+    root: TraceNode | None
+    escaping_exceptions: set[str]
+
+
+@dataclass
+class SubclassInfo:
+    """Info about a subclass."""
+
+    name: str
+    file: str | None
+    line: int | None
+    is_abstract: bool
+
+
+@dataclass
+class SubclassesResult:
+    """Result of finding subclasses."""
+
+    class_name: str
+    base_class_file: str | None
+    base_class_line: int | None
+    is_abstract: bool
+    abstract_methods: set[str]
+    subclasses: list[SubclassInfo]
+
+
+@dataclass
+class InitResult:
+    """Result of initializing .flow directory."""
+
+    flow_dir: str
+    functions_count: int
+    http_routes_count: int
+    cli_scripts_count: int
+    exception_classes_count: int
+    global_handlers_count: int
+    frameworks_detected: list[str]

bubble/stubs.py

@@ -0,0 +1,89 @@
+"""Exception stubs for external libraries."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class StubLibrary:
+    """Collection of exception stubs for external libraries."""
+
+    stubs: dict[str, dict[str, list[str]]] = field(default_factory=dict)
+
+    def get_raises(self, module: str, function: str) -> list[str]:
+        """Get exceptions that a function can raise."""
+        module_stubs = self.stubs.get(module, {})
+        return module_stubs.get(function, [])
+
+    def add_stub(self, module: str, function: str, exceptions: list[str]) -> None:
+        """Add a stub for a function."""
+        if module not in self.stubs:
+            self.stubs[module] = {}
+        self.stubs[module][function] = exceptions
+
+
+def _load_stub_file(library: StubLibrary, yaml_file: Path) -> None:
+    """Load stubs from a YAML file into the library."""
+    with open(yaml_file) as f:
+        data = yaml.safe_load(f)
+
+    if not data:
+        return
+
+    module = data.get("module", yaml_file.stem)
+    functions = data.get("functions", {})
+
+    for func_name, exceptions in functions.items():
+        if isinstance(exceptions, list):
+            library.add_stub(module, func_name, exceptions)
+
+
+def load_stubs(directory: Path) -> StubLibrary:
+    """Load all stub files from built-in and user directories."""
+    library = StubLibrary()
+
+    builtin_dir = Path(__file__).parent / "stubs"
+    user_dir = directory / ".flow" / "stubs"
+
+    for stub_dir in [builtin_dir, user_dir]:
+        if stub_dir.exists():
+            for yaml_file in stub_dir.glob("*.yaml"):
+                _load_stub_file(library, yaml_file)
+
+    return library
+
+
+def validate_stub_file(yaml_file: Path) -> list[str]:
+    """Validate a stub file and return any errors."""
+    errors: list[str] = []
+
+    try:
+        with open(yaml_file) as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        errors.append(f"YAML syntax error: {e}")
+        return errors
+
+    if not isinstance(data, dict):
+        errors.append("Root must be a dictionary")
+        return errors
+
+    if "module" not in data:
+        errors.append("Missing 'module' key")
+
+    if "functions" not in data:
+        errors.append("Missing 'functions' key")
+    elif not isinstance(data["functions"], dict):
+        errors.append("'functions' must be a dictionary")
+    else:
+        for func_name, exceptions in data["functions"].items():
+            if not isinstance(exceptions, list):
+                errors.append(f"'{func_name}' must map to a list of exceptions")
+            else:
+                for exc in exceptions:
+                    if not isinstance(exc, str):
+                        errors.append(f"Exception in '{func_name}' must be a string")
+
+    return errors

bubble/timing.py

@@ -0,0 +1,144 @@
+"""Simple timing instrumentation for performance analysis."""
+
+from __future__ import annotations
+
+import atexit
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+
+@dataclass
+class TimingStats:
+    """Collected timing statistics."""
+
+    timings: dict[str, float] = field(default_factory=dict)
+    counts: dict[str, int] = field(default_factory=dict)
+    enabled: bool = False
+    _console: Console | None = None
+
+
+_stats = TimingStats()
+
+
+def enable(console: Console | None = None) -> None:
+    """Enable timing collection."""
+    _stats.enabled = True
+    _stats.timings.clear()
+    _stats.counts.clear()
+    _stats._console = console
+    atexit.register(_print_report_on_exit)
+
+
+def disable() -> None:
+    """Disable timing collection."""
+    _stats.enabled = False
+
+
+def is_enabled() -> bool:
+    """Check if timing is enabled."""
+    return _stats.enabled
+
+
+@contextmanager
+def timed(name: str) -> Generator[None, None, None]:
+    """Context manager to time a block of code."""
+    if not _stats.enabled:
+        yield
+        return
+
+    start = time.perf_counter()
+    yield
+    elapsed = time.perf_counter() - start
+
+    _stats.timings[name] = _stats.timings.get(name, 0.0) + elapsed
+    _stats.counts[name] = _stats.counts.get(name, 0) + 1
+
+
+def record(name: str, elapsed: float) -> None:
+    """Record a timing directly."""
+    if not _stats.enabled:
+        return
+    _stats.timings[name] = _stats.timings.get(name, 0.0) + elapsed
+    _stats.counts[name] = _stats.counts.get(name, 0) + 1
+
+
+def record_count(name: str, count: int) -> None:
+    """Record a counter value (not a timing)."""
+    if not _stats.enabled:
+        return
+    _stats.timings[name] = 0.0
+    _stats.counts[name] = count
+
+
+def get_report() -> dict[str, dict[str, float | int]]:
+    """Get timing report as dict."""
+    return {
+        name: {
+            "total_seconds": _stats.timings[name],
+            "count": _stats.counts[name],
+            "avg_ms": (_stats.timings[name] / _stats.counts[name]) * 1000,
+        }
+        for name in sorted(_stats.timings, key=lambda k: _stats.timings[k], reverse=True)
+    }
+
+
+def format_report() -> str:
+    """Format timing report as a string."""
+    report = get_report()
+    if not report:
+        return "No timing data collected."
+
+    time_metrics = []
+    counter_metrics = []
+
+    for name, data in report.items():
+        total = data["total_seconds"]
+        count = data["count"]
+        is_counter = (
+            total == 0.0
+            or name.startswith("propagation_")
+            and name
+            not in (
+                "propagation_setup",
+                "propagation_fixpoint",
+            )
+        )
+
+        if is_counter:
+            counter_metrics.append((name, count))
+        elif count == 1:
+            time_metrics.append((name, f"{total:>8.3f}s"))
+        else:
+            avg_ms = data["avg_ms"]
+            time_metrics.append((name, f"{total:>8.3f}s  ({count:,} calls, {avg_ms:.2f}ms avg)"))
+
+    lines = ["", "Timing breakdown:"]
+    for name, value in time_metrics:
+        lines.append(f"  {name:30s} {value}")
+
+    if counter_metrics:
+        lines.append("")
+        lines.append("Propagation stats:")
+        for name, count in counter_metrics:
+            display_name = name.replace("propagation_", "  ")
+            lines.append(f"  {display_name:30s} {count:,}")
+
+    return "\n".join(lines)
+
+
+def _print_report_on_exit() -> None:
+    """Print timing report on program exit."""
+    if not _stats.enabled or not _stats.timings:
+        return
+
+    report_str = format_report()
+    if _stats._console:
+        _stats._console.print(report_str)
+    else:
+        print(report_str)

bubble_analysis-0.2.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: bubble-analysis
+Version: 0.2.0
+Summary: Static analysis tool for tracing exception flow through Python codebases
+Author-email: Ian McLaughlin <ianm199@github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ianm199/flow
+Project-URL: Repository, https://github.com/ianm199/flow
+Project-URL: Issues, https://github.com/ianm199/flow/issues
+Keywords: static-analysis,exceptions,python,code-analysis,flask,fastapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: libcst>=1.1.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# flow
+
+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.
+
+## Quick Start
+
+```bash
+pip install bubble-analysis
+```
+
+```bash
+# Check Flask routes for uncaught exceptions
+bubble flask audit -d /path/to/project
+
+# Check FastAPI routes
+bubble fastapi audit -d /path/to/project
+
+# Deep dive into one function
+bubble escapes create_user -d /path/to/project
+
+# Visualize the call tree
+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:
+
+```
+$ flow flask audit
+
+Scanning 23 flask entrypoints...
+
+3 entrypoints have uncaught exceptions:
+
+  POST /users/import
+    └─ FileNotFoundError (importers.py:45)
+    └─ ValidationError (validators.py:12)
+
+  GET /reports/{id}
+    └─ PermissionError (auth.py:89)
+
+20 entrypoints fully covered by exception handlers
+```
+
+For a specific endpoint, see the full picture:
+
+```
+$ flow escapes create_user
+
+Exceptions that can escape from POST /users:
+
+  FRAMEWORK-HANDLED (converted to HTTP response):
+    HTTPException
+      └─ becomes: HTTP 404
+      └─ raised in: routes/users.py:45 (get_user) [high confidence]
+
+  CAUGHT BY GLOBAL HANDLER:
+    ValidationError (@errorhandler(AppError))
+      └─ raised in: validators.py:27 (validate_input) [high confidence]
+
+  UNCAUGHT (will propagate to caller):
+    ConnectionError
+      └─ raised in: db/client.py:45 (execute) [medium confidence]
+      └─ call path: create_user → save_user → db.execute
+```
+
+Visualize as a tree:
+
+```
+$ flow trace create_user
+
+POST /users  → escapes: ValidationError, ConnectionError
+├── validate_input()  → ValidationError
+│   └── raises ValidationError (validators.py:27)
+└── save_user()  → ConnectionError
+    └── db.execute()  → ConnectionError
+        └── raises ConnectionError (db/client.py:45)
+```
+
+## Features
+
+- **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
+- **Polymorphism**: Expands abstract method calls to all concrete implementations
+- **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.)
+- **JSON output**: All commands support `-f json` for CI/automation
+- **Caching**: SQLite-based caching for fast repeated analysis
+
+## Commands
+
+### Core Commands (framework-agnostic)
+
+| Command | Description |
+|---------|-------------|
+| `bubble raises <exception>` | Find all places an exception is raised |
+| `bubble escapes <function>` | Show what can escape from a specific function |
+| `bubble callers <function>` | Find all callers of a function |
+| `bubble catches <exception>` | Find all places an exception is caught |
+| `bubble trace <function>` | Visualize exception flow as a call tree |
+| `bubble exceptions` | Show the exception class hierarchy |
+| `bubble subclasses <class>` | Show class inheritance tree |
+| `bubble stubs <action>` | Manage exception stubs (`list`, `init`, `validate`) |
+| `bubble stats` | Show codebase statistics |
+
+### Framework-Specific Commands
+
+| Command | Description |
+|---------|-------------|
+| `bubble flask audit` | Check Flask routes for escaping exceptions |
+| `bubble flask entrypoints` | List Flask HTTP routes |
+| `bubble flask routes-to <exc>` | Which Flask routes can trigger this exception? |
+| `bubble fastapi audit` | Check FastAPI routes for escaping exceptions |
+| `bubble fastapi entrypoints` | List FastAPI HTTP routes |
+| `bubble fastapi routes-to <exc>` | Which FastAPI routes can trigger this exception? |
+| `bubble cli audit` | Check CLI scripts for escaping exceptions |
+| `bubble cli entrypoints` | List CLI scripts |
+| `bubble cli scripts-to <exc>` | Which CLI scripts can trigger this exception? |
+
+All commands accept:
+- `-d, --directory`: Directory to analyze (default: current)
+- `-f, --format`: Output format (`text` or `json`)
+- `--no-cache`: Disable caching
+
+The `escapes` command accepts additional flags:
+- `--strict`: High precision mode - only includes precisely resolved calls
+- `--aggressive`: High recall mode - includes fuzzy matches
+
+## Supported Frameworks
+
+**Detected automatically:**
+- Flask (`@app.route`, `@blueprint.route`, `@app.errorhandler`)
+- FastAPI (`@router.get/post/put/delete`, `add_exception_handler`)
+- CLI scripts (`if __name__ == "__main__"`)
+
+**Not yet supported:**
+- Django
+- Celery tasks
+- Scheduled jobs (APScheduler, etc.)
+
+Custom patterns can be added via `.flow/detectors/` (run `bubble init` to set up).
+
+## Adding Custom Detectors
+
+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.
+
+To add support for a new framework (Django, Celery, your internal RPC layer, etc.):
+
+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/`
+
+Example prompt for an AI agent:
+
+```
+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
+
+Put the implementation in .flow/detectors/django.py
+```
+
+The detector just needs to implement:
+- `detect_entrypoints(functions, classes, ...)` → list of `Entrypoint`
+- `detect_global_handlers(...)` → list of `GlobalHandler`
+
+Flow will automatically load any `.py` files in `.flow/detectors/` and use them alongside the built-in Flask/FastAPI detectors.
+
+## Configuration
+
+Flow can be configured via `.flow/config.yaml`:
+
+```yaml
+resolution_mode: default  # "strict", "default", or "aggressive"
+exclude:
+  - vendor
+  - migrations
+```
+
+### Exception Stubs
+
+Flow 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:
+  do_thing:
+    - MyLibError
+    - TimeoutError
+```
+
+Manage stubs with `bubble stubs list` and `bubble stubs validate`.
+
+## How It Works
+
+1. **Parse**: LibCST parses all Python files
+2. **Extract**: Find functions, classes, raise/catch sites, calls, entrypoints
+3. **Build call graph**: Track who calls whom, resolve method calls
+4. **Propagate**: Fixed-point iteration computes which exceptions escape each function
+5. **Report**: For each entrypoint, show caught vs uncaught exceptions
+
+## Limitations
+
+- **Over-approximation**: May report more exceptions than actually possible (e.g., all implementations of an abstract method)
+- **Under-approximation**: Dynamic dispatch, `eval()`, and external libraries can't be fully traced
+- **No runtime info**: Analysis is purely static
+
+## Development
+
+```bash
+git clone https://github.com/ianm199/flow
+cd flow
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT