rigortype 0.3.7 → 0.3.8

data/lib/rigor/inference/hkt_sugar_translator.rb

@@ -6,39 +6,28 @@ require_relative "hkt_body"
 module Rigor
   module Inference
     class HktSugarTranslator
-      class << self
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-        def translate(rbs_type, uri:, params_set:, name_scope:)
-          new(uri: uri, params_set: params_set, name_scope: name_scope).translate(rbs_type)
-        end
-      end
-
       attr_reader :recursive
 
-      def initialize(uri:, params_set:, name_scope:)
+      def initialize(uri:, params_set:)
         @uri = uri
         @params_set = params_set
-        @name_scope = name_scope
         @recursive = false
       end
 
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       def translate(type)
         case type
         when RBS::Types::Alias
-          if type.name.to_s.sub(/\A::/, "") == @uri.to_s
+          if type.name.to_s.sub(/\A::/, "") == @uri.to_s && !type.args.empty?
             @recursive = true
             args = type.args.map { |a| translate(a) }
             HktBody::AppRef.new(uri: @uri, args: args)
           else
-            # Re-wrap other aliases as NominalApp or TypeLeaf?
-            # Actually, we can just translate them to TypeLeaf if they have no args,
-            # but Rigor handles aliases via RbsLoader.
-            # If we don't expand them here, they will just be RbsTypeTranslator.translate'd later?
-            # Wait, HktBody doesn't have an AliasRef node. HktBody uses NominalApp for things with args,
-            # or TypeLeaf for concrete Rigor::Type.
-
-            # Since Rigor doesn't support generic aliases outside of HKT AppRef,
-            # we can just translate to TypeLeaf.
+            # Everything else degrades to a concrete leaf: HktBody has no AliasRef node and Rigor
+            # resolves non-HKT aliases through RbsLoader. A bare self-reference with no type
+            # arguments (`type Foo::x[T] = ... | Foo::x`) lands here too — it is malformed for a
+            # parameterized alias (`rbs validate` rejects it), so it must not build an empty-args
+            # `AppRef`, which `HktBody` rejects.
             fallback_to_type_leaf(type)
           end
         when RBS::Types::ClassInstance
@@ -72,17 +61,22 @@ module Rigor
           fallback_to_type_leaf(type)
         end
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
       private
 
+      # The `else` arm and the unbound-variable / non-recursive-alias arms all degrade a subterm the
+      # HKT body grammar has no node for to a concrete `Rigor::Type` leaf. `RbsTypeTranslator` has no
+      # name-scope parameter — it never resolves relative names — and the alias decls this walk reads
+      # come off a `resolve_type_names`-d environment, so names arrive already absolute and there is
+      # nothing a scope would do here. `alias_expander: nil` is deliberate too: a nested alias reached
+      # in this fallback degrades to `Dynamic[Top]` rather than pulling a second alias body into an
+      # HKT definition.
       def fallback_to_type_leaf(type)
         require_relative "rbs_type_translator" unless defined?(RbsTypeTranslator)
         rigor_type = RbsTypeTranslator.translate(
           type,
           alias_expander: nil,
           type_vars: {},
-          name_scope: @name_scope,
           self_type: Rigor::Type::Combinator.untyped,
           instance_type: Rigor::Type::Combinator.untyped
         )

data/lib/rigor/plugin/registry.rb

@@ -316,9 +316,25 @@ module Rigor
       # determined by the user's `plugins:` list); user `.rbs` overlays merge on top of this overlay last.
       # Returns `Inference::HktRegistry::EMPTY` when no plugin contributes HKT entries so callers can skip the
       # merge.
+      #
+      # Issue #791 — a plugin's contribution is read inside a per-plugin rescue that re-raises the SAME
+      # exception class with the plugin named, and with the original backtrace, so the
+      # `rbs.coverage.hkt-scan-failed` row this ends up on says WHICH plugin to remove instead of only that
+      # "the plugin overlay" failed. `Exception#exception(message)` clones rather than re-constructing, so
+      # an exception class with a non-standard `initialize` survives the re-raise; `cause` is set to the
+      # original automatically. The aggregation itself (a duplicate URI across two plugins, say) is not
+      # attributable to one plugin and raises unnamed — the stage still is, which is what the row needs.
       def hkt_overlay_registry
