reviewer 0.1.5 → 1.0.0

data/lib/reviewer/output.rb

@@ -2,121 +2,80 @@
 
 require 'io/console/size' # For determining console width/height
 
+require_relative 'output/formatting'
 require_relative 'output/printer'
-require_relative 'output/scrubber'
-require_relative 'output/token'
 
 module Reviewer
-  # Friendly API for printing nicely-formatted output to the console
+  # Console display infrastructure — primitives for styled terminal output.
+  # Domain-specific display logic lives in each concept's Formatter class.
   class Output
     DEFAULT_CONSOLE_WIDTH = 120
-    DIVIDER = '·'
+    DIVIDER = '─'
+    RAKE_ABORTED_TEXT = "rake aborted!\n"
+
+    # Removes unhelpful rake exit status noise from stderr
+    # @param text [String, nil] the stderr output to clean up
+    # @return [String] the cleaned text with rake noise removed
+    def self.scrub(text)
+      text = text.to_s
+      return '' if text.empty?
+
+      text.include?(RAKE_ABORTED_TEXT) ? text.split(RAKE_ABORTED_TEXT).first : text
+    end
 
     attr_reader :printer
 
     # Creates an instance of Output to print Reviewer activity and results to the console
+    # @param printer [Printer] the low-level printer for styled terminal output
+    #
+    # @return [Output]
     def initialize(printer = Printer.new)
       @printer = printer
     end
 
+    # === Primitives ===
+
+    # Clears the terminal screen (no-op when output is not a TTY)
+    # @return [void]
     def clear
-      system('clear')
+      system('clear') if printer.tty?
     end
 
-    def newline
-      printer.puts(:default, '')
-    end
+    # Prints a blank line
+    # @return [void]
+    def newline = printer.puts(:default, '')
 
+    # Prints a horizontal rule spanning the console width
+    # @return [void]
     def divider
       newline
       printer.print(:muted, DIVIDER * console_width)
     end
 
-    # Prints plain text to the console
-    # @param message [String] the text to write to the console
-    #
+    # Prints an unformatted help message
+    # @param message [String] the help text to display
     # @return [void]
     def help(message)
       printer.puts(:default, message)
     end
 
-    # Prints a summary of the total time and results for a batch run. If multiple tools, it will
-    #  show the total tool count
-    # @param tool_count [Integer] the number of commands run in the batch
-    # @param seconds [Float] the total number of seconds the batch ran in realtime
-    #
+    # Writes raw output directly without formatting
+    # @param value [String] the raw output to write
     # @return [void]
-    def batch_summary(tool_count, seconds)
-      printer.print(:bold, "~#{seconds.round(1)} seconds")
-      printer.puts(:muted, " for #{tool_count} tools") if tool_count > 1
-    end
-
-    # Print a tool summary using the name and description. Used before running a command to help
-    #   identify which tool is running at any given moment.
-    # @param tool [Tool] the tool to identify and describe
-    #
-    # @return [void]
-    def tool_summary(tool)
-      printer.print(:bold, tool.name)
-      printer.puts(:muted, " #{tool.description}")
-    end
-
-    # Prints the text of a command to the console to help proactively expose potentials issues with
-    #   syntax if Reviewer translated thte provided options in an unexpected way
-    # @param command [String, Command] the command to identify on the console
-    #
-    # @return [void] [description]
-    def current_command(command)
-      printer.puts(:bold, 'Now Running:')
-      printer.puts(:default, String(command))
-    end
-
-    def success(timer)
-      printer.print(:success, 'Success')
-      printer.print(:success_light, " #{timer.total_seconds}s")
-      printer.print(:warning_light, " (#{timer.prep_percent}% prep ~#{timer.prep_seconds}s)") if timer.prepped?
-      newline
-      newline
-    end
-
-    def failure(details, command: nil)
-      printer.print(:failure, 'Failure')
-      printer.puts(:muted, " #{details}")
-
-      return if command.nil?
-
-      newline
-      printer.puts(:bold, 'Failed Command:')
-      printer.puts(:muted, String(command))
-    end
-
-    def unrecoverable(details)
-      printer.puts(:error, 'Unrecoverable Error:')
-      printer.puts(:muted, details)
-    end
-
-    def guidance(summary, details)
-      return if details.nil?
-
-      newline
-      printer.puts(:bold, summary)
-      printer.puts(:muted, details)
-    end
-
     def unfiltered(value)
