Refactor ArticulationPointsAdjacencyList: add docs, comments, and graph diagrams (williamfiset#1286)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: williamfiset

src/main/java/com/williamfiset/algorithms/graphtheory/ArticulationPointsAdjacencyList.java

@@ -1,9 +1,29 @@
 /**
- * Finds all articulation points on an undirected graph.
+ * Articulation Points (Cut Vertices) — Adjacency List
  *
- * <p>Tested against HackerEarth online judge at:
+ * An articulation point is a vertex whose removal disconnects the graph
+ * (or increases the number of connected components). This implementation
+ * uses Tarjan's DFS-based algorithm with low-link values.
+ *
+ * For each DFS tree rooted at node r, a non-root node u is an articulation
+ * point if it has a child v such that no vertex in the subtree rooted at v
+ * has a back edge to an ancestor of u:
+ *
+ *   ids[u] <= low[v]
+ *
+ * The root node r is an articulation point if it has more than one child
+ * in the DFS tree.
+ *
+ * Works on disconnected graphs by running DFS from every unvisited node.
+ *
+ * See also: {@link BridgesAdjacencyList} for finding bridge edges.
+ *
+ * Tested against HackerEarth online judge at:
  * https://www.hackerearth.com/practice/algorithms/graphs/articulation-points-and-bridges/tutorial
  *
+ * Time:  O(V + E)
+ * Space: O(V)
+ *
  * @author William Fiset, william.alexandre.fiset@gmail.com
  */
 package com.williamfiset.algorithms.graphtheory;
@@ -15,33 +35,38 @@
 
 public class ArticulationPointsAdjacencyList {
 
-  private int n, id, rootNodeOutgoingEdgeCount;
+  private final int n;
+  private final List<List<Integer>> graph;
   private boolean solved;
+  private int id, rootNodeOutgoingEdgeCount;
   private int[] low, ids;
   private boolean[] visited, isArticulationPoint;
-  private List<List<Integer>> graph;
 
   public ArticulationPointsAdjacencyList(List<List<Integer>> graph, int n) {
     if (graph == null || n <= 0 || graph.size() != n) throw new IllegalArgumentException();
     this.graph = graph;
     this.n = n;
   }
 
-  // Returns the indexes for all articulation points in the graph even if the
-  // graph is not fully connected.
+  /**
+   * Returns a boolean array where index i is true if node i is an articulation point.
+   * Works even if the graph is not fully connected.
+   */
   public boolean[] findArticulationPoints() {
     if (solved) return isArticulationPoint;
 
     id = 0;
-    low = new int[n]; // Low link values
-    ids = new int[n]; // Nodes ids
+    low = new int[n];
+    ids = new int[n];
     visited = new boolean[n];
     isArticulationPoint = new boolean[n];
 
+    // Run DFS from each unvisited node to handle disconnected components.
     for (int i = 0; i < n; i++) {
       if (!visited[i]) {
         rootNodeOutgoingEdgeCount = 0;
         dfs(i, i, -1);
+        // Root is an articulation point only if it has 2+ children in the DFS tree.
         isArticulationPoint[i] = (rootNodeOutgoingEdgeCount > 1);
       }
     }
@@ -51,48 +76,59 @@ public boolean[] findArticulationPoints() {
   }
 
   private void dfs(int root, int at, int parent) {
-
     if (parent == root) rootNodeOutgoingEdgeCount++;
 
     visited[at] = true;
     low[at] = ids[at] = id++;
 
-    List<Integer> edges = graph.get(at);
-    for (Integer to : edges) {
+    for (int to : graph.get(at)) {
       if (to == parent) continue;
       if (!visited[to]) {
         dfs(root, to, at);
         low[at] = min(low[at], low[to]);
+        // If no vertex in the subtree rooted at 'to' can reach above 'at',
+        // then removing 'at' would disconnect 'to's subtree.
         if (ids[at] <= low[to]) {
           isArticulationPoint[at] = true;
         }
       } else {
+        // Back edge: update low-link to the earliest reachable ancestor.
         low[at] = min(low[at], ids[to]);
       }
     }
   }
 
   /* Graph helpers */
 
-  // Initialize a graph with 'n' nodes.
   public static List<List<Integer>> createGraph(int n) {
     List<List<Integer>> graph = new ArrayList<>(n);
     for (int i = 0; i < n; i++) graph.add(new ArrayList<>());
     return graph;
   }
 
-  // Add an undirected edge to a graph.
   public static void addEdge(List<List<Integer>> graph, int from, int to) {
     graph.get(from).add(to);
     graph.get(to).add(from);
   }
 
-  /* Example usage: */
+  // ==================== Main ====================
 
   public static void main(String[] args) {
+    testExample1();
     testExample2();
   }
 
+  //
+  //        0 --- 1
+  //        |   /
+  //        2 -------- 3 --- 4
+  //        |
+  //        5 --- 6
+  //        |     |
+  //        8 --- 7
+  //
+  // Articulation points: 2, 3, 5
+  //
   private static void testExample1() {
     int n = 9;
     List<List<Integer>> graph = createGraph(n);
@@ -111,16 +147,18 @@ private static void testExample1() {
     ArticulationPointsAdjacencyList solver = new ArticulationPointsAdjacencyList(graph, n);
     boolean[] isArticulationPoint = solver.findArticulationPoints();
 
-    // Prints:
     // Node 2 is an articulation
     // Node 3 is an articulation
     // Node 5 is an articulation
     for (int i = 0; i < n; i++)
       if (isArticulationPoint[i]) System.out.printf("Node %d is an articulation\n", i);
   }
 
-  // Tests a graph with 3 nodes in a line: A - B - C
-  // Only node 'B' should be an articulation point.
+  //
+  //  0 --- 1 --- 2
+  //
+  // Articulation point: 1
+  //
   private static void testExample2() {
     int n = 3;
     List<List<Integer>> graph = createGraph(n);
@@ -131,7 +169,6 @@ private static void testExample2() {
     ArticulationPointsAdjacencyList solver = new ArticulationPointsAdjacencyList(graph, n);
     boolean[] isArticulationPoint = solver.findArticulationPoints();
 
-    // Prints:
     // Node 1 is an articulation
     for (int i = 0; i < n; i++)
       if (isArticulationPoint[i]) System.out.printf("Node %d is an articulation\n", i);