polytrix 0.0.1 → 0.1.0.pre

data/lib/polytrix/cli.rb

@@ -0,0 +1,158 @@
+require 'polytrix'
+require 'thor'
+
+module Polytrix
+  module CLI
+    autoload :Add, 'polytrix/cli/add'
+    autoload :Report, 'polytrix/cli/report'
+
+    class Base < Thor
+      include Polytrix::Core::FileSystemHelper
+
+      def self.config_options
+        # I had trouble with class_option and subclasses...
+        method_option :manifest, type: 'string', default: 'polytrix_tests.yml', desc: 'The Polytrix test manifest file'
+        method_option :config, type: 'string', default: 'polytrix.rb', desc: 'The Polytrix config file'
+      end
+
+      def self.log_options
+        method_option :quiet, type: :boolean, default: false, desc: 'Do not print log messages'
+      end
+
+      def self.doc_options
+        method_option :target_dir, type: :string, default: 'docs'
+        method_option :lang, enum: Polytrix::Documentation::CommentStyles::COMMENT_STYLES.keys, desc: 'Source language (auto-detected if not specified)'
+        method_option :format, enum: %w(md rst), default: 'md'
+      end
+
+      def self.sdk_options
+        method_option :sdk, type: 'string', desc: 'An implementor name or directory', default: '.'
+      end
+
+      protected
+
+      def find_sdks(sdks)
+        sdks.map do |sdk|
+          implementor = Polytrix.implementors.find { |i| i.name == sdk }
+          abort "SDK #{sdk} not found" if implementor.nil?
+          implementor
+        end
+      end
+
+      def pick_implementor(sdk)
+        Polytrix.implementors.find { |i| i.name == sdk } || Polytrix.configuration.implementor(sdk)
+      end
+
+      def debug(msg)
+        say("polytrix::debug: #{msg}", :cyan) if debugging?
+      end
+
+      def debugging?
+        !ENV['POLYTRIX_DEBUG'].nil?
+      end
+
+      def setup
+        manifest_file = File.expand_path options[:manifest]
+        config_file = File.expand_path options[:config]
+        if File.exists? manifest_file
+          debug "Loading manifest file: #{manifest_file}"
+          Polytrix.configuration.test_manifest = manifest_file if File.exists? manifest_file
+        end
+        if File.exists? config_file
+          debug "Loading Polytrix config: #{config_file}"
+          require_relative config_file
+        end
+      end
+    end
+
+    class Main < Base
+      include Polytrix::Documentation::Helpers::CodeHelper
+
+      # register Add, :add, 'add', 'Add implementors or code samples'
+      # register Report, :report, 'report', 'Generate test reports'
+      desc 'add', 'Add implementors or code samples'
+      subcommand 'add', Add
+
+      desc 'report', 'Generate test reports'
+      subcommand 'report', Report
+
+      desc 'code2doc FILES', 'Converts annotated code to Markdown or reStructuredText'
+      doc_options
+      def code2doc(*files)
+        if files.empty?
+          help('code2doc')
+          abort 'No FILES were specified, check usage above'
+        end
+
+        files.each do |file|
+          target_file_name = File.basename(file, File.extname(file)) + ".#{options[:format]}"
+          target_file = File.join(options[:target_dir], target_file_name)
+          say_status 'polytrix:code2doc', "Converting #{file} to #{target_file}", !quiet?
+          doc = Polytrix::DocumentationGenerator.new.code2doc(file, options[:lang])
+          FileUtils.mkdir_p File.dirname(target_file)
+          File.write(target_file, doc)
+        end
+      rescue Polytrix::Documentation::CommentStyles::UnknownStyleError => e
+        abort "Unknown file extension: #{e.extension}, please use --lang to set the language manually"
+      end
+
+      desc 'exec', 'Executes code sample(s), using the SDK settings if provided'
+      method_option :code2doc, type: :boolean, desc: 'Convert successfully executed code samples to documentation using the code2doc command'
+      doc_options
+      sdk_options
+      config_options
+      def exec(*files)
+        setup
+        if files.empty?
+          help('exec')
+          abort 'No FILES were specified, check usage above'
+        end
+
+        exec_options = {
+          # default_implementor: pick_implementor(options[:sdk])
+        }
+
+        files.each do | file |
+          say_status 'polytrix:exec', "Running #{file}..."
+          results = Polytrix.exec(file, exec_options)
+          display_results results
+          code2doc(file) if options[:code2doc]
+        end
+      end
+
+      desc 'bootstrap [SDKs]', 'Bootstraps the SDK by installing dependencies'
+      config_options
+      def bootstrap(*sdks)
+        setup
+        Polytrix.bootstrap(*sdks)
+      rescue ArgumentError => e
+        abort e.message
+      end
+
+      desc 'test [SDKs]', 'Runs and tests the code samples'
+      method_option :rspec_options, format: 'string', desc: 'Extra options to pass to rspec'
+      config_options
+      def test(*sdks)
+        setup
+        implementors = find_sdks(sdks)
+        Polytrix.configuration.rspec_options = options[:rspec_options]
+        Polytrix.run_tests(implementors)
+      end
+
+      protected
+
+      def quiet?
+        options[:quiet] || false
+      end
+
+      def display_results(challenge)
+        short_name = challenge.name
+        exit_code = challenge.result.execution_result.exitstatus
+        color = exit_code == 0 ? :green : :red
+        stderr = challenge.result.execution_result.stderr
+        say_status "polytrix:exec[#{short_name}][stderr]", stderr, !quiet? unless stderr.empty?
+        say_status "polytrix:exec[#{short_name}]", "Finished with exec code: #{challenge.result.execution_result.exitstatus}", color unless quiet?
+      end
+    end
+  end
+end

