roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/utils/remote_state_normalizer.py

@@ -0,0 +1,110 @@
+"""Normalizes remote issue state for comparison with local state.
+
+Extracted from SyncStateComparator to separate state normalization logic.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from structlog import get_logger
+
+logger = get_logger(__name__)
+
+
+class RemoteStateNormalizer:
+    """Normalizes remote issue state for sync operations."""
+
+    @staticmethod
+    def normalize_remote_state(remote: Any) -> dict[str, Any] | None:
+        """Normalize remote issue state to standard format.
+
+        Args:
+            remote: Remote issue object or dict
+
+        Returns:
+            Normalized state dict, or None if invalid
+        """
+        if remote is None:
+            return None
+
+        try:
+            if isinstance(remote, dict):
+                return remote.copy()
+
+            # Convert object to dict
+            state = {}
+
+            # Extract standard fields
+            for field in [
+                "id",
+                "status",
+                "title",
+                "content",
+                "labels",
+                "assignee",
+                "milestone",
+            ]:
+                value = getattr(remote, field, None)
+                if value is not None:
+                    state[field] = value
+
+            # Handle timestamps
+            for ts_field in ["updated_at", "created_at"]:
+                if hasattr(remote, ts_field):
+                    state[ts_field] = getattr(remote, ts_field)
+
+            return state if state else None
+
+        except Exception as e:
+            logger.debug(
+                "normalize_remote_state_failed",
+                error=str(e),
+                remote_type=type(remote).__name__,
+            )
+            return None
+
+    @staticmethod
+    def extract_timestamp(
+        remote: Any, field_name: str = "updated_at"
+    ) -> datetime | None:
+        """Extract timestamp from remote issue.
+
+        Args:
+            remote: Remote issue object or dict
+            field_name: Name of timestamp field (default: "updated_at")
+
+        Returns:
+            Datetime object, or None if not found/invalid
+        """
+        if remote is None:
+            return None
+
+        try:
+            if isinstance(remote, dict):
+                value = remote.get(field_name)
+            else:
+                value = getattr(remote, field_name, None)
+
+            if value is None:
+                return None
+
+            if isinstance(value, datetime):
+                return value
+
+            if isinstance(value, str):
+                # Try ISO format
+                try:
+                    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+                except (ValueError, AttributeError):
+                    return None
+
+            return None
+
+        except Exception as e:
+            logger.debug(
+                "normalize_state_failed",
+                operation="normalize_state",
+                error=str(e),
+                action="Returning None",
+            )
+            return None

roadmap/core/services/utils/retry_policy.py

@@ -0,0 +1,51 @@
+"""Retry policy with exponential backoff strategy."""
+
+import time
+
+
+class RetryPolicy:
+    """Simple exponential backoff retry policy.
+
+    Example:
+        rp = RetryPolicy(max_retries=3, base_delay=0.5, factor=2.0)
+        for attempt in range(1, rp.max_retries + 1):
+            try:
+                ...
+            except Exception:
+                if attempt == rp.max_retries:
+                    raise
+                time.sleep(rp.get_backoff_delay(attempt))
+    """
+
+    def __init__(
+        self, max_retries: int = 3, base_delay: float = 0.5, factor: float = 2.0
+    ):
+        """Initialize RetryPolicy.
+
+        Args:
+            max_retries: Maximum number of retry attempts.
+            base_delay: Initial delay in seconds.
+            factor: Exponential factor for delay increase.
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.factor = factor
+
+    def get_backoff_delay(self, attempt: int) -> float:
+        """Get delay in seconds for a given attempt (1-based)."""
+        if attempt <= 1:
+            return 0.0
+        return self.base_delay * (self.factor ** (attempt - 1))
+
+    def sleep_for_attempt(self, attempt: int) -> None:
+        """Sleep for the appropriate backoff delay based on attempt number.
+
+        Args:
+            attempt: The attempt number (1-based).
+        """
+        delay = self.get_backoff_delay(attempt)
+        if delay > 0:
+            time.sleep(delay)
+
+
+__all__ = ["RetryPolicy"]

