molinillo 0.1.0

data/lib/molinillo/modules/ui.rb

@@ -0,0 +1,63 @@
+module Molinillo
+  # Conveys information about the resolution process to a user.
+  module UI
+    # The {IO} object that should be used to print output. `STDOUT`, by default.
+    #
+    # @return [IO]
+    def output
+      STDOUT
+    end
+
+    # Called roughly every {#progress_rate}, this method should convey progress
+    # to the user.
+    #
+    # @return [void]
+    def indicate_progress
+      output.print '.' unless debug?
+    end
+
+    # How often progress should be conveyed to the user via
+    # {#indicate_progress}, in seconds. A third of a second, by default.
+    #
+    # @return [Float]
+    def progress_rate
+      0.33
+    end
+
+    # Called before resolution begins.
+    #
+    # @return [void]
+    def before_resolution
+      output.print 'Resolving dependencies...'
+    end
+
+    # Called after resolution ends (either successfully or with an error).
+    # By default, prints a newline.
+    #
+    # @return [void]
+    def after_resolution
+      output.puts
+    end
+
+    # Conveys debug information to the user.
+    # By default, prints to `STDERR` instead of {#output}.
+    #
+    # @param [Integer] depth the current depth of the resolution process.
+    # @return [void]
+    def debug(depth = 0)
+      if debug?
+        debug_info = yield
+        debug_info = debug_info.inspect unless debug_info.is_a?(String)
+        STDERR.puts debug_info.split("\n").map { |s| '  ' * depth + s }
+      end
+    end
+
+    # Whether or not debug messages should be printed.
+    # By default, whether or not the `CP_RESOLVER` environment variable is set.
+    #
+    # @return [Boolean]
+    def debug?
+      @debug_mode ||= ENV['CP_RESOLVER']
+    end
+  end
+end

data/lib/molinillo/resolution.rb

