reviewer 0.1.4 → 0.1.5

data/lib/reviewer/arguments/files.rb

@@ -9,14 +9,20 @@ module Reviewer
 
       alias raw provided
 
-      # Generates and instance of files from the provided arguments
+      # Generates an instance of files from the provided arguments
       # @param provided: Reviewer.arguments.files.raw [Array, String] file arguments provided
       #   directly via the -f or --files flag on the command line.
       # @param keywords: Reviewer.arguments.keywords [Array, String] keywords that can potentially
       #   be translated to a list of files (ex. 'staged')
       #
-      # @return [Arguments::Files] the container for determining targeted files from the provided
-      #   command line arguments
+      # @example Using the `-f` flag: `rvw -f ./file.rb`
+      #   reviewer = Reviewer::Arguments::Files.new(provided: ['./file.rb'], keywords: [])
+      #   reviewer.to_a # => ['./file.rb']
+      # @example Using the `--files` flag: `rvw --files ./file.rb,./directory/file.rb
+      #   reviewer = Reviewer::Arguments::Files.new(provided: ['./file.rb','./directory/file.rb'], keywords: [])
+      #   reviewer.to_a # => ['./file.rb','./directory/file.rb']
+      #
+      # @return [self]
       def initialize(provided: Reviewer.arguments.files.raw, keywords: Reviewer.arguments.keywords)
         @provided = Array(provided)
         @keywords = Array(keywords)
@@ -38,7 +44,7 @@ module Reviewer
 
       # Summary of the state of the file arguments
       #
-      # @return [Hash] represents the summary of the file values parsed from the command-line
+      # @return [Hash<Symbol, Array<String>>] summarizes all of the resulting file values
       def to_h
         {
           provided: provided.sort,
@@ -50,7 +56,7 @@ module Reviewer
       private
 
       # Combines the sorted list of unique files/paths by merging the explicitly-provided file
-      # arguments as well as those that were translated from any relevant keyword arguments.
+      #   arguments as well as those that were translated from any relevant keyword arguments.
       #
       # @return [Array] full list of files/paths passed via command-line including those extracted
       #   as a result of a keyword argument like `staged`
@@ -63,8 +69,8 @@ module Reviewer
 
       # Converts relevant keywords to the list of files they implicitly represent.
       #
-      # @return [Array] list of files/paths translated from any keyword arguments that represent a
-      #   list of files
+      # @return [Array<String>] list of files/paths translated from any keyword arguments that
+      #   represent a list of files
       def from_keywords
         return [] unless keywords.any?
 
@@ -76,7 +82,7 @@ module Reviewer
       end
 
       # If `staged` is passed as a keyword via the command-line, this will get the list of staged
-      # files via Git
+      #   files via Git
       #
       # @return [Array] list of the currently staged files
       def staged

data/lib/reviewer/arguments/keywords.rb

@@ -4,6 +4,9 @@ module Reviewer
   class Arguments
     # Handles interpreting all 'leftover' arguments and translating them to file-related,
     # tag-related, or tool-related arguments
+    #
+    # @!attribute provided
+    #   @return [Array<String>] the keywords extracted from the command-line arguments
     class Keywords
       RESERVED = %w[staged].freeze
 
@@ -11,10 +14,10 @@ module Reviewer
 
       alias raw provided
 
-      # Generates an instace of parsed keywords from the provided arguments
+      # Generates an instance of parsed keywords from the provided arguments
       # @param *provided [Array<String>] the leftover (non-flag) arguments from the command line
       #
-      # @return [Arguments::Keywords]
+      # @return [self]
       def initialize(*provided)
         @provided = Array(provided.flatten)
       end

data/lib/reviewer/arguments/tags.rb

@@ -8,14 +8,21 @@ module Reviewer
 
       alias raw provided
 
-      # Generates an instace of parsed tags from the provided arguments
+      # Generates an instace of parsed tags from the provided arguments by merging tag arguments
+      #   that were provided via either flags or keywords
       # @param provided: Reviewer.arguments.tags.raw [Array<String>] tag arguments provided
       #   directly via the -t or --tags flag on the command line.
       # @param keywords: Reviewer.arguments.keywords [Array, String] keywords that can potentially
       #   be translated to a list of tags based on the tags used in the configuration file
       #
-      # @return [Arguments::Tags] the container for extracting tags from the provided command line
-      #   arguments
+      # @example Using keywords: `rvw ruby` (assuming a 'ruby' tag is defined)
+      #   Reviewer::Arguments::Tags.new.to_a # => ['ruby']
+      # @example Using the `-t` flag: `rvw -t ruby`
+      #   Reviewer::Arguments::Tags.new.to_a # => ['ruby']
+      # @example Using the `--tags` flag: `rvw -t ruby,css`
+      #   Reviewer::Arguments::Tags.new.to_a # => ['css', 'ruby']
+      #
+      # @return [self]
       def initialize(provided: Reviewer.arguments.tags.raw, keywords: Reviewer.arguments.keywords.for_tags)
         @provided = Array(provided)
         @keywords = Array(keywords)
@@ -49,7 +56,7 @@ module Reviewer
       private
 
       # Combines the sorted list of unique tags by merging the explicitly-provided tag arguments
-      # as well as those that were recognized from any relevant keyword arguments.
+      #   as well as those that were recognized from any relevant keyword arguments.
       #
       # @return [Array] full list of tags passed via command-line including those matching keyword
       #   arguments

data/lib/reviewer/arguments.rb

@@ -23,10 +23,17 @@ module Reviewer
 
     attr_reader :output
 
-    # A catch all for aguments passed to reviewer via the command-line.
+    # 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
     #
-    # @return [Reviewer::Arguments] the full collection of arguments provided via the command line
+    # @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|
@@ -34,12 +41,12 @@ module Reviewer
         opts.array '-t', '--tags', 'a list of comma-separated tags', delimiter: ',', default: []
 
         opts.on '-v', '--version', 'print the version' do
-          @output.info VERSION
+          @output.help VERSION
           exit
         end
 
         opts.on '-h', '--help', 'print the help' do
-          @output.info opts
+          @output.help opts
           exit
         end
       end

data/lib/reviewer/batch.rb

@@ -7,6 +7,12 @@ module Reviewer
 
     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
@@ -14,17 +20,19 @@ module Reviewer
       @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
-        tools.each do |tool|
+        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)
-
-          # With multiple tools, run each one quietly.
-          # Otherwise, with just one tool
           runner.run
 
