rigortype 0.3.0 → 0.3.2

data/lib/rigor/scope.rb

@@ -24,7 +24,8 @@ module Rigor
                 :declaration_sourced,
                 :source_path, :discovery, :struct_fold_safe_locals,
                 :dynamic_origins, :local_origins, :ivar_origins,
-                :void_origins
+                :void_origins,
+                :optimistic_origins, :optimistic_locals, :optimistic_ivars
 
     # ADR-53 Track A — the seed-time discovery tables live on the {DiscoveryIndex} the scope carries by a single
     # reference; the per-table readers stay on Scope so engine call sites and plugins are unaffected by the
@@ -149,7 +150,10 @@ module Rigor
       dynamic_origins: {}.compare_by_identity,
       local_origins: EMPTY_ORIGINS,
       ivar_origins: EMPTY_ORIGINS,
-      void_origins: {}.compare_by_identity
+      void_origins: {}.compare_by_identity,
+      optimistic_origins: {}.compare_by_identity,
+      optimistic_locals: EMPTY_ORIGINS,
+      optimistic_ivars: EMPTY_ORIGINS
     )
       @environment = environment
       @locals = locals
@@ -168,9 +172,36 @@ module Rigor
       @local_origins = local_origins
       @ivar_origins = ivar_origins
       @void_origins = void_origins
+      @optimistic_origins = optimistic_origins
+      @optimistic_locals = optimistic_locals
+      @optimistic_ivars = optimistic_ivars
       freeze
     end
 
+    # Issue #286 — the {Inference::OptimisticOrigin} cause attached to a call node whose result is nil-free
+    # only because `RbsDispatch` reads past `%a{implicitly-returns-nil}`, or `nil` when the value's
+    # nil-freeness is a property of its class. Mirrors {#dynamic_origins} / {#void_origins}: advisory
+    # metadata, ignored by `==` / `hash`, and never varying a flow decision on its own.
+    def record_optimistic_origin(node, cause)
+      @optimistic_origins[node] = cause
+      self
+    end
+
+    def optimistic_local(name) = @optimistic_locals[name.to_sym]
+    def optimistic_ivar(name) = @optimistic_ivars[name.to_sym]
+
+    def with_optimistic_local(name, cause)
+      return self if cause.nil?
+
+      rebuild(optimistic_locals: @optimistic_locals.merge(name.to_sym => cause).freeze)
+    end
+
+    def with_optimistic_ivar(name, cause)
+      return self if cause.nil?
+
+      rebuild(optimistic_ivars: @optimistic_ivars.merge(name.to_sym => cause).freeze)
+    end
+
     # ADR-82 WD1 — the propagated origin of the `Dynamic` value currently bound to a local / instance
     # variable, or `nil` when none is tracked. Consulted by `Inference::ProtectionScanner` when a dispatch's
     # receiver is a bare `x` / `@x` read whose own node carries no origin.
@@ -215,7 +246,8 @@ module Rigor
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
               declaration_sourced: drop_declaration_sourced_for(:local, name),
-              local_origins: drop_origin(@local_origins, name))
+              local_origins: drop_origin(@local_origins, name),
+              optimistic_locals: drop_origin(@optimistic_locals, name))
     end
 
     def with_fact(fact)
@@ -281,7 +313,8 @@ module Rigor
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
               declaration_sourced: drop_declaration_sourced_for(:ivar, name),
-              ivar_origins: drop_origin(@ivar_origins, name))
+              ivar_origins: drop_origin(@ivar_origins, name),
+              optimistic_ivars: drop_origin(@optimistic_ivars, name))
     end
 
     # ADR-58 WD1 — used by the method-entry seed to mark an ivar whose only provenance is the class-ivar index.
@@ -394,11 +427,13 @@ module Rigor
     # recognised `define_method` invocation inside class/module bodies. The `rigor check` undefined-method and
     # wrong-arity rules consult this map to suppress diagnostics for methods the user has defined dynamically,
     # even when no RBS sig describes them.
+    # A name defined on both sides of one class records {DiscoveryIndex::METHOD_KIND_BOTH} and matches either kind.
     def discovered_method?(class_name, method_name, kind)
       table = @discovery.discovered_methods[class_name.to_s]
       return false unless table
 
