roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/cli/sync_handlers/progress_tracker.py

@@ -0,0 +1,128 @@
+"""Progress tracking for sync operations."""
+
+from contextlib import contextmanager
+
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+
+from roadmap.common.console import get_console
+
+
+class SyncProgressTracker:
+    """Tracks and displays progress during sync operations."""
+
+    def __init__(self, console=None):
+        """Initialize progress tracker.
+
+        Args:
+            console: Rich console instance (creates new one if None)
+        """
+        self.console = console or get_console()
+        self.progress = None
+        self.current_task = None
+
+    @contextmanager
+    def track_sync(self, total_issues: int):
+        """Context manager for tracking overall sync progress.
+
+        Args:
+            total_issues: Total number of issues to sync
+
+        Yields:
+            Progress tracker instance
+        """
+        self.progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[bold blue]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            TextColumn("•"),
+            TimeElapsedColumn(),
+            console=self.console,
+        )
+
+        with self.progress:
+            self.current_task = self.progress.add_task(
+                "Syncing issues...", total=total_issues
+            )
+            yield self
+
+    def update(self, advance: int = 1, description: str | None = None):
+        """Update progress.
+
+        Args:
+            advance: Number of steps to advance
+            description: Optional new description
+        """
+        if self.progress and self.current_task is not None:
+            if description:
+                self.progress.update(self.current_task, description=description)
+            self.progress.advance(self.current_task, advance)
+
+    def set_description(self, description: str):
+        """Set current task description.
+
+        Args:
+            description: New description text
+        """
+        if self.progress and self.current_task is not None:
+            self.progress.update(self.current_task, description=description)
+
+    @contextmanager
+    def track_phase(self, phase_name: str, total: int | None = None):
+        """Track a specific phase of sync operation.
+
+        Args:
+            phase_name: Name of the phase (e.g., "Fetching", "Pushing")
+            total: Total items in this phase
+
+        Yields:
+            Task ID for this phase
+        """
+        if not self.progress:
+            yield None
+            return
+
+        task_id = self.progress.add_task(
+            f"[cyan]{phase_name}...",
+            total=total if total is not None else None,
+        )
+
+        try:
+            yield task_id
+        finally:
+            self.progress.update(task_id, completed=True)
+
+    def update_phase(self, task_id, advance: int = 1, description: str | None = None):
+        """Update a specific phase task.
+
+        Args:
+            task_id: Task ID returned from track_phase
+            advance: Number of steps to advance
+            description: Optional new description
+        """
+        if self.progress and task_id is not None:
+            if description:
+                self.progress.update(task_id, description=description)
+            if advance:
+                self.progress.advance(task_id, advance)
+
+
+def create_spinner_progress() -> Progress:
+    """Create a simple spinner progress for indeterminate operations.
+
+    Returns:
+        Progress instance with spinner
+    """
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[bold blue]{task.description}"),
+        TimeElapsedColumn(),
+        console=get_console(),
+    )

roadmap/adapters/cli/sync_metrics_command.py

