reviewer 0.1.4 → 1.0.0

data/exe/rvw

@@ -4,4 +4,4 @@
 
 require_relative '../lib/reviewer'
 
-Reviewer.review(clear_screen: true)
+Reviewer.review

data/lib/reviewer/arguments/files.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'open3'
+
 module Reviewer
   class Arguments
     # Generates a Ruby-friendly list (Array) of files to run the command against from the provided
@@ -9,36 +11,43 @@ module Reviewer
 
       alias raw provided
 
-      # Generates and instance of files from the provided arguments
-      # @param provided: Reviewer.arguments.files.raw [Array, String] file arguments provided
-      #   directly via the -f or --files flag on the command line.
-      # @param keywords: Reviewer.arguments.keywords [Array, String] keywords that can potentially
-      #   be translated to a list of files (ex. 'staged')
+      # Generates an instance of files from the provided arguments
+      # @param provided [Array<String>] file arguments provided
+      #   directly via the -f or --files flag on the command line
+      # @param keywords [Array<String>] reserved keywords that can potentially
+      #   be translated to a list of files (e.g. 'staged', 'modified')
+      # @param output [Output] the console output handler
+      # @param on_git_error [Proc, nil] callback invoked with the error message
+      #   when a git command fails (nil silently swallows the error)
+      #
+      # @example Using the `-f` flag: `rvw -f ./file.rb`
+      #   reviewer = Reviewer::Arguments::Files.new(provided: ['./file.rb'], keywords: [])
+      #   reviewer.to_a # => ['./file.rb']
+      # @example Using the `--files` flag: `rvw --files ./file.rb,./directory/file.rb
+      #   reviewer = Reviewer::Arguments::Files.new(provided: ['./file.rb','./directory/file.rb'], keywords: [])
+      #   reviewer.to_a # => ['./file.rb','./directory/file.rb']
       #
-      # @return [Arguments::Files] the container for determining targeted files from the provided
-      #   command line arguments
-      def initialize(provided: Reviewer.arguments.files.raw, keywords: Reviewer.arguments.keywords)
+      # @return [self]
+      def initialize(provided: [], keywords: [], output: Output.new, on_git_error: nil)
         @provided = Array(provided)
         @keywords = Array(keywords)
+        @output = output
+        @on_git_error = on_git_error
       end
 
       # Provides the full list of file/path values derived from the command-line arguments
       #
       # @return [Array<String>] full collection of the file arguments as a string
-      def to_a
-        file_list
-      end
+      def to_a = file_list
 
       # Provides the full list of file/path values derived from the command-line arguments
       #
-      # @return [String] comma-separated string of the derived tag values
-      def to_s
-        to_a.join(',')
-      end
+      # @return [String] comma-separated string of the derived file values
+      def to_s = to_a.join(',')
 
       # Summary of the state of the file arguments
       #
