diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..7bd84eb --- /dev/null +++ b/BUILD.md @@ -0,0 +1,164 @@ +# WizardMerge Build and Development Guide + +This guide provides instructions for building and developing WizardMerge across all components. + +## Architecture Overview + +WizardMerge uses a multi-component architecture: + +``` +WizardMerge/ +├── backend/ # C++ core merge engine (Conan + Ninja) +├── frontend/ # Next.js web UI (bun) +├── spec/ # TLA+ formal specification +├── docs/ # Research paper and documentation +└── ROADMAP.md # Development roadmap +``` + +## Quick Start + +### C++ Backend + +The backend implements the core three-way merge algorithm. + +**Prerequisites:** +- C++17 compiler (GCC 7+, Clang 6+, MSVC 2017+) +- CMake 3.15+ +- Ninja build tool +- Conan package manager + +**Build:** +```bash +cd backend +./build.sh +``` + +**Usage:** +```bash +./build/wizardmerge-cli base.txt ours.txt theirs.txt output.txt +``` + +See [backend/README.md](backend/README.md) for details. + +### TypeScript Frontend + +The frontend provides a web-based UI for conflict resolution. + +**Prerequisites:** +- bun (JavaScript runtime and package manager) + +**Setup:** +```bash +cd frontend +bun install +``` + +**Development:** +```bash +bun run dev +``` + +Visit http://localhost:3000 + +See [frontend/README.md](frontend/README.md) for details. + +## Development Workflow + +### Making Changes + +1. **Backend (C++)**: Edit files in `backend/src/` and `backend/include/` +2. **Frontend (TypeScript)**: Edit files in `frontend/app/` +3. **Tests**: Add tests in `backend/tests/` for C++ changes +4. **Documentation**: Update relevant README files + +### Building + +```bash +# C++ backend +cd backend && ./build.sh + +# TypeScript frontend +cd frontend && bun run build +``` + +### Testing + +```bash +# C++ backend tests (requires GTest) +cd backend/build && ninja test + +# TypeScript frontend tests +cd frontend && bun test +``` + +## Project Standards + +### C++ (Backend) +- **Standard**: C++17 +- **Build System**: CMake + Ninja +- **Package Manager**: Conan +- **Coding Style**: Follow backend code conventions +- **Documentation**: Doxygen-style comments + +### TypeScript (Frontend) +- **Runtime**: bun +- **Framework**: Next.js 14 +- **Language**: TypeScript with strict mode +- **Coding Style**: Follow frontend code conventions +- **Package Manager**: bun + +## Roadmap Progress + +Track development progress in [ROADMAP.md](ROADMAP.md). + +**Phase 1 (Foundation):** ✓ In Progress +- [x] Three-way merge algorithm +- [x] Conflict detection +- [x] Auto-resolution patterns +- [ ] Git integration +- [ ] File I/O module + +**Phase 2 (Intelligence):** Planned +- Semantic merge +- Enhanced visualization +- Code intelligence + +**Phase 3 (Advanced):** Future +- AI-assisted merging +- Plugin ecosystem +- Performance optimizations + +## Contributing + +1. Check [ROADMAP.md](ROADMAP.md) for planned features +2. Create a branch for your changes +3. Write tests for new functionality +4. Update documentation +5. Submit a pull request + +## Research Foundation + +WizardMerge is based on research from The University of Hong Kong: +- 28.85% reduction in conflict resolution time +- Merge suggestions for 70%+ of conflict blocks +- Dependency analysis at text and LLVM-IR levels + +See [docs/PAPER.md](docs/PAPER.md) for the complete research paper. + +## Formal Specification + +The merge algorithm is formally specified in TLA+: +- [spec/WizardMergeSpec.tla](spec/WizardMergeSpec.tla) + +The specification defines the dependency-aware merge logic including: +- Vertex and edge classification +- Safe vs. violated edges +- Conflict detection rules + +## License + +See [LICENSE](LICENSE) for details. + +## Related Projects + +- [mergebot](https://github.com/JohnDoe6345789/mergebot) - Companion automation tool diff --git a/backend/tests/test_three_way_merge.cpp b/backend/tests/test_three_way_merge.cpp new file mode 100644 index 0000000..35bc27e --- /dev/null +++ b/backend/tests/test_three_way_merge.cpp @@ -0,0 +1,125 @@ +/** + * @file test_three_way_merge.cpp + * @brief Unit tests for three-way merge algorithm + */ + +#include "wizardmerge/merge/three_way_merge.h" +#include + +using namespace wizardmerge::merge; + +/** + * Test basic three-way merge with no conflicts + */ +TEST(ThreeWayMergeTest, NoConflicts) { + std::vector base = {"line1", "line2", "line3"}; + std::vector ours = {"line1", "line2_modified", "line3"}; + std::vector theirs = {"line1", "line2", "line3_modified"}; + + auto result = three_way_merge(base, ours, theirs); + + EXPECT_FALSE(result.has_conflicts()); + ASSERT_EQ(result.merged_lines.size(), 3); + EXPECT_EQ(result.merged_lines[0].content, "line1"); + EXPECT_EQ(result.merged_lines[1].content, "line2_modified"); + EXPECT_EQ(result.merged_lines[2].content, "line3_modified"); +} + +/** + * Test three-way merge with conflicts + */ +TEST(ThreeWayMergeTest, WithConflicts) { + std::vector base = {"line1", "line2", "line3"}; + std::vector ours = {"line1", "line2_ours", "line3"}; + std::vector theirs = {"line1", "line2_theirs", "line3"}; + + auto result = three_way_merge(base, ours, theirs); + + EXPECT_TRUE(result.has_conflicts()); + EXPECT_EQ(result.conflicts.size(), 1); +} + +/** + * Test identical changes from both sides + */ +TEST(ThreeWayMergeTest, IdenticalChanges) { + std::vector base = {"line1", "line2", "line3"}; + std::vector ours = {"line1", "line2_same", "line3"}; + std::vector theirs = {"line1", "line2_same", "line3"}; + + auto result = three_way_merge(base, ours, theirs); + + EXPECT_FALSE(result.has_conflicts()); + EXPECT_EQ(result.merged_lines[1].content, "line2_same"); +} + +/** + * Test base equals ours, theirs changed + */ +TEST(ThreeWayMergeTest, BaseEqualsOurs) { + std::vector base = {"line1", "line2", "line3"}; + std::vector ours = {"line1", "line2", "line3"}; + std::vector theirs = {"line1", "line2_changed", "line3"}; + + auto result = three_way_merge(base, ours, theirs); + + EXPECT_FALSE(result.has_conflicts()); + EXPECT_EQ(result.merged_lines[1].content, "line2_changed"); +} + +/** + * Test base equals theirs, ours changed + */ +TEST(ThreeWayMergeTest, BaseEqualsTheirs) { + std::vector base = {"line1", "line2", "line3"}; + std::vector ours = {"line1", "line2_changed", "line3"}; + std::vector theirs = {"line1", "line2", "line3"}; + + auto result = three_way_merge(base, ours, theirs); + + EXPECT_FALSE(result.has_conflicts()); + EXPECT_EQ(result.merged_lines[1].content, "line2_changed"); +} + +/** + * Test auto-resolve whitespace differences + */ +TEST(AutoResolveTest, WhitespaceOnly) { + std::vector base = {"line1", "line2", "line3"}; + std::vector ours = {"line1", " line2_changed ", "line3"}; + std::vector theirs = {"line1", "line2_changed", "line3"}; + + auto result = three_way_merge(base, ours, theirs); + auto resolved = auto_resolve(result); + + // Whitespace-only differences should be auto-resolved + EXPECT_LT(resolved.conflicts.size(), result.conflicts.size()); +} + +/** + * Test empty files + */ +TEST(ThreeWayMergeTest, EmptyFiles) { + std::vector base = {}; + std::vector ours = {}; + std::vector theirs = {}; + + auto result = three_way_merge(base, ours, theirs); + + EXPECT_FALSE(result.has_conflicts()); + EXPECT_EQ(result.merged_lines.size(), 0); +} + +/** + * Test one side adds lines + */ +TEST(ThreeWayMergeTest, OneSideAddsLines) { + std::vector base = {"line1"}; + std::vector ours = {"line1", "line2"}; + std::vector theirs = {"line1"}; + + auto result = three_way_merge(base, ours, theirs); + + EXPECT_FALSE(result.has_conflicts()); + ASSERT_EQ(result.merged_lines.size(), 2); +} diff --git a/spec/WizardMergeSpec.tla b/spec/WizardMergeSpec.tla index 12dbef2..3111cef 100644 --- a/spec/WizardMergeSpec.tla +++ b/spec/WizardMergeSpec.tla @@ -1,6 +1,34 @@ ------------------------------- MODULE WizardMergeSpec ------------------------------- EXTENDS Naturals, FiniteSets +(* + Implementation Status (as of December 2024): + + This formal specification describes the dependency-aware merge algorithm that + WizardMerge aims to implement. The current implementation status is: + + IMPLEMENTED (Phase 1.1): + - Basic three-way merge algorithm (C++ backend) + - Line-level conflict detection + - Auto-resolution for common patterns: + * Non-overlapping changes + * Identical changes from both sides + * Whitespace-only differences + - Command-line interface (wizardmerge-cli) + + NOT YET IMPLEMENTED (Future phases): + - Dependency graph construction (SDG analysis) + - LLVM-IR level analysis + - Edge classification (safe vs. violated) + - Fine-grained DCB (Definition-Code Block) tracking + - Mirror mapping and matching + + The current implementation in backend/src/merge/three_way_merge.cpp provides + a foundation for the full dependency-aware algorithm specified here. Future + phases will enhance it with the SDG analysis, edge classification, and + dependency-aware conflict resolution described in this specification. +*) + (* High-level intent