feat: Add BreadthFirstSearch algorithm with proper structure and tests

- Removed incorrectly placed .class files and Main.java from root
- Added BreadthFirstSearch.java with proper package structure
- Implemented generic and integer-based BFS traversal methods
- Added comprehensive test coverage in BreadthFirstSearchTest.java
- Fixed bug in original BFS where 'src' was used instead of 'current' node
- Follows project conventions and coding standards

Fixes TheAlgorithms#7158

Co-authored-by: Divyansh1802 <divyanshupadhyay1802@gmail.com>

Author: prashantdubeypng

Graph$Node.class

@@ -0,0 +1,182 @@
+package com.thealgorithms.datastructures.graphs;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Map;
+import java.util.Queue;
+import java.util.Set;
+
+/**
+ * Breadth-First Search (BFS) algorithm for graph traversal.
+ *
+ * <p>
+ * BFS is a graph traversal algorithm that explores all vertices at the present
+ * depth level before moving on to vertices at the next depth level. It uses a
+ * queue
+ * data structure to keep track of vertices to visit.
+ *
+ * <p>
+ * Time Complexity: O(V + E) where V is the number of vertices and E is the
+ * number of edges.
+ * Space Complexity: O(V) for the visited set and queue.
+ *
+ * <p>
+ * References:
+ * <ul>
+ * <li>https://en.wikipedia.org/wiki/Breadth-first_search</li>
+ * </ul>
+ *
+ * @author Divyansh1802
+ * @author prashantdubeypng (fixes and refactoring)
+ */
+public final class BreadthFirstSearch {
+
+    private BreadthFirstSearch() {
+        // Utility class; do not instantiate.
+    }
+
+    /**
+     * Performs BFS traversal on a graph represented as an adjacency list.
+     *
+     * @param adjacencyList the graph represented as a map from vertex to list of
+     *                      neighbors
+     * @param source        the starting vertex for traversal
+     * @param <T>           the type of vertices in the graph
+     * @return a list of vertices in BFS order starting from the source
+     * @throws IllegalArgumentException if source is null or not in the graph
+     */
+    public static <T> List<T> bfs(Map<T, List<T>> adjacencyList, T source) {
+        if (source == null) {
+            throw new IllegalArgumentException("Source vertex cannot be null");
+        }
+        if (adjacencyList == null || !adjacencyList.containsKey(source)) {
+            throw new IllegalArgumentException("Source vertex must exist in the graph");
+        }
+
+        List<T> result = new ArrayList<>();
+        Set<T> visited = new HashSet<>();
+        Queue<T> queue = new LinkedList<>();
+
+        queue.offer(source);
+        visited.add(source);
+
+        while (!queue.isEmpty()) {
+            T current = queue.poll();
+            result.add(current);
+
+            List<T> neighbors = adjacencyList.get(current);
+            if (neighbors != null) {
+                for (T neighbor : neighbors) {
+                    if (!visited.contains(neighbor)) {
+                        visited.add(neighbor);
+                        queue.offer(neighbor);
+                    }
+                }
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Performs BFS traversal on a graph represented using integer vertices.
+     *
+     * @param adjacencyList the graph represented as a list of lists of neighbors
+     * @param numVertices   the number of vertices in the graph
+     * @param source        the starting vertex for traversal (0-indexed)
+     * @return a list of vertices in BFS order starting from the source
+     * @throws IllegalArgumentException if source is out of bounds
+     */
+    public static List<Integer> bfs(List<List<Integer>> adjacencyList, int numVertices, int source) {
+        if (source < 0 || source >= numVertices) {
+            throw new IllegalArgumentException("Source vertex is out of bounds");
+        }
+        if (adjacencyList == null) {
+            throw new IllegalArgumentException("Adjacency list cannot be null");
+        }
+
+        List<Integer> result = new ArrayList<>();
+        boolean[] visited = new boolean[numVertices];
+        Queue<Integer> queue = new LinkedList<>();
+
+        queue.offer(source);
+        visited[source] = true;
+
+        while (!queue.isEmpty()) {
+            int current = queue.poll();
+            result.add(current);
+
+            if (current < adjacencyList.size()) {
+                List<Integer> neighbors = adjacencyList.get(current);
+                if (neighbors != null) {
+                    for (int neighbor : neighbors) {
+                        if (neighbor >= 0 && neighbor < numVertices && !visited[neighbor]) {
+                            visited[neighbor] = true;
+                            queue.offer(neighbor);
+                        }
+                    }
+                }
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Creates an adjacency list graph from edges.
+     *
+     * @param numVertices the number of vertices
+     * @param edges       array of edges where each edge is {from, to}
+     * @param undirected  if true, adds edges in both directions
+     * @return the adjacency list representation of the graph
+     */
+    public static List<List<Integer>> createGraph(int numVertices, int[][] edges, boolean undirected) {
+        List<List<Integer>> graph = new ArrayList<>();
+        for (int i = 0; i < numVertices; i++) {
+            graph.add(new ArrayList<>());
+        }
+
+        for (int[] edge : edges) {
+            if (edge.length >= 2) {
+                int from = edge[0];
+                int to = edge[1];
+                if (from >= 0 && from < numVertices && to >= 0 && to < numVertices) {
+                    graph.get(from).add(to);
+                    if (undirected) {
+                        graph.get(to).add(from);
+                    }
+                }
+            }
+        }
+
+        return graph;
+    }
+
+    /**
+     * Creates a Map-based adjacency list from string vertices.
+     *
+     * @param edges      array of edges where each edge is {from, to}
+     * @param undirected if true, adds edges in both directions
+     * @return the adjacency list representation as a Map
+     */
+    public static Map<String, List<String>> createStringGraph(String[][] edges, boolean undirected) {
+        Map<String, List<String>> graph = new HashMap<>();
+
+        for (String[] edge : edges) {
+            if (edge.length >= 2) {
+                String from = edge[0];
+                String to = edge[1];
+
+                graph.computeIfAbsent(from, k -> new ArrayList<>()).add(to);
+                if (undirected) {
+                    graph.computeIfAbsent(to, k -> new ArrayList<>()).add(from);
+                }
+            }
+        }
+
+        return graph;
+    }
+}

Graph.class

@@ -0,0 +1,171 @@
+package com.thealgorithms.datastructures.graphs;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests for {@link BreadthFirstSearch}.
+ */
+class BreadthFirstSearchTest {
+
+    @Test
+    void testBfsWithIntegerGraphSimple() {
+        // Create a simple graph: 0 -> 1 -> 2
+        // | |
+        // v v
+        // 3 4
+        int[][] edges = { { 0, 1 }, { 0, 3 }, { 1, 2 }, { 1, 4 } };
+        List<List<Integer>> graph = BreadthFirstSearch.createGraph(5, edges, false);
+
+        List<Integer> result = BreadthFirstSearch.bfs(graph, 5, 0);
+
+        assertEquals(5, result.size());
+        assertEquals(0, result.get(0)); // Source is first
+        // BFS visits by level: 0 -> [1, 3] -> [2, 4]
+        assertTrue(result.indexOf(1) < result.indexOf(2)); // 1 before 2
+        assertTrue(result.indexOf(1) < result.indexOf(4)); // 1 before 4
+    }
+
+    @Test
+    void testBfsWithUndirectedGraph() {
+        // Create an undirected graph
+        int[][] edges = { { 0, 1 }, { 1, 2 }, { 2, 3 }, { 3, 4 } };
+        List<List<Integer>> graph = BreadthFirstSearch.createGraph(5, edges, true);
+
+        List<Integer> result = BreadthFirstSearch.bfs(graph, 5, 2);
+
+        assertEquals(5, result.size());
+        assertEquals(2, result.get(0)); // Source is first
+    }
+
+    @Test
+    void testBfsWithDisconnectedGraph() {
+        // Graph with disconnected components: 0 -> 1, 2 -> 3 (separate components)
+        int[][] edges = { { 0, 1 }, { 2, 3 } };
+        List<List<Integer>> graph = BreadthFirstSearch.createGraph(4, edges, false);
+
+        List<Integer> result = BreadthFirstSearch.bfs(graph, 4, 0);
+
+        // Should only visit reachable vertices from 0
+        assertEquals(2, result.size());
+        assertTrue(result.contains(0));
+        assertTrue(result.contains(1));
+    }
+
+    @Test
+    void testBfsWithSingleVertex() {
+        int[][] edges = {};
+        List<List<Integer>> graph = BreadthFirstSearch.createGraph(1, edges, false);
+
+        List<Integer> result = BreadthFirstSearch.bfs(graph, 1, 0);
+
+        assertEquals(1, result.size());
+        assertEquals(0, result.get(0));
+    }
+
+    @Test
+    void testBfsWithCyclicGraph() {
+        // Graph with a cycle: 0 -> 1 -> 2 -> 0
+        int[][] edges = { { 0, 1 }, { 1, 2 }, { 2, 0 } };
+        List<List<Integer>> graph = BreadthFirstSearch.createGraph(3, edges, false);
+
+        List<Integer> result = BreadthFirstSearch.bfs(graph, 3, 0);
+
+        assertEquals(3, result.size());
+        assertEquals(0, result.get(0)); // Source is first
+    }
+
+    @Test
+    void testBfsWithMapBasedGraph() {
+        Map<String, List<String>> graph = new HashMap<>();
+        graph.put("A", List.of("B", "C"));
+        graph.put("B", List.of("D"));
+        graph.put("C", List.of("E"));
+        graph.put("D", new ArrayList<>());
+        graph.put("E", new ArrayList<>());
+
+        List<String> result = BreadthFirstSearch.bfs(graph, "A");
+
+        assertEquals(5, result.size());
+        assertEquals("A", result.get(0)); // Source is first
+        // B and C should come before D and E
+        assertTrue(result.indexOf("B") < result.indexOf("D"));
+        assertTrue(result.indexOf("C") < result.indexOf("E"));
+    }
+
+    @Test
+    void testBfsWithStringGraphCreation() {
+        String[][] edges = { { "DELHI", "MUMBAI" }, { "DELHI", "PUNE" }, { "MUMBAI", "GOA" } };
+        Map<String, List<String>> graph = BreadthFirstSearch.createStringGraph(edges, true);
+
+        List<String> result = BreadthFirstSearch.bfs(graph, "DELHI");
+
+        assertEquals(4, result.size());
+        assertEquals("DELHI", result.get(0));
+    }
+
+    @Test
+    void testBfsThrowsExceptionForNullSource() {
+        Map<String, List<String>> graph = new HashMap<>();
+        graph.put("A", List.of("B"));
+
+        assertThrows(IllegalArgumentException.class, () -> BreadthFirstSearch.bfs(graph, null));
+    }
+
+    @Test
+    void testBfsThrowsExceptionForSourceNotInGraph() {
+        Map<String, List<String>> graph = new HashMap<>();
+        graph.put("A", List.of("B"));
+
+        assertThrows(IllegalArgumentException.class, () -> BreadthFirstSearch.bfs(graph, "X"));
+    }
+
+    @Test
+    void testBfsThrowsExceptionForInvalidSourceIndex() {
+        List<List<Integer>> graph = BreadthFirstSearch.createGraph(3, new int[][] {}, false);
+
+        assertThrows(IllegalArgumentException.class, () -> BreadthFirstSearch.bfs(graph, 3, -1));
+        assertThrows(IllegalArgumentException.class, () -> BreadthFirstSearch.bfs(graph, 3, 5));
+    }
+
+    @Test
+    void testBfsLevelOrderProperty() {
+        // Test that BFS visits vertices level by level
+        // 0
+        // /|\
+        // 1 2 3
+        // | |
+        // 4 5
+        int[][] edges = { { 0, 1 }, { 0, 2 }, { 0, 3 }, { 1, 4 }, { 3, 5 } };
+        List<List<Integer>> graph = BreadthFirstSearch.createGraph(6, edges, false);
+
+        List<Integer> result = BreadthFirstSearch.bfs(graph, 6, 0);
+
+        // Level 0: 0
+        // Level 1: 1, 2, 3
+        // Level 2: 4, 5
+        assertEquals(0, result.get(0));
+        // All level-1 vertices come before level-2 vertices
+        int level1End = Math.max(result.indexOf(1), Math.max(result.indexOf(2), result.indexOf(3)));
+        int level2Start = Math.min(result.indexOf(4), result.indexOf(5));
+        assertTrue(level1End < level2Start);
+    }
+
+    @Test
+    void testBfsWithEmptyNeighborList() {
+        Map<String, List<String>> graph = new HashMap<>();
+        graph.put("A", new ArrayList<>());
+
+        List<String> result = BreadthFirstSearch.bfs(graph, "A");
+
+        assertEquals(1, result.size());
+        assertEquals("A", result.get(0));
+    }
+}