rigortype 0.3.0 → 0.3.2

data/lib/rigor/sig_gen/writer.rb

@@ -275,13 +275,23 @@ module Rigor
 
       def update_existing(source_path, target, candidates)
         source = target.read
+        # Pre-parser encoding guard, mirroring `Environment::RbsLoader.invalid_encoding?`: handed invalid
+        # UTF-8, `RBS::Parser` raises a bare `ArgumentError` on rbs 4.1 (not the `ParsingError` that
+        # `parse_signature` below rescues) and could hang outright on the older releases the gemspec
+        # supports. The refusal is loud — unlike an unparseable file (`:noop`, surfaced by `rigor check`'s
+        # own quarantine warning), a mojibake file would otherwise fail with a stack trace naming neither
+        # the file nor the fix.
+        unless source.valid_encoding?
+          return WriteResult.new(source_path: source_path, target_path: target,
+                                 action: :skipped_invalid_encoding,
+                                 error: "#{target} is not valid UTF-8")
+        end
+
         decls = parse_signature(source)
         return WriteResult.new(source_path: source_path, target_path: target, action: :noop) if decls.nil?
 
         state = MergeState.new(source: source, decls: decls, applied: [], skipped: [])
-        supers = merged_superclasses(candidates)
-        candidates.group_by(&:class_name).each { |class_name, methods| merge_class(state, class_name, methods, supers) }
-        merge_class_shells(state, collect_class_shells(candidates), merged_namespace_kinds(candidates))
+        merge_candidates(state, candidates)
 
         action = state.applied.empty? ? :noop : :updated
         unless action == :updated
@@ -304,25 +314,42 @@ module Rigor
                         action: action, applied: state.applied, skipped: state.skipped)
       end
 
+      # Applies every class group, then every requested shell, then normalises the layout the three steps
+      # leave behind. Each step mutates `state` in place and re-parses, so the next one sees current offsets.
+      def merge_candidates(state, candidates)
+        supers = merged_superclasses(candidates)
+        kinds = merged_namespace_kinds(candidates)
+        shells = collect_class_shells(candidates)
+        groups = candidates.group_by(&:class_name)
+        # Ancestors first, so `Foo` is created (or found) before `Foo::Bar` looks for a parent to nest under.
+        # A plain sort suffices: a name always sorts before every name it is a strict prefix of.
+        groups.keys.sort.each { |name| merge_class(state, name, groups.fetch(name), kinds, supers) }
+        merge_class_shells(state, shells, kinds, supers)
+        collapse_nested_declarations(state, groups.keys + shells.to_a)
+      end
+
       # ADR-14 gap-#3 (e): for every requested class shell that isn't already declared in the target file,
       # insert an empty `class Const\nend` block inside the nearest existing ancestor. Shells already covered by
       # an existing declaration are silently a no-op. The `applied` accumulator does NOT grow — shells are
       # structural declarations, not methods, so the action-count surface (`updated +N`) keeps reflecting method
       # changes only.
-      def merge_class_shells(state, shells, kinds)
+      def merge_class_shells(state, shells, kinds, supers)
         shells.each do |qualified|
           next if find_class_decl(state.decls, qualified)
 
-          insert_class_shell(state, qualified, kinds)
+          insert_namespace_chain(state, qualified, kinds, supers, [])
         end
       end
 
-      def insert_class_shell(state, qualified, kinds)
+      # Splices the missing part of `qualified`'s namespace chain into the nearest declaration the file
+      # already has for one of its ancestors, or at top level when it has none. `methods` land on the leaf
+      # node, so this is the single insertion path for both an empty class shell and a brand-new class.
+      def insert_namespace_chain(state, qualified, kinds, supers, methods)
         segments = qualified.split("::")
         anchor_segs, missing = split_at_existing_ancestor(state.decls, segments)
         anchor_decl = anchor_segs.empty? ? nil : find_class_decl(state.decls, anchor_segs.join("::"))
-        depth = anchor_decl ? anchor_decl_indent_depth(anchor_decl) : 0
-        snippet = build_shell_snippet(missing, anchor_segs, kinds, depth)
+        depth = anchor_decl ? member_indent_depth(anchor_decl) : 0
+        snippet = render_chain_snippet(missing, anchor_segs, kinds, supers, depth, methods)
         state.source = if anchor_decl
                          insert_before_end(state.source, anchor_decl, snippet)
                        else
