rigortype 0.1.9 → 0.1.11

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/absurd_recognizer.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "type_translator"
+
+module Rigor
+  module Plugin
+    class Sorbet < Rigor::Plugin::Base
+      # Slice 6 of ADR-11 — recognises `T.absurd(x)` calls and
+      # composes them with the engine's flow-sensitive
+      # narrowing. `T.absurd` asserts that a code branch is
+      # statically unreachable; it's the standard Sorbet idiom
+      # for case/when exhaustiveness:
+      #
+      #   case x
+      #   when A then ...
+      #   when B then ...
+      #   else
+      #     T.absurd(x)
+      #   end
+      #
+      # If every case has been handled, `x` at the `else` branch
+      # has been narrowed to `T.noreturn` (Rigor's `Type::Bot`)
+      # and the assertion holds. If the user forgot a case, `x`
+      # narrows to whatever's left and the assertion is wrong —
+      # we surface that mistake as `plugin.sorbet.absurd-reachable`.
+      #
+      # ## Two-phase mechanism
+      #
+      # The recogniser is invoked from `flow_contribution_for`
+      # where the per-node `scope:` carries the proper narrowing
+      # context. It returns:
+      #
+      # - A `FlowContribution` with `return_type: bot` and
+      #   `exceptional: :raises` regardless of reachability
+      #   (faithful to `T.absurd`'s runtime behaviour: it always
+      #   raises). This lets the engine's existing flow analysis
+      #   treat code after `T.absurd` as unreachable, matching
+      #   what users of Sorbet expect.
+      # - When the branch is REACHABLE (the discriminant's type
+      #   isn't `bot`), the recogniser also records the call
+      #   node in a per-plugin set. The plugin's
+      #   `diagnostics_for_file` later walks the AST for
+      #   `T.absurd` calls and emits a
+      #   `plugin.sorbet.absurd-reachable` warning at every
+      #   call_node whose object identity matches the recorded
+      #   set. We rely on the runner only parsing each file
+      #   once per run, so the same Prism node object is seen
+      #   in both `flow_contribution_for` and
+      #   `diagnostics_for_file`.
+      module AbsurdRecognizer
+        # @param call_node [Prism::CallNode]
+        # @return [Boolean] true when `call_node` is `T.absurd(x)`.
+        def self.absurd_call?(call_node)
+          return false unless call_node.is_a?(Prism::CallNode)
+          return false unless call_node.name == :absurd
+          return false unless TypeTranslator.sorbet_t_namespaced?(call_node.receiver)
+
+          # Slice 6 only handles single-argument `T.absurd(x)`;
+          # no-arg / multi-arg shapes are syntax errors at
+          # Sorbet's level too.
+          arguments = call_node.arguments&.arguments
+          arguments&.size == 1
+        end
+
+        # @param call_node [Prism::CallNode]
+        # @param scope [Rigor::Scope, nil]
+        # @return [Boolean] true when the discriminant has been
+        #   narrowed to `bot` (the branch is unreachable, so
+        #   `T.absurd` is correct). The caller suppresses the
+        #   `absurd-reachable` diagnostic in this case.
+        def self.exhaustive?(call_node, scope)
+          return false if scope.nil?
+
+          arg = call_node.arguments.arguments.first
+          arg_type = scope.type_of(arg)
+          arg_type.equal?(Rigor::Type::Bot.instance) || arg_type.is_a?(Rigor::Type::Bot)
+        rescue StandardError
+          # On synthetic / unrecognised nodes the typer may
+          # raise; treat as "can't prove unreachable" so the
+          # diagnostic fires conservatively.
+          false
+        end
+
+        # The contribution every `T.absurd` call gets,
+        # regardless of static reachability — `T.absurd` raises
+        # at runtime, so its return type is `bot` and the call
+        # is exceptional. This lets the engine's flow analysis
+        # treat code after the call as unreachable (no
+        # `flow.unreachable-branch` from us; that's an engine
+        # rule that consults the same effect lattice).
+        def self.contribution(call_node, plugin_id)
+          Rigor::FlowContribution.new(
+            return_type: Rigor::Type::Combinator.bot,
+            exceptional: :raises,
+            provenance: Rigor::FlowContribution::Provenance.new(
+              source_family: "plugin.#{plugin_id}",
+              plugin_id: plugin_id,
+              node: call_node,
+              descriptor: nil
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/assertion_recognizer.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "type_translator"
+
+module Rigor
+  module Plugin
+    class Sorbet < Rigor::Plugin::Base
+      # Lifts Sorbet's type-assertion calls (`T.let`, `T.cast`,
+      # `T.must`, `T.must_because`, `T.unsafe`, `T.reveal_type`)
+      # into `FlowContribution` return-type contributions.
+      # ADR-11 slice 2 covered the original four; the
+      # `must_because` / `reveal_type` light follow-up extends
+      # the same module rather than splitting into a parallel
+      # recogniser.
+      #
+      # | Sorbet form                  | Contribution                            |
+      # | ---------------------------- | --------------------------------------- |
+      # | `T.let(expr, T)`             | return type ← translated `T`            |
+      # | `T.cast(expr, T)`            | return type ← translated `T`            |
+      # | `T.must(expr)`               | return type ← `inferred(expr) - nil`    |
+      # | `T.must_because(expr, "..")` | return type ← `inferred(expr) - nil`    |
+      # | `T.unsafe(x)`                | return type ← `Dynamic[top]`            |
+      # | `T.reveal_type(expr)`        | return type ← `inferred(expr)` (passes through) |
+      # | `T.assert_type!(expr, T)`    | return type ← translated `T` + static subtype check |
+      # | `T.bind(self, T)`            | return type ← `Constant[nil]` + post_return_fact narrowing self to translated `T` |
+      #
+      # The Sorbet runtime's `T.let` / `T.cast` actually return
+      # the inner expression unchanged at runtime; their job is
+      # purely to *assert* a static type. From Rigor's static
+      # perspective the simplest faithful translation is "the
+      # call's return type IS the asserted type" — the call
+      # site's downstream uses see that type. This matches what
+      # `%a{rigor:v1:assert: x is T}` would do for an assignment
+      # in the surrounding scope.
+      #
+      # `T.must_because` is `T.must` with a second-argument
+      # string explanation. The static behaviour is identical to
+      # `T.must` — strip `nil` from the inferred type — so the
+      # recogniser dispatches through the same path.
+      #
+      # `T.reveal_type` is "diagnostic-only" in Sorbet: it
+      # passes the value through unchanged at runtime AND
+      # surfaces the inferred static type as a build-time
+      # message. The recogniser contributes the inferred type
+      # (so chained call sites still resolve as if the
+      # `T.reveal_type` wrapper weren't there); the plugin's
+      # `diagnostics_for_file` hook surfaces the
+      # `plugin.sorbet.reveal-type` `:info` message for human
+      # consumption.
+      #
+      # `T.bind(self, T)` is recognised as block-scope self
+      # narrowing. The recogniser returns a contribution whose
+      # `post_return_facts` carries a `Fact(target_kind: :self)`
+      # so the engine's `apply_self_post_return_fact` narrows
+      # `scope.self_type` for the surrounding scope (in a block
+      # body, the rest of the block). The first argument MUST be
+      # a literal `Prism::SelfNode` — Sorbet rejects other
+      # receivers and the recogniser mirrors that. The runtime
+      # call returns nil, so the static return type is
+      # `Constant[nil]`.
+      module AssertionRecognizer
+        # Method names this recogniser claims as Sorbet
+        # assertions. The plugin checks call sites against this
+        # set before any catalog lookup so a `T.let` call
+        # inside an analysed file always resolves through this
+        # module.
+        SORBET_ASSERTIONS = %i[let cast must must_because unsafe reveal_type assert_type! bind].freeze
+
+        module_function
+
+        # @param call_node [Prism::CallNode]
+        # @param scope [Rigor::Scope]
+        # @param plugin_id [String] used for the contribution's
+        #   `provenance.source_family`.
+        # @return [Rigor::FlowContribution, nil]
+        def recognize(call_node:, scope:, plugin_id:)
+          return nil unless TypeTranslator.sorbet_t_namespaced?(call_node.receiver)
+          return nil unless SORBET_ASSERTIONS.include?(call_node.name)
+
+          return recognize_bind(call_node, plugin_id) if call_node.name == :bind
+
+          return_type = return_type_for(call_node, scope)
+          return nil if return_type.nil?
+
+          contribution(call_node, return_type, plugin_id)
+        end
+
+        def return_type_for(call_node, scope)
+          case call_node.name
+          when :let, :cast then resolve_typed_assertion(call_node)
+          when :must, :must_because then resolve_must(call_node, scope)
+          when :unsafe then Rigor::Type::Combinator.untyped
+          when :reveal_type then resolve_reveal_type(call_node, scope)
+          when :assert_type! then resolve_typed_assertion(call_node)
+          end
+        end
+
+        # `T.bind(self, T)` recognition. Sorbet rejects any
+        # non-`self` receiver argument, and the recogniser
+        # mirrors that — calls like `T.bind(other, X)` fall
+        # through silently. The contribution carries:
+        #
+        # - `return_type: Constant[nil]` — Sorbet's runtime
+        #   `T.bind` returns nil; chained calls would be a
+        #   bug, but the typing stays accurate.
+        # - `post_return_facts: [Fact(target_kind: :self,
+        #   type: T)]` — the engine's
+        #   `apply_self_post_return_fact` narrows
+        #   `scope.self_type` for the surrounding scope. In a
+        #   block body, that scope is the block's own, so the
+        #   narrowing applies to the rest of the block —
+        #   matching Sorbet's documented contract.
+        def recognize_bind(call_node, plugin_id)
+          first_arg = nth_argument(call_node, 0)
+          return nil unless first_arg.is_a?(Prism::SelfNode)
+
+          type_arg = nth_argument(call_node, 1)
+          return nil if type_arg.nil?
+
+          asserted = TypeTranslator.translate(type_arg)
+          return nil if asserted.nil?
+
+          fact = Rigor::FlowContribution::Fact.new(
+            target_kind: :self, target_name: :self, type: asserted
+          )
+          Rigor::FlowContribution.new(
+            return_type: Rigor::Type::Combinator.constant_of(nil),
+            post_return_facts: [fact],
+            provenance: Rigor::FlowContribution::Provenance.new(
+              source_family: "plugin.#{plugin_id}",
+              plugin_id: plugin_id,
+              node: call_node,
+              descriptor: nil
+            )
+          )
+        end
+
+        # `T.assert_type!(expr, T)` shares the typed-assertion
+        # contribution shape with `T.cast` (return is the
+        # asserted type), so the recogniser delegates the
+        # return-type half through `resolve_typed_assertion`.
+        # The static subtype check that distinguishes
+        # `assert_type!` from `cast` lives in the plugin's
+        # `diagnostics_for_file` hook (mirroring the
+        # absurd-recognizer pattern: record the call here, emit
+        # the diagnostic from the per-file walker).
+        def assert_type_check(call_node, scope)
+          return nil if scope.nil?
+
+          inner = nth_argument(call_node, 0)
+          asserted_node = nth_argument(call_node, 1)
+          return nil if inner.nil? || asserted_node.nil?
+
+          asserted_type = TypeTranslator.translate(asserted_node)
+          return nil if asserted_type.nil?
+
+          inferred = scope.type_of(inner)
+          [inferred, asserted_type]
+        rescue StandardError
+          nil
+        end
+
+        # `T.reveal_type(expr)` returns `expr` unchanged at
+        # runtime; the Sorbet-side semantics is "make the
+        # inferred static type visible to the user." The
+        # contribution mirrors `T.must` minus the nil-stripping:
+        # the call's return type is the inner expression's
+        # inferred type. The companion diagnostic is emitted by
+        # the plugin's `diagnostics_for_file` hook through
+        # {RevealTypeRecognizer}; the recogniser here is
+        # contribution-only.
+        def resolve_reveal_type(call_node, scope)
+          inner = nth_argument(call_node, 0)
+          return Rigor::Type::Combinator.untyped if inner.nil? || scope.nil?
+
+          inner_type = scope.type_of(inner)
+          inner_type || Rigor::Type::Combinator.untyped
+        rescue StandardError
+          # Synthetic / virtual nodes can raise from
+          # `scope.type_of`; degrade gracefully so the dispatcher
+          # can still proceed with a benign untyped envelope.
+          Rigor::Type::Combinator.untyped
+        end
+
+        # `T.let(expr, T)` and `T.cast(expr, T)` share the same
+        # 2-argument shape: `arguments[1]` is the type
+        # expression. The first argument is opaque to slice 2 —
+        # we don't try to verify it at runtime; that's `srb tc`'s
+        # job and is out of scope per ADR-11.
+        def resolve_typed_assertion(call_node)
+          type_arg = nth_argument(call_node, 1)
+          return nil if type_arg.nil?
+
+          TypeTranslator.translate(type_arg)
+        end
+
+        # `T.must(expr)` strips `nil` from `expr`'s inferred
+        # type. The call's target type is therefore
+        # `inferred(expr) - Constant[nil]`. Falls back to the
+        # untyped envelope when the inferred shape is itself
+        # `Dynamic[top]` or when no scope is available
+        # (synthetic / virtual-node call sites).
+        def resolve_must(call_node, scope)
+          inner = nth_argument(call_node, 0)
+          return nil if inner.nil? || scope.nil?
+
+          inner_type = scope.type_of(inner)
+          return Rigor::Type::Combinator.untyped if inner_type.nil?
+
+          strip_nil(inner_type)
+        rescue StandardError
+          # `scope.type_of` may raise on synthetic nodes; degrade
+          # to "no contribution" rather than crash the dispatcher.
+          nil
+        end
+
+        # Removes `nil` (`Constant[nil]`) from `type` using the
+        # `Difference` carrier. Idempotent on shapes that don't
+        # contain nil — the resulting `Difference[base, removed]`
+        # collapses to `base` if `base` already excludes the
+        # removed value, but the simple form here is good enough
+        # for slice 2; the precise normalisation lands when the
+        # Difference carrier gets full algebraic support.
+        def strip_nil(type)
+          Rigor::Type::Combinator.difference(
+            type, Rigor::Type::Combinator.constant_of(nil)
+          )
+        end
+
+        def nth_argument(call_node, index)
+          call_node.arguments&.arguments&.[](index)
+        end
+
+        def contribution(call_node, return_type, plugin_id)
+          Rigor::FlowContribution.new(
+            return_type: return_type,
+            provenance: Rigor::FlowContribution::Provenance.new(
+              source_family: "plugin.#{plugin_id}",
+              plugin_id: plugin_id,
+              node: call_node,
+              descriptor: nil
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/catalog.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    class Sorbet < Rigor::Plugin::Base
+      # Per-run table of method signatures keyed by the
+      # `(class_name, method_name, kind)` triple. Built by
+      # {CatalogWalker} during the plugin's lazy pre-walk; read
+      # by {Sorbet#flow_contribution_for} at every call site.
+      #
+      # The catalog is mutable while it is being built, then
+      # frozen via {#freeze!} before the first read. Construction
+      # mutability is intentional — slice 1 builds the catalog
+      # incrementally as the walker visits each project file —
+      # but consumers MUST treat the catalog as read-only.
+      class Catalog
+        # Frozen empty bucket reused for classes that have no
+        # recorded mixins. Avoids allocating a fresh Hash on
+        # every `mixins_for` query.
+        EMPTY_MIXINS = { include: [].freeze, extend: [].freeze }.freeze
+
+        def initialize
+          @entries = {}
+          # ADR-11 slice 8 — per-class mixin declarations
+          # collected by `CatalogWalker`. Lookup-time chain
+          # traversal lifts sigs declared on a mixed-in
+          # module to call sites on the host class.
+          @mixins = {}
+          @frozen_after_build = false
+        end
+
+        # @param signature [MethodSignature]
+        def record(signature)
+          raise "Catalog already finalised" if @frozen_after_build
+
+          key = key_for(signature.class_name, signature.method_name, signature.kind)
+          @entries[key] = signature
+        end
+
+        # @param class_name [String] the class / module that
+        #   carries the mixin (`class Post; include Foo; end`
+        #   records under `"Post"`).
+        # @param kind [:include, :extend]
+        # @param module_name [String] the textual name of the
+        #   mixed-in module as it appeared at the include /
+        #   extend site (`"Foo"`, `"Foo::Bar"`, `"::Foo"`).
+        def record_mixin(class_name:, kind:, module_name:)
+          raise "Catalog already finalised" if @frozen_after_build
+
+          bucket = (@mixins[class_name] ||= { include: [], extend: [] })
+          list = bucket[kind]
+          list << module_name unless list.include?(module_name)
+        end
+
+        def freeze!
+          @frozen_after_build = true
+          @entries.freeze
+          @mixins.each_value do |bucket|
+            bucket.each_value(&:freeze)
+            bucket.freeze
+          end
+          @mixins.freeze
+          freeze
+        end
+
+        # @return [MethodSignature, nil]
+        def lookup(class_name:, method_name:, kind:)
+          @entries[key_for(class_name, method_name, kind)]
+        end
+
+        # @param class_name [String]
+        # @return [Hash{Symbol => Array<String>}] frozen mapping
+        #   `{ include: [...], extend: [...] }`. Returns
+        #   {EMPTY_MIXINS} when no mixins were recorded.
+        def mixins_for(class_name)
+          @mixins[class_name] || EMPTY_MIXINS
+        end
+
+        def empty?
+          @entries.empty?
+        end
+
+        def size
+          @entries.size
+        end
+
+        private
+
+        def key_for(class_name, method_name, kind)
+          [class_name.to_s, method_name.to_sym, kind]
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/catalog_walker.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "method_signature"
+require_relative "sig_parser"
+
+module Rigor
+  module Plugin
+    class Sorbet < Rigor::Plugin::Base
+      # Walks a parsed Prism program looking for
+      # `sig { ... }` / `sig do ... end` calls that immediately
+      # precede a `def` (or a `def self.foo` / `class << self;
+      # def foo; end`). Each recognised pair is parsed by
+      # {SigParser} and recorded in the {Catalog} under its
+      # qualified `(class_name, method_name, kind)` key.
+      #
+      # Anything we don't recognise (a stray `sig { ... }` not
+      # followed by a `def`, a `def` with no preceding `sig`,
+      # malformed sig blocks, etc.) is reported back to the
+      # caller through `parse_errors:` so the plugin can emit a
+      # `plugin.sorbet.parse-error` diagnostic. Walking is
+      # otherwise infallible — a bad sig block does not abort
+      # the catalog build for the rest of the file.
+      module CatalogWalker
+        # Detected error during walking. `kind` is one of:
+        # `:no_block` / `:empty_block` / `:missing_returns_or_void`
+        # / `:duplicate_sig` / `:dangling_sig`.
+        ParseError = Data.define(:kind, :node, :path)
+
+        module_function
+
+        # @param root [Prism::Node] the file's program node.
+        # @param catalog [Catalog] mutable; signatures are
+        #   recorded into it.
+        # @param path [String] file path used for diagnostic
+        #   provenance.
+        # @return [Array<ParseError>] errors observed during the
+        #   walk; empty when the file is sig-clean.
+        def walk(root:, catalog:, path:)
+          state = State.new(catalog: catalog, path: path)
+          walk_node(root, state, lexical_path: [], in_singleton_class: false)
+          state.errors
+        end
+
+        State = Struct.new(:catalog, :path, :errors, keyword_init: true) do
+          def initialize(catalog:, path:)
+            super(catalog: catalog, path: path, errors: [])
+          end
+
+          def record_error(kind, node)
+            errors << ParseError.new(kind: kind, node: node, path: path)
+          end
+        end
+
+        def walk_node(node, state, lexical_path:, in_singleton_class:)
+          return unless node.is_a?(Prism::Node)
+
+          case node
+          when Prism::ClassNode, Prism::ModuleNode
+            descend_class_or_module(node, state, lexical_path)
+          when Prism::SingletonClassNode
+            descend_singleton_class(node, state, lexical_path)
+          when Prism::StatementsNode
+            walk_statements(node, state, lexical_path: lexical_path, in_singleton_class: in_singleton_class)
+          when Prism::DefNode
+            # A `def` not preceded by a `sig` is fine; we just
+            # don't record anything for it. The interesting case
+            # is in `walk_statements`, which pairs sig+def.
+          else
+            node.compact_child_nodes.each do |child|
+              walk_node(child, state, lexical_path: lexical_path, in_singleton_class: in_singleton_class)
+            end
+          end
+        end
+
+        def descend_class_or_module(node, state, lexical_path)
+          name = qualified_name_for(node.constant_path)
+          if name && node.body
+            child_prefix = lexical_path + [name]
+            walk_node(node.body, state, lexical_path: child_prefix, in_singleton_class: false)
+          elsif node.body
+            walk_node(node.body, state, lexical_path: lexical_path, in_singleton_class: false)
+          end
+        end
+
+        def descend_singleton_class(node, state, lexical_path)
+          if node.expression.is_a?(Prism::SelfNode) && node.body
+            walk_node(node.body, state, lexical_path: lexical_path, in_singleton_class: true)
+          elsif node.body
+            walk_node(node.body, state, lexical_path: lexical_path, in_singleton_class: false)
+          end
+        end
+
+        # The pair-finding loop. Walks a `StatementsNode`'s
+        # children left-to-right; when it encounters a `sig`
+        # call, it remembers it and consumes the very next
+        # `def` / `def self.foo` as the target. Anything between
+        # a sig and its def (a comment is fine — comments aren't
+        # AST nodes — but a method call would be a problem)
+        # leaves the sig dangling.
+        def walk_statements(statements, state, lexical_path:, in_singleton_class:)
+          pending_sig = nil
+
+          statements.body.each do |child|
+            if pending_sig && def_node?(child)
+              record_def_with_sig(child, pending_sig, state, lexical_path, in_singleton_class)
+              pending_sig = nil
+            elsif sig_call?(child)
+              state.record_error(:duplicate_sig, pending_sig) if pending_sig
+              pending_sig = child
+            else
+              if pending_sig
+                state.record_error(:dangling_sig, pending_sig)
+                pending_sig = nil
+              end
+              # ADR-11 slice 8 — record `include` / `extend`
+              # declarations alongside the regular walk so the
+              # plugin's chain lookup can lift sigs declared
+              # on a mixed-in module to the host class.
+              record_mixin_call(child, state, lexical_path) if mixin_call?(child) && !in_singleton_class
+              walk_node(child, state, lexical_path: lexical_path, in_singleton_class: in_singleton_class)
+            end
+          end
+
+          state.record_error(:dangling_sig, pending_sig) if pending_sig
+        end
+
+        # `include Foo` / `extend Foo` / `include Foo, Bar` —
+        # the `include` and `extend` mixin macros that Tapioca-
+        # generated DSL RBIs depend on. Recognised when the
+        # call has no explicit receiver (top-level inside a
+        # class body) and every argument is a constant
+        # reference.
+        def mixin_call?(node)
+          return false unless node.is_a?(Prism::CallNode)
+          return false unless %i[include extend].include?(node.name)
+          return false unless node.receiver.nil?
+
+          args = node.arguments&.arguments
+          return false if args.nil? || args.empty?
+
+          args.all? do |arg|
+            arg.is_a?(Prism::ConstantReadNode) || arg.is_a?(Prism::ConstantPathNode)
+          end
+        end
+
+        def record_mixin_call(node, state, lexical_path)
+          return if lexical_path.empty?
+
+          class_name = lexical_path.join("::")
+          kind = node.name == :include ? :include : :extend
+          (node.arguments&.arguments || []).each do |arg|
+            module_name = qualified_name_for(arg)
+            next if module_name.nil?
+
+            state.catalog.record_mixin(
+              class_name: class_name, kind: kind, module_name: module_name
+            )
+          end
+        end
+
+        def sig_call?(node)
+          node.is_a?(Prism::CallNode) &&
+            node.name == :sig &&
+            node.receiver.nil? &&
+            !node.block.nil?
+        end
+
+        def def_node?(node)
+          node.is_a?(Prism::DefNode)
+        end
+
+        def record_def_with_sig(def_node, sig_call, state, lexical_path, in_singleton_class)
+          parsed = SigParser.parse(sig_call)
+          if parsed.is_a?(SigParser::ParseError)
+            state.record_error(parsed.reason, sig_call)
+            return
+          end
+
+          class_name = lexical_path.empty? ? "Object" : lexical_path.join("::")
+          kind = singleton_method?(def_node, in_singleton_class) ? :singleton : :instance
+          catalog_record(state.catalog, class_name, def_node.name, kind, parsed)
+        end
+
+        def catalog_record(catalog, class_name, method_name, kind, parsed)
+          catalog.record(
+            MethodSignature.new(
+              class_name: class_name,
+              method_name: method_name,
+              kind: kind,
+              params: parsed.params,
+              return_type: parsed.return_type,
+              modifiers: parsed.modifiers
+            )
+          )
+        end
+
+        def singleton_method?(def_node, in_singleton_class)
+          in_singleton_class || def_node.receiver.is_a?(Prism::SelfNode)
+        end
+
+        # Resolves a constant-path node (`Foo::Bar`,
+        # `::Foo::Bar`) to its dot-separated name. Returns nil
+        # for the rare dynamic-prefix shape so the walker
+        # doesn't guess a qualified name in that case.
+        def qualified_name_for(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parts = []
+            current = node
+            while current.is_a?(Prism::ConstantPathNode)
+              parts.unshift(current.name.to_s)
+              current = current.parent
+            end
+            case current
+            when nil then "::#{parts.join('::')}"
+            when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+            end
+          end
+        end
+      end
+    end
+  end
+end