factorix 0.5.0

data/lib/factorix/dependency/graph.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "tsort"
+
+module Factorix
+  module Dependency
+    # Directed graph of MOD dependencies using TSort
+    #
+    # This graph represents the dependency relationships between MODs.
+    # Nodes are MODs, edges are dependencies. The graph uses Ruby's TSort
+    # module for topological sorting and cycle detection.
+    class Graph
+      include TSort
+
+      # Create a new empty dependency graph
+      def initialize
+        @nodes = {}   # MOD => Node
+        @edges = {}   # MOD => [Edge]
+      end
+
+      # Add a node to the graph
+      #
+      # @param node [Factorix::Dependency::Node] The node to add
+      # @return [void]
+      # @raise [DependencyGraphError] if a node for this MOD already exists
+      def add_node(node)
+        mod = node.mod
+        raise DependencyGraphError, "Node for #{mod} already exists" if @nodes.key?(mod)
+
+        @nodes[mod] = node
+        @edges[mod] ||= []
+      end
+
+      # Set the planned operation for an existing node
+      #
+      # @param mod [Factorix::MOD] The MOD to update
+      # @param operation [Symbol, nil] The planned operation (:install, :enable, :disable, :uninstall, or nil)
+      # @return [Node, nil] The updated node, or nil if node doesn't exist
+      def set_node_operation(mod, operation)
+        node = @nodes[mod]
+        return unless node
+
+        @nodes[mod] = node.with(operation:)
+      end
+
+      # Add an edge to the graph
+      #
+      # @param edge [Factorix::Dependency::Edge] The edge to add
+      # @return [void]
+      # @raise [DependencyGraphError] if from_mod node doesn't exist
+      def add_edge(edge)
+        from_mod = edge.from_mod
+        raise DependencyGraphError, "Node for #{from_mod} doesn't exist" unless @nodes.key?(from_mod)
+
+        @edges[from_mod] ||= []
+        @edges[from_mod] << edge
+      end
+
+      # Add an uninstalled MOD (Category C) to the graph
+      #
+      # Creates a node for an uninstalled MOD and adds edges for its dependencies.
+      # Used by the install command to extend the graph with MODs fetched from the Portal API.
+      #
+      # @param mod_info [API::MODInfo] MOD information from Portal API
+      # @param release [API::Release] The release to install
+      # @param operation [Symbol] The operation to perform (default: :install)
+      # @return [void]
+      def add_uninstalled_mod(mod_info, release, operation: :install)
+        mod = MOD[name: mod_info.name]
+
+        existing_node = @nodes[mod]
+        if existing_node
+          # If already installed but disabled, mark for enabling
+          set_node_operation(mod, :enable) if existing_node.installed? && !existing_node.enabled?
+          return
+        end
+
+        node = Node.new(mod:, version: release.version, enabled: false, installed: false, operation:)
+        add_node(node)
+
+        dependencies = release.info_json[:dependencies] || []
+        parser = Dependency::Parser.new
+
+        dependencies.each do |dep_string|
+          dependency = parser.parse(dep_string)
+          next if dependency.mod.base?
+
+          edge = Edge.new(from_mod: mod, to_mod: dependency.mod, type: dependency.type, version_requirement: dependency.version_requirement)
+
+          add_edge(edge)
+        end
+      end
+
+      # Get a node by MOD
+      #
+      # @param mod [Factorix::MOD] The MOD identifier
+      # @return [Factorix::Dependency::Node, nil] The node or nil if not found
+      def node(mod) = @nodes[mod]
+
+      # Get all nodes
+      #
+      # @return [Array<Factorix::Dependency::Node>] All nodes in the graph
+      def nodes = @nodes.values
+
+      # Get edges from a MOD
+      #
+      # @param mod [Factorix::MOD] The MOD identifier
+      # @return [Array<Factorix::Dependency::Edge>] Edges from this MOD
+      def edges_from(mod) = @edges[mod] || []
+
+      # Get edges to a MOD
+      #
+      # @param mod [Factorix::MOD] The MOD identifier
+      # @return [Array<Factorix::Dependency::Edge>] Edges to this MOD
+      def edges_to(mod) = @edges.values.flatten.select {|edge| edge.to_mod == mod }
+
+      # Find all enabled MODs that have a required dependency on the given MOD
+      #
+      # @param mod [Factorix::MOD] The MOD to find dependents for
+      # @return [Array<Factorix::MOD>] MODs that depend on the given MOD
+      def find_enabled_dependents(mod)
+        dependents = []
+
+        nodes.each do |node|
+          next unless node.enabled?
+
+          edges_from(node.mod).each do |edge|
+            next unless edge.required? && edge.to_mod == mod
+
+            dependents << node.mod
+            break
+          end
+        end
+
+        dependents
+      end
+
+      # Get all edges in the graph
+      #
+      # @return [Array<Factorix::Dependency::Edge>] All edges
+      def edges = @edges.values.flatten
+
+      # Check if the graph contains a node for the given MOD
+      #
+      # @param mod [Factorix::MOD] The MOD identifier
+      # @return [Boolean]
+      def node?(mod) = @nodes.key?(mod)
+
+      # Get the number of nodes in the graph
+      #
+      # @return [Integer]
+      def size = @nodes.size
+
+      # Check if the graph is empty
+      #
+      # @return [Boolean]
+      def empty? = @nodes.empty?
+
+      # Check if the graph contains cycles
+      #
+      # @return [Boolean] true if the graph has cycles
+      def cyclic?
+        tsort
+        false
+      rescue TSort::Cyclic
+        true
+      end
+
+      # Find strongly connected components (cycles)
+      #
+      # @return [Array<Array<Factorix::MOD>>] Array of cycles
+      def strongly_connected_components = each_strongly_connected_component.to_a
+
+      # TSort interface: iterate over each node
+      #
+      # @yield [Factorix::MOD] Each MOD in the graph
+      # @return [void]
+      def tsort_each_node(&) = @nodes.each_key(&)
+
+      # TSort interface: iterate over children of a node
+      #
+      # @param mod [Factorix::MOD] The MOD to get children for
+      # @yield [Factorix::MOD] Each child MOD
+      # @return [void]
+      def tsort_each_child(mod)
+        edges_from(mod).each do |edge|
+          # Only follow required dependency edges for cycle detection
+          # Skip optional, incompatible, load-neutral, and hidden edges
+          # Optional cycles are allowed in Factorio
+          next unless edge.required?
+
+          yield edge.to_mod if @nodes.key?(edge.to_mod)
+        end
+      end
+
+      # Get a string representation of the graph
+      #
+      # @return [String]
+      def to_s = "#<#{self.class.name} nodes=#{@nodes.size} edges=#{edges.size}>"
+
+      # Detailed inspection string
+      #
+      # @return [String]
+      def inspect
+        node_list = @nodes.values.join(", ")
+        "#<#{self.class.name} [#{node_list}]>"
+      end
+    end
+  end
+end