-      return if value.nil? || value.strip.empty?
-
-      printer.stream << value
+      printer.write_raw(value)
     end
 
-    protected
+    private
 
+    # Returns the current console width, falling back to a default
+    # @return [Integer] the console width in columns
     def console_width
       return DEFAULT_CONSOLE_WIDTH if IO.console.nil?
 
       _height, width = IO.console.winsize
 
-      width
+      width.positive? ? width : DEFAULT_CONSOLE_WIDTH
     end
   end
 end

data/lib/reviewer/prompt.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Reviewer
+  # Simple interactive prompt for yes/no questions.
+  # Wraps input/output streams for testability.
+  class Prompt
+    attr_reader :input, :output
+
+    # Creates an interactive prompt for yes/no questions
+    # @param input [IO] the input stream (defaults to $stdin)
+    # @param output [IO] the output stream (defaults to $stdout)
+    #
+    # @return [Prompt]
+    def initialize(input: $stdin, output: $stdout)
+      @input = input
+      @output = output
+    end
+
+    # Asks a yes/no question and returns the boolean result.
+    # Returns false in non-interactive contexts (CI, pipes).
+    #
+    # @param message [String] the question to display
+    # @return [Boolean] true if the user answered yes
+    def yes?(message)
+      return false unless interactive?
+
+      @output.print "#{message} (y/n) "
+      response = @input.gets&.strip&.downcase
+      response&.start_with?('y') || false
+    end
+
+    private
+
+    def interactive?
+      @input.respond_to?(:tty?) && @input.tty?
+    end
+  end
+end

data/lib/reviewer/report/formatter.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Report
+    # Formats a Report for summary output to the console
+    class Formatter
+      include Output::Formatting
+
+      attr_reader :report, :output
+
+      # Creates a formatter for displaying a report
+      # @param report [Report] the report to format
+      # @param output [Output] the output handler for console display
+      #
+      # @return [Formatter] a formatter instance
+      def initialize(report, output: Output.new)
+        @report = report
+        @output = output
+        @name_width = 0
+      end
+
+      # Prints the formatted report to the console
+      #
+      # @return [void]
+      def print
+        if report.results.empty?
+          output.printer.puts(:muted, 'No tools to run')
+          return
+        end
+
+        print_tool_lines
+        output.newline
+        print_summary
+      end
+
+      private
+
+      def print_tool_lines
+        @name_width = max_name_width
+        report.results.each { |result| print_tool_line(result) }
+      end
+
+      def print_tool_line(result)
+        if result.missing?
+          print_missing_tool(result)
+        else
+          print_executed_tool(result)
+        end
+
+        output.newline
+      end
+
+      def print_missing_tool(result)
+        output.printer.print(:warning, "- #{result.tool_name.ljust(@name_width)}")
+        output.printer.print(:muted, '    not installed')
+      end
+
+      def print_executed_tool(result)
+        style = status_style(result.success?)
+        mark = status_mark(result.success?)
+        output.printer.print(style, "#{mark} #{result.tool_name.ljust(@name_width)}")
+        print_timing(result)
+        print_details(result)
+      end
+
+      def print_timing(result)
+        output.printer.print(:muted, "    #{format_duration(result.duration).rjust(6)}")
+      end
+
+      def max_name_width
+        report.results.map { |result| result.tool_name.length }.max || 0
+      end
+
+      def print_details(result)
+        detail = result.detail_summary
+        return unless detail
+
+        output.printer.print(:muted, "   #{detail}")
+      end
+
+      def print_summary
+        if report.success?
+          print_success_summary
+        else
+          print_failure_summary
+        end
+      end
+
+      def print_success_summary
+        output.printer.print(:success, 'All passed')
+        output.printer.puts(:muted, " (#{format_duration(report.duration)})")
+      end
+
+      def print_failure_summary
+        failed_results = report.results.reject(&:success?).reject(&:missing?)
+
+        failed_results.each do |result|
+          output.newline
+          output.printer.puts(:failure, "#{result.tool_name}:")
+          print_truncated_output(result.stdout)
+        end
+      end
+
+      def print_truncated_output(text)
+        content = text.to_s.strip
+        return if content.empty?
+
+        lines = content.lines
+        print_lines(lines.first(10))
+        print_truncation_notice(lines.size - 10)
+      end
+
+      def print_lines(lines)
+        lines.each { |line| output.printer.puts(:default, line.chomp) }
+      end
+
+      def print_truncation_notice(remaining)
+        return unless remaining.positive?
+
+        output.printer.puts(:muted, "[#{remaining} more lines]")
+      end
+    end
+  end
+end

