rigortype 0.4.4 → 0.4.5

data/lib/rigor/sig_gen/observation_collector.rb

@@ -10,6 +10,7 @@ require_relative "../source/constant_path"
 require_relative "../source/literals"
 require_relative "../source/node_children"
 require_relative "../inference/scope_indexer"
+require_relative "../rooted_glob"
 
 module Rigor
   module SigGen
@@ -32,6 +33,7 @@ module Rigor
     #   `let` / `subject` bindings ride on slice 5's optional `rigor-rspec` integration.
     # - Calls whose receiver does not type as a `Type::Nominal` (e.g. `(some_dynamic).bar(...)`) are skipped —
     #   the collector cannot attribute them to a specific class.
+    # - A `T | nil` receiver with one `Nominal` / `Singleton` non-nil member counts as that member (#1389).
     # - Zero-argument calls give no observation; methods are matched by `(class_name, method_name)` only.
     class ObservationCollector # rubocop:disable Metrics/ClassLength
       # @param paths — observe paths (files /
@@ -62,6 +64,12 @@ module Rigor
         observations.transform_values(&:freeze).freeze
       end
 
+      # Whether `arg` names something {#collect} reads: a directory, or a `.rb` file. The CLI's
+      # `observation` report splits roots on this, so "observed" means what the collector does (#1398).
+      def self.readable_root?(arg)
+        File.directory?(arg) || (File.file?(arg) && arg.end_with?(".rb"))
+      end
+
       private
 
       # Issue #821 — same universe as the generator and as `rigor check`; see
@@ -74,8 +82,8 @@ module Rigor
       def resolve_paths(args)
         args.flat_map do |arg|
           if File.directory?(arg)
-            Dir.glob(File.join(arg, "**/*.rb"), sort: true)
-          elsif File.file?(arg) && arg.end_with?(".rb")
+            RootedGlob.glob(arg, "**/*.rb")
+          elsif self.class.readable_root?(arg)
             [arg]
           else
             []
@@ -92,8 +100,9 @@ module Rigor
         base_scope = base_scope.with_discovery(base_scope.discovery.with(discovered_classes: discovered_classes))
         scope_index = Inference::ScopeIndexer.index(parse_result.value, default_scope: base_scope)
         bindings = collect_rspec_bindings(parse_result.value, scope_index)
+        @before_ivars = collect_before_ivars(parse_result.value, scope_index)
 
-        walk_calls(parse_result.value, scope_index, bindings, observations)
+        walk_calls(parse_result.value, scope_index, bindings, observations, [])
       end
 
       # Pre-walks `@source_paths` to collect every qualified class / module declaration. The result seeds the
@@ -145,22 +154,64 @@ module Rigor
         end
       end
 
-      def walk_calls(node, scope_index, bindings, observations)
+      # `blocks` is the chain of enclosing RSpec group / example / hook blocks, innermost last — the blocks a
+      # `before` ivar can reach the call from ({#before_ivar_type}). See {#enclosing_blocks} for where it is cut.
+      def walk_calls(node, scope_index, bindings, observations, blocks)
         return unless node.is_a?(Prism::Node)
 