-      # @return [Hash] represents the summary of the file values parsed from the command-line
+      # @return [Hash<Symbol, Array<String>>] summarizes all of the resulting file values
       def to_h
         {
           provided: provided.sort,
@@ -50,7 +59,7 @@ module Reviewer
       private
 
       # Combines the sorted list of unique files/paths by merging the explicitly-provided file
-      # arguments as well as those that were translated from any relevant keyword arguments.
+      #   arguments as well as those that were translated from any relevant keyword arguments.
       #
       # @return [Array] full list of files/paths passed via command-line including those extracted
       #   as a result of a keyword argument like `staged`
@@ -63,25 +72,49 @@ module Reviewer
 
       # Converts relevant keywords to the list of files they implicitly represent.
       #
-      # @return [Array] list of files/paths translated from any keyword arguments that represent a
-      #   list of files
+      # @return [Array<String>] list of files/paths translated from any keyword arguments that
+      #   represent a list of files
       def from_keywords
         return [] unless keywords.any?
 
         keywords.map do |keyword|
-          next unless respond_to?(keyword.to_sym, true)
+          method_name = keyword.to_sym
+          next unless respond_to?(method_name, true)
 
-          send(keyword.to_sym)
+          send(method_name)
         end.flatten.compact.uniq
       end
 
-      # If `staged` is passed as a keyword via the command-line, this will get the list of staged
-      # files via Git
-      #
-      # @return [Array] list of the currently staged files
       def staged
-        # Use git for list of staged fields
-        ::Reviewer::Keywords::Git::Staged.list
+        git_files(%w[diff --staged --name-only])
+      end
+
+      def unstaged
+        git_files(%w[diff --name-only])
+      end
+
+      def modified
+        git_files(%w[diff --name-only HEAD])
+      end
+
+      def untracked
+        git_files(%w[ls-files --others --exclude-standard])
+      end
+
+      # Executes a git command and returns the output as an array of file paths
+      # @param options [Array<String>] the git command options
+      #
+      # @return [Array<String>] the output lines from the command
+      def git_files(options)
+        command = (%w[git --no-pager] + options).join(' ')
+        stdout, stderr, status = Open3.capture3(command)
+
+        return stdout.split("\n").reject(&:empty?) if status.success?
+
+        raise SystemCallError.new("Git Error: #{stderr} (#{command})", status.exitstatus.to_i)
+      rescue SystemCallError => e
+        @on_git_error&.call(e.message)
+        []
       end
     end
   end

data/lib/reviewer/arguments/keywords.rb

@@ -4,35 +4,41 @@ module Reviewer
   class Arguments
     # Handles interpreting all 'leftover' arguments and translating them to file-related,
     # tag-related, or tool-related arguments
+    #
+    # @!attribute provided
+    #   @return [Array<String>] the keywords extracted from the command-line arguments
     class Keywords
-      RESERVED = %w[staged].freeze
+      RESERVED = %w[staged unstaged modified untracked failed].freeze
 
-      attr_accessor :provided
+      attr_reader :provided
+
+      # Sets the tools collection after initialization when tools become available
+      # @param value [Tools] the configured tools collection
+      # @return [Tools] the tools collection
+      attr_writer :tools
 
       alias raw provided
 
-      # Generates an instace of parsed keywords from the provided arguments
-      # @param *provided [Array<String>] the leftover (non-flag) arguments from the command line
+      # Generates an instance of parsed keywords from the provided arguments
+      # @param provided [Array<String>] the leftover (non-flag) arguments from the command line
+      # @param tools [Tools] the collection of configured tools for keyword recognition
       #
-      # @return [Arguments::Keywords]
-      def initialize(*provided)
+      # @return [self]
+      def initialize(*provided, tools: nil)
         @provided = Array(provided.flatten)
+        @tools = tools
       end
 
-      # Proves the full list of raw keyword arguments explicitly passed via command-line as an array
+      # Provides the full list of raw keyword arguments explicitly passed via command-line as an array
       #
-      # @return [Array] full collection of the provided keyword arguments as a string
-      def to_a
-        provided
-      end
+      # @return [Array<String>] full collection of the provided keyword arguments
+      def to_a = provided
 
       # Provides the full list of raw keyword arguments explicitly passed via command-line as a
       #   comma-separated string
       #
-      # @return [String] comma-separated list of the file arguments as a string
-      def to_s
-        to_a.join(',')
-      end
+      # @return [String] comma-separated list of the keyword arguments as a string
+      def to_s = to_a.join(',')
 
       # Summary of the state of keyword arguments based on how Reviewer parsed them
       #
@@ -50,52 +56,47 @@ module Reviewer
       end
       alias inspect to_h
 
+      # Whether the `failed` keyword was provided
+      #
+      # @return [Boolean] true if the `failed` keyword is present
+      def failed? = provided.include?('failed')
+
       # Extracts reserved keywords from the provided arguments
       #
       # @return [Array<String>] intersection of provided arguments and reserved keywords
-      def reserved
-        intersection_with RESERVED
-      end
+      def reserved = intersection_with(RESERVED)
 
       # Extracts keywords that match configured tags for enabled tools
       #
       # @return [Array<String>] intersection of provided arguments and configured tags for tools
-      def for_tags
-        intersection_with configured_tags
-      end
+      def for_tags = intersection_with(configured_tags)
 
       # Extracts keywords that match configured tool keys
       #
       # @return [Array<String>] intersection of provided arguments and configured tool names
-      def for_tool_names
-        intersection_with configured_tool_names
-      end
+      def for_tool_names = intersection_with(configured_tool_names)
 
       # Extracts keywords that match any possible recognized keyword values
       #
       # @return [Array<String>] intersection of provided arguments and recognizable keywords
-      def recognized
-        intersection_with possible
-      end
+      def recognized = intersection_with(possible)
 
       # Extracts keywords that don't match any possible recognized keyword values
       #
       # @return [Array<String>] leftover keywords that weren't recognized
-      def unrecognized
-        (provided - recognized).uniq.sort
-      end
+      def unrecognized = (provided - recognized).uniq.sort
 
       # Provides the complete list of all recognized keywords based on configuration
       #
-      # @return [Array<String>] all keywords that Reviewer can recognized
-      def possible
-        (RESERVED + configured_tags + configured_tool_names).uniq.sort
-      end
+      # @return [Array<String>] all keywords that Reviewer can recognize
+      def possible = (RESERVED + configured_tags + configured_tool_names).uniq.sort
 
       # Provides the complete list of all configured tags for enabled tools
       #
       # @return [Array<String>] all unique configured tags
       def configured_tags
+        return [] unless tools
+
         tools.enabled.map(&:tags).flatten.uniq.sort
       end
 
@@ -103,6 +104,8 @@ module Reviewer
       #
       # @return [Array<String>] all unique configured tools
       def configured_tool_names
+        return [] unless tools
+
         # We explicitly don't sort the tool names list because Reviewer uses the configuration order
         # to determine the execution order. So not sorting maintains the predicted order it will run
         # in and leaves the option to sort to the consuming code if needed
@@ -111,20 +114,13 @@ module Reviewer
 
       private
 
-      # Provides a collection of enabled Tools for convenient access
-      #
-      # @return [Array<Reviewer::Tool>] collection of all currently enabled tools
-      def tools
-        @tools ||= Reviewer.tools
-      end
+      attr_reader :tools
 
       # Syntactic sugar for finding intersections with valid keywords
       # @param values [Array<String>] the collection to use for finding intersecting values
       #
       # @return [Array<String>] the list of intersecting values
-      def intersection_with(values)
-        (values & provided).uniq.sort
-      end
+      def intersection_with(values) = (values & provided).uniq.sort
     end
   end
 end

data/lib/reviewer/arguments/tags.rb

@@ -4,19 +4,30 @@ module Reviewer
   class Arguments
     # Handles the logic of translating tag arguments
     class Tags
-      attr_accessor :provided, :keywords
+      # @!attribute provided
+      #   @return [Array<String>] tags explicitly provided via -t or --tags flag
+      # @!attribute keywords
+      #   @return [Array<String>] tags derived from keyword arguments
+      attr_reader :provided, :keywords
 
       alias raw provided
 
-      # Generates an instace of parsed tags from the provided arguments
-      # @param provided: Reviewer.arguments.tags.raw [Array<String>] tag arguments provided
+      # Generates an instance of parsed tags from the provided arguments by merging tag arguments
+      #   that were provided via either flags or keywords
+      # @param provided [Array<String>] tag arguments provided
       #   directly via the -t or --tags flag on the command line.
-      # @param keywords: Reviewer.arguments.keywords [Array, String] keywords that can potentially
+      # @param keywords [Array, String] keywords that can potentially
       #   be translated to a list of tags based on the tags used in the configuration file
       #
-      # @return [Arguments::Tags] the container for extracting tags from the provided command line
-      #   arguments
-      def initialize(provided: Reviewer.arguments.tags.raw, keywords: Reviewer.arguments.keywords.for_tags)
+      # @example Using keywords: `rvw ruby` (assuming a 'ruby' tag is defined)
+      #   Reviewer::Arguments::Tags.new.to_a # => ['ruby']
+      # @example Using the `-t` flag: `rvw -t ruby`
+      #   Reviewer::Arguments::Tags.new.to_a # => ['ruby']
+      # @example Using the `--tags` flag: `rvw -t ruby,css`
+      #   Reviewer::Arguments::Tags.new.to_a # => ['css', 'ruby']
+      #
+      # @return [self]
+      def initialize(provided: [], keywords: [])
         @provided = Array(provided)
         @keywords = Array(keywords)
       end
@@ -24,16 +35,12 @@ module Reviewer
       # Provides the full list of tags values derived from the command-line arguments
       #
       # @return [Array<String>] full collection of the tag arguments as a string
-      def to_a
-        tag_list
-      end
+      def to_a = tag_list
 
       # Provides the full list of tag values derived from the command-line arguments
       #
       # @return [String] comma-separated string of the derived tag values
-      def to_s
-        to_a.join(',')
-      end
+      def to_s = to_a.join(',')
 
       # Summary of the state of the tag arguments
       #
@@ -49,7 +56,7 @@ module Reviewer
       private
 
       # Combines the sorted list of unique tags by merging the explicitly-provided tag arguments
-      # as well as those that were recognized from any relevant keyword arguments.
+      #   as well as those that were recognized from any relevant keyword arguments.
       #
       # @return [Array] full list of tags passed via command-line including those matching keyword
       #   arguments

data/lib/reviewer/arguments.rb

@@ -19,32 +19,60 @@ module Reviewer
   #   `rvw ruby staged`
   #
   class Arguments
-    attr_accessor :options
+    # Valid output format options for the --format flag
+    KNOWN_FORMATS = %i[streaming summary json].freeze
+
+    # @!attribute options
+    #   @return [Slop::Result] the parsed command-line options
+    attr_reader :options
 
     attr_reader :output
 
-    # A catch all for aguments passed to reviewer via the command-line.
-    # @param options = ARGV [Hash] options to parse and extract the relevant values for a run
+    # Parses command-line arguments and makes them available as tags, files, and keywords.
+    # @param options [Array<String>] the command-line arguments to parse (defaults to ARGV)
+    # @param output [Output] the console output handler for displaying messages
+    #
+    # @example Using all options: `rvw keyword_one keyword_two --files ./example.rb,./example_test.rb --tags syntax`
+    #   reviewer = Reviewer::Arguments.new
+    #   reviewer.files.to_a # => ['./example.rb','./example_test.rb']
+    #   reviewer.tags.to_a # => ['syntax']
+    #   reviewer.keywords.to_a # => ['keyword_one', 'keyword_two']
     #
-    # @return [Reviewer::Arguments] the full collection of arguments provided via the command line
-    def initialize(options = ARGV)
-      @output = Output.new
-      @options = Slop.parse options do |opts|
-        opts.array '-f', '--files', 'a list of comma-separated files or paths', delimiter: ',', default: []
-        opts.array '-t', '--tags', 'a list of comma-separated tags', delimiter: ',', default: []
-
-        opts.on '-v', '--version', 'print the version' do
-          @output.info VERSION
-          exit
-        end
-
-        opts.on '-h', '--help', 'print the help' do
-          @output.info opts
-          exit
-        end
-      end
+    # @return [self]
+    def initialize(options = ARGV, output: Output.new)
+      @output = output
+      @options = Slop.parse(options) { |opts| configure_options(opts) }
+    end
+
+    private
+
+    def configure_options(opts)
+      configure_input_options(opts)
+      configure_output_options(opts)
+      configure_info_options(opts)
+    end
+
+    def configure_input_options(opts)
+      opts.array '-f', '--files', 'a list of comma-separated files or paths', delimiter: ',', default: []
+      opts.array '-t', '--tags', 'a list of comma-separated tags', delimiter: ',', default: []
+    end
+
+    def configure_output_options(opts)
+      opts.on '-r', '--raw', 'force raw output (no capturing)'
+      opts.on '-j', '--json', 'output results as JSON'
+      opts.string '--format', 'output format (streaming, summary, json)', default: 'streaming'
+    end
+
+    def configure_info_options(opts)
+      opts.on('-v', '--version', 'print the version')
+      opts.on('-h', '--help', 'print the help')
+      opts.on('-c', '--capabilities', 'output capabilities as JSON')
     end
 
+    def session_formatter = @session_formatter ||= Session::Formatter.new(output)
+
+    public
+
     # Converts the arguments to a hash for versatility
     #
     # @return [Hash] The files, tags, and keywords collected from the command line options
@@ -59,23 +87,73 @@ module Reviewer
 
     # The tag arguments collected from the command line via the `-t` or `--tags` flag
     #
-    # @return [Arguments::Tags] an colelction of the tag arguments collected from the command-line
-    def tags
-      @tags ||= Arguments::Tags.new(provided: options[:tags])
-    end
+    # @return [Arguments::Tags] a collection of the tag arguments collected from the command-line
+    def tags = @tags ||= Arguments::Tags.new(provided: options[:tags])
 
     # The file arguments collected from the command line via the `-f` or `--files` flag
     #
-    # @return [Arguments::Files] an collection of the file arguments collected from the command-line
+    # @return [Arguments::Files] a collection of the file arguments collected from the command-line
     def files
-      @files ||= Arguments::Files.new(provided: options[:files])
+      @files ||= Arguments::Files.new(
+        provided: options[:files],
+        keywords: keywords.reserved,
+        output: output,
+        on_git_error: session_formatter.method(:git_error)
+      )
     end
 
     # The leftover arguments collected from the command line without being associated with a flag
     #
-    # @return [Arguments::Keywords] an collection of the leftover arguments as keywords
-    def keywords
-      @keywords ||= Arguments::Keywords.new(options.arguments)
+    # @return [Arguments::Keywords] a collection of the leftover arguments as keywords
+    def keywords = @keywords ||= Arguments::Keywords.new(options.arguments)
+
+    # Whether the --help flag was passed
+    #
+    # @return [Boolean] true if help was requested
+    def help? = options[:help]
+
+    # Whether the --version flag was passed
+    #
+    # @return [Boolean] true if version was requested
+    def version? = options[:version]
+
+    # Whether to force raw/passthrough output regardless of tool count
+    #
+    # @return [Boolean] true if raw output mode is requested
+    def raw? = options[:raw]
+
+    # Whether to output results as JSON
+    #
+    # @return [Boolean] true if JSON output mode is requested
+    def json? = options[:json]
+
+    # The output format for results
+    #
+    # @return [Symbol] the output format (:streaming, :summary, or :json)
+    def format
+      return :json if json?
+
+      value = options[:format].to_sym
+      return value if KNOWN_FORMATS.include?(value)
+
+      session_formatter.invalid_format(options[:format], KNOWN_FORMATS)
+      :streaming
+    end
+
+    # Whether output should be streamed directly (not captured for later formatting)
+    #
+    # @return [Boolean] true if in streaming mode
+    def streaming? = format == :streaming
+
+    # Determines the appropriate runner strategy based on CLI flags
+    #
+    # @param multiple_tools [Boolean] whether multiple tools are being run
+    # @return [Class] the strategy class (Captured or Passthrough)
+    def runner_strategy(multiple_tools:)
+      return Runner::Strategies::Passthrough if raw?
+      return Runner::Strategies::Captured unless streaming?
+
+      multiple_tools ? Runner::Strategies::Captured : Runner::Strategies::Passthrough
     end
   end
 end

data/lib/reviewer/batch/formatter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative '../output/formatting'
+
+module Reviewer
+  class Batch
+    # Display logic for batch execution: summary, run preview, missing tools
+    class Formatter
+      include Output::Formatting
+
+      attr_reader :output, :printer
+      private :output, :printer
+
+      # Creates a formatter for batch execution display
+      # @param output [Output] the console output handler
+      #
+      # @return [Formatter]
+      def initialize(output)
+        @output = output
+        @printer = output.printer
+      end
+
+      # Displays a one-line success summary with timing and tool count
+      # @param tool_count [Integer] the number of tools that ran
+      # @param seconds [Float] total elapsed time in seconds
+      #
+      # @return [void]
+      def summary(tool_count, seconds)
+        output.newline
+        printer.print(:success, CHECKMARK)
+        printer.print(:muted, " ~#{seconds.round(1)} seconds")
+        printer.print(:muted, " for #{tool_count} tools") if tool_count > 1
+        output.newline
+      end
+
+      # Displays a preview of which tools will run and their target files
+      # @param entries [Array<Hash>] each with :name and :files keys
+      #
+      # @return [void]
+      def run_summary(entries)
+        return if entries.empty?
+
+        entries.each { |entry| print_run_entry(entry) }
+        output.newline
+      end
+
+      # Displays a list of tools whose executables were not found, with install hints
+      # @param missing [Array<Runner::Result>] the results for missing tools
+      # @param tools [Array<Tool>] the tools that were in the batch
+      #
+      # @return [void]
+      def missing_tools(missing, tools:)
+        output.newline
+        printer.puts(:warning, "#{missing.size} not installed:")
+        tool_lookup = tools.to_h { |tool| [tool.key, tool] }
+        missing.each { |result| print_missing_hint(result.tool_name, tool_lookup[result.tool_key]) }
+        output.newline
+      end
+
+      # Displays a message when `rvw failed` is used but no tools failed in the last run
+      #
+      # @return [void]
+      def no_failures_to_retry
+        printer.puts(:muted, 'No failures to retry')
+      end
+
+      # Displays a message when `rvw failed` is used but no previous run exists in history
+      #
+      # @return [void]
+      def no_previous_run
+        printer.puts(:muted, 'No previous run found')
+      end
+
+      private
+
+      def print_missing_hint(name, tool)
+        hint = tool&.installable? ? tool.install_command : ''
+        printer.puts(:muted, "  #{name.ljust(22)}#{hint}")
+      end
+
+      def print_run_entry(entry)
+        printer.puts(:muted, entry[:name])
+        entry[:files].each { |file| printer.puts(:muted, "  #{file}") }
+      end
+    end
+  end
+end