@@ -331,6 +358,113 @@ module Rigor
         state.decls = parse_signature(state.source) || state.decls
       end
 
+      # ADR-14 gap-#3 follow-up (c), update half: the create path folds a strict-prefix pair into one nested
+      # tree, but a file written before that fix — or by hand — can still carry the flat sibling layout
+      # (`class Foo` next to a top-level `class Foo::Bar`). After merging, relocate each declaration this run
+      # touched underneath its parent's declaration when the same file holds both, so an update converges on
+      # the same canonical layout a fresh generation would produce.
+      #
+      # Scope is deliberately the touched names only: an unrelated flat pair elsewhere in the file is none of
+      # sig-gen's business, and rewriting it would be a layout change the user never asked for. Shallowest
+      # first, so `Foo::Bar` has already moved under `Foo` by the time `Foo::Bar::Baz` looks for its parent.
+      def collapse_nested_declarations(state, names)
+        names.uniq.sort.each { |name| relocate_under_parent(state, name) }
+      end
+
+      def relocate_under_parent(state, qualified)
+        segments = qualified.split("::")
+        return if segments.size < 2
+
+        parent_name = segments[0...-1].join("::")
+        parent = find_class_decl(state.decls, parent_name)
+        decl = parent && find_class_decl(state.decls, qualified)
+        return if decl.nil? || overlapping?(parent, decl)
+
+        region = decl_region(state.source, decl)
+        block = region && relocated_block(state.source, decl, parent, segments.last, region)
+        return if block.nil?
+
+        apply_relocation(state, region, parent_name, block)
+      end
+
+      # Cuts the declaration's region out, re-parses so the parent's byte range reflects the removal, and
+      # splices the re-indented block back in as the parent's last member. Any step that cannot be carried
+      # out cleanly (an unparseable intermediate, a parent that vanished) abandons the move and leaves the
+      # merged source exactly as it was — a flat layout is cosmetic, a mangled `.rbs` is not.
+      def apply_relocation(state, region, parent_name, block)
+        source = splice_out(state.source, region)
+        decls = parse_signature(source)
+        anchor = decls && find_class_decl(decls, parent_name)
+        return if anchor.nil?
+
+        state.source = insert_before_end(source, anchor, block)
+        state.decls = parse_signature(state.source) || state.decls
+      end
+
+      # True when the two declarations' source ranges are not disjoint — either one already nests the other,
+      # or the file's shape is one this pass does not understand. Both are reasons not to move anything.
+      def overlapping?(one, other)
+        one.location.start_pos < other.location.end_pos && other.location.start_pos < one.location.end_pos
+      end
+
+      # The declaration's full source region, extended to cover its leading comment and annotations and to
+      # end just past the newline that closes it. Returns `nil` when either edge shares a line with something
+      # else, because cutting there would move — or strand — text the declaration does not own.
+      def decl_region(source, decl)
+        start_pos = ([decl.location.start_pos] + leading_positions(decl)).min
+        line_start = line_start_index(source, start_pos)
+        return nil unless blank_range?(source, line_start, start_pos)
+
+        finish = decl.location.end_pos
+        line_end = source.index("\n", finish) || source.size
+        return nil unless blank_range?(source, finish, line_end)
+
+        line_start...(line_end < source.size ? line_end + 1 : line_end)
+      end
+
+      def leading_positions(decl)
+        positions = decl.annotations.filter_map { |a| a.location&.start_pos }
+        comment_location = decl.comment&.location
+        positions << comment_location.start_pos if comment_location
+        positions
+      end
+
+      # The moved text, with its compact `Foo::Bar` head shortened to `Bar` and every line pushed in to the
+      # parent's member depth. The name's own sub-location drives the rewrite, so a superclass, type
+      # parameters, and the whole body survive byte-for-byte.
+      def relocated_block(source, decl, parent, short_name, region)
+        name_location = decl.location[:name]
+        return nil if name_location.nil?
+
+        text = source[region].to_s
+        head = name_location.start_pos - region.begin
+        tail = name_location.end_pos - region.begin
+        renamed = text[0...head].to_s + short_name + text[tail..].to_s
+        reindent(renamed, member_indent_depth(parent) - decl_indent_depth(decl))
+      end
+
+      def reindent(text, delta)
+        return text unless delta.positive?
+
+        prefix = INDENT * delta
+        text.lines.map { |line| line.match?(/\A\s*\z/) ? line : prefix + line }.join
+      end
+
+      # Removes `region`, collapsing the newline run left behind at the seam so the cut never shows up as a
+      # widening gap (or a trailing blank line at EOF) in the file it edited. Spacing that was already fine
+      # is left exactly as the user wrote it.
+      def splice_out(source, region)
+        before = source[0...region.begin].to_s
+        after = source[region.end..].to_s
+        return after.sub(/\A\n+/, "") if before.match?(/\A\s*\z/)
+        return before.sub(/\n{2,}\z/, "\n") if after.match?(/\A\s*\z/)
+
+        seam = before[/\n+\z/].to_s.size + after[/\A\n+/].to_s.size
+        return before + after if seam <= 2
+
+        "#{before.sub(/\n+\z/, "\n\n")}#{after.sub(/\A\n+/, '')}"
+      end
+
       def split_at_existing_ancestor(decls, segments)
         (segments.size - 1).downto(0).each do |i|
           ancestor = segments[0...i].join("::")
