roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/errors/exceptions.py

@@ -0,0 +1,432 @@
+"""Roadmap exception hierarchy.
+
+All exceptions include:
+- domain_message: Technical message for logging
+- user_message: User-friendly message for CLI output
+- exit_code: CLI exit code (for Click commands)
+
+This separation allows logging the full technical context while showing
+users a clean, actionable message.
+
+Example:
+    try:
+        service.create_issue(...)
+    except NotInitializedError as e:
+        logger.error(e.domain_message)  # Technical details
+        click.echo(e.user_message, err=True)  # What user sees
+        ctx.exit(e.exit_code)
+"""
+
+
+class RoadmapException(Exception):
+    """Base exception for all roadmap errors.
+
+    Attributes:
+        domain_message: Technical message for logging/debugging
+        user_message: User-friendly message for CLI output
+        exit_code: Exit code for CLI commands
+    """
+
+    exit_code: int = 1
+
+    def __init__(
+        self,
+        domain_message: str,
+        user_message: str | None = None,
+    ):
+        """Initialize exception with messages.
+
+        Args:
+            domain_message: Technical message (what happened technically)
+            user_message: User-friendly message (what user should do)
+                         Defaults to domain_message if not provided
+        """
+        self.domain_message = domain_message
+        self.user_message = user_message or domain_message
+        super().__init__(domain_message)
+
+    def __str__(self) -> str:
+        """Return user message for str()."""
+        return self.user_message
+
+
+# ============================================================================
+# Initialization & Setup Errors
+# ============================================================================
+
+
+class NotInitializedError(RoadmapException):
+    """Roadmap directory (.roadmap/) not initialized."""
+
+    exit_code = 1
+
+    def __init__(self):
+        """Initialize NotInitializedError."""
+        super().__init__(
+            domain_message="Roadmap .roadmap/ directory not found",
+            user_message="Roadmap not initialized. Run 'roadmap init' first.",
+        )
+
+
+class AlreadyInitializedError(RoadmapException):
+    """Roadmap already initialized in this directory."""
+
+    exit_code = 1
+
+    def __init__(self, directory: str):
+        """Initialize AlreadyInitializedError.
+
+        Args:
+            directory: Path where roadmap is already initialized.
+        """
+        super().__init__(
+            domain_message=f"Roadmap already initialized in {directory}",
+            user_message=f"Roadmap already initialized in {directory}/. "
+            "Use --force to reinitialize.",
+        )
+
+
+# ============================================================================
+# Entity Not Found Errors
+# ============================================================================
+
+
+class EntityNotFoundError(RoadmapException):
+    """Entity (issue, milestone, project) not found."""
+
+    exit_code = 1
+
+    def __init__(self, entity_type: str, entity_id: str):
+        """Initialize EntityNotFoundError.
+
+        Args:
+            entity_type: Type of entity (Issue, Milestone, Project).
+            entity_id: ID of the missing entity.
+        """
+        super().__init__(
+            domain_message=f"{entity_type} {entity_id} not found in database",
+            user_message=f"{entity_type} not found: {entity_id}",
+        )
+
+
+class IssueNotFoundError(EntityNotFoundError):
+    """Specific: Issue not found."""
+
+    def __init__(self, issue_id: str):
+        """Initialize IssueNotFoundError.
+
+        Args:
+            issue_id: ID of the missing issue.
+        """
+        super().__init__("Issue", issue_id)
+
+
+class MilestoneNotFoundError(EntityNotFoundError):
+    """Specific: Milestone not found."""
+
+    def __init__(self, milestone_id: str):
+        """Initialize MilestoneNotFoundError.
+
+        Args:
+            milestone_id: ID of the missing milestone.
+        """
+        super().__init__("Milestone", milestone_id)
+
+
+class ProjectNotFoundError(EntityNotFoundError):
+    """Specific: Project not found."""
+
+    def __init__(self, project_id: str):
+        """Initialize ProjectNotFoundError.
+
+        Args:
+            project_id: ID of the missing project.
+        """
+        super().__init__("Project", project_id)
+
+
+# ============================================================================
+# Validation Errors
+# ============================================================================
+
+
+class ValidationError(RoadmapException):
+    """Input validation failed."""
+
+    exit_code = 2
+
+    def __init__(self, domain_message: str, user_message: str | None = None):
+        """Initialize ValidationError.
+
+        Args:
+            domain_message: Technical message describing validation failure.
+            user_message: User-friendly message. Defaults to domain_message.
+        """
+        super().__init__(
+            domain_message=domain_message,
+            user_message=user_message or domain_message,
+        )
+
+
+class InvalidStatusError(ValidationError):
+    """Invalid status value."""
+
+    def __init__(self, status: str, valid_statuses: list[str]):
+        """Initialize InvalidStatusError.
+
+        Args:
+            status: Invalid status value provided.
+            valid_statuses: List of valid status values.
+        """
+        domain_message = f"Validation failed: status '{status}' is not valid"
+        user_message = (
+            f"Invalid status: '{status}'. Valid values: {', '.join(valid_statuses)}"
+        )
+        super().__init__(domain_message=domain_message, user_message=user_message)
+
+
+class InvalidPriorityError(ValidationError):
+    """Invalid priority value."""
+
+    def __init__(self, priority: str, valid_priorities: list[str]):
+        """Initialize InvalidPriorityError.
+
+        Args:
+            priority: Invalid priority value provided.
+            valid_priorities: List of valid priority values.
+        """
+        domain_message = f"Validation failed: priority '{priority}' is not valid"
+        user_message = f"Invalid priority: '{priority}'. Valid values: {', '.join(valid_priorities)}"
+        super().__init__(domain_message=domain_message, user_message=user_message)
+
+
+# ============================================================================
+# Operation Errors
+# ============================================================================
+
+
+class OperationError(RoadmapException):
+    """Operation failed (creation, update, deletion, etc.)."""
+
+    exit_code = 1
+
+    def __init__(self, operation: str, reason: str):
+        """Initialize OperationError.
+
+        Args:
+            operation: Description of the operation that failed.
+            reason: Reason why the operation failed.
+        """
+        super().__init__(
+            domain_message=f"Failed to {operation}: {reason}",
+            user_message=f"Failed to {operation}: {reason}",
+        )
+
+
+class CreateError(OperationError):
+    """Failed to create entity."""
+
+    def __init__(self, entity_type: str, reason: str):
+        """Initialize CreateError.
+
+        Args:
+            entity_type: Type of entity that failed to create.
+            reason: Reason for creation failure.
+        """
+        super().__init__(f"create {entity_type}", reason)
+
+
+class UpdateError(OperationError):
+    """Failed to update entity."""
+
+    def __init__(self, entity_type: str, reason: str):
+        """Initialize UpdateError.
+
+        Args:
+            entity_type: Type of entity that failed to update.
+            reason: Reason for update failure.
+        """
+        super().__init__(f"update {entity_type}", reason)
+
+
+class DeleteError(OperationError):
+    """Failed to delete entity."""
+
+    def __init__(self, entity_type: str, reason: str):
+        """Initialize DeleteError.
+
+        Args:
+            entity_type: Type of entity that failed to delete.
+            reason: Reason for deletion failure.
+        """
+        super().__init__(f"delete {entity_type}", reason)
+
+
+# ============================================================================
+# Database/Persistence Errors
+# ============================================================================
+
+
+class PersistenceError(RoadmapException):
+    """Database or file persistence operation failed."""
+
+    exit_code = 1
+
+    def __init__(self, operation: str, reason: str):
+        """Initialize PersistenceError.
+
+        Args:
+            operation: Name of the persistence operation that failed.
+            reason: Reason for failure.
+        """
+        super().__init__(
+            domain_message=f"Persistence operation '{operation}' failed: {reason}",
+            user_message="Storage operation failed. Check disk space and permissions.",
+        )
+
+
+class DatabaseError(PersistenceError):
+    """Database operation failed."""
+
+    def __init__(self, reason: str):
+        """Initialize DatabaseError.
+
+        Args:
+            reason: Reason for database operation failure.
+        """
+        super().__init__("database", reason)
+
+
+class FileOperationError(PersistenceError):
+    """File operation failed."""
+
+    def __init__(self, reason: str):
+        """Initialize FileOperationError.
+
+        Args:
+            reason: Reason for file operation failure.
+        """
+        super().__init__("file_operation", reason)
+
+
+# ============================================================================
+# Git/GitHub Errors
+# ============================================================================
+
+
+class GitError(RoadmapException):
+    """Git operation failed."""
+
+    exit_code = 1
+
+    def __init__(self, operation: str, reason: str):
+        """Initialize GitError.
+
+        Args:
+            operation: Name of the Git operation that failed.
+            reason: Reason for failure.
+        """
+        super().__init__(
+            domain_message=f"Git operation '{operation}' failed: {reason}",
+            user_message=f"Git operation failed: {reason}",
+        )
+
+
+class GitHubError(RoadmapException):
+    """GitHub integration failed."""
+
+    exit_code = 1
+
+    def __init__(self, operation: str, reason: str):
+        """Initialize GitHubError.
+
+        Args:
+            operation: Name of the GitHub operation that failed.
+            reason: Reason for failure.
+        """
+        super().__init__(
+            domain_message=f"GitHub operation '{operation}' failed: {reason}",
+            user_message=f"GitHub operation failed: {reason}",
+        )
+
+
+class NoGitRepositoryError(GitError):
+    """Not in a Git repository."""
+
+    def __init__(self):
+        """Initialize NoGitRepositoryError."""
+        super().__init__(
+            "repository_check",
+            "Not in a Git repository",
+        )
+
+
+class GitConfigError(GitError):
+    """Git configuration missing or invalid."""
+
+    def __init__(self, config_key: str):
+        """Initialize GitConfigError.
+
+        Args:
+            config_key: Name of the missing Git configuration key.
+        """
+        super().__init__(
+            "config_read",
+            f"Git config '{config_key}' not found. Run: git config user.name 'Your Name'",
+        )
+
+
+# ============================================================================
+# Configuration/Setup Errors
+# ============================================================================
+
+
+class ConfigurationError(RoadmapException):
+    """Configuration is invalid or missing."""
+
+    exit_code = 1
+
+    def __init__(self, issue: str):
+        """Initialize ConfigurationError.
+
+        Args:
+            issue: Description of the configuration problem.
+        """
+        super().__init__(
+            domain_message=f"Configuration error: {issue}",
+            user_message=f"Configuration error: {issue}",
+        )
+
+
+# ============================================================================
+# Security Errors
+# ============================================================================
+
+
+class SecurityError(RoadmapException):
+    """Security validation failed."""
+
+    exit_code = 1
+
+    def __init__(self, issue: str):
+        """Initialize SecurityError.
+
+        Args:
+            issue: Description of the security check failure.
+        """
+        super().__init__(
+            domain_message=f"Security check failed: {issue}",
+            user_message="Security validation failed. Check file permissions.",
+        )
+
+
+class PathValidationError(SecurityError):
+    """Path traversal or invalid path detected."""
+
+    def __init__(self, path: str):
+        """Initialize PathValidationError.
+
+        Args:
+            path: The invalid path that failed validation.
+        """
+        super().__init__(f"Invalid path: {path}")

