roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/cli/health/enhancer.py

@@ -0,0 +1,227 @@
+"""Health check result enhancement with details and recommendations.
+
+This module provides infrastructure for enriching health check results with:
+- Affected entities (which issues, milestones, etc. are affected)
+- Fix recommendations (what can be done to resolve issues)
+- Auto-fix commands (ready-to-run commands for common fixes)
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from roadmap.core.domain.health import HealthStatus
+
+
+@dataclass
+class HealthCheckDetail:
+    """Details about a specific health check result.
+
+    Attributes:
+        check_name: Name of the health check (e.g., "duplicate_issues")
+        status: Health status (HEALTHY, DEGRADED, UNHEALTHY)
+        message: Summary message about the check result
+        affected_items: List of affected entity IDs or names
+        recommendations: List of recommended fixes or actions
+        fix_commands: List of ready-to-run CLI commands that can fix the issue
+    """
+
+    check_name: str
+    status: HealthStatus
+    message: str
+    affected_items: list[str] = field(default_factory=list)
+    recommendations: list[str] = field(default_factory=list)
+    fix_commands: list[dict[str, str]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "check_name": self.check_name,
+            "status": self.status.value.upper(),
+            "message": self.message,
+            "affected_items": self.affected_items,
+            "affected_count": len(self.affected_items),
+            "recommendations": self.recommendations,
+            "fix_commands": self.fix_commands,
+        }
+
+
+class HealthCheckEnhancer:
+    """Enhances health check results with detailed information.
+
+    This service enriches basic health check results (status + message) with:
+    - Lists of affected entities
+    - Specific recommendations for fixes
+    - Ready-to-run CLI commands to fix issues
+
+    Works with both infrastructure and data quality checks.
+    """
+
+    def __init__(self, core=None):
+        """Initialize enhancer with optional core for entity lookups.
+
+        Args:
+            core: Optional core instance for accessing entities
+        """
+        self.core = core
+
+    def enhance_check_result(
+        self,
+        check_name: str,
+        status: HealthStatus,
+        message: str,
+    ) -> HealthCheckDetail:
+        """Enhance a health check result with details.
+
+        Args:
+            check_name: Name of the health check
+            status: Health status from the check
+            message: Message from the check
+
+        Returns:
+            HealthCheckDetail with enhanced information
+        """
+        detail = HealthCheckDetail(
+            check_name=check_name,
+            status=status,
+            message=message,
+        )
+
+        # Route to check-specific enhancement
+        if check_name == "duplicate_issues":
+            self._enhance_duplicate_issues(detail)
+        elif check_name == "orphaned_issues":
+            self._enhance_orphaned_issues(detail)
+        elif check_name == "old_backups":
+            self._enhance_old_backups(detail)
+        elif check_name == "folder_structure":
+            self._enhance_folder_structure(detail)
+        elif check_name == "comment_integrity":
+            self._enhance_comment_integrity(detail)
+        else:
+            # Generic enhancement for other checks
+            self._enhance_generic(detail)
+
+        return detail
+
+    def _enhance_duplicate_issues(self, detail: HealthCheckDetail) -> None:
+        """Add details for duplicate_issues check."""
+        detail.recommendations = [
+            "Review issues with identical titles and status",
+            "Merge duplicates, keeping the older issue as primary",
+            "Close/delete the newer duplicate issue",
+        ]
+        detail.fix_commands = [
+            {
+                "command": "roadmap health fix --fix-type duplicate_issues --dry-run",
+                "description": "Preview duplicate issues that can be fixed",
+            },
+            {
+                "command": "roadmap health fix --fix-type duplicate_issues",
+                "description": "Automatically fix duplicate issues (requires review)",
+            },
+        ]
+
+    def _enhance_orphaned_issues(self, detail: HealthCheckDetail) -> None:
+        """Add details for orphaned_issues check."""
+        detail.recommendations = [
+            "Assign issues without milestones to 'Backlog'",
+            "Review issues to ensure correct milestone assignment",
+            "Use 'roadmap issue assign' to move to correct milestone",
+        ]
+        detail.fix_commands = [
+            {
+                "command": "roadmap health fix --fix-type orphaned_issues --dry-run",
+                "description": "Preview issues to be assigned to Backlog",
+            },
+            {
+                "command": "roadmap health fix --fix-type orphaned_issues",
+                "description": "Automatically assign orphaned issues to Backlog",
+            },
+        ]
+
+    def _enhance_old_backups(self, detail: HealthCheckDetail) -> None:
+        """Add details for old_backups check."""
+        detail.recommendations = [
+            "Delete backup files older than 90 days to save storage",
+            "Review archived backups to ensure data is safely stored",
+            "Consider moving very old backups to external storage",
+        ]
+        detail.fix_commands = [
+            {
+                "command": "roadmap health fix --fix-type old_backups --dry-run",
+                "description": "Preview old backups that can be deleted",
+            },
+            {
+                "command": "roadmap health fix --fix-type old_backups",
+                "description": "Delete old backup files (>90 days)",
+            },
+        ]
+
+    def _enhance_folder_structure(self, detail: HealthCheckDetail) -> None:
+        """Add details for folder_structure check."""
+        detail.recommendations = [
+            "Move issues to their correct milestone folders",
+            "Verify milestone folder organization matches issue assignments",
+            "Use 'roadmap issue move' to reorganize structure",
+        ]
+        detail.fix_commands = [
+            {
+                "command": "roadmap health fix --fix-type folder_structure --dry-run",
+                "description": "Preview folder structure corrections",
+            },
+            {
+                "command": "roadmap health fix --fix-type folder_structure",
+                "description": "Automatically fix folder structure issues",
+            },
+        ]
+
+    def _enhance_comment_integrity(self, detail: HealthCheckDetail) -> None:
+        """Add details for comment_integrity check."""
+        detail.recommendations = [
+            "Review and sanitize malformed JSON in comments",
+            "Check for corrupted comment threads",
+            "Manually edit comments with formatting issues",
+        ]
+        detail.fix_commands = [
+            {
+                "command": "roadmap health fix --fix-type corrupted_comments --dry-run",
+                "description": "Preview comments that can be sanitized",
+            },
+            {
+                "command": "roadmap health fix --fix-type corrupted_comments",
+                "description": "Automatically sanitize malformed comments (review first)",
+            },
+        ]
+
+    def _enhance_generic(self, detail: HealthCheckDetail) -> None:
+        """Enhance check with generic recommendations."""
+        if detail.status == HealthStatus.HEALTHY:
+            detail.recommendations = ["No action needed"]
+        elif detail.status == HealthStatus.DEGRADED:
+            detail.recommendations = [
+                "Monitor this check in future health reports",
+                "Take action when status becomes UNHEALTHY",
+            ]
+        else:  # UNHEALTHY
+            detail.recommendations = [
+                "Investigate the root cause immediately",
+                "Review the detailed message for specific guidance",
+                "Use 'roadmap health scan' for entity-level diagnostics",
+            ]
+
+    def enhance_all_checks(
+        self, checks: Mapping[str, tuple[HealthStatus, str]]
+    ) -> dict[str, HealthCheckDetail]:
+        """Enhance all health check results.
+
+        Args:
+            checks: Dict mapping check names to (status, message) tuples
+
+        Returns:
+            Dict mapping check names to HealthCheckDetail objects
+        """
+        return {
+            check_name: self.enhance_check_result(check_name, status, message)
+            for check_name, (status, message) in checks.items()
+        }

roadmap/adapters/cli/health/fixer.py

@@ -0,0 +1,295 @@
+"""Health check fixer orchestrator and base infrastructure.
+
+Provides framework for automatically fixing detected health issues with:
+- Safe/review categorization
+- Dry-run preview mode (default)
+- Rollback capability tracking
+- Detailed fix result reporting
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class FixSafety(Enum):
+    """Safety level for a fixer.
+
+    SAFE: Can be applied automatically without human review
+    REVIEW: Requires human review before applying
+    """
+
+    SAFE = "safe"
+    REVIEW = "review"
+
+
+@dataclass
+class FixResult:
+    """Result of a fix operation.
+
+    Attributes:
+        fix_type: Type of fix that was applied
+        success: Whether the fix succeeded
+        dry_run: Whether this was a dry-run
+        message: Description of what was fixed
+        affected_items: IDs or names of affected entities
+        items_count: Number of items affected
+        changes_made: Number of changes actually made
+        rollback_info: Information for rolling back (if applicable)
+    """
+
+    fix_type: str
+    success: bool
+    dry_run: bool
+    message: str
+    affected_items: list[str] = field(default_factory=list)
+    items_count: int = 0
+    changes_made: int = 0
+    rollback_info: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "fix_type": self.fix_type,
+            "success": self.success,
+            "dry_run": self.dry_run,
+            "message": self.message,
+            "affected_items": self.affected_items,
+            "items_count": self.items_count,
+            "changes_made": self.changes_made,
+            "has_rollback": self.rollback_info is not None,
+        }
+
+
+class HealthFixer(ABC):
+    """Abstract base class for health check fixers.
+
+    Each fixer handles a specific type of health issue:
+    - old_backups: Delete old backup files
+    - duplicate_issues: Merge duplicate issues
+    - orphaned_issues: Assign unassigned issues to Backlog
+    - folder_structure: Move issues to correct milestone folders
+    - corrupted_comments: Sanitize malformed JSON comments
+    """
+
+    def __init__(self, core):
+        """Initialize fixer with core instance.
+
+        Args:
+            core: Core application instance
+        """
+        self.core = core
+
+    @property
+    @abstractmethod
+    def fix_type(self) -> str:
+        """Identifier for this fixer (e.g., 'duplicate_issues')."""
+        pass
+
+    @property
+    @abstractmethod
+    def safety_level(self) -> FixSafety:
+        """Safety level: SAFE or REVIEW."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description of what this fixer does."""
+        pass
+
+    @abstractmethod
+    def scan(self) -> dict[str, Any]:
+        """Scan for issues that can be fixed.
+
+        Returns:
+            Dict with:
+            - found: bool (whether issues were found)
+            - count: int (number of issues found)
+            - message: str (description)
+            - details: list (specific issues found)
+        """
+        pass
+
+    @abstractmethod
+    def dry_run(self) -> FixResult:
+        """Preview what would be fixed without making changes.
+
+        Returns:
+            FixResult with dry_run=True
+        """
+        pass
+
+    @abstractmethod
+    def apply(self, force: bool = False) -> FixResult:
+        """Apply the fix (actually make changes).
+
+        Args:
+            force: If True, apply without prompts
+
+        Returns:
+            FixResult with dry_run=False
+        """
+        pass
+
+    def confirm_apply(self, dry_run_result: FixResult) -> bool:
+        """Ask user to confirm applying a fix.
+
+        For SAFE fixes, this can auto-approve.
+        For REVIEW fixes, user must manually confirm.
+
+        Args:
+            dry_run_result: Result from dry_run()
+
+        Returns:
+            True if user confirms, False otherwise
+        """
+        if self.safety_level == FixSafety.SAFE:
+            return True
+
+        # REVIEW fixes require user confirmation
+        import click
+
+        message = f"\nApply {self.fix_type}? {dry_run_result.message}"
+        return click.confirm(message, default=False)
+
+
+class HealthFixOrchestrator:
+    """Orchestrates health fixes across all available fixers.
+
+    Handles:
+    - Loading all available fixers
+    - Running dry-run previews
+    - Applying fixes with proper safety checks
+    - Collecting results
+    """
+
+    def __init__(self, core):
+        """Initialize orchestrator.
+
+        Args:
+            core: Core application instance
+        """
+        self.core = core
+        self._fixers: dict[str, HealthFixer] = {}
+        self._load_fixers()
+
+    def _load_fixers(self) -> None:
+        """Load all available fixers."""
+        from roadmap.adapters.cli.health.fixers.corrupted_comments_fixer import (
+            CorruptedCommentsFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.data_integrity_fixer import (
+            DataIntegrityFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.duplicate_issues_fixer import (
+            DuplicateIssuesFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.folder_structure_fixer import (
+            FolderStructureFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.label_normalization_fixer import (
+            LabelNormalizationFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.milestone_name_normalization_fixer import (
+            MilestoneNameNormalizationFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.milestone_naming_compliance_fixer import (
+            MilestoneNamingComplianceFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.milestone_parse_error_fixer import (
+            MilestoneParseErrorFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.milestone_validation_fixer import (
+            MilestoneValidationFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.old_backups_fixer import (
+            OldBackupsFixer,
+        )
+        from roadmap.adapters.cli.health.fixers.orphaned_issues_fixer import (
+            OrphanedIssuesFixer,
+        )
+
+        fixers = [
+            OldBackupsFixer(self.core),
+            DuplicateIssuesFixer(self.core),
+            OrphanedIssuesFixer(self.core),
+            FolderStructureFixer(self.core),
+            CorruptedCommentsFixer(self.core),
+            DataIntegrityFixer(self.core),
+            LabelNormalizationFixer(self.core),
+            MilestoneNameNormalizationFixer(self.core),
+            MilestoneNamingComplianceFixer(self.core),
+            MilestoneValidationFixer(self.core),
+            MilestoneParseErrorFixer(self.core),
+        ]
+
+        for fixer in fixers:
+            self._fixers[fixer.fix_type] = fixer
+
+    def get_fixers(self) -> dict[str, HealthFixer]:
+        """Get all available fixers.
+
+        Returns:
+            Dict mapping fix_type to HealthFixer instance
+        """
+        return self._fixers.copy()
+
+    def get_fixer(self, fix_type: str) -> HealthFixer | None:
+        """Get a specific fixer by type.
+
+        Args:
+            fix_type: The fix type identifier
+
+        Returns:
+            HealthFixer instance or None if not found
+        """
+        return self._fixers.get(fix_type)
+
+    def scan_all(self) -> dict[str, dict[str, Any]]:
+        """Scan for all fixable issues.
+
+        Returns:
+            Dict mapping fix_type to scan results
+        """
+        results = {}
+        for fix_type, fixer in self._fixers.items():
+            results[fix_type] = fixer.scan()
+        return results
+
+    def dry_run_fix(self, fix_type: str) -> FixResult | None:
+        """Preview a specific fix.
+
+        Args:
+            fix_type: Which fix to preview
+
+        Returns:
+            FixResult or None if fixer not found
+        """
+        fixer = self.get_fixer(fix_type)
+        if not fixer:
+            return None
+        return fixer.dry_run()
+
+    def apply_fix(self, fix_type: str, force: bool = False) -> FixResult | None:
+        """Apply a specific fix.
+
+        Args:
+            fix_type: Which fix to apply
+            force: If True, apply without confirmation
+
+        Returns:
+            FixResult or None if fixer not found
+        """
+        fixer = self.get_fixer(fix_type)
+        if not fixer:
+            return None
+
+        # For review fixes, confirm first
+        if not force and fixer.safety_level == FixSafety.REVIEW:
+            dry_result = fixer.dry_run()
+            if not fixer.confirm_apply(dry_result):
+                return None
+
+        return fixer.apply(force=force)

roadmap/adapters/cli/health/fixers/__init__.py

@@ -0,0 +1,10 @@
+"""Health check fixers for automatically correcting detected issues.
+
+Available fixers:
+- OldBackupsFixer: Delete old backup files (>90 days)
+- DuplicateIssuesFixer: Merge duplicate issues
+- OrphanedIssuesFixer: Assign unassigned issues to Backlog
+- FolderStructureFixer: Move issues to correct milestone folders
+- CorruptedCommentsFixer: Sanitize malformed JSON comments
+- DataIntegrityFixer: Remove malformed issue files
+"""