roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/sync/services/issue_persistence_service.py

@@ -0,0 +1,263 @@
+"""Service for persisting issues to local storage (YAML files)."""
+
+import time
+from typing import TYPE_CHECKING
+
+from structlog import get_logger
+
+from roadmap.core.domain.issue import Issue
+from roadmap.core.models.sync_models import SyncIssue
+
+if TYPE_CHECKING:
+    from roadmap.infrastructure.coordination.core import RoadmapCore  # noqa: F401
+
+logger = get_logger(__name__)
+
+
+class IssuePersistenceService:
+    """Handles persistence of issues to local storage (YAML files).
+
+    Centralizes all operations for:
+    - Updating the github_issue field on Issue objects
+    - Managing remote_ids dictionaries
+    - Saving issues to YAML repository
+
+    This eliminates the duplication of save patterns in pull_issue() and push_issue().
+    """
+
+    @staticmethod
+    def update_issue_with_remote_id(
+        issue: Issue,
+        backend_name: str,
+        backend_id: int | str,
+    ) -> None:
+        """Update an issue's remote_ids dictionary with a new backend mapping.
+
+        Args:
+            issue: Issue to update
+            backend_name: Backend name (e.g., "github")
+            backend_id: ID from remote backend
+        """
+        if issue.remote_ids is None:
+            issue.remote_ids = {}
+
+        issue.remote_ids[backend_name] = str(backend_id)
+
+        logger.debug(
+            "updated_remote_ids",
+            issue_id=issue.id,
+            backend_name=backend_name,
+            backend_id=backend_id,
+        )
+
+    @staticmethod
+    def update_github_issue_number(issue: Issue, github_number: int) -> None:
+        """Update the github_issue field on an Issue object.
+
+        This field is used for quick GitHub lookups without querying remote_ids.
+
+        Args:
+            issue: Issue to update
+            github_number: GitHub issue number to set
+        """
+        issue.github_issue = github_number
+
+        logger.debug(
+            "updated_github_issue_number",
+            issue_id=issue.id,
+            github_issue=github_number,
+        )
+
+    @staticmethod
+    def save_issue(issue: Issue, core: "RoadmapCore") -> bool:
+        """Save an issue to local YAML repository.
+
+        Args:
+            issue: Issue to save
+            core: RoadmapCore for accessing repositories
+
+        Returns:
+            True if save succeeded, False otherwise
+        """
+        try:
+            if not issue or not issue.id:
+                logger.warning(
+                    "cannot_save_invalid_issue",
+                    issue_id=getattr(issue, "id", None),
+                )
+                return False
+
+            repo = core.issue_service.repository
+            if not repo:
+                logger.error(
+                    "issue_repository_not_available",
+                    issue_id=issue.id,
+                )
+                return False
+
+            attempts = 0
+            max_attempts = 3
+            while True:
+                try:
+                    repo.save(issue)
+                    break
+                except OSError as e:
+                    attempts += 1
+                    if attempts >= max_attempts:
+                        raise
+                    backoff = 0.1 * (2 ** (attempts - 1))
+                    logger.warning(
+                        "issue_persistence_retrying",
+                        issue_id=issue.id,
+                        attempt=attempts,
+                        delay_seconds=backoff,
+                        error=str(e),
+                    )
+                    time.sleep(backoff)
+
+            logger.info(
+                "issue_saved_to_yaml",
+                issue_id=issue.id,
+                title=issue.title,
+            )
+            return True
+
+        except AttributeError as e:
+            logger.error(
+                "issue_persistence_attribute_error",
+                issue_id=getattr(issue, "id", "unknown"),
+                error=str(e),
+                error_type="AttributeError",
+            )
+            return False
+        except Exception as e:
+            logger.error(
+                "issue_persistence_save_failed",
+                issue_id=getattr(issue, "id", "unknown"),
+                error=str(e),
+                error_type=type(e).__name__,
+                exc_info=True,
+            )
+            return False
+
+    @staticmethod
+    def apply_sync_issue_to_local(
+        local_issue: Issue,
+        sync_issue: SyncIssue,
+    ) -> None:
+        """Apply data from a SyncIssue to update a local Issue object.
+
+        Used when pulling changes from remote backend to update local state.
+        Preserves local ID while updating fields from remote.
+
+        Args:
+            local_issue: Local issue to update (ID preserved)
+            sync_issue: Remote sync_issue with new data
+        """
+        # Update core fields from sync_issue
+        local_issue.title = sync_issue.title or local_issue.title
+        local_issue.assignee = sync_issue.assignee or local_issue.assignee
+        local_issue.milestone = sync_issue.milestone or local_issue.milestone
+        local_issue.labels = sync_issue.labels or local_issue.labels
+
+        # Update timestamps
+        if sync_issue.updated_at:
+            local_issue.updated = sync_issue.updated_at
+
+        # Update remote_ids from sync_issue (important for tracking)
+        if sync_issue.remote_ids:
+            if local_issue.remote_ids is None:
+                local_issue.remote_ids = {}
+            local_issue.remote_ids.update(sync_issue.remote_ids)
+
+        # Merge metadata while preserving local metadata
+        if sync_issue.metadata:
+            if local_issue.github_sync_metadata is None:
+                local_issue.github_sync_metadata = {}
+            local_issue.github_sync_metadata.update(sync_issue.metadata)
+
+        logger.debug(
+            "applied_sync_issue_to_local",
+            issue_id=local_issue.id,
+            title=local_issue.title,
+            from_backend=sync_issue.backend_name,
+        )
+
+    @staticmethod
+    def get_issue_from_repo(
+        issue_id: str,
+        core: "RoadmapCore",
+    ) -> Issue | None:
+        """Retrieve an issue from the local repository.
+
+        Args:
+            issue_id: Issue ID to retrieve
+            core: RoadmapCore for accessing repositories
+
+        Returns:
+            Issue if found, None otherwise
+        """
+        try:
+            repo = core.issue_service.repository
+            issue = repo.get(issue_id)
+
+            if issue:
+                logger.debug(
+                    "retrieved_issue_from_repo",
+                    issue_id=issue_id,
+                    title=issue.get("title")
+                    if isinstance(issue, dict)
+                    else issue.title,
+                )
+            else:
+                logger.debug("issue_not_found_in_repo", issue_id=issue_id)
+
+            return issue
+
+        except Exception as e:
+            logger.error(
+                "failed_to_retrieve_issue_from_repo",
+                issue_id=issue_id,
+                error=str(e),
+            )
+            return None
+
+    @staticmethod
+    def is_github_linked(issue: Issue) -> bool:
+        """Check if an issue is already linked to GitHub.
+
+        Args:
+            issue: Issue to check
+
+        Returns:
+            True if issue has github_issue set or github in remote_ids
+        """
+        if hasattr(issue, "github_issue") and issue.github_issue:
+            return True
+
+        if issue.remote_ids and "github" in issue.remote_ids:
+            return True
+
+        return False
+
+    @staticmethod
+    def get_github_issue_number(issue: Issue) -> int | str | None:
+        """Extract the GitHub issue number from an Issue.
+
+        Checks both github_issue field and remote_ids dict.
+
+        Args:
+            issue: Issue to extract from
+
+        Returns:
+            GitHub issue number if found, None otherwise
+        """
+        # First check direct field (property)
+        if issue.github_issue is not None:
+            return issue.github_issue
+
+        # Then check remote_ids
+        if issue.remote_ids and "github" in issue.remote_ids:
+            return issue.remote_ids["github"]
+
+        return None