@@ -339,37 +473,61 @@ module Rigor
         [[], segments]
       end
 
-      # Pulls the indent depth (in `INDENT` units) one level deeper than the anchor decl's own column.
-      # Pre-existing members might be missing (an empty `class Foo; end`) so the keyword column is the robust
-      # signal.
-      def anchor_decl_indent_depth(decl)
-        decl_column = decl.location[:keyword].start_column
-        (decl_column / INDENT.size) + 1
+      # The indent depth (in `INDENT` units) a member of `decl` sits at: one level deeper than the
+      # declaration's own keyword column. Pre-existing members might be missing (an empty `class Foo; end`)
+      # so the keyword column is the robust signal.
+      def member_indent_depth(decl)
+        decl_indent_depth(decl) + 1
+      end
+
+      def decl_indent_depth(decl)
+        decl.location[:keyword].start_column / INDENT.size
       end
 
-      def build_shell_snippet(missing, anchor_segs, kinds, depth)
+      # Renders the `missing` segment chain as one nested block, carrying `methods` on its leaf, by handing a
+      # synthesised tree node to the create path's renderer. Both paths therefore agree on the keyword, the
+      # superclass suffix, and the indentation of every level. A leaf with no methods is a class shell, which
+      # is exactly the create path's `shell:` node (gap-#3 (e)).
+      def render_chain_snippet(missing, anchor_segs, kinds, supers, depth, methods)
         return "" if missing.empty?
 
-        head, *rest = missing
-        qualified = (anchor_segs + [head]).join("::")
-        indent = INDENT * depth
-        if rest.empty?
-          keyword = kinds[qualified] || :class
-          "#{indent}#{keyword} #{head}\n#{indent}end\n"
-        else
-          inner = build_shell_snippet(rest, anchor_segs + [head], kinds, depth + 1)
-          keyword = kinds[qualified] || :module
-          "#{indent}#{keyword} #{head}\n#{inner}#{indent}end\n"
+        node = missing.reverse.each_with_index.inject(nil) do |child, (segment, index)|
+          { name: segment, children: child ? { child[:name] => child } : {},
+            methods: index.zero? ? methods : [], shell: index.zero? && methods.empty? }
         end
+        render_tree_node(node, kinds, supers, depth, anchor_segs)
       end
 
+      # Splices `snippet` in just before the declaration's closing `end`. When that `end` starts its own line
+      # the insertion point moves to the START of that line: the snippet carries its own indentation, and
+      # anchoring at the keyword would otherwise donate the `end`'s indent to the snippet's first line and
+      # strand the `end` in column zero.
       def insert_before_end(source, decl, snippet)
+        return source if snippet.empty?
+
         end_pos = decl.location[:end].start_pos
