reviewer 0.1.5 → 1.0.0

data/lib/reviewer/tool/settings.rb

@@ -8,81 +8,125 @@ module Reviewer
 
       alias key tool_key
 
-      # Creates an instance of settings for retrieving values from the configuration file.
+      # 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: nil [Hash] the configuration values to examine for the settings
+      # @param config [Hash] the configuration values to examine for the settings
       #
-      # @return [self]
-      def initialize(tool_key, config: nil)
+      # @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)
+      def skip_in_batch?
+        if config.key?(:skip_in_batch)
+          config.fetch(:skip_in_batch) { false }
+        else
+          config.fetch(:disabled) { false }
+        end
       end
 
-      def enabled?
-        !disabled?
-      end
+      def disabled? = skip_in_batch?
+      def enabled? = !skip_in_batch?
 
-      def name
-        config.fetch(:name) { tool_key.to_s.capitalize }
-      end
+      # 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 }
 
-      def description
-        config.fetch(:description) { "(No description provided for '#{name}')" }
-      end
+      # 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}')" }
 
-      def tags
-        config.fetch(:tags) { [] }
-      end
+      # The tags used to categorize and filter the tool
+      #
+      # @return [Array<String>] configured tags or empty array
+      def tags = config.fetch(:tags) { [] }
 
-      def links
-        config.fetch(:links) { {} }
-      end
+      # 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) { {} }
 
-      def env
-        config.fetch(:env) { {} }
-      end
+      # The environment variables to set when running the tool
+      #
+      # @return [Hash] configured env vars or empty hash
+      def env = config.fetch(:env) { {} }
 
-      def flags
-        config.fetch(:flags) { {} }
-      end
+      # 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) { {} }
-      end
+      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)
-      end
+      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

data/lib/reviewer/tool/timing.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Reviewer
+  class Tool
+    # Manages timing persistence for a tool — recording, retrieving, and averaging
+    # execution times, plus tracking when the prepare command was last run.
+    class Timing
+      SIX_HOURS_IN_SECONDS = 60 * 60 * 6
+
+      # Creates a timing tracker for a specific tool
+      # @param history [History] the persistence store for timing data
+      # @param key [Symbol] the tool's unique key
+      #
+      # @return [Timing]
+      def initialize(history, key)
+        @history = history
+        @key = key
+      end
+
+      # Specifies when the tool last had its `prepare` command run
+      #
+      # @return [Time, nil] timestamp of when the `prepare` command was last run
+      def last_prepared_at
+        date_string = @history.get(@key, :last_prepared_at).to_s
+
+        date_string.empty? ? nil : DateTime.parse(date_string).to_time
+      end
+
+      # Sets the timestamp for when the tool last ran its `prepare` command
+      # @param timestamp [DateTime, Time] the value to record
+      #
+      # @return [void]
+      def last_prepared_at=(timestamp)
+        @history.set(@key, :last_prepared_at, timestamp.to_s)
+      end
+
+      # Calculates the average execution time for a command
+      # @param command [Command] the command to get timing for
+      #
+      # @return [Float] the average time in seconds or 0 if no history
+      def average_time(command)
+        times = get_timing(command)
+
+        times.any? ? times.sum / times.size : 0
+      end
+
+      # Retrieves historical timing data for a command
+      # @param command [Command] the command to look up
+      #
+      # @return [Array<Float>] the last few recorded execution times
+      def get_timing(command)
+        @history.get(@key, command.raw_string) || []
+      end
+
+      # Records the execution time for a command to calculate running averages
+      # @param command [Command] the command that was run
+      # @param time [Float, nil] the execution time in seconds
+      #
+      # @return [void]
+      def record_timing(command, time)
+        return unless time
+
+        timing = get_timing(command).take(4) << time.round(2)
+
+        @history.set(@key, command.raw_string, timing)
+      end
+
+      # Determines whether the `prepare` command was run recently enough
+      #
+      # @return [Boolean] true if the timestamp is nil or older than six hours
+      def stale?
+        !last_prepared_at || last_prepared_at < Time.now - SIX_HOURS_IN_SECONDS
+      end
+    end
+  end
+end

