roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/cli/analysis/commands.py

@@ -0,0 +1,370 @@
+"""Analysis commands for roadmap insights and reporting."""
+
+import json
+from pathlib import Path
+
+import click
+from structlog import get_logger
+
+from roadmap.common.console import get_console
+from roadmap.common.logging import verbose_output
+from roadmap.core.services.issue_helpers.issue_filters import IssueQueryService
+from roadmap.core.services.utils.critical_path_calculator import CriticalPathCalculator
+
+console = get_console()
+logger = get_logger()
+
+
+@click.group()
+def analysis():
+    """Analysis and insights commands."""
+    pass
+
+
+@analysis.command("critical-path")
+@click.option(
+    "--milestone",
+    "-m",
+    help="Analyze critical path for specific milestone only",
+)
+@click.option(
+    "--include-closed",
+    is_flag=True,
+    help="Include closed issues in analysis",
+)
+@click.option(
+    "--export",
+    type=click.Choice(["json", "csv"]),
+    help="Export format instead of displaying ASCII graph",
+)
+@click.option(
+    "--output",
+    "-o",
+    help="Output file path for export",
+)
+@click.pass_context
+@verbose_output
+def critical_path(
+    ctx: click.Context,
+    milestone: str | None,
+    include_closed: bool,
+    export: str | None,
+    output: str | None,
+):
+    """Analyze critical path of issues and dependencies.
+
+    Displays the longest dependency chain in your roadmap and identifies
+    the issues that have the most impact on project completion.
+
+    By default, shows an ASCII dependency graph with a summary of key metrics.
+    """
+    try:
+        logger.debug(
+            "Starting critical path analysis",
+            extra={
+                "milestone": milestone,
+                "include_closed": include_closed,
+                "export": export,
+            },
+        )
+
+        core = _get_core(ctx)
+        if not core or not core.is_initialized():
+            logger.warning("Roadmap not initialized", severity="operational")
+            console.print(
+                "❌ Roadmap not initialized. Run 'roadmap init' first.",
+                style="bold red",
+            )
+            return
+
+        # Load issues using query service
+        logger.debug("Loading issues from query service")
+        try:
+            query_service = IssueQueryService(core)
+            if milestone:
+                logger.debug(
+                    "filtering_issues_for_milestone",
+                    milestone=milestone,
+                )
+                issues_domain, filter_desc = query_service.get_filtered_issues(
+                    milestone=milestone
+                )
+            else:
+                logger.debug("Loading all issues")
+                issues_domain, filter_desc = query_service.get_filtered_issues()
+        except Exception as e:
+            logger.error(
+                "failed_to_load_issues",
+                error=str(e),
+                severity="operational",
+                exc_info=True,
+            )
+            console.print(f"❌ Failed to load issues: {str(e)}", style="bold red")
+            return
+
+        logger.debug(
+            "issues_loaded",
+            count=len(issues_domain),
+        )
+
+        # Filter closed issues unless explicitly included
+        if not include_closed:
+            original_count = len(issues_domain)
+            issues_domain = [i for i in issues_domain if i.status != "closed"]
+            filtered_count = original_count - len(issues_domain)
+            if filtered_count > 0:
+                logger.debug(
+                    "issues_filtered_for_status",
+                    filtered_count=filtered_count,
+                    remaining_count=len(issues_domain),
+                )
+
+        if not issues_domain:
+            logger.info(
+                "No active issues to analyze",
+                extra={"milestone": milestone, "include_closed": include_closed},
+            )
+            console.print(
+                f"ℹ️  No active issues to analyze.{f' In milestone: {milestone}' if milestone else ''}",
+                style="yellow",
+            )
+            return
+
+        # Calculate critical path
+        logger.debug(
+            "calculating_critical_path",
+            issue_count=len(issues_domain),
+        )
+        try:
+            calculator = CriticalPathCalculator()
+            result = calculator.calculate_critical_path(issues_domain)
+            logger.debug(
+                "Critical path calculation complete",
+                extra={
+                    "total_duration": result.total_duration,
+                    "critical_issues": len(result.critical_issue_ids),
+                },
+            )
+        except Exception as e:
+            logger.error(
+                "critical_path_calculation_failed",
+                error=str(e),
+                severity="operational",
+                exc_info=True,
+            )
+            console.print(
+                f"❌ Critical path calculation failed: {str(e)}", style="bold red"
+            )
+            return
+
+        # Output results
+        logger.debug(
+            "outputting_critical_path_results",
+            export_format=export or "display",
+        )
+        if export:
+            _export_critical_path(result, issues_domain, export, output)
+        else:
+            _display_critical_path(result, milestone)
+
+        logger.info("Critical path analysis completed successfully")
+
+    except Exception as e:
+        logger.error(
+            "critical_path_command_failed",
+            error=str(e),
+            severity="operational",
+            exc_info=True,
+        )
+        console.print(f"❌ Unexpected error: {str(e)}", style="bold red")
+
+
+def _get_core(ctx: click.Context):
+    """Get RoadmapCore from context.
+
+    Args:
+        ctx: Click context object
+
+    Returns:
+        RoadmapCore instance or None if not available
+    """
+    try:
+        return ctx.obj.get("core") if ctx.obj else None
+    except (AttributeError, TypeError) as e:
+        logger.warning(
+            "failed_to_get_core_from_context",
+            error=str(e),
+            severity="operational",
+        )
+        return None
+
+
+def _display_critical_path(result, milestone: str | None = None):
+    """Display critical path as ASCII graph with summary.
+
+    Args:
+        result: CriticalPathResult from calculator
+        milestone: Optional milestone name for context
+    """
+    try:
+        logger.debug("Formatting critical path for display")
+        from roadmap.adapters.cli.analysis.presenter import CriticalPathPresenter
+
+        presenter = CriticalPathPresenter()
+        output = presenter.format_critical_path(result, milestone)
+        console.print(output)
+        logger.debug("Critical path displayed successfully")
+    except Exception as e:
+        logger.error(
+            "failed_to_format_critical_path_display",
+            error=str(e),
+            severity="operational",
+            exc_info=True,
+        )
+        console.print(f"❌ Failed to format output: {str(e)}", style="bold red")
+
+
+def _export_critical_path(result, issues: list, format: str, output_path: str | None):
+    """Export critical path data to file or stdout.
+
+    Args:
+        result: CriticalPathResult from calculator
+        issues: List of Issue domain objects
+        format: Export format ('json' or 'csv')
+        output_path: Optional file path for export
+    """
+    try:
+        logger.debug(
+            "exporting_critical_path",
+            export_format=format,
+        )
+
+        if format == "json":
+            data = _format_json_export(result, issues)
+            output_str = json.dumps(data, indent=2, default=str)
+        elif format == "csv":
+            output_str = _format_csv_export(result, issues)
+        else:
+            logger.error(
+                "unsupported_export_format",
+                format=format,
+                error=None,
+                severity="config_error",
+            )
+            console.print("❌ Unsupported export format", style="bold red")
+            return
+
+        if output_path:
+            try:
+                path = Path(output_path)
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(output_str)
+                logger.info(
+                    "critical_path_exported",
+                    output_path=str(path),
+                )
+                console.print(f"✅ Exported to {path}", style="bold green")
+            except OSError as e:
+                logger.error(
+                    "failed_to_write_export_file",
+                    error=str(e),
+                    severity="operational",
+                    exc_info=True,
+                )
+                console.print(
+                    f"❌ Failed to write export file: {str(e)}", style="bold red"
+                )
+        else:
+            logger.debug("Outputting export to stdout")
+            console.print(output_str)
+
+    except Exception as e:
+        logger.error(
+            "critical_path_export_failed",
+            error=str(e),
+            severity="operational",
+            exc_info=True,
+        )
+        console.print(f"❌ Export failed: {str(e)}", style="bold red")
+
+
+def _format_json_export(result, issues: list) -> dict:
+    """Format critical path data as JSON.
+
+    Args:
+        result: CriticalPathResult from calculator
+        issues: List of Issue domain objects
+
+    Returns:
+        Dictionary with critical path and summary data
+    """
+    try:
+        logger.debug("Formatting critical path as JSON")
+        return {
+            "critical_path": [
+                {
+                    "issue_id": node.issue_id,
+                    "title": node.issue_title,
+                    "duration_hours": node.duration_hours,
+                    "is_critical": node.is_critical,
+                    "slack_time": node.slack_time,
+                }
+                for node in result.critical_path
+            ],
+            "summary": {
+                "total_duration": result.total_duration,
+                "critical_issue_count": len(result.critical_issue_ids),
+                "blocking_issues": result.blocking_issues,
+                "project_end_date": result.project_end_date.isoformat()
+                if result.project_end_date
+                else None,
+            },
+        }
+    except Exception as e:
+        logger.error(
+            "json_formatting_failed",
+            error=str(e),
+            severity="operational",
+            exc_info=True,
+        )
+        raise
+
+
+def _format_csv_export(result, issues: list) -> str:
+    """Format critical path data as CSV.
+
+    Args:
+        result: CriticalPathResult from calculator
+        issues: List of Issue domain objects
+
+    Returns:
+        CSV-formatted string
+    """
+    try:
+        logger.debug("Formatting critical path as CSV")
+        lines = [
+            "issue_id,title,duration_hours,dependencies,slack_hours,is_critical,status"
+        ]
+
+        for issue in issues:
+            deps = ",".join(issue.depends_on) if issue.depends_on else ""
+            # Find corresponding node
+            node = next(
+                (n for n in result.critical_path if n.issue_id == issue.id), None
+            )
+            slack = f"{node.slack_time:.1f}" if node else "N/A"
+            critical = "yes" if issue.id in result.critical_issue_ids else "no"
+
+            lines.append(
+                f'"{issue.id}","{issue.title}",{issue.estimated_hours or 0},"{deps}",{slack},{critical},{issue.status}'
+            )
+
+        return "\n".join(lines)
+    except Exception as e:
+        logger.error(
+            "csv_formatting_failed",
+            error=str(e),
+            severity="operational",
+            exc_info=True,
+        )
+        raise

