rigortype 0.3.8 → 0.4.0

data/lib/rigor/sig_gen/skip_reason_catalog.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "classification"
+
+module Rigor
+  module SigGen
+    # Answers for the `sig.skipped.*` identifiers `rigor sig-gen` prints when it declines to emit a
+    # signature for a method.
+    #
+    # ADR-108 WD4 — a skip id is an ANSWER ("Rigor cannot prove a type here"), and the command that exists
+    # to answer identifiers must be able to answer it. `rigor explain` resolves against
+    # {Analysis::RuleCatalog}, which carries diagnostic rules only, so `rigor explain
+    # sig.skipped.untyped-return` used to reply `Unknown rule` for an id Rigor had just printed. This is the
+    # second catalogue `explain` consults; it is deliberately separate from the rule catalog because a skip
+    # reason has no severity, no profile mapping and no suppression, and forcing it into {RuleCatalog::Entry}
+    # would mean inventing four fields that do not apply.
+    #
+    # Every id in {Classification::SKIP_DIAGNOSTIC_IDS} MUST have an entry here; the gate is
+    # `spec/rigor/sig_gen/skip_reason_catalog_spec.rb`.
+    module SkipReasonCatalog
+      class Entry < Data.define(:id, :summary, :explanation, :next_step)
+        # Hash-shaped form for `rigor explain --format=json`. String keys, and `kind` distinguishes a skip
+        # reason from a rule entry in a stream a consumer may receive either from.
+        def to_h
+          {
+            "id" => id,
+            "kind" => "sig_skip_reason",
+            "summary" => summary,
+            "explanation" => explanation,
+            "next_step" => next_step
+          }
+        end
+      end
+
+      ENTRIES = {
+        "sig.skipped.untyped-return" => Entry.new(
+          id: "sig.skipped.untyped-return",
+          summary: "The method's return types as Dynamic[top], so no signature was written.",
+          explanation: "Rigor inferred the body but the value it returns has no proven type — the last " \
+                       "expression widened to Dynamic[top] somewhere up its chain. Emitting `untyped` here " \
+                       "would record noise as a contract: the file would gain a signature that says nothing " \
+                       "and stops a later, better inference from being noticed. This is the commonest skip " \
+                       "reason on a project whose dependencies have no RBS.",
+          next_step: "Do not write the return type by hand — the skip is the finding. Trace the returned " \
+                     "expression back to where it became dynamic (`rigor annotate PATH` reads the `#=>` " \
+                     "column, `rigor trace --format=json --line=N` for one line) and close THAT: install or " \
+                     "write RBS for the dependency, enable the plugin for the framework, or report an " \
+                     "engine gap."
+        ),
+        "sig.skipped.user-authored" => Entry.new(
+          id: "sig.skipped.user-authored",
+          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, 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."
+        ),
+        "sig.skipped.unrenderable-rbs" => Entry.new(
+          id: "sig.skipped.unrenderable-rbs",
+          summary: "Rigor rendered a line that `rbs` itself rejects, so the method was dropped.",
+          explanation: "A defect in Rigor's renderer, not in your code. The method is skipped rather than " \
+                       "written so one pathological signature cannot make the whole generated file " \
+                       "unparseable, and the count is reported so the defect is not silent.",
+          next_step: "Report it, with the method and the file. `rigor sig-gen --print PATH` shows what was " \
+                     "generated for the rest of the file and is the useful attachment."
+        ),
+        "sig.skipped.complex-shape" => Entry.new(
+          id: "sig.skipped.complex-shape",
+          summary: "Reserved for a shape too complex to render; no code path produces it today.",
+          explanation: "The identifier is part of the reserved `sig.skipped.*` family and is carried so the " \
+                       "family stays stable, but no generator path emits it.",
+          next_step: "If you have actually seen this id in output, that is itself worth reporting — it means " \
+                     "a path exists that this catalogue does not describe."
+        ),
+        "sig.skipped.unresolvable-superclass" => Entry.new(
+          id: "sig.skipped.unresolvable-superclass",
+          summary: "The class's superclass chain does not end in a class the RBS environment knows.",
+          explanation: "Writing the declaration would make things worse rather than better: RBS would read " \
+                       "the class as rooted at an unknown parent and collapse it on the next run, losing the " \
+                       "members it can resolve today.",
+          next_step: "Give the environment the missing ancestor — install or write RBS for the gem that " \
+                     "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.",
+          explanation: "A declaration on the parent is inherited by every subclass that does not redeclare " \
+                       "the member. Emitting it here would hand the subclass a type describing the parent's " \
+                       "body, not the override the subclass actually runs.",
+          next_step: "Generate signatures for the overriding subclass too — widen the `sig-gen` path set to " \
+                     "cover it — and the parent's declaration becomes safe to emit."
+        )
+      }.freeze
+
+      module_function
+
+      # @param token — a `sig.skipped.*` identifier.
+      # @return the matching entry, or nil when the token is not a known skip reason.
+      def resolve(token)
+        ENTRIES[token.to_s]
+      end
+
+      def all
+        ENTRIES.values
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/superclass_spelling.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rigor
+  module SigGen
+    # Renders a recorded superclass token into the spelling that goes on an emitted `class` header.
+    #
+    # Issue [#609](https://github.com/rigortype/rigor/issues/609): every token that survives
+    # {Generator#demote_unresolvable_superclasses} names a class the RBS environment or this run declares at an
+    # ABSOLUTE position — both guards ask `Reflection.rbs_class_known?` and the emitted-name set, and both are
+    # keyed by fully qualified name. The writer then emitted that token bare inside a nested `module` tree, where
+    # RBS resolves its first segment relatively against the enclosing namespaces, so `class Show < Help::Show`
+    # written under `module Views; module Help` re-points at `::Views::Help::Show` — the class being declared.
+    # The self-referential ancestry is what made `AncestorBuilder#singleton_ancestors` recurse until the stack
+    # was exhausted on the reporter's project, and what `RBS::RecursiveAncestorError` collapses the class over on
+    # a smaller one. Anchoring the token with `::` says the name the guards already checked.
+    module SuperclassSpelling
+      module_function
+
+      # @param token — a recorded superclass token, possibly carrying type arguments (`Foo::Bar[untyped]`).
+      def absolute(token)
+        return token if token.nil? || token.start_with?("::")
+
+        "::#{token}"
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/type_elaborator.rb