roadmap/adapters/sync/services/issue_state_service.py

@@ -0,0 +1,243 @@
+"""Service for converting between SyncIssue and local Issue domain objects."""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from structlog import get_logger
+
+from roadmap.common.constants import Priority, Status
+from roadmap.core.domain.issue import Issue
+from roadmap.core.models.sync_models import SyncIssue
+
+logger = get_logger(__name__)
+
+
+class IssueStateService:
+    """Handles conversion between SyncIssue (remote) and Issue (local) domain objects.
+
+    Centralizes field mapping, normalization, and type conversions to eliminate
+    duplication between pull_issue() and push_issue() methods.
+    """
+
+    @staticmethod
+    def sync_issue_to_issue(issue_id: str, sync_issue: SyncIssue) -> Issue:
+        """Convert a SyncIssue (from backend) to a local Issue domain object.
+
+        Args:
+            issue_id: Local issue ID to assign
+            sync_issue: Remote SyncIssue with backend data
+
+        Returns:
+            Issue object ready for local storage/update
+
+        Raises:
+            ValueError: If required fields are missing
+        """
+        IssueStateService._validate_sync_issue_input(issue_id, sync_issue)
+        IssueStateService._warn_if_missing_sync_title(issue_id, sync_issue)
+
+        try:
+            created_at, updated_at = IssueStateService._resolve_sync_timestamps(
+                sync_issue
+            )
+            status = IssueStateService.normalize_status(sync_issue.status)
+            content = IssueStateService._resolve_sync_content(sync_issue)
+
+            issue = Issue(
+                id=issue_id,
+                title=sync_issue.title or "Untitled",
+                content=content,
+                status=status,
+                priority=Priority.MEDIUM,  # Default priority (not in SyncIssue)
+                labels=sync_issue.labels or [],
+                assignee=sync_issue.assignee,
+                milestone=sync_issue.milestone,
+                created=created_at,
+                updated=updated_at,
+            )
+
+            if sync_issue.remote_ids:
+                issue.remote_ids = sync_issue.remote_ids.copy()
+
+            issue.github_sync_metadata = IssueStateService._build_sync_metadata(
+                sync_issue
+            )
+
+            logger.info(
+                "converted_sync_issue_to_issue",
+                issue_id=issue_id,
+                title=issue.title,
+                status=status.value,
+                from_backend=sync_issue.backend_name,
+            )
+
+            return issue
+        except ValueError as e:
+            logger.error(
+                "sync_issue_conversion_validation_error",
+                issue_id=issue_id,
+                error=str(e),
+            )
+            raise
+        except Exception as e:
+            logger.error(
+                "sync_issue_conversion_failed",
+                issue_id=issue_id,
+                backend_name=sync_issue.backend_name,
+                error=str(e),
+                error_type=type(e).__name__,
+                exc_info=True,
+            )
+            raise
+
+    @staticmethod
+    def _validate_sync_issue_input(issue_id: str, sync_issue: SyncIssue | None) -> None:
+        """Validate required inputs for sync issue conversion."""
+        if not issue_id or not issue_id.strip():
+            logger.error("cannot_convert_sync_issue_empty_issue_id")
+            raise ValueError("issue_id cannot be empty")
+        if not sync_issue:
+            logger.error("cannot_convert_none_sync_issue")
+            raise ValueError("sync_issue cannot be None")
+
+    @staticmethod
+    def _warn_if_missing_sync_title(issue_id: str, sync_issue: SyncIssue) -> None:
+        """Emit warning when remote issue title is missing."""
+        if sync_issue.title and sync_issue.title.strip():
+            return
+        logger.warning(
+            "sync_issue_missing_title",
+            issue_id=issue_id,
+            backend_name=sync_issue.backend_name,
+            backend_id=sync_issue.backend_id,
+        )
+
+    @staticmethod
+    def _resolve_sync_timestamps(sync_issue: SyncIssue) -> tuple[datetime, datetime]:
+        """Resolve created/updated timestamps for a sync issue."""
+        created_at = sync_issue.created_at or datetime.now(UTC)
+        updated_at = sync_issue.updated_at or datetime.now(UTC)
+        return created_at, updated_at
+
+    @staticmethod
+    def _resolve_sync_content(sync_issue: SyncIssue) -> str:
+        """Resolve normalized content from sync issue headline."""
+        if sync_issue.headline and sync_issue.headline.strip():
+            return sync_issue.headline
+        return ""
+
+    @staticmethod
+    def _build_sync_metadata(sync_issue: SyncIssue) -> dict[str, Any]:
+        """Build metadata payload persisted on local issue."""
+        return {
+            "backend_name": sync_issue.backend_name,
+            "backend_id": sync_issue.backend_id,
+            **(sync_issue.metadata or {}),
+        }
+
+    @staticmethod
+    def issue_to_push_payload(issue: Issue) -> dict[str, Any]:
+        """Convert a local Issue to a push payload for remote backend.
+
+        Extracts fields that are relevant for pushing to GitHub/remote.
+
+        Args:
+            issue: Local Issue to convert
+
+        Returns:
+            Dictionary with fields safe for remote API
+
+        Raises:
+            ValueError: If issue is invalid or missing required fields
+        """
+        if not issue:
+            logger.error("cannot_build_push_payload_none_issue")
+            raise ValueError("issue cannot be None")
+
+        if not issue.title or not issue.title.strip():
+            logger.error(
+                "cannot_build_push_payload_empty_title",
+                issue_id=issue.id,
+            )
+            raise ValueError("issue.title cannot be empty")
+
+        try:
+            # Normalize status to backend format
+            state = "open"
+            if issue.status == Status.CLOSED:
+                state = "closed"
+
+            payload: dict[str, Any] = {
+                "title": issue.title,
+                "body": issue.content or "",
+                "state": state,
+            }
+
+            # Handle labels - may be comma-separated strings
+            if issue.labels:
+                labels_list: list[str] = []
+                for label in issue.labels:
+                    if isinstance(label, str):
+                        labels_list.extend(
+                            [
+                                label_item.strip()
+                                for label_item in label.split(",")
+                                if label_item.strip()
+                            ]
+                        )
+                    else:
+                        labels_list.append(str(label).strip())
+
+                if labels_list:
+                    payload["labels"] = labels_list
+
+            logger.info(
+                "issue_converted_to_push_payload",
+                issue_id=issue.id,
+                title=issue.title,
+                state=state,
+                has_labels=bool(payload.get("labels")),
+            )
+
+            return payload
+        except ValueError as e:
+            logger.error(
+                "push_payload_validation_error",
+                issue_id=issue.id,
+                error=str(e),
+            )
+            raise
+        except Exception as e:
+            logger.error(
+                "push_payload_creation_failed",
+                issue_id=issue.id,
+                title=issue.title,
+                error=str(e),
+                error_type=type(e).__name__,
+                exc_info=True,
+            )
+            raise
+
+    @staticmethod
+    def normalize_status(status_value: str | None) -> Status:
+        """Normalize a status string from any backend to local Status enum.
+
+        Args:
+            status_value: Status string from backend
+
+        Returns:
+            Normalized Status enum value
+        """
+        if not status_value:
+            return Status.TODO
+
+        status_lower = status_value.lower()
+
+        if status_lower in ("closed", "done", "completed", "resolved"):
+            return Status.CLOSED
+        elif status_lower in ("in_progress", "in progress", "active", "started"):
+            return Status.IN_PROGRESS
+        elif status_lower in ("on_hold", "on hold", "blocked", "paused"):
+            return Status.BLOCKED
+        else:
+            return Status.TODO

