reviewer 0.1.1 → 0.1.5

data/lib/reviewer/runner.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative 'runner/strategies/captured'
+require_relative 'runner/strategies/passthrough'
+
+module Reviewer
+  # Wrapper for executng a command and printing the results
+  class Runner
+    extend Forwardable
+
+    attr_accessor :strategy
+
+    attr_reader :command, :shell, :output
+
+    def_delegators :@command, :tool
+    def_delegators :@shell, :result, :timer
+    def_delegators :result, :exit_status, :stdout, :stderr, :rerunnable?
+
+    # 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
+      @output = output
+    end
+
+    def run
+      # Show which tool is running
+      identify_tool
+
+      # Use the provided strategy to run the command
+      execute_strategy
+
+      # 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
+
+    def success?
+      # Some review tools return a range of non-zero exit statuses and almost never return 0.
+      # (`yarn audit` is a good example.) Those tools can be configured to accept a non-zero exit
+      # status so they aren't constantly considered to be failing over minor issues.
+      #
+      # But when other command types (prepare, install, format) are run, they either succeed or they
+      # fail. With no shades of gray in those cases, anything other than a 0 is a failure.
+      if command.type == :review
+        exit_status <= tool.max_exit_status
+      else
+        exit_status.zero?
+      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)
+    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
+  end
+end

data/lib/reviewer/shell/result.rb

@@ -0,0 +1,84 @@
+# 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, :status, :exit_status
+
+      # An instance of a result from running a local command. Captures the values for `$stdout`,
+      #   `$stderr`, and the exit status of the command to provide a reliable way of interpreting
+      #   the results for commands that otherwise use these values inconsistently.
+      # @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
+      #
+      # @example Using with `Open3.capture3`
+      #   captured_results = Open3.capture3(command)
+      #   result = Result.new(*captured_results)
+      #
+      # @return [self]
+      def initialize(stdout = nil, stderr = nil, status = nil)
+        @stdout = stdout
+        @stderr = stderr
+        @status = status
+        @exit_status = status&.exitstatus
+      end
+
+      def exists?
+        [stdout, stderr, exit_status].compact.any?
+      end
+
+      # Determines if 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 rerunnable?
+        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
+        result_string = ''
+        result_string += stderr
+        result_string += stdout
+
+        result_string.strip
+      end
+    end
+  end
+end

data/lib/reviewer/shell/timer.rb

@@ -0,0 +1,72 @@
+# 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
+
+      # A 'Smart' timer that understands preparation time and main time and can easily do the math
+      #   to help determine what percentage of time was prep. The times can be passed in directly or
+      #   recorded using the `record_prep` and `record_main` methods
+      # @param prep: nil [Float] the amount of time in seconds the preparation command ran
+      # @param main: nil [Float] the amount of time in seconds the primary command ran
+      #
+      # @return [self]
+      def initialize(prep: nil, main: nil)
+        @prep = prep
+        @main = main
+      end
+
+      # Records the execution time for the block and assigns it to the `prep` time
+      # @param &block [Block] the commands to be timed
+      #
+      # @return [Float] the execution time for the preparation
+      def record_prep(&block)
+        @prep = record(&block)
+      end
+
+      # Records the execution time for the block and assigns it to the `main` time
+      # @param &block [Block] the commands to be timed
+      #
+      # @return [Float] the execution time for the main command
+      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/shell.rb

