rigortype 0.3.9 → 0.4.0

data/lib/rigor/sig_gen/inline_declarations.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+require_relative "../configuration"
+require_relative "../rbs_extended"
+
+module Rigor
+  module SigGen
+    # The methods the inline reader declares for each analysed file (ADR-112 WD4): what `# @rbs` / `#:` in a
+    # `.rb` file says, member by member, as `rigor sig-gen` needs it to copy that declaration into `sig/`.
+    #
+    # Read from the RBS the `rigor-rbs-inline` synthesizer contributed (`RbsLoader#virtual_rbs`), not from the
+    # built environment. The environment is the wrong witness twice over: once `sig/` declares a member, the
+    # loader stands one of the two down before the build (ADR-112 WD5), so the declaration a stale `sig/` copy
+    # should be compared against may no longer be there to read; and a member's origin is only recoverable off
+    # its location, which the ADR-54 environment cache does not keep. The synthesized text is the loader's input,
+    # identical on every run.
+    #
+    # A member the synthesizer marks `rigor:v1:inferred-signature` is in the text only because rbs-inline
+    # declares every `def` of a file it reads: the author annotated nothing on it, so it is present here
+    # ({#lookup} finds it, which is what `sig_gen.inline_declared: skip` needs) but not {Member#declared?}.
+    class InlineDeclarations
+      # One inline-declared method.
+      #
+      # - `method_types` — the declared overloads (`RBS::MethodType`, names as written, unresolved).
+      # - `annotations` — the annotation strings the author wrote on the member (`deprecated` for
+      #   `%a{deprecated}`), without the synthesizer's own `rigor:v1:inferred-*` markers.
+      # - `return_inferred` — the author declared the parameters and not the return: rbs-inline defaulted it,
+      #   and the synthesizer marked it `rigor:v1:inferred-return`.
+      # - `signature_inferred` — every type slot defaulted; the author said nothing about this member.
+      # - `attr_line` — for an attribute, the member in RBS's own `attr_*` spelling (`attr_reader name: String`),
+      #   which is what replaces an `attr_*` declaration in `sig/` under `--overwrite`; nil for a `def`.
+      Member = Data.define(:method_types, :annotations, :return_inferred, :signature_inferred, :attr_line) do
+        def declared?
+          !signature_inferred
+        end
+
+        # The member's annotations as RBS lines, each in a delimiter its content does not close.
+        def annotation_lines
+          annotations.filter_map { |string| InlineDeclarations.annotation_line(string) }
+        end
+      end
+
+      # The synthesizer channel this index reads; another plugin's virtual RBS is not an inline declaration.
+      SYNTHESIZER_ID = Configuration::AUTOWIRED_RBS_INLINE_ID
+      private_constant :SYNTHESIZER_ID
+
+      MARKERS = [RbsExtended::INFERRED_RETURN_DIRECTIVE, RbsExtended::INFERRED_SIGNATURE_DIRECTIVE].freeze
+      private_constant :MARKERS
+
+      # rbs lexes `%a` with each of these pairs, up to the first matching closer and with no escape
+      # (`rbs/src/lexer.re`), so an annotation is spelled in the first pair its content does not close.
+      ANNOTATION_DELIMITERS = Ractor.make_shareable([%w[{ }], %w[( )], %w[[ ]], %w[< >], %w[| |]])
+      private_constant :ANNOTATION_DELIMITERS
+
+      def self.annotation_line(string)
+        pair = ANNOTATION_DELIMITERS.find { |_open, close| !string.include?(close) }
+        pair && "%a#{pair[0]}#{string}#{pair[1]}"
+      end
+
+      # Fail-soft: an environment with no loader, or a loader this index cannot read, declares nothing inline,
+      # which is the answer for a project without the plugin.
+      def self.build(environment)
+        loader = environment&.rbs_loader
+        new(loader.respond_to?(:virtual_rbs) ? loader.virtual_rbs : [])
+      rescue StandardError
+        new([])
+      end
+
+      def initialize(virtual_rbs)
+        @by_path = {}
+        @generic_classes = {}
+        virtual_rbs.each do |name, content|
+          prefix, plugin_id, path = name.to_s.split(":", 3)
+          next unless prefix == "virtual" && plugin_id == SYNTHESIZER_ID && path
+
+          decls = parse(content.to_s)
+          next if decls.nil?
+
+          table = (@by_path[path] ||= {})
+          each_member(decls, []) { |class_name, member| record(table, class_name, member) }
+        end
+        @by_path.freeze
+        @generic_classes.freeze
+      end
+
+      # `{ class name => [type parameter names] }` for the classes and modules an inline declaration gives type
+      # parameters (`# @rbs generic T`). sig-gen does not write a class's type parameters, and a `sig/` header
+      # without them makes rbs reject the class (`GenericParameterMismatchError`), so the generator writes nothing
+      # that would open one of these, nor members into a `sig/` declaration that names the parameters otherwise.
+      attr_reader :generic_classes
+
+      # @return the inline declaration of `class_name`'s `method_name` on the `kind` side, declared in the file
+      #   at `path` — or nil.
+      def lookup(path, class_name, method_name, kind)
+        @by_path.dig(path.to_s, [class_name, method_name, kind])
+      end
+
+      private
+
+      def parse(content)
+        return nil if content.empty? || !content.valid_encoding?
+
+        _buffer, _directives, decls = ::RBS::Parser.parse_signature(content)
+        decls
+      rescue ::RBS::BaseError
+        nil
+      end
+
+      def each_member(decls, prefix, &block)
+        decls.each do |decl|
+          next unless decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
+
+          inner = prefix + [decl.name.to_s.delete_prefix("::")]
+          @generic_classes[inner.join("::")] ||= decl.type_params.map(&:name) unless decl.type_params.empty?
+          decl.members.each { |member| block.call(inner.join("::"), member) }
+          each_member(decl.members, inner, &block)
+        end
+      end
+
+      def record(table, class_name, member)
+        method_entries(member).each do |method_name, kind, method_types|
+          table[[class_name, method_name, kind]] ||= build_member(member, method_types)
+        end
+      end
+
+      # `[method_name, kind, method_types]` per method a member defines, mirroring what the RBS definition
+      # builder files it under: an attribute is its reader and / or writer, `def self?.x` is both sides. An
+      # `overloading?` member (`def x: ... | ...`) composes with another declaration rather than being one,
+      # and an alias declares no signature of its own, so neither is recorded.
+      def method_entries(member)
+        case member
+        when ::RBS::AST::Members::MethodDefinition then definition_entries(member)
+        when ::RBS::AST::Members::AttrReader then [reader_entry(member)]
+        when ::RBS::AST::Members::AttrWriter then [writer_entry(member)]
+        when ::RBS::AST::Members::AttrAccessor then [reader_entry(member), writer_entry(member)]
+        else []
+        end
+      end
+
+      def definition_entries(member)
+        return [] if member.overloading?
+
+        types = member.overloads.map(&:method_type)
+        kinds = member.kind == :singleton_instance ? %i[instance singleton] : [member.kind]
+        kinds.map { |kind| [member.name, kind, types] }
+      end
+
+      def reader_entry(member)
+        [member.name, member.kind, [::RBS::Parser.parse_method_type("() -> #{member.type}")]]
+      end
+
+      def writer_entry(member)
+        [:"#{member.name}=", member.kind, [::RBS::Parser.parse_method_type("(#{member.type}) -> #{member.type}")]]
+      end
+
+      ATTR_KEYWORDS = {
+        ::RBS::AST::Members::AttrReader => "attr_reader",
+        ::RBS::AST::Members::AttrWriter => "attr_writer",
+        ::RBS::AST::Members::AttrAccessor => "attr_accessor"
+      }.freeze
+      private_constant :ATTR_KEYWORDS
+
+      def attr_line(member)
+        keyword = ATTR_KEYWORDS[member.class]
+        return nil if keyword.nil?
+
+        "#{keyword} #{'self.' if member.kind == :singleton}#{member.name}: #{member.type}"
+      end
+
+      def build_member(member, method_types)
+        strings = member.annotations.map { |annotation| annotation.string.to_s.strip }
+        Member.new(
+          method_types: method_types.freeze,
+          annotations: (strings - MARKERS).freeze,
+          return_inferred: strings.include?(RbsExtended::INFERRED_RETURN_DIRECTIVE),
+          signature_inferred: strings.include?(RbsExtended::INFERRED_SIGNATURE_DIRECTIVE),
+          attr_line: attr_line(member)
+        )
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/method_candidate.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "classification"
+require_relative "effect_annotation"
+
 module Rigor
   module SigGen
     # Per-method record produced by the generator.