roadmap/common/formatters/__init__.py

@@ -0,0 +1,29 @@
+"""Formatters package - unified formatting utilities.
+
+Organized into focused modules:
+- text: Basic text, duration, status, operation formatting
+- output: Generic TableData rendering (JSON, CSV, Markdown, plain-text)
+- tables: Domain object to TableData conversion (Issue, Milestone, Project)
+- export: Issue export with multiple format support
+- kanban: Kanban board organization and layout
+
+Use submodule imports for clarity:
+  from roadmap.common.formatters.text import format_table, format_header
+  from roadmap.common.formatters.output import OutputFormatter
+  from roadmap.common.formatters.tables import IssueTableFormatter
+  from roadmap.common.formatters.export import IssueExporter
+  from roadmap.common.formatters.kanban import KanbanOrganizer, KanbanLayout
+"""
+
+from .export import IssueExporter
+from .kanban import KanbanLayout, KanbanOrganizer
+from .tables import IssueTableFormatter, MilestoneTableFormatter, ProjectTableFormatter
+
+__all__ = [
+    "IssueExporter",
+    "IssueTableFormatter",
+    "MilestoneTableFormatter",
+    "ProjectTableFormatter",
+    "KanbanOrganizer",
+    "KanbanLayout",
+]

roadmap/common/formatters/base_table_formatter.py

