rigortype 0.1.5 → 0.1.7

data/lib/rigor/inference/method_dispatcher.rb

@@ -4,6 +4,8 @@ require_relative "../reflection"
 require_relative "../type"
 require_relative "../flow_contribution"
 require_relative "../flow_contribution/merger"
+require_relative "../builtins/hkt_builtins"
+require_relative "../builtins/static_return_refinements"
 require_relative "method_dispatcher/constant_folding"
 require_relative "method_dispatcher/literal_string_folding"
 require_relative "method_dispatcher/shape_dispatch"
@@ -62,7 +64,7 @@ module Rigor
       # @param environment [Rigor::Environment, nil] required for
       #   RBS-backed dispatch; when nil only constant folding can fire.
       # @return [Rigor::Type, nil] inferred result type, or `nil` for "no rule".
-      def dispatch(receiver_type:, method_name:, arg_types:,
+      def dispatch(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/MethodLength
                    block_type: nil, environment: nil,
                    call_node: nil, scope: nil)
         return nil if receiver_type.nil?
@@ -88,6 +90,32 @@ module Rigor
         plugin_result = try_plugin_contribution(call_node, scope)
         return plugin_result if plugin_result
 
+        # ADR-20 slice 3 — Rigor-bundled HKT-builtin return-
+        # type tier. Sits ABOVE `RbsDispatch.try_dispatch` so
+        # the handful of stdlib methods whose upstream RBS
+        # signature is `untyped` but whose runtime shape Rigor
+        # models via a Lightweight HKT (`json::value`,
+        # eventually `dry_monads::result`, …) get the reduced
+        # type instead of `Dynamic[Top]`. The table that
+        # populates this tier lives in
+        # `Rigor::Builtins::HktBuiltins::METHOD_RETURN_OVERRIDES`;
+        # plugin-supplied per-method overrides are out of
+        # scope for slice 3 and continue to flow through the
+        # `try_plugin_contribution` tier above.
+        hkt_builtin_result = try_hkt_builtin_return(receiver_type, method_name, arg_types, environment)
+        return hkt_builtin_result if hkt_builtin_result
+
+        # Rigor-bundled static refinement tier. Sits between HKT
+        # and RBS so stdlib methods whose upstream RBS is broader
+        # than the documented behaviour (e.g. `Kernel#__dir__`
+        # declared `() -> String?` when the documented return is
+        # `non-empty-string | nil`) get the tightened type
+        # without modifying the vendored `ruby/rbs` submodule.
+        # The override table lives in
+        # `Rigor::Builtins::StaticReturnRefinements::OVERRIDES`.
+        static_refinement = try_static_refinement(receiver_type, method_name, arg_types)
+        return static_refinement if static_refinement
+
         rbs_result = RbsDispatch.try_dispatch(
           receiver: receiver_type, method_name: method_name, args: arg_types,
           environment: environment, block_type: block_type
@@ -111,6 +139,20 @@ module Rigor
         )
         return synthetic_result if synthetic_result
 
+        # ADR-17 slice 2 — project-side patched-method tier.
+        # Sits BELOW the substrate / plugin tiers and ABOVE
+        # dependency-source inference per ADR-17 § "Inference
+        # contract". When the user's `pre_eval:` list named a
+        # file that re-opens a class (e.g.,
+        # `lib/core_ext/string_extensions.rb` declaring
+        # `class String; def to_url; end; end`), the pre-pass
+        # populated `ProjectPatchedMethods` with the `(class,
+        # method, kind)` triple; this tier surfaces it as
+        # `Dynamic[top]` so the patched call resolves
+        # cross-file without `call.undefined-method`.
+        patched_result = try_project_patched_method(receiver_type, method_name, environment)
+        return patched_result if patched_result
+
         # ADR-10 slice 2b-ii — dependency-source inference tier.
         # Sits BELOW RBS dispatch (RBS / RBS::Inline / generated
         # stubs / plugin contracts always win) and ABOVE the
@@ -217,6 +259,80 @@ module Rigor
       # keeps moving — the run-level diagnostic envelope (per
       # ADR-2 § "Plugin Trust and I/O Policy") is owned by
       # `Analysis::Runner#plugin_emitted_diagnostics`.
+      # ADR-20 slice 3 — looks up the receiver / method pair
+      # in {Rigor::Builtins::HktBuiltins::METHOD_RETURN_OVERRIDES}
+      # and returns the reduced HKT type. Only fires when the
+      # receiver is a {Rigor::Type::Singleton} (the
+      # `JSON.parse` shape) and the registry-backed reduction
+      # succeeds; returns `nil` otherwise so the dispatcher
+      # falls through to RBS.
+      def try_hkt_builtin_return(receiver_type, method_name, arg_types, environment)
+        return nil if environment.nil?
+        return nil unless receiver_type.is_a?(Type::Singleton)
+
+        Rigor::Builtins::HktBuiltins.method_return_override(
+          class_name: receiver_type.class_name,
+          method_name: method_name,
+          kind: :singleton,
+          arg_types: arg_types,
+          hkt_registry: environment.hkt_registry
+        )
+      end
+
+      # Consults the Rigor-bundled static refinement table for a
+      # (owner-class, method-name, kind) entry. Kernel methods
+      # are mixed into every non-BasicObject class, so an
+      # implicit-self `__dir__` call (receiver_type =
+      # Nominal[ClassName]) is matched by looking up Kernel as
+      # the owner. Explicit `Kernel.__dir__` (receiver_type =
+      # Singleton[Kernel]) and instance-side calls
+      # (receiver_type = Nominal[Klass]) share the `:both` row.
+      #
+      # The receiver-side ancestor check is intentionally cheap:
+      # any non-BasicObject Nominal / Singleton matches every
+      # Kernel-owned override. BasicObject explicitly excludes
+      # Kernel and is therefore rejected. The narrow risk of a
+      # user-defined `def __dir__` shadowing Kernel's method
+      # would also alter the runtime answer; users with that
+      # configuration opt out via a `signature_paths` overlay
+      # declaring their own return type.
+      def try_static_refinement(receiver_type, method_name, arg_types)
+        candidates = Rigor::Builtins::StaticReturnRefinements.owners_for(method_name)
+        return nil if candidates.empty?
+
+        owner = static_refinement_owner_for(receiver_type, candidates)
+        return nil unless owner
+
+        kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
+        Rigor::Builtins::StaticReturnRefinements.lookup(
+          owner_class_name: owner,
+          method_name: method_name,
+          kind: kind,
+          arg_types: arg_types
+        )
+      end
+
+      # Picks the most specific override owner the receiver
+      # honours. For Kernel-owned overrides the receiver simply
+      # needs to be a real-class Nominal / Singleton (i.e. not
+      # BasicObject and not a Dynamic / Constant / shape carrier
+      # — those carriers go through their own narrower tiers).
+      def static_refinement_owner_for(receiver_type, candidates)
+        receiver_class = static_refinement_class_for(receiver_type)
+        return nil unless receiver_class
+
+        return "Kernel" if candidates.include?("Kernel") && receiver_class != "BasicObject"
+
+        candidates.find { |owner| owner == receiver_class }
+      end
+
+      def static_refinement_class_for(receiver_type)
+        case receiver_type
+        when Type::Singleton, Type::Nominal
+          receiver_type.class_name
+        end
+      end
+
       def try_plugin_contribution(call_node, scope)
         return nil if call_node.nil? || scope.nil?
 
@@ -334,6 +450,30 @@ module Rigor
         end
       end
 
+      # ADR-17 slice 2 — project-side patched-method tier.
+      # Slice 3a uses the registry's heuristic-extracted
+      # `return_type` (populated via the same
+      # `Analysis::DependencySourceInference::ReturnTypeHeuristic`
+      # the ADR-10 walker uses): a `def to_url; "hello"; end`
+      # patched onto `String` now resolves `s.to_url` to
+      # `Dynamic[Nominal[String]]` instead of the pre-3a
+      # `Dynamic[Top]`. Falls back to `Dynamic[Top]` when the
+      # heuristic declined (non-literal tail expression).
+      def try_project_patched_method(receiver_type, method_name, environment)
+        registry = environment&.project_patched_methods
+        return nil if registry.nil? || registry.empty?
+
+        class_name = synthetic_method_class_name(receiver_type)
+        return nil if class_name.nil?
+
+        kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
+        entry = registry.lookup(class_name: class_name, method_name: method_name, kind: kind)
+        return nil if entry.nil?
+        return Type::Combinator.untyped if entry.return_type.nil?
+
+        Type::Combinator.dynamic(entry.return_type)
+      end
+
       def try_dependency_source(receiver_type, method_name, environment)
         index = environment&.dependency_source_index
         return nil if index.nil? || index.empty?
@@ -350,8 +490,8 @@ module Rigor
         # inference must not contribute behind their backs.
         return nil if plugin_owns_receiver?(class_name, environment)
 
-        contribution_kind = index.contribution_for(class_name: class_name, method_name: method_name)
-        return Type::Combinator.untyped if contribution_kind
+        contribution = index.contribution_for(class_name: class_name, method_name: method_name)
+        return dependency_source_return_type(contribution) if contribution
 
         # ADR-10 5b — β budget semantics. On a catalog miss,
         # if the receiver class belongs to a budget-exceeded
@@ -403,6 +543,17 @@ module Rigor
         )
       end
 