-        source[0...end_pos] + snippet + source[end_pos..]
+        line_start = line_start_index(source, end_pos)
+        return source[0...line_start] + snippet + source[line_start..] if blank_range?(source, line_start, end_pos)
+
+        "#{source[0...end_pos]}\n#{snippet}#{source[end_pos..]}"
       end
 
+      # Appends a top-level block, separated from whatever precedes it by exactly one blank line.
       def append_top_level(source, snippet)
-        ends_with_newline?(source) ? source + snippet : "#{source}\n#{snippet}"
+        return snippet if source.empty?
+
+        base = ends_with_newline?(source) ? source : "#{source}\n"
+        base.end_with?("\n\n") ? base + snippet : "#{base}\n#{snippet}"
+      end
+
+      def line_start_index(source, pos)
+        return 0 unless pos.positive?
+
+        (source.rindex("\n", pos - 1) || -1) + 1
+      end
+
+      def blank_range?(source, from, to)
+        source[from...to].to_s.match?(/\A[ \t]*\z/)
       end
 
       def parse_signature(source)
@@ -379,14 +537,15 @@ module Rigor
         nil
       end
 
-      def merge_class(state, class_name, methods, supers = {})
+      def merge_class(state, class_name, methods, kinds, supers)
         decl = find_class_decl(state.decls, class_name)
-        state.source = if decl.nil?
-                         append_new_class(state.source, class_name, methods, state.applied, supers[class_name])
-                       else
-                         merge_into_existing_class(state.source, decl, methods, state.applied, state.skipped)
-                       end
-        state.decls = parse_signature(state.source) || state.decls
+        if decl.nil?
+          state.applied.concat(methods)
+          insert_namespace_chain(state, class_name, kinds, supers, methods)
+        else
+          state.source = merge_into_existing_class(state.source, decl, methods, state.applied, state.skipped)
+          state.decls = parse_signature(state.source) || state.decls
+        end
       end
 
       # Walks the parsed decl tree recursively, tracking the enclosing module/class prefix, and returns the
@@ -411,16 +570,6 @@ module Rigor
         nil
       end
 
-      # Appends an entirely new `class Foo … end` block at the end of the file (with a leading blank line as
-      # separator).
-      def append_new_class(source, class_name, methods, applied, superclass = nil)
-        body = methods.map { |c| "#{INDENT}#{c.rbs}" }.join("\n")
-        header = superclass ? "class #{class_name} < #{superclass}" : "class #{class_name}"
-        snippet = "\n#{header}\n#{body}\nend\n"
-        applied.concat(methods)
-        ends_with_newline?(source) ? source + snippet : "#{source}\n#{snippet}"
-      end
-
       def ends_with_newline?(source)
         source.end_with?("\n")
       end
@@ -477,9 +626,8 @@ module Rigor
       def insert_into_class(source, decl, new_methods)
         return source if new_methods.empty?
 
-        end_pos = decl.location[:end].start_pos
-        addition = new_methods.map { |c| "#{INDENT}#{c.rbs}\n" }.join
-        source[0...end_pos] + addition + source[end_pos..]
+        indent = INDENT * member_indent_depth(decl)
+        insert_before_end(source, decl, new_methods.map { |c| "#{indent}#{c.rbs}\n" }.join)
       end
 
       # Walks the class's existing method declarations; for each replaceable candidate that matches a member

data/lib/rigor/sig_gen.rb

@@ -3,6 +3,7 @@
 require_relative "sig_gen/classification"
 require_relative "sig_gen/method_candidate"
 require_relative "sig_gen/observed_call"
+require_relative "sig_gen/meta_class_shape"
 require_relative "sig_gen/type_elaborator"
 require_relative "sig_gen/observation_collector"
 require_relative "sig_gen/generator"

data/lib/rigor/version.rb

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

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable.rb

@@ -42,6 +42,25 @@ module Rigor
     #   informational only (deferred: cross-plugin handoff to a JS-side analyzer).
     # - **`broadcast_to` arity isn't checked.** The method takes any record + any data hash; there's no
     #   useful arity envelope.