@@ -20,9 +20,7 @@ module Rigor
     # The module is sig-gen-local; the broader question of whether the inference engine itself should always
     # construct generics with explicit type_args is queued as an ADR-14 follow-up.
     module TypeElaborator
-      # @param type [Rigor::Type]
-      # @param environment [Rigor::Environment]
-      # @return [Rigor::Type] same shape with bare generic
+      # @return same shape with bare generic
       #   nominals filled in.
       def self.elaborate(type, environment:)
         arity_cache = {}

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

data/lib/rigor/sig_gen/writer.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "rbs"
 
 require_relative "classification"
+require_relative "superclass_spelling"
 require_relative "write_result"
 
 module Rigor
@@ -30,12 +31,16 @@ module Rigor
 
       # Per-`update_existing` accumulator. The merge_class helper mutates `source` / `decls` / `applied` /
       # `skipped` in place as each class is processed so the next class sees the latest byte positions.
-      MergeState = Struct.new(:source, :decls, :applied, :skipped, keyword_init: true)
+      MergeState = Struct.new(:source, :decls, :applied, :skipped, :left_unreadable, :replaced, keyword_init: true)
       private_constant :MergeState
 
-      def initialize(path_mapper:, overwrite: false)
+      # @param dry_run — assemble and validate every target exactly as a write would, and report it, without
+      #   creating or changing a file. `sig-gen --check` (ADR-112 WD4) is this, so it can only ever disagree
+      #   with `--write` about the disk, never about the content.
+      def initialize(path_mapper:, overwrite: false, dry_run: false)
         @path_mapper = path_mapper
         @overwrite = overwrite