data/lib/reviewer/tool.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
-require 'date'
-
+require_relative 'tool/conversions'
+require_relative 'tool/file_resolver'
 require_relative 'tool/settings'
+require_relative 'tool/test_file_mapper'
+require_relative 'tool/timing'
 
 module Reviewer
   # Provides an instance of a specific tool for accessing its settings and run history
@@ -10,14 +12,9 @@ module Reviewer
     extend Forwardable
     include Comparable
 
-    # In general, Reviewer tries to save time where it can. In the case of the "prepare" command
-    # used by some tools to retrieve data, it only runs it occasionally in order to save time.
-    # This is the default window that it uses to determine if the tool's preparation step should be
-    # considered stale and needs to be rerun. Frequent enough that it shouldn't get stale, but
-    # infrequent enough that it's not cumbersome.
-    SIX_HOURS_IN_SECONDS = 60 * 60 * 6
+    SIX_HOURS_IN_SECONDS = Timing::SIX_HOURS_IN_SECONDS
 
-    attr_reader :settings, :history
+    attr_reader :settings
 
     def_delegators :@settings,
                    :key,
@@ -29,98 +26,86 @@ module Reviewer
                    :links,
                    :enabled?,
                    :disabled?,
-                   :max_exit_status
+                   :skip_in_batch?,
+                   :max_exit_status,
+                   :supports_files?
+
+    # Returns the tool's key as a symbol
+    # @return [Symbol] the tool's unique identifier
+    def to_sym = key
 
-    alias to_sym key
-    alias to_s name
+    # Returns the tool's name as a string
+    # @return [String] the tool's display name
+    def to_s = name
 
     # Create an instance of a tool
     # @param tool_key [Symbol] the key to the tool from the configuration file
+    # @param config [Hash] the tool's configuration hash
+    # @param history [History] the history store for timing and state persistence
     #
     # @return [Tool] an instance of tool for accessing settings information and facts about the tool
-    def initialize(tool_key)
-      @settings = Settings.new(tool_key)
+    def initialize(tool_key, config:, history:)
+      @settings = Settings.new(tool_key, config: config)
+      @history = history
+      @timing = Timing.new(history, key)
     end
 
-    # For determining if the tool should run it's prepration command. It will only be run both if
-    # the tool has a preparation command, and the command hasn't been run 6 hours
+    # For determining if the tool should run its preparation command. It will only be run if
+    # the tool has a preparation command and it hasn't been run in the last 6 hours
     #
     # @return [Boolean] true if the tool has a configured `prepare` command that hasn't been run in
     #   the last 6 hours
-    def prepare?
-      preparable? && stale?
-    end
+    def prepare? = preparable? && stale?
 
     # Determines whether a tool has a specific command type configured
     # @param command_type [Symbol] one of the available command types defined in Command::TYPES
     #
     # @return [Boolean] true if the command type is configured and not blank
     def command?(command_type)
-      commands.key?(command_type) && !commands[command_type].nil?
+      commands.key?(command_type) && commands[command_type]
     end
 
     # Determines if the tool can run a `install` command
     #
     # @return [Boolean] true if there is a non-blank `install` command configured
-    def installable?
-      command?(:install)
+    def installable? = command?(:install)
+
+    # Returns the install command string for this tool
+    #
+    # @return [String, nil] the install command or nil if not configured
+    def install_command
+      commands[:install]
     end
 
     # Determines if the tool can run a `prepare` command
     #
     # @return [Boolean] true if there is a non-blank `prepare` command configured
-    def preparable?
-      command?(:prepare)
-    end
+    def preparable? = command?(:prepare)
 
     # Determines if the tool can run a `review` command
     #
     # @return [Boolean] true if there is a non-blank `review` command configured
-    def reviewable?
-      command?(:review)
-    end
+    def reviewable? = command?(:review)
 
     # Determines if the tool can run a `format` command
     #
     # @return [Boolean] true if there is a non-blank `format` command configured
-    def formattable?
-      command?(:format)
-    end
-
-    # Specifies when the tool last had it's `prepare` command run
-    #
-    # @return [Time] timestamp of when the `prepare` command was last run
-    def last_prepared_at
-      date_string = Reviewer.history.get(key, :last_prepared_at)
-
-      date_string == '' || date_string.nil? ? nil : DateTime.parse(date_string).to_time
-    end
+    def formattable? = command?(:format)
 
