git-recap 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

git_recap/cli.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""
+GitRecap CLI - LLM-Friendly Command Line Interface
+
+This CLI tool fetches and summarizes git commit history from local repositories.
+It's designed to be easily used by LLMs and automated tools with clear, structured output.
+
+Usage Examples:
+    # Get commits from current directory (last 7 days)
+    git-recap .
+
+    # Get commits from multiple repositories
+    git-recap /path/to/repo1 /path/to/repo2
+
+    # Filter by author
+    git-recap . --author "John Doe"
+
+    # Filter by date range
+    git-recap . --start-date "2025-01-01" --end-date "2025-01-31"
+
+    # Save output to file
+    git-recap . --output summary.txt
+
+    # Combine filters
+    git-recap /path/to/repo1 /path/to/repo2 --author "Jane Smith" --start-date "2025-01-01" --output commits.txt
+"""
+
+import argparse
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+from git_recap.providers.local_fetcher import LocalFetcher
+from git_recap.utils import parse_entries_to_txt
+
+
+def parse_date(date_string: str) -> datetime:
+    """
+    Parse date string in ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS).
+    
+    Args:
+        date_string: Date string to parse
+        
+    Returns:
+        datetime: Parsed datetime object
+        
+    Raises:
+        argparse.ArgumentTypeError: If date format is invalid
+    """
+    try:
+        # Try parsing with time first
+        return datetime.fromisoformat(date_string)
+    except ValueError:
+        # Try parsing as date only (YYYY-MM-DD)
+        try:
+            return datetime.strptime(date_string, "%Y-%m-%d")
+        except ValueError:
+            raise argparse.ArgumentTypeError(
+                f"Invalid date format: '{date_string}'. "
+                f"Use ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS"
+            )
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """
+    Create and configure the argument parser for the CLI.
+    
+    Returns:
+        argparse.ArgumentParser: Configured parser with all arguments
+    """
+    parser = argparse.ArgumentParser(
+        prog='git-recap',
+        description=(
+            'GitRecap CLI - Fetch and summarize git commits from local repositories.\n\n'
+            'This tool aggregates commit history from multiple local git repositories, '
+            'filters by author and date range, and outputs structured text summaries. '
+            'Designed for easy integration with LLMs and automated workflows.'
+        ),
+        epilog=(
+            'Examples:\n'
+            '  git-recap .                                    # Current directory, last 7 days\n'
+            '  git-recap /path/to/repo1 /path/to/repo2        # Multiple repositories\n'
+            '  git-recap . --author "John Doe"               # Filter by author\n'
+            '  git-recap . --start-date "2025-01-01"         # From specific date\n'
+            '  git-recap . --output summary.txt               # Save to file\n'
+            '  git-recap . --author "Jane" --start-date "2025-01-01" --end-date "2025-01-31" --output commits.txt'
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    
+    parser.add_argument(
+        'paths',
+        nargs='+',
+        help=(
+            'One or more paths to local git repositories. '
+            'Each path must be a valid git repository (contains .git directory). '
+            'Can be absolute or relative paths. Multiple paths can be provided.'
+        )
+    )
+    
+    parser.add_argument(
+        '--author',
+        type=str,
+        help=(
+            'Filter commits by author name. '
+            'Partial matching is supported (e.g., "John" matches "John Doe"). '
+            'If not specified, commits from all authors are included.'
+        )
+    )
+    
+    parser.add_argument(
+        '--start-date',
+        type=parse_date,
+        help=(
+            'Start date for filtering commits (inclusive). '
+            'Format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. '
+            'If not specified, defaults to 7 days before current date.'
+        )
+    )
+    
+    parser.add_argument(
+        '--end-date',
+        type=parse_date,
+        help=(
+            'End date for filtering commits (inclusive). '
+            'Format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. '
+            'If not specified, defaults to current date and time.'
+        )
+    )
+    
+    parser.add_argument(
+        '--output', '-o',
+        type=str,
+        help=(
+            'Output file path to save the summary. '
+            'If not specified, results are printed to stdout. '
+            'The file will be created or overwritten if it exists.'
+        )
+    )
+    
+    return parser
+
+
+def filter_entries_by_author(
+    entries: List[Dict[str, Any]], 
+    author: str
+) -> List[Dict[str, Any]]:
+    """
+    Filter entries by author name (case-insensitive partial match).
+    
+    Args:
+        entries: List of commit entries
+        author: Author name to filter by
+        
+    Returns:
+        List[Dict[str, Any]]: Filtered entries matching the author
+    """
+    author_lower = author.lower()
+    return [
+        entry for entry in entries 
+        if author_lower in entry.get('author', '').lower()
+    ]
+
+
+def fetch_from_repos(
+    repo_paths: List[str],
+    authors: Optional[List[str]] = None,
+    start_date: Optional[datetime] = None,
+    end_date: Optional[datetime] = None
+) -> List[Dict[str, Any]]:
+    """
+    Fetch commits from multiple local repositories.
+    
+    Args:
+        repo_paths: List of repository paths
+        authors: Optional list of author names to filter by
+        start_date: Optional start date for filtering
+        end_date: Optional end date for filtering
+        
+    Returns:
+        List[Dict[str, Any]]: Aggregated list of commit entries from all repos
+    """
+    all_entries = []
+    
+    for repo_path in repo_paths:
+        try:
+            print(f"Fetching from: {repo_path}", file=sys.stderr)
+            fetcher = LocalFetcher(
+                repo_path=repo_path,
+                authors=authors,
+                start_date=start_date,
+                end_date=end_date,
+                validate_repo=True
+            )
+            entries = fetcher.fetch_commits()
+            all_entries.extend(entries)
+            print(f"  Found {len(entries)} commits", file=sys.stderr)
+        except ValueError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            continue
+        except Exception as e:
+            print(f"Unexpected error processing {repo_path}: {e}", file=sys.stderr)
+            continue
+    
+    return all_entries
+
+
+def main() -> int:
+    """
+    Main entry point for the CLI.
+    
+    Returns:
+        int: Exit code (0 for success, 1 for error)
+    """
+    parser = create_parser()
+    args = parser.parse_args()
+    
+    # Set default date range if not provided
+    if not args.start_date and not args.end_date:
+        # Default: last 7 days
+        from datetime import timedelta
+        args.end_date = datetime.now()
+        args.start_date = args.end_date - timedelta(days=7)
+    elif not args.start_date:
+        # Only end date provided, start from 7 days before end
+        from datetime import timedelta
+        args.start_date = args.end_date - timedelta(days=7)
+    elif not args.end_date:
+        # Only start date provided, use current time as end
+        args.end_date = datetime.now()
+    
+    # Prepare authors list
+    authors = [args.author] if args.author else None
+    
+    # Fetch commits from all repositories
+    entries = fetch_from_repos(
+        repo_paths=args.paths,
+        authors=authors,
+        start_date=args.start_date,
+        end_date=args.end_date
+    )
+    
+    # Check if we found any entries
+    if not entries:
+        print("No commits found matching the specified criteria.", file=sys.stderr)
+        return 0
+    
+    # Convert entries to text format
+    output_text = parse_entries_to_txt(entries)
+    
+    # Output to file or stdout
+    if args.output:
+        try:
+            output_path = Path(args.output)
+            # Create parent directories if they don't exist
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(output_text, encoding='utf-8')
+            print(f"Summary saved to: {args.output}", file=sys.stderr)
+        except Exception as e:
+            print(f"Error writing to file {args.output}: {e}", file=sys.stderr)
+            return 1
+    else:
+        print(output_text)
+    
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

git_recap/fetcher.py

@@ -3,6 +3,7 @@ from datetime import datetime, timedelta
 from git_recap.providers.github_fetcher import GitHubFetcher
 from git_recap.providers.azure_fetcher import AzureFetcher
 from git_recap.providers.gitlab_fetcher import GitLabFetcher
+from git_recap.providers.local_fetcher import LocalFetcher
 
 def main():
     parser = argparse.ArgumentParser(
@@ -11,10 +12,14 @@ def main():
     parser.add_argument(
         '--provider',
         required=True,
-        choices=['github', 'azure', 'gitlab'],
-        help='Platform name (github, azure, or gitlab)'
+        choices=['github', 'azure', 'gitlab', 'local'],
+        help='Platform name (github, azure, gitlab, or local)'
+    )
+    parser.add_argument('--pat', help='Personal Access Token (not required for local provider)')
+    parser.add_argument(
+        '--repo-path',
+        help='Path to local git repository (required for local provider)'
     )
-    parser.add_argument('--pat', required=True, help='Personal Access Token')
     parser.add_argument(
         '--organization-url',
         help='Organization URL for Azure DevOps'
@@ -51,6 +56,9 @@ def main():
     
     fetcher = None
     if args.provider == 'github':
+        if not args.pat:
+            print("PAT is required for GitHub provider")
+            exit(1)
         fetcher = GitHubFetcher(
             pat=args.pat,
             start_date=args.start_date,
@@ -58,6 +66,9 @@ def main():
             repo_filter=args.repos
         )
     elif args.provider == 'azure':
+        if not args.pat:
+            print("PAT is required for Azure DevOps provider")
+            exit(1)
         if not args.organization_url:
             print("Organization URL is required for Azure DevOps")
             exit(1)
@@ -69,6 +80,9 @@ def main():
             repo_filter=args.repos
         )
     elif args.provider == 'gitlab':
+        if not args.pat:
+            print("PAT is required for GitLab provider")
+            exit(1)
         gitlab_url = args.gitlab_url if args.gitlab_url else 'https://gitlab.com'
         fetcher = GitLabFetcher(
             pat=args.pat,
@@ -77,6 +91,16 @@ def main():
             end_date=args.end_date,
             repo_filter=args.repos
         )
+    elif args.provider == 'local':
+        if not args.repo_path:
+            print("--repo-path is required for local provider")
+            exit(1)
+        fetcher = LocalFetcher(
+            repo_path=args.repo_path,
+            start_date=args.start_date,
+            end_date=args.end_date,
+            repo_filter=args.repos
+        )
     
     messages = fetcher.get_authored_messages(limit=args.limit)
     for msg in messages:

git_recap/providers/__init__.py

@@ -2,10 +2,12 @@ from git_recap.providers.azure_fetcher import AzureFetcher
 from git_recap.providers.github_fetcher import GitHubFetcher
 from git_recap.providers.gitlab_fetcher import GitLabFetcher
 from git_recap.providers.url_fetcher import URLFetcher
+from git_recap.providers.local_fetcher import LocalFetcher
 
 __all__ = [
     "AzureFetcher",
     "GitHubFetcher",
     "GitLabFetcher",
-    "URLFetcher"
+    "URLFetcher",
+    "LocalFetcher"
 ]

git_recap/providers/azure_fetcher.py

@@ -1,14 +1,16 @@
 from azure.devops.connection import Connection
 from msrest.authentication import BasicAuthentication
+from azure.devops.exceptions import AzureDevOpsServiceError
 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.
+    Supports fetching commits, pull requests, issues, and authors.
     Release fetching is not supported and will raise NotImplementedError.
     """
 