-      table[method_name.to_sym] == kind
+      recorded = table[method_name.to_sym]
+      recorded == kind || recorded == DiscoveryIndex::METHOD_KIND_BOTH
     end
 
     # ADR-34 § "Decision" — predicate identifying a toplevel-shaped scope (no enclosing `class` / `module` body).
@@ -724,7 +759,10 @@ module Rigor
       dynamic_origins: @dynamic_origins,
       local_origins: @local_origins,
       ivar_origins: @ivar_origins,
-      void_origins: @void_origins
+      void_origins: @void_origins,
+      optimistic_origins: @optimistic_origins,
+      optimistic_locals: @optimistic_locals,
+      optimistic_ivars: @optimistic_ivars
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -739,7 +777,10 @@ module Rigor
         dynamic_origins: dynamic_origins,
         local_origins: local_origins,
         ivar_origins: ivar_origins,
-        void_origins: void_origins
+        void_origins: void_origins,
+        optimistic_origins: optimistic_origins,
+        optimistic_locals: optimistic_locals,
+        optimistic_ivars: optimistic_ivars
       )
     end
 
@@ -777,7 +818,10 @@ module Rigor
         dynamic_origins: @dynamic_origins,
         local_origins: join_origins(@local_origins, other.local_origins),
         ivar_origins: join_origins(@ivar_origins, other.ivar_origins),
-        void_origins: @void_origins
+        void_origins: @void_origins,
+        optimistic_origins: @optimistic_origins,
+        optimistic_locals: join_origins(@optimistic_locals, other.optimistic_locals),
+        optimistic_ivars: join_origins(@optimistic_ivars, other.optimistic_ivars)
       )
     end
 

data/lib/rigor/sig_gen/generator.rb

@@ -12,6 +12,7 @@ require_relative "../source/node_children"
 require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/rbs_type_translator"
+require_relative "meta_class_shape"
 require_relative "rbs_validity"
 
 module Rigor
@@ -61,6 +62,7 @@ module Rigor
         @module_function_methods = Set.new
         @class_shells = Set.new
         @class_superclasses = {}
+        @meta_layouts = {}
         # Whole-run, NOT per-file: a rendering defect is reported once at the end of the run.
         @unrenderable = []
       end
@@ -114,7 +116,13 @@ module Rigor
         @module_function_methods = Set.new
         @class_shells = Set.new
         @class_superclasses = {}
+        @meta_layouts = collect_meta_layouts(scope_index)
+        register_meta_classes
         defs = collect_method_definitions(parse_result.value)
+        # Candidate construction freezes the per-file maps above (see {#build_candidate}), so every registration
+        # pass has to be finished before the first `build_candidate` call. Meta members lead the RETURNED order —
+        # a value class's members and constructors read first, ahead of the methods its block body defines.
+        meta_candidates = collect_meta_member_candidates(path, scope_index)
         candidates_from_defs = defs.filter_map do |def_node, class_name, kind|
           # An analyzer bug typing one def's body must cost only that def's candidate, never the whole
           # `rigor sig-gen` run. The `check` path recovers each *file* this way (worker_session.rb); sig-gen
@@ -125,7 +133,8 @@ module Rigor
           nil
         end
         obs_ivar_map = build_observed_ivar_map(parse_result.value)
-        candidates_from_defs + collect_attr_candidates(parse_result.value, path, scope_index, obs_ivar_map)
+        meta_candidates + candidates_from_defs +
+          collect_attr_candidates(parse_result.value, path, scope_index, obs_ivar_map)
       end
 
       # Walks the AST collecting `(def_node, class_name, kind)` tuples for every `def` Rigor can re-type. Slice 1
@@ -163,8 +172,11 @@ module Rigor
           collect_def_node(node, prefix, in_singleton_class, module_function_active, out)
           return
         when Prism::ConstantWriteNode
-          register_data_struct_shell(node, prefix)
-          # fall through to recurse into the RHS so a trailing `do ... end` block carrying defs is still walked.
+          body = meta_block_body(node, prefix)
+          if body
+            walk_defs(body, prefix + [node.name.to_s], false, false, out)
+            return
+          end
         when Prism::StatementsNode
           walk_statements(node, prefix, in_singleton_class, module_function_active, out)
           return
