polytrix 0.1.0.pre → 0.1.0

data/lib/polytrix/command.rb

@@ -0,0 +1,209 @@
+require 'thread'
+
+module Polytrix
+  module Command
+    class Base
+      include Polytrix::DefaultLogger
+      include Polytrix::Logging
+      include Polytrix::Core::FileSystemHelper
+
+      # Need standard executor...
+      SUPPORTED_EXTENSIONS = %w(py rb js)
+
+      # Contstructs a new Command object.
+      #
+      # @param cmd_args [Array] remainder of the arguments from processed ARGV
+      # @param cmd_options [Hash] hash of Thor options
+      # @param options [Hash] configuration options
+      # @option options [String] :action action to take, usually corresponding
+      #   to the subcommand name (default: `nil`)
+      # @option options [proc] :help a callable that displays help for the
+      #   command
+      # @option options [Config] :test_dir a Config object (default: `nil`)
+      # @option options [Loader] :loader a Loader object (default: `nil`)
+      # @option options [String] :shell a Thor shell object
+      def initialize(cmd_args, cmd_options, options = {})
+        @args = cmd_args
+        @options = cmd_options
+        @action = options.fetch(:action, nil)
+        @help = options.fetch(:help, -> { 'No help provided' })
+        @manifest_file = options.fetch('manifest', nil)
+        @test_dir = options.fetch('test_dir', nil)
+        @loader = options.fetch(:loader, nil)
+        @shell = options.fetch(:shell)
+      end
+
+      private
+
+      # @return [Array] remainder of the arguments from processed ARGV
+      # @api private
+      attr_reader :args
+
+      # @return [Hash] hash of Thor options
+      # @api private
+      attr_reader :options
+
+      # @return [proc] a callable that displays help for the command
+      # @api private
+      attr_reader :help
+
+      # @return [Config] a Config object
+      # @api private
+      attr_reader :test_dir
+
+      # @return [Thor::Shell] a Thor shell object
+      # @api private
+      attr_reader :shell
+
+      # @return [String] the action to perform
+      # @api private
+      attr_reader :action
+
+      def setup
+        manifest_file = File.expand_path @manifest_file
+        if File.exists? manifest_file
+          logger.debug "Loading manifest file: #{manifest_file}"
+          Polytrix.configuration.manifest = @manifest_file
+        elsif @options.solo
+          solo_setup
+        else
+          fail StandardError, "No manifest found at #{manifest_file} and not using --solo mode"
+        end
+
+        Polytrix.configuration.documentation_dir = options[:target_dir]
+        Polytrix.configuration.documentation_format = options[:format]
+
+        manifest.build_challenges
+
+        test_dir = @test_dir.nil? ? nil : File.expand_path(@test_dir)
+        if test_dir && File.directory?(test_dir)
+          $LOAD_PATH.unshift test_dir
+          Dir["#{test_dir}/**/*.rb"].each do | file_to_require |
+            require relativize(file_to_require, test_dir).to_s.gsub('.rb', '')
+          end
+        end
+      end
+
+      def solo_setup
+        suites = {}
+        solo_basedir = @options.solo
+        solo_glob = @options.fetch(:solo_glob, "**/*.{#{SUPPORTED_EXTENSIONS.join(',')}}")
+        Dir[File.join(solo_basedir, solo_glob)].each do | code_sample |
+          code_sample = Pathname.new(code_sample)
+          suite_name = relativize(code_sample.dirname, solo_basedir).to_s
+          scenario_name = code_sample.basename(code_sample.extname).to_s
+          suite = suites[suite_name] ||= Polytrix::Manifest::Suite.new(samples: [])
+          suite.samples << scenario_name
+        end
+        @manifest = Polytrix.configuration.manifest = Polytrix::Manifest.new(
+          implementors: {
+            File.basename(solo_basedir) => {
+              basedir: solo_basedir
+            }
+          },
+          suites: suites
+        )
+      end
+
+      def manifest
+        @manifest ||= Polytrix.configuration.manifest
+        @manifest
+      end
+
+      # Emit an error message, display contextual help and then exit with a
+      # non-zero exit code.
+      #
+      # **Note** This method calls exit and will not return.
+      #
+      # @param msg [String] error message
+      # @api private
+      def die(msg)
+        logger.error "\n#{msg}\n\n"
+        help.call
+        exit 1
+      end
+
+      # @return [Array<Scenario>] an array of scenarios
+      # @raise [SystemExit] if no scenario are returned
+      # @api private
+      def all_scenarios
+        result = manifest.challenges.values
+
+        if result.empty?
+          die 'No scenarios defined'
+        else
+          result
+        end
+      end
+
+      # Return an array on scenarios whos name matches the regular expression.
+      #
+      # @param regexp [Regexp] a regular expression matching on instance names
+      # @return [Array<Instance>] an array of scenarios
+      # @raise [SystemExit] if no scenarios are returned or the regular
+      #   expression is invalid
+      # @api private
+      def filtered_scenarios(regexp)
+        result = begin
+          manifest.challenges.get(regexp) ||
+            manifest.challenges.get_all(/#{regexp}/)
+        rescue RegexpError => e
+          die "Invalid Ruby regular expression, " \
+            "you may need to single quote the argument. " \
+            "Please try again or consult http://rubular.com/ (#{e.message})"
+        end
+        result = [result] unless result.is_a? Array
+
+        if result.empty?
+          die "No scenarios for regex `#{regexp}', try running `polytrix list'"
+        else
+          result
+        end
+      end
+
+      # Return an array on scenarios whos name matches the regular expression,
+      # the full instance name, or  the `"all"` literal.
+      #
+      # @param arg [String] an instance name, a regular expression, the literal
+      #   `"all"`, or `nil`
+      # @return [Array<Instance>] an array of scenarios
+      # @api private
+      def parse_subcommand(arg = nil)
+        arg ||= 'all'
+        arg == 'all' ? all_scenarios : filtered_scenarios(arg)
+      end
+    end
+
+    # Common module to execute a Polytrix action such as create, converge, etc.
+    module RunAction
+      # Run an instance action (create, converge, setup, verify, destroy) on
+      # a collection of scenarios. The instance actions will take place in a
+      # seperate thread of execution which may or may not be running
+      # concurrently.
+      #
+      # @param action [String] action to perform
+      # @param scenarios [Array<Instance>] an array of scenarios
+      def run_action(action, scenarios, *args)
+        concurrency = 1
+        if options[:concurrency]
+          concurrency = options[:concurrency] || scenarios.size
+          concurrency = scenarios.size if concurrency > scenarios.size
+        end
+
+        queue = Queue.new
+        scenarios.each { |i| queue << i }
+        concurrency.times { queue << nil }
+
+        threads = []
+        concurrency.times do
+          threads << Thread.new do
+            while (instance = queue.pop)
+              instance.public_send(action, *args)
+            end
+          end
+        end
+        threads.map { |i| i.join }
+      end
+    end
+  end
+end

data/lib/polytrix/configuration.rb

@@ -1,7 +1,4 @@
 require 'middleware'
-require 'logger'
-require 'hashie/dash'
-require 'hashie/extensions/coercion'
 
 module Polytrix
   RESOURCES_DIR = File.expand_path '../../../resources', __FILE__
@@ -20,60 +17,40 @@ module Polytrix
     end
   end
 
-  class Configuration < Hashie::Dash
-    include Hashie::Extensions::Coercion
-
+  class Configuration < Polytrix::ManifestSection
     property :dry_run,      default: false
-    property :log_level,       default: 'info'
+    property :log_root,     default: '.polytrix/logs'
+    property :log_level,    default: :info
     property :middleware,   default: Polytrix::Runners::Middleware::STANDARD_MIDDLEWARE
     property :implementors, default: []
     # coerce_key :implementors, Polytrix::Implementor
     property :suppress_output, default: false
     property :default_doc_template
     property :template_dir, default: "#{RESOURCES_DIR}"
+    property :documentation_dir, default: 'docs/'
+    property :documentation_format, default: 'md'
     # Extra options for rspec
     property :rspec_options, default: ''
 
-    def logger
-      @logger ||= ::Logger.new($stdout).tap do |logger|
-        levels = {
-          'fatal' => ::Logger::FATAL,
-          'error' => ::Logger::ERROR,
-          'warn'  => ::Logger::WARN,
-          'info'  => ::Logger::INFO,
-          'debug' => ::Logger::DEBUG
-        }
-        fail "Unknown log level: #{log_level}" unless levels.keys.include? log_level
-        logger.level = levels[log_level]
-      end
-    end
-
-    def test_manifest
-      @test_manifest ||= Manifest.from_yaml 'polytrix_tests.yml'
+    def default_logger
+      @default_logger ||= Logger.new(stdout: $stdout, level: env_log)
     end
 
-    def test_manifest=(yaml_file)
-      @test_manifest = Manifest.from_yaml yaml_file
+    def manifest
+      @manifest ||= load_manifest('polytrix.yml')
     end
 
-    def implementor(metadata)
-      if metadata.is_a? Hash # load from data
-        Implementor.new(metadata).tap do |implementor|
-          implementors << implementor
-        end
-      else # load from filesystem
-        folder = metadata
-        fail ArgumentError, "#{folder} is not a directory" unless File.directory? folder
-        settings_file = File.expand_path('polytrix.yml', folder)
-        if File.exist? settings_file
-          settings = YAML.load(File.read(settings_file))
-          Polytrix.configuration.implementor(settings.merge(basedir: folder))
-        else
-          Polytrix.configuration.implementor name: File.basename(folder), basedir: folder
-        end
+    def manifest=(manifest_data)
+      if manifest_data.is_a? Manifest
+        @manifest = manifest_data
+      else
+        @manifest = Manifest.from_yaml manifest_data
       end
+      @manifest
     end
 
+    alias_method :load_manifest, :manifest=
+
     # The callback used to validate code samples that
     # don't have a custom validator.  The default
     # checks that the sample code runs successfully.
@@ -88,5 +65,18 @@ module Polytrix
     end
 
     attr_writer :default_validator_callback
+
+    private
+
+    # Determine the default log level from an environment variable, if it is
+    # set.
+    #
+    # @return [Integer,nil] a log level or nil if not set
+    # @api private
+    def env_log
+      level = ENV['POLYTRIX_LOG'] && ENV['POLYTRIX_LOG'].downcase.to_sym
+      level = Polytrix::Util.to_logger_level(level) unless level.nil?
+      level
+    end
   end
 end

data/lib/polytrix/core/file_system_helper.rb

@@ -1,7 +1,8 @@
 module Polytrix
   module Core
     module FileSystemHelper
-      include Polytrix::Logger
+      include Polytrix::Logging
+      include Polytrix::StringHelpers
       class FileNotFound < StandardError; end
 
       # Finds a file by loosely matching the file name to a scenario name
@@ -20,10 +21,6 @@ module Polytrix
         Pathname.new file
       end
 
-      def slugify(path)
-        path.downcase.gsub(' ', '_')
-      end
-
       def recursive_parent_search(path, file_name = nil, &block)
         if block_given?
           obj = yield path

data/lib/polytrix/core/hashie.rb

@@ -0,0 +1,14 @@
+require 'hashie/dash'
+require 'hashie/mash'
+require 'hashie/extensions/coercion'
+
+module Polytrix
+  class Dash < Hashie::Dash
+    include Hashie::Extensions::Coercion
+
+    def initialize(hash = {})
+      mash = Hashie::Mash.new(hash)
+      super mash.to_hash(symbolize_keys: true)
+    end
+  end
+end

data/lib/polytrix/core/implementor.rb

@@ -7,39 +7,79 @@ module Polytrix
       super "Feature #{feature} is not implemented"
     end
   end
-  class Implementor < Hashie::Dash
-    include Polytrix::Logger
+  class Implementor < Polytrix::ManifestSection
+    class GitOptions < Polytrix::ManifestSection
+      property :repo, required: true
+      property :branch
+      property :to
+
+      def initialize(data)
+        data = { repo: data } if data.is_a? String
+        super
+      end
+    end
+
+    include Polytrix::Logging
     include Polytrix::Core::FileSystemHelper
-    include Hashie::Extensions::Coercion
-    include Polytrix::Executor
+    include Polytrix::Runners::Executor
     property :name
     property :basedir, required: true
     property :language
     coerce_key :basedir, Pathname
+    property :git
+    coerce_key :git, GitOptions
 
     def initialize(data)
-      data = Hashie::Mash.new data
-      data[:name] ||= File.basename data[:basedir]
       data[:basedir] = File.absolute_path(data[:basedir])
-      super(data)
+      super
+    end
+
+    def logger
+      @logger ||= Polytrix::Logger.new_logger(self)
+    end
+
+    def clone
+      # Logging.mdc['implementor'] = name
+      if git.nil? || git.repo.nil?
+        logger.info 'Skipping clone because there are no git options'
+        return
+      end
+      branch = git.branch ||= 'master'
+      target_dir = git.to ||= basedir
+      if File.exists? target_dir
+        logger.info "Skipping clone because #{target_dir} already exists"
+      else
+        clone_cmd = "git clone #{git.repo} -b #{branch} #{target_dir}"
+        logger.info "Cloning: #{clone_cmd}"
+        execute clone_cmd
+      end
     end
 
     def bootstrap
+      # Logging.mdc['implementor'] = name
+      banner "Bootstrapping #{name}"
+      fail "Implementor #{name} has not been cloned" unless cloned?
+
       execute('./scripts/bootstrap', cwd: basedir, prefix: name)
     rescue Errno::ENOENT
       logger.warn "Skipping bootstrapping for #{name}, no script/bootstrap exists"
     end
 
     def build_challenge(challenge_data)
-      challenge_data[:source_file] ||= find_file basedir, challenge_data[:name]
       challenge_data[:basedir] ||= basedir
-      challenge_data[:source_file] = relativize(challenge_data[:source_file], challenge_data[:basedir])
       challenge_data[:implementor] ||= self
       challenge_data[:suite] ||= ''
-      fail FeatureNotImplementedError, "#{name} is not setup" unless File.directory? challenge_data[:basedir]
+      begin
+        challenge_data[:source_file] ||= find_file basedir, challenge_data[:name]
+        challenge_data[:source_file] = relativize(challenge_data[:source_file], challenge_data[:basedir])
+      rescue Polytrix::Core::FileSystemHelper::FileNotFound
+        challenge_data[:source_file] = nil
+      end
       Challenge.new challenge_data
-    rescue Polytrix::Core::FileSystemHelper::FileNotFound
-      raise FeatureNotImplementedError, challenge_data[:name]
+    end
+
+    def cloned?
+      File.directory? basedir
     end
   end
 end

data/lib/polytrix/core/manifest_section.rb

@@ -0,0 +1,4 @@
+module Polytrix
+  class ManifestSection < Polytrix::Dash
+  end
+end

data/lib/polytrix/core/string_helpers.rb

@@ -0,0 +1,15 @@
+module Polytrix
+  module StringHelpers
+    module ClassMethods
+      def slugify(*string)
+        string.join('-').downcase.gsub(' ', '_')
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    include ClassMethods
+  end
+end

data/lib/polytrix/documentation/helpers/code_helper.rb

@@ -18,9 +18,11 @@ module Polytrix
         class MarkdownHelper
           def self.code_block(source, language)
             buffer = StringIO.new
+            buffer.puts # I've seen lots of rendering issues without a dividing newline
             buffer.puts "```#{language}"
             buffer.puts source
             buffer.puts '```'
+            buffer.puts # Put a dividing newline after as well, to be safe...
             buffer.string
           end
         end
@@ -30,7 +32,7 @@ module Polytrix
         end
 
         def source
-          File.read source_file
+          File.read absolute_source_file
         end
 
         def code_block(source_code, language, opts = { format: :markdown })

data/lib/polytrix/error.rb

@@ -0,0 +1,209 @@
+require 'English'
+
+module Polytrix
+  # All Polytrix errors and exceptions.
+  module Error
+    # Creates an array of strings, representing a formatted exception,
+    # containing backtrace and nested exception info as necessary, that can
+    # be viewed by a human.
+    #
+    # For example:
+    #
+    #     ------Exception-------
+    #     Class: Polytrix::StandardError
+    #     Message: Failure starting the party
+    #     ---Nested Exception---
+    #     Class: IOError
+    #     Message: not enough directories for a party
+    #     ------Backtrace-------
+    #     nil
+    #     ----------------------
+    #
+    # @param exception [::StandardError] an exception
+    # @return [Array<String>] a formatted message
+    def self.formatted_trace(exception)
+      arr = formatted_exception(exception).dup
+      last = arr.pop
+      if exception.respond_to?(:original) && exception.original
+        arr += formatted_exception(exception.original, 'Nested Exception')
+        last = arr.pop
+      end
+      arr += ['Backtrace'.center(22, '-'), exception.backtrace, last].flatten
+      arr
+    end
+
+    # Creates an array of strings, representing a formatted exception that
+    # can be viewed by a human. Thanks to MiniTest for the inspiration
+    # upon which this output has been designed.
+    #
+    # For example:
+    #
+    #     ------Exception-------
+    #     Class: Polytrix::StandardError
+    #     Message: I have failed you
+    #     ----------------------
+    #
+    # @param exception [::StandardError] an exception
+    # @param title [String] a custom title for the message
+    #   (default: `"Exception"`)
+    # @return [Array<String>] a formatted message
+    def self.formatted_exception(exception, title = 'Exception')
+      [
+        title.center(22, '-'),
+        "Class: #{exception.class}",
+        "Message: #{exception.message}",
+        ''.center(22, '-')
+      ]
+    end
+  end
+
+  # Base exception class from which all Polytrix exceptions derive. This class
+  # nests an exception when this class is re-raised from a rescue block.
+  class StandardError < ::StandardError
+    include Error
+
+    # @return [::StandardError] the original (wrapped) exception
+    attr_reader :original
+
+    # Creates a new StandardError exception which optionally wraps an original
+    # exception if given or detected by checking the `$!` global variable.
+    #
+    # @param msg [String] exception message
+    # @param original [::StandardError] an original exception which will be
+    #   wrapped (default: `$ERROR_INFO`)
+    def initialize(msg, original = $ERROR_INFO)
+      super(msg)
+      @original = original
+    end
+  end
+
+  # Base exception class for all exceptions that are caused by user input
+  # errors.
+  class UserError < StandardError; end
+
+  # Base exception class for all exceptions that are caused by incorrect use
+  # of an API.
+  class ClientError < StandardError; end
+
+  # Base exception class for exceptions that are caused by external library
+  # failures which may be temporary.
+  class TransientFailure < StandardError; end
+
+  # Exception class for any exceptions raised when performing an challenge
+  # action.
+  class ActionFailed < TransientFailure; end
+
+  # Exception class capturing what caused an challenge to die.
+  class ChallengeFailure < TransientFailure; end
+
+  class ExecutionError < TransientFailure
+    attr_accessor :execution_result
+  end
+
+  # Yields to a code block in order to consistently emit a useful crash/error
+  # message and exit appropriately. There are two primary failure conditions:
+  # an expected challenge failure, and any other unexpected failures.
+  #
+  # **Note** This method may call `Kernel.exit` so may not return if the
+  # yielded code block raises an exception.
+  #
+  # ## Challenge Failure
+  #
+  # This is an expected failure scenario which could happen if an challenge
+  # couldn't be created, a Chef run didn't successfully converge, a
+  # post-convergence test suite failed, etc. In other words, you can count on
+  # encountering these failures all the time--this is Polytrix's worldview:
+  # crash early and often. In this case a cleanly formatted exception is
+  # written to `STDERR` and the exception message is written to
+  # the common Polytrix file logger.
+  #
+  # ## Unexpected Failure
+  #
+  # All other forms of `Polytrix::Error` exceptions are considered unexpected
+  # or unplanned exceptions, typically from user configuration errors, driver
+  # or provisioner coding issues or bugs, or internal code issues. Given
+  # a stable release of Polytrix and a solid set of drivers and provisioners,
+  # the most likely cause of this is user configuration error originating in
+  # the `.polytrix.yml` setup. For this reason, the exception is written to
+  # `STDERR`, a full formatted exception trace is written to the common
+  # Polytrix file logger, and a message is displayed on `STDERR` to the user
+  # informing them to check the log files and check their configuration with
+  # the `polytrix diagnose` subcommand.
+  #
+  # @raise [SystemExit] if an exception is raised in the yielded block
+  def self.with_friendly_errors
+    yield
+  rescue Polytrix::ChallengeFailure => e
+    Polytrix.mutex.synchronize do
+      handle_challenge_failure(e)
+    end
+    exit 10
+  rescue Polytrix::Error => e
+    Polytrix.mutex.synchronize do
+      handle_error(e)
+    end
+    exit 20
+  end
+
+  private
+
+  # Writes an array of lines to the common Polytrix logger's file device at the
+  # given severity level. If the Polytrix logger is set to debug severity, then
+  # the array of lines will also be written to the console output.
+  #
+  # @param level [Symbol,String] the desired log level
+  # @param lines [Array<String>] an array of strings to log
+  # @api private
+  def self.file_log(level, lines)
+    Array(lines).each do |line|
+      if Polytrix.logger.debug?
+        Polytrix.logger.debug(line)
+      else
+        Polytrix.logger.logdev && Polytrix.logger.logdev.public_send(level, line)
+      end
+    end
+  end
+
+  # Writes an array of lines to the `STDERR` device.
+  #
+  # @param lines [Array<String>] an array of strings to log
+  # @api private
+  def self.stderr_log(lines)
+    Array(lines).each do |line|
+      $stderr.puts(Color.colorize(">>>>>> #{line}", :red))
+    end
+  end
+
+  # Writes an array of lines to the common Polytrix debugger with debug
+  # severity.
+  #
+  # @param lines [Array<String>] an array of strings to log
+  # @api private
+  def self.debug_log(lines)
+    Array(lines).each { |line| Polytrix.logger.debug(line) }
+  end
+
+  # Handles an challenge failure exception.
+  #
+  # @param e [StandardError] an exception to handle
+  # @see Polytrix.with_friendly_errors
+  # @api private
+  def self.handle_challenge_failure(e)
+    stderr_log(e.message.split(/\s{2,}/))
+    stderr_log(Error.formatted_exception(e.original))
+    file_log(:error, e.message.split(/\s{2,}/).first)
+    debug_log(Error.formatted_trace(e))
+  end
+
+  # Handles an unexpected failure exception.
+  #
+  # @param e [StandardError] an exception to handle
+  # @see Polytrix.with_friendly_errors
+  # @api private
+  def self.handle_error(e)
+    stderr_log(Error.formatted_exception(e))
+    stderr_log('Please see .polytrix/logs/polytrix.log for more details')
+    # stderr_log("Also try running `polytrix diagnose --all` for configuration\n")
+    file_log(:error, Error.formatted_trace(e))
+  end
+end