reviewer 0.1.4 → 1.0.0

data/lib/reviewer/shell/result.rb

@@ -18,34 +18,48 @@ module Reviewer
         executable_not_found: "can't find executable"
       }.freeze
 
-      attr_accessor :stdout, :stderr, :exit_status
+      # @!attribute stdout
+      #   @return [String, nil] standard output from the command
+      # @!attribute stderr
+      #   @return [String, nil] standard error from the command
+      # @!attribute status
+      #   @return [Process::Status, nil] the process status object
+      # @!attribute exit_status
+      #   @return [Integer, nil] the exit status code from the command
+      attr_reader :stdout, :stderr, :status
+      attr_accessor :exit_status
 
-      # An instance of a result from running a local command
+      # 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
       #
-      # @return [Shell::Result] result from running a command-line 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
 
-      # Determines whether re-running a command is entirely futile. Primarily to help when a command
+      def exists? = [stdout, stderr, exit_status].compact.any?
+
+      # 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 total_failure?
-        exit_status >= EXIT_STATUS_CODES[:cannot_execute]
-      end
+      def rerunnable? = exit_status < EXIT_STATUS_CODES[:cannot_execute]
 
       # 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
+      def cannot_execute? = exit_status == EXIT_STATUS_CODES[:cannot_execute]
 
       # 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
@@ -62,7 +76,7 @@ module Reviewer
       #
       # @return [String] stdout if present, otherwise stderr
       def to_s
-        stderr.strip.empty? ? stdout : stderr
+        [stderr, stdout].compact.join("\n").strip
       end
     end
   end

data/lib/reviewer/shell/timer.rb

@@ -6,52 +6,72 @@ module Reviewer
   class Shell
     # Provides a structured interface for measuring realtime main while running comamnds
     class Timer
-      attr_accessor :prep, :main
+      # @!attribute prep
+      #   @return [Float, nil] the preparation time in seconds
+      # @!attribute main
+      #   @return [Float, nil] the main execution time in seconds
+      attr_reader :prep, :main
 
+      # A timer that tracks preparation and main execution times separately.
+      # Times can be passed directly or recorded using `record_prep` and `record_main`.
+      # @param prep [Float, nil] the preparation time in seconds
+      # @param main [Float, nil] the main execution time in seconds
+      #
+      # @return [Timer]
       def initialize(prep: nil, main: nil)
         @prep = prep
         @main = main
       end
 
-      def record_prep(&block)
-        @prep = record(&block)
-      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(&) = @prep = record(&)
 
-      def record_main(&block)
-        @main = 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(&) = @main = record(&)
 
-      def prep_seconds
-        prep.round(2)
-      end
+      # The preparation time rounded to two decimal places
+      #
+      # @return [Float] prep time in seconds
+      def prep_seconds = prep.round(2)
 
-      def main_seconds
-        main.round(2)
-      end
+      # The main execution time rounded to two decimal places
+      #
+      # @return [Float] main time in seconds
+      def main_seconds = main.round(2)
 
-      def total_seconds
-        total.round(2)
-      end
+      # The total execution time (prep + main) rounded to two decimal places
+      #
+      # @return [Float] total time in seconds
+      def total_seconds = total.round(2)
+
+      # The total time (prep + main) without rounding
+      #
+      # @return [Float] total time in seconds
+      def total = [prep, main].compact.sum
 
+      # Whether both prep and main times have been recorded
+      #
+      # @return [Boolean] true if both phases were timed
+      def prepped? = [prep, main].all?
+
+      # The percentage of total time spent on preparation
+      #
+      # @return [Integer, nil] percentage (0-100) or nil if not prepped
       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
+      def record(&) = Benchmark.realtime(&)
     end
   end
 end

data/lib/reviewer/shell.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'open3'
+require 'pty'
 
 require_relative 'shell/result'
 require_relative 'shell/timer'
@@ -10,49 +11,73 @@ module Reviewer
   class Shell
     extend Forwardable
 
-    attr_reader :timer, :result
+    attr_reader :timer, :result, :captured_results
 
     def_delegators :@result, :exit_status
 
     # Initializes a Reviewer shell for running and benchmarking commands, and capturing output
