gtg 0.4.0__py3-none-any.whl

goodtogo/core/models.py

@@ -0,0 +1,312 @@
+"""Data models for GoodToMerge PR analysis.
+
+This module defines all the Pydantic models and enums used throughout
+the GoodToMerge library for representing PR analysis results, comments,
+CI status, and thread information.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class PRStatus(str, Enum):
+    """Final PR status - maps to exit codes.
+
+    Exit code mapping:
+        READY: 0 - All clear, ready to merge
+        ACTION_REQUIRED: 1 - Actionable comments exist
+        UNRESOLVED_THREADS: 2 - Unresolved threads exist
+        CI_FAILING: 3 - CI/CD checks failing
+        ERROR: 4 - Error fetching data
+    """
+
+    READY = "READY"
+    ACTION_REQUIRED = "ACTION_REQUIRED"
+    UNRESOLVED_THREADS = "UNRESOLVED"
+    CI_FAILING = "CI_FAILING"
+    ERROR = "ERROR"
+
+
+class CommentClassification(str, Enum):
+    """Comment classification result.
+
+    Used to categorize comments from automated reviewers and humans
+    to determine what action (if any) is required.
+    """
+
+    ACTIONABLE = "ACTIONABLE"
+    """Comment that must be addressed before merge."""
+
+    NON_ACTIONABLE = "NON_ACTIONABLE"
+    """Comment that can be safely ignored (informational, nitpick, etc.)."""
+
+    AMBIGUOUS = "AMBIGUOUS"
+    """Comment that needs agent investigation - cannot determine classification."""
+
+
+class Priority(str, Enum):
+    """Comment priority level.
+
+    Used to sort and prioritize actionable comments. Maps to severity
+    indicators from various automated reviewers.
+    """
+
+    CRITICAL = "CRITICAL"
+    """Must fix immediately - blocking issue."""
+
+    MAJOR = "MAJOR"
+    """Must fix before merge - significant issue."""
+
+    MINOR = "MINOR"
+    """Should fix - notable but not blocking."""
+
+    TRIVIAL = "TRIVIAL"
+    """Nice to fix - minor improvement."""
+
+    UNKNOWN = "UNKNOWN"
+    """Could not determine priority."""
+
+
+class ReviewerType(str, Enum):
+    """Automated reviewer identification.
+
+    Used to select the appropriate parser for processing comments
+    from different automated code review tools.
+    """
+
+    CODERABBIT = "coderabbit"
+    """CodeRabbit AI code reviewer."""
+
+    GREPTILE = "greptile"
+    """Greptile code reviewer."""
+
+    CLAUDE = "claude"
+    """Claude Code reviewer."""
+
+    CURSOR = "cursor"
+    """Cursor/Bugbot code reviewer."""
+
+    HUMAN = "human"
+    """Human reviewer (not automated)."""
+
+    UNKNOWN = "unknown"
+    """Unknown reviewer type."""
+
+
+class Comment(BaseModel):
+    """Individual comment with classification.
+
+    Represents a single comment from a PR review, including its
+    classification result and metadata for addressing it.
+    """
+
+    id: str
+    """Unique identifier for the comment."""
+
+    author: str
+    """Username of the comment author."""
+
+    reviewer_type: ReviewerType
+    """Type of reviewer that posted this comment."""
+
+    body: str
+    """Full text content of the comment."""
+
+    classification: CommentClassification
+    """Classification result (ACTIONABLE, NON_ACTIONABLE, AMBIGUOUS)."""
+
+    priority: Priority
+    """Priority level for actionable comments."""
+
+    requires_investigation: bool
+    """True if AMBIGUOUS and needs agent investigation."""
+
+    thread_id: Optional[str]
+    """ID of the review thread this comment belongs to, if any."""
+
+    is_resolved: bool
+    """Whether the thread containing this comment is resolved."""
+
+    is_outdated: bool
+    """Whether this comment is outdated (code has changed)."""
+
+    file_path: Optional[str]
+    """Path to the file this comment references, if any."""
+
+    line_number: Optional[int]
+    """Line number in the file this comment references, if any."""
+
+    created_at: str
+    """ISO 8601 timestamp when the comment was created."""
+
+    addressed_in_commit: Optional[str]
+    """SHA of commit that addressed this comment, if known."""
+
+    url: Optional[str] = None
+    """URL to view this comment on GitHub, for agent workflows."""
+
+
+class CICheck(BaseModel):
+    """Individual CI check status.
+
+    Represents a single CI/CD check run (e.g., build, test, lint).
+    """
+
+    name: str
+    """Name of the CI check."""
+
+    status: str
+    """Current status: 'success', 'failure', or 'pending'."""
+
+    conclusion: Optional[str]
+    """Final conclusion of the check, if completed."""
+
+    url: Optional[str]
+    """URL to the check details/logs."""
+
+
+class CIStatus(BaseModel):
+    """Aggregate CI status.
+
+    Provides summary statistics and individual check details
+    for all CI/CD checks on a PR.
+    """
+
+    state: str
+    """Overall state: 'success', 'failure', or 'pending'."""
+
+    total_checks: int
+    """Total number of CI checks."""
+
+    passed: int
+    """Number of checks that passed."""
+
+    failed: int
+    """Number of checks that failed."""
+
+    pending: int
+    """Number of checks still running or pending."""
+
+    checks: list[CICheck]
+    """List of individual CI check results."""
+
+
+class UnresolvedThread(BaseModel):
+    """Detailed information about an unresolved review thread.
+
+    Contains all data an agent needs to resolve a thread without
+    additional API calls, including the GraphQL node ID for the
+    resolution mutation.
+    """
+
+    id: str
+    """GraphQL node ID for resolution mutation."""
+
+    url: Optional[str]
+    """Link to thread in GitHub UI (if available)."""
+
+    path: str
+    """File path the thread is attached to."""
+
+    line: Optional[int]
+    """Line number in the diff."""
+
+    author: str
+    """Username of the first comment author."""
+
+    body_preview: str
+    """First 200 characters of the first comment body."""
+
+
+class ThreadSummary(BaseModel):
+    """Thread resolution summary.
+
+    Provides counts of review thread states for determining
+    if unresolved discussions remain.
+    """
+
+    total: int
+    """Total number of review threads."""
+
+    resolved: int
+    """Number of resolved threads."""
+
+    unresolved: int
+    """Number of unresolved threads."""
+
+    outdated: int
+    """Number of outdated threads (code changed since comment)."""
+
+    unresolved_threads: list[UnresolvedThread]
+    """Detailed information about each unresolved thread for agent workflows."""
+
+
+class CacheStats(BaseModel):
+    """Cache performance metrics.
+
+    Used to report cache effectiveness for performance tuning.
+    """
+
+    hits: int
+    """Number of cache hits."""
+
+    misses: int
+    """Number of cache misses."""
+
+    hit_rate: float
+    """Cache hit rate as a decimal (0.0 to 1.0)."""
+
+
+class PRAnalysisResult(BaseModel):
+    """Complete PR analysis result - main output.
+
+    This is the primary output model returned by PRAnalyzer.analyze().
+    It contains all information needed for an AI agent to determine
+    the next action for a PR.
+    """
+
+    status: PRStatus
+    """Final PR status determining readiness to merge."""
+
+    pr_number: int
+    """PR number being analyzed."""
+
+    repo_owner: str
+    """Repository owner (organization or user)."""
+
+    repo_name: str
+    """Repository name."""
+
+    latest_commit_sha: str
+    """SHA of the latest commit on the PR branch."""
+
+    latest_commit_timestamp: str
+    """ISO 8601 timestamp of the latest commit."""
+
+    ci_status: CIStatus
+    """Aggregate CI/CD check status."""
+
+    threads: ThreadSummary
+    """Summary of review thread resolution status."""
+
+    comments: list[Comment]
+    """All comments on the PR with classifications."""
+
+    actionable_comments: list[Comment]
+    """Filtered list of comments requiring action."""
+
+    ambiguous_comments: list[Comment]
+    """Filtered list of comments requiring investigation."""
+
+    action_items: list[str]
+    """Human-readable list of actions needed."""
+
+    needs_action: bool
+    """True if any action is required before merge."""
+
+    cache_stats: Optional[CacheStats]
+    """Cache performance metrics, if caching is enabled."""

goodtogo/core/validation.py

@@ -0,0 +1,144 @@
+"""Input validation utilities for GoodToMerge.
+
+This module provides validation functions for all external inputs to ensure
+security and correctness. All GitHub identifiers, PR numbers, and cache keys
+are validated before use.
+
+Security: These functions implement defense-in-depth validation. Even if
+callers have pre-validated inputs, these functions perform additional checks
+to prevent injection attacks and ensure data integrity.
+"""
+
+from __future__ import annotations
+
+import re
+
+# GitHub identifier pattern: alphanumeric, dots, hyphens, underscores
+# Must start and end with alphanumeric
+# Maximum length is 39 characters (GitHub's limit)
+GITHUB_ID_PATTERN = re.compile(r"^[a-zA-Z0-9]([a-zA-Z0-9._-]{0,37}[a-zA-Z0-9])?$")
+
+
+def validate_github_identifier(value: str, field_name: str) -> str:
+    """Validate GitHub owner/repo name format.
+
+    GitHub identifiers (usernames, organization names, repository names) must:
+    - Be non-empty
+    - Be at most 39 characters long
+    - Contain only alphanumeric characters, dots, hyphens, and underscores
+    - Start and end with an alphanumeric character
+
+    Args:
+        value: The identifier value to validate.
+        field_name: The name of the field being validated (for error messages).
+
+    Returns:
+        The validated identifier (unchanged if valid).
+
+    Raises:
+        ValueError: If validation fails with a descriptive error message.
+
+    Examples:
+        >>> validate_github_identifier("my-org", "owner")
+        'my-org'
+        >>> validate_github_identifier("my_repo.name", "repo")
+        'my_repo.name'
+        >>> validate_github_identifier("", "owner")  # doctest: +IGNORE_EXCEPTION_DETAIL
+        Traceback (most recent call last):
+            ...
+        ValueError: owner cannot be empty
+    """
+    if not value:
+        raise ValueError(f"{field_name} cannot be empty")
+
+    if len(value) > 39:  # GitHub max length
+        raise ValueError(f"{field_name} exceeds maximum length (39 chars)")
+
+    if not GITHUB_ID_PATTERN.match(value):
+        raise ValueError(
+            f"{field_name} contains invalid characters. "
+            "Must be alphanumeric with ._- allowed, "
+            "starting and ending with alphanumeric."
+        )
+
+    return value
+
+
+def validate_pr_number(value: int) -> int:
+    """Validate PR number is a positive integer within bounds.
+
+    PR numbers must be:
+    - Greater than zero (positive)
+    - At most 2147483647 (max int32 value)
+
+    Args:
+        value: The PR number to validate.
+
+    Returns:
+        The validated PR number (unchanged if valid).
+
+    Raises:
+        ValueError: If the PR number is not positive or exceeds maximum value.
+
+    Examples:
+        >>> validate_pr_number(123)
+        123
+        >>> validate_pr_number(0)  # doctest: +IGNORE_EXCEPTION_DETAIL
+        Traceback (most recent call last):
+            ...
+        ValueError: PR number must be positive
+    """
+    if value <= 0:
+        raise ValueError("PR number must be positive")
+    if value > 2147483647:  # Max int32
+        raise ValueError("PR number exceeds maximum value")
+    return value
+
+
+def build_cache_key(*parts: str) -> str:
+    """Build a cache key from validated parts.
+
+    Constructs a colon-delimited cache key from the provided parts.
+    This function performs defense-in-depth validation to ensure that
+    special characters that could cause cache key collisions or glob
+    pattern issues are rejected.
+
+    Rejected characters:
+    - Colon (:) - Used as the key delimiter
+    - Asterisk (*) - Glob wildcard that could cause unintended pattern matches
+    - Question mark (?) - Glob single-character wildcard
+
+    All parts must be pre-validated via validate_github_identifier()
+    or validate_pr_number() before calling this function, but this
+    function still performs validation as a defense-in-depth measure.
+
+    Args:
+        *parts: Variable number of string parts to join into a cache key.
+                Each part will be converted to string if not already.
+
+    Returns:
+        A colon-delimited cache key string.
+
+    Raises:
+        ValueError: If any part contains invalid characters (colon, asterisk,
+                   question mark) or is empty.
+
+    Examples:
+        >>> build_cache_key("pr", "myorg", "myrepo", "123", "meta")
+        'pr:myorg:myrepo:123:meta'
+        >>> build_cache_key("pr", "org", "repo", 456, "ci")
+        'pr:org:repo:456:ci'
+        >>> build_cache_key("pr", "my:org", "repo", "123")  # doctest: +IGNORE_EXCEPTION_DETAIL
+        Traceback (most recent call last):
+            ...
+        ValueError: Invalid character in cache key part: my:org
+    """
+    # Double-check no special characters that could cause issues
+    for part in parts:
+        str_part = str(part)
+        if not str_part:
+            raise ValueError("Cache key parts cannot be empty")
+        if ":" in str_part or "*" in str_part or "?" in str_part:
+            raise ValueError(f"Invalid character in cache key part: {part}")
+
+    return ":".join(str(p) for p in parts)

goodtogo/parsers/claude.py

@@ -0,0 +1,188 @@
+"""Claude Code parser for GoodToMerge.
+
+This module implements the ReviewerParser interface for parsing comments
+from Claude Code (Anthropic's AI coding assistant). It classifies comments
+based on pattern matching to determine actionability and priority.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from goodtogo.core.interfaces import ReviewerParser
+from goodtogo.core.models import CommentClassification, Priority, ReviewerType
+
+if TYPE_CHECKING:
+    pass
+
+
+class ClaudeCodeParser(ReviewerParser):
+    """Parser for Claude Code automated reviewer comments.
+
+    Identifies and classifies comments from Claude Code based on author
+    patterns and body content. Uses keyword-based heuristics to determine
+    comment classification and priority.
+
+    Author patterns:
+        - claude-code[bot]
+        - anthropic-claude[bot]
+
+    Body signature fallback:
+        - Contains Claude Code signature patterns
+
+    Classification rules:
+        - ACTIONABLE: Contains "must", "should fix", "error", "bug"
+        - NON_ACTIONABLE: LGTM / approval keywords
+        - AMBIGUOUS: Contains "consider", "suggestion", "might" or unclassified
+    """
+
+    # Author patterns that identify Claude Code comments
+    _AUTHOR_PATTERNS: tuple[str, ...] = (
+        "claude[bot]",
+        "claude-code[bot]",
+        "anthropic-claude[bot]",
+    )
+
+    # Body patterns that identify Claude Code comments (fallback)
+    _BODY_SIGNATURE_PATTERNS: tuple[re.Pattern[str], ...] = (
+        re.compile(r"Generated with Claude Code", re.IGNORECASE),
+        re.compile(r"Claude Code", re.IGNORECASE),
+    )
+
+    # Patterns indicating actionable comments (case-insensitive)
+    _ACTIONABLE_PATTERNS: tuple[re.Pattern[str], ...] = (
+        re.compile(r"\bmust\b", re.IGNORECASE),
+        re.compile(r"\bshould\s+fix\b", re.IGNORECASE),
+        re.compile(r"\berror\b", re.IGNORECASE),
+        re.compile(r"\bbug\b", re.IGNORECASE),
+    )
+
+    # Patterns indicating non-actionable approval comments (case-insensitive)
+    _APPROVAL_PATTERNS: tuple[re.Pattern[str], ...] = (
+        re.compile(r"\bLGTM\b", re.IGNORECASE),
+        re.compile(r"\blooks\s+good\b", re.IGNORECASE),
+        re.compile(r"\bapproved?\b", re.IGNORECASE),
+        re.compile(r"\bship\s+it\b", re.IGNORECASE),
+    )
+
+    # Patterns indicating task completion summaries (non-actionable)
+    # These are automated review summaries, not actionable comments
+    _SUMMARY_PATTERNS: tuple[re.Pattern[str], ...] = (
+        # "**Claude finished @username's task**" header (username can have hyphens)
+        re.compile(r"\*\*Claude finished @[\w-]+'s task\*\*", re.IGNORECASE),
+        # "Claude finished reviewing" pattern
+        re.compile(r"Claude finished reviewing", re.IGNORECASE),
+        # Review summary headers
+        re.compile(r"^###?\s*(?:PR\s+)?Review(?:\s+Summary)?:", re.MULTILINE | re.IGNORECASE),
+        # Recommendation line at end of reviews
+        re.compile(r"^##?\s*Recommendation\s*$", re.MULTILINE | re.IGNORECASE),
+        # "Overall Assessment" sections
+        re.compile(r"^##?\s*Overall Assessment\s*$", re.MULTILINE | re.IGNORECASE),
+    )
+
+    # Patterns indicating ambiguous/suggestion comments (case-insensitive)
+    _SUGGESTION_PATTERNS: tuple[re.Pattern[str], ...] = (
+        re.compile(r"\bconsider\b", re.IGNORECASE),
+        re.compile(r"\bsuggestion\b", re.IGNORECASE),
+        re.compile(r"\bmight\b", re.IGNORECASE),
+    )
+
+    @property
+    def reviewer_type(self) -> ReviewerType:
+        """Return the reviewer type this parser handles.
+
+        Returns:
+            ReviewerType.CLAUDE for Claude Code comments.
+        """
+        return ReviewerType.CLAUDE
+
+    def can_parse(self, author: str, body: str) -> bool:
+        """Check if this parser can handle the comment.
+
+        Identifies Claude Code comments by:
+        1. Matching author name against known bot patterns
+        2. Checking body for Claude Code signature patterns (fallback)
+
+        Args:
+            author: Comment author's username/login.
+            body: Comment body text.
+
+        Returns:
+            True if the comment appears to be from Claude Code.
+        """
+        # Check author patterns first (most reliable)
+        author_lower = author.lower()
+        for author_pattern in self._AUTHOR_PATTERNS:
+            if author_pattern.lower() == author_lower:
+                return True
+
+        # Fallback: check body for Claude signature
+        for body_pattern in self._BODY_SIGNATURE_PATTERNS:
+            if body_pattern.search(body):
+                return True
+
+        return False
+
+    def parse(self, comment: dict) -> tuple[CommentClassification, Priority, bool]:
+        """Parse comment and return classification.
+
+        Classifies Claude Code comments based on keyword patterns:
+        - Actionable: Contains "must", "should fix", "error", "bug"
+        - Non-actionable: LGTM / approval keywords
+        - Ambiguous: Contains "consider", "suggestion", "might" or unclassified
+
+        Args:
+            comment: Dictionary containing comment data with 'body' key.
+
+        Returns:
+            Tuple of (classification, priority, requires_investigation):
+            - classification: ACTIONABLE, NON_ACTIONABLE, or AMBIGUOUS
+            - priority: MINOR for actionable, UNKNOWN otherwise
+            - requires_investigation: True for AMBIGUOUS classification
+        """
+        body = comment.get("body", "")
+
+        # Check for task completion summaries first (these are informational)
+        for pattern in self._SUMMARY_PATTERNS:
+            if pattern.search(body):
+                return (
+                    CommentClassification.NON_ACTIONABLE,
+                    Priority.UNKNOWN,
+                    False,
+                )
+
+        # Check for actionable patterns (highest priority for non-summary comments)
+        for pattern in self._ACTIONABLE_PATTERNS:
+            if pattern.search(body):
+                return (
+                    CommentClassification.ACTIONABLE,
+                    Priority.MINOR,
+                    False,
+                )
+
+        # Check for approval/LGTM patterns (non-actionable)
+        for pattern in self._APPROVAL_PATTERNS:
+            if pattern.search(body):
+                return (
+                    CommentClassification.NON_ACTIONABLE,
+                    Priority.UNKNOWN,
+                    False,
+                )
+
+        # Check for suggestion patterns (ambiguous, needs investigation)
+        for pattern in self._SUGGESTION_PATTERNS:
+            if pattern.search(body):
+                return (
+                    CommentClassification.AMBIGUOUS,
+                    Priority.UNKNOWN,
+                    True,
+                )
+
+        # Default: ambiguous, requires investigation
+        # Per design spec: "Never silently skip ambiguous comments"
+        return (
+            CommentClassification.AMBIGUOUS,
+            Priority.UNKNOWN,
+            True,
+        )