@@ -15,17 +18,28 @@ module Rigor
     # - `inferred_return` — `Rigor::Type` instance (or `nil` when the inference pass disqualified the def).
     # - `declared_return_rbs` — the existing RBS-declared return spelling, or `nil` when no RBS declares the
     #   method.
+    # - `declared_rbs` — for an `inline_overwrite`, or a `tighter_return` over the class's own declaration, the
+    #   whole declared line the proposal replaces, so `--diff` and `--check` can show both; `nil` otherwise.
+    # - `declared_annotations` — for a member declared inline, the annotations the author wrote on it
+    #   (`%a{deprecated}`), rendered above `rbs` like `annotations`. Empty otherwise.
     # - `rbs` — the rendered RBS one-liner the generator would emit (`nil` for skipped / equivalent rows).
     # - `skip_reason` — one of {Classification::SKIP_DIAGNOSTIC_IDS} keys when classification is `:skipped`,
     #   else `nil`.
+    # - `annotations` — RBS annotation lines to render ABOVE `rbs` (`%a{pure}` /
+    #   `%a{rigor:v1:effect …}`, ADR-103 WD9). Empty unless the effects opt-in is on and the method's
+    #   summary earned one; see {EffectAnnotation}.
+    # - `effect_reason` — one of {EffectAnnotation::DIAGNOSTIC_IDS} keys saying why `annotations` is what
+    #   it is, or `nil` when the run had nothing to say about this method's effects.
     class MethodCandidate
       attr_reader :path, :class_name, :method_name, :kind, :classification,
                   :inferred_return, :declared_return_rbs, :rbs, :skip_reason,