-        record_call(node, scope_index, bindings, observations) if node.is_a?(Prism::CallNode)
-        node.rigor_each_child { |child| walk_calls(child, scope_index, bindings, observations) }
+        record_call(node, scope_index, bindings, observations, blocks) if node.is_a?(Prism::CallNode)
+        node.rigor_each_child do |child|
+          walk_calls(child, scope_index, bindings, observations, enclosing_blocks(node, child, blocks))
+        end
+      end
+
+      # Group, example and hook calls whose block runs with the example's ivars. `RSpec.` may prefix a group call.
+      RSPEC_GROUP_CALLS = %i[
+        describe context feature shared_examples shared_examples_for shared_context
+      ].freeze
+      RSPEC_EXAMPLE_OR_HOOK_CALLS = %i[
+        it specify example scenario its before prepend_before append_before
+      ].freeze
+      private_constant :RSPEC_GROUP_CALLS, :RSPEC_EXAMPLE_OR_HOOK_CALLS
+
+      # The chain `child` of `parent` sees. A group / example / hook call's block extends it; every other block or
+      # lambda (`Class.new { … }`, `instance_eval { … }`, `define_method(:m) { … }`, `each { … }`), a class / module /
+      # singleton-class body, and a `def` that is not a direct statement of a group block cut it, since their `self`
+      # may be another object.
+      def enclosing_blocks(parent, child, blocks)
+        case child
+        when Prism::BlockNode then rspec_scope_call?(parent) ? [*blocks, child] : []
+        when Prism::LambdaNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode then []
+        when Prism::DefNode then group_statement?(child, blocks.last) ? blocks : []
+        else blocks
+        end
+      end
+
+      def rspec_scope_call?(node)
+        return false unless node.is_a?(Prism::CallNode)
+        return rspec_group_receiver?(node.receiver) if RSPEC_GROUP_CALLS.include?(node.name)
+
+        node.receiver.nil? && RSPEC_EXAMPLE_OR_HOOK_CALLS.include?(node.name)
       end
 
-      def record_call(call_node, scope_index, bindings, observations)
+      def rspec_group_receiver?(receiver)
+        receiver.nil? || (receiver.is_a?(Prism::ConstantReadNode) && receiver.name == :RSpec)
+      end
+
+      def group_statement?(node, block)
+        body = block&.body
+        body.is_a?(Prism::StatementsNode) && body.body.any? { |statement| statement.equal?(node) }
+      end
+
+      def record_call(call_node, scope_index, bindings, observations, blocks)
         receiver = call_node.receiver
         return if receiver.nil?
 
         scope = scope_index[call_node] || scope_index[receiver]
         return if scope.nil?
 
-        receiver_type = resolve_receiver_type(receiver, scope, bindings)
-        key = observation_key(call_node, receiver_type)
+        receiver_type = resolve_receiver_type(receiver, scope, bindings, blocks)
+        key = observation_key(call_node, observed_receiver(receiver_type, call_node, scope))
         return if key.nil?
 
         observation = collect_args(call_node, scope)
@@ -181,6 +232,36 @@ module Rigor
         end
       end
 
+      # Issue #1389 — a receiver typed `T | nil` whose one non-nil member is a `Nominal` or `Singleton` is observed as
+      # that member. A Minitest `setup` ivar read in a test method types as `Foo?` (setup is not `initialize`), and a
+      # call of a method `nil` does not answer can only have reached `Foo#bar` with its arguments: on `nil` it raises
+      # `NoMethodError`, and `&.` skips the call. A method `NilClass`'s RBS declares (`==`, `respond_to?`, `is_a?`)
+      # may have run on `nil` instead, so a plain `.` call of one keeps the union unobserved. The sole member still
+      # has to pass {#observation_key}'s `Nominal` / `Singleton` checks, so `untyped | nil` stays unobserved, and a
+      # union with two non-nil members (`Foo | Bar | nil`) passes through unchanged. Observation only: the
+      # receiver's inferred type elsewhere is untouched.
+      def observed_receiver(receiver_type, call_node, scope)
+        return receiver_type unless receiver_type.is_a?(Type::Union)
+
+        non_nil = receiver_type.members.reject { |member| nil_type?(member) }
+        return receiver_type unless non_nil.size == 1
+        return receiver_type if !call_node.safe_navigation? && nil_answers?(call_node.name, scope)
+
+        non_nil.first
+      end
+
+      # Whether `nil` may answer `method_name`: `NilClass`'s RBS declares it, or that RBS is not available to ask.
+      def nil_answers?(method_name, scope)
+        loader = scope.environment.rbs_loader
+        return true if loader.nil? || loader.instance_definition("NilClass").nil?
+
+        !loader.instance_method(class_name: "NilClass", method_name: method_name).nil?
+      end
+
+      def nil_type?(type)
+        (type.is_a?(Type::Constant) && type.value.nil?) || (type.is_a?(Type::Nominal) && type.class_name == "NilClass")
+      end
+
       # ADR-14 slice 5 — RSpec-aware receiver typing. Resolves a CallNode receiver against the collected
       # `bindings` map (built by {#collect_rspec_bindings}) before falling back to ordinary `scope.type_of`. The
       # three RSpec-shaped receivers we recognise:
