rigortype 0.4.6 → 0.4.7

data/lib/rigor/cli/plugin_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "optparse"
+
 require_relative "command"
 require_relative "../rooted_glob"
 
@@ -7,7 +9,7 @@ module Rigor
   class CLI
     # `rigor plugin` (singular) — discover and read the plugin source bundled with the `rigortype` gem.
     #
-    # Rigor ships ~30 production plugins under `plugins/` and a set of tutorial plugins under `examples/`. When Rigor is
+    # Rigor ships production plugins under `plugins/` and tutorial plugins under `examples/`. When Rigor is
     # installed via `mise` / `gem install` the gem checkout is on disk, so a plugin author (or an AI coding agent
     # following the `rigor-plugin-author` skill) can read a real, working plugin as a worked example — instead of
     # guessing the `Rigor::Plugin::Base` surface from prose. This command outputs the absolute paths so they can be
@@ -17,75 +19,122 @@ module Rigor
     # configured in *your* `.rigor.yml`. This command (singular) browses the plugins bundled in the *toolchain*.
     # Mnemonic: "plugins" = my config; "plugin" = the catalogue I can learn from.
     #
-    # Subcommands:
+    # Grammar (mirrors `rigor docs` and `rigor skill`, ADR-126 WD4): the positional slot is always a plugin *name*;
+    # alternative outputs are flags, so a plugin can never be shadowed by a verb.
     #
-    # - `rigor plugin list`          — every bundled plugin + example,
-    #                                  name + absolute directory path.
-    # - `rigor plugin path <name>`   — one-line absolute path to the
-    #                                  plugin's directory (Read-tool input).
-    # - `rigor plugin print <name>`  — a header (dir / lib / sig / README
-    #                                  paths) followed by the plugin's main
+    # - `rigor plugin`               — every bundled plugin + example, name + absolute directory path (the default).
+    # - `rigor plugin <name>`        — a header (dir / lib / sig / README paths) followed by the plugin's main
     #                                  `lib/<name>.rb` source body.
-    # - `rigor plugin root`          — the rigortype gem root and its key
-    #                                  subdirectories (lib/, plugins/,
-    #                                  examples/, skills/, sig/), so an
-    #                                  author can read the public plugin
-    #                                  API (`lib/rigor/plugin.rb`) directly.
+    # - `rigor plugin --path <name>` — one-line absolute path to the plugin's directory (Read-tool input).
+    # - `rigor plugin --list`        — the same listing as no argument.
+    # - `rigor plugin --root`        — the rigortype gem root and its key subdirectories (lib/, plugins/, examples/,
+    #                                  skills/, sig/), so an author can read the public plugin API
+    #                                  (`lib/rigor/plugin.rb`) directly.
     #
-    # `rigor plugin` with no subcommand is an alias for `list`.
+    # The verbs `list`, `path <name>`, `print <name>` and `root` are the pre-ADR-126 spelling. They still work for one
+    # minor, print the same stdout and return the same status, and add one deprecation notice on stderr naming the
+    # replacement.
     #
     # **Docker / cross-filesystem note.** Every path printed is resolved at runtime from this file's location, so it is
     # correct *on the filesystem where `rigor` runs*. If you run `rigor` inside a container but read files from the host
     # (or vice versa), the paths will not resolve — read them from the same environment that ran the command (`rigor
-    # plugin print` inlines the body for exactly this case: it works with no file-reading tool at all).
+    # plugin <name>` inlines the body for exactly this case: it works with no file-reading tool at all).
     class PluginCommand < Command
       USAGE = <<~USAGE
-        Usage: rigor plugin <subcommand> [args]
+        Usage: rigor plugin [<name>] [--path <name>] [--list] [--root]
 
         Browse the plugins bundled in the rigortype toolchain (worked
         examples for authoring your own). For the activation status of
         the plugins in your .rigor.yml, use `rigor plugins` (plural).
 
