semantic_puppet 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+.rbenv-*
+.yardoc
+coverage
+doc

data/.yardopts

@@ -0,0 +1 @@
+-m markdown

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased version][Unreleased date]
+### Changed
+
+## 0.1.0 - 2015-03-23
+### Added
+- initial release in concert with current Puppet Module Tool v4.0.0 behavior

data/Gemfile

@@ -0,0 +1,20 @@
+source "https://rubygems.org"
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks'
+end
+
+group :test do
+  gem 'rspec'
+end
+
+group :metrics do
+  gem 'cane',      :platform => [ :mri_19, :mri_20, :mri_21 ]
+  gem 'simplecov', :platform => [ :mri_19, :mri_20, :mri_21 ]
+end
+
+group :doc do
+  gem 'yard', '~> 0.8', :platform => [ :mri_19, :mri_20, :mri_21 ]
+  gem 'redcarpet',      :platform => [ :mri_19, :mri_20, :mri_21 ]
+end

data/Gemfile.lock

@@ -0,0 +1,38 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    cane (2.6.1)
+      parallel
+    diff-lcs (1.2.5)
+    docile (1.1.1)
+    multi_json (1.8.2)
+    parallel (0.9.1)
+    rake (10.1.0)
+    redcarpet (3.0.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    rubygems-tasks (0.2.4)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    yard (0.8.7.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cane
+  rake
+  redcarpet
+  rspec
+  rubygems-tasks
+  simplecov
+  yard (~> 0.8)

data/README.md

@@ -0,0 +1,64 @@
+SemanticPuppet
+==============
+
+Library of useful tools for working with Semantic Versions and module
+dependencies.
+
+Description
+-----------
+
+Library of tools used by Puppet to parse, validate, and compare Semantic
+Versions and Version Ranges and to query and resolve module dependencies.
+
+For sparse, but accurate documentation, please see the docs directory.
+
+Note that this is a 0 release version, and things can change. Expect that the
+version and version range code to stay relatively stable, but the module
+dependency code is expected to change.
+
+This library is used by a number of Puppet Labs projects, including
+[Puppet](https://github.com/puppetlabs/puppet) and
+[r10k](https://github.com/puppetlabs/r10k).
+
+Requirements
+------------
+
+Semantic_puppet will work on several ruby versions, including 1.9.3, 2.0.0, and
+2.1.0. Ruby 1.8.7 is immediately deprecated as it is in
+[r10k](https://github.com/puppetlabs/r10k).
+
+No gem/library requirements.
+
+Installation
+------------
+
+### Rubygems
+
+For general use, you should install semantic_puppet from Ruby gems:
+
+    gem install semantic_puppet
+
+### Github
+
+If you have more specific needs or plan on modifying semantic_puppet you can
+install it out of a git repository:
+
+    git clone git://github.com/puppetlabs/semantic_puppet
+
+Usage
+-----
+
+SemanticPuppet is intended to be used as a library. 
+
+### Verison Range Operator Support
+
+SemanticPuppet will support the same version range operators as those used when
+publishing modules to [Puppet Forge](https://forge.puppetlabs.com) which is
+documented at 
+[Publishing Modules on the Puppet Forge](https://docs.puppetlabs.com/puppet/latest/reference/modules_publishing.html#dependencies-in-metadatajson).
+
+Contributors
+------------
+
+Pieter van de Bruggen wrote the library originally, with additions by Alex
+Dreyer, Jesse Scott and Anderson Mills.

data/Rakefile

@@ -0,0 +1,69 @@
+# RSpec tasks
+begin
+  require 'rspec/core/rake_task'
+
+  # Create the 'spec' task
+  RSpec::Core::RakeTask.new(:spec) do |task|
+    task.rspec_opts = '--color'
+  end
+
+  namespace :spec do
+    desc "Run the test suite and generate coverage metrics"
+    task :coverage => [ :simplecov, :spec ]
+
+    # Add test coverage to the 'spec' task.
+    task :simplecov do
+      ENV['COVERAGE'] = '1'
+    end
+  end
+
+  task :default => :spec
+rescue LoadError
+  warn "[Warning]: Could not load `rspec`."
+end
+
+# YARD tasks
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+
+  YARD::Rake::YardocTask.new(:doc) do |yardoc|
+    yardoc.files = [ 'lib/**/*.rb', '-', '**/*.md' ]
+  end
+rescue LoadError
+  warn "[Warning]: Could not load `yard`."
+end
+
+# Cane tasks
+begin
+  require 'cane/rake_task'
+
+  Cane::RakeTask.new(:cane) do |cane|
+    cane.add_threshold 'coverage/.last_run.json', :>=, 100
+    cane.abc_max = 15
+  end
+
+  Rake::Task['cane'].prerequisites << Rake::Task['spec:coverage']
+  Rake::Task[:default].clear_prerequisites
+  task :default => :cane
+rescue LoadError
+  warn "[Warning]: Could not load `cane`."
+end
+
+# Gem tasks
+begin
+  require 'rubygems/tasks'
+
+  task :gem => 'gem:build'
+  task :validate => [ 'cane', 'doc', 'gem:validate' ]
+
+  namespace :gem do
+    Gem::Tasks.new(
+      :tag => { :format => 'v%s' },
+      :sign => { :checksum => true, :pgp => true },
+      :build => { :tar => true }
+    )
+  end
+rescue LoadError
+  warn "[Warning]: Could not load `rubygems/tasks`."
+end

data/lib/semantic_puppet.rb

@@ -0,0 +1,7 @@
+module SemanticPuppet
+  autoload :Version, 'semantic_puppet/version'
+  autoload :VersionRange, 'semantic_puppet/version_range'
+  autoload :Dependency, 'semantic_puppet/dependency'
+
+  VERSION = '0.1.0'
+end

data/lib/semantic_puppet/dependency.rb

@@ -0,0 +1,181 @@
+require 'semantic_puppet'
+
+module SemanticPuppet
+  module Dependency
+    extend self
+
+    autoload :Graph,         'semantic_puppet/dependency/graph'
+    autoload :GraphNode,     'semantic_puppet/dependency/graph_node'
+    autoload :ModuleRelease, 'semantic_puppet/dependency/module_release'
+    autoload :Source,        'semantic_puppet/dependency/source'
+
+    autoload :UnsatisfiableGraph, 'semantic_puppet/dependency/unsatisfiable_graph'
+
+    # @!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.
+    #
+    # @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 [Graph] the root of a dependency graph
+    def query(modules)
+      constraints = Hash[modules.map { |k, v| [ k, VersionRange.parse(v) ] }]
+
+      graph = Graph.new(constraints)
+      fetch_dependencies(graph)
+      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 [Graph] 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, graph.dependencies.dup)
+      end
+      raise UnsatisfiableGraph.new(graph)
+    end
+
+    # Fetches all available releases for the given module name.
+    #
+    # @param name [String] the module name to find releases for
+    # @return [Array<ModuleRelease>] the available releases
+    def fetch_releases(name)
+      releases = {}
+
+      sources.each do |source|
+        source.fetch(name).each do |dependency|
+          releases[dependency.version] ||= dependency
+        end
+      end
+
+      return releases.values
+    end
+
+    private
+
+    # Iterates over a changing set of dependencies in search of the best
+    # solution available. Fitness is specified as meeting all the constraints
+    # placed on it, being {ModuleRelease#satisfied? satisfied}, and having the
+    # greatest version number (with stability being preferred over prereleases).
+    #
+    # @todo Traversal order is not presently guaranteed.
+    #
+    # @param graph [Graph] the root of a dependency graph
+    # @param dependencies [{ String => Array<ModuleRelease> }] the dependencies
+    # @param considering [Array<GraphNode>] the set of releases being tested
+    # @return [Array<GraphNode>] the list of releases to use, if successful
+    def walk(graph, dependencies, *considering)
+      return considering if dependencies.empty?
+
+      # Selecting a dependency from the collection...
+      name = dependencies.keys.sort.first
+      deps = dependencies.delete(name)
+
+      # ... (and stepping over it if we've seen it before) ...
+      unless (deps & considering).empty?
+        return walk(graph, dependencies, *considering)
+      end
+
+      # ... we'll iterate through the list of possible versions in order.
+      preferred_releases(deps).reverse_each do |dep|
+
+        # We should skip any releases that violate any module's constraints.
+        unless [graph, *considering].all? { |x| x.satisfies_constraints?(dep) }
+          next
+        end
+
+        # We should skip over any releases that violate graph-level constraints.
+        potential_solution = considering.dup << dep
+        unless graph.satisfies_graph? potential_solution
+          next
+        end
+
+        catch :next do
+          # After adding any new dependencies and imposing our own constraints
+          # on existing dependencies, we'll mark ourselves as "under
+          # consideration" and recurse.
+          merged = dependencies.merge(dep.dependencies) { |_,a,b| a & b }
+
+          # If all subsequent dependencies resolved well, the recursive call
+          # 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(graph, merged, *potential_solution)
+        end
+      end
+
+      # Once we've exhausted all of our possible versions, we know that our
+      # last choice was unusable, so we'll unwind the stack and make a new
+      # choice.
+      throw :next
+    end
+
+    # 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 node [GraphNode] the node to fetch details for
+    # @return [void]
+    def fetch_dependencies(node, cache = {})
+      node.dependency_names.each do |name|
+        unless cache.key?(name)
+          cache[name] = fetch_releases(name)
+          cache[name].each { |dep| fetch_dependencies(dep, cache) }
+        end
+
+        node << cache[name]
+      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)
+      satisfied = releases.select { |x| x.satisfied? }
+
+      if satisfied.any? { |x| x.version.stable? }
+        return satisfied.select { |x| x.version.stable? }
+      else
+        return satisfied
+      end
+    end
+  end
+end

data/lib/semantic_puppet/dependency/graph.rb

@@ -0,0 +1,60 @@
+require 'semantic_puppet/dependency'
+
+module SemanticPuppet
+  module Dependency
+    class Graph
+      include GraphNode
+
+      attr_reader :modules
+
+      # Create a new instance of a dependency graph.
+      #
+      # @param modules [{String => VersionRange}] the required module
+      #        set and their version constraints
+      def initialize(modules = {})
+        @modules = modules.keys
+
+        modules.each do |name, range|
+          add_constraint('initialize', name, range.to_s) do |node|
+            range === node.version
+          end
+
+          add_dependency(name)
+        end
+      end
+
+      # Constrains graph solutions based on the given block.  Graph constraints
+      # are used to describe fundamental truths about the tooling or module
+      # system (e.g.: module names contain a namespace component which is
+      # dropped during install, so module names must be unique excluding the
+      # namespace).
+      #
+      # @example Ensuring a single source for all modules
+      #     @graph.add_constraint('installed', mod.name) do |nodes|
+      #       nodes.count { |node| node.source } == 1
+      #     end
+      #
+      # @see #considering_solution?
+      #
+      # @param source [String, Symbol] a name describing the source of the
+      #               constraint
+      # @yieldparam nodes [Array<GraphNode>] the nodes to test the constraint
+      #             against
+      # @yieldreturn [Boolean] whether the node passed the constraint
+      # @return [void]
+      def add_graph_constraint(source, &block)
+        constraints[:graph] << [ source, block ]
+      end
+
+      # Checks the proposed solution (or partial solution) against the graph's
+      # constraints.
+      #
+      # @see #add_graph_constraint
+      #
+      # @return [Boolean] true if none of the graph constraints are violated
+      def satisfies_graph?(solution)
+        constraints[:graph].all? { |_, check| check[solution] }
+      end
+    end
+  end
+end