rigortype 0.3.8 → 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/layout_index.rb

@@ -21,20 +21,19 @@ module Rigor
     # in multiple files for additive member contributions, but the writer only needs one canonical target per
     # class.
     class LayoutIndex
-      # @param signature_paths [Array<String, Pathname>, nil]
+      # @param signature_paths —
       #   the `.rigor.yml`-configured signature directories.
       #   When `nil` or empty, falls back to `<project_root>/sig`
       #   if it exists (matching `Environment.for_project`'s
       #   auto-detection convention).
-      # @param project_root [String, Pathname]
       def initialize(signature_paths:, project_root: Dir.pwd)
         @signature_paths = resolve_paths(signature_paths, project_root)
         @index = nil
       end
 
-      # @param class_name [String] fully-qualified Ruby class
+      # @param class_name — fully-qualified Ruby class
       #   name (e.g. `"Rigor::Type::Top"`).
-      # @return [Pathname, nil] absolute path of the sig file
+      # @return absolute path of the sig file
       #   that already declares this class, or `nil` when no
       #   existing declaration is found.
       def file_for(class_name)

data/lib/rigor/sig_gen/meta_class_shape.rb

@@ -29,11 +29,9 @@ module Rigor
 
       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]
+      # @param members — ordered member names from the ADR-48 layout.
+      # @param member_types — erased RBS spellings; a member with no entry renders `untyped`.
+      # @param keyword_init — the `Struct.new(..., keyword_init: true)` flag; ignored for `:data`.
       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)

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

@@ -3,8 +3,10 @@
 require "prism"
 
 require_relative "../environment"
+require_relative "../project_environment"
 require_relative "../scope"
 require_relative "../type"
+require_relative "../source/constant_path"
 require_relative "../source/literals"
 require_relative "../source/node_children"
 require_relative "../inference/scope_indexer"
@@ -13,12 +15,12 @@ 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:
     #
-    # @return [Hash{[class_name, method_name] => Array<Array<Rigor::Type>>}]
+    # @return => Array<Array<Rigor::Type>>}]
     #
     # ADR-5 clause 2 compliance: the observed union is the MOST PERMISSIVE parameter contract the existing
     # callers prove sufficient — by construction it accepts every type any caller has already passed. The
@@ -32,10 +34,9 @@ module Rigor
     #   the collector cannot attribute them to a specific class.
     # - Zero-argument calls give no observation; methods are matched by `(class_name, method_name)` only.
     class ObservationCollector # rubocop:disable Metrics/ClassLength
-      # @param configuration [Rigor::Configuration]
-      # @param paths [Array<String>] observe paths (files /
+      # @param paths — observe paths (files /
       #   directories).
-      # @param source_paths [Array<String>] source-tree paths
+      # @param source_paths — source-tree paths
       #   (defaults to `configuration.paths`) pre-walked to
       #   register every project-defined class so that calls
       #   like `Foo.new.bar(x)` in the observe tree resolve
@@ -51,10 +52,11 @@ module Rigor
       def collect
         return {} if @paths.empty?
 
-        environment = build_environment
+        resolved = resolve_paths(@paths)
+        environment = build_environment(resolved)
         discovered_classes = preindex_source_classes
         observations = Hash.new { |h, k| h[k] = [] }
-        resolve_paths(@paths).each do |path|
+        resolved.each do |path|
           collect_from_file(path, environment, discovered_classes, observations)
         end
         observations.transform_values(&:freeze).freeze
@@ -62,11 +64,11 @@ module Rigor
 
       private
 
-      def build_environment
-        Environment.for_project(
-          libraries: @configuration.libraries,
-          signature_paths: @configuration.signature_paths
-        )
+      # Issue #821 — same universe as the generator and as `rigor check`; see
+      # {Generator#build_environment}. An observation collected against a narrower environment types its
+      # argument differently from the run that will consume it.
+      def build_environment(source_files = [])
+        ProjectEnvironment.build(configuration: @configuration, source_files: source_files)
       end
 
       def resolve_paths(args)