data/lib/factorix/dependency/list.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "tsort"
+
+module Factorix
+  module Dependency
+    # Represents a collection of MOD dependencies
+    #
+    # This class manages a collection of Dependency::Entry objects, providing
+    # filtering, validation, and circular dependency detection capabilities.
+    #
+    # @example Creating from dependency strings
+    #   deps = Dependency::List.from_strings(["base >= 1.0.0", "? optional-mod", "! bad-mod"])
+    #   deps.required.each { |dep| puts dep.to_s }
+    #   deps.optional.each { |dep| puts dep.to_s }
+    #
+    # @example Validating dependencies
+    #   available = {"base" => MODVersion.from_string("1.1.0")}
+    #   puts "Missing: #{deps.missing_required(available).join(", ")}"
+    #
+    # @example Detecting circular dependencies
+    #   mod_deps_map = {
+    #     "mod-a" => Dependency::List.from_strings(["mod-b"]),
+    #     "mod-b" => Dependency::List.from_strings(["mod-a"])
+    #   }
+    #   cycles = Dependency::List.detect_circular(mod_deps_map)
+    #   cycles.each { |cycle| puts "Cycle: #{cycle.join(" -> ")}" }
+    class List
+      include Enumerable
+
+      # TSort protocol implementation for dependency graph analysis
+      #
+      # This internal class wraps a dependency map and implements the TSort protocol
+      # to enable cycle detection using strongly connected components analysis.
+      class DependencyGraph
+        include TSort
+
+        # @param mod_deps_map [Hash<String, Dependency::List>] Map of MOD names to dependencies
+        def initialize(mod_deps_map) = @mod_deps_map = mod_deps_map
+
+        # Iterate through all nodes in the graph
+        #
+        # @yieldparam node [String] MOD name
+        def tsort_each_node(&) = @mod_deps_map.each_key(&)
+
+        # Iterate through children (dependencies) of a node
+        #
+        # @param node [String] MOD name
+        # @yieldparam child [String] Dependent MOD name
+        def tsort_each_child(node)
+          deps = @mod_deps_map[node]
+          return unless deps
+
+          deps.required.each do |dep|
+            yield(dep.mod.name) if @mod_deps_map.key?(dep.mod.name)
+          end
+        end
+      end
+      private_constant :DependencyGraph
+
+      # Create List from an array of dependency strings
+      #
+      # @param dependency_strings [Array<String>] Array of dependency strings from info.json
+      # @return [List] New instance with parsed dependencies
+      # @raise [ArgumentError] if any dependency string is invalid
+      #
+      # @example
+      #   deps = Dependency::List.from_strings(["base", "? some-mod >= 1.2.0"])
+      def self.from_strings(dependency_strings)
+        parser = Parser.new
+        dependencies = dependency_strings.map {|str| parser.parse(str) }
+        new(dependencies)
+      end
+
+      # Detect circular dependencies in a collection of MOD dependencies
+      #
+      # Uses TSort to detect cycles in the dependency graph.
+      # Only considers required dependencies (optional and load-neutral are ignored).
+      #
+      # @param mod_dependencies_map [Hash<String, Dependency::List>] Map of MOD names to their dependencies
+      # @return [Array<Array<String>>] Array of circular dependency chains, or empty array if none found
+      #
+      # @example
+      #   map = {
+      #     "mod-a" => Dependency::List.from_strings(["mod-b"]),
+      #     "mod-b" => Dependency::List.from_strings(["mod-a"])
+      #   }
+      #   cycles = Dependency::List.detect_circular(map)
+      #   # => [["mod-a", "mod-b", "mod-a"]]
+      def self.detect_circular(mod_dependencies_map)
+        graph = DependencyGraph.new(mod_dependencies_map)
+        cycles = []
+
+        # Detect self-dependencies (not detected by strongly_connected_components)
+        mod_dependencies_map.each do |mod_name, deps|
+          if deps.required.any? {|dep| dep.mod.name == mod_name }
+            cycles << [mod_name, mod_name]
+          end
+        end
+
+        # Get strongly connected components (cycles are components with size > 1)
+        scc_cycles = graph.strongly_connected_components.filter_map {|component|
+          next if component.size <= 1
+
+          # Add first element at the end to make cycle explicit
+          component + [component.first]
+        }
+
+        cycles + scc_cycles
+      end
+
+      # Initialize a List collection
+      #
+      # @param dependencies [Array<Entry>] Array of parsed dependency objects
+      # @return [void]
+      # @raise [ArgumentError] if dependencies is not an Array
+      # @raise [ArgumentError] if any element is not a Dependency::Entry
+      def initialize(dependencies=[])
+        unless dependencies.is_a?(Array)
+          raise ArgumentError, "dependencies must be an Array, got #{dependencies.class}"
+        end
+
+        dependencies.each_with_index do |dep, index|
+          unless dep.is_a?(Entry)
+            raise ArgumentError, "dependencies[#{index}] must be a Dependency::Entry, got #{dep.class}"
+          end
+        end
+
+        @dependencies = dependencies.freeze
+      end
+
+      # Iterate through all dependencies
+      #
+      # @yieldparam dependency [Entry] Each dependency in the collection
+      # @return [Enumerator] if no block is given
+      # @return [List] if a block is given
+      def each(&block)
+        return @dependencies.to_enum unless block
+
+        @dependencies.each(&block)
+        self
+      end
+
+      # Get all required dependencies
+      #
+      # @return [Array<Entry>] Array of required dependencies
+      def required = @dependencies.select(&:required?)
+
+      # Get all optional dependencies (including hidden optional)
+      #
+      # @return [Array<Entry>] Array of optional dependencies
+      def optional = @dependencies.select(&:optional?)
+
+      # Get all incompatible dependencies
+      #
+      # @return [Array<Entry>] Array of incompatible dependencies
+      def incompatible = @dependencies.select(&:incompatible?)
+
+      # Get all load-neutral dependencies
+      #
+      # @return [Array<Entry>] Array of load-neutral dependencies
+      def load_neutral = @dependencies.select(&:load_neutral?)
+
+      # Check if this collection depends on a specific MOD
+      #
+      # @param mod_name_or_mod [String, MOD] MOD name or MOD instance to check
+      # @return [Boolean] true if depends on the MOD (not incompatible), false otherwise
+      def depends_on?(mod_name_or_mod)
+        mod_name = mod_name_or_mod.is_a?(MOD) ? mod_name_or_mod.name : mod_name_or_mod.to_s
+
+        @dependencies.any? {|dep| dep.mod.name == mod_name && !dep.incompatible? }
+      end
+
+      # Check if this collection marks a MOD as incompatible
+      #
+      # @param mod_name_or_mod [String, MOD] MOD name or MOD instance to check
+      # @return [Boolean] true if marked as incompatible, false otherwise
+      def incompatible_with?(mod_name_or_mod)
+        mod_name = mod_name_or_mod.is_a?(MOD) ? mod_name_or_mod.name : mod_name_or_mod.to_s
+
+        @dependencies.any? {|dep| dep.mod.name == mod_name && dep.incompatible? }
+      end
+
+      # Check if the collection is empty
+      #
+      # @return [Boolean] true if no dependencies, false otherwise
+      def empty? = @dependencies.empty?
+
+      # Get the total number of dependencies
+      #
+      # @return [Integer] Number of dependencies
+      def size = @dependencies.size
+
+      # Check if all required dependencies are satisfied
+      #
+      # @param available_mods [Hash<String, MODVersion>] Available MODs and their versions
+      # @return [Boolean] true if all required dependencies are satisfied
+      def satisfied_by?(available_mods) = required.all? {|dep| (version = available_mods[dep.mod.name]) && dep.satisfied_by?(version) }
+
+      # Get list of incompatible MODs that are present
+      #
+      # @param available_mods [Hash<String, MODVersion>] Available MODs and their versions
+      # @return [Array<String>] Array of conflicting MOD names
+      def conflicts_with?(available_mods) = incompatible.filter_map {|dep| dep.mod.name if available_mods.key?(dep.mod.name) }
+
+      # Get list of missing required dependencies
+      #
+      # @param available_mods [Hash<String, MODVersion>] Available MODs and their versions
+      # @return [Array<String>] Array of missing MOD names
+      def missing_required(available_mods) = required.filter_map {|dep| dep.mod.name unless available_mods.key?(dep.mod.name) }
+
+      # Get list of dependencies with unsatisfied version requirements
+      #
+      # @param available_mods [Hash<String, MODVersion>] Available MODs and their versions
+      # @return [Hash<String, Hash<Symbol, String>>] Hash of {mod_name => {required: ..., actual: ...}}
+      def unsatisfied_versions(available_mods)
+        result = {}
+
+        required.each do |dep|
+          next unless dep.version_requirement # Skip if no version requirement
+
+          version = available_mods[dep.mod.name]
+          next unless version # Skip if not available (covered by missing_required)
+
+          next if dep.satisfied_by?(version)
+
+          result[dep.mod.name] = {required: dep.version_requirement.to_s, actual: version.to_s}
+        end
+
+        result
+      end
+
+      # Convert to array of dependency strings
+      #
+      # @return [Array<String>] Array of dependency strings
+      def to_a = @dependencies.map(&:to_s)
+
+      # Convert to hash keyed by MOD name
+      #
+      # @return [Hash<String, Entry>] Hash of {mod_name => dependency}
+      def to_h = @dependencies.to_h {|dep| [dep.mod.name, dep] }
+    end
+  end
+end

