Module: Rigor::Inference::MethodDispatcher

Defined in:
lib/rigor/inference/method_dispatcher.rb,
lib/rigor/inference/method_dispatcher/file_folding.rb,
lib/rigor/inference/method_dispatcher/rbs_dispatch.rb,
lib/rigor/inference/method_dispatcher/block_folding.rb,
lib/rigor/inference/method_dispatcher/shape_dispatch.rb,
lib/rigor/inference/method_dispatcher/kernel_dispatch.rb,
lib/rigor/inference/method_dispatcher/constant_folding.rb,
lib/rigor/inference/method_dispatcher/iterator_dispatch.rb,
lib/rigor/inference/method_dispatcher/overload_selector.rb,
lib/rigor/inference/method_dispatcher/literal_string_folding.rb

Overview

Coordinates method dispatch for the inference engine.

Given ‘(receiver_type, method_name, arg_types, block_type, environment)`, the dispatcher returns the inferred result type or `nil` when no rule matches. `nil` is a deliberately blunt “I don’t know” signal: callers (today only ‘ExpressionTyper`) own the fail-soft fallback and decide whether to record a `FallbackTracer` event.

Tiers (in order):

  1. ConstantFolding: executes the Ruby operation directly when the receiver and argument are ‘Constant` carriers and the method is on the curated whitelist. Slice 2.

  2. ShapeDispatch: returns the precise element/value type for a curated catalogue of ‘Tuple`/`HashShape` element-access methods (`first`, `last`, `[]` with a static integer/key, `fetch`, `dig`, `size`/`length`/`count`). Slice 5 phase 2.

  3. RbsDispatch: looks up the receiver’s class in the RBS environment carried by the scope and translates the method’s return type into a Rigor::Type. Slice 4.

‘ShapeDispatch` deliberately runs above RbsDispatch so the precise per-position/per-key answer wins over the projected `Array#[]`/`Hash#fetch` answer; it falls through (`nil`) when the call cannot be proved against the static shape, in which case the projection answer from RbsDispatch applies.

The dispatcher’s public signature reserves space for ‘block_type:` and ADR-2 plugin extensions (later slices), so call sites added now do not have to be rewritten when those tiers arrive.

Defined Under Namespace

Modules: BlockFolding, ConstantFolding, FileFolding, IteratorDispatch, KernelDispatch, LiteralStringFolding, OverloadSelector, RbsDispatch, ShapeDispatch

Class Method Summary collapse

Class Method Details

.array_new_fill(type) ⇒ Object 



372
373
374
375
376
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 372

def array_new_fill(type)
  return Type::Combinator.constant_of(nil) if type.nil?

  type
end

.array_new_lift(class_name, arg_types) ⇒ Object 



355
356
357
358
359
360
361
362
363
364
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 355

def array_new_lift(class_name, arg_types)
  return nil unless class_name == "Array"
  return nil if arg_types.empty? || arg_types.size > 2

  size = array_new_size(arg_types.first)
  return nil if size.nil? || size.negative? || size > ARRAY_NEW_TUPLE_LIMIT

  fill = array_new_fill(arg_types[1])
  Type::Combinator.tuple_of(*Array.new(size, fill))
end

.array_new_size(type) ⇒ Object 



366
367
368
369
370
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 366

def array_new_size(type)
  return nil unless type.is_a?(Type::Constant) && type.value.is_a?(Integer)

  type.value
end

.budget_silence_result(class_name, index, _environment) ⇒ Object 



180
181
182
183
184
185
186
187
188
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 180

def budget_silence_result(class_name, index, _environment)
  return nil unless index.budget_overrun_strategy == :dependency_silence

  owning_gem = index.gem_for(class_name)
  return nil if owning_gem.nil?
  return nil unless index.budget_exceeded.include?(owning_gem)

  Type::Combinator.untyped
end

.collect_plugin_contributions(registry, call_node, scope) ⇒ Object 



215
216
217
218
219
220
221
222
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 215

def collect_plugin_contributions(registry, call_node, scope)
  registry.plugins.filter_map do |plugin|
    contribution = plugin.flow_contribution_for(call_node: call_node, scope: scope)
    contribution.is_a?(FlowContribution) ? contribution : nil
  rescue StandardError
    nil
  end
end

.constant_constructor_lift(class_name, arg_types) ⇒ Object 



333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 333

def constant_constructor_lift(class_name, arg_types)
  builder = CONSTANT_CONSTRUCTORS[class_name]
  return nil if builder.nil?
  return nil unless arg_types.size == 1

  arg = arg_types.first
  return nil unless arg.is_a?(Type::Constant) && arg.value.is_a?(String)

  result = builder.call(arg.value)
  Type::Combinator.constant_of(result)
rescue StandardError
  nil
end

.constant_metaclass(value) ⇒ Object 



386
387
388
389
390
391
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 386

def constant_metaclass(value)
  CONSTANT_METACLASSES.each do |klass, name|
    return Type::Combinator.singleton_of(name) if value.is_a?(klass)
  end
  nil
end

.dep_source_class_name(receiver_type) ⇒ Object 



209
210
211
212
213
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 209

def dep_source_class_name(receiver_type)
  case receiver_type
  when Type::Nominal, Type::Singleton then receiver_type.class_name
  end
end

.dispatch(receiver_type:, method_name:, arg_types:, block_type: nil, environment: nil, call_node: nil, scope: nil) ⇒ Rigor::Type?

Returns inferred result type, or ‘nil` for “no rule”.

