reviewer 0.1.5 → 1.0.0

data/lib/reviewer/batch.rb

@@ -1,83 +1,67 @@
 # 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
 
     # 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 output: Reviewer.output [Output] the output channel to print results to
+    # @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, output: Reviewer.output)
+    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 [Results] the results summary for all commands run
+    # @return [Report] the report containing results for all commands run
     def run
-      benchmark_batch do
+      elapsed_time = Benchmark.realtime do
+        clear_last_statuses
         matching_tools.each do |tool|
-          # Create and execute a runner for the given tool, command type, and strategy
-          runner = Runner.new(tool, command_type, strategy)
-          runner.run
-
-          # Record the exit status for this tool
-          record_exit_status(runner)
-
-          # If the tool fails, stop running other tools
-          break unless runner.success?
+          runner = run_tool(tool)
+          break unless runner.success? || runner.missing?
         end
       end
 
-      results
+      @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::Captured : Runner::Strategies::Passthrough
-    end
+      result = runner.to_result
+      @report.add(result)
+      tool.record_run(result) unless runner.missing?
 
-    # Notes the exit status for the runner based on whether the runner was considered successful or
-    #   not based on the configured `max_exit_status` for the tool. For example, some tools use exit
-    #   status to convey significance. So even though it returns a non-zero exit status like 2, it
-    #   can still be successful.
-    # @param runner [Runner] the instance of the runner that's being inspected
-    #
-    # @return [Integer] the adjusted exit status for the runner
-    def record_exit_status(runner)
-      # Since some tools can "succeed" with a positive exit status, the overall batch is only
-      # interested in subjective failure. So if the runner succeeded according to the tool's max
-      # exit status, it should record the tool's run as a success for the purposes of the larger
-      # batch success/failure
-      @results[runner.tool.key] = runner.success? ? 0 : runner.exit_status
+      runner
     end
 
-    # Records and prints the total runtime of a block
-    # @param &block [type] section of code to be timed
-    #
-    # @return [void] prints the elapsed time
-    def benchmark_batch(&block)
-      elapsed_time = Benchmark.realtime(&block)
-
-      # If there's failures, skip showing the total time to focus on the issues
-      return if @results.values.sum.positive?
-
-      output.batch_summary(results.size, elapsed_time)
+    def clear_last_statuses
+      matching_tools.each do |tool|
+        context.history.set(tool.key, :last_status, nil)
+      end
     end
 
     # Returns the set of tools matching the provided command. So when formatting, if a tool does not
@@ -85,7 +69,7 @@ module Reviewer
     #
     # @return [Array<Tool>] the enabled tools that support the provided command
     def matching_tools
-      tools.select { |tool| tool.settings.commands.key?(command_type) }
+      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

@@ -15,24 +15,30 @@ module Reviewer
           @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

@@ -27,9 +27,7 @@ module Reviewer
         #
         # @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
@@ -37,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

@@ -7,15 +7,23 @@ module Reviewer
   class Command
     # 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
-
-      def initialize(command_type, tool_settings:)
+      # 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
+        @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
@@ -23,23 +31,29 @@ 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
+          flags,
+          files_string
         ].compact
       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
-      end
+      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
@@ -53,14 +67,35 @@ module Reviewer
         Flags.new(tool_settings.flags).to_s
       end
 
+      # 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

@@ -5,23 +5,30 @@ require_relative 'command/string'
 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
+    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 context [Context] the shared runtime dependencies (arguments, output, history)
     #
     # @return [Command] the intersection of a tool, command type, and verbosity
-    def initialize(tool, type)
+    def initialize(tool, type, context:)
       @tool = Tool(tool)
       @type = type.to_sym
+      @seed = nil
+      @arguments = context.arguments
+      @history = context.history
     end
 
     # The final command string with all of the conditions appled
@@ -39,10 +46,14 @@ 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
@@ -50,13 +61,59 @@ module Reviewer
     # 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).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
     #
     # @return [String] the command string with the SEED_SUBSTITUTION_VALUE replaced
@@ -68,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

@@ -9,6 +9,8 @@ module Reviewer
   #   @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]
   #
@@ -18,10 +20,11 @@ module Reviewer
     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)

data/lib/reviewer/context.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Reviewer
+  # Bundles the shared runtime dependencies that flow through the review/format lifecycle.
+  # Passed from Session → Batch → Runner → Command so that no class needs to reach
+  # into module-level globals for arguments, output, or history.
+  #
+  # @!attribute [rw] arguments
+  #   @return [Arguments] the parsed command-line arguments
+  # @!attribute [rw] output
+  #   @return [Output] the output channel for displaying content
+  # @!attribute [rw] history
+  #   @return [History] the YAML store for timing data and prepare timestamps
+  Context = Struct.new(:arguments, :output, :history, keyword_init: true)
+end

data/lib/reviewer/doctor/config_check.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Doctor
+    # Validates the configuration file by delegating to Configuration::Loader
+    class ConfigCheck
+      attr_reader :report
+
+      # Creates a config check that validates the .reviewer.yml file
+      # @param report [Doctor::Report] the report to add findings to
+      # @param configuration [Configuration] the configuration to validate
+      #
+      # @return [ConfigCheck]
+      def initialize(report, configuration:)
+        @report = report
+        @configuration = configuration
+      end
+
+      # Checks for .reviewer.yml existence and validity
+      def check
+        config_file = @configuration.file
+
+        unless config_file.exist?
+          report.add(:configuration, status: :error,
+                                     message: 'No .reviewer.yml found', detail: 'Run `rvw init` to generate one')
+          return
+        end
+
+        report.add(:configuration, status: :ok, message: '.reviewer.yml found')
+        validate_via_loader
+      end
+
+      private
+
+      # Exercises the full Configuration::Loader pipeline (parse + validate) to surface config errors
+      def validate_via_loader
+        Configuration::Loader.configuration(file: @configuration.file)
+        report.add(:configuration, status: :ok, message: 'Configuration is valid')
+      rescue Configuration::Loader::InvalidConfigurationError => e
+        report.add(:configuration, status: :error, message: 'YAML syntax error', detail: e.message)
+      rescue Configuration::Loader::MissingReviewCommandError => e
+        report.add(:configuration, status: :error, message: 'Missing review command', detail: e.message)
+      end
+    end
+  end
+end