+        @dry_run = dry_run
         # Run-level (cross-file) namespace-kind view, populated per `#write_all` from every candidate's per-file
         # map. Empty until then so the single-target `#write` path falls back to per-candidate kinds only.
         @global_namespace_kinds = {}
@@ -50,8 +55,7 @@ module Rigor
       # ADR-14 follow-up: this is the consolidated-layout entry point. The legacy `write(source_path,
       # candidates)` below assumes all candidates share a target and remains for spec convenience.
       #
-      # @param candidates [Array<MethodCandidate>]
-      # @return [Array<WriteResult>] one per target sig file.
+      # @return one per target sig file.
       def write_all(candidates)
         emittable = candidates.select { |c| EMITTABLE.include?(c.classification) }
         return [] if emittable.empty?
@@ -62,12 +66,10 @@ module Rigor
                  .map { |target, group| write_target(target, group) }
       end
 
-      # @param source_path [String]
-      # @param candidates [Array<MethodCandidate>] only
+      # @param candidates — only
       #   emittable classifications (new-method /
       #   tighter-return) are honoured; the caller is
       #   responsible for filtering.
-      # @return [WriteResult]
       def write(source_path, candidates)
         emittable = candidates.select { |c| EMITTABLE.include?(c.classification) }
         return WriteResult.new(source_path: source_path, target_path: nil, action: :noop) if emittable.empty?
@@ -76,6 +78,15 @@ module Rigor
         write_target(target, emittable, source_path: source_path)
       end
 
+      # Whether `proposed` has STRICTLY FEWER bare `untyped` tokens than `existing`. A count, not a slot-by-slot
+      # comparison: it reads as "at least one more position is concrete", and does not prove that no concrete
+      # position became `untyped` elsewhere. Word-boundary matching counts `untyped` only as a type token, not
+      # as a substring inside identifiers. Public because the generator asks the same question before it lists a
+      # declared `initialize` at all (#1436).
+      def self.fewer_untyped?(proposed, existing)
+        proposed.scan(/\buntyped\b/).size < existing.scan(/\buntyped\b/).size
+      end
+
       private
 
       # Shared per-target write path used by both `#write` and `#write_all`. Picks a representative
@@ -93,7 +104,7 @@ module Rigor
       # Deliberately NARROWER than {Classification::EMITTABLE}: the write path has never produced a
       # `:new_file` row (the generator does not classify one), and admitting it here would let a
       # classification with no writer behind it decide that a target file must be created.
-      EMITTABLE = [Classification::NEW_METHOD, Classification::TIGHTER_RETURN].freeze
+      EMITTABLE = [Classification::NEW_METHOD, Classification::TIGHTER_RETURN, Classification::INLINE_OVERWRITE].freeze
       private_constant :EMITTABLE
 
       def inside_sig_root?(target)
@@ -118,8 +129,10 @@ module Rigor
                                  action: :skipped_invalid_rbs, error: error)
         end
 
-        FileUtils.mkdir_p(target.dirname)
-        target.write(content)
+        unless @dry_run
+          FileUtils.mkdir_p(target.dirname)
+          target.write(content)
+        end
         WriteResult.new(source_path: source_path, target_path: target,
                         action: :created, applied: candidates)
       end
@@ -247,7 +260,7 @@ module Rigor
 
       def render_tree_node_body(node, kinds, supers, depth, prefix)
         inner_indent = INDENT * (depth + 1)
-        method_lines = node[:methods].map { |c| "#{inner_indent}#{c.rbs}\n" }.join
+        method_lines = node[:methods].flat_map { |c| c.rbs_lines.map { |line| "#{inner_indent}#{line}\n" } }.join
         child_blocks = node[:children].values.map do |child|
           render_tree_node(child, kinds, supers, depth + 1, prefix + [node[:name]])
         end.join