-        Subcommands:
-          list                  List bundled + example plugins (default)
-          path  <name>          Print the absolute directory path of <name>
-          print <name>          Print <name>'s main lib source, with a header
-          root                  Print the gem root + key subdirectories
+          rigor plugin                List bundled + example plugins
+          rigor plugin <name>         Print <name>'s main lib source, with a header
+          rigor plugin --path <name>  Print the absolute directory path of <name>
+          rigor plugin --list         List bundled + example plugins
+          rigor plugin --root         Print the gem root + key subdirectories
 
         Examples:
-          rigor plugin list
-          rigor plugin path  rigor-activerecord
-          rigor plugin print rigor-activesupport-core-ext
-          rigor plugin root
+          rigor plugin
+          rigor plugin rigor-activesupport-core-ext
+          rigor plugin --path rigor-activerecord
+          rigor plugin --root
       USAGE
 
+      # The pre-ADR-126 verbs, each with the spelling that replaces it.
+      DEPRECATED_VERBS = {
+        "list" => "rigor plugin --list",
+        "path" => "rigor plugin --path <name>",
+        "print" => "rigor plugin <name>",
+        "root" => "rigor plugin --root"
+      }.freeze
+
       # The bundled plugins/examples/source live at `<gem_root>/...`. From `lib/rigor/cli/plugin_command.rb` the gem
       # root is three directories up (matching SkillCommand::SKILLS_ROOT).
       GEM_ROOT     = File.expand_path("../../..", __dir__).freeze
       PLUGINS_ROOT = File.join(GEM_ROOT, "plugins").freeze
       EXAMPLES_ROOT = File.join(GEM_ROOT, "examples").freeze
 
+      # The parser this command parses with, built without parsing anything: the catalogue reads its flags from it
+      # (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
+        OptionParser.new do |opts|
+          opts.banner = USAGE.lines.first.chomp
+          opts.on("--path NAME", "Print the absolute directory path of a plugin") { |value| options[:path] = value }
+          opts.on("--list", "List bundled + example plugins") { options[:list] = true }
+          opts.on("--root", "Print the gem root + key subdirectories") { options[:root] = true }
+        end
+      end
+
       # @return CLI exit status.
       def run
-        subcommand = @argv.shift || "list"
-
-        case subcommand
-        when "list" then run_list
-        when "path" then run_path
-        when "print" then run_print
-        when "root" then run_root
-        when "-h", "--help", "help"
+        if @argv.intersect?(%w[-h --help])
           @out.puts(USAGE)
-          0
-        else
-          @err.puts("Unknown subcommand: #{subcommand}")
-          @err.puts(USAGE)
-          Rigor::CLI::EXIT_USAGE
+          return 0
         end
+
+        verb = @argv.first
+        return run_deprecated_verb(@argv.shift) if DEPRECATED_VERBS.key?(verb)
+        return run_help if verb == "help"
+
+        run_grammar
       end
 
       private
 
+      def run_help
+        @out.puts(USAGE)
+        0
+      end
+
+      def run_grammar
+        options = {}
+        begin
+          option_parser(options).parse!(@argv)
+        rescue OptionParser::ParseError => e
+          return usage_error(e.message)
+        end
+        return run_path(options[:path]) if options.key?(:path)
+        return run_root if options[:root]
+        return run_list if options[:list]
+
+        name = @argv.shift
+        name.nil? ? run_list : run_print(name)
+      end
+
+      def run_deprecated_verb(verb)
+        @err.puts("rigor: `rigor plugin #{verb}` is deprecated and will be removed in the next minor release; " \
+                  "use `#{DEPRECATED_VERBS.fetch(verb)}`.")
+        # The verbs' stdout stays byte-identical to what they printed before the grammar changed, so its prose still
+        # names the verb spelling.
+        @legacy = true
+        case verb
+        when "list" then run_list
+        when "path" then run_path(@argv.shift)
+        when "print" then run_print(@argv.shift)
+        else run_root
+        end
+      end
+
       def run_list
         plugins = discover(PLUGINS_ROOT)
         examples = discover(EXAMPLES_ROOT)
