reviewer 0.1.4 → 0.1.5

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

@@ -1,92 +1,122 @@
 # frozen_string_literal: true
 
-require 'colorize'
+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
-    SUCCESS = 'Success'
-    FAILURE = 'Failure ·'
-    DIVIDER = ('-' * 60).to_s
+    DEFAULT_CONSOLE_WIDTH = 120
+    DIVIDER = '·'
 
     attr_reader :printer
 
-    def initialize(printer: Reviewer.configuration.printer)
+    # Creates an instance of Output to print Reviewer activity and results to the console
+    def initialize(printer = Printer.new)
       @printer = printer
     end
 
-    def info(message)
-      printer.info message
+    def clear
+      system('clear')
     end
 
-    def blank_line
-      printer.info
+    def newline
+      printer.puts(:default, '')
     end
 
     def divider
-      blank_line
-      printer.info DIVIDER.light_black
-      blank_line
+      newline
+      printer.print(:muted, DIVIDER * console_width)
     end
 
-    def tool_summary(tool)
-      printer.info "\n#{tool.name}".bold + ' · '.light_black + tool.description
+    # 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
 
-    def current_command(command)
-      command = String(command)
+    # 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
 
-      printer.info "\nNow Running:"
-      printer.info command.light_black
+    # 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
 
-    def exit_status(value)
-      failure("Exit Status #{value}")
+    # 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)
-      message = SUCCESS.green.bold + " #{timer.total_seconds}s".green
-      message += " (#{timer.prep_percent}% preparation)".yellow if timer.prepped?
-
-      printer.info message
+      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.error "#{FAILURE} #{details}".red.bold
+      printer.print(:failure, 'Failure')
+      printer.puts(:muted, " #{details}")
 
       return if command.nil?
 
-      blank_line
-      printer.error 'Failed Command:'.red.bold
-      printer.error String(command).light_black
+      newline
+      printer.puts(:bold, 'Failed Command:')
+      printer.puts(:muted, String(command))
     end
 
     def unrecoverable(details)
-      printer.error 'Unrecoverable Error:'.red.bold
-      printer.error details
+      printer.puts(:error, 'Unrecoverable Error:')
+      printer.puts(:muted, details)
     end
 
     def guidance(summary, details)
       return if details.nil?
 
-      blank_line
-      printer.info summary
-      printer.info details.to_s.light_black
+      newline
+      printer.puts(:bold, summary)
+      printer.puts(:muted, details)
     end
 
-    def missing_executable_guidance(command)
-      tool = command.tool
-      installation_command = Command.new(tool, :install, :no_silence).string if tool.installable?
-      install_link = tool.install_link
+    def unfiltered(value)
+      return if value.nil? || value.strip.empty?
 
-      failure("Missing executable for '#{tool}'", command: command)
-      guidance('Try installing the tool:', installation_command)
-      guidance('Read the installation guidance:', install_link)
+      printer.stream << value
     end
 
-    def syntax_guidance(ignore_link: nil, disable_link: nil)
-      guidance('Selectively Ignore a Rule:', ignore_link)
-      guidance('Fully Disable a Rule:', disable_link)
+    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/{verbose.rb → passthrough.rb}

@@ -3,22 +3,24 @@
 module Reviewer
   class Runner
     module Strategies
-      # Execution strategy to run a command verbosely
-      class Verbose
-        attr_accessor :runner
-
-        # Create an instance of the verbose strategy for a command runner. This strategy ensures
-        # that when a command is run, the output isn't suppressed. Essentially, it's a pass-through
-        # wrapper for running a command and displaying the results.
+      # 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 [Runner::Strategies::Verbose] an instance of the relevant verbose strategy
+        # @return [self]
         def initialize(runner)
           @runner = runner
-          @runner.command.verbosity = Reviewer::Command::Verbosity::NO_SILENCE
         end
 
-        # The prepare command strategy when running a command verbosely
+        # The prepare command strategy when running a command transparently
         #
         # @return [void]
         def prepare
@@ -37,12 +39,10 @@ module Reviewer
           runner.shell.direct(runner.prepare_command)
         end
 
-        # The run command strategy when running a command verbosely
+        # The run command strategy when running a command transparently
         #
         # @return [void]
         def run
-          # Display the exact command that's being 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.

data/lib/reviewer/runner.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'runner/strategies/quiet'
-require_relative 'runner/strategies/verbose'
+require_relative 'runner/strategies/captured'
+require_relative 'runner/strategies/passthrough'
 
 module Reviewer
   # Wrapper for executng a command and printing the results
