philiprehberger-graph 0.1.4 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20e307b29aa2270ecfaee50d6ca9418371fb3ca5446e0e8c85c6cbacbdc7a0a4
-  data.tar.gz: 51d347cc1674775d1bd8450f376ecd7ec23335f1048430635798403724649bc0
+  metadata.gz: f15e96fcf2bfd1b6c453e5f52f5f956dc63d62eb385f6aeedea59073b31f0379
+  data.tar.gz: 1f82fde8213303ead0365ba95914531b482955bf9b50962227e24f6ad60e8c8c
 SHA512:
-  metadata.gz: 46fd06902335c5dd7d20b31b33009e4e4e80c5954d0f7158aafbac58929b985723be10d8470561cf7ba5bb613b4c92ed0f3a2efdd982a9fb854d01e01d85a99a
-  data.tar.gz: fb38692ca5f586d2d92200fc66ef73b90bb28713fdec775417a7a83a79f71b360222dda3ed280e9d8e510204aced3deadd6aff6d0b63d936cb439e4cd0d4f166
+  metadata.gz: 21fee32160f5d5d391d383d779df1ab66ed9b66d66f50d1e9c3e32bfe47f35856722fd2ddde5617ca4c0066a91a97bb9aafe91cb90df73b427edd6b02726d1c2
+  data.tar.gz: 5c48eabd6cd2ea1e2454ce3d9aa842f5859f3045a098d8928e740f617149c17320150c148f03bba09a36c4ffb520909e463b1a3d51bb64514ecb65dc7a985abd

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-04-01
+
+### Fixed
+- Fix infinite recursion in union-find `uf_find` used by Kruskal MST algorithm
+- Fix `Graph.new` infinite recursion in module-level factory method
+- Fix greedy coloring test expectation for directed graphs
+
+## [0.2.2] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
+## [0.2.1] - 2026-03-31
+
+### Changed
+- Standardize README badges, support section, and license format
+
+## [0.2.0] - 2026-03-28
+
+### Added
+
+- Minimum spanning tree with Kruskal's and Prim's algorithms (`minimum_spanning_tree`)
+- Maximum flow using Edmonds-Karp algorithm (`max_flow`)
+- Greedy graph coloring (`coloring`, `chromatic_number_estimate`)
+- Bipartiteness checking (`bipartite?`, `bipartite_sets`)
+- Strongly connected components via Tarjan's algorithm (`strongly_connected_components`)
+- Graph serialization to DOT and JSON formats (`to_dot`, `to_json`, `Graph.from_json`)
+
+## [0.1.5] - 2026-03-26
+
+### Changed
+
+- Add Sponsor badge and fix License link format in README
+
 ## [0.1.4] - 2026-03-24
 
 ### Changed

data/README.md