-          # Record the exit status
-          capture_results(runner)
+          # Record the exit status for this tool
+          record_exit_status(runner)
 
           # If the tool fails, stop running other tools
           break unless runner.success?
@@ -34,10 +42,6 @@ module Reviewer
       results
     end
 
-    def self.run(*args)
-      new(*args).run
-    end
-
     private
 
     def multiple_tools?
@@ -45,11 +49,22 @@ module Reviewer
     end
 
     def strategy
-      multiple_tools? ? Runner::Strategies::Quiet : Runner::Strategies::Verbose
+      multiple_tools? ? Runner::Strategies::Captured : Runner::Strategies::Passthrough
     end
 
-    def capture_results(runner)
-      @results[runner.tool.key] = runner.exit_status
+    # 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
@@ -58,7 +73,19 @@ module Reviewer
     # @return [void] prints the elapsed time
     def benchmark_batch(&block)
       elapsed_time = Benchmark.realtime(&block)
-      output.info "\nTotal Time ".white + "#{elapsed_time.round(1)}s".bold
+
+      # 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

@@ -7,6 +7,10 @@ module Reviewer
       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

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

@@ -3,18 +3,29 @@
 module Reviewer
   class Command
     class String
-      # Assembles tool flag settings into a single string or array
+      # 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) }

data/lib/reviewer/command/string.rb

@@ -2,20 +2,18 @@
 
 require_relative 'string/env'
 require_relative 'string/flags'
-require_relative 'string/verbosity'
 
 module Reviewer
   class Command
-    # Assembles tool tool_settings into a usable command string for the command type and verbosity
+    # Assembles tool tool_settings into a usable command string for the command type
     class String
       include Conversions
 
-      attr_reader :command_type, :tool_settings, :verbosity
+      attr_reader :command_type, :tool_settings
 
-      def initialize(command_type, tool_settings:, verbosity: nil)
+      def initialize(command_type, tool_settings:)
         @command_type = command_type
         @tool_settings = tool_settings
-        @verbosity = Verbosity(verbosity)
       end
 
       def to_s
@@ -29,11 +27,13 @@ module Reviewer
         [
           env_variables,
           body,
-          flags,
-          verbosity_options
+          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
@@ -42,23 +42,17 @@ module Reviewer
         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
-        # Flags to be used for `review` commands.
-        # 1. The `review` commands are the only commands that use flags
-        # 2. If no flags are configured, this won't do much
-        #
-        # Note: Since verbosity is handled separately, flags for 'quiet' are handled separately at a
-        #   lower level by design and excluded from this check. They are not included with the other
-        #   configured flags.
         return nil unless flags?
 
         Flags.new(tool_settings.flags).to_s
       end
 
-      def verbosity_options
-        Verbosity.new(tool_settings.quiet_option, level: verbosity.level).to_s
-      end
-
       private
 
       # Determines whether the string needs flags added

data/lib/reviewer/command.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'command/string'
-require_relative 'command/verbosity'
 
 module Reviewer
   # The core funtionality to translate a tool, command type, and verbosity into a runnable command
@@ -10,19 +9,19 @@ module Reviewer
 
     SEED_SUBSTITUTION_VALUE = '$SEED'
 
-    attr_reader :tool, :type
+    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)
-    # @param verbosity = Verbosity::TOTAL_SILENCE [Symbol] the desired verbosity for the command
     #
     # @return [Command] the intersection of a tool, command type, and verbosity
-    def initialize(tool, type, verbosity = Verbosity::TOTAL_SILENCE)
+    def initialize(tool, type)
       @tool = Tool(tool)
       @type = type.to_sym
-      @verbosity = Verbosity(verbosity)
     end
 
     # The final command string with all of the conditions appled
@@ -33,26 +32,6 @@ module Reviewer
     end
     alias to_s string
 
