roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/services/retry.py

@@ -0,0 +1,288 @@
+"""Retry logic with exponential backoff for handling transient failures."""
+
+import functools
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ..logging import get_logger
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def retry(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    backoff: float = 2.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+    on_retry: Callable[[Exception, int], None] | None = None,
+):
+    """Retry decorator with exponential backoff.
+
+    This decorator automatically retries a function if it raises one of the
+    specified exceptions. The delay between retries increases exponentially
+    using the backoff factor.
+
+    Args:
+        max_attempts: Maximum number of attempts (including the first try)
+        delay: Initial delay in seconds between retries
+        backoff: Multiplier for delay after each retry (exponential backoff)
+        exceptions: Tuple of exception types to catch and retry on
+        on_retry: Optional callback function called before each retry.
+                 Takes (exception, attempt_number) as arguments.
+
+    Example:
+        @retry(max_attempts=5, delay=1.0, backoff=2.0, exceptions=(ConnectionError, TimeoutError))
+        def fetch_data():
+            # ... make network request
+            pass
+
+        The retry delays will be: 1s, 2s, 4s, 8s
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            attempt = 0
+            current_delay = delay
+            last_exception: Exception | None = None
+
+            while attempt < max_attempts:
+                attempt += 1
+
+                try:
+                    result = func(*args, **kwargs)
+
+                    # Log success if we had previous failures
+                    if attempt > 1:
+                        logger.info(
+                            "retry_succeeded",
+                            function=func.__name__,
+                            attempt=attempt,
+                            max_attempts=max_attempts,
+                        )
+
+                    return result
+
+                except exceptions as e:
+                    last_exception = e
+
+                    # Don't retry if we've exhausted attempts
+                    if attempt >= max_attempts:
+                        logger.error(
+                            "retry_exhausted",
+                            function=func.__name__,
+                            attempts=attempt,
+                            error=str(e),
+                            error_type=type(e).__name__,
+                        )
+                        raise
+
+                    # Log retry attempt
+                    logger.warning(
+                        "retry_attempt",
+                        function=func.__name__,
+                        attempt=attempt,
+                        max_attempts=max_attempts,
+                        delay_seconds=current_delay,
+                        error=str(e),
+                        error_type=type(e).__name__,
+                    )
+
+                    # Call on_retry callback if provided
+                    if on_retry:
+                        try:
+                            on_retry(e, attempt)
+                        except Exception as callback_error:
+                            logger.error(
+                                "retry_callback_failed",
+                                function=func.__name__,
+                                error=str(callback_error),
+                            )
+
+                    # Wait before retrying
+                    time.sleep(current_delay)
+
+                    # Exponential backoff
+                    current_delay *= backoff
+
+            # This should never be reached, but just in case
+            if last_exception:
+                raise last_exception
+            raise RuntimeError(f"Retry logic failed for {func.__name__}")
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def async_retry(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    backoff: float = 2.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+    on_retry: Callable[[Exception, int], None] | None = None,
+):
+    """Async version of retry decorator with exponential backoff.
+
+    Args:
+        max_attempts: Maximum number of attempts (including the first try)
+        delay: Initial delay in seconds between retries
+        backoff: Multiplier for delay after each retry (exponential backoff)
+        exceptions: Tuple of exception types to catch and retry on
+        on_retry: Optional callback function called before each retry
+
+    Example:
+        @async_retry(max_attempts=5, delay=1.0, backoff=2.0)
+        async def fetch_data():
+            # ... make async network request
+            pass
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            import asyncio
+
+            attempt = 0
+            current_delay = delay
+            last_exception: Exception | None = None
+
+            while attempt < max_attempts:
+                attempt += 1
+
+                try:
+                    result = await func(*args, **kwargs)
+
+                    # Log success if we had previous failures
+                    if attempt > 1:
+                        logger.info(
+                            "async_retry_succeeded",
+                            function=func.__name__,
+                            attempt=attempt,
+                            max_attempts=max_attempts,
+                        )
+
+                    return result
+
+                except exceptions as e:
+                    last_exception = e
+
+                    # Don't retry if we've exhausted attempts
+                    if attempt >= max_attempts:
+                        logger.error(
+                            "async_retry_exhausted",
+                            function=func.__name__,
+                            attempts=attempt,
+                            error=str(e),
+                            error_type=type(e).__name__,
+                        )
+                        raise
+
+                    # Log retry attempt
+                    logger.warning(
+                        "async_retry_attempt",
+                        function=func.__name__,
+                        attempt=attempt,
+                        max_attempts=max_attempts,
+                        delay_seconds=current_delay,
+                        error=str(e),
+                        error_type=type(e).__name__,
+                    )
+
+                    # Call on_retry callback if provided
+                    if on_retry:
+                        try:
+                            on_retry(e, attempt)
+                        except Exception as callback_error:
+                            logger.error(
+                                "async_retry_callback_failed",
+                                function=func.__name__,
+                                error=str(callback_error),
+                            )
+
+                    # Wait before retrying (async sleep)
+                    await asyncio.sleep(current_delay)
+
+                    # Exponential backoff
+                    current_delay *= backoff
+
+            # This should never be reached, but just in case
+            if last_exception:
+                raise last_exception
+            raise RuntimeError(f"Async retry logic failed for {func.__name__}")
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+class RetryConfig:
+    """Configuration for retry behavior.
+
+    This class provides a convenient way to share retry configuration
+    across multiple operations.
+    """
+
+    def __init__(
+        self,
+        max_attempts: int = 3,
+        delay: float = 1.0,
+        backoff: float = 2.0,
+        exceptions: tuple[type[Exception], ...] = (Exception,),
+    ):
+        """Initialize retry configuration.
+
+        Args:
+            max_attempts: Maximum number of attempts
+            delay: Initial delay in seconds
+            backoff: Exponential backoff multiplier
+            exceptions: Exception types to retry on
+        """
+        self.max_attempts = max_attempts
+        self.delay = delay
+        self.backoff = backoff
+        self.exceptions = exceptions
+
+    def __call__(self, func: F) -> F:
+        """Use config as a decorator."""
+        return retry(
+            max_attempts=self.max_attempts,
+            delay=self.delay,
+            backoff=self.backoff,
+            exceptions=self.exceptions,
+        )(func)
+
+    def async_decorator(self, func: F) -> F:
+        """Use config as an async decorator."""
+        return async_retry(
+            max_attempts=self.max_attempts,
+            delay=self.delay,
+            backoff=self.backoff,
+            exceptions=self.exceptions,
+        )(func)
+
+
+# Predefined retry configurations for common scenarios
+NETWORK_RETRY = RetryConfig(
+    max_attempts=5,
+    delay=1.0,
+    backoff=2.0,
+    exceptions=(ConnectionError, TimeoutError, OSError),
+)
+
+API_RETRY = RetryConfig(
+    max_attempts=3,
+    delay=0.5,
+    backoff=1.5,
+    exceptions=(ConnectionError, TimeoutError),
+)
+
+DATABASE_RETRY = RetryConfig(
+    max_attempts=3,
+    delay=0.1,
+    backoff=2.0,
+    exceptions=(Exception,),  # Database-specific exceptions would go here
+)