-        registrations = plugins.flat_map { |plugin| plugin.manifest.hkt_registrations }
-        definitions = plugins.flat_map { |plugin| plugin.manifest.hkt_definitions }
+        registrations = []
+        definitions = []
+        plugins.each do |plugin|
+          manifest = plugin.manifest
+          registrations.concat(manifest.hkt_registrations)
+          definitions.concat(manifest.hkt_definitions)
+        rescue StandardError => e
+          raise e, "plugin #{safe_plugin_id(plugin).inspect} raised while contributing HKT " \
+                   "registrations: #{e.message}", e.backtrace
+        end
         return Inference::HktRegistry::EMPTY if registrations.empty? && definitions.empty?
 
         Inference::HktRegistry.new(registrations: registrations, definitions: definitions)
@@ -455,6 +471,13 @@ module Rigor
       rescue StandardError
         []
       end
+
+      # Issue #791 — the id to name in the HKT-overlay failure message, derived through {#safe_manifest}
+      # because a raising manifest read is one of the shapes that gets here. Mirrors `Runner#safe_plugin_id`
+      # (the `:plugin_loader` envelope's own naming) so both failure surfaces name a plugin the same way.
+      def safe_plugin_id(plugin)
+        safe_manifest(plugin)&.id || plugin.class.to_s
+      end
     end
 
     # Assigned after the class body completes — `Registry.new` runs at assignment time and `#initialize` calls

data/lib/rigor/rbs_extended/envelope_scanner.rb

@@ -22,14 +22,15 @@ module Rigor
     #
     # ## Why it parses rather than reading the built environment
     #
-    # {ConformanceChecker}, the obvious model, walks `RbsLoader`'s built env. An envelope cannot: the
+    # {ConformanceChecker}, the obvious model, walks `RbsLoader`'s built env. An envelope did not: the
     # diagnostic has to name **where the bound was written** (`sig/foo.rbs:12`), and the ADR-54 env
-    # cache dumps every `RBS::Location` to a zero-range `<cached>` sentinel, so a warm run would lose
-    # both the position and the only evidence of which file a declaration came from. Parsing the
-    # project's own signature sources is a few milliseconds over a tree Rigor already globs, it is
-    # identical warm and cold, and it enforces ADR-103 WD6's trust rule structurally: a `%a{pure}` in
-    # rbs core or in a gem's shipped RBS is never read, so it cannot bound a project method that
-    # happens to share its key.
+    # cache reduced every `RBS::Location` to a zero-range `<cached>` sentinel, so a warm run lost both
+    # the position and the only evidence of which file a declaration came from. That particular loss is
+    # closed now — #696 restored the buffer name, #799 an annotation's position — so what still decides
+    # it is the rest: parsing the project's own signature sources is a few milliseconds over a tree
+    # Rigor already globs, it is identical warm and cold, and it enforces ADR-103 WD6's trust rule
+    # structurally: a `%a{pure}` in rbs core or in a gem's shipped RBS is never read, so it cannot bound
+    # a project method that happens to share its key.
     #
     # Malformed payloads and `pure`-versus-`effect` contradictions are recorded on a {Reporter} the
     # scanner owns and ride out on {Result#unresolved}. They surface no diagnostic in this slice:

data/lib/rigor/rbs_extended/hkt_directives.rb

@@ -2,6 +2,7 @@
 
 require_relative "../inference/hkt_registry"
 require_relative "../inference/hkt_body_parser"
+require_relative "reporter"
 
 module Rigor
   module RbsExtended
@@ -286,10 +287,24 @@ module Rigor
         source_location.respond_to?(:start_line) ? source_location.start_line : nil
       end
 
+      # Issue #785 — routes a declined directive to the per-run reporter. The FIRST arm is the one that
+      # matters: the production reporter is {RbsExtended::Reporter}, whose surface is `record_unresolved` /
+      # `record_lossy_projection` / `record_hkt_error` — it has neither `#record` nor `#<<`, so before this
+      # arm existed every call here fell off the end of the `if` and every malformed HKT directive was
+      # dropped in every real run, while the doc comments claimed an `:info` entry was recorded. The
+      # position is flattened at record time through {RbsExtended::Reporter.position_of}, the one place
+      # every stream flattens through since #805, because the entry has to reach the pool drain channel as
+      # primitives (see {RbsExtended::Reporter}).
+      #
+      # The `#record` / `#<<` arms stay for the collecting doubles the directive specs and plugin authors
+      # use, which is the contract `scan_rbs_loader`'s `@param reporter [#record, nil]` documents.
       def record_hkt_error(reporter, message, source_location)
         return if reporter.nil?
 
