reviewer 0.1.1 → 0.1.5

data/lib/reviewer/arguments.rb

@@ -2,43 +2,87 @@
 
 require 'slop'
 
-# Handles option parsing for bin/review
+require_relative 'arguments/keywords'
+require_relative 'arguments/files'
+require_relative 'arguments/tags'
+
 module Reviewer
+  # Handles option parsing for `rvw` and `fmt` commands
+  #
+  # @example
+  #
+  #   `rvw`
+  #   `rvw -t ruby`
+  #   `rvw -f ./example.rb,./example_test.rb`
+  #   `rvw staged`
+  #   `rvw --files ./example.rb,./example_test.rb --tags syntax`
+  #   `rvw ruby staged`
+  #
   class Arguments
     attr_accessor :options
 
+    attr_reader :output
+
+    # A catch all for aguments passed to reviewer via the command-line so they can be interpreted
+    #   and made available via the relevant classes.
+    # @param options = ARGV [Hash] options to parse and extract the relevant values for a run
+    #
+    # @example Using all options: `rvw keyword_one keyword_two --files ./example.rb,./example_test.rb --tags syntax`
+    #   reviewer = Reviewer::Arguments.new
+    #   reviewer.files.to_a # => ['./example.rb','./example_test.rb']
+    #   reviewer.tags.to_a # => ['syntax']
+    #   reviewer.keywords.to_a # => ['keyword_one', 'keyword_two']
+    #
+    # @return [self]
     def initialize(options = ARGV)
+      @output = Output.new
       @options = Slop.parse options do |opts|
         opts.array '-f', '--files', 'a list of comma-separated files or paths', delimiter: ',', default: []
         opts.array '-t', '--tags', 'a list of comma-separated tags', delimiter: ',', default: []
 
         opts.on '-v', '--version', 'print the version' do
-          puts VERSION
+          @output.help VERSION
           exit
         end
 
         opts.on '-h', '--help', 'print the help' do
-          puts opts
+          @output.help opts
           exit
         end
       end
     end
 
-    def files
-      options[:files]
+    # Converts the arguments to a hash for versatility
+    #
+    # @return [Hash] The files, tags, and keywords collected from the command line options
+    def to_h
+      {
+        files: files.raw,
+        tags: tags.raw,
+        keywords: keywords.raw
+      }
     end
+    alias inspect to_h
 
+    # The tag arguments collected from the command line via the `-t` or `--tags` flag
+    #
+    # @return [Arguments::Tags] an colelction of the tag arguments collected from the command-line
     def tags
-      options[:tags]
+      @tags ||= Arguments::Tags.new(provided: options[:tags])
     end
 
-    def arguments
-      options.arguments
+    # The file arguments collected from the command line via the `-f` or `--files` flag
+    #
+    # @return [Arguments::Files] an collection of the file arguments collected from the command-line
+    def files
+      @files ||= Arguments::Files.new(provided: options[:files])
     end
 
+    # The leftover arguments collected from the command line without being associated with a flag
+    #
+    # @return [Arguments::Keywords] an collection of the leftover arguments as keywords
     def keywords
-      # TODO: Filter arguments to only for allowed keywords to be defined later.
-      arguments
+      @keywords ||= Arguments::Keywords.new(options.arguments)
     end
   end
 end

