roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/health/health_check_service.py

@@ -0,0 +1,166 @@
+"""Health check service for roadmap CLI.
+
+This module handles system health checking and reporting, providing
+component status information and overall system health assessment.
+"""
+
+from typing import Any
+
+from roadmap.common.logging import get_logger
+from roadmap.core.domain.health import HealthStatus
+from roadmap.infrastructure.coordination.core import RoadmapCore
+from roadmap.infrastructure.observability.health import HealthCheck
+
+logger = get_logger(__name__)
+
+
+class HealthCheckService:
+    """Manages system health checks and reporting."""
+
+    def __init__(self, core: RoadmapCore):
+        """Initialize the service.
+
+        Args:
+            core: RoadmapCore instance
+        """
+        self.core = core
+
+    def run_all_checks(self) -> dict[str, tuple[HealthStatus, str]]:
+        """Run all system health checks.
+
+        Returns:
+            Dictionary mapping check names to (status, message) tuples
+        """
+        try:
+            checks = HealthCheck.run_all_checks(self.core)
+            logger.debug("health_checks_completed", check_count=len(checks))
+            return checks
+        except Exception as e:
+            logger.error("health_checks_failed", error=str(e), severity="system_error")
+            return {}
+
+    def get_overall_status(
+        self, checks: dict[str, tuple[HealthStatus, str]] | None = None
+    ) -> HealthStatus:
+        """Get overall system health status.
+
+        Args:
+            checks: Optional dict of checks. If None, runs checks first.
+
+        Returns:
+            Overall HealthStatus
+        """
+        try:
+            if checks is None:
+                checks = self.run_all_checks()
+
+            overall = HealthCheck.get_overall_status(checks)
+            logger.debug("overall_status_calculated", status=overall.value)
+            return overall
+        except Exception as e:
+            logger.error("overall_status_failed", error=str(e), severity="system_error")
+            return HealthStatus.UNHEALTHY
+
+    def get_check_status(self, check_name: str) -> tuple[HealthStatus, str] | None:
+        """Get status of a specific health check.
+
+        Args:
+            check_name: Name of the check to retrieve
+
+        Returns:
+            Tuple of (status, message) or None if check not found
+        """
+        try:
+            checks = self.run_all_checks()
+            return checks.get(check_name)
+        except Exception as e:
+            logger.error(
+                "get_check_status_failed",
+                check_name=check_name,
+                error=str(e),
+                severity="system_error",
+            )
+            return None
+
+    def get_health_summary(self) -> dict[str, Any]:
+        """Get comprehensive health summary.
+
+        Returns:
+            Dictionary with health summary data
+        """
+        try:
+            checks = self.run_all_checks()
+            overall_status = self.get_overall_status(checks)
+
+            healthy_count = sum(
+                1 for _, (status, _) in checks.items() if status == HealthStatus.HEALTHY
+            )
+            degraded_count = sum(
+                1
+                for _, (status, _) in checks.items()
+                if status == HealthStatus.DEGRADED
+            )
+            unhealthy_count = sum(
+                1
+                for _, (status, _) in checks.items()
+                if status == HealthStatus.UNHEALTHY
+            )
+
+            return {
+                "overall_status": overall_status.value,
+                "checks": checks,
+                "summary": {
+                    "total": len(checks),
+                    "healthy": healthy_count,
+                    "degraded": degraded_count,
+                    "unhealthy": unhealthy_count,
+                },
+            }
+        except Exception as e:
+            logger.error("health_summary_failed", error=str(e), severity="system_error")
+            return {"error": str(e)}
+
+    def is_healthy(self) -> bool:
+        """Check if system is in healthy state.
+
+        Returns:
+            True if overall status is HEALTHY
+        """
+        try:
+            overall_status = self.get_overall_status()
+            return overall_status == HealthStatus.HEALTHY
+        except Exception as e:
+            logger.error(
+                "is_healthy_check_failed", error=str(e), severity="system_error"
+            )
+            return False
+
+    def is_degraded(self) -> bool:
+        """Check if system is in degraded state.
+
+        Returns:
+            True if overall status is DEGRADED
+        """
+        try:
+            overall_status = self.get_overall_status()
+            return overall_status == HealthStatus.DEGRADED
+        except Exception as e:
+            logger.error(
+                "is_degraded_check_failed", error=str(e), severity="system_error"
+            )
+            return False
+
+    def is_unhealthy(self) -> bool:
+        """Check if system is in unhealthy state.
+
+        Returns:
+            True if overall status is UNHEALTHY
+        """
+        try:
+            overall_status = self.get_overall_status()
+            return overall_status == HealthStatus.UNHEALTHY
+        except Exception as e:
+            logger.error(
+                "is_unhealthy_check_failed", error=str(e), severity="system_error"
+            )
+            return True  # Fail safe: assume unhealthy on error

