reviewer 0.1.1 → 0.1.5

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Keywords
+    module Git
+      # Provides a convenient interface to get the list of staged files via Git
+      class Staged
+        OPTIONS = [
+          'diff',
+          '--staged',
+          '--name-only'
+        ].freeze
+
+        attr_reader :stdout, :stderr, :status, :exit_status
+
+        def to_a
+          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
+
+          @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
+
+        private
+
+        def raise_command_line_error
+          message = "Git Error: #{stderr} (#{command})"
+          raise SystemCallError.new(message, exit_status)
+        end
+
+        def command_parts
+          BASE_COMMAND + OPTIONS
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/keywords/git.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'git/staged'
+
+module Reviewer
+  module Keywords
+    module Git
+      BASE_COMMAND = [
+        'git',
+        '--no-pager'
+      ].freeze
+    end
+  end
+end

data/lib/reviewer/keywords.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'keywords/git'
+
+module Keywords
+  # Grouping for individual commands
+  module Git
+  end
+end

data/lib/reviewer/loader.rb

@@ -1,32 +1,59 @@
 # frozen_string_literal: true
 
-require "yaml"
-require "active_support/core_ext/hash/indifferent_access"
+require 'yaml'
 
-# Provides a collection of the configured tools
 module Reviewer
+  # Provides a collection of the configured tools
   class Loader
     class MissingConfigurationError < StandardError; end
+
     class InvalidConfigurationError < StandardError; end
 
-    attr_reader :configuration
+    class MissingReviewCommandError < StandardError; end
+
+    attr_reader :configuration, :file
+
+    def initialize(file = Reviewer.configuration.file)
+      @file = file
+      @configuration = configuration_hash
 
-    def initialize
-      @configuration = HashWithIndifferentAccess.new(configuration_hash)
+      validate_configuration!
     end
 
     def to_h
       configuration
     end
 
+    def self.configuration
+      new.configuration
+    end
+
     private
 
+    def validate_configuration!
+      # Any additional guidance for configuration issues will live here
+      require_review_commands!
+    end
+
+    def require_review_commands!
+      configuration.each do |key, value|
+        commands = value[:commands]
+
+        next if commands.key?(:review)
+
+        # Ideally, folks would want to fill out everything to receive the most benefit,
+        # but realistically, the 'review' command is the only required value. If the key
+        # is missing, or maybe there was a typo, fail right away.
+        raise MissingReviewCommandError, "'#{key}' does not have a 'review' key under 'commands' in `#{file}`"
+      end
+    end
+
     def configuration_hash
-      @configuration_hash ||= YAML.load_file(Reviewer.configuration.file)
+      @configuration_hash ||= Psych.safe_load_file(@file, symbolize_names: true)
     rescue Errno::ENOENT
-      raise MissingConfigurationError, "Tools configuration file couldn't be found - #{Reviewer.configuration.file}"
+      raise MissingConfigurationError, "Tools configuration file couldn't be found at `#{file}`"
     rescue Psych::SyntaxError => e
-      raise InvalidConfigurationError, "Tools configuration file has a syntax error - #{e.message}"
+      raise InvalidConfigurationError, "Tools configuration file (#{file}) has a syntax error: #{e.message}"
     end
   end
 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

data/lib/reviewer/output/scrubber.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Output
+    # Provides a structure interface for the results of running a command
+    class Scrubber
+      # A lot of tools are run via rake which inclues some unhelpful drive when there's a non-zero
+      #   exit status. This is what it starts with so Reviewer can recognize and remove it.
+      RAKE_ABORTED_TEXT = <<~DRIVEL
+        rake aborted!
+      DRIVEL
+
+      attr_accessor :raw
+
+      # Creates a scrubber instance for the provided text content
+      # @param raw [String] the text to be scrubbed of unhelpful content
+      #
+      # @return [self]
+      def initialize(raw)
+        @raw = raw || ''
+      end
+
+      def clean
+        rake_aborted_text? ? preceding_text : raw
+      end
+
+      private
+
+      def rake_aborted_text?
+        raw.include?(RAKE_ABORTED_TEXT)
+      end
+
+      # Removes any unhelpful rake exit status details from $stderr. Reviewew uses `exit` when a
+      #   command fails so that the resulting command-line exit status can be interpreted correctly
+      #   in CI and similar environments. Without that exit status, those environments wouldn't
+      #   recognize the failure. As a result, Rake almost always adds noise that begins with the value
+      #   in RAKE_EXIT_DRIVEL when `exit` is called. Frequently, that RAKE_EXIT_DRIVEL is the only
+      #   information in $stderr, and it's not helpful in the human-readable output, but other times
+      #   when a valid exception occurs, there's useful error information preceding RAKE_EXIT_DRIVEL.
+      #   So this ensures that the unhelpful part is always removed so the output is cluttered with
+      #   red herrings since the command is designed to fail with an exit status of 1 under normal
+      #   operation with tool failures.
+      def preceding_text
+        raw.split(RAKE_ABORTED_TEXT).first
+      end
+    end
+  end
+end

