reviewer 0.1.4 → 1.0.0

data/lib/reviewer/batch.rb

@@ -1,64 +1,75 @@
 # frozen_string_literal: true
 
+require_relative 'batch/formatter'
+
 module Reviewer
   # Provides a structure for running commands for a given set of tools
   class Batch
+    # Raised when a tool specifies an unrecognized command type
     class UnrecognizedCommandError < ArgumentError; end
 
-    attr_reader :command_type, :tools, :output, :results
+    attr_reader :command_type, :tools, :report, :context, :strategy
+    private :context, :strategy
 
-    def initialize(command_type, tools, output: Reviewer.output)
+    # Generates an instance of Batch for running multiple tools together
+    # @param command_type [Symbol] the type of command to run for each tool.
+    # @param tools [Array<Tool>] the tools to run the commands for
+    # @param strategy [Class] the runner strategy class (Captured or Passthrough)
+    # @param context [Context] the shared runtime dependencies (arguments, output, history)
+    #
+    # @return [self]
+    def initialize(command_type, tools, strategy:, context:)
       @command_type = command_type
       @tools = tools
-      @output  = output
-      @results = {}
+      @strategy = strategy
+      @context = context
+      @report = Report.new
     end
 
+    # Iterates over the tools in the batch to successfully run the commands. Also times the entire
+    #   batch in order to provide a total execution time.
+    #
+    # @return [Report] the report containing results for all commands run
     def run
-      benchmark_batch do
-        tools.each do |tool|
-          runner = Runner.new(tool, command_type, strategy)
-
-          # With multiple tools, run each one quietly.
-          # Otherwise, with just one tool
-          runner.run
-
-          # Record the exit status
-          capture_results(runner)
-
-          # If the tool fails, stop running other tools
-          break unless runner.success?
+      elapsed_time = Benchmark.realtime do
+        clear_last_statuses
+        matching_tools.each do |tool|
+          runner = run_tool(tool)
+          break unless runner.success? || runner.missing?
         end
       end
 
-      results
-    end
-
-    def self.run(*args)
-      new(*args).run
+      @report.record_duration(elapsed_time)
+      @report
     end
 
     private
 
-    def multiple_tools?
-      tools.size > 1
-    end
+    # Runs a single tool and records its result in the report.
+    # @return [Runner] the runner after execution
+    def run_tool(tool)
+      runner = Runner.new(tool, command_type, strategy, context: context)
+      runner.run
 
-    def strategy
-      multiple_tools? ? Runner::Strategies::Quiet : Runner::Strategies::Verbose
+      result = runner.to_result
+      @report.add(result)
+      tool.record_run(result) unless runner.missing?
+
+      runner
     end
 
-    def capture_results(runner)
-      @results[runner.tool.key] = runner.exit_status
+    def clear_last_statuses
+      matching_tools.each do |tool|
+        context.history.set(tool.key, :last_status, nil)
+      end
     end
 
-    # Records and prints the total runtime of a block
-    # @param &block [type] section of code to be timed
+    # Returns the set of tools matching the provided command. So when formatting, if a tool does not
+    #   have a format command, then it will be skipped.
     #
-    # @return [void] prints the elapsed time
-    def benchmark_batch(&block)
-      elapsed_time = Benchmark.realtime(&block)
-      output.info "\nTotal Time ".white + "#{elapsed_time.round(1)}s".bold
+    # @return [Array<Tool>] the enabled tools that support the provided command
+    def matching_tools
+      tools.select { |tool| tool.command?(command_type) }
     end
   end
 end