@@ -192,8 +204,8 @@ module Rigor
       # collapse the whole env (the 2026-07-04 redmine `GitAdapter < AbstractAdapter` crash). Only a plain
       # constant superclass is emittable: `class X < Foo` / `class X < Foo::Bar` yields the source token verbatim
       # (RBS resolves it relative to the emitted namespace, matching Ruby's lexical scope). A computed
-      # superclass (`Struct.new`, `Data.define`, `Class.new`, any `CallNode`) is left unrecorded — those flow
-      # through the {#register_data_struct_shell} shell path or are simply un-representable, and guessing would
+      # superclass (`Class.new`, any other `CallNode`) is left unrecorded — a `Data.define` / `Struct.new` one is
+      # already carried by {#register_meta_classes}, and the rest are un-representable, where guessing would
       # misfold.
       def record_superclass(node, full)
         return unless node.is_a?(Prism::ClassNode)
@@ -202,37 +214,60 @@ module Rigor
         @class_superclasses[full] = superclass if superclass
       end
 
-      # ADR-14 gap-#3 (e): recognises `Const = Data.define(...)` and `Const = Struct.new(...)` as class
-      # declarations. The runtime side stamps a brand-new anonymous class at the RHS and binds it to `Const`, so
-      # the generated RBS needs an explicit `class Const` declaration even though no `class Const ... end` block
-      # appears in source. Without it, references to `Const` in return types fail to resolve under Steep (the
-      # canonical case is `GemResolver::Resolved | GemResolver::Unresolvable` where
-      # `Unresolvable = Data.define(:gem_name, :reason)`).
-      #
-      # The walker records the fully-qualified constant name in `@class_shells` (carried through to every
-      # candidate so the writer's tree-builder picks it up) AND in `@namespace_kinds` so the leaf's `class`
-      # keyword wins over the intermediate-segment `module` default.
-      def register_data_struct_shell(node, prefix)
-        return unless data_or_struct_call?(node.value)
+      # The ADR-48 member layouts for this file, in one table keyed by qualified class name. Reading the engine's
+      # own tables instead of re-recognising `Data.define` / `Struct.new` here is what keeps sig-gen's view of a
+      # value class from drifting from the analyser's: the walker that populates them ({Inference::ScopeIndexer})
+      # already covers the constant-assigned form (`Point = Data.define(:x, :y)`), the named-subclass form
+      # (`class Point < Data.define(:x, :y)`), a `::Data` receiver, and the `keyword_init:` flag. sig-gen's earlier
+      # private recogniser covered none of the last three and was the reason #227's output was wrong rather than
+      # merely thin.
+      MetaLayout = Data.define(:kind, :member_names, :keyword_init)
+      private_constant :MetaLayout
 
-        full = (prefix + [node.name.to_s]).join("::")
-        @class_shells << full
-        @namespace_kinds[full] = :class
-      end
+      def collect_meta_layouts(scope_index)
+        scope = scope_index.each_value.first
+        return {} if scope.nil?
 
-      DATA_STRUCT_SHELL_HEADS = {
-        "Data" => :define,
-        "Struct" => :new
-      }.freeze
-      private_constant :DATA_STRUCT_SHELL_HEADS
+        layouts = {}
+        scope.data_member_layouts.each do |name, members|
+          layouts[name] = MetaLayout.new(kind: :data, member_names: members, keyword_init: false)
+        end
+        scope.struct_member_layouts.each do |name, layout|
+          layouts[name] = MetaLayout.new(kind: :struct, member_names: layout[:members],
+                                         keyword_init: layout[:keyword_init])
+        end
+        layouts
+      end
 
-      def data_or_struct_call?(value)
-        return false unless value.is_a?(Prism::CallNode)
+      # ADR-14 gap-#3 (e): a `Const = Data.define(...)` / `Const = Struct.new(...)` assignment declares a class the
+      # source never spells with a `class` keyword — the runtime stamps an anonymous class at the rvalue and binds
+      # it to `Const` — so the generated RBS needs an explicit `class Const` of its own. Without it, references to
+      # `Const` in a return type fail to resolve under Steep (the canonical case is
+      # `GemResolver::Resolved | GemResolver::Unresolvable`, where `Unresolvable = Data.define(:gem_name, :reason)`).
+      #
+      # Every layout-carrying class therefore gets the `class` keyword in `@namespace_kinds` (so the leaf wins over
+      # the intermediate-segment `module` default), its `::Data` / `::Struct[untyped]` ancestry, and a `@class_shells`
+      # entry so the writer declares it even when every member candidate is suppressed as already-declared. The
+      # named-subclass form is registered too: its `class` keyword is not in question, but its computed superclass
+      # is exactly what {#record_superclass} refuses to guess at.
+      def register_meta_classes
+        @meta_layouts.each do |class_name, layout|
+          @namespace_kinds[class_name] = :class
+          @class_shells << class_name
+          @class_superclasses[class_name] = MetaClassShape::SUPERCLASSES.fetch(layout.kind)
+        end
+      end
 
