philiprehberger-dependency_graph 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 14caf2b96dc00176fbb8c735d7e3a422ba7fa072afc920b8823cb0d8001924bb
+  data.tar.gz: 314339dfad0850e220045e048522d9e42576ea9152baf95436c234766d3b620d
+SHA512:
+  metadata.gz: 109656f98b923105df821c4c1e2833dddbd44011e4b11696b6aaf956a033410ce3d879d7e632f344c38e532b4d1cfc6a0a4931097f5c20f822687c976f03ef21
+  data.tar.gz: fa4193c6610e9bdf3e3b7878e023cfb4fa18ddb550b5c77a45a38b710d2799e006fa50442754faf55a93c771aa8a1f44e414785dfb64d3c620b9e1631388538e

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Dependency graph construction with `add` method
+- Topological sort resolution via `resolve`
+- Parallel batch scheduling via `parallel_batches`
+- Cycle detection with `cycle?` and `cycles`
+- Support for diamond and transitive dependencies

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,97 @@
+# philiprehberger-dependency_graph
+
+[![Tests](https://github.com/philiprehberger/rb-dependency-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-dependency-graph/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-dependency_graph.svg)](https://rubygems.org/gems/philiprehberger-dependency_graph)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-dependency-graph)](LICENSE)
+
+Dependency resolver with topological sort and parallel batch scheduling
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-dependency_graph"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-dependency_graph
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/dependency_graph"
+
+graph = Philiprehberger::DependencyGraph.new
+graph.add(:a)
+graph.add(:b, depends_on: [:a])
+graph.add(:c, depends_on: [:a])
+graph.add(:d, depends_on: [:b, :c])
+
+graph.resolve  # => [:a, :b, :c, :d] (dependencies first)
+```
+
+### Parallel Batches
+
+```ruby
+graph = Philiprehberger::DependencyGraph.new
+graph.add(:a)
+graph.add(:b, depends_on: [:a])
+graph.add(:c, depends_on: [:a])
+graph.add(:d, depends_on: [:b, :c])
+
+graph.parallel_batches
+# => [[:a], [:b, :c], [:d]]
+# Batch 1: run :a
+# Batch 2: run :b and :c in parallel
+# Batch 3: run :d
+```
+
+### Cycle Detection
+
+```ruby
+graph = Philiprehberger::DependencyGraph.new
+graph.add(:a, depends_on: [:b])
+graph.add(:b, depends_on: [:a])
+
+graph.cycle?  # => true
+graph.cycles  # => [[:a, :b, :a]]
+```
+
+### Chaining
+
+```ruby
+graph = Philiprehberger::DependencyGraph.new
+graph.add(:a).add(:b, depends_on: [:a]).add(:c, depends_on: [:b])
+graph.resolve  # => [:a, :b, :c]
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `DependencyGraph.new` | Create a new empty graph |
+| `Graph#add(item, depends_on:)` | Add an item with dependencies |
+| `Graph#resolve` | Topological sort, dependencies first |
+| `Graph#parallel_batches` | Group into parallel execution batches |
+| `Graph#cycle?` | Check if the graph contains cycles |
+| `Graph#cycles` | List all detected cycles |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/dependency_graph/graph.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module DependencyGraph
+    # Directed acyclic graph for dependency resolution
+    class Graph
+      Error = DependencyGraph::Error
+
+      # @return [Hash] the adjacency list (item => dependencies)
+      attr_reader :nodes
+
+      def initialize
+        @nodes = {}
+      end
+
+      # Add an item with its dependencies
+      #
+      # @param item [Object] the item to add
+      # @param depends_on [Array] the items this item depends on
+      # @return [self]
+      def add(item, depends_on: [])
+        @nodes[item] ||= []
+        depends_on.each do |dep|
+          @nodes[dep] ||= []
+          @nodes[item] << dep unless @nodes[item].include?(dep)
+        end
+        self
+      end
+
+      # Resolve dependencies using topological sort (Kahn's algorithm)
+      #
+      # @return [Array] items in dependency order (dependencies first)
+      # @raise [Error] if a cycle is detected
+      def resolve
+        raise Error, "Cycle detected: #{cycles.first.join(' -> ')}" if cycle?
+
+        in_degree = Hash.new(0)
+        @nodes.each_key { |node| in_degree[node] ||= 0 }
+        @nodes.each_value do |deps|
+          deps.each { |dep| in_degree[dep] += 1 }
+        end
+
+        queue = @nodes.keys.select { |node| in_degree[node].zero? }
+        result = []
+
+        until queue.empty?
+          node = queue.shift
+          result << node
+          @nodes[node].each do |dep|
+            in_degree[dep] -= 1
+            queue << dep if in_degree[dep].zero?
+          end
+        end
+
+        result.reverse
+      end
+
+      # Group items into parallel execution batches
+      #
+      # @return [Array<Array>] batches where items in each batch can run in parallel
+      # @raise [Error] if a cycle is detected
+      def parallel_batches
+        raise Error, "Cycle detected: #{cycles.first.join(' -> ')}" if cycle?
+
+        remaining = @nodes.keys.dup
+        resolved = []
+        batches = []
+
+        until remaining.empty?
+          batch = remaining.select do |item|
+            @nodes[item].all? { |dep| resolved.include?(dep) }
+          end
+
+          raise Error, 'Unable to resolve dependencies' if batch.empty?
+
+          batches << batch
+          resolved.concat(batch)
+          remaining -= batch
+        end
+
+        batches
+      end
+
+      # Check if the graph contains any cycles
+      #
+      # @return [Boolean]
+      def cycle?
+        !cycles.empty?
+      end
+
+      # Find all cycles in the graph
+      #
+      # @return [Array<Array>] list of cycles, each cycle is an array of items
+      def cycles
+        found_cycles = []
+        visited = {}
+        stack = {}
+
+        @nodes.each_key do |node|
+          next if visited[node]
+
+          detect_cycles(node, visited, stack, [], found_cycles)
+        end
+
+        found_cycles
+      end
+
+      private
+
+      def detect_cycles(node, visited, stack, path, found_cycles)
+        visited[node] = true
+        stack[node] = true
+        path = path + [node]
+
+        @nodes[node]&.each do |dep|
+          if stack[dep]
+            cycle_start = path.index(dep)
+            found_cycles << path[cycle_start..] + [dep] if cycle_start
+          elsif !visited[dep]
+            detect_cycles(dep, visited, stack, path, found_cycles)
+          end
+        end
+
+        stack.delete(node)
+      end
+    end
+  end
+end

data/lib/philiprehberger/dependency_graph/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module DependencyGraph
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/dependency_graph.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'dependency_graph/version'
+
+module Philiprehberger
+  module DependencyGraph
+    class Error < StandardError; end
+  end
+end
+
+require_relative 'dependency_graph/graph'
+
+module Philiprehberger
+  module DependencyGraph
+
+    # Create a new dependency graph
+    #
+    # @return [Graph] a new empty graph
+    def self.new
+      Graph.new
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-dependency_graph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: Build and resolve dependency graphs using topological sort, detect cycles,
+  and generate parallel execution batches for concurrent task scheduling.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/dependency_graph.rb
+- lib/philiprehberger/dependency_graph/graph.rb
+- lib/philiprehberger/dependency_graph/version.rb
+homepage: https://github.com/philiprehberger/rb-dependency-graph
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-dependency-graph
+  source_code_uri: https://github.com/philiprehberger/rb-dependency-graph
+  changelog_uri: https://github.com/philiprehberger/rb-dependency-graph/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-dependency-graph/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Dependency resolver with topological sort and parallel batch scheduling
+test_files: []