data/lib/reviewer/batch.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Reviewer
+  # Provides a structure for running commands for a given set of tools
+  class Batch
+    class UnrecognizedCommandError < ArgumentError; end
+
+    attr_reader :command_type, :tools, :output, :results
+
+    # Generates an instance of Batch for running multiple tools together
+    # @param command_type [Symbol] the type of command to run for each tool.
+    # @param tools [Array<Tool>] the tools to run the commands for
+    # @param output: Reviewer.output [Output] the output channel to print results to
+    #
+    # @return [self]
+    def initialize(command_type, tools, output: Reviewer.output)
+      @command_type = command_type
+      @tools = tools
+      @output  = output
+      @results = {}
+    end
+
+    # Iterates over the tools in the batch to successfully run the commands. Also times the entire
+    #   batch in order to provide a total execution time.
+    #
+    # @return [Results] the results summary for all commands run
+    def run
+      benchmark_batch do
+        matching_tools.each do |tool|
+          # Create and execute a runner for the given tool, command type, and strategy
+          runner = Runner.new(tool, command_type, strategy)
+          runner.run
+
+          # Record the exit status for this tool
+          record_exit_status(runner)
+
+          # If the tool fails, stop running other tools
+          break unless runner.success?
+        end
+      end
+
+      results
+    end
+
+    private
+
+    def multiple_tools?
+      tools.size > 1
+    end
+
+    def strategy
+      multiple_tools? ? Runner::Strategies::Captured : Runner::Strategies::Passthrough
+    end
+
+    # Notes the exit status for the runner based on whether the runner was considered successful or
+    #   not based on the configured `max_exit_status` for the tool. For example, some tools use exit
+    #   status to convey significance. So even though it returns a non-zero exit status like 2, it
+    #   can still be successful.
+    # @param runner [Runner] the instance of the runner that's being inspected
+    #
+    # @return [Integer] the adjusted exit status for the runner
+    def record_exit_status(runner)
+      # Since some tools can "succeed" with a positive exit status, the overall batch is only
+      # interested in subjective failure. So if the runner succeeded according to the tool's max
+      # exit status, it should record the tool's run as a success for the purposes of the larger
+      # batch success/failure
+      @results[runner.tool.key] = runner.success? ? 0 : runner.exit_status
+    end
+
+    # Records and prints the total runtime of a block
+    # @param &block [type] section of code to be timed
+    #
+    # @return [void] prints the elapsed time
+    def benchmark_batch(&block)
+      elapsed_time = Benchmark.realtime(&block)
+
+      # If there's failures, skip showing the total time to focus on the issues
+      return if @results.values.sum.positive?
+
+      output.batch_summary(results.size, elapsed_time)
+    end
+
+    # Returns the set of tools matching the provided command. So when formatting, if a tool does not
+    #   have a format command, then it will be skipped.
+    #
+    # @return [Array<Tool>] the enabled tools that support the provided command
+    def matching_tools
+      tools.select { |tool| tool.settings.commands.key?(command_type) }
+    end
+  end
+end