@@ -118,11 +120,11 @@ module Rigor
         return unless node.is_a?(Prism::Node)
 
         if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
-          name = qualified_constant_path(node.constant_path)
-          if name
-            full = (prefix + [name]).join("::")
+          child_prefix = Source::ConstantPath.declaration_prefix(prefix, node.constant_path)
+          if child_prefix
+            full = child_prefix.join("::")
             accumulator[full] = Type::Combinator.singleton_of(full)
-            walk_class_decls(node.body, prefix + [name], accumulator) if node.body
+            walk_class_decls(node.body, child_prefix, accumulator) if node.body
             return
           end
         end

data/lib/rigor/sig_gen/path_mapper.rb

@@ -21,9 +21,8 @@ module Rigor
     # When the source path is not under any configured source root (e.g. files supplied directly on the CLI
     # from outside `lib/`), the full relative path is preserved under the sig root.
     class PathMapper
-      # @param configuration [Rigor::Configuration]
-      # @param project_root [String, Pathname] (defaults to `Dir.pwd`)
-      # @param layout_index [LayoutIndex, nil] optional class
+      # @param project_root — (defaults to `Dir.pwd`)
+      # @param layout_index — optional class
       #   → existing sig file index; routes the target to the
       #   consolidated file when the class is already declared.
       def initialize(configuration:, project_root: Dir.pwd, layout_index: nil)
@@ -32,12 +31,11 @@ module Rigor
         @layout_index = layout_index
       end
 
-      # @param source_path [String]
-      # @param class_name [String, nil] fully-qualified Ruby
+      # @param class_name — fully-qualified Ruby
       #   class name. When supplied and matched by the
       #   `LayoutIndex`, the consolidated sig file's path is
       #   returned instead of the 1:1 mirror.
-      # @return [Pathname] absolute path of the target `.rbs`
+      # @return absolute path of the target `.rbs`
       #   file for the candidate.
       def target_for(source_path, class_name: nil)
         existing = existing_target_for(class_name)

data/lib/rigor/sig_gen/rbs_validity.rb

@@ -23,16 +23,16 @@ module Rigor
 
       module_function
 
-      # @param line [String] a rendered RBS method line, e.g. `def self.parse: (String) -> Integer`.
-      # @return [String, nil] the parse error's first line, or nil when the line is valid.
+      # @param line — a rendered RBS method line, e.g. `def self.parse: (String) -> Integer`.
+      # @return the parse error's first line, or nil when the line is valid.
       def method_line_error(line)
         return nil if line.nil?
 
         source_error("class #{PROBE_CLASS}\n  #{line}\nend\n")
       end
 
-      # @param source [String] a complete `.rbs` file's text.
-      # @return [String, nil] the parse error's first line, or nil when the file is valid.
+      # @param source — a complete `.rbs` file's text.
+      # @return the parse error's first line, or nil when the file is valid.
       def source_error(source)
         ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: "(rigor sig-gen)", content: source))
         nil

data/lib/rigor/sig_gen/renderer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "classification"
+require_relative "superclass_spelling"
 
 module Rigor
   module SigGen
@@ -21,10 +22,8 @@ module Rigor
         @out = out
       end
 
-      # @param candidates [Array<MethodCandidate>]
-      # @param mode [:print, :diff]
-      # @param format [String] "text" or "json"
-      # @param selection [Array<Symbol>] subset of
+      # @param format — "text" or "json"
+      # @param selection — subset of
       #   {Classification} constants to include; an empty
       #   array means "all emittable classifications".
       def render(candidates:, mode:, format:, selection:)
@@ -75,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
@@ -91,7 +94,7 @@ module Rigor
         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}"
+        superclass ? "class #{class_name} < #{SuperclassSpelling.absolute(superclass)}" : "class #{class_name}"
       end
 
       def render_diff(candidates)
@@ -102,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))
@@ -118,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")
@@ -145,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)
@@ -174,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