reviewer 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d918dfc0f53f9d2283d846207fc760f0aa0cafaa2d9db0f2225396935cdbd38
-  data.tar.gz: 2f8635ce31fee7646608c5dd591c277190e918b3c940b773d04731254c3ea707
+  metadata.gz: 9e521c12a7d3f686337af0ad6dff4adb7e1c0f6e7ec49e05ed244931bf27d14f
+  data.tar.gz: 779c50bbe81345a91f80d31b5b9c269d283fc8e3b0d54f5193e8e01e4ca9b0d3
 SHA512:
-  metadata.gz: fc770176795e88d1c88e56903eb1ce3d756f0f46176edc1d1a280bff14069b0739a27a4aefa6ca04313c08f1324e3f9d45da86860c9563c97f7a82472005f7ca
-  data.tar.gz: dbfdb47cbc0c321bc2338251b4a16242d976d4b6fb893019e7dc5578d875bfc85ef4124297864fa50cbe52cf7189471e6fc2ece940e114cf92fe8ab0e429e369
+  metadata.gz: 764931418180d96bc1331f43a67c333b1788169f41584a3603684e1fbd1f801a00a72fc9a578a4052535327256281de299cb90d86419f1438ac4e7edc87bdab0
+  data.tar.gz: 4045484668eab50715cb5b1d61961db4ea9377a12c5e5bb1bd097425c7413cde923dc17cc6a1351b11d6f63336ebf1e33bdbbe2d6ccda0d130e447937d179a52

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [1.2.0] - 2026-09-24
+
+### Added
+
+- `branched` keyword: selects every file that differs from `origin/HEAD` since the current work split
+  from it, including uncommitted and new files, so a whole branch can be reviewed before a pull
+  request. It never substitutes another branch: when it can't compare against `origin/HEAD`, it
+  stops with a usage error that names the fix or shows Git's message.
+
+### Fixed
+
+- Report tool failures normally when a tool prints non-ASCII text under a non-UTF-8 locale (such as
+  `LC_ALL=C` or an unrecognized `LC_ALL`), or prints bytes that aren't valid UTF-8, instead of crashing
+  with an encoding error. Captured output is read as UTF-8 and invalid bytes are replaced.
+- Include files with non-ASCII names in `staged`, `unstaged`, `modified` and `untracked` runs. Git's
+  escaped path names previously never matched the real files, so those files were silently skipped,
+  and a non-UTF-8 locale could crash the run.
+- Report a mistyped or unsupported option, such as `rvw --list`, as a usage error with exit status 2
+  instead of crashing with a backtrace.
+- Describe `modified` accurately in `--capabilities` and `--help`: it covers tracked files changed
+  since the last commit and excludes untracked files.
+
+## [1.1.1] - 2026-09-02
+
+### Fixed
+
+- Keep explicit and Git-derived file-scoped runs focused by skipping tools that cannot accept files,
+  while preserving bare runs and failed retries; reject empty file options instead of running broadly.
+
 ## [1.1.0] - 2026-08-28
 
 Reviewer 1.1 makes review outcomes more precise and dependable for people and automated consumers.

data/docs/configuration.md

@@ -106,8 +106,11 @@ rubocop:
 | `files.pattern` | Keeps matching paths before the command runs |
 | `files.map_to_tests` | Maps Ruby source paths to existing `minitest` or `rspec` test paths |
 