@@ -190,11 +271,23 @@ module Rigor
       # - `described_class.new(...)` chain — when the surrounding `describe Foo do … end` resolved `Foo`,
       #   return `Type::Nominal[Foo]`.
       # - Anything else — pass through to `scope.type_of`, matching slice-3 behaviour.
-      def resolve_receiver_type(receiver, scope, bindings)
+      def resolve_receiver_type(receiver, scope, bindings, blocks)
         return resolve_described_class_new(bindings) if described_class_new?(receiver)
         return bindings[receiver.name] if bound_call?(receiver, bindings)
 
-        safe_type_of(scope, receiver)
+        type = safe_type_of(scope, receiver)
+        return type unless receiver.is_a?(Prism::InstanceVariableReadNode) && (type.nil? || type.is_a?(Type::Dynamic))
+
+        before_ivar_type(receiver.name, blocks) || type
+      end
+
+      # Issue #1389 — an ivar read inside an `it` block types as `Dynamic` (the block's ivars are not a class's), so
+      # a `before { @foo = Foo.new }` write stands in for it. Only a `before` whose example-group block encloses the
+      # read counts — a sibling `describe`, an un-included `shared_context` or a class body never reaches it — and
+      # when those `before`s write the name with more than one type, no type is answered.
+      def before_ivar_type(name, blocks)
+        types = blocks.flat_map { |block| @before_ivars.dig(block, name) || [] }.uniq
+        types.size == 1 ? types.first : nil
       end
 
       def bound_call?(receiver, bindings)
@@ -279,6 +372,39 @@ module Rigor
         bindings[name] = body_type if body_type
       end
 
+      # `before { @foo = Foo.new }` / `before(:each) do … end` inside an example-group block: records each ivar the
+      # `before` block's top-level statements write, with the written value's type, under that enclosing group
+      # block — `{ BlockNode => { :@foo => [Type] } }`, keyed by node identity. A `before` outside every group
+      # block ({#enclosing_blocks}), and `config.before`, record nothing.
+      def collect_before_ivars(root, scope_index)
+        index = {}.compare_by_identity
+        walk_before_ivars(root, [], index, scope_index)
+        index
+      end
+
+      def walk_before_ivars(node, blocks, index, scope_index)
+        return unless node.is_a?(Prism::Node)
+
+        record_before_ivars(node, blocks.last, index, scope_index) if blocks.last
+        node.rigor_each_child do |child|
+          walk_before_ivars(child, enclosing_blocks(node, child, blocks), index, scope_index)
+        end
+      end
+
+      def record_before_ivars(node, group, index, scope_index)
+        return unless node.is_a?(Prism::CallNode) && node.name == :before && node.receiver.nil?
+
+        body = block_body_node(node.block)
+        statements = body.is_a?(Prism::StatementsNode) ? body.body : [body].compact
+        statements.each do |statement|
+          next unless statement.is_a?(Prism::InstanceVariableWriteNode)
+
+          scope = scope_index[statement.value] || scope_index[statement]
+          type = scope && safe_type_of(scope, statement.value)
+          ((index[group] ||= {})[statement.name] ||= []) << type if type
+        end
+      end
+
       def binding_name_for(call_node)
         first_arg = call_node.arguments&.arguments&.first
         return call_node.name == :subject ? :subject : nil if first_arg.nil?

data/lib/rigor/sig_gen/renderer.rb

@@ -4,6 +4,7 @@ require "json"
 
 require_relative "classification"
 require_relative "superclass_spelling"
+require_relative "write_reporter"
 
 module Rigor
   module SigGen
@@ -26,9 +27,11 @@ module Rigor
       # @param selection — subset of
       #   {Classification} constants to include; an empty
       #   array means "all emittable classifications".
