roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/interfaces/__init__.py

@@ -0,0 +1,109 @@
+"""Protocol definitions for dependency injection and service abstraction."""
+
+from typing import Protocol
+
+from .assignee_validator import AssigneeValidator  # type: ignore[assignment]
+from .backend_factory import SyncBackendFactoryInterface, SyncBackendInterface
+from .github import GitHubBackendInterface
+from .parsers import (
+    FrontmatterParserInterface,
+    IssueParserInterface,
+    MilestoneParserInterface,
+    ProjectParserInterface,
+)
+from .persistence import (
+    FileNotFound,
+    GitHistoryError,
+    PersistenceInterface,
+)
+from .repositories import (
+    IssueRepository,
+    MilestoneRepository,
+    ProjectRepository,
+)
+from .state_managers import (
+    IssueStateManager,
+    MilestoneStateManager,
+    ProjectStateManager,
+    QueryStateManager,
+    SyncStateManager,
+)
+from .state_storage import SyncStateStorageInterface
+from .sync_backend import (
+    SyncConflict,
+    SyncReport,
+)
+from .sync_services import SyncCacheServiceInterface, SyncLinkingServiceInterface
+
+__all__ = [
+    "CredentialProvider",
+    "AssigneeValidator",
+    "ProjectStateManager",
+    "MilestoneStateManager",
+    "IssueStateManager",
+    "SyncStateManager",
+    "QueryStateManager",
+    "SyncBackendInterface",
+    "SyncBackendFactoryInterface",
+    "SyncConflict",
+    "SyncReport",
+    "PersistenceInterface",
+    "IssueParserInterface",
+    "FrontmatterParserInterface",
+    "MilestoneParserInterface",
+    "ProjectParserInterface",
+    "GitHubBackendInterface",
+    "SyncStateStorageInterface",
+    "SyncLinkingServiceInterface",
+    "SyncCacheServiceInterface",
+    "IssueRepository",
+    "MilestoneRepository",
+    "ProjectRepository",
+    "FileNotFound",
+    "GitHistoryError",
+]
+
+
+class CredentialProvider(Protocol):
+    """Abstract interface for credential management.
+
+    Defines the contract that any credential provider must implement.
+    Allows services to work with different credential backends without
+    depending on concrete implementations.
+    """
+
+    def get_token(self) -> str | None:
+        """Retrieve a stored token.
+
+        Returns:
+            Token string if found, None otherwise
+        """
+        ...
+
+    def store_token(self, token: str, repo_info: dict[str, str] | None = None) -> bool:  # noqa: F841
+        """Store a token securely.
+
+        Args:
+            token: Token to store
+            repo_info: Optional repository information (owner, repo)
+
+        Returns:
+            True if stored successfully, False otherwise
+        """
+        ...
+
+    def delete_token(self) -> bool:
+        """Delete a stored token.
+
+        Returns:
+            True if deleted successfully, False otherwise
+        """
+        ...
+
+    def is_available(self) -> bool:
+        """Check if the credential provider is available on this system.
+
+        Returns:
+            True if available, False otherwise
+        """
+        ...

roadmap/core/interfaces/assignee_validator.py

@@ -0,0 +1,40 @@
+"""Assignee validator interface.
+
+Defines the contract for assignee validation implementations that can be
+swapped based on the configured sync backend.
+"""
+
+from typing import Protocol
+
+
+class AssigneeValidator(Protocol):
+    """Protocol for assignee validation.
+
+    Implementations validate assignees according to their backend's rules.
+    For example, GitHub validator checks against repository collaborators,
+    while a no-op validator always accepts any assignee.
+    """
+
+    def validate(self, assignee: str) -> tuple[bool, str]:
+        """Validate an assignee.
+
+        Args:
+            assignee: Username to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+            - (True, "") if valid
+            - (False, error_message) if invalid
+        """
+        ...
+
+    def get_canonical_assignee(self, assignee: str) -> str:
+        """Get the canonical form of an assignee name.
+
+        Args:
+            assignee: Input assignee name
+
+        Returns:
+            Canonical assignee name (may be same as input if no mapping exists)
+        """
+        ...

roadmap/core/interfaces/backend_factory.py