data/lib/reviewer/output/token.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Output
+    # Simple class for streamlining the output of 'tokens' representing a style and content
+    #
+    # @author [garrettdimon]
+    #
+    class Token
+      ESC = "\e["
+
+      attr_accessor :style, :content
+
+      def initialize(style, content)
+        @style = style
+        @content = content
+      end
+
+      def to_s
+        [
+          style_string,
+          content,
+          reset_string
+        ].join
+      end
+
+      private
+
+      def style_string
+        "#{ESC}#{weight};#{color}m"
+      end
+
+      def reset_string
+        "#{ESC}0m"
+      end
+
+      def weight_key
+        style_components[0]
+      end
+
+      def color_key
+        style_components[1]
+      end
+
+      def weight
+        {
+          default: 0,
+          bold: 1,
+          light: 2,
+          italic: 3
+        }.fetch(weight_key)
+      end
+
+      def color
+        {
+          black: 30,
+          red: 31,
+          green: 32,
+          yellow: 33,
+          blue: 34,
+          magenta: 35,
+          cyan: 36,
+          gray: 37,
+          default: 39
+        }.fetch(color_key)
+      end
+
+      def style_components
+        {
+          success_bold: %i[bold green],
+          success: %i[default green],
+          success_light: %i[light green],
+          error: %i[bold red],
+          failure: %i[default red],
+          warning: %i[bold yellow],
+          warning_light: %i[light yellow],
+          source: %i[italic default],
+          bold: %i[default default],
+          default: %i[default default],
+          muted: %i[light gray]
+        }.fetch(style)
+      end
+    end
+  end
+end

data/lib/reviewer/output.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'io/console/size' # For determining console width/height
+
+require_relative 'output/printer'
+require_relative 'output/scrubber'
+require_relative 'output/token'
+
+module Reviewer
+  # Friendly API for printing nicely-formatted output to the console
+  class Output
+    DEFAULT_CONSOLE_WIDTH = 120
+    DIVIDER = '·'
+
+    attr_reader :printer
+
+    # Creates an instance of Output to print Reviewer activity and results to the console
+    def initialize(printer = Printer.new)
+      @printer = printer
+    end
+
+    def clear
+      system('clear')
+    end
+
+    def newline
+      printer.puts(:default, '')
+    end
+
+    def divider
+      newline
+      printer.print(:muted, DIVIDER * console_width)
+    end
+
+    # Prints plain text to the console
+    # @param message [String] the text to write to the console
+    #
+    # @return [void]
+    def help(message)
+      printer.puts(:default, message)
+    end
+
+    # Prints a summary of the total time and results for a batch run. If multiple tools, it will
+    #  show the total tool count
+    # @param tool_count [Integer] the number of commands run in the batch
+    # @param seconds [Float] the total number of seconds the batch ran in realtime
+    #
+    # @return [void]
+    def batch_summary(tool_count, seconds)
+      printer.print(:bold, "~#{seconds.round(1)} seconds")
+      printer.puts(:muted, " for #{tool_count} tools") if tool_count > 1
+    end
+
+    # Print a tool summary using the name and description. Used before running a command to help
+    #   identify which tool is running at any given moment.
+    # @param tool [Tool] the tool to identify and describe
+    #
+    # @return [void]
+    def tool_summary(tool)
+      printer.print(:bold, tool.name)
+      printer.puts(:muted, " #{tool.description}")
+    end
+
+    # Prints the text of a command to the console to help proactively expose potentials issues with
+    #   syntax if Reviewer translated thte provided options in an unexpected way
+    # @param command [String, Command] the command to identify on the console
+    #
+    # @return [void] [description]
+    def current_command(command)
+      printer.puts(:bold, 'Now Running:')
+      printer.puts(:default, String(command))
+    end
+
+    def success(timer)
+      printer.print(:success, 'Success')
+      printer.print(:success_light, " #{timer.total_seconds}s")
+      printer.print(:warning_light, " (#{timer.prep_percent}% prep ~#{timer.prep_seconds}s)") if timer.prepped?
+      newline
+      newline
+    end
+
+    def failure(details, command: nil)
+      printer.print(:failure, 'Failure')
+      printer.puts(:muted, " #{details}")
+
+      return if command.nil?
+
+      newline
+      printer.puts(:bold, 'Failed Command:')
+      printer.puts(:muted, String(command))
+    end
+
+    def unrecoverable(details)
+      printer.puts(:error, 'Unrecoverable Error:')
+      printer.puts(:muted, details)
+    end
+
+    def guidance(summary, details)
+      return if details.nil?
+
+      newline
+      printer.puts(:bold, summary)
+      printer.puts(:muted, details)
+    end
+
+    def unfiltered(value)
+      return if value.nil? || value.strip.empty?
+
+      printer.stream << value
+    end
+
+    protected
+
+    def console_width
+      return DEFAULT_CONSOLE_WIDTH if IO.console.nil?
+
+      _height, width = IO.console.winsize
+
+      width
+    end
+  end
+end