Parameters:

  • receiver_type (Rigor::Type, nil) —

    type of the receiver expression, or ‘nil` for an implicit-self call.

  • method_name (Symbol)
  • arg_types (Array<Rigor::Type>) —

    positional argument types.

  • block_type (Rigor::Type, nil) (defaults to: nil) —

    inferred return type of the accompanying ‘do … end` / `{ … }` block (Slice 6 phase C sub-phase 2). When non-nil, the dispatcher prefers an overload that declares a block, and binds the method’s block-return type variable to ‘block_type` so a return type like `Array` resolves to `Array`.

  • environment (Rigor::Environment, nil) (defaults to: nil) —

    required for RBS-backed dispatch; when nil only constant folding can fire.

Returns:

  • (Rigor::Type, nil) —

    inferred result type, or ‘nil` for “no rule”.



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 64

def dispatch(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/ParameterLists
             block_type: nil, environment: nil,
             call_node: nil, scope: nil)
  return nil if receiver_type.nil?

  precise = dispatch_precise_tiers(receiver_type, method_name, arg_types, block_type)
  return precise if precise

  # v0.1.1 Track 2 slice 7 — plugin return-type contribution
  # tier. Sits ahead of `RbsDispatch` so a plugin that
  # understands a domain-specific dispatch (e.g. an
  # `ActiveRecord::Base.find` returning `Nominal[<resolved
  # model>]`) wins over the RBS-projected envelope. Only
  # consults the registry when both `call_node` and `scope`
  # are supplied — the dispatcher's own internal callers
  # (per-element block fold, etc.) skip this tier.
  plugin_result = try_plugin_contribution(call_node, scope)
  return plugin_result if plugin_result

  rbs_result = RbsDispatch.try_dispatch(
    receiver: receiver_type, method_name: method_name, args: arg_types,
    environment: environment, block_type: block_type
  )
  return rbs_result if rbs_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
  # user-class fallback so a method defined in an opt-in
  # gem stops emitting `call.undefined-method` even when
  # no signature contract resolves. Returns
  # `Dynamic[top]` — slice 2b-ii deliberately stops at the
  # dynamic-origin envelope; per-method return-type
  # precision is queued for a later slice.
  dep_source_result = try_dependency_source(receiver_type, method_name, environment)
  return dep_source_result if dep_source_result

  # Slice 7 phase 10 — user-class ancestor fallback. When
  # the receiver is `Nominal[T]` or `Singleton[T]` for a
  # class not in the RBS environment (typically a
  # user-defined class), retry the dispatch against the
  # implicit ancestor: `Nominal[Object]` for instance
  # receivers and `Singleton[Object]` for singleton
  # receivers. This resolves Kernel intrinsics
  # (`require`, `raise`, `puts`, ...) and Module/Class
  # introspection (`attr_reader`, `private`, ...) on
  # user classes without requiring the user to author
  # their own RBS.
  try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
end

.dispatch_precise_tiers(receiver_type, method_name, arg_types, block_type = nil) ⇒ Object