@@ -261,7 +274,7 @@ module Rigor
         return "" unless keyword == :class
 
         superclass = supers[qualified]
-        superclass ? " < #{superclass}" : ""
+        superclass ? " < #{SuperclassSpelling.absolute(superclass)}" : ""
       end
 
       # Per ADR-14 gap-#3 (a) the keyword for a segment comes from `namespace_kinds` when known. The default for
@@ -293,13 +306,15 @@ module Rigor
         decls = parse_signature(source)
         return WriteResult.new(source_path: source_path, target_path: target, action: :noop) if decls.nil?
 
-        state = MergeState.new(source: source, decls: decls, applied: [], skipped: [])
+        state = MergeState.new(source: source, decls: decls, applied: [], skipped: [], left_unreadable: [],
+                               replaced: [])
         merge_candidates(state, candidates)
 
         action = state.applied.empty? ? :noop : :updated
         unless action == :updated
           return WriteResult.new(source_path: source_path, target_path: target, action: action,
-                                 applied: state.applied, skipped: state.skipped)
+                                 applied: state.applied, skipped: state.skipped,
+                                 left_unreadable: state.left_unreadable)
         end
 
         # The merge splices text into an existing file by byte offset, so a bug here can produce a file neither
@@ -312,9 +327,10 @@ module Rigor
                                  action: :skipped_invalid_rbs, error: error)
         end
 
-        target.write(state.source)
+        target.write(state.source) unless @dry_run
         WriteResult.new(source_path: source_path, target_path: target,
-                        action: action, applied: state.applied, skipped: state.skipped)
+                        action: action, applied: state.applied, skipped: state.skipped,
+                        left_unreadable: state.left_unreadable, replaced: state.replaced)
       end
 
       # Applies every class group, then every requested shell, then normalises the layout the three steps
@@ -546,7 +562,7 @@ module Rigor
           state.applied.concat(methods)
           insert_namespace_chain(state, class_name, kinds, supers, methods)
         else
-          state.source = merge_into_existing_class(state.source, decl, methods, state.applied, state.skipped)
+          state.source = merge_into_existing_class(state.source, decl, methods, state)
           state.decls = parse_signature(state.source) || state.decls
         end
       end
@@ -577,24 +593,29 @@ module Rigor
         source.end_with?("\n")
       end
 
-      def merge_into_existing_class(source, decl, methods, applied, skipped)
+      def merge_into_existing_class(source, decl, methods, state)
         existing_pairs = collect_member_pairs(decl)
         new_methods, conflicting = partition_against_existing(methods, existing_pairs)
 
         source = insert_into_class(source, decl, new_methods)
-        applied.concat(new_methods)
+        state.applied.concat(new_methods)
 
         if @overwrite
-          source, replaced = replace_eligible_conflicts(source, decl, conflicting)
-          applied.concat(replaced)
-          skipped.concat(conflicting.reject { |c| replaced.include?(c) }.map { |c| [c, :user_authored] })
+          source, replaced = replace_eligible_conflicts(source, decl, conflicting, state)
+          state.applied.concat(replaced)
+          state.replaced.concat(replaced)
+          state.skipped.concat(conflicting.reject { |c| replaced.include?(c) }.map { |c| [c, :user_authored] })
         else
-          skipped.concat(conflicting.map { |c| [c, :user_authored] })
+          state.skipped.concat(conflicting.map { |c| [c, :user_authored] })
         end
 
         source
       end
 
+      def inline_overwrite?(candidate)
+        candidate.classification == Classification::INLINE_OVERWRITE
+      end
+
       # Returns a list of `[method_name (Symbol), kind (Symbol)]` pairs for every method-like member in the
       # declaration. ADR-14 slice 4 recognises `MethodDefinition`'s `:instance` / `:singleton` kind plus the
       # three `attr_*` declaration kinds so a source-side `attr_reader :name` and an RBS-side