-      def render(candidates:, mode:, format:, selection:)
+      # @param observation — `{ paths:, missing: }` under `--params=observed`, else `nil`; JSON carries it
+      #   as the top-level `observation` key (#1398).
+      def render(candidates:, mode:, format:, selection:, observation: nil)
         case format
-        when "json" then render_json(filter(candidates, selection, with_skipped: true))
+        when "json" then render_json(filter(candidates, selection, with_skipped: true), observation)
         when "text"
           filtered = filter(candidates, selection)
           mode == :diff ? render_diff(filtered) : render_print(filtered)
@@ -121,175 +124,30 @@ module Rigor
         end
       end
 
-      def render_json(candidates)
+      def render_json(candidates, observation = nil)
         payload = { candidates: candidates.map(&:to_h) }
+        payload[:observation] = observation if observation
         @out.puts(JSON.pretty_generate(payload))
       end
 
       public
 
-      # Renders the per-source-file outcomes of a `--write` run. Distinct from {#render} because the write
-      # path's reporting surface is action-oriented (created / updated / skipped) rather than candidate-oriented.
-      # @param refused — methods refused as `sig.skipped.inline-differs`; the JSON payload names them under
-      #   `refused` (absent when there are none, so an ordinary payload is unchanged), and text mode leaves them
-      #   to the command's stderr `REFUSED` lines.
+      # The per-source-file outcomes of a `--write` run, and the `--check` verdict, are reported by
+      # {WriteReporter}; these delegate so the command keeps one renderer.
       def render_write(results:, format:, refused: [])
-        case format
-        when "json" then render_write_json(results, refused)
-        when "text" then render_write_text(results)
-        else raise ArgumentError, "unsupported format: #{format}"
-        end
+        WriteReporter.new(out: @out).render_write(results: results, format: format, refused: refused)
       end
 
-      # ADR-112 WD4 — `sig-gen --check`: the results of a dry-run `--write`. Only the targets `--write` would
-      # change (or refuse) are shown, each with the lines it would add; the verdict is the exit status, which
-      # the command derives from the same results ({.out_of_date}).
-      #
-      # @param refused — the methods the generator refused to reconcile (`sig.skipped.inline-differs`):
-      #   `sig/` is not up to date while one stands, and `--write` cannot fix it.
       def render_check(results:, format:, refused: [])
-        stale = self.class.out_of_date(results)
-        case format
-        when "json"
-          @out.puts(JSON.pretty_generate({ up_to_date: stale.empty? && refused.empty?,
-                                           results: stale.map { |r| check_entry(r) },
-                                           refused: refused.map(&:to_h) }))
-        when "text" then render_check_text(stale, refused)
-        else raise ArgumentError, "unsupported format: #{format}"
-        end
+        WriteReporter.new(out: @out).render_check(results: results, format: format, refused: refused)
       end
 
-      # One line per method sig-gen refused to reconcile with its `sig/` copy. Shared by `--write` (on stderr,
-      # next to the write report) and `--check`.
       def self.refusal_lines(refused)
-        refused.map do |candidate|
-          separator = candidate.kind == :singleton ? "." : "#"
-          "REFUSED #{candidate.path}: #{candidate.class_name}#{separator}#{candidate.method_name} — its inline " \
-            "declaration and its sig/ declaration disagree, so neither was changed " \
-            "(#{Classification::SKIP_DIAGNOSTIC_IDS.fetch(candidate.skip_reason)}). Make them agree, or pass " \
-            "--overwrite to replace the sig/ member with the inline declaration; `rigor explain " \
-            "#{Classification::SKIP_DIAGNOSTIC_IDS.fetch(candidate.skip_reason)}` says when that is not enough."
-        end
+        WriteReporter.refusal_lines(refused)
       end
 
-      # The results that make a `--check` fail: a target `--write` would create or change, and one it would
-      # refuse, since a write that cannot happen is not an up-to-date `sig/` either.
       def self.out_of_date(results)