Runs the precision tiers (constant fold, shape dispatch, file-path fold, block fold) in order and returns the first non-nil answer. Each tier owns its own receiver/argument shape checks; a tier that does not recognise the receiver returns nil so the next tier can try. The RBS tier sits below this chain and is invoked by the outer ‘dispatch` method.

‘BlockFolding` runs last among the precision tiers because its rules apply only to block-taking calls, so the cheaper arity-based fold tiers above it filter out the common cases first. When `block_type` is nil the tier is a no-op.



236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 236

def dispatch_precise_tiers(receiver_type, method_name, arg_types, block_type = nil)
  meta_result = try_meta_introspection(receiver_type, method_name, arg_types)
  return meta_result if meta_result

  ConstantFolding.try_fold(receiver: receiver_type, method_name: method_name, args: arg_types) ||
    LiteralStringFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
    ShapeDispatch.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
    FileFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
    KernelDispatch.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
    BlockFolding.try_fold(
      receiver: receiver_type, method_name: method_name, args: arg_types, block_type: block_type
    )
end

.expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil) ⇒ Array<Rigor::Type>

Returns the positional block parameter types declared by the receiving method’s selected RBS overload, translated into ‘Rigor::Type`. Used by the StatementEvaluator’s CallNode handler to bind block parameter names before evaluating the block body.

The probe is best-effort: it returns an empty array whenever the receiver, environment, method definition, or selected overload does not provide statically declared block parameter types. Callers MUST treat the empty array as “no information”; the binder falls back to ‘Dynamic` for every parameter slot in that case.

Parameters:

Returns:



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 411

def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil)
  return [] if receiver_type.nil?

  iterator_result = IteratorDispatch.block_param_types(
    receiver: receiver_type,
    method_name: method_name,
    args: arg_types
  )
  return iterator_result if iterator_result

  RbsDispatch.block_param_types(
    receiver: receiver_type,
    method_name: method_name,
    args: arg_types,
    environment: environment
  )
end

.meta_class(receiver_type) ⇒ Object 



297
298
299
300
301
302
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 297

def meta_class(receiver_type)
  case receiver_type
  when Type::Nominal then Type::Combinator.singleton_of(receiver_type.class_name)
  when Type::Constant then constant_metaclass(receiver_type.value)
  end
end

.meta_new(receiver_type, arg_types = []) ⇒ Object

‘Singleton.new` returns `Nominal` (a fresh instance), regardless of whether Foo is in RBS. This short-circuits the Class.new generic-`instance` plumbing for user classes, so a discovered-class `ScanAccumulator.new` types as `Nominal` rather than `Class`.

v0.0.7 — for the curated set of immutable scalar-shaped classes that ‘Type::Constant::SCALAR_CLASSES` accepts (today: `Pathname`), `.new(Constant<…>)` lifts to a `Constant<…>` carrier so downstream method calls fold through the standard catalog tier.



316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 316

def meta_new(receiver_type, arg_types = [])
  return nil unless receiver_type.is_a?(Type::Singleton)

  constant_lift = constant_constructor_lift(receiver_type.class_name, arg_types)
  return constant_lift if constant_lift

  array_lift = array_new_lift(receiver_type.class_name, arg_types)
  return array_lift if array_lift

  Type::Combinator.nominal_of(receiver_type.class_name)
end

.plugin_owns_receiver?(class_name, environment) ⇒ Boolean

Returns:

  • (Boolean) 


190
191
192
193
194
195
196
197
198
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 190

def plugin_owns_receiver?(class_name, environment)
  registry = environment&.plugin_registry
  return false if registry.nil? || registry.empty?

  registry.plugins.any? do |plugin|
    owns = plugin.manifest.owns_receivers # rigor:disable undefined-method
    owns.any? { |owner| receiver_matches_owner?(class_name, owner, environment) }
  end
end

.receiver_matches_owner?(class_name, owner, environment) ⇒ Boolean

Returns:

  • (Boolean) 


200
201
202
203
204
205
206
207
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 200

def receiver_matches_owner?(class_name, owner, environment)
  return true if class_name == owner

  ordering = environment.class_ordering(class_name, owner)
  %i[equal subclass].include?(ordering)
rescue StandardError
  false
end

