roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/datetime_parser.py

@@ -0,0 +1,319 @@
+"""Unified DateTime Parser for Roadmap CLI.
+
+This module provides a single source of truth for all datetime parsing operations
+across the roadmap CLI, eliminating duplication and ensuring consistent behavior.
+"""
+
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+from structlog import get_logger
+
+# Import timezone utilities
+from .utils.timezone_utils import (
+    ensure_timezone_aware,
+    get_timezone_manager,
+)
+
+logger = get_logger()
+
+
+class UnifiedDateTimeParser:
+    """Single source of truth for all datetime parsing in roadmap CLI."""
+
+    # Common datetime format patterns for parsing
+    DATETIME_FORMATS = [
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%d %H:%M",
+        "%Y-%m-%d",
+        "%m/%d/%Y %H:%M:%S",
+        "%m/%d/%Y %H:%M",
+        "%m/%d/%Y",
+        "%d/%m/%Y %H:%M:%S",
+        "%d/%m/%Y %H:%M",
+        "%d/%m/%Y",
+        "%Y/%m/%d %H:%M:%S",
+        "%Y/%m/%d %H:%M",
+        "%Y/%m/%d",
+    ]
+
+    @classmethod
+    def _handle_datetime_object(
+        cls, value: datetime, assumed_timezone: str | None
+    ) -> datetime:
+        """Handle datetime object input (ensure timezone awareness).
+
+        Args:
+            value: Datetime object
+            assumed_timezone: Timezone to assume for naive datetimes
+
+        Returns:
+            Timezone-aware datetime in UTC
+        """
+        return ensure_timezone_aware(value, assumed_timezone or "UTC")
+
+    @classmethod
+    def _normalize_string_value(cls, value: str) -> str | None:
+        """Normalize string input for parsing.
+
+        Args:
+            value: String value to normalize
+
+        Returns:
+            Normalized string or None if empty
+        """
+        if not isinstance(value, str):
+            value = str(value)
+        value = value.strip()
+        return value if value else None
+
+    @classmethod
+    def _route_to_specialized_parser(
+        cls, value: str, source_type: str, assumed_timezone: str | None
+    ) -> datetime | None:
+        """Route value to appropriate specialized parser based on type and format.
+
+        Args:
+            value: String value to parse
+            source_type: Hint for parsing behavior
+            assumed_timezone: Timezone to assume for naive datetimes
+
+        Returns:
+            Parsed datetime or None
+        """
+        if source_type == "github" or cls._is_github_format(value):
+            return cls.parse_github_timestamp(value)
+        elif source_type == "iso" or cls._is_iso_format(value):
+            return cls.parse_iso_datetime(value, assumed_timezone)
+        elif source_type == "file":
+            return cls.parse_file_datetime(value, assumed_timezone)
+        else:
+            return cls.parse_user_datetime(value, assumed_timezone)
+
+    @classmethod
+    def parse_any_datetime(
+        cls, value: Any, source_type: str = "user", assumed_timezone: str | None = None
+    ) -> datetime | None:
+        """Universal datetime parser for all roadmap CLI needs.
+
+        This is the primary entry point for datetime parsing. It handles:
+        - String datetime values in various formats
+        - Existing datetime objects (ensures timezone awareness)
+        - None values (returns None)
+        - GitHub API timestamps (Z suffix)
+        - File frontmatter datetimes
+        - User input in multiple formats
+
+        Args:
+            value: Any datetime-like value (string, datetime, None)
+            source_type: Hint for parsing behavior ("user", "github", "file", "iso")
+            assumed_timezone: Timezone to assume for naive datetimes
+
+        Returns:
+            Timezone-aware datetime in UTC, or None if value is None/invalid
+        """
+        if value is None:
+            return None
+
+        if isinstance(value, datetime):
+            return cls._handle_datetime_object(value, assumed_timezone)
+
+        # Normalize string value
+        normalized = cls._normalize_string_value(value)
+        if not normalized:
+            return None
+
+        # Route to specialized parser
+        return cls._route_to_specialized_parser(
+            normalized, source_type, assumed_timezone
+        )
+
+    @classmethod
+    def parse_github_timestamp(cls, github_timestamp: str) -> datetime:
+        """Specialized GitHub API timestamp parsing.
+
+        Handles GitHub's ISO format timestamps which typically end with 'Z' (UTC).
+        Also handles malformed test timestamps with mixed timezone formats.
+
+        Args:
+            github_timestamp: GitHub API timestamp string
+
+        Returns:
+            Timezone-aware datetime in UTC
+
+        Raises:
+            ValueError: If timestamp cannot be parsed
+        """
+        if not github_timestamp:
+            return datetime.min.replace(tzinfo=UTC)
+
+        # Handle malformed timestamps from tests (e.g., "2025-01-01T00:00:00+00:00Z")
+        if github_timestamp.endswith("Z") and "+00:00" in github_timestamp:
+            # Remove the trailing Z if there's already timezone info
+            github_timestamp = github_timestamp[:-1]
+        elif github_timestamp.endswith("Z"):
+            # Standard GitHub API format: replace Z with +00:00
+            github_timestamp = github_timestamp.replace("Z", "+00:00")
+
+        try:
+            # Parse the timestamp and ensure it's in UTC
+            dt = datetime.fromisoformat(github_timestamp)
+            return ensure_timezone_aware(dt, "UTC")
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid GitHub timestamp format: {github_timestamp}"
+            ) from e
+
+    @classmethod
+    def parse_file_datetime(
+        cls, value: str, assumed_timezone: str | None = None
+    ) -> datetime | None:
+        """Parse datetime from markdown frontmatter or file content.
+
+        Args:
+            value: Datetime string from file
+            assumed_timezone: Timezone to assume for naive datetimes
+
+        Returns:
+            Timezone-aware datetime in UTC, or None if invalid
+        """
+        if not value or not isinstance(value, str):
+            return None
+
+        value = value.strip()
+        if not value:
+            return None
+
+        # Try ISO format first (most common in files)
+        if cls._is_iso_format(value):
+            return cls.parse_iso_datetime(value, assumed_timezone)
+
+        # Try other common formats
+        return cls._parse_with_formats(value, cls.DATETIME_FORMATS, assumed_timezone)
+
+    @classmethod
+    def parse_user_datetime(
+        cls, value: str, assumed_timezone: str | None = None
+    ) -> datetime | None:
+        """Parse datetime from user input with flexible format support.
+
+        Args:
+            value: User input datetime string
+            assumed_timezone: Timezone to assume for naive datetimes
+
+        Returns:
+            Timezone-aware datetime in UTC, or None if invalid
+        """
+        if not value or not isinstance(value, str):
+            return None
+
+        # Use the TimezoneManager for user input parsing
+        try:
+            timezone_manager = get_timezone_manager()
+            return timezone_manager.parse_user_input(value, assumed_timezone)
+        except Exception as e:
+            logger.debug("timezone_manager_parsing_failed", value=value, error=str(e))
+            # Fallback to manual parsing
+            return cls._parse_with_formats(
+                value, cls.DATETIME_FORMATS, assumed_timezone
+            )
+
+    @classmethod
+    def parse_iso_datetime(
+        cls, value: str, assumed_timezone: str | None = None
+    ) -> datetime | None:
+        """Parse ISO format datetime string.
+
+        Args:
+            value: ISO format datetime string
+            assumed_timezone: Timezone to assume for naive datetimes
+
+        Returns:
+            Timezone-aware datetime in UTC, or None if invalid
+        """
+        if not value:
+            return None
+
+        try:
+            # Handle Z suffix (UTC indicator)
+            if value.endswith("Z"):
+                value = value.replace("Z", "+00:00")
+
+            # Parse with fromisoformat
+            dt = datetime.fromisoformat(value)
+            return ensure_timezone_aware(dt, assumed_timezone or "UTC")
+
+        except ValueError as e:
+            logger.debug("iso_datetime_parse_failed", value=value, error=str(e))
+            return None
+
+    @classmethod
+    def _is_github_format(cls, value: str) -> bool:
+        """Check if string looks like a GitHub API timestamp."""
+        return value.endswith("Z") or (
+            "T" in value and (":" in value) and ("+" in value or "Z" in value)
+        )
+
+    @classmethod
+    def _is_iso_format(cls, value: str) -> bool:
+        """Check if string looks like ISO format."""
+        iso_pattern = r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}"
+        return bool(re.match(iso_pattern, value))
+
+    @classmethod
+    def _parse_with_formats(
+        cls, value: str, formats: list, assumed_timezone: str | None = None
+    ) -> datetime | None:
+        """Try parsing with multiple datetime formats.
+
+        Args:
+            value: Datetime string to parse
+            formats: List of strptime format strings to try
+            assumed_timezone: Timezone to assume for naive datetimes
+
+        Returns:
+            Timezone-aware datetime in UTC, or None if no format works
+        """
+        for fmt in formats:
+            try:
+                dt = datetime.strptime(value, fmt)
+                return ensure_timezone_aware(dt, assumed_timezone or "UTC")
+            except ValueError as e:
+                logger.debug(
+                    "format_datetime_parse_failed",
+                    value=value,
+                    format=fmt,
+                    error=str(e),
+                )
+                continue
+        return None
+
+
+# Convenience functions for backward compatibility and ease of use
+def parse_datetime(
+    value: Any, source_type: str = "user", assumed_timezone: str | None = None
+) -> datetime | None:
+    """Parse datetime from various input formats."""
+    return UnifiedDateTimeParser.parse_any_datetime(
+        value, source_type, assumed_timezone
+    )
+
+
+def parse_github_datetime(github_timestamp: str) -> datetime:
+    """Parse GitHub timestamp format."""
+    return UnifiedDateTimeParser.parse_github_timestamp(github_timestamp)
+
+
+def parse_file_datetime(
+    value: str, assumed_timezone: str | None = None
+) -> datetime | None:
+    """Parse datetime from file path format."""
+    return UnifiedDateTimeParser.parse_file_datetime(value, assumed_timezone)
+
+
+def parse_user_datetime(
+    value: str, assumed_timezone: str | None = None
+) -> datetime | None:
+    """Parse user-input datetime string."""
+    return UnifiedDateTimeParser.parse_user_datetime(value, assumed_timezone)

