CodeRabbit Conflict Resolver

An intelligent, automated conflict resolution system for GitHub PR comments
Specifically designed for CodeRabbit AI but extensible to other code review bots

---

📋 Table of Contents

• Problem Statement
• Quick Start
• Features
• Architecture
• Use Cases
• Environment Variables
• Documentation
• Contributing
• Project Status
• License

---

🎯 Problem Statement

When multiple PR review comments suggest overlapping changes to the same file, traditional automation tools either:

• Skip all conflicting changes (losing valuable suggestions)
• Apply changes sequentially without conflict awareness (potentially breaking code)
• Require tedious manual resolution for every conflict

CodeRabbit Conflict Resolver provides intelligent, semantic-aware conflict resolution that:

• ✅ Understands code structure (JSON, YAML, TOML, Python, TypeScript)
• ✅ Uses priority-based resolution (user selections, security fixes, syntax errors)
• ✅ Supports semantic merging (combining non-conflicting changes automatically)
• ✅ Learns from your decisions to improve over time
• ✅ Provides detailed conflict analysis and actionable suggestions

🚀 Quick Start

Installation

pip install pr-conflict-resolver

Basic Usage

# Set your GitHub token (required)
export GITHUB_PERSONAL_ACCESS_TOKEN="your_token_here"

# Analyze conflicts in a PR
pr-resolve analyze --owner VirtualAgentics --repo my-repo --pr 123

# Apply suggestions with conflict resolution
pr-resolve apply --owner VirtualAgentics --repo my-repo --pr 123 --strategy priority

# Apply only conflicting changes
pr-resolve apply --owner VirtualAgentics --repo my-repo --pr 123 --mode conflicts-only

# Simulate without applying changes (dry-run mode)
pr-resolve apply --owner VirtualAgentics --repo my-repo --pr 123 --mode dry-run

# Use parallel processing for large PRs
pr-resolve apply --owner VirtualAgentics --repo my-repo --pr 123 --parallel --max-workers 8

# Load configuration from file
pr-resolve apply --owner VirtualAgentics --repo my-repo --pr 123 --config config.yaml

Python API

from pr_conflict_resolver import ConflictResolver
from pr_conflict_resolver.config import PresetConfig

resolver = ConflictResolver(config=PresetConfig.BALANCED)
results = resolver.resolve_pr_conflicts(
    owner="VirtualAgentics",
    repo="my-repo",
    pr_number=123
)

print(f"Applied: {results.applied_count}")
print(f"Conflicts: {results.conflict_count}")
print(f"Success rate: {results.success_rate}%")

🎨 Features

Intelligent Conflict Analysis

• Semantic Understanding: Analyzes JSON, YAML, TOML structure, not just text
• Conflict Categorization: Exact, major, partial, minor, disjoint-keys, semantic-duplicate
• Impact Assessment: Evaluates scope, risk level, and criticality of changes
• Actionable Suggestions: Provides specific guidance for each conflict

Smart Resolution Strategies

• Priority-Based: User selections > Security fixes > Syntax errors > Regular suggestions
• Semantic Merging: Combines non-conflicting changes in structured files
• Sequential Application: Applies compatible changes in optimal order
• Defer to User: Escalates complex conflicts for manual review

File-Type Handlers

• JSON: Duplicate key detection, key-level merging
• YAML: Comment preservation, structure-aware merging
• TOML: Section merging, format preservation
• Python/TypeScript: AST-aware analysis (planned)

Learning & Optimization

• ML-Assisted Priority: Learns from your resolution decisions
• Metrics Tracking: Monitors success rates, resolution times, strategy effectiveness
• Conflict Caching: Reuses analysis for similar conflicts
• Performance: Parallel processing for large PRs

Configuration & Presets

• Conservative: Skip all conflicts, manual review required
• Balanced: Priority system + semantic merging (default)
• Aggressive: Maximize automation, user selections always win
• Semantic: Focus on structure-aware merging for config files

Application Modes

• all: Apply both conflicting and non-conflicting changes (default)
• conflicts-only: Apply only changes that have conflicts
• non-conflicts-only: Apply only changes without conflicts
• dry-run: Analyze and report without applying any changes

Rollback & Safety Features

• Automatic Rollback: Git-based checkpointing with automatic rollback on failure
• Pre-Application Validation: Validates changes before applying (optional)
• File Integrity Checks: Verifies file safety and containment
• Detailed Logging: Comprehensive logging for debugging and audit trails

Runtime Configuration

Configure via multiple sources with precedence chain: CLI flags > Environment variables > Config file > Defaults

• Configuration Files: Load settings from YAML or TOML files
• Environment Variables: Set options using CR_* prefix variables
• CLI Overrides: Override any setting via command-line flags

See .env.example for available environment variables.

📖 Documentation

User Guides

• Getting Started Guide - Installation, setup, and first steps
• Configuration Reference - Complete configuration options
• Rollback System - Automatic rollback and recovery
• Parallel Processing - Performance tuning guide
• Migration Guide - Upgrading from earlier versions
• Troubleshooting - Common issues and solutions

Reference Documentation

• API Reference - Python API documentation
• Conflict Types Explained - Understanding conflict categories
• Resolution Strategies - Strategy selection guide

Architecture & Development

• Architecture Overview - System design and components
• Contributing Guide - How to contribute

Security

