factorix 0.5.0

data/lib/factorix/installed_mod.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "concurrent/executor/fixed_thread_pool"
+require "concurrent/future"
+require "dry/events"
+
+module Factorix
+  InstalledMOD = Data.define(:mod, :version, :form, :path, :info)
+
+  # Represents a MOD installed in the MOD directory or data directory
+  #
+  # InstalledMOD represents an actual MOD package found in either:
+  # - The MOD directory (user-installed MODs as ZIP files or directories)
+  # - The data directory (base and expansion MODs bundled with the game)
+  #
+  # This is distinct from MOD (which is just a name identifier) and
+  # MODState (which represents desired state in mod-list.json).
+  class InstalledMOD
+    # @!attribute [r] mod
+    #   @return [Factorix::MOD] The MOD identifier
+    # @!attribute [r] version
+    #   @return [Factorix::MODVersion] The MOD version
+    # @!attribute [r] form
+    #   @return [Symbol] :zip or :directory
+    # @!attribute [r] path
+    #   @return [Pathname] The path to the ZIP file or directory
+    # @!attribute [r] info
+    #   @return [Factorix::InfoJSON] The parsed info.json metadata
+
+    include Comparable
+
+    # Make the class itself enumerable over all installed MODs
+    extend Enumerable
+
+    # Form constants
+    ZIP_FORM = :zip
+    public_constant :ZIP_FORM
+    DIRECTORY_FORM = :directory
+    public_constant :DIRECTORY_FORM
+
+    # Get all installed MODs
+    #
+    # @param handler [Progress::ScanHandler, nil] optional event handler for progress tracking
+    # @return [Array<InstalledMOD>] Array of all installed MODs
+    def self.all(handler: nil)
+      scanner = Scanner.new
+      scanner.subscribe(handler) if handler
+      result = scanner.scan
+      scanner.unsubscribe(handler) if handler
+      result
+    end
+
+    # Enumerate over all installed MODs
+    #
+    # @yieldparam [InstalledMOD] mod Each installed MOD
+    # @return [Enumerator, Array] Enumerator if no block given, otherwise the result of the block
+    def self.each(&) = all.each(&)
+
+    # Create InstalledMOD from a ZIP file
+    #
+    # @param path [Pathname] Path to the ZIP file
+    # @return [InstalledMOD] New InstalledMOD instance
+    # @raise [FileFormatError] if ZIP file is invalid
+    def self.from_zip(path)
+      info = InfoJSON.from_zip(path)
+
+      expected_filename = "#{info.name}_#{info.version}.zip"
+      actual_filename = path.basename.to_s
+
+      unless actual_filename == expected_filename
+        raise FileFormatError, "Filename mismatch: expected #{expected_filename}, got #{actual_filename}"
+      end
+
+      new(mod: MOD[name: info.name], version: info.version, form: ZIP_FORM, path:, info:)
+    end
+
+    # Create InstalledMOD from a directory
+    #
+    # @param path [Pathname] Path to the directory
+    # @return [InstalledMOD] New InstalledMOD instance
+    # @raise [FileFormatError] if directory is invalid
+    def self.from_directory(path)
+      info_path = path + "info.json"
+      raise FileFormatError, "Missing info.json" unless info_path.file?
+
+      info = InfoJSON.from_json(info_path.read)
+
+      dirname = path.basename.to_s
+      expected_unversioned = info.name
+      expected_versioned = "#{info.name}_#{info.version}"
+
+      unless dirname == expected_unversioned || dirname == expected_versioned
+        raise FileFormatError, "Directory name mismatch: expected #{expected_unversioned} or #{expected_versioned}, got #{dirname}"
+      end
+
+      new(mod: MOD[name: info.name], version: info.version, form: DIRECTORY_FORM, path:, info:)
+    end
+
+    # Scanner for finding installed MODs
+    #
+    # Scans MOD directory and data directory for installed MODs.
+    # Gets directory paths from Runtime automatically.
+    # Publishes progress events during scan.
+    class Scanner
+      include Import[:runtime, :logger]
+      include Dry::Events::Publisher[:scanner]
+
+      register_event("scan.started")
+      register_event("scan.progress")
+      register_event("scan.completed")
+
+      DEFAULT_PARALLEL_JOBS = 4
+      private_constant :DEFAULT_PARALLEL_JOBS
+
+      # Scan directories for installed MODs
+      #
+      # Scans the MOD directory for both ZIP and directory form MODs.
+      # Also scans the data directory for base/expansion MODs.
+      # Invalid packages are skipped with debug logging.
+      # Publishes scan.started, scan.progress, and scan.completed events.
+      #
+      # @return [Array<InstalledMOD>] Array of installed MODs
+      def scan
+        mod_dir = runtime.mod_dir
+        data_dir = runtime.data_dir
+
+        mod_paths = mod_dir.children.select {|path| (path.file? && path.extname == ".zip") || path.directory? }
+        data_paths = data_dir.children.select {|path|
+          next false unless path.directory?
+
+          mod_name = path.basename.to_s
+          candidate_mod = MOD[name: mod_name]
+          candidate_mod.base? || candidate_mod.expansion?
+        }
+
+        total = mod_paths.size + data_paths.size
+        current = 0
+        mutex = Mutex.new
+
+        publish("scan.started", total:)
+
+        pool = Concurrent::FixedThreadPool.new(DEFAULT_PARALLEL_JOBS)
+
+        begin
+          futures = mod_paths.map {|path|
+            Concurrent::Future.execute(executor: pool) do
+              result = scan_mod_path(path)
+              mutex.synchronize do
+                current += 1
+                publish("scan.progress", current:, total:)
+              end
+              result
+            end
+          }
+
+          installed_mods = futures.filter_map(&:value)
+        ensure
+          pool.shutdown
+          pool.wait_for_termination
+        end
+
+        data_paths.each do |path|
+          result = scan_mod_path(path)
+          installed_mods << result if result
+          current += 1
+          publish("scan.progress", current:, total:)
+        end
+
+        publish("scan.completed", total: installed_mods.size)
+
+        resolved = resolve_duplicates(installed_mods)
+        resolved.sort_by(&:version).reverse
+      end
+
+      # Scan a single MOD path (ZIP file or directory)
+      #
+      # @param path [Pathname] Path to scan
+      # @return [InstalledMOD, nil] The installed MOD, or nil if invalid
+      private def scan_mod_path(path)
+        if path.file? && path.extname == ".zip"
+          InstalledMOD.from_zip(path)
+        elsif path.directory?
+          InstalledMOD.from_directory(path)
+        end
+      rescue ArgumentError => e
+        logger.debug("Skipping invalid MOD package", path: path.to_s, reason: e.message)
+        nil
+      rescue => e
+        logger.debug("Error loading MOD package", path: path.to_s, error: e.message)
+        nil
+      end
+
+      # Resolve duplicate MODs (same name and version)
+      #
+      # When multiple MODs with the same name and version exist, prefer
+      # directory form over ZIP form.
+      #
+      # @param mods [Array<InstalledMOD>] Array of installed MODs
+      # @return [Array<InstalledMOD>] Array with duplicates resolved
+      private def resolve_duplicates(mods)
+        groups = mods.group_by {|mod| [mod.mod, mod.version] }
+        groups.map {|_key, group_mods| group_mods.max }
+      end
+    end
+    private_constant :Scanner
+
+    # Compare with another InstalledMOD
+    #
+    # Comparison is by version (ascending), then by form (directory > ZIP)
+    #
+    # @param other [InstalledMOD] The other InstalledMOD
+    # @return [Integer, nil] -1, 0, 1 for less than, equal to, greater than; nil if not comparable
+    def <=>(other)
+      return nil unless other.is_a?(InstalledMOD)
+      return nil unless mod == other.mod
+
+      # Compare by version (ascending), then by form priority (directory > ZIP)
+      (version <=> other.version).nonzero? || form_priority(form) <=> form_priority(other.form)
+    end
+
+    # Check if this is the base MOD
+    #
+    # @return [Boolean] true if this is the base MOD
+    def base? = mod.base?
+
+    # Check if this is an expansion MOD
+    #
+    # @return [Boolean] true if this is an expansion MOD
+    def expansion? = mod.expansion?
+
+    private def form_priority(form)
+      case form
+      when DIRECTORY_FORM then 1
+      when ZIP_FORM then 0
+      else -1
+      end
+    end
+  end
+end