@@ -30,9 +32,12 @@ class AzureFetcher(BaseFetcher):
         self.connection = Connection(base_url=self.organization_url, creds=credentials)
         self.core_client = self.connection.clients.get_core_client()
         self.git_client = self.connection.clients.get_git_client()
+        
+        # Extract project name from organization URL or use first project
+        projects = self.core_client.get_projects().value
+        self.project_name = projects[0].name if projects else None
+        
         self.repos = self.get_repos()
-        # Azure DevOps doesn't provide an affiliation filter;
-        # we'll iterate over all repos in each project.
         if authors is None:
             self.authors = []
 
@@ -43,8 +48,10 @@ class AzureFetcher(BaseFetcher):
             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]
+        repos = []
+        for project in projects:
+            project_repos = self.git_client.get_repositories(project.id)
+            repos.extend(project_repos)
         return repos
 
     @property
@@ -55,8 +62,7 @@ class AzureFetcher(BaseFetcher):
         Returns:
             List[str]: List of repository names.
         """
-        # To be implemented if needed for UI or listing.
-        ...
+        return [repo.name for repo in self.repos]
 
     def _filter_by_date(self, date_obj: datetime) -> bool:
         """
@@ -103,15 +109,14 @@ class AzureFetcher(BaseFetcher):
             for author in self.authors:
                 try:
                     commits = self.git_client.get_commits(
-                        project=repo.id,
+                        project=repo.project.id,
                         repository_id=repo.id,
                         search_criteria={"author": author}
                     )
                 except Exception:
                     continue
                 for commit in commits:
-                    # Azure DevOps returns a commit with an 'author' property.
-                    commit_date = commit.author.date  # assumed datetime
+                    commit_date = commit.author.date
                     if self._filter_by_date(commit_date):
                         sha = commit.commit_id
                         if sha not in processed_commits:
@@ -151,10 +156,9 @@ class AzureFetcher(BaseFetcher):
                 except Exception:
                     continue
                 for pr in pull_requests:
-                    # Check that the PR creator is one of our authors.
                     if pr.created_by.unique_name not in self.authors:
                         continue
-                    pr_date = pr.creation_date  # type: datetime
+                    pr_date = pr.creation_date
                     if not self._filter_by_date(pr_date):
                         continue
 
@@ -204,7 +208,6 @@ class AzureFetcher(BaseFetcher):
         """
         entries = []
         wit_client = self.connection.clients.get_work_item_tracking_client()
-        # Query work items for each author using a simplified WIQL query.
         for author in self.authors:
             wiql = f"SELECT [System.Id], [System.Title], [System.CreatedDate] FROM WorkItems WHERE [System.AssignedTo] CONTAINS '{author}'"
             try:
@@ -235,5 +238,136 @@ class AzureFetcher(BaseFetcher):
         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).")
+        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.
+        """
+        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.
+        """
+        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.
+        """
+        raise NotImplementedError("Pull request creation is not yet implemented for Azure DevOps (AzureFetcher).")
+
+    def get_authors(self, repo_names: List[str]) -> List[Dict[str, str]]:
+        """
+        Retrieve unique authors from specified Azure DevOps repositories.
+        
+        Args:
+            repo_names: List of repository names.
+                       Empty list fetches from all accessible repositories.
+        
+        Returns:
+            List of unique author dictionaries with name and email.
+        """
+        authors_set = set()
+        
+        try:
+            git_client = self.connection.clients.get_git_client()
+            
+            if not repo_names:
+                repos = self.repos
+            else:
+                repos = [repo for repo in self.repos if repo.name in repo_names]
+            
+            for repo in repos:
+                if self.repo_filter and repo.name not in self.repo_filter:
+                    continue
+                
+                try:
+                    commits = git_client.get_commits(
+                        repository_id=repo.id,
+                        search_criteria={'$top': 1000}
+                    )
+                    
+                    for commit in commits:
+                        if commit.author:
+                            author_name = commit.author.name or "Unknown"
+                            author_email = commit.author.email or "unknown@example.com"
+                            authors_set.add((author_name, author_email))
+                        
+                        if commit.committer:
+                            committer_name = commit.committer.name or "Unknown"
+                            committer_email = commit.committer.email or "unknown@example.com"
+                            authors_set.add((committer_name, committer_email))
+                
+                except AzureDevOpsServiceError as e:
+                    print(f"Error fetching authors from {repo.name}: {e}")
+                    continue
+            
+            authors_list = [
+                {"name": name, "email": email}
+                for name, email in sorted(authors_set)
+            ]
+            
+            return authors_list
+        
+        except Exception as e:
+            print(f"Error in get_authors: {e}")
+            return []
+
+    def get_current_author(self) -> Optional[Dict[str, str]]:
+        """
+        Retrieve the current authenticated user's information.
+        
+        For Azure DevOps, default author functionality is not currently implemented,
+        so this method returns None.
+        
+        Returns:
+            None: Azure DevOps fetcher does not support default author retrieval.
+        """
+        return None

git_recap/providers/base_fetcher.py

@@ -90,6 +90,102 @@ class BaseFetcher(ABC):
         """
         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")
+
+    @abstractmethod
+    def get_authors(self, repo_names: List[str]) -> List[Dict[str, str]]:
+        """
+        Retrieve unique authors from specified repositories.
+        
+        Args:
+            repo_names: List of repository names to fetch authors from.
+                       Empty list means fetch from all available repositories.
+        
+        Returns:
+            List of dictionaries containing author information:
+            [{"name": "John Doe", "email": "john@example.com"}, ...]
+        """
+        pass
+
+    @abstractmethod
+    def get_current_author(self) -> Optional[Dict[str, str]]:
+        """
+        Retrieve the current authenticated user's information.
+        
+        Returns the default authenticated user's name and email if available
+        for the current fetcher session, or None if not applicable for the provider.
+        
+        Returns:
+            Optional[Dict[str, str]]: Dictionary with 'name' and 'email' keys,
+                                     or None if no default author is available.
+                                     Example: {"name": "John Doe", "email": "john@example.com"}
+        """
+        pass
+
     def get_authored_messages(self) -> List[Dict[str, Any]]:
         """
         Aggregates all commit, pull request, and issue entries into a single list,