roadmap/adapters/sync/services/local_change_filter.py

@@ -0,0 +1,129 @@
+"""Filters local changes from baseline for sync operations.
+
+Extracted from SyncMergeEngine to separate change filtering logic.
+"""
+
+from structlog import get_logger
+
+logger = get_logger(__name__)
+
+
+class LocalChangeFilter:
+    """Filters and identifies local changes since baseline."""
+
+    @staticmethod
+    def filter_unchanged_from_base(
+        issues: list, current_local: dict, base_state_issues: dict
+    ) -> list:
+        """Filter out unchanged issues, keeping only changed or new ones.
+
+        Args:
+            issues: List of issues to filter
+            current_local: Dict of current local issues keyed by ID
+            base_state_issues: Dict of baseline state issues keyed by ID
+
+        Returns:
+            Filtered list containing only changed or new issues
+        """
+        if not base_state_issues:
+            logger.debug(
+                "filter_no_base_state",
+                input_count=len(issues),
+                reason="first_sync_no_previous_state",
+            )
+            return issues
+
+        filtered = []
+        skipped_count = 0
+        new_count = 0
+        changed_count = 0
+
+        for issue in issues:
+            issue_id = issue.id if hasattr(issue, "id") else issue
+            if issue_id not in current_local:
+                logger.debug(
+                    "filter_issue_not_in_local",
+                    issue_id=issue_id,
+                    reason="might_be_stale",
+                )
+                continue
+            if issue_id not in base_state_issues:
+                logger.debug(
+                    "filter_new_local_issue",
+                    issue_id=issue_id,
+                    reason="not_in_previous_sync",
+                )
+                new_count += 1
+                filtered.append(issue)
+                continue
+
+            local_issue = current_local[issue_id]
+            base_state = base_state_issues[issue_id]
+
+            fields_to_check = {
+                "status": lambda obj: (
+                    obj.status.value
+                    if hasattr(obj.status, "value")
+                    else str(obj.status)
+                ),
+                "assignee": lambda obj: obj.assignee,
+                "description": lambda obj: obj.description,
+                "labels": lambda obj: sorted(obj.labels or []),
+            }
+
+            has_local_changes = False
+            changed_fields = []
+
+            for field_name, getter in fields_to_check.items():
+                try:
+                    local_value = getter(local_issue)
+                except Exception as e:
+                    logger.warning(
+                        "filter_field_extraction_failed",
+                        issue_id=issue_id,
+                        field=field_name,
+                        error=str(e),
+                    )
+                    local_value = None
+
+                base_value = getattr(base_state, field_name, None)
+
+                if local_value != base_value:
+                    logger.debug(
+                        "filter_local_change_detected",
+                        issue_id=issue_id,
+                        field=field_name,
+                        base_value=base_value,
+                        local_value=local_value,
+                    )
+                    changed_fields.append(field_name)
+                    has_local_changes = True
+
+            if has_local_changes:
+                logger.debug(
+                    "filter_issue_has_local_changes",
+                    issue_id=issue_id,
+                    changed_fields=changed_fields,
+                )
+                changed_count += 1
+                filtered.append(issue)
+            else:
+                logger.debug(
+                    "filter_issue_unchanged_since_sync",
+                    issue_id=issue_id,
+                    reason="no_local_modifications",
+                )
+                skipped_count += 1
+
+        logger.info(
+            "filter_complete",
+            input_count=len(issues),
+            output_count=len(filtered),
+            skipped_count=skipped_count,
+            new_count=new_count,
+            changed_count=changed_count,
+            filtered_out_percentage=round((skipped_count / len(issues) * 100), 1)
+            if len(issues) > 0
+            else 0,
+        )
+        return filtered