roadmap/adapters/cli/analysis/presenter.py

@@ -0,0 +1,125 @@
+"""Presenter for critical path analysis output."""
+
+from roadmap.core.services.utils.critical_path_calculator import CriticalPathResult
+
+
+class CriticalPathPresenter:
+    """Formats critical path analysis for CLI display."""
+
+    def format_critical_path(
+        self, result: CriticalPathResult, milestone: str | None = None
+    ) -> str:
+        """Format critical path as ASCII graph with summary.
+
+        Args:
+            result: CriticalPathResult from calculator
+            milestone: Optional milestone name for context
+
+        Returns:
+            Formatted string with dependency graph and summary
+        """
+        lines = []
+
+        # Title
+        title = "🎯 Critical Path Analysis"
+        if milestone:
+            title += f" - {milestone}"
+        lines.append(f"\n{title}")
+        lines.append("=" * len(title))
+        lines.append("")
+
+        # Dependency graph
+        if result.critical_path:
+            lines.extend(self._format_dependency_graph(result.critical_path))
+        else:
+            lines.append("(No critical path - all issues independent)")
+
+        lines.append("")
+
+        # Summary
+        lines.extend(self._format_summary(result))
+
+        return "\n".join(lines)
+
+    def _format_dependency_graph(self, critical_path: list) -> list[str]:
+        """Format the critical path as an ASCII dependency graph."""
+        lines = ["📊 Critical Path (Longest Dependency Chain):", ""]
+
+        for i, node in enumerate(critical_path):
+            # Draw the node
+            prefix = "  " if i > 0 else ""
+            connector = "└─ " if i > 0 else ""
+
+            duration_str = f"{node.duration_hours:.1f}h"
+            slack_str = (
+                f"(slack: {node.slack_time:.1f}h)" if node.slack_time > 0 else ""
+            )
+
+            line = f"{prefix}{connector}{node.issue_id}: {node.issue_title[:40]:<40} [{duration_str:>6}] {slack_str}"
+            lines.append(line)
+
+            # Add vertical connector if not last
+            if i < len(critical_path) - 1:
+                lines.append("  │")
+
+        return lines
+
+    def _format_summary(self, result: CriticalPathResult) -> list[str]:
+        """Format the summary section."""
+        lines = ["📈 Summary", "─" * 50]
+
+        # Duration and count
+        lines.append(f"Total Duration:      {result.total_duration:.1f} hours")
+        if result.total_duration >= 8:
+            business_days = result.total_duration / 8.0
+            lines.append(f"                    ~{business_days:.1f} business days")
+
+        lines.append(f"Critical Issues:     {len(result.critical_issue_ids)}")
+
+        # Risk assessment
+        risk_level = self._assess_risk(result)
+        lines.append(f"Risk Level:          {risk_level}")
+
+        # Top blockers
+        if result.blocking_issues:
+            blockers = [
+                (issue_id, len(blocked))
+                for issue_id, blocked in result.blocking_issues.items()
+                if len(blocked) > 0
+            ]
+            blockers.sort(key=lambda x: x[1], reverse=True)
+
+            if blockers:
+                lines.append("")
+                lines.append("🔴 Top Blockers (most dependent issues):")
+                for issue_id, count in blockers[:3]:
+                    lines.append(
+                        f"  • {issue_id} blocks {count} issue{'s' if count != 1 else ''}"
+                    )
+
+        # Project end date
+        if result.project_end_date:
+            date_str = result.project_end_date.strftime("%b %d, %Y")
+            lines.append(f"Estimated Complete:  {date_str}")
+
+        return lines
+
+    def _assess_risk(self, result: CriticalPathResult) -> str:
+        """Assess risk level based on critical path metrics."""
+        if not result.critical_issue_ids:
+            return "🟢 LOW (no critical path)"
+
+        # Calculate risk based on slack time and duration
+        avg_slack = (
+            sum(n.slack_time for n in result.critical_path) / len(result.critical_path)
+            if result.critical_path
+            else 0
+        )
+
+        # Heuristic: if average slack is low relative to duration, risk is high
+        if avg_slack < 4:  # Less than half a business day
+            return "🔴 HIGH (minimal slack time)"
+        elif avg_slack < 12:  # Less than 1.5 business days
+            return "🟡 MEDIUM (some slack available)"
+        else:
+            return "🟢 LOW (adequate slack time)"