@@ -0,0 +1,190 @@
+"""CLI command for displaying and querying sync metrics.
+
+This module provides commands to view sync operation metrics,
+historical data, and aggregate statistics.
+"""
+
+import click
+from rich.panel import Panel
+
+from roadmap.adapters.cli.cli_command_helpers import require_initialized
+from roadmap.adapters.persistence.sync_metrics_repository import (
+    SyncMetricsRepository,
+)
+from roadmap.common.console import get_console
+from roadmap.presentation.formatters.sync_metrics_formatter import (
+    create_metrics_history_table,
+    create_metrics_summary_table,
+)
+
+
+@click.command(name="metrics")
+@click.option(
+    "--backend",
+    type=str,
+    default=None,
+    help="Filter metrics by backend type (e.g., github, vanilla_git)",
+)
+@click.option(
+    "--days",
+    type=int,
+    default=7,
+    help="Show metrics from the last N days (default: 7)",
+)
+@click.option(
+    "--latest",
+    is_flag=True,
+    help="Show only the latest sync metrics",
+)
+@click.option(
+    "--stats",
+    is_flag=True,
+    help="Show aggregate statistics for the period",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show detailed metrics including performance data",
+)
+@click.pass_context
+@require_initialized
+def sync_metrics(
+    ctx: click.Context,
+    backend: str | None,
+    days: int,
+    latest: bool,
+    stats: bool,
+    verbose: bool,
+) -> None:
+    r"""Display sync operation metrics and history.
+
+    View historical sync metrics, performance data, and statistics
+    to monitor sync health and performance over time.
+
+    Examples:
+    \b
+        # Show metrics from last 7 days
+        roadmap sync metrics
+
+    \b
+        # Show metrics from last 30 days for GitHub
+        roadmap sync metrics --backend github --days 30
+
+    \b
+        # Show only the latest sync
+        roadmap sync metrics --latest
+
+    \b
+        # Show aggregate statistics
+        roadmap sync metrics --stats
+    """
+    console_inst = get_console()
+    core = ctx.obj["core"]
+
+    try:
+        # Initialize repository with core's database manager
+        metrics_repo = SyncMetricsRepository(core.db_manager)
+
+        # Get metrics
+        if latest:
+            # Show only the latest sync
+            metrics = metrics_repo.get_latest(backend_type=backend)
+            if not metrics:
+                console_inst.print("[yellow]No sync metrics found[/yellow]")
+                return
+
+            console_inst.print()
+            console_inst.print(
+                Panel(
+                    create_metrics_summary_table(metrics, verbose),
+                    title="[bold cyan]Latest Sync Metrics[/bold cyan]",
+                    border_style="cyan",
+                )
+            )
+            console_inst.print()
+
+        elif stats:
+            # Show aggregate statistics
+            statistics = metrics_repo.get_statistics(backend_type=backend, days=days)
+
+            if statistics and statistics["total_syncs"] > 0:
+                from rich.table import Table
+
+                stats_table = Table(show_header=False, box=None, padding=(0, 2))
+                stats_table.add_column(style="bold")
+                stats_table.add_column(justify="right", style="cyan")
+
+                stats_table.add_row(
+                    "Total Syncs",
+                    str(statistics["total_syncs"]),
+                )
+                stats_table.add_row(
+                    "Average Duration",
+                    f"{statistics['avg_duration_seconds']:.1f}s",
+                )
+                stats_table.add_row(
+                    "Total Duplicates",
+                    str(statistics["total_duplicates_detected"]),
+                )
+                stats_table.add_row(
+                    "Total Conflicts",
+                    str(statistics["total_conflicts_detected"]),
+                )
+                stats_table.add_row(
+                    "Total Errors",
+                    str(statistics["total_errors"]),
+                )
+
+                console_inst.print()
+                console_inst.print(
+                    Panel(
+                        stats_table,
+                        title=f"[bold cyan]Statistics ({days} days)[/bold cyan]",
+                        border_style="cyan",
+                    )
+                )
+                console_inst.print()
+            else:
+                console_inst.print(
+                    "[yellow]No sync metrics found for the specified period[/yellow]"
+                )
+
+        else:
+            # Show history
+            metrics_list = metrics_repo.list_by_date(backend_type=backend, days=days)
+
+            if not metrics_list:
+                console_inst.print(
+                    f"[yellow]No sync metrics found in the last {days} days[/yellow]"
+                )
+                return
+
+            console_inst.print()
+            console_inst.print(
+                Panel(
+                    create_metrics_history_table(metrics_list, limit=10),
+                    title=f"[bold cyan]Sync History (last {days} days)[/bold cyan]",
+                    border_style="cyan",
+                )
+            )
+            console_inst.print()
+
+            # Show brief summary
+            latest_metrics = metrics_list[0] if metrics_list else None
+            if latest_metrics and verbose:
+                console_inst.print(
+                    Panel(
+                        create_metrics_summary_table(latest_metrics, verbose),
+                        title="[bold cyan]Latest Sync Details[/bold cyan]",
+                        border_style="cyan",
+                    )
+                )
+                console_inst.print()
+
+    except Exception as e:
+        console_inst.print(
+            f"[bold red]❌ Error retrieving metrics: {str(e)}[/bold red]"
+        )
+        if verbose:
+            raise