data/lib/factorix/dependency/mod_version_requirement.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Dependency
+    # Define MODVersionRequirement as an immutable data class
+    MODVersionRequirement = Data.define(:operator, :version)
+
+    # Represents a MOD version requirement with an operator and version
+    #
+    # This class is used in MOD dependencies to specify version constraints.
+    # It supports the following comparison operators: <, <=, =, >=, >
+    #
+    # @example Creating a version requirement
+    #   requirement = MODVersionRequirement[operator: ">=", version: MODVersion.from_string("1.2.0")]
+    #   requirement.satisfied_by?(MODVersion.from_string("1.3.0")) # => true
+    #   requirement.satisfied_by?(MODVersion.from_string("1.1.0")) # => false
+    class MODVersionRequirement
+      # @!attribute [r] operator
+      #   @return [String] Comparison operator (<, <=, =, >=, >)
+      # @!attribute [r] version
+      #   @return [MODVersion] Version to compare against
+
+      # Valid comparison operators
+      VALID_OPERATORS = ["<", "<=", "=", ">=", ">"].freeze
+      private_constant :VALID_OPERATORS
+
+      # Create a new MODVersionRequirement
+      #
+      # @param operator [String] Comparison operator (<, <=, =, >=, >)
+      # @param version [MODVersion] Version to compare against
+      # @return [MODVersionRequirement]
+      # @raise [ArgumentError] if operator is not valid
+      # @raise [ArgumentError] if version is not a MODVersion
+      def initialize(operator:, version:)
+        unless VALID_OPERATORS.include?(operator)
+          raise ArgumentError, "Invalid operator: #{operator}. Must be one of: #{VALID_OPERATORS.join(", ")}"
+        end
+
+        unless version.is_a?(MODVersion)
+          raise ArgumentError, "version must be a MODVersion, got #{version.class}"
+        end
+
+        super
+      end
+
+      # Check if a given version satisfies this requirement
+      #
+      # @param mod_version [MODVersion] Version to check
+      # @return [Boolean] true if the version satisfies the requirement
+      def satisfied_by?(mod_version)
+        case operator
+        when "="
+          mod_version == version
+        when ">="
+          mod_version >= version
+        when ">"
+          mod_version > version
+        when "<="
+          mod_version <= version
+        when "<"
+          mod_version < version
+        else
+          raise ArgumentError, "Unexpected operator: #{operator}"
+        end
+      end
+
+      # String representation of the requirement
+      #
+      # @return [String] String representation (e.g., ">= 1.2.0")
+      def to_s = "#{operator} #{version}"
+    end
+  end
+end

