factorix 0.5.0

data/lib/factorix/dependency/parser.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Factorix
+  module Dependency
+    # Parser for MOD dependency strings using Parslet
+    #
+    # This class parses dependency strings from info.json files and converts them
+    # into Dependency::Entry objects using a PEG-based parser.
+    #
+    # @example Parsing various dependency formats
+    #   parser = Dependency::Parser.new
+    #
+    #   # Required dependency
+    #   dep1 = parser.parse("base")
+    #
+    #   # Optional dependency with version
+    #   dep2 = parser.parse("? some-mod >= 1.2.0")
+    #
+    #   # Incompatible MOD
+    #   dep3 = parser.parse("! bad-mod")
+    #
+    #   # Hidden optional
+    #   dep4 = parser.parse("(?) hidden-mod")
+    #
+    #   # Load-neutral
+    #   dep5 = parser.parse("~ neutral-mod")
+    class Parser
+      # Parslet grammar for dependency strings
+      class Grammar < Parslet::Parser
+        rule(:space) { match['\s'].repeat(1) }
+        rule(:space?) { space.maybe }
+
+        # Prefix rules (longest first to avoid partial matches)
+        rule(:prefix) do
+          str("(?)").as(:hidden_optional) |
+            str("!").as(:incompatible) |
+            str("?").as(:optional) |
+            str("~").as(:load_neutral)
+        end
+
+        # MOD name: starts with alphanumeric, can contain spaces
+        # Cannot start with operators or contain only operators
+        rule(:mod_name_start) { match["a-zA-Z0-9_-"] }
+        rule(:mod_name_char) { match["a-zA-Z0-9_-"] | (space >> match["a-zA-Z0-9_-"].repeat(1)) }
+        rule(:mod_name) { (mod_name_start >> mod_name_char.repeat).as(:mod_name) }
+
+        # Version operators (longest first)
+        rule(:operator) do
+          (str(">=") | str("<=") | str(">") | str("<") | str("=")).as(:operator)
+        end
+
+        # Version: X.Y.Z or X.Y format
+        rule(:version) do
+          (match["0-9"].repeat(1) >> str(".") >> match["0-9"].repeat(1) >> (str(".") >> match["0-9"].repeat(1)).maybe).as(:version)
+        end
+
+        # Version requirement: operator space version
+        rule(:version_requirement) do
+          space? >> operator >> space? >> version
+        end
+
+        # Complete dependency: [prefix] [space] mod_name [version_requirement]
+        rule(:dependency) do
+          space? >>
+            prefix.maybe.as(:prefix) >>
+            space? >>
+            mod_name >>
+            version_requirement.maybe.as(:requirement) >>
+            space?
+        end
+
+        root(:dependency)
+      end
+
+      # Transform parsed tree into structured data
+      class Transform < Parslet::Transform
+        rule(mod_name: simple(:name)) { {mod_name: name.to_s.strip} }
+
+        rule(version: simple(:ver)) { {version: ver.to_s} }
+
+        rule(operator: simple(:op), version: simple(:ver)) do
+          {operator: op.to_s, version: ver.to_s}
+        end
+
+        rule(optional: simple(:_)) { {type: Entry::OPTIONAL} }
+        rule(hidden_optional: simple(:_)) { {type: Entry::HIDDEN_OPTIONAL} }
+        rule(incompatible: simple(:_)) { {type: Entry::INCOMPATIBLE} }
+        rule(load_neutral: simple(:_)) { {type: Entry::LOAD_NEUTRAL} }
+      end
+
+      def initialize
+        @grammar = Grammar.new
+        @transform = Transform.new
+      end
+
+      # Parse a dependency string into a Dependency::Entry object
+      #
+      # @param dependency_string [String] Dependency string to parse
+      # @return [Entry] Parsed dependency object
+      # @raise [DependencyParseError] if the dependency string is invalid
+      def parse(dependency_string)
+        raise DependencyParseError, "dependency_string cannot be nil or empty" if dependency_string.nil? || dependency_string.empty?
+
+        begin
+          tree = @grammar.parse(dependency_string)
+          data = @transform.apply(tree)
+
+          mod_name = data[:mod_name].to_s
+          mod = MOD[name: mod_name]
+          type = data.dig(:prefix, :type) || Entry::REQUIRED
+          version_requirement = build_version_requirement(data[:requirement])
+
+          Entry[mod:, type:, version_requirement:]
+        rescue Parslet::ParseFailed => e
+          raise DependencyParseError, parse_error_message(dependency_string, e)
+        end
+      end
+
+      private def build_version_requirement(requirement_data)
+        return nil if requirement_data.nil? || requirement_data.empty?
+
+        operator = requirement_data[:operator]
+        version_string = requirement_data[:version]
+
+        version = MODVersion.from_string(version_string)
+        MODVersionRequirement[operator:, version:]
+      rescue VersionParseError => e
+        # Skip version requirements with out-of-range version components
+        Application[:logger].warn("Skipping version requirement '#{version_string}': #{e.message}")
+        nil
+      end
+
+      private def parse_error_message(input, error)
+        if input.strip.match?(/^[><=]+/)
+          "Invalid dependency format: empty MOD name (input: #{input.inspect})"
+        elsif input.match?(/[><=]\s*$/)
+          "Invalid dependency format: empty version (input: #{input.inspect})"
+        elsif input.match?(/[><=]\s+\S+$/) && !input.match?(/[><=]\s+\d+\.\d+\.\d+/)
+          "Invalid version requirement: invalid version format (input: #{input.inspect})"
+        else
+          "Invalid dependency format (input: #{input.inspect}): #{error.parse_failure_cause.ascii_tree}"
+        end
+      end
+    end
+  end
+end

