git-recap 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

git_recap/providers/azure_fetcher.py

@@ -1,12 +1,29 @@
 from azure.devops.connection import Connection
 from msrest.authentication import BasicAuthentication
 from datetime import datetime
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Optional
 from git_recap.providers.base_fetcher import BaseFetcher
 
 class AzureFetcher(BaseFetcher):
+    """
+    Fetcher implementation for Azure DevOps repositories.
+
+    Supports fetching commits, pull requests, and issues.
+    Release fetching is not supported and will raise NotImplementedError.
+    """
+
     def __init__(self, pat: str, organization_url: str, start_date=None, end_date=None, repo_filter=None, authors=None):
-        # authors should be passed as a list of unique names (e.g., email or unique id)
+        """
+        Initialize the AzureFetcher.
+
+        Args:
+            pat (str): Personal Access Token for Azure DevOps.
+            organization_url (str): The Azure DevOps organization URL.
+            start_date (datetime, optional): Start date for filtering entries.
+            end_date (datetime, optional): End date for filtering entries.
+            repo_filter (List[str], optional): List of repository names to filter.
+            authors (List[str], optional): List of author identifiers (e.g., email or unique id).
+        """
         super().__init__(pat, start_date, end_date, repo_filter, authors)
         self.organization_url = organization_url
         credentials = BasicAuthentication('', self.pat)
@@ -20,17 +37,37 @@ class AzureFetcher(BaseFetcher):
             self.authors = []
 
     def get_repos(self):
+        """
+        Retrieve all repositories in all projects for the organization.
+        Returns:
+            List of repository objects.
+        """
         projects = self.core_client.get_projects().value
         # Get all repositories in each project
         repos = [self.git_client.get_repositories(project.id) for project in projects]
         return repos
 
     @property
-    def repos_names(self)->List[str]:
-        "to be implemented later"
+    def repos_names(self) -> List[str]:
+        """
+        Return the list of repository names.
+
+        Returns:
+            List[str]: List of repository names.
+        """
+        # To be implemented if needed for UI or listing.
         ...
 
     def _filter_by_date(self, date_obj: datetime) -> bool:
+        """
+        Check if a datetime object is within the configured date range.
+
+        Args:
+            date_obj (datetime): The datetime to check.
+
+        Returns:
+            bool: True if within range, False otherwise.
+        """
         if self.start_date and date_obj < self.start_date:
             return False
         if self.end_date and date_obj > self.end_date:
@@ -38,11 +75,26 @@ class AzureFetcher(BaseFetcher):
         return True
 
     def _stop_fetching(self, date_obj: datetime) -> bool:
+        """
+        Determine if fetching should stop based on the date.
+
+        Args:
+            date_obj (datetime): The datetime to check.
+
+        Returns:
+            bool: True if should stop, False otherwise.
+        """
         if self.start_date and date_obj < self.start_date:
             return True
         return False
 
     def fetch_commits(self) -> List[Dict[str, Any]]:
+        """
+        Fetch commits for all repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of commit entries.
+        """
         entries = []
         processed_commits = set()
         for repo in self.repos:
@@ -77,6 +129,12 @@ class AzureFetcher(BaseFetcher):
         return entries
 
     def fetch_pull_requests(self) -> List[Dict[str, Any]]:
+        """
+        Fetch pull requests and their associated commits for all repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of pull request and commit_from_pr entries.
+        """
         entries = []
         processed_pr_commits = set()
         projects = self.core_client.get_projects().value
@@ -138,6 +196,12 @@ class AzureFetcher(BaseFetcher):
         return entries
 
     def fetch_issues(self) -> List[Dict[str, Any]]:
+        """
+        Fetch issues (work items) assigned to the configured authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of issue entries.
+        """
         entries = []
         wit_client = self.connection.clients.get_work_item_tracking_client()
         # Query work items for each author using a simplified WIQL query.
@@ -160,4 +224,93 @@ class AzureFetcher(BaseFetcher):
                     entries.append(entry)
                 if self._stop_fetching(created_date):
                     break