roadmap/common/error_formatter.py

@@ -0,0 +1,84 @@
+"""Error formatting utilities for CLI output.
+
+Provides consistent error message formatting for both plain and rich output modes.
+"""
+
+from roadmap.common.console import is_plain_mode
+from roadmap.common.errors.exceptions import RoadmapException
+
+
+def format_error_message(exc: RoadmapException | Exception) -> str:
+    """Format an exception for user-friendly CLI output.
+
+    For RoadmapException: Uses user_message with appropriate styling
+    For other exceptions: Uses generic fallback message
+
+    Args:
+        exc: Exception to format
+
+    Returns:
+        Formatted error message suitable for stderr output
+    """
+    plain = is_plain_mode()
+
+    if isinstance(exc, RoadmapException):
+        message = exc.user_message
+    else:
+        message = str(exc)
+
+    # Add prefix based on mode
+    if plain:
+        return f"[ERROR] {message}"
+    else:
+        return f"❌ {message}"
+
+
+def format_warning_message(message: str) -> str:
+    """Format a warning message for CLI output.
+
+    Args:
+        message: Warning message text
+
+    Returns:
+        Formatted warning message
+    """
+    plain = is_plain_mode()
+
+    if plain:
+        return f"[WARN] {message}"
+    else:
+        return f"⚠️  {message}"
+
+
+def format_info_message(message: str) -> str:
+    """Format an info message for CLI output.
+
+    Args:
+        message: Info message text
+
+    Returns:
+        Formatted info message
+    """
+    plain = is_plain_mode()
+
+    if plain:
+        return f"[INFO] {message}"
+    else:
+        return f"ℹ️  {message}"
+
+
+def format_success_message(message: str) -> str:
+    """Format a success message for CLI output.
+
+    Args:
+        message: Success message text
+
+    Returns:
+        Formatted success message
+    """
+    plain = is_plain_mode()
+
+    if plain:
+        return f"[OK] {message}"
+    else:
+        return f"✅ {message}"