+    # @param stream [IO] the output stream for direct (passthrough) output
     #
     # @return [Shell] a shell instance for running and benchmarking commands
-    def initialize
+    def initialize(stream: $stdout)
+      @stream = stream
       @timer = Timer.new
       @result = Result.new
+      @captured_results = nil
     end
 
-    # Run a command without capturing the output. This ensures the results are displayed the same as
-    # 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.
+    # Run a command via PTY, streaming output in real-time while capturing it for later use
+    # (e.g. failed file extraction). PTY allocates a pseudo-terminal so the child process
+    # preserves ANSI colors and interactive behavior.
     # @param command [String] the command to run
     #
-    # @return [Integer] exit status vaue of 0 when successful or 1 when unsuccessful
+    # @return [Result] the captured result including stdout and exit status
     def direct(command)
-      result.exit_status = print_results(command) ? 0 : 1
-    end
+      command = String(command)
+      buffer = +''
 
-    def capture_prep(command)
-      timer.record_prep { capture_results(command) }
-    end
+      reader, _writer, pid = PTY.spawn(command)
+      begin
+        reader.each_line do |line|
+          @stream.print line
+          buffer << line
+        end
+      rescue Errno::EIO
+        # Expected when child process exits before all output is read
+      end
 
-    def capture_main(command)
-      timer.record_main { capture_results(command) }
+      _, status = Process.waitpid2(pid)
+      @result = Result.new(buffer, nil, status)
+    rescue Errno::ENOENT
+      @result = Result.new(buffer, nil, nil)
+      @result.exit_status = Result::EXIT_STATUS_CODES[:executable_not_found]
     end
 
-    private
+    # Captures and times the preparation command execution
+    # @param command [String, Command] the command to run
+    #
+    # @return [Result] the captured result including stdout, stderr, and exit status
+    def capture_prep(command) = timer.record_prep { capture_results(command) }
 
-    def capture_results(command)
-      command = String(command)
+    # Captures and times the main command execution
+    # @param command [String, Command] the command to run
+    #
+    # @return [Result] the captured result including stdout, stderr, and exit status
+    def capture_main(command) = timer.record_main { capture_results(command) }
 
-      captured_results = Open3.capture3(command)
-      @result = Result.new(*captured_results)
-    end
+    private
 
-    def print_results(command)
+    # Open3.capture3 returns stdout, stderr, and status separately. Keeping them
+    # separate matters for FailedFiles, which merges the streams intentionally
+    # when scanning for file paths after a failure.
+    def capture_results(command)
       command = String(command)
 
-      system(command)
+      @captured_results = Open3.capture3(command)
+      @result = Result.new(*@captured_results)
+    rescue Errno::ENOENT
+      @result = Result.new(nil, nil, nil)
+      @result.exit_status = Result::EXIT_STATUS_CODES[:executable_not_found]
     end
   end
 end

data/lib/reviewer/tool/conversions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Tool
+    # Conversion functions for coercing values to Tool instances
+    module Conversions
+      # Coerces a value into a Tool instance
+      # @param value [Tool] the value to convert
+      # @return [Tool] the resulting Tool instance
+      # @raise [TypeError] if the value is not a Tool
+      def Tool(value) # rubocop:disable Naming/MethodName
+        case value
+        in Tool then value
+        else raise TypeError, "Cannot convert #{value.class} to Tool"
+        end
+      end
+      module_function :Tool
+    end
+  end
+end

