reviewer 0.1.3 → 0.1.4

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Runner
+    module Strategies
+      # Execution strategy to run a command quietly
+      class Quiet
+        attr_accessor :runner
+
+        # Create an instance of the quiet 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 [Runner::Strategies::Quiet] an instance of the relevant quiet strategy
+        def initialize(runner)
+          @runner = runner
+          @runner.command.verbosity = Reviewer::Command::Verbosity::TOTAL_SILENCE
+        end
+
+        # The prepare command strategy when running a command quietly
+        #
+        # @return [void]
+        def prepare
+          # Running the prepare command, so make sure the timestamp is updated
+          runner.update_last_prepared_at
+
+          # Run the prepare command, suppressing the output and capturing the realtime benchmark
+          runner.shell.capture_prep(runner.prepare_command)
+        end
+
+        # The run command strategy when running a command verbosely
+        #
+        # @return [void]
+        def run
+          # Run the primary command, suppressing the output and capturing the realtime benchmark
+          runner.shell.capture_main(runner.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
+
+        # Prints "Success" and the resulting timing details before moving on to the next tool
+        #
+        # @return [void]
+        def show_timing_result
+          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
+          runner.output.failure("Exit Status #{runner.exit_status}", command: runner.command)
+
+          # If it can't be rerun, then don't try
+          return if runner.result.total_failure?
+
+          # If it can be rerun, set the strategy to verbose so the output will be visible, and then
+          # run it with the verbose strategy so the output isn't suppressed. Long-term, it makes
+          # sense to add an option for whether to focus on speed or rich output.
+          #
+          # For now, the simplest strategy is to re-run the exact same command without suppressing
+          # the output. However, running a command twice isn't exactly efficient. Since we've
+          # already run it once and captured the output, we could just display that output, but it
+          # would be filtered through as a dumb string. That would mean it strips out color and
+          # formatting. It would save time, but what's the threshold where the time savings is worth
+          # it?
+          #
+          # Ultimately, this will be a tradeoff between how much the tool's original formatting
+          # makes it easier to scan the results and take action. For example, if a command takes
+          # 60 seconds to run, it might be faster to show the low-fidelity output immediately rather
+          # than waiting another 60 seconds for higher-fidelity output.
+          #
+          # Most likely, this will be a tool-by-tool decision and need to be added as an option to
+          # the tool configuration, but that will create additional complexity/overhead when adding
+          # a new tool.
+          #
+          # So for now, we punt. And pay close attention.
+          runner.strategy = Strategies::Verbose
+          runner.run
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+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.
+        # @param runner [Runner] the instance of the runner to apply the strategy to
+        #
+        # @return [Runner::Strategies::Verbose] an instance of the relevant verbose strategy
+        def initialize(runner)
+          @runner = runner
+          @runner.command.verbosity = Reviewer::Command::Verbosity::NO_SILENCE
+        end
+
+        # The prepare command strategy when running a command verbosely
+        #
+        # @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 verbosely
+        #
+        # @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.
+          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

data/lib/reviewer/shell.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+require_relative 'shell/result'
+require_relative 'shell/timer'
+
+module Reviewer
+  # Handles running, timing, and capturing results for a command
+  class Shell
+    extend Forwardable
+
+    attr_reader :timer, :result
+
+    def_delegators :@result, :exit_status
+
+    # Initializes a Reviewer shell for running and benchmarking commands, and capturing output
+    #
+    # @return [Shell] a shell instance for running and benchmarking commands
+    def initialize
+      @timer = Timer.new
+      @result = Result.new
+    end
+
+    # Run a command without capturing the output. This ensures the results are displayed the same as
+    # if the command was run directly in the shell. So it keeps any color or other formatting that
+    # would be stripped out by capturing $stdout as a basic string.
+    # @param command [String] the command to run
+    #
+    # @return [Integer] exit status vaue of 0 when successful or 1 when unsuccessful
+    def direct(command)
+      result.exit_status = print_results(command) ? 0 : 1
+    end
+
+    def capture_prep(command)
+      timer.record_prep { capture_results(command) }
+    end
+
+    def capture_main(command)
+      timer.record_main { capture_results(command) }
+    end
+
+    private
+
+    def capture_results(command)
+      command = String(command)
+
+      captured_results = Open3.capture3(command)
+      @result = Result.new(*captured_results)
+    end
+
+    def print_results(command)
+      command = String(command)
+
+      system(command)
+    end
+  end
+end

data/lib/reviewer/shell/result.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Shell
+    # Provides a structure interface for the results of running a command
+    class Result
+      EXIT_STATUS_CODES = {
+        success: 0,
+        cannot_execute: 126,
+        executable_not_found: 127,
+        terminated: 130
+      }.freeze
+
+      # Not all command line tools use the 127 exit status when an executable cannot be found, so
+      # this provides a home for recognizeable strings in those tools' error messages that we can
+      # translate to the appropriate exit status for internal consistency
+      STD_ERROR_STRINGS = {
+        executable_not_found: "can't find executable"
+      }.freeze
+
+      attr_accessor :stdout, :stderr, :exit_status
+
+      # An instance of a result from running a local command
+      # @param stdout = nil [String] standard out output from a command
+      # @param stderr = nil [String] standard error output from a command
+      # @param status = nil [ProcessStatus] an instance of ProcessStatus for a command
+      #
+      # @return [Shell::Result] result from running a command-line command
+      def initialize(stdout = nil, stderr = nil, status = nil)
+        @stdout = stdout
+        @stderr = stderr
+        @exit_status = status&.exitstatus
+      end
+
+      # Determines whether re-running a command is entirely futile. Primarily to help when a command
+      # fails within a batch and needs to be re-run to show the output
+      #
+      # @return [Boolean] true if the exit status code is greater than or equal to 126
+      def total_failure?
+        exit_status >= EXIT_STATUS_CODES[:cannot_execute]
+      end
+
+      # Determines whether a command simply cannot be executed.
+      #
+      # @return [Boolean] true if the exit sttaus code equals 126
+      def cannot_execute?
+        exit_status == EXIT_STATUS_CODES[:cannot_execute]
+      end
+
+      # Determines whether the command failed because the executable cannot be found. Since this is
+      # an error that can be corrected fairly predictably and easily, it provides the ability to
+      # tailor the error guidance to help folks recover
+      #
+      # @return [Boolean] true if the exit sttaus code is 127 or there's a recognizable equivalent
+      #   value in the standard error string
+      def executable_not_found?
+        exit_status == EXIT_STATUS_CODES[:executable_not_found] ||
+          stderr&.include?(STD_ERROR_STRINGS[:executable_not_found])
+      end
+
+      # Returns a string representation of the result
+      #
+      # @return [String] stdout if present, otherwise stderr
+      def to_s
+        stderr.strip.empty? ? stdout : stderr
+      end
+    end
+  end
+end

data/lib/reviewer/shell/timer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Reviewer
+  class Shell
+    # Provides a structured interface for measuring realtime main while running comamnds
+    class Timer
+      attr_accessor :prep, :main
+
+      def initialize(prep: nil, main: nil)
+        @prep = prep
+        @main = main
+      end
+
+      def record_prep(&block)
+        @prep = record(&block)
+      end
+
+      def record_main(&block)
+        @main = record(&block)
+      end
+
+      def prep_seconds
+        prep.round(2)
+      end
+
+      def main_seconds
+        main.round(2)
+      end
+
+      def total_seconds
+        total.round(2)
+      end
+
+      def prep_percent
+        return nil unless prepped?
+
+        (prep / total.to_f * 100).round
+      end
+
+      def total
+        [prep, main].compact.sum
+      end
+
+      def prepped?
+        !(prep.nil? || main.nil?)
+      end
+
+      private
+
+      def record(&block)
+        Benchmark.realtime(&block)
+      end
+    end
+  end
+end

data/lib/reviewer/tool.rb

@@ -1,67 +1,136 @@
 # frozen_string_literal: true
 
-require_relative 'tool/command'
-require_relative 'tool/env'
-require_relative 'tool/flags'
 require_relative 'tool/settings'
-require_relative 'tool/verbosity'
 
 module Reviewer
-  # Provides an instance of a specific tool
+  # Provides an instance of a specific tool for accessing its settings and run history
   class Tool
-    attr_reader :settings
-
-    delegate :name,
-             :description,
-             :tags,
-             :key,
-             :enabled?,
-             :disabled?,
-             :max_exit_status,
-             :prepare_command?,
-             :install_command?,
-             :format_command?,
-             :install_link?,
-             to: :settings
-
-    def initialize(tool)
-      @settings = Settings.new(tool)
+    extend Forwardable
+    include Comparable
+
+    # In general, Reviewer tries to save time where it can. In the case of the "prepare" command
+    # used by some tools to retrieve data, it only runs it occasionally in order to save time.
+    # This is the default window that it uses to determine if the tool's preparation step should be
+    # considered stale and needs to be rerun. Frequent enough that it shouldn't get stale, but
+    # infrequent enough that it's not cumbersome.
+    SIX_HOURS_IN_SECONDS = 60 * 60 * 6
+
+    attr_reader :settings, :history
+
+    def_delegators :@settings,
+                   :key,
+                   :name,
+                   :hash,
+                   :description,
+                   :tags,
+                   :commands,
+                   :links,
+                   :enabled?,
+                   :disabled?,
+                   :max_exit_status
+
+    alias to_sym key
+    alias to_s name
+
+    # Create an instance of a tool
+    # @param tool_key [Symbol] the key to the tool from the configuration file
+    #
+    # @return [Tool] an instance of tool for accessing settings information and facts about the tool
+    def initialize(tool_key)
+      @settings = Settings.new(tool_key)
     end
 
-    def to_s
-      name
+    # For determining if the tool should run it's prepration command. It will only be run both if
+    # the tool has a preparation command, and the command hasn't been run 6 hours
+    #
+    # @return [Boolean] true if the tool has a configured `prepare` command that hasn't been run in
+    #   the last 6 hours
+    def prepare?
+      preparable? && stale?
     end
 
-    def to_sym
-      key
+    # Determines whether a tool has a specific command type configured
+    # @param command_type [Symbol] one of the available command types defined in Command::TYPES
+    #
+    # @return [Boolean] true if the command type is configured and not blank
+    def command?(command_type)
+      commands.key?(command_type) && !commands[command_type].nil?
     end
 
-    def ==(other)
-      settings == other.settings
+    # Determines if the tool can run a `install` command
+    #
+    # @return [Boolean] true if there is a non-blank `install` command configured
+    def installable?
+      command?(:install)
+    end
+
+    # Determines if the tool can run a `prepare` command
+    #
+    # @return [Boolean] true if there is a non-blank `prepare` command configured
+    def preparable?
+      command?(:prepare)
     end
 
-    def installation_command(verbosity_level = :no_silence)
-      command_string(:install, verbosity_level: verbosity_level)
+    # Determines if the tool can run a `review` command
+    #
+    # @return [Boolean] true if there is a non-blank `review` command configured
+    def reviewable?
+      command?(:review)
     end
 
-    def preparation_command(verbosity_level = :total_silence)
-      command_string(:prepare, verbosity_level: verbosity_level)
+    # Determines if the tool can run a `format` command
+    #
+    # @return [Boolean] true if there is a non-blank `format` command configured
+    def formattable?
+      command?(:format)
     end
 
-    def review_command(verbosity_level = :total_silence, seed: nil)
-      command_string(:review, verbosity_level: verbosity_level).gsub('$SEED', seed.to_s)
+    # Specifies when the tool last had it's `prepare` command run
+    #
+    # @return [DateTime] timestamp of when the `prepare` command was last run
+    def last_prepared_at
+      Reviewer.history.get(key, :last_prepared_at)
     end
 
-    def format_command(verbosity_level = :no_silence)
-      command_string(:format, verbosity_level: verbosity_level)
+    # Sets the timestamp for when the tool last ran its `prepare` command
+    # @param last_prepared_at [DateTime] the value to record for when the `prepare` command last ran
+    #
+    # @return [DateTime] timestamp of when the `prepare` command was last run
+    def last_prepared_at=(last_prepared_at)
+      Reviewer.history.set(key, :last_prepared_at, last_prepared_at)
     end
 
-    private
+    # Determines whether the `prepare` command was run recently enough
+    #
+    # @return [Boolean] true if a prepare command exists, a timestamp exists, and it was run more
+    #   than six hours ago
+    def stale?
+      return false unless preparable?
+
+      last_prepared_at.nil? || last_prepared_at < Time.now - SIX_HOURS_IN_SECONDS
+    end
 
-    def command_string(command_type, verbosity_level: :no_silence)
-      cmd = Command.new(command_type, tool_settings: settings, verbosity_level: verbosity_level)
+    # Convenience method for determining if a tool has a configured install link
+    #
+    # @return [Boolean] true if there is an `install` key under links and the value isn't blank
+    def install_link?
+      links.key?(:install) && !links[:install].nil?
+    end
 
-      cmd.to_s
+    # Returns the text for the install link if available
+    #
+    # @return [String, nil] the link if it exists, nil otherwise
+    def install_link
+      install_link? ? links.fetch(:install) : nil
+    end
+
+    # Determines if two tools are equal
+    # @param other [Tool] the tool to compare to the current instance
+    #
+    # @return [Boolean] true if the settings match
+    def eql?(other)
+      settings == other.settings
     end
+    alias :== eql?
   end
 end