data/lib/reviewer/command/string/env.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Command
+    class String
+      # Assembles tool environment variables into a single string or array
+      class Env
+        attr_reader :env_pairs
+
+        # Creates an instance of env variables for a tool to help generate the command string
+        # @param env_pairs [Hash] [description]
+        #
+        # @return [self]
+        def initialize(env_pairs)
+          @env_pairs = env_pairs
+        end
+
+        def to_s
+          to_a.compact.join(' ')
+        end
+
+        def to_a
+          env = []
+          env_pairs.each { |key, value| env << env(key, value) }
+          env
+        end
+
+        private
+
+        def env(key, value)
+          return nil if key.to_s.strip.empty? || value.to_s.strip.empty?
+
+          value = needs_quotes?(value) ? "'#{value}'" : value
+
+          "#{key.to_s.strip.upcase}=#{value.to_s.strip}"
+        end
+
+        def needs_quotes?(value)
+          value.is_a?(::String) && value.include?(' ')
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/command/string/flags.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Command
+    class String
+      # Translates tool flag settings from the tool's configuration values into a single string or
+      #   array that can be used to generate the command string
+      class Flags
+        attr_reader :flag_pairs
+
+        # Creates an instance of command-string friendly flags
+        # @param flag_pairs [Hash] the flags (keys) and their values
+        #
+        # @return [self]
+        def initialize(flag_pairs)
+          @flag_pairs = flag_pairs
+        end
+
+        # Creates a string-friendly format to use in a command
+        #
+        # @return [String] a string of flags that can be safely passed to a command
+        def to_s
+          to_a.join(' ')
+        end
+
+        # Creates an array of all flag name/value pairs
+        #
+        # @return [Array<String>] array of all flag strings to use to when running the command
+        def to_a
+          flags = []
+          flag_pairs.each { |key, value| flags << flag(key, value) }
+          flags
+        end
+
+        private
+
+        def flag(key, value)
+          dash = key.to_s.size == 1 ? '-' : '--'
+
+          value = needs_quotes?(value) ? "'#{value}'" : value
+
+          "#{dash}#{key} #{value}".strip
+        end
+
+        def needs_quotes?(value)
+          value.is_a?(::String) && value.include?(' ')
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/command/string.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'string/env'
+require_relative 'string/flags'
+
+module Reviewer
+  class Command
+    # Assembles tool tool_settings into a usable command string for the command type
+    class String
+      include Conversions
+
+      attr_reader :command_type, :tool_settings
+
+      def initialize(command_type, tool_settings:)
+        @command_type = command_type
+        @tool_settings = tool_settings
+      end
+
+      def to_s
+        to_a
+          .map(&:strip) # Remove extra spaces on the components
+          .join(' ')    # Merge the components
+          .strip        # Strip extra spaces from the end result
+      end
+
+      def to_a
+        [
+          env_variables,
+          body,
+          flags
+        ].compact
+      end
+
+      # The string of environment variables built from a tool's configuration settings
+      #
+      # @return [String] the environment variable names and values concatened for the command
+      def env_variables
+        Env.new(tool_settings.env).to_s
+      end
+
+      def body
+        tool_settings.commands.fetch(command_type)
+      end
+
+      # Gets the flags to be used in conjunction with the review command for a tool
+      #   1. The `review` commands are the only commands that use flags
+      #   2. If no flags are configured, this won't do anything
+      #
+      # @return [String] the concatenated list of flags to pass to the review command
+      def flags
+        return nil unless flags?
+
+        Flags.new(tool_settings.flags).to_s
+      end
+
+      private
+
+      # Determines whether the string needs flags added
+      #
+      # @return [Boolean] true if it's a review command and it has flags configured
+      def flags?
+        command_type == :review && tool_settings.flags.any?
+      end
+    end
+  end
+end

data/lib/reviewer/command.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative 'command/string'
+
+module Reviewer
+  # The core funtionality to translate a tool, command type, and verbosity into a runnable command
+  class Command
+    include Conversions
+
+    SEED_SUBSTITUTION_VALUE = '$SEED'
+
+    attr_reader :tool
+
+    attr_accessor :type
+
+    # Creates an instance of the Command class to synthesize a command string using the tool,
+    # command type, and verbosity.
+    # @param tool [Tool, Symbol] a tool or tool key to use to look up the command and options
+    # @param type [Symbol] the desired command type (:install, :prepare, :review, :format)
+    #
+    # @return [Command] the intersection of a tool, command type, and verbosity
+    def initialize(tool, type)
+      @tool = Tool(tool)
+      @type = type.to_sym
+    end
+
+    # The final command string with all of the conditions appled
+    #
+    # @return [String] the final, valid command string to run
+    def string
+      @string ||= seed_substitution? ? seeded_string : raw_string
+    end
+    alias to_s string
+
+    # Generates a seed that can be re-used across runs so that the results are consistent across
+    # related runs for tools that would otherwise change the seed automatically every run.
+    # Since not all tools will use the seed, there's no need to generate it in the initializer.
+    # Instead, it's memoized if it's used.
+    #
+    # @return [Integer] a random integer to pass to tools that use seeds
+    def seed
+      @seed ||= Random.rand(100_000)
+
+      # Store the seed for reference
+      Reviewer.history.set(tool.key, :last_seed, @seed)
+
+      @seed
+    end
+
+    # The raw command string before any substitutions. For example, since seeds need to remain
+    # consistent from one run to the next, they're
+    #
+    # @return [type] [description]
+    def raw_string
+      @raw_string ||= String.new(type, tool_settings: tool.settings).to_s
+    end
+
+    private
+
+    # The version of the command with the SEED_SUBSTITUTION_VALUE replaced
+    #
+    # @return [String] the command string with the SEED_SUBSTITUTION_VALUE replaced
+    def seeded_string
+      # Update the string with the memoized seed value
+      raw_string.gsub(SEED_SUBSTITUTION_VALUE, seed.to_s)
+    end
+
+    # Determines if the raw command string has a SEED_SUBSTITUTION_VALUE that needs replacing
+    #
+    # @return [Boolean] true if the raw command string contains the SEED_SUBSTITUTION_VALUE
+    def seed_substitution?
+      raw_string.include?(SEED_SUBSTITUTION_VALUE)
+    end
+  end
+end

