WizardMerge/.github/issues/01-project-specification.md

title, labels, assignees

title	labels	assignees
Project Specification: WizardMerge Core Architecture and Features	documentation project-spec high-priority

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

• Define core architecture
• Implement three-way merge algorithm
• Add GitHub/GitLab PR integration
• 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.