-        return entries
+        return entries
+
+    def fetch_releases(self) -> List[Dict[str, Any]]:
+        """
+        Fetch releases for Azure DevOps repositories.
+
+        Not implemented for Azure DevOps.
+
+        Raises:
+            NotImplementedError: Always, since release fetching is not supported for AzureFetcher.
+        """
+        # If Azure DevOps release fetching is supported in the future, implement logic here.
+        raise NotImplementedError("Release fetching is not supported for Azure DevOps (AzureFetcher).")
+
+    def get_branches(self) -> List[str]:
+        """
+        Get all branches in the repository.
+        
+        Returns:
+            List[str]: List of branch names.
+        
+        Raises:
+            NotImplementedError: Always, since branch listing is not yet implemented for AzureFetcher.
+        """
+        # TODO: Implement get_branches() for Azure DevOps support
+        # This would use: git_client.get_branches(repository_id, project)
+        # and extract branch names from the returned objects
+        raise NotImplementedError("Branch listing is not yet implemented for Azure DevOps (AzureFetcher).")
+
+    def get_valid_target_branches(self, source_branch: str) -> List[str]:
+        """
+        Get branches that can receive a pull request from the source branch.
+        
+        Validates that the source branch exists, filters out branches with existing
+        open PRs from source, excludes the source branch itself, and optionally
+        checks if source is ahead of target.
+        
+        Args:
+            source_branch (str): The source branch name.
+        
+        Returns:
+            List[str]: List of valid target branch names.
+        
+        Raises:
+            NotImplementedError: Always, since PR target validation is not yet implemented for AzureFetcher.
+        """
+        # TODO: Implement get_valid_target_branches() for Azure DevOps support
+        # This would require:
+        # 1. Verify source_branch exists using git_client.get_branch()
+        # 2. Get all branches using get_branches()
+        # 3. Filter out source branch
+        # 4. Check for existing pull requests using git_client.get_pull_requests()
+        # 5. Filter out branches with existing open PRs from source
+        # 6. Optionally check branch policies and protection rules
+        raise NotImplementedError("Pull request target branch validation is not yet implemented for Azure DevOps (AzureFetcher).")
+
+    def create_pull_request(
+        self,
+        head_branch: str,
+        base_branch: str,
+        title: str,
+        body: str,
+        draft: bool = False,
+        reviewers: Optional[List[str]] = None,
+        assignees: Optional[List[str]] = None,
+        labels: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a pull request between two branches with optional metadata.
+        
+        Args:
+            head_branch: Source branch for the PR.
+            base_branch: Target branch for the PR.
+            title: PR title.
+            body: PR description.
+            draft: Whether to create as draft PR (default: False).
+            reviewers: List of reviewer usernames (optional).
+            assignees: List of assignee usernames (optional).
+            labels: List of label names (optional).
+        
+        Returns:
+            Dict[str, Any]: Dictionary containing PR metadata (url, number, state, success) or error information.
+        
+        Raises:
+            NotImplementedError: Always, since PR creation is not yet implemented for AzureFetcher.
+        """
+        # TODO: Implement create_pull_request() for Azure DevOps support
+        # This would use: git_client.create_pull_request() with appropriate parameters
+        # Would need to handle reviewers, work item links (assignees), labels, and draft status
+        raise NotImplementedError("Pull request creation is not yet implemented for Azure DevOps (AzureFetcher).")

git_recap/providers/base_fetcher.py

@@ -9,7 +9,7 @@ class BaseFetcher(ABC):
         start_date: Optional[datetime] = None,
         end_date: Optional[datetime] = None,
         repo_filter: Optional[List[str]] = None,
-        authors: Optional[List[str]]=None
+        authors: Optional[List[str]] = None
     ):
         self.pat = pat
         if start_date is not None:
@@ -28,32 +28,148 @@ class BaseFetcher(ABC):
 
     @property
     @abstractmethod
-    def repos_names(self)->List[str]:
+    def repos_names(self) -> List[str]:
+        """
+        Return the list of repository names accessible to this fetcher.
+
+        Returns:
+            List[str]: List of repository names.
+        """
         pass
-        
+
     @abstractmethod
-    def fetch_commits(self) -> List[str]:
+    def fetch_commits(self) -> List[Dict[str, Any]]:
+        """
+        Fetch commit entries for the configured repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of commit entries.
+        """
         pass
 
     @abstractmethod
-    def fetch_pull_requests(self) -> List[str]:
+    def fetch_pull_requests(self) -> List[Dict[str, Any]]:
+        """
+        Fetch pull request entries for the configured repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of pull request entries.
+        """
         pass
 
     @abstractmethod
-    def fetch_issues(self) -> List[str]:
+    def fetch_issues(self) -> List[Dict[str, Any]]:
+        """
+        Fetch issue entries for the configured repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of issue entries.
+        """
         pass
 
+    @abstractmethod
+    def fetch_releases(self) -> List[Dict[str, Any]]:
+        """
+        Fetch releases for all repositories accessible to this fetcher.
+
+        Returns:
+            List[Dict[str, Any]]: List of releases, each as a structured dictionary.
+                The dictionary should include at least:
+                  - tag_name: str
+                  - name: str
+                  - repo: str
+                  - author: str
+                  - published_at: datetime
+                  - created_at: datetime
+                  - draft: bool
+                  - prerelease: bool
+                  - body: str
+                  - assets: List[Dict[str, Any]] (if available)
+        Raises:
+            NotImplementedError: If the provider does not support release fetching.
+        """
+        raise NotImplementedError("Release fetching is not implemented for this provider.")
+
+    @abstractmethod
+    def get_branches(self) -> List[str]:
+        """
+        Get all branches in the repository.
+        
+        Returns:
+            List[str]: List of branch names.
+        
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement get_branches() to return all repository branches")
+
+    @abstractmethod
+    def get_valid_target_branches(self, source_branch: str) -> List[str]:
+        """
+        Get branches that can receive a pull request from the source branch.
+        
+        Validates that the source branch exists, filters out branches with existing
+        open PRs from source, excludes the source branch itself, and optionally
+        checks if source is ahead of target.
+        
+        Args:
+            source_branch (str): The source branch name.
+        
+        Returns:
+            List[str]: List of valid target branch names.
+        
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement get_valid_target_branches() to return valid PR target branches for the given source branch")
+
+    @abstractmethod
+    def create_pull_request(
+        self,
+        head_branch: str,
+        base_branch: str,
+        title: str,
+        body: str,
+        draft: bool = False,
+        reviewers: Optional[List[str]] = None,
+        assignees: Optional[List[str]] = None,
+        labels: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a pull request between two branches with optional metadata.
+        
+        Args:
+            head_branch: Source branch for the PR.
+            base_branch: Target branch for the PR.
+            title: PR title.
+            body: PR description.
+            draft: Whether to create as draft PR (default: False).
+            reviewers: List of reviewer usernames (optional).
+            assignees: List of assignee usernames (optional).
+            labels: List of label names (optional).
+        
+        Returns:
+            Dict[str, Any]: Dictionary containing PR metadata (url, number, state, success) or error information.
+        
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement create_pull_request() to create a pull request with the specified parameters")
+
     def get_authored_messages(self) -> List[Dict[str, Any]]:
         """
         Aggregates all commit, pull request, and issue entries into a single list,
         ensuring no duplicate commits (based on SHA) are present, and then sorts
         them in chronological order based on their timestamp.
+
+        Returns:
+            List[Dict[str, Any]]: Aggregated and sorted list of entries.
         """
         commit_entries = self.fetch_commits()
         pr_entries = self.fetch_pull_requests()
         try:
             issue_entries = self.fetch_issues()
-        except Exception as e:
+        except Exception:
             issue_entries = []
 
         all_entries = pr_entries + commit_entries + issue_entries
@@ -75,11 +191,17 @@ class BaseFetcher(ABC):
         # Sort all entries by their timestamp.
         final_entries.sort(key=lambda x: x["timestamp"])
         return self.convert_timestamps_to_str(final_entries)
-    
+
     @staticmethod
     def convert_timestamps_to_str(entries: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """
         Converts the timestamp field from datetime to string format for each entry in the list.
+
+        Args:
+            entries (List[Dict[str, Any]]): List of entries with possible datetime timestamps.
+
+        Returns:
+            List[Dict[str, Any]]: Entries with timestamps as ISO-formatted strings.
         """
         for entry in entries:
             if isinstance(entry.get("timestamp"), datetime):

git_recap/providers/github_fetcher.py

@@ -1,18 +1,29 @@
 from github import Github
+from github import GithubException
 from datetime import datetime
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Optional
 from git_recap.providers.base_fetcher import BaseFetcher
+import logging
+
+logger = logging.getLogger(__name__)
+
 
 class GitHubFetcher(BaseFetcher):
+    """
+    Fetcher implementation for GitHub repositories.
+
+    Supports fetching commits, pull requests, issues, and releases.
+    """
+
     def __init__(self, pat: str, start_date=None, end_date=None, repo_filter=None, authors=None):
         super().__init__(pat, start_date, end_date, repo_filter, authors)
         self.github = Github(self.pat)
-        self.user = self.github.get_user()        
+        self.user = self.github.get_user()
         self.repos = self.user.get_repos(affiliation="owner,collaborator,organization_member")
         self.authors.append(self.user.login)
 
     @property
-    def repos_names(self)->List[str]:
+    def repos_names(self) -> List[str]:
         return [repo.name for repo in self.repos]
 
     def _stop_fetching(self, date_obj: datetime) -> bool:
@@ -53,6 +64,32 @@ class GitHubFetcher(BaseFetcher):
                         break
         return entries
 
+    def fetch_branch_diff_commits(self, source_branch: str, target_branch: str) -> List[Dict[str, Any]]:
+        entries = []
+        processed_commits = set()
+        for repo in self.repos:
+            if self.repo_filter and repo.name not in self.repo_filter:
+                continue
+            try:
+                comparison = repo.compare(target_branch, source_branch)
+                for commit in comparison.commits:
+                    commit_date = commit.commit.author.date
+                    sha = commit.sha
+                    if sha not in processed_commits:
+                        entry = {
+                            "type": "commit",
+                            "repo": repo.name,
+                            "message": commit.commit.message.strip(),
+                            "timestamp": commit_date,
+                            "sha": sha,
+                        }
+                        entries.append(entry)
+                        processed_commits.add(sha)
+            except GithubException as e:
+                logger.error(f"Failed to compare branches in {repo.name}: {str(e)}")
+                continue
+        return entries
+
     def fetch_pull_requests(self) -> List[Dict[str, Any]]:
         entries = []
         # Maintain a local set to skip duplicate commits already captured in a PR.
@@ -101,7 +138,6 @@ class GitHubFetcher(BaseFetcher):
                     break
         return entries
 
-
     def fetch_issues(self) -> List[Dict[str, Any]]:
         entries = []
         issues = self.user.get_issues()
@@ -117,4 +153,256 @@ class GitHubFetcher(BaseFetcher):
                 entries.append(entry)
             if self._stop_fetching(issue_date):
                 break
-        return entries
+        return entries
+
+    def fetch_releases(self) -> List[Dict[str, Any]]:
+        """
+        Fetch releases for all repositories accessible to the user.
+
+        Returns:
+            List[Dict[str, Any]]: List of releases, each as a structured dictionary with:
+                - tag_name: str
+                - name: str
+                - repo: str
+                - author: str
+                - published_at: datetime
+                - created_at: datetime
+                - draft: bool
+                - prerelease: bool
+                - body: str
+                - assets: List[Dict[str, Any]] (each with name, size, download_url, content_type, etc.)
+        """
+        releases = []
+        for repo in self.repos:
+            if self.repo_filter and repo.name not in self.repo_filter:
+                continue
+            try:
+                for rel in repo.get_releases():
+                    # Compose asset list
+                    assets = []
+                    for asset in rel.get_assets():
+                        assets.append({
+                            "name": asset.name,
+                            "size": asset.size,
+                            "download_url": asset.browser_download_url,
+                            "content_type": asset.content_type,
+                            "created_at": asset.created_at,
+                            "updated_at": asset.updated_at,
+                        })
+                    release_entry = {
+                        "tag_name": rel.tag_name,
+                        "name": rel.title if hasattr(rel, "title") else rel.name,
+                        "repo": repo.name,
+                        "author": rel.author.login if rel.author else None,
+                        "published_at": rel.published_at,
+                        "created_at": rel.created_at,
+                        "draft": rel.draft,
+                        "prerelease": rel.prerelease,
+                        "body": rel.body,
+                        "assets": assets,
+                    }
+                    releases.append(release_entry)
+            except Exception:
+                # If fetching releases fails for a repo, skip it (could be permissions or no releases)
+                continue
+        return releases
+
+    def get_branches(self) -> List[str]:
+        """
+        Get all branches in the repository.
+        Returns:
+            List[str]: List of branch names.
+        Raises:
+            Exception: If API rate limits are exceeded or authentication fails.
+        """
+        logger.debug("Fetching branches from all accessible repositories")
+        try:
+            branches = []
+            for repo in self.repos:
+                if self.repo_filter and repo.name not in self.repo_filter:
+                    continue
+                logger.debug(f"Fetching branches for repository: {repo.name}")
+                repo_branches = repo.get_branches()
+                for branch in repo_branches:
+                    branches.append(branch.name)
+            logger.debug(f"Successfully fetched {len(branches)} branches")
+            return branches
+        except GithubException as e:
+            if e.status == 403:
+                logger.error(f"Rate limit exceeded or authentication failed: {str(e)}")
+                raise Exception(f"Failed to fetch branches: Rate limit exceeded or authentication failed - {str(e)}")
+            elif e.status == 401:
+                logger.error(f"Authentication failed: {str(e)}")
+                raise Exception(f"Failed to fetch branches: Authentication failed - {str(e)}")
+            else:
+                logger.error(f"GitHub API error while fetching branches: {str(e)}")
+                raise Exception(f"Failed to fetch branches: {str(e)}")
+        except Exception as e:
+            logger.error(f"Unexpected error while fetching branches: {str(e)}")
+            raise Exception(f"Failed to fetch branches: {str(e)}")
+
+    def get_valid_target_branches(self, source_branch: str) -> List[str]:
+        """
+        Get branches that can receive a pull request from the source branch.
+        Validates that the source branch exists, filters out branches with existing
+        open PRs from source, excludes the source branch itself, and optionally
+        checks if source is ahead of target.
+        Args:
+            source_branch (str): The source branch name.
+        Returns:
+            List[str]: List of valid target branch names.
+        Raises:
+            ValueError: If source branch does not exist.
+            Exception: If API errors occur during validation.
+        """
+        logger.debug(f"Validating target branches for source branch: {source_branch}")
+        try:
+            all_branches = self.get_branches()
+            if source_branch not in all_branches:
+                logger.error(f"Source branch '{source_branch}' does not exist")
+                raise ValueError(f"Source branch '{source_branch}' does not exist")
+            valid_targets = []
+            for repo in self.repos:
+                if self.repo_filter and repo.name not in self.repo_filter:
+                    continue
+                logger.debug(f"Processing repository: {repo.name}")
+                repo_branches = [branch.name for branch in repo.get_branches()]
+                # Get existing open PRs from source branch
+                try:
+                    open_prs = repo.get_pulls(state='open', head=source_branch)
+                except GithubException as e:
+                    logger.error(f"GitHub API error while getting PRs: {str(e)}")
+                    raise Exception(f"Failed to validate target branches: {str(e)}")
+                existing_pr_targets = set()
+                for pr in open_prs:
+                    existing_pr_targets.add(pr.base.ref)
+                    logger.debug(f"Found existing PR from {source_branch} to {pr.base.ref}")
+                for branch_name in repo_branches:
+                    if branch_name == source_branch:
+                        logger.debug(f"Excluding source branch: {branch_name}")
+                        continue
+                    if branch_name in existing_pr_targets:
+                        logger.debug(f"Excluding branch with existing PR: {branch_name}")
+                        continue
+                    # Optionally check if source is ahead of target (performance cost)
+                    valid_targets.append(branch_name)
+                    logger.debug(f"Valid target branch: {branch_name}")
+            logger.debug(f"Found {len(valid_targets)} valid target branches")
+            return valid_targets
+        except ValueError:
+            raise
+        except GithubException as e:
+            logger.error(f"GitHub API error while validating target branches: {str(e)}")
+            raise Exception(f"Failed to validate target branches: {str(e)}")
+        except Exception as e:
+            logger.error(f"Unexpected error while validating target branches: {str(e)}")
+            raise Exception(f"Failed to validate target branches: {str(e)}")
+
+    def create_pull_request(
+        self,
+        head_branch: str,
+        base_branch: str,
+        title: str,
+        body: str,
+        draft: bool = False,
+        reviewers: Optional[List[str]] = None,
+        assignees: Optional[List[str]] = None,
+        labels: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a pull request between two branches with optional metadata.
+        Args:
+            head_branch: Source branch for the PR.
+            base_branch: Target branch for the PR.
+            title: PR title.
+            body: PR description.
+            draft: Whether to create as draft PR (default: False).
+            reviewers: List of reviewer usernames (optional).
+            assignees: List of assignee usernames (optional).
+            labels: List of label names (optional).
+        Returns:
+            Dict[str, Any]: Dictionary containing PR metadata or error information.
+        Raises:
+            ValueError: If branches don't exist or PR already exists.
+        """
+        logger.info(f"Creating pull request from {head_branch} to {base_branch}")
+        try:
+            all_branches = self.get_branches()
+            if head_branch not in all_branches:
+                logger.error(f"Head branch '{head_branch}' does not exist")
+                raise ValueError(f"Head branch '{head_branch}' does not exist")
+            if base_branch not in all_branches:
+                logger.error(f"Base branch '{base_branch}' does not exist")
+                raise ValueError(f"Base branch '{base_branch}' does not exist")
+            for repo in self.repos:
+                if self.repo_filter and repo.name not in self.repo_filter:
+                    continue
+                logger.debug(f"Checking for existing PRs in repository: {repo.name}")
+                try:
+                    existing_prs = repo.get_pulls(state='open', head=head_branch, base=base_branch)
+                except GithubException as e:
+                    logger.error(f"GitHub API error while getting PRs: {str(e)}")
+                    raise
+                if hasattr(existing_prs, "totalCount") and existing_prs.totalCount > 0:
+                    logger.error(f"Pull request already exists from {head_branch} to {base_branch}")
+                    raise ValueError(f"Pull request already exists from {head_branch} to {base_branch}")
+                elif isinstance(existing_prs, list) and len(existing_prs) > 0:
+                    logger.error(f"Pull request already exists from {head_branch} to {base_branch}")
+                    raise ValueError(f"Pull request already exists from {head_branch} to {base_branch}")
+                logger.info(f"Creating pull request in repository: {repo.name}")
+                try:
+                    pr = repo.create_pull(
+                        title=title,
+                        body=body,
+                        head=head_branch,
+                        base=base_branch,
+                        draft=draft
+                    )
+                    logger.info(f"Pull request created successfully: {pr.html_url}")
+                    if reviewers and len(reviewers) > 0:
+                        try:
+                            logger.debug(f"Adding reviewers: {reviewers}")
+                            pr.create_review_request(reviewers=reviewers)
+                            logger.info(f"Successfully added reviewers: {reviewers}")
+                        except GithubException as e:
+                            logger.warning(f"Failed to add reviewers: {str(e)}")
+                    if assignees and len(assignees) > 0:
+                        try:
+                            logger.debug(f"Adding assignees: {assignees}")
+                            pr.add_to_assignees(*assignees)
+                            logger.info(f"Successfully added assignees: {assignees}")
+                        except GithubException as e:
+                            logger.warning(f"Failed to add assignees: {str(e)}")
+                    if labels and len(labels) > 0:
+                        try:
+                            logger.debug(f"Adding labels: {labels}")
+                            pr.add_to_labels(*labels)
+                            logger.info(f"Successfully added labels: {labels}")
+                        except GithubException as e:
+                            logger.warning(f"Failed to add labels: {str(e)}")
+                    return {
+                        "url": pr.html_url,
+                        "number": pr.number,
+                        "state": pr.state,
+                        "success": True
+                    }
+                except GithubException as e:
+                    if e.status == 404:
+                        logger.error(f"Branch not found: {str(e)}")
+                        raise ValueError(f"Branch not found: {str(e)}")
+                    elif e.status == 403:
+                        logger.error(f"Permission denied: {str(e)}")
+                        raise GithubException(e.status, f"Permission denied: {str(e)}", e.headers)
+                    elif e.status == 422:
+                        logger.error(f"Merge conflict or validation error: {str(e)}")
+                        raise ValueError(f"Merge conflict or validation error: {str(e)}")
+                    else:
+                        logger.error(f"GitHub API error: {str(e)}")
+                        raise
+            logger.error("No repository found to create pull request")
+            raise ValueError("No repository found to create pull request")
+        except (ValueError, GithubException):
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error while creating pull request: {str(e)}")
+            raise Exception(f"Failed to create pull request: {str(e)}")

git_recap/providers/gitlab_fetcher.py

@@ -1,14 +1,40 @@
 import gitlab
 from datetime import datetime
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Optional
 from git_recap.providers.base_fetcher import BaseFetcher
 
 class GitLabFetcher(BaseFetcher):
-    def __init__(self, pat: str, url: str = 'https://gitlab.com', start_date=None, end_date=None, repo_filter=None, authors=None):
+    """
+    Fetcher implementation for GitLab repositories.
+
+    Supports fetching commits, merge requests (pull requests), and issues.
+    Release fetching is not supported and will raise NotImplementedError.
+    """
+
+    def __init__(
+        self,
+        pat: str,
+        url: str = 'https://gitlab.com',
+        start_date=None,
+        end_date=None,
+        repo_filter=None,
+        authors=None
+    ):
+        """
+        Initialize the GitLabFetcher.
+
+        Args:
+            pat (str): Personal Access Token for GitLab.
+            url (str): The GitLab instance URL.
+            start_date (datetime, optional): Start date for filtering entries.
+            end_date (datetime, optional): End date for filtering entries.
+            repo_filter (List[str], optional): List of repository names to filter.
+            authors (List[str], optional): List of author usernames.
+        """
         super().__init__(pat, start_date, end_date, repo_filter, authors)
         self.gl = gitlab.Gitlab(url, private_token=self.pat)
         self.gl.auth()
-        # Instead of only owned projects, retrieve projects where you're a member.
+        # Retrieve projects where the user is a member.
         self.projects = self.gl.projects.list(membership=True, all=True)
         # Default to the authenticated user's username if no authors are provided.
         if authors is None:
@@ -17,11 +43,12 @@ class GitLabFetcher(BaseFetcher):
             self.authors = authors
 
     @property
-    def repos_names(self)->List[str]:
-        "to be implemented later"
+    def repos_names(self) -> List[str]:
+        """Return the list of repository names."""
         return [project.name for project in self.projects]
 
     def _filter_by_date(self, date_str: str) -> bool:
+        """Check if a date string is within the configured date range."""
         date_obj = datetime.fromisoformat(date_str)
         if self.start_date and date_obj < self.start_date:
             return False
@@ -30,12 +57,19 @@ class GitLabFetcher(BaseFetcher):
         return True
 
     def _stop_fetching(self, date_str: str) -> bool:
+        """Determine if fetching should stop based on the date string."""
         date_obj = datetime.fromisoformat(date_str)
         if self.start_date and date_obj < self.start_date:
             return True
         return False
 
     def fetch_commits(self) -> List[Dict[str, Any]]:
+        """
+        Fetch commits for all projects and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of commit entries.
+        """
         entries = []
         processed_commits = set()
         for project in self.projects:
@@ -63,6 +97,12 @@ class GitLabFetcher(BaseFetcher):
         return entries
 
     def fetch_pull_requests(self) -> List[Dict[str, Any]]:
+        """
+        Fetch merge requests (pull requests) and their associated commits for all projects and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of pull request and commit_from_pr entries.
+        """
         entries = []
         processed_pr_commits = set()
         for project in self.projects:
@@ -109,6 +149,12 @@ class GitLabFetcher(BaseFetcher):
         return entries
 
     def fetch_issues(self) -> List[Dict[str, Any]]:
+        """
+        Fetch issues assigned to the authenticated user for all projects.
+
+        Returns:
+            List[Dict[str, Any]]: List of issue entries.
+        """
         entries = []
         for project in self.projects:
             if self.repo_filter and project.name not in self.repo_filter:
@@ -126,4 +172,78 @@ class GitLabFetcher(BaseFetcher):
                     entries.append(entry)
                 if self._stop_fetching(issue_date):
                     break
-        return entries
+        return entries
+
+    def fetch_releases(self) -> List[Dict[str, Any]]:
+        """
+        Fetch releases for GitLab repositories.
+
+        Not implemented for GitLabFetcher.
+
+        Raises:
+            NotImplementedError: Always, since release fetching is not supported for GitLabFetcher.
+        """
+        raise NotImplementedError("Release fetching is not supported for GitLab (GitLabFetcher).")
+
+    def get_branches(self) -> List[str]:
+        """
+        Get all branches in the repository.
+        
+        Returns:
+            List[str]: List of branch names.
+        
+        Raises:
+            NotImplementedError: Always, since branch listing is not yet implemented for GitLabFetcher.
+        """
+        raise NotImplementedError("Branch listing is not yet implemented for GitLab (GitLabFetcher).")
+
+    def get_valid_target_branches(self, source_branch: str) -> List[str]:
+        """
+        Get branches that can receive a pull request from the source branch.
+        
+        Validates that the source branch exists, filters out branches with existing
+        open PRs from source, excludes the source branch itself, and optionally
+        checks if source is ahead of target.
+        
+        Args:
+            source_branch (str): The source branch name.
+        
+        Returns:
+            List[str]: List of valid target branch names.
+        
+        Raises:
+            NotImplementedError: Always, since PR target validation is not yet implemented for GitLabFetcher.
+        """
+        raise NotImplementedError("Pull request target branch validation is not yet implemented for GitLab (GitLabFetcher).")
+
+    def create_pull_request(
+        self,
+        head_branch: str,
+        base_branch: str,
+        title: str,
+        body: str,
+        draft: bool = False,
+        reviewers: Optional[List[str]] = None,
+        assignees: Optional[List[str]] = None,
+        labels: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a pull request (merge request) between two branches with optional metadata.
+        
+        Args:
+            head_branch: Source branch for the PR.
+            base_branch: Target branch for the PR.
+            title: PR title.
+            body: PR description.
+            draft: Whether to create as draft PR (default: False).
+            reviewers: List of reviewer usernames (optional).
+            assignees: List of assignee usernames (optional).
+            labels: List of label names (optional).
+        
+        Returns:
+            Dict[str, Any]: Dictionary containing PR metadata (url, number, state, success) or error information.
+        
+        Raises:
+            NotImplementedError: Always, since PR creation is not yet implemented for GitLabFetcher.
+        """
+        raise NotImplementedError("Pull request (merge request) creation is not yet implemented for GitLab (GitLabFetcher).")

git_recap/providers/url_fetcher.py

@@ -11,14 +11,14 @@ from git_recap.providers.base_fetcher import BaseFetcher
 
 class URLFetcher(BaseFetcher):
     """Fetcher implementation for generic Git repository URLs."""
-    
+
     GIT_URL_PATTERN = re.compile(
         r'^(?:http|https|git|ssh)://'  # Protocol
         r'(?:\S+@)?'  # Optional username
         r'([^/]+)'  # Domain
         r'(?:[:/])([^/]+/[^/]+?)(?:\.git)?$'  # Repo path
     )
-    
+
     def __init__(
         self,
         url: str,
@@ -52,7 +52,7 @@ class URLFetcher(BaseFetcher):
         """Validate the Git repository URL using git ls-remote."""
         if not self.GIT_URL_PATTERN.match(self.url):
             raise ValueError(f"Invalid Git repository URL format: {self.url}")
-            
+
         try:
             result = subprocess.run(
                 ["git", "ls-remote", self.url],
@@ -80,7 +80,7 @@ class URLFetcher(BaseFetcher):
                 text=True,
                 timeout=300
             )
-            
+
             # Fetch all branches
             subprocess.run(
                 ["git", "-C", self.temp_dir, "fetch", "--all"],
@@ -89,7 +89,7 @@ class URLFetcher(BaseFetcher):
                 text=True,
                 timeout=300
             )
-            
+
             # Verify the cloned repository has at least one commit
             verify_result = subprocess.run(
                 ["git", "-C", self.temp_dir, "rev-list", "--count", "--all"],
@@ -99,7 +99,7 @@ class URLFetcher(BaseFetcher):
             )
             if int(verify_result.stdout.strip()) == 0:
                 raise ValueError("Cloned repository has no commits")
-                
+
         except subprocess.TimeoutExpired:
             raise RuntimeError("Repository cloning timed out")
         except subprocess.CalledProcessError as e:
@@ -113,23 +113,23 @@ class URLFetcher(BaseFetcher):
         """Return list of repository names (single item for URL fetcher)."""
         if not self.temp_dir:
             return []
-        
+
         match = self.GIT_URL_PATTERN.match(self.url)
         if not match:
             repo_name = self.url.split('/')[-1]
             return [repo_name]
-            
+
         repo_name = match.group(2).split('/')[-1]
         if repo_name.endswith(".git"):
             repo_name = repo_name[:-4]
-            
+
         return [repo_name]
 
     def _get_all_branches(self) -> List[str]:
         """Get list of all remote branches in the repository."""
         if not self.temp_dir:
             return []
-            
+
         try:
             result = subprocess.run(
                 ["git", "-C", self.temp_dir, "branch", "-r", "--format=%(refname:short)"],
@@ -187,11 +187,11 @@ class URLFetcher(BaseFetcher):
         for line in log_output.splitlines():
             if not line.strip():
                 continue
-                
+
             try:
                 sha, author, date_str, message = line.split("|", 3)
                 timestamp = datetime.fromisoformat(date_str)
-                
+
                 if self.start_date and timestamp < self.start_date:
                     continue
                 if self.end_date and timestamp > self.end_date:
@@ -207,7 +207,7 @@ class URLFetcher(BaseFetcher):
                 })
             except ValueError:
                 continue  # Skip malformed log entries
-                
+
         return entries
 
     def fetch_commits(self) -> List[Dict[str, Any]]:
@@ -222,6 +222,74 @@ class URLFetcher(BaseFetcher):
         """Fetch issues (not implemented for generic Git URLs)."""
         return []
 
+    def fetch_releases(self) -> List[Dict[str, Any]]:
+        """
+        Fetch releases for the repository.
+        Not implemented for generic Git URLs.
+        Raises:
+            NotImplementedError: Always, since release fetching is not supported for URLFetcher.
+        """
+        raise NotImplementedError("Release fetching is not supported for generic Git URLs (URLFetcher).")
+
+    def get_branches(self) -> List[str]:
+        """
+        Get all branches in the repository.
+        
+        Returns:
+            List[str]: List of branch names.
+        
+        Raises:
+            NotImplementedError: Always, since branch listing is not yet implemented for URLFetcher.
+        """
+        raise NotImplementedError("Branch listing is not yet implemented for generic Git URLs (URLFetcher).")
+
+    def get_valid_target_branches(self, source_branch: str) -> List[str]:
+        """
+        Get branches that can receive a pull request from the source branch.
+        
+        Args:
+            source_branch (str): The source branch name.
+        
+        Returns:
+            List[str]: List of valid target branch names.
+        
+        Raises:
+            NotImplementedError: Always, since PR target validation is not supported for URLFetcher.
+        """
+        raise NotImplementedError("Pull request target branch validation is not supported for generic Git URLs (URLFetcher).")
+
+    def create_pull_request(
+        self,
+        head_branch: str,
+        base_branch: str,
+        title: str,
+        body: str,
+        draft: bool = False,
+        reviewers: Optional[List[str]] = None,
+        assignees: Optional[List[str]] = None,
+        labels: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a pull request between two branches.
+        
+        Args:
+            head_branch: Source branch for the PR.
+            base_branch: Target branch for the PR.
+            title: PR title.
+            body: PR description.
+            draft: Whether to create as draft PR (default: False).
+            reviewers: List of reviewer usernames (optional).
+            assignees: List of assignee usernames (optional).
+            labels: List of label names (optional).
+        
+        Returns:
+            Dict[str, Any]: Dictionary containing PR metadata or error information.
+        
+        Raises:
+            NotImplementedError: Always, since PR creation is not supported for URLFetcher.
+        """
+        raise NotImplementedError("Pull request creation is not supported for generic Git URLs (URLFetcher).")
+
     def clear(self) -> None:
         """Clean up temporary directory."""
         if self.temp_dir and os.path.exists(self.temp_dir):

git_recap/utils.py

@@ -54,40 +54,94 @@ def parse_entries_to_txt(entries: List[Dict[str, Any]]) -> str:
     
     return "\n".join(lines)
 
-# Example usage:
-if __name__ == "__main__":
-    # Assuming `output` is the list of dict entries from your fetcher.
-    output = [
-        {
-            "type": "commit_from_pr",
-            "repo": "AiCore",
-            "message": "feat: update TODOs for ObservabilityDashboard with new input/output tokens and cross workspace analysis",
-            "timestamp": "2025-03-14T00:17:02+00:00",
-            "sha": "d1f185f09e4fcb775374b9468755b8463c94a605",
-            "pr_title": "Unified ai integration error monitoring"
-        },
-        {
-            "type": "commit_from_pr",
-            "repo": "AiCore",
-            "message": "feat: enhance token usage visualization in ObservabilityDashboard with grouped bar chart",
-            "timestamp": "2025-03-15T00:20:15+00:00",
-            "sha": "875457b9c80076d821f36cc646ec354ef5124088",
-            "pr_title": "Unified ai integration error monitoring"
-        },
-        {
-            "type": "pull_request",
-            "repo": "AiCore",
-            "message": "Unified ai integration error monitoring",
-            "timestamp": "2025-03-15T21:47:13+00:00",
-            "pr_number": 5
-        },
-        {
-            "type": "commit",
-            "repo": "AiCore",
-            "message": "feat: update openai package version to 1.66.3 in requirements.txt and setup.py",
-            "timestamp": "2025-03-15T23:22:28+00:00",
-            "sha": "9f7e30ebcca8c909274dd8ca91fcfbd17bbf9195"
-        },
-    ]
-    context_txt = parse_entries_to_txt(output)
-    print(context_txt)
+def parse_releases_to_txt(releases: List[Dict[str, Any]]) -> str:
+    """
+    Groups releases by day (YYYY-MM-DD, using published_at or created_at) and produces a plain text summary.
+
+    Each day's header is the date string, followed by a clear, LLM-friendly separator between releases:
+      - tag name and release name
+      - repo name
+      - author
+      - draft/prerelease status
+      - body/notes (if present)
+      - assets (if present)
+    """
+    grouped = defaultdict(list)
+    for rel in releases:
+        ts = rel.get("published_at") or rel.get("created_at")
+        if isinstance(ts, str):
+            dt = datetime.fromisoformat(ts)
+        else:
+            dt = ts
+        day = dt.strftime("%Y-%m-%d")
+        grouped[day].append(rel)
+
+    sorted_days = sorted(grouped.keys())
+
+    lines = []
+    for day in sorted_days:
+        lines.append(f"Date: {day}")
+        day_releases = sorted(grouped[day], key=lambda x: x.get("published_at") or x.get("created_at"))
+        for rel in day_releases:
+            lines.append("----- Release Start -----")
+            tag = rel.get("tag_name", "N/A")
+            name = rel.get("name", "")
+            repo = rel.get("repo", "N/A")
+            author = rel.get("author", "N/A")
+            draft = rel.get("draft", False)
+            prerelease = rel.get("prerelease", False)
+            body = rel.get("body", "")
+            assets = rel.get("assets", [])
+            
+            status = []
+            if draft:
+                status.append("draft")
+            if prerelease:
+                status.append("prerelease")
+            status_str = f" ({', '.join(status)})" if status else ""
+
+            lines.append(f"Release: {name}")
+            lines.append(f"Repository: {repo}")
+            lines.append(f"Tag: {tag}")
+            lines.append(f"Author: {author}")
+            if status_str:
+                lines.append(f"Status: {status_str.strip()}")
+            if body and body.strip():
+                lines.append(f"Notes: {body.strip()}")
+            if assets:
+                lines.append("Assets:")
+                for asset in assets:
+                    asset_name = asset.get("name", "N/A")
+                    asset_size = asset.get("size", "N/A")
+                    asset_url = asset.get("download_url", "")
+                    lines.append(f"  - {asset_name} ({asset_size} bytes){' - ' + asset_url if asset_url else ''}")
+            lines.append("----- Release End -----\n")  # clear end of release
+
+        lines.append("")  # blank line between days
+
+    return "\n".join(lines)
+
+
+# Example usage for releases:
+# if __name__ == "__main__":
+#     releases = [
+#         {
+#             "tag_name": "v1.0.0",
+#             "name": "Release 1.0.0",
+#             "repo": "test-repo",
+#             "author": "testuser",
+#             "published_at": "2025-03-15T10:00:00",
+#             "created_at": "2025-03-15T09:00:00",
+#             "draft": False,
+#             "prerelease": False,
+#             "body": "This is a test release",
+#             "assets": [
+#                 {
+#                     "name": "test-asset.zip",
+#                     "size": 1024,
+#                     "download_url": "https://github.com/test/releases/download/v1.0.0/test-asset.zip",
+#                 }
+#             ],
+#         }
+#     ]
+#     print(parse_releases_to_txt(releases))

{git_recap-0.1.3.dist-info → git_recap-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-recap
-Version: 0.1.3
+Version: 0.1.5
 Summary: A modular Python tool that aggregates and formats user-authored messages from repositories.
 Author: Bruno V.
 Author-email: bruno.vitorino@tecnico.ulisboa.pt
@@ -21,8 +21,16 @@ Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: summary
 
+<a href="https://www.uneed.best/tool/gitrecap">
+  <img src="https://www.uneed.best/POTD2A.png" style="width: 250px;" alt="Uneed POTD2 Badge" />
+</a>
+
+---
+
 # Git Recap
 
+🎉 **Featured in Uneed's Latest Newsletter as a Staff Pick!** 🎉
+
 Git Recap is a modular Python tool that aggregates and formats user-authored messages from repositories hosted on GitHub, Azure DevOps, and GitLab. It fetches commit messages, pull requests (along with their associated commits), and issues, then consolidates and sorts these events into a clear, chronological summary. This summary is output as a plain text string that can serve as context for large language models or other analysis tools.
 
 ## Features

git_recap-0.1.5.dist-info/RECORD

@@ -0,0 +1,14 @@
+git_recap/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+git_recap/fetcher.py,sha256=oRlenzd9OsiBkCtpUgSZGlUoUnVpdkolUZhFOF1USBs,2677
+git_recap/utils.py,sha256=NAG0cvm1sYKEQD5E9PueduB3CZQRTahrioxZNgwwmi4,5481
+git_recap/providers/__init__.py,sha256=njrsu58KB60-wN78P0egm1lkQLIRq_PHLKM4WBt39Os,330
+git_recap/providers/azure_fetcher.py,sha256=ex1XX1SZ5xgWDSEQdsAtaKGaOK21pem_sWdoPZe2DNE,13152
+git_recap/providers/base_fetcher.py,sha256=yqVHTVAPlsDPD85SESx1u6SHeT_I9XLv41SnFo_ESPQ,7472
+git_recap/providers/github_fetcher.py,sha256=pSvpaAoE2-lK-rEwvpliOZh-oIiI0SulHMuiYaqiEts,19239
+git_recap/providers/gitlab_fetcher.py,sha256=i9W00H-DLyc-R--KxWbVy4CSDbORf_BmWcKveWulyzs,9752
+git_recap/providers/url_fetcher.py,sha256=hwASWC8j17P37qLoQxO6WeT1EZ2AqwtYc9kiXKHLBhQ,10753
+git_recap-0.1.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+git_recap-0.1.5.dist-info/METADATA,sha256=CbKCAeuSX9PBSxb8HpYea_OZi8dlzgIpB44Vgur9aNY,4946
+git_recap-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+git_recap-0.1.5.dist-info/top_level.txt,sha256=1JUKd3WPB8c3LcD1deIW-1UTmYzA0zJqwugAz72YZ_o,10
+git_recap-0.1.5.dist-info/RECORD,,

{git_recap-0.1.3.dist-info → git_recap-0.1.5.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (79.0.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

git_recap-0.1.3.dist-info/RECORD

@@ -1,14 +0,0 @@
-git_recap/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-git_recap/fetcher.py,sha256=oRlenzd9OsiBkCtpUgSZGlUoUnVpdkolUZhFOF1USBs,2677
-git_recap/utils.py,sha256=mAGZ6bNklBmE-qpA6RG17_Bka8WRXzjLRAAGS9p3QXk,3646
-git_recap/providers/__init__.py,sha256=njrsu58KB60-wN78P0egm1lkQLIRq_PHLKM4WBt39Os,330
-git_recap/providers/azure_fetcher.py,sha256=PfPEeWTtx1Fqa1jClFPKqXhY5Yvs8MyEkSJkLAl4QvQ,7241
-git_recap/providers/base_fetcher.py,sha256=SS35FP8B9_RwnU6CnMbcV9g5_YRWp7v-S7pwbt402Ng,3067
-git_recap/providers/github_fetcher.py,sha256=rDb00RVy2NMpwv8s8Ry1-UjS6wf1Sh2Ndl0xKOZXMxU,4998
-git_recap/providers/gitlab_fetcher.py,sha256=ch1V9O-MPv5_nyg9yLs6EC9e-yqsFXBXMm6xVevWzuQ,5396
-git_recap/providers/url_fetcher.py,sha256=ofpwpwygJFlW9x7pU2PrO-tn6XcykWDSJbXeBV1KK3c,8337
-git_recap-0.1.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-git_recap-0.1.3.dist-info/METADATA,sha256=-6OhqY14z1qf3BjkUaH6LNGXeAkTy2A_-1gXiwtRRIY,4721
-git_recap-0.1.3.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
-git_recap-0.1.3.dist-info/top_level.txt,sha256=1JUKd3WPB8c3LcD1deIW-1UTmYzA0zJqwugAz72YZ_o,10
-git_recap-0.1.3.dist-info/RECORD,,