Merge pull request steam-bell-92#1335 from ruhelamahi7-code/feature/merge-sort-visualizer

Add: Merge Sort Visualizer with Python CLI, web visualizer, tests, an…

Author: steam-bell-92

math/Merge-Sort/Merge-Sort.py

@@ -0,0 +1,115 @@
+import sys
+import os
+
+# Add project root to sys.path
+if "__file__" in globals():
+    sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")))
+else:
+    sys.path.append(os.path.abspath(os.getcwd()))
+
+import importlib.util
+
+# Load validation module directly to avoid broken package __init__.py
+_val_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "scripts", "validation.py"))
+_val_spec = importlib.util.spec_from_file_location("validation", _val_path)
+_val_mod = importlib.util.module_from_spec(_val_spec)
+_val_spec.loader.exec_module(_val_mod)
+get_choice = _val_mod.get_choice
+get_int_list = _val_mod.get_int_list
+
+
+def merge_sort(arr: list[int], reverse: bool = False) -> list[int]:
+    """Sorts a list of integers using the Merge Sort algorithm.
+
+    Args:
+        arr: The list of integers to sort.
+        reverse: If True, sorts in descending order. Otherwise, ascending.
+
+    Returns:
+        A new sorted list.
+    """
+    # Base case: a list of 0 or 1 elements is already sorted
+    if len(arr) <= 1:
+        return arr.copy()
+
+    # Divide: split the list into two halves
+    mid = len(arr) // 2
+    left = merge_sort(arr[:mid], reverse)
+    right = merge_sort(arr[mid:], reverse)
+
+    # Conquer: merge the two sorted halves
+    return merge(left, right, reverse)
+
+
+def merge(left: list[int], right: list[int], reverse: bool = False) -> list[int]:
+    """Merges two sorted lists into one sorted list.
+
+    Args:
+        left: The left sorted list.
+        right: The right sorted list.
+        reverse: If True, merges in descending order. Otherwise, ascending.
+
+    Returns:
+        A single merged and sorted list.
+    """
+    result = []
+    i = 0
+    j = 0
+
+    while i < len(left) and j < len(right):
+        if not reverse and left[i] <= right[j]:
+            result.append(left[i])
+            i += 1
+        elif reverse and left[i] >= right[j]:
+            result.append(left[i])
+            i += 1
+        else:
+            result.append(right[j])
+            j += 1
+
+    # Append any remaining elements
+    result.extend(left[i:])
+    result.extend(right[j:])
+    return result
+
+
+def main() -> None:
+    print("=" * 50)
+    print("🔀 MERGE SORT INTERACTIVE TOOL 🔀")
+    print("=" * 50)
+    print("Sort a list of numbers in Ascending or Descending order.\n")
+
+    while True:
+        print("=" * 50)
+        arr = get_int_list(
+            prompt="➡️  Enter numbers to sort separated by spaces (e.g., 64 34 25): ",
+            error_empty="❌ Error: Input cannot be empty!",
+            error_invalid="❌ Error: Please enter valid integers only."
+        )
+
+        print("\nChoose sorting order:")
+        print("1️⃣  Ascending")
+        print("2️⃣  Descending")
+        order_choice = get_choice(
+            prompt="🎯 Enter your choice (1 or 2): ",
+            choices=["1", "2"],
+            error_invalid="❌ Invalid sorting choice! Please select 1 or 2."
+        )
+
+        reverse = (order_choice == "2")
+        sorted_arr = merge_sort(arr, reverse)
+
+        print(f"\n📊 Original list: {arr}")
+        if reverse:
+            print(f"✅ Sorted list (Descending): {sorted_arr}")
+        else:
+            print(f"✅ Sorted list (Ascending): {sorted_arr}")
+
+        again = input("\n🔄 Do you want to sort another list? (y/n): ").strip().lower()
+        if again != 'y':
+            print("\n👋 Thanks for using Merge Sort Tool! Goodbye!\n")
+            break
+
+
+if __name__ == "__main__":
+    main()

tests/test_merge_sort.py