-        receiver = value.receiver
-        return false unless receiver.is_a?(Prism::ConstantReadNode)
+      # The `do ... end` body of a `Const = Data.define(...) do ... end` assignment, when `Const` carries a layout.
+      # Defs inside that block bind on `Const`, NOT on the enclosing namespace — the runtime `class_eval`s the block
+      # into the anonymous class it just stamped. Attributing them to the enclosing namespace is what made sig-gen
+      # report `VoidOrigin#label` against `Rigor::Inference` and then, because a method-bearing leaf defaults to the
+      # `class` keyword, redeclare that module as a class (#227).
+      def meta_block_body(node, prefix)
+        return nil unless node.value.is_a?(Prism::CallNode)
+        return nil unless @meta_layouts.key?((prefix + [node.name.to_s]).join("::"))
 
-        DATA_STRUCT_SHELL_HEADS[receiver.name.to_s] == value.name
+        node.value.block&.body
       end
 
       # Module / class bodies are walked through the `walk_statements` path so `module_function` (no-args)
@@ -824,6 +859,12 @@ module Rigor
           # Skip method bodies — attr_* there would refer to whatever the method is doing dynamically, not a
           # class-level declaration.
           return
+        when Prism::ConstantWriteNode
+          body = meta_block_body(node, prefix)
+          if body
+            walk_attr_calls(body, prefix + [node.name.to_s], false, ctx)
+            return
+          end
         when Prism::CallNode
           collect_attr_call(node, prefix, in_singleton_class, ctx)
         end
@@ -1065,6 +1106,64 @@ module Rigor
         when :writer then "def #{method_name}: (#{erased}) -> #{wrapped}"
         end
       end
+
+      # One candidate per member accessor and constructor {MetaClassShape} renders for each layout-carrying class.
+      # These are the members no `def` or `attr_*` in the source declares, so nothing else in sig-gen can find them —
+      # and once `register_meta_classes` has declared the class, an undeclared member reads as a missing one.
+      def collect_meta_member_candidates(path, scope_index)
+        return [] if @meta_layouts.empty?
+
+        scope = scope_index.each_value.first
+        environment = scope&.environment
+        @meta_layouts.flat_map do |class_name, layout|
+          types = meta_member_types(class_name, layout.member_names)
+          shape = MetaClassShape.of(
+            kind: layout.kind, members: layout.member_names, keyword_init: layout.keyword_init,
+            member_types: types.transform_values { |type| paren_wrap_union(union_erase([type])) }
+          )
+          shape.member_decls.filter_map do |member|
+            meta_member_candidate(path, class_name, member, types, scope, environment)
+          end
+        end
+      end
+
+      def meta_member_candidate(path, class_name, member, types, scope, environment)
+        existing = lookup_existing_method(class_name, member.method_name, member.kind, environment, scope)
+        return nil if declared_on_class_itself?(existing, class_name)
+
+        build_candidate(
+          path: path, class_name: class_name, method_name: member.method_name, kind: member.kind,
+          classification: Classification::NEW_METHOD,
+          inferred_return: types[member.source_member] || Type::Combinator.untyped,
+          rbs: member.rbs
+        )
+      end
+
+      # Whether an RBS declaration found for a member is the user's own, i.e. sits on this very class. Inheritance
+      # is the whole point of the distinction: `::Data.new: () -> bot` and `::Struct.new`'s factory both answer the
+      # `.new` lookup for every value class, and deferring to them is what leaves the arity false positive in place.
+      def declared_on_class_itself?(method_def, class_name)
+        return false if method_def.nil?
+        return false unless method_def.respond_to?(:defined_in)
+
+        method_def.defined_in.to_s.delete_prefix("::") == class_name
+      end
+
+      # `--params=observed` member types. {ObservationCollector} routes `Point.new(...)` call sites to
+      # `[class_name, :initialize]`, so a keyword call site names its member directly, while a positional one is
+      # matched by index — and only from call sites whose arity covers the whole member list, so a one-argument
+      # `Point.new(attrs)` shim cannot type member 0 as `Hash`. Empty without `--params=observed`.
+      def meta_member_types(class_name, members)
+        observations = @observations[[class_name, :initialize]] || []
+        return {} if observations.empty?
+
+        full_arity = observations.select { |obs| obs.positional.size == members.size }
+        members.each_with_index.to_h do |member, index|
+          observed = observations.filter_map { |obs| obs.keyword[member] } +
+                     full_arity.filter_map { |obs| obs.positional[index] }
+          [member, observed.empty? ? nil : Type::Combinator.union(*observed)]
+        end.compact
+      end
     end
   end
 end

