"""Base trait definition for issue handlers."""

from abc import ABC, abstractmethod

from .schema import Issue, IssueComment, LinkedIssue


class IssueHandler(ABC):
    """
    Abstract base class defining the interface for issue operations.
    This allows the workflow to be platform-agnostic for issue operations.
    """

    @abstractmethod
    async def fetch_issue(self, repo: str, issue_number: int) -> Issue:
        """
        Fetch a single issue by number.

        Args:
            repo: Repository identifier
            issue_number: Issue number

        Returns:
            Issue object
        """
        pass

    @abstractmethod
    async def fetch_issue_comments(
        self, repo: str, issue_number: int, limit: int = 50
    ) -> list[IssueComment]:
        """
        Fetch comments/notes for an issue.

        Args:
            repo: Repository identifier
            issue_number: Issue number
            limit: Maximum number of comments to fetch

        Returns:
            List of IssueComment objects
        """
        pass

    @abstractmethod
    async def fetch_linked_issues(self, repo: str, issue_number: int) -> list[LinkedIssue]:
        """
        Fetch issues linked to this issue via API (not text parsing).

        Args:
            repo: Repository identifier
            issue_number: Issue number

        Returns:
            List of LinkedIssue objects
        """
        pass

    @abstractmethod
    async def fetch_pr_linked_issues(self, repo: str, pr_number: int) -> list[LinkedIssue]:
        """
        Fetch issues linked to a PR/MR via platform API.

        Args:
            repo: Repository identifier
            pr_number: Pull request/merge request number

        Returns:
            List of LinkedIssue objects
        """
        pass

    @abstractmethod
    async def close(self) -> None:
        """Close the HTTP client."""
        pass