data/lib/factorix/mod.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Factorix
+  MOD = Data.define(:name)
+
+  # Represents a local MOD
+  #
+  # This class encapsulates a MOD's name and provides utility methods
+  # for MOD identification and comparison.
+  class MOD
+    include Comparable
+
+    # @!attribute [r] name
+    #   @return [String] the name of the MOD
+
+    # Expansion MOD names
+    EXPANSION_MODS = %w[space-age quality elevated-rails].freeze
+    private_constant :EXPANSION_MODS
+
+    # Check if this MOD is the base MOD
+    #
+    # @return [Boolean] true if this MOD is the base MOD
+    # @note The check is case-sensitive, only "base" (not "BASE" or "Base") is considered the base MOD
+    def base? = name == "base"
+
+    # Check if this MOD is an expansion MOD
+    #
+    # @return [Boolean] true if this MOD is an expansion MOD (space-age, quality, or elevated-rails)
+    # @note The check is case-sensitive
+    def expansion? = EXPANSION_MODS.include?(name)
+
+    # Return the name of the MOD
+    #
+    # @return [String] the name of the MOD
+    def to_s = name
+
+    # Compare this MOD with another MOD by name
+    #
+    # @param other [MOD] the other MOD
+    # @return [Integer] -1 if this MOD precedes the other, 0 if they are equal, 1 if this MOD follows the other
+    # @note Comparison is case-sensitive for MOD names.
+    # @note The base MOD (exactly "base", case-sensitive) always comes before any other MOD.
+    def <=>(other)
+      return nil unless other.is_a?(MOD)
+
+      if base?
+        other.base? ? 0 : -1
+      elsif other.base?
+        1
+      else
+        name <=> other.name
+      end
+    end
+  end
+end

