solve 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f8183623942ab701e9117e2912fd2fb4fefdfc19
-  data.tar.gz: a001a2bb59751962e18719575d3b59ff3192a753
+  metadata.gz: 674f7a18cf70685b1cd690b5babdb327b8186c5e
+  data.tar.gz: 784d73c2042284cc1c8100f2e4097b07d1dc4ae3
 SHA512:
-  metadata.gz: 548d9980b3b6e1f32922abcc0da8fd5146cf02f220453d6633a57a30eb982a18198fb7f4e21f7cab995c208a61a55af4417dc7b7161f36d6e48a7c1c0fe2e8ee
-  data.tar.gz: b0009f814da7354eea4a7c0fc90b378fd477cc14ab6207c94b6782c1fe48b4ce349ba84831d36a4886dcfb233026edc4c2fe435eba04e5a63b555ba10a0f2bcd
+  metadata.gz: 8dd9fe4edfff28b0a34b9223ae2163d346bec2a306e3319d3e559362477e82883080cc4031a567a065f17da5b99cc9231e9fed21a5cf08f102056f32400b08e9
+  data.tar.gz: 7a5b6622bd17b7d8d492c62f8e941db4137a05d963a5fc71b0ea8f8a8d5868cadb360456ae723e21cd9ffb451ff84f81f6e82409775c355926512fff18e8ab44

data/.gitignore

@@ -4,6 +4,7 @@
 .config
 .yardoc
 Gemfile.lock
+NoGecode.gemfile.lock
 InstalledFiles
 _yardoc
 coverage

data/.travis.yml

@@ -4,9 +4,14 @@ before_install:
 script: "bundle exec thor spec"
 language: ruby
 env: USE_SYSTEM_GECODE=1
-bundler_args: --without development
-rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1.0
-  - jruby-19mode
+bundler_args: --without dev
+
+matrix:
+  include:
+    - rvm: 1.9.3
+    - rvm: 2.0.0
+    - rvm: 2.1.0
+    - rvm: jruby-19mode
+    - rvm: 2.1
+      gemfile: NoGecode.gemfile
+      script: "bundle exec thor nogecode_spec"

data/Gemfile

@@ -2,7 +2,14 @@ source 'https://rubygems.org'
 
 gemspec
 
-group :development do
+group :gecode do
+  gem "dep_selector", "~> 1.0"
+end
+
+# If this group is named "development", then `bundle install --without
+# development` automagically excludes development dependencies that are listed
+# in the gemspec, which will skip installing rspec and then we can't run tests.
+group :dev do
   gem 'fuubar'
   gem 'yard'
   gem 'redcarpet'
@@ -24,10 +31,3 @@ group :development do
   end
 end
 
-group :test do
-  gem 'thor', '>= 0.16.0'
-  gem 'rake', '>= 0.9.2.2'
-
-  gem 'spork'
-  gem 'rspec'
-end

data/NoGecode.gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gemspec
+

data/README.md

@@ -38,6 +38,22 @@ NOTE: This will raise Solve::Errors::UnsortableSolutionError if the solution con
 
     Solve.it!(graph, [['nginx', '>= 0.100.0']], sorted: true)
 
