pkg-30922 1.0.0__py3-none-any.whl

pkg_30922/__init__.py

@@ -0,0 +1,37 @@
+"""
+Main package entry point.
+
+This package provides automated pull request merging functionality for GitHub,
+including repository discovery, PR filtering, merge readiness evaluation, and
+batch merging operations.
+
+Submodules:
+    - config: Configuration loading and validation
+    - services.gh_ci: Merge readiness evaluation with CI and review checks
+    - services.gh_merge: PR merge execution
+    - services.gh_pr: Open PR retrieval and filtering
+    - services.gh_repo: Repository discovery
+    - services.gh_user: GitHub authentication and user info
+"""
+
+from .config import Config, load_config, merge_config_with_cli
+from .services.gh_ci import get_merge_readiness
+from .services.gh_merge import put_merge_pr
+from .services.gh_pr import get_open_prs
+from .services.gh_repo import get_repos_from_all, get_repos_from_owner
+from .services.gh_user import get_auth, get_token_user_info
+
+__version__ = "1.0.0"
+
+__all__ = (
+    "Config",
+    "load_config",
+    "merge_config_with_cli",
+    "get_auth",
+    "get_merge_readiness",
+    "put_merge_pr",
+    "get_open_prs",
+    "get_repos_from_all",
+    "get_repos_from_owner",
+    "get_token_user_info",
+)

pkg_30922/cli.py