roadmap/adapters/cli/sync_presenter.py

@@ -0,0 +1,58 @@
+"""Presentation helpers for the `roadmap sync` CLI command.
+
+This module contains functions responsible for printing analysis results
+and prompting the user for confirmation. It centralizes UI logic so that
+the sync command can remain focused on orchestration.
+"""
+
+from typing import Any
+
+from roadmap.common.console import get_console
+
+
+def present_analysis(analysis_report: Any, verbose: bool = False) -> None:
+    """Present a summary (and optional details) of the sync analysis.
+
+    The function is defensive about which attributes exist on
+    `analysis_report` to avoid tight coupling with concrete report classes.
+    """
+    console = get_console()
+
+    console.print("\n[bold cyan]📈 Sync Analysis[/bold cyan]")
+    console.print(
+        f"   ✓ Up-to-date: {getattr(analysis_report, 'issues_up_to_date', 0)}"
+    )
+    console.print(
+        f"   📤 Needs Push: {getattr(analysis_report, 'issues_needs_push', 0)}"
+    )
+    console.print(
+        f"   📥 Needs Pull: {getattr(analysis_report, 'issues_needs_pull', 0)}"
+    )
+    console.print(
+        f"   ✓ Potential Conflicts: {getattr(analysis_report, 'conflicts_detected', 0)}"
+    )
+
+    if verbose:
+        # If the report exposes a list of changes, show a concise table-like view
+        changes = getattr(analysis_report, "changes", None)
+        if changes:
+            console.print("\n[bold]Detailed changes:[/bold]")
+            for change in changes:
+                try:
+                    line = f"   • {change.issue_id}: "
+                    if getattr(change, "has_conflict", False):
+                        line += "(CONFLICT) "
+                    title = getattr(change, "title", None)
+                    if title:
+                        line += f"{title}"
+                    console.print(line)
+                except Exception as e:
+                    from roadmap.common.logging import get_logger
+
+                    logger = get_logger(__name__)
+                    logger.debug(
+                        "sync_change_presentation_failed",
+                        error=str(e),
+                        action="present_change",
+                    )
+                    continue

roadmap/adapters/cli/sync_validation.py

