reviewer 0.1.4 → 1.0.0

data/lib/reviewer/runner.rb

@@ -1,73 +1,217 @@
 # frozen_string_literal: true
 
-require_relative 'runner/strategies/quiet'
-require_relative 'runner/strategies/verbose'
+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'
 
 module Reviewer
   # Wrapper for executng a command and printing the results
   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
+    def_delegators :result, :exit_status, :stdout, :stderr, :rerunnable?
 
-    def initialize(tool, command_type, strategy = Strategies::Quiet, output: Reviewer.output)
-      @command = Command.new(tool, command_type)
+    # 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 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 [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, 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
-      # Show which tool is about to run
-      output.tool_summary(tool)
+      # 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
+
+      # 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?
+      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.
+    # Only displays in streaming mode; non-streaming strategies handle their own output.
+    #
+    # @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?
+
+      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.
+    #
+    # @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
 
-      # If it failed,
-      guidance.show unless success?
+    # 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?
 
-      exit_status
-    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, context: @context)
 
-    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
+    # 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 = 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
+    #   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
 
-    def run_prepare_step?
-      command.type != :prepare && tool.prepare?
+    # 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 ||= 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
 
-    def prepare_command
-      @prepare_command ||= Command.new(tool, :prepare, command.verbosity)
+    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
 
-    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
+    # 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
 
-    def guidance
-      @guidance ||= Reviewer::Guidance.new(command: command, result: result, output: output)
+    # 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

data/lib/reviewer/session/formatter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative '../output/formatting'
+
+module Reviewer
+  class Session
+    # Display logic for lifecycle warnings: unrecognized keywords, no matching tools, etc.
+    class Formatter
+      include Output::Formatting
+
+      attr_reader :output, :printer
+      private :output, :printer
+
+      # Creates a formatter for session lifecycle warnings
+      # @param output [Output] the console output handler
+      #
+      # @return [Formatter]
+      def initialize(output)
+        @output = output
+        @printer = output.printer
+      end
+
+      # Displays warnings for keywords that don't match any tool or git scope
+      # @param unrecognized [Array<String>] the unrecognized keyword strings
+      # @param suggestions [Hash{String => String}] keyword => suggested correction
+      #
+      # @return [void]
+      def unrecognized_keywords(unrecognized, suggestions)
+        unrecognized.each do |keyword|
+          printer.puts(:warning, "Unrecognized: #{keyword}")
+          suggestion = suggestions[keyword]
+          printer.puts(:muted, "  did you mean '#{suggestion}'?") if suggestion
+        end
+        output.newline
+      end
+
+      # Displays a warning when an unrecognized output format is requested
+      # @param value [String] the invalid format name
+      # @param known [Array<Symbol>] the valid format options
+      #
+      # @return [void]
+      def invalid_format(value, known)
+        printer.puts(:warning, "Unknown format '#{value}', using 'streaming'")
+        printer.puts(:muted, "Valid formats: #{known.join(', ')}")
+        output.newline
+      end
+
+      # Displays a git-related error with context-appropriate messaging
+      # @param message [String] the error message from the git command
+      #
+      # @return [void]
+      def git_error(message)
+        if message.include?('not a git repository')
+          printer.puts(:warning, 'Not a git repository')
+          printer.puts(:muted, 'Git keywords (staged, modified, etc.) require a git repository')
+        else
+          printer.puts(:warning, 'Git command failed')
+          printer.puts(:muted, message)
+          printer.puts(:muted, 'Continuing without file filtering')
+        end
+      end
+
+      # Displays a message when file-scoping keywords resolved to no files
+      # @param keywords [Array<String>] the file keywords that were requested (e.g. ['staged'])
+      #
+      # @return [void]
+      def no_reviewable_files(keywords:)
+        output.newline
+        printer.puts(:muted, "No reviewable #{keywords.join(', ')} files found")
+        output.newline
+      end
+
+      # Displays a warning when no configured tools match the requested names or tags
+      # @param requested [Array<String>] tool names or tags the user asked for
+      # @param available [Array<String>] all configured tool keys
+      #
+      # @return [void]
+      def no_matching_tools(requested:, available:)
+        output.newline
+        printer.puts(:warning, 'No matching tools found')
+        printer.puts(:muted, "Requested: #{requested.join(', ')}") if requested.any?
+        printer.puts(:muted, "Available: #{available.join(', ')}") if available.any?
+        output.newline
+      end
+    end
+  end
+end