data/lib/reviewer/tool/file_resolver.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Tool
+    # Resolves which files a tool should process by mapping and filtering.
+    class FileResolver
+      # Creates a FileResolver for a tool's settings
+      # @param settings [Tool::Settings] the tool's settings containing file configuration
+      #
+      # @return [FileResolver] a resolver instance for the tool
+      def initialize(settings)
+        @settings = settings
+      end
+
+      # Resolves input files by mapping source files to test files (if configured) and
+      # filtering by the tool's file pattern
+      # @param files [Array<String>] the input files to resolve
+      #
+      # @return [Array<String>] files after mapping and filtering
+      def resolve(files)
+        return files unless pattern
+
+        filter(map(files))
+      end
+
+      # Determines if the tool should be skipped because files were requested but none match
+      # @param files [Array<String>] the requested files
+      #
+      # @return [Boolean] true if files were requested but none remain after resolution
+      def skip?(files)
+        files.any? && resolve(files).empty?
+      end
+
+      private
+
+      attr_reader :settings
+
+      def map(files)
+        mapper = settings.map_to_tests
+        return files unless mapper
+
+        TestFileMapper.new(mapper).map(files)
+      end
+
+      def filter(files)
+        files.select { |file| File.fnmatch(pattern, File.basename(file)) }
+      end
+
+      def pattern
+        settings.files_pattern
+      end
+    end
+  end
+end

data/lib/reviewer/tool/settings.rb

@@ -2,80 +2,131 @@
 
 module Reviewer
   class Tool
-    # Converts/casts tool configuration values and provides default values if not set.
+    # Converts/casts tool configuration values and provides appropriate default values if not set.
     class Settings
       attr_reader :tool_key, :config
 
       alias key tool_key
 
-      def initialize(tool_key, config: nil)
+      # 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 [Hash] the configuration values to examine for the settings
+      #
+      # @return [Settings]
+      def initialize(tool_key, config:)
         @tool_key = tool_key.to_sym
-        @config = config || load_config
+        @config = config
       end
 
-      def hash
-        state.hash
-      end
+      # Returns a hash code for comparing settings instances
+      #
+      # @return [Integer] hash code based on configuration state
+      def hash = state.hash
 
+      # Compares two settings instances for equality based on their configuration
+      # @param other [Settings] the settings to compare against
+      # @return [Boolean] true if both have the same configuration
       def eql?(other)
         self.class == other.class &&
           state == other.state
       end
       alias :== eql?
 
-      def disabled?
-        config.fetch(:disabled, false)
-      end
-
-      def enabled?
-        !disabled?
-      end
-
-      def name
-        config.fetch(:name) { tool_key.to_s.capitalize }
-      end
-
-      def description
-        config.fetch(:description) { "(No description provided for '#{name}')" }
-      end
-
-      def tags
-        config.fetch(:tags) { [] }
-      end
-
-      def links
-        config.fetch(:links) { {} }
-      end
-
-      def env
-        config.fetch(:env) { {} }
-      end
-
-      def flags
-        config.fetch(:flags) { {} }
-      end
-
-      def commands
-        config.fetch(:commands) { {} }
-      end
-
-      def max_exit_status
-        commands.fetch(:max_exit_status, 0)
-      end
-
-      def quiet_option
-        commands.fetch(:quiet_option, '')
-      end
+      def skip_in_batch?
+        if config.key?(:skip_in_batch)
+          config.fetch(:skip_in_batch) { false }
+        else
+          config.fetch(:disabled) { false }
+        end
+      end
+
+      def disabled? = skip_in_batch?
+      def enabled? = !skip_in_batch?
+
+      # The human-readable name of the tool
+      #
+      # @return [String] the configured name or capitalized tool key
+      def name = config.fetch(:name) { tool_key.to_s.capitalize }
+
+      # The human-readable description of what the tool does
+      #
+      # @return [String] the configured description or a default placeholder
+      def description = config.fetch(:description) { "(No description provided for '#{name}')" }
+
+      # The tags used to categorize and filter the tool
+      #
+      # @return [Array<String>] configured tags or empty array
+      def tags = config.fetch(:tags) { [] }
+
+      # The collection of reference links for the tool (home, install, usage, etc.)
+      #
+      # @return [Hash] configured links or empty hash if none
+      def links = config.fetch(:links) { {} }
+
+      # The environment variables to set when running the tool
+      #
+      # @return [Hash] configured env vars or empty hash
+      def env = config.fetch(:env) { {} }
+
+      # The CLI flags to pass to the tool's review command
+      #
+      # @return [Hash] configured flags or empty hash
+      def flags = config.fetch(:flags) { {} }
+
+      # The CLI flag used to pass files to the tool (e.g., '--files')
+      #
+      # @return [String] the configured flag or empty string if files are passed directly
+      def files_flag = config.dig(:files, :flag) || ''
+
+      # The separator used to join multiple file paths in the command
+      #
+      # @return [String] the configured separator or a space by default
+      def files_separator = config.dig(:files, :separator) || ' '
+
+      # The glob pattern used to filter which files this tool should process
+      #
+      # @return [String, nil] the pattern (e.g., '*.rb') or nil if not configured
+      def files_pattern = config.dig(:files, :pattern)
+
+      # The test framework to use for mapping source files to test files
+      #
+      # @return [String, nil] the framework name ('minitest' or 'rspec') or nil if not configured
+      def map_to_tests = config.dig(:files, :map_to_tests)
+
+      def supports_files? = config.key?(:files)
+
+      # The regex pattern for extracting a summary detail from tool output
+      #
+      # @return [String, nil] the configured pattern or nil
+      def summary_pattern = config.dig(:summary, :pattern)
+
+      # The label template for displaying the extracted summary detail
+      #
+      # @return [String, nil] the configured label or nil
+      def summary_label = config.dig(:summary, :label)
+
+      # Returns the file-scoped command override for a given command type.
+      # When configured, this command replaces the standard command when files are passed.
+      #
+      # @param command_type [Symbol] the command type (:review, :format)
+      # @return [String, nil] the file-scoped command or nil if not configured
+      def files_command(command_type) = config.dig(:files, command_type)
+
+      # The collection of configured commands for the tool
+      #
+      # @return [Hash] all of the commands configured for the tool
+      def commands = config.fetch(:commands) { {} }
+
+      # 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 }
 
       protected
 