data/lib/factorix/dependency/validation_result.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Dependency
+    # Represents the result of MOD dependency validation
+    #
+    # Holds errors and warnings found during validation.
+    class ValidationResult
+      Error = Data.define(:type, :message, :mod, :dependency)
+
+      # Validation error information
+      #
+      # Represents an error found during dependency validation.
+      class Error
+        # @!attribute [r] type
+        #   @return [Symbol] error type
+        # @!attribute [r] message
+        #   @return [String] error message
+        # @!attribute [r] mod
+        #   @return [Factorix::MOD, nil] related MOD
+        # @!attribute [r] dependency
+        #   @return [Factorix::MOD, nil] dependency MOD
+      end
+
+      Warning = Data.define(:type, :message, :mod)
+
+      # Validation warning information
+      #
+      # Represents a warning found during dependency validation.
+      class Warning
+        # @!attribute [r] type
+        #   @return [Symbol] warning type
+        # @!attribute [r] message
+        #   @return [String] warning message
+        # @!attribute [r] mod
+        #   @return [Factorix::MOD, nil] related MOD
+      end
+
+      Suggestion = Data.define(:message, :mod, :version)
+
+      # Validation suggestion information
+      #
+      # Represents a suggestion for resolving dependency issues.
+      class Suggestion
+        # @!attribute [r] message
+        #   @return [String] suggestion message
+        # @!attribute [r] mod
+        #   @return [Factorix::MOD] related MOD
+        # @!attribute [r] version
+        #   @return [Factorix::MODVersion] suggested version
+      end
+
+      # Error types
+      MISSING_DEPENDENCY = :missing_dependency
+      public_constant :MISSING_DEPENDENCY
+      DISABLED_DEPENDENCY = :disabled_dependency
+      public_constant :DISABLED_DEPENDENCY
+      VERSION_MISMATCH = :version_mismatch
+      public_constant :VERSION_MISMATCH
+      CONFLICT = :conflict
+      public_constant :CONFLICT
+      CIRCULAR_DEPENDENCY = :circular_dependency
+      public_constant :CIRCULAR_DEPENDENCY
+
+      # Warning types
+      MOD_IN_LIST_NOT_INSTALLED = :mod_in_list_not_installed
+      public_constant :MOD_IN_LIST_NOT_INSTALLED
+      MOD_INSTALLED_NOT_IN_LIST = :mod_installed_not_in_list
+      public_constant :MOD_INSTALLED_NOT_IN_LIST
+
+      def initialize
+        @errors = []
+        @warnings = []
+        @suggestions = []
+      end
+
+      # Add an error
+      #
+      # @param type [Symbol] Error type
+      # @param message [String] Error message
+      # @param mod [Factorix::MOD, nil] Related MOD
+      # @param dependency [Factorix::MOD, nil] Dependency MOD
+      # @return [void]
+      def add_error(type:, message:, mod: nil, dependency: nil) = @errors << Error.new(type:, message:, mod:, dependency:)
+
+      # Add a warning
+      #
+      # @param type [Symbol] Warning type
+      # @param message [String] Warning message
+      # @param mod [Factorix::MOD, nil] Related MOD
+      # @return [void]
+      def add_warning(type:, message:, mod: nil) = @warnings << Warning.new(type:, message:, mod:)
+
+      # Add a suggestion
+      #
+      # @param message [String] Suggestion message
+      # @param mod [Factorix::MOD] Related MOD
+      # @param version [Factorix::MODVersion] Suggested version
+      # @return [void]
+      def add_suggestion(message:, mod:, version:) = @suggestions << Suggestion.new(message:, mod:, version:)
+
+      # Get all errors
+      #
+      # @return [Array<Error>]
+      attr_reader :errors
+
+      # Get all warnings
+      #
+      # @return [Array<Warning>]
+      attr_reader :warnings
+
+      # Get all suggestions
+      #
+      # @return [Array<Suggestion>]
+      attr_reader :suggestions
+
+      # Check if there are any errors
+      #
+      # @return [Boolean]
+      def errors? = !@errors.empty?
+
+      # Check if there are any warnings
+      #
+      # @return [Boolean]
+      def warnings? = !@warnings.empty?
+
+      # Check if there are any suggestions
+      #
+      # @return [Boolean]
+      def suggestions? = !@suggestions.empty?
+
+      # Check if validation passed (no errors)
+      #
+      # @return [Boolean]
+      def valid? = !errors?
+    end
+  end
+end

