roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/__init__.py

@@ -0,0 +1,308 @@
+"""Shared Layer - Common Utilities & Patterns.
+
+This layer contains utilities and patterns used across all layers.
+Common code that would otherwise be duplicated.
+
+Modules:
+- datetime_parser.py: Universal datetime parsing
+- timezone_utils.py: Timezone-aware datetime handling
+- validation.py: Data validation rules and validators
+- logging.py: Structured logging configuration
+- progress.py: Progress calculation engine
+- errors.py: Exception definitions
+- constants.py: Application constants and enums
+- file_utils.py: Secure file I/O operations
+- security.py: Security utilities and path validation
+
+Guidelines:
+- No layer-specific logic
+- Shared by all other layers
+- Pure functions or simple utilities
+- No external dependencies
+- Focused on one concern per module
+"""
+
+from .constants import (
+    ANALYSIS_MAX_HISTORICAL_DAYS,
+    ANALYSIS_MIN_SAMPLE_SIZE,
+    ANALYSIS_TREND_WINDOW,
+    AUTH_TIMEOUT,
+    # Configuration defaults
+    AUTH_TOKEN_ENV_VAR,
+    CACHE_TTL_DEFAULT,
+    CACHE_TTL_LONG,
+    CACHE_TTL_SHORT,
+    DEFAULT_BACKOFF_FACTOR,
+    DEFAULT_BATCH_SIZE,
+    DEFAULT_CACHE_FILE,
+    DEFAULT_CONFIG_FILE,
+    DEFAULT_DATA_DIR,
+    DEFAULT_DATE_FORMAT,
+    DEFAULT_DATETIME_FORMAT,
+    DEFAULT_MAX_ITEMS_DISPLAY,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RETRY_DELAY,
+    DEFAULT_ROADMAP_FILE,
+    DEFAULT_TABLE_WIDTH,
+    ERROR_MESSAGE_MAX_LENGTH,
+    GIT_COMMIT_MESSAGE_MAX_LENGTH,
+    GIT_MAX_OUTPUT_LINES,
+    GIT_TIMEOUT,
+    GITHUB_API_BASE,
+    GITHUB_API_TIMEOUT,
+    GITHUB_GRAPHQL_ENDPOINT,
+    GITHUB_RATE_LIMIT_THRESHOLD,
+    LOG_FORMAT_DEFAULT,
+    LOG_LEVEL_DEFAULT,
+    PERFORMANCE_CONNECTION_POOL_SIZE,
+    PERFORMANCE_ENABLE_ASYNC,
+    PERFORMANCE_ENABLE_CACHE,
+    PERFORMANCE_THREAD_POOL_SIZE,
+    PROGRESS_BAR_LENGTH,
+    PROGRESS_REFRESH_INTERVAL,
+    VALIDATION_ERROR_MAX_FIELDS,
+    VALIDATION_NAME_PATTERN,
+    VALIDATION_TITLE_MAX_LENGTH,
+    VALIDATION_TITLE_MIN_LENGTH,
+    IssueType,
+    MilestoneStatus,
+    Priority,
+    ProjectStatus,
+    RiskLevel,
+    Status,
+)
+from .datetime_parser import (
+    UnifiedDateTimeParser,
+    parse_datetime,
+    parse_file_datetime,
+    parse_github_datetime,
+    parse_user_datetime,
+)
+from .errors import (
+    AuthenticationError,
+    ConfigurationError,
+    DirectoryCreationError,
+    ErrorCategory,
+    ErrorSeverity,
+    ExportError,
+    FileLockError,
+    FileOperationError,
+    FileReadError,
+    FileWriteError,
+    GitHubAPIError,
+    GitOperationError,
+    IssueNotFoundError,
+    MilestoneNotFoundError,
+    NetworkError,
+    ParseError,
+    PathValidationError,
+    PersistenceError,
+    RoadmapError,
+    SecurityError,
+    StateError,
+    ValidationError,
+)
+from .logging import (
+    configure_for_testing,
+    get_logger,
+    get_security_logger,
+    log_operation,
+    setup_logging,
+)
+from .progress import ProgressCalculationEngine, ProgressEventSystem
+from .security import (
+    cleanup_old_backups,
+    create_secure_directory,
+    create_secure_file,
+    create_secure_temp_file,
+    log_security_event,
+    sanitize_filename,
+    secure_file_permissions,
+    validate_export_size,
+    validate_path,
+)
+from .services import (
+    API_RETRY,
+    DATABASE_RETRY,
+    NETWORK_RETRY,
+    MetricsCollector,
+    OperationMetric,
+    OperationTimer,
+    RetryConfig,
+    async_retry,
+    async_timed_operation,
+    get_metrics_collector,
+    retry,
+    timed_operation,
+)
+from .utils import (
+    SecureFileManager,
+    TimezoneManager,
+    backup_file,
+    cleanup_temp_files,
+    ensure_directory_exists,
+    ensure_timezone_aware,
+    file_exists_check,
+    format_datetime,
+    format_relative_time,
+    get_file_size,
+    get_timezone_manager,
+    migrate_naive_datetime,
+    now_local,
+    now_utc,
+    safe_read_file,
+    safe_write_file,
+)
+from .validation import (
+    FieldValidator,
+    RoadmapValidator,
+    SchemaValidator,
+    ValidationResult,
+    ValidationType,
+    default_validator,
+    validate_and_raise,
+    validate_frontmatter_structure,
+)
+
+__all__ = [
+    # DateTime parsing
+    "UnifiedDateTimeParser",
+    "parse_datetime",
+    "parse_file_datetime",
+    "parse_github_datetime",
+    "parse_user_datetime",
+    # Timezone utilities
+    "TimezoneManager",
+    "get_timezone_manager",
+    "now_utc",
+    "now_local",
+    "ensure_timezone_aware",
+    "migrate_naive_datetime",
+    "format_datetime",
+    "format_relative_time",
+    # Validation
+    "ValidationType",
+    "ValidationResult",
+    "FieldValidator",
+    "SchemaValidator",
+    "RoadmapValidator",
+    "default_validator",
+    "validate_and_raise",
+    "validate_frontmatter_structure",
+    # File utilities
+    "SecureFileManager",
+    "backup_file",
+    "cleanup_temp_files",
+    "ensure_directory_exists",
+    "file_exists_check",
+    "get_file_size",
+    "safe_read_file",
+    "safe_write_file",
+    # Security utilities
+    "cleanup_old_backups",
+    "create_secure_directory",
+    "create_secure_file",
+    "create_secure_temp_file",
+    "log_security_event",
+    "sanitize_filename",
+    "secure_file_permissions",
+    "validate_export_size",
+    "validate_path",
+    # Logging
+    "setup_logging",
+    "get_logger",
+    "get_security_logger",
+    "configure_for_testing",
+    # Progress
+    "ProgressCalculationEngine",
+    "ProgressEventSystem",
+    # Errors
+    "RoadmapError",
+    "FileOperationError",
+    "ValidationError",
+    "NetworkError",
+    "GitOperationError",
+    "ConfigurationError",
+    "ErrorSeverity",
+    "ErrorCategory",
+    # Constants and enums
+    "Priority",
+    "Status",
+    "MilestoneStatus",
+    "ProjectStatus",
+    "RiskLevel",
+    "IssueType",
+    # Configuration defaults
+    "DEFAULT_ROADMAP_FILE",
+    "DEFAULT_CONFIG_FILE",
+    "DEFAULT_DATA_DIR",
+    "DEFAULT_CACHE_FILE",
+    "GITHUB_API_BASE",
+    "GITHUB_GRAPHQL_ENDPOINT",
+    "GITHUB_API_TIMEOUT",
+    "GITHUB_RATE_LIMIT_THRESHOLD",
+    "DEFAULT_TABLE_WIDTH",
+    "DEFAULT_MAX_ITEMS_DISPLAY",
+    "DEFAULT_DATE_FORMAT",
+    "DEFAULT_DATETIME_FORMAT",
+    "CACHE_TTL_DEFAULT",
+    "CACHE_TTL_LONG",
+    "CACHE_TTL_SHORT",
+    "DEFAULT_BATCH_SIZE",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_RETRY_DELAY",
+    "DEFAULT_BACKOFF_FACTOR",
+    "PROGRESS_REFRESH_INTERVAL",
+    "PROGRESS_BAR_LENGTH",
+    "LOG_LEVEL_DEFAULT",
+    "LOG_FORMAT_DEFAULT",
+    "ERROR_MESSAGE_MAX_LENGTH",
+    "VALIDATION_ERROR_MAX_FIELDS",
+    "AUTH_TOKEN_ENV_VAR",
+    "AUTH_TIMEOUT",
+    "GIT_TIMEOUT",
+    "GIT_MAX_OUTPUT_LINES",
+    "GIT_COMMIT_MESSAGE_MAX_LENGTH",
+    "ANALYSIS_MIN_SAMPLE_SIZE",
+    "ANALYSIS_MAX_HISTORICAL_DAYS",
+    "ANALYSIS_TREND_WINDOW",
+    "PERFORMANCE_ENABLE_CACHE",
+    "PERFORMANCE_ENABLE_ASYNC",
+    "PERFORMANCE_THREAD_POOL_SIZE",
+    "PERFORMANCE_CONNECTION_POOL_SIZE",
+    "VALIDATION_TITLE_MIN_LENGTH",
+    "VALIDATION_TITLE_MAX_LENGTH",
+    "VALIDATION_NAME_PATTERN",
+    # Error types
+    "AuthenticationError",
+    "DirectoryCreationError",
+    "ExportError",
+    "FileLockError",
+    "FileReadError",
+    "FileWriteError",
+    "GitHubAPIError",
+    "IssueNotFoundError",
+    "MilestoneNotFoundError",
+    "ParseError",
+    "PathValidationError",
+    "PersistenceError",
+    "SecurityError",
+    "StateError",
+    # Logging operations
+    "log_operation",
+    # Metrics
+    "MetricsCollector",
+    "OperationMetric",
+    "get_metrics_collector",
+    # Performance
+    "OperationTimer",
+    "async_timed_operation",
+    "timed_operation",
+    # Retry
+    "API_RETRY",
+    "DATABASE_RETRY",
+    "NETWORK_RETRY",
+    "RetryConfig",
+    "async_retry",
+    "retry",
+]

