reviewer 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d918dfc0f53f9d2283d846207fc760f0aa0cafaa2d9db0f2225396935cdbd38
-  data.tar.gz: 2f8635ce31fee7646608c5dd591c277190e918b3c940b773d04731254c3ea707
+  metadata.gz: f8754795211c60e4aff15d716db73abc4ecbbc55c99afda217ab56180dc74b35
+  data.tar.gz: 9d7172360cecb1439d2ae513053211027f064786d72ad59f3a4f8029fbbdb557
 SHA512:
-  metadata.gz: fc770176795e88d1c88e56903eb1ce3d756f0f46176edc1d1a280bff14069b0739a27a4aefa6ca04313c08f1324e3f9d45da86860c9563c97f7a82472005f7ca
-  data.tar.gz: dbfdb47cbc0c321bc2338251b4a16242d976d4b6fb893019e7dc5578d875bfc85ef4124297864fa50cbe52cf7189471e6fc2ece940e114cf92fe8ab0e429e369
+  metadata.gz: ebbf843d62775a5aa4c7ead5da403f9a368680a503782433e2674df6643a5b9911802e9663200fb39e184d26cffb25c166af6ceef340c5f8926efb5f7cbbec93
+  data.tar.gz: e48861c8fe35cf51877298cd97e177705022720f0576e4aa4dc1bd73dd9c4221ca27a676837e888eeff7bf4529e3c5418656ce8b78aba643025cee3a0ad6879e

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [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

@@ -63,9 +63,10 @@ File selectors resolve paths from Git:
 | `untracked` | Untracked, non-ignored files |
 
 `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:
 
@@ -75,6 +76,10 @@ rvw -t ruby modified
 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.
+
 The [configuration reference](configuration.md#file-targeting) describes filtering, file-scoped
 commands, and Minitest/RSpec source-to-test mapping.
 
@@ -117,7 +122,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 +166,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 +183,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/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/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,8 @@ module Reviewer
     class Formatter
       include Output::Formatting
 
+      MISSING_FILES_MESSAGE = 'The --files option requires at least one file or path.'
+
       attr_reader :output, :printer
       private :output, :printer
 
@@ -55,6 +57,29 @@ module Reviewer
         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 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

@@ -45,11 +45,17 @@ 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?
 
       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
+      USAGE_ERROR
+    end
+
     def run_json(command_type)
       message = json_early_exit_message
       return emit_json_early_exit(message) if message

data/lib/reviewer/version.rb

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

data/lib/reviewer.rb

@@ -100,13 +100,18 @@ 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
 
+    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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reviewer
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Garrett Dimon