@@ -630,7 +651,8 @@ module Rigor
         return source if new_methods.empty?
 
         indent = INDENT * member_indent_depth(decl)
-        insert_before_end(source, decl, new_methods.map { |c| "#{indent}#{c.rbs}\n" }.join)
+        lines = new_methods.flat_map { |c| c.rbs_lines.map { |line| "#{indent}#{line}\n" } }.join
+        insert_before_end(source, decl, lines)
       end
 
       # Walks the class's existing method declarations; for each replaceable candidate that matches a member
@@ -645,21 +667,34 @@ module Rigor
       #    canonical case is `initialize_stub_candidate`, which bypasses the existing-RBS comparison and always
       #    classifies as `NEW_METHOD` — when sig-gen's `--params=observed` upgrades a `(path: untyped) -> void`
       #    declaration to `(path: String) -> void` we want `--overwrite` to apply it.
-      def replace_eligible_conflicts(source, decl, candidates)
+      def replace_eligible_conflicts(source, decl, candidates, state)
         eligible = candidates.select { |c| eligible_for_replacement?(c, decl, source) }
         return [source, []] if eligible.empty?
 
         replaced = []
+        done = {}
         # Apply replacements from highest byte position downward so earlier byte offsets remain valid as the
         # source grows or shrinks.
-        sorted = eligible.sort_by { |c| -member_position(decl, c.method_name, c.kind) }
+        sorted = eligible.sort_by { |c| -member_position(decl, c) }
         sorted.each do |candidate|
-          source = apply_replacement(source, decl, candidate) and replaced << candidate
+          member = replaceable_member(decl, candidate)
+          # An `attr_accessor` answers for two methods; its one replacement covers both candidates.
+          next replaced << candidate if member && done[member.location.start_pos]
+
+          result = apply_replacement(source, decl, candidate, state)
+          next if result.nil?
+
+          done[member.location.start_pos] = true
+          source = result
+          replaced << candidate
         end
         [source, replaced]
       end
 
       def eligible_for_replacement?(candidate, decl, source)
+        return true if inline_overwrite?(candidate)
+        return false if replaces_declared_void?(candidate, decl)
+
         case candidate.classification
         when Classification::TIGHTER_RETURN then true
         when Classification::NEW_METHOD then tightens_untyped?(candidate, decl, source)
@@ -667,27 +702,56 @@ module Rigor
         end
       end
 
-      # Compares the existing member's source-side RBS text against the candidate's proposed RBS text. Returns
-      # true when the new spelling has STRICTLY FEWER bare `untyped` tokens than the existing one — i.e. at
-      # least one `untyped` slot becomes a concrete type AND no concrete slot becomes `untyped`. Word-boundary
-      # matching ensures we count `untyped` only as a type token, not as a substring inside identifiers.
-      def tightens_untyped?(candidate, decl, source)
+      # Issue #836 — `--overwrite` never turns a declared `-> void` into a value return. The generator no
+      # longer proposes one (`Generator#declares_void?` classifies the method `equivalent`), but the writer
+      # reaches the same member through case 2 above whenever the RBS environment did not resolve the `def` to
+      # this declaration: an observed-parameter upgrade of `(untyped m) -> void` to `(Module m) -> Registry`
+      # counts one `untyped` fewer and would be applied, erasing the author's statement that the return is not
+      # part of the contract. A candidate that keeps `void` is still eligible, which is what case 2 is for —
+      # the `initialize` stub is always spelled `-> void`.
+      def replaces_declared_void?(candidate, decl)
         member = find_method_member(decl, candidate.method_name, candidate.kind)
         return false if member.nil?
 
-        existing_rbs = source[member.location.start_pos...member.location.end_pos]
-        count_untyped(candidate.rbs) < count_untyped(existing_rbs)
+        declared_void = member.overloads.any? do |overload|
+          overload.method_type.type.return_type.is_a?(RBS::Types::Bases::Void)
+        end
+        declared_void && !candidate.rbs.to_s.end_with?(" -> void")
       end
 
