From a1fd0e9370b6e9c1b0b7ba4dcf962cac73d4097d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Dec 2025 03:11:55 +0000 Subject: [PATCH] Create comprehensive GitHub issue templates and feature issues Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/bug_report.yml | 94 ++++ .github/ISSUE_TEMPLATE/config.yml | 11 + .github/ISSUE_TEMPLATE/documentation.yml | 61 +++ .github/ISSUE_TEMPLATE/feature_request.yml | 90 ++++ .github/issues/01-project-specification.md | 136 +++++ .github/issues/02-file-io-git-integration.md | 158 ++++++ .../03-semantic-merge-structured-files.md | 319 ++++++++++++ .github/issues/04-ast-based-merging.md | 451 +++++++++++++++++ .github/issues/05-sdg-analysis.md | 408 +++++++++++++++ .github/issues/06-multi-platform-support.md | 429 ++++++++++++++++ .github/issues/07-core-ui-components.md | 357 +++++++++++++ .github/issues/08-ai-assisted-merging.md | 388 ++++++++++++++ .../issues/09-conflict-resolution-actions.md | 476 ++++++++++++++++++ .github/issues/10-testing-quality.md | 434 ++++++++++++++++ .github/issues/README.md | 179 +++++++ 15 files changed, 3991 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/issues/01-project-specification.md create mode 100644 .github/issues/02-file-io-git-integration.md create mode 100644 .github/issues/03-semantic-merge-structured-files.md create mode 100644 .github/issues/04-ast-based-merging.md create mode 100644 .github/issues/05-sdg-analysis.md create mode 100644 .github/issues/06-multi-platform-support.md create mode 100644 .github/issues/07-core-ui-components.md create mode 100644 .github/issues/08-ai-assisted-merging.md create mode 100644 .github/issues/09-conflict-resolution-actions.md create mode 100644 .github/issues/10-testing-quality.md create mode 100644 .github/issues/README.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..db3a1fc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,94 @@ +name: Bug Report +description: Report a bug or issue with WizardMerge +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please fill out the sections below to help us fix the issue. + + - type: dropdown + id: component + attributes: + label: Component + description: Which component is affected? + options: + - Backend (C++) + - Frontend - Qt6 Desktop + - Frontend - Next.js Web + - Frontend - CLI + - Build System + - Documentation + - Other + validations: + required: true + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: Describe the issue you encountered... + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Go to '...' + 2. Click on '...' + 3. Execute command '...' + 4. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: Describe what you expected... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? + placeholder: Describe what actually happened... + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Information about your environment + placeholder: | + - OS: [e.g., Ubuntu 22.04, Windows 11, macOS 13] + - WizardMerge Version: [e.g., main branch, v1.0.0] + - Compiler: [e.g., GCC 11, Clang 14, MSVC 2022] + - Qt Version: [if applicable] + - Node/bun Version: [if applicable] + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs and Error Messages + description: Please provide any relevant logs or error messages + placeholder: Paste logs here... + render: shell + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context about the problem here + placeholder: Any additional information... diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..de959b3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: πŸ’¬ Discussions + url: https://github.com/johndoe6345789/WizardMerge/discussions + about: Ask questions and discuss ideas with the community + - name: πŸ“š Documentation + url: https://github.com/johndoe6345789/WizardMerge#readme + about: Read the documentation to learn more about WizardMerge + - name: πŸ—ΊοΈ Roadmap + url: https://github.com/johndoe6345789/WizardMerge/blob/main/ROADMAP.md + about: View the project roadmap and planned features diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 0000000..9bc980b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,61 @@ +name: Documentation Improvement +description: Suggest improvements or report issues with documentation +title: "[Docs]: " +labels: ["documentation", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for helping improve our documentation! + + - type: dropdown + id: doc_type + attributes: + label: Documentation Type + description: What type of documentation needs improvement? + options: + - README + - API Documentation + - User Guide + - Developer Guide + - Build Instructions + - Architecture Documentation + - Code Comments + - Research Paper + - Other + validations: + required: true + + - type: input + id: location + attributes: + label: Documentation Location + description: Which file or section needs improvement? + placeholder: e.g., README.md, backend/README.md, docs/PAPER.md + validations: + required: true + + - type: textarea + id: issue + attributes: + label: Issue Description + description: What is unclear, incorrect, or missing in the documentation? + placeholder: Describe the documentation issue... + validations: + required: true + + - type: textarea + id: suggestion + attributes: + label: Suggested Improvement + description: How should the documentation be improved? + placeholder: Describe your suggestion... + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context about the documentation improvement + placeholder: Any additional information... diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..8e7ccd1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,90 @@ +name: Feature Request +description: Suggest an idea or new feature for WizardMerge +title: "[Feature]: " +labels: ["enhancement", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! Please describe your idea below. + + - type: dropdown + id: component + attributes: + label: Component + description: Which component would this feature affect? + options: + - Backend (C++) + - Frontend - Qt6 Desktop + - Frontend - Next.js Web + - Frontend - CLI + - Merge Algorithm + - Git Integration + - UI/UX + - Documentation + - Other + validations: + required: true + + - type: dropdown + id: phase + attributes: + label: Roadmap Phase + description: If applicable, which roadmap phase does this align with? + options: + - Phase 1 - Foundation + - Phase 2 - Intelligence & Usability + - Phase 3 - Advanced Features + - Not in current roadmap + validations: + required: false + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this feature solve? What is the motivation? + placeholder: Describe the problem or need... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see + placeholder: Describe your proposed solution... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Describe any alternative solutions or features you've considered + placeholder: What alternatives have you considered? + + - type: textarea + id: benefits + attributes: + label: Benefits + description: What are the benefits of this feature? + placeholder: | + - Better user experience + - Faster conflict resolution + - More accurate merging + - etc. + + - type: textarea + id: implementation + attributes: + label: Implementation Notes + description: If you have ideas about how to implement this, share them here + placeholder: Technical implementation details... + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context, mockups, or screenshots about the feature request + placeholder: Any additional information... diff --git a/.github/issues/01-project-specification.md b/.github/issues/01-project-specification.md new file mode 100644 index 0000000..4c610d7 --- /dev/null +++ b/.github/issues/01-project-specification.md @@ -0,0 +1,136 @@ +--- +title: "Project Specification: WizardMerge Core Architecture and Features" +labels: ["documentation", "project-spec", "high-priority"] +assignees: [] +--- + +## Overview + +This issue tracks the comprehensive project specification for WizardMerge - an intelligent merge conflict resolution tool based on research from The University of Hong Kong. + +## Core Mission + +WizardMerge aims to reduce merge conflict resolution time by 28.85% through intelligent algorithms that provide merge suggestions for over 70% of code blocks affected by conflicts, using dependency analysis at text and LLVM-IR levels. + +## Architecture Components + +### 1. Backend (C++) +- **Build System**: CMake + Ninja + Conan +- **Web Framework**: Drogon HTTP server +- **Core Features**: + - Three-way merge algorithm βœ… + - Conflict detection and auto-resolution βœ… + - HTTP API endpoints βœ… + - GitHub Pull Request integration βœ… + - GitLab Merge Request integration βœ… + - Git CLI integration for branch creation βœ… + +### 2. Frontend Options + +#### Qt6 Native Desktop (C++) +- **Framework**: Qt6 with QML +- **Platforms**: Linux, Windows, macOS +- **Features**: Native desktop UI, offline capability, high performance + +#### Next.js Web UI (TypeScript) +- **Runtime**: bun +- **Framework**: Next.js 14 +- **Features**: Web-based UI, real-time collaboration, cross-platform access + +#### CLI (C++) +- **Features**: Command-line interface, automation support, CI/CD integration +- **Use Cases**: Batch processing, scripting, terminal workflows + +### 3. Formal Verification +- **Specification**: TLA+ formal specification (spec/WizardMergeSpec.tla) +- **CI Integration**: Automated verification on every push +- **Coverage**: Syntax, module structure, invariants, temporal properties + +## Research Foundation + +Based on research achieving: +- 28.85% reduction in conflict resolution time +- Merge suggestions for >70% of conflicted code blocks +- Dependency analysis at text and LLVM-IR levels +- Tested on 227 conflicts across five large-scale projects + +See: `docs/PAPER.md` + +## Core Principles + +1. **Visual Clarity**: Show conflicts in a way that makes the problem immediately obvious +2. **Smart Assistance**: Provide intelligent suggestions while keeping humans in control +3. **Context Awareness**: Understand code structure and semantics, not just text diffs +4. **Workflow Integration**: Seamlessly fit into developers' existing Git workflows +5. **Safety First**: Make it hard to accidentally lose changes or break code + +## Current Implementation Status + +### Phase 1 (Foundation) - Partially Complete +- βœ… Three-way merge algorithm (base, ours, theirs) +- βœ… Conflict detection and marking +- βœ… Common auto-resolvable patterns (non-overlapping, identical, whitespace) +- βœ… Git CLI wrapper module for branch operations +- βœ… GitHub and GitLab PR/MR resolution via API +- ⏳ Support for different conflict markers +- ⏳ Line-level granularity with word-level highlighting +- ⏳ Git repository detection and conflict listing +- ⏳ File input/output with backup mechanism + +### Future Phases (See Roadmap) +- Phase 2: Intelligence & Usability (3-6 months) +- Phase 3: Advanced Features (6-12 months) + +## API Endpoints + +### POST /api/merge +Three-way merge for direct file content + +### POST /api/pr/resolve +Pull Request/Merge Request conflict resolution with branch creation support + +### Platform Support +- βœ… GitHub (via GitHub API v3) +- βœ… GitLab (via GitLab API) +- πŸ”œ Bitbucket (planned - Phase 2) +- πŸ”œ Azure DevOps (planned - Phase 2) +- πŸ”œ Gitea/Forgejo (planned - Phase 2) + +## Related Documentation + +- Main README: `README.md` +- Roadmap: `ROADMAP.md` +- Build Guide: `BUILD.md` +- Research Paper: `docs/PAPER.md` +- Git CLI Implementation: `GIT_CLI_IMPLEMENTATION.md` +- Backend README: `backend/README.md` + +## Success Metrics + +### Phase 1 (Current) +- βœ… Successfully resolve basic three-way merges +- βœ… Handle 90% of common conflict patterns +- βœ… Command-line integration working +- ⏳ 5 active users providing feedback + +## Tasks + +- [x] Define core architecture +- [x] Implement three-way merge algorithm +- [x] Add GitHub/GitLab PR integration +- [x] Add Git CLI wrapper +- [ ] Document API specification +- [ ] Create comprehensive user guide +- [ ] Define plugin API specification +- [ ] Document semantic merge algorithm design +- [ ] Document SDG analysis architecture + +## Related Issues + +- Phase 1 Features: #TBD +- Phase 2 Features: #TBD +- Phase 3 Features: #TBD + +--- + +**Note**: This is a living specification that will be updated as the project evolves. Please refer to the latest version in the repository. diff --git a/.github/issues/02-file-io-git-integration.md b/.github/issues/02-file-io-git-integration.md new file mode 100644 index 0000000..664482d --- /dev/null +++ b/.github/issues/02-file-io-git-integration.md @@ -0,0 +1,158 @@ +--- +title: "Phase 1.2: File Input/Output and Git Integration" +labels: ["enhancement", "phase-1", "git-integration", "high-priority"] +assignees: [] +milestone: "Phase 1 - Foundation" +--- + +## Overview + +Implement comprehensive file I/O and Git integration features to enable WizardMerge to work directly with Git repositories and conflicted files. + +## Related Roadmap Section + +Phase 1.2 and 1.5 from ROADMAP.md + +## Features to Implement + +### File Input/Output Module + +- [ ] Parse Git conflict markers from files (`<<<<<<<`, `=======`, `>>>>>>>`) +- [ ] Support for Mercurial conflict markers +- [ ] Load base, ours, and theirs versions from Git +- [ ] Save resolved merge results to files +- [ ] Support for directory-level conflict resolution +- [ ] Backup mechanism for safety (create `.backup` files before resolution) +- [ ] Handle file encodings (UTF-8, UTF-16, etc.) +- [ ] Validate file write permissions before attempting resolution + +**Deliverable**: `backend/src/io/` module with file handlers + +### Git Repository Integration + +- [ ] Detect when running in Git repository (check for `.git` directory) +- [ ] Read `.git/MERGE_HEAD` to identify active merge conflicts +- [ ] List all conflicted files in repository +- [ ] Get base, ours, theirs versions using Git commands: + - `git show :1:file` (base) + - `git show :2:file` (ours) + - `git show :3:file` (theirs) +- [ ] Mark files as resolved in Git index (`git add`) +- [ ] Support launching from command line: `wizardmerge [file]` +- [ ] Support launching with no arguments to resolve all conflicts in repo + +**Deliverable**: Enhanced `backend/src/git/` module and CLI enhancements + +## Technical Design + +### File Parser Architecture + +```cpp +class ConflictFileParser { + // Parse conflict markers and extract sections + ConflictSections parse(const std::string& file_content); + + // Detect conflict marker style (Git, Mercurial, etc.) + ConflictMarkerStyle detect_marker_style(const std::string& content); + + // Extract base/ours/theirs sections + std::vector extract_conflict_blocks(const std::string& content); +}; +``` + +### Git Integration Architecture + +```cpp +class GitRepository { + // Check if we're in a Git repository + bool is_git_repo(const std::string& path); + + // List conflicted files + std::vector list_conflicted_files(); + + // Get file version from Git index + std::string get_file_version(const std::string& file, GitStage stage); + + // Mark file as resolved + bool mark_resolved(const std::string& file); +}; +``` + +## Implementation Steps + +1. **Create file I/O module structure** + - Set up `backend/src/io/` directory + - Add CMake configuration + - Create header files + +2. **Implement conflict marker parser** + - Parse standard Git markers + - Support custom conflict marker labels + - Handle nested conflicts (edge case) + +3. **Implement Git integration** + - Repository detection + - Conflict file listing + - Index stage reading (`:1:`, `:2:`, `:3:`) + +4. **Add CLI enhancements** + - File path argument handling + - Directory scanning for conflicts + - Progress reporting for multiple files + +5. **Add safety features** + - Automatic backups before resolution + - Dry-run mode for testing + - Verification of resolved content + +6. **Testing** + - Unit tests for parser + - Integration tests with real Git repos + - Test various conflict scenarios + +## Acceptance Criteria + +- [ ] Can parse Git conflict markers from files +- [ ] Can load base/ours/theirs from Git index +- [ ] Can save resolved files +- [ ] Creates backups before modifying files +- [ ] CLI accepts file paths and resolves conflicts +- [ ] Works with conflicted directories +- [ ] All tests pass +- [ ] Documentation updated + +## Dependencies + +- Git CLI integration (already implemented) βœ… +- Three-way merge algorithm (already implemented) βœ… + +## Test Cases + +1. Parse simple conflict with standard markers +2. Parse multiple conflicts in same file +3. Parse conflict with custom labels +4. Read file versions from Git index +5. Save resolved file without corruption +6. Create and restore from backups +7. Handle binary file conflicts gracefully +8. Handle missing base version (add/add conflict) + +## Documentation Updates + +- [ ] Update README.md with file I/O usage +- [ ] Update CLI documentation +- [ ] Add examples to backend/README.md +- [ ] Document conflict marker formats supported + +## Priority + +**HIGH** - This is essential for Phase 1 completion and enables standalone operation without external tools. + +## Estimated Effort + +2-3 weeks + +## Related Issues + +- #TBD (Phase 1 completion tracking) +- #TBD (CLI enhancements) diff --git a/.github/issues/03-semantic-merge-structured-files.md b/.github/issues/03-semantic-merge-structured-files.md new file mode 100644 index 0000000..47d1395 --- /dev/null +++ b/.github/issues/03-semantic-merge-structured-files.md @@ -0,0 +1,319 @@ +--- +title: "Phase 2.1: Semantic Merge for Structured File Types (JSON, YAML, XML, Package Files)" +labels: ["enhancement", "phase-2", "semantic-merge", "high-priority"] +assignees: [] +milestone: "Phase 2 - Intelligence & Usability" +--- + +## Overview + +Implement intelligent, structure-aware merging for common structured file types. Instead of treating these files as plain text, understand their structure and merge at the semantic level. + +## Related Roadmap Section + +Phase 2.1 - Smart Conflict Resolution (Semantic merge for common file types) + +## Motivation + +Traditional text-based merging fails to understand the structure of JSON, YAML, XML, and package files. This leads to: +- Unnecessary conflicts in well-structured data +- Breaking valid syntax during merge +- Missing semantic relationships between changes +- Poor handling of reordered elements + +Semantic merging can reduce conflicts by 30-50% in structured files. + +## Features to Implement + +### JSON Merging + +- [ ] **Key-based merging**: Merge objects by key structure +- [ ] **Preserve nested objects**: Maintain hierarchy during merge +- [ ] **Smart array merging**: + - Detect ID fields (`id`, `_id`, `key`, etc.) + - Match array elements by ID when possible + - Handle insertions, deletions, and reordering +- [ ] **Structural vs. value changes**: Differentiate between structure modifications and value updates +- [ ] **Conflict detection**: Identify true semantic conflicts (e.g., same key, different values) + +**Example**: +```json +// Base +{"users": [{"id": 1, "name": "Alice"}]} + +// Ours +{"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]} + +// Theirs +{"users": [{"id": 1, "name": "Alice", "email": "alice@example.com"}]} + +// Merged (semantic) +{"users": [{"id": 1, "name": "Alice", "email": "alice@example.com"}, {"id": 2, "name": "Bob"}]} +``` + +### YAML Merging + +- [ ] **Hierarchy preservation**: Maintain indentation and structure +- [ ] **Comment preservation**: Keep comments associated with keys +- [ ] **Anchor and alias handling**: Preserve YAML anchors (`&`) and aliases (`*`) +- [ ] **Multi-document YAML**: Handle files with multiple YAML documents (`---` separators) +- [ ] **Schema-aware conflicts**: Detect conflicts based on YAML schema (if available) + +**Example**: +```yaml +# Base +config: + host: localhost + port: 8080 + +# Ours (add new key) +config: + host: localhost + port: 8080 + timeout: 30 + +# Theirs (change value) +config: + host: example.com # Updated host + port: 8080 + +# Merged +config: + host: example.com + port: 8080 + timeout: 30 +``` + +### Package File Merging + +Intelligent dependency merging for various ecosystems: + +#### package.json (npm) +- [ ] Merge dependencies by semver ranges +- [ ] Detect version conflicts (incompatible ranges) +- [ ] Preserve script order and structure +- [ ] Handle devDependencies, peerDependencies separately + +#### requirements.txt (pip) +- [ ] Detect version conflicts +- [ ] Merge inline comments +- [ ] Handle version specifiers (==, >=, ~=, etc.) + +#### go.mod +- [ ] Merge require directives +- [ ] Handle replace directives +- [ ] Resolve version conflicts using go.sum + +#### Cargo.toml (Rust) +- [ ] Merge dependencies table +- [ ] Handle feature flags +- [ ] Resolve version conflicts + +#### pom.xml (Maven) +- [ ] Merge dependencies +- [ ] Handle dependency management +- [ ] Resolve version conflicts + +**Common Features**: +- [ ] Detect breaking version upgrades +- [ ] Warn about incompatible version ranges +- [ ] Suggest conflict resolution based on semver + +### XML Merging + +- [ ] **Structure-aware**: Understand element hierarchy +- [ ] **DTD/Schema preservation**: Keep document type declarations +- [ ] **Attribute-based matching**: Match elements by `id`, `name`, or other attributes +- [ ] **Namespace handling**: Correctly handle XML namespaces +- [ ] **Comment preservation**: Maintain XML comments + +**Example**: +```xml + + + + + + + + + + + + + + + + + + + + + +``` + +## Technical Design + +### Architecture + +```cpp +// Abstract base class for semantic mergers +class SemanticMerger { +public: + virtual MergeResult merge( + const std::string& base, + const std::string& ours, + const std::string& theirs + ) = 0; + + virtual bool can_handle(const std::string& file_path) = 0; +}; + +// Implementations +class JSONMerger : public SemanticMerger { /* ... */ }; +class YAMLMerger : public SemanticMerger { /* ... */ }; +class XMLMerger : public SemanticMerger { /* ... */ }; +class PackageFileMerger : public SemanticMerger { /* ... */ }; +``` + +### Merger Registry + +```cpp +class SemanticMergerRegistry { + void register_merger(std::unique_ptr merger); + SemanticMerger* find_merger(const std::string& file_path); + MergeResult smart_merge(const std::string& file_path, /* ... */); +}; +``` + +### Integration with Three-Way Merge + +```cpp +// In three_way_merge.cpp +MergeResult merge_files(const std::string& base, /* ... */) { + // Try semantic merge first + auto semantic_merger = merger_registry.find_merger(file_path); + if (semantic_merger) { + auto result = semantic_merger->merge(base, ours, theirs); + if (result.success || result.has_semantic_conflicts) { + return result; + } + } + + // Fall back to text-based merge + return text_based_merge(base, ours, theirs); +} +``` + +## Implementation Steps + +1. **Set up semantic merge framework** + - Create `backend/src/semantic/` directory + - Define `SemanticMerger` interface + - Create merger registry + +2. **Implement JSON merger** + - Use JSON library (jsoncpp, nlohmann/json, or similar) + - Recursive object merging + - Array merging with ID detection + - Unit tests + +3. **Implement YAML merger** + - Use yaml-cpp library + - Preserve comments and anchors + - Handle multi-document files + - Unit tests + +4. **Implement XML merger** + - Use libxml2 or tinyxml2 + - Element matching by attributes + - Namespace handling + - Unit tests + +5. **Implement package file mergers** + - Detect file types by name + - Version comparison logic + - Conflict reporting + - Unit tests + +6. **Integration** + - Hook into main merge pipeline + - Add file type detection + - Update API to support semantic merging + - Integration tests + +7. **Documentation** + - User guide for semantic merging + - Examples for each file type + - API documentation + +## Libraries to Use + +- **JSON**: nlohmann/json (header-only, modern C++) +- **YAML**: yaml-cpp (Conan available) +- **XML**: tinyxml2 (Conan available) +- **Semver**: semver.c or custom implementation + +## Acceptance Criteria + +- [ ] JSON files merge at object/array level +- [ ] YAML files preserve structure and comments +- [ ] XML files merge by element attributes +- [ ] Package files detect version conflicts +- [ ] Falls back to text merge when semantic merge fails +- [ ] All unit tests pass (>90% coverage) +- [ ] Integration tests with real-world examples +- [ ] Performance: <100ms for files up to 10MB +- [ ] Documentation complete + +## Test Cases + +### JSON +1. Merge objects with non-overlapping keys +2. Merge arrays with ID fields +3. Detect value conflicts for same key +4. Handle nested object merging +5. Preserve number precision + +### YAML +1. Merge with comment preservation +2. Handle anchors and aliases +3. Multi-document YAML files +4. Nested structure merging + +### XML +1. Match elements by ID attribute +2. Namespace handling +3. DTD preservation +4. Comment preservation + +### Package Files +1. Merge dependencies without conflicts +2. Detect version conflicts +3. Handle different package managers +4. Preserve comments and formatting + +## Priority + +**HIGH** - This is a key differentiator for WizardMerge and significantly improves user experience. + +## Estimated Effort + +4-6 weeks + +## Dependencies + +- Three-way merge algorithm βœ… +- File I/O module (Issue #TBD) + +## Related Issues + +- #TBD (Phase 2 tracking) +- #TBD (Language-aware AST merging) +- #TBD (SDG Analysis) + +## Success Metrics + +- Reduce conflicts in structured files by 40% +- 95% user satisfaction for JSON/YAML merging +- <100ms merge time for typical files diff --git a/.github/issues/04-ast-based-merging.md b/.github/issues/04-ast-based-merging.md new file mode 100644 index 0000000..a5ebe97 --- /dev/null +++ b/.github/issues/04-ast-based-merging.md @@ -0,0 +1,451 @@ +--- +title: "Phase 2.1: Language-Aware AST-Based Merging (Python, JavaScript, Java, C/C++)" +labels: ["enhancement", "phase-2", "ast-merge", "high-priority"] +assignees: [] +milestone: "Phase 2 - Intelligence & Usability" +--- + +## Overview + +Implement Abstract Syntax Tree (AST) based merging for programming languages. Parse code into AST, merge at the semantic level, and regenerate code. This enables intelligent merging that understands language structure and semantics. + +## Related Roadmap Section + +Phase 2.1 - Smart Conflict Resolution (Language-aware merging) + +## Motivation + +Text-based merging treats code as plain text, leading to: +- Conflicts in imports even when they don't overlap +- Breaking syntax during merge +- Missing semantic relationships (e.g., a function using an imported module) +- False conflicts from formatting/whitespace changes + +AST-based merging can: +- Merge import statements intelligently (deduplicate, sort) +- Detect real semantic conflicts vs. formatting conflicts +- Preserve code structure and validity +- Understand language-specific constructs (decorators, annotations, etc.) + +## Languages to Support + +### Priority 1 (High Usage) +- Python +- JavaScript/TypeScript +- Java +- C/C++ + +### Priority 2 (Future) +- Go +- Rust +- C# +- Ruby +- PHP + +## Features by Language + +### Python + +- [ ] **Import merging** + - Deduplicate imports + - Merge `from X import Y, Z` statements + - Preserve import aliases + - Detect conflicting aliases +- [ ] **Function definitions** + - Merge non-overlapping functions + - Detect signature conflicts + - Handle decorators intelligently +- [ ] **Class hierarchies** + - Merge methods in classes + - Handle inheritance changes + - Merge class attributes +- [ ] **Type hints** + - Preserve type annotations + - Merge type imports from `typing` +- [ ] **Docstrings** + - Preserve and merge docstrings + +**Example**: +```python +# Base +import os +def hello(): + pass + +# Ours +import os +import sys +def hello(): + pass +def world(): + pass + +# Theirs +import os +from pathlib import Path +def hello(): + """Say hello""" + pass + +# Merged (AST-based) +import os +import sys +from pathlib import Path + +def hello(): + """Say hello""" + pass + +def world(): + pass +``` + +### JavaScript/TypeScript + +- [ ] **Import/Export merging** + - Merge ES6 imports (`import X from 'Y'`) + - Handle named vs default exports + - Deduplicate imports +- [ ] **Module analysis** + - Detect exported functions/classes + - Handle re-exports +- [ ] **React components** + - Merge component props + - Handle JSX conflicts + - Detect hook usage conflicts +- [ ] **Type definitions (TypeScript)** + - Merge interfaces + - Handle type aliases + - Resolve type conflicts + +**Example**: +```typescript +// Base +import { useState } from 'react'; + +// Ours +import { useState, useEffect } from 'react'; +function MyComponent() { /* ... */ } + +// Theirs +import { useState } from 'react'; +import axios from 'axios'; + +// Merged +import { useState, useEffect } from 'react'; +import axios from 'axios'; + +function MyComponent() { /* ... */ } +``` + +### Java + +- [ ] **Package declarations** + - Ensure consistent package + - Detect package conflicts +- [ ] **Import statements** + - Merge imports + - Remove unused imports + - Sort imports +- [ ] **Class structure** + - Merge methods + - Handle overloaded methods + - Merge fields +- [ ] **Annotations** + - Preserve annotations + - Detect annotation conflicts +- [ ] **Method signatures** + - Detect incompatible changes to method signatures + - Handle generics + +**Example**: +```java +// Base +import java.util.List; +public class MyClass { + public void doSomething() { } +} + +// Ours +import java.util.List; +import java.util.Map; +public class MyClass { + public void doSomething() { } + public void doMore() { } +} + +// Theirs +import java.util.List; +import java.io.File; +public class MyClass { + @Override + public void doSomething() { } +} + +// Merged +import java.io.File; +import java.util.List; +import java.util.Map; + +public class MyClass { + @Override + public void doSomething() { } + + public void doMore() { } +} +``` + +### C/C++ + +- [ ] **Include directives** + - Merge `#include` statements + - Preserve include guards + - Deduplicate includes +- [ ] **Macro definitions** + - Detect conflicting macros + - Merge non-overlapping macros +- [ ] **Function declarations** + - Merge forward declarations + - Handle function overloading (C++) +- [ ] **Namespace handling (C++)** + - Merge namespace contents + - Handle using directives +- [ ] **Class definitions (C++)** + - Merge member functions + - Handle access specifiers + - Merge nested classes + +**Example**: +```cpp +// Base +#include + +void foo(); + +// Ours +#include +#include + +void foo(); +void bar(); + +// Theirs +#include +#include + +void foo(); +namespace utils { + void helper(); +} + +// Merged +#include +#include +#include + +void foo(); +void bar(); + +namespace utils { + void helper(); +} +``` + +## Technical Design + +### Architecture + +```cpp +// Abstract AST merger interface +class ASTMerger { +public: + virtual MergeResult merge( + const std::string& base, + const std::string& ours, + const std::string& theirs + ) = 0; + + virtual bool can_handle(const std::string& file_path) = 0; + +protected: + virtual ParseTree parse(const std::string& code) = 0; + virtual ParseTree merge_ast(ParseTree base, ParseTree ours, ParseTree theirs) = 0; + virtual std::string generate_code(ParseTree merged) = 0; +}; + +// Language-specific implementations +class PythonASTMerger : public ASTMerger { /* ... */ }; +class JavaScriptASTMerger : public ASTMerger { /* ... */ }; +class JavaASTMerger : public ASTMerger { /* ... */ }; +class CPPASTMerger : public ASTMerger { /* ... */ }; +``` + +### Using Tree-sitter + +Tree-sitter provides fast, incremental parsing for many languages: + +```cpp +#include + +class TreeSitterMerger : public ASTMerger { + TSParser* parser; + const TSLanguage* language; + + ParseTree parse(const std::string& code) override { + TSTree* tree = ts_parser_parse_string(parser, nullptr, code.c_str(), code.length()); + return ParseTree(tree); + } + + // Traverse AST and merge nodes + TSNode merge_nodes(TSNode base, TSNode ours, TSNode theirs); +}; +``` + +### Merge Strategy + +1. **Parse all three versions** into AST +2. **Identify top-level constructs** (imports, functions, classes) +3. **Match constructs by name/signature** +4. **Merge non-overlapping constructs** +5. **Detect conflicts** (same construct, different body) +6. **Generate merged code** from merged AST +7. **Format output** (use language-specific formatter) + +## Implementation Steps + +1. **Set up tree-sitter integration** + - Add tree-sitter dependency to Conan + - Add language grammars (Python, JS, Java, C++) + - Create wrapper classes + +2. **Implement Python merger** + - Parse Python code with tree-sitter + - Identify imports, functions, classes + - Implement merge logic + - Code generation + - Unit tests + +3. **Implement JavaScript/TypeScript merger** + - Parse JS/TS code + - Handle ES6 modules + - Merge imports and exports + - Unit tests + +4. **Implement Java merger** + - Parse Java code + - Handle packages and imports + - Merge class members + - Unit tests + +5. **Implement C/C++ merger** + - Parse C/C++ code + - Handle includes and macros + - Merge declarations and definitions + - Unit tests + +6. **Integration** + - Register AST mergers in merger registry + - Add file extension detection + - Integration tests + +7. **Formatting** + - Integrate with clang-format (C/C++) + - Use prettier (JavaScript/TypeScript) + - Use black or autopep8 (Python) + - Use google-java-format (Java) + +8. **Documentation** + - User guide for AST merging + - Examples for each language + - Limitations and edge cases + +## Libraries and Tools + +- **tree-sitter**: Fast, incremental parsing + - tree-sitter-python + - tree-sitter-javascript + - tree-sitter-java + - tree-sitter-cpp +- **Formatters**: + - clang-format (C/C++) + - prettier (JS/TS) + - black/autopep8 (Python) + - google-java-format (Java) + +## Acceptance Criteria + +- [ ] Can parse and merge Python files +- [ ] Can parse and merge JavaScript/TypeScript files +- [ ] Can parse and merge Java files +- [ ] Can parse and merge C/C++ files +- [ ] Imports/includes are merged intelligently +- [ ] Syntax validity is preserved +- [ ] Falls back to text merge on parse errors +- [ ] Unit tests for each language (>90% coverage) +- [ ] Integration tests with real-world code +- [ ] Performance: <200ms for files up to 5000 lines +- [ ] Documentation complete + +## Test Cases + +### Python +1. Merge imports (deduplicate) +2. Merge from-imports +3. Merge functions with decorators +4. Merge class methods +5. Handle type hints +6. Preserve docstrings + +### JavaScript/TypeScript +1. Merge ES6 imports +2. Handle default and named exports +3. Merge React components +4. Handle TypeScript interfaces +5. Preserve JSX + +### Java +1. Merge imports +2. Merge class methods +3. Handle method overloads +4. Preserve annotations +5. Merge nested classes + +### C/C++ +1. Merge include directives +2. Handle header guards +3. Merge function declarations +4. Handle namespaces (C++) +5. Merge macro definitions + +## Priority + +**HIGH** - Language-aware merging is a key differentiator and complements semantic merging. + +## Estimated Effort + +6-8 weeks + +## Dependencies + +- Semantic merge framework (Issue #TBD) +- Three-way merge algorithm βœ… + +## Related Issues + +- #TBD (Phase 2 tracking) +- #TBD (Semantic merge for structured files) +- #TBD (SDG Analysis) + +## Success Metrics + +- Reduce conflicts in code files by 50% +- Preserve syntax validity in 99% of merges +- 90% user satisfaction for AST merging +- <200ms merge time for typical files + +## Future Enhancements + +- Support for more languages (Go, Rust, C#) +- Semantic conflict detection (e.g., variable renamed but still used) +- Integration with LSP for real-time validation +- AI-assisted resolution for complex conflicts diff --git a/.github/issues/05-sdg-analysis.md b/.github/issues/05-sdg-analysis.md new file mode 100644 index 0000000..f27c341 --- /dev/null +++ b/.github/issues/05-sdg-analysis.md @@ -0,0 +1,408 @@ +--- +title: "Phase 2.1: System Dependence Graph (SDG) Analysis for Intelligent Conflict Resolution" +labels: ["enhancement", "phase-2", "sdg-analysis", "research", "high-priority"] +assignees: [] +milestone: "Phase 2 - Intelligence & Usability" +--- + +## Overview + +Implement System Dependence Graph (SDG) analysis based on the research paper from The University of Hong Kong. This is the core innovation of WizardMerge that achieves 28.85% reduction in conflict resolution time and provides merge suggestions for >70% of conflicted blocks. + +## Related Roadmap Section + +Phase 2.1 - Smart Conflict Resolution (SDG Analysis) + +## Research Foundation + +Based on the paper in `docs/PAPER.md`, which demonstrates: +- **28.85% reduction** in conflict resolution time +- **Merge suggestions for >70%** of code blocks affected by conflicts +- Tested on **227 conflicts** across five large-scale projects +- Uses **dependency analysis** at text and LLVM-IR levels + +## What is SDG Analysis? + +A System Dependence Graph (SDG) captures dependencies between code blocks: +- **Nodes**: Code blocks (statements, expressions, definitions) +- **Edges**: Dependencies (data flow, control flow) +- **Types**: + - Data dependencies (def-use relationships) + - Control dependencies (branching, loops) + - Call dependencies (function calls) + +### Why SDG for Merging? + +Traditional text-based merging ignores code semantics: +```python +# Base +x = 1 +y = x + 1 + +# Ours: Change x +x = 2 +y = x + 1 + +# Theirs: Use y +x = 1 +y = x + 1 +print(y) # Depends on x! + +# Text merge: May miss that x change affects print(y) +# SDG merge: Detects dependency and suggests keeping x = 2 +``` + +## Architecture + +### Multi-Level Dependency Analysis + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Text-Level Dependencies β”‚ +β”‚ - Line-to-line dependencies β”‚ +β”‚ - Block-to-block dependencies β”‚ +β”‚ - Variable def-use (regex-based) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ AST-Level Dependencies β”‚ +β”‚ - Function calls β”‚ +β”‚ - Variable references β”‚ +β”‚ - Class/method relationships β”‚ +β”‚ - Import dependencies β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ LLVM-IR Level Dependencies (C/C++) β”‚ +β”‚ - Precise data flow β”‚ +β”‚ - Control flow β”‚ +β”‚ - Pointer aliasing β”‚ +β”‚ - Memory dependencies β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### SDG Construction + +```cpp +class SystemDependenceGraph { +public: + // Build SDG for a code file + void build_graph(const std::string& code, const std::string& language); + + // Add nodes (code blocks) + NodeID add_node(const CodeBlock& block); + + // Add edges (dependencies) + void add_edge(NodeID from, NodeID to, DependencyType type); + + // Query dependencies + std::vector get_dependencies(NodeID node); + std::vector get_dependents(NodeID node); + + // Transitive closure + std::set get_transitive_dependencies(NodeID node); + + // Conflict analysis + ConflictAnalysis analyze_conflict( + const SDG& base_sdg, + const SDG& ours_sdg, + const SDG& theirs_sdg + ); +}; +``` + +### Dependency Types + +```cpp +enum class DependencyType { + // Data dependencies + DATA_FLOW, // x = 1; y = x; + DEF_USE, // Definition-use chain + + // Control dependencies + CONTROL_FLOW, // if (x) { y = 1; } + CALL, // foo(); (inside foo's body) + + // Structural dependencies + IMPORT, // import X; use X.method() + INHERITANCE, // class B extends A + FIELD_ACCESS, // obj.field + + // LLVM-IR dependencies (C/C++) + MEMORY_ALIAS, // Pointer aliasing + LOAD_STORE, // Memory load/store dependencies +}; +``` + +## Features to Implement + +### 1. Text-Level Dependency Analysis + +- [ ] **Line-to-line dependencies** + - Variable definition tracking (regex-based) + - Variable use tracking + - Build def-use chains + +- [ ] **Block-level dependencies** + - Identify code blocks (functions, loops, conditionals) + - Track block boundaries + - Build block dependency graph + +**Algorithm**: +``` +For each line: + 1. Extract variable definitions (x = ..., def foo():) + 2. Extract variable uses (y = x + 1) + 3. Create dependency edge: definition β†’ use +``` + +### 2. AST-Level Dependency Analysis + +- [ ] **Parse code into AST** (using tree-sitter) +- [ ] **Extract semantic elements**: + - Function definitions and calls + - Variable declarations and references + - Class definitions and instantiations + - Import/include statements +- [ ] **Build dependency graph**: + - Function call graph + - Variable reference graph + - Import dependency graph +- [ ] **Detect conflicts**: + - Modified functions with dependent code + - Changed variables still in use + - Removed imports still referenced + +**Example**: +```python +# Base +def compute(x): + return x * 2 + +result = compute(5) + +# Ours: Change compute +def compute(x): + return x * 3 # Changed! + +result = compute(5) + +# Theirs: Use result +def compute(x): + return x * 2 + +result = compute(5) +print(result) # Depends on compute! + +# SDG Analysis: Detects that print(result) depends on compute() +# Suggests: Keep changed compute, preserve print +``` + +### 3. LLVM-IR Level Analysis (C/C++) + +- [ ] **Compile to LLVM IR** + - Use Clang to generate LLVM IR + - Parse IR and build control flow graph (CFG) + - Build data flow graph (DFG) + +- [ ] **Analyze dependencies**: + - Data flow (load/store, SSA form) + - Control flow (branches, loops) + - Memory dependencies (aliasing) + - Function calls + +- [ ] **Conflict detection**: + - Detect violated dependencies + - Find affected code blocks + - Compute conflict impact radius + +**Tools**: LLVM libraries (libclang, LLVM IR parser) + +### 4. Conflict Analysis with SDG + +```cpp +struct ConflictAnalysis { + // Classification + bool is_true_conflict; // Semantic conflict + bool is_false_conflict; // Text conflict only + + // Impact + std::set affected_blocks; // Blocks affected by conflict + int impact_radius; // Distance in dependency graph + + // Dependencies + std::vector violated_edges; // Dependencies broken by merge + std::vector safe_edges; // Dependencies preserved + + // Suggestions + std::vector suggestions; // Merge suggestions + double confidence; // Confidence score (0-1) +}; + +class ConflictAnalyzer { + ConflictAnalysis analyze( + const SDG& base_sdg, + const SDG& ours_sdg, + const SDG& theirs_sdg, + const ConflictRegion& conflict + ); + + // Classify edges + void classify_edges(); + + // Compute impact + void compute_impact(); + + // Generate suggestions + void generate_suggestions(); +}; +``` + +### 5. Visualization + +- [ ] **Dependency graph viewer**: + - Interactive graph visualization + - Show nodes (code blocks) + - Show edges (dependencies) + - Highlight conflicts and affected blocks + +- [ ] **Impact visualization**: + - Color-coded nodes (safe, conflicted, affected) + - Show dependency paths + - Display conflict impact radius + +- [ ] **Suggestion UI**: + - Show suggested resolutions + - Display confidence scores + - Explain reasoning (why this suggestion?) + +**Library**: D3.js (web) or Qt Graphics (desktop) + +## Implementation Steps + +1. **Phase 1: Text-Level Analysis (2 weeks)** + - Implement variable tracking + - Build line-level dependency graph + - Test on simple examples + +2. **Phase 2: AST-Level Analysis (3 weeks)** + - Integrate tree-sitter + - Parse AST for Python, JS, Java, C++ + - Build semantic dependency graph + - Test on real-world code + +3. **Phase 3: LLVM-IR Analysis (3 weeks)** + - Integrate LLVM/Clang + - Generate and parse LLVM IR + - Build precise dependency graph + - Test on C/C++ projects + +4. **Phase 4: Conflict Analysis (2 weeks)** + - Implement edge classification + - Compute conflict impact + - Generate merge suggestions + - Test on conflict datasets + +5. **Phase 5: Visualization (2 weeks)** + - Build dependency graph viewer + - Integrate into UI + - User testing + +6. **Phase 6: Integration & Optimization (2 weeks)** + - Integrate with merge pipeline + - Optimize performance + - Cache dependency graphs + - Final testing + +## Libraries and Tools + +- **tree-sitter**: AST parsing +- **LLVM/Clang**: IR generation and analysis +- **Boost Graph Library**: Graph algorithms +- **D3.js**: Visualization (web) +- **Qt Graphics**: Visualization (desktop) + +## Acceptance Criteria + +- [ ] Text-level dependency analysis works +- [ ] AST-level dependency analysis works for Python, JS, Java, C++ +- [ ] LLVM-IR analysis works for C/C++ +- [ ] Conflict analyzer detects true vs. false conflicts +- [ ] Generates merge suggestions with confidence scores +- [ ] Achieves >70% suggestion rate on test dataset +- [ ] Reduces resolution time by >25% (user study) +- [ ] Visualization is clear and helpful +- [ ] Performance: <500ms for files up to 2000 lines +- [ ] Documentation complete + +## Test Cases + +### Text-Level +1. Simple def-use chain +2. Multiple definitions +3. Variable shadowing +4. Cross-block dependencies + +### AST-Level +1. Function call dependencies +2. Import dependencies +3. Class inheritance +4. Variable references across scopes + +### LLVM-IR (C/C++) +1. Pointer aliasing +2. Memory dependencies +3. Control flow dependencies +4. Function call dependencies + +### Conflict Analysis +1. True conflict (semantic) +2. False conflict (text-only) +3. Transitive dependencies +4. Conflict impact radius +5. Suggestion generation + +## Priority + +**HIGH** - This is the core innovation of WizardMerge and the main research contribution. + +## Estimated Effort + +10-14 weeks (full implementation) + +Incremental approach: +- **Milestone 1** (4 weeks): Text and AST analysis +- **Milestone 2** (4 weeks): LLVM-IR analysis +- **Milestone 3** (4 weeks): Conflict analysis and visualization + +## Dependencies + +- AST-based merging (Issue #TBD) +- Three-way merge algorithm βœ… + +## Related Issues + +- #TBD (Phase 2 tracking) +- #TBD (AST-based merging) +- #TBD (Visualization enhancements) + +## Success Metrics + +- **28.85% reduction** in conflict resolution time (match research) +- **>70% suggestion rate** for conflicted blocks +- **90% user satisfaction** with SDG-based suggestions +- **High precision** (>80%) for conflict detection + +## References + +- Research paper: `docs/PAPER.md` +- Formal specification: `spec/WizardMergeSpec.tla` +- ROADMAP.md Phase 2.1 + +## Future Enhancements + +- Machine learning for confidence scoring +- User feedback loop (learn from resolutions) +- Cross-file dependency analysis +- Language-specific semantic analysis +- Integration with LSP for real-time analysis diff --git a/.github/issues/06-multi-platform-support.md b/.github/issues/06-multi-platform-support.md new file mode 100644 index 0000000..96c64e5 --- /dev/null +++ b/.github/issues/06-multi-platform-support.md @@ -0,0 +1,429 @@ +--- +title: "Phase 2.5: Multi-Platform Support (Bitbucket, Azure DevOps, Gitea/Forgejo)" +labels: ["enhancement", "phase-2", "git-platforms", "medium-priority"] +assignees: [] +milestone: "Phase 2 - Intelligence & Usability" +--- + +## Overview + +Extend PR/MR conflict resolution to support additional Git platforms beyond GitHub and GitLab. Implement an extensible platform pattern that makes it easy to add new platforms in the future. + +## Related Roadmap Section + +Phase 2.5 - Additional Platform Support + +## Current Status + +βœ… **Implemented**: +- GitHub (GitHub API v3) +- GitLab (GitLab API) + +πŸ”œ **To Implement**: +- Bitbucket (Cloud and Server) +- Azure DevOps (Cloud and Server) +- Gitea/Forgejo + +## Platforms to Support + +### 1. Bitbucket + +#### Bitbucket Cloud +- **API**: Bitbucket Cloud REST API 2.0 +- **URL Pattern**: `https://bitbucket.org/{workspace}/{repo}/pull-requests/{number}` +- **Authentication**: + - App passwords + - OAuth 2.0 +- **API Endpoints**: + - GET `/2.0/repositories/{workspace}/{repo}/pullrequests/{number}` + - GET `/2.0/repositories/{workspace}/{repo}/src/{commit}/{path}` + - GET `/2.0/repositories/{workspace}/{repo}/diff/{spec}` + +#### Bitbucket Server (Self-Hosted) +- **API**: Bitbucket Server REST API 1.0 +- **URL Pattern**: `https://{server}/projects/{project}/repos/{repo}/pull-requests/{number}` +- **Authentication**: Personal Access Tokens, HTTP Basic Auth +- **API Endpoints**: + - GET `/rest/api/1.0/projects/{project}/repos/{repo}/pull-requests/{number}` + - GET `/rest/api/1.0/projects/{project}/repos/{repo}/browse/{path}?at={ref}` + +**Implementation Priority**: HIGH + +### 2. Azure DevOps + +#### Azure DevOps Cloud +- **API**: Azure DevOps REST API 6.0 +- **URL Pattern**: `https://dev.azure.com/{organization}/{project}/_git/{repo}/pullrequest/{number}` +- **Authentication**: Personal Access Tokens (PAT) +- **API Endpoints**: + - GET `/{organization}/{project}/_apis/git/repositories/{repo}/pullrequests/{number}` + - GET `/{organization}/{project}/_apis/git/repositories/{repo}/items?path={path}&version={ref}` + +#### Azure DevOps Server (On-Premises) +- **API**: Same as cloud +- **URL Pattern**: `https://{server}/{organization}/{project}/_git/{repo}/pullrequest/{number}` +- **Authentication**: PAT, NTLM, Kerberos + +**Implementation Priority**: HIGH (widely used in enterprise) + +### 3. Gitea / Forgejo + +- **API**: Gitea/Forgejo API (OpenAPI compatible) +- **URL Pattern**: `https://{server}/{owner}/{repo}/pulls/{number}` +- **Authentication**: Access tokens +- **API Endpoints**: + - GET `/api/v1/repos/{owner}/{repo}/pulls/{number}` + - GET `/api/v1/repos/{owner}/{repo}/contents/{path}?ref={ref}` +- **Note**: Forgejo is a fork of Gitea with compatible API + +**Implementation Priority**: MEDIUM (growing community adoption) + +## Extensible Platform Pattern + +### Design Goals + +1. **Easy to add new platforms** - Minimal code changes +2. **Abstract common operations** - Unified interface +3. **Platform-specific customization** - Handle API differences +4. **Configuration-driven** - Define platforms via config +5. **Plugin system** - External platform implementations + +### Abstract Interface + +```cpp +// Abstract Git platform API +class GitPlatformAPI { +public: + virtual ~GitPlatformAPI() = default; + + // Core operations + virtual PullRequest fetch_pr_info( + const std::string& owner, + const std::string& repo, + const std::string& pr_number, + const std::string& token + ) = 0; + + virtual std::string fetch_file_content( + const std::string& owner, + const std::string& repo, + const std::string& file_path, + const std::string& ref, + const std::string& token + ) = 0; + + // Optional operations + virtual bool create_comment( + const std::string& owner, + const std::string& repo, + const std::string& pr_number, + const std::string& comment, + const std::string& token + ) { return false; } + + virtual bool update_pr_status( + const std::string& owner, + const std::string& repo, + const std::string& pr_number, + const std::string& status, + const std::string& token + ) { return false; } + + // Metadata + virtual std::string platform_name() const = 0; + virtual std::string api_base_url() const = 0; +}; +``` + +### Platform Registry + +```cpp +class GitPlatformRegistry { +public: + // Register a platform implementation + void register_platform( + const std::string& name, + std::unique_ptr api + ); + + // Detect platform from URL + GitPlatform detect_platform(const std::string& url); + + // Get platform implementation + GitPlatformAPI* get_platform(GitPlatform platform); + + // Parse PR URL (delegates to platform) + PRInfo parse_pr_url(const std::string& url); +}; +``` + +### Platform Detection + +```cpp +struct URLPattern { + std::string pattern; // Regex pattern + GitPlatform platform; // Platform enum + std::vector capture_groups; // owner, repo, pr_number, etc. +}; + +class PlatformDetector { + std::vector patterns; + + GitPlatform detect(const std::string& url) { + for (const auto& pattern : patterns) { + if (std::regex_match(url, pattern.pattern)) { + return pattern.platform; + } + } + return GitPlatform::Unknown; + } +}; +``` + +### Configuration-Based Platform Definitions + +```yaml +# platforms.yml +platforms: + - name: bitbucket_cloud + url_pattern: "(?:https?://)?bitbucket\\.org/([^/]+)/([^/]+)/pull-requests/(\\d+)" + api_base_url: "https://api.bitbucket.org/2.0" + auth_type: bearer_token + endpoints: + pr_info: "/repositories/{owner}/{repo}/pullrequests/{number}" + file_content: "/repositories/{owner}/{repo}/src/{ref}/{path}" + field_mappings: + base_ref: "destination.branch.name" + head_ref: "source.branch.name" + + - name: azure_devops + url_pattern: "https://dev\\.azure\\.com/([^/]+)/([^/]+)/_git/([^/]+)/pullrequest/(\\d+)" + api_base_url: "https://dev.azure.com/{organization}/{project}/_apis" + auth_type: basic_auth + endpoints: + pr_info: "/git/repositories/{repo}/pullrequests/{number}?api-version=6.0" + file_content: "/git/repositories/{repo}/items?path={path}&version={ref}&api-version=6.0" +``` + +## Implementation Steps + +### 1. Refactor Existing Code (1 week) + +- [ ] Extract GitHub implementation to `GitHubAPI` class +- [ ] Extract GitLab implementation to `GitLabAPI` class +- [ ] Create `GitPlatformAPI` interface +- [ ] Create `GitPlatformRegistry` +- [ ] Update `PRController` to use registry + +### 2. Implement Bitbucket Support (1.5 weeks) + +- [ ] Create `BitbucketCloudAPI` class +- [ ] Implement PR info fetching +- [ ] Implement file content fetching +- [ ] Handle authentication (App passwords) +- [ ] Add URL pattern to detector +- [ ] Unit tests +- [ ] Integration tests with Bitbucket API + +- [ ] Create `BitbucketServerAPI` class (separate from Cloud) +- [ ] Handle different API structure +- [ ] Test with Bitbucket Server instance + +### 3. Implement Azure DevOps Support (1.5 weeks) + +- [ ] Create `AzureDevOpsAPI` class +- [ ] Implement PR info fetching +- [ ] Implement file content fetching +- [ ] Handle PAT authentication +- [ ] Add URL pattern to detector +- [ ] Handle both Cloud and Server versions +- [ ] Unit tests +- [ ] Integration tests + +### 4. Implement Gitea/Forgejo Support (1 week) + +- [ ] Create `GiteaAPI` class +- [ ] Implement PR info fetching +- [ ] Implement file content fetching +- [ ] Handle token authentication +- [ ] Add URL pattern to detector +- [ ] Unit tests +- [ ] Integration tests + +### 5. Configuration System (1 week) + +- [ ] Design YAML schema for platform definitions +- [ ] Implement YAML parser +- [ ] Create `ConfigBasedPlatform` class +- [ ] Support dynamic platform loading +- [ ] Documentation for adding custom platforms + +### 6. Testing & Documentation (1 week) + +- [ ] Comprehensive unit tests for all platforms +- [ ] Integration tests with real APIs (use test repos) +- [ ] Update README.md with examples for all platforms +- [ ] Create platform implementation guide +- [ ] API documentation + +## Example Usage + +### Bitbucket Cloud + +```bash +# CLI +./wizardmerge-cli-frontend pr-resolve \ + --url https://bitbucket.org/myworkspace/myrepo/pull-requests/42 \ + --token + +# Or with environment variable +export BITBUCKET_TOKEN= +./wizardmerge-cli-frontend pr-resolve \ + --url https://bitbucket.org/myworkspace/myrepo/pull-requests/42 +``` + +```bash +# HTTP API +curl -X POST http://localhost:8080/api/pr/resolve \ + -H "Content-Type: application/json" \ + -d '{ + "pr_url": "https://bitbucket.org/myworkspace/myrepo/pull-requests/42", + "api_token": "" + }' +``` + +### Azure DevOps + +```bash +# CLI +./wizardmerge-cli-frontend pr-resolve \ + --url https://dev.azure.com/myorg/myproject/_git/myrepo/pullrequest/123 \ + --token + +# HTTP API +curl -X POST http://localhost:8080/api/pr/resolve \ + -H "Content-Type: application/json" \ + -d '{ + "pr_url": "https://dev.azure.com/myorg/myproject/_git/myrepo/pullrequest/123", + "api_token": "" + }' +``` + +### Gitea + +```bash +# CLI +./wizardmerge-cli-frontend pr-resolve \ + --url https://gitea.mycompany.com/owner/repo/pulls/5 \ + --token +``` + +## Platform Implementation Guide + +For future contributors who want to add a new platform: + +### Step 1: Create Platform API Class + +```cpp +class MyPlatformAPI : public GitPlatformAPI { +public: + PullRequest fetch_pr_info(...) override { + // 1. Build API URL + std::string url = api_base_url + "/pr/endpoint"; + + // 2. Make HTTP request with auth + auto response = http_client.get(url, headers); + + // 3. Parse JSON response + Json::Value root = parse_json(response.body); + + // 4. Map to PullRequest structure + PullRequest pr; + pr.base_ref = root["target_branch"].asString(); + pr.head_ref = root["source_branch"].asString(); + // ... map other fields + + return pr; + } + + std::string fetch_file_content(...) override { + // Similar pattern + } + + std::string platform_name() const override { return "MyPlatform"; } +}; +``` + +### Step 2: Add URL Pattern + +```cpp +// In git_platform_client.cpp +std::regex myplatform_regex( + R"((?:https?://)?myplatform\.com/([^/]+)/([^/]+)/pr/(\\d+))" +); + +if (std::regex_match(pr_url, match, myplatform_regex)) { + platform = GitPlatform::MyPlatform; + // Extract owner, repo, pr_number from match groups +} +``` + +### Step 3: Register in Registry + +```cpp +// In main() or init() +platform_registry.register_platform( + "myplatform", + std::make_unique() +); +``` + +### Step 4: Add Tests + +```cpp +TEST(MyPlatformAPITest, FetchPRInfo) { + MyPlatformAPI api; + auto pr = api.fetch_pr_info("owner", "repo", "123", "token"); + ASSERT_EQ(pr.number, "123"); + ASSERT_FALSE(pr.base_ref.empty()); +} +``` + +## Acceptance Criteria + +- [ ] Bitbucket Cloud support working +- [ ] Bitbucket Server support working +- [ ] Azure DevOps Cloud support working +- [ ] Azure DevOps Server support working +- [ ] Gitea/Forgejo support working +- [ ] Platform registry implemented +- [ ] URL detection automatic +- [ ] Configuration-based platforms supported +- [ ] All platforms tested with real APIs +- [ ] Documentation complete +- [ ] Implementation guide available + +## Priority + +**MEDIUM-HIGH** - Important for enterprise adoption and wider user base. + +## Estimated Effort + +6-8 weeks total + +## Dependencies + +- PR resolution feature βœ… +- Git CLI integration βœ… + +## Related Issues + +- #TBD (Phase 2 tracking) +- #TBD (API improvements) + +## Success Metrics + +- Support 5+ major Git platforms +- <5% error rate for each platform +- Easy to add new platforms (<1 day of work) +- 90% user satisfaction across platforms diff --git a/.github/issues/07-core-ui-components.md b/.github/issues/07-core-ui-components.md new file mode 100644 index 0000000..6274549 --- /dev/null +++ b/.github/issues/07-core-ui-components.md @@ -0,0 +1,357 @@ +--- +title: "Phase 1.3: Core UI Components for Conflict Visualization" +labels: ["enhancement", "phase-1", "ui-ux", "high-priority"] +assignees: [] +milestone: "Phase 1 - Foundation" +--- + +## Overview + +Implement core UI components for visualizing and resolving merge conflicts in the Qt6 and Next.js frontends. Provide an intuitive, visual interface for understanding and resolving conflicts. + +## Related Roadmap Section + +Phase 1.3 - Core UI Components + +## Motivation + +Current merge tools often present conflicts in a confusing way. WizardMerge aims to make conflicts immediately obvious with: +- Clear visual distinction between base, ours, and theirs +- Syntax highlighting for readability +- Easy navigation between conflicts +- Intuitive action buttons + +## Features to Implement + +### 1. Three-Panel Diff View + +Display base, ours, and theirs side-by-side: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ BASE β”‚ OURS β”‚ THEIRS β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ def foo(): β”‚ def foo(): β”‚ def foo(): β”‚ +β”‚ return 1 β”‚ return 2 β”‚ return 3 β”‚ +β”‚ β”‚ def bar(): β”‚ def baz(): β”‚ +β”‚ β”‚ pass β”‚ pass β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Components**: +- [ ] `ThreePanelView` - Container for three panels +- [ ] `DiffPanel` - Individual diff panel with syntax highlighting +- [ ] Synchronized scrolling between panels +- [ ] Line number display +- [ ] Change highlighting (added, removed, modified) + +### 2. Unified Conflict View + +Display conflicts inline with markers: + +``` +func calculate(x int) int { + // Non-conflicted code + y := x * 2 + +<<<<<<< OURS + return y + 1 +======= + return y + 2 +>>>>>>> THEIRS + + // More non-conflicted code +} +``` + +**Components**: +- [ ] `UnifiedConflictView` - Inline conflict display +- [ ] `ConflictMarker` - Visual markers for conflict boundaries +- [ ] `ConflictRegion` - Highlighted conflict sections +- [ ] Color coding: Green (ours), Blue (theirs), Yellow (both) +- [ ] Collapsible conflict regions + +### 3. Syntax Highlighting + +- [ ] Support for common languages: + - Python + - JavaScript/TypeScript + - Java + - C/C++ + - Go + - Rust + - Ruby + - PHP + - Shell scripts + - JSON/YAML/XML + - HTML/CSS + - Markdown + +**Qt6 Implementation**: QSyntaxHighlighter +**Next.js Implementation**: Prism.js or Highlight.js + +### 4. Line Numbering + +- [ ] Display line numbers for each panel +- [ ] Align line numbers with code +- [ ] Handle line insertions/deletions +- [ ] Optional: Show line numbers from original files + +### 5. Conflict Navigation + +- [ ] Conflict counter: "Conflict 2 of 5" +- [ ] Next/Previous conflict buttons +- [ ] Jump to conflict dropdown +- [ ] Keyboard shortcuts: + - `n` - Next conflict + - `p` - Previous conflict + - `j`/`k` - Scroll down/up +- [ ] Minimap showing conflict locations (optional) + +**UI Mockup**: +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ [< Prev] Conflict 2 of 5 [Next >] [v] β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 6. Conflict Complexity Indicator + +Show how complex each conflict is: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Conflict 1: ●○○○○ Simple β”‚ +β”‚ Conflict 2: ●●●○○ Medium β”‚ +β”‚ Conflict 3: ●●●●● Complex β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Complexity Factors**: +- Lines affected +- Number of changes +- Semantic complexity (if SDG analysis available) + +### 7. Change Type Highlighting + +Color-coded change types: +- 🟒 **Added** (green) - New lines +- πŸ”΄ **Removed** (red) - Deleted lines +- 🟑 **Modified** (yellow) - Changed lines +- πŸ”΅ **Conflicted** (blue) - Merge conflict +- βšͺ **Unchanged** (default) - No change + +## Technical Design + +### Qt6 (QML) Components + +```qml +// ThreePanelView.qml +Item { + id: threePanelView + + Row { + spacing: 1 + + DiffPanel { + id: basePanel + title: "BASE" + content: mergeModel.baseContent + width: parent.width / 3 + } + + DiffPanel { + id: oursPanel + title: "OURS" + content: mergeModel.oursContent + width: parent.width / 3 + } + + DiffPanel { + id: theirsPanel + title: "THEIRS" + content: mergeModel.theirsContent + width: parent.width / 3 + } + } + + // Synchronized scrolling + Connections { + target: basePanel.flickable + onContentYChanged: { + oursPanel.flickable.contentY = basePanel.flickable.contentY + theirsPanel.flickable.contentY = basePanel.flickable.contentY + } + } +} + +// DiffPanel.qml +Rectangle { + id: diffPanel + property string title: "" + property string content: "" + property alias flickable: scrollView.contentItem + + Column { + Header { + text: title + } + + ScrollView { + id: scrollView + + TextArea { + text: content + readOnly: true + font.family: "monospace" + // Syntax highlighting applied here + } + } + } +} +``` + +### Next.js (React) Components + +```tsx +// ThreePanelView.tsx +import { useState } from 'react'; +import DiffPanel from './DiffPanel'; +import SyntaxHighlighter from 'react-syntax-highlighter'; + +export default function ThreePanelView({ base, ours, theirs, language }) { + const [scrollTop, setScrollTop] = useState(0); + + const handleScroll = (e) => { + setScrollTop(e.target.scrollTop); + }; + + return ( +
+ + + +
+ ); +} + +// DiffPanel.tsx +export default function DiffPanel({ title, content, language, scrollTop, onScroll }) { + return ( +
+
{title}
+
+ + {content} + +
+
+ ); +} +``` + +## Implementation Steps + +### Phase 1: Basic Layout (1 week) +- [ ] Create three-panel layout (Qt6) +- [ ] Create three-panel layout (Next.js) +- [ ] Implement synchronized scrolling +- [ ] Add line numbers + +### Phase 2: Conflict Display (1 week) +- [ ] Parse conflicts from merge result +- [ ] Display conflict markers +- [ ] Highlight conflict regions +- [ ] Color-code changes + +### Phase 3: Syntax Highlighting (1 week) +- [ ] Integrate QSyntaxHighlighter (Qt6) +- [ ] Integrate Prism.js (Next.js) +- [ ] Add language detection +- [ ] Configure themes + +### Phase 4: Navigation (1 week) +- [ ] Implement conflict counter +- [ ] Add next/previous buttons +- [ ] Keyboard shortcuts +- [ ] Jump to conflict dropdown + +### Phase 5: Polish (1 week) +- [ ] Conflict complexity indicator +- [ ] Minimap (optional) +- [ ] Responsive design (Next.js) +- [ ] Accessibility (ARIA labels, keyboard nav) +- [ ] Dark mode support + +## Acceptance Criteria + +- [ ] Three-panel view displays base, ours, theirs +- [ ] Unified view shows conflicts inline +- [ ] Syntax highlighting works for major languages +- [ ] Line numbers displayed correctly +- [ ] Can navigate between conflicts easily +- [ ] Keyboard shortcuts work +- [ ] Scrolling is synchronized in three-panel view +- [ ] UI is responsive (Next.js) +- [ ] Dark mode supported +- [ ] Accessible (keyboard navigation, screen readers) + +## Testing + +- [ ] Unit tests for components +- [ ] Visual regression tests +- [ ] Accessibility tests +- [ ] Performance tests (large files) +- [ ] Cross-browser testing (Next.js) + +## Dependencies + +- Three-way merge algorithm βœ… +- Backend API βœ… + +## Priority + +**HIGH** - Essential for user experience + +## Estimated Effort + +5 weeks (parallel development for Qt6 and Next.js) + +## Related Issues + +- #TBD (Phase 1 completion) +- #TBD (UI/UX improvements) +- #TBD (Enhanced visualization - Phase 2) + +## Design Resources + +- [ ] Create mockups for three-panel view +- [ ] Create mockups for unified view +- [ ] Design conflict navigation UI +- [ ] Choose color scheme for changes +- [ ] Select monospace fonts + +## Success Metrics + +- 90% user satisfaction with UI +- <100ms render time for typical files +- 100% keyboard accessibility +- Positive feedback on conflict clarity diff --git a/.github/issues/08-ai-assisted-merging.md b/.github/issues/08-ai-assisted-merging.md new file mode 100644 index 0000000..f3b4b9b --- /dev/null +++ b/.github/issues/08-ai-assisted-merging.md @@ -0,0 +1,388 @@ +--- +title: "Phase 3.1: AI-Assisted Merge Conflict Resolution" +labels: ["enhancement", "phase-3", "ai-ml", "medium-priority"] +assignees: [] +milestone: "Phase 3 - Advanced Features" +--- + +## Overview + +Integrate AI/ML capabilities to provide intelligent merge conflict resolution suggestions, pattern recognition from repository history, and natural language explanations of conflicts. + +## Related Roadmap Section + +Phase 3.1 - AI-Assisted Merging + +## Motivation + +While SDG analysis provides structural insights, AI can: +- Learn from historical resolutions in the codebase +- Recognize patterns across projects +- Provide natural language explanations +- Suggest context-aware resolutions +- Assess risk of resolution choices + +## Features to Implement + +### 1. ML Model for Conflict Resolution + +Train a machine learning model to suggest resolutions based on: +- Code structure (AST features) +- Historical resolutions in the repo +- Common patterns in similar codebases +- Developer intent (commit messages, PR descriptions) + +**Model Types to Explore**: +- [ ] **Decision Tree / Random Forest**: For rule-based classification +- [ ] **Neural Network**: For complex pattern recognition +- [ ] **Transformer-based**: For code understanding (CodeBERT, GraphCodeBERT) +- [ ] **Hybrid**: Combine SDG + ML for best results + +**Features for ML Model**: +```python +features = { + # Structural features + 'conflict_size': int, # Lines in conflict + 'conflict_type': str, # add/add, modify/modify, etc. + 'file_type': str, # .py, .js, .java + 'num_dependencies': int, # From SDG + + # Historical features + 'similar_resolutions': List[str], # Past resolutions in repo + 'author_ours': str, # Who made 'ours' change + 'author_theirs': str, # Who made 'theirs' change + + # Semantic features + 'ast_node_type': str, # function, class, import, etc. + 'variable_names': List[str], # Variables involved + 'function_calls': List[str], # Functions called + + # Context features + 'commit_message_ours': str, # Commit message for 'ours' + 'commit_message_theirs': str, # Commit message for 'theirs' + 'pr_description': str, # PR description (if available) +} +``` + +### 2. Pattern Recognition from Repository History + +Analyze past conflict resolutions in the repository: + +- [ ] **Mining Git history**: + - Find merge commits + - Extract conflicts and their resolutions + - Build training dataset + +- [ ] **Pattern extraction**: + - Common resolution strategies (keep ours, keep theirs, merge both) + - File-specific patterns (package.json always merges dependencies) + - Developer-specific patterns (Alice tends to keep UI changes) + +- [ ] **Pattern matching**: + - Compare current conflict to historical patterns + - Find most similar past conflicts + - Suggest resolutions based on similarity + +**Algorithm**: +```python +def find_similar_conflicts(current_conflict, history): + # 1. Extract features from current conflict + features = extract_features(current_conflict) + + # 2. Compute similarity to historical conflicts + similarities = [] + for past_conflict in history: + sim = cosine_similarity(features, past_conflict.features) + similarities.append((sim, past_conflict)) + + # 3. Return top-k most similar + return sorted(similarities, reverse=True)[:5] + +def suggest_resolution(current_conflict, similar_conflicts): + # Majority vote from similar conflicts + resolutions = [c.resolution for c in similar_conflicts] + return most_common(resolutions) +``` + +### 3. Natural Language Explanations + +Generate human-readable explanations of conflicts and suggestions: + +**Example**: +``` +Conflict in file: src/utils.py +Location: function calculate() + +Explanation: +- BASE: The function returned x * 2 +- OURS: Changed return value to x * 3 (commit abc123 by Alice: "Increase multiplier") +- THEIRS: Changed return value to x + 1 (commit def456 by Bob: "Use addition instead") + +Dependencies affected: +- 3 functions call calculate() in this file +- 2 test cases depend on the return value + +Suggestion: Keep OURS (confidence: 75%) +Reasoning: +- Alice's change (x * 3) maintains the multiplication pattern used elsewhere +- Bob's change (x + 1) alters the semantic meaning significantly +- Historical resolutions in similar functions favor keeping the multiplication + +Risk: MEDIUM +- Test case test_calculate() may need updating +- Consider reviewing with Bob to understand intent +``` + +**Implementation**: +- [ ] Template-based generation for simple cases +- [ ] GPT/LLM-based generation for complex explanations +- [ ] Integrate commit messages and PR context +- [ ] Explain SDG dependencies in plain language + +### 4. Context-Aware Code Completion + +During conflict resolution, provide intelligent code completion: + +- [ ] **Integrate with LSP** (Language Server Protocol) +- [ ] **Suggest imports** needed for resolution +- [ ] **Validate syntax** in real-time +- [ ] **Auto-complete variables/functions** from context +- [ ] **Suggest type annotations** (TypeScript, Python) + +### 5. Risk Assessment for Resolution Choices + +Assess the risk of each resolution option: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Resolution Options β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ βœ“ Keep OURS Risk: LOW ●○○ β”‚ +β”‚ - Maintains existing tests β”‚ +β”‚ - Consistent with codebase style β”‚ +β”‚ β”‚ +β”‚ β—‹ Keep THEIRS Risk: HIGH ●●● β”‚ +β”‚ - Breaks 3 test cases β”‚ +β”‚ - Incompatible with feature X β”‚ +β”‚ β”‚ +β”‚ β—‹ Merge both Risk: MED ●●○ β”‚ +β”‚ - Requires manual adjustment β”‚ +β”‚ - May cause runtime error β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Risk Factors**: +- Test coverage affected +- Number of dependencies broken +- Semantic compatibility +- Historical success rate +- Developer confidence + +## Technical Design + +### ML Pipeline + +```python +# Training pipeline +class ConflictResolutionModel: + def __init__(self): + self.model = None # Transformer or other model + self.feature_extractor = FeatureExtractor() + + def train(self, training_data): + """Train on historical conflicts and resolutions""" + features = [self.feature_extractor.extract(c) for c in training_data] + labels = [c.resolution for c in training_data] + self.model.fit(features, labels) + + def predict(self, conflict): + """Predict resolution for new conflict""" + features = self.feature_extractor.extract(conflict) + prediction = self.model.predict(features) + confidence = self.model.predict_proba(features) + return prediction, confidence + +# Feature extraction +class FeatureExtractor: + def extract(self, conflict): + return { + 'structural': self.extract_structural(conflict), + 'historical': self.extract_historical(conflict), + 'semantic': self.extract_semantic(conflict), + 'contextual': self.extract_contextual(conflict), + } +``` + +### Integration with WizardMerge + +```cpp +// C++ backend integration +class AIAssistant { +public: + // Get AI suggestion for conflict + ResolutionSuggestion suggest(const Conflict& conflict); + + // Get natural language explanation + std::string explain(const Conflict& conflict); + + // Assess risk of resolution + RiskAssessment assess_risk(const Conflict& conflict, Resolution resolution); + +private: + // Call Python ML service + std::string call_ml_service(const std::string& endpoint, const Json::Value& data); +}; +``` + +### ML Service Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ WizardMerge C++ β”‚ +β”‚ Backend β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ HTTP/gRPC + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ ML Service β”‚ +β”‚ (Python/FastAPI) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ - Feature Extractionβ”‚ +β”‚ - Model Inference β”‚ +β”‚ - NLP Generation β”‚ +β”‚ - Risk Assessment β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Model Storage β”‚ +β”‚ - Trained models β”‚ +β”‚ - Feature cache β”‚ +β”‚ - Historical data β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Implementation Steps + +### Phase 1: Data Collection & Preparation (2 weeks) +- [ ] Mine Git history for conflicts and resolutions +- [ ] Build training dataset +- [ ] Feature engineering +- [ ] Data cleaning and validation + +### Phase 2: Model Training (3 weeks) +- [ ] Implement feature extraction +- [ ] Train baseline models (Decision Tree, Random Forest) +- [ ] Evaluate performance +- [ ] Experiment with advanced models (Transformers) +- [ ] Hyperparameter tuning + +### Phase 3: ML Service (2 weeks) +- [ ] Create Python FastAPI service +- [ ] Implement prediction endpoints +- [ ] Model serving and caching +- [ ] Performance optimization + +### Phase 4: Integration (2 weeks) +- [ ] Integrate ML service with C++ backend +- [ ] Add AI suggestions to merge API +- [ ] Update UI to display suggestions +- [ ] Add confidence scores + +### Phase 5: Natural Language Generation (2 weeks) +- [ ] Implement explanation templates +- [ ] Integrate with LLM (OpenAI API or local model) +- [ ] Context extraction (commits, PRs) +- [ ] UI for displaying explanations + +### Phase 6: Risk Assessment (1 week) +- [ ] Implement risk scoring +- [ ] Test impact analysis +- [ ] Dependency impact analysis +- [ ] UI for risk display + +### Phase 7: Testing & Refinement (2 weeks) +- [ ] User testing +- [ ] Model performance evaluation +- [ ] A/B testing (with and without AI) +- [ ] Collect feedback and iterate + +## Technologies + +- **ML Framework**: PyTorch or TensorFlow +- **NLP**: Hugging Face Transformers, OpenAI API +- **Feature Extraction**: tree-sitter (AST), Git2 (history) +- **ML Service**: FastAPI (Python) +- **Model Serving**: TorchServe or TensorFlow Serving +- **Vector Database**: Pinecone or FAISS (for similarity search) + +## Acceptance Criteria + +- [ ] ML model trained on historical data +- [ ] Achieves >70% accuracy on test set +- [ ] Provides suggestions in <1 second +- [ ] Natural language explanations are clear +- [ ] Risk assessment is accurate (validated by users) +- [ ] Integrates seamlessly with existing UI +- [ ] Falls back gracefully when ML unavailable +- [ ] User satisfaction >85% + +## Test Cases + +### Model Accuracy +1. Train on 80% of conflicts, test on 20% +2. Evaluate precision, recall, F1 score +3. Compare to baseline (SDG-only) + +### User Studies +1. Conflict resolution time (with vs without AI) +2. User satisfaction survey +3. Accuracy of AI suggestions (user feedback) +4. Usefulness of explanations + +### Performance +1. Prediction latency <1s +2. Explanation generation <2s +3. Risk assessment <500ms + +## Priority + +**MEDIUM** - Advanced feature for Phase 3, builds on SDG analysis + +## Estimated Effort + +14 weeks (3-4 months) + +## Dependencies + +- SDG analysis (Issue #TBD) +- AST-based merging (Issue #TBD) +- Git history mining + +## Related Issues + +- #TBD (Phase 3 tracking) +- #TBD (SDG Analysis) +- #TBD (Natural language processing) + +## Success Metrics + +- 30% reduction in conflict resolution time (beyond SDG) +- 80% accuracy for AI suggestions +- 90% user satisfaction with explanations +- <1s latency for all AI features + +## Ethical Considerations + +- [ ] Ensure ML model doesn't learn sensitive code patterns +- [ ] Provide transparency in AI decisions +- [ ] Allow users to disable AI features +- [ ] Don't store sensitive repository data +- [ ] Comply with data privacy regulations + +## Future Enhancements + +- Fine-tune on user's specific codebase +- Federated learning across multiple repos +- Reinforcement learning from user feedback +- Multi-modal learning (code + documentation + issues) diff --git a/.github/issues/09-conflict-resolution-actions.md b/.github/issues/09-conflict-resolution-actions.md new file mode 100644 index 0000000..518474b --- /dev/null +++ b/.github/issues/09-conflict-resolution-actions.md @@ -0,0 +1,476 @@ +--- +title: "Phase 1.4: Basic Conflict Resolution Actions and Undo/Redo" +labels: ["enhancement", "phase-1", "ui-ux", "high-priority"] +assignees: [] +milestone: "Phase 1 - Foundation" +--- + +## Overview + +Implement user actions for resolving conflicts: accept ours, accept theirs, accept both, manual edit, and a robust undo/redo system for safe conflict resolution. + +## Related Roadmap Section + +Phase 1.4 - Basic Conflict Resolution Actions + +## Motivation + +Users need simple, clear actions to resolve conflicts: +- One-click resolution for simple cases +- Safety net (undo) for mistakes +- Keyboard shortcuts for efficiency +- Visual feedback for actions taken + +## Features to Implement + +### 1. Resolution Actions + +#### Accept Ours +- [ ] Keep changes from "ours" branch +- [ ] Discard changes from "theirs" branch +- [ ] Button: "Accept Ours" or "Keep Ours" +- [ ] Keyboard shortcut: `o` or `Ctrl+1` + +#### Accept Theirs +- [ ] Keep changes from "theirs" branch +- [ ] Discard changes from "ours" branch +- [ ] Button: "Accept Theirs" or "Keep Theirs" +- [ ] Keyboard shortcut: `t` or `Ctrl+2` + +#### Accept Both +- [ ] Keep changes from both branches +- [ ] Concatenate or merge intelligently +- [ ] Button: "Accept Both" or "Keep Both" +- [ ] Keyboard shortcut: `b` or `Ctrl+3` +- [ ] Options for ordering: + - Ours first, then theirs + - Theirs first, then ours + - Smart merge (if possible) + +#### Manual Edit +- [ ] Allow direct text editing in conflict region +- [ ] Syntax highlighting preserved +- [ ] Real-time validation +- [ ] Button: "Edit Manually" +- [ ] Keyboard shortcut: `e` or `Ctrl+E` + +#### Accept Smart Suggestion +- [ ] If SDG or AI provides suggestion, allow one-click accept +- [ ] Display confidence score +- [ ] Button: "Accept Suggestion" +- [ ] Keyboard shortcut: `s` or `Ctrl+Enter` + +### 2. Action Bar UI + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Conflict 2 of 5 β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Keep Oursβ”‚Keep Theirsβ”‚Keep Bothβ”‚Edit (e) β”‚ β”‚ +β”‚ β”‚ (o) β”‚ (t) β”‚ (b) β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ Smart Suggestion (82% confidence): Keep Ours β”‚ +β”‚ [ Accept Suggestion (s) ] β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 3. Undo/Redo System + +**Requirements**: +- [ ] Unlimited undo/redo history (or configurable limit) +- [ ] Per-conflict undo/redo +- [ ] Global undo/redo across all conflicts +- [ ] Persist undo history during session +- [ ] Clear visual indication of undo state + +**UI**: +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ File: src/app.py [Undo (⌘Z)] [Redo (βŒ˜β‡§Z)] β”‚ +β”‚ β”‚ +β”‚ History: β”‚ +β”‚ βœ“ Conflict 1: Accepted Ours β”‚ +β”‚ βœ“ Conflict 2: Accepted Both β”‚ +β”‚ β†’ Conflict 3: Manual Edit (current) β”‚ +β”‚ ? Conflict 4: Unresolved β”‚ +β”‚ ? Conflict 5: Unresolved β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Keyboard Shortcuts**: +- Undo: `Ctrl+Z` (Win/Linux), `Cmd+Z` (Mac) +- Redo: `Ctrl+Shift+Z` or `Ctrl+Y` (Win/Linux), `Cmd+Shift+Z` (Mac) + +**Command Pattern Implementation**: +```cpp +class Command { +public: + virtual ~Command() = default; + virtual void execute() = 0; + virtual void undo() = 0; + virtual std::string description() const = 0; +}; + +class AcceptOursCommand : public Command { + ConflictID conflict_id; + std::string previous_state; + std::string new_state; + +public: + void execute() override { + previous_state = get_conflict_state(conflict_id); + set_conflict_state(conflict_id, resolve_with_ours()); + new_state = get_conflict_state(conflict_id); + } + + void undo() override { + set_conflict_state(conflict_id, previous_state); + } + + std::string description() const override { + return "Accept Ours for Conflict " + std::to_string(conflict_id); + } +}; + +class UndoRedoManager { + std::vector> undo_stack; + std::vector> redo_stack; + +public: + void execute_command(std::unique_ptr cmd) { + cmd->execute(); + undo_stack.push_back(std::move(cmd)); + redo_stack.clear(); // Clear redo stack on new command + } + + void undo() { + if (!undo_stack.empty()) { + auto cmd = std::move(undo_stack.back()); + undo_stack.pop_back(); + cmd->undo(); + redo_stack.push_back(std::move(cmd)); + } + } + + void redo() { + if (!redo_stack.empty()) { + auto cmd = std::move(redo_stack.back()); + redo_stack.pop_back(); + cmd->execute(); + undo_stack.push_back(std::move(cmd)); + } + } + + bool can_undo() const { return !undo_stack.empty(); } + bool can_redo() const { return !redo_stack.empty(); } + + std::vector get_history() const { + std::vector history; + for (const auto& cmd : undo_stack) { + history.push_back(cmd->description()); + } + return history; + } +}; +``` + +### 4. Visual Feedback + +- [ ] **Action confirmation**: Show toast/notification after action + - "βœ“ Conflict resolved with 'Ours'" + - "βœ“ Manual edit applied" + +- [ ] **Progress indicator**: Show how many conflicts resolved + - "3 of 5 conflicts resolved" + +- [ ] **Color changes**: Mark resolved conflicts differently + - Unresolved: Red border + - Resolved: Green border + +- [ ] **Animation**: Smooth transition when accepting resolution + - Fade out conflict markers + - Fade in resolved code + +### 5. Batch Actions + +For multiple similar conflicts: + +- [ ] **Accept All Ours**: Resolve all conflicts with "ours" +- [ ] **Accept All Theirs**: Resolve all conflicts with "theirs" +- [ ] **Accept All Smart Suggestions**: Auto-resolve with AI/SDG suggestions +- [ ] **Confirmation dialog**: "This will resolve 5 conflicts. Continue?" + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Batch Actions β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Accept All Ours β”‚ Accept All Theirsβ”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ [ Accept All Smart Suggestions ] β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 6. Conflict Status Tracking + +Track state of each conflict: + +```cpp +enum class ConflictState { + UNRESOLVED, // Not yet resolved + RESOLVED_OURS, // Resolved with "ours" + RESOLVED_THEIRS, // Resolved with "theirs" + RESOLVED_BOTH, // Resolved with "both" + RESOLVED_MANUAL, // Manually edited + RESOLVED_SUGGESTION, // Accepted smart suggestion +}; + +struct ConflictStatus { + ConflictID id; + ConflictState state; + std::string resolved_content; + time_t resolved_at; + std::string resolution_method; // "ours", "theirs", "both", "manual", "suggestion" +}; +``` + +### 7. Keyboard Shortcuts + +Full keyboard navigation: + +| Action | Shortcut | Alternative | +|--------|----------|-------------| +| Accept Ours | `o` | `Ctrl+1` | +| Accept Theirs | `t` | `Ctrl+2` | +| Accept Both | `b` | `Ctrl+3` | +| Manual Edit | `e` | `Ctrl+E` | +| Accept Suggestion | `s` | `Ctrl+Enter` | +| Next Conflict | `n` | `Ctrl+Down` | +| Previous Conflict | `p` | `Ctrl+Up` | +| Undo | `Ctrl+Z` | `u` | +| Redo | `Ctrl+Shift+Z` | `r` | +| Save | `Ctrl+S` | - | +| Cancel | `Esc` | `Ctrl+Q` | + +## Technical Design + +### Action Handler (C++ Backend) + +```cpp +class ConflictResolver { +public: + // Resolution actions + MergeResult accept_ours(ConflictID conflict_id); + MergeResult accept_theirs(ConflictID conflict_id); + MergeResult accept_both(ConflictID conflict_id, MergeOrder order); + MergeResult manual_edit(ConflictID conflict_id, const std::string& content); + MergeResult accept_suggestion(ConflictID conflict_id); + + // Batch actions + std::vector accept_all_ours(); + std::vector accept_all_theirs(); + std::vector accept_all_suggestions(); + + // State management + ConflictStatus get_status(ConflictID conflict_id); + std::vector get_all_statuses(); + bool is_all_resolved(); +}; +``` + +### UI Integration (Qt6 QML) + +```qml +Item { + id: conflictResolutionPanel + + property var undoRedoManager: UndoRedoManager {} + + Row { + spacing: 10 + + Button { + text: "Keep Ours (o)" + onClicked: resolveWithOurs() + } + + Button { + text: "Keep Theirs (t)" + onClicked: resolveWithTheirs() + } + + Button { + text: "Keep Both (b)" + onClicked: resolveWithBoth() + } + + Button { + text: "Edit (e)" + onClicked: enableManualEdit() + } + } + + Row { + Button { + text: "Undo (Ctrl+Z)" + enabled: undoRedoManager.canUndo + onClicked: undoRedoManager.undo() + } + + Button { + text: "Redo (Ctrl+Shift+Z)" + enabled: undoRedoManager.canRedo + onClicked: undoRedoManager.redo() + } + } + + // Keyboard shortcuts + Shortcut { + sequence: "o" + onActivated: resolveWithOurs() + } + + Shortcut { + sequence: "Ctrl+Z" + onActivated: undoRedoManager.undo() + } + + // ... other shortcuts +} +``` + +### UI Integration (Next.js React) + +```tsx +import { useState } from 'react'; +import { useHotkeys } from 'react-hotkeys-hook'; + +export default function ConflictResolutionPanel({ conflict, onResolve }) { + const [history, setHistory] = useState([]); + const [historyIndex, setHistoryIndex] = useState(-1); + + const resolveWithOurs = () => { + const command = { type: 'OURS', conflictId: conflict.id, previousState: conflict.state }; + executeCommand(command); + }; + + const undo = () => { + if (historyIndex >= 0) { + const command = history[historyIndex]; + undoCommand(command); + setHistoryIndex(historyIndex - 1); + } + }; + + const redo = () => { + if (historyIndex < history.length - 1) { + const command = history[historyIndex + 1]; + executeCommand(command); + setHistoryIndex(historyIndex + 1); + } + }; + + // Keyboard shortcuts + useHotkeys('o', resolveWithOurs); + useHotkeys('ctrl+z', undo); + useHotkeys('ctrl+shift+z', redo); + + return ( +
+
+ + + + +
+
+ + +
+
+ ); +} +``` + +## Implementation Steps + +### Phase 1: Basic Actions (1 week) +- [ ] Implement accept ours/theirs/both in backend +- [ ] Create action buttons in UI +- [ ] Add visual feedback (toasts) +- [ ] Test with simple conflicts + +### Phase 2: Manual Edit (1 week) +- [ ] Enable manual editing mode +- [ ] Preserve syntax highlighting during edit +- [ ] Real-time validation +- [ ] Save edited content + +### Phase 3: Undo/Redo (2 weeks) +- [ ] Implement command pattern +- [ ] Create undo/redo manager +- [ ] Integrate with UI +- [ ] Test complex scenarios + +### Phase 4: Keyboard Shortcuts (1 week) +- [ ] Implement all shortcuts +- [ ] Add shortcut hints in UI +- [ ] Handle conflicts between shortcuts +- [ ] Test on different platforms + +### Phase 5: Batch Actions (1 week) +- [ ] Implement batch resolution +- [ ] Add confirmation dialogs +- [ ] Progress indicators +- [ ] Test with many conflicts + +### Phase 6: Polish (1 week) +- [ ] Animations and transitions +- [ ] Accessibility improvements +- [ ] Error handling +- [ ] User testing + +## Acceptance Criteria + +- [ ] Can resolve conflicts with one click +- [ ] Undo/redo works correctly +- [ ] Keyboard shortcuts work on all platforms +- [ ] Manual editing preserves syntax +- [ ] Batch actions work for multiple conflicts +- [ ] Visual feedback is clear +- [ ] State persists during session +- [ ] Accessible (keyboard-only navigation) + +## Testing + +- [ ] Unit tests for each action +- [ ] Undo/redo edge cases +- [ ] Keyboard shortcut conflicts +- [ ] Performance with many conflicts +- [ ] Accessibility testing + +## Priority + +**HIGH** - Essential for basic usability + +## Estimated Effort + +7 weeks + +## Dependencies + +- Core UI components (Issue #TBD) +- Three-way merge algorithm βœ… + +## Related Issues + +- #TBD (Phase 1 completion) +- #TBD (Core UI components) +- #TBD (Keyboard navigation) + +## Success Metrics + +- 95% user satisfaction with actions +- <50ms action response time +- 100% undo/redo correctness +- 90% of users use keyboard shortcuts diff --git a/.github/issues/10-testing-quality.md b/.github/issues/10-testing-quality.md new file mode 100644 index 0000000..7332877 --- /dev/null +++ b/.github/issues/10-testing-quality.md @@ -0,0 +1,434 @@ +--- +title: "Phase 2.7: Comprehensive Testing & Quality Assurance" +labels: ["testing", "quality", "phase-2", "high-priority"] +assignees: [] +milestone: "Phase 2 - Intelligence & Usability" +--- + +## Overview + +Establish comprehensive testing infrastructure and quality assurance processes to ensure WizardMerge is reliable, performant, and correct. This includes unit tests, integration tests, performance benchmarks, and fuzzing. + +## Related Roadmap Section + +Phase 2.7 - Testing & Quality + +## Motivation + +As WizardMerge grows more complex with semantic merging, SDG analysis, and multi-platform support, we need: +- Confidence that changes don't break existing functionality +- Performance metrics to prevent regressions +- Edge case coverage to handle real-world scenarios +- Quality documentation and examples + +## Testing Strategy + +### 1. Unit Tests + +**Coverage Target**: >90% code coverage + +#### Backend (C++) +- [ ] **Three-way merge algorithm** + - Test all merge cases (clean merge, conflicts, auto-resolution) + - Test edge cases (empty files, binary files, large files) + - Test different line endings (LF, CRLF) + +- [ ] **Semantic mergers** + - JSON merger tests (objects, arrays, nested structures) + - YAML merger tests (comments, anchors, multi-document) + - XML merger tests (namespaces, attributes, DTD) + - Package file merger tests (version conflicts, dependencies) + +- [ ] **AST mergers** + - Python: imports, functions, classes + - JavaScript: ES6 modules, React components + - Java: classes, methods, annotations + - C++: includes, namespaces, templates + +- [ ] **SDG analysis** + - Dependency graph construction + - Edge classification + - Conflict analysis + - Suggestion generation + +- [ ] **Git integration** + - Git CLI operations + - Repository detection + - Branch operations + - PR/MR fetching + +**Framework**: Google Test (gtest) + +```cpp +// Example unit test +TEST(ThreeWayMergeTest, NonOverlappingChanges) { + ThreeWayMerge merger; + std::string base = "line1\nline2\nline3\n"; + std::string ours = "line1\nline2_modified\nline3\n"; + std::string theirs = "line1\nline2\nline3_modified\n"; + + auto result = merger.merge(base, ours, theirs); + + ASSERT_TRUE(result.success); + ASSERT_FALSE(result.has_conflicts); + EXPECT_EQ(result.merged_content, "line1\nline2_modified\nline3_modified\n"); +} +``` + +#### Frontends + +**Qt6 (C++)**: +- [ ] UI component tests +- [ ] QML integration tests +- [ ] Model-view tests + +**Framework**: Qt Test + +**Next.js (TypeScript)**: +- [ ] Component tests (React Testing Library) +- [ ] API client tests +- [ ] Integration tests +- [ ] E2E tests (Playwright or Cypress) + +**Framework**: Jest, React Testing Library, Playwright + +```typescript +// Example component test +import { render, screen, fireEvent } from '@testing-library/react'; +import ConflictPanel from './ConflictPanel'; + +test('renders conflict and resolves with "ours"', () => { + const conflict = { id: 1, ours: 'code A', theirs: 'code B' }; + const onResolve = jest.fn(); + + render(); + + const oursButton = screen.getByText('Keep Ours'); + fireEvent.click(oursButton); + + expect(onResolve).toHaveBeenCalledWith(1, 'ours'); +}); +``` + +### 2. Integration Tests + +Test interactions between components: + +- [ ] **Backend + Git** + - Clone repo, create branch, commit changes + - Fetch PR/MR data, apply merge, create branch + +- [ ] **Backend + Frontend** + - API calls from UI + - WebSocket updates + - File upload/download + +- [ ] **End-to-end scenarios** + - User resolves conflict via UI + - CLI resolves PR conflicts + - Batch resolution of multiple files + +**Framework**: +- C++: Integration test suite with real Git repos +- Next.js: Playwright for E2E testing + +```typescript +// Example E2E test (Playwright) +test('resolve conflict via web UI', async ({ page }) => { + await page.goto('http://localhost:3000'); + + // Upload conflicted file + await page.setInputFiles('input[type=file]', 'test_conflict.txt'); + + // Wait for merge analysis + await page.waitForSelector('.conflict-panel'); + + // Click "Keep Ours" + await page.click('button:has-text("Keep Ours")'); + + // Verify resolution + const resolved = await page.textContent('.merged-content'); + expect(resolved).toContain('code A'); + expect(resolved).not.toContain('<<<<<<<'); +}); +``` + +### 3. Performance Benchmarks + +**Goals**: +- Merge time: <100ms for files up to 10MB +- API response: <500ms for typical PRs +- UI rendering: <50ms for typical conflicts +- SDG analysis: <500ms for files up to 2000 lines + +**Benchmark Suite**: +```cpp +// Benchmark framework: Google Benchmark +static void BM_ThreeWayMerge_SmallFile(benchmark::State& state) { + std::string base = generate_file(100); // 100 lines + std::string ours = modify_lines(base, 10); + std::string theirs = modify_lines(base, 10); + + ThreeWayMerge merger; + for (auto _ : state) { + auto result = merger.merge(base, ours, theirs); + benchmark::DoNotOptimize(result); + } +} +BENCHMARK(BM_ThreeWayMerge_SmallFile); + +static void BM_ThreeWayMerge_LargeFile(benchmark::State& state) { + std::string base = generate_file(10000); // 10k lines + std::string ours = modify_lines(base, 100); + std::string theirs = modify_lines(base, 100); + + ThreeWayMerge merger; + for (auto _ : state) { + auto result = merger.merge(base, ours, theirs); + benchmark::DoNotOptimize(result); + } +} +BENCHMARK(BM_ThreeWayMerge_LargeFile); +``` + +**Metrics to Track**: +- Execution time (median, p95, p99) +- Memory usage +- CPU usage +- Throughput (files/second) + +**Regression Detection**: +- Run benchmarks on every commit +- Alert if performance degrades >10% +- Track performance over time + +### 4. Fuzzing + +Find edge cases and bugs with fuzz testing: + +**Targets**: +- [ ] Three-way merge algorithm +- [ ] JSON/YAML/XML parsers +- [ ] Git URL parsing +- [ ] API input validation + +**Framework**: libFuzzer, AFL++, or OSS-Fuzz + +```cpp +// Example fuzz target +extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size) { + std::string input(reinterpret_cast(data), size); + + ThreeWayMerge merger; + try { + // Try to crash the merger with random input + auto result = merger.merge(input, input, input); + } catch (...) { + // Catch exceptions to continue fuzzing + } + + return 0; +} +``` + +**Goals**: +- Find crashes and hangs +- Discover edge cases not covered by unit tests +- Improve input validation +- Run continuously in CI + +### 5. Test Data & Fixtures + +**Real-World Test Cases**: +- [ ] Collect conflicts from popular open-source projects +- [ ] Build test dataset with various conflict types +- [ ] Include edge cases (large files, binary files, unusual encodings) +- [ ] Categorize by difficulty (simple, medium, complex) + +**Test Repositories**: +``` +tests/ +β”œβ”€β”€ fixtures/ +β”‚ β”œβ”€β”€ conflicts/ +β”‚ β”‚ β”œβ”€β”€ simple/ +β”‚ β”‚ β”‚ β”œβ”€β”€ 01-non-overlapping.txt +β”‚ β”‚ β”‚ β”œβ”€β”€ 02-identical-changes.txt +β”‚ β”‚ β”‚ └── ... +β”‚ β”‚ β”œβ”€β”€ medium/ +β”‚ β”‚ β”‚ β”œβ”€β”€ 01-json-merge.json +β”‚ β”‚ β”‚ β”œβ”€β”€ 02-python-imports.py +β”‚ β”‚ β”‚ └── ... +β”‚ β”‚ └── complex/ +β”‚ β”‚ β”œβ”€β”€ 01-sdg-analysis-needed.cpp +β”‚ β”‚ β”œβ”€β”€ 02-multi-file-dependencies.zip +β”‚ β”‚ └── ... +β”‚ β”œβ”€β”€ repositories/ +β”‚ β”‚ β”œβ”€β”€ test-repo-1/ # Git repo for integration tests +β”‚ β”‚ β”œβ”€β”€ test-repo-2/ +β”‚ β”‚ └── ... +β”‚ └── api-responses/ +β”‚ β”œβ”€β”€ github-pr-123.json +β”‚ β”œβ”€β”€ gitlab-mr-456.json +β”‚ └── ... +``` + +### 6. Continuous Integration + +**CI Pipeline**: +```yaml +# .github/workflows/ci.yml +name: CI + +on: [push, pull_request] + +jobs: + test-backend: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Build backend + run: cd backend && ./build.sh + - name: Run unit tests + run: cd backend/build && ctest --output-on-failure + - name: Upload coverage + uses: codecov/codecov-action@v3 + + test-frontend-nextjs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: oven-sh/setup-bun@v1 + - name: Install dependencies + run: cd frontends/nextjs && bun install + - name: Run tests + run: cd frontends/nextjs && bun test + - name: E2E tests + run: cd frontends/nextjs && bun run test:e2e + + benchmark: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Build backend + run: cd backend && ./build.sh + - name: Run benchmarks + run: cd backend/build && ./benchmarks + - name: Check for regressions + run: python scripts/check_benchmark_regression.py + + fuzz: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Build fuzzer + run: cd backend && cmake -DFUZZING=ON . && make + - name: Run fuzzer (5 minutes) + run: ./backend/build/fuzzer -max_total_time=300 +``` + +### 7. Code Quality Tools + +- [ ] **Static Analysis**: clang-tidy, cppcheck +- [ ] **Code Coverage**: gcov, lcov (C++), Istanbul (JS) +- [ ] **Linting**: cpplint (C++), ESLint (JS), Prettier +- [ ] **Memory Safety**: Valgrind, AddressSanitizer +- [ ] **Security Scanning**: CodeQL (already in use βœ…) + +```bash +# Run all quality checks +./scripts/quality-check.sh +``` + +### 8. Documentation & Examples + +- [ ] **API Documentation**: Doxygen (C++), JSDoc (JS) +- [ ] **User Guide**: Step-by-step examples +- [ ] **Developer Guide**: Architecture, contributing +- [ ] **Example Conflicts**: Tutorials for common scenarios +- [ ] **Video Demos**: Screen recordings of key features + +## Implementation Steps + +### Phase 1: Unit Tests (3 weeks) +- [ ] Set up test frameworks +- [ ] Write unit tests for core algorithms +- [ ] Achieve 80% code coverage +- [ ] CI integration + +### Phase 2: Integration Tests (2 weeks) +- [ ] Set up test repositories +- [ ] Write integration tests +- [ ] E2E tests for frontends +- [ ] CI integration + +### Phase 3: Performance Benchmarks (1 week) +- [ ] Set up benchmark framework +- [ ] Write benchmark suite +- [ ] Baseline measurements +- [ ] Regression detection + +### Phase 4: Fuzzing (1 week) +- [ ] Set up fuzzing infrastructure +- [ ] Write fuzz targets +- [ ] Run continuous fuzzing +- [ ] Fix discovered issues + +### Phase 5: Quality Tools (1 week) +- [ ] Integrate static analysis +- [ ] Set up code coverage +- [ ] Memory safety checks +- [ ] CI integration + +### Phase 6: Documentation (2 weeks) +- [ ] Generate API docs +- [ ] Write user guide +- [ ] Create examples +- [ ] Video demos + +## Acceptance Criteria + +- [ ] >90% code coverage for backend +- [ ] >80% code coverage for frontends +- [ ] All unit tests pass +- [ ] All integration tests pass +- [ ] Performance benchmarks meet targets +- [ ] Zero crashes from fuzzing (after fixes) +- [ ] Documentation complete and accurate +- [ ] CI pipeline green on all commits + +## Priority + +**HIGH** - Quality and reliability are essential for user trust + +## Estimated Effort + +10 weeks (can be done in parallel with feature development) + +## Dependencies + +- Core features implemented (Phase 1 and 2) + +## Related Issues + +- #TBD (Phase 2 completion) +- #TBD (All feature implementation issues) + +## Success Metrics + +- 0 critical bugs in production +- <1% test failure rate +- 95% user satisfaction with stability +- Performance targets met consistently + +## Test Coverage Goals + +| Component | Coverage Target | +|-----------|-----------------| +| Three-way merge | 95% | +| Semantic mergers | 90% | +| AST mergers | 90% | +| SDG analysis | 85% | +| Git integration | 90% | +| API endpoints | 95% | +| UI components | 80% | +| Overall | 90% | diff --git a/.github/issues/README.md b/.github/issues/README.md new file mode 100644 index 0000000..bba20de --- /dev/null +++ b/.github/issues/README.md @@ -0,0 +1,179 @@ +# WizardMerge GitHub Issues + +This directory contains detailed GitHub issues for the WizardMerge project, covering project specifications and future feature implementations. + +## Overview + +These issue templates provide comprehensive documentation for: +- Project architecture and specifications +- Phase 1 (Foundation) features +- Phase 2 (Intelligence & Usability) features +- Phase 3 (Advanced Features) +- Testing and quality assurance + +## Issue Templates + +Located in `.github/ISSUE_TEMPLATE/`: + +1. **bug_report.yml** - Report bugs and issues +2. **feature_request.yml** - Suggest new features +3. **documentation.yml** - Improve documentation +4. **config.yml** - Configuration for issue templates + +## Feature Issues + +Located in `.github/issues/`: + +### Project Specification +- **01-project-specification.md** - Core architecture, components, and current status + +### Phase 1: Foundation +- **02-file-io-git-integration.md** - File I/O, Git repository integration, conflict parsing +- **07-core-ui-components.md** - Three-panel view, syntax highlighting, conflict navigation +- **09-conflict-resolution-actions.md** - Resolution actions, undo/redo, keyboard shortcuts + +### Phase 2: Intelligence & Usability +- **03-semantic-merge-structured-files.md** - JSON, YAML, XML, package file merging +- **04-ast-based-merging.md** - Language-aware merging (Python, JS, Java, C++) +- **05-sdg-analysis.md** - System Dependence Graph analysis (core research contribution) +- **06-multi-platform-support.md** - Bitbucket, Azure DevOps, Gitea/Forgejo support +- **10-testing-quality.md** - Comprehensive testing, benchmarks, fuzzing + +### Phase 3: Advanced Features +- **08-ai-assisted-merging.md** - ML models, natural language explanations, risk assessment + +## How to Use These Issues + +### For Project Planning + +1. **Review the project specification** (issue 01) to understand the overall architecture +2. **Prioritize issues** based on roadmap phases and dependencies +3. **Create GitHub issues** from these templates by copying content +4. **Track progress** using GitHub Projects or milestones + +### For Contributors + +1. **Choose an issue** that matches your skills and interests +2. **Read the full issue description** including implementation steps +3. **Check dependencies** - some issues require others to be completed first +4. **Ask questions** by commenting on the issue +5. **Submit PRs** that reference the issue number + +### For Creating GitHub Issues + +You can create issues directly from these templates: + +```bash +# Using GitHub CLI +gh issue create --title "Phase 2.1: Semantic Merge for Structured Files" \ + --body-file .github/issues/03-semantic-merge-structured-files.md \ + --label "enhancement,phase-2,semantic-merge,high-priority" \ + --milestone "Phase 2 - Intelligence & Usability" +``` + +Or copy-paste the content into GitHub's web interface. + +## Issue Metadata + +Each issue includes: +- **Title** - Clear, descriptive title +- **Labels** - For categorization (phase, priority, component) +- **Milestone** - Which roadmap phase it belongs to +- **Overview** - High-level description +- **Motivation** - Why this feature is important +- **Features** - Detailed list of sub-features +- **Technical Design** - Architecture and implementation approach +- **Implementation Steps** - Phased development plan +- **Acceptance Criteria** - Definition of done +- **Dependencies** - What must be completed first +- **Estimated Effort** - Time estimate +- **Priority** - HIGH/MEDIUM/LOW + +## Priority Levels + +- **HIGH**: Essential for the current phase, blocks other work +- **MEDIUM**: Important but can be deferred +- **LOW**: Nice to have, future enhancement + +## Dependencies + +Issues are organized with dependencies in mind: + +``` +Phase 1 (Foundation) +β”œβ”€ Three-way merge algorithm βœ… (completed) +β”œβ”€ Git CLI integration βœ… (completed) +β”œβ”€ 02: File I/O & Git integration +β”œβ”€ 07: Core UI components +└─ 09: Conflict resolution actions + +Phase 2 (Intelligence) +β”œβ”€ 03: Semantic merge (depends on: Phase 1) +β”œβ”€ 04: AST-based merging (depends on: 03) +β”œβ”€ 05: SDG analysis (depends on: 04) +β”œβ”€ 06: Multi-platform support (depends on: Phase 1) +└─ 10: Testing & quality (depends on: all Phase 2) + +Phase 3 (Advanced) +└─ 08: AI-assisted merging (depends on: 05) +``` + +## Roadmap Alignment + +These issues align with the project roadmap in `ROADMAP.md`: + +- **Phase 1 (0-3 months)**: Foundation - Issues 02, 07, 09 +- **Phase 2 (3-6 months)**: Intelligence - Issues 03, 04, 05, 06, 10 +- **Phase 3 (6-12 months)**: Advanced - Issue 08 + +## Contributing + +See each issue for: +- **Implementation steps** - Detailed development plan +- **Technical design** - Architecture and code examples +- **Acceptance criteria** - How to know when it's done +- **Test cases** - What to test + +## Issue Labels + +Common labels used: +- `enhancement` - New feature +- `bug` - Bug report +- `documentation` - Documentation improvement +- `phase-1`, `phase-2`, `phase-3` - Roadmap phase +- `high-priority`, `medium-priority`, `low-priority` - Priority level +- Component labels: `semantic-merge`, `ast-merge`, `sdg-analysis`, `ui-ux`, `git-integration`, `ai-ml`, `testing` + +## Creating Issues from Templates + +### Option 1: GitHub Web Interface +1. Go to Issues β†’ New Issue +2. Select template (bug report, feature request, or documentation) +3. Fill in the form +4. Submit + +### Option 2: Copy from Issue Files +1. Navigate to `.github/issues/` +2. Open the issue markdown file +3. Copy content to new GitHub issue +4. Set labels and milestone + +### Option 3: GitHub CLI +```bash +# Create issue from file +gh issue create \ + --title "Issue Title" \ + --body-file .github/issues/XX-issue-name.md \ + --label "label1,label2" \ + --milestone "Milestone Name" +``` + +## Questions? + +- Open a discussion in GitHub Discussions +- Comment on related issues +- Reach out to maintainers + +## License + +These issue templates are part of the WizardMerge project and follow the same license.