@@ -0,0 +1,175 @@
+"""Backend factory interface for creating sync backends.
+
+Defines contract for backend instantiation without importing adapter implementations.
+Allows dynamic backend selection without layer violations.
+
+Updated to use Result<T, SyncError> pattern for explicit error handling.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from roadmap.common.result import Result
+    from roadmap.core.services.sync.sync_errors import SyncError
+
+    from .sync_backend import SyncReport
+
+
+class SyncBackendFactoryInterface(ABC):
+    """Contract for creating sync backends."""
+
+    @abstractmethod
+    def create_backend(
+        self,
+        backend_type: str,  # noqa: F841
+        config: dict[str, Any],  # noqa: F841
+    ) -> "SyncBackendInterface":
+        """Create a sync backend instance.
+
+        Args:
+            backend_type: Type of backend to create (e.g., 'github', 'gitlab')
+            config: Configuration dictionary for the backend
+
+        Returns:
+            SyncBackendInterface implementation
+
+        Raises:
+            ValueError: If backend_type is not supported
+        """
+        pass
+
+    @abstractmethod
+    def list_supported_backends(self) -> list[str]:
+        """List all supported backend types.
+
+        Returns:
+            List of backend type identifiers
+        """
+        pass
+
+    @abstractmethod
+    def get_default_backend(self) -> str:
+        """Get the default backend type.
+
+        Returns:
+            Backend type identifier
+        """
+        pass
+
+
+class SyncBackendInterface(ABC):
+    """Contract for sync backend implementations.
+
+    Updated to use Result<T, SyncError> for explicit error handling.
+    """
+
+    @abstractmethod
+    def authenticate(self) -> "Result[bool, SyncError]":
+        """Authenticate with the backend service.
+
+        Returns:
+            Ok(True) if authentication successful
+            Err(SyncError) with error details
+        """
+        pass
+
+    @abstractmethod
+    def get_backend_name(self) -> str:
+        """Get the backend name.
+
+        Returns:
+            Backend identifier string
+        """
+        pass
+
+    @abstractmethod
+    def get_issues(self) -> "Result[dict[str, Any], SyncError]":
+        """Get issues from backend.
+
+        Returns:
+            Ok(dict) of issues on success
+            Err(SyncError) with error details
+        """
+        pass
+
+    @abstractmethod
+    def push_issues(self, issues: dict[str, Any]) -> "Result[SyncReport, SyncError]":  # noqa: F841
+        """Push issues to backend.
+
+        Args:
+            issues: Dictionary of issues to push
+
+        Returns:
+            Ok(SyncReport) with results on success
+            Err(SyncError) with fatal error details
+        """
+        pass
+
+    @abstractmethod
+    def push_issue(self, local_issue: Any) -> "Result[bool, SyncError]":  # noqa: F841
+        """Push a single issue to backend.
+
+        Delegates to push_issues by default but can be overridden.
+
+        Args:
+            local_issue: Issue object to push
+
+        Returns:
+            Ok(True) if successful
+            Err(SyncError) with error details
+        """
+        pass
+
+    @abstractmethod
+    def pull_issues(self, issue_ids: list[str]) -> "Result[SyncReport, SyncError]":
+        """Pull issues from backend.
+
+        Args:
+            issue_ids: List of issue IDs to pull
+
+        Returns:
+            Ok(SyncReport) with results on success
+            Err(SyncError) with fatal error details
+        """
+        pass
+
+    @abstractmethod
+    def pull_issue(self, issue_id: str) -> "Result[bool, SyncError]":
+        """Pull a single issue from backend.
+
+        Delegates to pull_issues by default but can be overridden.
+
+        Args:
+            issue_id: Issue ID to pull
+
+        Returns:
+            Ok(True) if successful
+            Err(SyncError) with error details
+        """
+        pass
+
+    @abstractmethod
+    def get_conflict_resolution_options(self, conflict: Any) -> list[str]:  # noqa: F841
+        """Get conflict resolution options.
+
+        Args:
+            conflict: Conflict object
+
+        Returns:
+            List of resolution options
+        """
+        pass
+
+    @abstractmethod
+    def resolve_conflict(self, conflict: Any, resolution: str) -> bool:  # noqa: F841
+        """Resolve a conflict.
+
+        Args:
+            conflict: Conflict object
+            resolution: Resolution option selected
+
+        Returns:
+            True if resolved successfully
+        """
+        pass

roadmap/core/interfaces/github.py

@@ -0,0 +1,102 @@
+"""GitHub backend interface for core services.
+
+Defines contract for GitHub operations without importing adapter implementations.
+Allows core services to work with GitHub without layer violations.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from roadmap.core.domain import Issue
+
+
+class GitHubBackendInterface(ABC):
+    """Contract for GitHub backend operations."""
+
+    @abstractmethod
+    def authenticate(self) -> bool:
+        """Authenticate with GitHub.
+
+        Returns:
+            True if authentication successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_issues(self) -> dict[str, Any]:
+        """Get all issues from GitHub repository.
+
+        Returns:
+            Dictionary mapping issue IDs to issue data
+        """
+        pass
+
+    @abstractmethod
+    def get_issue(self, issue_id: str) -> Any:
+        """Get a specific issue from GitHub.
+
+        Args:
+            issue_id: The GitHub issue ID
+
+        Returns:
+            Issue data or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def create_issue(self, issue: Issue) -> str:
+        """Create an issue on GitHub.
+
+        Args:
+            issue: Issue domain object to create
+
+        Returns:
+            GitHub issue ID of created issue
+        """
+        pass
+
+    @abstractmethod
+    def update_issue(self, issue_id: str, issue: Issue) -> bool:
+        """Update an issue on GitHub.
+
+        Args:
+            issue_id: GitHub issue ID
+            issue: Updated issue data
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def close_issue(self, issue_id: str) -> bool:
+        """Close an issue on GitHub.
+
+        Args:
+            issue_id: GitHub issue ID
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def list_repositories(self) -> list[str]:
+        """List accessible repositories.
+
+        Returns:
+            List of repository identifiers
+        """
+        pass
+
+    @abstractmethod
+    def validate_credentials(self, token: str) -> bool:
+        """Validate GitHub API credentials.
+
+        Args:
+            token: GitHub API token
+
+        Returns:
+            True if credentials are valid
+        """
+        pass