roadmap/common/cache.py

@@ -0,0 +1,209 @@
+"""Session-level caching for performance optimization.
+
+This module provides a thread-safe cache for storing results during a single
+command execution. The cache is designed to be cleared between commands to
+ensure data freshness while reducing redundant operations.
+"""
+
+import time
+from threading import Lock
+from typing import Any, TypeVar
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+class SessionCache:
+    """Thread-safe cache for session-level (single command) data.
+
+    This cache stores results with optional TTL (time-to-live) to balance
+    performance with data freshness. It's intended to be used within a
+    single command execution and cleared afterward.
+
+    Example:
+        cache = SessionCache()
+        cache.set("team_members", members, ttl=60)
+        result = cache.get("team_members")  # Returns cached value if not expired
+
+    Attributes:
+        _cache: Dictionary mapping cache keys to (value, timestamp) tuples
+        _ttl: Dictionary mapping cache keys to their TTL in seconds
+        _lock: Thread lock for concurrent access safety
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty cache with no stored values."""
+        self._cache: dict[str, tuple[Any, float]] = {}
+        self._ttl: dict[str, float] = {}
+        self._lock = Lock()
+        logger.debug("session_cache_initialized")
+
+    def get(self, key: str) -> Any | None:
+        """Retrieve a value from cache if it exists and hasn't expired.
+
+        Args:
+            key: The cache key to retrieve
+
+        Returns:
+            The cached value if found and not expired, None otherwise
+
+        Example:
+            value = cache.get("issues")
+            if value is not None:
+                # Use cached value
+                print(value)
+        """
+        with self._lock:
+            if key not in self._cache:
+                logger.debug("cache_miss", key=key)
+                return None
+
+            value, timestamp = self._cache[key]
+            ttl = self._ttl.get(key, float("inf"))
+
+            # Check if cached value has expired
+            if time.time() - timestamp > ttl:
+                logger.debug("cache_expired", key=key)
+                del self._cache[key]
+                if key in self._ttl:
+                    del self._ttl[key]
+                return None
+
+            logger.debug("cache_hit", key=key)
+            return value
+
+    def set(self, key: str, value: Any, ttl: float = float("inf")) -> None:
+        """Store a value in cache with optional TTL.
+
+        Args:
+            key: The cache key to store under
+            value: The value to cache
+            ttl: Time-to-live in seconds (default: infinite)
+
+        Example:
+            cache.set("team_members", members, ttl=60)  # Expires after 60s
+            cache.set("config", config)  # Never expires
+        """
+        with self._lock:
+            self._cache[key] = (value, time.time())
+            self._ttl[key] = ttl
+            logger.debug("cache_set", key=key, ttl=ttl)
+
+    def clear(self) -> None:
+        """Clear all cached values.
+
+        Use this at the end of a command to reset for the next execution.
+
+        Example:
+            # After command completes
+            cache.clear()
+        """
+        with self._lock:
+            count = len(self._cache)
+            self._cache.clear()
+            self._ttl.clear()
+            logger.debug("cache_cleared", entries_cleared=count)
+
+    def invalidate(self, key: str) -> None:
+        """Remove a specific key from cache.
+
+        Useful for invalidating stale data without clearing entire cache.
+
+        Args:
+            key: The cache key to remove
+
+        Example:
+            cache.invalidate("team_members")  # Force refresh on next access
+        """
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                if key in self._ttl:
+                    del self._ttl[key]
+                logger.debug("cache_invalidated", key=key)
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get current cache statistics.
+
+        Returns:
+            Dictionary with cache metrics:
+                - entries: Number of cached items
+                - keys: List of all cache keys
+
+        Example:
+            stats = cache.get_stats()
+            print(f"Cached {stats['entries']} items")
+        """
+        with self._lock:
+            return {
+                "entries": len(self._cache),
+                "keys": list(self._cache.keys()),
+            }
+
+
+# Global session cache instance
+_session_cache = SessionCache()
+
+
+def get_session_cache() -> SessionCache:
+    """Get the global session cache instance.
+
+    Returns:
+        The singleton SessionCache instance
+
+    Example:
+        cache = get_session_cache()
+        cache.set("data", value)
+    """
+    return _session_cache
+
+
+def clear_session_cache() -> None:
+    """Clear the global session cache.
+
+    Call this at the beginning of each command execution to ensure
+    a clean slate while allowing intra-command caching benefits.
+
+    Example:
+        # In CLI command entry point
+        clear_session_cache()
+        # ... run command
+    """
+    _session_cache.clear()
+
+
+def cache_result(key: str, ttl: float = float("inf")):
+    """Cache function results in session cache.
+
+    Args:
+        key: The cache key to use (can contain {arg_name} placeholders)
+        ttl: Time-to-live in seconds
+
+    Example:
+        @cache_result("team_members", ttl=60)
+        def get_team_members() -> list[str]:
+            # ... fetch from API
+            return members
+
+        # Second call within 60s returns cached result
+        members = get_team_members()
+    """
+
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            # Try to get from cache first
+            cached = get_session_cache().get(key)
+            if cached is not None:
+                return cached
+
+            # Call function and cache result
+            result = func(*args, **kwargs)
+            get_session_cache().set(key, result, ttl=ttl)
+            return result
+
+        return wrapper
+
+    return decorator

roadmap/common/cli_errors.py

@@ -0,0 +1,147 @@
+"""Unified error handling for CLI commands.
+
+Provides consistent error handling, logging, and user feedback across all CLI commands.
+"""
+
+import functools
+import sys
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+import click
+
+from roadmap.common.console import get_console
+from roadmap.common.logging import (
+    clear_correlation_id,
+    get_logger,
+    set_correlation_id,
+)
+
+logger = get_logger(__name__)
+console = get_console()
+
+# Type variable for decorator
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def handle_cli_errors(
+    command_name: str | None = None, show_traceback: bool = False, log_args: bool = True
+) -> Callable[[F], F]:
+    """Add unified error handling to CLI commands with timing and correlation tracking.
+
+    Args:
+        command_name: Name of the command (for logging)
+        show_traceback: Whether to show full traceback on errors
+        log_args: Whether to log function arguments (filtered to remove sensitive data)
+
+    Example:
+        @click.command()
+        @handle_cli_errors(command_name="issue create")
+        def create_issue(...):
+            # Your command logic here
+            pass
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            cmd_name = command_name or func.__name__
+            start_time = time.perf_counter()
+
+            # Set correlation ID for this command invocation
+            correlation_id = set_correlation_id()
+
+            # Filter sensitive data from arguments
+            if log_args:
+                filtered_kwargs = {
+                    k: "***REDACTED***"
+                    if any(s in k.lower() for s in ["token", "password", "secret"])
+                    else v
+                    for k, v in kwargs.items()
+                }
+                logger.info(
+                    "command_invoked",
+                    operation=cmd_name,
+                    correlation_id=correlation_id,
+                    args=filtered_kwargs,
+                )
+            else:
+                logger.info(
+                    "command_invoked",
+                    operation=cmd_name,
+                    correlation_id=correlation_id,
+                )
+
+            try:
+                result = func(*args, **kwargs)
+
+                # Log successful completion with timing
+                duration = time.perf_counter() - start_time
+                logger.info(
+                    "command_completed",
+                    operation=cmd_name,
+                    correlation_id=correlation_id,
+                    duration_ms=round(duration * 1000, 2),
+                    success=True,
+                )
+
+                return result
+
+            except KeyboardInterrupt:
+                duration = time.perf_counter() - start_time
+                logger.warning(
+                    "Operation cancelled by user",
+                    operation=cmd_name,
+                    correlation_id=correlation_id,
+                    duration_ms=round(duration * 1000, 2),
+                )
+                console.print("\n[yellow]⚠️  Operation cancelled by user[/yellow]")
+                sys.exit(130)
+
+            except click.Abort:
+                # Already handled, just re-raise
+                raise
+
+            except Exception as e:
+                duration = time.perf_counter() - start_time
+                logger.error(
+                    "command_failed",
+                    operation=cmd_name,
+                    correlation_id=correlation_id,
+                    duration_ms=round(duration * 1000, 2),
+                    error_type=type(e).__name__,
+                    error_message=str(e),
+                )
+                if show_traceback:
+                    console.print(f"\n[red]❌ Error: {e}[/red]")
+                    import traceback
+
+                    console.print(f"[dim]{traceback.format_exc()}[/dim]")
+                raise
+
+            finally:
+                # Clear correlation ID after command completes
+                clear_correlation_id()
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
+def validate_required_args(**kwargs: Any) -> None:
+    """Validate that required arguments are provided.
+
+    Args:
+        **kwargs: Dictionary of argument names and values to validate
+
+    Raises:
+        click.UsageError: If any required argument is missing
+
+    Example:
+        validate_required_args(title=title, assignee=assignee)
+    """
+    missing = [name for name, value in kwargs.items() if value is None or value == ""]
+    if missing:
+        missing_args = ", ".join(f"--{name.replace('_', '-')}" for name in missing)
+        raise click.UsageError(f"Missing required arguments: {missing_args}")

roadmap/common/configuration/__init__.py

@@ -0,0 +1,33 @@
+"""Configuration management utilities."""
+
+# Import Pydantic configuration models for backward compatibility
+from roadmap.common.models.config_models import (  # noqa: F401
+    ExportConfig,
+    GitConfig,
+    OutputConfig,
+)
+
+from .config_loader import ConfigLoader  # noqa: F401
+from .config_manager import ConfigManager  # noqa: F401
+from .config_schema import (  # noqa: F401
+    BehaviorConfig,
+    DisplayConfig,
+    GitHubConfig,
+    PathsConfig,
+    RoadmapConfig,
+    UserConfig,
+)
+
+__all__ = [
+    "ConfigLoader",
+    "ConfigManager",
+    "RoadmapConfig",
+    "BehaviorConfig",
+    "DisplayConfig",
+    "GitHubConfig",
+    "PathsConfig",
+    "UserConfig",
+    "ExportConfig",
+    "OutputConfig",
+    "GitConfig",
+]