diff --git a/.gitignore b/.gitignore index d01bd1a9..60a37584 100644 --- a/.gitignore +++ b/.gitignore @@ -18,4 +18,6 @@ Cargo.lock # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ \ No newline at end of file +#.idea/ + +.DS_Store \ No newline at end of file diff --git a/documentationMultipleLanguageSuport/CONFLICT_TYPES.md b/documentationMultipleLanguageSuport/CONFLICT_TYPES.md new file mode 100644 index 00000000..4257d4d4 --- /dev/null +++ b/documentationMultipleLanguageSuport/CONFLICT_TYPES.md @@ -0,0 +1,478 @@ +# Git Merge Conflict Types - Multi-Language Reference + +This document categorizes common types of merge conflicts across different programming languages and provides resolution strategies for AI agents. + +--- + +## Conflict Classification System + +Each conflict is assigned a **difficulty score (1-5)** that determines whether the agent should: +- **1-2 (Trivial):** Auto-resolve without user input +- **3 (Moderate):** Auto-resolve with confidence indicators +- **4 (Complex):** Present options to user +- **5 (Critical):** Always require user decision + +--- + +## Language-Agnostic Conflicts + +These patterns appear across all languages: + +### 1. Whitespace Conflicts (Difficulty: 1) + +**Description:** Differences only in spaces, tabs, or newlines. + +**Example:** +```python +<<<<<<< HEAD +def hello(): + print("world") +======= +def hello(): + print("world") # Tab instead of spaces +>>>>>>> branch +``` + +**Resolution Strategy:** +- Normalize to project style (detect from `.editorconfig` or majority usage) +- If Python: always use spaces (PEP 8) +- If Go: always use tabs + +**Auto-Resolve:** Yes + +--- + +### 2. Comment Conflicts (Difficulty: 1) + +**Description:** Only comments differ between versions. + +**Example:** +```javascript +<<<<<<< HEAD +// TODO: Refactor this function +======= +// FIXME: This needs optimization +>>>>>>> branch +function process() { ... } +``` + +**Resolution Strategy:** +- Merge both comments if they convey different information +- If duplicate meaning, keep the more actionable one + +**Auto-Resolve:** Yes + +--- + +### 3. Import/Dependency Conflicts (Difficulty: 2) + +**Description:** Different imports or dependencies added on each branch. + +**Python Example:** +```python +<<<<<<< HEAD +import os +import sys +======= +import os +import json +>>>>>>> branch +``` + +**JavaScript Example:** +```javascript +<<<<<<< HEAD +import { useState } from 'react'; +import axios from 'axios'; +======= +import { useState } from 'react'; +import fetch from 'node-fetch'; +>>>>>>> branch +``` + +**Resolution Strategy:** +- **Union merge:** Include all unique imports +- Sort imports alphabetically (language convention) +- Remove duplicates +- Verify all imports are actually used in the resolved code + +**Auto-Resolve:** Yes (with verification) + +--- + +### 4. Variable/Function Renaming (Difficulty: 3) + +**Description:** One branch renames an identifier, the other modifies its usage. + +**Example:** +```python +<<<<<<< HEAD +def calculate_total(items): + return sum(items) +======= +def compute_sum(items): + return sum(items) +>>>>>>> branch + +# Elsewhere in the file: +result = calculate_total([1, 2, 3]) # Which name to use? +``` + +**Resolution Strategy:** +1. Detect rename pattern (same logic, different name) +2. Choose the new name from the branch that renamed +3. **Update all references** throughout the file +4. Verify no undefined references remain + +**Auto-Resolve:** ⚠️ Conditional (if confident about rename scope) + +--- + +### 5. Configuration Value Changes (Difficulty: 3) + +**Description:** Both branches change the same config value. + +**JSON Example:** +```json +{ +<<<<<<< HEAD + "timeout": 5000 +======= + "timeout": 10000 +>>>>>>> branch +} +``` + +**YAML Example:** +```yaml +<<<<<<< HEAD +max_connections: 100 +======= +max_connections: 200 +>>>>>>> branch +``` + +**Resolution Strategy:** +- Check commit messages for rationale +- If one is a "hotfix" or "critical", prefer that value +- Otherwise, ask user which value to keep +- Suggest creating an environment variable instead + +**Auto-Resolve:** ❌ No (user decision needed) + +--- + +## Language-Specific Conflicts + +### Python + +#### Type Hints Conflict (Difficulty: 2) +```python +<<<<<<< HEAD +def process(data: dict) -> list: +======= +def process(data: Dict[str, Any]) -> List[str]: +>>>>>>> branch +``` + +**Resolution:** Prefer the more specific type hint (branch version). + +#### Docstring Conflict (Difficulty: 2) +```python +<<<<<<< HEAD +"""Process data and return results.""" +======= +""" +Process data with validation. + +Args: + data: Input dictionary + +Returns: + List of processed items +""" +>>>>>>> branch +``` + +**Resolution:** Keep the more detailed docstring. + +--- + +### JavaScript/TypeScript + +#### TypeScript Interface Conflict (Difficulty: 3) +```typescript +<<<<<<< HEAD +interface User { + name: string; + email: string; +} +======= +interface User { + name: string; + email: string; + age?: number; +} +>>>>>>> branch +``` + +**Resolution:** Union merge (keep all properties). Mark new fields as optional. + +#### React Component Props Conflict (Difficulty: 4) +```tsx +<<<<<<< HEAD +function Button({ onClick }: { onClick: () => void }) { +======= +function Button({ onClick, disabled }: { onClick: () => void; disabled?: boolean }) { +>>>>>>> branch +``` + +**Resolution:** Union merge props, ensure new props have defaults. + +--- + +### Go + +#### Error Handling Pattern Conflict (Difficulty: 3) +```go +<<<<<<< HEAD +if err != nil { + return err +} +======= +if err != nil { + return fmt.Errorf("failed to connect: %w", err) +} +>>>>>>> branch +``` + +**Resolution:** Prefer wrapped errors (better debugging). + +--- + +### Rust + +#### Ownership/Borrow Conflict (Difficulty: 5) +```rust +<<<<<<< HEAD +fn process(data: Vec) -> usize { + data.len() +} +======= +fn process(data: &Vec) -> usize { + data.len() +} +>>>>>>> branch +``` + +**Resolution:** This requires semantic analysis. Prefer `&Vec` (borrowing) unless ownership transfer is needed. **Must verify borrow checker passes.** + +--- + +## Logic Conflicts (All Languages) + +### 6. Conditional Logic Merge (Difficulty: 4) + +**Description:** Both branches add different conditions to the same block. + +**Python Example:** +```python +<<<<<<< HEAD +if user.is_authenticated and user.has_permission: + allow_access() +======= +if user.is_authenticated and not user.is_banned: + allow_access() +>>>>>>> branch +``` + +**Resolution Strategy:** +- **Additive approach:** Combine conditions with `and` +- Result: `if user.is_authenticated and user.has_permission and not user.is_banned:` +- Verify logical consistency (no contradictions) + +**Auto-Resolve:** ⚠️ Conditional (if intents align) + +--- + +### 7. Algorithm Change Conflict (Difficulty: 5) + +**Description:** Both branches implement different algorithms for the same function. + +**Example:** +```python +<<<<<<< HEAD +def sort_items(items): + return sorted(items) # Quick sort +======= +def sort_items(items): + # Bubble sort for stability + for i in range(len(items)): + for j in range(len(items)-i-1): + if items[j] > items[j+1]: + items[j], items[j+1] = items[j+1], items[j] + return items +>>>>>>> branch +``` + +**Resolution Strategy:** +- **Cannot auto-merge** - fundamentally different approaches +- Present both implementations to user +- Suggest keeping both as separate functions (e.g., `sort_items_fast` vs `sort_items_stable`) + +**Auto-Resolve:** ❌ Never + +--- + +## Detection Patterns (For Agent Implementation) + +The agent should detect conflict types using these heuristics: + +### Whitespace Detection +```python +def is_whitespace_conflict(local, remote): + return local.strip() == remote.strip() +``` + +### Import Detection +```python +def is_import_conflict(local, remote, language): + patterns = { + 'python': r'^import |^from .* import', + 'javascript': r'^import .* from|^const .* = require', + 'go': r'^import \(', + } + local_is_import = re.match(patterns[language], local) + remote_is_import = re.match(patterns[language], remote) + return local_is_import and remote_is_import +``` + +### Rename Detection +```python +def is_rename_conflict(local, remote): + # Check if structure is identical except for one identifier + local_tokens = tokenize(local) + remote_tokens = tokenize(remote) + + if len(local_tokens) != len(remote_tokens): + return False + + differences = sum(1 for l, r in zip(local_tokens, remote_tokens) if l != r) + return differences == 1 # Only one token differs +``` + +--- + +## Resolution Priority Rules + +When multiple conflicts exist in a file, resolve in this order: + +1. **Whitespace conflicts** (trivial) +2. **Comment conflicts** (trivial) +3. **Import conflicts** (can affect later resolutions) +4. **Rename conflicts** (affects variable references) +5. **Logic conflicts** (most complex) + +--- + +## Agent Decision Tree + +``` +Is conflict whitespace-only? +├─ YES → Auto-normalize and resolve +└─ NO + │ + Are both sides adding new imports? + ├─ YES → Union merge imports + └─ NO + │ + Is it a rename + modification? + ├─ YES → Apply rename everywhere + └─ NO + │ + Are commit messages clear? + ├─ YES → Follow semantic intent + └─ NO → Present options to user +``` + +--- + +## Language-Specific Import Sorting + +### Python (PEP 8 Order) +1. Standard library imports +2. Related third-party imports +3. Local application imports + +```python +import os +import sys + +import numpy as np +import pandas as pd + +from .models import User +``` + +### JavaScript/TypeScript +1. External packages +2. Internal packages +3. Relative imports + +```javascript +import React from 'react'; +import axios from 'axios'; + +import { API_URL } from '@/config'; + +import './styles.css'; +``` + +### Go +- Group standard library, then external packages +- Use `goimports` tool for automatic sorting + +--- + +## Testing Conflict Resolution + +Create test scenarios for each conflict type: + +```bash +# Setup test repo +git init test-conflicts +cd test-conflicts + +# Create conflicting branches +git checkout -b feature-a +echo "version A" > file.txt +git commit -am "Change A" + +git checkout main +echo "version B" > file.txt +git commit -am "Change B" + +# Attempt merge +git merge feature-a # Creates conflict + +# Test agent resolution +python get_tools.py extract file.txt +# Agent analyzes and resolves... +``` + +--- + +## Future Enhancements + +1. **Machine Learning Model:** Train on resolved conflicts to predict resolution strategy +2. **AST-Level Merging:** Parse code into AST, merge at semantic level +3. **Test-Driven Resolution:** Run tests for each resolution candidate +4. **Cross-Reference Detection:** Identify when changes in one file affect imports in another + +--- + +## References + +- [Google Sheet - Conflict Types](https://docs.google.com/spreadsheets/d/1cT7eUNmxuOgy26hpWKud_L2dnhitMGqS2d6XJF2SJ4A/) +- Git Documentation: [How Conflicts Are Presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented) +- [Semantic Merge Paper (2011)](https://www.semanticmerge.com/) \ No newline at end of file diff --git a/documentationMultipleLanguageSuport/LANGUAGE_SUPPORT.md b/documentationMultipleLanguageSuport/LANGUAGE_SUPPORT.md new file mode 100644 index 00000000..9e25dcca --- /dev/null +++ b/documentationMultipleLanguageSuport/LANGUAGE_SUPPORT.md @@ -0,0 +1,296 @@ +# Multi-Language Syntax Validation Support + +This document describes the syntax validation capabilities of the Git Merge Conflict Resolution skill across different programming languages. + +## Currently Supported Languages + +### Python (.py) + +- **Validator:** Built-in AST parser +- **Requirements:** None (Python standard library) +- **Validation Method:** `ast.parse()` +- **Coverage:** Full syntax validation including indentation errors + +### JavaScript (.js, .jsx, .mjs) + +- **Validator:** Node.js +- **Requirements:** `node` must be installed +- **Validation Method:** `node --check` +- **Coverage:** ECMAScript syntax validation +- **Install:** [Download Node.js](https://nodejs.org/) + +### TypeScript (.ts, .tsx) + +- **Validator:** TypeScript Compiler +- **Requirements:** `tsc` must be installed globally +- **Validation Method:** `tsc --noEmit --skipLibCheck` +- **Coverage:** Full TypeScript type checking +- **Install:** `npm install -g typescript` + +### JSON (.json) + +- **Validator:** Built-in JSON parser +- **Requirements:** None (Python standard library) +- **Validation Method:** `json.load()` +- **Coverage:** JSON syntax and structure validation + +### Go (.go) + +- **Validator:** Go compiler +- **Requirements:** `go` must be installed +- **Validation Method:** `go fmt` +- **Coverage:** Go syntax validation +- **Install:** [Download Go](https://golang.org/dl/) + +### Rust (.rs) + +- **Validator:** Rust compiler +- **Requirements:** `rustc` must be installed +- **Validation Method:** `rustc --crate-type lib` +- **Coverage:** Full Rust syntax and borrow checker +- **Install:** [Install Rust](https://rustup.rs/) + +### Generic Fallback (All Other Files) + +- **Validator:** Basic file readability check +- **Requirements:** None +- **Coverage:** Checks if file exists and is readable as UTF-8 text +- **Limitation:** Does NOT validate actual syntax + +--- + +## Validation Status Messages + +The validator returns a JSON object with the following fields: + +```json +{ + "status": "valid" | "error" | "warning" | "skipped", + "message": "Human-readable status message", + "details": "Detailed error information (if applicable)", + "language": "python" | "javascript" | "typescript" | ... +} +``` + +### Status Types + +| Status | Meaning | +| --------- | ---------------------------------------------------- | +| `valid` | File syntax is correct | +| `error` | Syntax error detected | +| `warning` | File validated but with caveats (e.g., binary files) | +| `skipped` | Required tool not installed, validation skipped | + +--- + +## Usage Examples + +### From Command Line + +```bash +# Verify a Python file +python get_tools.py verify src/main.py + +# Verify a TypeScript file +python get_tools.py verify components/App.tsx + +# Verify a JSON configuration +python get_tools.py verify package.json +``` + +### From Agent Context + +The agent can call the verify command after resolving conflicts: + +``` +Agent: I've resolved the conflict in `server.js`. Let me verify the syntax... +System: python get_tools.py verify server.js +Output: {"status": "valid", "message": "JavaScript syntax check passed.", "language": "javascript"} +Agent: ✓ Syntax verified. You can now run `git add server.js`. +``` + +--- + +## Adding Support for New Languages + +To add a new language validator: + +### 1. Create a Validator Class + +In `syntax_validators.py`, add a new class: + +```python +class YourLanguageValidator(SyntaxValidator): + """Validates YourLanguage syntax.""" + + def __init__(self): + super().__init__() + self.supported_extensions = ['.ext'] # File extensions + self.has_tool = self._check_tool_available() + + def _check_tool_available(self) -> bool: + """Check if validation tool is installed.""" + try: + subprocess.run(['your-tool', '--version'], + capture_output=True, + check=True, + timeout=2) + return True + except: + return False + + def validate(self, filepath: str) -> Dict[str, str]: + if not self.has_tool: + return { + "status": "skipped", + "message": "Tool not found. Install instructions...", + "language": "yourlanguage" + } + + # Your validation logic here + # ... + + return { + "status": "valid", + "message": "Validation passed.", + "language": "yourlanguage" + } +``` + +### 2. Register the Validator + +In `ValidatorRegistry.__init__()`, add your validator: + +```python +self.validators = [ + PythonValidator(), + JavaScriptValidator(), + # ... existing validators ... + YourLanguageValidator(), # Add here +] +``` + +### 3. Test + +```bash +python syntax_validators.py path/to/file.ext +``` + +--- + +## Language Priority Suggestions + +Based on GitHub usage statistics, recommended next languages to support: + +1. **Java** (.java) - Use `javac` or `jdk.compiler` API +2. **C/C++** (.c, .cpp, .h) - Use `gcc -fsyntax-only` +3. **C#** (.cs) - Use `dotnet build` or Roslyn +4. **PHP** (.php) - Use `php -l` +5. **Ruby** (.rb) - Use `ruby -c` +6. **Swift** (.swift) - Use `swiftc -parse` +7. **Kotlin** (.kt) - Use `kotlinc` + +--- + +## Graceful Degradation + +The system is designed to **never block** the agent's workflow: + +- If a validator is not installed → `status: "skipped"` with helpful install message +- If file type is unsupported → Generic validator checks basic readability +- If validation times out → Returns error but doesn't crash + +This ensures the agent can always proceed with merge resolution, even in environments with limited tooling. + +--- + +## Performance Considerations + +### Fast Validators (< 100ms) + +- Python (AST) +- JSON (Native) +- Generic (File read) + +### Medium Validators (< 1s) + +- JavaScript (Node.js) +- Go (go fmt) + +### Slower Validators (1-5s) + +- TypeScript (tsc with type checking) +- Rust (rustc compilation) + +**Optimization:** All validators have a 5-10 second timeout to prevent hanging. + +--- + +## Testing the Validator + +### Create Test Files + +```bash +# In your test repo +mkdir -p test_files + +# Python test +echo "print('hello')" > test_files/valid.py +echo "print('unclosed" > test_files/invalid.py + +# JavaScript test +echo "console.log('hello');" > test_files/valid.js +echo "console.log('unclosed" > test_files/invalid.js + +# JSON test +echo '{"valid": true}' > test_files/valid.json +echo '{"invalid": }' > test_files/invalid.json +``` + +### Run Validation + +```bash +python get_tools.py verify test_files/valid.py +python get_tools.py verify test_files/invalid.py +python get_tools.py verify test_files/valid.js +python get_tools.py verify test_files/invalid.json +``` + +--- + +## FAQ + +### Q: What if I don't have Node.js installed? + +**A:** JavaScript files will return `status: "skipped"` with a message explaining what's missing. The agent can still resolve the conflict, but won't validate syntax. + +### Q: Can I disable validation for certain file types? + +**A:** Yes. Modify the `ValidatorRegistry` to skip specific extensions, or the agent can be instructed to skip the verify step. + +### Q: Does validation modify my files? + +**A:** No. All validators are read-only except `go fmt`, which we run in a way that doesn't modify the original file. + +### Q: What about binary files (images, PDFs)? + +**A:** The generic validator detects binary files and returns `status: "warning"` without attempting text parsing. + +--- + +## Integration with instructions.md + +The agent's main instructions should reference this capability: + +```markdown +### COMMAND: apply + +**Action:** + +1. Write the resolved content to disk +2. **Verify syntax** using `python get_tools.py verify ` +3. Report validation status to user +4. If syntax is invalid, ask user if they want Claude to fix it +``` + +This ensures every resolved conflict is validated before the user stages it. diff --git a/llm-git-conflict-resolve/Makefile b/llm-git-conflict-resolve/Makefile new file mode 100644 index 00000000..fcae1cae --- /dev/null +++ b/llm-git-conflict-resolve/Makefile @@ -0,0 +1,28 @@ +SCRIPT_RENAME = generate_conflict_rename_vs_modify.sh +DIR_RENAME = conflict-rename-vs-modify + +SCRIPT_LOGIC = generate_conflict_logic_merge.sh +DIR_LOGIC = conflict-logic-merge + +.PHONY: all help rename logic clean + +all: help + +help: + @echo "Available targets:" + @echo " make rename - Generate Rename vs Modify conflicted repo" + @echo " make logic - Generate Logic Merge conflicted repo" + @echo " make clean - Remove generated directories" + +rename: + @rm -rf $(DIR_RENAME) + @chmod +x $(SCRIPT_RENAME) + @./$(SCRIPT_RENAME) + +logic: + @rm -rf $(DIR_LOGIC) + @chmod +x $(SCRIPT_LOGIC) + @./$(SCRIPT_LOGIC) + +clean: + @rm -rf $(DIR_RENAME) $(DIR_LOGIC) \ No newline at end of file diff --git a/llm-git-conflict-resolve/generate_conflict_logic_merge.sh b/llm-git-conflict-resolve/generate_conflict_logic_merge.sh new file mode 100755 index 00000000..c5b08b11 --- /dev/null +++ b/llm-git-conflict-resolve/generate_conflict_logic_merge.sh @@ -0,0 +1,91 @@ +#!/bin/bash + +# Setup script for Git merge conflict demo (Scenario: Logic Merge) +# Conflict: Price Update (Local) vs Stock Check (Remote) + +# 1. Create directory +mkdir -p conflict-logic-merge +cd conflict-logic-merge + +# 2. Initialize git quietly +git init -q +git config user.email "dev@example.com" +git config user.name "Dev User" + +# 3. Copy tools and setup GEMINI.md +if [ -d "../skill" ]; then + cp ../skill/git_tools.py . + cp ../skill/instructions.md GEMINI.md +else + echo "Error: '../skill' directory not found." + exit 1 +fi + +# 4. Base Commit +cat > products.py << 'EOF' +import sys + +def filter_products(products): + """ + Filters a list of products based on basic criteria. + Current rule: Only cheap products under $100. + """ + valid_products = [] + for p in products: + if p['price'] < 100: + valid_products.append(p) + return valid_products +EOF + +git add products.py +git commit -q -m "Initial commit" + +# 5. Remote Branch (Feature): Add Stock Check & Logging +git checkout -q -b feature-stock +cat > products.py << 'EOF' +import sys +import logging + +def filter_products(products): + """ + Filters products: cheap AND in stock. + """ + valid_products = [] + for p in products: + if p['price'] < 100 and p['in_stock'] is True: + valid_products.append(p) + else: + logging.info(f"Skipping product: {p['id']}") + return valid_products +EOF + +git commit -a -q -m "Feature: Add stock check validation" + +# 6. Local Branch (Master): Update Price Policy (Inflation) +git checkout -q master +cat > products.py << 'EOF' +import sys +import math + +def filter_products(products): + """ + Filters a list of products based on basic criteria. + Updated rule: Adjusted for inflation, limit is now $150. + """ + valid_products = [] + for p in products: + if p['price'] < 150: + valid_products.append(p) + return valid_products +EOF + +git commit -a -q -m "Policy Update: Increase price limit to $150" + +# 7. Create Conflict +git merge feature-stock --no-edit > /dev/null 2>&1 || true + +echo "==================================" +echo "Conflicted Repo Ready (Logic Conflict)" +echo "Folder: conflict-logic-merge/" +echo "To start: cd conflict-logic-merge && gemini" +echo "==================================" \ No newline at end of file diff --git a/llm-git-conflict-resolve/generate_conflict_rename_vs_modify.sh b/llm-git-conflict-resolve/generate_conflict_rename_vs_modify.sh new file mode 100755 index 00000000..f7dedc85 --- /dev/null +++ b/llm-git-conflict-resolve/generate_conflict_rename_vs_modify.sh @@ -0,0 +1,106 @@ +#!/bin/bash + +# Setup script for Git merge conflict demo (Scenario: Rename vs Modify) + +# 1. Create directory +mkdir -p conflict-rename-vs-modify +cd conflict-rename-vs-modify + +# 2. Initialize git quietly +git init -q +git config user.email "test@example.com" +git config user.name "Test User" + +# 3. Copy tools and setup GEMINI.md +if [ -d "../skill" ]; then + cp ../skill/git_tools.py . + cp ../skill/instructions.md GEMINI.md +else + echo "Error: '../skill' directory not found." + exit 1 +fi + +# 4. Base Commit +cat > utils.py << 'EOF' +import os +import sys + +def process_data(data): + """Process the input data.""" + result = [] + for item in data: + result.append(item * 2) + return result + +def calculate_sum(numbers): + """Calculate sum of numbers.""" + total = 0 + for num in numbers: + total += num + return total +EOF + +git add utils.py +git commit -q -m "Initial commit" + +# 5. Remote Branch (Feature): Add logging & new function +git checkout -q -b feature +cat > utils.py << 'EOF' +import os +import sys +import json + +def process_data(data): + """Process the input data with enhanced logging.""" + result = [] + for item in data: + print(f"Processing: {item}") + result.append(item * 2) + return result + +def calculate_sum(numbers): + """Calculate sum of numbers.""" + total = 0 + for num in numbers: + total += num + return total + +def export_to_json(data, filename): + """Export data to JSON file.""" + with open(filename, 'w') as f: + json.dump(data, f, indent=2) +EOF + +git commit -a -q -m "Feature: Add JSON export and logging" + +# 6. Local Branch (Master): Rename functions +git checkout -q master +cat > utils.py << 'EOF' +import os +import sys + +def transform_data(data): + """Transform the input data (renamed from process_data).""" + result = [] + for item in data: + result.append(item * 2) + return result + +def sum_numbers(numbers): + """Calculate sum of numbers (renamed from calculate_sum).""" + total = 0 + for num in numbers: + total += num + return total +EOF + +git commit -a -q -m "Refactor: Rename functions" + +# 7. Create Conflict +git merge feature --no-edit > /dev/null 2>&1 || true + +echo "==================================" +echo "Conflicted Repo Ready (Rename vs Modify)" +echo "Folder: conflict-rename-vs-modify/" +echo "To start: cd conflict-rename-vs-modify && gemini" +echo "==================================" \ No newline at end of file diff --git a/llm-git-conflict-resolve/skill/README.md b/llm-git-conflict-resolve/skill/README.md new file mode 100644 index 00000000..d37c58ab --- /dev/null +++ b/llm-git-conflict-resolve/skill/README.md @@ -0,0 +1,196 @@ +# Git Merge Conflict Resolution Skill + +An intelligent AI-powered tool that resolves complex git merge conflicts by understanding the semantic intent behind code changes, not just the textual differences. + +## What This Skill Does + +This skill acts as an **expert Git Merge Conflict Orchestrator** that: + +- **Automatically detects** merge conflicts in your repository +- **Analyzes semantic intent** by examining commit messages and code changes +- **Intelligently merges** conflicting changes by understanding what each branch was trying to accomplish +- **Verifies syntax** of resolved files to ensure code validity +- **Guides you step-by-step** through the entire conflict resolution process + +Unlike traditional merge tools that only show you textual differences, this skill understands programming logic and can synthesize changes from both branches to produce code that satisfies both sets of requirements. + +## How It Works + +### The Intelligence Behind Resolution + +1. **Three-Way Diff Analysis**: Extracts the base (common ancestor), local (your changes), and remote (incoming changes) versions of each conflicted file + +2. **Semantic Intent Detection**: Reads commit messages to understand *why* changes were made on each branch, not just *what* changed + +3. **Logic Synthesis**: Intelligently combines changes by: + - Distinguishing structural changes (renaming, refactoring) from functional changes (new logic, behavior) + - Adapting one branch's logic to another branch's structural changes + - Combining additive changes when both branches add new constraints + - Choosing between conflicting values based on commit context + +4. **Code Integrity Validation**: Ensures the final output is syntactically valid and includes all necessary imports + +## How to Use This Skill + +### Prerequisites + +- You must be in a git repository with active merge conflicts +- Python 3 must be available on your system +- The `git_tools.py` script must be present in your working directory + +### Basic Workflow + +**1. Start the conversation** +``` +Hello +``` +The AI will greet you and suggest typing `scan` to begin. + +**2. Scan for conflicts** +``` +scan +``` +This lists all files with merge conflicts. + +**3. Resolve a specific file** +``` +resolve filename.py +``` +The AI will analyze the conflict and present a fully merged version of the file. + +**4. Apply the resolution** +``` +apply +``` +This writes the resolved content to disk and verifies syntax. + +**5. Mark as resolved in git** +```bash +git add filename.py +``` +You must manually run this command to tell git the conflict is resolved. + +**6. Continue with remaining conflicts** +``` +scan +``` +Repeat the process for other conflicted files. + +### Available Commands + +| Command | Aliases | Description | +|---------|---------|-------------| +| `scan` | find conflicts, list, status | Lists all files with merge conflicts | +| `resolve ` | solve, fix, extract | Analyzes and resolves conflicts in the specified file | +| `apply` | yes, save, confirm | Saves the resolved content and verifies syntax | +| `help` | info, commands | Shows available commands and workflow | + +### Example Session + +``` +User: hi +AI: Hello! Welcome to the Git Merge Conflict Resolver. Type 'help' to see available + commands, or type 'scan' to begin analyzing conflicts. + +User: scan +AI: Found 2 conflicted files: + • src/app.py (UU) + • config/settings.py (UU) + + To start resolving, type: resolve src/app.py + +User: resolve src/app.py +AI: [Analyzes the file and presents merged code] + + Review the code above. If it looks correct, type 'apply' to save it. + +User: apply +AI: ✓ File written successfully + ✓ Syntax verified: Python syntax check passed + + Please run `git add src/app.py` manually to mark it resolved, then type 'scan' to check for remaining conflicts. +``` + +## Resolution Strategies + +The AI uses several intelligent strategies to resolve conflicts: + +### 1. Structural vs. Functional Changes +- **Structural**: Renaming variables, moving functions, reformatting +- **Functional**: New logic, different values, behavior changes + +If one branch renames a variable and another modifies its logic, the AI applies the logic to the new name. + +### 2. Additive Merging +When both branches add new functionality (new imports, new conditions, new checks), the AI combines them unless they're mutually exclusive. + +### 3. Conflict Precedence +For direct conflicts (same value changed to different things), the AI examines commit messages to determine which change reflects the more recent policy or intent. + +### 4. Import Consolidation +Ensures all necessary imports from both versions are included in the final file. + +## Limitations + +### Current Constraints + +1. **Language Support**: Syntax verification currently only works for **Python files**. Other languages are assumed valid. + +2. **Manual Git Operations**: You must still manually run `git add ` after applying changes. + +3. **Complex Business Logic**: The AI makes its best judgment based on code structure and commit messages, but cannot understand complex business requirements or domain-specific rules. + +4. **Binary Files**: Cannot resolve conflicts in binary files (images, compiled code, etc.). + +5. **Requires Context**: Works best when commit messages are descriptive. Poor commit messages ("fixed stuff", "updates") reduce resolution accuracy. + +### When Human Review is Essential + +- **Security-sensitive code**: Always review changes to authentication, authorization, or cryptographic code +- **Database migrations**: Schema changes require careful human oversight +- **API contracts**: Changes to public APIs need manual verification +- **Configuration values**: Production settings should be manually confirmed + +## Best Practices + +### For Optimal Results + +1. **Write descriptive commit messages**: Clear messages help the AI understand intent + - Poor example: "updates" + - Good example: "Refactored authentication to use JWT tokens" + +2. **Review before applying**: Always review the proposed resolution before typing `apply` + +3. **Test after resolution**: Run your test suite after resolving conflicts + +4. **Resolve one file at a time**: Don't rush through multiple files without verification + +5. **Keep git_tools.py accessible**: Ensure the script is in your working directory + +### Troubleshooting + +**"File not found" error**: Make sure you're in the git repository root + +**"No conflicts found"**: Run `git status` to verify you're in a merge state + +**Syntax errors after resolution**: The AI will detect these and offer to fix them, or you can manually edit the file + +**Unexpected resolution**: Provide feedback and manually adjust the code. The AI learns from descriptive commit messages. + +## Getting Help + +- Type `help` at any time to see available commands +- The AI will always guide you on the next step +- If stuck, start over with `scan` to see the current state + +## Contributing + +This skill improves with better commit message analysis and expanded language support. Future enhancements may include: +- JavaScript/TypeScript syntax verification +- Automatic git add after successful resolution +- Interactive conflict resolution for ambiguous cases +- Machine learning from user feedback on resolutions + +--- + +**Remember**: This tool is designed to assist, not replace human judgment. Always review critical changes, especially in production code. \ No newline at end of file diff --git a/llm-git-conflict-resolve/skill/git_tools.py b/llm-git-conflict-resolve/skill/git_tools.py new file mode 100644 index 00000000..21ebec80 --- /dev/null +++ b/llm-git-conflict-resolve/skill/git_tools.py @@ -0,0 +1,151 @@ +import sys +import argparse +import subprocess +import json +import os +import ast + +def run_git_command(command): + """Executes a git command and returns the output as a string.""" + try: + result = subprocess.check_output( + command, + stderr=subprocess.STDOUT, + shell=True + ) + return result.decode('utf-8').strip() + except subprocess.CalledProcessError as e: + # Return None to signal that, for example, the file does not exist in that version + return None + +def list_conflicted_files(): + """Identifies files marked as conflicted.""" + # --porcelain provides a stable format for parsing + output = run_git_command("git status --porcelain") + if not output: + return [] + + conflicted_files = [] + for line in output.split('\n'): + # Conflicts are usually marked with 'UU', 'AA', 'UD', etc. + # The first 2 characters indicate the status + status = line[:2] + filepath = line[3:].strip() + + # Simplified filter: if both sides modified (U) or added (A) + if 'U' in status or 'A' in status: + conflicted_files.append({ + "filepath": filepath, + "status": status + }) + + return conflicted_files + +def get_file_content_at_stage(filepath, stage): + """ + Extracts file content at a specific git stage. + Stage 1 = Base (Ancestor) + Stage 2 = Ours (Local/HEAD) + Stage 3 = Theirs (Remote/MERGE_HEAD) + """ + # git show :: + content = run_git_command(f"git show :{stage}:{filepath}") + return content if content is not None else "" + +def get_commit_context(filepath): + """ + Extracts commit messages to understand semantic intent (Solution 3). + """ + # HEAD is the current branch (Local) + local_msg = run_git_command(f"git log -1 --pretty=%B HEAD -- {filepath}") + + # MERGE_HEAD is the incoming branch (Remote). + # It might be null if we are not in a standard merge, but we handle the case. + remote_msg = run_git_command(f"git log -1 --pretty=%B MERGE_HEAD -- {filepath}") + + return { + "local_intent": local_msg.strip() if local_msg else "Unknown (Manual changes or no commit msg)", + "remote_intent": remote_msg.strip() if remote_msg else "Unknown (No MERGE_HEAD found)" + } + +def verify_syntax(filepath): + """ + Verifies file syntax. Currently supports Python via AST. + Can be extended for JS/TS by running 'node -c' etc. + """ + if not os.path.exists(filepath): + return {"status": "error", "message": "File not found"} + + # File extension + _, ext = os.path.splitext(filepath) + + if ext == '.py': + try: + with open(filepath, 'r', encoding='utf-8') as f: + source = f.read() + ast.parse(source) + return {"status": "valid", "message": "Python syntax check passed."} + except SyntaxError as e: + return { + "status": "error", + "message": f"Syntax Error on line {e.lineno}: {e.msg}", + "details": str(e) + } + + # For other files, currently return valid (or implement specific linters) + return {"status": "valid", "message": f"No linter configured for {ext}, assuming valid."} + +def main(): + parser = argparse.ArgumentParser(description="Git Merge Conflict Tool for AI Agents") + subparsers = parser.add_subparsers(dest="command", help="Available commands") + + # --- Command: list --- + subparsers.add_parser("list", help="List conflicted files") + + # --- Command: extract --- + extract_parser = subparsers.add_parser("extract", help="Extract content and context") + extract_parser.add_argument("filepath", type=str, help="Path to the conflicted file") + + # --- Command: verify --- + verify_parser = subparsers.add_parser("verify", help="Verify syntax") + verify_parser.add_argument("filepath", type=str, help="Path to the file to verify") + + args = parser.parse_args() + + # Command routing + if args.command == "list": + result = list_conflicted_files() + print(json.dumps(result, indent=2)) + + elif args.command == "extract": + filepath = args.filepath + + # 1. Extract Diff (Code) + diff_data = { + "base": get_file_content_at_stage(filepath, 1), + "local": get_file_content_at_stage(filepath, 2), + "remote": get_file_content_at_stage(filepath, 3) + } + + # 2. Extract Context (Intent) + context_data = get_commit_context(filepath) + + # 3. Build the complete payload + full_payload = { + "file": filepath, + "diff": diff_data, + "context": context_data, + "note": "Use 'context' to determine intent, then merge 'diff' accordingly." + } + print(json.dumps(full_payload, indent=2)) + + elif args.command == "verify": + result = verify_syntax(args.filepath) + print(json.dumps(result, indent=2)) + + else: + # If no command is provided + parser.print_help() + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/llm-git-conflict-resolve/skill/instructions.md b/llm-git-conflict-resolve/skill/instructions.md new file mode 100644 index 00000000..905e4f0a --- /dev/null +++ b/llm-git-conflict-resolve/skill/instructions.md @@ -0,0 +1,83 @@ +# Git Merge Conflict Resolution Skill - System Instructions + +You are an expert Git Merge Conflict Orchestrator. Your goal is to resolve complex git merge conflicts autonomously by analyzing not just the textual diffs, but the semantic intent behind changes. + +## I. INTERACTION & GUIDANCE PROTOCOL + +**1. The "Welcome" Rule:** +At the very beginning of the conversation (or if the user says "hello", "hi", "start" or anything similar), you should: + 1. Greet the user. + 2. Mention that `help` lists available commands. + 3. Suggest typing `scan` to begin. + +**2. The "Next Step" Rule:** +Always guide the user on what to do next. Do not leave the conversation dead-ended. + - **Do not use slashes (/)** in your suggested commands. + - After scanning -> Suggest resolving specific files. + - After resolving -> Suggest applying the changes. + - After applying -> Remind the user to manually `git add` the file. + +--- + +## II. TOOL USAGE +1. **`python3 git_tools.py `**: Your primary interface for git analysis. +2. **`run_shell_command`** (Native Tool): Use this to execute the python scripts and to write files to disk. + +--- + +## III. COMMAND WORKFLOWS + +You must listen for the following keywords. Execute the action, then **guide the user**. + +### COMMAND: scan +**Triggers:** "scan", "find conflicts", "list", "status" +**Action:** +1. Execute: `python3 git_tools.py list` +2. Parse the JSON output. +3. Present a bulleted list of conflicted files. +4. **Guidance Example:** "To start resolving, you can type `resolve `." + +### COMMAND: resolve +**Triggers:** "resolve", "solve", "fix", "extract" (with or without filename) +**Action:** +1. **Validation:** If the user did NOT specify a filename (e.g., just said "solve"), ask: "Which file would you like to resolve?" and STOP. +2. **Extraction:** If a filename is present, execute `python3 git_tools.py extract `. +3. Analyze the Diff + Context using the Resolution Logic (Section IV). +4. Output the fully merged code block. +5. **Guidance Example:** "Review the code above. If it looks correct, type `apply` to save it." + +### COMMAND: apply +**Triggers:** "apply", "yes", "save", "confirm" +**Action:** +1. **Write:** Use `run_shell_command` to overwrite the file with the resolved content. +2. **Verify:** Execute `python3 git_tools.py verify `. +3. **Report:** Report the status ("Syntax Valid" or "Error"). +4. **Guidance Example:** + - If valid: "Syntax verified. Please run `git add ` manually to mark it resolved, then type `scan` to check for others." + - If error: "Syntax error detected. Shall I try to fix it?" + +### COMMAND: help +**Triggers:** "help", "info", "commands" +**Action:** +1. List the available commands (`scan`, `resolve`, `apply`). +2. Explain the workflow briefly. + +--- + +## IV. RESOLUTION LOGIC & STRATEGY + +You must use your understanding of programming logic to merge the files. Do not rely on git markers blindly. + +### 1. Semantic Intent Analysis +- Read the commit messages in the `context` object to understand *why* changes were made on each branch. +- **Structural vs. Functional:** Distinguish between changes that alter code structure (renaming, moving functions) and changes that alter behavior (new logic, new values). +- **Adaptation:** If one branch changes the structure (e.g., renames a variable) and the other modifies the logic of that same variable, you must apply the new logic to the new name. + +### 2. Logic Synthesis +- **Preserve Intent:** Your goal is to produce code that satisfies the requirements of **both** branches simultaneously. +- **Additive Changes:** If both branches add new constraints or conditions to the same block of code, attempt to combine them (Logical Union) unless they are explicitly mutually exclusive. +- **Conflict Precedence:** If two branches change the exact same value to different things (e.g., a timeout setting), look for clues in the commit message (e.g., "Updated policy") to decide which value supersedes the other. + +### 3. Code Integrity +- **Imports:** Ensure the final file includes all necessary imports from both versions. +- **Syntax:** The final output must be valid code with no `<<<<<<<` markers remaining. \ No newline at end of file diff --git a/llm-git-conflict-resolve/solution_templates/solution_1.md b/llm-git-conflict-resolve/solution_templates/solution_1.md new file mode 100644 index 00000000..eb67d716 --- /dev/null +++ b/llm-git-conflict-resolve/solution_templates/solution_1.md @@ -0,0 +1,128 @@ +# Git Merge Conflict Prompt for AI Agents + +This project defines a skill for the Claude Code Agent, designed to detect and resolve Git merge conflicts. The skill provides clear instructions, well‑defined procedures, and auxiliary tools to help the agent interpret files containing conflicts and generate a correct final version without conflict markers. + +## Objective + +The goal of the skill is to provide a complete set of instructions enabling an AI agent to: + +- Detect conflicts in files. +- Identify the structure of Git markers (`<<<<<<<`, `=======`, `>>>>>>>`). +- Extract the conflicting sections. +- Analyze differences between HEAD and branch versions. +- Apply various merge strategies (automatic, HEAD‑first, branch‑first, semantic). +- Call auxiliary Python code for more advanced analysis. +- Generate a coherent final resolution. +- Rewrite the final file without conflict markers. + +The agent **does not use real Git commands**. All operations are based exclusively on text processing according to the instructions in this skill. + +--- + +# Skill Contents + +The skill consists of three main components: the logic file (`skill.md`), the auxiliary script (`merge_utils.py`), and the usage documentation (`usage.md`). + +## 1. `skill.md` – Main Instructions + +This file defines the agent’s behavior and the rules it must follow when resolving conflicts. + +### What it contains + +- Description of the skill’s purpose. +- Explanation of mandatory operational steps. +- Clear definition of how to detect and extract conflicts. +- Rules for analyzing and applying merge strategies. +- Instructions on how to use the auxiliary Python code. +- Sample inputs and outputs to guide the agent. + +### Operational steps + +1. Identify conflict markers: + ``` + <<<<<<< HEAD + ... + ======= + ... + >>>>>>> branch + ``` +2. Extract the two sections into this structure: + ```json + { + "HEAD": "...", + "branch": "..." + } + ``` +3. Analyze the differences between the two sections. +4. Apply a merge strategy based on instructions and context. +5. Generate a final resolved version. +6. If necessary, call the Python script (`merge_utils.py`) for: + - conflict detection, + - advanced comparisons, + - semantic analysis. +7. Interpret the JSON output returned by the script. +8. Reconstruct the final file without conflict markers. + +### Documented merge strategies + +- **Automatic strategy**: if one version is contained in the other. +- **HEAD‑first strategy**: keep the HEAD version. +- **Branch‑first strategy**: keep the branch version. +- **Semantic merge**: + - reconstruct JSON, + - combine functions in code when changes are not conflicting. +- **Assisted merge**: the agent asks the user for explicit selection. + +### Examples + +The skill includes examples of conflicts and their correct resolutions so that the agent understands the expected format. + +--- + +## 2. `merge_utils.py` – Auxiliary Python Code + +This script is used for operations that are more efficient or safer when executed as local Python code. The agent may explicitly call it during the merge process. + +### Possible functionalities + +- `detect_conflicts(file_text)` identifies all conflicting sections in a file and returns a JSON structure. +- `three_way_merge(base, ours, theirs)` implements a three‑way merge. +- `ast_merge_python(ours, theirs)` performs a semantic merge of Python functions. +- `json_merge(ours, theirs)` safely combines JSON structures. +- `line_similarity(a, b)` returns a similarity score between lines for automated decisions. + +### Recommended output format + +```json +{ + "conflicts": [ + { + "start_line": 42, + "end_line": 68, + "HEAD": "...", + "branch": "...", + "type": "text" + } + ] +} +``` + +--- + +## 3. `usage.md` – Usage Documentation + +The `usage.md` file explains the correct way to use the skill, for both the agent and the user. + +### Contents + +- Instructions on how to call the Python script. +- Accepted input formats. +- How to interpret output. +- Complete examples of usage. +- Conventions between agent and script (CLI arguments, JSON structures, etc.). + +--- + +# Conclusion + +The skill provides a complete methodology for resolving Git merge conflicts without using Git directly. The documentation in `skill.md` serves as the operational guide for the agent, `merge_utils.py` provides advanced technical support, and `usage.md` clarifies how to interact with the skill. This set of files enables the agent to efficiently detect, interpret, and combine conflicting sections, producing a clean and coherent final version. diff --git a/llm-git-conflict-resolve/solution_templates/solution_2.md b/llm-git-conflict-resolve/solution_templates/solution_2.md new file mode 100644 index 00000000..cf801a6d --- /dev/null +++ b/llm-git-conflict-resolve/solution_templates/solution_2.md @@ -0,0 +1,55 @@ +# Git Merge Conflict Resolution Skill for AI Agents + +This repository contains a modular skill designed to enable AI agents (specifically within the Claude Code environment) to autonomously and accurately resolve git merge conflicts. + +While Large Language Models are proficient at writing code, they often struggle with the syntax of standard git merge markers (`<<<<<<<`, `=======`, `>>>>>>>`) due to a lack of context regarding the conflicting branches. This project bridges that gap by providing the agent with executable tools to retrieve the full history of the conflict (Base, Local, Remote) and a strict set of operational guidelines. + +## Architecture Overview + +The solution relies on a "Tool-Use" pattern where the agent acts not just as a text processor but as an orchestrator. It uses local Python scripts to interact with the Git CLI, processes the data, and applies resolution logic based on a predefined educational context. + +## Repository Structure & File Descriptions + +To implement this skill effectively, the project requires the following file structure. Each file serves a specific role in the agent's decision-making loop. + +### 1. `instructions.md` (The Educational Layer) +This file acts as the system prompt or "knowledge base" for the agent. It dictates the behavior and decision-making process. It does not contain code to be executed, but rather the logic the agent must follow. + +* **Purpose:** Teaches the agent the "Algorithm of Resolution." +* **Key Contents:** + * **Step-by-Step Workflow:** Instructions to identify conflicts, fetch raw data, analyze intent, and apply fixes. + * **Conflict Strategies:** Rules for handling specific scenarios (e.g., "If *Local* changes variable names and *Remote* changes logic, keep both"). + * **Import Handling:** Specific instructions to perform a union of imports rather than overwriting them. + * **Fallbacks:** Directives on what to do when code intent is ambiguous (e.g., defaulting to HEAD and adding a TODO comment). + +### 2. `git_tools.py` (The Execution Layer) +This Python script serves as the bridge between the AI agent and the local Git repository. The agent calls functions within this file to gather factual data about the state of the codebase. + +* **Purpose:** Provides deterministic, structured data to the LLM. +* **Key Functions:** + * `list_conflicted_files()`: Parses `git status --porcelain` to identify files requiring attention. + * `get_three_way_diff(filepath)`: Uses `git show` to extract the three versions of the truth: + * **:1 (Base):** The common ancestor. + * **:2 (Ours):** The local changes (HEAD). + * **:3 (Theirs):** The incoming changes. + * `validate_syntax(filepath)`: A utility to run language-specific linters (e.g., `ast` for Python) to ensure the resolved code is syntactically valid before staging. + +### 3. `resolution_template.md` (Optional) +A template file used by the agent to structure its reasoning before editing the code. + +* **Purpose:** Forces the agent to output a "Chain of Thought" before writing code. +* **Structure:** + * Conflict Summary. + * Detected Intent (Local vs. Remote). + * Proposed Resolution Strategy. + +## Operational Workflow + +When the agent is tasked with fixing a merge conflict, the expected execution flow is: + +1. **Context Loading:** The agent reads `instructions.md` to understand its role and constraints. +2. **Discovery:** The agent executes `python git_tools.py --list` to find the target files. +3. **Data Extraction:** For every conflict, the agent executes `python git_tools.py --extract `. It receives a structured object containing the Base, Ours, and Theirs content. +4. **Logic Synthesis:** The agent compares the three versions. Instead of guessing based on conflict markers, it reconstructs the valid code path based on the logic defined in the instructions. +5. **Application:** The agent rewrites the file content locally. +6. **Verification:** The agent executes `python git_tools.py --verify ` to catch syntax errors. \ No newline at end of file diff --git a/llm-git-conflict-resolve/solution_templates/solution_3.md b/llm-git-conflict-resolve/solution_templates/solution_3.md new file mode 100644 index 00000000..6b01a1e9 --- /dev/null +++ b/llm-git-conflict-resolve/solution_templates/solution_3.md @@ -0,0 +1,119 @@ +# Git Merge Conflict Resolution Skill - Solution Design + +## Core Philosophy + +This skill treats merge conflict resolution as a **semantic understanding problem** rather than text manipulation. The agent reconstructs the complete 3-way evolution (Base → Ours, Base → Theirs) to understand *why* conflicts occurred, enabling intelligent reconciliation based on developer intent rather than pattern-matching on conflict markers. + +## Approach + +**Context Over Heuristics**: Extract full 3-way diffs, analyze commit messages, examine dependencies, and make decisions based on semantic code understanding. + +**Progressive Resolution**: Address conflicts by difficulty—trivial (whitespace) → structural (imports) → logical (algorithms)—auto-resolving simple cases while escalating complex ones. + +**Safety Through Validation**: Multi-layer verification (syntax, semantics, integration) with automatic backups before any modifications. + +## Skill Structure + +``` +git-merge-conflict-skill/ +├── instructions/ +│ ├── 01-workflow.md # Detection, prioritization, backup creation +│ ├── 02-context-extraction.md # How to retrieve 3-way diffs and commit history +│ ├── 03-resolution-strategies.md # Decision trees for each conflict type +│ ├── 04-validation.md # Post-resolution verification protocol +│ └── 05-escalation.md # When and how to request human help +│ +└── tools/ + ├── conflict_extractor.py # Extract 3-way diffs and parse conflict markers + ├── semantic_analyzer.py # Analyze dependencies and infer intent + ├── conflict_categorizer.py # Classify conflict types automatically + ├── resolution_validator.py # Verify syntax and semantic correctness + └── git_context.py # Fetch commit history and branch metadata +``` + +### Instructions Layer (Markdown) + +**Purpose**: Educate the agent on resolution logic—the "what to do" without executable code. + +**01-workflow.md**: Teaches initial conflict detection, how to scan for conflicts, create backups, and prioritize resolution order (simple first). + +**02-context-extraction.md**: Guides the agent through retrieving Base/Ours/Theirs versions, fetching commit messages from both branches, and understanding author intent through git blame. + +**03-resolution-strategies.md**: Core decision logic organized by conflict type: +- **Imports**: Union merge, deduplicate, sort alphabetically +- **Whitespace**: Auto-resolve with project formatter +- **Renames**: Detect pattern, apply rename everywhere, keep other side's logic +- **Function signatures**: Check compatibility, merge if safe, escalate if breaking +- **Logic divergence**: Compare intents (bugfix vs feature), attempt combination or escalate with analysis +- **Refactoring**: Accept new structure, apply other side's changes to relocated code + +**04-validation.md**: Multi-stage verification—syntax check (must pass), semantic check (undefined vars, type errors), integration check (works with surrounding code), plus test recommendations. + +**05-escalation.md**: Clear criteria for requesting human help—ambiguous intent, data loss risk, test conflicts, complex dependencies. Defines escalation report format with detailed analysis and resolution options. + +### Tools Layer (Python) + +**Purpose**: Provide deterministic, structured data to the agent—the "how to fetch" without decision logic. + +**conflict_extractor.py**: +- Scans repository using `git status --porcelain` +- Extracts 3-way diff via git stages (`:1` base, `:2` ours, `:3` theirs) +- Parses conflict markers, returns structured blocks with surrounding context + +**semantic_analyzer.py**: +- Maps code dependencies (what variables/functions are used) +- Detects rename patterns by comparing identifiers across versions +- Infers intent by analyzing commit messages and code changes +- Validates that resolved code satisfies its dependencies + +**conflict_categorizer.py**: +- Automatically classifies conflicts (IMPORT, LOGIC, REFACTOR, etc.) +- Estimates difficulty (EASY, MEDIUM, HARD, ESCALATE) +- Provides initial assessment to guide strategy selection + +**resolution_validator.py**: +- Language-specific syntax checking (AST parsing for Python, etc.) +- Semantic validation (undefined references, type mismatches) +- Runs project linters +- Suggests relevant tests based on changed code + +**git_context.py**: +- Fetches commit messages that modified conflicted regions +- Finds merge base (common ancestor commit) +- Retrieves author info for escalation context +- Creates backup branches before resolution + +## Resolution Workflow + +``` +DETECT → EXTRACT → CATEGORIZE → STRATEGIZE → RESOLVE → VALIDATE → COMMIT/ESCALATE +``` + +**For each conflict:** + +1. **Extract Context**: Get 3-way diff, commit history, dependencies +2. **Categorize**: Classify type and difficulty using categorizer tool +3. **Select Strategy**: Match to decision tree in instructions +4. **Apply Resolution**: Generate resolved code based on strategy +5. **Validate**: Syntax → Semantics → Integration (must pass all) +6. **Finalize**: Stage if valid, escalate with detailed report if not + +## Key Innovations + +**Intent-Driven Resolution**: Analyzes commit messages + code semantics to understand the *goal* of each change, enabling intelligent merging of complementary features. + +**Complete Context**: 3-way diff reveals full story (original → how each side changed → why), eliminating guesswork from conflict markers alone. + +**Explicit Boundaries**: Clear escalation criteria prevent incorrect auto-resolutions while maximizing safe automation. + +**Semantic Validation**: Beyond syntax, verifies resolved code makes semantic sense—no undefined variables, consistent types, satisfied dependencies. + +**Progressive Complexity**: Sorts conflicts simple → complex, builds confidence on easy cases, bails early if complexity exceeds capabilities. + +## Success Criteria + +**Target auto-resolution rates**: 95% for trivial conflicts (imports, whitespace), 60% for structural (renames, refactors), 30% for logic conflicts. + +**Quality**: Zero syntax errors through validation. <1% semantic errors through multi-layer checking. Clear escalation reports when human input needed. + +**Safety-first**: Always backup before changes. Never commit invalid code. Escalate with detailed analysis when uncertain. \ No newline at end of file diff --git a/llm-git-conflict-resolve/solution_templates/solutions_comparison.md b/llm-git-conflict-resolve/solution_templates/solutions_comparison.md new file mode 100644 index 00000000..6556d0b0 --- /dev/null +++ b/llm-git-conflict-resolve/solution_templates/solutions_comparison.md @@ -0,0 +1,28 @@ +# Comparative Analysis: AI Git Merge Skill Architectures + +This document evaluates the 3 strategies for building an Claude skill to resolve Git merge conflicts, ranging from text-based processing to deep semantic analysis. + + + +| Criterion | Solution 1: "The Text Processor" | Solution 2: "The Modular Architect" | Solution 3: "The Semantic Expert" | +| :--- | :--- | :--- | :--- | +| **Core Philosophy** | **Text Manipulation**. Operates exclusively on text processing without executing real Git commands. | **Tool Orchestration**. Acts as a bridge between the LLM and Git CLI to fetch deterministic data. | **Semantic Understanding**. Focuses on *intent*, context, and progressive resolution (simple → complex). | +| **Source of Truth** | **Conflict Markers**. Parses `<<<<<<<` and `>>>>>>>` from file text. | **Git History (3-Way)**. Uses `git show` to extract Base, Ours, and Theirs versions. | **Rich Context**. Combines 3-Way Diff + Commit Messages + Dependency Graphs + Git Blame. | +| **Architecture** | **Simple Scripting**. `skill.md` (rules) + `merge_utils.py` (helper functions). | **Modular Tooling**. `instructions.md` (logic) + `git_tools.py` (execution) + `template`. | **Granular Micro-Services**. Split instructions (Workflow, Context, Strategy) & specialized tools (Extractor, Analyzer, Validator). | +| **Resolution Logic** | **Pattern Matching**. Applies strategies (Head/Branch first) based on text structure. | **Standard 3-Way**. Reconstructs code based on the "Base" version and divergent changes. | **Intent-Driven**. Analyzes *why* code changed (e.g., Refactor vs. Feature) using commit history and semantics. | +| **Validation** | **Basic**. Optional Python script helper. | **Syntax Only**. Runs linters (e.g., AST, eslint) before staging. | **Multi-Layer**. Syntax + Semantic (undefined vars) + Integration checks + Escalation reports. | +| **Complexity** | **Low**. Easy to implement, high risk of error due to lack of context. | **Medium**. Balanced approach, industry standard for automation. | **High**. Complex setup requiring dependency analysis and conflict categorization logic. | + +--- + +## Final Recommendation: The "Semantic Architect" Hybrid + +While **Solution 2** offers the cleanest structural foundation, **Solution 3** offers the necessary intelligence to handle real-world software engineering. **Solution 1** is not recommended for production as it lacks "Real Git" access, making it prone to errors. + +The optimal approach is to **upgrade the architecture of Solution 2 with the intelligence of Solution 3**: + +1. **Adopt the Infrastructure of Solution 2:** Keep the setup simple with a single robust Python interface (`git_tools.py`) rather than five separate micro-scripts, to maintain agent speed and reduce token usage. +2. **Inject the Logic of Solution 3:** + * **Context:** Enhance `git_tools.py` to fetch **Commit Messages** (from Solution 3), not just code diffs. The agent needs to know *why* a change happened. + * **Categorization:** Adopt the **"Progressive Resolution"** workflow from Solution 3. Teach the agent to identify and solve "Trivial" conflicts (whitespace/imports) first, before attempting "Logical" conflicts. + * **Safety:** Implement the **Backup & Escalation** protocol from Solution 3. If the agent cannot determine intent, it must stop and generate a report rather than guessing. \ No newline at end of file diff --git a/multyLanguageImplementation/get_tools.py b/multyLanguageImplementation/get_tools.py new file mode 100644 index 00000000..4bffb28f --- /dev/null +++ b/multyLanguageImplementation/get_tools.py @@ -0,0 +1,139 @@ +import sys +import argparse +import subprocess +import json +import os + +# Import the new multi-language syntax validator +from syntax_validators import verify_syntax as validate_syntax_multi_lang + +def run_git_command(command): + """Executes a git command and returns the output as a string.""" + try: + result = subprocess.check_output( + command, + stderr=subprocess.STDOUT, + shell=True + ) + return result.decode('utf-8').strip() + except subprocess.CalledProcessError as e: + # Return None to signal that, for example, the file does not exist in that version + return None + +def list_conflicted_files(): + """Identifies files marked as conflicted.""" + # --porcelain provides a stable format for parsing + output = run_git_command("git status --porcelain") + if not output: + return [] + + conflicted_files = [] + for line in output.split('\n'): + # Conflicts are usually marked with 'UU', 'AA', 'UD', etc. + # The first 2 characters indicate the status + status = line[:2] + filepath = line[3:].strip() + + # Simplified filter: if both sides modified (U) or added (A) + if 'U' in status or 'A' in status: + conflicted_files.append({ + "filepath": filepath, + "status": status + }) + + return conflicted_files + +def get_file_content_at_stage(filepath, stage): + """ + Extracts file content at a specific git stage. + Stage 1 = Base (Ancestor) + Stage 2 = Ours (Local/HEAD) + Stage 3 = Theirs (Remote/MERGE_HEAD) + """ + # git show :: + content = run_git_command(f"git show :{stage}:{filepath}") + return content if content is not None else "" + +def get_commit_context(filepath): + """ + Extracts commit messages to understand semantic intent (Solution 3). + """ + # HEAD is the current branch (Local) + local_msg = run_git_command(f"git log -1 --pretty=%B HEAD -- {filepath}") + + # MERGE_HEAD is the incoming branch (Remote). + # It might be null if we are not in a standard merge, but we handle the case. + remote_msg = run_git_command(f"git log -1 --pretty=%B MERGE_HEAD -- {filepath}") + + return { + "local_intent": local_msg.strip() if local_msg else "Unknown (Manual changes or no commit msg)", + "remote_intent": remote_msg.strip() if remote_msg else "Unknown (No MERGE_HEAD found)" + } + +def verify_syntax(filepath): + """ + Verifies file syntax using the multi-language validator. + Now supports: Python, JavaScript, TypeScript, JSON, Go, Rust, and more. + + Falls back to basic file readability check for unsupported types. + """ + if not os.path.exists(filepath): + return {"status": "error", "message": "File not found"} + + # Delegate to the multi-language validator + return validate_syntax_multi_lang(filepath) + +def main(): + parser = argparse.ArgumentParser(description="Git Merge Conflict Tool for AI Agents") + subparsers = parser.add_subparsers(dest="command", help="Available commands") + + # --- Command: list --- + subparsers.add_parser("list", help="List conflicted files") + + # --- Command: extract --- + extract_parser = subparsers.add_parser("extract", help="Extract content and context") + extract_parser.add_argument("filepath", type=str, help="Path to the conflicted file") + + # --- Command: verify --- + verify_parser = subparsers.add_parser("verify", help="Verify syntax") + verify_parser.add_argument("filepath", type=str, help="Path to the file to verify") + + args = parser.parse_args() + + # Command routing + if args.command == "list": + result = list_conflicted_files() + print(json.dumps(result, indent=2)) + + elif args.command == "extract": + filepath = args.filepath + + # 1. Extract Diff (Code) + diff_data = { + "base": get_file_content_at_stage(filepath, 1), + "local": get_file_content_at_stage(filepath, 2), + "remote": get_file_content_at_stage(filepath, 3) + } + + # 2. Extract Context (Intent) + context_data = get_commit_context(filepath) + + # 3. Build the complete payload + full_payload = { + "file": filepath, + "diff": diff_data, + "context": context_data, + "note": "Use 'context' to determine intent, then merge 'diff' accordingly." + } + print(json.dumps(full_payload, indent=2)) + + elif args.command == "verify": + result = verify_syntax(args.filepath) + print(json.dumps(result, indent=2)) + + else: + # If no command is provided + parser.print_help() + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/multyLanguageImplementation/syntax_validators.py b/multyLanguageImplementation/syntax_validators.py new file mode 100644 index 00000000..078fe181 --- /dev/null +++ b/multyLanguageImplementation/syntax_validators.py @@ -0,0 +1,467 @@ +""" +Multi-language syntax validation module for git merge conflict resolution. +This module provides syntax checking for various programming languages without +requiring external dependencies beyond standard library where possible. +""" + +import os +import ast +import json +import subprocess +import tempfile +from typing import Dict, Optional + + +class SyntaxValidator: + """Base class for language-specific syntax validators.""" + + def __init__(self): + self.supported_extensions = [] + + def validate(self, filepath: str) -> Dict[str, str]: + """ + Validates syntax of a file. + + Returns: + Dict with keys: 'status' ('valid' or 'error'), 'message', 'details' (optional) + """ + raise NotImplementedError("Subclasses must implement validate()") + + +class PythonValidator(SyntaxValidator): + """Validates Python syntax using AST.""" + + def __init__(self): + super().__init__() + self.supported_extensions = ['.py'] + + def validate(self, filepath: str) -> Dict[str, str]: + try: + with open(filepath, 'r', encoding='utf-8') as f: + source = f.read() + ast.parse(source) + return { + "status": "valid", + "message": "Python syntax check passed.", + "language": "python" + } + except SyntaxError as e: + return { + "status": "error", + "message": f"Syntax Error on line {e.lineno}: {e.msg}", + "details": str(e), + "language": "python" + } + except Exception as e: + return { + "status": "error", + "message": f"Unexpected error: {str(e)}", + "language": "python" + } + + +class JavaScriptValidator(SyntaxValidator): + """Validates JavaScript/TypeScript syntax using Node.js.""" + + def __init__(self): + super().__init__() + self.supported_extensions = ['.js', '.jsx', '.mjs'] + self.has_node = self._check_node_available() + + def _check_node_available(self) -> bool: + """Check if Node.js is installed.""" + try: + subprocess.run(['node', '--version'], + capture_output=True, + check=True, + timeout=2) + return True + except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired): + return False + + def validate(self, filepath: str) -> Dict[str, str]: + if not self.has_node: + return { + "status": "skipped", + "message": "Node.js not found. Install Node.js for JavaScript validation.", + "language": "javascript" + } + + try: + # Use node --check for syntax validation + result = subprocess.run( + ['node', '--check', filepath], + capture_output=True, + text=True, + timeout=5 + ) + + if result.returncode == 0: + return { + "status": "valid", + "message": "JavaScript syntax check passed.", + "language": "javascript" + } + else: + return { + "status": "error", + "message": "JavaScript syntax error detected.", + "details": result.stderr, + "language": "javascript" + } + except subprocess.TimeoutExpired: + return { + "status": "error", + "message": "Syntax check timed out.", + "language": "javascript" + } + except Exception as e: + return { + "status": "error", + "message": f"Validation failed: {str(e)}", + "language": "javascript" + } + + +class TypeScriptValidator(SyntaxValidator): + """Validates TypeScript syntax using tsc.""" + + def __init__(self): + super().__init__() + self.supported_extensions = ['.ts', '.tsx'] + self.has_tsc = self._check_tsc_available() + + def _check_tsc_available(self) -> bool: + """Check if TypeScript compiler is installed.""" + try: + subprocess.run(['tsc', '--version'], + capture_output=True, + check=True, + timeout=2) + return True + except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired): + return False + + def validate(self, filepath: str) -> Dict[str, str]: + if not self.has_tsc: + return { + "status": "skipped", + "message": "TypeScript compiler (tsc) not found. Install with: npm install -g typescript", + "language": "typescript" + } + + try: + # Use tsc --noEmit for syntax check without generating output + result = subprocess.run( + ['tsc', '--noEmit', '--skipLibCheck', filepath], + capture_output=True, + text=True, + timeout=10 + ) + + if result.returncode == 0: + return { + "status": "valid", + "message": "TypeScript syntax check passed.", + "language": "typescript" + } + else: + return { + "status": "error", + "message": "TypeScript syntax error detected.", + "details": result.stderr, + "language": "typescript" + } + except subprocess.TimeoutExpired: + return { + "status": "error", + "message": "Syntax check timed out.", + "language": "typescript" + } + except Exception as e: + return { + "status": "error", + "message": f"Validation failed: {str(e)}", + "language": "typescript" + } + + +class JSONValidator(SyntaxValidator): + """Validates JSON syntax.""" + + def __init__(self): + super().__init__() + self.supported_extensions = ['.json'] + + def validate(self, filepath: str) -> Dict[str, str]: + try: + with open(filepath, 'r', encoding='utf-8') as f: + json.load(f) + return { + "status": "valid", + "message": "JSON syntax check passed.", + "language": "json" + } + except json.JSONDecodeError as e: + return { + "status": "error", + "message": f"JSON Error on line {e.lineno}, column {e.colno}: {e.msg}", + "details": str(e), + "language": "json" + } + except Exception as e: + return { + "status": "error", + "message": f"Unexpected error: {str(e)}", + "language": "json" + } + + +class GoValidator(SyntaxValidator): + """Validates Go syntax using go fmt.""" + + def __init__(self): + super().__init__() + self.supported_extensions = ['.go'] + self.has_go = self._check_go_available() + + def _check_go_available(self) -> bool: + """Check if Go is installed.""" + try: + subprocess.run(['go', 'version'], + capture_output=True, + check=True, + timeout=2) + return True + except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired): + return False + + def validate(self, filepath: str) -> Dict[str, str]: + if not self.has_go: + return { + "status": "skipped", + "message": "Go compiler not found. Install Go for validation.", + "language": "go" + } + + try: + # Use go fmt to check syntax + result = subprocess.run( + ['go', 'fmt', filepath], + capture_output=True, + text=True, + timeout=5 + ) + + # go fmt returns non-zero on syntax errors + if "syntax error" in result.stderr.lower(): + return { + "status": "error", + "message": "Go syntax error detected.", + "details": result.stderr, + "language": "go" + } + + return { + "status": "valid", + "message": "Go syntax check passed.", + "language": "go" + } + except subprocess.TimeoutExpired: + return { + "status": "error", + "message": "Syntax check timed out.", + "language": "go" + } + except Exception as e: + return { + "status": "error", + "message": f"Validation failed: {str(e)}", + "language": "go" + } + + +class RustValidator(SyntaxValidator): + """Validates Rust syntax using rustc.""" + + def __init__(self): + super().__init__() + self.supported_extensions = ['.rs'] + self.has_rustc = self._check_rustc_available() + + def _check_rustc_available(self) -> bool: + """Check if Rust compiler is installed.""" + try: + subprocess.run(['rustc', '--version'], + capture_output=True, + check=True, + timeout=2) + return True + except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired): + return False + + def validate(self, filepath: str) -> Dict[str, str]: + if not self.has_rustc: + return { + "status": "skipped", + "message": "Rust compiler (rustc) not found. Install Rust for validation.", + "language": "rust" + } + + try: + # Use rustc with --crate-type lib and output to temp dir + with tempfile.TemporaryDirectory() as tmpdir: + result = subprocess.run( + ['rustc', '--crate-type', 'lib', '--out-dir', tmpdir, filepath], + capture_output=True, + text=True, + timeout=10 + ) + + if result.returncode == 0: + return { + "status": "valid", + "message": "Rust syntax check passed.", + "language": "rust" + } + else: + return { + "status": "error", + "message": "Rust syntax error detected.", + "details": result.stderr, + "language": "rust" + } + except subprocess.TimeoutExpired: + return { + "status": "error", + "message": "Syntax check timed out.", + "language": "rust" + } + except Exception as e: + return { + "status": "error", + "message": f"Validation failed: {str(e)}", + "language": "rust" + } + + +class GenericValidator(SyntaxValidator): + """Fallback validator for unsupported file types.""" + + def __init__(self): + super().__init__() + self.supported_extensions = [] # Matches any extension + + def validate(self, filepath: str) -> Dict[str, str]: + _, ext = os.path.splitext(filepath) + + # Check if file exists and is readable + if not os.path.exists(filepath): + return { + "status": "error", + "message": "File not found", + "language": "unknown" + } + + try: + with open(filepath, 'r', encoding='utf-8') as f: + f.read() + return { + "status": "valid", + "message": f"No linter configured for {ext}. Basic readability check passed.", + "language": "unknown" + } + except UnicodeDecodeError: + return { + "status": "warning", + "message": f"File appears to be binary ({ext}). Skipping syntax check.", + "language": "binary" + } + except Exception as e: + return { + "status": "error", + "message": f"File read error: {str(e)}", + "language": "unknown" + } + + +class ValidatorRegistry: + """Registry that maps file extensions to appropriate validators.""" + + def __init__(self): + self.validators = [ + PythonValidator(), + JavaScriptValidator(), + TypeScriptValidator(), + JSONValidator(), + GoValidator(), + RustValidator(), + ] + self.generic_validator = GenericValidator() + + # Build extension map + self.extension_map = {} + for validator in self.validators: + for ext in validator.supported_extensions: + self.extension_map[ext] = validator + + def get_validator(self, filepath: str) -> SyntaxValidator: + """Returns the appropriate validator for a given file.""" + _, ext = os.path.splitext(filepath) + return self.extension_map.get(ext, self.generic_validator) + + def validate_file(self, filepath: str) -> Dict[str, str]: + """Validates a file using the appropriate validator.""" + validator = self.get_validator(filepath) + return validator.validate(filepath) + + def list_supported_languages(self) -> list: + """Returns list of supported languages with their extensions.""" + languages = [] + for validator in self.validators: + if validator.supported_extensions: + lang = validator.validate("") # Get language name + languages.append({ + "language": lang.get("language", "unknown"), + "extensions": validator.supported_extensions + }) + return languages + + +# Singleton instance +_registry = ValidatorRegistry() + + +def verify_syntax(filepath: str) -> Dict[str, str]: + """ + Main entry point for syntax verification. + This function should be called from get_tools.py + + Args: + filepath: Path to the file to verify + + Returns: + Dictionary with validation results + """ + return _registry.validate_file(filepath) + + +def list_supported_languages() -> list: + """Returns list of all supported languages.""" + return _registry.list_supported_languages() + + +if __name__ == "__main__": + # CLI for testing + import sys + + if len(sys.argv) < 2: + print("Usage: python syntax_validators.py ") + print("\nSupported languages:") + for lang_info in list_supported_languages(): + print(f" {lang_info['language']}: {', '.join(lang_info['extensions'])}") + sys.exit(1) + + filepath = sys.argv[1] + result = verify_syntax(filepath) + print(json.dumps(result, indent=2)) \ No newline at end of file