data/lib/reviewer/capabilities.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Reviewer
+  # Provides machine-readable output describing available tools and usage patterns.
+  # Designed for AI agents and automation tools to discover and use Reviewer correctly.
+  #
+  # @example
+  #   puts Reviewer::Capabilities.new.to_json
+  class Capabilities
+    attr_reader :tools
+
+    # Creates a capabilities report for machine-readable tool discovery
+    # @param tools [Tools] the tools collection to report on
+    #
+    # @return [Capabilities]
+    def initialize(tools:)
+      @tools = tools
+    end
+
+    KEYWORDS = {
+      staged: 'Files staged for commit',
+      unstaged: 'Files with unstaged changes',
+      modified: 'All changed files',
+      untracked: 'New files not yet tracked'
+    }.freeze
+
+    SCENARIOS = {
+      before_commit: 'rvw staged',
+      during_development: 'rvw modified',
+      full_review: 'rvw'
+    }.freeze
+
+    # Convert capabilities to a hash representation
+    #
+    # @return [Hash] structured capabilities data
+    def to_h
+      {
+        version: VERSION,
+        tools: tools_data,
+        keywords: KEYWORDS,
+        scenarios: SCENARIOS
+      }
+    end
+
+    # Convert capabilities to formatted JSON string
+    #
+    # @return [String] JSON representation of capabilities
+    def to_json(*_args)
+      JSON.pretty_generate(to_h)
+    end
+
+    private
+
+    # Build tool data from configured tools
+    #
+    # @return [Array<Hash>] array of tool capability hashes
+    def tools_data
+      tools.all.map { |tool| tool_data(tool) }
+    end
+
+    # Build capability data for a single tool
+    #
+    # @param tool [Tool] the tool to extract data from
+    # @return [Hash] tool capability hash
+    def tool_data(tool)
+      {
+        key: tool.key.to_s,
+        name: tool.name,
+        description: tool.description,
+        tags: tool.tags,
+        skip_in_batch: tool.skip_in_batch?,
+        commands: {
+          review: tool.reviewable?,
+          format: tool.formattable?
+        }
+      }
+    end
+  end
+end

data/lib/reviewer/command/string/env.rb

@@ -7,28 +7,38 @@ module Reviewer
       class Env
         attr_reader :env_pairs
 
+        # Creates an instance of env variables for a tool to help generate the command string
+        # @param env_pairs [Hash] [description]
+        #
+        # @return [self]
         def initialize(env_pairs)
           @env_pairs = env_pairs
         end
 
+        # Converts environment variables to a space-separated string
+        #
+        # @return [String] formatted environment variables (e.g., "KEY=value KEY2=value2")
         def to_s
           to_a.compact.join(' ')
         end
 
+        # Converts environment variables to an array of KEY=value strings
+        #
+        # @return [Array<String, nil>] array of formatted env vars, nil for empty values
         def to_a
-          env = []
-          env_pairs.each { |key, value| env << env(key, value) }
-          env
+          env_pairs.map { |key, value| env(key, value) }
         end
 
         private
 
         def env(key, value)
-          return nil if key.to_s.strip.empty? || value.to_s.strip.empty?
+          key_str = key.to_s.strip
+          value_str = value.to_s.strip
+          return nil if key_str.empty? || value_str.empty?
 
-          value = needs_quotes?(value) ? "'#{value}'" : value
+          value_str = "'#{value_str}'" if needs_quotes?(value)
 
-          "#{key.to_s.strip.upcase}=#{value.to_s.strip}"
+          "#{key_str.upcase}=#{value_str}"
         end
 
         def needs_quotes?(value)

data/lib/reviewer/command/string/flags.rb

@@ -3,22 +3,31 @@
 module Reviewer
   class Command
     class String
-      # Assembles tool flag settings into a single string or array
+      # Translates tool flag settings from the tool's configuration values into a single string or
+      #   array that can be used to generate the command string
       class Flags
         attr_reader :flag_pairs
 
+        # Creates an instance of command-string friendly flags
+        # @param flag_pairs [Hash] the flags (keys) and their values
+        #
+        # @return [self]
         def initialize(flag_pairs)
           @flag_pairs = flag_pairs
         end
 
+        # Creates a string-friendly format to use in a command
+        #
+        # @return [String] a string of flags that can be safely passed to a command
         def to_s
           to_a.join(' ')
         end
 
+        # Creates an array of all flag name/value pairs
+        #
+        # @return [Array<String>] array of all flag strings to use to when running the command
         def to_a
-          flags = []
-          flag_pairs.each { |key, value| flags << flag(key, value) }
-          flags
+          flag_pairs.map { |key, value| flag(key, value) }
         end
 
         private
@@ -26,7 +35,7 @@ module Reviewer
         def flag(key, value)
           dash = key.to_s.size == 1 ? '-' : '--'
 
-          value = needs_quotes?(value) ? "'#{value}'" : value
+          value = "'#{value}'" if needs_quotes?(value)
 
           "#{dash}#{key} #{value}".strip
         end

data/lib/reviewer/command/string.rb

@@ -2,22 +2,28 @@
 
 require_relative 'string/env'
 require_relative 'string/flags'
-require_relative 'string/verbosity'
 
 module Reviewer
   class Command
-    # Assembles tool tool_settings into a usable command string for the command type and verbosity
+    # Assembles tool tool_settings into a usable command string for the command type
     class String