@@ -0,0 +1,258 @@
+"""
+CLI tool to automate pull request merging.
+
+This module provides functionality to:
+- Get a list of repositories across organizations and users
+- Filter repositories with open pull requests
+- Filter pull requests by label, base branch, title prefix, and owner
+- Evaluate merge readiness based on CI status and code review approvals
+- Execute batch merge operations across multiple repositories
+
+Key Features:
+- Concurrent processing using asyncio for efficiency
+- Support for dry-run mode to preview merges without executing
+- Filtering by multiple criteria (labels, branch, prefix, owner)
+- Merge method selection (merge, rebase, squash)
+- Bypass review count option to merge without sufficient approvals
+"""
+
+import asyncio
+import os
+import sys
+from typing import Optional
+
+import asyncclick as click
+
+from pkg_30922 import (
+    __version__,
+    get_auth,
+    get_merge_readiness,
+    get_open_prs,
+    get_repos_from_all,
+    get_repos_from_owner,
+    get_token_user_info,
+    put_merge_pr,
+)
+from pkg_30922.config import Config, load_config, merge_config_with_cli
+
+ALLOWED_REPO_TYPES = ["all", "private", "public"]
+ALLOWED_MERGE_METHODS = ["merge", "rebase", "squash"]
+
+
+class CustomError(Exception):
+    pass
+
+
+def check_owner(owner: str, orgs: list[str], login: str) -> None:
+    """
+    Validate that the owner is valid for the authenticated token.
+
+    Args:
+        owner: The owner to validate (username or organization name).
+        orgs: List of organizations the token has access to.
+        login: The authenticated user's login name.
+
+    Raises:
+        CustomError: If owner is not in orgs and doesn't match the token owner.
+    """
+    if owner:
+        if owner not in orgs and owner != login:
+            raise CustomError("CLI option '--owner' is invalid (mismatch what the token suggests)")
+
+
+def find_config_file() -> Optional[str]:
+    """
+    Find configuration file for GitHub Actions users.
+
+    Searches for config file at the default location (./config/default.yaml).
+
+    Returns:
+        Path to config file if found, None otherwise.
+    """
+    config_locations = ["./config/default.yaml"]
+
+    for location in config_locations:
+        if os.path.exists(location):
+            return location
+
+    return None
+
+
+def check_repo_type(repo_type: str) -> None:
+    """
+    Validate the repository type option.
+
+    Args:
+        repo_type: The repository type to validate.
+
+    Raises:
+        CustomError: If repo_type is not one of 'all', 'private', or 'public'.
+    """
+    if repo_type:
+        if not repo_type.strip().lower() in ALLOWED_REPO_TYPES:
+            raise CustomError("CLI option '--repo-type' requires all or private or public")
+
+
+def check_merge_method(merge_method: str) -> None:
+    """
+    Validate the merge method option.
+
+    Args:
+        merge_method: The merge method to validate.
+
+    Raises:
+        CustomError: If merge_method is not one of 'merge', 'rebase', or 'squash'.
+    """
+    if merge_method:
+        if not merge_method.strip().lower() in ALLOWED_MERGE_METHODS:
+            raise CustomError("CLI option '--merge-method' requires merge, rebase, or squash")
+
+
+def print_summary(number_of_open_prs: int, number_of_mergeable_prs: int, number_of_merged_prs: int) -> None:
+    """
+    Print summary
+
+    Args:
+        number_of_open_prs: Number of open pull requests
+        number_of_mergeable_prs: Number of mergeable pull requests
+        number_of_merged_prs: Number of merged pull requests
+    """
+    dict_summary = {}
+    dict_summary["open-prs"] = number_of_open_prs
+    dict_summary["mergeable-prs"] = number_of_mergeable_prs
+    dict_summary["merged-prs"] = number_of_merged_prs
+    print()
+    print(f"🎉 Merge Pull Request Task Info. :: {dict_summary}")
+
+
+@click.command()
+@click.option("--base-branch", type=str, default="main", help="Restrict to a particular base-branch [case-sensitive]")
+@click.option("--bypass-review-count", type=bool, default=False, help="Bypass required review count (default: false)")
+@click.option("--exclude-labels", type=str, default="", help="Restrict to particular labels to excldue")
+@click.option("--include-labels", type=str, default="", help="Restrict to particular labels to incldue")
+@click.option("--merge-method", type=str, default="merge", help="merge|rebase|squash (default: merge)")
+@click.option("--owner", type=str, default="", help="Restrict to a particular user/org")
+@click.option("--prefix", type=str, default="", help="Restrict to a PR title prefix")
+@click.option("--repo-type", type=str, default="all", help="all|private|public (default: all)")
+@click.option("--dry-run", type=bool, default=True, help="Show PR ready for merge (default: true)")
+@click.version_option(version=__version__)
+async def main(
+    base_branch: str,
+    dry_run: bool,
+    exclude_labels: str,
+    include_labels: str,
+    merge_method: str,
+    bypass_review_count: bool,
+    owner: str,
+    prefix: str,
+    repo_type: str,
+) -> None:
+    """
+    Main CLI entry point to merge pull requests
+
+    \f
+    Executes the complete workflow:
+    1. Load configuration (YAML file or defaults)
+    2. Validate and merge CLI arguments with config
+    3. Authenticate with GitHub API
+    4. Discover repositories
+    5. Fetch and filter open pull requests
+    6. Evaluate merge readiness (CI + reviews)
+    7. Execute merge operations (or dry-run)
+    """
+    config_file = find_config_file()
+    if config_file:
+        config, _ = load_config(config_file)
+    else:
+        config = Config()
+
+    cli_args = {
+        "base_branch": base_branch,
+        "dry_run": dry_run,
+        "exclude_labels": exclude_labels,
+        "include_labels": include_labels,
+        "merge_method": merge_method,
+        "bypass_review_count": bypass_review_count,
+        "owner": owner,
+        "prefix": prefix,
+        "repo_type": repo_type,
+    }
+    merged_config = merge_config_with_cli(config, cli_args)
+
+    # Display startup message first
+    print("🚀 Starting Merge-Pulls (Merge Pull Requests) on GitHub...\n")
+
+    # Load config if available (for display purposes)
+    if config_file:
+        print(f"📚 Loading configuration from: {config_file}")
+
+    # Display merged configuration
+    print("📚 Configuration (merged YAML and CLI):")
+    print(f"   base-branch: {merged_config['base_branch']}")
+    print(f"   bypass-review-count: {merged_config['bypass_review_count']}")
+    print(f"   dry-run: {merged_config['dry_run']}")
+    print(f"   exclude-labels: {merged_config['exclude_labels']}")
+    print(f"   include-labels: {merged_config['include_labels']}")
+    print(f"   merge-method: {merged_config['merge_method']}")
+    print(f"   owner: {merged_config['owner']}")
+    print(f"   prefix: {merged_config['prefix']}")
+    print(f"   repo-type: {merged_config['repo_type']}")
+
+    print()  # Empty line before actual operations
+
+    try:
+        # Create a single GitHub client instance for the rest of the process
+        gh, gh_token = get_auth()
+
+        # 1. Get Token User Data
+        user = gh.get_user()
+        login, orgs = get_token_user_info(gh, user)
+
+        # 2. Process Click Inputs (use merged config values)
+        owner = merged_config["owner"]
+        repo_type = merged_config["repo_type"]
+        merge_method = merged_config["merge_method"]
+        set_exclude_labels = merged_config["exclude_labels"]
+        set_include_labels = merged_config["include_labels"]
+        base_branch = merged_config["base_branch"]
+        prefix = merged_config["prefix"]
+        dry_run = merged_config["dry_run"]
+        bypass_review_count = merged_config["bypass_review_count"]
+
+        check_owner(owner=owner, orgs=orgs, login=login)
+        check_repo_type(repo_type=repo_type)
+        check_merge_method(merge_method=merge_method)
+
+        # 3. Get Repo Data
+        if owner:
+            repos_obj, repos = get_repos_from_owner(gh, user, owner, repo_type)
+        else:
+            repos_obj, repos = get_repos_from_all(gh, user, repo_type)
+
+        # 4. Get PR Data
+        list_open_prs = await get_open_prs(gh, repos_obj, base_branch, set_exclude_labels, set_include_labels, prefix)
+
+        # 5. Check Merge Readiness
+        list_mergeable_prs = await get_merge_readiness(gh, list_open_prs, base_branch, bypass_review_count, merge_method)
+
+        # 6. Merge PRs
+        list_merged_prs = await put_merge_pr(gh, list_mergeable_prs, merge_method, dry_run)
+
+        print_summary(len(list_open_prs), len(list_mergeable_prs), len(list_merged_prs))
+
+    except CustomError as err:
+        print(f"\n❌ Configuration Error: {err}")
+        sys.exit(1)
+    except (KeyError, PermissionError) as err:
+        print(f"\n❌ Authentication Error: {err}")
+        sys.exit(1)
+    except ValueError as err:
+        print(f"\n❌ Error: {err}")
+        sys.exit(1)
+    except Exception as err:
+        print(f"\n❌ Unexpected Error: {err}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    asyncio.run(main())

pkg_30922/config/__init__.py

@@ -0,0 +1,13 @@
+"""
+Configuration management services.
+
+Modules:
+    - config:
+        - Loading YAML configuration files
+        - Validating configuration against schema
+        - Merging CLI options with config file settings
+"""
+
+from .config import Config, load_config, merge_config_with_cli
+
+__all__ = ["Config", "load_config", "merge_config_with_cli"]

pkg_30922/config/config.py

@@ -0,0 +1,213 @@
+"""
+Configuration management and validation.
+
+This module handles:
+- Loading YAML configuration files from multiple locations
+- Strict validation against a dataclass schema
+- Merging CLI options with config file (CLI takes precedence over YAML)
+- Label conversion (string to set) and boolean string parsing
+- Error handling for invalid configurations
+"""
+
+import os
+from dataclasses import dataclass, fields
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+)
+
+import yaml
+
+
+@dataclass
+class Config:
+    """
+    Configuration model.
+
+    All fields are optional with defaults. CLI arguments take precedence over
+    this configuration when provided.
+
+    Attributes:
+        base_branch: Target base branch name (default: "main")
+        bypass_review_count: Bypass required review count (default: False)
+        dry_run: Preview mode without actual merges (default: True)
+        exclude_labels: List of labels to exclude to filter PRs (default: [])
+        include_labels: List of labels to include to filter PRs (default: [])
+        merge_method: Merge strategy: merge, rebase, or squash (default: "merge")
+        owner: Filter to specific user/org (default: "")
+        prefix: Filter PRs by title prefix (default: "")
+        repo_type: Repository type filter: all, private, or public (default: "all")
+    """
+
+    base_branch: str = "main"
+    dry_run: bool = True
+    exclude_labels: Optional[List[str]] = None
+    include_labels: Optional[List[str]] = None
+    merge_method: str = "merge"
+    bypass_review_count: bool = False
+    owner: str = ""
+    prefix: str = ""
+    repo_type: str = "all"
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        if self.exclude_labels is None:
+            self.exclude_labels = []
+
+        if self.include_labels is None:
+            self.include_labels = []
+
+        allowed_merge_methods = {"merge", "rebase", "squash"}
+        if self.merge_method not in allowed_merge_methods:
+            raise ValueError(f"merge_method must be one of {allowed_merge_methods}, got '{self.merge_method}'")
+
+        allowed_repo_types = {"all", "private", "public"}
+        if self.repo_type not in allowed_repo_types:
+            raise ValueError(f"repo_type must be one of {allowed_repo_types}, got '{self.repo_type}'")
+
+        # Reject extra fields
+        field_names = {f.name for f in fields(self)}
+        for key in self.__dict__.keys():
+            if key not in field_names:
+                raise ValueError(f"Invalid config field: '{key}'")
+
+
+def load_config(config_path: Optional[str] = None) -> tuple[Config, Dict[str, Any]]:
+    """
+    Load configuration from YAML file.
+
+    For GitHub Actions users, config is expected at ./config/default.yaml.
+    For CLI users, this file is optional (dataclass defaults are used if not found).
+
+    Args:
+        config_path: Optional explicit path to config file (default: ./config/default.yaml).
+
+    Returns:
+        Tuple of (Config object, raw config dict)
+
+    Raises:
+        ValueError: If config validation fails.
+        yaml.YAMLError: If YAML parsing fails.
+    """
+    config_locations = []
+
+    if config_path:
+        config_locations.append(config_path)
+    else:
+        # Default location for GA users
+        config_locations.append("./config/default.yaml")
+
+    config_dict: Dict[str, Any] = {}
+
+    for location in config_locations:
+        if os.path.exists(location):
+            with open(location, "r") as f:
+                config_dict = yaml.safe_load(f) or {}
+                break
+
+    if not config_dict and not config_path:
+        config_dict = {}
+
+    try:
+        # Convert kebab-case keys to snake_case
+        converted_dict = _convert_kebab_to_snake(config_dict)
+        config = Config(**converted_dict)
+        return config, config_dict
+    except Exception as err:
+        source_file = config_locations[0] if config_path else "default configuration"
+        raise ValueError(f"Configuration error in {source_file}: {err}")
+
+
+def _convert_kebab_to_snake(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert kebab-case keys to snake_case for dataclass initialization."""
+    conversion_map = {
+        "base-branch": "base_branch",
+        "bypass-review-count": "bypass_review_count",
+        "dry-run": "dry_run",
+        "exclude-labels": "exclude_labels",
+        "include-labels": "include_labels",
+        "merge-method": "merge_method",
+        "repo-type": "repo_type",
+    }
+
+    result: Dict[str, Any] = {}
+    for key, value in data.items():
+        if key in conversion_map:
+            result[conversion_map[key]] = value
+        else:
+            # Keep unknown keys as-is (they'll be caught by __post_init__ validation if invalid)
+            result[key] = value
+
+    return result
+
+
+def merge_config_with_cli(config: Config, cli_args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Merge CLI arguments with config, giving precedence to CLI args.
+
+    Args:
+        config: Config object from YAML file (or defaults).
+        cli_args: Dictionary of CLI arguments.
+
+    Returns:
+        Dictionary with merged configuration (CLI overrides YAML).
+    """
+    merged = {
+        "base_branch": cli_args.get("base_branch") or config.base_branch,
+        "bypass_review_count": (
+            cli_args.get("bypass_review_count")
+            if cli_args.get("bypass_review_count") is not None
+            else config.bypass_review_count
+        ),
+        "dry_run": cli_args.get("dry_run") if cli_args.get("dry_run") is not None else config.dry_run,
+        "exclude_labels": cli_args.get("exclude_labels"),
+        "include_labels": cli_args.get("include_labels"),
+        "merge_method": cli_args.get("merge_method") or config.merge_method,
+        "owner": cli_args.get("owner") or config.owner,
+        "prefix": cli_args.get("prefix") or config.prefix,
+        "repo_type": cli_args.get("repo_type") or config.repo_type,
+    }
+
+    # Use config defaults for any None values (labels can be None, others use 'or' above)
+    if merged["exclude_labels"] is None:
+        merged["exclude_labels"] = config.exclude_labels
+    if merged["include_labels"] is None:
+        merged["include_labels"] = config.include_labels
+
+    # Handle exclude_labels: convert to set (CLI string or YAML list)
+    if isinstance(merged["exclude_labels"], str):
+        # Split on both commas and spaces for flexibility
+        # First replace commas with spaces, then split
+        exclude_label_str = merged["exclude_labels"].replace(",", " ")
+        merged["exclude_labels"] = (
+            {item.strip() for item in exclude_label_str.split() if item.strip()} if merged["exclude_labels"] else set()
+        )
+    elif isinstance(merged["exclude_labels"], list):
+        merged["exclude_labels"] = set(merged["exclude_labels"])
+    else:
+        # Handle None or other types (None falls back to config in merge, so this is defensive)
+        merged["exclude_labels"] = set()
+
+    # Handle include_labels: convert to set (CLI string or YAML list)
+    if isinstance(merged["include_labels"], str):
+        # Split on both commas and spaces for flexibility
+        # First replace commas with spaces, then split
+        include_label_str = merged["include_labels"].replace(",", " ")
+        merged["include_labels"] = (
+            {item.strip() for item in include_label_str.split() if item.strip()} if merged["include_labels"] else set()
+        )
+    elif isinstance(merged["include_labels"], list):
+        merged["include_labels"] = set(merged["include_labels"])
+    else:
+        # Handle None or other types (None falls back to config in merge, so this is defensive)
+        merged["include_labels"] = set()
+
+    # Convert boolean strings to actual booleans (for CLI args)
+    for bool_field in ["dry_run", "bypass_review_count"]:
+        if isinstance(merged[bool_field], str):
+            value = merged[bool_field].lower()
+            merged[bool_field] = value in ("true", "1", "yes")
+
+    return merged