roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/sync/sync_metadata_service.py

@@ -0,0 +1,361 @@
+"""Sync metadata service for tracking issue sync history and statistics."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+import structlog
+
+from roadmap.core.domain import Issue
+
+logger = structlog.get_logger()
+
+
+@dataclass
+class SyncRecord:
+    """Record of a single sync operation for an issue."""
+
+    sync_timestamp: str  # ISO format
+    success: bool
+    local_changes: dict[str, Any] | None = None
+    github_changes: dict[str, Any] | None = None
+    conflict_resolution: str | None = None  # "local", "github", or None
+    error_message: str | None = None
+    milestone_dependencies: list[str] = field(
+        default_factory=list
+    )  # Milestone IDs this sync depended on
+    dependency_resolution_time: float | None = (
+        None  # Time spent resolving dependencies in seconds
+    )
+
+
+@dataclass
+class SyncMetadata:
+    """Metadata tracking for issue synchronization."""
+
+    issue_id: str
+    github_issue_id: int
+    last_sync_time: str | None = None
+    sync_count: int = 0
+    successful_syncs: int = 0
+    last_sync_status: str = "never"  # "success", "conflict", "error", "never"
+    sync_history: list[SyncRecord] = field(default_factory=list)
+    milestone_sync_count: int = 0  # Number of syncs involving milestones
+    last_milestone_resolution_time: float | None = (
+        None  # Last dependency resolution time
+    )
+    circular_dependencies_detected: int = 0  # Count of circular dependency detections
+
+    def add_sync_record(self, record: SyncRecord) -> None:
+        """Add a sync record to history."""
+        self.sync_history.append(record)
+        self.sync_count += 1
+        self.last_sync_time = record.sync_timestamp
+
+        if record.success:
+            self.successful_syncs += 1
+            self.last_sync_status = "success"
+        elif record.conflict_resolution:
+            self.last_sync_status = "conflict"
+        else:
+            self.last_sync_status = "error"
+
+        # Track milestone-specific metrics
+        if record.milestone_dependencies:
+            self.milestone_sync_count += 1
+        if record.dependency_resolution_time is not None:
+            self.last_milestone_resolution_time = record.dependency_resolution_time
+
+    def get_success_rate(self) -> float:
+        """Calculate sync success rate."""
+        if self.sync_count == 0:
+            return 0.0
+        return (self.successful_syncs / self.sync_count) * 100
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for storage."""
+        return {
+            "issue_id": self.issue_id,
+            "github_issue_id": self.github_issue_id,
+            "last_sync_time": self.last_sync_time,
+            "sync_count": self.sync_count,
+            "successful_syncs": self.successful_syncs,
+            "last_sync_status": self.last_sync_status,
+            "milestone_sync_count": self.milestone_sync_count,
+            "last_milestone_resolution_time": self.last_milestone_resolution_time,
+            "circular_dependencies_detected": self.circular_dependencies_detected,
+            "sync_history": [
+                {
+                    "sync_timestamp": r.sync_timestamp,
+                    "success": r.success,
+                    "local_changes": r.local_changes,
+                    "github_changes": r.github_changes,
+                    "conflict_resolution": r.conflict_resolution,
+                    "error_message": r.error_message,
+                    "milestone_dependencies": r.milestone_dependencies,
+                    "dependency_resolution_time": r.dependency_resolution_time,
+                }
+                for r in self.sync_history
+            ],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SyncMetadata":
+        """Create from dictionary (loaded from storage)."""
+        history = [
+            SyncRecord(
+                sync_timestamp=r["sync_timestamp"],
+                success=r["success"],
+                local_changes=r.get("local_changes"),
+                github_changes=r.get("github_changes"),
+                conflict_resolution=r.get("conflict_resolution"),
+                error_message=r.get("error_message"),
+                milestone_dependencies=r.get("milestone_dependencies", []),
+                dependency_resolution_time=r.get("dependency_resolution_time"),
+            )
+            for r in data.get("sync_history", [])
+        ]
+        return cls(
+            issue_id=data["issue_id"],
+            github_issue_id=data["github_issue_id"],
+            last_sync_time=data.get("last_sync_time"),
+            sync_count=data.get("sync_count", 0),
+            successful_syncs=data.get("successful_syncs", 0),
+            last_sync_status=data.get("last_sync_status", "never"),
+            milestone_sync_count=data.get("milestone_sync_count", 0),
+            last_milestone_resolution_time=data.get("last_milestone_resolution_time"),
+            circular_dependencies_detected=data.get(
+                "circular_dependencies_detected", 0
+            ),
+            sync_history=history,
+        )
+
+
+class SyncMetadataService:
+    """Service for managing sync metadata persistence and queries."""
+
+    def __init__(self, core):
+        """Initialize metadata service.
+
+        Args:
+            core: RoadmapCore instance
+        """
+        self.core = core
+        # In-memory cache of metadata (keyed by issue_id)
+        self._cache: dict[str, SyncMetadata] = {}
+
+    def get_metadata(self, issue: Issue) -> SyncMetadata:
+        """Get sync metadata for an issue.
+
+        Args:
+            issue: Issue to get metadata for
+
+        Returns:
+            SyncMetadata for the issue
+        """
+        if issue.id in self._cache:
+            return self._cache[issue.id]
+
+        # Try to load from issue's github_sync_metadata field
+        if hasattr(issue, "github_sync_metadata") and issue.github_sync_metadata:
+            try:
+                metadata = SyncMetadata.from_dict(issue.github_sync_metadata)
+                self._cache[issue.id] = metadata
+                return metadata
+            except Exception as e:
+                logger.debug(
+                    "sync_metadata_deserialization_failed",
+                    operation="load_from_cache",
+                    issue_id=issue.id,
+                    error=str(e),
+                    action="Creating new metadata",
+                )
+
+        # Create new metadata
+        github_id = getattr(issue, "github_issue", None)
+        metadata = SyncMetadata(
+            issue_id=issue.id,
+            github_issue_id=github_id or 0,
+        )
+        self._cache[issue.id] = metadata
+        return metadata
+
+    def record_sync(
+        self,
+        issue: Issue,
+        success: bool,
+        local_changes: dict[str, Any] | None = None,
+        github_changes: dict[str, Any] | None = None,
+        conflict_resolution: str | None = None,
+        error_message: str | None = None,
+    ) -> None:
+        """Record a sync operation for an issue.
+
+        Args:
+            issue: Issue that was synced
+            success: Whether sync succeeded
+            local_changes: Local changes detected
+            github_changes: GitHub changes detected
+            conflict_resolution: How conflicts were resolved
+            error_message: Error message if sync failed
+        """
+        metadata = self.get_metadata(issue)
+
+        record = SyncRecord(
+            sync_timestamp=datetime.now(UTC).isoformat(),
+            success=success,
+            local_changes=local_changes,
+            github_changes=github_changes,
+            conflict_resolution=conflict_resolution,
+            error_message=error_message,
+        )
+        metadata.add_sync_record(record)
+
+        # Persist to issue
+        if not hasattr(issue, "github_sync_metadata"):
+            issue.github_sync_metadata = {}
+        issue.github_sync_metadata = metadata.to_dict()
+
+    def get_sync_history(self, issue: Issue, limit: int = 10) -> list[SyncRecord]:
+        """Get sync history for an issue.
+
+        Args:
+            issue: Issue to get history for
+            limit: Maximum number of records to return
+
+        Returns:
+            List of sync records (most recent first)
+        """
+        metadata = self.get_metadata(issue)
+        return list(reversed(metadata.sync_history))[:limit]
+
+    def get_statistics(self, issues: list[Issue]) -> dict[str, Any]:
+        """Get aggregate sync statistics across issues.
+
+        Args:
+            issues: List of issues to analyze
+
+        Returns:
+            Dictionary with statistics
+        """
+        total_issues = len(issues)
+        total_syncs = 0
+        successful_syncs = 0
+        never_synced = 0
+        total_conflicts = 0
+
+        for issue in issues:
+            metadata = self.get_metadata(issue)
+            total_syncs += metadata.sync_count
+            successful_syncs += metadata.successful_syncs
+
+            if metadata.sync_count == 0:
+                never_synced += 1
+
+            total_conflicts += sum(
+                1 for record in metadata.sync_history if record.conflict_resolution
+            )
+
+        return {
+            "total_issues": total_issues,
+            "never_synced": never_synced,
+            "total_sync_attempts": total_syncs,
+            "successful_syncs": successful_syncs,
+            "total_conflicts": total_conflicts,
+            "success_rate": (
+                (successful_syncs / total_syncs * 100) if total_syncs > 0 else 0
+            ),
+            "conflict_rate": (
+                (total_conflicts / total_syncs * 100) if total_syncs > 0 else 0
+            ),
+        }
+
+    def store_sync_metrics(
+        self, core, operation_id: str, metrics: dict[str, Any]
+    ) -> None:
+        """Store sync metrics to database.
+
+        Stores metrics as JSON in sync_metrics table for historical tracking
+        and analysis.
+
+        Args:
+            core: RoadmapCore instance
+            operation_id: ID of the sync operation
+            metrics: SyncMetrics.to_dict() result with all metrics
+        """
+        try:
+            # Store to first issue's metadata as a global sync record
+            issues = []
+            if hasattr(core, "issues"):
+                issues = core.issues.list_all_including_archived() or []
+            elif hasattr(core, "issue_service"):
+                issues = core.issue_service.list_all_including_archived() or []
+            if issues:
+                first_issue = issues[0]
+                if not first_issue.github_sync_metadata:
+                    first_issue.github_sync_metadata = {}
+
+                # Store metrics under special _sync_metrics key
+                first_issue.github_sync_metadata["_sync_metrics"] = {
+                    "operation_id": operation_id,
+                    "timestamp": datetime.now(UTC).isoformat(),
+                    "metrics": metrics,
+                }
+
+                # Persist via repository to ensure metadata is written
+                from roadmap.adapters.sync.services import IssuePersistenceService
+
+                saved = IssuePersistenceService.save_issue(first_issue, core)
+                if not saved:
+                    logger.warning(
+                        "sync_metrics_persist_failed",
+                        operation_id=operation_id,
+                        issue_id=first_issue.id,
+                        severity="operational",
+                    )
+                    return
+
+                logger.info(
+                    "sync_metrics_stored",
+                    operation_id=operation_id,
+                    timestamp=first_issue.github_sync_metadata["_sync_metrics"][
+                        "timestamp"
+                    ],
+                )
+        except Exception as e:
+            logger.error(
+                "sync_metrics_storage_failed",
+                operation_id=operation_id,
+                error=str(e),
+                severity="operational",
+            )
+
+    def get_last_sync_metrics(self, core) -> dict[str, Any] | None:
+        """Retrieve last sync metrics from database.
+
+        Returns:
+            Dictionary with metrics or None if no metrics stored
+        """
+        try:
+            issues = []
+            if hasattr(core, "issues"):
+                issues = core.issues.list_all_including_archived() or []
+            elif hasattr(core, "issue_service"):
+                issues = core.issue_service.list_all_including_archived() or []
+            if issues:
+                first_issue = issues[0]
+                if (
+                    first_issue.github_sync_metadata
+                    and "_sync_metrics" in first_issue.github_sync_metadata
+                ):
+                    return first_issue.github_sync_metadata["_sync_metrics"].get(
+                        "metrics"
+                    )
+            return None
+        except Exception as e:
+            logger.error(
+                "sync_metrics_retrieval_failed",
+                error=str(e),
+                severity="operational",
+            )
+            return None

roadmap/core/services/sync/sync_plan.py

@@ -0,0 +1,171 @@
+"""Lightweight Action and SyncPlan models for incremental sync refactor."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Action:
+    """Base action representing a single mutating operation to be applied by the Executor.
+
+    This class is intentionally simple: it is a serializable carrier of the
+    operation type and any payload necessary to perform it. Executors will
+    implement the actual semantics of applying each action type.
+    """
+
+    action_type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    def describe(self) -> str:
+        """Human-readable description useful for dry-run previews."""
+        # Keep concise and deterministic for testing
+        payload_preview = {k: self.payload.get(k) for k in sorted(self.payload.keys())}
+        return f"{self.action_type}: {payload_preview}"
+
+
+@dataclass
+class PushAction(Action):
+    """Action to push a local issue to a remote backend."""
+
+    def __init__(self, issue_id: str, issue_payload: Any = None):
+        """Initialize PushAction.
+
+        Args:
+            issue_id: ID of the issue to push.
+            issue_payload: Payload data for the issue.
+        """
+        super().__init__(
+            action_type="push",
+            payload={"issue_id": issue_id, "issue": issue_payload or {}},
+        )
+
+
+@dataclass
+class PullAction(Action):
+    """Action to pull remote changes for a local issue."""
+
+    def __init__(self, issue_id: str, remote_payload: Any = None):
+        """Initialize PullAction.
+
+        Args:
+            issue_id: ID of the issue to pull.
+            remote_payload: Remote payload data.
+        """
+        super().__init__(
+            action_type="pull",
+            payload={"issue_id": issue_id, "remote": remote_payload or {}},
+        )
+
+
+@dataclass
+class CreateLocalAction(Action):
+    """Action to create a local issue from a remote entity."""
+
+    def __init__(self, remote_id: str, remote_payload: Any = None):
+        """Initialize CreateLocalAction.
+
+        Args:
+            remote_id: Remote ID of the issue.
+            remote_payload: Remote payload data.
+        """
+        super().__init__(
+            action_type="create_local",
+            payload={"remote_id": remote_id, "remote": remote_payload or {}},
+        )
+
+
+@dataclass
+class LinkAction(Action):
+    """Action to link a local issue with a remote issue."""
+
+    def __init__(self, issue_id: str, backend_name: str, remote_id: str):
+        """Initialize LinkAction.
+
+        Args:
+            issue_id: Local issue ID.
+            backend_name: Name of the backend.
+            remote_id: Remote ID to link to.
+        """
+        super().__init__(
+            action_type="link",
+            payload={
+                "issue_id": issue_id,
+                "backend": backend_name,
+                "remote_id": remote_id,
+            },
+        )
+
+
+@dataclass
+class UpdateBaselineAction(Action):
+    """Action to update the baseline snapshot."""
+
+    def __init__(self, baseline_snapshot: dict[str, Any]):
+        """Initialize UpdateBaselineAction.
+
+        Args:
+            baseline_snapshot: Baseline snapshot to update.
+        """
+        super().__init__(
+            action_type="update_baseline", payload={"baseline": baseline_snapshot}
+        )
+
+
+@dataclass
+class ResolveConflictAction(Action):
+    """Action to resolve a sync conflict for an issue."""
+
+    def __init__(self, issue_id: str, resolution: dict[str, Any]):
+        """Initialize ResolveConflictAction.
+
+        Args:
+            issue_id: ID of the issue with conflict.
+            resolution: Resolution data for the conflict.
+        """
+        super().__init__(
+            action_type="resolve_conflict",
+            payload={"issue_id": issue_id, "resolution": resolution},
+        )
+
+
+@dataclass
+class SyncPlan:
+    """A collection of `Action`s representing the plan produced by the Analyzer.
+
+    The `SyncPlan` is intentionally minimal: it stores ordered actions and a
+    small metadata map that presenters or executors can consume.
+    """
+
+    actions: list[Action] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def add(self, action: Action) -> None:
+        """Add an action to the sync plan.
+
+        Args:
+            action: The action to add.
+        """
+        self.actions.append(action)
+
+    def describe(self) -> list[str]:
+        """Get textual descriptions of all actions in the plan.
+
+        Returns:
+            List of action descriptions.
+        """
+        return [a.describe() for a in self.actions]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the sync plan to a dictionary representation.
+
+        Returns:
+            Dictionary with actions and metadata.
+        """
+        return {
+            "actions": [
+                {"type": a.action_type, "payload": a.payload} for a in self.actions
+            ],
+            "metadata": self.metadata,
+        }