mirror of
https://github.com/johndoe6345789/WizardMerge.git
synced 2026-04-24 13:44:55 +00:00
137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
---
|
|
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.
|