data/lib/reviewer/runner/strategies/captured.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Runner
+    module Strategies
+      # Execution strategy for a runner to run a command quietly by capturing the output and only
+      #   displaying it if there's a failure that justifies it
+      # @attr_reader runner [Runner] the instance of the runner that will be executed with this strategy
+      # @attr_reader start_time [Time] the start time for the strategy_for timing purposes
+      class Captured
+        attr_reader :runner, :start_time
+
+        # Create an instance of the captured strategy for a command runner so that any output is
+        #    fully suppressed so as to not create too much noise when running multiple commands.
+        # @param runner [Runner] the instance of the runner to apply the strategy to
+        #
+        # @return [self]
+        def initialize(runner)
+          @runner = runner
+          @start_time = Time.now
+        end
+
+        # The prepare command strategy when running a command and capturing the results
+        #
+        # @return [void]
+        def prepare
+          command = runner.prepare_command
+
+          display_progress(command) { runner.shell.capture_prep(command) }
+
+          # Running the prepare command, so make sure the timestamp is updated
+          runner.update_last_prepared_at
+        end
+
+        # The run command strategy when running a command and capturing the results
+        #
+        # @return [void]
+        def run
+          command = runner.command
+
+          display_progress(command) { runner.shell.capture_main(command) }
+
+          # If it's successful, show that it was a success and how long it took to run, otherwise,
+          # it wasn't successful and we got some explaining to do...
+          runner.success? ? show_timing_result : show_command_output
+        end
+
+        private
+
+        # Displays the progress of the current command since the output is captured/suppressed.
+        #   Helps people know that the sub-command is running within expectations.
+        # @param command [String] the precise command string generated by Reviewer. Serves as the
+        #   key for looking up the command's history.
+        # @param &block [Block] the runner for the command that's being timed and having its
+        #   progress updated and printed
+        #
+        # @return [void]
+        def display_progress(command, &block) # rubocop:disable Metrics/AbcSize
+          start_time = Time.now
+          average_time = runner.tool.average_time(command)
+
+          thread = Thread.new { block.call }
+
+          while thread.alive?
+            elapsed = (Time.now - start_time).to_f.round(1)
+            progress = if average_time.zero?
+                         "#{elapsed}s"
+                       else
+                         "~#{((elapsed / average_time) * 100).round}%"
+                       end
+
+            $stdout.print "> #{progress} \r"
+            $stdout.flush
+          end
+        end
+
+        # Determines if stdout or stderr captured any useful output that can be displayed in order
+        #   to more rapidly display output when a command fails. As long as both aren't nil or
+        #   otherwise 'blank' strings, then that's enough.
+        #
+        # @return [Boolean] true if either stdout or stderr contain printable content
+        def usable_output_captured?
+          [runner.stdout, runner.stderr].reject { |value| value.nil? || value.strip.empty? }.any?
+        end
+
+        # Prints "Success" and the resulting timing details before moving on to the next tool
+        #
+        # @return [void]
+        def show_timing_result
+          runner.record_timing
+          runner.output.success(runner.timer)
+        end
+
+        # Prints "Failure" and the resulting exit status. Shows the precise command that led to the
+        # failure for easier copy and paste or making it easier to see any incorrect syntax or
+        # options that could be corrected.
+        #
+        # @return [void]
+        def show_command_output
+          # If there's a failure, clear the successful command output to focus on the issues
+          runner.output.clear
+
+          # Show the exit status and failed command
+          runner.output.failure("Exit Status #{runner.exit_status}", command: runner.command)
+
+          # If it can't be rerun, then don't try
+          usable_output_captured? ? show_captured_output : rerun_via_passthrough
+        end
+
+        # If the command sent output to stdout/stderr as most will, simply display what was captured
+        #
+        # @return [void]
+        def show_captured_output
+          show_captured_stdout
+          show_captured_stderr
+        end
+
+        # If there's a useful stdout value, display it with a divider to visually separate it.
+        #
+        # @return [void]
+        def show_captured_stdout # rubocop:disable Metrics/AbcSize
+          return if runner.stdout.nil? || runner.stdout.empty?
+
+          runner.output.divider
+          runner.output.newline
+          runner.output.unfiltered(runner.stdout)
+        end
+
+        # If there's a useful stderr value, display it with a divider to visually separate it.
+        #
+        # @return [void]
+        def show_captured_stderr # rubocop:disable Metrics/AbcSize
+          return if runner.stderr.nil? || runner.stderr.empty?
+
+          scrubbed_stderr = Reviewer::Output::Scrubber.new(runner.stderr).clean
+
+          runner.output.divider
+          runner.output.newline
+          runner.output.guidance('Runtime Errors:', scrubbed_stderr)
+        end
+
+        # If for some reason, the command didn't send anything to stdout/stderr, the only option to
+        # show results is to rerun it via the passthrough strategy
+        #
+        # @return [void]
+        def rerun_via_passthrough
+          return unless runner.rerunnable?
+
+          runner.strategy = Strategies::Passthrough
+
+          runner.output.divider
+          runner.run
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/runner/strategies/passthrough.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Runner
+    module Strategies
+      # Execution strategy for a runner to run a command transparently-displaying the command's
+      #   output in realtime as it runs (as opposed to capturing and suppressing the output unless
+      #   the command fails)
+      # @attr_reader runner [Runner] the instance of the runner that will be executed with this strategy
+      class Passthrough
+        attr_reader :runner
+
+        # Create an instance of the passthrough strategy for a command runner. This strategy ensures
+        # that when a command is run, the output isn't suppressed. Essentially, it's a transparent
+        # wrapper for running a command and displaying the results realtime.
+        # @param runner [Runner] the instance of the runner to apply the strategy to
+        #
+        # @return [self]
+        def initialize(runner)
+          @runner = runner
+        end
+
+        # The prepare command strategy when running a command transparently
+        #
+        # @return [void]
+        def prepare
+          # Running the prepare command, so make sure the timestamp is updated
+          runner.update_last_prepared_at
+
+          # Display the exact command syntax that's being run. This can come in handy if there's an
+          # issue and the command can be copied/pasted or if the generated command somehow has some
+          # incorrect syntax or options that need to be corrected.
+          runner.output.current_command(runner.prepare_command)
+
+          # Add a divider to visually delineate the results
+          runner.output.divider
+
+          # Run the command through the shell directly so no output is suppressed
+          runner.shell.direct(runner.prepare_command)
+        end
+
+        # The run command strategy when running a command transparently
+        #
+        # @return [void]
+        def run
+          # Display the exact command syntax that's being run. This can come in handy if there's an
+          # issue and the command can be copied/pasted or if the generated command somehow has some
+          # incorrect syntax or options that need to be corrected.
+          runner.output.current_command(runner.command)
+
+          # Add a divider to visually delineate the results
+          runner.output.divider
+
+          # Run the command through the shell directly so no output is suppressed
+          runner.shell.direct(runner.command)
+
+          # Add a final divider to visually delineate the results
+          runner.output.divider
+        end
+      end
+    end
+  end
+end