roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/interfaces/sync_services.py

@@ -0,0 +1,119 @@
+"""Specialized adapter interfaces for sync services.
+
+Defines contracts for sync-specific operations without layer violations.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class SyncLinkingServiceInterface(ABC):
+    """Contract for sync linking operations.
+
+    Handles linking/unlinking of local and remote issues during sync.
+    """
+
+    @abstractmethod
+    def link_issues(self, local_id: str, remote_id: str) -> bool:  # noqa: F841
+        """Link a local issue to a remote issue.
+
+        Args:
+            local_id: Local issue ID
+            remote_id: Remote issue ID
+
+        Returns:
+            True if successful
+        """
+        pass
+
+    @abstractmethod
+    def unlink_issue(self, local_id: str) -> bool:  # noqa: F841
+        """Unlink an issue from its remote mapping.
+
+        Args:
+            local_id: Local issue ID
+
+        Returns:
+            True if successful
+        """
+        pass
+
+    @abstractmethod
+    def get_linked_remote_id(self, local_id: str) -> str | None:  # noqa: F841
+        """Get the remote issue ID for a local issue.
+
+        Args:
+            local_id: Local issue ID
+
+        Returns:
+            Remote issue ID or None if not linked
+        """
+        pass
+
+    @abstractmethod
+    def get_linked_local_id(self, remote_id: str) -> str | None:
+        """Get the local issue ID for a remote issue.
+
+        Args:
+            remote_id: Remote issue ID
+
+        Returns:
+            Local issue ID or None if not linked
+        """
+        pass
+
+
+class SyncCacheServiceInterface(ABC):
+    """Contract for sync caching operations.
+
+    Manages cache of remote state to reduce API calls.
+    """
+
+    @abstractmethod
+    def cache_remote_issue(self, issue_id: str, issue_data: dict[str, Any]) -> bool:
+        """Cache remote issue data.
+
+        Args:
+            issue_id: Issue identifier
+            issue_data: Issue data dictionary
+
+        Returns:
+            True if successful
+        """
+        pass
+
+    @abstractmethod
+    def get_cached_remote_issue(self, issue_id: str) -> dict[str, Any] | None:
+        """Get cached remote issue data.
+
+        Args:
+            issue_id: Issue identifier
+
+        Returns:
+            Issue data or None if not cached
+        """
+        pass
+
+    @abstractmethod
+    def invalidate_cache(self, issue_id: str | None = None) -> bool:
+        """Invalidate cache.
+
+        Args:
+            issue_id: Specific issue ID to invalidate, or None for all
+
+        Returns:
+            True if successful
+        """
+        pass
+
+    @abstractmethod
+    def is_cache_fresh(self, issue_id: str) -> bool:
+        """Check if cached data is still fresh.
+
+        Args:
+            issue_id: Issue identifier
+
+        Returns:
+            True if cache is valid and fresh
+        """
+        pass

roadmap/core/interfaces/sync_validators.py

@@ -0,0 +1,180 @@
+"""Protocol and abstract base class definitions for sync validation.
+
+This module defines validators to ensure data integrity and prevent database
+corruption during sync operations, particularly foreign key constraint violations.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Protocol
+
+
+class ForeignKeyValidator(ABC):
+    """Abstract base class for validating foreign key constraints before syncing.
+
+    Ensures prerequisite data exists before syncing dependent entities,
+    preventing FOREIGN KEY constraint violations.
+
+    Example:
+        validator = MilestoneFKValidator(db_connection)
+        try:
+            validator.validate()  # Raises if projects table is empty
+        except ForeignKeyValidationError as e:
+            logger.error(f"Validation failed: {e}")
+            raise
+    """
+
+    @abstractmethod
+    def validate(self) -> None:
+        """Validate that all foreign key prerequisites exist.
+
+        Raises:
+            ForeignKeyValidationError: If prerequisite data doesn't exist
+            RuntimeError: If database connection fails
+
+        Notes:
+            - Should fail fast on missing prerequisites
+            - Must not swallow exceptions
+            - Log specific missing references with entity IDs
+        """
+        ...
+
+    @abstractmethod
+    def missing_prerequisites(self) -> list[str]:
+        """Return list of missing prerequisite entities.
+
+        Returns:
+            List of entity IDs or descriptions that are missing
+
+        Example:
+            ['project-id-1', 'project-id-2']
+        """
+        ...
+
+
+class SyncPhaseOrder(Protocol):
+    """Protocol defining ordered sync phases to prevent constraint violations.
+
+    Ensures entities are synced in correct dependency order:
+    1. Projects (no dependencies)
+    2. Milestones (depends on projects)
+    3. Issues (depends on projects and milestones)
+
+    Implementation should enforce this ordering and fail if called out-of-order.
+    """
+
+    def validate_phase_order(self, _current_phase: str, _next_phase: str) -> bool:
+        """Validate that phase transition is allowed.
+
+        Args:
+            current_phase: Current sync phase ('projects', 'milestones', 'issues')
+            next_phase: Next sync phase to execute
+
+        Returns:
+            True if transition is valid, False otherwise
+
+        Raises:
+            ValueError: If phases are invalid or transition violates ordering
+        """
+        ...
+
+    def get_phase_order(self) -> list[str]:
+        """Get the canonical phase execution order.
+
+        Returns:
+            Ordered list of phases: ['projects', 'milestones', 'issues']
+        """
+        ...
+
+
+class PreSyncValidator(Protocol):
+    """Protocol for pre-sync validation with fail-fast semantics.
+
+    Validates preconditions before any sync operations begin.
+    Failures immediately abort sync to prevent partial state corruptions.
+    """
+
+    def validate_pre_sync(self, _roadmap_dir: str | None = None) -> dict[str, Any]:
+        """Validate preconditions before sync.
+
+        Args:
+            roadmap_dir: Optional roadmap directory path to validate
+
+        Returns:
+            dict with validation results:
+            {
+                'valid': bool,
+                'errors': list[str],
+                'warnings': list[str],
+                'prerequisite_count': int
+            }
+
+        Raises:
+            ValueError: If critical preconditions fail (fail-fast)
+            RuntimeError: If database connection fails
+
+        Notes:
+            - Errors (critical) cause immediate abort via exception
+            - Warnings (non-critical) logged but allow sync to proceed
+            - Should check prerequisite tables before FK-dependent syncing
+        """
+        ...
+
+
+class AtomicSyncPhase(Protocol):
+    """Protocol for atomic sync operations (transaction-based).
+
+    Wraps entity sync in transactions to ensure all-or-nothing semantics
+    per sync phase.
+
+    Usage:
+        with atomic_sync('projects') as phase:
+            sync_project_1()  # If any sync fails, entire phase rolls back
+            sync_project_2()
+    """
+
+    def __enter__(self) -> "AtomicSyncPhase":
+        """Enter atomic sync context (start transaction)."""
+        ...
+
+    def __exit__(
+        self,
+        _exc_type: type,
+        _exc_val: Exception,
+        _exc_tb: Any,
+    ) -> None:
+        """Exit atomic sync context (commit or rollback)."""
+        ...
+
+
+class ForeignKeyValidationError(Exception):
+    """Raised when foreign key validation fails.
+
+    Indicates missing prerequisite data that would cause FK constraint
+    violations if sync proceeded.
+
+    Attributes:
+        entity_type: Type of entity with missing FK (e.g., 'milestone')
+        missing_references: List of missing referenced entity IDs
+        error_details: Detailed error message with context
+    """
+
+    def __init__(
+        self,
+        entity_type: str,
+        missing_references: list[str],
+        error_details: str,
+    ):
+        """Initialize validation error.
+
+        Args:
+            entity_type: Type of entity that failed validation
+            missing_references: IDs of missing prerequisite entities
+            error_details: Detailed error context
+        """
+        self.entity_type = entity_type
+        self.missing_references = missing_references
+        self.error_details = error_details
+        super().__init__(
+            f"FK validation failed for {entity_type}: "
+            f"missing {len(missing_references)} references. {error_details}"
+        )