data/lib/reviewer/configuration.rb

@@ -1,18 +1,43 @@
 # frozen_string_literal: true
 
+require 'pathname'
+
 module Reviewer
+  # Configuration values container for Reviewer
+  #
+  # @!attribute file
+  #   @return [Pathname] the pathname for the primary configuraton file
+  # @!attribute history_file
+  #   @return [Pathname] the pathname for the history file to store data across runs
+  #
+  # @author [garrettdimon]
+  #
   class Configuration
-    DEFAULT_CONFIGURATION_PATH = Dir.pwd.freeze
-    DEFAULT_CONFIGURATION_FILE = '.reviewer.yml'.freeze
+    DEFAULT_PATH = Dir.pwd.freeze
+
+    DEFAULT_CONFIG_FILE_NAME = '.reviewer.yml'
+    DEFAULT_HISTORY_FILE_NAME = '.reviewer_history.yml'
 
-    attr_accessor :file
+    DEFAULT_CONFIG_LOCATION = "#{DEFAULT_PATH}/#{DEFAULT_CONFIG_FILE_NAME}"
+    DEFAULT_HISTORY_LOCATION = "#{DEFAULT_PATH}/#{DEFAULT_HISTORY_FILE_NAME}"
+
+    attr_accessor :file, :history_file, :printer
 
     def initialize
-      @file = "#{DEFAULT_CONFIGURATION_PATH}/#{DEFAULT_CONFIGURATION_FILE}"
-    end
+      @file = Pathname(DEFAULT_CONFIG_LOCATION)
+      @history_file = Pathname(DEFAULT_HISTORY_LOCATION)
 
-    def tools
-      @tools ||= Loader.new.to_h
+      # Future Configuration Options:
+      # - seed_substitution_value(string): Currently a constant of `$SEED` in Reviewer::Command, but
+      #   may need to be configurable in case any command-line strings have other legitimate uses
+      #   for the value such that it may need to be override. Ideally, it woudl be changed to3
+      #   something obscure enough that conflicts wouldn't happen, but you never know
+      # - benchmark_everything(:dev, :optimize): Use the `time_up` gem to measure and show all the results
+      #   for each tool and step to help identify and reduce bottlenecks. It would mainly be a flag
+      #   for use in development, but it could also help folks troubleshoot their speed in finer
+      #   detail than the standard Reviewer output
+      # - default_preparation_refresh(integer time): Right now, it's hard-coded at 6 hours, but that may require
+      #   tuning for individual tools
     end
   end
 end

data/lib/reviewer/conversions.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Reviewer
+  # Conversion functions for special types in Reviewer
+  module Conversions
+    def Tool(value) # rubocop:disable Naming/MethodName
+      case value
+      when Tool   then value
+      when Symbol then Tool.new(value)
+      when String then Tool.new(value.to_sym)
+      else raise TypeError, "Cannot convert #{value} to Tool"
+      end
+    end
+    module_function :Tool
+  end
+end