-        if reporter.respond_to?(:record)
+        if reporter.respond_to?(:record_hkt_error)
+          path, line, column = Reporter.position_of(source_location)
+          reporter.record_hkt_error(message: message, path: path, line: line, column: column)
+        elsif reporter.respond_to?(:record)
           reporter.record(directive: "hkt", message: message, source_location: source_location)
         elsif reporter.respond_to?(:<<)
           reporter << { directive: "hkt", message: message, source_location: source_location }

data/lib/rigor/rbs_extended/reporter.rb

@@ -6,7 +6,7 @@ module Rigor
     # cannot surface at the point of failure (the parsers are fail-soft, returning `nil` so call sites fall back
     # to the RBS-declared type).
     #
-    # Owns two event streams:
+    # Owns three event streams:
     #
     # - `#unresolved_payloads` — `rigor:v1:*` directive payloads the resolver could not turn into a
     #   {Rigor::Type}. Surface as `dynamic.rbs-extended.unresolved` `:info` diagnostics.
@@ -14,21 +14,60 @@ module Rigor
     #   `required_of` / `readonly_of`) applied to a carrier that does not preserve shape information (anything
     #   other than `Type::HashShape` / `Type::Tuple`). Surface as `dynamic.shape.lossy-projection` `:info`
     #   diagnostics.
+    # - `#hkt_directive_errors` — malformed `rigor:v1:hkt_register` / `rigor:v1:hkt_define` directives the
+    #   ADR-20 parser declined. Surface as `dynamic.rbs-extended.hkt-directive-invalid` `:info` diagnostics.
     #
     # Mutable through the run; consumed once by {Rigor::Analysis::Runner} at end-of-run. Each event is
-    # deduplicated by `(payload, source_location)` for unresolved and `(head, source_location)` for
-    # lossy-projection so a single annotation read from many call sites yields one diagnostic.
+    # deduplicated by its whole entry — `(payload, path, line, column)` for unresolved, `(head, path, line,
+    # column)` for lossy-projection, `(message, path, line, column)` for an hkt directive — so a single
+    # annotation read from many call sites yields one diagnostic.
     #
     # The reporter is intentionally thread-safe via a coarse `Mutex` because the inference engine may read the
     # same method definition from multiple files in parallel; the critical sections are short (Array#include? +
     # Array#<<) so the lock contention is negligible.
     class Reporter
-      UnresolvedEntry = Data.define(:payload, :source_location)
-      LossyProjectionEntry = Data.define(:head, :source_location)
+      # Every entry carries its position as `(path, line, column)` primitives, flattened from the parser's
+      # `RBS::Location` by {.position_of} at record time. Issues #785 (hkt) and #805 (the two older streams).
+      # Two reasons, and either alone decides it. All three streams are drained out of every fork-pool worker
+      # ({Rigor::Analysis::WorkerSession#drain_reporters}), and an `RBS::Location` is a C-extension object with
+      # no `_dump`, so a `Marshal.dump` of the drain payload raises `TypeError` — which kills the worker at
+      # drain time and degrades the run to in-process re-analysis. And an `RBS::Location` compares equal only
+      # against a location over the SAME `RBS::Buffer` object, so two workers that each read the same `.rbs`
+      # would hand the coordinator two entries the dedup cannot collapse — `--workers=N` would then print N
+      # copies of a row `--workers=0` prints once.
+      #
+      # The record methods take the triple rather than the location for the same reason: a door that accepts
+      # an `RBS::Location` is a door a future caller reintroduces the bug through.
+      UnresolvedEntry = Data.define(:payload, :path, :line, :column)
+      LossyProjectionEntry = Data.define(:head, :path, :line, :column)
+      HktDirectiveEntry = Data.define(:message, :path, :line, :column)
+
+      # Flattens an `RBS::Location` (or anything answering the same readers) to the `(path, line, column)`
+      # triple every entry carries. `column` is 1-based, since `RBS::Location#start_column` is 0-based and
+      # diagnostics are not. Each component is `nil` when the location cannot supply it, and the diagnostic
+      # then falls back to `.rigor.yml:1:1`.
+      #
+      # Fail-soft by construction, like every parser that calls it: a location that raises while being read
+      # costs the entry its position, never the run.
+      #
+      # @param source_location [RBS::Location, nil]
+      # @return [Array(String, nil, Integer, nil, Integer, nil)]
+      def self.position_of(source_location)
+        return [nil, nil, nil] if source_location.nil?
+
+        buffer = source_location.respond_to?(:buffer) ? source_location.buffer : nil
+        name = buffer.respond_to?(:name) ? buffer.name.to_s : ""
+        line = source_location.respond_to?(:start_line) ? source_location.start_line : nil
+        column = source_location.respond_to?(:start_column) ? source_location.start_column + 1 : nil
+        [name.empty? ? nil : name, line, column]
+      rescue StandardError
+        [nil, nil, nil]
+      end
 
       def initialize
         @unresolved_payloads = []
         @lossy_projections = []
