reviewer 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8754795211c60e4aff15d716db73abc4ecbbc55c99afda217ab56180dc74b35
-  data.tar.gz: 9d7172360cecb1439d2ae513053211027f064786d72ad59f3a4f8029fbbdb557
+  metadata.gz: 9e521c12a7d3f686337af0ad6dff4adb7e1c0f6e7ec49e05ed244931bf27d14f
+  data.tar.gz: 779c50bbe81345a91f80d31b5b9c269d283fc8e3b0d54f5193e8e01e4ca9b0d3
 SHA512:
-  metadata.gz: ebbf843d62775a5aa4c7ead5da403f9a368680a503782433e2674df6643a5b9911802e9663200fb39e184d26cffb25c166af6ceef340c5f8926efb5f7cbbec93
-  data.tar.gz: e48861c8fe35cf51877298cd97e177705022720f0576e4aa4dc1bd73dd9c4221ca27a676837e888eeff7bf4529e3c5418656ce8b78aba643025cee3a0ad6879e
+  metadata.gz: 764931418180d96bc1331f43a67c333b1788169f41584a3603684e1fbd1f801a00a72fc9a578a4052535327256281de299cb90d86419f1438ac4e7edc87bdab0
+  data.tar.gz: 4045484668eab50715cb5b1d61961db4ea9377a12c5e5bb1bd097425c7413cde923dc17cc6a1351b11d6f63336ebf1e33bdbbe2d6ccda0d130e447937d179a52

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [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

data/docs/usage.md

@@ -59,8 +59,16 @@ 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. File-aware tools retry those paths; tools without file support retry their
@@ -73,12 +81,13 @@ 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`, and `untracked` requests skip tools without a
-`files:` configuration instead of running their full-project command. Bare `rvw` remains the full
-configured review.
+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.

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/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/session/formatter.rb

@@ -10,6 +10,8 @@ module Reviewer
 
       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
 
@@ -25,31 +27,35 @@ 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: []
         }
@@ -80,6 +86,32 @@ module Reviewer
         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: []
+        }
+
+        printer.write_raw("#{JSON.pretty_generate(payload)}\n")
+      end
+
       # Displays a warning when an unrecognized output format is requested
       # @param value [String] the invalid format name
       # @param known [Array<Symbol>] the valid format options

data/lib/reviewer/session.rb

@@ -47,12 +47,18 @@ module Reviewer
     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
-      json_output? ? formatter.missing_files_option_json : formatter.missing_files_option
+    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
 
@@ -92,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.1'
+  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.
@@ -105,6 +109,16 @@ module Reviewer
       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
@@ -133,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:
@@ -144,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.1
+  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