data/lib/factorix/dependency/node.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Dependency
+    Node = Data.define(:mod, :version, :enabled, :installed, :operation)
+
+    # Represents a MOD node in the dependency graph
+    #
+    # Each node represents a MOD with its version, installation state,
+    # and enabled state. Operations can be planned on nodes (:enable,
+    # :disable, :install, :uninstall).
+    class Node
+      # @!attribute [r] mod
+      #   @return [Factorix::MOD] The MOD identifier
+      # @!attribute [r] version
+      #   @return [Factorix::MODVersion] The MOD version
+      # @!attribute [r] enabled
+      #   @return [Boolean] Whether the MOD is enabled
+      # @!attribute [r] installed
+      #   @return [Boolean] Whether the MOD is installed
+      # @!attribute [r] operation
+      #   @return [Symbol, nil] Planned operation (:enable, :disable, :install, :uninstall, nil)
+
+      def initialize(mod:, version:, enabled: false, installed: false, operation: nil) = super
+
+      # Check if the MOD is enabled
+      #
+      # @return [Boolean]
+      def enabled? = enabled
+
+      # Check if the MOD is installed
+      #
+      # @return [Boolean]
+      def installed? = installed
+
+      # Check if an operation is planned for this node
+      #
+      # @return [Boolean]
+      def operation? = !operation.nil?
+
+      # String representation of the node
+      #
+      # @return [String]
+      def to_s
+        state_flags = []
+        state_flags << "enabled" if enabled
+        state_flags << "installed" if installed
+        state_flags << "op:#{operation}" if operation
+
+        state = state_flags.empty? ? "new" : state_flags.join(", ")
+        "#{mod} v#{version} (#{state})"
+      end
+
+      # Detailed inspection string
+      #
+      # @return [String]
+      def inspect = "#<#{self.class.name} #{self}>"
+    end
+  end
+end