data/lib/rigor/sig_gen/layout_index.rb

@@ -74,6 +74,12 @@ module Rigor
 
       def index_file(rbs_path, accumulator)
         source = rbs_path.read
+        # Pre-parser encoding guard (mirrors `Environment::RbsLoader.invalid_encoding?`): on rbs releases
+        # before 4.1 the C lexer could hang on an invalid UTF-8 byte, and a hang is the one failure the
+        # rescue below cannot absorb. Skipping is safe here for the same reason the rescue is — placement
+        # falls back as for any unparseable file, and the env loader's quarantine warning names the file.
+        return unless source.valid_encoding?
+
         _, _, decls = RBS::Parser.parse_signature(source)
         record_decls(decls, [], rbs_path, accumulator)
       rescue StandardError

data/lib/rigor/sig_gen/meta_class_shape.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Rigor
+  module SigGen
+    # The RBS surface of a class the runtime builds from `Data.define(...)` / `Struct.new(...)` — its ancestry, its
+    # synthesised member accessors, and its constructors — rendered from an ADR-48 member layout.
+    #
+    # Declaring the class without them would be worse than not declaring it at all. `::Data`'s own RBS declares
+    # `def self.new: () -> bot` and `::Struct`'s declares only the `Struct.new("Name", :a, :b)` factory, so a
+    # subclass that carries no `.new` of its own turns every `Point.new(1, 2)` into a false-positive arity error —
+    # where the undeclared class it replaced merely typed as `Dynamic` and reported nothing. The same reasoning
+    # covers the member readers and `.[]` (`Point[1, 2]`, which `::Data`'s RBS does not declare): narrowing dispatch
+    # from `Dynamic` to a nominal class means everything the runtime synthesises must be declared, or it reads as
+    # missing.
+    #
+    # Member types arrive already erased to RBS and already parenthesised for return position. One pre-wrapped
+    # string serves every position this module interpolates into — `(a: (String | Integer))`,
+    # `((String | Integer) a)`, `?(String | Integer) a` all parse and validate.
+    module MetaClassShape
+      # `::Struct` is generic (`class Struct[E]`), and RBS rejects a bare `< ::Struct` with
+      # `InvalidTypeApplicationError`. `untyped` is the only element type a layout can justify.
+      SUPERCLASSES = { data: "::Data", struct: "::Struct[untyped]" }.freeze
+
+      # `method_name` / `kind` feed the writer's existing-member matching. `source_member` is the layout member a
+      # reader / writer derives from, and nil for a constructor, so the caller can attach the member's carrier to
+      # the candidate it builds.
+      Member = ::Data.define(:method_name, :kind, :rbs, :source_member)
+      Shape = ::Data.define(:superclass, :member_decls)
+
+      module_function
+
+      # @param kind [:data, :struct]
+      # @param members [Array<Symbol>] ordered member names from the ADR-48 layout.
+      # @param member_types [Hash{Symbol => String}] erased RBS spellings; a member with no entry renders `untyped`.
+      # @param keyword_init [Boolean] the `Struct.new(..., keyword_init: true)` flag; ignored for `:data`.
+      # @return [Shape]
+      def of(kind:, members:, member_types: {}, keyword_init: false)
+        types = members.to_h { |member| [member, member_types[member] || "untyped"] }
+        accessors = kind == :struct ? struct_accessors(members, types) : readers(members, types)
+        Shape.new(superclass: SUPERCLASSES.fetch(kind),
+                  member_decls: accessors + constructors(kind, members, types, keyword_init))
+      end
+
+      def readers(members, types)
+        members.map do |member|
+          Member.new(method_name: member, kind: :instance, source_member: member,
+                     rbs: "def #{member}: () -> #{types[member]}")
+        end
+      end
+
+      # A Struct's members are mutable, so each one contributes a writer too. The writer returns the assigned
+      # value's type — Ruby's assignment semantics, and the spelling the `attr_writer` path already emits.
+      def struct_accessors(members, types)
+        writers = members.map do |member|
+          Member.new(method_name: :"#{member}=", kind: :instance, source_member: member,
+                     rbs: "def #{member}=: (#{types[member]}) -> #{types[member]}")
+        end
+        readers(members, types) + writers
+      end
+
+      # `.new` and its `.[]` alias share one overload list.
+      def constructors(kind, members, types, keyword_init)
+        overloads = constructor_overloads(kind, members, types, keyword_init).join(" | ")
+        %i[new []].map do |name|
+          Member.new(method_name: name, kind: :singleton, source_member: nil, rbs: "def self.#{name}: #{overloads}")
+        end
+      end
+
+      # `Data` requires every member; a Struct fills a missing one with `nil`, so its positions are all optional.
+      #
+      # `keyword_init: true` accepts keyword arguments only. Every other layout gets BOTH forms, because the flag
+      # reads `false` for an absent `keyword_init:` as well as for a literal `keyword_init: false` — and since Ruby
+      # 3.2 the absent case, by far the dominant one, accepts both. Emitting both is the false-positive-free reading
+      # of an ambiguity the layout cannot resolve.
+      def constructor_overloads(kind, members, types, keyword_init)
+        optional = kind == :struct ? "?" : ""
+        keyword = "(#{members.map { |m| "#{optional}#{m}: #{types[m]}" }.join(', ')}) -> instance"
+        return [keyword] if kind == :struct && keyword_init
+
+        [keyword, "(#{members.map { |m| "#{optional}#{types[m]} #{m}" }.join(', ')}) -> instance"]
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/renderer.rb

@@ -66,7 +66,7 @@ module Rigor
 
       def render_classes(items)
         items.group_by(&:class_name).each do |class_name, methods|
-          @out.puts("class #{class_name}")
+          @out.puts(declaration_header(methods.first, class_name))
           methods.each do |candidate|
             tag = case candidate.classification
                   when Classification::NEW_METHOD then "[new]"
@@ -81,6 +81,17 @@ module Rigor
         end
       end
 
+      # The keyword and ancestry for a printed group, from the same per-file maps the `--write` path reads. Print
+      # mode used to hard-code `class`, which turned a module into a class the moment it held an emittable method —
+      # output that raises `RBS::DuplicatedDeclarationError` on load if the real `module` is declared anywhere else
+      # (#227). Defaulting to `class` when the map has no entry keeps the pre-existing spelling for a leaf class.
+      def declaration_header(candidate, class_name)
+        return "module #{class_name}" if candidate.namespace_kinds[class_name] == :module
+
+        superclass = candidate.class_superclasses[class_name]
+        superclass ? "class #{class_name} < #{superclass}" : "class #{class_name}"
+      end
+
       def render_diff(candidates)
         if candidates.empty?
           @out.puts("No candidates")
@@ -127,6 +138,7 @@ module Rigor
           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
@@ -153,6 +165,13 @@ module Rigor
         @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)
         @out.puts(JSON.pretty_generate({ results: results.map(&:to_h) }))
       end

data/lib/rigor/sig_gen/write_result.rb

@@ -11,13 +11,15 @@ module Rigor
     # - `target_path` — `.rbs` file the writer was responsible for (`nil` when the source path falls outside
     #   the project signature tree, in which case `action` is `:skipped_outside_sig_root`).
     # - `action` — one of `:created` / `:updated` / `:noop` / `:skipped_outside_sig_root` /
-    #   `:skipped_invalid_rbs`.
+    #   `:skipped_invalid_rbs` / `:skipped_invalid_encoding`.
     # - `applied` — the {MethodCandidate}s that actually landed on disk.
     # - `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`).
-    # - `error` — the parse error, when `action` is `: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).
+    # - `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