roadmap/common/errors/__init__.py

@@ -0,0 +1,143 @@
+"""Error handling and exception definitions for Roadmap.
+
+This package provides organized error classes, categorized by concern:
+- exceptions: High-level exceptions with domain and user messages (NEW)
+- error_base: Core exception classes and enums
+- error_file: File and I/O related errors
+- error_validation: Data validation errors
+- error_network: Network and GitHub API errors
+- error_git: Git operation errors and configuration errors
+- error_security: Security and parsing errors
+- error_handler: Error handling utilities
+- error_standards: Standardized error handling decorators and context managers (NEW)
+"""
+
+# Legacy error hierarchy (backwards compatibility)
+from roadmap.common.errors.error_base import (
+    ErrorCategory,
+    ErrorSeverity,
+    RoadmapError,
+)
+from roadmap.common.errors.error_file import (
+    DirectoryCreationError,
+    ExportError,
+    FileLockError,
+    FileOperationError,
+    FileReadError,
+    FileWriteError,
+    ImportError,
+    PersistenceError,
+)
+from roadmap.common.errors.error_git import ConfigurationError, GitOperationError
+from roadmap.common.errors.error_handler import ErrorHandler, handle_errors
+from roadmap.common.errors.error_network import (
+    AuthenticationError,
+    GitHubAPIError,
+    NetworkError,
+)
+from roadmap.common.errors.error_security import (
+    ParseError,
+    PathValidationError,
+    SecurityError,
+)
+
+# Standardized error handling decorators and utilities
+from roadmap.common.errors.error_standards import (
+    ErrorContext,
+    OperationType,
+    RecoveryAction,
+    log_operation,
+    safe_operation,
+    with_error_handling,
+)
+from roadmap.common.errors.error_validation import (
+    IssueNotFoundError,
+    MilestoneNotFoundError,
+    StateError,
+    ValidationError,
+)
+
+# New exception hierarchy (recommended for future use)
+from roadmap.common.errors.exceptions import (
+    AlreadyInitializedError,
+    CreateError,
+    DatabaseError,
+    DeleteError,
+    EntityNotFoundError,
+    GitConfigError,
+    GitError,
+    GitHubError,
+    InvalidPriorityError,
+    InvalidStatusError,
+    NoGitRepositoryError,
+    NotInitializedError,
+    OperationError,
+    ProjectNotFoundError,
+    RoadmapException,
+    UpdateError,
+)
+from roadmap.common.errors.exceptions import (
+    IssueNotFoundError as NewIssueNotFoundError,
+)
+from roadmap.common.errors.exceptions import (
+    MilestoneNotFoundError as NewMilestoneNotFoundError,
+)
+from roadmap.common.errors.exceptions import (
+    ValidationError as NewValidationError,
+)
+
+__all__ = [
+    # Legacy (backwards compatibility)
+    "ErrorSeverity",
+    "ErrorCategory",
+    "RoadmapError",
+    "FileOperationError",
+    "DirectoryCreationError",
+    "FileReadError",
+    "FileWriteError",
+    "ExportError",
+    "ImportError",
+    "PersistenceError",
+    "FileLockError",
+    "ValidationError",
+    "NetworkError",
+    "AuthenticationError",
+    "GitHubAPIError",
+    "GitOperationError",
+    "SecurityError",
+    "PathValidationError",
+    "ParseError",
+    "ErrorHandler",
+    "handle_errors",
+    "StateError",
+    "IssueNotFoundError",
+    "MilestoneNotFoundError",
+    "ConfigurationError",
+    # New exceptions (recommended)
+    "RoadmapException",
+    "NotInitializedError",
+    "AlreadyInitializedError",
+    "EntityNotFoundError",
+    "NewIssueNotFoundError",
+    "NewMilestoneNotFoundError",
+    "ProjectNotFoundError",
+    "NewValidationError",
+    "InvalidStatusError",
+    "InvalidPriorityError",
+    "OperationError",
+    "CreateError",
+    "UpdateError",
+    "DeleteError",
+    "DatabaseError",
+    "GitError",
+    "GitHubError",
+    "GitConfigError",
+    "NoGitRepositoryError",
+    # Standardized error handling decorators and utilities
+    "safe_operation",
+    "log_operation",
+    "with_error_handling",
+    "ErrorContext",
+    "OperationType",
+    "RecoveryAction",
+]