+      # Maps a {DependencySourceInference::Walker::CatalogEntry}
+      # to the Type the dispatcher returns at the call site.
+      # When the heuristic recovered a static facet, wrap it in
+      # `Dynamic[T]` per ADR-10's gem-boundary contract;
+      # otherwise fall back to the pre-heuristic `Dynamic[top]`.
+      def dependency_source_return_type(contribution)
+        return Type::Combinator.untyped if contribution.return_type.nil?
+
+        Type::Combinator.dynamic(contribution.return_type)
+      end
+
       # Composite preflight for {#record_boundary_cross_if_applicable}.
       # Returns the receiver class name only when every prerequisite
       # for emitting the diagnostic is satisfied (environment carries
@@ -506,21 +657,38 @@ module Rigor
         fallback_receiver = user_class_fallback_receiver(receiver_type, environment)
         return nil if fallback_receiver.nil?
 
+        # Preserve the ORIGINAL receiver type as the `self`
+        # substitution so `Kernel#dup: () -> self` and other
+        # `self`-returning methods route through Object's RBS
+        # while still returning the caller's type rather than
+        # `Object`. Without this, `base = self.dup` inside a
+        # `Bundler::URI::Generic` instance method types `base`
+        # as `Object` because `Bundler::URI::Generic` is not in
+        # RBS and the fallback's `self` resolves to Object.
         RbsDispatch.try_dispatch(
           receiver: fallback_receiver,
           method_name: method_name,
           args: arg_types,
           environment: environment,
-          block_type: block_type
+          block_type: block_type,
+          self_type_override: receiver_type
         )
       end
 
       def user_class_fallback_receiver(receiver_type, environment)
         case receiver_type
         when Type::Nominal