-        results.reject { |result| %i[noop skipped_outside_sig_root].include?(result.action) }
-      end
-
-      # Nothing was written, so the entry must not read like one that was: `created` / `updated` become
-      # `would_create` / `would_update`. A refusal keeps its action — `--write` would refuse the same way.
-      CHECK_ACTIONS = { created: "would_create", updated: "would_update" }.freeze
-      private_constant :CHECK_ACTIONS
-
-      private
-
-      def check_entry(result)
-        entry = result.to_h
-        entry[:action] = CHECK_ACTIONS.fetch(result.action, entry[:action])
-        entry
-      end
-
-      def render_check_text(stale, refused)
-        if stale.empty? && refused.empty?
-          @out.puts("sig/ is up to date")
-          return
-        end
-
-        self.class.refusal_lines(refused).each { |line| @out.puts(line) }
-
-        stale.each do |result|
-          case result.action
-          when :created, :updated then render_check_change(result)
-          when :skipped_invalid_rbs then render_write_invalid(result)
-          when :skipped_invalid_encoding then render_write_invalid_encoding(result)
-          end
-        end
-      end
-
-      def render_check_change(result)
-        counts = result.action == :created ? "#{result.applied.size} method(s)" : applied_counts(result)
-        verb = result.action == :created ? "would create" : "would update"
-        @out.puts("#{verb} #{result.target_path} (#{counts})")
-        result.applied.each do |candidate|
-          @out.puts("  - #{candidate.declared_rbs}") if candidate.declared_rbs
-          candidate.rbs_lines.each { |line| @out.puts("  + #{line}") }
-        end
-      end
-
-      def render_write_text(results)
-        if results.all? { |r| r.action == :noop }
-          @out.puts("No changes")
-          return
-        end
-
-        results.each do |result|
-          case result.action
-          when :created then render_write_created(result)
-          when :updated then render_write_updated(result)
-          when :skipped_outside_sig_root then render_write_skipped(result)
-          when :skipped_invalid_rbs then render_write_invalid(result)
-          when :skipped_invalid_encoding then render_write_invalid_encoding(result)
-          end
-        end
-      end
-
-      # `+N` counts added lines; an existing line replaced (`--overwrite`, or an inline update) is counted apart,
-      # because "added 2" when one of them rewrote a line the project already had would understate the change.
-      def applied_counts(result)
-        added = "+#{result.applied.size - result.replaced.size}"
-        result.replaced.empty? ? added : "#{added}, replaced #{result.replaced.size}"
-      end
-
-      def render_write_created(result)
-        @out.puts("created #{result.target_path} (#{result.applied.size} method(s))")
-      end
-
-      def render_write_updated(result)
-        @out.puts("updated #{result.target_path} (#{applied_counts(result)}, " \
-                  "skipped #{result.skipped.size} user-authored)")
-        render_left_unreadable(result)
-      end
-
-      # ADR-103 WD9 — the declarations whose annotation region the writer refused to rewrite. Named per
-      # method rather than counted: the fix is a human reading one existing annotation and deciding what
-      # it should say, and there is no count of those a reader could act on.
-      def render_left_unreadable(result)
-        return if result.left_unreadable.empty?
-
-        @out.puts("  left #{result.left_unreadable.size} existing annotation(s) byte-untouched " \
-                  "(sig.effect.left-unreadable):")
-        result.left_unreadable.each do |candidate|
-          @out.puts("    #{candidate.class_name}##{candidate.method_name} — " \
-                    "would have emitted #{candidate.annotations.join(' ')}")
-        end
-      end
-
-      def render_write_skipped(result)
-        @out.puts("skipped #{result.source_path} -> #{result.target_path} (outside sig root)")
-      end
-
-      # The assembled file does not parse, so it was NOT written. Writing it would poison the sig tree — the
-      # consumer quarantines an unparseable `.rbs` whole, taking every other type in that file down with it,
-      # including the user's own hand-written ones.
-      def render_write_invalid(result)
-        @out.puts("REFUSED #{result.target_path} — the generated RBS does not parse, so it was not written")
-        @out.puts("  #{result.error}")
-        @out.puts("  This is a bug in Rigor's RBS rendering, not in your code — please report it.")
-      end
-
-      # The EXISTING target file is not valid UTF-8, so the writer will not merge into it — the opposite
-      # attribution from {#render_write_invalid}: this one is the file's problem, and the fix is the user's.
-      def render_write_invalid_encoding(result)
-        @out.puts("REFUSED #{result.target_path} — the existing file is not valid UTF-8, so it was not updated")
-        @out.puts("  Re-save the file as UTF-8 and re-run; sig-gen never modifies a file it cannot read faithfully.")
-      end
-
-      def render_write_json(results, refused)
-        payload = { results: results.map(&:to_h) }
-        payload[:refused] = refused.map(&:to_h) unless refused.empty?
-        @out.puts(JSON.pretty_generate(payload))
+        WriteReporter.out_of_date(results)
       end
     end
   end