roadmap/common/status_style_manager.py

@@ -0,0 +1,114 @@
+"""Centralized status styling for consistent UI across application.
+
+This module consolidates all status-to-style mappings to eliminate DRY violations
+and ensure consistent status rendering everywhere.
+"""
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+class StatusStyle(Enum):
+    """Enum for common status values."""
+
+    TODO = "TODO"
+    IN_PROGRESS = "IN_PROGRESS"
+    BLOCKED = "BLOCKED"
+    REVIEW = "REVIEW"
+    CLOSED = "CLOSED"
+    OPEN = "OPEN"
+    COMPLETED = "COMPLETED"
+    ARCHIVED = "ARCHIVED"
+
+
+class StatusStyleManager:
+    """Centralized manager for status styling across application."""
+
+    # Rich style mappings for status values
+    STATUS_STYLES: dict[str, str] = {
+        # Issue/Task statuses
+        "TODO": "white",
+        "IN_PROGRESS": "yellow",
+        "BLOCKED": "red",
+        "REVIEW": "blue",
+        "CLOSED": "green",
+        # Project/Milestone statuses
+        "OPEN": "cyan",
+        "COMPLETED": "green",
+        "ARCHIVED": "dim",
+    }
+
+    # Emoji mapping for status
+    STATUS_EMOJIS: dict[str, str] = {
+        "TODO": "📝",
+        "IN_PROGRESS": "🔄",
+        "BLOCKED": "🚫",
+        "REVIEW": "👀",
+        "CLOSED": "✅",
+        "OPEN": "📂",
+        "COMPLETED": "🎉",
+        "ARCHIVED": "📦",
+    }
+
+    @classmethod
+    def get_style(cls, status: str | Enum) -> str:
+        """Get Rich style string for a status.
+
+        Args:
+            status: Status value (string or Enum)
+
+        Returns:
+            Rich style string (e.g., "bold red")
+        """
+        status_str = status.value if isinstance(status, Enum) else str(status).upper()
+        return cls.STATUS_STYLES.get(status_str, "white")
+
+    @classmethod
+    def get_emoji(cls, status: str | Enum) -> str:
+        """Get emoji for a status.
+
+        Args:
+            status: Status value (string or Enum)
+
+        Returns:
+            Emoji character
+        """
+        status_str = status.value if isinstance(status, Enum) else str(status).upper()
+        return cls.STATUS_EMOJIS.get(status_str, "•")
+
+    @classmethod
+    def get_rich_text(cls, status: str | Enum, text: str | None = None) -> Any:
+        """Create Rich Text object with proper style and emoji.
+
+        Args:
+            status: Status value
+            text: Optional custom text (defaults to status string)
+
+        Returns:
+            Rich Text object ready for rendering
+        """
+        from rich.text import Text
+
+        display_text = text or str(status)
+        return Text(display_text, style=cls.get_style(status))
+
+    @classmethod
+    def all_styles(cls) -> dict[str, str]:
+        """Get all available status styles.
+
+        Returns:
+            Dictionary mapping status -> style
+        """
+        return cls.STATUS_STYLES.copy()
+
+    @classmethod
+    def all_emojis(cls) -> dict[str, str]:
+        """Get all available status emojis.
+
+        Returns:
+            Dictionary mapping status -> emoji
+        """
+        return cls.STATUS_EMOJIS.copy()