roadmap/core/services/validator_base.py

@@ -0,0 +1,130 @@
+"""Base class for all health validators.
+
+Provides consistent error handling, logging, and status reporting patterns
+for health check validators throughout the application.
+
+All validators should inherit from BaseValidator and implement:
+- get_check_name(): Return unique check identifier
+- perform_check(): Return (status, message) tuple
+
+The base class handles error handling and logging automatically.
+"""
+
+from abc import ABC, abstractmethod
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class HealthStatus:
+    """Health status constants for validator responses."""
+
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+
+
+class BaseValidator(ABC):
+    """Abstract base class for all health validators.
+
+    Provides:
+    - Consistent error handling and logging
+    - Standard status/message return format
+    - Simplified subclass implementation (business logic only)
+
+    Subclasses should override:
+    - get_check_name(): Return the unique name of this check
+    - perform_check(): Return (status, message) tuple or raise exceptions
+
+    The check() method wraps perform_check() with try/except, logging,
+    and error handling so subclasses focus on business logic only.
+
+    Example:
+        class RoadmapDirectoryValidator(BaseValidator):
+            @staticmethod
+            def get_check_name() -> str:
+                return "roadmap_directory"
+
+            @staticmethod
+            def perform_check() -> Tuple[str, str]:
+                roadmap_dir = Path(".roadmap")
+                if not roadmap_dir.exists():
+                    return HealthStatus.DEGRADED, ".roadmap not found"
+
+                try:
+                    test_file = roadmap_dir / ".test"
+                    test_file.touch()
+                    test_file.unlink()
+                except OSError:
+                    return HealthStatus.DEGRADED, "Directory not writable"
+
+                return HealthStatus.HEALTHY, "Accessible and writable"
+
+        # Usage:
+        status, message = RoadmapDirectoryValidator.check()
+    """
+
+    @staticmethod
+    @abstractmethod
+    def get_check_name() -> str:
+        """Return the unique name of this check.
+
+        Returns:
+            Check name as string (e.g., "roadmap_directory", "git_repository")
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def perform_check() -> tuple[str, str]:
+        """Perform the actual check logic.
+
+        Should return a tuple of (status, message) where:
+        - status is one of: HealthStatus.HEALTHY, .DEGRADED, .UNHEALTHY
+        - message is a human-readable description
+
+        May raise exceptions for error conditions. The check() method
+        will catch them and return UNHEALTHY status.
+
+        Returns:
+            Tuple of (status, message)
+
+        Raises:
+            Any exception on error conditions (will be caught and logged)
+        """
+        pass
+
+    @classmethod
+    def check(cls) -> tuple[str, str]:
+        """Execute the check with standard error handling and logging.
+
+        Wraps perform_check() with:
+        - Exception handling
+        - Automatic logging at appropriate levels
+        - Error context enrichment
+        - Consistent status reporting
+
+        Returns:
+            Tuple of (status, message)
+        """
+        try:
+            status, message = cls.perform_check()
+            logger.debug(
+                "health_check_completed",
+                check_name=cls.get_check_name(),
+                status=status,
+            )
+            return status, message
+        except Exception as e:
+            logger.error(
+                "health_check_failed",
+                check_name=cls.get_check_name(),
+                error=str(e),
+                error_type=type(e).__name__,
+                severity="system_error",
+            )
+            return (
+                HealthStatus.UNHEALTHY,
+                f"Error checking {cls.get_check_name()}: {e}",
+            )

roadmap/core/services/validators/__init__.py

@@ -0,0 +1,28 @@
+"""Data integrity validators for health checks."""
+
+from ._utils import BackupScanResult, extract_issue_id
+from .archivable_issues_validator import ArchivableIssuesValidator
+from .archivable_milestones_validator import ArchivableMilestonesValidator
+from .backup_validator import BackupValidator
+from .data_integrity_validator import DataIntegrityValidator
+from .duplicate_issues_validator import DuplicateIssuesValidator
+from .duplicate_milestones_validator import DuplicateMilestonesValidator
+from .folder_structure_validator import FolderStructureValidator
+from .missing_headlines_validator import MissingHeadlinesValidator
+from .orphaned_issues_validator import OrphanedIssuesValidator
+from .orphaned_milestones_validator import OrphanedMilestonesValidator
+
+__all__ = [
+    "BackupScanResult",
+    "extract_issue_id",
+    "DuplicateIssuesValidator",
+    "DuplicateMilestonesValidator",
+    "FolderStructureValidator",
+    "BackupValidator",
+    "ArchivableIssuesValidator",
+    "ArchivableMilestonesValidator",
+    "DataIntegrityValidator",
+    "OrphanedIssuesValidator",
+    "OrphanedMilestonesValidator",
+    "MissingHeadlinesValidator",
+]

roadmap/core/services/validators/_utils.py

@@ -0,0 +1,20 @@
+"""Shared utilities for validators."""
+
+import re
+from typing import TypedDict
+
+
+class BackupScanResult(TypedDict):
+    """Type definition for backup scan results."""
+
+    files_to_delete: list[dict]
+    total_size_bytes: int
+
+
+def extract_issue_id(filename: str) -> str | None:
+    """Extract issue ID from filename (first part before the dashes and title).
+
+    Issue IDs are 8 hex characters.
+    """
+    match = re.match(r"^([a-f0-9]{8})", filename)
+    return match.group(1) if match else None

roadmap/core/services/validators/archivable_issues_validator.py

@@ -0,0 +1,71 @@
+"""Validator for archivable issues."""
+
+from roadmap.common.logging import get_logger
+from roadmap.common.utils.timezone_utils import now_utc
+from roadmap.core.services.validator_base import HealthStatus
+
+logger = get_logger(__name__)
+
+
+class ArchivableIssuesValidator:
+    """Validator for archivable issues."""
+
+    @staticmethod
+    def scan_for_archivable_issues(core, threshold_days: int = 30) -> list[dict]:
+        """Scan for issues that should be archived (closed >threshold_days ago).
+
+        Returns a list of issue dicts with id, title, status, closed date, and days_since_close.
+        """
+        archivable = []
+
+        try:
+            issues = core.issue_service.list_issues()
+            now = now_utc()
+
+            for issue in issues:
+                # Check if issue is closed (by status or by completed_date)
+                if issue.status.value == "closed" or issue.actual_end_date:
+                    close_date = issue.actual_end_date or now
+                    days_since_close = (now - close_date).days
+
+                    if days_since_close > threshold_days:
+                        archivable.append(
+                            {
+                                "id": issue.id,
+                                "title": issue.title,
+                                "status": issue.status.value,
+                                "closed_date": close_date.isoformat()
+                                if close_date
+                                else None,
+                                "days_since_close": days_since_close,
+                            }
+                        )
+        except Exception as e:
+            logger.debug("scan_archivable_issues_error", error=str(e))
+
+        return archivable
+
+    @staticmethod
+    def check_archivable_issues(core) -> tuple[str, str]:
+        """Check for archivable issues.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        try:
+            archivable = ArchivableIssuesValidator.scan_for_archivable_issues(core)
+
+            if not archivable:
+                logger.debug("health_check_archivable_issues", status="none")
+                return HealthStatus.HEALTHY, "No issues to archive"
+
+            message = (
+                f"ℹ️ {len(archivable)} issue(s) eligible for archival "
+                "(closed >30 days ago): Consider archiving old issues"
+            )
+            logger.info("health_check_archivable_issues", count=len(archivable))
+            return HealthStatus.DEGRADED, message
+
+        except Exception as e:
+            logger.debug("health_check_archivable_issues_failed", error=str(e))
+            return HealthStatus.HEALTHY, "Could not check for archivable issues"