-                  :namespace_kinds, :class_shells, :class_superclasses
+                  :namespace_kinds, :class_shells, :class_superclasses,
+                  :annotations, :effect_reason, :declared_rbs, :declared_annotations
 
       def initialize(path:, class_name:, method_name:, kind:, classification:, # rubocop:disable Metrics/ParameterLists
                      inferred_return: nil, declared_return_rbs: nil, rbs: nil, skip_reason: nil,
-                     namespace_kinds: {}, class_shells: [], class_superclasses: {})
+                     namespace_kinds: {}, class_shells: [], class_superclasses: {},
+                     annotations: [], effect_reason: nil, declared_rbs: nil, declared_annotations: [])
         @path = path
         @class_name = class_name
         @method_name = method_name
@@ -41,9 +55,32 @@ module Rigor
         # superclasses appear; computed ones are absent. The Writer emits `class Bar < Base` for the leaf when
         # present.
         @class_superclasses = class_superclasses.freeze
+        @annotations = annotations.freeze
+        @effect_reason = effect_reason
+        @declared_rbs = declared_rbs
+        @declared_annotations = declared_annotations.freeze
         freeze
       end
 
+      # Every line this candidate contributes to a declaration body, annotations first. The single place
+      # the renderer and the writer agree that an annotation precedes the `def` line it binds.
+      def rbs_lines
+        @declared_annotations + @annotations + [@rbs].compact
+      end
+
+      # A copy carrying a different annotation decision. The generator's effect pass rebuilds rather than
+      # mutates, because a candidate is frozen the moment it is built.
+      def with_effect_annotation(annotations, reason)
+        self.class.new(
+          path: @path, class_name: @class_name, method_name: @method_name, kind: @kind,
+          classification: @classification, inferred_return: @inferred_return,
+          declared_return_rbs: @declared_return_rbs, rbs: @rbs, skip_reason: @skip_reason,
+          namespace_kinds: @namespace_kinds, class_shells: @class_shells,
+          class_superclasses: @class_superclasses, annotations: annotations, effect_reason: reason,
+          declared_rbs: @declared_rbs, declared_annotations: @declared_annotations
+        )
+      end
+
       def to_h
         {
           file: path,
@@ -54,7 +91,14 @@ module Rigor
           rbs: rbs,
           inferred_return: inferred_return&.erase_to_rbs,
           declared_return_rbs: declared_return_rbs,
-          skip_reason: skip_reason ? Classification::SKIP_DIAGNOSTIC_IDS.fetch(skip_reason) : nil
+          declared_rbs: declared_rbs,
+          declared_annotations: declared_annotations.empty? ? nil : declared_annotations,
+          skip_reason: skip_reason ? Classification::SKIP_DIAGNOSTIC_IDS.fetch(skip_reason) : nil,
+          # Named fields rather than a merge into `rbs`: a consumer routing on the annotation has to be
+          # able to find it without re-lexing the rendered line. Both are absent (not empty / null) when
+          # the run had no effect answer, so an effects-off payload is byte-identical to a pre-#391 one.
+          effect_annotations: annotations.empty? ? nil : annotations,
+          effect_reason: effect_reason ? EffectAnnotation::DIAGNOSTIC_IDS.fetch(effect_reason) : nil
         }.compact
       end
     end

