reviewer 0.1.5 → 1.0.0

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'ruby-progressbar'
+
 module Reviewer
   class Runner
     module Strategies
@@ -8,6 +10,12 @@ module Reviewer
       # @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
@@ -28,6 +36,9 @@ module Reviewer
 
           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
@@ -40,6 +51,12 @@ module Reviewer
 
           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
@@ -51,36 +68,92 @@ module Reviewer
         #   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
+        # @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
+        def display_progress(command)
           average_time = runner.tool.average_time(command)
+          start_time = Time.now
+          thread = Thread.new { yield }
 
-          thread = Thread.new { block.call }
+          # 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?
-            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
+            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.nil? || value.strip.empty? }.any?
+          [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
@@ -88,7 +161,7 @@ module Reviewer
         # @return [void]
         def show_timing_result
           runner.record_timing
-          runner.output.success(runner.timer)
+          runner.formatter.success(runner.timer)
         end
 
         # Prints "Failure" and the resulting exit status. Shows the precise command that led to the
@@ -101,7 +174,7 @@ module Reviewer
           runner.output.clear
 
           # Show the exit status and failed command
-          runner.output.failure("Exit Status #{runner.exit_status}", command: runner.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
@@ -118,25 +191,27 @@ module Reviewer
         # 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?
+        def show_captured_stdout
+          stdout = runner.stdout.to_s
+          return if stdout.empty?
 
           runner.output.divider
           runner.output.newline
-          runner.output.unfiltered(runner.stdout)
+          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 # rubocop:disable Metrics/AbcSize
-          return if runner.stderr.nil? || runner.stderr.empty?
+        def show_captured_stderr
+          stderr = runner.stderr.to_s
+          return if stderr.empty?
 
-          scrubbed_stderr = Reviewer::Output::Scrubber.new(runner.stderr).clean
+          scrubbed_stderr = Output.scrub(stderr)
 
           runner.output.divider
           runner.output.newline
-          runner.output.guidance('Runtime Errors:', scrubbed_stderr)
+          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

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

@@ -30,10 +30,7 @@ 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)
@@ -46,16 +43,10 @@ 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.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

data/lib/reviewer/runner.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'runner/failed_files'
+require_relative 'runner/formatter'
+require_relative 'runner/guidance'
+require_relative 'runner/result'
 require_relative 'runner/strategies/captured'
 require_relative 'runner/strategies/passthrough'
 
@@ -8,60 +12,106 @@ module Reviewer
   class Runner
     extend Forwardable
 
+    # @!attribute strategy
+    #   @return [Class] the strategy class for running the command (Captured or Passthrough)
     attr_accessor :strategy
 
-    attr_reader :command, :shell, :output
+    attr_reader :command, :shell
 
     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
+    # Creates a wrapper for running commands 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.
+    #   generous way so that non-zero exit statuses can still potentially 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
+    # @param strategy [Runner::Strategies] how to execute and handle the results of the command
+    # @param context [Context] the shared runtime dependencies (arguments, output, history)
     #
     # @return [self]
-    def initialize(tool, command_type, strategy = Strategies::Captured, output: Reviewer.output)
-      @command = Command.new(tool, command_type)
+    def initialize(tool, command_type, strategy = Strategies::Captured, context:)
+      @command = Command.new(tool, command_type, context: context)
       @strategy = strategy
-      @shell = Shell.new
-      @output = output
+      @shell = Shell.new(stream: context.output.printer.stream)
+      @context = context
+      @skipped = false
+      @missing = false
     end
 
+    # The output channel for displaying content, delegated from context.
+    #
+    # @return [Output]
+    def output = @context.output
+
+    # Display formatter for runner-specific output (tool summary, success, failure, etc.)
+    # Computed rather than stored to avoid exceeding instance variable threshold.
+    #
+    # @return [Runner::Formatter]
+    def formatter = @formatter ||= Runner::Formatter.new(output)
+
+    # Whether this runner is operating in streaming mode
+    #
+    # @return [Boolean] true if output should be streamed
+    def streaming? = @context.arguments.streaming?
+
+    # Executes the command and returns the exit status
+    #
+    # @return [Integer] the exit status from the command
     def run
+      # Skip if files were requested but none match this tool's pattern
+      if command.skip?
+        @skipped = true
+        show_skipped
+        return 0
+      end
+
       # 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
+      # Handle the result based on whether the tool was found
+      result.executable_not_found? ? handle_missing : handle_result
     end
 
+    # Whether this runner was skipped due to no matching files
+    #
+    # @return [Boolean] true if the tool was skipped
+    def skipped? = @skipped == true
+
+    # Whether this runner's executable was not found (exit status 127)
+    #
+    # @return [Boolean] true if the tool was missing
+    def missing? = @missing == true
+
+    # 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.
+    #
+    # Skipped tools are always considered successful.
     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
+      return true if skipped?
+
+      command.type == :review ? exit_status <= tool.max_exit_status : exit_status.zero?
+    end
+
+    def failure? = !success?
+
+    # Extracts file paths from stdout/stderr for failed-file tracking
+    #
+    # @return [Array<String>] file paths found in the command output
+    def failed_files
+      FailedFiles.new(stdout, stderr).to_a
     end
 
-    # Prints the tool name and description to the console as a frame of reference
+    # Prints the tool name and description to the console as a frame of reference.
+    # Only displays in streaming mode; non-streaming strategies handle their own output.
     #
     # @return [void]
     def identify_tool
@@ -69,7 +119,18 @@ module Reviewer
       # be redundant.
       return if result.exists?
 
-      output.tool_summary(tool)
+      stream_output { formatter.tool_summary(tool) }
+    end
+
+    # Shows that a tool was skipped due to no matching files.
+    # Only displays in streaming mode; non-streaming modes report skips in the final summary.
+    #
+    # @return [void]
+    def show_skipped
+      stream_output do
+        formatter.tool_summary(tool)
+        formatter.skipped
+      end
     end
 
     # Runs the relevant strategy to either capture or pass through command output.
@@ -88,25 +149,18 @@ module Reviewer
     #   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
+    def run_prepare_step? = command.type != :prepare && tool.prepare?
 
     # 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
+    def prepare_command = @prepare_command ||= Command.new(tool, :prepare, context: @context)
 
     # 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
+    def update_last_prepared_at = tool.last_prepared_at = Time.now
 
     # 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
@@ -124,8 +178,40 @@ module Reviewer
     #   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)
+    def guidance = @guidance ||= Guidance.new(command: command, result: result, context: @context)
+
+    # Builds an immutable Result object from the current runner state
+    #
+    # @return [Runner::Result] the result of running this tool
+    def to_result
+      Result.from_runner(self)
+    end
+
+    private
+
+    # Yields the block only when in streaming mode.
+    # Centralizes the streaming guard so display methods don't each check independently.
+    #
+    # @return [void]
+    def stream_output
+      yield if streaming?
+    end
+
+    # Marks the tool as missing and shows a skip message
+    #
+    # @return [Integer] the exit status from the command
+    def handle_missing
+      @missing = true
+      stream_output { formatter.skipped('not installed') }
+      exit_status
+    end
+
+    # Shows failure guidance if needed and returns the exit status
+    #
+    # @return [Integer] the exit status from the command
+    def handle_result
+      stream_output { guidance.show } if failure?
+      exit_status
     end
   end
 end