roadmap/common/union_find.py

@@ -0,0 +1,88 @@
+"""Union-Find (Disjoint Set Union) data structure with path compression.
+
+Provides O(α(n)) ≈ O(1) operations for union and find operations,
+where α is the inverse Ackermann function (effectively constant).
+"""
+
+from typing import Any
+
+
+class UnionFind:
+    """Efficient disjoint set data structure with path compression and union by rank."""
+
+    def __init__(self, items: list[Any]) -> None:
+        """Initialize union-find with given items.
+
+        Args:
+            items: List of hashable items to track
+        """
+        self.parent: dict[Any, Any] = {item: item for item in items}
+        self.rank: dict[Any, int] = dict.fromkeys(items, 0)
+
+    def find(self, item: Any) -> Any:
+        """Find the canonical representative of item's set with path compression.
+
+        Args:
+            item: Item to find representative for
+
+        Returns:
+            Canonical representative of item's set
+        """
+        if self.parent[item] != item:
+            # Path compression: point directly to root
+            self.parent[item] = self.find(self.parent[item])
+        return self.parent[item]
+
+    def union(self, item1: Any, item2: Any) -> bool:
+        """Union the sets containing item1 and item2.
+
+        Args:
+            item1: First item
+            item2: Second item
+
+        Returns:
+            True if union occurred, False if already in same set
+        """
+        root1 = self.find(item1)
+        root2 = self.find(item2)
+
+        if root1 == root2:
+            return False  # Already in same set
+
+        # Union by rank: attach smaller tree under larger
+        if self.rank[root1] < self.rank[root2]:
+            self.parent[root1] = root2
+        elif self.rank[root1] > self.rank[root2]:
+            self.parent[root2] = root1
+        else:
+            # Same rank: pick one and increment its rank
+            self.parent[root2] = root1
+            self.rank[root1] += 1
+
+        return True
+
+    def get_canonical(self, item: Any) -> Any:
+        """Get canonical representative (alias for find)."""
+        return self.find(item)
+
+    def get_representatives(self) -> set[Any]:
+        """Get all canonical representatives (roots of each set).
+
+        Returns:
+            Set of canonical representatives
+        """
+        return {self.find(item) for item in self.parent.keys()}
+
+    def get_groups(self) -> dict[Any, list[Any]]:
+        """Get mapping of representative -> list of items in that group.
+
+        Returns:
+            Dict mapping canonical representative to list of items
+        """
+        groups: dict[Any, list[Any]] = {}
+        for item in self.parent.keys():
+            rep = self.find(item)
+            if rep not in groups:
+                groups[rep] = []
+            groups[rep].append(item)
+        return groups