+        @hkt_directive_errors = []
         @mutex = Mutex.new
       end
 
@@ -42,11 +81,13 @@ module Rigor
         @mutex.synchronize { @lossy_projections.dup.freeze }
       end
 
-      # Records a `dynamic.rbs-extended.unresolved` event. The `source_location` argument is the {RBS::Location}
-      # attached to the source annotation (or `nil` when the caller doesn't have one — the diagnostic falls back
-      # to a generic location in that case).
-      def record_unresolved(payload:, source_location: nil)
-        entry = UnresolvedEntry.new(payload: payload.to_s, source_location: source_location)
+      # Records a `dynamic.rbs-extended.unresolved` event. The position triple is the source annotation's
+      # `.rbs` file / line / 1-based column — {.position_of} flattens the caller's `RBS::Location` into it —
+      # each `nil` when the caller had no location (the diagnostic then falls back to `.rigor.yml:1:1`).
+      def record_unresolved(payload:, path: nil, line: nil, column: nil)
+        entry = UnresolvedEntry.new(
+          payload: frozen_text(payload), path: frozen_text(path), line: line, column: column
+        )
         @mutex.synchronize do
           return if @unresolved_payloads.include?(entry)
 
@@ -56,8 +97,11 @@ module Rigor
 
       # Records a `dynamic.shape.lossy-projection` event for one of the five shape-projection heads. `head` MUST
       # be a String (`"pick_of"`, `"omit_of"`, …); the diagnostic message identifies which projection degraded.
-      def record_lossy_projection(head:, source_location: nil)
-        entry = LossyProjectionEntry.new(head: head.to_s, source_location: source_location)
+      # The position triple is read exactly as {#record_unresolved}'s is.
+      def record_lossy_projection(head:, path: nil, line: nil, column: nil)
+        entry = LossyProjectionEntry.new(
+          head: frozen_text(head), path: frozen_text(path), line: line, column: column
+        )
         @mutex.synchronize do
           return if @lossy_projections.include?(entry)
 
@@ -65,10 +109,46 @@ module Rigor
         end
       end
 
+      # @return [Array<HktDirectiveEntry>] frozen snapshot of the accumulated hkt-directive failures.
+      def hkt_directive_errors
+        @mutex.synchronize { @hkt_directive_errors.dup.freeze }
+      end
+
+      # Records a `dynamic.rbs-extended.hkt-directive-invalid` event: one malformed ADR-20 HKT directive the
+      # {Rigor::RbsExtended::HktDirectives} parser declined. `message` names what the parser objected to; the
+      # position triple is the annotation's `.rbs` file / line / 1-based column, each `nil` when the caller had
+      # no location (the diagnostic then falls back to `.rigor.yml:1:1`).
+      #
+      # Every String is frozen individually, not just the enclosing `Data`: the entry crosses the pool drain
+      # channel, whose stated invariant is that its payload is `Ractor.shareable?` as well as Marshal-clean.
+      def record_hkt_error(message:, path: nil, line: nil, column: nil)
+        entry = HktDirectiveEntry.new(
+          message: frozen_text(message), path: frozen_text(path), line: line, column: column
+        )
+        @mutex.synchronize do
+          return if @hkt_directive_errors.include?(entry)
+
+          @hkt_directive_errors << entry
+        end
+      end
+
       # True when no events have accumulated. Used by callers that want to skip the diagnostic-emission pass
       # entirely on the common no-event path.
       def empty?