-      include Conversions
+      attr_reader :command_type, :tool_settings, :files
 
-      attr_reader :command_type, :tool_settings, :verbosity
-
-      def initialize(command_type, tool_settings:, verbosity: nil)
+      # Creates a command string builder for a tool
+      # @param command_type [Symbol] the command type (:install, :prepare, :review, :format)
+      # @param tool_settings [Tool::Settings] the tool's configuration settings
+      # @param files [Array<String>] files to include in the command
+      #
+      # @return [String] a command string builder instance
+      def initialize(command_type, tool_settings:, files: [])
         @command_type = command_type
         @tool_settings = tool_settings
-        @verbosity = Verbosity(verbosity)
+        @files = Array(files)
       end
 
+      # Converts the command to a complete string ready for execution
+      #
+      # @return [String] the full command string
       def to_s
         to_a
           .map(&:strip) # Remove extra spaces on the components
@@ -25,48 +31,71 @@ module Reviewer
           .strip        # Strip extra spaces from the end result
       end
 
+      # Converts the command to an array of its components
+      #
+      # @return [Array<String, nil>] env vars, body, flags, and files
       def to_a
         [
           env_variables,
           body,
           flags,
-          verbosity_options
+          files_string
         ].compact
       end
 
-      def env_variables
-        Env.new(tool_settings.env).to_s
-      end
+      # The string of environment variables built from a tool's configuration settings
+      #
+      # @return [String] the environment variable names and values concatened for the command
+      def env_variables = Env.new(tool_settings.env).to_s
 
+      # The base command string from the tool's configuration.
+      # Uses the file-scoped command when files are present and one is configured.
+      #
+      # @return [String] the configured command for the command type
       def body
-        tool_settings.commands.fetch(command_type)
+        file_scoped_command || tool_settings.commands.fetch(command_type)
       end
 
+      # Gets the flags to be used in conjunction with the review command for a tool
+      #   1. The `review` commands are the only commands that use flags
+      #   2. If no flags are configured, this won't do anything
+      #
+      # @return [String] the concatenated list of flags to pass to the review command
       def flags
-        # Flags to be used for `review` commands.
-        # 1. The `review` commands are the only commands that use flags
-        # 2. If no flags are configured, this won't do much
-        #
-        # Note: Since verbosity is handled separately, flags for 'quiet' are handled separately at a
-        #   lower level by design and excluded from this check. They are not included with the other
-        #   configured flags.
         return nil unless flags?
 
         Flags.new(tool_settings.flags).to_s
       end
 
-      def verbosity_options
-        Verbosity.new(tool_settings.quiet_option, level: verbosity.level).to_s
+      # Builds the files portion of the command string
+      #
+      # @return [String, nil] the formatted files string or nil if not applicable
+      def files_string
+        return nil unless files_applicable?
+
+        file_list = files.join(tool_settings.files_separator)
+        flag = tool_settings.files_flag
+
+        flag.empty? ? file_list : "#{flag} #{file_list}"
       end
 
       private
 
+      def file_scoped_command
+        return nil unless files.any?
+
+        tool_settings.files_command(command_type)
+      end
+
       # Determines whether the string needs flags added
       #
       # @return [Boolean] true if it's a review command and it has flags configured
-      def flags?
-        command_type == :review && tool_settings.flags.any?
-      end
+      def flags? = command_type == :review && tool_settings.flags.any?
+
+      # Determines whether files should be appended to the command
+      #
+      # @return [Boolean] true if tool supports files and files were provided
+      def files_applicable? = tool_settings.supports_files? && files.any?
     end
   end
 end

data/lib/reviewer/command.rb

@@ -1,28 +1,34 @@
 # frozen_string_literal: true
 
 require_relative 'command/string'
-require_relative 'command/verbosity'
 
 module Reviewer
   # The core funtionality to translate a tool, command type, and verbosity into a runnable command
   class Command
-    include Conversions
+    include Tool::Conversions
 
     SEED_SUBSTITUTION_VALUE = '$SEED'
 
-    attr_reader :tool, :type
+    attr_reader :tool, :arguments, :history
+    private :arguments, :history
+
+    # @!attribute type
+    #   @return [Symbol] the command type (:install, :prepare, :review, :format)
+    attr_accessor :type
 
     # Creates an instance of the Command class to synthesize a command string using the tool,
     # command type, and verbosity.
     # @param tool [Tool, Symbol] a tool or tool key to use to look up the command and options
     # @param type [Symbol] the desired command type (:install, :prepare, :review, :format)