data/lib/rigor/sig_gen/observation_collector.rb

@@ -15,7 +15,7 @@ module Rigor
   module SigGen
     # ADR-14 slice 3 — caller-side argument-type observation collector.
     #
-    # Walks the user-supplied `--observe=PATH...` tree (default `spec/`), parses every `.rb` file with `Prism`,
+    # Walks the `--observe=PATH...` tree (default: the project's test roots), parses every `.rb` file with `Prism`,
     # scope- indexes it the same way the main generator does, and records the per-call-site argument-type tuples
     # for every `Prism::CallNode` whose receiver types as a `Type::Nominal`. The {Generator} consumes the
     # resulting map to render `--params=observed` RBS:

data/lib/rigor/sig_gen/renderer.rb

@@ -74,9 +74,13 @@ module Rigor
                   when Classification::NEW_FILE then "[new-file]"
                   when Classification::TIGHTER_RETURN
                     "[tighter, was: #{candidate.declared_return_rbs}]"
+                  when Classification::INLINE_OVERWRITE
+                    "[inline-overwrite, was: #{candidate.declared_rbs}]"
                   end
             @out.puts("  # #{tag}")
-            @out.puts("  #{candidate.rbs}")
+            # Annotations first: an RBS annotation binds the declaration BELOW it, so `%a{pure}` printed
+            # after the `def` line would bind the next member — or nothing at all at the end of a class.
+            candidate.rbs_lines.each { |line| @out.puts("  #{line}") }
           end
           @out.puts("end")
         end
@@ -101,13 +105,22 @@ module Rigor
 
         candidates.each do |candidate|
           @out.puts("--- #{candidate.path}: #{candidate.class_name}##{candidate.method_name}")
-          declared = candidate.declared_return_rbs
-          @out.puts("- def #{candidate.method_name}: () -> #{declared}") if declared
-          @out.puts("+ #{candidate.rbs}")
+          render_removed_line(candidate)
+          candidate.rbs_lines.each { |line| @out.puts("+ #{line}") }
           @out.puts
         end
       end
 