roadmap/adapters/sync/services/pull_result_processor.py

@@ -0,0 +1,71 @@
+"""Processes pull results from sync operations.
+
+Extracted from SyncMergeEngine to separate pull processing logic.
+"""
+
+from structlog import get_logger
+
+logger = get_logger(__name__)
+
+
+class PullResultProcessor:
+    """Processes results from pull operations."""
+
+    @staticmethod
+    def process_pull_result(fetched) -> tuple[int, list, list]:
+        """Process pull result and extract metrics.
+
+        Args:
+            fetched: Pull result (list or report object)
+
+        Returns:
+            Tuple of (pulled_count, pull_errors, pulled_remote_ids)
+        """
+        pulled_count = 0
+        pull_errors = []
+        pulled_remote_ids = []
+
+        if isinstance(fetched, list):
+            pulled_items = [r for r in fetched if r]
+            pulled_count = len(pulled_items)
+            for item in pulled_items:
+                try:
+                    rid = getattr(item, "backend_id", None) or getattr(item, "id", None)
+                    if rid is not None:
+                        pulled_remote_ids.append(str(rid))
+                except Exception as e:
+                    logger.debug("pulled_item_id_extraction_failed", error=str(e))
+                    continue
+        else:
+            pull_report = fetched
+            if getattr(pull_report, "errors", None):
+                try:
+                    err_keys = (
+                        list(pull_report.errors.keys())
+                        if isinstance(pull_report.errors, dict)
+                        else []
+                    )
+                except Exception as e:
+                    logger.debug("error_keys_extraction_failed", error=str(e))
+                    err_keys = []
+                pull_errors = err_keys
+                logger.warning(
+                    "pull_batch_had_errors",
+                    error_count=len(pull_errors),
+                    errors=str(pull_report.errors)[:200],
+                )
+
+            pulled_raw = getattr(pull_report, "pulled", None)
+            if pulled_raw is None:
+                pulled_count = 0
+                pulled_remote_ids = []
+            else:
+                try:
+                    pulled_iter = list(pulled_raw)
+                except Exception as e:
+                    logger.debug("pulled_iter_conversion_failed", error=str(e))
+                    pulled_iter = [pulled_raw]
+                pulled_remote_ids = [str(i) for i in pulled_iter]
+                pulled_count = len(pulled_remote_ids)
+
+        return pulled_count, pull_errors, pulled_remote_ids