-    # @param verbosity = Verbosity::TOTAL_SILENCE [Symbol] the desired verbosity for the command
+    # @param context [Context] the shared runtime dependencies (arguments, output, history)
     #
     # @return [Command] the intersection of a tool, command type, and verbosity
-    def initialize(tool, type, verbosity = Verbosity::TOTAL_SILENCE)
+    def initialize(tool, type, context:)
       @tool = Tool(tool)
       @type = type.to_sym
-      @verbosity = Verbosity(verbosity)
+      @seed = nil
+      @arguments = context.arguments
+      @history = context.history
     end
 
     # The final command string with all of the conditions appled
@@ -33,26 +39,6 @@ module Reviewer
     end
     alias to_s string
 
-    # Getter for @verbosity. Since the setter is custom, the getter needs to be explicitly declared.
-    # Otherwise, using `attr_accessor` and then overriding the setter muddies the waters.
-    #
-    # @return [Verbosity] the current verbosity setting for the command
-    def verbosity # rubocop:disable Style/TrivialAccessors
-      @verbosity
-    end
-
-    # Override verbosity assignment to clear the related memoized values when verbosity changes
-    # @param verbosity [Verbosity, Symbol] the desired verbosity for the command
-    #
-    # @return [Verbosity] the updated verbosity level for the command
-    def verbosity=(verbosity)
-      # Unmemoize string since the verbosity has been changed
-      @raw_string = nil
-      @string = nil
-
-      @verbosity = Verbosity(verbosity)
-    end
-
     # Generates a seed that can be re-used across runs so that the results are consistent across
     # related runs for tools that would otherwise change the seed automatically every run.
     # Since not all tools will use the seed, there's no need to generate it in the initializer.
@@ -60,26 +46,72 @@ module Reviewer
     #
     # @return [Integer] a random integer to pass to tools that use seeds
     def seed
-      @seed ||= Random.rand(100_000)
+      @seed ||= if arguments.keywords.failed?
+                  history.get(tool.key, :last_seed) || Random.rand(100_000)
+                else
+                  Random.rand(100_000)
+                end
 
       # Store the seed for reference
-      Reviewer.history.set(tool.key, :last_seed, @seed)
+      history.set(tool.key, :last_seed, @seed)
 
       @seed
     end
 
-    private
-
     # The raw command string before any substitutions. For example, since seeds need to remain
     # consistent from one run to the next, they're
     #
-    # @return [type] [description]
+    # @return [String] the command string before seed substitution
     def raw_string
-      @raw_string ||= String.new(
-        type,
-        tool_settings: tool.settings,
-        verbosity: verbosity
-      ).to_s
+      @raw_string ||= String.new(type, tool_settings: tool.settings, files: target_files).to_s # rubocop:disable Lint/RedundantTypeConversion
+    end
+
+    # Gets the list of files to target for this command, resolved by the tool
+    #
+    # @return [Array<String>] the list of files from arguments, resolved by tool
+    def target_files
+      @target_files ||= tool.resolve_files(requested_files)
+    end
+
+    # Determines if this command should be skipped because files were requested but none match
+    #
+    # @return [Boolean] true if files were requested but resolution left none for this tool
+    def skip?
+      tool.skip_files?(requested_files)
+    end
+
+    # Returns a summary hash for run display, or nil if this command should be skipped
+    #
+    # @return [Hash, nil] { name:, files: } or nil if skipped
+    def run_summary
+      return nil if skip?
+
+      { name: tool.name, files: target_files }
+    end
+
+    private
+
+    # The raw list of files from arguments before resolution.
+    # Falls through to stored failed files when the `failed` keyword is present
+    # and no explicit files were provided.
+    #
+    # @return [Array<String>] files from -f flag, keywords like 'staged', or stored failed files
+    def requested_files
+      @requested_files ||= begin
+        explicit = arguments.files.to_a
+        if explicit.empty? && arguments.keywords.failed?
+          stored_failed_files
+        else
+          explicit
+        end
+      end
+    end
+
+    # Retrieves failed files stored from the previous run for this tool
+    #
+    # @return [Array<String>] stored failed file paths, or empty array
+    def stored_failed_files
+      history.get(tool.key, :last_failed_files) || []
     end
 
     # The version of the command with the SEED_SUBSTITUTION_VALUE replaced
@@ -93,8 +125,6 @@ module Reviewer
     # Determines if the raw command string has a SEED_SUBSTITUTION_VALUE that needs replacing
     #
     # @return [Boolean] true if the raw command string contains the SEED_SUBSTITUTION_VALUE