-      def count_untyped(rbs)
-        rbs.scan(/\buntyped\b/).size
+      # Compares the existing member's source-side RBS text against the candidate's proposed RBS text
+      # ({.fewer_untyped?}).
+      def tightens_untyped?(candidate, decl, source)
+        member = find_method_member(decl, candidate.method_name, candidate.kind)
+        return false if member.nil?
+
+        self.class.fewer_untyped?(candidate.rbs, source[member.location.start_pos...member.location.end_pos])
       end
 
-      def member_position(decl, method_name, kind)
-        member = find_method_member(decl, method_name, kind)
+      def member_position(decl, candidate)
+        member = replaceable_member(decl, candidate)
         member ? member.location.start_pos : -1
       end
 
+      # The member a replacement overwrites. An inline overwrite may also land on an `attr_*` declaration of
+      # the same method (ADR-112 WD4), which it replaces in the inline attribute's own spelling; an
+      # `overloading?` member (`| ...`) is never its target.
+      def replaceable_member(decl, candidate)
+        member = find_method_member(decl, candidate.method_name, candidate.kind)
+        return member unless candidate.classification == Classification::INLINE_OVERWRITE
+
+        member = nil if member.respond_to?(:overloading?) && member.overloading?
+        member || find_attr_member(decl, candidate.method_name, candidate.kind)
+      end
+
+      def find_attr_member(decl, method_name, kind)
+        decl.members.find do |m|
+          pairs = []
+          collect_pairs_for_member(m, pairs) unless m.is_a?(RBS::AST::Members::MethodDefinition)
+          m.respond_to?(:kind) && m.kind == kind && pairs.any? { |name, _| name == method_name }
+        end
+      end
+
       def find_method_member(decl, method_name, kind)
         decl.members.find do |m|
           m.is_a?(RBS::AST::Members::MethodDefinition) && m.name == method_name && m.kind == kind
@@ -697,12 +761,96 @@ module Rigor
       # Splices the new RBS one-liner over the existing declaration's byte range. `RBS::Parser`'s location
       # starts at the `def` keyword, NOT at the column zero of the line, so the leading whitespace stays inside
       # `source[0...start_pos]` and we do not re-emit it.
-      def apply_replacement(source, decl, candidate)
-        member = find_method_member(decl, candidate.method_name, candidate.kind)
+      def apply_replacement(source, decl, candidate, state)
+        member = replaceable_member(decl, candidate)
         return nil if member.nil?
 
         loc = member.location