roadmap/core/services/validators/archivable_milestones_validator.py

@@ -0,0 +1,69 @@
+"""Validator for archivable milestones."""
+
+from datetime import UTC, datetime
+
+from roadmap.common.logging import get_logger
+from roadmap.core.services.validator_base import HealthStatus
+
+logger = get_logger(__name__)
+
+
+class ArchivableMilestonesValidator:
+    """Validator for archivable milestones."""
+
+    @staticmethod
+    def scan_for_archivable_milestones(core, threshold_days: int = 14) -> list[dict]:
+        """Scan for milestones that should be archived (completed >threshold_days ago).
+
+        Returns a list of milestone dicts with name, status, closed date, issue count, and days_since_close.
+        """
+        archivable = []
+
+        try:
+            milestones = core.milestone_service.list_milestones()
+            now = datetime.now(UTC)
+
+            for milestone in milestones:
+                if milestone.status.value == "closed" and milestone.closed_at:
+                    days_since_close = (now - milestone.closed_at).days
+
+                    if days_since_close > threshold_days:
+                        archivable.append(
+                            {
+                                "name": milestone.name,
+                                "status": milestone.status.value,
+                                "closed_date": milestone.closed_at.isoformat(),
+                                "days_since_close": days_since_close,
+                            }
+                        )
+        except Exception as e:
+            logger.debug("scan_archivable_milestones_error", error=str(e))
+
+        return archivable
+
+    @staticmethod
+    def check_archivable_milestones(core) -> tuple[str, str]:
+        """Check for archivable milestones.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        try:
+            archivable = ArchivableMilestonesValidator.scan_for_archivable_milestones(
+                core
+            )
+
+            if not archivable:
+                logger.debug("health_check_archivable_milestones", status="none")
+                return HealthStatus.HEALTHY, "No milestones to archive"
+
+            message = (
+                f"ℹ️ {len(archivable)} milestone(s) eligible for archival "
+                "(closed >14 days ago): Consider archiving old milestones"
+            )
+            logger.info("health_check_archivable_milestones", count=len(archivable))
+            return HealthStatus.DEGRADED, message
+
+        except Exception as e:
+            logger.debug("health_check_archivable_milestones_failed", error=str(e))
+            return HealthStatus.HEALTHY, "Could not check for archivable milestones"

roadmap/core/services/validators/backup_validator.py

@@ -0,0 +1,89 @@
+"""Validator for old backup files."""
+
+from pathlib import Path
+
+from roadmap.common.logging import get_logger
+
+from . import BackupScanResult
+
+logger = get_logger(__name__)
+
+
+class BackupValidator:
+    """Validator for old backup files."""
+
+    @staticmethod
+    def scan_for_old_backups(backups_dir: Path, keep: int = 10) -> BackupScanResult:
+        """Scan for old backup files that could be deleted.
+
+        Returns a dict with:
+        - 'files_to_delete': List of backup files that exceed the keep threshold
+        - 'total_size_bytes': Total size of files that could be deleted (int)
+        """
+        result: BackupScanResult = {"files_to_delete": [], "total_size_bytes": 0}
+
+        if not backups_dir.exists():
+            return result
+
+        backup_files = list(backups_dir.glob("*.backup.md"))
+        if not backup_files:
+            return result
+
+        # Group backups by issue ID
+        backups_by_issue = {}
+        for backup_file in backup_files:
+            parts = backup_file.stem.split("_")
+            issue_key = "_".join(parts[:-1])
+
+            if issue_key not in backups_by_issue:
+                backups_by_issue[issue_key] = []
+
+            stat = backup_file.stat()
+            backups_by_issue[issue_key].append(
+                {
+                    "path": backup_file,
+                    "mtime": stat.st_mtime,
+                    "size": stat.st_size,
+                }
+            )
+
+        # Find files that exceed keep threshold
+        for _issue_key, backups in backups_by_issue.items():
+            backups.sort(key=lambda x: x["mtime"], reverse=True)
+
+            for idx, backup in enumerate(backups):
+                if idx >= keep:
+                    result["files_to_delete"].append(backup)
+                    result["total_size_bytes"] += backup["size"]
+
+        return result
+
+    @staticmethod
+    def check_old_backups() -> tuple[str, str]:
+        """Check for old backup files.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        try:
+            from roadmap.core.services.validator_base import HealthStatus
+
+            backups_dir = Path(".roadmap/backups")
+            old_backups = BackupValidator.scan_for_old_backups(backups_dir)
+
+            if not old_backups["files_to_delete"]:
+                logger.debug("health_check_old_backups", status="none")
+                return HealthStatus.HEALTHY, "No old backups to clean up"
+
+            count = len(old_backups["files_to_delete"])
+            size_mb = old_backups["total_size_bytes"] / (1024 * 1024)
+            message = (
+                f"ℹ️ {count} old backup file(s) could be deleted "
+                f"(~{size_mb:.1f} MB saved): Run 'roadmap cleanup' to remove"
+            )
+            logger.info("health_check_old_backups", count=count, size_mb=size_mb)
+            return HealthStatus.HEALTHY, message
+
+        except Exception as e:
+            logger.debug("health_check_old_backups_failed", error=str(e))
+            return HealthStatus.HEALTHY, "Could not check for old backups"