-    def seed_substitution?
-      raw_string.include?(SEED_SUBSTITUTION_VALUE)
-    end
+    def seed_substitution? = raw_string.include?(SEED_SUBSTITUTION_VALUE)
   end
 end

data/lib/reviewer/configuration/loader.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Reviewer
+  class Configuration
+    # Provides a collection of the configured tools
+    class Loader
+      # Raised when the .reviewer.yml configuration file cannot be found
+      class MissingConfigurationError < StandardError; end
+
+      # Raised when the .reviewer.yml file contains invalid YAML syntax
+      class InvalidConfigurationError < StandardError; end
+
+      # Raised when a configured tool is missing a required review command
+      class MissingReviewCommandError < StandardError; end
+
+      attr_reader :configuration, :file
+
+      # Creates a loader instance for the configuration file
+      # @param file [Pathname] the path to the configuration YAML file
+      #
+      # @return [Loader] a loader with parsed configuration
+      # @raise [MissingConfigurationError] if the file doesn't exist
+      # @raise [InvalidConfigurationError] if the YAML is malformed
+      # @raise [MissingReviewCommandError] if a tool lacks a review command
+      def initialize(file:)
+        @file = file
+        @configuration = configuration_hash
+
+        validate_configuration
+      end
+
+      # Whether all configured tools have a review command
+      #
+      # @return [Boolean] true if every tool has a review command configured
+      def review_commands_present?
+        configuration.all? { |_key, value| value[:commands]&.key?(:review) }
+      end
+
+      # Converts the loader to its configuration hash
+      #
+      # @return [Hash] the parsed configuration
+      def to_h = configuration
+
+      # Loads and returns the tools configuration hash
+      #
+      # @return [Hash] the parsed configuration from the YAML file
+      def self.configuration(file:) = new(file: file).configuration
+
+      private
+
+      def require_review_commands
+        return if review_commands_present?
+
+        missing = configuration.find { |_key, value| !value[:commands]&.key?(:review) }
+        raise MissingReviewCommandError, "'#{missing[0]}' does not have a 'review' key under 'commands' in `#{file}`"
+      end
+      alias validate_configuration require_review_commands
+
+      def configuration_hash
+        @configuration_hash ||= Psych.safe_load_file(@file, symbolize_names: true)
+      rescue Errno::ENOENT
+        raise MissingConfigurationError, "Tools configuration file couldn't be found at `#{file}`"
+      rescue Psych::SyntaxError => e
+        raise InvalidConfigurationError, "Tools configuration file (#{file}) has a syntax error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/reviewer/configuration.rb

@@ -4,21 +4,31 @@ require 'pathname'
 
 module Reviewer
   # Configuration values container for Reviewer
+  #
+  # @!attribute file
+  #   @return [Pathname] the pathname for the primary configuraton file
+  # @!attribute history_file
+  #   @return [Pathname] the pathname for the history file to store data across runs
+  # @!attribute printer
+  #   @return [Output::Printer] the printer instance for console output
+  #
+  # @author [garrettdimon]
+  #
   class Configuration
     DEFAULT_PATH = Dir.pwd.freeze
 
     DEFAULT_CONFIG_FILE_NAME = '.reviewer.yml'
     DEFAULT_HISTORY_FILE_NAME = '.reviewer_history.yml'
 
-    DEFAULT_CONFIG_LOCATION = "#{DEFAULT_PATH}/#{DEFAULT_CONFIG_FILE_NAME}"
-    DEFAULT_HISTORY_LOCATION = "#{DEFAULT_PATH}/#{DEFAULT_HISTORY_FILE_NAME}"
+    DEFAULT_CONFIG_LOCATION = "#{DEFAULT_PATH}/#{DEFAULT_CONFIG_FILE_NAME}".freeze
+    DEFAULT_HISTORY_LOCATION = "#{DEFAULT_PATH}/#{DEFAULT_HISTORY_FILE_NAME}".freeze
 
-    attr_accessor :file, :history_file, :printer
+    attr_accessor :file, :history_file
+    attr_reader :printer
 
     def initialize
       @file = Pathname(DEFAULT_CONFIG_LOCATION)
       @history_file = Pathname(DEFAULT_HISTORY_LOCATION)
-      @printer = ::Reviewer::Printer.new
 
       # Future Configuration Options:
       # - seed_substitution_value(string): Currently a constant of `$SEED` in Reviewer::Command, but