first

packages/asf-connectors/asf_connectors/git.py

@@ -0,0 +1,57 @@
+"""Abstract Git (repository / source-control) connector interface."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Protocol, AsyncIterator, Optional, Sequence
+
+
+@dataclass(frozen=True)
+class CommitInfo:
+    sha: str
+    message: str
+    author_email: str
+    author_name: str
+    authored_at: datetime
+    branch: Optional[str] = None
+    files_changed: Sequence[str] = ()
+
+
+@dataclass(frozen=True)
+class PullRequestInfo:
+    number: int
+    title: str
+    state: str  # open | closed | merged
+    branch: str
+    target_branch: str
+    author: str
+    created_at: datetime
+    merged_at: Optional[datetime] = None
+    description: Optional[str] = None
+    commit_shas: Sequence[str] = ()
+    labels: Sequence[str] = ()
+
+
+class GitConnector(Protocol):
+    """Any Git-hosting provider: GitHub, GitLab, Bitbucket, local Gitea..."""
+
+    async def list_commits(
+        self, repo_ref: str, *, branch: Optional[str] = None, since: Optional[datetime] = None
+    ) -> AsyncIterator[CommitInfo]: ...
+
+    async def get_commit(self, repo_ref: str, sha: str) -> Optional[CommitInfo]: ...
+
+    async def list_pull_requests(
+        self, repo_ref: str, *, state: str = "open"
+    ) -> AsyncIterator[PullRequestInfo]: ...
+
+    async def get_pull_request(self, repo_ref: str, number: int) -> Optional[PullRequestInfo]: ...
+
+    async def index_repository(self, repo_ref: str) -> None:
+        """Trigger a full sync (artifacts + relationships) for a repo.
+
+        Implementation must emit events; it must NOT mutate Core data
+        directly.
+        """
+        ...