roadmap/adapters/cli/archive_operations.py

@@ -0,0 +1,86 @@
+"""Shared utilities for archive and restore CLI commands.
+
+Consolidates common error handling and validation patterns across
+archive/restore commands for issues, milestones, and projects.
+"""
+
+from rich.console import Console
+
+from roadmap.adapters.cli.cli_error_handlers import handle_cli_error
+from roadmap.common.console import get_console
+
+
+def handle_archive_parse_error(
+    error: Exception,
+    entity_type: str,
+    entity_id: str,
+    archive_dir: str,
+    console: Console | None = None,
+    extra_context: dict | None = None,
+) -> None:
+    """Handle errors when parsing archived entity files.
+
+    Provides consistent error handling across archive/restore commands.
+
+    Args:
+        error: The exception that occurred
+        entity_type: Type of entity ("issue", "milestone", "project")
+        entity_id: ID or name of the entity
+        archive_dir: Path to the archive directory
+        console: Optional console instance (uses default if not provided)
+        extra_context: Optional additional context dict to merge with base context
+    """
+    if console is None:
+        console = get_console()
+
+    context = {"archive_dir": str(archive_dir)}
+    if extra_context:
+        context.update(extra_context)
+
+    handle_cli_error(
+        error=error,
+        operation=f"parse_archived_{entity_type}",
+        entity_type=entity_type,
+        entity_id=entity_id,
+        context=context,
+        fatal=False,
+    )
+    console.print(f"  • {entity_id} (parse error)", style="red")  # type: ignore[union-attr]
+
+
+def handle_restore_parse_error(
+    error: Exception,
+    entity_type: str,
+    entity_id: str,
+    archive_dir: str,
+    console: Console | None = None,
+    extra_context: dict | None = None,
+) -> None:
+    """Handle errors when parsing files during restore.
+
+    Provides consistent error handling across restore commands.
+
+    Args:
+        error: The exception that occurred
+        entity_type: Type of entity ("issue", "milestone", "project")
+        entity_id: ID or name of the entity
+        archive_dir: Path to the archive directory
+        console: Optional console instance (uses default if not provided)
+        extra_context: Optional additional context dict to merge with base context
+    """
+    if console is None:
+        console = get_console()
+
+    context = {"archive_dir": str(archive_dir)}
+    if extra_context:
+        context.update(extra_context)
+
+    handle_cli_error(
+        error=error,
+        operation=f"restore_{entity_type}",
+        entity_type=entity_type,
+        entity_id=entity_id,
+        context=context,
+        fatal=False,
+    )
+    console.print(f"  • {entity_id} (restore error)", style="red")  # type: ignore[union-attr]