roadmap/core/models/__init__.py

@@ -0,0 +1,31 @@
+"""Core models for roadmap."""
+
+from pathlib import Path
+
+from roadmap.core.services.sync.sync_state import IssueBaseState, SyncState
+
+# Import from parent models.py (service params and other models)
+# Get the parent directory's models.py file
+_models_file = Path(__file__).parent.parent / "models.py"
+_models_spec = __import__("importlib.util").util.spec_from_file_location(
+    "_models_module", _models_file
+)
+_models_mod = __import__("importlib.util").util.module_from_spec(_models_spec)
+_models_spec.loader.exec_module(_models_mod)
+
+# Re-export items from models.py
+NOT_PROVIDED = _models_mod.NOT_PROVIDED
+IssueCreateServiceParams = _models_mod.IssueCreateServiceParams
+IssueUpdateServiceParams = _models_mod.IssueUpdateServiceParams
+ProjectCreateServiceParams = _models_mod.ProjectCreateServiceParams
+ProjectUpdateServiceParams = _models_mod.ProjectUpdateServiceParams
+
+__all__ = [
+    "NOT_PROVIDED",
+    "IssueCreateServiceParams",
+    "IssueUpdateServiceParams",
+    "ProjectCreateServiceParams",
+    "ProjectUpdateServiceParams",
+    "IssueBaseState",
+    "SyncState",
+]