+      # A tighter return or an inline update replaces a whole `sig/` line, which it carries; any other row
+      # knows only the declared return.
+      def render_removed_line(candidate)
+        if candidate.declared_rbs
+          @out.puts("- #{candidate.declared_rbs}")
+        elsif candidate.declared_return_rbs
+          @out.puts("- def #{candidate.method_name}: () -> #{candidate.declared_return_rbs}")
+        end
+      end
+
       def render_json(candidates)
         payload = { candidates: candidates.map(&:to_h) }
         @out.puts(JSON.pretty_generate(payload))
@@ -117,16 +130,94 @@ module Rigor
 
       # 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.
-      def render_write(results:, format:)
+      # @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)
+        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 }
           @out.puts("No changes")
@@ -144,13 +235,35 @@ module Rigor
         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} (+#{result.applied.size}, " \
+        @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)
@@ -173,8 +286,10 @@ module Rigor
         @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)
-        @out.puts(JSON.pretty_generate({ results: results.map(&:to_h) }))
+      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

data/lib/rigor/sig_gen/skip_reason_catalog.rb

@@ -52,7 +52,7 @@ module Rigor
           summary: "An RBS declaration for this method already exists and was left alone.",
           explanation: "Not a gap. The project already states a type for this member, and sig-gen does not " \
                        "overwrite a hand-authored contract without being told to. Where `sig/` and an inline " \
-                       "annotation both declare the member, `sig/` wins.",
+                       "annotation both declare the member, ADR-112 WD5's consistency rule decides which binds.",
           next_step: "Read the existing declaration. If it disagrees with what Rigor infers, raise the " \
                      "disagreement rather than silently retyping it; pass `--overwrite` only once you have " \
                      "decided the generated type is the better contract."
@@ -84,6 +84,49 @@ module Rigor
                      "defines it, or add the project file that declares it to the analysed paths — then " \
                      "re-run `rigor sig-gen`."
         ),