@@ -0,0 +1,99 @@
+import unittest
+from unittest.mock import patch
+import io
+import os
+import importlib.util
+
+# Absolute path to Merge-Sort.py
+file_path = os.path.join(
+    os.path.dirname(__file__), "..",
+    "math", "Merge-Sort", "Merge-Sort.py"
+)
+file_path = os.path.abspath(file_path)
+
+# Load module dynamically
+spec = importlib.util.spec_from_file_location("merge_sort_module", file_path)
+merge_sort_module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(merge_sort_module)
+
+merge_sort = merge_sort_module.merge_sort
+merge = merge_sort_module.merge
+main = merge_sort_module.main
+
+
+class TestMergeSort(unittest.TestCase):
+
+    def test_merge_sort_ascending(self):
+        self.assertEqual(merge_sort([64, 34, 25, 12, 22, 11, 90]), [11, 12, 22, 25, 34, 64, 90])
+        self.assertEqual(merge_sort([5, 1, 4, 2, 8]), [1, 2, 4, 5, 8])
+
+    def test_merge_sort_descending(self):
+        self.assertEqual(merge_sort([64, 34, 25, 12, 22, 11, 90], reverse=True), [90, 64, 34, 25, 22, 12, 11])
+        self.assertEqual(merge_sort([5, 1, 4, 2, 8], reverse=True), [8, 5, 4, 2, 1])
+
+    def test_merge_sort_empty_and_single_item(self):
+        self.assertEqual(merge_sort([]), [])
+        self.assertEqual(merge_sort([42]), [42])
+
+    def test_merge_sort_negative_integers(self):
+        self.assertEqual(merge_sort([-5, -1, -10, 0, 5]), [-10, -5, -1, 0, 5])
+        self.assertEqual(merge_sort([-5, -1, -10, 0, 5], reverse=True), [5, 0, -1, -5, -10])
+
+    def test_merge_sort_already_sorted(self):
+        self.assertEqual(merge_sort([1, 2, 3, 4, 5]), [1, 2, 3, 4, 5])
+        self.assertEqual(merge_sort([5, 4, 3, 2, 1], reverse=True), [5, 4, 3, 2, 1])
+
+    def test_merge_sort_with_duplicates(self):
+        self.assertEqual(merge_sort([5, 3, 8, 3, 9, 1, 5]), [1, 3, 3, 5, 5, 8, 9])
+
+    def test_merge_sort_does_not_mutate_original(self):
+        original = [5, 3, 1, 4, 2]
+        original_copy = original.copy()
+        merge_sort(original)
+        self.assertEqual(original, original_copy)
+
+    def test_merge_ascending(self):
+        self.assertEqual(merge([1, 3, 5], [2, 4, 6]), [1, 2, 3, 4, 5, 6])
+
+    def test_merge_descending(self):
+        self.assertEqual(merge([5, 3, 1], [6, 4, 2], reverse=True), [6, 5, 4, 3, 2, 1])
+
+    def test_merge_empty_left(self):
+        self.assertEqual(merge([], [1, 2, 3]), [1, 2, 3])
+
+    def test_merge_empty_right(self):
+        self.assertEqual(merge([1, 2, 3], []), [1, 2, 3])
+
+    @patch('builtins.input')
+    @patch('sys.stdout', new_callable=io.StringIO)
+    def test_main_flow_ascending(self, mock_stdout, mock_input):
+        mock_input.side_effect = ["64 34 25", "1", "n"]
+        main()
+        output = mock_stdout.getvalue()
+        self.assertIn("Original list: [64, 34, 25]", output)
+        self.assertIn("Sorted list (Ascending): [25, 34, 64]", output)
+
+    @patch('builtins.input')
+    @patch('sys.stdout', new_callable=io.StringIO)
+    def test_main_flow_descending(self, mock_stdout, mock_input):
+        mock_input.side_effect = ["64 34 25", "2", "n"]
+        main()
+        output = mock_stdout.getvalue()
+        self.assertIn("Original list: [64, 34, 25]", output)
+        self.assertIn("Sorted list (Descending): [64, 34, 25]", output)
+
+    @patch('builtins.input')
+    @patch('sys.stdout', new_callable=io.StringIO)
+    def test_main_flow_invalid_inputs(self, mock_stdout, mock_input):
+        mock_input.side_effect = ["", "64 abc 25", "64 34 25", "3", "64 34 25", "1", "y", "12 11", "2", "n"]
+        main()
+        output = mock_stdout.getvalue()
+        self.assertIn("Error: Input cannot be empty!", output)
+        self.assertIn("Error: Please enter valid integers only.", output)
+        self.assertIn("Invalid sorting choice! Please select 1 or 2.", output)
+        self.assertIn("Sorted list (Ascending): [25, 34, 64]", output)
+        self.assertIn("Sorted list (Descending): [12, 11]", output)
+
+
+if __name__ == '__main__':
+    unittest.main()

web-app/assets/banners/merge-sort.webp

@@ -563,6 +563,26 @@ def draw_o(ox, oy):
         for i, h in enumerate(bar_heights):
             x = 230 + i * 50
             v_draw.rectangle([x, 320 - h, x + 30, 320], fill=color_accent)