roadmap/core/models/sync_models.py

@@ -0,0 +1,162 @@
+"""Sync dataclasses - canonical representations for sync operations.
+
+These dataclasses serve as the common currency between local state and remote state
+during sync operations. Backends normalize their API responses into these types,
+and the generic orchestrator works exclusively with them.
+
+This ensures the core sync logic is completely backend-agnostic.
+"""
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class SyncIssue:
+    """Canonical representation of an issue for sync operations.
+
+    Used as the common currency between local and remote states.
+    Backends normalize their API responses into this format.
+    """
+
+    # Core fields (present in all backends)
+    id: str
+    title: str
+    status: str  # Normalized: "open", "closed", "in_progress", etc.
+
+    # Optional fields (may not be present in all backends)
+    headline: str = ""
+    assignee: str | None = None
+    milestone: str | None = None
+    labels: list[str] = field(default_factory=list)
+
+    # Timing
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    # Backend tracking
+    backend_name: str = "unknown"  # "github", "gitlab", "git", etc.
+    backend_id: str | int | None = None  # Native backend ID
+    remote_ids: dict[str, str | int] = field(
+        default_factory=dict
+    )  # All known remote IDs
+
+    # Extensibility for backend-specific data
+    custom_fields: dict[str, Any] = field(
+        default_factory=dict
+    )  # Jira-style custom fields
+    raw_response: dict[str, Any] = field(default_factory=dict)  # Raw API response
+    metadata: dict[str, Any] = field(default_factory=dict)  # Custom tracking data
+
+    def __post_init__(self):
+        """Validate sync issue data."""
+        if not self.id:
+            raise ValueError("SyncIssue.id is required")
+        if not self.title:
+            raise ValueError("SyncIssue.title is required")
+        if not self.status:
+            raise ValueError("SyncIssue.status is required")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SyncIssue":
+        """Create from dictionary (e.g., from JSON/YAML)."""
+        # Handle datetime strings
+        if isinstance(data.get("created_at"), str):
+            data["created_at"] = datetime.fromisoformat(data["created_at"])
+        if isinstance(data.get("updated_at"), str):
+            data["updated_at"] = datetime.fromisoformat(data["updated_at"])
+
+        # Filter to only known fields
+        valid_fields = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered_data = {k: v for k, v in data.items() if k in valid_fields}
+        return cls(**filtered_data)
+
+
+@dataclass
+class SyncMilestone:
+    """Canonical representation of a milestone for sync operations."""
+
+    # Core fields
+    id: str
+    name: str
+    status: str = "open"  # "open", "closed"
+
+    # Optional fields
+    headline: str | None = None
+    due_date: datetime | None = None
+
+    # Backend tracking
+    backend_name: str = "unknown"
+    backend_id: str | int | None = None
+    remote_ids: dict[str, str | int] = field(default_factory=dict)
+
+    # Extensibility
+    custom_fields: dict[str, Any] = field(default_factory=dict)
+    raw_response: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate sync milestone data."""
+        if not self.id:
+            raise ValueError("SyncMilestone.id is required")
+        if not self.name:
+            raise ValueError("SyncMilestone.name is required")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SyncMilestone":
+        """Create from dictionary."""
+        if isinstance(data.get("due_date"), str):
+            data["due_date"] = datetime.fromisoformat(data["due_date"])
+
+        valid_fields = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered_data = {k: v for k, v in data.items() if k in valid_fields}
+        return cls(**filtered_data)
+
+
+@dataclass
+class SyncProject:
+    """Canonical representation of a project for sync operations."""
+
+    # Core fields
+    id: str
+    name: str
+
+    # Optional fields
+    headline: str | None = None
+
+    # Backend tracking
+    backend_name: str = "unknown"
+    backend_id: str | int | None = None
+    remote_ids: dict[str, str | int] = field(default_factory=dict)
+
+    # Extensibility
+    custom_fields: dict[str, Any] = field(default_factory=dict)
+    raw_response: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate sync project data."""
+        if not self.id:
+            raise ValueError("SyncProject.id is required")
+        if not self.name:
+            raise ValueError("SyncProject.name is required")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SyncProject":
+        """Create from dictionary."""
+        valid_fields = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered_data = {k: v for k, v in data.items() if k in valid_fields}
+        return cls(**filtered_data)

