rigortype 0.1.5 → 0.1.6

data/lib/rigor/inference/method_dispatcher/receiver_affinity.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Stable-sort an overload list so that "receiver-affinity"
+      # arms come first. An overload is receiver-affinity-matching
+      # when every positional param's class equals `self_type`'s
+      # class name OR is one of its proper RBS ancestors. The
+      # canonical case the helper exists for: when `bigdecimal`'s
+      # stdlib RBS reopens `Integer#+` at the FRONT of the
+      # overload list with `(BigDecimal) -> BigDecimal`, that
+      # disjoint-sibling arm would win every dispatch for
+      # `Integer#+(?)` by overload-list position alone, returning
+      # a spurious `BigDecimal` for plain integer arithmetic.
+      # Demoting the arm honours the coerce convention: when the
+      # arg type is unknown or itself an Integer, the
+      # receiver-preserving `(Integer) -> Integer` arm should win.
+      #
+      # No-op when (a) the environment can't answer
+      # `class_ordering` (nil env), or (b) the receiver isn't a
+      # nominal / singleton carrying a class name. The partition
+      # is stable, so within each bucket the RBS-declared order
+      # is preserved.
+      module ReceiverAffinity
+        module_function
+
+        def reorder(overloads, self_type:, environment:)
+          return overloads if environment.nil?
+
+          self_class_name = self_type_class_name(self_type)
+          return overloads if self_class_name.nil?
+
+          affinity, other = overloads.partition do |mt|
+            overload_param_classes_in_ancestry?(mt, self_class_name, environment)
+          end
+          affinity + other
+        end
+
+        class << self
+          private
+
+          def self_type_class_name(self_type)
+            case self_type
+            when Type::Nominal, Type::Singleton then self_type.class_name
+            end
+          end
+
+          def overload_param_classes_in_ancestry?(method_type, self_class_name, environment)
+            fun = method_type.type
+            params = fun.required_positionals + fun.optional_positionals + fun.trailing_positionals
+            return false if params.empty?
+
+            params.all? { |param| param_class_in_ancestry?(param.type, self_class_name, environment) }
+          end
+
+          # Walks Optional and Union one level so `(Numeric?)` and
+          # `(Integer | Float)` still classify when every branch
+          # sits in the ancestry. Non-`ClassInstance` shapes
+          # (Alias / Interface / Intersection / type variables)
+          # don't carry a clean class identity and therefore
+          # disqualify the overload from the affinity bucket.
+          def param_class_in_ancestry?(rbs_type, self_class_name, environment)
+            case rbs_type
+            when RBS::Types::ClassInstance
+              class_in_ancestry?(rbs_type.name.to_s.delete_prefix("::"), self_class_name, environment)
+            when RBS::Types::Optional
+              param_class_in_ancestry?(rbs_type.type, self_class_name, environment)
+            when RBS::Types::Union
+              rbs_type.types.all? { |t| param_class_in_ancestry?(t, self_class_name, environment) }
+            else
+              false
+            end
+          end
+
+          def class_in_ancestry?(param_class_name, self_class_name, environment)
+            return true if param_class_name == self_class_name
+
+            environment.class_ordering(self_class_name, param_class_name) == :subclass
+          end
+        end
+      end
+    end
+  end
+end

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

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