markitect-main/markitect/issues/base.py

"""
Abstract base class for issue management backends.

This module defines the interface that all issue management backends must implement.
"""

from abc import ABC, abstractmethod
from typing import List, Optional, Dict, Any
import sys
from pathlib import Path
# Add project root to path so domain module can be imported
project_root = Path(__file__).parent.parent.parent
if str(project_root) not in sys.path:
    sys.path.insert(0, str(project_root))

from domain.issues.models import Issue


class IssueBackend(ABC):
    """Abstract base class for issue management backends."""

    def __init__(self, config: Dict[str, Any]):
        """Initialize backend with configuration."""
        self.config = config

    @abstractmethod
    def list_issues(self, state: Optional[str] = None) -> List[Issue]:
        """
        List issues with optional state filter.

        Args:
            state: Filter by state ('open', 'closed', 'all', or None for all)

        Returns:
            List of Issue objects
        """
        pass

    @abstractmethod
    def get_issue(self, issue_id: str) -> Issue:
        """
        Get specific issue by ID.

        Args:
            issue_id: The issue identifier

        Returns:
            Issue object

        Raises:
            Exception: If issue not found
        """
        pass

    @abstractmethod
    def create_issue(self, title: str, body: str, **kwargs) -> Issue:
        """
        Create new issue.

        Args:
            title: Issue title
            body: Issue body/description
            **kwargs: Additional issue properties (labels, assignees, etc.)

        Returns:
            Created Issue object
        """
        pass

    @abstractmethod
    def add_comment(self, issue_id: str, comment: str) -> Dict[str, Any]:
        """
        Add comment to issue.

        Args:
            issue_id: The issue identifier
            comment: Comment text

        Returns:
            Comment metadata (id, timestamp, etc.)
        """
        pass

    @abstractmethod
    def close_issue(self, issue_id: str) -> Issue:
        """
        Close issue.

        Args:
            issue_id: The issue identifier

        Returns:
            Updated Issue object with closed state
        """
        pass

    @abstractmethod
    def update_issue(self, issue_id: str, **kwargs) -> Issue:
        """
        Update issue properties.

        Args:
            issue_id: The issue identifier
            **kwargs: Properties to update (title, body, state, etc.)

        Returns:
            Updated Issue object
        """
        pass