+    #
+    # ## `#receive(data)` protocol contract (ADR-28)
+    #
+    # ActionCable's `Connection::Subscriptions#perform_action` dispatches an incoming message to the
+    # action named by the payload's `"action"` key, defaulting to `:receive` when that key is absent —
+    # i.e. `#receive(data)` is the framework-documented catch-all handler for messages with no explicit
+    # action. Either way the single positional argument is always the `ActiveSupport::JSON.decode` of the
+    # client-sent payload, which is a JSON object and therefore a `Hash` by convention (the bundled JS
+    # client only ever calls `perform(action, data = {})` with an object). This plugin declares a
+    # path-scoped protocol contract (`method_name: :receive`, `param_types: [{index: 0, type_name:
+    # "Hash"}]`) so `data` types as `Hash` instead of `Dynamic[Top]` inside a channel's `#receive` body.
+    #
+    # Deliberately narrower than Hanami's `#handle`: custom action methods (`def speak(data)`) also
+    # receive the decoded Hash, but their names are project-chosen, not a single fixed Symbol a
+    # `ProtocolContract` can name — only `:receive` is a framework-reserved, uniformly-shaped method name.
+    # Per ADR-28, the contract is path-scoped, not class-scoped: any `#receive(data)` defined anywhere
+    # under the (possibly multi-root) `channel_search_paths` is typed, even on a stray non-channel class
+    # that happens to live in that directory — the same accepted-risk shape as `rigor-hanami`'s
+    # `#handle`.
     class Actioncable < Rigor::Plugin::Base
       manifest(
         id: "actioncable",
@@ -53,7 +72,15 @@ module Rigor
             kind: :array,
             default: ["ApplicationCable::Channel", "ActionCable::Channel::Base"]
           }
-        }
+        },
+        protocol_contracts: [
+          Rigor::Plugin::ProtocolContract.new(
+            path_glob: "app/channels/**/*.rb",
+            method_name: :receive,
+            param_types: [{ index: 0, type_name: "Hash" }]
+            # return_type_name: nil — receive's return value is discarded by the framework dispatcher.
+          )
+        ]
       )
 
       # `watch:` covers every `.rb` file under the channel search paths so the cache invalidates when
@@ -70,6 +97,20 @@ module Rigor
       def init(_services)
         @channel_search_paths = Array(config.fetch("channel_search_paths")).map(&:to_s)
         @channel_base_classes = Array(config.fetch("channel_base_classes")).map(&:to_s)
+
+        # ADR-28 WD5 — `channel_search_paths` is user-configurable and may name multiple roots; retarget
+        # the manifest's default `app/channels/**/*.rb` glob to the actual configured root(s) so the
+        # contract neither goes inert on a project that renames/adds channel directories nor (more
+        # importantly, per the project's false-positive discipline) risks matching an unrelated `#receive`
+        # outside them. `File::FNM_EXTGLOB` (enabled by `Registry#contracts_for_path`) makes a `{a,b}`
+        # brace group a single valid glob for multiple roots.
+        @protocol_contracts = manifest.protocol_contracts.map { |c| c.with_path_glob(channel_search_glob) }
+      end
+
+      # ADR-28 — override so the per-project `channel_search_paths` config reaches both the engine's
+      # parameter-provision tier and this plugin's own path-scoped reasoning.
+      def protocol_contracts
+        @protocol_contracts || manifest.protocol_contracts
       end
 
       # File-level only: the load-error emission. Per-call broadcast validation runs over the
@@ -91,6 +132,15 @@ module Rigor
 
       private
 