@@ -113,8 +162,7 @@ module Rigor
         end
       end
 
-      def run_path
-        name = @argv.shift
+      def run_path(name)
         return usage_error("`path` requires a plugin name") if name.nil?
 
         plugin = find(name)
@@ -124,8 +172,7 @@ module Rigor
         0
       end
 
-      def run_print
-        name = @argv.shift
+      def run_print(name)
         return usage_error("`print` requires a plugin name") if name.nil?
 
         plugin = find(name)
@@ -159,7 +206,7 @@ module Rigor
         0
       end
 
-      # The header that precedes the plugin body when an author runs `rigor plugin print <name>`. `# `-prefixed so the
+      # The header that precedes the plugin body when an author runs `rigor plugin <name>`. `# `-prefixed so the
       # combined output stays readable; the Ruby body below it is unchanged.
       def render_print_header(plugin)
         dir = plugin.fetch(:path)
@@ -176,7 +223,7 @@ module Rigor
           # The main source body is below; read the other files from the
           # paths above. To suppress `call.undefined-method` for methods a
           # DSL generates, study how an RBS-bundle plugin ships `sig/` (see
-          # `rigor plugin print rigor-activesupport-core-ext`).
+          # `#{@legacy ? 'rigor plugin print' : 'rigor plugin'} rigor-activesupport-core-ext`).
         HEADER
       end
 
@@ -211,12 +258,12 @@ module Rigor
       def docker_note
         "\nNote: paths are local to where `rigor` runs. If you run rigor in a " \
           "container,\nread these files from the same filesystem (use " \
-          "`rigor plugin print` to inline a body)."
+          "`#{@legacy ? 'rigor plugin print' : 'rigor plugin <name>'}` to inline a body)."
       end
 
       def name_error(name)
         @err.puts("Unknown plugin: #{name}")
-        @err.puts("Run `rigor plugin list` to see the bundled plugins.")
+        @err.puts("Run `rigor plugin --list` to see the bundled plugins.")
         1
       end
 

data/lib/rigor/cli/plugins_command.rb

@@ -30,7 +30,7 @@ module Rigor
     # - every manifest-declared extension surface
     #   (`open_receivers:` / `owns_receivers:` / `produces:` /
     #   `consumes:` / `block_as_methods:` / `heredoc_templates:` /
-    #   `trait_registries:` /
+    #   `trait_registries:` / `per_invocation_classes:` /
     #   `type_node_resolvers:` / `hkt_registrations:` /
     #   `hkt_definitions:` / `protocol_contracts:` /
     #   `source_rbs_synthesizer:`);
@@ -80,6 +80,20 @@ module Rigor
         0
       end
 
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          Options.add_format(opts, options, "Output format: text (default) or json")
+          opts.on("--strict", "Exit 1 if any plugin failed to load (CI gate)") { options[:strict] = true }
+          opts.on("--capabilities", "Emit the per-plugin extension-protocol catalogue (ADR-37)") do
+            options[:capabilities] = true
+          end
+        end
+      end
+
       private
 
       # Picks the renderer view. `--capabilities` switches to the focused extension-protocol catalogue (ADR-37 §
@@ -97,25 +111,10 @@ module Rigor
 
       def parse_options
         options = { config: nil, format: "text", strict: false, capabilities: false }
-        OptionParser.new do |opts|
-          opts.banner = USAGE
-          Options.add_config(opts, options)
-          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
-          opts.on("--strict", "Exit 1 if any plugin failed to load (CI gate)") { options[:strict] = true }
-          opts.on("--capabilities", "Emit the per-plugin extension-protocol catalogue (ADR-37)") do
-            options[:capabilities] = true
-          end
-        end.parse!(@argv)
-        validate!(options)
+        option_parser(options).parse!(@argv)
         options
       end
 
-      def validate!(options)
-        return if %w[text json].include?(options.fetch(:format))
-
-        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
-      end
-
       # Runs the plugin loader against the project configuration and returns a row per declared plugin entry. Each row
       # is a plain Hash with the fields enumerated in the class docstring so the renderer (text + JSON) reads from a
       # single shape.