@@ -2,9 +2,9 @@
 
 [![Tests](https://github.com/philiprehberger/rb-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-graph/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-graph.svg)](https://rubygems.org/gems/philiprehberger-graph)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-graph)](LICENSE)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-graph)](https://github.com/philiprehberger/rb-graph/commits/main)
 
-Directed and undirected graph with traversal, shortest path, and topological sort
+Directed and undirected graph data structure with traversal, shortest path, MST, max flow, coloring, and serialization
 
 ## Requirements
 
@@ -76,6 +76,84 @@ g.add_edge(:c, :d)
 g.connected_components  # => [[:a, :b], [:c, :d]]
 ```
 
+### Minimum Spanning Tree
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b, weight: 4)
+g.add_edge(:a, :c, weight: 2)
+g.add_edge(:b, :c, weight: 1)
+g.add_edge(:b, :d, weight: 5)
+
+g.minimum_spanning_tree(algorithm: :kruskal)
+# => [{from: :b, to: :c, weight: 1}, {from: :a, to: :c, weight: 2}, {from: :b, to: :d, weight: 5}]
+g.minimum_spanning_tree(algorithm: :prim)
+```
+
+### Maximum Flow
+
+```ruby
+g = Philiprehberger::Graph.new(directed: true)
+g.add_edge(:s, :a, weight: 10)
+g.add_edge(:s, :b, weight: 5)
+g.add_edge(:a, :t, weight: 5)
+g.add_edge(:b, :t, weight: 10)
+g.add_edge(:a, :b, weight: 15)
+
+g.max_flow(:s, :t)  # => 15
+```
+
+### Graph Coloring
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b)
+g.add_edge(:b, :c)
+g.add_edge(:c, :a)
+
+g.coloring                  # => {:a=>0, :b=>1, :c=>2}
+g.chromatic_number_estimate # => 3
+```
+
+### Bipartiteness
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b)
+g.add_edge(:b, :c)
+
+g.bipartite?      # => true
+g.bipartite_sets  # => [#<Set: {:a, :c}>, #<Set: {:b}>]
+```
+
+### Strongly Connected Components
+
+```ruby
+g = Philiprehberger::Graph.new(directed: true)
+g.add_edge(:a, :b)
+g.add_edge(:b, :a)
+g.add_edge(:b, :c)
+g.add_edge(:c, :d)
+g.add_edge(:d, :c)
+
+g.strongly_connected_components  # => [[:d, :c], [:b, :a]]
+```
+
+### Serialization
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b, weight: 3)
+
+g.to_dot
+# => "graph G {\n  a;\n  b;\n  a -- b [weight=3];\n}"
+
+g.to_json
+# => '{"directed":false,"nodes":["a","b"],"edges":[{"from":"a","to":"b","weight":3}]}'
+
+g2 = Philiprehberger::Graph::Graph.from_json(g.to_json)
+```
+
 ## API
 
 | Method | Description |
@@ -95,6 +173,16 @@ g.connected_components  # => [[:a, :b], [:c, :d]]
 | `#topological_sort` | Topological ordering (DAG only) |
 | `#cycle?` | Check for cycles |
 | `#connected_components` | Find connected components |
+| `#minimum_spanning_tree(algorithm:)` | Kruskal's or Prim's MST |
+| `#max_flow(source, sink)` | Edmonds-Karp maximum flow |
+| `#coloring` | Greedy graph coloring |
+| `#chromatic_number_estimate` | Estimated chromatic number |
+| `#bipartite?` | Check if graph is bipartite |
+| `#bipartite_sets` | Get bipartite partition sets |
+| `#strongly_connected_components` | Tarjan's SCC algorithm |
+| `#to_dot` | Serialize to DOT format |
+| `#to_json` | Serialize to JSON |
+| `.from_json(str)` | Deserialize from JSON |
 
 ## Development
 