roadmap/common/update_constants.py

@@ -0,0 +1,13 @@
+"""Shared constants for update operations."""
+
+# Fields that are displayed when showing update results
+DISPLAYABLE_UPDATE_FIELDS = [
+    "title",
+    "priority",
+    "status",
+    "assignee",
+    "milestone",
+    "description",
+]
+
+__all__ = ["DISPLAYABLE_UPDATE_FIELDS"]

roadmap/common/utils/__init__.py

@@ -0,0 +1,65 @@
+"""Common utility functions for CLI operations, file handling, and data processing.
+
+This package provides low-level utilities used across the application:
+- CLI helpers: Output formatting, decorators for command functions
+- File utilities: File operations and secure file handling
+- Path utilities: Path checking and validation
+- Status utilities: Status-related helpers
+- Timezone utilities: Timezone-aware date/time operations
+
+Note: These are utility functions with minimal dependencies - they should not
+import from higher-level modules (services, domain, adapters) to avoid
+layer violations and circular dependencies.
+"""
+
+from .cli_helpers import OutputFormatHandler, format_output
+from .file_utils import (
+    SecureFileManager,
+    backup_file,
+    cleanup_temp_files,
+    ensure_directory_exists,
+    file_exists_check,
+    get_file_size,
+    safe_read_file,
+    safe_write_file,
+)
+from .path_utils import build_roadmap_paths
+from .status_utils import StatusSummary
+from .timezone_utils import (
+    TimezoneManager,
+    ensure_timezone_aware,
+    format_datetime,
+    format_relative_time,
+    get_timezone_manager,
+    migrate_naive_datetime,
+    now_local,
+    now_utc,
+)
+
+__all__ = [
+    # CLI helpers
+    "OutputFormatHandler",
+    "format_output",
+    # File utilities
+    "SecureFileManager",
+    "backup_file",
+    "cleanup_temp_files",
+    "ensure_directory_exists",
+    "file_exists_check",
+    "get_file_size",
+    "safe_read_file",
+    "safe_write_file",
+    # Path utilities
+    "build_roadmap_paths",
+    # Status utilities
+    "StatusSummary",
+    # Timezone utilities
+    "TimezoneManager",
+    "ensure_timezone_aware",
+    "format_datetime",
+    "format_relative_time",
+    "get_timezone_manager",
+    "migrate_naive_datetime",
+    "now_local",
+    "now_utc",
+]