@@ -204,7 +203,7 @@ module Rigor
           .merge(load_error: nil)
       end
 
-      # ADR-37 narrow extension protocols. Unlike the 10 declarative manifest fields, these are class-level DSLs
+      # ADR-37 narrow extension protocols. Unlike the declarative manifest fields, these are class-level DSLs
       # (`node_rule` / `dynamic_return` / `narrowing_facts`), so they are read off the plugin class rather than the
       # manifest. The gate values — node types, receiver class names, specified method names — are the greppable,
       # enumerable surface the capability catalogue exposes.

data/lib/rigor/cli/plugins_renderer.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "json_document"
 
 module Rigor
   class CLI
     # Renderer for `rigor plugins`. Produces a human-readable text table and a JSON representation from the same row
-    # shape (the Hash documented on {Rigor::CLI::PluginsCommand#loaded_row}).
+    # shape (the Hash {Rigor::CLI::PluginsCommand#build_rows} returns).
     #
     # The two formats carry the same content; JSON is meant for tooling (SKILLs, CI, editor integrations) while text is
     # for interactive inspection. Rows are printed in the order the loader resolved them.
@@ -44,7 +45,7 @@ module Rigor
             "available" => @inflection.fetch(:available)
           }
         end
-        JSON.pretty_generate(payload)
+        JSON.pretty_generate(JsonDocument.stamp(payload, mode: "status"))
       end
 
       # ADR-37 § "Machine-readable capability catalogue" — the focused per-plugin extension-protocol dump. Only loaded
@@ -53,10 +54,13 @@ module Rigor
       # type-specifier methods, and produced / consumed facts.
       def capabilities_json
         JSON.pretty_generate(
-          {
-            "configuration" => @configuration_path,
-            "capabilities" => loaded_rows.map { |row| capabilities_json_for(row) }
-          }
+          JsonDocument.stamp(
+            {
+              "configuration" => @configuration_path,
+              "capabilities" => loaded_rows.map { |row| capabilities_json_for(row) }
+            },
+            mode: "capabilities"
+          )
         )
       end
 

data/lib/rigor/cli/protection_fork_scan.rb

@@ -31,8 +31,8 @@ module Rigor
       # @return one entry per path.
       def run(paths:, scanner:, environment:, configuration:, workers:)
         # Force the full RBS load on the parent so children copy-on-write inherit a warm environment rather
-        # than each rebuilding it after the fork (mirrors the check fork pool's parent-side prewarm). A
-        # no-op on the sequential path but cheap.
+        # than each rebuilding it after the fork (mirrors the check fork pool's parent-side prewarm).
+        # Skipped when the run is sequential.
         environment.rbs_loader&.prewarm if Inference::ForkMap.parallel?([workers, paths.size].min)
 
         payloads = Inference::ForkMap.call(items: paths, workers: workers) do |slice|

data/lib/rigor/cli/protection_renderer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "../inference/dynamic_origin"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -32,7 +33,7 @@ module Rigor
       private
 
       def render_json(report)
-        @out.puts(JSON.pretty_generate(report.to_h))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(report.to_h, mode: "protection")))
       end
 
       def render_text(report)

data/lib/rigor/cli/show_bleedingedge_command.rb

@@ -7,6 +7,7 @@ require_relative "../bleeding_edge"
 require_relative "../configuration"
 require_relative "command"
 require_relative "options"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -35,19 +36,23 @@ module Rigor
         0
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", config: nil }
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
         OptionParser.new do |opt|
           opt.banner = USAGE
-          opt.on("--format=FORMAT", %w[text json], "Output format (text | json). Default: text.") do |fmt|
-            options[:format] = fmt
-          end
+          Options.add_format(opt, options, "Output format (text | json). Default: text.")
           opt.on("--config=PATH", "Path to a .rigor.yml (default: auto-discovery).") do |path|
             options[:config] = Options.config_path(path)
           end