-        @mutex.synchronize { @unresolved_payloads.empty? && @lossy_projections.empty? }
+        @mutex.synchronize do
+          @unresolved_payloads.empty? && @lossy_projections.empty? && @hkt_directive_errors.empty?
+        end
+      end
+
+      private
+
+      # `nil` stays `nil` — the diagnostic falls back to `.rigor.yml:1:1` on a missing path. Anything else
+      # becomes an individually frozen String: the `Data` wrapper is frozen on its own, but the pool drain's
+      # stated invariant is that its payload is `Ractor.shareable?`, which is a DEEP freeze. Coercing here also
+      # means a caller that hands the door an `RBS::Location` by mistake stores its `#to_s`, not the object —
+      # the entry cannot become un-Marshalable from the outside.
+      def frozen_text(value)
+        value.nil? ? nil : value.to_s.dup.freeze
       end
     end
   end

data/lib/rigor/rbs_extended.rb

@@ -812,10 +812,15 @@ module Rigor
     # ADR-13 slice 3b — guards every reporter call so the in-RbsExtended-module call sites can record events
     # uniformly without nil-checking each time. When the reporter is nil (the v0.1.0 → v0.1.3 default for call
     # sites that do not yet thread `environment:`), the call is a no-op and the parser stays fail-soft.
+    #
+    # Issue #805 — the location is flattened to `(path, line, column)` here, at record time, because the
+    # entry is drained out of every fork-pool worker and an `RBS::Location` neither survives `Marshal.dump`
+    # nor compares equal across two workers' buffers (see {Rigor::RbsExtended::Reporter}).
     def record_unresolved(reporter, payload, source_location)
       return if reporter.nil?
 
-      reporter.record_unresolved(payload: payload, source_location: source_location)
+      path, line, column = Reporter.position_of(source_location)
+      reporter.record_unresolved(payload: payload, path: path, line: line, column: column)
     end
   end
 end

data/lib/rigor/sig_gen/generator.rb

@@ -24,12 +24,16 @@ module Rigor
     # body's last expression to derive an inferred return, looks up the project's existing RBS declaration (if
     # any), and emits one {MethodCandidate} per def.
     #
-    # The MVP keeps the scope deliberately narrow:
-    # - Only instance methods inside a `class` / `module` body are considered. Top-level / DSL-block / singleton
-    #   defs are skipped (`sig.skipped.complex-shape`).
-    # - Parameter signatures are hard-coded to `untyped` per ADR-14 § "Robustness principle compliance" clause 2;
-    #   `--params=observed` arrives in slice 3.
-    # - Optional / rest / keyword / block params disqualify the def (`sig.skipped.complex-shape`).
+    # The scope, as it stands after the slices that widened the MVP:
+    # - Instance and singleton methods inside a nameable `class` / `module` body are considered. Top-level /
+    #   DSL-block defs have no nameable receiver and are not candidates.
+    # - Parameter types are `untyped` per ADR-14 § "Robustness principle compliance" clause 2 unless
+    #   `--params=observed` supplies call-site observations; the parameter LIST always mirrors the def's runtime
+    #   shape (required / optional / rest / trailing / keyword / keyword-rest / forwarding / block). Issue #778
+    #   retired the slice-1 gate that skipped every shape beyond required positionals as
+    #   `sig.skipped.complex-shape`: the body typer binds every parameter to `untyped` when no RBS declares the
+    #   method, so the inferred return is the same clause-1 answer for every shape, and the renderer the
+    #   `initialize` stub already used spells them all.
     # - A `Dynamic[top]` inferred return becomes `sig.skipped.untyped-return` — emitting `untyped` would obscure
     #   rather than help.
     # - Tighter-return detection compares the RBS-erased spellings only when the existing declared return
@@ -650,8 +654,8 @@ module Rigor
       end
 
       # Emits `def initialize: (<shape>) -> void`. The return is always `void` because Ruby's `initialize`
-      # return value is never meaningful. The parameter list mirrors the runtime shape (required / optional /
-      # rest / keyword / keyword-rest / block).
+      # return value is never meaningful. The parameter list mirrors the runtime shape through the same
+      # {#render_param_list} every other def renders with.
       #
       # When `--params=observed` populates `@observations` for `[class_name, :initialize]` (via the
       # `ObservationCollector`'s `.new` → `:initialize` routing), positional and keyword arg types come from the
