"""
adapters/base/vcs.py
Abstract base class for all Version Control System adapters.
"""
from abc import ABC, abstractmethod


class VCSAdapter(ABC):
    """Contract that every VCS provider adapter must fulfil."""

    @abstractmethod
    def create_branch(self, name: str) -> None:
        """
        Create a new branch with the given name.

        Parameters
        ----------
        name : Branch name (e.g. "feat/webhook-ingestion").
        """
        ...

    @abstractmethod
    def commit(self, files: list[str], message: str) -> str:
        """
        Stage the given files and create a commit.

        Parameters
        ----------
        files   : List of file paths to stage (relative to repo root).
        message : Commit message.

        Returns
        -------
        The commit SHA as a string.
        """
        ...

    @abstractmethod
    def create_pr(self, title: str, body: str, head: str, base: str) -> str:
        """
        Open a pull request.

        Parameters
        ----------
        title : PR title.
        body  : PR description / body markdown.
        head  : Head branch name.
        base  : Base branch name (e.g. "main").

        Returns
        -------
        The URL of the created pull request.
        """
        ...

    @abstractmethod
    def get_pr_status(self, pr_id: str) -> str:
        """
        Fetch the current status of a pull request.

        Parameters
        ----------
        pr_id : Provider-specific PR identifier (number, node-id, or URL).

        Returns
        -------
        One of: "open" | "merged" | "closed".
        """
        ...