-        end.parse!(@argv)
+        end
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", config: nil }
+        option_parser(options).parse!(@argv)
         options
       end
 
@@ -60,13 +65,14 @@ module Rigor
 
       def render_json(configuration)
         selector = configuration.bleeding_edge
-        @out.puts(JSON.pretty_generate(
-                    "overlay" => BleedingEdge.features.map(&:to_h),
-                    "selector" => configuration.to_h.fetch("bleeding_edge"),
-                    "active" => BleedingEdge.active_features(selector).map(&:id),
-                    "unknown_selected" => BleedingEdge.unknown_selected_ids(selector),
-                    "graduated" => BleedingEdge::GRADUATED
-                  ))
+        payload = {
+          "overlay" => BleedingEdge.features.map(&:to_h),
+          "selector" => configuration.to_h.fetch("bleeding_edge"),
+          "active" => BleedingEdge.active_features(selector).map(&:id),
+          "unknown_selected" => BleedingEdge.unknown_selected_ids(selector),
+          "graduated" => BleedingEdge::GRADUATED
+        }
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(payload)))
       end
 
       def render_text(configuration)

data/lib/rigor/cli/sig_gen_command.rb

@@ -38,7 +38,11 @@ module Rigor
 
       VALID_MODES = %w[print diff write check].freeze
       VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
-      VALID_FORMATS = %w[text json].freeze
+
+      # The per-target outcomes `--write` refuses: the file is left untouched and the run exits 1. `--check` counts
+      # them apart from the targets it would update, since `--write` does not fix a refused file.
+      TARGET_REFUSALS = %i[skipped_invalid_rbs skipped_invalid_encoding skipped_unparseable].freeze
+      private_constant :TARGET_REFUSALS
 
       # The skip reasons {#report_skipped} counts. The four left out each have a report of their own
       # ({#report_unrenderable}, {#report_unresolvable_superclasses}, {#report_inline_declared}, and the refusal
@@ -61,17 +65,18 @@ module Rigor
 
         observation_roots = observation_roots(configuration, options)
         observations = collect_observations(configuration, options, observation_roots, paths)
+        mode = options.fetch(:mode).to_sym
         generator = SigGen::Generator.new(configuration: configuration, paths: paths,
                                           observations: observations,
                                           include_private: options.fetch(:include_private),
                                           effect_annotator: effect_annotator(configuration, paths, options),
-                                          overwrite: options.fetch(:overwrite))
+                                          overwrite: options.fetch(:overwrite),
+                                          target_writer: target_writer(configuration, options, mode))
         candidates = generator.run
-        mode = options.fetch(:mode).to_sym
 
         status = case mode
-                 when :write then dispatch_write(candidates, configuration, options)
-                 when :check then dispatch_check(candidates, configuration, options)
+                 when :write then dispatch_write(candidates, configuration, options, generator)
+                 when :check then dispatch_check(candidates, configuration, options, generator)
                  else
                    dispatch_print_or_diff(candidates, mode, options, observation_roots, path_errors)
                    0
@@ -86,7 +91,12 @@ module Rigor
         report_inline_declared(candidates, options)
         report_withheld_annotations(candidates, options)
         report_unrenderable(generator.unrenderable)
-        report_unresolvable_superclasses(generator.unresolvable_superclasses)
+        report_unresolvable_superclasses(generator.unresolvable_superclasses, generator)
+      end
+
+      # The parser `run` parses with, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+      def option_parser(options = {})
+        build_option_parser(options)
       end
 
       private
@@ -217,16 +227,36 @@ module Rigor
       # declaring it would fail to build and take the class's type coverage with it. Naming the unresolved
       # superclass is the actionable part — it is usually one gem's missing RBS standing between the user
       # and signatures for a whole layer of their app.