@@ -0,0 +1,54 @@
+# 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, :captured_results
+
+    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 realtime
+    # 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)
+      command = String(command)
+
+      result.exit_status = system(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
+  end
+end

data/lib/reviewer/tool/settings.rb

@@ -1,36 +1,43 @@
 # frozen_string_literal: true
 
-# Converts/casts tool configuration values and provides default values if not set
 module Reviewer
   class Tool
+    # Converts/casts tool configuration values and provides appropriate default values if not set.
     class Settings
-      class MissingReviewCommandError < StandardError; end
-
-      attr_reader :tool, :config
+      attr_reader :tool_key, :config
+
+      alias key tool_key
+
+      # Creates an instance of settings for retrieving values from the configuration file.
+      # @param tool_key [Symbol] the unique identifier for the tool in the config file
+      # @param config: nil [Hash] the configuration values to examine for the settings
+      #
+      # @return [self]
+      def initialize(tool_key, config: nil)
+        @tool_key = tool_key.to_sym
+        @config = config || load_config
+      end
 
-      def initialize(tool, config: nil)
-        @tool = tool
-        @config = config || Reviewer.configuration.tools.fetch(tool.to_sym) { {} }
+      def hash
+        state.hash
+      end
 
-        # Ideally, folks would fill out everything, 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, "'#{name}' does not have a 'review' key under 'commands' in your tools configuration" unless commands.key?(:review)
+      def eql?(other)
+        self.class == other.class &&
+          state == other.state
       end
+      alias :== eql?
 
       def disabled?
-        config.fetch(:disabled) { false }
+        config.fetch(:disabled, false)
       end
 
       def enabled?
         !disabled?
       end
 
-      def key
-        tool.to_sym
-      end
-
       def name
-        config.fetch(:name) { tool.to_s.titleize }
+        config.fetch(:name) { tool_key.to_s.capitalize }
       end
 
       def description
@@ -53,16 +60,28 @@ module Reviewer
         config.fetch(:flags) { {} }
       end
 
+      # The collection of configured commands for the tool
+      #
+      # @return [Hash] all of the commands configured for the tool
       def commands
         config.fetch(:commands) { {} }
       end
 
+      # The largest exit status that can still be considered a success for the command
+      #
+      # @return [Integer] the configured `max_exit_status` for the tool or 0 if one isn't configured
       def max_exit_status
-        commands.fetch(:max_exit_status) { 0 }
+        commands.fetch(:max_exit_status, 0)
+      end
+
+      protected
+
+      def state
+        config.to_hash
       end
 
-      def quiet_flag
-        commands.fetch(:quiet_flag) { '' }
+      def load_config
+        Reviewer.tools.to_h.fetch(key) { {} }
       end
     end
   end

data/lib/reviewer/tool.rb

@@ -1,44 +1,158 @@
 # frozen_string_literal: true
 
-require "active_support/core_ext/string"
-require_relative "tool/command"
-require_relative "tool/env"
-require_relative "tool/flags"
-require_relative "tool/settings"
-require_relative "tool/verbosity"
-
-# Provides an instance of a specific tool
+require 'date'
+
+require_relative 'tool/settings'
+
 module Reviewer
+  # Provides an instance of a specific tool for accessing its settings and run history
   class Tool
-    attr_reader :settings
+    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
+
+    # 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
+
+    # 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
+
+    # 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
 
-    def initialize(tool)
-      @settings = Settings.new(tool)
+    # 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 = :no_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)
-      command_string(:review, verbosity_level: verbosity_level)
+    # Specifies when the tool last had it's `prepare` command run
+    #
+    # @return [Time] timestamp of when the `prepare` command was last run
+    def last_prepared_at
+      date_string = Reviewer.history.get(key, :last_prepared_at)
+
+      date_string == '' || date_string.nil? ? nil : DateTime.parse(date_string).to_time
+    end
+
+    # 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.to_s)
+    end
+
+    def average_time(command)
+      times = get_timing(command)
+
+      times.any? ? times.sum / times.size : 0
+    end
+
+    def get_timing(command)
+      Reviewer.history.get(key, command.raw_string) || []
     end
 
-    def format_command(verbosity_level = :no_silence)
-      command_string(:format, verbosity_level: verbosity_level)
+    def record_timing(command, time)
+      return if time.nil?
+
+      timing = get_timing(command).take(4) << time.round(2)
+
+      Reviewer.history.set(key, command.raw_string, timing)
     end
 
+    # 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?
 
-    private
+      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
+
+    # 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
 
-      cmd.to_s
+    # 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