Conflict Resolution Guide
Overview
Rhema’s advanced conflict resolution system provides comprehensive dependency conflict detection and resolution capabilities. This guide covers how to use the conflict resolution features through the CLI and programmatically.
CLI Commands
Basic Conflict Resolution
# Resolve conflicts in the current lock file
rhema lock resolve-conflicts
# Resolve conflicts in a specific lock file
rhema lock resolve-conflicts --file path/to/rhema.lock
# Show detailed information about conflicts
rhema lock resolve-conflicts --verbose
# Show only conflicts that need manual resolution
rhema lock resolve-conflicts --manual-onlyAdvanced Configuration
# Use a specific resolution strategy
rhema lock resolve-conflicts --strategy smart_selection
# Configure fallback strategies
rhema lock resolve-conflicts --fallback-strategies "conservative,manual_resolution"
# Set compatibility threshold for smart selection
rhema lock resolve-conflicts --compatibility-threshold 0.9
# Enable parallel resolution for better performance
rhema lock resolve-conflicts --parallel --max-threads 8
# Prefer stable versions
rhema lock resolve-conflicts --prefer-stable
# Enforce pinned versions strictly
rhema lock resolve-conflicts --strict-pinningOutput and Reporting
# Generate a detailed report
rhema lock resolve-conflicts --report-file conflict-report.json --format json
# Show performance metrics
rhema lock resolve-conflicts --show-metrics
# Apply resolved changes to lock file
rhema lock resolve-conflicts --apply
# Dry run (don't apply changes)
rhema lock resolve-conflicts --apply=falseResolution Strategies
1. Latest Compatible (Default)
Automatically selects the latest version that satisfies all requirements.
rhema lock resolve-conflicts --strategy latest_compatibleBest for: Projects that want the newest features while maintaining compatibility.
2. Pinned Version
Enforces pinned versions when available, ensuring deterministic builds.
rhema lock resolve-conflicts --strategy pinned_versionBest for: Production environments requiring exact version reproducibility.
3. Smart Selection
Uses compatibility scores for intelligent version selection.
rhema lock resolve-conflicts --strategy smart_selection --compatibility-threshold 0.8Best for: Complex dependency trees where compatibility is critical.
4. Conservative
Prefers stable, well-tested versions over the latest features.
rhema lock resolve-conflicts --strategy conservativeBest for: Production systems where stability is more important than new features.
5. Aggressive
Prefers latest versions with newest features.
rhema lock resolve-conflicts --strategy aggressiveBest for: Development environments where you want the latest features.
6. Manual Resolution
Detects conflicts and provides guidance for manual resolution.
rhema lock resolve-conflicts --strategy manual_resolution --allow-promptsBest for: Complex conflicts requiring human judgment.
7. Automatic Detection
Comprehensive conflict detection without auto-resolution.
rhema lock resolve-conflicts --strategy automatic_detectionBest for: Understanding dependency conflicts before deciding how to resolve them.
8. History Tracking
Uses historical resolution data to inform decisions.
rhema lock resolve-conflicts --strategy history_trackingBest for: Teams with established resolution patterns.
9. Hybrid
Combines multiple strategies in sequence.
rhema lock resolve-conflicts --strategy hybridBest for: Complex scenarios requiring multiple resolution approaches.
Configuration Options
Primary Strategy
The main resolution strategy to use:
latest_compatible(default)pinned_versionmanual_resolutionautomatic_detectionhistory_trackingsmart_selectionconservativeaggressivehybrid
Fallback Strategies
Comma-separated list of fallback strategies to try if the primary strategy fails.
Compatibility Threshold
For smart selection strategy, the minimum compatibility score (0.0-1.0) required for a version to be considered.
Performance Options
--parallel: Enable parallel resolution--max-threads: Maximum number of parallel threads (default: 4)--timeout: Timeout for resolution operations in seconds (default: 300)
Behavior Control
--prefer-stable: Prefer stable versions over latest--strict-pinning: Enforce pinned versions strictly--allow-prompts: Allow user prompts for manual resolution--auto-detection: Enable automatic conflict detection--track-history: Track resolution history
Understanding Conflict Types
Version Incompatibility
Different scopes require incompatible versions of the same dependency.
Example: Scope A requires lib@^1.0.0 while Scope B requires lib@^2.0.0
Circular Dependencies
Dependencies form a cycle, making resolution impossible.
Example: A → B → C → A
Missing Dependencies
A required dependency is not available or cannot be found.
Ambiguous Resolution
Multiple versions satisfy the constraints, making the choice unclear.
Security Vulnerabilities
A dependency version has known security issues.
License Incompatibility
Dependencies have incompatible licenses.
Conflict Severity Levels
Low
Can be auto-resolved without significant risk.
Medium
Requires user attention but can often be resolved automatically.
High
May break functionality and requires careful consideration.
Critical
Must be resolved manually and may require architectural changes.
Best Practices
1. Start with Detection
Before resolving conflicts, understand what conflicts exist:
rhema lock resolve-conflicts --strategy automatic_detection --verbose2. Use Appropriate Strategies
- Development: Use
aggressiveorlatest_compatible - Staging: Use
conservativeorsmart_selection - Production: Use
pinned_versionorconservative
3. Review Before Applying
Always review the resolution plan before applying changes:
rhema lock resolve-conflicts --apply=false --verbose4. Use Fallback Strategies
Configure multiple fallback strategies for robust resolution:
rhema lock resolve-conflicts \
--strategy smart_selection \
--fallback-strategies "conservative,manual_resolution"5. Monitor Performance
Use performance metrics to optimize resolution:
rhema lock resolve-conflicts --show-metrics6. Track Resolution History
Enable history tracking to learn from past resolutions:
rhema lock resolve-conflicts --track-historyIntegration with CI/CD
Automated Conflict Resolution
# In CI pipeline
rhema lock resolve-conflicts \
--strategy conservative \
--apply \
--report-file conflict-report.json \
--format jsonConflict Detection in PRs
# Check for conflicts without resolving
rhema lock resolve-conflicts \
--strategy automatic_detection \
--report-file conflicts.json \
--format jsonSecurity-Focused Resolution
# Focus on security vulnerabilities
rhema lock resolve-conflicts \
--strategy conservative \
--prefer-stable \
--strict-pinningTroubleshooting
Common Issues
Resolution Timeout
If resolution takes too long, try:
rhema lock resolve-conflicts --timeout 600 --parallel --max-threads 8Too Many Conflicts
If there are too many conflicts to resolve automatically:
rhema lock resolve-conflicts --strategy manual_resolution --manual-onlyIncompatible Versions
For version incompatibilities:
rhema lock resolve-conflicts --strategy conservative --prefer-stableCircular Dependencies
For circular dependencies:
rhema lock resolve-conflicts --strategy manual_resolution --verboseDebugging
Enable verbose output for detailed information:
rhema lock resolve-conflicts --verbose --show-metricsGenerate detailed reports for analysis:
rhema lock resolve-conflicts \
--report-file debug-report.json \
--format json \
--verbose \
--show-metricsAPI Usage
Programmatic Conflict Resolution
use rhema::lock::{
ConflictResolver, ConflictResolutionConfig, ConflictResolutionStrategy,
DependencySpec, LockSystem
};
// Create configuration
let config = ConflictResolutionConfig {
primary_strategy: ConflictResolutionStrategy::SmartSelection,
fallback_strategies: vec![
ConflictResolutionStrategy::Conservative,
ConflictResolutionStrategy::ManualResolution,
],
compatibility_threshold: 0.8,
prefer_stable: true,
track_history: true,
..Default::default()
};
// Resolve conflicts
let dependencies = vec![/* your dependencies */];
let repo_path = PathBuf::from("/path/to/repo");
let result = LockSystem::resolve_conflicts(&dependencies, &repo_path, Some(config))?;
if result.successful {
println!("Resolved {} conflicts", result.stats.auto_resolved);
} else {
for warning in &result.warnings {
println!("Warning: {}", warning);
}
}Custom Conflict Resolver
use rhema::lock::ConflictResolver;
let mut resolver = ConflictResolver::with_config(config);
let result = resolver.resolve_conflicts(&dependencies, &repo_path)?;
// Access detailed information
println!("Total conflicts: {}", result.stats.total_conflicts);
println!("Auto-resolved: {}", result.stats.auto_resolved);
println!("Manual resolution required: {}", result.stats.manual_resolution_required);
// Get performance metrics
let metrics = &result.performance_metrics;
println!("Total time: {}ms", metrics.total_time_ms);
println!("Memory usage: {} bytes", metrics.memory_usage_bytes);Examples
Example 1: Basic Conflict Resolution
# Simple conflict resolution
rhema lock resolve-conflicts --applyExample 2: Conservative Resolution for Production
# Production-ready conflict resolution
rhema lock resolve-conflicts \
--strategy conservative \
--prefer-stable \
--strict-pinning \
--apply \
--report-file production-resolution.jsonExample 3: Development with Latest Features
# Development environment with latest features
rhema lock resolve-conflicts \
--strategy aggressive \
--parallel \
--max-threads 8 \
--applyExample 4: Complex Conflict Analysis
# Detailed conflict analysis
rhema lock resolve-conflicts \
--strategy automatic_detection \
--verbose \
--manual-only \
--report-file conflict-analysis.json \
--format json \
--show-metricsExample 5: CI/CD Integration
# Automated resolution in CI
rhema lock resolve-conflicts \
--strategy smart_selection \
--compatibility-threshold 0.9 \
--apply \
--report-file ci-resolution.json \
--format jsonConclusion
Rhema’s conflict resolution system provides powerful tools for managing dependency conflicts. By understanding the available strategies and best practices, you can effectively resolve conflicts in your projects while maintaining stability and compatibility.
For more advanced usage and customization, refer to the API documentation and examples in the codebase.