roadmap/core/models.py

@@ -0,0 +1,115 @@
+"""Service layer dataclasses for internal parameter passing.
+
+These models decouple service method signatures from their implementations.
+They're used internally by services (not exposed to CLI).
+
+Benefits:
+- Services have clean, stable signatures
+- Easy to add new fields without breaking callers
+- Self-documenting business logic
+- Better testability (can mock as single object)
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+# Sentinel value to distinguish "not provided" from "None"
+class _NotProvided:
+    """Sentinel value indicating a field was not provided in an update."""
+
+    def __repr__(self):
+        return "<NOT_PROVIDED>"
+
+
+NOT_PROVIDED = _NotProvided()
+
+
+@dataclass
+class IssueCreateServiceParams:
+    """Parameters for creating an issue (service layer)."""
+
+    title: str
+    priority: str | None = None
+    status: str = "todo"
+    issue_type: str | None = None
+    milestone: str | None = None
+    assignee: str | None = None
+    content: str | None = None
+    estimate: float | None = None
+    labels: list[str] = field(default_factory=list)
+    depends_on: list[str] = field(default_factory=list)
+    blocks: list[str] = field(default_factory=list)
+
+
+@dataclass
+class IssueUpdateServiceParams:
+    """Parameters for updating an issue (service layer)."""
+
+    issue_id: str
+    title: str | None | _NotProvided = NOT_PROVIDED
+    priority: str | None | _NotProvided = NOT_PROVIDED
+    status: str | None | _NotProvided = NOT_PROVIDED
+    assignee: str | None | _NotProvided = NOT_PROVIDED
+    milestone: str | None | _NotProvided = NOT_PROVIDED
+    content: str | None | _NotProvided = NOT_PROVIDED
+    estimate: float | None | _NotProvided = NOT_PROVIDED
+    reason: str | None | _NotProvided = NOT_PROVIDED
+    archived: bool | _NotProvided = NOT_PROVIDED
+
+
+@dataclass
+class IssueQueryParams:
+    """Parameters for querying/filtering issues (service layer)."""
+
+    status: str | None = None
+    priority: str | None = None
+    issue_type: str | None = None
+    assignee: str | None = None
+    milestone: str | None = None
+    overdue: bool = False
+    blocked: bool = False
+    unassigned: bool = False
+    limit: int | None = None
+    offset: int = 0
+
+
+@dataclass
+class MilestoneCreateServiceParams:
+    """Parameters for creating a milestone (service layer)."""
+
+    name: str
+    content: str = ""
+    due_date: datetime | None = None
+
+
+@dataclass
+class MilestoneUpdateServiceParams:
+    """Parameters for updating a milestone (service layer)."""
+
+    name: str
+    content: str | None = None
+    due_date: datetime | None = None
+    clear_due_date: bool = False
+    status: str | None = None
+    archived: bool | _NotProvided = NOT_PROVIDED
+
+
+@dataclass
+class ProjectCreateServiceParams:
+    """Parameters for creating a project (service layer)."""
+
+    name: str
+    content: str = ""
+    milestones: list | None = None
+
+
+@dataclass
+class ProjectUpdateServiceParams:
+    """Parameters for updating a project (service layer)."""
+
+    project_id: str
+    name: str | None = None
+    content: str | None = None
+    milestones: list | None = None
+    status: str | None = None

roadmap/core/observability/__init__.py

@@ -0,0 +1,17 @@
+"""Observability and metrics tracking for sync operations.
+
+Provides comprehensive metrics collection, aggregation, and reporting
+for sync operations including:
+- Deduplication metrics (local/remote reduction percentages, timing)
+- Fetch/push/pull operation metrics
+- Conflict detection and resolution tracking
+- Duplicate detection and resolution metrics
+- Performance timing and throughput
+"""
+
+from .sync_metrics import SyncMetrics, SyncObservability
+
+__all__ = [
+    "SyncMetrics",
+    "SyncObservability",
+]