data/lib/reviewer/report.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'report/formatter'
+
+module Reviewer
+  # Collects results from multiple tool runs and provides serialization
+  class Report
+    attr_reader :results, :duration
+
+    def initialize
+      @results = []
+      @duration = nil
+    end
+
+    # Adds a Runner::Result to the collection
+    #
+    # @param result [Runner::Result] the result to add
+    # @return [Array<Runner::Result>] the updated results array
+    def add(result)
+      @results << result
+    end
+
+    # Records the total duration for all tool runs
+    #
+    # @param seconds [Float] the total elapsed time in seconds
+    # @return [Float] the recorded duration
+    def record_duration(seconds)
+      @duration = seconds
+    end
+
+    # Whether all executed tools in the report succeeded (excludes missing and skipped)
+    #
+    # @return [Boolean] true if all executed results are successful
+    def success?
+      executed_results.all?(&:success?)
+    end
+
+    # Returns the highest exit status from executed results (excludes missing and skipped)
+    #
+    # @return [Integer] the maximum exit status, or 0 if empty
+    def max_exit_status
+      executed_results.map(&:exit_status).max || 0
+    end
+
+    # Returns results for tools whose executables were not found
+    #
+    # @return [Array<Runner::Result>] missing tool results
+    def missing_results
+      results.select(&:missing?)
+    end
+
+    # Whether any tools were missing
+    #
+    # @return [Boolean] true if any results are missing
+    def missing?
+      missing_results.any?
+    end
+
+    # Returns data for missing tools (name and key)
+    #
+    # @return [Array<Runner::Result>] the missing results with tool info
+    def missing_tools
+      missing_results
+    end
+
+    # Converts the report to a hash suitable for serialization
+    #
+    # @return [Hash] structured hash with summary and tool results
+    def to_h
+      {
+        success: success?,
+        summary: {
+          total: results.size,
+          passed: results.count(&:success?),
+          failed: results.count { |result| !result.success? && !result.missing? },
+          missing: missing_results.size,
+          duration: duration
+        },
+        tools: results.map(&:to_h)
+      }
+    end
+
+    # Converts the report to formatted JSON
+    #
+    # @return [String] JSON representation of the report
+    def to_json(*_args)
+      JSON.pretty_generate(to_h)
+    end
+
+    private
+
+    # Results for tools that actually executed (excludes skipped and missing)
+    #
+    # @return [Array<Runner::Result>] executed results only
+    def executed_results
+      results.select(&:executed?)
+    end
+  end
+end

data/lib/reviewer/runner/failed_files.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Runner
+    # Extracts file paths from tool output so that subsequent re-runs can be scoped
+    # to only the files that had issues.
+    #
+    # Merges stdout and stderr before scanning because linters (rubocop, reek, etc.)
+    # write findings to stdout, not stderr. No common tool splits output with
+    # "passing files" on stdout and "failing files" on stderr, so merging is safe.
+    # The regex pattern and File.exist? guard filter out any incidental matches.
+    class FailedFiles
+      # Matches relative path-like tokens at or near the start of a line, allowing
+      # leading whitespace for tools that indent output (reek groupings, rspec nesting).
+      # Rejects absolute paths (starting with /) to exclude Ruby runtime warnings and
+      # gem internals that would otherwise match. Tool findings always use relative
+      # paths from the project root. Supports any file extension so non-Ruby tools
+      # (eslint, stylelint) also work. File.exist? in to_a provides a final guard.
+      #
+      #   lib/foo.rb:45:3: C: Style/... (rubocop)
+      #   test/foo_test.rb:45 (minitest)
+      #   lib/foo.rb -- message (reek)
+      #   src/app.js:10:5: error ... (eslint)
+      FILE_PATH_PATTERN = %r{^\s*([^/\s]\S*\.\w+)(?::\d| -- )}
+
+      attr_reader :stdout, :stderr
+
+      # Creates a failed-file extractor from captured tool output
+      # @param stdout [String, nil] captured standard output from the tool
+      # @param stderr [String, nil] captured standard error from the tool
+      #
+      # @return [FailedFiles]
+      def initialize(stdout, stderr)
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      # Regex-matched paths filtered to only those that exist on disk, deduplicated.
+      # @return [Array<String>] unique file paths that exist in the working directory
+      def to_a
+        matched_paths.select { |path| File.exist?(path) }.uniq
+      end
+
+      # All regex-matched paths before filesystem filtering. Useful for testing
+      # pattern matching without requiring real files on disk.
+      # @return [Array<String>] raw paths extracted from combined output
+      def matched_paths
+        combined_output.scan(FILE_PATH_PATTERN).flatten
+      end
+
+      private
+
+      # Merges both streams and strips ANSI escape codes before scanning. Linters
+      # write diagnostic output (file paths with line numbers) to stdout, while
+      # stderr typically only contains crash or startup errors. Scanning both catches
+      # paths regardless of which stream the tool uses. ANSI codes are stripped via
+      # Rainbow::StringUtils.uncolor because tools run with --color embed escape
+      # sequences around file paths, which would otherwise become part of the
+      # captured path string.
+      # @return [String] merged stdout and stderr, stripped of ANSI codes
+      def combined_output
+        Rainbow::StringUtils.uncolor([stdout, stderr].compact.join("\n"))
+      end
+    end
+  end
+end