-    # Sets the timestamp for when the tool last ran its `prepare` command
-    # @param last_prepared_at [DateTime] the value to record for when the `prepare` command last ran
+    # Whether this tool matches any of the given tags and is eligible for batch runs
     #
-    # @return [DateTime] timestamp of when the `prepare` command was last run
-    def last_prepared_at=(last_prepared_at)
-      Reviewer.history.set(key, :last_prepared_at, last_prepared_at.to_s)
+    # @param tag_list [Array<String, Symbol>] tags to match against
+    # @return [Boolean] true if the tool is batch-eligible and shares at least one tag
+    def matches_tags?(tag_list)
+      !skip_in_batch? && tag_list.intersect?(tags)
     end
 
-    def average_time(command)
-      times = get_timing(command)
-
-      times.any? ? times.sum / times.size : 0
-    end
-
-    def get_timing(command)
-      Reviewer.history.get(key, command.raw_string) || []
-    end
-
-    def record_timing(command, time)
-      return if time.nil?
-
-      timing = get_timing(command).take(4) << time.round(2)
-
-      Reviewer.history.set(key, command.raw_string, timing)
-    end
+    def_delegators :@timing,
+                   :last_prepared_at,
+                   :last_prepared_at=,
+                   :average_time,
+                   :get_timing,
+                   :record_timing
 
     # Determines whether the `prepare` command was run recently enough
     #
@@ -129,22 +114,18 @@ module Reviewer
     def stale?
       return false unless preparable?
 
-      last_prepared_at.nil? || last_prepared_at < Time.now - SIX_HOURS_IN_SECONDS
+      @timing.stale?
     end
 
     # Convenience method for determining if a tool has a configured install link
     #
     # @return [Boolean] true if there is an `install` key under links and the value isn't blank
-    def install_link?
-      links.key?(:install) && !links[:install].nil?
-    end
+    def install_link? = links.key?(:install) && !!links[:install]
 
     # Returns the text for the install link if available
     #
     # @return [String, nil] the link if it exists, nil otherwise
-    def install_link
-      install_link? ? links.fetch(:install) : nil
-    end
+    def install_link = install_link? ? links.fetch(:install) : nil
 
     # Determines if two tools are equal
     # @param other [Tool] the tool to compare to the current instance
@@ -154,5 +135,43 @@ module Reviewer
       settings == other.settings
     end
     alias :== eql?
+
+    # Records the pass/fail status and failed files from a result into history
+    # @param result [Runner::Result] the result of running this tool
+    #
+    # @return [void]
+    def record_run(result)
+      status = result.success? ? :passed : :failed
+      @history.set(key, :last_status, status)
+
+      if result.success?
+        @history.set(key, :last_failed_files, nil)
+      else
+        files = Runner::FailedFiles.new(result.stdout, result.stderr).to_a
+        @history.set(key, :last_failed_files, files) if files.any?
+      end
+    end
+
+    # Resolves which files this tool should process
+    # @param files [Array<String>] the input files to resolve
+    #
+    # @return [Array<String>] files after mapping and filtering
+    def resolve_files(files)
+      file_resolver.resolve(files)
+    end
+
+    # Determines if this 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 match after resolution
+    def skip_files?(files)
+      file_resolver.skip?(files)
+    end
+
+    private
+
+    def file_resolver
+      @file_resolver ||= FileResolver.new(settings)
+    end
   end
 end

data/lib/reviewer/tools.rb

@@ -7,37 +7,39 @@ module Reviewer
     include Enumerable
 
     # Provides an instance to work with for knowing which tools to run in a given context.
-    # @param tags: nil [Array] the tags to use to filter tools for a run
-    # @param tool_names: nil [type] the explicitly provided tool names to filter tools for a run
+    # @param tags [Array] the tags to use to filter tools for a run
+    # @param tool_names [Array<String>] the explicitly provided tool names to filter tools for a run
+    # @param arguments [Arguments] the parsed CLI arguments
+    # @param history [History] the history store for status persistence
+    # @param config_file [Pathname, nil] path to the .reviewer.yml configuration file
     #
     # @return [Reviewer::Tools] collection of tools based on the current run context
