Class: Rigor::Scope

Inherits:
Object
  • Object
show all
Defined in:
lib/rigor/scope.rb,
lib/rigor/scope/discovery_index.rb,
sig/rigor/scope.rbs

Overview

Immutable analyzer scope: holds local-variable bindings and a reference to the surrounding Environment. State changes return new scopes through explicit transition methods (#with_local). The central query is #type_of(node), the Rigor counterpart of PHPStan's $scope->getType($node).

See docs/internal-spec/inference-engine.md for the binding contract. rubocop:disable Metrics/ClassLength,Metrics/ParameterLists

Defined Under Namespace

Classes: ChainKey, DiscoveryIndex, IndexedKey

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(environment:, locals:, fact_store: Analysis::FactStore.empty, self_type: nil, ivars: EMPTY_VAR_BINDINGS, cvars: EMPTY_VAR_BINDINGS, globals: EMPTY_VAR_BINDINGS, discovery: DiscoveryIndex::EMPTY, indexed_narrowings: EMPTY_INDEXED_NARROWINGS, method_chain_narrowings: EMPTY_CHAIN_NARROWINGS, declaration_sourced: EMPTY_DECLARATION_SOURCED, source_path: nil, struct_fold_safe_locals: EMPTY_FOLD_SAFE, dynamic_origins: {}.compare_by_identity, local_origins: EMPTY_ORIGINS, ivar_origins: EMPTY_ORIGINS) ⇒ Scope

Returns a new instance of Scope.

Parameters:

  • environment: (Environment)
  • locals: (Hash[Symbol, Type::t])
  • fact_store: (Analysis::FactStore) (defaults to: Analysis::FactStore.empty)
  • self_type: (Type::t, nil) (defaults to: nil)
  • ivars: (Hash[Symbol, Type::t]) (defaults to: EMPTY_VAR_BINDINGS)
  • cvars: (Hash[Symbol, Type::t]) (defaults to: EMPTY_VAR_BINDINGS)
  • globals: (Hash[Symbol, Type::t]) (defaults to: EMPTY_VAR_BINDINGS)
  • discovery: (DiscoveryIndex) (defaults to: DiscoveryIndex::EMPTY)
  • source_path: (String, nil) (defaults to: nil)
  • dynamic_origins: (Hash[untyped, Symbol]) (defaults to: {}.compare_by_identity) 


120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/rigor/scope.rb', line 120

def initialize(
  environment:, locals:,
  fact_store: Analysis::FactStore.empty,
  self_type: nil,
  ivars: EMPTY_VAR_BINDINGS,
  cvars: EMPTY_VAR_BINDINGS,
  globals: EMPTY_VAR_BINDINGS,
  discovery: DiscoveryIndex::EMPTY,
  indexed_narrowings: EMPTY_INDEXED_NARROWINGS,
  method_chain_narrowings: EMPTY_CHAIN_NARROWINGS,
  declaration_sourced: EMPTY_DECLARATION_SOURCED,
  source_path: nil,
  struct_fold_safe_locals: EMPTY_FOLD_SAFE,
  dynamic_origins: {}.compare_by_identity,
  local_origins: EMPTY_ORIGINS,
  ivar_origins: EMPTY_ORIGINS
)
  @environment = environment
  @locals = locals
  @fact_store = fact_store
  @self_type = self_type
  @ivars = ivars
  @cvars = cvars
  @globals = globals
  @discovery = discovery
  @indexed_narrowings = indexed_narrowings
  @method_chain_narrowings = method_chain_narrowings
  @declaration_sourced = declaration_sourced
  @source_path = source_path
  @struct_fold_safe_locals = struct_fold_safe_locals
  @dynamic_origins = dynamic_origins
  @local_origins = local_origins
  @ivar_origins = ivar_origins
  freeze
end

Instance Attribute Details

#cvars ⇒ Hash[Symbol, Type::t] (readonly)

Returns the value of attribute cvars.

Returns:

  • (Hash[Symbol, Type::t]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def cvars
  @cvars
end

#declaration_sourced ⇒ Set[[Symbol, Symbol]] (readonly)

Returns the value of attribute declaration_sourced.

Returns:

  • (Set[[Symbol, Symbol]]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def declaration_sourced
  @declaration_sourced
end

#discovery ⇒ DiscoveryIndex (readonly)

Returns the value of attribute discovery.

Returns:



20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def discovery
  @discovery
end

#dynamic_origins ⇒ Hash[untyped, Symbol] (readonly)

Returns the value of attribute dynamic_origins.

Returns:

  • (Hash[untyped, Symbol]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def dynamic_origins
  @dynamic_origins
end

#environment ⇒ Environment (readonly)

Returns the value of attribute environment.

Returns:



20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def environment
  @environment
end

#fact_store ⇒ Analysis::FactStore (readonly)

Returns the value of attribute fact_store.

Returns:



20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def fact_store
  @fact_store
end

#globals ⇒ Hash[Symbol, Type::t] (readonly)

Returns the value of attribute globals.

Returns:

  • (Hash[Symbol, Type::t]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def globals
  @globals
end

#indexed_narrowings ⇒ Hash[IndexedKey, Type::t] (readonly)

Returns the value of attribute indexed_narrowings.

Returns:



20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def indexed_narrowings
  @indexed_narrowings
end

#ivar_origins ⇒ Hash[Symbol, Symbol] (readonly)

Returns the value of attribute ivar_origins.

Returns:

  • (Hash[Symbol, Symbol]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def ivar_origins
  @ivar_origins
end

#ivars ⇒ Hash[Symbol, Type::t] (readonly)

Returns the value of attribute ivars.

Returns:

  • (Hash[Symbol, Type::t]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def ivars
  @ivars
end

#local_origins ⇒ Hash[Symbol, Symbol] (readonly)

Returns the value of attribute local_origins.

Returns:

  • (Hash[Symbol, Symbol]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def local_origins
  @local_origins
end

#locals ⇒ Hash[Symbol, Type::t] (readonly)

Returns the value of attribute locals.

Returns:

  • (Hash[Symbol, Type::t]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def locals
  @locals
end

#method_chain_narrowings ⇒ Hash[ChainKey, Type::t] (readonly)

Returns the value of attribute method_chain_narrowings.

Returns:



20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def method_chain_narrowings
  @method_chain_narrowings
end

#self_type ⇒ Type::t? (readonly)

Returns the value of attribute self_type.

Returns:

  • (Type::t, nil) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def self_type
  @self_type
end

#source_path ⇒ String? (readonly)

Returns the value of attribute source_path.

Returns:

  • (String, nil) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def source_path
  @source_path
end

#struct_fold_safe_locals ⇒ Set[Symbol] (readonly)

Returns the value of attribute struct_fold_safe_locals.

Returns:

  • (Set[Symbol]) 


20
21
22
 
# File 'lib/rigor/scope.rb', line 20

def struct_fold_safe_locals
  @struct_fold_safe_locals
end

Class Method Details

.empty(environment: Environment.default, source_path: nil) ⇒ Scope

Parameters:

  • environment: (Environment) (defaults to: Environment.default)
  • source_path: (String, nil) (defaults to: nil)

Returns:



109
110
111
112
 
# File 'lib/rigor/scope.rb', line 109

def empty(environment: Environment.default, source_path: nil)
  new(environment: environment, locals: {}.freeze,
      fact_store: Analysis::FactStore.empty, source_path: source_path)
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


622
623
624
625
626
627
628
629
630
631
632
633
634
 
# File 'lib/rigor/scope.rb', line 622

def ==(other)
  other.is_a?(Scope) &&
    environment.equal?(other.environment) &&
    @locals == other.locals &&
    fact_store == other.fact_store &&
    self_type == other.self_type &&
    @ivars == other.ivars &&
    @cvars == other.cvars &&
    @globals == other.globals &&
    @indexed_narrowings == other.indexed_narrowings &&
    @method_chain_narrowings == other.method_chain_narrowings &&
    @declaration_sourced == other.declaration_sourced
end

#class_cvars ⇒ Hash[String, Hash[Symbol, Type::t]]

Returns:

  • (Hash[String, Hash[Symbol, Type::t]]) 


36
 
# File 'lib/rigor/scope.rb', line 36

def class_cvars = @discovery.class_cvars

#class_cvars_for(class_name) ⇒ Hash[Symbol, Type::t]

Slice 7 phase 6 — class-level cvar accumulator (same shape as class_ivars but populated from Prism::ClassVariableWriteNode writes, and seeded on BOTH instance and singleton method bodies because Ruby cvars are visible from each).

Parameters:

  • class_name (String, Symbol, nil)

Returns:

  • (Hash[Symbol, Type::t]) 


335
336
337
338
339
 
# File 'lib/rigor/scope.rb', line 335

def class_cvars_for(class_name)
  return EMPTY_VAR_BINDINGS if class_name.nil?

  @discovery.class_cvars[class_name.to_s] || EMPTY_VAR_BINDINGS
end

#class_ivars ⇒ Hash[String, Hash[Symbol, Type::t]]

Returns:

  • (Hash[String, Hash[Symbol, Type::t]]) 


35
 
# File 'lib/rigor/scope.rb', line 35

def class_ivars = @discovery.class_ivars

#class_ivars_for(class_name) ⇒ Hash[Symbol, Type::t]

Slice 7 phase 2 — class-level ivar accumulator. Keyed by the qualified class name (e.g. "Rigor::Scope"); the value is a Hash[Symbol, Type::t] of every ivar that appears as a write target inside any def body of that class. StatementEvaluator#build_method_entry_scope seeds the method body's ivars map from this table so a def get; @x; end reads the type written in a sibling def init; @x = 1; end.

ScopeIndexer populates the table once at index time through a separate pre-pass over the program. The map is frozen and shared by structural reference across every derived scope.

Parameters:

  • class_name (String, Symbol, nil)

Returns:

  • (Hash[Symbol, Type::t]) 


326
327
328
329
330
 
# File 'lib/rigor/scope.rb', line 326

def class_ivars_for(class_name)
  return EMPTY_VAR_BINDINGS if class_name.nil?

  @discovery.class_ivars[class_name.to_s] || EMPTY_VAR_BINDINGS
end

#cvar(name) ⇒ Type::t?

Parameters:

  • name (String, Symbol)

Returns:

  • (Type::t, nil) 


248
249
250
 
# File 'lib/rigor/scope.rb', line 248

def cvar(name)
  @cvars[name.to_sym]
end

#data_member_layout(class_name) ⇒ Array[Symbol]?

ADR-48 — per-class table mapping a fully qualified class name to its ordered Data.define / Struct.new member-name list. Populated by ScopeIndexer for both the constant-assigned form (Point = Data.define(:x, :y)) and the named-subclass form (class Point < Data.define(:x, :y)). Consumed by Inference::MethodDispatcher::DataFolding so Point.new(...) on a Singleton[Point] receiver materialises a precise member instance. Returns nil when the class has no recorded layout.

Parameters:

  • class_name (String, Symbol)

Returns:

  • (Array[Symbol], nil) 


464
465
466
467
468
469
470
 
# File 'lib/rigor/scope.rb', line 464

def data_member_layout(class_name)
  layout = @discovery.data_member_layouts[class_name.to_s]
  # Record the ancestry dependency only on a hit — DataFolding consults this for every `Singleton[*].new`,
  # and a miss (the common case: an ordinary class) must not manufacture a spurious cross-file edge.
  record_class_dependency(class_name) if layout && Analysis::DependencyRecorder.active?
  layout
end

#data_member_layouts ⇒ Hash[String, Array[Symbol]]

Returns:

  • (Hash[String, Array[Symbol]]) 


48
 
# File 'lib/rigor/scope.rb', line 48

def data_member_layouts = @discovery.data_member_layouts

#declaration_sourced?(kind, name) ⇒ Boolean

ADR-58 WD1 — true when (kind, name)'s binding optionality is purely declaration-sourced (no flow-live write/narrowing has touched it).

Parameters:

  • kind (Symbol)
  • name (String, Symbol)

Returns:

  • (Boolean) 


293
294
295
 
# File 'lib/rigor/scope.rb', line 293

def declaration_sourced?(kind, name)
  @declaration_sourced.include?([kind.to_sym, name.to_sym])
end

#declared_types ⇒ Hash[untyped, Type::t]

ADR-53 Track A — the seed-time discovery tables live on the DiscoveryIndex; Scope keeps per-table readers as delegates.

Returns:

  • (Hash[untyped, Type::t]) 


34
 
# File 'lib/rigor/scope.rb', line 34

def declared_types = @discovery.declared_types

#discovered_class_sources ⇒ Hash[String, Set[String]]

Returns:

  • (Hash[String, Set[String]]) 


47
 
# File 'lib/rigor/scope.rb', line 47

def discovered_class_sources = @discovery.discovered_class_sources

#discovered_classes ⇒ Hash[String, Type::Singleton]

Returns:



38
 
# File 'lib/rigor/scope.rb', line 38

def discovered_classes = @discovery.discovered_classes

#discovered_def_nodes ⇒ Hash[String, Hash[Symbol, untyped]]

Returns:

  • (Hash[String, Hash[Symbol, untyped]]) 


41
 
# File 'lib/rigor/scope.rb', line 41

def discovered_def_nodes = @discovery.discovered_def_nodes

#discovered_def_sources ⇒ Hash[String, Hash[Symbol, String]]

Returns:

  • (Hash[String, Hash[Symbol, String]]) 


43
 
# File 'lib/rigor/scope.rb', line 43

def discovered_def_sources = @discovery.discovered_def_sources

#discovered_includes ⇒ Hash[String, Array[String]]

Returns:

  • (Hash[String, Array[String]]) 


46
 
# File 'lib/rigor/scope.rb', line 46

def discovered_includes = @discovery.discovered_includes

#discovered_method?(class_name, method_name, kind) ⇒ Boolean

Slice 7 phase 12 — in-source method discovery. Maps a qualified class name to a Hash[Symbol, Symbol] of method_name => :instance | :singleton. Populated by ScopeIndexer from every Prism::DefNode and recognised define_method invocation inside class/module bodies. The rigor check undefined-method and wrong-arity rules consult this map to suppress diagnostics for methods the user has defined dynamically, even when no RBS sig describes them.

Parameters:

  • class_name (String, Symbol)
  • method_name (String, Symbol)
  • kind (Symbol)

Returns:

  • (Boolean) 


346
347
348
349
350
351
 
# File 'lib/rigor/scope.rb', line 346

def discovered_method?(class_name, method_name, kind)
  table = @discovery.discovered_methods[class_name.to_s]
  return false unless table

  table[method_name.to_sym] == kind
end

#discovered_method_visibilities ⇒ Hash[String, Hash[Symbol, Symbol]]

Returns:

  • (Hash[String, Hash[Symbol, Symbol]]) 


44
 
# File 'lib/rigor/scope.rb', line 44

def discovered_method_visibilities = @discovery.discovered_method_visibilities

#discovered_method_visibility(class_name, method_name) ⇒ Symbol?

v0.1.2 — per-class table mapping method_name (Symbol) → :public | :private | :protected. Populated by ScopeIndexer for every def it sees inside a class body, with the visibility taken from the surrounding private / protected / public modifier state plus any post-hoc private :name, ... named-argument calls. Consumed by the def.method-visibility-mismatch rule so explicit-non-self calls to a private method surface a diagnostic.

Parameters:

  • class_name (String, Symbol)
  • method_name (String, Symbol)

Returns:

  • (Symbol, nil) 


511
512
513
514
515
516
 
# File 'lib/rigor/scope.rb', line 511

def discovered_method_visibility(class_name, method_name)
  table = @discovery.discovered_method_visibilities[class_name.to_s]
  return nil unless table

  table[method_name.to_sym]
end

#discovered_methods ⇒ Hash[String, Hash[Symbol, Symbol]]

Returns:

  • (Hash[String, Hash[Symbol, Symbol]]) 


40
 
# File 'lib/rigor/scope.rb', line 40

def discovered_methods = @discovery.discovered_methods

#discovered_singleton_def_nodes ⇒ Hash[String, Hash[Symbol, untyped]]

Returns:

  • (Hash[String, Hash[Symbol, untyped]]) 


42
 
# File 'lib/rigor/scope.rb', line 42

def discovered_singleton_def_nodes = @discovery.discovered_singleton_def_nodes

#discovered_superclasses ⇒ Hash[String, String]

Returns:

  • (Hash[String, String]) 


45
 
# File 'lib/rigor/scope.rb', line 45

def discovered_superclasses = @discovery.discovered_superclasses

#evaluate(node, tracer: nil) ⇒ [Type::t, Scope]

Statement-level evaluation: returns the pair [type, scope'] where type is what the node produces and scope' is the scope observable after the node has run. The receiver scope is never mutated. See Inference::StatementEvaluator for the catalogue of nodes that thread scope; everything else defers to #type_of and returns the receiver scope unchanged.

Parameters:

Returns:



599
600
601
 
# File 'lib/rigor/scope.rb', line 599

def evaluate(node, tracer: nil)
  Inference::StatementEvaluator.new(scope: self, tracer: tracer).evaluate(node)
end

#facts_for(target: nil, bucket: nil) ⇒ Array[Analysis::FactStore::Fact]

Parameters:

Returns:



583
584
585
 
# File 'lib/rigor/scope.rb', line 583

def facts_for(target: nil, bucket: nil)
  fact_store.facts_for(target: target, bucket: bucket)
end

#forget_match_globals ⇒ Scope

Returns:



313
314
315
316
317
 
# File 'lib/rigor/scope.rb', line 313

def forget_match_globals
  return self unless @globals.keys.any? { |k| MATCH_DATA_GLOBALS.include?(k) }

  rebuild(globals: @globals.except(*MATCH_DATA_GLOBALS).freeze)
end

#global(name) ⇒ Type::t?

Parameters:

  • name (String, Symbol)

Returns:

  • (Type::t, nil) 


252
253
254
 
# File 'lib/rigor/scope.rb', line 252

def global(name)
  @globals[name.to_sym]
end

#hash ⇒ Integer

Returns:

  • (Integer) 


637
638
639
 
# File 'lib/rigor/scope.rb', line 637

def hash
  [Scope, environment.object_id, @locals, fact_store, self_type, @ivars, @cvars, @globals].hash
end

#in_source_constants ⇒ Hash[String, Type::t]

Returns:

  • (Hash[String, Type::t]) 


39
 
# File 'lib/rigor/scope.rb', line 39

def in_source_constants = @discovery.in_source_constants

#includes_of(class_name) ⇒ Array[String]

ADR-24 slice 2 — per-class/module table mapping a fully qualified user class or module to the list of module names it includes / prepends, AS WRITTEN at the mixin call. Populated by ScopeIndexer (per-file plus the cross-file pre-pass) and consumed by ExpressionTyper#resolve_user_def_through_ancestors so an implicit-self call resolves against an included module's defs, not just the superclass chain. As-written names are resolved to qualified classes at walk time.

Parameters:

  • class_name (String, Symbol)

Returns:

  • (Array[String]) 


488
489
490
491
 
# File 'lib/rigor/scope.rb', line 488

def includes_of(class_name)
  record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
  @discovery.discovered_includes[class_name.to_s] || []
end

#indexed_narrowing(receiver_kind, receiver_name, key) ⇒ Type::t?

Closes the "params[:f] ||= []; params[:f] << x" precision gap (ROADMAP § Type-language / engine — indexed-collection narrowing through Hash[k] ||= default). After receiver[key] ||= default, the next read at receiver[key] is known non-nil; recording the post-||= type keyed on (receiver_kind, receiver_name, literal_key) lets the ExpressionTyper's [] dispatch hand back the narrowed type. Receiver-rebind and []=/mutator invalidation rules are documented at the call sites in Inference::StatementEvaluator.

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)
  • key (Object)

Returns:

  • (Type::t, nil) 


524
525
526
 
# File 'lib/rigor/scope.rb', line 524

def indexed_narrowing(receiver_kind, receiver_name, key)
  @indexed_narrowings[indexed_key(receiver_kind, receiver_name, key)]
end

#ivar(name) ⇒ Type::t?

Slice 7 phase 1 — instance/class/global variable bindings. ivar(name) / cvar(name) / global(name) return the type currently bound for the named variable, or nil when the variable has not been written in the analyzed slice of the program. The first cut tracks bindings only within a single method body (each def enters with a fresh binding map), so reads in other methods of the same class fall through to Dynamic[Top]. Cross-method ivar/cvar inference is a follow-up slice.

Parameters:

  • name (String, Symbol)

Returns:

  • (Type::t, nil) 


244
245
246
 
# File 'lib/rigor/scope.rb', line 244

def ivar(name)
  @ivars[name.to_sym]
end

#ivar_origin(name) ⇒ Symbol?

Parameters:

  • name (String, Symbol)

Returns:

  • (Symbol, nil) 


160
 
# File 'lib/rigor/scope.rb', line 160

def ivar_origin(name) = @ivar_origins[name.to_sym]

#join(other) ⇒ Scope

Joins this scope with another at a control-flow merge point. The joined scope is bound to every local that BOTH branches bind, with the type widened to the union of both sides. Names bound in only one branch are dropped from the joined scope; the eventual statement-level evaluator (Slice 3 phase 2) is responsible for nil-injecting half-bound names where the language semantics demand it. The two scopes MUST share the same Environment.

Parameters:

Returns:

Raises:

  • (ArgumentError) 


608
609
610
611
612
613
614
615
616
617
618
619
620
 
# File 'lib/rigor/scope.rb', line 608

def join(other)
  raise ArgumentError, "join requires a Rigor::Scope, got #{other.class}" unless other.is_a?(Scope)

  unless environment.equal?(other.environment)
    raise ArgumentError, "join requires both scopes to share the same Environment"
  end

  joined_locals = join_bindings(locals, other.locals)
  joined_ivars = join_bindings(ivars, other.ivars)
  joined_cvars = join_bindings(cvars, other.cvars)
  joined_globals = join_bindings(globals, other.globals)
  build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other)
end

#local(name) ⇒ Type::t?

Parameters:

  • name (String, Symbol)

Returns:

  • (Type::t, nil) 


176
177
178
 
# File 'lib/rigor/scope.rb', line 176

def local(name)
  @locals[name.to_sym]
end

#local_facts(name, bucket: nil) ⇒ Array[Analysis::FactStore::Fact]

Parameters:

  • name (String, Symbol)
  • bucket: (Symbol, nil) (defaults to: nil)

Returns:



587
588
589
 
# File 'lib/rigor/scope.rb', line 587

def local_facts(name, bucket: nil)
  facts_for(target: Analysis::FactStore::Target.local(name), bucket: bucket)
end

#local_origin(name) ⇒ Symbol?

ADR-82 WD1 — the propagated origin of the Dynamic value currently bound to a local / instance variable, or nil when none is tracked. Consulted by Inference::ProtectionScanner when a dispatch's receiver is a bare x / @x read whose own node carries no origin.

Parameters:

  • name (String, Symbol)

Returns:

  • (Symbol, nil) 


159
 
# File 'lib/rigor/scope.rb', line 159

def local_origin(name) = @local_origins[name.to_sym]

#method_chain_narrowing(receiver_kind, receiver_name, method_name) ⇒ Type::t?

Closes the "stable receiver method-chain narrowing" gap (ROADMAP § Future cycles / Type-language / engine — "Method-call receiver narrowing across stable receivers"; 2026-05-28 Redmine survey). After if x.last.is_a?(Array) the dominated body's x.last reads MUST observe the truthy-narrowed type; the same chain reaching the falsey edge observes the negative narrowing.

Address shape mirrors #indexed_narrowing: stable root variable + no-arg single-hop method name. See ChainKey for the precise contract.

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)
  • method_name (String, Symbol)

Returns:

  • (Type::t, nil) 


557
558
559
 
# File 'lib/rigor/scope.rb', line 557

def method_chain_narrowing(receiver_kind, receiver_name, method_name)
  @method_chain_narrowings[chain_key(receiver_kind, receiver_name, method_name)]
end

#param_inferred_types ⇒ Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]

ADR-67 WD3 — call-site-inferred parameter types, keyed by [class_name, method_name, kind]. build_method_entry_scope consults this to seed an undeclared def parameter with the union of its resolved call-site argument types (precision-additive; an RBS-declared parameter always wins). Empty unless a collection pass seeded it.

Returns:

  • (Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]) 


54
 
# File 'lib/rigor/scope.rb', line 54

def param_inferred_types = @discovery.param_inferred_types

#program_globals ⇒ Hash[Symbol, Type::t]

Returns:

  • (Hash[Symbol, Type::t]) 


37
 
# File 'lib/rigor/scope.rb', line 37

def program_globals = @discovery.program_globals

#record_dynamic_origin(node, cause) ⇒ Scope

Parameters:

  • node (Object)
  • cause (Symbol)

Returns:



115
116
117
118
 
# File 'lib/rigor/scope.rb', line 115

def record_dynamic_origin(node, cause)
  @dynamic_origins[node] = cause
  self
end

#seed_declaration_sourced_ivar(name, type) ⇒ Scope

ADR-58 WD1 — used by the method-entry seed to mark an ivar whose only provenance is the class-ivar index. Unlike with_ivar this binds the type AND records the declaration-sourced mark in one transition.

Parameters:

  • name (String, Symbol)
  • type (Type::t)

Returns:



271
272
273
274
 
# File 'lib/rigor/scope.rb', line 271

def seed_declaration_sourced_ivar(name, type)
  rebuild(ivars: @ivars.merge(name.to_sym => type).freeze,
          declaration_sourced: add_declaration_sourced(:ivar, name))
end

#singleton_def_for(class_name, method_name) ⇒ Object?

Module-singleton call resolution (ADR-57 follow-up) — companion of #user_def_for for SINGLETON-side defs (def self.x, def Foo.x, class << self bodies, and module_function defs). Returns the Prism::DefNode for class_name.method_name invoked on the module/class constant itself, or nil. The discovered_def_nodes table is deliberately instance-side only (its ancestor walk binds self as Nominal), so singleton bodies live in a parallel table the ScopeIndexer populates alongside it. Records the same cross-file dependency edge as the instance path (ADR-46).

Parameters:

  • class_name (String, Symbol)
  • method_name (String, Symbol)

Returns:

  • (Object, nil) 


380
381
382
383
384
385
 
# File 'lib/rigor/scope.rb', line 380

def singleton_def_for(class_name, method_name)
  table = @discovery.discovered_singleton_def_nodes[class_name.to_s]
  node = table && table[method_name.to_sym]
  record_cross_file_method(class_name, method_name, node) if Analysis::DependencyRecorder.active?
  node
end

#struct_fold_safe?(name) ⇒ Boolean

True when name's Struct member reads are fold-safe in this body (the local is provably never mutated / aliased / escaped).

Parameters:

  • name (String, Symbol)

Returns:

  • (Boolean) 


229
230
231
 
# File 'lib/rigor/scope.rb', line 229

def struct_fold_safe?(name)
  @struct_fold_safe_locals.include?(name.to_sym)
end

#struct_member_layout(class_name) ⇒ { members: Array[Symbol], keyword_init: bool }?

ADR-48 Struct follow-up — the { members:, keyword_init: } layout recorded for a Struct.new(...)-defined class, in the constant form (Point = Struct.new(:x, :y)) and the named-subclass form (class Point < Struct.new(:x, :y)). Consumed by Inference::MethodDispatcher::StructFolding so Point.new(...) on a Singleton[Point] receiver materialises a member instance. Returns nil when the class has no recorded struct layout. Mirrors #data_member_layout's dependency-recording contract.

Parameters:

  • class_name (String, Symbol)

Returns:

  • ({ members: Array[Symbol], keyword_init: bool }, nil) 


477
478
479
480
481
 
# File 'lib/rigor/scope.rb', line 477

def struct_member_layout(class_name)
  layout = @discovery.struct_member_layouts[class_name.to_s]
  record_class_dependency(class_name) if layout && Analysis::DependencyRecorder.active?
  layout
end

#struct_member_layouts ⇒ Hash[String, { members: Array[Symbol], keyword_init: bool }]

Returns:

  • (Hash[String, { members: Array[Symbol], keyword_init: bool }]) 


49
50
51
52
53
 
# File 'lib/rigor/scope.rb', line 49

def struct_member_layouts = @discovery.struct_member_layouts
# ADR-67 WD3 — call-site-inferred parameter types, keyed by `[class_name, method_name, kind]`.
# `build_method_entry_scope` consults this to seed an undeclared `def` parameter with the union of its resolved
# call-site argument types (precision-additive; an RBS-declared parameter always wins). Empty unless a
# collection pass seeded it.

#superclass_of(class_name) ⇒ String?

ADR-24 slice 2 — per-class table mapping a fully qualified user-class name to its superclass name AS WRITTEN at the class Foo < Bar declaration ("Bar", possibly a qualified "A::B"). Populated by ScopeIndexer — per-file plus the cross-file project pre-pass — and consumed by ExpressionTyper#try_user_method_inference to walk the superclass chain when an implicit-self call does not resolve against the enclosing class's own defs. The as-written name is resolved to a qualified class at walk time against the call's lexical nesting.

Parameters:

  • class_name (String, Symbol)

Returns:

  • (String, nil) 


454
455
456
457
 
# File 'lib/rigor/scope.rb', line 454

def superclass_of(class_name)
  record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
  @discovery.discovered_superclasses[class_name.to_s]
end

#top_level_def_for(method_name) ⇒ Object?

v0.0.3 A — top-level def lookup for implicit-self calls. Returns the Prism::DefNode for a top-level (or DSL-block-nested, outside any class body) def <method_name> in the file, or nil. The sentinel key is owned by Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY; consumers should treat its presence as an opaque implementation detail and go through this accessor.

Parameters:

  • method_name (String, Symbol)

Returns:

  • (Object, nil) 


409
410
411
412
413
414
 
# File 'lib/rigor/scope.rb', line 409

def top_level_def_for(method_name)
  table = @discovery.discovered_def_nodes[Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY]
  node = table && table[method_name.to_sym]
  record_cross_file_toplevel(method_name, node) if Analysis::DependencyRecorder.active?
  node
end

#toplevel? ⇒ Boolean

ADR-34 § "Decision" — predicate identifying a toplevel-shaped scope (no enclosing class / module body). True at the top of a file AND inside a top-level def body (since toplevel defs leave self_type nil per the existing scope-construction contract — the same nil-self_type signal ADR-24's self-call return adoption historically keyed on before ADR-57 opened the gate unconditionally). Used by CheckRules#unresolved_toplevel_diagnostic to gate the call.unresolved-toplevel rule so it fires only outside class / module bodies, where Rails-DSL metaprogramming leniency (ADR-24 WD3 → WD4) does not apply.

Returns:

  • (Boolean) 


359
360
361
 
# File 'lib/rigor/scope.rb', line 359

def toplevel?
  @self_type.nil?
end

#type_of(node, tracer: nil) ⇒ Type::t

Parameters:

Returns:

  • (Type::t) 


591
592
593
 
# File 'lib/rigor/scope.rb', line 591

def type_of(node, tracer: nil)
  Inference::ExpressionTyper.new(scope: self, tracer: tracer).type_of(node)
end

#user_def_for(class_name, method_name) ⇒ Object?

v0.0.2 #5 — per-class table mapping method_name (Symbol) → Prism::DefNode. Populated by ScopeIndexer alongside discovered_methods for instance-side defs only (singleton-side and define_method-introduced methods do not contribute a static body the engine can re-type). Consumed by ExpressionTyper to do inter-procedural return-type inference when the receiver class is user-defined and has no RBS sig.

Parameters:

  • class_name (String, Symbol)
  • method_name (String, Symbol)

Returns:

  • (Object, nil) 


367
368
369
370
371
372
 
# File 'lib/rigor/scope.rb', line 367

def user_def_for(class_name, method_name)
  table = @discovery.discovered_def_nodes[class_name.to_s]
  node = table && table[method_name.to_sym]
  record_cross_file_method(class_name, method_name, node) if Analysis::DependencyRecorder.active?
  node
end

#user_def_site_for(class_name, method_name) ⇒ String?

Companion to #user_def_for: returns the "path:line" where the project defines class_name#method_name (instance-side), or nil. Populated only by the cross-file project pre-pass (Inference::ScopeIndexer.discovered_def_index_for_paths) — a Prism::Location hides its source file, so the site is recorded at scan time. CheckRules#undefined_method_diagnostic consults this to name the defining file when a project monkey-patch on a core/stdlib/gem class is called cross-file, so the diagnostic can point at pre_eval: (ADR-17) instead of reading as a bare unresolved call.

Parameters:

  • class_name (String, Symbol)
  • method_name (String, Symbol)

Returns:

  • (String, nil) 


441
442
443
444
445
446
 
# File 'lib/rigor/scope.rb', line 441

def user_def_site_for(class_name, method_name)
  table = @discovery.discovered_def_sources[class_name.to_s]
  return nil unless table

  table[method_name.to_sym]
end

#with_cvar(name, type) ⇒ Scope

Parameters:

  • name (String, Symbol)
  • type (Type::t)

Returns:



297
298
299
 
# File 'lib/rigor/scope.rb', line 297

def with_cvar(name, type)
  rebuild(cvars: @cvars.merge(name.to_sym => type).freeze)
end

#with_declaration_sourced_local(name, type) ⇒ Scope

ADR-58 WD1 — a local assignment r = @right whose RHS is a pure read of a declaration-sourced ivar inherits the mark, so the survey's exact rotation/traversal shape (r = @right; r.key) does not fire. Binds the type and stamps the local's mark in one transition (the plain with_local would have dropped it).

Parameters:

  • name (String, Symbol)
  • type (Type::t)

Returns:



279
280
281
282
 
# File 'lib/rigor/scope.rb', line 279

def with_declaration_sourced_local(name, type)
  written = with_local(name, type)
  written.with_local_declaration_mark(name)
end

#with_discovery(index) ⇒ Scope

ADR-53 Track A — swaps the whole discovery index in one transition. The sole seeding path; the per-table writers it replaced are derived off-Scope through scope.discovery.with(table_name: table).

Parameters:

Returns:



235
236
237
 
# File 'lib/rigor/scope.rb', line 235

def with_discovery(index)
  rebuild(discovery: index)
end

#with_fact(fact) ⇒ Scope

Parameters:

Returns:



203
204
205
 
# File 'lib/rigor/scope.rb', line 203

def with_fact(fact)
  rebuild(fact_store: fact_store.with_fact(fact))
end

#with_global(name, type) ⇒ Scope

Parameters:

  • name (String, Symbol)
  • type (Type::t)

Returns:



301
302
303
 
# File 'lib/rigor/scope.rb', line 301

def with_global(name, type)
  rebuild(globals: @globals.merge(name.to_sym => type).freeze)
end

#with_indexed_narrowing(receiver_kind, receiver_name, key, type) ⇒ Scope

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)
  • key (Object)
  • type (Type::t)

Returns:



528
529
530
531
532
533
 
# File 'lib/rigor/scope.rb', line 528

def with_indexed_narrowing(receiver_kind, receiver_name, key, type)
  new_table = @indexed_narrowings.merge(
    indexed_key(receiver_kind, receiver_name, key) => type
  ).freeze
  rebuild(indexed_narrowings: new_table)
end

#with_ivar(name, type) ⇒ Scope

Parameters:

  • name (String, Symbol)
  • type (Type::t)

Returns:



256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/rigor/scope.rb', line 256

def with_ivar(name, type)
  new_indexed_narrowings = drop_indexed_narrowings_for(:ivar, name)
  new_chain_narrowings = drop_chain_narrowings_for(:ivar, name)
  # ADR-58 WD1 — a method-local ivar write or narrowing is flow-live: drop any declaration-sourced mark so
  # subsequent reads of `@name` observe flow-live provenance and fire as before. The seed path uses
  # `seed_declaration_sourced_ivar` to (re-)establish the mark.
  rebuild(ivars: @ivars.merge(name.to_sym => type).freeze,
          indexed_narrowings: new_indexed_narrowings,
          method_chain_narrowings: new_chain_narrowings,
          declaration_sourced: drop_declaration_sourced_for(:ivar, name),
          ivar_origins: drop_origin(@ivar_origins, name))
end

#with_ivar_origin(name, cause) ⇒ Scope

Parameters:

  • name (String, Symbol)
  • cause (Symbol, nil)

Returns:



170
171
172
173
174
 
# File 'lib/rigor/scope.rb', line 170

def with_ivar_origin(name, cause)
  return self if cause.nil?

  rebuild(ivar_origins: @ivar_origins.merge(name.to_sym => cause).freeze)
end

#with_local(name, type) ⇒ Scope

Parameters:

  • name (String, Symbol)
  • type (Type::t)

Returns:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/rigor/scope.rb', line 180

def with_local(name, type)
  # `rigor trace` — the moment a local enters the scope.
  Inference::FlowTracer.bind(name, type) if Inference::FlowTracer.active?
  new_locals = @locals.merge(name.to_sym => type).freeze
  new_fact_store = fact_store.invalidate_target(Analysis::FactStore::Target.local(name))
  # Rebinding `name` invalidates every "after `receiver[key] ||= default`" narrowing keyed on it — the slot at
  # `name[*]` is reachable through the old binding only, so the next read against the new binding does not
  # inherit the earlier non-nil guarantee. The same logic applies to method-chain narrowings: `x.last` after
  # `x = something_new` is a call on the new binding and any prior `is_a?`-driven narrowing keyed on
  # `(local, :x, :last)` no longer holds.
  new_indexed_narrowings = drop_indexed_narrowings_for(:local, name)
  new_chain_narrowings = drop_chain_narrowings_for(:local, name)
  # ADR-58 WD1 — rebinding a local is a flow-live touch: any prior declaration-sourced mark on `name` no
  # longer holds (the new value may carry a method-local nil). `with_declaration_sourced_local` re-establishes
  # the mark afterward when the RHS is a pure copy of a declaration-sourced ivar read; the default is to drop
  # it.
  rebuild(locals: new_locals, fact_store: new_fact_store,
          indexed_narrowings: new_indexed_narrowings,
          method_chain_narrowings: new_chain_narrowings,
          declaration_sourced: drop_declaration_sourced_for(:local, name),
          local_origins: drop_origin(@local_origins, name))
end

#with_local_declaration_mark(name) ⇒ Scope

ADR-58 WD1 — re-stamp the local mark on a scope produced by with_local (which always drops it). Public so the sibling with_declaration_sourced_local can call it across the new post-write receiver without reaching into a private method.

Parameters:

  • name (String, Symbol)

Returns:



287
288
289
 
# File 'lib/rigor/scope.rb', line 287

def with_local_declaration_mark(name)
  rebuild(declaration_sourced: add_declaration_sourced(:local, name))
end

#with_local_origin(name, cause) ⇒ Scope

Records the cause of the Dynamic value being bound to name. A nil cause is a no-op (the common case — most bindings are concrete or have no recorded origin), so callers need not pre-check.

Parameters:

  • name (String, Symbol)
  • cause (Symbol, nil)

Returns:



164
165
166
167
168
 
# File 'lib/rigor/scope.rb', line 164

def with_local_origin(name, cause)
  return self if cause.nil?

  rebuild(local_origins: @local_origins.merge(name.to_sym => cause).freeze)
end

#with_method_chain_narrowing(receiver_kind, receiver_name, method_name, type) ⇒ Scope

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)
  • method_name (String, Symbol)
  • type (Type::t)

Returns:



561
562
563
564
565
566
 
# File 'lib/rigor/scope.rb', line 561

def with_method_chain_narrowing(receiver_kind, receiver_name, method_name, type)
  new_table = @method_chain_narrowings.merge(
    chain_key(receiver_kind, receiver_name, method_name) => type
  ).freeze
  rebuild(method_chain_narrowings: new_table)
end

#with_self_type(type) ⇒ Scope

Slice A-engine. Returns a scope with self_type set to type, preserving locals and facts. StatementEvaluator injects this at class-body and method-body boundaries; ExpressionTyper consults it when typing Prism::SelfNode and implicit-self Prism::CallNode receivers.

Parameters:

  • type (Type::t, nil)

Returns:



210
211
212
 
# File 'lib/rigor/scope.rb', line 210

def with_self_type(type)
  rebuild(self_type: type)
end

#with_source_path(path) ⇒ Scope

ADR-28 / ADR-52 slice 5a — per-file source path carried on the scope. The analyzer stamps the current file's path onto the seed scope; nested rebuilds propagate it so plugin rules (dynamic_return's file_methods: gate, sigil checks) can resolve "which file does this call site belong to?" without thread-locals.

Parameters:

  • path (String, nil)

Returns:



217
218
219
 
# File 'lib/rigor/scope.rb', line 217

def with_source_path(path)
  rebuild(source_path: path)
end

#with_struct_fold_safe(locals) ⇒ Scope

ADR-48 Struct slice 3 — installs the per-body fold-safe-local set (Inference::StructFoldSafety). Set once at body entry; inherited unchanged through subsequent flow transitions.

Parameters:

  • locals (Set[Symbol])

Returns:



223
224
225
 
# File 'lib/rigor/scope.rb', line 223

def with_struct_fold_safe(locals)
  rebuild(struct_fold_safe_locals: locals)
end

#without_indexed_narrowing(receiver_kind, receiver_name, key) ⇒ Scope

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)
  • key (Object)

Returns:



535
536
537
538
539
540
541
 
# File 'lib/rigor/scope.rb', line 535

def without_indexed_narrowing(receiver_kind, receiver_name, key)
  lookup = indexed_key(receiver_kind, receiver_name, key)
  return self unless @indexed_narrowings.key?(lookup)

  new_table = @indexed_narrowings.reject { |k, _| k == lookup }.freeze
  rebuild(indexed_narrowings: new_table)
end

#without_indexed_narrowings_for(receiver_kind, receiver_name) ⇒ Scope

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)

Returns:



543
544
545
546
547
548
 
# File 'lib/rigor/scope.rb', line 543

def without_indexed_narrowings_for(receiver_kind, receiver_name)
  new_table = drop_indexed_narrowings_for(receiver_kind, receiver_name)
  return self if new_table.equal?(@indexed_narrowings)

  rebuild(indexed_narrowings: new_table)
end

#without_method_chain_narrowing(receiver_kind, receiver_name, method_name) ⇒ Scope

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)
  • method_name (String, Symbol)

Returns:



568
569
570
571
572
573
574
 
# File 'lib/rigor/scope.rb', line 568

def without_method_chain_narrowing(receiver_kind, receiver_name, method_name)
  lookup = chain_key(receiver_kind, receiver_name, method_name)
  return self unless @method_chain_narrowings.key?(lookup)

  new_table = @method_chain_narrowings.reject { |k, _| k == lookup }.freeze
  rebuild(method_chain_narrowings: new_table)
end

#without_method_chain_narrowings_for(receiver_kind, receiver_name) ⇒ Scope

Parameters:

  • receiver_kind (Symbol)
  • receiver_name (String, Symbol)

Returns:



576
577
578
579
580
581
 
# File 'lib/rigor/scope.rb', line 576

def without_method_chain_narrowings_for(receiver_kind, receiver_name)
  new_table = drop_chain_narrowings_for(receiver_kind, receiver_name)
  return self if new_table.equal?(@method_chain_narrowings)

  rebuild(method_chain_narrowings: new_table)
end