data/lib/factorix/dependency/validator.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Dependency
+    # Validates MOD dependencies in a graph
+    #
+    # Performs comprehensive validation of MOD dependencies including:
+    # - Required dependencies are installed and enabled
+    # - Version requirements are satisfied
+    # - No conflicts between enabled MODs
+    # - No circular dependencies
+    class Validator
+      # Initialize validator
+      #
+      # @param graph [Factorix::Dependency::Graph] The dependency graph
+      # @param mod_list [Factorix::MODList] The MOD list
+      # @param installed_mods [Array<Factorix::InstalledMOD>] The installed MODs
+      def initialize(graph:, mod_list:, installed_mods:)
+        @graph = graph
+        @mod_list = mod_list
+        @installed_mods = installed_mods
+      end
+
+      # Validate the graph
+      #
+      # @return [Factorix::Dependency::ValidationResult]
+      def validate
+        result = ValidationResult.new
+
+        validate_circular_dependencies(result)
+        validate_dependencies(result)
+        validate_conflicts(result)
+        validate_mod_list(result)
+
+        result
+      end
+
+      private attr_reader :graph, :mod_list, :installed_mods
+
+      private def validate_circular_dependencies(result)
+        return unless graph.cyclic?
+
+        components = graph.strongly_connected_components
+        cycles = components.select {|component| component.size > 1 }
+
+        cycles.each do |cycle|
+          mod_names = cycle.map(&:name).join(" -> ")
+          result.add_error(
+            type: ValidationResult::CIRCULAR_DEPENDENCY,
+            message: "Circular dependency detected: #{mod_names}"
+          )
+        end
+      end
+
+      # Validate dependencies for all enabled MODs
+      private def validate_dependencies(result)
+        graph.nodes.each do |node|
+          next unless node.enabled?
+
+          validate_node_dependencies(node, result)
+        end
+      end
+
+      # Validate dependencies for a single node
+      private def validate_node_dependencies(node, result)
+        graph.edges_from(node.mod).each do |edge|
+          next unless edge.required?
+
+          validate_required_dependency(node, edge, result)
+        end
+      end
+
+      # Validate a single required dependency
+      private def validate_required_dependency(node, edge, result)
+        dependency_node = graph.node(edge.to_mod)
+
+        unless dependency_node
+          result.add_error(
+            type: ValidationResult::MISSING_DEPENDENCY,
+            message: "MOD '#{node.mod}@#{node.version}' requires '#{edge.to_mod}' which is not installed",
+            mod: node.mod,
+            dependency: edge.to_mod
+          )
+          return
+        end
+
+        unless dependency_node.enabled?
+          result.add_error(
+            type: ValidationResult::DISABLED_DEPENDENCY,
+            message: "MOD '#{node.mod}@#{node.version}' requires '#{edge.to_mod}' which is not enabled",
+            mod: node.mod,
+            dependency: edge.to_mod
+          )
+          return
+        end
+
+        return if edge.satisfied_by?(dependency_node.version)
+
+        result.add_error(
+          type: ValidationResult::VERSION_MISMATCH,
+          message: "MOD '#{node.mod}@#{node.version}' requires '#{edge.to_mod}' version " \
+                   "#{edge.version_requirement}, but version #{dependency_node.version} is installed",
+          mod: node.mod,
+          dependency: edge.to_mod
+        )
+
+        check_alternative_versions(edge, result)
+      end
+
+      # Validate that no conflicts exist between enabled MODs
+      private def validate_conflicts(result)
+        graph.nodes.each do |node|
+          next unless node.enabled?
+
+          validate_node_conflicts(node, result)
+        end
+      end
+
+      # Validate conflicts for a single node
+      private def validate_node_conflicts(node, result)
+        graph.edges_from(node.mod).each do |edge|
+          next unless edge.incompatible?
+
+          conflict_node = graph.node(edge.to_mod)
+          next unless conflict_node&.enabled?
+
+          result.add_error(
+            type: ValidationResult::CONFLICT,
+            message: "MOD '#{node.mod}@#{node.version}' conflicts with '#{edge.to_mod}@#{conflict_node.version}' but both are enabled",
+            mod: node.mod,
+            dependency: edge.to_mod
+          )
+        end
+      end
+
+      # Validate MOD list consistency
+      private def validate_mod_list(result)
+        validate_mods_in_list_not_installed(result)
+        validate_mods_installed_not_in_list(result)
+      end
+
+      # Warn about MODs in list but not installed
+      private def validate_mods_in_list_not_installed(result)
+        mod_list.each_mod do |mod|
+          next if graph.node?(mod)
+
+          result.add_warning(
+            type: ValidationResult::MOD_IN_LIST_NOT_INSTALLED,
+            message: "MOD '#{mod}' in mod-list.json is not installed",
+            mod:
+          )
+        end
+      end
+
+      # Warn about installed MODs not in list
+      private def validate_mods_installed_not_in_list(result)
+        graph.nodes.each do |node|
+          next if mod_list.exist?(node.mod)
+
+          result.add_warning(
+            type: ValidationResult::MOD_INSTALLED_NOT_IN_LIST,
+            message: "MOD '#{node.mod}' is installed but not in mod-list.json",
+            mod: node.mod
+          )
+        end
+      end
+
+      # Check for alternative installed versions that satisfy a requirement
+      #
+      # @param edge [Factorix::Dependency::Edge] The dependency edge with version requirement
+      # @param result [Factorix::Dependency::ValidationResult] The validation result to add suggestions to
+      # @return [void]
+      private def check_alternative_versions(edge, result)
+        return if installed_mods.empty?
+
+        alternative_versions = installed_mods.select {|im| im.mod == edge.to_mod }
+
+        alternative_versions.each do |installed_mod|
+          next unless edge.satisfied_by?(installed_mod.version)
+
+          result.add_suggestion(
+            message: "MOD '#{edge.to_mod}' version #{installed_mod.version} is installed and would satisfy this requirement",
+            mod: edge.to_mod,
+            version: installed_mod.version
+          )
+        end
+      end
+    end
+  end
+end