roadmap/core/services/validators/data_integrity_validator.py

@@ -0,0 +1,84 @@
+"""Validator for data integrity."""
+
+from pathlib import Path
+
+from roadmap.common.logging import get_logger
+from roadmap.core.services.validator_base import HealthStatus
+from roadmap.infrastructure.persistence_gateway import PersistenceGateway
+
+logger = get_logger(__name__)
+
+
+class DataIntegrityValidator:
+    """Validator for data integrity."""
+
+    @staticmethod
+    def scan_for_data_integrity_issues(
+        issues_dir: Path,
+    ) -> dict[str, list[str]]:
+        """Scan for data integrity issues (orphaned/missing files).
+
+        Returns a dict with:
+        - 'malformed_files': List of files that couldn't be parsed
+        """
+        result = {"malformed_files": []}
+
+        if not issues_dir.exists():
+            return result
+
+        # Scan all issue files recursively
+        for issue_file in issues_dir.rglob("*.md"):
+            if ".backup" in issue_file.name:
+                continue
+
+            try:
+                PersistenceGateway.parse_issue_file(issue_file)
+            except Exception:
+                # File couldn't be parsed
+                result["malformed_files"].append(
+                    str(issue_file.relative_to(issues_dir))
+                )
+
+        return result
+
+    @staticmethod
+    def check_data_integrity() -> tuple[str, str]:
+        """Check data integrity.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        try:
+            issues_dir = Path(".roadmap/issues")
+            if not issues_dir.exists():
+                return (
+                    HealthStatus.HEALTHY,
+                    "Issues directory not found (not initialized yet)",
+                )
+
+            integrity_issues = DataIntegrityValidator.scan_for_data_integrity_issues(
+                issues_dir
+            )
+
+            if not integrity_issues["malformed_files"]:
+                logger.debug("health_check_data_integrity", status="healthy")
+                return HealthStatus.HEALTHY, "No data integrity issues found"
+
+            message = (
+                f"⚠️ {len(integrity_issues['malformed_files'])} malformed file(s) detected: "
+                "These files couldn't be parsed - manual review required"
+            )
+            logger.warning(
+                "health_check_data_integrity",
+                count=len(integrity_issues["malformed_files"]),
+                severity="operational",
+            )
+            return HealthStatus.DEGRADED, message
+
+        except Exception as e:
+            logger.error(
+                "health_check_data_integrity_failed",
+                error=str(e),
+                severity="system_error",
+            )
+            return HealthStatus.UNHEALTHY, f"Error checking data integrity: {e}"