-          return nil if Rigor::Reflection.rbs_class_known?(receiver_type.class_name, environment: environment)
+          # Modules: even when RBS knows the module, an instance
+          # method on a mixin-only module (e.g. `PP::ObjectMixin`)
+          # observes Kernel / Object methods through every concrete
+          # includer's ancestor chain. Route through the
+          # `Nominal[Object]` fallback so `self.inspect` /
+          # `self.respond_to?` / `self.class` resolve cleanly when
+          # the module itself does not declare them.
+          known = Rigor::Reflection.rbs_class_known?(receiver_type.class_name, environment: environment)
+          return environment.nominal_for_name("Object") if !known || environment.rbs_module?(receiver_type.class_name)
 
-          environment.nominal_for_name("Object")
+          nil
         when Type::Singleton
           return nil if Rigor::Reflection.rbs_class_known?(receiver_type.class_name, environment: environment)
 

data/lib/rigor/inference/narrowing.rb

@@ -950,7 +950,7 @@ module Rigor
         end
 
         def simple_dispatch_name?(name)
-          %i[nil? ! is_a? kind_of? instance_of? == != ===].include?(name)
+          %i[nil? ! is_a? kind_of? instance_of? == != === =~].include?(name)
         end
 
         def dispatch_call_simple(node, scope, name)
