reviewer 0.1.4 → 1.0.0

data/lib/reviewer/runner/guidance.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Runner
+    # Handles the logic around what to display after a command has been run
+    class Guidance
+      attr_reader :command, :result, :formatter, :context
+      private :context
+
+      # Create an instance of guidance for suggesting recovery steps after errors
+      # @param command [Command] the command that was run and needs recovery guidance
+      # @param result [Result] the result of the command
+      # @param context [Context] the shared runtime dependencies
+      #
+      # @return [Guidance] the guidance class to suggest relevant recovery steps
+      def initialize(command:, result:, context:)
+        @command = command
+        @result = result
+        @context = context
+        @formatter = Runner::Formatter.new(context.output)
+      end
+
+      # Prints the relevant guidance based on the command and result context
+      #
+      # @return [void] prints the relevant guidance to the stream
+      def show
+        case result
+        when executable_not_found? then show_missing_executable_guidance
+        when cannot_execute?       then show_unrecoverable_guidance
+        else                            show_syntax_guidance
+        end
+      end
+
+      private
+
+      # Conditional check for when the command result was that the executable couldn't be found
+      #
+      # @return [Boolean] true if the result indicates the command couldn't be found
+      def executable_not_found?
+        lambda(&:executable_not_found?)
+      end
+
+      # Conditional check for when the command result was that it was unable to be executed
+      #
+      # @return [Boolean] true if the result indicates the command couldn't be executed
+      def cannot_execute?
+        lambda(&:cannot_execute?)
+      end
+
+      # Shows the recovery guidance for when a command is missing
+      #
+      # @return [void] prints missing executable guidance
+      def show_missing_executable_guidance
+        tool = command.tool
+        installation_command = Command.new(tool, :install, context: context).string if tool.installable?
+        install_link = tool.install_link
+
+        formatter.failure("Missing executable for '#{tool}'", command: command)
+        formatter.guidance('Try installing the tool:', installation_command)
+        formatter.guidance('Read the installation guidance:', install_link)
+      end
+
+      # Shows the recovery guidance for when a command generates an unrecoverable error
+      #
+      # @return [void] prints unrecoverable error guidance
+      def show_unrecoverable_guidance
+        formatter.unrecoverable(result.stderr)
+      end
+
+      # Shows suggestions for ignoring or disable rules when a command fails after reviewing code
+      #
+      # @return [void] prints syntax guidance
+      def show_syntax_guidance
+        formatter.guidance('Selectively Ignore a Rule:', command.tool.links[:ignore_syntax])
+        formatter.guidance('Fully Disable a Rule:', command.tool.links[:disable_syntax])
+      end
+    end
+  end
+end