-    def initialize(tags: nil, tool_names: nil)
-      @tags       = tags
-      @tool_names = tool_names
+    def initialize(tags: nil, tool_names: nil, arguments: nil, history: nil, config_file: nil)
+      @tags        = tags
+      @tool_names  = tool_names
+      @arguments   = arguments
+      @history     = history
+      @config_file = config_file
     end
 
     # The current state of all available configured tools regardless of whether they are disabled
     #
     # @return [Hash] hash representing all of the configured tools
-    def to_h
-      configured
-    end
+    def to_h = configured
     alias inspect to_h
 
     # Provides a collection of all configured tools instantiated as Tool instances
     #
     # @return [Array<Tool>] the full collection of all Tool instances
     def all
-      configured.keys.map { |tool_name| Tool.new(tool_name) }
+      configured.map { |tool_name, config| Tool.new(tool_name, config: config, history: @history) }
     end
     alias to_a all
 
-    # Provides a collection of all enabled tools instantiated as Tool instances
+    # Provides a collection of all tools that run in the default batch
     #
-    # @return [Array<Tool>] the full collection of all enabled Tool instances
-    def enabled
-      @enabled ||= all.keep_if(&:enabled?)
-    end
+    # @return [Array<Tool>] the full collection of batch-included Tool instances
+    def enabled = @enabled ||= all.reject(&:skip_in_batch?)
 
     # Provides a collection of all explicitly-specified-via-command-line tools as Tool instances
     #
@@ -54,13 +56,22 @@ module Reviewer
     end
 
     # Uses the full context of a run to provide the filtered subset of tools to use. It takes into
-    # consideration: tagged tools, explicitly-specified tools, configuration (enabled/disabled), and
-    # any other relevant details that should influence whether a specific tool should be run as part
-    # of the current batch being executed.
+    # consideration: tagged tools, explicitly-specified tools, failed tools, configuration
+    # (enabled/disabled), and any other relevant details that should influence whether a specific
+    # tool should be run as part of the current batch being executed.
     #
     # @return [Array<Tool>] the full collection of should-be-used-for-this-run tools
     def current
-      subset? ? (specified + tagged).uniq : enabled
+      return enabled unless subset? || failed_keyword?
+
+      (specified + tagged + failed).uniq
+    end
+
+    # Returns tools that failed in the previous run based on history
+    #
+    # @return [Array<Tool>] tools with :last_status of :failed in history
+    def failed_from_history
+      all.select { |tool| @history.get(tool.key, :last_status) == :failed }
     end
 
     private
@@ -70,28 +81,31 @@ module Reviewer
     # only a subset of relevant tools.
     #
     # @return [Boolean] true if any tool names or tags are provided via the command line
-    def subset?
-      tool_names.any? || tags.any?
-    end
+    def subset? = tool_names.any? || tags.any?
 
-    def configured
-      @configured ||= Loader.configuration
-    end
+    def failed
+      return [] unless failed_keyword?
 
-    def tags
-      Array(@tags || Reviewer.arguments.tags)
+      failed_from_history
     end
 
-    def tool_names
-      Array(@tool_names || Reviewer.arguments.keywords.for_tool_names)
-    end
+    def failed_keyword? = @arguments&.keywords&.failed? || false
+
+    def configured = @configured ||= Configuration::Loader.configuration(file: @config_file)
+    def tags = Array(@tags || matching_tags)
+    def tool_names = Array(@tool_names || matching_tool_names)
+    def tagged?(tool) = tool.matches_tags?(tags)
+    def named?(tool) = tool_names.map(&:to_s).include?(tool.key.to_s)
 
-    def tagged?(tool)
-      tool.enabled? && (tags & tool.tags).any?
+    def matching_tool_names
+      provided = @arguments&.keywords&.provided || []
+      provided & configured.keys.map(&:to_s)
     end
 
-    def named?(tool)
-      tool_names.map(&:to_s).include?(tool.key.to_s)
+    def matching_tags
+      provided = @arguments&.keywords&.provided || []
+      all_tags = enabled.flat_map(&:tags).uniq
+      (provided & all_tags) + Array(@arguments&.tags&.raw)
     end
   end
 end