• Security Policy - Vulnerability reporting, security features
• Security Architecture - Design principles, threat model
• Threat Model - STRIDE analysis, risk assessment
• Incident Response - Security incident procedures
• Compliance - GDPR, OWASP, SOC2, OpenSSF
• Security Testing - Testing guide, fuzzing, SAST

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    GitHub PR Comments                       │
│                   (CodeRabbit, Review Bot)                  │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              Comment Parser & Extractor                     │
│   (Suggestions, Diffs, Codemods, Multi-Options)            │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              Conflict Detection Engine                      │
│  • Fingerprinting  • Overlap Analysis  • Semantic Check    │
└────────────────────┬────────────────────────────────────────┘
                     │
         ┌───────────┴──────────┐
         ▼                      ▼
┌──────────────────┐   ┌──────────────────┐
│  File Handlers   │   │  Priority System │
│  • JSON          │   │  • User Selected │
│  • YAML          │   │  • Security Fix  │
│  • TOML          │   │  • Syntax Error  │
│  • Python        │   │  • Regular       │
└─────────┬────────┘   └────────┬─────────┘
          │                     │
          └──────────┬──────────┘
                     ▼
┌─────────────────────────────────────────────────────────────┐
│           Resolution Strategy Selector                      │
│  • Skip  • Override  • Merge  • Sequential  • Defer        │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              Application Engine                             │
│  • Backup  • Apply  • Validate  • Rollback                 │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│        Reporting & Metrics                                  │
│  • Conflict Summary  • Visual Diff  • Success Rate         │
└─────────────────────────────────────────────────────────────┘

🔧 Use Cases

1. CodeRabbit Multi-Option Selections

Problem: User selects "Option 2" but it conflicts with another suggestion Solution: Priority system ensures user selections override lower-priority changes

2. Overlapping Configuration Changes

Problem: Two suggestions modify different keys in package.json Solution: Semantic merging combines both changes automatically

3. Security Fix vs. Formatting

Problem: Security fix conflicts with formatting suggestion Solution: Priority system applies security fix, skips formatting

4. Large PR with 50+ Comments

Problem: Manual conflict resolution is time-consuming Solution: Parallel processing + caching resolves conflicts in seconds

🔧 Environment Variables

Configure the tool using environment variables (see .env.example for all options):

Variable	Description	Default
GITHUB_PERSONAL_ACCESS_TOKEN	GitHub API token (required)	None
CR_MODE	Application mode (all, conflicts-only, non-conflicts-only, dry-run)	all
CR_ENABLE_ROLLBACK	Enable automatic rollback on failure	true
CR_VALIDATE	Enable pre-application validation	true
CR_PARALLEL	Enable parallel processing	false
CR_MAX_WORKERS	Number of parallel workers	4
CR_LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO
CR_LOG_FILE	Log file path (optional)	None

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/VirtualAgentics/coderabbit-conflict-resolver.git
cd coderabbit-conflict-resolver
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

Running Tests

# Run standard tests with coverage
pytest tests/ --cov=src --cov-report=html

# Run property-based fuzzing tests
make test-fuzz              # Dev profile: 50 examples
make test-fuzz-ci           # CI profile: 100 examples
make test-fuzz-extended     # Extended: 1000 examples

# Run all tests (standard + fuzzing)
make test-all

📜 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Inspired by the sophisticated code review capabilities of CodeRabbit AI
• Built with experience from ContextForge Memory project
• Community feedback and contributions

📊 Project Status

Current Version: 0.1.0 (Alpha)

Roadmap:

• ✅ Phase 0: Security Foundation (COMPLETE)
  • ✅ 0.1: Security Architecture Design
  • ✅ 0.2: Input Validation & Sanitization
  • ✅ 0.3: Secure File Handling
  • ✅ 0.4: Secret Detection (14+ patterns)
  • ✅ 0.5: Security Testing Suite (95%+ coverage)
  • ✅ 0.6: Security Configuration
  • ✅ 0.7: CI/CD Security Scanning (7+ tools)
  • ✅ 0.8: Security Documentation
• ✅ Phase 1: Core Features (COMPLETE)
  • ✅ Core conflict detection and analysis
  • ✅ File handlers (JSON, YAML, TOML)
  • ✅ Priority system
  • ✅ Rollback system with git-based checkpointing
• ✅ Phase 2: CLI & Configuration (COMPLETE)
  • ✅ CLI with comprehensive options
  • ✅ Runtime configuration system
  • ✅ Application modes (all, conflicts-only, non-conflicts-only, dry-run)
  • ✅ Parallel processing support
  • ✅ Multiple configuration sources (file, env, CLI)
• 🔄 Phase 3: Documentation & Examples (IN PROGRESS)
  • 🔄 Comprehensive documentation updates
  • 📅 Example configurations and use cases
• 📅 Phase 4: Advanced resolution strategies and ML-assisted learning
• 📅 Phase 5: Performance optimization and caching

Security Highlights

• ClusterFuzzLite: Continuous fuzzing (3 fuzz targets, ASan + UBSan)
• Test Coverage: 82.35% overall, 95%+ for security modules
• Security Scanning: CodeQL, Trivy, TruffleHog, Bandit, pip-audit, OpenSSF Scorecard
• Secret Detection: 14+ pattern types (GitHub tokens, AWS keys, API keys, etc.)
• Documentation: Comprehensive security documentation (threat model, incident response, compliance)

🔗 Related Projects

• ContextForge Memory - Original implementation
• CodeRabbit AI - AI-powered code review

---

Made with ❤️ by VirtualAgentics