@@ -0,0 +1,323 @@
+module Molinillo
+  class Resolver
+    # A specific resolution from a given {Resolver}
+    class Resolution
+      # A conflict that the resolution process encountered
+      # @attr [{String,Nil=>[Object]}] requirements the requirements that caused the conflict
+      # @attr [Object, nil] existing the existing spec that was in conflict with
+      #   the {#possibility}
+      # @attr [Object] possibility the spec that was unable to be activated due
+      #   to a conflict
+      Conflict = Struct.new(
+        :requirements,
+        :existing,
+        :possibility
+      )
+
+      # @return [SpecificationProvider] the provider that knows about
+      #   dependencies, requirements, specifications, versions, etc.
+      attr_reader :specification_provider
+
+      # @return [UI] the UI that knows how to communicate feedback about the
+      #   resolution process back to the user
+      attr_reader :resolver_ui
+
+      # @return [DependencyGraph] the base dependency graph to which
+      #   dependencies should be 'locked'
+      attr_reader :base
+
+      # @return [Array] the dependencies that were explicitly required
+      attr_reader :original_requested
+
+      # @param [SpecificationProvider] specification_provider
+      #   see {#specification_provider}
+      # @param [UI] resolver_ui see {#resolver_ui}
+      # @param [Array] requested see {#original_requested}
+      # @param [DependencyGraph] base see {#base}
+      def initialize(specification_provider, resolver_ui, requested, base)
+        @specification_provider = specification_provider
+        @resolver_ui = resolver_ui
+        @original_requested = requested
+        @base = base
+        @states = []
+        @iteration_counter = 0
+      end
+
+      # Resolves the {#original_requested} dependencies into a full dependency
+      #   graph
+      # @raise [ResolverError] if successful resolution is impossible
+      # @return [DependencyGraph] the dependency graph of successfully resolved
+      #   dependencies
+      def resolve
+        start_resolution
+
+        while state
+          break unless state.requirements.any? || state.requirement
+          indicate_progress
+          if state.respond_to?(:pop_possibility_state) # DependencyState
+            debug(depth) { "creating possibility state (#{possibilities.count} remaining)" }
+            state.pop_possibility_state.tap { |s| states.push(s) if s }
+          end
+          process_topmost_state
+        end
+
+        activated.freeze
+      ensure
+        end_resolution
+      end
+
+      private
+
+      # Sets up the resolution process
+      # @return [void]
+      def start_resolution
+        @started_at = Time.now
+
+        states.push(initial_state)
+
+        debug { "starting resolution (#{@started_at})" }
+        resolver_ui.before_resolution
+      end
+
+      # Ends the resolution process
+      # @return [void]
+      def end_resolution
+        resolver_ui.after_resolution
+        debug do
+          "finished resolution (#{@iteration_counter} steps) " \
+          "(took #{(ended_at = Time.now) - @started_at} seconds) (#{ended_at})"
+        end
+        debug { 'unactivated: ' + Hash[activated.vertices.reject { |_n, v| v.payload }].keys.join(', ') }
+        debug { 'activated: ' + Hash[activated.vertices.select { |_n, v| v.payload }].keys.join(', ') }
+      end
+
+      require 'molinillo/state'
+      require 'molinillo/modules/specification_provider'
+
+      # @return [Integer] the number of resolver iterations in between calls to
+      #   {#resolver_ui}'s {UI#indicate_progress} method
+      attr_accessor :iteration_rate
+
+      # @return [Time] the time at which resolution began
+      attr_accessor :started_at
+
+      # @return [Array<ResolutionState>] the stack of states for the resolution
+      attr_accessor :states
+
+      ResolutionState.new.members.each do |member|
+        define_method member do |*args, &block|
+          state.send(member, *args, &block)
+        end
+      end
+
+      SpecificationProvider.instance_methods(false).each do |instance_method|
+        define_method instance_method do |*args, &block|
+          begin
+            specification_provider.send(instance_method, *args, &block)
+          rescue NoSuchDependencyError => error
+            vertex = activated.vertex_named(name_for error.dependency)
+            error.required_by += vertex.incoming_edges.map { |e| e.origin.name }
+            error.required_by << name_for_explicit_dependency_source unless vertex.explicit_requirements.empty?
+            raise
+          end
+        end
+      end
+
+      # Processes the topmost available {RequirementState} on the stack
+      # @return [void]
+      def process_topmost_state
+        if possibility
+          attempt_to_activate
+        else
+          create_conflict if state.is_a? PossibilityState
+          unwind_for_conflict until possibility && state.is_a?(DependencyState)
+        end
+      end
+
+      # @return [Object] the current possibility that the resolution is trying
+      #   to activate
+      def possibility
+        possibilities.last
+      end
+
+      # @return [RequirementState] the current state the resolution is
+      #   operating upon
+      def state
+        states.last
+      end
+
+      # Creates the initial state for the resolution, based upon the
+      # {#requested} dependencies
+      # @return [DependencyState] the initial state for the resolution
+      def initial_state
+        graph = DependencyGraph.new.tap do |dg|
+          original_requested.each { |r| dg.add_root_vertex(name_for(r), nil).tap { |v| v.explicit_requirements << r } }
+        end
+
+        requirements = sort_dependencies(original_requested, graph, {})
+        initial_requirement = requirements.shift
+        DependencyState.new(
+          initial_requirement && name_for(initial_requirement),
+          requirements,
+          graph,
+          initial_requirement,
+          initial_requirement && search_for(initial_requirement),
+          0,
+          {}
+        )
+      end
+
+      # Unwinds the states stack because a conflict has been encountered
+      # @return [void]
+      def unwind_for_conflict
+        if depth > 0
+          debug(depth) { 'Unwinding from level ' + state.depth.to_s }
+          conflicts.tap do |c|
+            states.pop
+            state.conflicts = c
+          end
+        else
+          raise VersionConflict.new(conflicts)
+        end
+      end
+
+      # @return [Conflict] a {Conflict} that reflects the failure to activate
+      #   the {#possibility} in conjunction with the current {#state}
+      def create_conflict
+        vertex = activated.vertex_named(name)
+        existing = vertex.payload
+        requirements = {
+          name_for_explicit_dependency_source => vertex.explicit_requirements,
+          name_for_locking_dependency_source => Array(locked_requirement_named(name)),
+        }
+        vertex.incoming_edges.each { |edge| (requirements[edge.origin.payload] ||= []).unshift(*edge.requirements) }
+        conflicts[name] = Conflict.new(
+          requirements,
+          existing,
+          possibility
+        )
+      end
+
+      # Indicates progress roughly once every second
+      # @return [void]
+      def indicate_progress
+        @iteration_counter += 1
+        @progress_rate ||= resolver_ui.progress_rate
+        if iteration_rate.nil?
+          if Time.now - started_at >= @progress_rate
+            self.iteration_rate = @iteration_counter
+          end
+        end
+
+        if iteration_rate && (@iteration_counter % iteration_rate) == 0
+          resolver_ui.indicate_progress
+        end
+      end
+
+      # Calls the {#resolver_ui}'s {UI#debug} method
+      # @param [Integer] depth the depth of the {#states} stack
+      # @param [Proc] block a block that yields a {#to_s}
+      # @return [void]
+      def debug(depth = 0, &block)
+        resolver_ui.debug(depth, &block)
+      end
+
+      # Attempts to activate the current {#possibility}
+      # @return [void]
+      def attempt_to_activate
+        debug(depth) { 'attempting to activate ' + possibility.to_s }
+        existing_node = activated.vertex_named(name)
+        if existing_node && existing_node.payload
+          attempt_to_activate_existing_spec(existing_node)
+        else
+          attempt_to_activate_new_spec
+        end
+      end
+
+      # Attempts to activate the current {#possibility} (given that it has
+      # already been activated)
+      # @return [void]
+      def attempt_to_activate_existing_spec(existing_node)
+        existing_spec = existing_node.payload
+        if requirement_satisfied_by?(requirement, activated, existing_spec)
+          new_requirements = requirements.dup
+          push_state_for_requirements(new_requirements)
+        else
+          create_conflict
+          debug(depth) { 'Unsatisfied by existing spec' }
+          unwind_for_conflict
+        end
+      end
+
+      # Attempts to activate the current {#possibility} (given that it hasn't
+      # already been activated)
+      # @return [void]
+      def attempt_to_activate_new_spec
+        satisfied = begin
+          locked_requirement = locked_requirement_named(name)
+          requested_spec_satisfied = requirement_satisfied_by?(requirement, activated, possibility)
+          locked_spec_satisfied = !locked_requirement ||
+            requirement_satisfied_by?(locked_requirement, activated, possibility)
+          debug(depth) { 'Unsatisfied by requested spec' } unless requested_spec_satisfied
+          debug(depth) { 'Unsatisfied by locked spec' } unless locked_spec_satisfied
+          requested_spec_satisfied && locked_spec_satisfied
+        end
+        if satisfied
+          activate_spec
+        else
+          create_conflict
+          unwind_for_conflict
+        end
+      end
+
+      # @param [String] requirement_name the spec name to search for
+      # @return [Object] the locked spec named `requirement_name`, if one
+      #   is found on {#base}
+      def locked_requirement_named(requirement_name)
+        vertex = base.vertex_named(requirement_name)
+        vertex && vertex.payload
+      end
+
+      # Add the current {#possibility} to the dependency graph of the current
+      # {#state}
+      # @return [void]
+      def activate_spec
+        conflicts.delete(name)
+        debug(depth) { 'activated ' + name + ' at ' + possibility.to_s }
+        vertex = activated.vertex_named(name)
+        vertex.payload = possibility
+        require_nested_dependencies_for(possibility)
+      end
+
+      # Requires the dependencies that the recently activated spec has
+      # @param [Object] activated_spec the specification that has just been
+      #   activated
+      # @return [void]
+      def require_nested_dependencies_for(activated_spec)
+        nested_dependencies = dependencies_for(activated_spec)
+        debug(depth) { "requiring nested dependencies (#{nested_dependencies.map(&:to_s).join(', ')})" }
+        nested_dependencies.each { |d|  activated.add_child_vertex name_for(d), nil, [name_for(activated_spec)], d }
+
+        push_state_for_requirements(requirements + nested_dependencies)
+      end
+
+      # Pushes a new {DependencyState} that encapsulates both existing and new
+      # requirements
+      # @param [Array] new_requirements
+      # @return [void]
+      def push_state_for_requirements(new_requirements)
+        new_requirements = sort_dependencies(new_requirements, activated, conflicts)
+        new_requirement = new_requirements.shift
+        states.push DependencyState.new(
+          new_requirement ? name_for(new_requirement) : '',
+          new_requirements,
+          activated.dup,
+          new_requirement,
+          new_requirement ? search_for(new_requirement) : [],
+          depth,
+          conflicts.dup
+        )
+      end
+    end
+  end
+end