roadmap/adapters/cli/cli_command_helpers.py

@@ -0,0 +1,109 @@
+"""CLI command helpers - Consolidated patterns for common CLI operations.
+
+Provides decorators and functions to reduce duplication in CLI commands:
+- Initialization checks
+- Entity validation
+- Operation error handling
+- Confirmation dialogs
+"""
+
+import functools
+import sys
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import click  # type: ignore[import-not-found]
+from rich.console import Console  # type: ignore[import-not-found]
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+console = Console()
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def require_initialized(func: Callable) -> Callable:
+    """Require roadmap to be initialized before command execution.
+
+    Usage:
+        @click.command()
+        @click.pass_context
+        @require_initialized
+        def my_command(ctx: click.Context):
+            # ctx.obj["core"] is guaranteed to be initialized
+            pass
+
+    Exits with error code 1 if not initialized.
+    """
+
+    @functools.wraps(func)
+    def wrapper(ctx: click.Context, *args: Any, **kwargs: Any) -> Any:
+        core = ctx.obj.get("core")
+        if not core or not core.is_initialized():
+            console.print(
+                "❌ Roadmap not initialized. Run 'roadmap init' first.",
+                style="bold red",
+            )
+            ctx.exit(1)
+        return func(ctx, *args, **kwargs)
+
+    return wrapper
+
+
+def ensure_entity_exists(
+    core: Any, entity_type: str, entity_id: str, entity: Any = None
+) -> Any:
+    """Ensure entity exists, exit with error if not found.
+
+    Args:
+        core: RoadmapCore instance
+        entity_type: Type of entity ('issue', 'project', 'milestone')
+        entity_id: ID of entity to look up
+        entity: Pre-fetched entity (if None, will look up via core)
+
+    Returns:
+        The entity object
+
+    Exits with error code 1 if entity not found.
+    """
+    if entity is None:
+        # Fetch from core
+        entity_collection = getattr(core, f"{entity_type}s", None)
+        if entity_collection is None:
+            console.print(
+                f"❌ Invalid entity type: {entity_type}",
+                style="bold red",
+            )
+            sys.exit(1)
+        entity = entity_collection.get(entity_id)
+
+    if not entity:
+        console.print(
+            f"❌ {entity_type.capitalize()} not found: {entity_id}",
+            style="bold red",
+        )
+        sys.exit(1)
+
+    return entity
+
+
+def confirm_action(prompt: str, default: bool = False, force: bool = False) -> bool:
+    """Prompt user to confirm an action.
+
+    Args:
+        prompt: Confirmation prompt text
+        default: Default answer if user just presses Enter
+        force: If True, skip prompt and return True (for --force flag)
+
+    Returns:
+        True if user confirms, False otherwise (displays cancellation message)
+    """
+    if force:
+        return True
+
+    if not click.confirm(prompt, default=default):
+        console.print("❌ Cancelled.", style="yellow")
+        return False
+
+    return True