gtg 0.4.0__py3-none-any.whl

goodtogo/cli.py

@@ -0,0 +1,311 @@
+"""Thin CLI wrapper around PRAnalyzer.
+
+This module provides a command-line interface for the GoodToMerge library,
+enabling AI agents and humans to check PR readiness from the terminal or
+CI/CD pipelines.
+
+Exit codes (default - AI-friendly mode):
+    0 - Any analyzable state (READY, ACTION_REQUIRED, UNRESOLVED_THREADS, CI_FAILING)
+    4 - Error fetching data (PRStatus.ERROR)
+
+Exit codes (with -q or --semantic-codes):
+    0 - Ready to merge (PRStatus.READY)
+    1 - Actionable comments need addressing (PRStatus.ACTION_REQUIRED)
+    2 - Unresolved threads exist (PRStatus.UNRESOLVED_THREADS)
+    3 - CI/CD checks failing (PRStatus.CI_FAILING)
+    4 - Error fetching data (PRStatus.ERROR)
+
+Example:
+    $ gtg 123                          # auto-detect repo from git origin
+    $ gtg 123 --repo myorg/myrepo      # explicit repo
+    $ gtg 123 --format text --verbose  # human-readable output
+    $ gtg 123 -q                       # quiet mode with semantic exit codes
+    $ gtg 123 --semantic-codes         # semantic exit codes with output
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from typing import Optional
+
+import click
+
+from goodtogo import __version__
+from goodtogo.container import Container
+from goodtogo.core.analyzer import PRAnalyzer
+from goodtogo.core.errors import redact_error
+from goodtogo.core.models import PRAnalysisResult, PRStatus
+
+
+def parse_github_remote_url(url: str) -> Optional[tuple[str, str]]:
+    """Parse a GitHub remote URL to extract owner and repo.
+
+    Supports both HTTPS and SSH formats:
+    - https://github.com/owner/repo.git
+    - https://github.com/owner/repo
+    - git@github.com:owner/repo.git
+    - git@github.com:owner/repo
+
+    Args:
+        url: The git remote URL to parse.
+
+    Returns:
+        Tuple of (owner, repo) if the URL is a valid GitHub URL,
+        None otherwise.
+    """
+    if not url:
+        return None
+
+    # HTTPS format: https://github.com/owner/repo.git or https://github.com/owner/repo
+    https_pattern = r"^https://github\.com/([^/]+)/([^/]+?)(?:\.git)?/?$"
+    match = re.match(https_pattern, url)
+    if match:
+        return (match.group(1), match.group(2))
+
+    # SSH format: git@github.com:owner/repo.git or git@github.com:owner/repo
+    ssh_pattern = r"^git@github\.com:([^/]+)/([^/]+?)(?:\.git)?/?$"
+    match = re.match(ssh_pattern, url)
+    if match:
+        return (match.group(1), match.group(2))
+
+    return None
+
+
+def get_repo_from_git_origin() -> Optional[tuple[str, str]]:
+    """Get repository owner and name from git remote origin.
+
+    Runs `git remote get-url origin` to get the origin URL,
+    then parses it to extract owner and repo name.
+
+    Returns:
+        Tuple of (owner, repo) if origin is a valid GitHub URL,
+        None if not in a git repo, no origin remote, origin isn't GitHub,
+        git is not installed, or the command times out.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=5,
+        )
+        origin_url = result.stdout.strip()
+        return parse_github_remote_url(origin_url)
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        # No origin remote, not a git repo, git not installed, or timeout
+        return None
+
+
+# Semantic exit codes for shell scripting (-q or --semantic-codes)
+SEMANTIC_EXIT_CODES: dict[PRStatus, int] = {
+    PRStatus.READY: 0,
+    PRStatus.ACTION_REQUIRED: 1,
+    PRStatus.UNRESOLVED_THREADS: 2,
+    PRStatus.CI_FAILING: 3,
+    PRStatus.ERROR: 4,
+}
+
+# AI-friendly exit codes (default) - only ERROR is non-zero
+AI_FRIENDLY_EXIT_CODES: dict[PRStatus, int] = {
+    PRStatus.READY: 0,
+    PRStatus.ACTION_REQUIRED: 0,
+    PRStatus.UNRESOLVED_THREADS: 0,
+    PRStatus.CI_FAILING: 0,
+    PRStatus.ERROR: 4,
+}
+
+
+@click.command()
+@click.argument("pr_number", type=int)
+@click.option(
+    "--repo",
+    "-r",
+    required=False,
+    default=None,
+    help="Repository in owner/repo format (auto-detected from git origin if not provided)",
+)
+@click.option(
+    "--cache",
+    type=click.Choice(["sqlite", "redis", "none"]),
+    default="sqlite",
+    help="Cache backend (default: sqlite)",
+)
+@click.option(
+    "--cache-path",
+    default=".goodtogo/cache.db",
+    help="SQLite cache path",
+)
+@click.option(
+    "--redis-url",
+    envvar="REDIS_URL",
+    help="Redis URL (required if --cache=redis)",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "text"]),
+    default="json",
+    help="Output format (default: json)",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Verbose output",
+)
+@click.option(
+    "--exclude-checks",
+    "-x",
+    multiple=True,
+    help="CI check names to exclude (can be repeated)",
+)
+@click.option(
+    "-q",
+    "--quiet",
+    is_flag=True,
+    help="Quiet mode: no output, use semantic exit codes (like grep -q)",
+)
+@click.option(
+    "--semantic-codes",
+    is_flag=True,
+    help="Use semantic exit codes (0=ready, 1=action, 2=threads, 3=ci, 4=error)",
+)
+@click.version_option(version=__version__)
+def main(
+    pr_number: int,
+    repo: Optional[str],
+    cache: str,
+    cache_path: str,
+    redis_url: Optional[str],
+    output_format: str,
+    verbose: bool,
+    exclude_checks: tuple[str, ...],
+    quiet: bool,
+    semantic_codes: bool,
+) -> None:
+    """Check if a PR is ready to merge.
+
+    PR_NUMBER is the pull request number to check.
+
+    Exit codes (default - AI-friendly):
+      0 - Any analyzable state (ready, action required, threads, CI)
+      4 - Error fetching data
+
+    Exit codes (with -q or --semantic-codes):
+      0 - Ready to merge
+      1 - Actionable comments need addressing
+      2 - Unresolved threads exist
+      3 - CI/CD checks failing
+      4 - Error fetching data
+    """
+    # Get GitHub token from environment
+    github_token = os.environ.get("GITHUB_TOKEN")
+    if not github_token:
+        click.echo("Error: GITHUB_TOKEN environment variable required", err=True)
+        sys.exit(4)
+
+    # Determine owner/repo - either from --repo option or auto-detect from git origin
+    if repo is not None:
+        # Parse owner/repo from --repo option
+        try:
+            owner, repo_name = repo.strip().split("/")
+            if not owner or not repo_name:
+                raise ValueError("Empty owner or repo name")
+        except ValueError:
+            click.echo("Error: --repo must be in owner/repo format", err=True)
+            sys.exit(4)
+    else:
+        # Auto-detect from git origin
+        detected = get_repo_from_git_origin()
+        if detected is None:
+            click.echo(
+                "Error: Could not detect repository from git origin. "
+                "Use --repo owner/repo or run from a GitHub repository.",
+                err=True,
+            )
+            sys.exit(4)
+        owner, repo_name = detected
+
+    # Create container and analyzer, then analyze PR
+    try:
+        container = Container.create_default(
+            github_token=github_token,
+            cache_type=cache,
+            cache_path=cache_path,
+            redis_url=redis_url,
+        )
+        analyzer = PRAnalyzer(container)
+        result = analyzer.analyze(owner, repo_name, pr_number, exclude_checks=set(exclude_checks))
+    except Exception as e:
+        # Redact sensitive data from error messages
+        redacted = redact_error(e)
+        if verbose:
+            click.echo(f"Error: {redacted}", err=True)
+        else:
+            click.echo(
+                "Error: Failed to analyze PR. Use --verbose for details.",
+                err=True,
+            )
+        sys.exit(4)
+
+    # Determine which exit code mapping to use
+    use_semantic = quiet or semantic_codes
+    exit_codes = SEMANTIC_EXIT_CODES if use_semantic else AI_FRIENDLY_EXIT_CODES
+
+    # Output result in requested format (skip if quiet mode)
+    if not quiet:
+        if output_format == "json":
+            click.echo(result.model_dump_json(indent=2))
+        else:
+            _print_text_output(result, verbose)
+
+    sys.exit(exit_codes[result.status])
+
+
+def _print_text_output(result: PRAnalysisResult, verbose: bool) -> None:
+    """Print human-readable output.
+
+    Displays a formatted summary of the PR analysis result suitable
+    for human consumption in the terminal.
+
+    Args:
+        result: The PR analysis result to display.
+        verbose: If True, show additional details like ambiguous comments.
+    """
+    status_icons = {
+        PRStatus.READY: "OK",
+        PRStatus.ACTION_REQUIRED: "!!",
+        PRStatus.UNRESOLVED_THREADS: "??",
+        PRStatus.CI_FAILING: "XX",
+        PRStatus.ERROR: "##",
+    }
+
+    icon = status_icons.get(result.status, "??")
+    click.echo(f"{icon} PR #{result.pr_number}: {result.status.value}")
+    click.echo(
+        f"   CI: {result.ci_status.state} "
+        f"({result.ci_status.passed}/{result.ci_status.total_checks} passed)"
+    )
+    click.echo(f"   Threads: {result.threads.resolved}/{result.threads.total} resolved")
+
+    if result.action_items:
+        click.echo("\nAction required:")
+        for item in result.action_items:
+            click.echo(f"   - {item}")
+
+    if verbose and result.ambiguous_comments:
+        click.echo("\nAmbiguous (needs investigation):")
+        for comment in result.ambiguous_comments:
+            # Truncate body to 80 chars for readability
+            body_preview = comment.body[:80]
+            if len(comment.body) > 80:
+                body_preview += "..."
+            click.echo(f"   - [{comment.author}] {body_preview}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

goodtogo/container.py

@@ -0,0 +1,313 @@
+"""Dependency injection container for GoodToMerge.
+
+This module provides the Container class that manages all dependencies
+for the GoodToMerge library, following the Ports & Adapters (Hexagonal)
+architecture pattern.
+
+The Container provides factory methods for creating production and test
+configurations, ensuring all dependencies are properly initialized with
+appropriate adapters.
+
+Example:
+    # Production usage
+    container = Container.create_default(
+        github_token="ghp_...",
+        cache_type="sqlite",
+        cache_path=".goodtogo/cache.db",
+    )
+
+    # Test usage
+    container = Container.create_for_testing()
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from goodtogo.adapters.cache_memory import InMemoryCacheAdapter
+from goodtogo.adapters.cache_sqlite import SqliteCacheAdapter
+from goodtogo.adapters.github import GitHubAdapter
+from goodtogo.adapters.time_provider import MockTimeProvider, SystemTimeProvider
+from goodtogo.core.interfaces import CachePort, GitHubPort, ReviewerParser, TimeProvider
+from goodtogo.core.models import ReviewerType
+from goodtogo.parsers.claude import ClaudeCodeParser
+from goodtogo.parsers.coderabbit import CodeRabbitParser
+from goodtogo.parsers.cursor import CursorBugbotParser
+from goodtogo.parsers.generic import GenericParser
+from goodtogo.parsers.greptile import GreptileParser
+
+
+class MockGitHubAdapter(GitHubPort):
+    """Mock GitHub adapter for testing.
+
+    This adapter raises NotImplementedError for all methods by default.
+    Test code should replace individual methods with mock implementations
+    as needed.
+
+    Example:
+        container = Container.create_for_testing()
+        container.github.get_pr = MagicMock(return_value={"number": 123})
+    """
+
+    def __repr__(self) -> str:
+        """Return string representation for debugging."""
+        return "MockGitHubAdapter()"
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return self.__repr__()
+
+    def get_pr(self, owner: str, repo: str, pr_number: int) -> dict[str, Any]:
+        """Fetch PR metadata.
+
+        Raises:
+            NotImplementedError: Always raised - override in tests.
+        """
+        raise NotImplementedError(
+            "MockGitHubAdapter.get_pr() not implemented. " "Replace with a mock in your test."
+        )
+
+    def get_pr_comments(self, owner: str, repo: str, pr_number: int) -> list[dict[str, Any]]:
+        """Fetch all PR comments.
+
+        Raises:
+            NotImplementedError: Always raised - override in tests.
+        """
+        raise NotImplementedError(
+            "MockGitHubAdapter.get_pr_comments() not implemented. "
+            "Replace with a mock in your test."
+        )
+
+    def get_pr_reviews(self, owner: str, repo: str, pr_number: int) -> list[dict[str, Any]]:
+        """Fetch all PR reviews.
+
+        Raises:
+            NotImplementedError: Always raised - override in tests.
+        """
+        raise NotImplementedError(
+            "MockGitHubAdapter.get_pr_reviews() not implemented. "
+            "Replace with a mock in your test."
+        )
+
+    def get_pr_threads(self, owner: str, repo: str, pr_number: int) -> list[dict[str, Any]]:
+        """Fetch all review threads.
+
+        Raises:
+            NotImplementedError: Always raised - override in tests.
+        """
+        raise NotImplementedError(
+            "MockGitHubAdapter.get_pr_threads() not implemented. "
+            "Replace with a mock in your test."
+        )
+
+    def get_ci_status(self, owner: str, repo: str, ref: str) -> dict[str, Any]:
+        """Fetch CI/CD check status.
+
+        Raises:
+            NotImplementedError: Always raised - override in tests.
+        """
+        raise NotImplementedError(
+            "MockGitHubAdapter.get_ci_status() not implemented. "
+            "Replace with a mock in your test."
+        )
+
+
+@dataclass
+class Container:
+    """DI container - all dependencies injected, no global state.
+
+    The Container holds all adapters and parsers needed by the PRAnalyzer.
+    It provides factory methods for creating properly configured instances
+    for production and testing scenarios.
+
+    Attributes:
+        github: GitHub API adapter implementing GitHubPort interface.
+        cache: Cache adapter implementing CachePort interface.
+        parsers: Dictionary mapping ReviewerType to parser implementations.
+        time_provider: TimeProvider for time operations (enables deterministic testing).
+
+    Example:
+        # Create production container
+        container = Container.create_default(github_token="ghp_...")
+        analyzer = PRAnalyzer(container)
+        result = analyzer.analyze("owner", "repo", 123)
+
+        # Create test container with mocks
+        container = Container.create_for_testing()
+        container.github.get_pr = MagicMock(return_value={...})
+    """
+
+    github: GitHubPort
+    cache: CachePort
+    parsers: dict[ReviewerType, ReviewerParser]
+    time_provider: TimeProvider
+
+    @classmethod
+    def create_default(
+        cls,
+        github_token: str,
+        cache_type: str = "sqlite",
+        cache_path: str = ".goodtogo/cache.db",
+        redis_url: Optional[str] = None,
+    ) -> Container:
+        """Factory for standard production configuration.
+
+        Creates a Container with production-ready adapters:
+        - GitHubAdapter for real GitHub API access
+        - SQLite or Redis cache based on cache_type
+        - All default reviewer parsers
+
+        Args:
+            github_token: GitHub personal access token or OAuth token.
+                         Must have 'repo' scope for private repositories.
+            cache_type: Cache backend to use. One of:
+                       - "sqlite": Local SQLite database (default)
+                       - "redis": Redis server (requires redis_url)
+                       - "none": No caching (NoCacheAdapter)
+            cache_path: Path to SQLite database file. Only used when
+                       cache_type is "sqlite". Default: ".goodtogo/cache.db"
+            redis_url: Redis connection URL. Required when cache_type is "redis".
+                      Example: "redis://localhost:6379" or "rediss://..." for TLS.
+
+        Returns:
+            Configured Container instance ready for production use.
+
+        Raises:
+            ValueError: If cache_type is "redis" but redis_url is not provided,
+                       or if cache_type is unknown.
+        """
+        time_provider = SystemTimeProvider()
+        cache = _create_cache(cache_type, cache_path, redis_url, time_provider)
+        return cls(
+            github=GitHubAdapter(token=github_token, time_provider=time_provider),
+            cache=cache,
+            parsers=_create_default_parsers(),
+            time_provider=time_provider,
+        )
+
+    @classmethod
+    def create_for_testing(
+        cls,
+        github: Optional[GitHubPort] = None,
+        cache: Optional[CachePort] = None,
+        time_provider: Optional[TimeProvider] = None,
+    ) -> Container:
+        """Factory for tests - all mocks by default.
+
+        Creates a Container suitable for testing with mock adapters:
+        - MockGitHubAdapter that raises NotImplementedError (override as needed)
+        - InMemoryCacheAdapter for fast, ephemeral caching
+        - MockTimeProvider for deterministic time control
+        - All default reviewer parsers
+
+        Args:
+            github: Optional GitHubPort implementation to use instead of mock.
+                   If None, uses MockGitHubAdapter.
+            cache: Optional CachePort implementation to use instead of mock.
+                  If None, uses InMemoryCacheAdapter.
+            time_provider: Optional TimeProvider implementation. If None, uses
+                          MockTimeProvider starting at time 0.
+
+        Returns:
+            Container instance configured for testing.
+
+        Example:
+            # Basic test setup
+            container = Container.create_for_testing()
+
+            # With custom mock
+            mock_github = MagicMock(spec=GitHubPort)
+            mock_github.get_pr.return_value = {"number": 123, "title": "Test"}
+            container = Container.create_for_testing(github=mock_github)
+
+            # With controlled time
+            time = MockTimeProvider(start=1000.0)
+            container = Container.create_for_testing(time_provider=time)
+            time.advance(60)  # Advance 60 seconds instantly
+        """
+        resolved_time_provider = time_provider if time_provider is not None else MockTimeProvider()
+        return cls(
+            github=github if github is not None else MockGitHubAdapter(),
+            cache=(
+                cache
+                if cache is not None
+                else InMemoryCacheAdapter(time_provider=resolved_time_provider)
+            ),
+            parsers=_create_default_parsers(),
+            time_provider=resolved_time_provider,
+        )
+
+
+def _create_cache(
+    cache_type: str,
+    path: str,
+    redis_url: Optional[str],
+    time_provider: Optional[TimeProvider] = None,
+) -> CachePort:
+    """Create cache adapter based on type.
+
+    Factory function that creates the appropriate cache adapter
+    based on the specified cache type.
+
+    Args:
+        cache_type: Type of cache to create. One of:
+                   - "sqlite": Local SQLite database
+                   - "redis": Redis server
+                   - "none": No-op cache adapter
+        path: Path to SQLite database file (only used for "sqlite").
+        redis_url: Redis connection URL (only used for "redis").
+        time_provider: Optional TimeProvider for time operations.
+
+    Returns:
+        CachePort implementation matching the requested type.
+
+    Raises:
+        ValueError: If cache_type is "redis" but redis_url is not provided,
+                   or if cache_type is unknown.
+    """
+    if cache_type == "sqlite":
+        return SqliteCacheAdapter(path, time_provider=time_provider)
+    elif cache_type == "redis":
+        if not redis_url:
+            raise ValueError("redis_url required for redis cache")
+        # Import Redis adapter only when needed to avoid requiring redis package
+        from goodtogo.adapters.cache_redis import (  # type: ignore[import-untyped]
+            RedisCacheAdapter,
+        )
+
+        result: CachePort = RedisCacheAdapter(redis_url)
+        return result
+    elif cache_type == "none":
+        # No-op cache - use in-memory with immediate expiration
+        # For a true no-op, we could create a NoCacheAdapter, but
+        # InMemoryCacheAdapter with TTL=0 effectively accomplishes this
+        return InMemoryCacheAdapter(time_provider=time_provider)
+    else:
+        raise ValueError(f"Unknown cache type: {cache_type}")
+
+
+def _create_default_parsers() -> dict[ReviewerType, ReviewerParser]:
+    """Create default parser registry.
+
+    Creates a dictionary mapping each ReviewerType to its corresponding
+    parser implementation. The GenericParser is used as a fallback for
+    both HUMAN and UNKNOWN reviewer types.
+
+    Returns:
+        Dictionary with all default parsers registered:
+        - CODERABBIT: CodeRabbitParser
+        - GREPTILE: GreptileParser
+        - CLAUDE: ClaudeCodeParser
+        - CURSOR: CursorBugbotParser
+        - HUMAN: GenericParser (fallback)
+        - UNKNOWN: GenericParser (fallback)
+    """
+    return {
+        ReviewerType.CODERABBIT: CodeRabbitParser(),
+        ReviewerType.GREPTILE: GreptileParser(),
+        ReviewerType.CLAUDE: ClaudeCodeParser(),
+        ReviewerType.CURSOR: CursorBugbotParser(),
+        ReviewerType.HUMAN: GenericParser(),
+        ReviewerType.UNKNOWN: GenericParser(),
+    }