data/lib/reviewer/guidance.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'yaml/store'
+
+module Reviewer
+  # Handles the logic around what to display after a command has been run
+  class Guidance
+    attr_reader :command, :result, :output
+
+    # Create an instance of guidance for suggesting recovery steps after errors
+    # @param command: [Command] the command that was run and needs recovery guidance
+    # @param result: [Result] the result of the command
+    # @param output: Reviewer.output [Output] the output channel for displaying content
+    #
+    # @return [Guidance] the guidance class to suggest relevant recovery steps
+    def initialize(command:, result:, output: Reviewer.output)
+      @command = command
+      @result = result
+      @output = output
+    end
+
+    # Prints the relevant guidance based on the command and result context
+    #
+    # @return [void] prints the relevant guidance to the stream
+    def show
+      case result
+      when executable_not_found? then show_missing_executable_guidance
+      when cannot_execute?       then show_unrecoverable_guidance
+      else                            show_syntax_guidance
+      end
+    end
+
+    private
+
+    # Conditional check for when the command result was that the executable couldn't be found
+    #
+    # @return [Boolean] true if the result indicates the command couldn't be found
+    def executable_not_found?
+      ->(result) { result.executable_not_found? }
+    end
+
+    # Conditional check for when the command result was that it was unable to be executed
+    #
+    # @return [Boolean] true if the result indicates the command couldn't be executed
+    def cannot_execute?
+      ->(result) { result.cannot_execute? }
+    end
+
+    # Shows the recovery guidance for when a command is missing
+    #
+    # @return [void] prints missing executable guidance
+    def show_missing_executable_guidance
+      tool = command.tool
+      installation_command = Command.new(tool, :install).string if tool.installable?
+      install_link = tool.install_link
+
+      output.failure("Missing executable for '#{tool}'", command: command)
+      output.guidance('Try installing the tool:', installation_command)
+      output.guidance('Read the installation guidance:', install_link)
+    end
+
+    # Shows the recovery guidance for when a command generates an unrecoverable error
+    #
+    # @return [void] prints unrecoverable error guidance
+    def show_unrecoverable_guidance
+      output.unrecoverable(result.stderr)
+    end
+
+    # Shows suggestions for ignoring or disable rules when a command fails after reviewing code
+    #
+    # @return [void] prints syntax guidance
+    def show_syntax_guidance
+      output.guidance('Selectively Ignore a Rule:', command.tool.links[:ignore_syntax])
+      output.guidance('Fully Disable a Rule:', command.tool.links[:disable_syntax])
+    end
+  end
+end

data/lib/reviewer/history.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'yaml/store'
+
+module Reviewer
+  # Provides an interface to a local storage resource for persisting data across runs. For example,
+  # it enables remembering when `prepare` commands were run for reviews so they can be run less
+  # frequently and thus improve performance.
+  #
+  # It also enables remembering seeds across runs. Eventually `rvw rerun` could reuse the seeds from
+  # the immediately preceding run to more easily facilitate fixing tests that are accidentally
+  # order-dependent. Or it could automatically record a list of seeds that led to failures.
+  #
+  # Long term, it could serve to record timing details across runs to provide insight to min, max,
+  # and means. Those times could then be used for reviewer to make more informed decisions about
+  # default behavior to ensure each run remains fast.
+  class History
+    attr_reader :file, :store
+
+    # Creates an instance of a YAML::Store-backed history file.
+    # @param file = Reviewer.configuration.history_file [Pathname] the history file to store data
+    #
+    # @return [History] an instance of history
+    def initialize(file = Reviewer.configuration.history_file)
+      @file = file
+      @store = YAML::Store.new(file)
+    end
+
+    # Saves a value to a given location in the history
+    # @param group [Symbol] the first-level key to use for saving the value--frequently a tool name
+    # @param attribute [Symbol] the second-level key to use for retrieving the value
+    # @param value [Primitive] any value that can be cleanly stored in YAML
+    #
+    # @return [Primitive] the value being stored
+    def set(group, attribute, value)
+      store.transaction do |s|
+        s[group] = {} if s[group].nil?
+        s[group][attribute] = value
+      end
+    end
+
+    # Retrieves a stored value from the history file
+    # @param group [Symbol] the first-level key to use for retrieving the value
+    # @param attribute [Symbol] the second-level key to use for retrieving the value
+    #
+    # @return [Primitive] the value being stored
+    def get(group, attribute)
+      store.transaction do |s|
+        s[group].nil? ? nil : s[group][attribute]
+      end
+    end
+
+    # Removes the existing history file.
+    #
+    # @return [void]
+    def reset!
+      return unless File.exist?(file)
+
+      FileUtils.rm(file)
+    end
+
+    # Convenience class method for removing the history file.
+    #
+    # @return [void]
+    def self.reset!
+      new.reset!
+    end
+  end
+end