feat: expand rule support for PR comments, diff analysis, and fix CODEOWNERS/contributor rules

[dkargatzis]

Overview

Extend Watchflow rule system to support additional GitHub events and use cases, including PR comment-based rules, diff-based code analysis rules, and fixes for existing rules that rely on CODEOWNERS files and contributor history.

Requirements

PR Comment Rules

• Block PR merge when unresolved review comments exist
• Require specific comment resolution before merge
• Enforce comment response time requirements
• Validate comment thread resolution patterns
• Support rules based on comment author (e.g., require maintainer response)

PR Diff-Based Rules

• Analyze actual code changes in PR diffs (patch content)
• Detect security-sensitive patterns in code changes (API keys, secrets, hardcoded credentials)
• Validate code style and patterns in changed lines
• Require tests for modified functions/classes
• Check for specific code patterns or anti-patterns in diffs
• Validate import statements and dependency changes

Additional Event Types

• issue_comment - Rules based on issue/PR comments
• pull_request_review - Rules for review submission patterns
• pull_request_review_comment - Rules for inline code comments
• status - Rules based on CI/CD status checks
• check_run - Rules for workflow run requirements

New Validators

• UnresolvedCommentsCondition - Check for unresolved review comments
• CommentResponseTimeCondition - Validate comment response times
• RequiredCommentResolutionCondition - Ensure specific comments are resolved
• StatusCheckCondition - Validate CI/CD status check results
• WorkflowRunCondition - Check workflow run completion and success
• DiffPatternCondition - Analyze code patterns in PR diffs
• SecurityPatternCondition - Detect security-sensitive changes in diffs
• TestCoverageCondition - Require tests for modified code paths

Fixes for Existing Rules

CODEOWNERS Integration

• Fix CodeOwnersCondition to fetch CODEOWNERS file from GitHub API instead of local filesystem
• Update is_critical_file() to accept GitHub client and fetch CODEOWNERS dynamically
• Support multiple CODEOWNERS file locations (.github/CODEOWNERS, CODEOWNERS, docs/CODEOWNERS)
• Cache CODEOWNERS file content to avoid repeated API calls
• Handle missing CODEOWNERS files gracefully

Past Contributor Rules

• Fix PastContributorApprovalCondition to properly fetch contributor history from GitHub API
• Improve is_new_contributor() to use actual commit/PR history instead of placeholder logic
• Add caching for contributor status to improve performance
• Handle edge cases (first-time contributors, users with no history)
• Ensure proper error handling when GitHub API calls fail

Rule Examples

rules:

• description: Block PR merge if unresolved review comments exist
  event_types: [pull_request]
  parameters:
  block_on_unresolved_comments: true
  require_resolution: true

• description: Detect hardcoded API keys or secrets in code changes
  event_types: [pull_request]
  parameters:
  security_patterns: ["api_key", "secret", "password", "token"]
  block_on_detection: true

• description: Require tests for modified functions
  event_types: [pull_request]
  parameters:
  require_tests_for_modified_code: true
  test_file_patterns: ["/test.py", "/spec.py"]

• description: New contributors require approval from at least one past contributor
  event_types: [pull_request]
  parameters:
  min_past_contributors: 1## Implementation Notes

Diff Analysis

• Parse patch field from event_data["files"] (already available from GitHub API)
• Create diff parsing utilities in src/rules/utils/diff.py
• Support unified diff format from GitHub API
• Extract changed lines, hunks, and file contexts

CODEOWNERS Fixes

• Update src/rules/utils/codeowners.py to accept GitHub client
• Modify is_critical_file() to fetch CODEOWNERS via github_client.get_file_content()
• Add async CODEOWNERS loading with caching
• Update CodeOwnersCondition to pass GitHub client to codeowners utilities

Contributor History Fixes

• Enhance src/rules/utils/contributors.py to use actual GitHub API data
• Fetch commit history and PR history for accurate contributor status
• Add caching layer for contributor analysis
• Improve error handling and fallback logic

Integration Points

• Event processors for issue_comment and pull_request_review events
• GitHub API client methods for fetching comments, status checks, and CODEOWNERS
• Rule engine validation logic for comment-based and diff-based rules
• Documentation updates for new rule types

Acceptance Criteria

• Unresolved comment blocking rules work correctly
• Diff-based security pattern detection works
• CODEOWNERS file is fetched from GitHub API (not local filesystem)
• Past contributor rules use actual GitHub commit/PR history
• New validators follow existing patterns
• All new event types are properly handled
• Documentation includes examples for new rule types
• Tests cover new validators and fixed existing validators
• Performance is acceptable with caching for CODEOWNERS and contributor data