data/lib/reviewer/runner/formatter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative '../output/formatting'
+
+module Reviewer
+  class Runner
+    # Display logic for tool execution: tool identity, success, failure, skipped, guidance
+    class Formatter
+      include Output::Formatting
+
+      attr_reader :output, :printer
+      private :output, :printer
+
+      # Creates a formatter for runner-specific display
+      # @param output [Output] the console output handler
+      #
+      # @return [Formatter]
+      def initialize(output)
+        @output = output
+        @printer = output.printer
+      end
+
+      # Prints the tool name and description as a header before execution
+      # @param tool [Tool] the tool being run
+      #
+      # @return [void]
+      def tool_summary(tool)
+        printer.print(:bold, tool.name)
+        printer.puts(:muted, " #{tool.description}")
+      end
+
+      # Displays the exact command string being executed for debugging and copy/paste
+      # @param command [Command, String] the command to display
+      #
+      # @return [void]
+      def current_command(command)
+        printer.print(:default, ' ↳ ')
+        printer.puts(:muted, String(command))
+        output.newline
+      end
+
+      # Displays a success message with timing breakdown
+      # @param timer [Shell::Timer] the timer with prep and main execution times
+      #
+      # @return [void]
+      def success(timer)
+        printer.print(:success, 'Success')
+        printer.print(:success_light, " #{timer.total_seconds}s")
+        printer.print(:warning_light, " (#{timer.prep_percent}% prep ~#{timer.prep_seconds}s)") if timer.prepped?
+        output.newline
+        output.newline
+      end
+
+      # Displays a skip notice with the reason
+      # @param reason [String] why the tool was skipped
+      #
+      # @return [void]
+      def skipped(reason = 'no matching files')
+        printer.print(:muted, 'Skipped')
+        printer.puts(:muted, " (#{reason})")
+        output.newline
+      end
+
+      # Displays a failure message with details and optionally the failed command
+      # @param details [String] the failure summary (e.g. exit status)
+      # @param command [Command, String, nil] the command that failed, if applicable
+      #
+      # @return [void]
+      def failure(details, command: nil)
+        printer.print(:failure, 'Failure')
+        printer.puts(:muted, " #{details}")
+
+        return unless command
+
+        output.newline
+        printer.puts(:bold, 'Failed Command:')
+        printer.puts(:muted, String(command))
+      end
+
+      # Displays an unrecoverable error that prevents further execution
+      # @param details [String] the error description
+      #
+      # @return [void]
+      def unrecoverable(details)
+        printer.puts(:error, 'Unrecoverable Error:')
+        printer.puts(:muted, details)
+      end
+
+      # Displays contextual guidance after a failure to help the user recover
+      # @param summary [String] the guidance heading
+      # @param details [String, nil] the guidance body (skipped if nil)
+      #
+      # @return [void]
+      def guidance(summary, details)
+        return unless details
+
+        output.newline
+        printer.puts(:bold, summary)
+        printer.puts(:muted, details)
+      end
+    end
+  end
+end

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