+    elif "merge sort" in n_lower:
+        # Divide and conquer visualization - splitting bars
+        cx, cy = 400, 225
+        # Draw bars being split into halves
+        bar_vals = [4, 2, 6, 1, 5, 3, 7]
+        bar_w = 50
+        total_w = len(bar_vals) * (bar_w + 8)
+        start_x = cx - total_w // 2
+        for i, val in enumerate(bar_vals):
+            x = start_x + i * (bar_w + 8)
+            h = val * 25
+            y = cy + 80 - h
+            color = color_accent if i < len(bar_vals) // 2 else (255, 255, 255, 180)
+            v_draw.rounded_rectangle([x, y, x + bar_w, cy + 80], radius=6, fill=color)
+        # Dividing line in the middle
+        mid_x = start_x + (len(bar_vals) // 2) * (bar_w + 8) - 4
+        v_draw.line([(mid_x, cy - 60), (mid_x, cy + 90)], fill=(239, 68, 68), width=3)
+        # Arrow showing merge direction
+        v_draw.line([(cx - 80, cy - 80), (cx + 80, cy - 80)], fill=color_accent, width=2)
+        v_draw.polygon([(cx + 80, cy - 85), (cx + 95, cy - 80), (cx + 80, cy - 75)], fill=color_accent)
     elif "tsp" in n_lower or "salesperson" in n_lower:
         # Nodes connected by a path
         nodes = [(250, 150), (450, 100), (550, 250), (400, 350), (200, 300)]
@@ -668,6 +688,7 @@ def draw_o(ox, oy):
     ("Binary Search", "math", "binary-search.webp"),
     ("Bubble Sort", "math", "bubble-sort.webp"),
     ("Quick Sort", "math", "quick-sort.webp"),
+    ("Merge Sort", "math", "merge-sort.webp"),
     ("Tower of Hanoi", "math", "tower-of-hanoi.webp"),
     ("Matrix Calculator", "math", "matrix-calculator.webp"),
     ("Fourier Series", "math", "fourier-series.webp"),

web-app/generate_banners.py

@@ -866,6 +866,7 @@ <h3>Legal</h3>
     <script defer src="js/projects/binary-search.js"></script>
     <script defer src="js/projects/bubble-sort.js"></script>
     <script defer src="js/projects/quick-sort.js"></script>
+    <script defer src="js/projects/merge-sort.js"></script>
     <script defer src="js/projects/hangman.js"></script>
     <script defer src="js/projects/flames.js"></script>
     <script defer src="js/projects/fibonacci.js"></script>
@@ -1082,6 +1083,13 @@ <h3>Legal</h3>
             desc: "Visualize quick sort algorithm with pivot partitioning",
             tags: "math,algorithm",
           },
+          {
+            project: "merge-sort",
+            title: "Merge Sort",
+            category: "math",
+            desc: "Visualize merge sort algorithm with divide-and-conquer approach",
+            tags: "math,algorithm",
+          },
           {
             project: "fibonacci",
             title: "Fibonacci",

web-app/index.html

@@ -32,6 +32,7 @@ function getProjectHTML(projectName) {
         'bubble-sort': getBubbleSortHTML(),
         'quick-sort': getQuickSortHTML(),
         'fourier-series': getFourierSeriesHTML(),
+        'merge-sort': getMergeSortHTML(),
         'pathfinding-visualizer': getPathfindingVisualizerHTML(),
         'tsp-visualizer': getTspVisualizerHTML()
     };
@@ -67,6 +68,7 @@ function initializeProject(projectName) {
         'reverse-hangman': initReverseHangman,
         'budget-tracker': initBudgetTracker,
         'fourier-series': initFourierSeries,
+        'merge-sort': initMergeSort,
         'pathfinding-visualizer': initPathfindingVisualizer,
         'tsp-visualizer': initTspVisualizer
     };
@@ -1869,6 +1871,15 @@ const projectInstructions = {
     "Smaller elements go left, larger go right",
     "Process repeats until fully sorted"
   ]
+},
+"merge-sort": {
+  title: "🔀 How Merge Sort Works",
+  steps: [
+    "Enter an array of numbers",
+    "Array is divided into two halves",
+    "Each half is recursively sorted",
+    "Sorted halves are merged back together"
+  ]
 },
   "tower-of-hanoi": {
     title: "🗼 How to Solve Tower of Hanoi",
@@ -3202,6 +3213,7 @@ function initializeProject(projectName) {
     "binary-search": "initBinarySearch",
     "bubble-sort": "initBubbleSort",
     "quick-sort": "initQuickSort",
+    "merge-sort": "initMergeSort",
     "progression-recognizer": "initProgressionRecognizer",
     "pascal-triangle": "initPascalTriangle",
     armstrong: "initArmstrong",