-    # Getter for @verbosity. Since the setter is custom, the getter needs to be explicitly declared.
-    # Otherwise, using `attr_accessor` and then overriding the setter muddies the waters.
-    #
-    # @return [Verbosity] the current verbosity setting for the command
-    def verbosity # rubocop:disable Style/TrivialAccessors
-      @verbosity
-    end
-
-    # Override verbosity assignment to clear the related memoized values when verbosity changes
-    # @param verbosity [Verbosity, Symbol] the desired verbosity for the command
-    #
-    # @return [Verbosity] the updated verbosity level for the command
-    def verbosity=(verbosity)
-      # Unmemoize string since the verbosity has been changed
-      @raw_string = nil
-      @string = nil
-
-      @verbosity = Verbosity(verbosity)
-    end
-
     # 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.
@@ -68,20 +47,16 @@ module Reviewer
       @seed
     end
 
-    private
-
     # 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,
-        verbosity: verbosity
-      ).to_s
+      @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

data/lib/reviewer/configuration.rb

@@ -4,6 +4,14 @@ 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_PATH = Dir.pwd.freeze
 
@@ -18,7 +26,6 @@ module Reviewer
     def initialize
       @file = Pathname(DEFAULT_CONFIG_LOCATION)
       @history_file = Pathname(DEFAULT_HISTORY_LOCATION)
-      @printer = ::Reviewer::Printer.new
 
       # Future Configuration Options:
       # - seed_substitution_value(string): Currently a constant of `$SEED` in Reviewer::Command, but

data/lib/reviewer/conversions.rb

@@ -12,16 +12,5 @@ module Reviewer
       end
     end
     module_function :Tool
-
-    def Verbosity(value) # rubocop:disable Naming/MethodName
-      case value
-      when Command::Verbosity then value
-      when Symbol             then Command::Verbosity.new(value)
-      when String             then Command::Verbosity.new(value.to_sym)
-      when Integer            then Command::Verbosity.new(Command::Verbosity::LEVELS[value])
-      else raise TypeError, "Cannot convert #{value} to Verbosity"
-      end
-    end
-    module_function :Verbosity
   end
 end

data/lib/reviewer/guidance.rb

@@ -50,7 +50,13 @@ module Reviewer
     #
     # @return [void] prints missing executable guidance
     def show_missing_executable_guidance
-      output.missing_executable_guidance(command)
+      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
@@ -64,10 +70,8 @@ module Reviewer
     #
     # @return [void] prints syntax guidance
     def show_syntax_guidance
-      output.syntax_guidance(
-        ignore_link: command.tool.links[:ignore_syntax],
-        disable_link: command.tool.links[:disable_syntax]
-      )
+      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

@@ -3,15 +3,35 @@
 require 'yaml/store'
 
 module Reviewer
-  # Provides an instance of a storage resource for persisting data across runs
+  # 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?
@@ -19,18 +39,29 @@ module Reviewer
       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

data/lib/reviewer/keywords/git/staged.rb

@@ -17,6 +17,12 @@ module Reviewer
           stdout.strip.empty? ? [] : stdout.split("\n")
         end
 
+        # Gets the list of staged files
+        #
+        # @example Get the list of files
+        #   staged.list #=> ['/Code/example.rb', '/Code/run.rb']
+        #
+        # @return [Array<String>] the array of staged filenames as strings
         def list
           @stdout, @stderr, @status = Open3.capture3(command)
           @exit_status = @status.exitstatus.to_i
@@ -24,10 +30,20 @@ module Reviewer
           @status.success? ? to_a : raise_command_line_error
         end
 
+        # Convenience method for retrieving the list of staged files since there's no parameters
+        #   for an initializer.
+        #
+        # @example Get the list of files
+        #   Reviewer::Keywords::Git::Staged.list #=> ['/Code/example.rb', '/Code/run.rb']
+        #
+        # @return [Array<String>] the array of staged filenames as strings
         def self.list
           new.list
         end
 
+        # Assembles the pieces of the command that gets the list of staged files
+        #
+        # @return [String] the full command to run to retrieve the list of staged files
         def command
           command_parts.join(' ')
         end

data/lib/reviewer/output/printer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'io/console' # For determining console width/height
+
+module Reviewer
+  class Output
+    # Wrapper to encapsulate some lower-level details of printing to $stdout
+    class Printer
+      attr_reader :stream
+
+      # Creates an instance of Output to print Reviewer activity and results to the console
+      def initialize(stream = $stdout)
+        @stream = stream.tap do |str|
+          # If the IO channel supports flushing the output immediately, then ensure it's enabled
+          str.sync = str.respond_to?(:sync=)
+        end
+      end
+
+      def print(style, content)
+        text(style, content)
+      end
+
+      def puts(style, content)
+        text(style, content)
+        stream.puts
+      end
+
+      def tty?
+        stream.tty?
+      end
+      alias style_enabled? tty?
+
+      private
+
+      def text(style, content)
+        if style_enabled?
+          stream.print Token.new(style, content).to_s
+        else
+          stream.print content
+        end
+      end
+    end
+  end
+end