roadmap/core/interfaces/parsers.py

@@ -0,0 +1,140 @@
+"""Parser interfaces for domain object deserialization.
+
+These interfaces define contracts for parsing files and content into domain objects.
+Implementations should be in the infrastructure/adapters layer.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from roadmap.core.domain import Issue, Milestone, Project
+
+
+class IssueParserInterface(ABC):
+    """Contract for parsing issue markdown files."""
+
+    @abstractmethod
+    def parse_issue_file(self, file_path: Path) -> "Issue":
+        """Parse an issue markdown file and return an Issue domain object.
+
+        Args:
+            file_path: Path to issue markdown file
+
+        Returns:
+            Issue domain object
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file cannot be parsed
+        """
+        pass
+
+    @abstractmethod
+    def parse_issue_content(self, content: str) -> dict[str, Any]:
+        """Parse issue content string and return frontmatter as dict.
+
+        Args:
+            content: File content as string
+
+        Returns:
+            Parsed frontmatter as dictionary
+        """
+        pass
+
+
+class MilestoneParserInterface(ABC):
+    """Contract for parsing milestone markdown files."""
+
+    @abstractmethod
+    def parse_milestone_file(self, file_path: Path) -> "Milestone":
+        """Parse a milestone markdown file and return a Milestone domain object.
+
+        Args:
+            file_path: Path to milestone markdown file
+
+        Returns:
+            Milestone domain object
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file cannot be parsed
+        """
+        pass
+
+    @abstractmethod
+    def parse_milestone_content(self, content: str) -> dict[str, Any]:
+        """Parse milestone content string and return frontmatter as dict.
+
+        Args:
+            content: File content as string
+
+        Returns:
+            Parsed frontmatter as dictionary
+        """
+        pass
+
+
+class ProjectParserInterface(ABC):
+    """Contract for parsing project markdown files."""
+
+    @abstractmethod
+    def parse_project_file(self, file_path: Path) -> "Project":
+        """Parse a project markdown file and return a Project domain object.
+
+        Args:
+            file_path: Path to project markdown file
+
+        Returns:
+            Project domain object
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file cannot be parsed
+        """
+        pass
+
+    @abstractmethod
+    def parse_project_content(self, content: str) -> dict[str, Any]:
+        """Parse project content string and return frontmatter as dict.
+
+        Args:
+            content: File content as string
+
+        Returns:
+            Parsed frontmatter as dictionary
+        """
+        pass
+
+
+class FrontmatterParserInterface(ABC):
+    """Contract for parsing YAML frontmatter from markdown files."""
+
+    @abstractmethod
+    def parse_file(self, file_path: Path) -> tuple[dict[str, Any], str]:
+        """Parse a markdown file and extract frontmatter and content.
+
+        Args:
+            file_path: Path to markdown file
+
+        Returns:
+            Tuple of (frontmatter dict, content string)
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file cannot be parsed
+        """
+        pass
+
+    @abstractmethod
+    def parse_content(self, content: str) -> tuple[dict[str, Any], str]:
+        """Parse markdown content and extract frontmatter and text.
+
+        Args:
+            content: File content as string
+
+        Returns:
+            Tuple of (frontmatter dict, content string)
+        """
+        pass

roadmap/core/interfaces/persistence.py

@@ -0,0 +1,45 @@
+"""Persistence interface for core services.
+
+Defines contract for file persistence and git history operations.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+
+class FileNotFound(Exception):
+    """Raised when a file is not found in history."""
+
+    pass
+
+
+class GitHistoryError(Exception):
+    """Raised when git history operations fail."""
+
+    pass
+
+
+class PersistenceInterface(ABC):
+    """Interface for file persistence operations."""
+
+    @abstractmethod
+    def get_file_at_timestamp(self, file_path: str, timestamp: datetime) -> str:
+        """Get file content at a specific git timestamp.
+
+        Args:
+            file_path: Path to file relative to repo root
+            timestamp: Datetime to retrieve file at
+
+        Returns:
+            File content as string
+
+        Raises:
+            FileNotFound: If file doesn't exist at timestamp
+            GitHistoryError: If git operation fails
+        """
+        pass
+
+    @abstractmethod
+    def list_files_in_directory(self, directory: str) -> list[str]:
+        """List all files in a directory at HEAD."""
+        pass