data/lib/reviewer/runner/result.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Runner
+    # Immutable value object representing the result of running a single tool
+    #
+    # @!attribute [r] tool_key
+    #   @return [Symbol] the unique identifier for the tool
+    # @!attribute [r] tool_name
+    #   @return [String] the human-readable name of the tool
+    # @!attribute [r] command_type
+    #   @return [Symbol] the type of command run (:review, :format, etc.)
+    # @!attribute [r] command_string
+    #   @return [String] the full command string that was executed
+    # @!attribute [r] success
+    #   @return [Boolean] whether the command completed successfully
+    # @!attribute [r] exit_status
+    #   @return [Integer] the exit status code from the command
+    # @!attribute [r] duration
+    #   @return [Float] the execution time in seconds
+    # @!attribute [r] stdout
+    #   @return [String, nil] the standard output from the command
+    # @!attribute [r] stderr
+    #   @return [String, nil] the standard error from the command
+    # @!attribute [r] skipped
+    #   @return [Boolean] whether the tool was skipped
+    # @!attribute [r] missing
+    #   @return [Boolean] whether the tool's executable was not found
+    Result = Struct.new(
+      :tool_key,
+      :tool_name,
+      :command_type,
+      :command_string,
+      :success,
+      :exit_status,
+      :duration,
+      :stdout,
+      :stderr,
+      :skipped,
+      :missing,
+      :summary_pattern,
+      :summary_label,
+      keyword_init: true
+    ) do
+      # Freeze on initialization to maintain immutability like Data.define
+      def initialize(...)
+        super
+        freeze
+      end
+
+      # Builds an immutable Result from a runner's current state.
+      # @param runner [Runner] the runner after command execution
+      #
+      # @return [Result] an immutable result for reporting
+      def self.from_runner(runner)
+        if runner.skipped?
+          build_skipped(runner)
+        elsif runner.missing?
+          build_missing(runner)
+        else
+          build_executed(runner)
+        end
+      end
+
+      def self.base_attributes(runner)
+        tool = runner.tool
+        {
+          tool_key: tool.key,
+          tool_name: tool.name,
+          command_type: runner.command.type,
+          command_string: runner.command.string
+        }
+      end
+
+      def self.build_skipped(runner)
+        new(
+          **base_attributes(runner),
+          command_string: nil,
+          success: true, exit_status: 0, duration: 0,
+          stdout: nil, stderr: nil, skipped: true
+        )
+      end
+
+      def self.build_missing(runner)
+        new(
+          **base_attributes(runner),
+          success: false, exit_status: runner.shell.result.exit_status, duration: 0,
+          stdout: nil, stderr: nil, skipped: nil, missing: true
+        )
+      end
+
+      def self.build_executed(runner)
+        shell = runner.shell
+        shell_result = shell.result
+        settings = runner.tool.settings
+        new(
+          **base_attributes(runner),
+          success: runner.success?, exit_status: shell_result.exit_status,
+          duration: shell.timer.total_seconds,
+          stdout: shell_result.stdout, stderr: shell_result.stderr, skipped: nil,
+          summary_pattern: settings.summary_pattern,
+          summary_label: settings.summary_label
+        )
+      end
+
+      private_class_method :base_attributes, :build_skipped, :build_missing, :build_executed
+
+      alias_method :success?, :success
+      alias_method :skipped?, :skipped
+      alias_method :missing?, :missing
+
+      # Whether this result represents a tool that actually ran (not skipped or missing)
+      #
+      # @return [Boolean] true if the tool was executed
+      def executed? = !skipped? && !missing?
+
+      # Extracts a short summary detail from stdout for display purposes.
+      # Each tool type may have its own summary format (test count, offense count, etc.)
+      #
+      # @return [String, nil] a brief summary or nil if no detail can be extracted
+      def detail_summary
+        return nil unless summary_pattern
+
+        match = stdout&.match(/#{summary_pattern}/i)
+        return nil unless match
+
+        summary_label.gsub(/\\(\d+)/) { match[Regexp.last_match(1).to_i] }
+      end
+
+      # Converts the result to a hash suitable for serialization
+      #
+      # @return [Hash] hash representation with nil values removed
+      def to_h
+        {
+          tool: tool_key,
+          name: tool_name,
+          command_type: command_type,
+          command: command_string,
+          success: success,
+          exit_status: exit_status,
+          duration: duration,
+          stdout: stdout,
+          stderr: stderr,
+          skipped: skipped,
+          missing: missing
+        }.compact # Excludes summary_pattern/summary_label (config, not results)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'ruby-progressbar'
+
+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
+        # 256-color ANSI codes for progress bar styling (not in AnsiStyles' 16-color palette)
+        PROGRESS_GRAY      = "\e[38;5;245m"
+        PROGRESS_DARK_GRAY = "\e[38;5;240m"
+        ANSI_RESET         = "\e[0m"
+        ERASE_LINE         = "\r\e[2K"
+
+        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) }
+
+          # Erase the prep progress bar — the run step will show its own
+          stream.print(ERASE_LINE) if style_enabled? && runner.streaming?
+
+          # 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) }
+
+          # Skip output for non-streaming modes - results are formatted at the end
+          return unless runner.streaming?
+
+          # Missing tools are handled by the Runner (shows "Skipped (not installed)")
+          return if runner.shell.result.executable_not_found?
+
+          # 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)
+          average_time = runner.tool.average_time(command)
+          start_time = Time.now
+          thread = Thread.new { yield }
+
+          # Skip progress output for non-streaming modes
+          return thread.join unless runner.streaming?
+
+          print_progress(thread, start_time, average_time)
+        end
+
+        def print_progress(thread, start_time, average_time)
+          bar = create_progress_bar(average_time)
+
+          while thread.alive?
+            update_progress(bar, start_time, average_time)
+            sleep 0.1
+          end
+
+          thread.join
+
+          # Erase the progress bar line if the executable wasn't found
+          if runner.shell.result.executable_not_found?
+            stream.print(ERASE_LINE) if style_enabled?
+            return
+          end
+
+          finish_progress_bar(bar, average_time.positive?)
+        end
+
+        def finish_progress_bar(bar, timed)
+          if timed
+            bar.format = style_enabled? ? "#{PROGRESS_GRAY}%b#{PROGRESS_DARK_GRAY}%i %p%%#{ANSI_RESET}" : '%b%i %p%%'
+            bar.finish
+          else
+            bar.stop
+          end
+        end
+
+        def create_progress_bar(average_time)
+          shared = {
+            output: stream,
+            title: '',
+            progress_mark: "\u2501",
+            remainder_mark: "\u2500"
+          }
+
+          if average_time.positive?
+            eta = average_time >= 3 ? ' %e' : ''
+            format = style_enabled? ? "#{PROGRESS_GRAY}%b#{PROGRESS_DARK_GRAY}%i %p%%#{eta}#{ANSI_RESET}" : "%b%i %p%%#{eta}"
+            ProgressBar.create(**shared, total: 100, format: format)
+          else
+            format = style_enabled? ? "#{PROGRESS_GRAY}%B#{ANSI_RESET}" : '%B'
+            ProgressBar.create(**shared, total: nil, format: format)
+          end
+        end
+
+        def update_progress(bar, start_time, average_time)
+          if average_time.positive?
+            elapsed = Time.now - start_time
+            percent = [(elapsed / average_time * 100).round, 99].min
+            bar.progress = percent if percent > bar.progress
+          else
+            bar.increment
+          end
+        end
+
+        # The output stream from the runner's printer
+        # @return [IO]
+        def stream = runner.output.printer.stream
+
+        # Whether ANSI styling is enabled on the output stream
+        # @return [Boolean]
+        def style_enabled? = runner.output.printer.style_enabled?
+
+        # 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.to_s.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.formatter.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.formatter.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
+          stdout = runner.stdout.to_s
+          return if stdout.empty?
+
+          runner.output.divider
+          runner.output.newline
+          runner.output.unfiltered(stdout)
+        end
+
+        # If there's a useful stderr value, display it with a divider to visually separate it.
+        #
+        # @return [void]
+        def show_captured_stderr
+          stderr = runner.stderr.to_s
+          return if stderr.empty?
+
+          scrubbed_stderr = Output.scrub(stderr)
+
+          runner.output.divider
+          runner.output.newline
+          runner.formatter.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
@@ -28,34 +30,23 @@ module Reviewer
           # 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
+          runner.formatter.current_command(runner.prepare_command)
 
           # 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
+        # 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.
-          runner.output.current_command(runner.command)
-
-          # Add a divider to visually delineate the results
-          runner.output.divider
+          runner.formatter.current_command(runner.command)
 
           # 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