roadmap/core/services/health/health_models.py

@@ -0,0 +1,80 @@
+"""Shared health scanning models.
+
+Holds dataclasses and enums used by the various health scanners.
+"""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class EntityType(StrEnum):
+    """Types of entities that can be scanned."""
+
+    ISSUE = "issue"
+    MILESTONE = "milestone"
+    PROJECT = "project"
+
+
+class HealthSeverity(StrEnum):
+    """Severity levels for health issues."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass
+class HealthIssue:
+    """A single health issue found during scanning."""
+
+    code: str
+    message: str
+    severity: HealthSeverity
+    category: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EntityHealthReport:
+    """Health report for a single entity."""
+
+    entity_id: str
+    entity_type: EntityType
+    entity_title: str
+    status: str
+    issues: list[HealthIssue] = field(default_factory=list)
+
+    @property
+    def issue_count(self) -> int:
+        """Return the total number of health issues."""
+        return len(self.issues)
+
+    @property
+    def error_count(self) -> int:
+        """Return the count of error-severity health issues."""
+        return sum(1 for i in self.issues if i.severity == HealthSeverity.ERROR)
+
+    @property
+    def warning_count(self) -> int:
+        """Return the count of warning-severity health issues."""
+        return sum(1 for i in self.issues if i.severity == HealthSeverity.WARNING)
+
+    @property
+    def info_count(self) -> int:
+        """Return the count of info-severity health issues."""
+        return sum(1 for i in self.issues if i.severity == HealthSeverity.INFO)
+
+    @property
+    def is_healthy(self) -> bool:
+        """Check if entity is healthy (no errors or critical issues)."""
+        return not any(
+            i.severity in (HealthSeverity.ERROR, HealthSeverity.CRITICAL)
+            for i in self.issues
+        )
+
+    @property
+    def is_degraded(self) -> bool:
+        """Check if entity has any warnings."""
+        return any(i.severity == HealthSeverity.WARNING for i in self.issues)

roadmap/core/services/health/infrastructure_validator_service.py

@@ -0,0 +1,328 @@
+"""Infrastructure validators for health checks.
+
+Handles validation of:
+- Roadmap directory structure
+- State database file
+- Issues and milestones directories
+- Git repository status
+- Database integrity
+
+Uses BaseValidator abstract class to eliminate boilerplate and ensure
+consistent error handling and logging across all validators.
+"""
+
+from pathlib import Path
+
+import structlog
+
+from roadmap.common.logging import get_logger
+from roadmap.common.logging.error_logging import (
+    log_error_with_context,
+)
+from roadmap.common.observability.instrumentation import traced
+from roadmap.core.services.validator_base import BaseValidator, HealthStatus
+from roadmap.core.services.validators.health_status_utils import (
+    get_overall_status,
+)
+from roadmap.infrastructure.persistence_gateway import PersistenceGateway
+
+logger = structlog.get_logger()
+
+logger = get_logger(__name__)
+
+
+class RoadmapDirectoryValidator(BaseValidator):
+    """Validator for .roadmap directory."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the roadmap_directory check.
+        """
+        return "roadmap_directory"
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check if .roadmap directory exists and is accessible.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        roadmap_dir = Path(".roadmap")
+        if not roadmap_dir.exists():
+            return HealthStatus.DEGRADED, ".roadmap directory not initialized"
+
+        if not roadmap_dir.is_dir():
+            return (
+                HealthStatus.UNHEALTHY,
+                ".roadmap exists but is not a directory",
+            )
+
+        # Check if directory is writable
+        test_file = roadmap_dir / ".health_check"
+        try:
+            test_file.touch()
+            test_file.unlink()
+        except OSError as e:
+            logger.error(
+                "roadmap_dir_not_writable",
+                error=str(e),
+                action="check_writable",
+                severity="system_error",
+            )
+            return HealthStatus.DEGRADED, ".roadmap directory is not writable"
+
+        return (
+            HealthStatus.HEALTHY,
+            ".roadmap directory is accessible and writable",
+        )
+
+
+class StateFileValidator(BaseValidator):
+    """Validator for state database file."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the state_file check.
+        """
+        return "state_file"
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check if state database exists and is readable.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        state_db = Path(".roadmap/db/state.db")
+
+        if not state_db.exists():
+            return (
+                HealthStatus.DEGRADED,
+                "state.db not found (project not initialized)",
+            )
+
+        # Check if file is readable and has content
+        try:
+            size = state_db.stat().st_size
+            if size == 0:
+                return HealthStatus.DEGRADED, "state.db is empty"
+
+            # Try to open it to verify it's accessible
+            with open(state_db, "rb") as f:
+                f.read(16)  # Read SQLite header
+
+        except OSError as e:
+            return HealthStatus.UNHEALTHY, f"Cannot read state.db: {e}"
+
+        return HealthStatus.HEALTHY, "state.db is accessible and readable"
+
+
+class IssuesDirectoryValidator(BaseValidator):
+    """Validator for issues directory."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the issues_directory check.
+        """
+        return "issues_directory"
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check if issues directory exists and is accessible.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        issues_dir = Path(".roadmap/issues")
+
+        if not issues_dir.exists():
+            return HealthStatus.DEGRADED, "issues directory not found"
+
+        if not issues_dir.is_dir():
+            return (
+                HealthStatus.UNHEALTHY,
+                "issues path exists but is not a directory",
+            )
+
+        # Check if directory is readable
+        try:
+            list(issues_dir.iterdir())
+        except OSError as e:
+            return HealthStatus.UNHEALTHY, f"Cannot read issues directory: {e}"
+
+        return HealthStatus.HEALTHY, "issues directory is accessible"
+
+
+class MilestonesDirectoryValidator(BaseValidator):
+    """Validator for milestones directory."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the milestones_directory check.
+        """
+        return "milestones_directory"
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check if milestones directory exists and is accessible.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        milestones_dir = Path(".roadmap/milestones")
+
+        if not milestones_dir.exists():
+            return HealthStatus.DEGRADED, "milestones directory not found"
+
+        if not milestones_dir.is_dir():
+            return (
+                HealthStatus.UNHEALTHY,
+                "milestones path exists but is not a directory",
+            )
+
+        # Check if directory is readable
+        try:
+            list(milestones_dir.iterdir())
+        except OSError as e:
+            return (
+                HealthStatus.UNHEALTHY,
+                f"Cannot read milestones directory: {e}",
+            )
+
+        return HealthStatus.HEALTHY, "milestones directory is accessible"
+
+
+class GitRepositoryValidator(BaseValidator):
+    """Validator for git repository."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the git_repository check.
+        """
+        return "git_repository"
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check if Git repository exists and is accessible.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        git_dir = Path(".git")
+
+        if not git_dir.exists():
+            return (
+                HealthStatus.DEGRADED,
+                "not a Git repository (.git not found)",
+            )
+
+        if not git_dir.is_dir():
+            return (
+                HealthStatus.UNHEALTHY,
+                ".git exists but is not a directory",
+            )
+
+        return HealthStatus.HEALTHY, "Git repository is accessible"
+
+
+class DatabaseIntegrityValidator(BaseValidator):
+    """Validator for database integrity."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the database_integrity check.
+        """
+        return "database_integrity"
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check if database is accessible and can be queried.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        # Import here to avoid circular imports
+        try:
+            state_mgr = PersistenceGateway.get_state_manager()
+            # Try a simple query to verify DB is healthy
+            conn = state_mgr._get_connection()
+            conn.execute("SELECT 1")
+            return HealthStatus.HEALTHY, "Database is accessible and responsive"
+        except Exception as e:
+            return (
+                HealthStatus.UNHEALTHY,
+                f"Database query failed: {e}",
+            )
+
+
+class InfrastructureValidator:
+    """Orchestrator for infrastructure validation checks."""
+
+    def __init__(self):
+        """Initialize infrastructure validator."""
+        # Note: This service uses static methods from validators.
+        # Instance creation is kept for potential future stateful functionality.
+        pass
+
+    @traced("run_all_infrastructure_checks")
+    def run_all_infrastructure_checks(self) -> dict[str, tuple[str, str]]:
+        """Run all infrastructure validators.
+
+        Returns:
+            Dictionary mapping check names to (status, message) tuples
+        """
+        checks = {}
+
+        try:
+            checks["roadmap_directory"] = RoadmapDirectoryValidator.check()
+            checks["state_file"] = StateFileValidator.check()
+            checks["issues_directory"] = IssuesDirectoryValidator.check()
+            checks["milestones_directory"] = MilestonesDirectoryValidator.check()
+            checks["git_repository"] = GitRepositoryValidator.check()
+            checks["database_integrity"] = DatabaseIntegrityValidator.check()
+
+            return checks
+        except Exception as e:
+            log_error_with_context(
+                e,
+                operation="run_all_infrastructure_checks",
+                entity_type="Infrastructure",
+            )
+            logger.error(
+                "infrastructure_validation_failed",
+                error=str(e),
+                severity="system_error",
+            )
+            return {
+                "error": (
+                    HealthStatus.UNHEALTHY,
+                    f"Infrastructure validation failed: {e}",
+                )
+            }
+
+    @traced("get_overall_status")
+    def get_overall_status(self, checks: dict) -> str:
+        """Get overall status from all checks.
+
+        Returns:
+            Overall status: 'healthy', 'degraded', or 'unhealthy'
+        """
+        return get_overall_status(checks)