data/lib/factorix/mod_list.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Factorix
+  # Represents a list of MODs and their enabled status
+  #
+  # This class manages the mod-list.json file, which contains the list of MODs
+  # and their enabled/disabled states.
+  class MODList
+    include Enumerable
+
+    # Raised when a MOD is not found in the list
+    class MODNotInListError < MODNotFoundError; end
+
+    # Load the MOD list from the given file
+    #
+    # @param path [Pathname] the path to the file to load the MOD list from (default: runtime.mod_list_path)
+    # @return [Factorix::MODList] the loaded MOD list
+    # @raise [MODSettingsError] if the base MOD is disabled
+    def self.load(path=Application[:runtime].mod_list_path)
+      raw_data = JSON.parse(path.read, symbolize_names: true)
+      mods_hash = raw_data[:mods].to_h {|entry|
+        mod = MOD[name: entry[:name]]
+        version = entry[:version] ? MODVersion.from_string(entry[:version]) : nil
+        state = MODState[enabled: entry[:enabled], version:]
+
+        # Validate that base MOD is not disabled
+        if mod.base? && !entry[:enabled]
+          raise MODSettingsError, "base MOD cannot be disabled"
+        end
+
+        [mod, state]
+      }
+      new(mods_hash)
+    end
+
+    # Initialize the MOD list
+    #
+    # @param mods [Hash{Factorix::MOD => Factorix::MODState}] the MODs and their state
+    # @return [void]
+    def initialize(mods={})
+      @mods = {}
+      mods.each do |mod, state|
+        @mods[mod] = state
+      end
+    end
+
+    # Save the MOD list to the given file
+    #
+    # @param path [Pathname] the path to the file to save the MOD list to (default: runtime.mod_list_path)
+    # @return [void]
+    def save(path=Application[:runtime].mod_list_path)
+      mods_data = @mods.map {|mod, state|
+        data = {name: mod.name, enabled: state.enabled?}
+        # Only include version in the output if it exists
+        data[:version] = state.version.to_s if state.version
+        data
+      }
+      path.write(JSON.pretty_generate({mods: mods_data}))
+    end
+
+    # Iterate through all MOD-state pairs
+    #
+    # @yieldparam mod [Factorix::MOD] the MOD
+    # @yieldparam state [Factorix::MODState] the MOD state
+    # @return [Enumerator] if no block is given
+    # @return [Factorix::MODList] if a block is given
+    def each(&block)
+      return @mods.to_enum unless block
+
+      @mods.each(&block)
+      self
+    end
+
+    # Iterate through all MODs
+    #
+    # @yieldparam mod [Factorix::MOD] the MOD
+    # @return [Enumerator] if no block is given
+    # @return [Factorix::MODList] if a block is given
+    def each_mod(&block)
+      return @mods.keys.to_enum unless block
+
+      @mods.each_key(&block)
+      self
+    end
+
+    # Alias for each_mod
+    #
+    # @yieldparam mod [Factorix::MOD] the MOD
+    # @return [Enumerator] if no block is given
+    # @return [Factorix::MODList] if a block is given
+    alias each_key each_mod
+
+    # Add the MOD to the list
+    #
+    # @param mod [Factorix::MOD] the MOD to add
+    # @param enabled [Boolean] the enabled status. Default to true
+    # @param version [Factorix::MODVersion, nil] the version of the MOD. Default to nil
+    # @return [void]
+    # @raise [MODSettingsError] if the MOD is the base MOD and the enabled status is false
+    def add(mod, enabled: true, version: nil)
+      raise MODSettingsError, "can't disable the base MOD" if mod.base? && enabled == false
+
+      @mods[mod] = MODState[enabled:, version:]
+    end
+
+    # Remove the MOD from the list
+    #
+    # @param mod [Factorix::MOD] the MOD to remove
+    # @return [void]
+    # @raise [MODSettingsError] if the MOD is the base MOD or an expansion MOD
+    def remove(mod)
+      raise MODSettingsError, "can't remove the base MOD" if mod.base?
+      raise MODSettingsError, "can't remove expansion MOD: #{mod}" if mod.expansion?
+
+      @mods.delete(mod)
+    end
+
+    # Check if the MOD is in the list
+    #
+    # @param mod [Factorix::MOD] the MOD to check
+    # @return [Boolean] true if the MOD is in the list, false otherwise
+    def exist?(mod) = @mods.key?(mod)
+
+    # Check if the MOD is enabled
+    #
+    # @param mod [Factorix::MOD] the MOD to check
+    # @return [Boolean] true if the MOD is enabled, false otherwise
+    # @raise [Factorix::MODList::MODNotInListError] if the MOD is not in the list
+    def enabled?(mod)
+      raise MODNotInListError, "MOD not in the list: #{mod}" unless exist?(mod)
+
+      @mods[mod].enabled?
+    end
+
+    # Get the version of the MOD
+    #
+    # @param mod [Factorix::MOD] the MOD to check
+    # @return [Factorix::MODVersion, nil] the version of the MOD, or nil if not specified
+    # @raise [Factorix::MODList::MODNotInListError] if the MOD is not in the list
+    def version(mod)
+      raise MODNotInListError, "MOD not in the list: #{mod}" unless exist?(mod)
+
+      @mods[mod].version
+    end
+
+    # Enable the MOD
+    #
+    # @param mod [Factorix::MOD] the MOD to enable
+    # @return [void]
+    # @raise [Factorix::MODList::MODNotInListError] if the MOD is not in the list
+    def enable(mod)
+      raise MODNotInListError, "MOD not in the list: #{mod}" unless exist?(mod)
+
+      current_state = @mods[mod]
+      @mods[mod] = MODState[enabled: true, version: current_state.version]
+    end
+
+    # Disable the MOD
+    #
+    # @param mod [Factorix::MOD] the MOD to disable
+    # @return [void]
+    # @raise [MODSettingsError] if the MOD is the base MOD
+    # @raise [Factorix::MODList::MODNotInListError] if the MOD is not in the list
+    def disable(mod)
+      raise MODSettingsError, "can't disable the base MOD" if mod.base?
+      raise MODNotInListError, "MOD not in the list: #{mod}" unless exist?(mod)
+
+      current_state = @mods[mod]
+      @mods[mod] = MODState[enabled: false, version: current_state.version]
+    end
+  end
+end