data/lib/reviewer/session.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative 'session/formatter'
+
+module Reviewer
+  # Run lifecycle with full dependency injection.
+  # Owns the review/format lifecycle that was previously in Reviewer module methods.
+  class Session
+    attr_reader :context, :tools
+    private :context, :tools
+
+    # Creates a session with all dependencies injected
+    # @param context [Context] the shared runtime dependencies (arguments, output, history)
+    # @param tools [Tools] the collection of configured tools
+    #
+    # @return [Session]
+    def initialize(context:, tools:)
+      @context = context
+      @tools = tools
+      context.arguments.keywords.tools = tools
+    end
+
+    # Runs the review command for the current set of tools
+    #
+    # @return [Integer] the maximum exit status from all tools
+    def review
+      run_tools(:review)
+    end
+
+    # Runs the format command for the current set of tools
+    #
+    # @return [Integer] the maximum exit status from all tools
+    def format
+      run_tools(:format)
+    end
+
+    private
+
+    def arguments = context.arguments
+    def output = context.output
+    def history = context.history
+
+    def run_tools(command_type)
+      if json_output?
+        run_json(command_type)
+      else
+        run_text(command_type)
+      end
+    end
+
+    def run_json(command_type)
+      message = json_early_exit_message
+      return emit_json_early_exit(message) if message
+
+      current_tools = tools.current
+      return 0 if current_tools.empty?
+
+      strategy = runner_strategy(current_tools)
+      report = Batch.new(command_type, current_tools, strategy: strategy, context: context).run
+      puts report.to_json
+      report.max_exit_status
+    end
+
+    def run_text(command_type)
+      return 0 if handle_failed_with_nothing_to_run?
+      return 0 if handle_file_scoping_with_no_files?
+
+      warn_unrecognized_keywords
+
+      current_tools = tools.current
+      return warn_no_matching_tools if current_tools.empty?
+
+      show_run_summary(current_tools, command_type)
+
+      strategy = runner_strategy(current_tools)
+      report = Batch.new(command_type, current_tools, strategy: strategy, context: context).run
+      display_text_report(report)
+      show_missing_tools(report, current_tools)
+
+      report.max_exit_status
+    end
+
+    def warn_no_matching_tools
+      formatter.no_matching_tools(
+        requested: arguments.keywords.provided + arguments.tags.to_a,
+        available: tools.all.map { |tool| tool.key.to_s }
+      )
+      0
+    end
+
+    def json_output?
+      arguments.format == :json
+    end
+
+    def json_early_exit_message
+      if failed_with_nothing_to_run?
+        'No failures to retry'
+      elsif file_scoping_with_no_files?
+        "No reviewable #{arguments.files.keywords.join(', ')} files found"
+      end
+    end
+
+    def emit_json_early_exit(message)
+      puts JSON.pretty_generate(
+        success: true,
+        message: message,
+        summary: { total: 0, passed: 0, failed: 0, missing: 0, duration: 0 },
+        tools: []
+      )
+      0
+    end
+
+    def warn_unrecognized_keywords
+      unrecognized = arguments.keywords.unrecognized
+      return if unrecognized.empty?
+
+      suggestions = build_suggestions(unrecognized)
+      formatter.unrecognized_keywords(unrecognized, suggestions)
+    end
+
+    def build_suggestions(unrecognized)
+      possible = arguments.keywords.possible
+      checker = DidYouMean::SpellChecker.new(dictionary: possible)
+
+      unrecognized.each_with_object({}) do |keyword, map|
+        corrections = checker.correct(keyword)
+        map[keyword] = corrections.first if corrections.any?
+      end
+    end
+
+    # Returns true if failed keyword is present with nothing to re-run (caller should return early)
+    def handle_failed_with_nothing_to_run?
+      return false unless failed_with_nothing_to_run?
+
+      display_failed_empty_message
+      true
+    end
+
+    def failed_with_nothing_to_run?
+      keywords = arguments.keywords
+      keywords.failed? &&
+        tools.failed_from_history.empty? &&
+        keywords.for_tool_names.empty? &&
+        keywords.for_tags.empty? &&
+        arguments.tags.to_a.empty?
+    end
+
+    # Returns true if file keywords were provided but resolved to no files (caller should return early)
+    def handle_file_scoping_with_no_files?
+      return false unless file_scoping_with_no_files?
+
+      formatter.no_reviewable_files(keywords: arguments.files.keywords)
+      true
+    end
+
+    def file_scoping_with_no_files?
+      arguments.files.keywords.any? && arguments.files.to_a.empty?
+    end
+
+    def display_failed_empty_message
+      if tools.all.any? { |tool| history.get(tool.key, :last_status) }
+        batch_formatter.no_failures_to_retry
+      else
+        batch_formatter.no_previous_run
+      end
+    end
+
+    def display_text_report(report)
+      if arguments.format == :summary
+        Report::Formatter.new(report, output: output).print
+      elsif report.success?
+        ran_count = report.results.count { |result| !result.missing? && !result.skipped? }
+        batch_formatter.summary(ran_count, report.duration)
+      end
+    end
+
+    def show_missing_tools(report, current_tools)
+      return unless report.missing?
+
+      batch_formatter.missing_tools(report.missing_tools, tools: current_tools)
+    end
+
+    def show_run_summary(current_tools, command_type)
+      return unless arguments.keywords.provided.any?
+
+      entries = build_run_summary(current_tools, command_type)
+      return if entries.size <= 1 && entries.none? { |entry| entry[:files].any? }
+
+      batch_formatter.run_summary(entries)
+    end
+
+    def build_run_summary(current_tools, command_type)
+      current_tools.filter_map do |tool|
+        Command.new(tool, command_type, context: context).run_summary
+      end
+    end
+
+    def runner_strategy(current_tools)
+      arguments.runner_strategy(multiple_tools: current_tools.size > 1)
+    end
+
+    def formatter = @formatter ||= Session::Formatter.new(output)
+
+    def batch_formatter
+      Batch::Formatter.new(output)
+    end
+  end
+end