roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/github/github_issue_client.py

@@ -0,0 +1,346 @@
+"""GitHub issue client service for roadmap application.
+
+This module handles fetching and syncing GitHub issues with internal roadmap issues.
+It provides a simple interface for GitHub issue operations without requiring a
+GitHub repository to be configured.
+"""
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from roadmap.adapters.github.handlers.base import GitHubAPIError
+from roadmap.common.logging import get_logger
+from roadmap.common.logging.error_logging import (
+    log_external_service_error,
+    log_validation_error,
+)
+from roadmap.common.observability.instrumentation import traced
+from roadmap.infrastructure.github_gateway import GitHubGateway
+
+if TYPE_CHECKING:
+    from roadmap.core.interfaces import GitHubBackendInterface  # noqa: F401
+
+logger = get_logger(__name__)
+
+
+class GitHubIssueClient:
+    """Client for fetching and managing GitHub issues.
+
+    This client allows operations on GitHub issues without requiring
+    owner/repo configuration upfront. Configuration can be provided
+    per-request or via environment variables.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        github_backend: "GitHubBackendInterface | None" = None,
+    ):
+        """Initialize GitHub issue client.
+
+        Args:
+            token: Optional GitHub personal access token.
+                  If not provided, will look for GITHUB_TOKEN environment variable.
+            github_backend: Optional GitHub backend interface. If not provided,
+                           will create GitHubBackendAdapter instances per-request.
+
+        Raises:
+            GitHubAPIError: If no token is available
+        """
+        self.token = token or os.getenv("GITHUB_TOKEN")
+        if not self.token:
+            raise GitHubAPIError(
+                "GitHub token is required. Set GITHUB_TOKEN environment variable "
+                "or provide token to GitHubIssueClient."
+            )
+        self._github_backend = github_backend
+        logger.debug("github_issue_client_initialized")
+
+    @traced("fetch_issue")
+    def fetch_issue(self, owner: str, repo: str, issue_number: int) -> dict[str, Any]:
+        """Fetch a GitHub issue by number.
+
+        Args:
+            owner: Repository owner (username or organization)
+            repo: Repository name
+            issue_number: GitHub issue number (must be positive integer)
+
+        Returns:
+            Dictionary with issue details:
+                - number: Issue number
+                - title: Issue title
+                - body: Issue description
+                - state: 'open' or 'closed'
+                - labels: List of label names
+                - assignees: List of assignee usernames
+                - milestone: Milestone title or None
+                - url: GitHub issue URL
+                - created_at: ISO format timestamp
+                - updated_at: ISO format timestamp
+
+        Raises:
+            GitHubAPIError: If issue not found or API error occurs
+            ValueError: If issue_number is invalid
+        """
+        logger.info(
+            "fetching_github_issue", owner=owner, repo=repo, number=issue_number
+        )
+
+        try:
+            # Use injected backend or create adapter on-demand
+            if self._github_backend is None:
+                client = GitHubGateway.get_github_client(
+                    {"token": self.token, "owner": owner, "repo": repo}
+                )
+                issue_data = client.fetch_issue(issue_number)
+            else:
+                issue_data = self._github_backend.get_issue(str(issue_number))
+
+            logger.debug("github_issue_fetched_successfully", number=issue_number)
+            return issue_data if isinstance(issue_data, dict) else {}
+        except ValueError as e:
+            log_validation_error(
+                e,
+                entity_type="GitHubIssue",
+                field_name="issue_number",
+                proposed_value=issue_number,
+            )
+            logger.warning(
+                "invalid_github_issue_number", error=str(e), severity="data_error"
+            )
+            raise
+        except GitHubAPIError as e:
+            log_external_service_error(
+                e,
+                service_name="GitHub",
+                operation="fetch_issue",
+            )
+            logger.warning(
+                "github_issue_fetch_failed", error=str(e), severity="infrastructure"
+            )
+            raise
+
+    @traced("validate_token")
+    def validate_token(self) -> tuple[bool, str]:
+        """Validate GitHub token by making a test API call.
+
+        Returns:
+            Tuple of (is_valid, message)
+            - (True, "Token is valid (authenticated as USERNAME)") if successful
+            - (False, error_message) if invalid or error
+        """
+        logger.info("validating_github_token")
+        try:
+            # Create a backend adapter with minimal configuration (needs owner/repo for initialization)
+            # We'll use a dummy repo for validation since we only care about authentication
+            client = GitHubGateway.get_github_client(
+                {"token": self.token, "owner": "dummy", "repo": "dummy"}
+            )
+            is_valid, message = client.validate_github_token()
+
+            if is_valid:
+                logger.debug("github_token_validated", authenticated_user=message)
+            else:
+                logger.warning(
+                    "github_token_validation_failed",
+                    error_message=message,
+                    severity="config_error",
+                )
+            return is_valid, message
+        except GitHubAPIError as e:
+            log_external_service_error(
+                e,
+                service_name="GitHub",
+                operation="validate_token",
+            )
+            return False, str(e)
+
+    @traced("issue_exists")
+    def issue_exists(self, owner: str, repo: str, issue_number: int) -> bool:
+        """Check if a GitHub issue exists.
+
+        Args:
+            owner: Repository owner (username or organization)
+            repo: Repository name
+            issue_number: GitHub issue number
+
+        Returns:
+            True if issue exists, False otherwise
+        """
+        logger.info(
+            "checking_github_issue_exists", owner=owner, repo=repo, number=issue_number
+        )
+        try:
+            self.fetch_issue(owner, repo, issue_number)
+            logger.debug("github_issue_exists", number=issue_number)
+            return True
+        except GitHubAPIError:
+            logger.debug("github_issue_does_not_exist", number=issue_number)
+            return False
+
+    @traced("get_issue_diff")
+    def get_issue_diff(
+        self,
+        owner: str,
+        repo: str,
+        issue_number: int,
+        local_data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Get differences between local issue data and GitHub issue.
+
+        Args:
+            owner: Repository owner
+            repo: Repository name
+            issue_number: GitHub issue number
+            local_data: Local issue data to compare (keys: title, body, state, labels, assignees)
+
+        Returns:
+            Dictionary with changes:
+                - has_changes: bool
+                - title_changed: bool (if different)
+                - body_changed: bool (if different)
+                - state_changed: bool (if different)
+                - labels_changed: bool (if different)
+                - assignees_changed: bool (if different)
+                - github_data: dict with full GitHub issue data
+                - changes: dict with field-level details
+
+        Raises:
+            GitHubAPIError: If issue fetch fails
+        """
+        logger.info(
+            "comparing_issue_with_github", owner=owner, repo=repo, number=issue_number
+        )
+
+        github_data = self.fetch_issue(owner, repo, issue_number)
+
+        changes = {}
+        has_changes = False
+
+        # Compare fields
+        fields_to_compare = ["title", "body", "state"]
+        for field in fields_to_compare:
+            local_value = local_data.get(field, "")
+            github_value = github_data.get(field, "")
+            if local_value != github_value:
+                changes[field] = {
+                    "local": local_value,
+                    "github": github_value,
+                    "changed": True,
+                }
+                has_changes = True
+
+        # Compare lists (labels, assignees)
+        for field in ["labels", "assignees"]:
+            local_value = sorted(set(local_data.get(field, [])))
+            github_value = sorted(set(github_data.get(field, [])))
+            if local_value != github_value:
+                changes[field] = {
+                    "local": local_value,
+                    "github": github_value,
+                    "changed": True,
+                }
+                has_changes = True
+
+        result = {
+            "has_changes": has_changes,
+            "github_data": github_data,
+            "changes": changes,
+        }
+
+        logger.debug(
+            "issue_diff_computed", has_changes=has_changes, fields_changed=len(changes)
+        )
+        return result
+
+    @traced("get_issues")
+    def get_issues(
+        self,
+        owner: str,
+        repo: str,
+        state: str = "all",
+        labels: list[str] | None = None,
+        milestone: str | None = None,
+        assignee: str | None = None,
+        per_page: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Get issues from a GitHub repository.
+
+        Args:
+            owner: Repository owner (username or organization)
+            repo: Repository name
+            state: Issue state filter ('open', 'closed', 'all')
+            labels: Optional list of label names to filter by
+            milestone: Optional milestone title to filter by
+            assignee: Optional assignee username to filter by
+            per_page: Number of issues per page (max 100)
+
+        Returns:
+            List of issue dictionaries from GitHub API
+
+        Raises:
+            GitHubAPIError: If API call fails
+        """
+        logger.info(
+            "fetching_github_issues",
+            owner=owner,
+            repo=repo,
+            state=state,
+            limit=per_page,
+        )
+
+        try:
+            # Use injected backend or create adapter on-demand
+            if self._github_backend is None:
+                client = GitHubGateway.get_github_client(
+                    {"token": self.token, "owner": owner, "repo": repo}
+                )
+                issues_data = client.get_issues(
+                    state, labels, milestone, assignee, per_page
+                )
+            else:
+                # If backend provided, use it - backend get_issues() takes no parameters
+                if hasattr(self._github_backend, "get_issues"):
+                    all_issues = self._github_backend.get_issues()
+                    # Filter results if needed (backend returns all issues)
+                    issues_data = (
+                        all_issues
+                        if isinstance(all_issues, list)
+                        else list(all_issues.values())
+                        if isinstance(all_issues, dict)
+                        else []
+                    )
+                else:
+                    issues_data = []
+
+            logger.debug(
+                "github_issues_fetched",
+                owner=owner,
+                repo=repo,
+                count=len(issues_data or []),
+            )
+            return issues_data if isinstance(issues_data, list) else []
+
+        except GitHubAPIError as e:
+            log_external_service_error(
+                e,
+                service_name="GitHub",
+                operation="get_issues",
+            )
+            logger.warning(
+                "github_issues_fetch_failed", error=str(e), severity="infrastructure"
+            )
+            raise
+        except Exception as e:
+            log_external_service_error(
+                e,
+                service_name="GitHub",
+                operation="get_issues",
+            )
+            logger.error(
+                "github_issues_fetch_error",
+                error=str(e),
+                error_type=type(e).__name__,
+                severity="infrastructure",
+            )
+            raise GitHubAPIError(f"Failed to fetch issues: {str(e)}") from e

roadmap/core/services/health/__init__.py

@@ -0,0 +1 @@
+"""Package initialization file."""

roadmap/core/services/health/backup_cleanup_service.py

@@ -0,0 +1,202 @@
+"""Service for cleaning up old backup files."""
+
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import TypedDict
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class BackupInfo(TypedDict):
+    """Information about a backup file."""
+
+    path: Path
+    mtime: datetime
+    size: int
+
+
+class BackupCleanupResult:
+    """Result of backup cleanup operation."""
+
+    def __init__(self):
+        """Initialize BackupCleanupResult."""
+        self.deleted_count: int = 0
+        self.failed_count: int = 0
+        self.total_freed_bytes: int = 0
+        self.files_deleted: list[Path] = []
+        self.files_failed: list[tuple[Path, str]] = []
+
+    def add_deleted(self, path: Path, size: int) -> None:
+        """Record a deleted file."""
+        self.deleted_count += 1
+        self.total_freed_bytes += size
+        self.files_deleted.append(path)
+
+    def add_failed(self, path: Path, error: str) -> None:
+        """Record a file that failed to delete."""
+        self.failed_count += 1
+        self.files_failed.append((path, error))
+
+    @property
+    def freed_mb(self) -> float:
+        """Get freed space in MB."""
+        return self.total_freed_bytes / (1024 * 1024)
+
+
+class BackupCleanupService:
+    """Cleans up old backup files based on age and count."""
+
+    def cleanup_backups(
+        self,
+        roadmap_dir: Path,
+        keep: int = 10,
+        days: int | None = None,
+        dry_run: bool = False,
+    ) -> BackupCleanupResult:
+        """Clean up old backup files.
+
+        Args:
+            roadmap_dir: Roadmap directory
+            keep: Number of most recent backups to keep per issue
+            days: Delete backups older than this many days
+            dry_run: If True, don't delete files
+
+        Returns:
+            BackupCleanupResult with deletion statistics
+        """
+        backups_dir = roadmap_dir / "backups"
+        result = BackupCleanupResult()
+
+        if not backups_dir.exists():
+            logger.info("No backups directory found")
+            return result
+
+        # Get files to delete
+        files_to_delete = self._select_backups_for_deletion(backups_dir, keep, days)
+
+        if not files_to_delete:
+            logger.info("No backups to clean up")
+            return result
+
+        # Dry run: just record what would be deleted
+        if dry_run:
+            for backup in files_to_delete:
+                result.add_deleted(backup["path"], backup["size"])
+            logger.info(
+                "Dry run: would delete backups",
+                count=len(files_to_delete),
+                freed_mb=result.freed_mb,
+            )
+            return result
+
+        # Actually delete files
+        for backup in files_to_delete:
+            try:
+                backup["path"].unlink()
+                result.add_deleted(backup["path"], backup["size"])
+                logger.info("Deleted backup file", file=backup["path"].name)
+            except Exception as e:
+                result.add_failed(backup["path"], str(e))
+                logger.warning(
+                    "Failed to delete backup",
+                    file=backup["path"].name,
+                    error=str(e),
+                    severity="operational",
+                )
+
+        return result
+
+    @staticmethod
+    @staticmethod
+    def _group_backups_by_issue(
+        backup_files: list[Path],
+    ) -> dict[str, list[BackupInfo]]:
+        """Group backup files by issue ID.
+
+        Args:
+            backup_files: List of backup file paths
+
+        Returns:
+            Dict of issue_key -> list of BackupInfo
+        """
+        backups_by_issue: dict[str, list[BackupInfo]] = {}
+        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": datetime.fromtimestamp(stat.st_mtime, tz=UTC),
+                    "size": stat.st_size,
+                }
+            )
+
+        return backups_by_issue
+
+    @staticmethod
+    def _should_delete_backup(
+        idx: int, backup: BackupInfo, keep: int, cutoff_date: datetime | None
+    ) -> bool:
+        """Determine if backup should be deleted.
+
+        Args:
+            idx: Index in sorted backup list
+            backup: Backup info dict
+            keep: Keep this many most recent backups
+            cutoff_date: Delete backups older than this date
+
+        Returns:
+            True if backup should be deleted
+        """
+        # Delete if beyond keep count
+        if idx >= keep:
+            return True
+
+        # Delete if older than cutoff
+        if cutoff_date and backup["mtime"] < cutoff_date:
+            return True
+
+        return False
+
+    @staticmethod
+    def _select_backups_for_deletion(
+        backups_dir: Path, keep: int, days: int | None
+    ) -> list[BackupInfo]:
+        """Select backup files to delete based on age and count.
+
+        Args:
+            backups_dir: Directory containing backup files
+            keep: Keep this many most recent backups per issue
+            days: Delete backups older than this many days
+
+        Returns:
+            List of BackupInfo dicts for files to delete
+        """
+        backup_files = list(backups_dir.glob("*.backup.md"))
+        if not backup_files:
+            return []
+
+        # Group backups by issue ID
+        backups_by_issue = BackupCleanupService._group_backups_by_issue(backup_files)
+
+        # Determine files to delete
+        files_to_delete: list[BackupInfo] = []
+        cutoff_date = datetime.now(UTC) - timedelta(days=days) if days else None
+
+        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 BackupCleanupService._should_delete_backup(
+                    idx, backup, keep, cutoff_date
+                ):
+                    files_to_delete.append(backup)
+
+        return files_to_delete

roadmap/core/services/health/data_integrity_validator_service.py

@@ -0,0 +1,90 @@
+"""Data integrity validator service orchestrator.
+
+Coordinates all data integrity validators and provides a unified interface
+for running health checks across the system.
+"""
+
+from roadmap.common.logging import get_logger
+from roadmap.core.services.validator_base import HealthStatus
+from roadmap.core.services.validators import (
+    ArchivableIssuesValidator,
+    ArchivableMilestonesValidator,
+    BackupValidator,
+    DataIntegrityValidator,
+    DuplicateIssuesValidator,
+    DuplicateMilestonesValidator,
+    FolderStructureValidator,
+    OrphanedIssuesValidator,
+    OrphanedMilestonesValidator,
+)
+from roadmap.core.services.validators import (
+    __all__ as _validators_all,
+)
+from roadmap.core.services.validators.health_status_utils import (
+    get_overall_status,
+)
+
+logger = get_logger(__name__)
+
+# Re-export validators for backward compatibility - use same list as validators module
+_exported_validators: list[str] = (
+    list(_validators_all) if isinstance(_validators_all, list | tuple) else []
+)
+__all__ = ["DataIntegrityValidatorService"] + _exported_validators  # type: ignore[operator]
+
+
+class DataIntegrityValidatorService:
+    """Orchestrator for data integrity validation checks."""
+
+    def __init__(self):
+        """Initialize data integrity validator service."""
+        # Note: This service uses static methods from validators.
+        # Instance creation is kept for potential future stateful functionality.
+        pass
+
+    def run_all_data_integrity_checks(self, core) -> dict[str, tuple[str, str]]:
+        """Run all data integrity checks.
+
+        Returns:
+            Dictionary mapping check names to (status, message) tuples
+        """
+        checks = {}
+
+        try:
+            checks["duplicate_issues"] = DuplicateIssuesValidator.perform_check()
+            checks["duplicate_milestones"] = (
+                DuplicateMilestonesValidator.perform_check()
+            )
+            checks["folder_structure"] = FolderStructureValidator.perform_check()
+            checks["old_backups"] = BackupValidator.check_old_backups()
+            checks["archivable_issues"] = (
+                ArchivableIssuesValidator.check_archivable_issues(core)
+            )
+            checks["archivable_milestones"] = (
+                ArchivableMilestonesValidator.check_archivable_milestones(core)
+            )
+            checks["data_integrity"] = DataIntegrityValidator.check_data_integrity()
+            checks["orphaned_issues"] = OrphanedIssuesValidator.check_orphaned_issues(
+                core
+            )
+            checks["orphaned_milestones"] = OrphanedMilestonesValidator.perform_check()
+
+            return checks
+        except Exception as e:
+            logger.error(
+                "data_integrity_validation_failed", error=str(e), severity="data_error"
+            )
+            return {
+                "error": (
+                    HealthStatus.UNHEALTHY,
+                    f"Data integrity validation failed: {e}",
+                )
+            }
+
+    def get_overall_status(self, checks: dict[str, tuple[str, str]]) -> str:
+        """Get overall status from all data integrity checks.
+
+        Returns:
+            Overall status: 'healthy', 'degraded', or 'unhealthy'
+        """
+        return get_overall_status(checks)