@@ -0,0 +1,96 @@
+"""Base table formatter for DRY consolidation.
+
+This module provides abstract base class for all table formatters,
+eliminating duplicate code across Issue, Project, and Milestone formatters.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from roadmap.common.console import get_console
+from roadmap.common.models import TableData
+
+
+class BaseTableFormatter[T](ABC):
+    """Abstract base class for table formatters."""
+
+    @property
+    def console(self):
+        """Get console instance dynamically for test compatibility."""
+        return get_console()
+
+    @abstractmethod
+    def create_table(self) -> Any:
+        """Create and configure the rich Table for this formatter.
+
+        Returns:
+            Configured Rich Table with columns
+        """
+        pass
+
+    @abstractmethod
+    def add_row(self, table: Any, item: T) -> None:
+        """Add a single item row to the table.
+
+        Args:
+            table: The Rich Table to add row to
+            item: The domain object to format
+        """
+        pass
+
+    @abstractmethod
+    def get_filter_description(self, items: list[T]) -> str:
+        """Get human-readable description of filtered items.
+
+        Args:
+            items: List of items being displayed
+
+        Returns:
+            Description string (e.g., "2 open issue")
+        """
+        pass
+
+    def display_items(self, items: list[T], filter_description: str = "all") -> None:
+        """Display items in a formatted table.
+
+        Args:
+            items: List of items to display
+            filter_description: Human-readable filter description
+        """
+        if not items:
+            self.console.print(
+                f"📋 No {filter_description} items found.", style="yellow"
+            )
+            self.console.print(
+                "Create one with: roadmap [command] create '[Name]'",
+                style="dim",
+            )
+            return
+
+        # Display header with filter info
+        filter_desc = self.get_filter_description(items)
+        self.console.print(f"📋 {filter_desc}", style="bold cyan")
+        self.console.print()
+
+        # Create and populate table
+        table = self.create_table()
+        for item in items:
+            self.add_row(table, item)
+
+        self.console.print(table)
+
+    @abstractmethod
+    def items_to_table_data(
+        self, items: list[T], title: str = "Items", description: str = ""
+    ) -> TableData:
+        """Convert items to TableData for structured output.
+
+        Args:
+            items: List of items to convert
+            title: Table title
+            description: Optional description
+
+        Returns:
+            TableData object for rendering in any format
+        """
+        pass

roadmap/common/formatters/export/__init__.py

@@ -0,0 +1,7 @@
+"""Export module public API."""
+
+from .issue_exporter import IssueExporter
+
+__all__ = [
+    "IssueExporter",
+]

roadmap/common/formatters/export/issue_exporter.py

@@ -0,0 +1,97 @@
+"""Issue export functionality."""
+
+import csv
+import json
+from collections.abc import Sequence
+from io import StringIO
+
+from roadmap.common.formatters.output import OutputFormatter
+from roadmap.common.formatters.tables import IssueTableFormatter
+from roadmap.core.domain import Issue
+
+
+class IssueExporter:
+    """Export issues to various formats.
+
+    Supports two export styles:
+    1. Unified export() - recommended for production use
+    2. Legacy to_json/to_csv/to_markdown - for backward compatibility
+    """
+
+    # Legacy CSV fields definition
+    CSV_FIELDS = [
+        "id",
+        "title",
+        "status",
+        "assignee",
+        "priority",
+        "estimated_hours",
+        "milestone",
+        "created",
+        "updated",
+    ]
+
+    @staticmethod
+    def export(issues: Sequence[Issue], format_type: str, title: str = "Issues") -> str:
+        """Export issues using the unified OutputFormatter.
+
+        Converts issues to TableData and uses OutputFormatter for consistent
+        rendering across all formats.
+
+        Args:
+            issues: List of Issue objects
+            format_type: One of 'json', 'csv', 'markdown'
+            title: Optional table title
+
+        Returns:
+            Formatted string ready for output
+        """
+        table_data = IssueTableFormatter.issues_to_table_data(issues, title=title)  # type: ignore
+        formatter = OutputFormatter(table_data)
+
+        if format_type == "json":
+            return formatter.to_json()
+        elif format_type == "csv":
+            return formatter.to_csv()
+        elif format_type == "markdown":
+            return formatter.to_markdown()
+        else:
+            raise ValueError(
+                f"Unknown format: {format_type}. Use 'json', 'csv', or 'markdown'."
+            )
+
+    @staticmethod
+    def to_json(issues: Sequence[Issue], serializer_func) -> str:
+        """Legacy JSON export with custom serializer (for backward compatibility)."""
+        payload = [serializer_func(i) for i in issues]
+        return json.dumps(payload, indent=2)
+
+    @classmethod
+    def to_csv(cls, issues: Sequence[Issue], serializer_func) -> str:
+        """Legacy CSV export with custom serializer (for backward compatibility)."""
+        buf = StringIO()
+        writer = csv.DictWriter(buf, fieldnames=cls.CSV_FIELDS)
+        writer.writeheader()
+        for issue in issues:
+            row = serializer_func(issue)
+            writer.writerow({f: row.get(f, "") for f in cls.CSV_FIELDS})
+        return buf.getvalue()
+
+    @staticmethod
+    def to_markdown(issues: Sequence[Issue]) -> str:
+        """Legacy Markdown export (for backward compatibility)."""
+        lines = [
+            "| id | title | status | assignee | milestone | estimated |",
+            "|---|---|---:|---|---|---:|",
+        ]
+        for i in issues:
+            est = (
+                i.estimated_time_display
+                if hasattr(i, "estimated_time_display")
+                else (i.estimated_hours or "")
+            )
+            status_val = i.status.value if hasattr(i.status, "value") else i.status
+            lines.append(
+                f"| {i.id} | {i.title} | {status_val} | {i.assignee or ''} | {i.milestone or ''} | {est} |"
+            )
+        return "\n".join(lines)

roadmap/common/formatters/helpers.py

@@ -0,0 +1,28 @@
+"""Formatting helpers - wrapper to avoid circular dependencies.
+
+This module re-exports OutputFormatHandler from cli_helpers to break
+the circular dependency between formatting and utils modules.
+"""
+
+from typing import TYPE_CHECKING
+
+# Import only for type checking to avoid circular imports
+if TYPE_CHECKING:
+    from roadmap.common.utils.cli_helpers import OutputFormatHandler, format_output
+
+
+def __getattr__(name: str):  # noqa: ANN001, ANN201
+    """Lazy load OutputFormatHandler and format_output from cli_helpers."""
+    if name == "OutputFormatHandler":
+        from roadmap.common.utils.cli_helpers import OutputFormatHandler
+
+        return OutputFormatHandler
+    elif name == "format_output":
+        from roadmap.common.utils.cli_helpers import format_output
+
+        return format_output
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
+
+
+__all__ = ["format_output", "OutputFormatHandler"]

roadmap/common/formatters/kanban/__init__.py

@@ -0,0 +1,9 @@
+"""Kanban module public API."""
+
+from .layout import KanbanLayout
+from .organizer import KanbanOrganizer
+
+__all__ = [
+    "KanbanOrganizer",
+    "KanbanLayout",
+]