Add tests, update TLA+ spec, and add comprehensive build documentation

Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>

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

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 <gtest/gtest.h>
+
+using namespace wizardmerge::merge;
+
+/**
+ * Test basic three-way merge with no conflicts
+ */
+TEST(ThreeWayMergeTest, NoConflicts) {
+    std::vector<std::string> base = {"line1", "line2", "line3"};
+    std::vector<std::string> ours = {"line1", "line2_modified", "line3"};
+    std::vector<std::string> 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<std::string> base = {"line1", "line2", "line3"};
+    std::vector<std::string> ours = {"line1", "line2_ours", "line3"};
+    std::vector<std::string> 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<std::string> base = {"line1", "line2", "line3"};
+    std::vector<std::string> ours = {"line1", "line2_same", "line3"};
+    std::vector<std::string> 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<std::string> base = {"line1", "line2", "line3"};
+    std::vector<std::string> ours = {"line1", "line2", "line3"};
+    std::vector<std::string> 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<std::string> base = {"line1", "line2", "line3"};
+    std::vector<std::string> ours = {"line1", "line2_changed", "line3"};
+    std::vector<std::string> 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<std::string> base = {"line1", "line2", "line3"};
+    std::vector<std::string> ours = {"line1", "  line2_changed  ", "line3"};
+    std::vector<std::string> 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<std::string> base = {};
+    std::vector<std::string> ours = {};
+    std::vector<std::string> 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<std::string> base = {"line1"};
+    std::vector<std::string> ours = {"line1", "line2"};
+    std::vector<std::string> theirs = {"line1"};
+    
+    auto result = three_way_merge(base, ours, theirs);
+    
+    EXPECT_FALSE(result.has_conflicts());
+    ASSERT_EQ(result.merged_lines.size(), 2);
+}

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