refactor: deduplicate buildAdjacency + BFS into shared GraphUtils

- Added GraphUtils.bfsDistancesFromAdj() for BFS on pre-built adjacency
  maps, complementing the existing bfsDistances() which takes a Graph.

- GraphAutoPilot: removed private buildAdjacency() (~12 lines) and
  bfs() (~16 lines), replaced 6 call sites with GraphUtils methods.

- GraphInformationDiffusionEngine: removed private buildAdjacency()
  (~13 lines) and bfs() (~15 lines), replaced 5 call sites.

- GraphSentinel: removed private buildAdjacencyMap() (~5 lines),
  replaced 2 call sites with GraphUtils.buildAdjacencyMap().

Net: ~77 lines of duplicated adjacency/BFS code removed across 3
engines, consolidated into the existing GraphUtils utility class.
All changed files compile cleanly against JUNG 2.0.1.

Author: sauravbhattacharya001

Gvisual/src/gvisual/GraphAutoPilot.java

@@ -232,7 +232,7 @@ public void analyze() {
             return;
         }
 
-        adjacency = buildAdjacency(graph);
+        adjacency = GraphUtils.buildAdjacencyMap(graph);
         beforeHealth = computeHealth(graph);
 
         // Phase 1: Diagnose
@@ -710,7 +710,7 @@ private void planShortcuts() {
 
         for (int t = 0; t < trials && count < 2; t++) {
             String start = vertices.get(t);
-            Map<String, Integer> dist = bfs(start, adjacency);
+            Map<String, Integer> dist = GraphUtils.bfsDistancesFromAdj(start, adjacency);
             // Find the farthest node
             String farthest = null;
             int maxDist = 0;
@@ -775,7 +775,7 @@ private HealthSnapshot computeHealth(Graph<String, Edge> g) {
             return h;
         }
 
-        Map<String, Set<String>> adj = buildAdjacency(g);
+        Map<String, Set<String>> adj = GraphUtils.buildAdjacencyMap(g);
 
         // Bridges
         h.bridgeCount = findBridges(g, adj).size();
@@ -823,19 +823,7 @@ private HealthSnapshot computeHealth(Graph<String, Edge> g) {
 
     // ── Graph algorithms ───────────────────────────────────
 
-    private Map<String, Set<String>> buildAdjacency(Graph<String, Edge> g) {
-        Map<String, Set<String>> adj = new HashMap<>();
-        for (String v : g.getVertices()) adj.put(v, new HashSet<>());
-        for (Edge e : g.getEdges()) {
-            Collection<String> ep = g.getEndpoints(e);
-            if (ep == null || ep.size() < 2) continue;
-            Iterator<String> it = ep.iterator();
-            String a = it.next(), b = it.next();
-            adj.get(a).add(b);
-            adj.get(b).add(a);
-        }
-        return adj;
-    }
+    // buildAdjacency removed — use GraphUtils.buildAdjacencyMap(graph)
 
     /** Find bridge edges. Returns set of "u||v" keys (sorted). */
     private Set<String> findBridges(Graph<String, Edge> g, Map<String, Set<String>> adj) {
@@ -986,24 +974,7 @@ private List<Set<String>> findComponents(Graph<String, Edge> g, Map<String, Set<
         return components;
     }
 
-    /** BFS distances from a source. */
-    private Map<String, Integer> bfs(String source, Map<String, Set<String>> adj) {
-        Map<String, Integer> dist = new HashMap<>();
-        Queue<String> queue = new ArrayDeque<>();
-        dist.put(source, 0);
-        queue.add(source);
-        while (!queue.isEmpty()) {
-            String u = queue.poll();
-            int d = dist.get(u);
-            for (String v : adj.getOrDefault(u, Collections.emptySet())) {
-                if (!dist.containsKey(v)) {
-                    dist.put(v, d + 1);
-                    queue.add(v);
-                }
-            }
-        }
-        return dist;
-    }
+    // bfs removed — use GraphUtils.bfsDistancesFromAdj(source, adj)
 
     /** Approximate diameter using BFS from a few nodes. */
     private double approximateDiameter(Graph<String, Edge> g, Map<String, Set<String>> adj) {
@@ -1012,7 +983,7 @@ private double approximateDiameter(Graph<String, Edge> g, Map<String, Set<String
         int maxDist = 0;
         int samples = Math.min(10, vertices.size());
         for (int i = 0; i < samples; i++) {
-            Map<String, Integer> dist = bfs(vertices.get(i), adj);
+            Map<String, Integer> dist = GraphUtils.bfsDistancesFromAdj(vertices.get(i), adj);
             for (int d : dist.values()) {
                 if (d > maxDist) maxDist = d;
             }

Gvisual/src/gvisual/GraphInformationDiffusionEngine.java

@@ -164,7 +164,7 @@ public DiffusionReport analyze(Graph<String, Edge> graph) {
         }
 
         // Build adjacency
-        Map<String, Set<String>> adj = buildAdjacency(graph, vertices);
+        Map<String, Set<String>> adj = GraphUtils.buildAdjacencyMap(graph);
 
         // Select seeds
         Set<String> seeds = resolveSeedNodes(vertices, adj);
@@ -697,31 +697,15 @@ private int estimateDiameter(List<String> vertices, Map<String, Set<String>> adj
         List<String> probeNodes = new ArrayList<>(vertices);
         Collections.shuffle(probeNodes, rng);
         for (int p = 0; p < probes; p++) {
-            Map<String, Integer> dist = bfs(probeNodes.get(p), adj);
+            Map<String, Integer> dist = GraphUtils.bfsDistancesFromAdj(probeNodes.get(p), adj);
             for (int d : dist.values()) {
                 if (d > maxDist) maxDist = d;
             }
         }
         return maxDist;
     }
 
-    private Map<String, Integer> bfs(String start, Map<String, Set<String>> adj) {
-        Map<String, Integer> dist = new LinkedHashMap<>();
-        dist.put(start, 0);
-        Queue<String> queue = new LinkedList<>();
-        queue.add(start);
-        while (!queue.isEmpty()) {
-            String u = queue.poll();
-            int d = dist.get(u);
-            for (String v : adj.getOrDefault(u, Collections.emptySet())) {
-                if (!dist.containsKey(v)) {
-                    dist.put(v, d + 1);
-                    queue.add(v);
-                }
-            }
-        }
-        return dist;
-    }
+    // bfs removed — use GraphUtils.bfsDistancesFromAdj(source, adj)
 
     private double computeGini(double[] sorted) {
         int n = sorted.length;
@@ -741,7 +725,7 @@ private double giantComponentFraction(List<String> vertices, Map<String, Set<Str
         int maxComp = 0;
         for (String v : vertices) {
             if (visited.contains(v)) continue;
-            Map<String, Integer> comp = bfs(v, adj);
+            Map<String, Integer> comp = GraphUtils.bfsDistancesFromAdj(v, adj);
             visited.addAll(comp.keySet());
             if (comp.size() > maxComp) maxComp = comp.size();
         }
@@ -815,19 +799,7 @@ private List<String> generateInsights(ICResult ic, LTResult lt,
     // Helpers
     // ==================================================================
 
-    private Map<String, Set<String>> buildAdjacency(Graph<String, Edge> graph, List<String> vertices) {
-        Map<String, Set<String>> adj = new LinkedHashMap<>();
-        for (String v : vertices) adj.put(v, new LinkedHashSet<>());
-        for (Edge edge : graph.getEdges()) {
-            String v1 = edge.getVertex1();
-            String v2 = edge.getVertex2();
-            if (v1 == null || v2 == null) continue;
-            if (v1.equals(v2)) continue; // skip self-loops
-            adj.computeIfAbsent(v1, k -> new LinkedHashSet<>()).add(v2);
-            adj.computeIfAbsent(v2, k -> new LinkedHashSet<>()).add(v1);
-        }
-        return adj;
-    }
+    // buildAdjacency removed — use GraphUtils.buildAdjacencyMap(graph)
 
     private Set<String> resolveSeedNodes(List<String> vertices, Map<String, Set<String>> adj) {
         if (seedNodes != null && !seedNodes.isEmpty()) {

Gvisual/src/gvisual/GraphSentinel.java

@@ -163,8 +163,8 @@ public DriftReport analyze() {
         report.edgesBefore = before.getEdgeCount();
         report.edgesAfter = after.getEdgeCount();
 
-        Map<String, Set<String>> adjBefore = buildAdjacencyMap(before);
-        Map<String, Set<String>> adjAfter = buildAdjacencyMap(after);
+        Map<String, Set<String>> adjBefore = GraphUtils.buildAdjacencyMap(before);
+        Map<String, Set<String>> adjAfter = GraphUtils.buildAdjacencyMap(after);
 
         // Pre-compute degrees and hubs once — reused by hub dynamics and stability scoring
         Map<String, Integer> degBefore = computeDegrees(before);
@@ -742,13 +742,7 @@ private List<Alert> generateAlerts(DriftReport report) {
 
     // -- Utility methods ---------------------------------------------------
 
-    private Map<String, Set<String>> buildAdjacencyMap(Graph<String, Edge> g) {
-        Map<String, Set<String>> adj = new HashMap<>();
-        for (String v : g.getVertices()) {
-            adj.put(v, new HashSet<>(g.getNeighbors(v)));
-        }
-        return adj;
-    }
+    // buildAdjacencyMap removed — use GraphUtils.buildAdjacencyMap(graph)
 
     private Map<String, Integer> computeDegrees(Graph<String, Edge> g) {
         Map<String, Integer> deg = new HashMap<>();

Gvisual/src/gvisual/GraphUtils.java

@@ -406,6 +406,40 @@ public static int cycleRankOfSubgraph(
         return edges - vertices.size() + comps;
     }
 
+    // ── BFS from adjacency map ─────────────────────────────────────────
+
+    /**
+     * BFS from a source vertex using a pre-built adjacency map, returning
+     * distances (hop counts) to all reachable vertices.
+     *
+     * <p>This variant is useful when the caller already holds an adjacency
+     * map and wants to avoid re-traversing the JUNG graph structure.</p>
+     *
+     * @param source the starting vertex
+     * @param adj    pre-built adjacency map (vertex → set of neighbors)
+     * @return map from vertex ID to its BFS distance from source
+     */
+    public static Map<String, Integer> bfsDistancesFromAdj(
+            String source, Map<String, Set<String>> adj) {
+        Map<String, Integer> dist = new HashMap<String, Integer>();
+        ArrayDeque<String> queue = new ArrayDeque<String>();
+        dist.put(source, 0);
+        queue.add(source);
+        while (!queue.isEmpty()) {
+            String u = queue.poll();
+            int d = dist.get(u);
+            Set<String> neighbors = adj.get(u);
+            if (neighbors == null) continue;
+            for (String v : neighbors) {
+                if (!dist.containsKey(v)) {
+                    dist.put(v, d + 1);
+                    queue.add(v);
+                }
+            }
+        }
+        return dist;
+    }
+
     // ── Clustering coefficient ────────────────────────────────────────
 
     /**