+        "sig.skipped.inline-declared" => Entry.new(
+          id: "sig.skipped.inline-declared",
+          summary: "The member is declared inline, and `sig_gen.inline_declared: skip` keeps it out of `sig/`.",
+          explanation: "Not a gap. The project asked sig-gen to leave every method its inline `# @rbs` / `#:` " \
+                       "reader declares out of `sig/`, the setting for a project whose Steep reads the same " \
+                       "annotations (`inline: true` beside `signature \"sig\"`), where a `sig/` copy would " \
+                       "declare the method twice (`DuplicatedMethodDefinition`). Rigor still reads the inline " \
+                       "declaration when it analyses the source; a consumer reading only the shipped `sig/` " \
+                       "does not see this method.",
+          next_step: "Nothing, if the setting is intended. To ship the member in `sig/`, remove " \
+                     "`sig_gen.inline_declared: skip` from `.rigor.yml` and stop Steep from reading the " \
+                     "annotations of the files you generate for."
+        ),
+        "sig.skipped.inline-generic-class" => Entry.new(
+          id: "sig.skipped.inline-generic-class",
+          summary: "The class is generic by an inline declaration, and sig-gen does not write type parameters.",
+          explanation: "The class (or one it is nested in) takes type parameters from `# @rbs generic`, and " \
+                       "`sig/` either does not declare it yet or declares it with differently named parameters. " \
+                       "sig-gen would have to open it with a header that has no type parameters, which rbs " \
+                       "rejects (`GenericParameterMismatchError`) — the class, and every class whose signature " \
+                       "mentions it, would fail its definition build and read `Dynamic[top]` — or write members " \
+                       "whose `T` the `sig/` declaration does not bind. The inline declaration still binds when " \
+                       "the source is analysed.",
+          next_step: "Declare the class in `sig/` with the same type parameters as the inline declaration " \
+                     "(`class Box[T]` ... `end`) and re-run; sig-gen then writes the members into it."
+        ),
+        "sig.skipped.inline-differs" => Entry.new(
+          id: "sig.skipped.inline-differs",
+          summary: "The method's inline declaration and its `sig/` declaration disagree; neither was changed.",
+          explanation: "The method is declared inline by `# @rbs` / `#:` and in `sig/` (a `def` or an `attr_*`), " \
+                       "and the two do not state the same types, or `sig/` lacks an annotation written inline. " \
+                       "Parameter names, union spelling and a `::` that does not change what a name resolves to " \
+                       "are ignored; overload order is not, because RBS answers a call with the first overload " \
+                       "that matches. For a parameter-only annotation (`# @rbs name: T`, no `return:`) only the " \
+                       "parameters are compared, and the return follows the ordinary proposal rules. sig-gen " \
+                       "does not presume either side right, so it refuses, and `--write` and `--check` exit 1.",
+          next_step: "Decide which declaration is right. To keep the inline one, re-run with `--overwrite`, which " \
+                     "replaces the whole `sig/` member with it (an overload written only in `sig/` is dropped); " \
+                     "to keep the `sig/` one, edit the annotation to match, or delete it. A parameter-only " \
+                     "annotation whose parameters differ stays refused under `--overwrite`, because its return " \
+                     "would be inferred under the `sig/` parameters: delete the `sig/` member and re-run, or add " \
+                     "`# @rbs return:` so nothing is inferred."
+        ),
         "sig.skipped.overridden-by-unsigned-subclass" => Entry.new(
           id: "sig.skipped.overridden-by-unsigned-subclass",
           summary: "A subclass overrides this method and its override was not itself emitted.",

data/lib/rigor/sig_gen/write_result.rb

@@ -13,23 +13,32 @@ module Rigor
     # - `action` — one of `:created` / `:updated` / `:noop` / `:skipped_outside_sig_root` /
     #   `:skipped_invalid_rbs` / `:skipped_invalid_encoding`.
     # - `applied` — the {MethodCandidate}s that actually landed on disk.
+    # - `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`).
+    # - `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
+    #   still updated.
     # - `error` — the refusal cause, when `action` is a refusal: for `:skipped_invalid_rbs` the file the writer
     #   assembled does not parse, so it was NOT written (writing it would poison the project's sig tree — the
     #   consumer quarantines an unparseable `.rbs`, taking every other type in that file down with it); for
     #   `:skipped_invalid_encoding` the EXISTING target file is not valid UTF-8, so the writer refuses to merge
     #   into content it cannot read faithfully.
     class WriteResult
-      attr_reader :source_path, :target_path, :action, :applied, :skipped, :error
+      attr_reader :source_path, :target_path, :action, :applied, :skipped, :error, :left_unreadable, :replaced
 
-      def initialize(source_path:, target_path:, action:, applied: [], skipped: [], error: nil)
+      def initialize(source_path:, target_path:, action:, applied: [], skipped: [], error: nil, # rubocop:disable Metrics/ParameterLists
+                     left_unreadable: [], replaced: [])
         @source_path = source_path
         @target_path = target_path
         @action = action
         @applied = applied.freeze
         @skipped = skipped.freeze
         @error = error
+        @left_unreadable = left_unreadable.freeze
+        @replaced = replaced.freeze
         freeze
       end
 
@@ -40,7 +49,14 @@ module Rigor
           action: action.to_s,
           applied: applied.map(&:to_h),
           skipped: skipped.map { |c, reason| c.to_h.merge(write_skip_reason: reason.to_s) }
-        }.tap { |h| h[:error] = error if error }
+        }.tap do |h|
+          h[:error] = error if error
+          # Absent when nothing was replaced, so a run that only adds lines keeps its pre-#1076 payload.
+          h[:replaced] = replaced.map(&:to_h) unless replaced.empty?
+          # Absent rather than empty when nothing was left: an effects-off payload stays byte-identical
+          # to a pre-#391 one.
+          h[:effect_left_unreadable] = left_unreadable.map(&:to_h) unless left_unreadable.empty?
+        end
       end
     end
   end