-Only tools with a `files:` block receive resolved file arguments; tools without one run their
-configured command unchanged.
+Only tools with a `files:` block receive resolved file arguments. File-scoped requests skip tools
+without one so `rvw staged`, `rvw modified`, and `rvw -f ...` cannot expand into full-project checks.
+Bare `rvw` still runs every tool in the default batch. See the
+[file-scoped behavior matrix](usage.md#file-scoped-behavior) for explicit scopes, composed Git
+selectors, and failed-run precedence.
 
 Slashless patterns match each path's basename. Patterns containing `/` match normalized
 repository-relative paths with pathname semantics. In path patterns, `**/` crosses directory

data/docs/usage.md

@@ -59,22 +59,36 @@ File selectors resolve paths from Git:
 |---|---|
 | `staged` | Staged changes |
 | `unstaged` | Unstaged changes |
-| `modified` | Staged and unstaged changes compared with `HEAD` |
+| `modified` | Tracked files changed since the last commit (staged and unstaged); excludes untracked files |
 | `untracked` | Untracked, non-ignored files |
+| `branched` | Every file that differs from `origin/HEAD` since this work split from it, including uncommitted and new files |
+
+`branched` always compares against `origin/HEAD` and never substitutes another branch. When it
+can't, it stops with a usage error rather than reviewing nothing:
+
+- If `origin/HEAD` isn't set, run `git remote set-head origin --auto`.
+- In a shallow clone, such as a default CI checkout, fetch the default branch with its history
+  (for example, `fetch-depth: 0`).
 
 `failed` selects tools whose last executed review failed and, when available, reuses each tool's
-stored failed file paths. A tool remains selected until an executed review records a pass. Skipped,
-missing, formatted, and not-run tools leave that review history unchanged, so a passing scoped run
-can coexist with tools still selected by `rvw failed`.
+stored failed file paths. File-aware tools retry those paths; tools without file support retry their
+full command. A tool remains selected until an executed review records a pass. Skipped, missing,
+formatted, and not-run tools leave that review history unchanged, so a passing scoped run can coexist
+with tools still selected by `rvw failed`.
 
 Selections compose:
 
 ```console
 rvw rubocop staged
 rvw -t ruby modified
+rvw rubocop branched
 rvw tests -f test/reviewer_test.rb
 ```
 
+Explicit `-f`, `staged`, `unstaged`, `modified`, `untracked`, and `branched` requests skip tools
+without a `files:` configuration instead of running their full-project command. Bare `rvw` remains
+the full configured review.
+
 The [configuration reference](configuration.md#file-targeting) describes filtering, file-scoped
 commands, and Minitest/RSpec source-to-test mapping.
 
@@ -117,7 +131,7 @@ State describes the terminal disposition Reviewer acts on. For executed failures
 |---|---|---:|---|
 | `passed` | The command executed within its configured threshold | `true` | None |
 | `failed` | The command executed outside its configured threshold | `false` | Exit `1` |
-| `skipped` | Requested files did not match the tool | `false` | None |
+| `skipped` | The tool cannot accept the file scope, or no requested files matched | `false` | None |
 | `missing` | The executable was unavailable | `false` | None in 1.1 |
 | `not_run` | An earlier tool failed and fail-fast stopped the batch | `false` | None |
 
@@ -161,7 +175,10 @@ Every summary contains `total`, all five state counts, and `duration`; the state
 |---|---|---|
 | Nonempty report | `schema_version`, `success`, `summary`, `tools` | `state`, `message`, `error` |
 | Empty report | `schema_version`, `state: "empty"`, `success: true`, `message`, zero summary, `tools: []` | `error` |
-| Selector error | `schema_version`, `state: "error"`, `error`, zero summary, `tools: []` | `success`, `message` |
+| Usage error | `schema_version`, `state: "error"`, `error`, zero summary, `tools: []` | `success`, `message` |
+
+Usage errors include `error.code: "unrecognized_selector"` for an unknown tool, tag, or keyword and
+`error.code: "missing_files"` for an empty or missing `-f`/`--files` value.
 
 | Tool state | Execution fields | Compatibility flags |
 |---|---|---|
@@ -175,13 +192,31 @@ tool now has `success: false`, and its unavailable execution fields are null ins
 omitted. Valid 1.x `Runner::Result.new` keyword calls and the legacy true-valued payload flags remain
 supported through the 1.x line.
 
+## File-scoped behavior
+
+| Request | Tools with `files:` | Tools without `files:` |
+|---|---|---|
+| `rvw` | Run without a file filter | Run without a file filter |
+| `rvw -f app/a.rb` | Run with `app/a.rb` | Skip |
+| `rvw staged untracked` | Run with the deduplicated union | Skip |
+| `rvw staged` with no staged files | Do not run | Do not run |
+| `rvw failed` | Use stored failed paths when available; otherwise retry without a file filter | Retry without a file filter |
+| `rvw failed staged` | Use the newly resolved staged paths instead of stored paths | Skip |
+| `rvw failed -f app/a.rb` | Use `app/a.rb` instead of stored paths | Skip |
+
+Repeated `-f` options and Git selectors compose. For review and format execution, every `-f` or
+`--files` occurrence requires at least one path; an empty or missing value exits 2 without running
+any tool. Informational `--help` and `--version` requests, plus the `init` and `doctor` control
+commands, exit before file-scope validation. A valid Git selector that finds no files is instead a
+successful no-op because the selector itself was complete.
+
 ## Exit statuses
 
 | Status | Meaning |
 |---|---|
 | `0` | Every executed tool passed; skipped, missing, and not-run tools do not fail the run |
 | `1` | At least one executed tool failed |
-| `2` | The request used an unrecognized tool, tag, or keyword |
+| `2` | The request used an unrecognized selector or an empty `-f`/`--files` option |
 
 A tool may pass with a nonzero process status when its `commands.max_exit_status` allows it. Reviewer
 returns its own status above instead of forwarding the tool's process status.

data/lib/reviewer/arguments/files/branched_files.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Reviewer
+  class Arguments
+    class Files
+      # Selects the files for the `branched` keyword: every file that differs from origin/HEAD since
+      # this work split from it, including uncommitted and new files. It compares against origin/HEAD
+      # only, so when any git step fails, `missing` says why and no files are selected rather than
+      # substituting another branch or reviewing nothing.
+      class BranchedFiles
+        # The problem, then how to fix it. An unexpected git error has no known fix, so git's own
+        # message is shown instead.
+        MISSING_MESSAGES = {
+          origin_head: [
+            "Can't compare against origin/HEAD: origin/HEAD isn't set",
+            'Run `git remote set-head origin --auto`, then try again.'
+          ],
+          merge_base: [
+            "Can't find where this work split from origin/HEAD",
+            'Fetch the default branch with its history (for example, `fetch-depth: 0` in CI), then try again.'
+          ],
+          git_error: ["Git couldn't list the files that differ from origin/HEAD"]
+        }.freeze
+
+        # Why the files couldn't be selected. `reason` is :origin_head when origin/HEAD isn't set,
+        # :merge_base when HEAD shares no history with it (as in a shallow clone), or :git_error for
+        # any other git failure, whose message is kept in `detail`.
+        Missing = Struct.new(:reason, :detail) do
+          # @return [String] what went wrong
+          def problem = MISSING_MESSAGES.fetch(reason).first
+
+          # @return [String, nil] how to fix it, or git's message for an unexpected error
+          def fix = MISSING_MESSAGES.fetch(reason)[1] || detail
+
+          # @return [String] the problem and its fix as one line
+          def message = "#{problem}. #{fix}"
+        end
+
+        # @!attribute [r] files
+        #   @return [Array<String>] the selected paths, empty when `missing` is set
+        # @!attribute [r] missing
+        #   @return [Missing, nil] why the files couldn't be selected, or nil when they were
+        attr_reader :files, :missing
+
+        # Runs every git step immediately so both attributes reflect the same git state
+        #
+        # @return [self]
+        def initialize
+          @missing = nil
+          @files = select || []
+        end
+
+        private
+
+        def select
+          merge_base = find_merge_base
+          changed = merge_base && lookup(%W[diff --name-only #{merge_base}])
+          untracked = changed && lookup(%w[ls-files --others --exclude-standard])
+          return unless untracked
+
+          (changed.split("\n") + untracked.split("\n")).reject(&:empty?)
+        end
+
+        def find_merge_base
+          lookup(%w[rev-parse --verify --quiet refs/remotes/origin/HEAD], when_absent: :origin_head) &&
+            lookup(%w[merge-base HEAD origin/HEAD], when_absent: :merge_base)
+        end
+
+        # Git exits 1 when a ref or merge base doesn't exist. Any other failure is reported with git's
+        # own message, since the fix for an absent ref wouldn't apply to it. Output is read as UTF-8
+        # with paths unescaped, like the other git keywords.
+        def lookup(options, when_absent: :git_error)
+          stdout, stderr, status = Open3.capture3('git', '-c', 'core.quotePath=false', '--no-pager', *options)
+          case status.exitstatus
+          when 0 then Shell::Result.decode(stdout).strip
+          when 1 then record_missing(when_absent, stderr)
+          else record_missing(:git_error, stderr)
+          end
+        end
+
+        # Only an unexpected error keeps git's message; an absent ref or merge base has a known fix
+        def record_missing(reason, stderr)
+          detail = (Shell::Result.decode(stderr).lines.first&.strip if reason == :git_error)
+          @missing = Missing.new(reason, detail)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/arguments/files.rb

@@ -2,6 +2,8 @@
 
 require 'open3'
 
+require_relative 'files/branched_files'
+
 module Reviewer
   class Arguments
     # Generates a Ruby-friendly list (Array) of files to run the command against from the provided
@@ -56,6 +58,15 @@ module Reviewer
       end
       alias inspect to_h
 
+      # Why `branched` couldn't select files. `branched` never substitutes another ref, so the
+      # caller reports this instead of reviewing nothing.
+      #
+      # @return [BranchedFiles::Missing, nil] why the files couldn't be selected, or nil when they
+      #   were or `branched` wasn't requested
+      def missing_base
+        branched_files.missing if keywords.include?('branched')
+      end
+
       private
 
       # Combines the sorted list of unique files/paths by merging the explicitly-provided file
@@ -101,15 +112,21 @@ module Reviewer
         git_files(%w[ls-files --others --exclude-standard])
       end
 
-      # Executes a git command and returns the output as an array of file paths
+      def branched = branched_files.files
+
+      def branched_files = @branched_files ||= BranchedFiles.new
+
+      # Executes a git command and returns the output as an array of file paths. Git escapes
+      # non-ASCII paths unless `core.quotePath` is off, and its output is read as UTF-8 like any
+      # other command output so the paths match the real files regardless of locale.
       # @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(' ')
+        command = (%w[git -c core.quotePath=false --no-pager] + options).join(' ')
         stdout, stderr, status = Open3.capture3(command)
 
-        return stdout.split("\n").reject(&:empty?) if status.success?
+        return Shell::Result.decode(stdout).split("\n").reject(&:empty?) if status.success?
 
         raise SystemCallError.new("Git Error: #{stderr} (#{command})", status.exitstatus.to_i)
       rescue SystemCallError => e

data/lib/reviewer/arguments/keywords.rb

@@ -10,7 +10,7 @@ module Reviewer
     class Keywords
       # Keywords that resolve to a list of files. `Arguments::Files` implements one method per
       # entry, so a keyword here without a matching method silently contributes nothing.
-      FOR_FILES = %w[staged unstaged modified untracked].freeze
+      FOR_FILES = %w[staged unstaged modified untracked branched].freeze
 
       # Keywords that select tools rather than files. `failed` reads `last_status` from history via
       # `Tools#failed_from_history`; the per-tool file scope comes from `Command#stored_failed_files`.

data/lib/reviewer/arguments/options.rb

@@ -15,9 +15,10 @@ module Reviewer
       #
       # @return [void]
       # :reek:TooManyStatements -- a flag declaration list, not branching logic
-      def configure(opts)
+      def configure(opts, files_callback: nil)
         # Narrowing what gets reviewed
-        opts.array '-f', '--files', 'a list of comma-separated files or paths', delimiter: ',', default: []
+        opts.array '-f', '--files', 'a list of comma-separated files or paths',
+                   delimiter: ',', default: [], &files_callback
         opts.array '-t', '--tags', 'a list of comma-separated tags', delimiter: ',', default: []
 
         # Selecting how results are displayed

data/lib/reviewer/arguments.rb

@@ -42,7 +42,11 @@ module Reviewer
     # @return [self]
     def initialize(options = ARGV, output: Output.new)
       @output = output
-      @options = Slop.parse(options) { |opts| Options.configure(opts) }
+      @raw_options = options.to_a.dup
+      @invalid_files_option = false
+      @parser = Slop::Options.new
+      Options.configure(@parser, files_callback: files_validation_callback)
+      @options = @parser.parse(normalized_options)
     end
 
     private
@@ -105,6 +109,16 @@ module Reviewer
     # @return [Boolean] true if JSON output mode is requested
     def json? = options[:json]
 
+    # Whether the --capabilities flag was passed
+    #
+    # @return [Boolean] true if capabilities were requested
+    def capabilities? = options[:capabilities]
+
+    # Whether a files option was supplied without a usable value
+    #
+    # @return [Boolean] true when any -f/--files occurrence is empty
+    def invalid_files_option? = @invalid_files_option
+
     # The output format for results
     #
     # @return [Symbol] the output format (:streaming, :summary, or :json)
@@ -114,7 +128,7 @@ module Reviewer
       value = options[:format].to_sym
       return value if KNOWN_FORMATS.include?(value)
 
-      session_formatter.invalid_format(options[:format], KNOWN_FORMATS)
+      session_formatter.invalid_format(options[:format], KNOWN_FORMATS) unless invalid_files_option?
       :streaming
     end
 
@@ -133,5 +147,53 @@ module Reviewer
 
       multiple_tools ? Runner::Strategies::Captured : Runner::Strategies::Passthrough
     end
+
+    private
+
+    def files_validation_callback
+      previous_file_count = 0
+      lambda do |files|
+        current_files = Array(files)
+        file_count = current_files.length
+        new_files = current_files.drop(previous_file_count)
+        @invalid_files_option = true if file_count <= previous_file_count ||
+                                        new_files.all? { |file| file.strip.empty? }
+        previous_file_count = file_count
+      end
+    end
+
+    def normalized_options
+      parsing_options = true
+      @raw_options.each_with_index.flat_map do |token, index|
+        parsing_options = false if token == '--'
+        missing_value = parsing_options && files_option_awaiting_value?(token) &&
+                        known_option_token?(@raw_options[index + 1])
+        normalized_token = parsing_options ? normalize_compact_files_option(token) : token
+
+        missing_value ? [normalized_token, ''] : [normalized_token]
+      end
+    end
+
+    def normalize_compact_files_option(token)
+      return token unless token.start_with?('-f') && token.length > 2 && !token.start_with?('-f=')
+
+      "-f=#{token.delete_prefix('-f')}"
+    end
+
+    def known_option_token?(token)
+      return false unless token&.start_with?('-') && token != '--'
+
+      Slop.parse([token]) { |opts| Options.configure(opts) }
+      true
+    rescue Slop::UnknownOption
+      false
+    end
+
+    def files_option_awaiting_value?(token)
+      return true if %w[-f --files].include?(token)
+      return false if token.start_with?('-f')
+
+      token.match?(/\A-[^-]+f\z/) && known_option_token?(token)
+    end
   end
 end

data/lib/reviewer/batch.rb

@@ -34,7 +34,7 @@ module Reviewer
       runnable_tools = matching_tools
       elapsed_time = Benchmark.realtime do
         failed_index = runnable_tools.find_index { |tool| run_tool(tool).failed? }
-        record_not_run(runnable_tools.drop(failed_index + 1)) if failed_index
+        record_remaining(runnable_tools.drop(failed_index + 1)) if failed_index
       end
 
       @report.record_duration(elapsed_time)
@@ -43,8 +43,13 @@ module Reviewer
 
     private
 
-    def record_not_run(tools)
+    def record_remaining(tools)
       tools.each do |tool|
+        if Command.new(tool, command_type, context: context).skip?
+          run_tool(tool)
+          next
+        end
+
         result = Runner::Result.not_run(tool: tool, command_type: command_type)
         @report.add(result)
       end

data/lib/reviewer/capabilities.rb

@@ -26,8 +26,10 @@ module Reviewer
     KEYWORD_DESCRIPTIONS = {
       'staged' => 'Files staged for commit',
       'unstaged' => 'Files with unstaged changes',
-      'modified' => 'All changed files',
+      'modified' => 'Tracked files changed since the last commit (staged and unstaged); excludes untracked files',
       'untracked' => 'New files not yet tracked',
+      'branched' => 'Every file that differs from origin/HEAD since this work split from it, ' \
+                    'including uncommitted and new files',
       'failed' => 'Tools whose last executed review failed and have not passed since'
     }.freeze
 
@@ -38,6 +40,7 @@ module Reviewer
     SCENARIOS = {
       before_commit: 'rvw staged',
       during_development: 'rvw modified',
+      before_pull_request: 'rvw branched',
       full_review: 'rvw'
     }.freeze
 

data/lib/reviewer/command.rb

@@ -73,10 +73,12 @@ module Reviewer
       @target_files ||= tool.resolve_files(requested_files)
     end
 
-    # Determines if this command should be skipped because files were requested but none match
+    # Determines if this command should be skipped for the requested file scope
     #
-    # @return [Boolean] true if files were requested but resolution left none for this tool
+    # @return [Boolean] true if the tool cannot accept an explicit file scope or no files match it
     def skip?
+      return true if explicit_files.any? && !tool.supports_files?
+
       tool.skip_files?(requested_files)
     end
 
@@ -97,16 +99,15 @@ module Reviewer
     #
     # @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
+      @requested_files ||= if explicit_files.empty? && arguments.keywords.failed?
+                             stored_failed_files
+                           else
+                             explicit_files
+                           end
     end
 
+    def explicit_files = @explicit_files ||= arguments.files.to_a
+
     # Retrieves failed files stored from the last executed review for this tool
     #
     # @return [Array<String>] stored failed file paths, or empty array

data/lib/reviewer/session/formatter.rb

@@ -8,6 +8,10 @@ module Reviewer
     class Formatter
       include Output::Formatting
 
+      MISSING_FILES_MESSAGE = 'The --files option requires at least one file or path.'
+
+      BRANCHED_HINT = "'branched' always compares against origin/HEAD and doesn't take a branch name"
+
       attr_reader :output, :printer
       private :output, :printer
 
@@ -23,31 +27,84 @@ module Reviewer
       # Displays warnings for keywords that don't match any tool or git scope
       # @param unrecognized [Array<String>] the unrecognized keyword strings
       # @param suggestions [Hash{String => String}] keyword => suggested correction
+      # @param hint [String, nil] a closing note about how the request was misread
       #
       # @return [void]
-      def unrecognized_keywords(unrecognized, suggestions)
+      def unrecognized_keywords(unrecognized, suggestions, hint = nil)
         unrecognized.each do |keyword|
           printer.puts(:warning, "Unrecognized: #{keyword}")
           suggestion = suggestions[keyword]
           printer.puts(:muted, "  did you mean '#{suggestion}'?") if suggestion
         end
+        printer.puts(:muted, hint) if hint
         output.newline
       end
 
       # Renders a machine-readable envelope for a name Reviewer cannot honour
       # @param unrecognized [Array<String>] the names that matched nothing
       # @param suggestions [Hash] closest known name per unrecognized name
+      # @param hint [String, nil] a note about how the request was misread, omitted when nil
       #
       # @return [void]
-      def unrecognized_keywords_json(unrecognized, suggestions)
+      def unrecognized_keywords_json(unrecognized, suggestions, hint = nil)
         payload = {
           schema_version: Report::SCHEMA_VERSION,
           state: 'error',
           error: {
             code: 'unrecognized_selector',
             message: "Unrecognized: #{unrecognized.join(', ')}",
-            suggestions: suggestions
-          },
+            suggestions: suggestions,
+            hint: hint
+          }.compact,
+          summary: Report.empty_summary,
+          tools: []
+        }
+
+        printer.write_raw("#{JSON.pretty_generate(payload)}\n")
+      end
+
+      # Displays a usage error when -f/--files has no value
+      #
+      # @return [void]
+      def missing_files_option
+        printer.puts(:warning, MISSING_FILES_MESSAGE)
+        output.newline
+      end
+
+      # Renders the machine-readable form of the missing files usage error
+      #
+      # @return [void]
+      def missing_files_option_json
+        payload = {
+          schema_version: Report::SCHEMA_VERSION,
+          state: 'error',
+          error: { code: 'missing_files', message: MISSING_FILES_MESSAGE },
+          summary: Report.empty_summary,
+          tools: []
+        }
+
+        printer.write_raw("#{JSON.pretty_generate(payload)}\n")
+      end
+
+      # Displays a usage error when `branched` can't find where the work split from origin/HEAD
+      # @param missing [Arguments::Files::BranchedFiles::Missing] why the branched files couldn't be selected
+      #
+      # @return [void]
+      def missing_base(missing)
+        printer.puts(:warning, missing.problem)
+        printer.puts(:muted, missing.fix)
+        output.newline
+      end
+
+      # Renders the machine-readable form of the missing base usage error
+      # @param missing [Arguments::Files::BranchedFiles::Missing] why the branched files couldn't be selected
+      #
+      # @return [void]
+      def missing_base_json(missing)
+        payload = {
+          schema_version: Report::SCHEMA_VERSION,
+          state: 'error',
+          error: { code: 'missing_base', message: missing.message },
           summary: Report.empty_summary,
           tools: []
         }

data/lib/reviewer/session.rb

@@ -45,11 +45,23 @@ module Reviewer
     def history = context.history
 
     def run_tools(command_type)
+      return reject_invalid_files_option if arguments.invalid_files_option?
       return reject_unrecognized_selectors if unrecognized_selectors.any?
+      return reject_missing_base if arguments.files.missing_base
 
       json_output? ? run_json(command_type) : run_text(command_type)
     end
 
+    def reject_invalid_files_option = reject_as_usage_error(:missing_files_option)
+
+    def reject_missing_base = reject_as_usage_error(:missing_base, arguments.files.missing_base)
+
+    # Renders a usage error through the formatter's text or JSON form, then returns its status
+    def reject_as_usage_error(formatter_method, *)
+      formatter.public_send(json_output? ? :"#{formatter_method}_json" : formatter_method, *)
+      USAGE_ERROR
+    end
+
     def run_json(command_type)
       message = json_early_exit_message
       return emit_json_early_exit(message) if message
@@ -86,15 +98,11 @@ module Reviewer
     # attributing that success to a tool that never ran.
     def reject_unrecognized_selectors
       names = unrecognized_selectors
-      suggestions = build_suggestions(names)
-
-      if json_output?
-        formatter.unrecognized_keywords_json(names, suggestions)
-      else
-        formatter.unrecognized_keywords(names, suggestions)
-      end
+      reject_as_usage_error(:unrecognized_keywords, names, build_suggestions(names), unrecognized_selector_hint)
+    end
 
-      USAGE_ERROR
+    def unrecognized_selector_hint
+      Session::Formatter::BRANCHED_HINT if arguments.files.keywords.include?('branched')
     end
 
     # Positional selectors and `-t` values are the same request spelled two ways,

data/lib/reviewer/shell/result.rb

@@ -42,12 +42,21 @@ module Reviewer
       #
       # @return [self]
       def initialize(stdout = nil, stderr = nil, status = nil)
-        @stdout = stdout
-        @stderr = stderr
+        @stdout = self.class.decode(stdout)
+        @stderr = self.class.decode(stderr)
         @status = status
         @exit_status = status&.exitstatus
       end
 
+      # Ruby labels command output with the locale's encoding, which is US-ASCII under `LC_ALL=C`
+      # or an unrecognized locale. Tools overwhelmingly emit UTF-8, so output is read as UTF-8
+      # regardless of locale, and bytes that aren't valid UTF-8 are replaced so that later string
+      # operations can't raise. Passthrough output reaches the terminal before this, unchanged.
+      # @param text [String, nil] raw output from a command
+      #
+      # @return [String, nil] valid UTF-8 text
+      def self.decode(text) = text && String.new(text, encoding: Encoding::UTF_8).scrub
+
       def exists? = [stdout, stderr, exit_status].compact.any?
 
       # Determines if re-running a command is entirely futile. Primarily to help when a command

data/lib/reviewer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reviewer
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/lib/reviewer.rb

@@ -41,6 +41,8 @@ module Reviewer
     # @return [void] Prints output to the console
     def review
       handle_early_exits { exit build_session.review }
+    rescue Slop::Error => e
+      reject_invalid_option(e.message)
     end
 
     # Runs the `format` command for the specified tools/files for which it is configured.
@@ -48,6 +50,8 @@ module Reviewer
     # @return [void] Prints output to the console
     def format
       handle_early_exits { exit build_session.format }
+    rescue Slop::Error => e
+      reject_invalid_option(e.message)
     end
 
     # The collection of arguments that were passed via the command line.
@@ -100,13 +104,28 @@ module Reviewer
       return Setup.run(configuration: configuration) if subcommand?(:init)
       return run_doctor if subcommand?(:doctor)
       return run_capabilities if capabilities_flag?
-      return run_first_time_setup unless configuration.file.exist?
+      return run_first_time_setup if first_time_setup?
 
       yield
     end
 
+    # A mistyped or unsupported option is a usage error, not a crash
+    # @param message [String] the parser's description of the invalid option
+    #
+    # @return [void]
+    def reject_invalid_option(message)
+      output.printer.puts(:warning, message)
+      output.printer.puts(:muted, 'Run `rvw --help` for usage.')
+      exit Session::USAGE_ERROR
+    end
+
+    def first_time_setup? = !arguments.invalid_files_option? && !configuration.file.exist?
+
     def subcommand?(name) = ARGV.first == name.to_s
-    def capabilities_flag? = ARGV.include?('--capabilities') || ARGV.include?('-c')
+
+    def capabilities_flag?
+      !arguments.invalid_files_option? && arguments.capabilities?
+    end
 
     def show_help
       output.help(help_text)
@@ -128,8 +147,9 @@ module Reviewer
         Keywords:
             staged                       Files staged for commit
             unstaged                     Files with unstaged changes
-            modified                     All changed files (staged + unstaged)
+            modified                     Tracked files changed since the last commit
             untracked                    New files not yet tracked by git
+            branched                     All files that differ from origin/HEAD, including new ones
             failed                       Re-run tools whose last executed review failed
 
         Options:
@@ -139,6 +159,7 @@ module Reviewer
             rvw rubocop                  Run RuboCop only
             rvw staged                   Review staged files across all tools
             rvw -t security modified     Run security-tagged tools on changed files
+            rvw branched                 Review everything this branch changes before a PR
             rvw tests -f test/user_test.rb   Run tests on a specific file
             rvw failed                   Re-run tools whose last executed review failed
             fmt rubocop                  Auto-fix with RuboCop

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reviewer
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Garrett Dimon
@@ -190,6 +190,7 @@ files:
 - lib/reviewer.rb
 - lib/reviewer/arguments.rb
 - lib/reviewer/arguments/files.rb
+- lib/reviewer/arguments/files/branched_files.rb
 - lib/reviewer/arguments/keywords.rb
 - lib/reviewer/arguments/options.rb
 - lib/reviewer/arguments/tags.rb