@@ -659,7 +663,7 @@ module Rigor
       # clause 2.
       def initialize_stub_candidate(path, def_node, class_name)
         params = def_node.parameters
-        rbs = "def initialize: (#{render_initialize_param_list(params, class_name)})" \
+        rbs = "def initialize: (#{render_param_list(params, class_name, :initialize)})" \
               "#{block_signature_suffix(params)} -> void"
         build_candidate(
           path: path, class_name: class_name, method_name: :initialize,
@@ -668,57 +672,81 @@ module Rigor
         )
       end
 
-      def render_initialize_param_list(params, class_name)
+      # The RBS parameter list of a def, mirroring its runtime shape position by position: `untyped` per
+      # required positional, `?untyped` per optional, `*untyped` for a rest, one `untyped` per trailing
+      # positional after the rest, `name: untyped` / `?name: untyped` per keyword, `**untyped` for a keyword
+      # rest, and `*untyped, **untyped` for `...` forwarding (its block half is {#block_signature_suffix}'s).
+      # `**nil` declares that no keywords are accepted, which RBS cannot spell, so it renders nothing.
+      #
+      # Per ADR-5 clause 2 every position is `untyped` unless `--params=observed` supplied call-site
+      # observations, in which case each leading positional and each keyword carries the union of the types the
+      # arity-compatible observations passed there ({#arity_matched_observations}). The rest, the trailing
+      # positionals and the keyword rest stay `untyped`: an observation does not say which of its arguments the
+      # splat absorbed. Before #778 only `initialize` rendered through this path and every other def with a
+      # shape beyond required positionals was skipped as `sig.skipped.complex-shape`.
+      def render_param_list(params, class_name, method_name)
         return "" unless params.is_a?(Prism::ParametersNode)
 
-        observations = initialize_observations(class_name, params)
-        offset = 0
+        observations = arity_matched_observations(class_name, method_name, params)
         parts = []
-
-        params.requireds.each_with_index do |_, i|
-          parts << initialize_positional_type(observations, offset + i, "")
-        end
-        offset += params.requireds.size
-
-        params.optionals.each_with_index do |_, i|
-          parts << initialize_positional_type(observations, offset + i, "?")
-        end
-
+        params.requireds.each_index { |i| parts << positional_type(observations, i, "") }
+        offset = params.requireds.size
+        params.optionals.each_index { |i| parts << positional_type(observations, offset + i, "?") }
         parts << "*untyped" if params.rest
+        parts.concat(Array.new(params.posts.size, "untyped"))
         params.keywords.each { |kw| parts << render_keyword_param(kw, observations) }
-        parts << "**untyped" if params.keyword_rest
+        parts.concat(keyword_rest_parts(params))
         parts.join(", ")
       end
 
+      def keyword_rest_parts(params)
+        case params.keyword_rest
+        when Prism::ForwardingParameterNode
+          # `...` forwards positionals as well as keywords; a rest already rendered covers the former.
+          params.rest ? ["**untyped"] : ["*untyped", "**untyped"]
+        when Prism::KeywordRestParameterNode then ["**untyped"]
+        else []
+        end
+      end
+
       # The RBS block suffix for a `def` that takes a `&block` parameter, e.g. ` ?{ (*untyped) -> untyped }`.
       # A block belongs AFTER the parameter parens in RBS (`(params) ?{ block } -> ret`), not inside them —
       # emitting it as a comma-joined member produced `(**untyped, ?{ (?) -> void })`, which RBS rejects
       # (`optional keyword argument type is expected`) and which then collapsed the whole env build. sig-gen
       # never observes the block's own signature, so it is rendered maximally lenient (ADR-5): an optional
-      # block (`?{`, since a `&block` need not be passed) taking `*untyped` and returning `untyped`. Returns
-      # "" when the method takes no block.
+      # block (`?{`, since a `&block` need not be passed) taking `*untyped` and returning `untyped`. `...`
+      # forwards a block too and gets the same suffix. Returns "" when the method takes no block.
       def block_signature_suffix(params)
         return "" unless params.is_a?(Prism::ParametersNode)
-        return "" if params.block.nil?
+        return "" unless params.block || params.keyword_rest.is_a?(Prism::ForwardingParameterNode)
 
         " ?{ (*untyped) -> untyped }"
       end
 