data/lib/factorix/errors.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Factorix
+  # Base error class for Factorix
+  class Error < StandardError; end
+
+  # =====================================
+  # Infrastructure layer errors
+  # =====================================
+  class InfrastructureError < Error; end
+
+  # Configuration errors
+  class ConfigurationError < InfrastructureError; end
+
+  # Credential/environment variable errors
+  class CredentialError < ConfigurationError; end
+
+  # Shell/completion errors
+  class ShellError < ConfigurationError; end
+
+  # Directory not found errors
+  class DirectoryNotFoundError < ConfigurationError; end
+
+  # URL related errors
+  class URLError < InfrastructureError; end
+
+  # Platform-specific errors (WSL, etc.)
+  class PlatformError < InfrastructureError; end
+
+  # Unsupported platform errors
+  class UnsupportedPlatformError < PlatformError; end
+
+  # HTTP errors
+  class HTTPError < InfrastructureError; end
+
+  # HTTP client error (4xx) with optional API error details
+  class HTTPClientError < HTTPError
+    attr_reader :api_error
+    attr_reader :api_message
+
+    def initialize(message=nil, api_error: nil, api_message: nil)
+      @api_error = api_error
+      @api_message = api_message
+      super(message)
+    end
+  end
+
+  class HTTPNotFoundError < HTTPClientError; end
+  class HTTPServerError < HTTPError; end
+
+  # Digest verification errors
+  class DigestMismatchError < InfrastructureError; end
+
+  # External command not found
+  class CommandNotFoundError < InfrastructureError; end
+
+  # File format related errors
+  class FileFormatError < InfrastructureError; end
+
+  # Binary format errors
+  class BinaryFormatError < FileFormatError; end
+  class InvalidLengthError < BinaryFormatError; end
+  class UnknownPropertyType < BinaryFormatError; end
+  class ExtraDataError < BinaryFormatError; end
+
+  # MOD settings file errors
+  class MODSectionNotFoundError < FileFormatError; end
+
+  # =====================================
+  # Domain layer errors
+  # =====================================
+  class DomainError < Error; end
+
+  # MOD errors
+  class MODNotFoundError < DomainError; end
+  class MODNotOnPortalError < MODNotFoundError; end
+  class BundledMODError < DomainError; end
+
+  # MOD conflict errors
+  class MODConflictError < DomainError; end
+
+  # MOD settings errors
+  class MODSettingsError < DomainError; end
+
+  # Invalid operation errors (e.g., cannot disable base MOD)
+  class InvalidOperationError < DomainError; end
+
+  # CLI argument validation errors
+  class InvalidArgumentError < DomainError; end
+
+  # Version parsing errors
+  class VersionParseError < DomainError; end
+
+  # Dependency parsing errors
+  class DependencyParseError < DomainError; end
+
+  # Dependency graph errors
+  class DependencyGraphError < DomainError; end
+
+  # Dependency errors
+  class DependencyError < DomainError; end
+  class CircularDependencyError < DependencyError; end
+  class DependencyMissingError < DependencyError; end
+  class DependencyVersionError < DependencyError; end
+  class DependencyViolationError < DependencyError; end
+
+  # Dependency validation errors
+  class ValidationError < DomainError; end
+
+  # Game state errors
+  class GameRunningError < DomainError; end
+end