@@ -0,0 +1,295 @@
+"""Sync validation commands for checking remote link health.
+
+This module provides commands to validate and repair remote links in the database,
+ensuring that all YAML remote_ids are properly tracked and accessible.
+"""
+
+import sys
+
+import click
+
+from roadmap.adapters.cli.cli_command_helpers import require_initialized
+from roadmap.common.console import get_console
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@click.command(name="validate-links")
+@click.option(
+    "--auto-fix",
+    is_flag=True,
+    help="Automatically repair broken or missing links",
+)
+@click.option(
+    "--prune-extra",
+    is_flag=True,
+    help="Remove database links that are not present in YAML",
+)
+@click.option(
+    "--dedupe",
+    is_flag=True,
+    help="Remove duplicate remote_id links (keep YAML-backed link if present)",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Preview changes without applying them",
+)
+@click.option(
+    "--verbose",
+    is_flag=True,
+    help="Show detailed validation information for each issue",
+)
+@click.pass_context
+@require_initialized
+def validate_links(
+    ctx: click.Context,
+    auto_fix: bool,
+    prune_extra: bool,
+    dedupe: bool,
+    dry_run: bool,
+    verbose: bool,
+) -> None:
+    """Validate remote links in the database against YAML files.
+
+    This command scans all YAML files to verify that remote_ids are:
+    1. Properly loaded in the database
+    2. Match between YAML source and database cache
+    3. Valid and accessible for sync operations
+
+    **Examples:**
+        # Check link health
+        roadmap sync validate-links
+
+        # Show detailed info about each issue
+        roadmap sync validate-links --verbose
+
+        # Preview what would be fixed
+        roadmap sync validate-links --auto-fix --dry-run
+
+        # Repair broken links
+        roadmap sync validate-links --auto-fix
+    """
+    core = ctx.obj["core"]
+    console = get_console()
+
+    try:
+        issues_dir = core.issues_dir
+        if not issues_dir.exists():
+            console.print(
+                f"❌ Issues directory not found: {issues_dir}", style="bold red"
+            )
+            sys.exit(1)
+
+        validation_data = core.validation.collect_remote_link_validation_data(
+            issues_dir
+        )
+        issue_files = validation_data["issue_files"]
+        if not issue_files:
+            console.print("ℹ️  No issue files found", style="yellow")
+            return
+
+        validation_report: dict = {
+            "total_files": len(issue_files),
+            "files_with_remote_ids": 0,
+            "database_links": 0,
+            "discrepancies": [],
+            "missing_in_db": [],
+            "extra_in_db": [],
+            "duplicate_remote_ids": {},
+        }
+        yaml_remote_ids = validation_data["yaml_remote_ids"]
+        unparseable_files = validation_data["unparseable_files"]
+        db_links = validation_data["db_links"]
+        validation_report.update(
+            core.validation.build_remote_link_report(yaml_remote_ids, db_links)
+        )
+
+        _display_validation_summary(validation_report, unparseable_files, console)
+
+        if auto_fix:
+            _apply_auto_fix(
+                core,
+                yaml_remote_ids,
+                validation_report,
+                console,
+                dry_run,
+                verbose,
+                prune_extra,
+                dedupe,
+            )
+
+        if validation_report["missing_in_db"] and (not auto_fix or dry_run):
+            sys.exit(1)
+
+        console.print(
+            "\n✅ All remote links are valid and synchronized", style="bold green"
+        )
+
+    except Exception as e:
+        logger.error(
+            "validation_failed",
+            error=str(e),
+            error_type=type(e).__name__,
+            severity="system_error",
+        )
+        console.print(f"❌ Validation failed: {str(e)}", style="bold red")
+        sys.exit(1)
+
+
+def _display_validation_summary(
+    validation_report: dict, unparseable_files: list, console
+) -> None:
+    """Print the remote-link validation summary to the console."""
+    console.print("\n[bold]Remote Links Validation Report[/bold]", style="bold cyan")
+    console.print(f"Total issue files: {validation_report['total_files']}")
+    console.print(
+        f"Files with remote_ids: {validation_report['files_with_remote_ids']}"
+    )
+    console.print(f"Database links: {validation_report['database_links']}")
+
+    missing = validation_report["missing_in_db"]
+    if missing:
+        console.print(f"\n[bold red]❌ Missing in database: {len(missing)}[/bold red]")
+        for issue_uuid in missing[:5]:
+            console.print(f"  - {issue_uuid}")
+        if len(missing) > 5:
+            console.print(f"  ... and {len(missing) - 5} more")
+
+    if validation_report["extra_in_db"]:
+        console.print(
+            f"\n[bold yellow]⚠️  In database but not in YAML: {len(validation_report['extra_in_db'])}[/bold yellow]"
+        )
+        console.print("  (These may be archived issues)")
+
+    dup_ids = validation_report["duplicate_remote_ids"]
+    if dup_ids:
+        console.print(
+            f"\n[bold yellow]⚠️  Duplicate remote IDs: {len(dup_ids)}[/bold yellow]"
+        )
+        for remote_id, issue_uuids in list(dup_ids.items())[:5]:
+            console.print(f"  - {remote_id}: {', '.join(issue_uuids)}", style="dim")
+        if len(dup_ids) > 5:
+            console.print(f"  ... and {len(dup_ids) - 5} more")
+
+    if unparseable_files:
+        console.print(
+            f"\n[bold yellow]⚠️  Could not parse {len(unparseable_files)} files[/bold yellow]"
+        )
+        for file_path, error in unparseable_files[:3]:
+            console.print(f"  - {file_path}: {error}")
+        if len(unparseable_files) > 3:
+            console.print(f"  ... and {len(unparseable_files) - 3} more")
+
+
+def _apply_auto_fix(
+    core,
+    yaml_remote_ids: dict,
+    validation_report: dict,
+    console,
+    dry_run: bool,
+    verbose: bool,
+    prune_extra: bool,
+    dedupe: bool,
+) -> None:
+    """Apply automatic fixes for missing remote links.
+
+    Args:
+        core: RoadmapCore instance with validation coordinator
+        yaml_remote_ids: Dict of issue_uuid -> {backend -> remote_id}
+        validation_report: Validation report dict to update
+        console: Console instance for output
+        dry_run: If True, don't actually apply changes
+        verbose: If True, show detailed information
+        prune_extra: If True, remove links missing from YAML
+        dedupe: If True, remove duplicate remote IDs
+    """
+    missing = validation_report["missing_in_db"]
+    if not _has_auto_fix_work(missing, prune_extra, dedupe):
+        console.print("\n✅ No links need fixing", style="bold green")
+        return
+
+    _display_auto_fix_plan(
+        console,
+        missing,
+        yaml_remote_ids,
+        validation_report,
+        dry_run,
+        verbose,
+        prune_extra,
+        dedupe,
+    )
+
+    try:
+        results = core.validation.apply_remote_link_fixes(
+            yaml_remote_ids,
+            validation_report,
+            backend_name="github",
+            prune_extra=prune_extra,
+            dedupe=dedupe,
+            dry_run=dry_run,
+        )
+    except Exception as e:
+        logger.warning("auto_fix_failed", error=str(e), severity="operational")
+        console.print(f"  ⚠️  Auto-fix failed: {str(e)}", style="yellow")
+        return
+
+    _display_auto_fix_results(console, results, dry_run)
+
+
+def _has_auto_fix_work(missing: list[str], prune_extra: bool, dedupe: bool) -> bool:
+    return bool(missing or prune_extra or dedupe)
+
+
+def _display_auto_fix_plan(
+    console,
+    missing: list[str],
+    yaml_remote_ids: dict,
+    validation_report: dict,
+    dry_run: bool,
+    verbose: bool,
+    prune_extra: bool,
+    dedupe: bool,
+) -> None:
+    if missing:
+        console.print(
+            f"\n[bold cyan]🔧 Auto-fixing {len(missing)} missing links...[/bold cyan]"
+        )
+        if dry_run:
+            console.print(
+                "  (Dry-run mode - no changes will be made)", style="dim yellow"
+            )
+
+    if verbose and yaml_remote_ids:
+        for issue_uuid, remote_ids in yaml_remote_ids.items():
+            console.print(
+                f"  📄 {issue_uuid}: {', '.join(remote_ids.keys())}", style="cyan"
+            )
+
+    if prune_extra and validation_report.get("extra_in_db"):
+        console.print(
+            f"\n[bold cyan]🧹 Removing {len(validation_report['extra_in_db'])} extra links...[/bold cyan]"
+        )
+
+    if dedupe and validation_report.get("duplicate_remote_ids"):
+        console.print(
+            f"\n[bold cyan]🧹 Removing {len(validation_report['duplicate_remote_ids'])} duplicate remote IDs...[/bold cyan]"
+        )
+
+
+def _display_auto_fix_results(console, results: dict, dry_run: bool) -> None:
+    if results.get("fixed_count"):
+        console.print(
+            f"\n[bold green]✅ Fixed {results['fixed_count']} missing remote links[/bold green]"
+        )
+    if results.get("removed_count"):
+        console.print(
+            f"[bold green]✅ Removed {results['removed_count']} extra remote links[/bold green]"
+        )
+    if results.get("deduped_count"):
+        console.print(
+            f"[bold green]✅ Removed {results['deduped_count']} duplicate remote links[/bold green]"
+        )
+    if dry_run:
+        console.print("Re-run without --dry-run to apply changes", style="dim yellow")