@@ -14,9 +14,19 @@ module Reviewer
 
     def_delegators :@command, :tool
     def_delegators :@shell, :result, :timer
-    def_delegators :result, :exit_status
+    def_delegators :result, :exit_status, :stdout, :stderr, :rerunnable?
 
-    def initialize(tool, command_type, strategy = Strategies::Quiet, output: Reviewer.output)
+    # Creates a wrapper for running commansd through Reviewer in order to provide a more accessible
+    #   API for recording execution time and interpreting the results of a command in a more
+    #   generous way so that non-zero exit statuses can still potentiall be passing.
+    # @param tool [Symbol] the key for the desired tool to run
+    # @param command_type [Symbol] the key for the type of command to run
+    # @param strategy = Strategies::Captured [Runner::Strategies] how to execute and handle the
+    #   results of the command
+    # @param output: Reviewer.output [Review::Output] the output formatter for the results
+    #
+    # @return [self]
+    def initialize(tool, command_type, strategy = Strategies::Captured, output: Reviewer.output)
       @command = Command.new(tool, command_type)
       @strategy = strategy
       @shell = Shell.new
@@ -24,18 +34,16 @@ module Reviewer
     end
 
     def run
-      # Show which tool is about to run
-      output.tool_summary(tool)
+      # Show which tool is running
+      identify_tool
 
-      # Run the provided strategy
-      strategy.new(self).tap do |run_strategy|
-        run_strategy.prepare if run_prepare_step?
-        run_strategy.run
-      end
+      # Use the provided strategy to run the command
+      execute_strategy
 
-      # If it failed,
+      # If it failed, display guidance to help them get back on track
       guidance.show unless success?
 
+      # Return the exit status generated by the tool as interpreted by the Result
       exit_status
     end
 
@@ -53,19 +61,69 @@ module Reviewer
       end
     end
 
+    # Prints the tool name and description to the console as a frame of reference
+    #
+    # @return [void]
+    def identify_tool
+      # If there's an existing result, the runner is being re-run, and identifying the tool would
+      # be redundant.
+      return if result.exists?
+
+      output.tool_summary(tool)
+    end
+
+    # Runs the relevant strategy to either capture or pass through command output.
+    #
+    # @return [void]
+    def execute_strategy
+      # Run the provided strategy
+      strategy.new(self).tap do |run_strategy|
+        run_strategy.prepare if run_prepare_step?
+        run_strategy.run
+      end
+    end
+
+    # Determines whether a preparation step should be run before the primary command. If/when the
+    #   primary command is a `:prepare` command, then it shouldn't run twice. So it skips what would
+    #   be a superfluous run of the preparation.
+    #
+    # @return [Boolean] true the primary command is not prepare and the tool needs to be prepare
     def run_prepare_step?
       command.type != :prepare && tool.prepare?
     end
 
+    # Creates_an instance of the prepare command for a tool
+    #
+    # @return [Comman] the current tool's prepare command
     def prepare_command
-      @prepare_command ||= Command.new(tool, :prepare, command.verbosity)
+      @prepare_command ||= Command.new(tool, :prepare)
     end
 
+    # Updates the 'last prepared at' timestamp that Reviewer uses to know if a tool's preparation
+    #   step is stale and needs to be run again.
+    #
+    # @return [Time] the timestamp `last_prepared_at` is updated to
     def update_last_prepared_at
       # Touch the `last_prepared_at` timestamp for the tool so it waits before running again.
       tool.last_prepared_at = Time.now
     end
 
+    # Saves the last 5 elapsed times for the commands used this run by using the raw command as a
+    #   unique key. This enables the ability to compare times across runs while taking into
+    #   consideration that different iterations of the command may be running on fewer files. So
+    #   comparing a full run to the average time for a partial run wouldn't be helpful. By using the
+    #   raw command string, it will always be apples to apples.
+    #
+    # @return [void]
+    def record_timing
+      tool.record_timing(prepare_command, timer.prep)
+      tool.record_timing(command, timer.main)
+    end
+
+    # Uses the result of the runner to determine what, if any, guidance to display to help the user
+    #   get back on track in the event of an unsuccessful run.
+    #
+    # @return [Guidance] the relevant guidance based on the result of the runner
     def guidance
       @guidance ||= Reviewer::Guidance.new(command: command, result: result, output: output)
     end