data/lib/molinillo/resolver.rb

@@ -0,0 +1,43 @@
+require 'molinillo/dependency_graph'
+
+module Molinillo
+  # This class encapsulates a dependency resolver.
+  # The resolver is responsible for determining which set of dependencies to
+  # activate, with feedback from the the {#specification_provider}
+  #
+  #
+  class Resolver
+    require 'molinillo/resolution'
+
+    # @return [SpecificationProvider] the specification provider used
+    #   in the resolution process
+    attr_reader :specification_provider
+
+    # @return [UI] the UI module used to communicate back to the user
+    #   during the resolution process
+    attr_reader :resolver_ui
+
+    # @param  [SpecificationProvider] specification_provider
+    #   see {#specification_provider}
+    # @param  [UI] resolver_ui
+    #   see {#resolver_ui}
+    def initialize(specification_provider, resolver_ui)
+      @specification_provider = specification_provider
+      @resolver_ui = resolver_ui
+    end
+
+    # Resolves the requested dependencies into a {DependencyGraph},
+    # locking to the base dependency graph (if specified)
+    # @param [Array] requested an array of 'requested' dependencies that the
+    #   {#specification_provider} can understand
+    # @param [DependencyGraph,nil] base the base dependency graph to which
+    #   dependencies should be 'locked'
+    def resolve(requested, base = DependencyGraph.new)
+      Resolution.new(specification_provider,
+                     resolver_ui,
+                     requested,
+                     base).
+        resolve
+    end
+  end
+end

data/lib/molinillo/state.rb

@@ -0,0 +1,43 @@
+module Molinillo
+  # A state that a {Resolution} can be in
+  # @attr [String] name
+  # @attr [Array<Object>] requirements
+  # @attr [DependencyGraph] activated
+  # @attr [Object] requirement
+  # @attr [Object] possibility
+  # @attr [Integer] depth
+  # @attr [Set<Object>] conflicts
+  ResolutionState = Struct.new(
+    :name,
+    :requirements,
+    :activated,
+    :requirement,
+    :possibilities,
+    :depth,
+    :conflicts
+  )
+
+  # A state that encapsulates a set of {#requirements} with an {Array} of
+  # possibilities
+  class DependencyState < ResolutionState
+    # Removes a possibility from `self`
+    # @return [PossibilityState] a state with a single possibility,
+    #  the possibility that was removed from `self`
+    def pop_possibility_state
+      PossibilityState.new(
+        name,
+        requirements.dup,
+        activated.dup,
+        requirement,
+        [possibilities.pop],
+        depth + 1,
+        conflicts.dup
+      )
+    end
+  end
+
+  # A state that encapsulates a single possibility to fulfill the given
+  # {#requirement}
+  class PossibilityState < ResolutionState
+  end
+end