-      def state
-        config.to_hash
-      end
-
-      def load_config
-        Reviewer.tools.to_h.fetch(key) { {} }
-      end
+      # Returns the configuration as a plain hash for comparison
+      # @return [Hash] the configuration state
+      def state = config.to_hash
     end
   end
 end

data/lib/reviewer/tool/test_file_mapper.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Tool
+    # Maps source files to their corresponding test files based on framework conventions.
+    class TestFileMapper
+      FRAMEWORKS = {
+        minitest: { dir: 'test', suffix: '_test.rb', source_dirs: %w[app lib] },
+        rspec: { dir: 'spec', suffix: '_spec.rb', source_dirs: %w[app lib] }
+      }.freeze
+
+      # Creates a mapper for the specified test framework
+      # @param framework [Symbol, String, nil] the test framework (:minitest or :rspec)
+      #
+      # @return [TestFileMapper] a mapper instance for the framework
+      def initialize(framework)
+        @framework = framework&.to_sym
+      end
+
+      # Maps source files to their corresponding test files
+      # @param files [Array<String>] source files to map
+      #
+      # @return [Array<String>] mapped test files (only those that exist on disk)
+      def map(files)
+        return files unless supported?
+
+        files.map { |file| map_file(file) }.compact.uniq
+      end
+
+      # Checks if the framework is supported for mapping
+      #
+      # @return [Boolean] true if the framework is :minitest or :rspec
+      def supported?
+        @framework && FRAMEWORKS.key?(@framework)
+      end
+
+      private
+
+      def map_file(file)
+        return file if test_file?(file)
+
+        mapped = source_to_test(file)
+        mapped && File.exist?(mapped) ? mapped : nil
+      end
+
+      def test_file?(file)
+        file.end_with?(config[:suffix])
+      end
+
+      def source_to_test(file)
+        return nil unless file.end_with?('.rb')
+
+        replace_source_dir_with_test_dir(file).sub(/\.rb$/, config[:suffix])
+      end
+
+      def replace_source_dir_with_test_dir(path)
+        config[:source_dirs].each do |dir|
+          return path.sub(%r{^#{dir}/}, "#{config[:dir]}/") if path.start_with?("#{dir}/")
+        end
+        prepend_test_dir(path)
+      end
+
+      def prepend_test_dir(path)
+        dir = config[:dir]
+        path.start_with?(dir) ? path : "#{dir}/#{path}"
+      end
+
+      def config
+        FRAMEWORKS[@framework]
+      end
+    end
+  end
+end