data/lib/rigor/sig_gen/skip_reason_catalog.rb

@@ -147,6 +147,17 @@ module Rigor
                        "not reported.",
           next_step: "Nothing is required. To type the method, move it into a module (`module_function` or " \
                      "`extend self` keeps the call sites), or write the `Object` declaration by hand in `sig/`."
+        ),
+        "sig.skipped.uncertain-module-function" => Entry.new(
+          id: "sig.skipped.uncertain-module-function",
+          summary: "Whether the method is a module function depends on a visibility call that may not run.",
+          explanation: "A bare `module_function` makes the module's later methods module functions, and a later " \
+                       "bare `public`, `private` or `protected` ends that. Here such a call sits in control " \
+                       "flow or a block between the two, so it may or may not run, and the method is either a " \
+                       "module function (`def self?.name`) or an instance method only (`def name`). sig-gen " \
+                       "writes neither rather than guess (#1968).",
+          next_step: "Move the visibility call to the module body's own statements, or name the methods it " \
+                     "should cover (`public :name`, `module_function :name`), so the reading is certain."
         )
       }.freeze
 

data/lib/rigor/sig_gen/write_reporter.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "classification"
+
+module Rigor
+  module SigGen
+    # Reports a `rigor sig-gen --write` run (the per-target {WriteResult}s) and the `--check` verdict. Split out of
+    # {Renderer}, which formats candidates; this formats what the writer did with them.
+    class WriteReporter
+      def initialize(out:)
+        @out = out
+      end
+
+      # Renders the per-source-file outcomes of a `--write` run. Distinct from {Renderer#render} because the write
+      # path's reporting surface is action-oriented (created / updated / skipped) rather than candidate-oriented.
+      # @param refused — methods refused as `sig.skipped.inline-differs`; the JSON payload names them under
+      #   `refused` (absent when there are none, so an ordinary payload is unchanged), and text mode leaves them
+      #   to the command's stderr `REFUSED` lines.
+      def render_write(results:, format:, refused: [])
+        case format
+        when "json" then render_write_json(results, refused)
+        when "text" then render_write_text(results)
+        else raise ArgumentError, "unsupported format: #{format}"
+        end
+      end
+
+      # ADR-112 WD4 — `sig-gen --check`: the results of a dry-run `--write`. Only the targets `--write` would
+      # change (or refuse) are shown, each with the lines it would add; the verdict is the exit status, which
+      # the command derives from the same results ({.out_of_date}).
+      #
+      # @param refused — the methods the generator refused to reconcile (`sig.skipped.inline-differs`):
+      #   `sig/` is not up to date while one stands, and `--write` cannot fix it.
+      def render_check(results:, format:, refused: [])
+        stale = self.class.out_of_date(results)
+        case format
+        when "json"
+          @out.puts(JSON.pretty_generate({ up_to_date: stale.empty? && refused.empty?,
+                                           results: stale.map { |r| check_entry(r) },
+                                           refused: refused.map(&:to_h) }))
+        when "text" then render_check_text(stale, refused)
+        else raise ArgumentError, "unsupported format: #{format}"
+        end
+      end
+
+      # One line per method sig-gen refused to reconcile with its `sig/` copy. Shared by `--write` (on stderr,
+      # next to the write report) and `--check`.
+      def self.refusal_lines(refused)
+        refused.map do |candidate|
+          separator = candidate.kind == :singleton ? "." : "#"
+          "REFUSED #{candidate.path}: #{candidate.class_name}#{separator}#{candidate.method_name} — its inline " \
+            "declaration and its sig/ declaration disagree, so neither was changed " \
+            "(#{Classification::SKIP_DIAGNOSTIC_IDS.fetch(candidate.skip_reason)}). Make them agree, or pass " \
+            "--overwrite to replace the sig/ member with the inline declaration; `rigor explain " \
+            "#{Classification::SKIP_DIAGNOSTIC_IDS.fetch(candidate.skip_reason)}` says when that is not enough."
+        end
+      end
+
+      # The results that make a `--check` fail: a target `--write` would create or change, and one it would
+      # refuse, since a write that cannot happen is not an up-to-date `sig/` either.
+      def self.out_of_date(results)
+        results.reject { |result| %i[noop skipped_outside_sig_root].include?(result.action) }
+      end
+
+      # Nothing was written, so the entry must not read like one that was: `created` / `updated` become
+      # `would_create` / `would_update`. A refusal keeps its action — `--write` would refuse the same way.
+      CHECK_ACTIONS = { created: "would_create", updated: "would_update" }.freeze
+      private_constant :CHECK_ACTIONS
+
+      private
+
+      def check_entry(result)
+        entry = result.to_h
+        entry[:action] = CHECK_ACTIONS.fetch(result.action, entry[:action])
+        entry
+      end
+
+      def render_check_text(stale, refused)
+        if stale.empty? && refused.empty?
+          @out.puts("sig/ is up to date")
+          return
+        end
+
+        self.class.refusal_lines(refused).each { |line| @out.puts(line) }
+
+        stale.each do |result|
+          case result.action
+          when :created, :updated then render_check_change(result)
+          when :skipped_invalid_rbs then render_write_invalid(result)
+          when :skipped_invalid_encoding then render_write_invalid_encoding(result)
+          end
+        end
+      end
+
+      def render_check_change(result)
+        counts = result.action == :created ? "#{result.applied.size} method(s)" : applied_counts(result)
+        verb = result.action == :created ? "would create" : "would update"
+        @out.puts("#{verb} #{result.target_path} (#{counts})")
+        result.applied.each do |candidate|
+          @out.puts("  - #{candidate.declared_rbs}") if candidate.declared_rbs
+          candidate.rbs_lines.each { |line| @out.puts("  + #{line}") }
+        end
+      end
+
+      def render_write_text(results)
+        if results.all? { |r| r.action == :noop && r.skipped.empty? }
+          @out.puts("No changes")
+          return
+        end
+
+        results.each do |result|
+          case result.action
+          when :created then render_write_created(result)
+          when :updated then render_write_updated(result)
+          when :noop then render_write_unchanged(result)
+          when :skipped_outside_sig_root then render_write_skipped(result)
+          when :skipped_invalid_rbs then render_write_invalid(result)
+          when :skipped_invalid_encoding then render_write_invalid_encoding(result)
+          end
+        end
+      end
+
+      # `+N` counts added lines; an existing line replaced (`--overwrite`, or an inline update) is counted apart,
+      # because "added 2" when one of them rewrote a line the project already had would understate the change.
+      def applied_counts(result)
+        added = "+#{result.applied.size - result.replaced.size}"
+        result.replaced.empty? ? added : "#{added}, replaced #{result.replaced.size}"
+      end
+
+      def render_write_created(result)
+        @out.puts("created #{result.target_path} (#{result.applied.size} method(s))")
+      end
+
+      def render_write_updated(result)
+        @out.puts("updated #{result.target_path} (#{applied_counts(result)}, " \
+                  "skipped #{result.skipped.size} user-authored)")
+        render_write_skips(result)
+        render_left_unreadable(result)
+      end
+
+      # A target the writer opened and changed nothing in, because every proposal for it was a member the
+      # project already declares (#1975). Without this line the run read as "No changes" or said nothing about it.
+      def render_write_unchanged(result)
+        return if result.skipped.empty?
+
+        @out.puts("unchanged #{result.target_path} (skipped #{result.skipped.size} user-authored)")
+        render_write_skips(result)
+      end
+
+      # One line per proposal the writer declined, so a change `--diff` or `--print` showed is never dropped
+      # without a reason. The same entries are the `skipped` rows of the `--format=json` payload.
+      def render_write_skips(result)
+        result.skipped.each do |candidate, reason|
+          separator = candidate.kind == :singleton ? "." : "#"
+          label = "#{candidate.class_name}#{separator}#{candidate.method_name}"
+          @out.puts("  skipped #{label} (#{reason.to_s.tr('_', '-')}): #{candidate.rbs_lines.join(' ')}")
+        end
+      end
+
+      # ADR-103 WD9 — the declarations whose annotation region the writer refused to rewrite. Named per
+      # method rather than counted: the fix is a human reading one existing annotation and deciding what
+      # it should say, and there is no count of those a reader could act on.
+      def render_left_unreadable(result)
+        return if result.left_unreadable.empty?
+
+        @out.puts("  left #{result.left_unreadable.size} existing annotation(s) byte-untouched " \
+                  "(sig.effect.left-unreadable):")
+        result.left_unreadable.each do |candidate|
+          @out.puts("    #{candidate.class_name}##{candidate.method_name} — " \
+                    "would have emitted #{candidate.annotations.join(' ')}")
+        end
+      end
+
+      def render_write_skipped(result)
+        @out.puts("skipped #{result.source_path} -> #{result.target_path} (outside sig root)")
+        render_write_skips(result)
+      end
+
+      # The assembled file does not parse, so it was NOT written. Writing it would poison the sig tree — the
+      # consumer quarantines an unparseable `.rbs` whole, taking every other type in that file down with it,
+      # including the user's own hand-written ones.
+      def render_write_invalid(result)
+        @out.puts("REFUSED #{result.target_path} — the generated RBS does not parse, so it was not written")
+        @out.puts("  #{result.error}")
+        @out.puts("  This is a bug in Rigor's RBS rendering, not in your code — please report it.")
+      end
+
+      # The EXISTING target file is not valid UTF-8, so the writer will not merge into it — the opposite
+      # attribution from {#render_write_invalid}: this one is the file's problem, and the fix is the user's.
+      def render_write_invalid_encoding(result)
+        @out.puts("REFUSED #{result.target_path} — the existing file is not valid UTF-8, so it was not updated")
+        @out.puts("  Re-save the file as UTF-8 and re-run; sig-gen never modifies a file it cannot read faithfully.")
+      end
+
+      def render_write_json(results, refused)
+        payload = { results: results.map(&:to_h) }
+        payload[:refused] = refused.map(&:to_h) unless refused.empty?
+        @out.puts(JSON.pretty_generate(payload))
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/write_result.rb

@@ -16,7 +16,9 @@ module Rigor
     # - `replaced` — the subset of `applied` that replaced an existing declaration rather than adding one
     #   (`--overwrite`'s tighter returns, and inline updates).
     # - `skipped` — the {MethodCandidate}s the writer declined (e.g. tighter-return without `--overwrite`). Each
-    #   entry pairs the candidate with a skip reason keyword (`:user_authored`).
+    #   entry pairs the candidate with a skip reason keyword: `:user_authored` (the target already declares the
+    #   member, and the writer does not replace it) or `:outside_sig_root` (the member routes to a file outside
+    #   the writer's sig root, so nothing was attempted).
     # - `left_unreadable` — the {MethodCandidate}s whose effect annotation was NOT written because the
     #   target declaration already carries annotations, so its bytes were left alone
     #   (`sig.effect.left-unreadable`; see {Writer#splice_annotations}). The signature line itself was