@@ -960,9 +960,111 @@ module Rigor
           when :instance_of? then analyse_class_predicate(node, scope, exact: true)
           when :==, :!= then analyse_equality_predicate(node, scope, equality: name)
           when :=== then analyse_case_equality_predicate(node, scope)
+          when :=~ then analyse_regex_match_predicate(node, scope)
           end
         end
 
+        # Survey item (b): `/regex/ =~ str` and `str =~ /regex/`
+        # bind the regex match-data globals on each edge.
+        #
+        # - Truthy edge (`=~` returned an Integer position — the
+        #   match succeeded): `$~` to `Nominal[MatchData]`; `$&`
+        #   and `$1..$N` (where N is the number of capture groups
+        #   in the regex source) to `Nominal[String]`. This is the
+        #   same optimistic-narrowing shape the existing
+        #   `analyse_match_write` uses for named captures inside
+        #   `if /(?<x>...)/ =~ str` — optional groups in the
+        #   regex source (`(\d+)?`) would bind `$N` to `nil` at
+        #   runtime, but the floor here matches the common idiom
+        #   (required captures) and lets `unless /(\d+)/ =~ s;
+        #   raise; end; $1.to_i` resolve cleanly.
+        # - Falsey edge (`=~` returned nil — no match): `$~` and
+        #   every numbered / back-reference global bound to
+        #   `Constant<nil>`.
+        #
+        # Returns nil (no narrowing) when the receiver / argument
+        # pair does not include a `RegularExpressionNode` literal
+        # we can count.
+        def analyse_regex_match_predicate(node, scope)
+          return nil if node.arguments.nil?
+          return nil unless node.arguments.arguments.size == 1
+
+          regex_node = regex_match_literal(node.receiver, node.arguments.arguments.first)
+          return nil if regex_node.nil?
+
+          group_count = count_regex_capture_groups(regex_node.unescaped)
+          regex_match_predicate_scopes(scope, group_count)
+        end
+
+        def regex_match_literal(left, right)
+          return left if left.is_a?(Prism::RegularExpressionNode)
+          return right if right.is_a?(Prism::RegularExpressionNode)
+
+          nil
+        end
+
+        # Curated set of back-reference globals bound by every
+        # `=~`. Numbered references (`$1..$N`) are handled
+        # separately because N depends on the regex source.
+        REGEX_MATCH_GLOBALS = %i[$~ $& $` $' $+].freeze
+        private_constant :REGEX_MATCH_GLOBALS
+
+        def regex_match_predicate_scopes(scope, group_count)
+          string_t = Type::Combinator.nominal_of("String")
+          match_data_t = Type::Combinator.nominal_of("MatchData")
+          nil_t = Type::Combinator.constant_of(nil)
+
+          truthy = scope
+          falsey = scope
+          truthy = truthy.with_global(:$~, match_data_t)
+          falsey = falsey.with_global(:$~, nil_t)
+          REGEX_MATCH_GLOBALS.each do |name|
+            next if name == :$~
+
+            truthy = truthy.with_global(name, string_t)
+            falsey = falsey.with_global(name, nil_t)
+          end
+          group_count.times do |i|
+            name = :"$#{i + 1}"
+            truthy = truthy.with_global(name, string_t)
+            falsey = falsey.with_global(name, nil_t)
+          end
+          [truthy, falsey]
+        end
+
+        # Counts capture groups (numbered + named — both
+        # contribute to `$1..$N`) in a regex source. Backslash
+        # escapes are skipped; non-capturing `(?:...)`, lookahead
+        # `(?=...)` / `(?!...)`, and lookbehind `(?<=...)` /
+        # `(?<!...)` do NOT count. Named groups `(?<name>...)`
+        # DO count. The walker is intentionally light — it does
+        # not parse the regex AST, just scans char-by-char — so
+        # exotic constructs that overlap the lookaround syntax
+        # may miscount; the unsoundness is bounded (over- or
+        # under-binding a few `$N` globals) and we already accept
+        # the same shape of unsoundness for `analyse_match_write`.
+        def count_regex_capture_groups(source)
+          i = 0
+          total = 0
+          length = source.length
+          while i < length
+            c = source[i]
+            if c == "\\"
+              i += 2
+              next
+            end
+            if c == "("
+              if source[i + 1] == "?"
+                total += 1 if source[i + 2] == "<" && source[i + 3] != "=" && source[i + 3] != "!"
+              else
+                total += 1
+              end
+            end
+            i += 1
+          end
+          total
+        end
+
         def dispatch_call_numeric(node, scope, name)
           if COMPARISON_OPERATORS.include?(name)
             analyse_comparison_predicate(node, scope, comparator: name)

data/lib/rigor/inference/project_patched_methods.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-17 § "Inference contract" — project-wide patched-method
+    # registry populated by the pre-eval pre-pass (slice 2) from
+    # the user's `.rigor.yml` `pre_eval:` list.
+    #
+    # Each entry records one `def` declaration the pre-pass
+    # observed inside a class / module body. The dispatcher's
+    # `try_project_patched_method` tier consults this registry
+    # between the plugin tier and the dependency-source tier so
+    # project-side `lib/core_ext/string_extensions.rb` patches
+    # are visible to cross-file dispatch.
+    #
+    # Slice 2 ships the registry at the **floor**: the dispatcher
+    # answers `Type::Combinator.untyped` (Dynamic[Top]) on a hit;
+    # return-type inference for patched methods stays deferred
+    # (a separate slice when concrete demand surfaces — most
+    # real-world `core_ext` patches return shapes the analyzer
+    # could heuristically extract via the same machinery the
+    # ADR-10 walker uses, but slice 2 keeps the surface narrow).
+    class ProjectPatchedMethods
+      # Frozen value-object recording one `def` observed by the
+      # pre-pass. `class_name` is the qualified prefix
+      # (`"String"`, `"Foo::Bar"`); `method_name` is the
+      # declared name; `kind` is `:instance` or `:singleton`;
+      # `source_path` / `source_line` carry attribution for
+      # diagnostics; `return_type` is the
+      # {Analysis::DependencySourceInference::ReturnTypeHeuristic}-
+      # extracted static facet (a `Rigor::Type::*`) or `nil`
+      # when the heuristic declined. The dispatcher wraps a
+      # non-nil `return_type` in `Dynamic[T]`; a `nil`
+      # `return_type` falls back to `Dynamic[top]`.
+      Entry = Data.define(:class_name, :method_name, :kind, :source_path, :source_line, :return_type) do
+        def initialize(class_name:, method_name:, kind:, source_path:, source_line:, return_type: nil)
+          super
+        end
+      end
+
+      attr_reader :by_key
+
+      # @param entries [Array<Entry>] flat list of declarations
+      #   observed during the pre-pass. First-write-wins on
+      #   `(class_name, method_name, kind)` duplicates so the
+      #   `pre-eval.duplicate-declaration` diagnostic emission
+      #   stays decoupled from registry behaviour.
+      def initialize(entries: [])
+        @by_key = entries.each_with_object({}) do |entry, acc|
+          key = [entry.class_name, entry.method_name, entry.kind]
+          acc[key] ||= entry
+        end.freeze
+        freeze
+      end
+
+      # @return [Entry, nil] the recorded entry for the given
+      #   `(class_name, method_name, kind)` triple, or `nil`
+      #   when no pre-eval file declared it.
+      def lookup(class_name:, method_name:, kind:)
+        @by_key[[class_name, method_name, kind]]
+      end
+
+      def empty?
+        @by_key.empty?
+      end
+
+      EMPTY = new.freeze
+    end
+  end
+end

data/lib/rigor/inference/project_patched_scanner.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "project_patched_methods"
+require_relative "../analysis/dependency_source_inference/return_type_heuristic"
+
+module Rigor
+  module Inference
+    # ADR-17 slice 2 — pre-pass scanner. Walks every file the user
+    # listed under `pre_eval:` and harvests every `def` /
+    # `def self.` declaration inside a class / module body into a
+    # {ProjectPatchedMethods} registry the dispatcher consults
+    # below the plugin tier.
+    #
+    # The walker is intentionally a strict subset of
+    # {Rigor::Inference::ScopeIndexer}'s machinery: it only needs
+    # `class C; def m; end; end` shape recognition, not full
+    # inference. Parse errors degrade to a fail-soft `:warning`
+    # `pre-eval.parse-error` diagnostic accumulated alongside
+    # the registry; per ADR-17 § "Failure modes" a parse failure
+    # in a pre-eval file MUST NOT abort the rest of the run.
+    module ProjectPatchedScanner
+      # Frozen scan outcome carrying the populated registry and
+      # the per-file warnings the runner emits at run start.
+      class Result < Data.define(:registry, :diagnostics)
+        def initialize(registry:, diagnostics: [])
+          super(
+            registry: registry,
+            diagnostics: diagnostics.freeze
+          )
+        end
+      end
+
+      module_function
+
+      # @param paths [Array<String>] absolute paths to the
+      #   pre-eval files. The runner has already validated that
+      #   each path exists (slice-1 `pre-eval.file-not-found`
+      #   `:error` covers missing entries); the scanner does NOT
+      #   re-check existence.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      #   editor-mode buffer binding. When set, the scanner reads
+      #   the buffer's physical bytes if a pre-eval entry matches
+      #   the logical path, so users editing a monkey-patch file
+      #   see the in-flight version in their analysis.
+      # @return [Result] the populated registry plus any
+      #   per-file warnings.
+      def scan(paths, buffer: nil)
+        entries = []
+        diagnostics = []
+        paths.each { |path| scan_file(path, entries, diagnostics, buffer) }
+        diagnostics.concat(duplicate_declaration_diagnostics(entries))
+        Result.new(
+          registry: ProjectPatchedMethods.new(entries: entries),
+          diagnostics: diagnostics
+        )
+      end
+
+      # ADR-17 § "Failure modes" — when two pre-eval entries
+      # declare the same `(class_name, method_name, kind)` triple,
+      # emit one `:info` `pre-eval.duplicate-declaration`
+      # diagnostic per collision. The registry's first-write-wins
+      # behaviour is unchanged; the diagnostic just makes the
+      # shadowing visible so users notice when a later patch
+      # is silently masked.
+      def duplicate_declaration_diagnostics(entries)
+        seen = {}
+        entries.each_with_object([]) do |entry, acc|
+          key = [entry.class_name, entry.method_name, entry.kind]
+          if (first = seen[key])
+            acc << build_diagnostic(
+              path: entry.source_path,
+              line: entry.source_line,
+              column: 1,
+              severity: :info,
+              rule: "pre-eval.duplicate-declaration",
+              message: "pre-eval duplicate declaration: " \
+                       "#{entry.class_name}##{entry.method_name} " \
+                       "(#{entry.kind}) is already declared at " \
+                       "#{first.source_path}:#{first.source_line}. " \
+                       "The first declaration wins; this entry is shadowed."
+            )
+          else
+            seen[key] = entry
+          end
+        end
+      end
+      private_class_method :duplicate_declaration_diagnostics
+
+      def scan_file(path, entries, diagnostics, buffer = nil)
+        physical = buffer ? buffer.resolve(path) : path
+        parse_result =
+          if physical == path
+            Prism.parse_file(path)
+          else
+            Prism.parse(File.read(physical), filepath: path)
+          end
+        unless parse_result.errors.empty?
+          diagnostics << parse_error_diagnostic(path, parse_result.errors)
+          return
+        end
+
+        walk_node(parse_result.value, [], false, path, entries)
+      rescue StandardError => e
+        diagnostics << build_diagnostic(
+          path: path, line: 1, column: 1,
+          severity: :warning,
+          rule: "pre-eval.parse-error",
+          message: "rigor: failed to read pre_eval entry #{path.inspect}: " \
+                   "#{e.class}: #{e.message}. Pre-evaluation skipped for this file; " \
+                   "the rest of the run proceeds."
+        )
+      end
+      private_class_method :scan_file
+
+      def parse_error_diagnostic(path, errors)
+        first = errors.first
+        line = first.respond_to?(:location) ? first.location&.start_line || 1 : 1
+        build_diagnostic(
+          path: path, line: line, column: 1,
+          severity: :warning,
+          rule: "pre-eval.parse-error",
+          message: "rigor: pre_eval entry #{path.inspect} has a parse error " \
+                   "(#{first&.message}). Pre-evaluation skipped for this file; " \
+                   "the rest of the run proceeds."
+        )
+      end
+      private_class_method :parse_error_diagnostic
+
+      # Builds a diagnostic Hash-shape the runner translates to a
+      # `Rigor::Analysis::Diagnostic`. The scanner intentionally
+      # does NOT depend on the analysis layer (it's a pre-pass);
+      # the runner adapts at the call site.
+      def build_diagnostic(path:, line:, column:, severity:, rule:, message:)
+        { path: path, line: line, column: column, severity: severity, rule: rule, message: message }
+      end
+      private_class_method :build_diagnostic
+
+      def walk_node(node, qualified_prefix, in_singleton_class, source_path, entries)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          descend_class_or_module(node, qualified_prefix, in_singleton_class, source_path, entries)
+        when Prism::SingletonClassNode
+          descend_singleton_class(node, qualified_prefix, source_path, entries)
+        when Prism::DefNode
+          record_def_node(node, qualified_prefix, in_singleton_class, source_path, entries)
+        else
+          walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
+        end
+      end
+      private_class_method :walk_node
+
+      def walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
+        node.compact_child_nodes.each do |child|
+          walk_node(child, qualified_prefix, in_singleton_class, source_path, entries)
+        end
+      end
+      private_class_method :walk_children
+
+      def descend_class_or_module(node, qualified_prefix, in_singleton_class, source_path, entries)
+        name = qualified_name_for(node.constant_path)
+        if name && node.body
+          walk_node(node.body, qualified_prefix + [name], in_singleton_class, source_path, entries)
+        else
+          walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
+        end
+      end
+      private_class_method :descend_class_or_module
+
+      def descend_singleton_class(node, qualified_prefix, source_path, entries)
+        if node.expression.is_a?(Prism::SelfNode) && node.body
+          walk_node(node.body, qualified_prefix, true, source_path, entries)
+        else
+          walk_children(node, qualified_prefix, false, source_path, entries)
+        end
+      end
+      private_class_method :descend_singleton_class
+
+      def record_def_node(node, qualified_prefix, in_singleton_class, source_path, entries)
+        return if qualified_prefix.empty?
+
+        class_name = qualified_prefix.join("::")
+        kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
+        line = node.location&.start_line || 1
+        return_type = Analysis::DependencySourceInference::ReturnTypeHeuristic.extract(node)
+        entries << ProjectPatchedMethods::Entry.new(
+          class_name: class_name, method_name: node.name, kind: kind,
+          source_path: source_path, source_line: line,
+          return_type: return_type
+        )
+      end
+      private_class_method :record_def_node
+
+      def qualified_name_for(node)
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode
+          parent = node.parent.nil? ? nil : qualified_name_for(node.parent)
+          return nil if !node.parent.nil? && parent.nil?
+
+          parent.nil? ? node.name.to_s : "#{parent}::#{node.name}"
+        end
+      end
+      private_class_method :qualified_name_for
+    end
+  end
+end