+
+### Selecting A Resolver
+
+Solve supports two different resolvers. A pure Ruby solver implemented using [Molinillo](https://github.com/CocoaPods/Molinillo) and the same dependency resolver the Chef Server uses, [dep-selector](https://github.com/chef/dep-selector), which is a Ruby C extension for [Gecode](https://github.com/ampl/gecode).
+
+You can set the resolver by calling `Solver.engine=` with the symbol `:ruby` or `:gecode`.
+
+```ruby
+    Solver.engine = :ruby
+    Solver.engine = :gecode
+```
+
+The Ruby solver is installed and enabled by default. If you'd like to use the Gecode solver you can do so by installing the dep-selector gem or adding it to your Gemfile:
+
+    $ gem install dep_selector
+
 ### Increasing the solver's timeout
 
 By default the solver will wait 30 seconds before giving up on finding a solution. Under certain conditions a graph may be too complicated to solve within the alotted time. To increase the timeout you can set the "SOLVE_TIMEOUT" environment variable to the amount of seconds desired.

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/Thorfile

@@ -28,4 +28,9 @@ class Default < Thor
   def spec
     exec "rspec --color --format=documentation spec"
   end
+
+  desc "spec", "Run RSpec code examples"
+  def nogecode_spec
+    exec "rspec -t '~gecode' --color --format=documentation spec"
+  end
 end

data/lib/solve.rb

@@ -7,12 +7,42 @@ module Solve
   require_relative 'solve/version'
   require_relative 'solve/errors'
   require_relative 'solve/graph'
-  require_relative 'solve/solver'
+  require_relative 'solve/ruby_solver'
+  require_relative 'solve/gecode_solver'
 
   class << self
     # @return [Solve::Formatter]
     attr_reader :tracer
 
+    @engine = :ruby
+
+    # Returns the currently configured engine.
+    # @see #engine=
+    # @return [Symbol]
+    attr_reader :engine
+
+
+    # Sets the solving backend engine. Solve supports 2 engines:
+    # * `:ruby` - Molinillo, a pure ruby solver
+    # * `:gecode` - dep-selector, a wrapper around the Gecode CSP solver library
+    #
+    # Note that dep-selector is an optional dependency and may therefore not be
+    # available.
+    #
+    # @param [Symbol] selected_engine
+    # @return [Symbol] selected_engine
+    # @raise [Solve::Errors::EngineNotAvailable] when the selected engine's deps aren't installed.
+    # @raise [Solve::Errors::InvalidEngine] when `selected_engine` is invalid.
+    def engine=(selected_engine)
+      engine_class = solver_for_engine(selected_engine)
+      if engine_class.nil?
+        raise Errors::InvalidEngine, "Engine `#{selected_engine}` is not supported. Valid values are `:ruby`, `:gecode`"
+      else
+        engine_class.activate
+      end
+      @engine = selected_engine
+    end
+
     # A quick solve. Given the "world" as we know it (the graph) and a list of
     # requirements (demands) which must be met. Return me the best solution of
     # artifacts and verisons that I should use.
@@ -29,7 +59,18 @@ module Solve
     #
     # @return [Hash]
     def it!(graph, demands, options = {})
-      Solver.new(graph, demands).resolve(options)
+      solver_for_engine(engine).new(graph, demands, options).resolve(options)
     end
+
+    def solver_for_engine(engine_name)
+      case engine_name
+      when :ruby
+        RubySolver
+      when :gecode
+        GecodeSolver
+      end
+    end
+
+    private :solver_for_engine
   end
 end

data/lib/solve/demand.rb

@@ -2,7 +2,7 @@ module Solve
   class Demand
     # A reference to the solver this demand belongs to
     #
-    # @return [Solve::Solver]
+    # @return [Solve::RubySolver,Solve::GecodeSolver]
     attr_reader :solver
 
     # The name of the artifact this demand is for
@@ -15,7 +15,7 @@ module Solve
     # @return [Semverse::Constraint]
     attr_reader :constraint
 
-    # @param [Solve::Solver] solver
+    # @param [Solve::RubySolver,Solve::GecodeSolver] solver
     # @param [#to_s] name
     # @param [Semverse::Constraint, #to_s] constraint
     def initialize(solver, name, constraint = Semverse::DEFAULT_CONSTRAINT)

data/lib/solve/errors.rb

@@ -4,6 +4,12 @@ module Solve
       alias_method :mesage, :to_s
     end
 
+    class EngineNotAvailable < SolveError
+    end
+
+    class InvalidEngine < SolveError
+    end
+
     class NoSolutionError < SolveError
 
       # Artifacts that don't exist at any version but are required for a valid

data/lib/solve/{solver.rb → gecode_solver.rb}

@@ -1,9 +1,9 @@
-require 'dep_selector'
 require 'set'
+require 'solve/errors'
 require_relative 'solver/serializer'
 
 module Solve
-  class Solver
+  class GecodeSolver
     class << self
       # The timeout (in seconds) to use when resolving graphs. Default is 10. This can be
       # configured by setting the SOLVE_TIMEOUT environment variable.
@@ -13,6 +13,13 @@ module Solve
         seconds = 30 unless seconds = ENV["SOLVE_TIMEOUT"]
         seconds.to_i * 1_000
       end
+
+      # Attemp to load the dep_selector gem which this solver engine requires.
+      def activate
+        require 'dep_selector'
+      rescue LoadError => e
+        raise Errors::EngineNotAvailable, "dep_selector is not installed, GecodeSolver cannot be used (#{e})"
+      end
     end
 
     # Graph object with references to all known artifacts and dependency
@@ -30,10 +37,11 @@ module Solve
     #   graph = Solve::Graph.new
     #   graph.artifacts("mysql", "1.2.0")
     #   demands = [["mysql"]]
-    #   Solver.new(graph, demands)
+    #   GecodeSolver.new(graph, demands)
     # @param [Solve::Graph] graph
     # @param [Array<String>, Array<Array<String, String>>] demands
-    def initialize(graph, demands)
+    # @param [Hash] options - unused, only present for API compatibility with RubySolver
+    def initialize(graph, demands, options = {})
       @ds_graph      = DepSelector::DependencyGraph.new
       @graph         = graph
       @demands_array = demands

data/lib/solve/ruby_solver.rb

@@ -0,0 +1,207 @@
+require 'set'
+require 'molinillo'
+require_relative 'solver/serializer'
+
+module Solve
+  class RubySolver
+    class << self
+      # The timeout (in seconds) to use when resolving graphs. Default is 10. This can be
+      # configured by setting the SOLVE_TIMEOUT environment variable.
+      #
+      # @return [Integer]
+      def timeout
+        seconds = 30 unless seconds = ENV["SOLVE_TIMEOUT"]
+        seconds.to_i * 1_000
+      end
+
+      # For optinal solver engines, this attempts to load depenencies. The
+      # RubySolver is a non-optional component, so this is a no-op
+      def activate
+        true
+      end
+    end
+
+    # Graph object with references to all known artifacts and dependency
+    # constraints.
+    #
+    # @return [Solve::Graph]
+    attr_reader :graph
+
+    # @example Demands are Arrays of Arrays with an artifact name and optional constraint:
+    #   [['nginx', '= 1.0.0'], ['mysql']]
+    # @return [Array<String>, Array<Array<String, String>>] demands
+    attr_reader :demands_array
+
+    # @example Basic use:
+    #   graph = Solve::Graph.new
+    #   graph.artifacts("mysql", "1.2.0")
+    #   demands = [["mysql"]]
+    #   RubySolver.new(graph, demands)
+    # @param [Solve::Graph] graph
+    # @param [Array<String>, Array<Array<String, String>>] demands
+    def initialize(graph, demands, options = {})
+      @graph         = graph
+      @demands_array = demands
+      @timeout_ms    = self.class.timeout
+
+      @dependency_source = options[:dependency_source] || 'user-specified dependency'
+
+      @molinillo_graph = Molinillo::DependencyGraph.new
+      @resolver = Molinillo::Resolver.new(self, self)
+    end
+
+    # The problem demands given as Demand model objects
+    # @return [Array<Solve::Demand>]
+    def demands
+      demands_array.map do |name, constraint|
+        Demand.new(self, name, constraint)
+      end
+    end
+
+    # @option options [Boolean] :sorted
+    #   return the solution as a sorted list instead of a Hash
+    #
+    # @return [Hash, List] Returns a hash like { "Artifact Name" => "Version",... }
+    #   unless the :sorted option is true, then it returns a list like [["Artifact Name", "Version],...]
+    # @raise [Errors::NoSolutionError] when the demands cannot be met for the
+    #   given graph.
+    # @raise [Errors::UnsortableSolutionError] when the :sorted option is true
+    #   and the demands have a solution, but the solution contains a cyclic
+    #   dependency
+    def resolve(options = {})
+      solved_graph = resolve_with_error_wrapping
+
+      solution =  solved_graph.map(&:payload)
+
+      unsorted_solution = solution.inject({}) do |stringified_soln, artifact|
+        stringified_soln[artifact.name] = artifact.version.to_s
+        stringified_soln
+      end
+
+      if options[:sorted]
+        build_sorted_solution(unsorted_solution)
+      else
+        unsorted_solution
+      end
+    end
+
+    ###
+    # Molinillo Callbacks
+    #
+    # Molinillo calls back to this class to get information about our
+    # dependency model objects. An abstract implementation is provided at
+    # https://github.com/CocoaPods/Molinillo/blob/master/lib/molinillo/modules/specification_provider.rb
+    #
+    ###
+
+    # Callback required by Molinillo, called when the solve starts
+    # @return [Integer]
+    def progress_rate
+      1
+    end
+
+    # Callback required by Molinillo, called when the solve starts
+    # @return nil
+    def before_resolution
+      nil
+    end
+
+    # Callback required by Molinillo, called when the solve is complete.
+    # @return nil
+    def after_resolution
+      nil
+    end
+
+    # Callback required by Molinillo, gives debug information about the solution
+    # @return nil
+    def debug(current_resolver_depth)
+      # debug info will be returned if you call yield here, but it seems to be
+      # broken in current Molinillo
+      nil
+    end
+
+    # Callback required by Molinillo
+    # @return [String] the dependency's name
+    def name_for(dependency)
+      dependency.name
+    end
+
+    # Callback required by Molinillo
+    # @return [Array<Solve::Dependency>] the dependencies sorted by preference.
+    def sort_dependencies(dependencies, activated, conflicts)
+      dependencies.sort_by do |dependency|
+        name = name_for(dependency)
+        [
+          activated.vertex_named(name).payload ? 0 : 1,
+          conflicts[name] ? 0 : 1,
+          activated.vertex_named(name).payload ? 0 : graph.versions(dependency.name).count,
+        ]
+      end
+    end
+
+    # Callback required by Molinillo
+    # @return [Array<Solve::Artifact>] the artifacts that match the dependency.
+    def search_for(dependency)
+      # This array gets mutated by Molinillo; it's okay because sort returns a
+      # new array.
+      graph.versions(dependency.name, dependency.constraint).sort
+    end
+
+    # Callback required by Molinillo
+    # @return [Boolean]
+    def requirement_satisfied_by?(requirement, activated, spec)
+      requirement.constraint.satisfies?(spec.version)
+    end
+
+    # Callback required by Molinillo
+    # @return [Array<Solve::Dependency>] the dependencies of the given artifact
+    def dependencies_for(specification)
+      specification.dependencies
+    end
+
+    # @return [String] the name of the source of explicit dependencies, i.e.
+    #   those passed to {Resolver#resolve} directly.
+    def name_for_explicit_dependency_source
+      @dependency_source
+    end
+
+    # @return [String] the name of the source of 'locked' dependencies, i.e.
+    #   those passed to {Resolver#resolve} directly as the `base`
+    def name_for_locking_dependency_source
+      'Lockfile'
+    end
+
+    private
+
+      def resolve_with_error_wrapping
+        @resolver.resolve(demands, @molinillo_graph)
+      rescue Molinillo::VersionConflict, Molinillo::CircularDependencyError => e
+        raise Solve::Errors::NoSolutionError.new(e.message)
+      end
+
+      def build_sorted_solution(unsorted_solution)
+        nodes = Hash.new
+        unsorted_solution.each do |name, version|
+          nodes[name] = @graph.artifact(name, version).dependencies.map(&:name)
+        end
+
+        # Modified from http://ruby-doc.org/stdlib-1.9.3/libdoc/tsort/rdoc/TSort.html
+        class << nodes
+          include TSort
+          alias tsort_each_node each_key
+          def tsort_each_child(node, &block)
+            fetch(node).each(&block)
+          end
+        end
+        begin
+          sorted_names = nodes.tsort
+        rescue TSort::Cyclic => e
+          raise Solve::Errors::UnsortableSolutionError.new(e, unsorted_solution)
+        end
+
+        sorted_names.map do |artifact|
+          [artifact, unsorted_solution[artifact]]
+        end
+      end
+  end
+end