-        source[0...loc.start_pos] + candidate.rbs + source[loc.end_pos..]
+        replaced = source[0...loc.start_pos] + kept_comments(source, loc) + candidate.rbs + source[loc.end_pos..]
+        # Both splices insert above the member, the effect annotation at its own line and the declared ones at
+        # its first annotation's, so running the lower insertion first keeps the positions the parse gave valid.
+        replaced = splice_annotations(replaced, member, candidate, state)
+        splice_declared_annotations(replaced, member, candidate)
+      end
+
+      # A member written across lines (`def f: () -> A` / `  # why` / `  | (B) -> C`) can hold comments inside its
+      # own location, which the splice above would delete with the text it replaces. Each such comment line is
+      # kept, moved above the new line at the member's indentation. Only whole comment lines are recognised: RBS
+      # has no string type that spans a line, so a line whose first non-blank character is `#` is a comment.
+      def kept_comments(source, loc)
+        text = source[loc.start_pos...loc.end_pos].to_s
+        return "" unless text.include?("\n")
+
+        indent = source[line_start_index(source, loc.start_pos)...loc.start_pos].to_s
+        indent = "" unless indent.match?(/\A[ \t]*\z/)
+        text.lines.drop(1).filter_map { |line| line.strip if line.match?(/\A\s*#/) }
+            .map { |comment| "#{comment}\n#{indent}" }.join
+      end
+
+      # ADR-112 WD4 — the annotations an inline declaration carries that its `sig/` copy lacks, added above the
+      # member. Additive only: an annotation already there stays, whoever wrote it, so a copy never loses
+      # anything to regeneration (an annotation later deleted inline is therefore not deleted here).
+      def splice_declared_annotations(source, member, candidate)
+        missing = missing_declared_annotations(member, candidate)
+        return source if missing.empty?
+
+        line_start = line_start_index(source, member.location.start_pos)
+        indent = source[line_start...member.location.start_pos].to_s
+        return source unless indent.match?(/\A[ \t]*\z/)
+
+        anchor = annotation_block_start(source, member, line_start)
+        source[0...anchor] + missing.map { |line| "#{indent}#{line}\n" }.join + source[anchor..]
+      end
+
+      # A declared annotation line is `%a` plus a one-character delimiter pair around its content.
+      def missing_declared_annotations(member, candidate)
+        present = member.annotations.map { |annotation| annotation.string.to_s.strip }
+        candidate.declared_annotations.reject { |line| present.include?(line[3...-1].to_s.strip) }
+      end
+
+      # The start of the line the member's first annotation sits on, or of the member's own line.
+      def annotation_block_start(source, member, line_start)
+        starts = member.annotations.filter_map { |annotation| annotation.location&.start_pos }
+        ([line_start] + starts.map { |pos| line_start_index(source, pos) }).min
+      end
+
+      # ADR-103 WD9 — the annotation half of a replacement, and the one place this slice is allowed to
+      # write bytes ABOVE an existing declaration.
+      #
+      # `RBS::Parser` puts a member's annotations OUTSIDE its `location`, so {#apply_replacement} above
+      # already leaves every annotation on the declaration byte-untouched — the `%a{deprecated}` and the
+      # `%a{implicitly-returns-nil}` a user wrote survive an `--overwrite` unchanged. What is left is the
+      # question of adding ours, and the answer is: only onto a declaration that carries none.
+      #
+      # A declaration that already carries an annotation is left exactly as it is, and the candidate is
+      # reported as `sig.effect.left-unreadable`. The writer cannot tell an annotation it authored from
+      # one the user wrote, and it has no grammar for merging two — so rewriting the region could silently
+      # replace an author's own `%a{pure}` with a labelled envelope, or strip a directive Rigor does not
+      # read at all. Leaving it and saying so is the only move that cannot destroy an authored fact.
+      #
+      # An annotation on one of the member's overloads (`def m: %a{pure} (Integer) -> String`) counts too:
+      # it sits inside the location, and a tighter return keeps it (#1436), so ours would be a second one.
+      def splice_annotations(source, member, candidate, state)
+        return source if candidate.annotations.empty?
+
+        if annotated?(member)
+          # Rebuilt so the reported row carries the reason it was actually given. The generator stamped
+          # `:emitted` when it decided the annotation; only the writer knows the declaration refused it.
+          state.left_unreadable << candidate.with_effect_annotation(candidate.annotations, :left_unreadable)
+          return source
+        end
+
+        line_start = line_start_index(source, member.location.start_pos)
+        indent = source[line_start...member.location.start_pos].to_s
+        return source unless indent.match?(/\A[ \t]*\z/)
+
+        source[0...line_start] + candidate.annotations.map { |line| "#{indent}#{line}\n" }.join + source[line_start..]
+      end
+
+      def annotated?(member)
+        return true unless member.annotations.empty?
+
+        member.respond_to?(:overloads) && member.overloads.any? { |overload| overload.annotations.any? }
       end
     end
   end

data/lib/rigor/sig_gen.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "sig_gen/alias_index"
 require_relative "sig_gen/classification"
+require_relative "sig_gen/effect_annotation"
+require_relative "sig_gen/inline_declarations"
 require_relative "sig_gen/method_candidate"
 require_relative "sig_gen/observed_call"
 require_relative "sig_gen/meta_class_shape"