+      # Builds the `#receive` contract's `path_glob` from the configured `channel_search_paths`. A single
+      # root becomes a plain `**/*.rb` glob; multiple roots become an `FNM_EXTGLOB` brace group so every
+      # configured root — and only a configured root — is covered.
+      def channel_search_glob
+        roots = @channel_search_paths.map { |p| p.chomp("/") }
+        base = roots.length == 1 ? roots.first : "{#{roots.join(',')}}"
+        "#{base}/**/*.rb"
+      end
+
       def load_error_diagnostic(path)
         error = producer_error(:channel_index)
         Rigor::Analysis::Diagnostic.new(

data/plugins/rigor-activesupport-core-ext/sig/active_support/core_ext.rbs

@@ -248,10 +248,10 @@ class Time
   def self.zone: () -> untyped # ActiveSupport::TimeZone | nil
   def self.zone=: (String | Symbol | untyped) -> untyped
 
-  # `core_ext/time/conversions` — also `Time.parse` from stdlib
-  # `time`, which is already in core RBS.
-  def self.httpdate: (String) -> Time
-  def self.iso8601: (String) -> Time
+  # `core_ext/time/conversions` — nothing to declare. `Time.parse`, `Time.httpdate` and
+  # `Time.iso8601` all come from stdlib `time`, which rbs types; ActiveSupport only re-opens them.
+  # Declaring them here raised `RBS::DuplicatedMethodDefinitionError` and collapsed the whole `Time`
+  # definition to `Dynamic[top]`.
 
   # `core_ext/time/calculations`
   def yesterday: () -> Time
@@ -281,7 +281,7 @@ class Time
   def midday: () -> Time
   def midnight: () -> Time
   def noon: () -> Time
-  def utc?: () -> bool
+  # NOTE: `Time#utc?` is NOT declared here — it is Ruby core, already typed by rbs's `core/time.rbs`.
   def acts_like_time?: () -> true
   # `advance(days: 1, months: -2)` and `all_day` (a `beginning_of_day..end_of_day` Range).
   def advance: (untyped options) -> Time
@@ -468,7 +468,7 @@ end
 
 class DateTime
   def utc: () -> Time
-  def to_time: () -> Time
+  # NOTE: `DateTime#to_time` is NOT declared here — stdlib `date` already types it.
   def in_time_zone: (?String | Symbol zone) -> untyped
   def yesterday: () -> DateTime
   def tomorrow: () -> DateTime

data/plugins/rigor-dry-schema/lib/rigor/plugin/dry_schema/result_shape.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class DrySchema < Rigor::Plugin::Base
+      # Translates one `:dry_schema_table` entry into the `Rigor::Type::HashShape` that
+      # `SomeSchema.call(input).to_h` returns, and recognises the call chain that earns it.
+      #
+      # The table entry is the shape {SchemaScanner} publishes:
+      #
+      #     { required: { email: { type: "String", list: false } },
+      #       optional: { nickname: { type: "String", list: true } } }
+      #
+      # ## Why the shape mirrors the declaration's own vocabulary
+      #
+      # `Dry::Schema::Result#to_h` returns the *coerced input*, so on a failed validation a
+      # `required(:email)` key can be absent. Modelling that worst case — every key optional — would be
+      # the sound reading and the wrong one: the idiomatic consumer checks `success?` first, and typing
+      # `result.to_h[:age]` as `Integer?` inside that branch draws a nil diagnostic on correct code.
+      # Rigor weighs a false positive above a worst-case static reading (AGENTS.md § Implementation
+      # Guidelines), and already took the same call for RBS's `%a{implicitly-returns-nil}`.
+      #
+      # So `required` rows become required keys and `optional` rows become optional keys — the schema's
+      # own words. A reader who wrote `optional(:nickname)` is not surprised that the key reads as
+      # possibly-absent, and one who wrote `required(:email)` is not surprised that it does not.
+      #
+      # The shape is **open**: dry-schema's key map only emits declared keys, but a closed shape would
+      # turn any read of an undeclared key into a diagnostic, and being wrong there costs more than the
+      # extra precision buys.
+      module ResultShape
+        # `:bool` rows land in the published fact as "TrueClass" — the fact's vocabulary names one
+        # underlying class per row and has no union slot. A hash value typed `TrueClass` would false-fire
+        # on every `false`, so the shape widens it back to the two-class union here rather than in the
+        # fact, whose consumers (rigor-dry-struct, rigor-dry-validation) read it for a class name.
+        BOOL_CLASSES = %w[TrueClass FalseClass].freeze
+
+        module_function
+
+        # The schema constant `to_h_node`'s receiver chain names, or nil when the chain isn't the
+        # recognised `<Const>.call(...).to_h` form.
+        #
+        # Floor: the schema must be named by a constant *as written* at the call site, because the FQN is
+        # matched against the table's keys verbatim. A schema referenced through a local
+        # (`schema = NewUserSchema; schema.call(x).to_h`) or by a relative constant path from inside the
+        # declaring module resolves to no entry and contributes nothing — the pre-slice behaviour.
+        def schema_name(to_h_node)
+          return nil unless to_h_node.is_a?(Prism::CallNode) && to_h_node.name == :to_h
+          return nil unless to_h_node.arguments.nil? && to_h_node.block.nil?
+
+          inner = to_h_node.receiver
+          return nil unless inner.is_a?(Prism::CallNode) && inner.name == :call
+
+          constant_name(inner.receiver)
+        end
+
+        # The HashShape for one table entry, or nil when the schema declares no key at all. An empty open
+        # shape would be a carrier that says nothing the bare `untyped` did not already say, so declining
+        # keeps the hash's type honest about how little is known.
+        def build(entry)
+          unmodelled = entry[:unmodelled] || {}
+          required = pairs_for(entry[:required]).merge(untyped_pairs(unmodelled[:required]))
+          optional = pairs_for(entry[:optional]).merge(untyped_pairs(unmodelled[:optional]))
+          return nil if required.empty? && optional.empty?
+
+          Rigor::Type::Combinator.hash_shape_of(
+            required.merge(optional),
+            required_keys: required.keys,
+            optional_keys: optional.keys,
+            extra_keys: :open
+          )
+        end
+
+        # A key the schema declares but the scanner could not type still belongs in the shape, as
+        # `untyped`.
+        #
+        # This costs nothing at a read and buys nothing at one either — measured: with and without these
+        # entries, `payload[:address]`, `payload.fetch(:address)` and every other read infer identically,
+        # because #249 made an undeclared key on an OPEN shape read as `untyped` rather than `nil`. What
+        # it buys is the rendered shape, which is what hover and `dump_type` show: `{ email: String,
+        # address: Dynamic[top], ... }` says the schema declares `address` and Rigor cannot type it, while
+        # `{ email: String, ... }` is indistinguishable from a schema that never mentioned it — the
+        # trailing `...` only ever means "keys beyond these are permitted".
+        #
+        # It was originally load-bearing for a different reason: before #249 a key outside the shape read
+        # as `nil`, so dropping `required(:address).schema { … }` put a `call.undefined-method` on the next
+        # line of correct code. That hazard is gone; the entries stay for the honesty of the rendering.
+        def untyped_pairs(keys)
+          (keys || []).to_h { |key| [key, Rigor::Type::Combinator.untyped] }
+        end
+
+        def pairs_for(rows)
+          (rows || {}).each_with_object({}) do |(key, row), pairs|
+            type = row_type(row)
+            pairs[key] = type unless type.nil?
+          end
+        end
+
+        def row_type(row)
+          element = element_type(row[:type])
+          return nil if element.nil?
+
+          row[:list] ? Rigor::Type::Combinator.nominal_of("Array", type_args: [element]) : element
+        end
+
+        # `type` is either a class-name String (the scalar case) or a `{nested: <shape>}` Hash — an
+        # `each do ... end` element-type recursion (issue #137's ceiling slice): {SchemaScanner} already
+        # collected the nested block with the same `collect_schema_shape` algorithm a top-level schema
+        # body uses, so building its HashShape is just a recursive {.build} call.
+        def element_type(type)
+          return build(type[:nested]) if type.is_a?(Hash)
+
+          class_type(type)
+        end
+
+        def class_type(class_name)
+          return nil if class_name.nil? || class_name.empty?
+          return Rigor::Type::Combinator.union(*BOOL_CLASSES.map { |c| Rigor::Type::Combinator.nominal_of(c) }) \
+            if class_name == "TrueClass"
+
+          Rigor::Type::Combinator.nominal_of(class_name)
+        end
+
+        # Renders `Foo` / `Foo::Bar` / `::Foo::Bar` as the `::`-joined String the table is keyed by.
+        # Mirrors the helper rigor-sorbet's TypeTranslator and rigor-activerecord's ModelDiscoverer use.
+        def constant_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then constant_path_name(node)
+          end
+        end
+
+        def constant_path_name(node)
+          parent = node.parent
+          name = node.name&.to_s
+          return nil if name.nil?
+          return name if parent.nil? # `::Foo` — the table keys are unrooted, so drop the leading `::`
+
+          prefix = constant_name(parent)
+          prefix.nil? ? nil : "#{prefix}::#{name}"
+        end
+      end
+    end
+  end
+end