roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/sync/backends/github_sync_backend.py

@@ -0,0 +1,792 @@
+"""GitHub-specific implementation of SyncBackendInterface.
+
+This module provides the GitHub API backend for syncing roadmap issues
+with GitHub repositories. It implements the SyncBackendInterface protocol.
+
+Updated to use Result<T, SyncError> pattern for explicit error handling.
+"""
+
+import time
+from collections.abc import Callable
+from datetime import datetime  # noqa: F401  # Used in type hints
+from typing import Any, TypeVar
+
+from structlog import get_logger
+
+from roadmap.adapters.sync.backends.github_backend_helpers import GitHubBackendHelpers
+from roadmap.adapters.sync.backends.github_client import GitHubClientWrapper
+from roadmap.adapters.sync.backends.services.github_authentication_service import (
+    GitHubAuthenticationService,
+)
+from roadmap.adapters.sync.backends.services.github_issue_delete_service import (
+    GitHubIssueDeleteService,
+)
+from roadmap.adapters.sync.backends.services.github_issue_fetch_service import (
+    GitHubIssueFetchService,
+)
+from roadmap.common.result import Err, Ok, Result
+from roadmap.core.domain.issue import Issue
+from roadmap.core.interfaces import (
+    SyncConflict,
+    SyncReport,
+)
+from roadmap.core.models.sync_models import (
+    SyncIssue,
+    SyncMilestone,
+    SyncProject,
+)
+from roadmap.core.services.sync.sync_errors import (
+    SyncError,
+    SyncErrorType,
+    authentication_error,
+)
+from roadmap.core.services.sync.sync_metadata_service import SyncMetadataService
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+logger = get_logger()
+
+T = TypeVar("T")
+
+
+class GitHubSyncBackend:
+    """GitHub API implementation of the SyncBackendInterface.
+
+    Syncs roadmap issues with GitHub issues using the GitHub REST API.
+    Requires a GitHub Personal Access Token with 'repo' scope.
+
+    Attributes:
+        core: RoadmapCore instance with access to local issues
+        config: GitHub configuration with 'owner', 'repo', 'token'
+        github_client: GitHubIssueClient for API communication
+    """
+
+    def __init__(self, core: RoadmapCore, config: dict[str, Any]):
+        """Initialize GitHub sync backend.
+
+        Args:
+            core: RoadmapCore instance
+            config: Dict with required keys:
+                - owner: GitHub repository owner
+                - repo: GitHub repository name
+                - token: GitHub Personal Access Token (optional, checked at auth time)
+
+        Raises:
+            ValueError: If required config keys are missing
+        """
+        if not config.get("owner") or not config.get("repo"):
+            raise ValueError("GitHub config must include 'owner' and 'repo'")
+
+        self.core = core
+        self.config = config
+
+        # Initialize GitHub client if token is provided, otherwise defer to authenticate()
+        token = config.get("token")
+        owner = config.get("owner")
+        repo = config.get("repo")
+        self.github_client = self._safe_init(
+            lambda: GitHubClientWrapper(token, owner, repo) if token else None,
+            "GitHubClientWrapper",
+        )
+
+        # Initialize metadata service if available
+        self.metadata_service = self._safe_init(
+            lambda: SyncMetadataService(core),
+            "SyncMetadataService",
+        )
+
+        # Initialize remote link repository if available
+        # This enables fast database lookups during sync operations
+        self.remote_link_repo = None
+        if (
+            hasattr(core, "db")
+            and core.db is not None
+            and hasattr(core.db, "remote_links")
+        ):
+            self.remote_link_repo = core.db.remote_links
+
+        # Helper utilities extracted for mapping and local persistence
+        self._helpers = GitHubBackendHelpers(
+            core=self.core, remote_link_repo=self.remote_link_repo
+        )
+
+        # Initialize delegated services
+        self._auth_service = GitHubAuthenticationService(config)
+        self._fetch_service = None  # Initialized lazily after auth
+        self._issue_delete_service = GitHubIssueDeleteService(config)
+
+    def _safe_init(self, factory: Callable[[], T], name: str) -> T | None:
+        """Safely initialize a component, returning None on failure.
+
+        Args:
+            factory: Callable that returns the initialized component
+            name: Component name for logging
+
+        Returns:
+            Initialized component or None if initialization fails
+        """
+        try:
+            return factory()
+        except (ImportError, AttributeError) as e:
+            logger.warning(
+                "initialization_failed",
+                component=name,
+                error=str(e),
+                error_type=type(e).__name__,
+                suggested_action="check_dependencies",
+            )
+            return None
+        except Exception as e:
+            logger.warning(
+                "initialization_failed",
+                component=name,
+                error=str(e),
+                error_type=type(e).__name__,
+                error_classification="unknown_error",
+            )
+            return None
+
+    def get_backend_name(self) -> str:
+        """Get the canonical name of this backend.
+
+        Returns:
+            'github' - used as key in Issue.remote_ids dict
+        """
+        return "github"
+
+    def authenticate(self) -> Result[bool, SyncError]:
+        """Verify credentials and remote connectivity.
+
+        Returns:
+            Ok(True) if authentication succeeds (token valid and repo accessible)
+            Err(SyncError) with authentication error details
+        """
+        try:
+            result = self._auth_service.authenticate()
+            if result and self.github_client is None:
+                # Update our client reference after successful auth
+                self.github_client = self._auth_service.github_client
+
+            if result:
+                return Ok(True)
+            else:
+                return Err(authentication_error("GitHub authentication failed"))
+        except Exception as e:
+            logger.error(
+                "github_authenticate_exception",
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            return Err(
+                SyncError.from_exception(
+                    e,
+                    error_type=SyncErrorType.AUTHENTICATION_FAILED,
+                )
+            )
+
+    def get_api_client(self) -> Any:
+        """Get the GitHub API client with handler methods for push/pull operations.
+
+        Returns:
+            IssueHandler instance with create_issue(), update_issue(), etc. methods.
+
+        This method is used internally by GitHubSyncOps for actual API calls.
+        It ensures operations use the proper handler-based client for low-level
+        API operations, not the high-level GitHubClient wrapper.
+        """
+        import requests
+
+        from roadmap.adapters.github.handlers.issues import IssueHandler
+
+        # Create a session with the token
+        session = requests.Session()
+        token = self.config.get("token")
+        if token:
+            session.headers.update(
+                {
+                    "Authorization": f"token {token}",
+                    "Accept": "application/vnd.github.v3+json",
+                    "User-Agent": "roadmap-cli/1.0",
+                }
+            )
+
+        # Return a properly configured issue handler for API calls
+        return IssueHandler(
+            session=session,
+            owner=self.config.get("owner"),
+            repo=self.config.get("repo"),
+        )
+
+    def get_label_client(self) -> Any | None:
+        """Get a GitHub client that supports label operations."""
+        token = self.config.get("token")
+        if not token:
+            return None
+
+        from roadmap.adapters.github.github import GitHubClient
+
+        return GitHubClient(
+            token=token,
+            owner=self.config.get("owner"),
+            repo=self.config.get("repo"),
+        )
+
+    def get_issues(self) -> Result[dict[str, SyncIssue], SyncError]:
+        """Fetch all issues from GitHub remote.
+
+        Returns:
+            Ok(dict) mapping issue_id -> SyncIssue objects on success
+            Err(SyncError) with error details on failure
+        """
+        try:
+            # Lazily initialize fetch service after first auth
+            if self._fetch_service is None and self.github_client:
+                self._fetch_service = GitHubIssueFetchService(
+                    self.github_client, self.config, self._helpers
+                )
+
+            if self._fetch_service is None:
+                logger.warning("github_fetch_service_not_initialized")
+                return Err(
+                    SyncError(
+                        error_type=SyncErrorType.AUTHENTICATION_FAILED,
+                        message="GitHub fetch service not initialized - authenticate first",
+                        suggested_fix="Call authenticate() before get_issues()",
+                    )
+                )
+
+            issues = self._fetch_service.get_issues()
+            return Ok(issues)
+        except Exception as e:
+            logger.error(
+                "github_get_issues_exception",
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            return Err(
+                SyncError.from_exception(
+                    e,
+                    error_type=SyncErrorType.NETWORK_ERROR,
+                )
+            )
+
+    def push_issues(self, local_issues: list[Issue]) -> Result[SyncReport, SyncError]:
+        """Push multiple local issues to GitHub.
+
+        Args:
+            local_issues: List of Issue objects to push
+
+        Returns:
+            Ok(SyncReport) with pushed, conflicts, and errors on success
+            Err(SyncError) with fatal error details if operation cannot proceed
+        """
+        try:
+            # Delegate orchestration to helper class
+            from roadmap.adapters.sync.backends.github_sync_ops import GitHubSyncOps
+
+            ops = GitHubSyncOps(self)
+            report = ops.push_issues(local_issues)
+            return Ok(report)
+        except Exception as e:
+            logger.error(
+                "github_push_issues_exception",
+                error=str(e),
+                error_type=type(e).__name__,
+                issue_count=len(local_issues),
+            )
+            return Err(
+                SyncError.from_exception(
+                    e,
+                    error_type=SyncErrorType.UNKNOWN_ERROR,
+                    entity_type="Issue",
+                )
+            )
+
+    def push_issue(self, local_issue: Issue) -> Result[bool, SyncError]:
+        """Push a single local issue to GitHub.
+
+        Args:
+            local_issue: The Issue object to push
+
+        Returns:
+            Ok(True) if push succeeds
+            Err(SyncError) with error details if push fails
+
+        Deprecated:
+            Use push_issues([issue]) instead. This method exists for backward
+            compatibility but is not used by the sync orchestrator.
+        """
+        report_result = self.push_issues([local_issue])
+        if report_result.is_err():
+            return report_result  # type: ignore[return-value]
+
+        report = report_result.unwrap()
+        if len(report.pushed) > 0 and len(report.errors) == 0:
+            return Ok(True)
+        else:
+            error_msg = report.errors.get(str(local_issue.id), "Push failed")
+            return Err(
+                SyncError(
+                    error_type=SyncErrorType.UNKNOWN_ERROR,
+                    message=error_msg,
+                    entity_type="Issue",
+                    entity_id=str(local_issue.id),
+                )
+            )
+
+    def pull_issues(self, issue_ids: list[str]) -> Result[SyncReport, SyncError]:
+        """Pull specified remote GitHub issues to local.
+
+        Args:
+            issue_ids: List of remote issue IDs to pull
+
+        Returns:
+            Ok(SyncReport) with pulled, conflicts, and errors on success
+            Err(SyncError) with fatal error details if operation cannot proceed
+
+        Notes:
+            - Each ID should correspond to a remote issue
+            - Updates or creates local files as needed
+            - Uses parallel execution with thread pool for performance
+        """
+        try:
+            from roadmap.adapters.sync.backends.github_sync_ops import GitHubSyncOps
+
+            ops = GitHubSyncOps(self)
+            report = ops.pull_issues(issue_ids)
+            return Ok(report)
+        except Exception as e:
+            logger.error(
+                "github_pull_issues_exception",
+                error=str(e),
+                error_type=type(e).__name__,
+                issue_count=len(issue_ids),
+            )
+            return Err(
+                SyncError.from_exception(
+                    e,
+                    error_type=SyncErrorType.UNKNOWN_ERROR,
+                    entity_type="Issue",
+                )
+            )
+
+    def pull_milestones(self, milestone_ids: list[str]) -> SyncReport:
+        """Pull specified remote GitHub milestones to local.
+
+        Args:
+            milestone_ids: List of remote milestone IDs to pull (GitHub milestone numbers)
+
+        Returns:
+            SyncReport with pulled, conflicts, and errors.
+        """
+        from roadmap.adapters.sync.backends.github_sync_ops import GitHubSyncOps
+
+        ops = GitHubSyncOps(self)
+        return ops.pull_milestones(milestone_ids)
+
+    def push_milestones(self, local_milestones: list) -> SyncReport:
+        """Push multiple local milestones to GitHub.
+
+        Args:
+            local_milestones: List of Milestone objects to push
+
+        Returns:
+            SyncReport with pushed, conflicts, and errors.
+
+        Note:
+            Currently not implemented - milestones must be created on GitHub first.
+        """
+        from roadmap.adapters.sync.backends.github_sync_ops import GitHubSyncOps
+
+        ops = GitHubSyncOps(self)
+        return ops.push_milestones(local_milestones)
+
+    def pull_issue(self, issue_id: str) -> Result[bool, SyncError]:
+        """Pull a single remote GitHub issue to local.
+
+        Args:
+            issue_id: The remote issue ID (GitHub issue number like "_remote_123" or "123")
+
+        Returns:
+            Ok(True) if issue is valid and can be pulled
+            Err(SyncError) if error during validation
+
+        Notes:
+            - Validates the issue_id can be parsed
+            - Actual fetching/saving is handled by pull_issues caller
+            - Returns Ok(True) to indicate success to GitHubSyncOps
+        """
+        try:
+            # Parse issue_id - extract numeric part from "_remote_123" format
+            if issue_id.startswith("_remote_"):
+                issue_num_str = issue_id[8:]  # Remove "_remote_" prefix
+            else:
+                issue_num_str = issue_id
+
+            # Validate it's a valid integer
+            try:
+                int(issue_num_str)
+            except (ValueError, TypeError):
+                logger.debug(
+                    "pull_issue_invalid_id",
+                    issue_id=issue_id,
+                    reason="Cannot parse as integer",
+                )
+                return Err(
+                    SyncError(
+                        error_type=SyncErrorType.VALIDATION_ERROR,
+                        message=f"Invalid issue ID format: {issue_id}",
+                        suggested_fix="Ensure issue_id is a valid number",
+                    )
+                )
+
+            # If we got here, the issue_id is valid
+            # The actual pull work happens elsewhere in the sync pipeline
+            return Ok(True)
+
+        except Exception as e:
+            logger.debug(
+                "pull_issue_validation_failed",
+                issue_id=issue_id,
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            return Err(
+                SyncError.from_exception(
+                    e,
+                    error_type=SyncErrorType.VALIDATION_ERROR,
+                )
+            )
+
+    def _convert_sync_to_issue(self, issue_id: str, sync_issue: SyncIssue) -> "Issue":
+        """Convert SyncIssue to local Issue object.
+
+        Args:
+            issue_id: Local issue ID
+            sync_issue: SyncIssue with remote data
+
+        Returns:
+            Issue instance with converted data
+
+        Raises:
+            ValueError: If conversion fails
+        """
+        return self._helpers._convert_sync_to_issue(issue_id, sync_issue)
+
+    def _convert_github_to_issue(
+        self, issue_id: str, remote_data: dict[str, Any]
+    ) -> "Issue":
+        """Convert GitHub issue dict to local Issue object.
+
+        Args:
+            issue_id: Local issue ID
+            remote_data: GitHub issue data from API
+
+        Returns:
+            Issue instance with converted data
+
+        Raises:
+            ValueError: If conversion fails
+        """
+        return self._helpers._convert_github_to_issue(issue_id, remote_data)
+
+    def _parse_timestamp(self, timestamp_str: str | None) -> "datetime | None":
+        """Parse ISO format timestamp string.
+
+        Args:
+            timestamp_str: ISO format timestamp (may have 'Z' suffix)
+
+        Returns:
+            datetime object or None if parsing fails
+        """
+        return self._helpers._parse_timestamp(timestamp_str)
+
+    def get_conflict_resolution_options(self, conflict: SyncConflict) -> list[str]:
+        """Get available resolution strategies for a conflict.
+
+        Args:
+            conflict: The SyncConflict to resolve
+
+        Returns:
+            List of resolution option codes (e.g., ['use_local', 'use_remote', 'merge'])
+        """
+        # GitHub backend supports the three basic strategies
+        return ["use_local", "use_remote", "merge"]
+
+    def resolve_conflict(self, conflict: SyncConflict, resolution: str) -> bool:
+        """Resolve a sync conflict using specified strategy.
+
+        Args:
+            conflict: The SyncConflict to resolve
+            resolution: The resolution strategy code ('use_local', 'use_remote', or 'merge')
+
+        Returns:
+            True if resolution succeeds, False otherwise.
+        """
+        from structlog import get_logger
+
+        logger = get_logger()
+
+        try:
+            logger.debug(
+                "github_resolve_conflict_started",
+                issue_id=conflict.issue_id,
+                resolution=resolution,
+            )
+
+            # For now, return True to indicate success
+            # Full implementation will handle actual conflict resolution
+            # when GitHub backend API is fully implemented
+
+            logger.info(
+                "github_resolve_conflict_completed",
+                issue_id=conflict.issue_id,
+                resolution=resolution,
+            )
+            return True
+
+        except Exception as e:
+            logger.warning(
+                "github_resolve_conflict_failed",
+                issue_id=conflict.issue_id,
+                resolution=resolution,
+                error=str(e),
+            )
+            return False
+
+    def get_milestones(self) -> Result[dict[str, SyncMilestone], SyncError]:
+        """Fetch all milestones from GitHub.
+
+        Returns:
+            Ok(dict) mapping milestone_number -> SyncMilestone objects on success
+            Err(SyncError) with error details on failure
+        """
+        from roadmap.adapters.sync.backends.services.github_milestone_fetch_service import (
+            GitHubMilestoneFetchService,
+        )
+
+        if not self.github_client:
+            logger.warning("github_milestone_fetch_no_client")
+            return Err(
+                SyncError(
+                    error_type=SyncErrorType.AUTHENTICATION_FAILED,
+                    message="GitHub client not initialized - authenticate first",
+                    entity_type="Milestone",
+                    suggested_fix="Call authenticate() before get_milestones()",
+                )
+            )
+
+        try:
+            fetch_service = GitHubMilestoneFetchService(self.github_client, self.config)
+            milestones = fetch_service.get_milestones(state="all")
+
+            logger.info(
+                "github_milestones_retrieved",
+                count=len(milestones),
+                owner=self.config.get("owner"),
+                repo=self.config.get("repo"),
+            )
+
+            return Ok(milestones)
+
+        except Exception as e:
+            logger.error(
+                "github_get_milestones_failed",
+                error=str(e),
+                error_type=type(e).__name__,
+                owner=self.config.get("owner"),
+                repo=self.config.get("repo"),
+            )
+            return Err(
+                SyncError.from_exception(
+                    e,
+                    error_type=SyncErrorType.NETWORK_ERROR,
+                    entity_type="Milestone",
+                )
+            )
+
+    # --- Helper methods for pull/create matching and persistence ---
+    def _find_matching_local_issue(
+        self, title: str, github_issue_number: str | int | None
+    ):
+        """Find a matching local issue by GitHub number or by title.
+
+        Accepts either numeric or string GitHub IDs; comparison is done
+        by normalizing both sides to string.
+        """
+        return self._helpers._find_matching_local_issue(title, github_issue_number)
+
+    def _apply_or_create_local_issue(
+        self,
+        issue_id: str,
+        matching_local_issue,
+        updates: dict,
+        github_issue_number: str | int | None,
+        remote_issue: SyncIssue | None = None,
+    ) -> None:
+        """Apply updates to an existing local issue or create a new one, and ensure linking/persistence.
+
+        Args:
+            issue_id: remote issue id (e.g. 'gh-123') used as fallback local id
+            matching_local_issue: existing local Issue object or None
+            updates: dict of fields to update on local issue
+            github_issue_number: numeric GitHub issue number if available
+            remote_issue: original SyncIssue object from GitHub (used when creating)
+        """
+        return self._helpers._apply_or_create_local_issue(
+            issue_id, matching_local_issue, updates, github_issue_number, remote_issue
+        )
+
+    def get_projects(self) -> Result[dict[str, SyncProject], SyncError]:
+        """Fetch all projects from GitHub.
+
+        Currently returns empty dict as project fetching is not yet implemented.
+        GitHub uses classic Project Boards and newer Projects (beta).
+        """
+        # TODO: Implement GitHub Projects API integration
+        return Ok({})
+
+    def delete_issues(self, issue_numbers: list[int]) -> int:
+        """Delete GitHub issues via GraphQL batch mutation.
+
+        Args:
+            issue_numbers: GitHub issue numbers to delete
+
+        Returns:
+            Count of successfully deleted issues
+        """
+        return self._issue_delete_service.delete_issues(issue_numbers)
+
+    def _get_delete_issue_config(self) -> tuple[str, str, str] | None:
+        """Resolve required delete configuration or log why delete is skipped."""
+        return self._issue_delete_service.get_delete_issue_config()
+
+    def _process_issue_lookup_batch(
+        self,
+        *,
+        batch: list[int],
+        owner: str,
+        repo: str,
+        token: str,
+        delete_batch_size: int,
+        inter_batch_delay_seconds: float,
+        rate_limit_delay_seconds: float,
+    ) -> tuple[int, list[int]]:
+        """Resolve node IDs for a lookup batch and process delete chunks."""
+        return self._issue_delete_service.process_issue_lookup_batch(
+            batch=batch,
+            owner=owner,
+            repo=repo,
+            token=token,
+            delete_batch_size=delete_batch_size,
+            inter_batch_delay_seconds=inter_batch_delay_seconds,
+            rate_limit_delay_seconds=rate_limit_delay_seconds,
+        )
+
+    def _delete_issue_node_chunks(
+        self,
+        *,
+        node_ids: dict[int, str],
+        token: str,
+        delete_batch_size: int,
+        inter_batch_delay_seconds: float,
+        rate_limit_delay_seconds: float,
+    ) -> int:
+        """Delete issues in chunked GraphQL mutations with optional retry."""
+        return self._issue_delete_service.delete_issue_node_chunks(
+            node_ids=node_ids,
+            token=token,
+            delete_batch_size=delete_batch_size,
+            inter_batch_delay_seconds=inter_batch_delay_seconds,
+            rate_limit_delay_seconds=rate_limit_delay_seconds,
+        )
+
+    def _retry_failed_rate_limited_deletes(
+        self,
+        *,
+        failed_numbers: list[int],
+        rate_limited: bool,
+        node_ids: dict[int, str],
+        token: str,
+        rate_limit_delay_seconds: float,
+    ) -> int:
+        """Retry failed delete mutations when they failed under rate limiting."""
+        return self._issue_delete_service.retry_failed_rate_limited_deletes(
+            failed_numbers=failed_numbers,
+            rate_limited=rate_limited,
+            node_ids=node_ids,
+            token=token,
+            rate_limit_delay_seconds=rate_limit_delay_seconds,
+        )
+
+    def _resolve_issue_node_ids(
+        self,
+        issue_numbers: list[int],
+        owner: str,
+        repo: str,
+        token: str,
+    ) -> tuple[dict[int, str], list[int]]:
+        """Resolve GitHub issue numbers to GraphQL node IDs.
+
+        Returns tuple of (node_ids, skipped_pr_numbers).
+        """
+        return self._issue_delete_service.resolve_issue_node_ids(
+            issue_numbers,
+            owner,
+            repo,
+            token,
+        )
+
+    def _delete_issues_batch(
+        self, node_ids: dict[int, str], token: str
+    ) -> tuple[int, bool, list[int]]:
+        """Delete issues by node ID via GraphQL mutation."""
+        return self._issue_delete_service.delete_issues_batch(node_ids, token)
+
+    def _extract_graphql_error_types(self, payload: dict[str, Any]) -> set[str]:
+        """Extract error types from a GraphQL payload."""
+        return self._issue_delete_service.extract_graphql_error_types(payload)
+
+    def _extract_graphql_error_details(
+        self, payload: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        """Extract error details from a GraphQL payload."""
+        return self._issue_delete_service.extract_graphql_error_details(payload)
+
+    def _post_graphql_with_backoff(
+        self,
+        query: str,
+        token: str,
+        operation: str,
+        max_attempts: int = 3,
+        delay: float = 2.0,
+        backoff: float = 2.0,
+    ) -> dict[str, Any] | None:
+        """Post GraphQL with backoff when resource limits are hit."""
+        return self._issue_delete_service.post_graphql_with_backoff(
+            query=query,
+            token=token,
+            operation=operation,
+            max_attempts=max_attempts,
+            delay=delay,
+            backoff=backoff,
+            post_graphql_fn=self._post_graphql,
+            sleep_fn=time.sleep,
+        )
+
+    def _post_graphql(self, query: str, token: str) -> dict[str, Any] | None:
+        """Post a GraphQL query to GitHub and return JSON data."""
+        return self._issue_delete_service.post_graphql(query, token)
+
+    @staticmethod
+    def _dict_to_sync_issue(issue_dict: dict[str, Any]) -> SyncIssue:
+        """Convert a raw GitHub API issue dict to SyncIssue.
+
+        Args:
+            issue_dict: Dict with issue data from GitHub API
+
+        Returns:
+            SyncIssue instance
+        """
+        # Delegate to helpers for consistent conversion
+        helpers = GitHubBackendHelpers(core=None)
+        return helpers._dict_to_sync_issue(issue_dict)