data/lib/factorix/formatting.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Factorix
+  # Formatting utilities for human-readable output
+  #
+  # This module provides methods for formatting sizes and durations
+  # in a human-readable format for CLI output.
+  #
+  # @example
+  #   include Factorix::Formatting
+  #   format_size(1536)      # => "1.5 KiB"
+  #   format_duration(3661)  # => "1h 1m"
+  module Formatting
+    # Format size value for display using binary prefixes (IEC)
+    #
+    # @param size [Integer, nil] size in bytes
+    # @return [String] formatted size ("unlimited" if nil)
+    def format_size(size)
+      return "unlimited" if size.nil?
+      return "0 B" if size == 0
+
+      units = %w[B KiB MiB GiB TiB]
+      unit_index = 0
+      value = Float(size)
+
+      while value >= 1024 && unit_index < units.size - 1
+        value /= 1024
+        unit_index += 1
+      end
+
+      unit_index == 0 ? "#{size} B" : "#{"%.1f" % value} #{units[unit_index]}"
+    end
+
+    # Format duration value for display
+    #
+    # @param seconds [Integer, Float, nil] duration in seconds
+    # @return [String] formatted duration ("-" if nil)
+    def format_duration(seconds)
+      return "-" if seconds.nil?
+
+      seconds = Integer(seconds)
+      return "#{seconds}s" if seconds < 60
+
+      minutes = seconds / 60
+      return "#{minutes}m" if minutes < 60
+
+      hours = minutes / 60
+      remaining_minutes = minutes % 60
+      return "#{hours}h #{remaining_minutes}m" if hours < 24
+
+      days = hours / 24
+      remaining_hours = hours % 24
+      "#{days}d #{remaining_hours}h"
+    end
+  end
+end