@@ -104,6 +192,24 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this project useful:
+
+⭐ [Star the repo](https://github.com/philiprehberger/rb-graph)
+
+🐛 [Report issues](https://github.com/philiprehberger/rb-graph/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+
+💡 [Suggest features](https://github.com/philiprehberger/rb-graph/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+
+❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)
+
+🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)
+
+💻 [GitHub Profile](https://github.com/philiprehberger)
+
+🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/graph/graph.rb

@@ -213,16 +213,192 @@ module Philiprehberger
         components = []
 
         @adjacency.each_key do |node|
-          unless visited[node]
-            component = []
-            cc_visit(node, visited, component)
-            components << component
-          end
+          next if visited[node]
+
+          component = []
+          cc_visit(node, visited, component)
+          components << component
         end
 
         components
       end
 
+      # Find the minimum spanning tree using Kruskal's or Prim's algorithm.
+      # Only works on undirected graphs.
+      #
+      # @param algorithm [Symbol] :kruskal or :prim
+      # @return [Array<Hash>] edges in the MST as {from:, to:, weight:} hashes
+      # @raise [Error] if the graph is directed or disconnected
+      def minimum_spanning_tree(algorithm: :kruskal)
+        raise Error, 'minimum spanning tree requires an undirected graph' if @directed
+        raise Error, 'graph is empty' if @adjacency.empty?
+
+        components = connected_components
+        raise Error, 'graph is disconnected' if components.length > 1
+
+        case algorithm
+        when :kruskal then kruskal_mst
+        when :prim then prim_mst
+        else raise Error, "unknown algorithm: #{algorithm}"
+        end
+      end
+
+      # Compute the maximum flow from source to sink using Edmonds-Karp (BFS-based Ford-Fulkerson).
+      # Only works on directed graphs.
+      #
+      # @param source [Object] source node
+      # @param sink [Object] sink node
+      # @return [Numeric] the maximum flow value
+      # @raise [Error] if the graph is not directed or nodes don't exist
+      def max_flow(source, sink)
+        raise Error, 'max_flow requires a directed graph' unless @directed
+        raise Error, 'source node not found' unless @adjacency.key?(source)
+        raise Error, 'sink node not found' unless @adjacency.key?(sink)
+        return 0 if source == sink
+
+        edmonds_karp(source, sink)
+      end
+
+      # Greedy graph coloring. Assigns the smallest available color (integer) to each node.
+      #
+      # @return [Hash] mapping of node => color (integer starting from 0)
+      def coloring
+        result = {}
+        @adjacency.each_key do |node|
+          used_colors = Set.new
+          neighbors(node).each do |neighbor|
+            used_colors << result[neighbor] if result.key?(neighbor)
+          end
+          color = 0
+          color += 1 while used_colors.include?(color)
+          result[node] = color
+        end
+        result
+      end
+
+      # Estimate the chromatic number using greedy coloring.
+      #
+      # @return [Integer] estimated chromatic number
+      def chromatic_number_estimate
+        return 0 if @adjacency.empty?
+
+        colors = coloring
+        (colors.values.max || 0) + 1
+      end
+
+      # Check whether the graph is bipartite.
+      #
+      # @return [Boolean]
+      def bipartite?
+        !bipartite_sets.nil?
+      end
+
+      # Find bipartite partition sets using BFS 2-coloring.
+      #
+      # @return [Array<Set, Set>, nil] two sets of nodes, or nil if not bipartite
+      def bipartite_sets
+        color = {}
+        set_a = Set.new
+        set_b = Set.new
+
+        @adjacency.each_key do |start|
+          next if color.key?(start)
+
+          color[start] = 0
+          set_a << start
+          queue = [start]
+
+          until queue.empty?
+            node = queue.shift
+            all_neighbors = bipartite_neighbors(node)
+            all_neighbors.each do |neighbor|
+              if color.key?(neighbor)
+                return nil if color[neighbor] == color[node]
+              else
+                color[neighbor] = 1 - color[node]
+                if color[neighbor].zero?
+                  set_a << neighbor
+                else
+                  set_b << neighbor
+                end
+                queue << neighbor
+              end
+            end
+          end
+        end
+
+        [set_a, set_b]
+      end
+
+      # Find strongly connected components using Tarjan's algorithm.
+      # Only works on directed graphs.
+      #
+      # @return [Array<Array<Object>>] arrays of node ids per SCC
+      # @raise [Error] if the graph is not directed
+      def strongly_connected_components
+        raise Error, 'strongly_connected_components requires a directed graph' unless @directed
+
+        tarjan_scc
+      end
+
+      # Serialize the graph to DOT format.
+      #
+      # @return [String] DOT format string
+      def to_dot
+        type = @directed ? 'digraph' : 'graph'
+        connector = @directed ? '->' : '--'
+        lines = ["#{type} G {"]
+
+        @adjacency.each_key do |node|
+          lines << "  #{dot_escape(node)};"
+        end
+
+        seen = {}
+        @adjacency.each do |from, edges_list|
+          edges_list.each do |edge|
+            key = @directed ? [from, edge[:node]] : [from, edge[:node]].sort
+            next if seen[key]
+
+            seen[key] = true
+            attrs = edge[:weight] == 1 ? '' : " [weight=#{edge[:weight]}]"
+            lines << "  #{dot_escape(from)} #{connector} #{dot_escape(edge[:node])}#{attrs};"
+          end
+        end
+
+        lines << '}'
+        lines.join("\n")
+      end
+
+      # Serialize the graph to JSON.
+      #
+      # @return [String] JSON string
+      def to_json(*_args)
+        require 'json'
+        data = {
+          directed: @directed,
+          nodes: @adjacency.keys,
+          edges: edges.map { |e| { from: e[:from], to: e[:to], weight: e[:weight] } }
+        }
+        JSON.generate(data)
+      end
+
+      # Deserialize a graph from JSON.
+      #
+      # @param json_str [String] JSON string
+      # @return [Graph] a new graph instance
+      def self.from_json(json_str)
+        require 'json'
+        data = JSON.parse(json_str, symbolize_names: true)
+        graph = new(directed: data[:directed])
+        (data[:nodes] || []).each { |n| graph.add_node(n.is_a?(String) ? n.to_sym : n) }
+        (data[:edges] || []).each do |e|
+          from = e[:from].is_a?(String) ? e[:from].to_sym : e[:from]
+          to = e[:to].is_a?(String) ? e[:to].to_sym : e[:to]
+          graph.add_edge(from, to, weight: e[:weight] || 1)
+        end
+        graph
+      end
+
       private
 
       def dfs_visit(node, visited, result)
@@ -282,9 +458,7 @@ module Philiprehberger
         visited = {}
 
         @adjacency.each_key do |node|
-          unless visited[node]
-            return true if undirected_cycle_visit(node, nil, visited)
-          end
+          return true if !visited[node] && undirected_cycle_visit(node, nil, visited)
         end
 
         false
@@ -319,6 +493,202 @@ module Philiprehberger
           cc_visit(neighbor, visited, component) unless visited[neighbor]
         end
       end
+
+      # ── MST helpers ──
+
+      def kruskal_mst
+        all_edges = edges.sort_by { |e| e[:weight] }
+        parent = {}
+        rank = Hash.new(0)
+
+        @adjacency.each_key { |n| parent[n] = n }
+
+        mst = []
+        all_edges.each do |edge|
+          root_from = uf_find(parent, edge[:from])
+          root_to = uf_find(parent, edge[:to])
+          next if root_from == root_to
+
+          mst << edge
+          uf_union(parent, rank, root_from, root_to)
+          break if mst.length == @adjacency.length - 1
+        end
+
+        mst
+      end
+
+      def prim_mst
+        start = @adjacency.keys.first
+        in_mst = { start => true }
+        mst = []
+        candidate_edges = (@adjacency[start] || []).map { |e| { from: start, to: e[:node], weight: e[:weight] } }
+
+        until candidate_edges.empty? || mst.length == @adjacency.length - 1
+          candidate_edges.sort_by! { |e| e[:weight] }
+          idx = candidate_edges.index { |e| !in_mst[e[:to]] }
+          break if idx.nil?
+
+          edge = candidate_edges.delete_at(idx)
+          next if in_mst[edge[:to]]
+
+          in_mst[edge[:to]] = true
+          mst << edge
+          (@adjacency[edge[:to]] || []).each do |e|
+            candidate_edges << { from: edge[:to], to: e[:node], weight: e[:weight] } unless in_mst[e[:node]]
+          end
+        end
+
+        mst
+      end
+
+      def uf_find(parent, node)
+        root = node
+        root = parent[root] while parent[root] != root
+
+        # Path compression
+        while parent[node] != root
+          next_node = parent[node]
+          parent[node] = root
+          node = next_node
+        end
+
+        root
+      end
+
+      def uf_union(parent, rank, a, b)
+        if rank[a] < rank[b]
+          parent[a] = b
+        elsif rank[a] > rank[b]
+          parent[b] = a
+        else
+          parent[b] = a
+          rank[a] += 1
+        end
+      end
+
+      # ── Max flow helpers ──
+
+      def edmonds_karp(source, sink)
+        # Build residual capacity graph
+        capacity = Hash.new { |h, k| h[k] = Hash.new(0) }
+        @adjacency.each do |from, edges_list|
+          edges_list.each do |edge|
+            capacity[from][edge[:node]] += edge[:weight]
+          end
+        end
+
+        total_flow = 0
+        loop do
+          # BFS to find augmenting path
+          parent = { source => nil }
+          visited = { source => true }
+          queue = [source]
+
+          until queue.empty?
+            node = queue.shift
+            break if node == sink
+
+            capacity[node].each do |neighbor, cap|
+              next unless cap.positive? && !visited[neighbor]
+
+              visited[neighbor] = true
+              parent[neighbor] = node
+              queue << neighbor
+            end
+          end
+
+          break unless visited[sink]
+
+          # Find bottleneck
+          path_flow = Float::INFINITY
+          node = sink
+          while parent[node]
+            path_flow = [path_flow, capacity[parent[node]][node]].min
+            node = parent[node]
+          end
+
+          # Update residual capacities
+          node = sink
+          while parent[node]
+            capacity[parent[node]][node] -= path_flow
+            capacity[node][parent[node]] += path_flow
+            node = parent[node]
+          end
+
+          total_flow += path_flow
+        end
+
+        total_flow
+      end
+
+      # ── Bipartite helpers ──
+
+      def bipartite_neighbors(node)
+        result = Set.new
+        (@adjacency[node] || []).each { |e| result << e[:node] }
+        if @directed
+          @adjacency.each do |from, edges_list|
+            edges_list.each { |e| result << from if e[:node] == node }
+          end
+        end
+        result
+      end
+
+      # ── Tarjan's SCC ──
+
+      def tarjan_scc
+        index_counter = [0]
+        stack = []
+        on_stack = {}
+        index = {}
+        lowlink = {}
+        result = []
+
+        @adjacency.each_key do |node|
+          tarjan_visit(node, index_counter, stack, on_stack, index, lowlink, result) unless index.key?(node)
+        end
+
+        result
+      end
+
+      def tarjan_visit(node, index_counter, stack, on_stack, index, lowlink, result)
+        index[node] = index_counter[0]
+        lowlink[node] = index_counter[0]
+        index_counter[0] += 1
+        stack.push(node)
+        on_stack[node] = true
+
+        neighbors(node).each do |neighbor|
+          if !index.key?(neighbor)
+            tarjan_visit(neighbor, index_counter, stack, on_stack, index, lowlink, result)
+            lowlink[node] = [lowlink[node], lowlink[neighbor]].min
+          elsif on_stack[neighbor]
+            lowlink[node] = [lowlink[node], index[neighbor]].min
+          end
+        end
+
+        return unless lowlink[node] == index[node]
+
+        component = []
+        loop do
+          w = stack.pop
+          on_stack[w] = false
+          component << w
+          break if w == node
+        end
+        result << component
+      end
+
+      # ── DOT helpers ──
+
+      def dot_escape(value)
+        str = value.to_s
+        if str.match?(/\A[a-zA-Z_]\w*\z/)
+          str
+        else
+          "\"#{str.gsub('"', '\\"')}\""
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module Graph
-    VERSION = '0.1.4'
+    VERSION = '0.2.3'
   end
 end

data/lib/philiprehberger/graph.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'set'
 
 require_relative 'graph/version'
@@ -14,7 +15,7 @@ module Philiprehberger
     # @param directed [Boolean] whether the graph is directed
     # @return [Graph] a new graph instance
     def self.new(directed: false)
-      Graph.new(directed: directed)
+      Philiprehberger::Graph::Graph.new(directed: directed)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-graph
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.3
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-04-01 00:00:00.000000000 Z
 dependencies: []
 description: Graph data structure supporting directed and undirected modes with adjacency
   list storage. Includes BFS, DFS, Dijkstra shortest path, topological sort, cycle
@@ -25,11 +25,11 @@ files:
 - lib/philiprehberger/graph.rb
 - lib/philiprehberger/graph/graph.rb
 - lib/philiprehberger/graph/version.rb
-homepage: https://github.com/philiprehberger/rb-graph
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-graph
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-graph
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-graph
   source_code_uri: https://github.com/philiprehberger/rb-graph
   changelog_uri: https://github.com/philiprehberger/rb-graph/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-graph/issues