-      # Picks observations under `[class_name, :initialize]` whose positional arity matches the def's accepted
-      # range (required..required+optional). Looser arities don't get used because they describe a different
-      # overload the stub cannot express.
-      def initialize_observations(class_name, params)
+      # Observations under `[class_name, method_name]` whose positional arity the def accepts: at least its
+      # required count (leading plus trailing), and, unless a rest or `...` absorbs the surplus, at most
+      # required plus optional. An arity outside that window describes a different overload the signature
+      # cannot express, so it says nothing about these positions. #778 widened the window for ordinary defs
+      # from the exact required count — `def optional(text = "x")` called as `optional` AND as `optional("y")`
+      # now credits both call sites.
+      def arity_matched_observations(class_name, method_name, params)
         return [] if @observations.empty?
 
-        list = @observations[[class_name, :initialize]] || []
-        min = params.requireds.size
-        max = min + params.optionals.size
-        list.select { |obs| (min..max).cover?(obs.positional.size) }
+        list = @observations[[class_name, method_name]] || []
+        min = params.requireds.size + params.posts.size
+        max = unbounded_positionals?(params) ? Float::INFINITY : min + params.optionals.size
+        list.select { |obs| obs.positional.size.between?(min, max) }
+      end
+
+      def unbounded_positionals?(params)
+        !params.rest.nil? || params.keyword_rest.is_a?(Prism::ForwardingParameterNode)
       end
 
-      def initialize_positional_type(observations, index, prefix)
+      # A bare union is a valid positional type in RBS (`(String | Integer, ?String | Integer)`), so unlike the
+      # return position it is not parenthesised.
+      def positional_type(observations, index, prefix)
         types = observations.filter_map { |obs| obs.positional[index] }
-        "#{prefix}#{types.empty? ? 'untyped' : paren_wrap_union(union_erase(types))}"
+        "#{prefix}#{union_erase(types)}"
       end
 
       def render_keyword_param(keyword, observations)
@@ -746,10 +774,6 @@ module Rigor
         return nil if initialize_excludes?(def_node, kind)
         return initialize_stub_candidate(path, def_node, class_name) if non_trivial_initialize?(def_node, kind)
 
-        unless simple_parameter_shape?(def_node.parameters)
-          return skipped(path, def_node, class_name, kind, :complex_shape)
-        end
-
         inferred = infer_return_type(def_node, scope_index)
         return skipped(path, def_node, class_name, kind, :untyped_return) if inferred.nil? || dynamic_top?(inferred)
 
@@ -763,20 +787,6 @@ module Rigor
         end
       end
 
-      # Required positionals only; the MVP's body-typing path gives well-defined returns for that shape.
-      # Optional / rest / keyword / block parameters route through the `sig.skipped.complex-shape` reason until
-      # slices 3+ widen the param policy.
-      def simple_parameter_shape?(params)
-        return true if params.nil?
-        return false unless params.is_a?(Prism::ParametersNode)
-
-        params.optionals.empty? &&
-          params.rest.nil? &&
-          params.keywords.empty? &&
-          params.keyword_rest.nil? &&
-          params.block.nil?
-      end
-
       # Mirrors the `def.return-type-mismatch` rule's body-type extraction: type the implicit-return expression
       # under the scope the indexer associated with the body. The parameter bindings (typed `untyped` per the
       # indexer's default) come from `with_local` inside `StatementEvaluator`; the result is the carrier the
@@ -991,8 +1001,8 @@ module Rigor
       end
 
       def render_rbs_line(def_node, inferred, class_name, kind)
-        arity = required_arity(def_node)
-        head = arity.zero? ? "()" : "(#{render_param_list(class_name, def_node.name, arity)})"
+        params = def_node.parameters
+        head = "(#{render_param_list(params, class_name, def_node.name)})#{block_signature_suffix(params)}"
         prefix = method_def_prefix(class_name, def_node.name, kind)
         "#{prefix}#{def_node.name}: #{head} -> #{paren_wrap_union(elaborated_rbs(inferred))}"
       end
@@ -1028,30 +1038,6 @@ module Rigor
         false
       end
 