roadmap/common/errors/error_base.py

@@ -0,0 +1,73 @@
+"""Base error classes and enums for Roadmap."""
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorSeverity(Enum):
+    """Error severity levels for consistent classification."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class ErrorCategory(Enum):
+    """Error categories for better organization and handling."""
+
+    FILE_OPERATION = "file_operation"
+    VALIDATION = "validation"
+    NETWORK = "network"
+    GIT_OPERATION = "git_operation"
+    GITHUB_API = "github_api"
+    PARSING = "parsing"
+    CONFIGURATION = "configuration"
+    PERMISSION = "permission"
+    DEPENDENCY = "dependency"
+    USER_INPUT = "user_input"
+
+
+class RoadmapError(Exception):
+    """Base exception for all roadmap-specific errors."""
+
+    def __init__(
+        self,
+        message: str,
+        severity: ErrorSeverity = ErrorSeverity.MEDIUM,
+        category: ErrorCategory = ErrorCategory.VALIDATION,
+        context: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+    ):
+        """Initialize RoadmapError.
+
+        Args:
+            message: Error message.
+            severity: Error severity level.
+            category: Error category.
+            context: Additional context dictionary.
+            cause: Underlying exception that caused this error.
+        """
+        super().__init__(message)
+        self.message = message
+        self.severity = severity
+        self.category = category
+        self.context = context or {}
+        self.cause = cause
+
+    def __str__(self) -> str:
+        """Return string representation of error."""
+        return self.message
+
+    def get_context_info(self) -> str:
+        """Get formatted context information."""
+        if not self.context:
+            return ""
+
+        context_parts = []
+        for key, value in self.context.items():
+            context_parts.append(f"{key}: {value}")
+
+        return f" ({', '.join(context_parts)})"

roadmap/common/errors/error_file.py

@@ -0,0 +1,82 @@
+"""File and I/O related error classes."""
+
+from pathlib import Path
+
+from roadmap.common.errors.error_base import ErrorCategory, ErrorSeverity, RoadmapError
+
+
+class FileOperationError(RoadmapError):
+    """Errors related to file operations."""
+
+    def __init__(
+        self,
+        message: str,
+        file_path: Path | None = None,
+        operation: str | None = None,
+        **kwargs,
+    ):
+        """Initialize FileOperationError.
+
+        Args:
+            message: Error message.
+            file_path: Path to the file involved in the error.
+            operation: Name of the file operation that failed.
+            **kwargs: Additional arguments passed to parent class.
+        """
+        context = kwargs.get("context", {})
+        if file_path:
+            context["file_path"] = str(file_path)
+        if operation:
+            context["operation"] = operation
+
+        super().__init__(
+            message,
+            severity=kwargs.get("severity", ErrorSeverity.HIGH),
+            category=ErrorCategory.FILE_OPERATION,
+            context=context,
+            cause=kwargs.get("cause"),
+        )
+        self.file_path = file_path
+        self.operation = operation
+
+
+class PersistenceError(FileOperationError):
+    """Raised when database or file persistence operations fail."""
+
+    pass
+
+
+class FileLockError(FileOperationError):
+    """Raised when file locking operations fail."""
+
+    pass
+
+
+class DirectoryCreationError(FileOperationError):
+    """Raised when directory creation fails."""
+
+    pass
+
+
+class FileReadError(FileOperationError):
+    """Raised when file reading fails."""
+
+    pass
+
+
+class FileWriteError(FileOperationError):
+    """Raised when file writing fails."""
+
+    pass
+
+
+class ExportError(FileOperationError):
+    """Raised when data export fails."""
+
+    pass
+
+
+class ImportError(FileOperationError):
+    """Raised when data import fails."""
+
+    pass