data/lib/polytrix/configuration.rb

@@ -4,6 +4,7 @@ require 'hashie/dash'
 require 'hashie/extensions/coercion'
 
 module Polytrix
+  RESOURCES_DIR = File.expand_path '../../../resources', __FILE__
   # Autoload pool
   module Runners
     module Middleware
@@ -22,10 +23,70 @@ module Polytrix
   class Configuration < Hashie::Dash
     include Hashie::Extensions::Coercion
 
-    property :logger,       :default => Logger.new($stdout)
-    property :middleware,   :default => Polytrix::Runners::Middleware::STANDARD_MIDDLEWARE
-    property :implementors
-    coerce_key :implementors, Polytrix::Implementor
+    property :dry_run,      default: false
+    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}"
+    # 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'
+    end
+
+    def test_manifest=(yaml_file)
+      @test_manifest = Manifest.from_yaml yaml_file
+    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
+      end
+    end
+
+    # The callback used to validate code samples that
+    # don't have a custom validator.  The default
+    # checks that the sample code runs successfully.
+    def default_validator_callback
+      @default_validator_callback ||= proc do |challenge|
+        expect(challenge[:result].execution_result.exitstatus).to eq(0)
+      end
+    end
+
+    def default_validator
+      @default_validator ||= Validator.new(suite: //, scenario: //, &default_validator_callback)
+    end
+
+    attr_writer :default_validator_callback
   end
 end

data/lib/polytrix/core/file_system_helper.rb

@@ -0,0 +1,75 @@
+module Polytrix
+  module Core
+    module FileSystemHelper
+      include Polytrix::Logger
+      class FileNotFound < StandardError; end
+
+      # Finds a file by loosely matching the file name to a scenario name
+      def find_file(search_path, scenario_name, ignored_patterns = read_gitignore(search_path))
+        glob_string = "#{search_path}/**/*#{slugify(scenario_name)}.*"
+        potential_files = Dir.glob(glob_string, File::FNM_CASEFOLD)
+        potential_files.concat Dir.glob(glob_string.gsub('_', '-'), File::FNM_CASEFOLD)
+        potential_files.concat Dir.glob(glob_string.gsub('_', ''), File::FNM_CASEFOLD)
+
+        # Find the first file, not including generated files
+        file = potential_files.find do |f|
+          !ignored? ignored_patterns, search_path, f
+        end
+
+        fail FileNotFound, "No file was found for #{scenario_name} within #{search_path}" if file.nil?
+        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
+          return obj if obj
+        elsif file_name
+          file = File.expand_path(file_name, path)
+          logger.debug "Checking for #{file}"
+          found = File.exists? file
+        else
+          fail ArgumentError, 'Provide either a file_name to search for, or a block to check directories'
+        end
+
+        parent_dir = File.dirname(path)
+        return path if found
+        return nil if parent_dir == path # we've reached the top
+        recursive_parent_search(parent_dir, file_name, &block)
+      end
+
+      private
+
+      def read_gitignore(dir)
+        gitignore_file = "#{dir}/.gitignore"
+        File.read(gitignore_file)
+      rescue
+        ''
+      end
+
+      def ignored?(ignored_patterns, base_path, target_file)
+        # Trying to match the git ignore rules but there's some discrepencies.
+        ignored_patterns.split.find do |pattern|
+          # if git ignores a folder, we should ignore all files it contains
+          pattern = "#{pattern}**" if pattern[-1] == '/'
+          started_with_slash = pattern.start_with? '/'
+
+          pattern.gsub!(/\A\//, '') # remove leading slashes since we're searching from root
+          file = relativize(target_file, base_path)
+          ignored = file.fnmatch? pattern
+          ignored || (file.fnmatch? "**/#{pattern}" unless started_with_slash)
+        end
+      end
+
+      def relativize(file, base_path)
+        absolute_file = File.absolute_path(file)
+        absolute_base_path = File.absolute_path(base_path)
+        Pathname.new(absolute_file).relative_path_from Pathname.new(absolute_base_path)
+      end
+    end
+  end
+end

data/lib/polytrix/core/implementor.rb

@@ -2,16 +2,44 @@ require 'hashie/dash'
 require 'hashie/extensions/coercion'
 
 module Polytrix
+  class FeatureNotImplementedError < StandardError
+    def initialize(feature)
+      super "Feature #{feature} is not implemented"
+    end
+  end
   class Implementor < Hashie::Dash
+    include Polytrix::Logger
+    include Polytrix::Core::FileSystemHelper
     include Hashie::Extensions::Coercion
+    include Polytrix::Executor
     property :name
-    property :basedir
+    property :basedir, required: true
     property :language
     coerce_key :basedir, Pathname
 
     def initialize(data)
-      data[:basedir] ||= "sdks/#{data[:name]}"
+      data = Hashie::Mash.new data
+      data[:name] ||= File.basename data[:basedir]
+      data[:basedir] = File.absolute_path(data[:basedir])
       super(data)
     end
+
+    def bootstrap
+      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]
+      Challenge.new challenge_data
+    rescue Polytrix::Core::FileSystemHelper::FileNotFound
+      raise FeatureNotImplementedError, challenge_data[:name]
+    end
   end
-end
+end

data/lib/polytrix/documentation/code_segmenter.rb

@@ -0,0 +1,168 @@
+require 'polytrix/documentation/comment_styles'
+
+module Polytrix
+  module Documentation
+    # This class was extracted from the [Rocco](http://rtomayko.github.com/rocco/) project
+    # which was in turn based on the [Docco](http://jashkenas.github.com/docco/).
+    class CodeSegmenter # rubocop:disable all
+                        # Cops are disabled because the code is from Rocco
+      include CommentStyles
+
+      DEFAULT_OPTIONS = {
+        language: 'rb',
+        comment_chars: '#'
+      }
+
+      def initialize(options = {})
+        @options = DEFAULT_OPTIONS.merge options
+        @options[:comment_chars] = generate_comment_chars if @options[:comment_chars].is_a? String
+      end
+      # Internal Parsing and Highlighting
+      # ---------------------------------
+
+      # Parse the raw file source_code into a list of two-tuples. Each tuple has the
+      # form `[docs, code]` where both elements are arrays containing the
+      # raw lines parsed from the input file, comment characters stripped.
+      def segment(source_code)
+        sections, docs, code = [], [], []
+        lines = source_code.split("\n")
+
+        # The first line is ignored if it is a shebang line.  We also ignore the
+        # PEP 263 encoding information in python sourcefiles, and the similar ruby
+        # 1.9 syntax.
+        lines.shift if lines[0] =~ /^\#\!/
+        lines.shift if lines[0] =~ /coding[:=]\s*[-\w.]+/ &&
+                       %w(python rb).include?(@options[:language])
+
+        # To detect both block comments and single-line comments, we'll set
+        # up a tiny state machine, and loop through each line of the file.
+        # This requires an `in_comment_block` boolean, and a few regular
+        # expressions for line tests.  We'll do the same for fake heredoc parsing.
+        in_comment_block = false
+        in_heredoc = false
+        single_line_comment, block_comment_start, block_comment_mid, block_comment_end =
+          nil, nil, nil, nil
+        if not @options[:comment_chars][:single].nil?
+          single_line_comment = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:single])}\\s?")
+        end
+        if not @options[:comment_chars][:multi].nil?
+          block_comment_start = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\s*$")
+          block_comment_end   = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\s*$")
+          block_comment_one_liner = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\s*(.*?)\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\s*$")
+          block_comment_start_with = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\s*(.*?)$")
+          block_comment_end_with = Regexp.new("\\s*(.*?)\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\s*$")
+          if @options[:comment_chars][:multi][:middle]
+            block_comment_mid = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:middle])}\\s?")
+          end
+        end
+        if not @options[:comment_chars][:heredoc].nil?
+          heredoc_start = Regexp.new("#{Regexp.escape(@options[:comment_chars][:heredoc])}(\\S+)$")
+        end
+        lines.each do |line|
+          # If we're currently in a comment block, check whether the line matches
+          # the _end_ of a comment block or the _end_ of a comment block with a
+          # comment.
+          if in_comment_block
+            if block_comment_end && line.match(block_comment_end)
+              in_comment_block = false
+            elsif block_comment_end_with && line.match(block_comment_end_with)
+              in_comment_block = false
+              docs << line.match(block_comment_end_with).captures.first.
+                            sub(block_comment_mid || '', '')
+            else
+              docs << line.sub(block_comment_mid || '', '')
+            end
+          # If we're currently in a heredoc, we're looking for the end of the
+          # heredoc, and everything it contains is code.
+          elsif in_heredoc
+            if line.match(Regexp.new("^#{Regexp.escape(in_heredoc)}$"))
+              in_heredoc = false
+            end
+            code << line
+          # Otherwise, check whether the line starts a heredoc. If so, note the end
+          # pattern, and the line is code.  Otherwise check whether the line matches
+          # the beginning of a block, or a single-line comment all on it's lonesome.
+          # In either case, if there's code, start a new section.
+          else
+            if heredoc_start && line.match(heredoc_start)
+              in_heredoc = Regexp.last_match[1]
+              code << line
+            elsif block_comment_one_liner && line.match(block_comment_one_liner)
+              if code.any?
+                sections << [docs, code]
+                docs, code = [], []
+              end
+              docs << line.match(block_comment_one_liner).captures.first
+            elsif block_comment_start && line.match(block_comment_start)
+              in_comment_block = true
+              if code.any?
+                sections << [docs, code]
+                docs, code = [], []
+              end
+            elsif block_comment_start_with && line.match(block_comment_start_with)
+              in_comment_block = true
+              if code.any?
+                sections << [docs, code]
+                docs, code = [], []
+              end
+              docs << line.match(block_comment_start_with).captures.first
+            elsif single_line_comment && line.match(single_line_comment)
+              if code.any?
+                sections << [docs, code]
+                docs, code = [], []
+              end
+              docs << line.sub(single_line_comment || '', '')
+            else
+              code << line
+            end
+          end
+        end
+        sections << [docs, code] if docs.any? || code.any?
+        normalize_leading_spaces(sections)
+      end
+
+      # Normalizes documentation whitespace by checking for leading whitespace,
+      # removing it, and then removing the same amount of whitespace from each
+      # succeeding line.  That is:
+      #
+      #     def func():
+      #       """
+      #         Comment 1
+      #         Comment 2
+      #       """
+      #       print "omg!"
+      #
+      # should yield a comment block of `Comment 1\nComment 2` and code of
+      # `def func():\n  print "omg!"`
+      def normalize_leading_spaces(sections)
+        sections.map do |section|
+          if section.any? && section[0].any?
+            leading_space = section[0][0].match("^\s+")
+            if leading_space
+              section[0] =
+                section[0].map { |line| line.sub(/^#{leading_space.to_s}/, '') }
+            end
+          end
+          section
+        end
+      end
+
+      def comment(lines)
+        lines.map do | line |
+          "#{@options[:comment_chars][:single]} #{line}"
+        end.join "\n"
+      end
+
+      private
+
+      def generate_comment_chars
+        @_commentchar ||=
+          if COMMENT_STYLES[@options[:language]]
+            COMMENT_STYLES[@options[:language]]
+          else
+            { single: @options[:comment_chars], multi: nil, heredoc: nil }
+          end
+      end
+    end # rubocop:enable all
+  end
+end

data/lib/polytrix/documentation/comment_styles.rb

@@ -0,0 +1,87 @@
+module Polytrix
+  module Documentation
+    # This class was extracted from the [Rocco](http://rtomayko.github.com/rocco/) project
+    # which was in turn based on the [Docco](http://jashkenas.github.com/docco/).
+    module CommentStyles
+      class UnknownStyleError < StandardError
+        attr_accessor :extension
+
+        def initialize(extension)
+          @extension = extension
+        end
+      end
+
+      def self.infer(extension)
+        extension.tr! '.', ''
+        return extension, COMMENT_STYLES[extension] if COMMENT_STYLES.key? extension
+
+        COMMENT_STYLES.each do | style_name, style |
+          return extension, style if style[:extensions].include? extension
+        end
+
+        fail UnknownStyleError, extension
+      end
+
+      C_STYLE_COMMENTS = {
+        single: '//',
+        multi: { start: '/**', middle: '*', end: '*/' },
+        heredoc: nil,
+        extensions: %w(c cpp cs java js php scala go)
+      }
+
+      COMMENT_STYLES  = {
+        'bash'          =>  { single: '#', multi: nil, extensions: %w(sh) },
+        'c'             =>  C_STYLE_COMMENTS,
+        'coffee-script' =>  {
+          single: '#',
+          multi: { start: '###', middle: nil, end: '###' },
+          heredoc: nil,
+          extensions: %w(coffee)
+        },
+        'cpp' =>  C_STYLE_COMMENTS,
+        'csharp' => C_STYLE_COMMENTS,
+        'css'           =>  {
+          single: nil,
+          multi: { start: '/**', middle: '*', end: '*/' },
+          heredoc: nil,
+          extensions: %w(css scss sass)
+        },
+        'html'           =>  {
+          single: nil,
+          multi: { start: '<!--', middle: nil, end: '-->' },
+          heredoc: nil,
+          extensions: %w(html htm)
+        },
+        'java'          =>  C_STYLE_COMMENTS,
+        'js'            =>  C_STYLE_COMMENTS,
+        'lua'           =>  {
+          single: '--',
+          multi: nil,
+          heredoc: nil,
+          extensions: %w(lua)
+        },
+        'php' => C_STYLE_COMMENTS,
+        'python'        =>  {
+          single: '#',
+          multi: { start: '"""', middle: nil, end: '"""' },
+          heredoc: nil,
+          extensions: %w(py)
+        },
+        'rb'            =>  {
+          single: '#',
+          multi: { start: '=begin', middle: nil, end: '=end', idiomatic: false },
+          heredoc: '<<-',
+          extensions: %w(rb)
+        },
+        'scala'         =>  C_STYLE_COMMENTS,
+        'scheme'        =>  { single: ';;',  multi: nil, heredoc: nil, extensions: %w(schema) },
+        'xml'           =>  {
+          single: nil,
+          multi: { start: '<!--', middle: nil, end: '-->' },
+          heredoc: nil,
+          extensions: %w(xml xsl xslt)
+        }
+      }
+    end
+  end
+end