-      def required_arity(def_node)
-        params = def_node.parameters
-        params.is_a?(Prism::ParametersNode) ? params.requireds.size : 0
-      end
-
-      # Per ADR-5 clause 2 the default is `untyped` for every position. Observed-policy callers
-      # (`--params=observed`) pass an `observations:` map at construction time; the generator unions
-      # per-position arg types whose tuple arity matches the def's required-positional count. Observations from
-      # arities other than the def's count are discarded — they describe a different overload the MVP does not
-      # emit.
-      def render_param_list(class_name, method_name, arity)
-        tuples = matching_observations(class_name, method_name, arity)
-        return Array.new(arity, "untyped").join(", ") if tuples.empty?
-
-        Array.new(arity) { |i| union_erase(tuples.map { |obs| obs.positional[i] }) }.join(", ")
-      end
-
-      def matching_observations(class_name, method_name, arity)
-        return [] if @observations.empty?
-
-        list = @observations[[class_name, method_name]] || []
-        list.select { |obs| obs.positional.size == arity }
-      end
-
       def union_erase(types)
         return "untyped" if types.empty?
         return elaborated_rbs(types.first) if types.size == 1

data/lib/rigor/sig_gen/renderer.rb

@@ -14,7 +14,8 @@ module Rigor
     # - `:diff` — a unified-style diff comparing the existing RBS spelling (if any) against the inferred
     #   spelling. The MVP renders a minimal "- declared / + inferred" block; full per-file diffing arrives with
     #   slice 2's `--write` merge.
-    # - `:json` — machine-readable payload with the same classification table as `:print`.
+    # - `:json` — machine-readable payload with the same classification table as `:print`, plus every `skipped`
+    #   row with its `skip_reason` (#778).
     class Renderer
       def initialize(out:)
         @out = out
@@ -27,11 +28,10 @@ module Rigor
       #   {Classification} constants to include; an empty
       #   array means "all emittable classifications".
       def render(candidates:, mode:, format:, selection:)
-        filtered = filter(candidates, selection)
-
         case format
-        when "json" then render_json(filtered)
+        when "json" then render_json(filter(candidates, selection, with_skipped: true))
         when "text"
+          filtered = filter(candidates, selection)
           mode == :diff ? render_diff(filtered) : render_print(filtered)
         else
           raise ArgumentError, "unsupported format: #{format}"
@@ -40,9 +40,16 @@ module Rigor
 
       private
 
-      def filter(candidates, selection)
+      # The emittable rows the selection asks for. JSON also carries every `skipped` row whatever the selection:
+      # ADR-14 makes the JSON payload the surface where `sig.skipped.*` is reported, and a consumer asking why a
+      # method is missing from its `sig/` needs the reason next to the rows that did emit (#778 — the rows were
+      # built with their `skip_reason` and then dropped here). `equivalent` rows stay out: nothing to do,
+      # nothing to explain.
+      def filter(candidates, selection, with_skipped: false)
         active = selection.empty? ? Classification::EMITTABLE : selection
-        candidates.select { |c| active.include?(c.classification) }
+        candidates.select do |c|
+          active.include?(c.classification) || (with_skipped && c.classification == Classification::SKIPPED)
+        end
       end
 
       def render_print(candidates)

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.3.7"
+  VERSION = "0.3.8"
 end

data/sig/rigor/environment.rbs

@@ -13,6 +13,12 @@ module Rigor
     attr_reader synthetic_method_index: untyped?
     attr_reader project_patched_methods: untyped?
     attr_reader hkt_registry: untyped?
+    # Issue #784 — `[error_class_name, first_message_line, raw_frame_or_nil, stage]` when either stage of
+    # the HKT-registry build raised at its seam (`:scan`, the RBS `type`-alias scan; `:overlay`, the
+    # plugin-manifest aggregation — #791), nil when both built or were never demanded. Declared `untyped?`
+    # like its neighbours:
+    # `rigor sig-gen` emits nothing for this delegating reader, and the tuple shape is documented here.
+    def hkt_scan_failure: () -> untyped?
 
     def self.default: () -> Environment
     def self.for_project: (?root: String, ?libraries: Array[String], ?signature_paths: Array[String | _ToPath]?, ?cache_store: untyped?, ?plugin_registry: untyped?, ?dependency_source_index: untyped?, ?rbs_extended_reporter: untyped?, ?boundary_cross_reporter: untyped?, ?source_rbs_synthesis_reporter: untyped?, ?bundler_bundle_path: String?, ?bundler_auto_detect: bool, ?synthetic_method_index: untyped?, ?project_patched_methods: untyped?) -> Environment