superqode 0.1.5__py3-none-any.whl

superqode/utils/error_handling.py

@@ -0,0 +1,323 @@
+"""
+Error handling utilities for SuperQode OSS
+
+Provides robust error handling for common edge cases and failure modes.
+"""
+
+import os
+import sys
+import logging
+from typing import Optional, Dict, Any, Callable
+from pathlib import Path
+from functools import wraps
+import asyncio
+
+logger = logging.getLogger(__name__)
+
+
+class SuperQodeError(Exception):
+    """Base exception for SuperQode errors."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class ConfigurationError(SuperQodeError):
+    """Configuration-related errors."""
+
+    pass
+
+
+class DependencyError(SuperQodeError):
+    """Missing dependency errors."""
+
+    pass
+
+
+class NetworkError(SuperQodeError):
+    """Network connectivity errors."""
+
+    pass
+
+
+class TimeoutError(SuperQodeError):
+    """Timeout-related errors."""
+
+    pass
+
+
+class ResourceError(SuperQodeError):
+    """Resource exhaustion errors."""
+
+    pass
+
+
+def handle_errors(fallback_message: str = "An unexpected error occurred"):
+    """Decorator to handle common errors gracefully."""
+
+    def decorator(func):
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                return handle_error(e, fallback_message, func.__name__)
+
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                return handle_error(e, fallback_message, func.__name__)
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        return sync_wrapper
+
+    return decorator
+
+
+def handle_error(error: Exception, fallback_message: str, context: str = "") -> Optional[Any]:
+    """Handle an error with appropriate logging and user-friendly messages."""
+
+    error_type = type(error).__name__
+
+    # Log the full error for debugging
+    logger.error(f"Error in {context}: {error_type}: {error}", exc_info=True)
+
+    # Handle specific error types with user-friendly messages
+    if isinstance(error, (OSError, PermissionError)):
+        if "permission denied" in str(error).lower():
+            print(f"❌ Permission denied: {error}")
+            print("💡 Try running with appropriate permissions or check file access.")
+            return None
+        elif "no space left on device" in str(error).lower():
+            print(f"❌ Disk full: {error}")
+            print("💡 Free up disk space and try again.")
+            return None
+        else:
+            print(f"❌ System error: {error}")
+
+    elif isinstance(error, ImportError):
+        if "opencode" in str(error).lower():
+            print("❌ OpenCode not found. Install with: npm i -g opencode-ai")
+            print("💡 OpenCode is required for AI agent analysis.")
+        else:
+            print(f"❌ Missing dependency: {error}")
+        return None
+
+    elif isinstance(error, asyncio.TimeoutError):
+        print(f"⏰ Operation timed out: {error}")
+        print("💡 Try increasing timeout or checking network connectivity.")
+        return None
+
+    elif isinstance(error, ConnectionError):
+        print(f"🌐 Network error: {error}")
+        print("💡 Check your internet connection and try again.")
+        return None
+
+    elif isinstance(error, MemoryError):
+        print(f"💾 Out of memory: {error}")
+        print("💡 Try closing other applications or reducing workload.")
+        return None
+
+    elif isinstance(error, FileNotFoundError):
+        if "opencode" in str(error).lower():
+            print("❌ OpenCode command not found.")
+            print("💡 Install OpenCode: npm i -g opencode-ai")
+        else:
+            print(f"❌ File not found: {error}")
+        return None
+
+    else:
+        # Generic error handling
+        print(f"❌ {fallback_message}: {error}")
+        if context:
+            print(f"   Context: {context}")
+
+    return None
+
+
+def check_dependencies():
+    """Check for required dependencies and provide helpful error messages."""
+
+    issues = []
+
+    # Check for Python version
+    if sys.version_info < (3, 8):
+        issues.append("Python 3.8+ required (current: {}.{}.{})".format(*sys.version_info[:3]))
+
+    # Check for Node.js and npm (for OpenCode)
+    try:
+        import subprocess
+
+        result = subprocess.run(["node", "--version"], capture_output=True, text=True, timeout=5)
+        if result.returncode != 0:
+            issues.append("Node.js not found or not working")
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        issues.append("Node.js not found - required for OpenCode")
+
+    try:
+        result = subprocess.run(["npm", "--version"], capture_output=True, text=True, timeout=5)
+        if result.returncode != 0:
+            issues.append("npm not found or not working")
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        issues.append("npm not found - required for OpenCode")
+
+    # Check for OpenCode
+    if not os.path.exists("/usr/local/bin/opencode") and not os.path.exists("/usr/bin/opencode"):
+        try:
+            result = subprocess.run(
+                ["which", "opencode"], capture_output=True, text=True, timeout=5
+            )
+            if result.returncode != 0:
+                issues.append("OpenCode not installed - install with: npm i -g opencode-ai")
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            issues.append("OpenCode not found - install with: npm i -g opencode-ai")
+
+    if issues:
+        print("⚠️  Dependency Issues Found:")
+        for issue in issues:
+            print(f"   • {issue}")
+        print("\n🔧 Fix these issues before running SuperQode QE features.")
+
+    return len(issues) == 0
+
+
+def validate_project_structure(project_root: Path) -> Dict[str, Any]:
+    """Validate project structure and return issues found."""
+
+    issues = {"warnings": [], "errors": [], "missing_files": [], "large_files": []}
+
+    # Check for common project files
+    common_files = ["package.json", "requirements.txt", "pyproject.toml", "Pipfile", "yarn.lock"]
+    has_project_file = any((project_root / f).exists() for f in common_files)
+
+    if not has_project_file:
+        issues["warnings"].append(
+            "No standard project file found (package.json, requirements.txt, etc.)"
+        )
+
+    # Check for large files that might cause issues
+    large_files = []
+    total_size = 0
+
+    try:
+        for file_path in project_root.rglob("*"):
+            if file_path.is_file() and not any(part.startswith(".") for part in file_path.parts):
+                try:
+                    size = file_path.stat().st_size
+                    total_size += size
+
+                    # Flag files over 50MB
+                    if size > 50 * 1024 * 1024:
+                        large_files.append(f"{file_path.name} ({size / (1024 * 1024):.1f}MB)")
+
+                    # Flag files over 10MB as warnings
+                    elif size > 10 * 1024 * 1024:
+                        issues["warnings"].append(
+                            f"Large file: {file_path.name} ({size / (1024 * 1024):.1f}MB)"
+                        )
+
+                except (OSError, PermissionError):
+                    continue
+
+        if large_files:
+            issues["errors"].extend([f"File too large for analysis: {f}" for f in large_files])
+
+        # Check total project size (warn over 500MB)
+        if total_size > 500 * 1024 * 1024:
+            issues["warnings"].append(".1f")
+
+    except Exception as e:
+        issues["warnings"].append(f"Could not analyze project structure: {e}")
+
+    return issues
+
+
+def create_fallback_result(operation: str, error: Exception) -> Dict[str, Any]:
+    """Create a fallback result when an operation fails."""
+
+    return {
+        "success": False,
+        "operation": operation,
+        "error": str(error),
+        "error_type": type(error).__name__,
+        "fallback": True,
+        "message": f"Operation '{operation}' failed, using fallback mode",
+    }
+
+
+def safe_file_operation(operation_name: str):
+    """Decorator for safe file operations."""
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except (OSError, PermissionError) as e:
+                logger.warning(f"File operation '{operation_name}' failed: {e}")
+                return create_fallback_result(operation_name, e)
+            except Exception as e:
+                logger.error(f"Unexpected error in '{operation_name}': {e}")
+                return create_fallback_result(operation_name, e)
+
+        return wrapper
+
+    return decorator
+
+
+def safe_network_operation(operation_name: str, timeout: int = 30):
+    """Decorator for safe network operations."""
+
+    def decorator(func):
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            try:
+                return await asyncio.wait_for(func(*args, **kwargs), timeout=timeout)
+            except asyncio.TimeoutError:
+                logger.warning(f"Network operation '{operation_name}' timed out")
+                return create_fallback_result(
+                    operation_name, asyncio.TimeoutError("Operation timed out")
+                )
+            except Exception as e:
+                logger.error(f"Network operation '{operation_name}' failed: {e}")
+                return create_fallback_result(operation_name, e)
+
+        return async_wrapper
+
+    return decorator
+
+
+# Global error recovery strategies
+def attempt_recovery(func: Callable, max_retries: int = 3, backoff_factor: float = 1.5):
+    """Attempt to recover from transient failures."""
+
+    import time
+
+    @wraps(func)
+    async def async_wrapper(*args, **kwargs):
+        last_error = None
+
+        for attempt in range(max_retries):
+            try:
+                return await func(*args, **kwargs)
+            except (ConnectionError, OSError) as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    delay = backoff_factor**attempt
+                    logger.info(f"Attempt {attempt + 1} failed, retrying in {delay:.1f}s: {e}")
+                    await asyncio.sleep(delay)
+                else:
+                    logger.error(f"All {max_retries} attempts failed: {e}")
+            except Exception as e:
+                # Don't retry for non-transient errors
+                raise e
+
+        # If we get here, all retries failed
+        raise last_error
+
+    return async_wrapper

superqode/utils/fuzzy.py

@@ -0,0 +1,257 @@
+"""Fuzzy search utilities with LRU caching for fast completion."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import NamedTuple
+
+
+class FuzzyMatch(NamedTuple):
+    """A fuzzy match result with score and match positions."""
+
+    text: str
+    score: float
+    positions: list[int]  # Character positions that matched
+
+
+class FuzzySearch:
+    """
+    Fast fuzzy search with LRU caching.
+
+    Inspired by fzf/fuzzysort algorithms with:
+    - Bonus for matches at word boundaries
+    - Bonus for contiguous matches
+    - Case-insensitive matching with case-match bonus
+    """
+
+    def __init__(self, max_cache_size: int = 1024):
+        """Initialize with cache size."""
+        self._cache_size = max_cache_size
+        # Create cached version of core search
+        self._cached_score = lru_cache(maxsize=max_cache_size)(self._compute_score)
+
+    def _compute_score(self, query: str, text: str) -> tuple[float, tuple[int, ...]]:
+        """
+        Compute fuzzy match score between query and text.
+
+        Returns (score, positions) where higher score = better match.
+        """
+        if not query:
+            return (0.0, ())
+
+        query_lower = query.lower()
+        text_lower = text.lower()
+
+        # Quick rejection: all query chars must be in text
+        for char in query_lower:
+            if char not in text_lower:
+                return (-1.0, ())
+
+        # Find best match using greedy algorithm
+        positions: list[int] = []
+        score = 0.0
+        query_idx = 0
+        prev_match_idx = -2  # For contiguity bonus
+
+        # Word boundary detection
+        word_boundaries = {0}  # Start is always a boundary
+        for i, char in enumerate(text):
+            if i > 0:
+                prev_char = text[i - 1]
+                # Boundary after: space, underscore, hyphen, slash, dot
+                # Or transition from lowercase to uppercase (camelCase)
+                if prev_char in " _-/." or (prev_char.islower() and char.isupper()):
+                    word_boundaries.add(i)
+
+        for text_idx, char in enumerate(text_lower):
+            if query_idx >= len(query_lower):
+                break
+
+            if char == query_lower[query_idx]:
+                positions.append(text_idx)
+
+                # Base score for match
+                match_score = 1.0
+
+                # Bonus for word boundary match
+                if text_idx in word_boundaries:
+                    match_score += 2.0
+
+                # Bonus for exact case match
+                if text[text_idx] == query[query_idx]:
+                    match_score += 0.5
+
+                # Bonus for contiguous matches
+                if text_idx == prev_match_idx + 1:
+                    match_score += 1.5
+
+                # Bonus for matching at start
+                if text_idx == 0:
+                    match_score += 3.0
+
+                score += match_score
+                prev_match_idx = text_idx
+                query_idx += 1
+
+        # All query characters must be matched
+        if query_idx < len(query_lower):
+            return (-1.0, ())
+
+        # Normalize score by query length and penalize by text length
+        # Shorter texts with same matches are preferred
+        normalized_score = score / len(query) - (len(text) * 0.01)
+
+        return (normalized_score, tuple(positions))
+
+    def search(
+        self,
+        query: str,
+        items: list[str],
+        max_results: int = 10,
+        threshold: float = 0.0,
+    ) -> list[FuzzyMatch]:
+        """
+        Search items for fuzzy matches to query.
+
+        Args:
+            query: The search query
+            items: List of strings to search
+            max_results: Maximum number of results to return
+            threshold: Minimum score threshold (default 0 = any match)
+
+        Returns:
+            List of FuzzyMatch objects sorted by score (best first)
+        """
+        if not query:
+            # Return first max_results items with score 0
+            return [FuzzyMatch(text=item, score=0.0, positions=[]) for item in items[:max_results]]
+
+        results: list[FuzzyMatch] = []
+
+        for item in items:
+            score, positions = self._cached_score(query, item)
+            if score >= threshold:
+                results.append(FuzzyMatch(text=item, score=score, positions=list(positions)))
+
+        # Sort by score descending
+        results.sort(key=lambda x: x.score, reverse=True)
+
+        return results[:max_results]
+
+    def search_with_data(
+        self,
+        query: str,
+        items: list[tuple[str, any]],
+        max_results: int = 10,
+        threshold: float = 0.0,
+    ) -> list[tuple[FuzzyMatch, any]]:
+        """
+        Search items with associated data.
+
+        Args:
+            query: The search query
+            items: List of (searchable_text, data) tuples
+            max_results: Maximum number of results
+            threshold: Minimum score threshold
+
+        Returns:
+            List of (FuzzyMatch, data) tuples sorted by score
+        """
+        if not query:
+            return [
+                (FuzzyMatch(text=text, score=0.0, positions=[]), data)
+                for text, data in items[:max_results]
+            ]
+
+        results: list[tuple[FuzzyMatch, any]] = []
+
+        for text, data in items:
+            score, positions = self._cached_score(query, text)
+            if score >= threshold:
+                results.append(
+                    (FuzzyMatch(text=text, score=score, positions=list(positions)), data)
+                )
+
+        results.sort(key=lambda x: x[0].score, reverse=True)
+
+        return results[:max_results]
+
+    def highlight_match(
+        self,
+        text: str,
+        positions: list[int],
+        highlight_start: str = "[bold cyan]",
+        highlight_end: str = "[/bold cyan]",
+    ) -> str:
+        """
+        Apply Rich markup to highlight matched positions.
+
+        Args:
+            text: Original text
+            positions: List of matched character positions
+            highlight_start: Rich markup to start highlight
+            highlight_end: Rich markup to end highlight
+
+        Returns:
+            Text with Rich markup applied to matched characters
+        """
+        if not positions:
+            return text
+
+        result = []
+        pos_set = set(positions)
+        in_highlight = False
+
+        for i, char in enumerate(text):
+            if i in pos_set:
+                if not in_highlight:
+                    result.append(highlight_start)
+                    in_highlight = True
+                result.append(char)
+            else:
+                if in_highlight:
+                    result.append(highlight_end)
+                    in_highlight = False
+                result.append(char)
+
+        if in_highlight:
+            result.append(highlight_end)
+
+        return "".join(result)
+
+    def clear_cache(self) -> None:
+        """Clear the search cache."""
+        self._cached_score.cache_clear()
+
+
+class PathFuzzySearch(FuzzySearch):
+    """
+    Specialized fuzzy search for file paths.
+
+    Gives extra weight to:
+    - Filename matches (last segment)
+    - Matches after path separators
+    """
+
+    def _compute_score(self, query: str, text: str) -> tuple[float, tuple[int, ...]]:
+        """Compute path-aware fuzzy match score."""
+        base_score, positions = super()._compute_score(query, text)
+
+        if base_score < 0:
+            return (base_score, positions)
+
+        # Bonus for matches in filename (after last /)
+        last_sep = text.rfind("/")
+        if last_sep >= 0:
+            filename_positions = [p for p in positions if p > last_sep]
+            if filename_positions:
+                # Significant bonus for filename matches
+                base_score += len(filename_positions) * 2.0
+
+        return (base_score, positions)
+
+
+# Global instances for convenience
+fuzzy_search = FuzzySearch()
+path_fuzzy_search = PathFuzzySearch()