-      def report_unresolvable_superclasses(unresolvable)
-        return if unresolvable.empty?
+      #
+      # Issue #2437 — a superclass the project declares in source but this run wrote nothing for gets different
+      # advice: no gem RBS is missing; the superclass's own methods could not be typed, or were not written.
+      def report_unresolvable_superclasses(unresolvable, generator)
+        reports = unresolvable.map { |name, superclass| [name, *generator.unresolvable_superclass_report(superclass)] }
+        project, external = reports.partition { |_name, kind, _root| kind == :project }
+                                   .map { |rows| rows.to_h { |name, _kind, root| [name, root] } }
+        report_unwritten_project_superclasses(project)
+        return if external.empty?
 
         @err.puts(
-          "rigor sig-gen: skipped #{unresolvable.size} class(es) whose superclass no loaded RBS declares. " \
+          "rigor sig-gen: skipped #{external.size} class(es) whose superclass no loaded RBS declares. " \
           "A signature for them would fail to build (`RBS::NoSuperclassFoundError`) and would leave the " \
           "class LESS typed than it is now. Provide RBS for the superclass — `rbs collection install`, the " \
           "gem's own `sig/`, or a `signature_paths:` entry — and re-run."
         )
-        unresolvable.sort.each { |class_name, superclass| @err.puts("  #{class_name} < #{superclass}") }
+        external.sort.each { |class_name, superclass| @err.puts("  #{class_name} < #{superclass}") }
+      end
+
+      def report_unwritten_project_superclasses(project)
+        return if project.empty?
+
+        @err.puts(
+          "rigor sig-gen: skipped #{project.size} class(es) whose superclass this run wrote no signature for. " \
+          "The superclass is declared in the project's source, but its own methods could not be typed, or its " \
+          "`sig/` file could not be written, so a signature for these subclasses would fail to build " \
+          "(`RBS::NoSuperclassFoundError`). Annotate or type the superclass's methods, fix its `sig/` file, or " \
+          "hand-write its declaration, and re-run."
+        )
+        project.sort.each { |class_name, superclass| @err.puts("  #{class_name} < #{superclass}") }
       end
 
       # #1991 — the path errors `rigor check` reports for the arguments: a path that is neither a directory nor a
@@ -265,18 +295,19 @@ module Rigor
       end
 
       # @return exit status — non-zero when a file the user asked to write could not be written.
-      def dispatch_write(candidates, configuration, options)
-        results = build_writer(configuration, options).write_all(candidates)
+      def dispatch_write(candidates, configuration, options, generator)
+        writer = build_writer(configuration, options)
+        results = writer.write_all(candidates, header_spelling: generator.method(:generic_header_spelling))
 
         refused = refused_candidates(candidates)
-        SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format), refused: refused)
+        SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format), refused: refused,
+                                                     left_bare: writer.left_bare)
         SigGen::Renderer.refusal_lines(refused).each { |line| @err.puts(line) }
-        # A refused write (an assembled file that does not parse, an existing target that is not valid UTF-8,
-        # or a method whose inline and `sig/` declarations disagree without `--overwrite`) means the user asked for a
-        # write and did not get one, so the command must not report success — a green `sig-gen --write` in CI
-        # would otherwise mean nothing.
-        refusals = %i[skipped_invalid_rbs skipped_invalid_encoding]
-        results.any? { |result| refusals.include?(result.action) } || !refused.empty? ? 1 : 0
+        # A refused write (an assembled file that does not parse, an existing target that is not valid UTF-8 or
+        # does not parse, or a method whose inline and `sig/` declarations disagree without `--overwrite`) means the
+        # user asked for a write and did not get one, so the command must not report success — a green
+        # `sig-gen --write` in CI would otherwise mean nothing.
+        results.any? { |result| TARGET_REFUSALS.include?(result.action) } || !refused.empty? ? 1 : 0
       end
 
       # ADR-112 WD4 — the methods whose inline and `sig/` declarations disagree, refused because the run did not
@@ -292,11 +323,15 @@ module Rigor
       # --overwrite` would apply it.
       #
       # @return 1 when `sig/` is out of date (or a write would be refused), 0 when it is current.
