Even more docs and cleanup. Yay!

Author: pvande

lib/semantic/dependency.rb

@@ -7,41 +7,64 @@ module Dependency
     autoload :ModuleRelease, 'semantic/dependency/module_release'
     autoload :Source, 'semantic/dependency/source'
 
+    # @!group Sources
+
+    # @return [Array<Source>] a frozen copy of the {Source} list
     def sources
       (@sources ||= []).dup.freeze
     end
 
+    # Appends a new {Source} to the current list.
+    # @param source [Source] the {Source} to add
+    # @return [void]
     def add_source(source)
       sources
       @sources << source
+      nil
     end
 
+    # Clears the current list of {Source}s.
+    # @return [void]
     def clear_sources
       sources
       @sources.clear
+      nil
     end
 
+    # @!endgroup
+
     # Fetches a graph of modules and their dependencies from the currently
     # configured list of {Source}s.
     #
-    # @param modules [{ String => String }]
+    # @todo Return a specialized "Graph" object.
+    # @todo Allow for external constraints to be added to the graph.
     # @see #sources
     # @see #add_source
     # @see #clear_sources
+    #
+    # @param modules [{ String => String }]
+    # @return [ModuleRelease] the root of a dependency graph
     def query(modules)
-      release = Source::ROOT_CAUSE.create_release('', nil, modules)
+      graph = Source::ROOT_CAUSE.create_release('', nil, modules)
 
-      modules = fetch release
-      releases = modules.values.flatten << release
+      modules = fetch(graph)
+      releases = modules.values.flatten << graph
       releases.each do |rel|
         rel.dependencies.each do |name|
-          rel.satisfy_dependencies modules[name]
+          rel.satisfy_dependencies(modules[name])
         end
       end
 
-      return release
+      return graph
     end
 
+    # Given a graph result from {#query}, this method will resolve the graph of
+    # dependencies, if possible, into a flat list of the best suited modules. If
+    # the dependency graph does not have a suitable resolution, this method will
+    # raise an exception to that effect.
+    #
+    # @param graph [ModuleRelease] the root of a dependency graph
+    # @return [Array<ModuleRelease>] the list of releases to act on
     def resolve(graph)
       catch :next do
         return walk(graph.depends_on)
@@ -56,9 +79,11 @@ def resolve(graph)
     # placed on it, being {ModuleRelease#satisfied? satisfied}, and having the
     # greatest version number (with stability being preferred over prereleases).
     #
-    # @param dependencies [{ String => Array(ModuleRelease) }] the dependencies
-    # @param considering [Array(ModuleRelease)] the set of releases being tested
-    # @return [Array(ModuleRelease)] the list of releases to use, if successful
+    # @todo Traversal order is not presently guaranteed.
+    #
+    # @param dependencies [{ String => Array<ModuleRelease> }] the dependencies
+    # @param considering [Array<ModuleRelease>] the set of releases being tested
+    # @return [Array<ModuleRelease>] the list of releases to use, if successful
     def walk(dependencies, *considering)
       return considering if dependencies.empty?
 
@@ -80,7 +105,7 @@ def walk(dependencies, *considering)
           # will return a completed dependency list. If there were problems
           # resolving our dependencies, we'll catch `:next`, which will cause
           # us to move to the next possibility.
-          return walk(merged, dep, *considering)
+          return walk(merged, *considering, dep)
         end
       end
 
@@ -90,15 +115,20 @@ def walk(dependencies, *considering)
       throw :next
     end
 
-    # @param module [ModuleRelease] the release to detail
+    # Given a {ModuleRelease}, this method will iterate through the current
+    # list of {Source}s to find the complete list of versions available for its
+    # dependencies.
+    #
+    # @param release [ModuleRelease] the release to fetch details for
+    # @return [{ String => [ModuleRelease] }] the fetched dependency information
     def fetch(release, cache = Hash.new { |h,k| h[k] = {} })
       release.dependencies.each do |mod|
         next if cache.key? mod
         releases = cache[mod]
         sources.each do |source|
           source.fetch(mod).each do |dependency|
             releases[dependency.version] ||= dependency
-            fetch dependency, cache
+            fetch(dependency, cache)
           end
         end
       end
@@ -108,13 +138,19 @@ def fetch(release, cache = Hash.new { |h,k| h[k] = {} })
       end
     end
 
+    # Given a list of potential releases, this method returns the most suitable
+    # releases for exploration. Only {ModuleRelease#satisfied? satisfied}
+    # releases are considered, and releases with stable versions are preferred.
+    #
+    # @param releases [Array<ModuleRelease>] a list of potential releases
+    # @return [Array<ModuleRelease>] releases open for consideration
     def preferred_releases(releases)
-      stable = proc { |x| x.version.prerelease.nil? }
+      satisfied = releases.select { |x| x.satisfied? }
 
-      if releases.none?(&stable)
-        return releases.select { |r| r.satisfied? }
+      if satisfied.any? { |x| x.version.stable? }
+        return satisfied.select { |x| x.version.stable? }
       else
-        return releases.select(&stable).select { |r| r.satisfied? }
+        return satisfied
       end
     end
   end

lib/semantic/dependency/module_release.rb

@@ -60,7 +60,7 @@ def satisfied?
       # end
 
       def to_s
-        "<#{name}@#{version}>"
+        "#<#{self.class} #{name}@#{version}>"
       end
     end
   end

lib/semantic/dependency/source.rb

@@ -6,7 +6,9 @@ class Source
       def create_release(name, version, dependencies = {})
         version = Version.parse(version) if version.is_a? String
         dependencies = dependencies.inject({}) do |hash, (key, value)|
-          hash[key] = VersionRange.parse(value); hash
+          hash[key] = VersionRange.parse(value || '>= 0')
+          hash[key] ||= VersionRange::EMPTY_RANGE
+          hash
         end
         ModuleRelease.new(self, name, version, dependencies)
       end

lib/semantic/version_range.rb

@@ -26,7 +26,7 @@ class << self
       def parse(range)
         partial = '\d+(?:[.]\d+)?(?:[.][xX*]|[.]\d+(?:[-][0-9a-zA-Z-]*)?)?'
 
-        range = range.sub(/([><=~])[ ]/, '\1')
+        range = range.gsub(/([><=~])[ ]/, '\1')
 
         return case range
         when /\A(#{partial})\Z/
@@ -251,9 +251,6 @@ def process_loose_expr(expr)
       end
     end
 
-    # A range that matches no versions
-    EMPTY_RANGE = VersionRange.new(Version.parse('0.0.0'), Version.parse('0.0.0'), true).freeze
-
     # Computes the intersection of a pair of ranges. If the ranges have no
     # useful intersection, an empty range is returned.
     #
@@ -293,5 +290,10 @@ def intersection(other)
     def ends_before?(other)
       self.end < other.end || (self.end == other.end && self.exclude_end?)
     end
+
+    public
+
+    # A range that matches no versions
+    EMPTY_RANGE = VersionRange.new(MIN_VERSION, MIN_VERSION, true).freeze
   end
 end

spec/unit/semantic/version_range_spec.rb

@@ -273,7 +273,7 @@ def self.range(x, y, ex = false)
       Semantic::VersionRange.new(v(x), v(y), ex)
     end
 
-    EMPTY_RANGE = range(0, 0, true)
+    EMPTY_RANGE = Semantic::VersionRange::EMPTY_RANGE
 
     tests = {
       # This falls entirely before the target range