molinillo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f58da410ac680b6b1dcb44c90cff7ee899e05e2d
+  data.tar.gz: dfa4c21e605ee3fd74bcec2ea167fb0e1c1a1ae4
+SHA512:
+  metadata.gz: bdfa7ee068ed2f379406f047d4f6ed72935c29046ff314b772dceee1568fbe9bce54a7a2a7524adec384760c483f5b1f800467726574871267e55df56321ed3d
+  data.tar.gz: e6070563c8b8020cf71c23e518522423769fe2248790bc7b5e88e90dd66eb321a6e6a01176a5957fd912b1052abb171a4f83a208cbdde59db926ae091ab45ecd

data/LICENSE

@@ -0,0 +1,9 @@
+This project is licensed under the MIT license.
+
+Copyright (c) 2014 Samuel E. Giddins segiddins@segiddins.me
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,45 @@
+# Molinillo
+
+[![Build Status](https://img.shields.io/travis/CocoaPods/Molinillo/master.svg?style=flat)](https://travis-ci.org/CocoaPods/Molinillo)
+[![Coverage](https://img.shields.io/codeclimate/coverage/github/CocoaPods/Molinillo.svg?style=flat)](https://codeclimate.com/github/CocoaPods/Molinillo)
+[![Code Climate](https://img.shields.io/codeclimate/github/CocoaPods/Molinillo.svg?style=flat)](https://codeclimate.com/github/CocoaPods/Molinillo)
+
+A generic dependency-resolution implementation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'molinillo', :git => 'https://github.com/CocoaPods/Molinillo'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install molinillo
+```
+
+## Usage
+
+Look at the test suite for example usage. Better documentation and examples are
+forthcoming.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a pull request
+
+## The Name
+
+[Molinillo](http://en.wikipedia.org/wiki/Molinillo_(whisk)) is a special whisk used in Mexico in the preparation of beverages such as hot chocolate.
+Much like a dependency resolver, a molinillo helps take a list of ingredients and turn it into a delicious concoction!

data/lib/molinillo.rb

@@ -0,0 +1,5 @@
+require 'molinillo/gem_metadata'
+require 'molinillo/errors'
+require 'molinillo/resolver'
+require 'molinillo/modules/ui'
+require 'molinillo/modules/specification_provider'

data/lib/molinillo/dependency_graph.rb

@@ -0,0 +1,243 @@
+require 'set'
+
+module Molinillo
+  # A directed acyclic graph that is tuned to hold named dependencies
+  class DependencyGraph
+    include Enumerable
+
+    def each
+      vertices.values.each { |v| yield v }
+    end
+
+    # A directed edge of a {DependencyGraph}
+    # @attr [Vertex] origin The origin of the directed edge
+    # @attr [Vertex] destination The destination of the directed edge
+    # @attr [Array] requirements The requirements the directed edge represents
+    Edge = Struct.new(:origin, :destination, :requirements)
+
+    # @return [{String => Vertex}] vertices that have no {Vertex#predecessors},
+    #   keyed by by {Vertex#name}
+    attr_reader :root_vertices
+    # @return [{String => Vertex}] the vertices of the dependency graph, keyed
+    #   by {Vertex#name}
+    attr_reader :vertices
+    # @return [Set<Edge>] the edges of the dependency graph
+    attr_reader :edges
+
+    def initialize
+      @vertices = {}
+      @edges = Set.new
+      @root_vertices = {}
+    end
+
+    # Initializes a copy of a {DependencyGraph}, ensuring that all {#vertices}
+    # have the correct {Vertex#graph} set
+    def initialize_copy(other)
+      super
+      @vertices = other.vertices.reduce({}) do |vertices, (name, vertex)|
+        vertices.tap do |hash|
+          hash[name] = vertex.dup.tap { |v| v.graph = self }
+        end
+      end
+      @root_vertices = Hash[vertices.select { |n, _v| other.root_vertices[n] }]
+      @edges = other.edges.map do |edge|
+        Edge.new(
+          vertex_named(edge.origin.name),
+          vertex_named(edge.destination.name),
+          edge.requirements.dup
+        )
+      end
+    end
+
+    # @return [String] a string suitable for debugging
+    def inspect
+      "#{self.class}:#{vertices.values.inspect}"
+    end
+
+    # @return [Boolean] whether the two dependency graphs are equal, determined
+    #   by a recursive traversal of each {#root_vertices} and its
+    #   {Vertex#successors}
+    def ==(other)
+      root_vertices == other.root_vertices
+    end
+
+    # @param [String] name
+    # @param [Object] payload
+    # @param [Array<String>] parent_names
+    # @param [Object] requirement the requirement that is requiring the child
+    # @return [void]
+    def add_child_vertex(name, payload, parent_names, requirement)
+      is_root = parent_names.include?(nil)
+      parent_nodes = parent_names.compact.map { |n| vertex_named(n) }
+      vertex = vertex_named(name) || if is_root
+                                       add_root_vertex(name, payload)
+                                     else
+                                       add_vertex(name, payload)
+                                     end
+      vertex.payload ||= payload
+      parent_nodes.each do |parent_node|
+        add_edge(parent_node, vertex, requirement)
+      end
+      vertex
+    end
+
+    # @param [String] name
+    # @param [Object] payload
+    # @return [Vertex] the vertex that was added to `self`
+    def add_vertex(name, payload)
+      vertex = vertices[name] ||= Vertex.new(self, name, payload)
+      vertex.tap { |v| v.payload = payload }
+    end
+
+    # @param [String] name
+    # @param [Object] payload
+    # @return [Vertex] the vertex that was added to `self`
+    def add_root_vertex(name, payload)
+      add_vertex(name, payload).tap { |v| root_vertices[name] = v }
+    end
+
+    # Detaches the {#vertex_named} `name` {Vertex} from the graph, recursively
+    # removing any non-root vertices that were orphaned in the process
+    # @param [String] name
+    # @return [void]
+    def detach_vertex_named(name)
+      vertex = vertex_named(name)
+      successors = vertex.successors
+      vertices.delete(name)
+      edges.reject! { |e| e.origin == vertex || e.destination == vertex }
+      successors.each { |v| detach_vertex_named(v.name) unless root_vertices[v.name] || v.predecessors.any? }
+    end
+
+    # @param [String] name
+    # @return [Vertex,nil] the vertex with the given name
+    def vertex_named(name)
+      vertices[name]
+    end
+
+    # @param [String] name
+    # @return [Vertex,nil] the root vertex with the given name
+    def root_vertex_named(name)
+      root_vertices[name]
+    end
+
+    # Adds a new {Edge} to the dependency graph
+    # @param [Vertex] origin
+    # @param [Vertex] destination
+    # @param [Object] requirement the requirement that this edge represents
+    # @return [Edge] the added edge
+    def add_edge(origin, destination, requirement)
+      if origin == destination || destination.path_to?(origin)
+        raise CircularDependencyError.new([origin, destination])
+      end
+      Edge.new(origin, destination, [requirement]).tap { |e| edges << e }
+    end
+
+    # A vertex in a {DependencyGraph} that encapsulates a {#name} and a
+    # {#payload}
+    class Vertex
+      # @return [DependencyGraph] the graph this vertex is a node of
+      attr_accessor :graph
+
+      # @return [String] the name of the vertex
+      attr_accessor :name
+
+      # @return [Object] the payload the vertex holds
+      attr_accessor :payload
+
+      # @return [Arrary<Object>] the explicit requirements that required
+      #   this vertex
+      attr_reader :explicit_requirements
+
+      # @param [DependencyGraph] graph see {#graph}
+      # @param [String] name see {#name}
+      # @param [Object] payload see {#payload}
+      def initialize(graph, name, payload)
+        @graph = graph
+        @name = name
+        @payload = payload
+        @explicit_requirements = []
+      end
+
+      # @return [Array<Object>] all of the requirements that required
+      #   this vertex
+      def requirements
+        incoming_edges.flat_map(&:requirements) + explicit_requirements
+      end
+
+      # @return [Array<Edge>] the edges of {#graph} that have `self` as their
+      #   {Edge#origin}
+      def outgoing_edges
+        graph.edges.select { |e| e.origin.shallow_eql?(self) }
+      end
+
+      # @return [Array<Edge>] the edges of {#graph} that have `self` as their
+      #   {Edge#destination}
+      def incoming_edges
+        graph.edges.select { |e| e.destination.shallow_eql?(self) }
+      end
+
+      # @return [Set<Vertex>] the vertices of {#graph} that have an edge with
+      #   `self` as their {Edge#destination}
+      def predecessors
+        incoming_edges.map(&:origin).to_set
+      end
+
+      # @return [Set<Vertex>] the vertices of {#graph} that have an edge with
+      #   `self` as their {Edge#origin}
+      def successors
+        outgoing_edges.map(&:destination).to_set
+      end
+
+      # @return [Set<Vertex>] the vertices of {#graph} where `self` is an
+      #   {#ancestor?}
+      def recursive_successors
+        successors + successors.map(&:recursive_successors).reduce(Set.new, &:+)
+      end
+
+      # @return [String] a string suitable for debugging
+      def inspect
+        "#{self.class}:#{name}(#{payload.inspect})"
+      end
+
+      # @return [Boolean] whether the two vertices are equal, determined
+      #   by a recursive traversal of each {Vertex#successors}
+      def ==(other)
+        shallow_eql?(other) &&
+          successors == other.successors
+      end
+
+      # @return [Boolean] whether the two vertices are equal, determined
+      #   solely by {#name} and {#payload} equality
+      def shallow_eql?(other)
+        other &&
+          name == other.name &&
+          payload == other.payload
+      end
+
+      alias_method :eql?, :==
+
+      # @return [Fixnum] a hash for the vertex based upon its {#name}
+      def hash
+        name.hash
+      end
+
+      # Is there a path from `self` to `other` following edges in the
+      # dependency graph?
+      # @return true iff there is a path following edges within this {#graph}
+      def path_to?(other)
+        successors.include?(other) || successors.any? { |v| v.path_to?(other) }
+      end
+
+      alias_method :descendent?, :path_to?
+
+      # Is there a path from `other` to `self` following edges in the
+      # dependency graph?
+      # @return true iff there is a path following edges within this {#graph}
+      def ancestor?(other)
+        predecessors.include?(other) || predecessors.any? { |v| v.ancestor?(other) }
+      end
+
+      alias_method :is_reachable_from?, :ancestor?
+    end
+  end
+end

data/lib/molinillo/errors.rb

@@ -0,0 +1,69 @@
+module Molinillo
+  # An error that occurred during the resolution process
+  class ResolverError < StandardError; end
+
+  # An error caused by searching for a dependency that is completely unknown,
+  # i.e. has no versions available whatsoever.
+  class NoSuchDependencyError < ResolverError
+    # @return [Object] the dependency that could not be found
+    attr_accessor :dependency
+
+    # @return [Array<Object>] the specifications that depended upon {#dependency}
+    attr_accessor :required_by
+
+    # @param [Object] dependency @see {#dependency}
+    # @param [Array<Object>] required_by @see {#required_by}
+    def initialize(dependency, required_by = [])
+      @dependency = dependency
+      @required_by = required_by
+      super()
+    end
+
+    def message
+      sources = required_by.map { |r| "`#{r}`" }.join(' and ')
+      message = "Unable to find a specification for `#{dependency}`"
+      message << " depended upon by #{sources}" unless sources.empty?
+      message
+    end
+  end
+
+  # An error caused by attempting to fulfil a dependency that was circular
+  #
+  # @note This exception will be thrown iff a {Vertex} is added to a
+  #   {DependencyGraph} that has a {DependencyGraph::Vertex#path_to?} an
+  #   existing {DependencyGraph::Vertex}
+  class CircularDependencyError < ResolverError
+    # [Set<Object>] the dependencies responsible for causing the error
+    attr_reader :dependencies
+
+    # @param [Array<DependencyGraph::Vertex>] nodes the nodes in the dependency
+    #   that caused the error
+    def initialize(nodes)
+      super "There is a circular dependency between #{nodes.map(&:name).join(' and ')}"
+      @dependencies = nodes.map(&:payload).to_set
+    end
+  end
+
+  # An error caused by conflicts in version
+  class VersionConflict < ResolverError
+    # @return [{String => Resolution::Conflict}] the conflicts that caused
+    #   resolution to fail
+    attr_reader :conflicts
+
+    # @param [{String => Resolution::Conflict}] conflicts see {#conflicts}
+    def initialize(conflicts)
+      pairs = []
+      conflicts.values.flatten.map(&:requirements).flatten.each do |conflicting|
+        conflicting.each do |source, conflict_requirements|
+          conflict_requirements.each do |c|
+            pairs << [c, source]
+          end
+        end
+      end
+
+      super "Unable to satisfy the following requirements:\n\n" \
+        "#{pairs.map { |r, d| "- `#{r}` required by `#{d}`" }.join("\n")}"
+      @conflicts = conflicts
+    end
+  end
+end

data/lib/molinillo/gem_metadata.rb

@@ -0,0 +1,3 @@
+module Molinillo
+  VERSION = '0.1.0'
+end

data/lib/molinillo/modules/specification_provider.rb

@@ -0,0 +1,90 @@
+module Molinillo
+  # Provides information about specifcations and dependencies to the resolver,
+  # allowing the {Resolver} class to remain generic while still providing power
+  # and flexibility.
+  #
+  # This module contains the methods that users of Molinillo must to implement,
+  # using knowledge of their own model classes.
+  module SpecificationProvider
+    # Search for the specifications that match the given dependency.
+    # The specifications in the returned array will be considered in reverse
+    # order, so the latest version ought to be last.
+    # @note This method should be 'pure', i.e. the return value should depend
+    #   only on the `dependency` parameter.
+    #
+    # @param [Object] dependency
+    # @return [Array<Object>] the specifications that satisfy the given
+    #   `dependency`.
+    def search_for(dependency)
+      []
+    end
+
+    # Returns the dependencies of `specification`.
+    # @note This method should be 'pure', i.e. the return value should depend
+    #   only on the `specification` parameter.
+    #
+    # @param [Object] specification
+    # @return [Array<Object>] the dependencies that are required by the given
+    #   `specification`.
+    def dependencies_for(specification)
+      []
+    end
+
+    # Determines whether the given `requirement` is satisfied by the given
+    # `spec`, in the context of the current `activated` dependency graph.
+    #
+    # @param [Object] requirement
+    # @param [DependencyGraph] activated the current dependency graph in the
+    #   resolution process.
+    # @param [Object] spec
+    # @return [Boolean] whether `requirement` is satisfied by `spec` in the
+    #   context of the current `activated` dependency graph.
+    def requirement_satisfied_by?(requirement, activated, spec)
+      true
+    end
+
+    # Returns the name for the given `dependency`.
+    # @note This method should be 'pure', i.e. the return value should depend
+    #   only on the `dependency` parameter.
+    #
+    # @param [Object] dependency
+    # @return [String] the name for the given `dependency`.
+    def name_for(dependency)
+      dependency.to_s
+    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
+      'user-specified dependency'
+    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
+
+    # Sort dependencies so that the ones that are easiest to resolve are first.
+    # Easiest to resolve is (usually) defined by:
+    #   1) Is this dependency already activated?
+    #   2) How relaxed are the requirements?
+    #   3) Are there any conflicts for this dependency?
+    #   4) How many possibilities are there to satisfy this dependency?
+    #
+    # @param [Array<Object>] dependencies
+    # @param [DependencyGraph] activated the current dependency graph in the
+    #   resolution process.
+    # @param [{String => Array<Conflict>}] conflicts
+    # @return [Array<Object>] a sorted copy of `dependencies`.
+    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,
+        ]
+      end
+    end
+  end
+end