.try_dependency_source(receiver_type, method_name, environment) ⇒ Object

ADR-10 slice 2b-ii. Consults the per-run ‘Analysis::DependencySourceInference::Index` carried by the environment for `(class_name, method_name)` observations harvested from opt-in gems’ ‘roots:`. On a hit, returns `Combinator.untyped` so the call site carries the `Dynamic` provenance (per ADR-10’s “Inference contract”: gem-source-inferred shapes never publish as ground-truth ‘T`). Returns `nil` when the environment carries no index, the index has no entry, or the receiver has no nominal class to look up.



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 150

def try_dependency_source(receiver_type, method_name, environment)
  index = environment&.dependency_source_index
  return nil if index.nil? || index.empty?

  class_name = dep_source_class_name(receiver_type)
  return nil if class_name.nil?

  # ADR-10 5a — per-receiver plugin veto. When a
  # registered plugin declares `manifest(owns_receivers:
  # [<class>])` AND the call's receiver IS that class
  # (or a subclass), decline and let plugins handle the
  # call. Plugins that own a receiver are the
  # authoritative source for that type; gem-source
  # 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

  # ADR-10 5b — β budget semantics. On a catalog miss,
  # if the receiver class belongs to a budget-exceeded
  # gem AND the user opted into `:dependency_silence`,
  # return `Dynamic[top]` rather than falling through to
  # the user-class fallback. The user-class fallback
  # would otherwise emit `call.undefined-method` for
  # methods Rigor's catalog couldn't reach because the
  # walker hit its cap.
  budget_silence_result(class_name, index, environment)
end

.try_meta_introspection(receiver_type, method_name, arg_types = []) ⇒ Object

Slice 7 phase 8 — meta-introspection shortcuts. The default ‘Object#class` RBS return type is `Class`, but for a receiver of known nominal identity we can do better: `instance_of(Foo).class` is `Singleton` (the class object itself), which downstream dispatch uses to resolve `self.class.some_class_method`. The same logic answers `Foo.class` as `Singleton` (deliberate; calling `.class` on a class object yields `Class`, the metaclass). We also special-case `is_a?`- adjacent calls and the trivial `instance_of?(self)` later as the rule catalogue grows; for now only `class` is handled.



290
291
292
293
294
295
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 290

def try_meta_introspection(receiver_type, method_name, arg_types = [])
  case method_name
  when :class then meta_class(receiver_type)
  when :new then meta_new(receiver_type, arg_types)
  end
end

.try_plugin_contribution(call_node, scope) ⇒ Object

ADR-2 § “Flow Contribution Bundle” / v0.1.1 Track 2 slice 7. Walks every loaded plugin’s ‘#flow_contribution_for(call_node:, scope:)` hook, collects the non-nil `FlowContribution` bundles, merges them through `FlowContribution::Merger`, and returns the merged `return_type` slot (or nil when no plugin contributed a return type).

Plugins whose hook raises have their contribution silently dropped for this call so the dispatch chain keeps moving — the run-level diagnostic envelope (per ADR-2 § “Plugin Trust and I/O Policy”) is owned by ‘Analysis::Runner#plugin_emitted_diagnostics`.



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 128

def try_plugin_contribution(call_node, scope)
  return nil if call_node.nil? || scope.nil?

  registry = scope.environment&.plugin_registry
  return nil if registry.nil? || registry.empty?

  contributions = collect_plugin_contributions(registry, call_node, scope)
  return nil if contributions.empty?

  FlowContribution::Merger.merge(contributions).return_type
end

.try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type) ⇒ Object 



250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 250

def try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
  return nil if environment.nil?

  fallback_receiver = user_class_fallback_receiver(receiver_type, environment)
  return nil if fallback_receiver.nil?

  RbsDispatch.try_dispatch(
    receiver: fallback_receiver,
    method_name: method_name,
    args: arg_types,
    environment: environment,
    block_type: block_type
  )
end

.user_class_fallback_receiver(receiver_type, environment) ⇒ Object 



265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/rigor/inference/method_dispatcher.rb', line 265

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)

    environment.nominal_for_name("Object")
  when Type::Singleton
    return nil if Rigor::Reflection.rbs_class_known?(receiver_type.class_name, environment: environment)

    environment.singleton_for_name("Class")
  end
end