-      def dispatch_check(candidates, configuration, options)
-        results = build_writer(configuration, options, dry_run: true).write_all(candidates)
+      #
+      # A generic header held back from the repair (#2605) is reported, but does not fail the check: `--write`
+      # cannot change it, and it was failing the project's env build before the run as well.
+      def dispatch_check(candidates, configuration, options, generator)
+        writer = build_writer(configuration, options, dry_run: true)
+        results = writer.write_all(candidates, header_spelling: generator.method(:generic_header_spelling))
         refused = refused_candidates(candidates)
         SigGen::Renderer.new(out: @out).render_check(results: results, format: options.fetch(:format),
-                                                     refused: refused)
+                                                     refused: refused, left_bare: writer.left_bare)
         stale = SigGen::Renderer.out_of_date(results)
         return 0 if stale.empty? && refused.empty?
 
@@ -305,16 +340,40 @@ module Rigor
       end
 
       def report_check_failure(stale, refused)
-        unless stale.empty?
-          @err.puts("rigor sig-gen --check: #{stale.size} signature file(s) out of date; " \
+        pending, refusals = stale.partition { |result| !TARGET_REFUSALS.include?(result.action) }
+        unless pending.empty?
+          @err.puts("rigor sig-gen --check: #{pending.size} signature file(s) out of date; " \
                     "run `rigor sig-gen --write` with the same options to update them.")
         end
+        @err.puts(refused_targets_line(refusals)) unless refusals.empty?
         return if refused.empty?
 
         @err.puts("rigor sig-gen --check: #{refused.size} method(s) whose inline declaration and sig/ copy " \
                   "disagree; make them agree, or pass --overwrite to replace the sig/ member.")
       end
 
+      # A target `--write` refuses is not one it would update: it is counted apart from the out-of-date targets. Where
+      # the existing file is the user's to repair (encoding, parse), it is named for a hand fix. An invalid generated
+      # file is a Rigor rendering bug (its REFUSED line says so), so it is counted but never listed as a hand fix.
+      def refused_targets_line(results)
+        by_hand = results.reject { |result| result.action == :skipped_invalid_rbs }
+                         .map { |result| result.target_path.to_s }
+        head = "rigor sig-gen --check: #{results.size} signature file(s) refused; `--write` does not update them"
+        if by_hand.empty?
+          return "#{head}. The generated RBS did not parse: a Rigor bug, see its REFUSED line on stdout."
+        end
+
+        "#{head}. Repair by hand: #{by_hand.join(', ')}."
+      end
+
+      # #2461 — only a run that writes or compares files asks whether the writer will accept each target: where a
+      # target lands depends on the working directory, and print, diff and JSON output must not.
+      def target_writer(configuration, options, mode)
+        return nil unless %i[write check].include?(mode)
+
+        build_writer(configuration, options, dry_run: true)
+      end
+
       def build_writer(configuration, options, dry_run: false)
         layout_index = SigGen::LayoutIndex.new(signature_paths: configuration.signature_paths)
         path_mapper = SigGen::PathMapper.new(configuration: configuration, layout_index: layout_index)
@@ -426,7 +485,7 @@ module Rigor
           opts.on("--no-cache", "Do not read or write the analysis cache (effect collection only)") do
             options[:no_cache] = true
           end
-          opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+          Options.add_format(opts, options, "Output format: text or json")
           opts.on("--params=POLICY", "Parameter policy: untyped (default), observed, observed-strict") do |value|
             options[:params] = value
           end
@@ -456,11 +515,9 @@ module Rigor
 
       def validation_error(options)
         mode = options.fetch(:mode)
-        format = options.fetch(:format)
         params = options.fetch(:params)
 
         return "--print, --diff, --write, and --check are mutually exclusive flags; pick one" if mode == "conflict"
-        return "unsupported --format=#{format}" unless VALID_FORMATS.include?(format)
         return "unsupported --params=#{params}" unless VALID_PARAM_POLICIES.include?(params)
         if params == "observed-strict"
           return "--params=observed-strict is reserved until the capability-role catalog ships"