fix(hopcroft-karp): Improve test coverage and fix edge cases

Added new unit tests for the Hopcroft-Karp algorithm to cover more scenarios and edge cases. This led to a fix for a bug where graphs with no possible matching were handled incorrectly. Also updated the README documentation.

Author: awesohame

README.md

@@ -91,6 +91,7 @@ If you are interested, please contact us at zigrazor@gmail.com or contribute to
     - [Borůvka's Algorithm](#borůvkas-algorithm)
     - [Graph Slicing based on connectivity](#graph-slicing-based-on-connectivity)
     - [Ford-Fulkerson Algorithm](#ford-fulkerson-algorithm)
+    - [Hopcroft-Karp Algorithm](#hopcroft-karp-algorithm)
     - [Kosaraju's Algorithm](#kosarajus-algorithm)
     - [Kahn's Algorithm](#kahns-algorithm)
   - [Partition Algorithm Explanation](#partition-algorithm-explanation)
@@ -461,6 +462,18 @@ This algorithm is used in garbage collection systems to decide which other objec
 [Ford-Fulkerson Algorithm](https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm) is a greedy algorithm for finding a maximum flow in a flow network.
 The idea behind the algorithm is as follows: as long as there is a path from the source (start node) to the sink (end node), with available capacity on all edges in the path, we send flow along one of the paths. Then we find another path, and so on. A path with available capacity is called an augmenting path.
 
+### Hopcroft-Karp Algorithm
+
+[Hopcroft-Karp Algorithm](https://en.wikipedia.org/wiki/Hopcroft%E2%80%93Karp_algorithm) is an algorithm that finds the maximum cardinality matching in a bipartite graph in O(E√V) time. It repeatedly finds augmenting paths of shortest length using BFS, then uses DFS to find a maximal set of vertex-disjoint augmenting paths of that length.
+
+The algorithm operates in phases:
+
+1. **BFS Phase**: Find the shortest augmenting path length from unmatched left vertices to unmatched right vertices. If no augmenting path exists, the current matching is maximum.
+2. **DFS Phase**: Use DFS to find a maximal set of vertex-disjoint augmenting paths of the shortest length found in the BFS phase.
+3. **Augmentation**: Add all found augmenting paths to the matching simultaneously.
+
+This process repeats until no more augmenting paths exist. Each iteration increases the matching size by at least one, and there are at most O(√V) iterations, giving the overall O(E√V) time complexity.
+
 ### Kosaraju's Algorithm
 [Kosaraju's Algorithm](https://en.wikipedia.org/wiki/Kosaraju%27s_algorithm) is a linear time algorithm to find the strongly connected components of a directed graph.  It is based on the idea that if one is able to reach a vertex v starting from vertex u, then one should be able to reach vertex u starting from vertex v and if such is the case, one can say that vertices u and v are strongly connected - they are in a strongly connected sub-graph. Following is an example:
 

include/CXXGraph/Graph/Algorithm/HopcroftKarp_impl.hpp

@@ -34,6 +34,14 @@ namespace CXXGraph {
         result.errorMessage = "";
         result.maxMatching = 0;
 
+        // If the graph is empty or has no edges, the maximum matching is 0.
+        // The graph is still bipartite.
+        if (this->getNodeSet().empty() || this->getEdgeSet().empty()) {
+            result.success = true;
+            result.maxMatching = 0;
+            return result;
+        }
+
         auto nodeSet = getNodeSet();
 
         // need at least 2 nodes for matching
@@ -116,7 +124,6 @@ namespace CXXGraph {
             return result;
         }
 
-        // main Hopcroft-Karp algorithm
         std::unordered_map<shared<const Node<T>>, shared<const Node<T>>, nodeHash<T>> match;
         std::unordered_map<shared<const Node<T>>, int, nodeHash<T>> dist;
         int matchingSize = 0;

test/HopcroftKarpTest.cpp

@@ -84,29 +84,27 @@ TEST(HopcroftKarpTest, test_single_edge) {
 }
 
 TEST(HopcroftKarpTest, test_empty_graph) {
-  // empty graph should fail due to insufficient nodes
+  // empty graph should be considered bipartite with 0 matching
   CXXGraph::T_EdgeSet<int> edgeSet;
 
   CXXGraph::Graph<int> graph(edgeSet);
   CXXGraph::HopcroftKarpResult result = graph.hopcroftKarp();
 
-  ASSERT_FALSE(result.success);
+  ASSERT_TRUE(result.success);
   ASSERT_EQ(result.maxMatching, 0);
-  ASSERT_FALSE(result.errorMessage.empty());
-  ASSERT_EQ(result.errorMessage, "Graph must have at least 2 nodes for bipartite matching.");
+  ASSERT_TRUE(result.errorMessage.empty());
 }
 
 TEST(HopcroftKarpTest, test_single_node_graph) {
-  // single node should fail due to insufficient nodes
+  // single node graph is also bipartite with 0 matching
   CXXGraph::Graph<int> graph;
   graph.addNode(std::make_shared<CXXGraph::Node<int>>("1", 1));
-  
+
   CXXGraph::HopcroftKarpResult result = graph.hopcroftKarp();
 
-  ASSERT_FALSE(result.success);
+  ASSERT_TRUE(result.success);
   ASSERT_EQ(result.maxMatching, 0);
-  ASSERT_FALSE(result.errorMessage.empty());
-  ASSERT_EQ(result.errorMessage, "Graph must have at least 2 nodes for bipartite matching.");
+  ASSERT_TRUE(result.errorMessage.empty());
 }
 
 TEST(HopcroftKarpTest, test_non_bipartite_graph) {
@@ -223,3 +221,107 @@ TEST(HopcroftKarpTest, test_incremental_matching) {
   std::set<std::string> possibleMatches = { "v1", "v2", "v3" };
   ASSERT_TRUE(possibleMatches.count(result.matching[0].second) > 0);
 }
+
+TEST(HopcroftKarpTest, test_disconnected_graph) {
+  // tests matching on a graph with multiple disconnected components
+  // component 1: a single edge (matching size 1)
+  CXXGraph::Node<int> u1("u1", 1), v1("v1", 2);
+  CXXGraph::UndirectedEdge<int> edge1(1, u1, v1);
+
+  // component 2: a 4-cycle (matching size 2)
+  CXXGraph::Node<int> u2("u2", 3), v2("v2", 4);
+  CXXGraph::Node<int> u3("u3", 5), v3("v3", 6);
+  CXXGraph::UndirectedEdge<int> edge2(2, u2, v2);
+  CXXGraph::UndirectedEdge<int> edge3(3, v2, u3);
+  CXXGraph::UndirectedEdge<int> edge4(4, u3, v3);
+  CXXGraph::UndirectedEdge<int> edge5(5, v3, u2);
+
+  CXXGraph::T_EdgeSet<int> edgeSet;
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge1));
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge2));
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge3));
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge4));
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge5));
+
+  CXXGraph::Graph<int> graph(edgeSet);
+  CXXGraph::HopcroftKarpResult result = graph.hopcroftKarp();
+
+  // expected matching is sum of matchings from each component (1 + 2 = 3)
+  ASSERT_TRUE(result.success);
+  ASSERT_EQ(result.maxMatching, 3);
+  ASSERT_EQ(result.matching.size(), 3);
+  ASSERT_TRUE(result.errorMessage.empty());
+}
+
+TEST(HopcroftKarpTest, test_graph_with_isolated_vertices) {
+  // tests matching on a graph with isolated vertices
+  CXXGraph::Node<int> u1("u1", 1), v1("v1", 2);
+  CXXGraph::UndirectedEdge<int> edge1(1, u1, v1);
+
+  // isolated nodes
+  CXXGraph::Node<int> iso1("iso1", 3), iso2("iso2", 4);
+
+  CXXGraph::T_EdgeSet<int> edgeSet;
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge1));
+  
+  CXXGraph::Graph<int> graph(edgeSet);
+  graph.addNode(make_shared<CXXGraph::Node<int>>(iso1));
+  graph.addNode(make_shared<CXXGraph::Node<int>>(iso2));
+
+  CXXGraph::HopcroftKarpResult result = graph.hopcroftKarp();
+
+  // isolated vertices should not affect the matching
+  ASSERT_TRUE(result.success);
+  ASSERT_EQ(result.maxMatching, 1);
+  ASSERT_EQ(result.matching.size(), 1);
+  ASSERT_TRUE(result.errorMessage.empty());
+  ASSERT_EQ(result.matching[0].first, "u1");
+  ASSERT_EQ(result.matching[0].second, "v1");
+}
+
+TEST(HopcroftKarpTest, test_no_matching_possible) {
+  // tests a bipartite graph with no edges between partitions
+  CXXGraph::Node<int> u1("u1", 1), u2("u2", 2);
+  CXXGraph::Node<int> v1("v1", 3), v2("v2", 4);
+
+  // no edges connect U and V partitions
+  CXXGraph::T_EdgeSet<int> edgeSet;
+
+  CXXGraph::Graph<int> graph(edgeSet);
+  graph.addNode(make_shared<CXXGraph::Node<int>>(u1));
+  graph.addNode(make_shared<CXXGraph::Node<int>>(u2));
+  graph.addNode(make_shared<CXXGraph::Node<int>>(v1));
+  graph.addNode(make_shared<CXXGraph::Node<int>>(v2));
+
+  CXXGraph::HopcroftKarpResult result = graph.hopcroftKarp();
+
+  // graph is bipartite, but matching should be 0
+  ASSERT_TRUE(result.success);
+  ASSERT_EQ(result.maxMatching, 0);
+  ASSERT_EQ(result.matching.size(), 0);
+  ASSERT_TRUE(result.errorMessage.empty());
+}
+
+TEST(HopcroftKarpTest, test_unbalanced_bipartite_graph) {
+  // tests an unbalanced bipartite graph (U=3, V=2)
+  CXXGraph::Node<int> u1("u1", 1), u2("u2", 2), u3("u3", 3);
+  CXXGraph::Node<int> v1("v1", 4), v2("v2", 5);
+
+  CXXGraph::UndirectedEdge<int> edge1(1, u1, v1);
+  CXXGraph::UndirectedEdge<int> edge2(2, u2, v1);
+  CXXGraph::UndirectedEdge<int> edge3(3, u3, v2);
+
+  CXXGraph::T_EdgeSet<int> edgeSet;
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge1));
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge2));
+  edgeSet.insert(make_shared<CXXGraph::UndirectedEdge<int>>(edge3));
+
+  CXXGraph::Graph<int> graph(edgeSet);
+  CXXGraph::HopcroftKarpResult result = graph.hopcroftKarp();
+
+  // max matching cannot exceed the size of the smaller partition (V)
+  ASSERT_TRUE(result.success);
+  ASSERT_EQ(result.maxMatching, 2);
+  ASSERT_EQ(result.matching.size(), 2);
+  ASSERT_TRUE(result.errorMessage.empty());
+}