rigortype 0.4.1 → 0.4.3

data/lib/rigor/scope.rb

@@ -5,6 +5,7 @@ require_relative "environment"
 require_relative "scope/discovery_index"
 require_relative "scope/resolution_chain"
 require_relative "inference/definer_resolution"
+require_relative "inference/in_effect_refinements"
 require_relative "analysis/fact_store"
 require_relative "analysis/dependency_recorder"
 require_relative "inference/expression_typer"
@@ -26,12 +27,12 @@ module Rigor
                 :indexed_narrowings, :method_chain_narrowings,
                 :declaration_sourced, :published_constant_sourced,
                 :source_path, :discovery, :struct_fold_safe_locals,
-                :opaque_block_self, :singleton_class_body, :lexical_nesting,
+                :opaque_block_self, :block_self_unknown, :singleton_class_body, :lexical_nesting,
                 :dynamic_origins, :local_origins, :ivar_origins,
                 :void_origins, :plugin_typed_calls,
                 :optimistic_origins, :optimistic_locals, :optimistic_ivars,
                 :repeated_or_writes, :match_frame,
-                :constant_narrowings, :guard_records, :bot_guard_classes
+                :constant_narrowings, :guard_records, :bot_guard_classes, :declared_refinements
 
     # ADR-53 Track A — the seed-time discovery tables live on the {DiscoveryIndex} the scope carries by a single
     # reference; the per-table readers stay on Scope so engine call sites and plugins are unaffected by the
@@ -62,6 +63,20 @@ module Rigor
     # Issue #1120 — `{refined class name => {method name => [refining module names]}}`: what each
     # `refine X do … end` block defines, visible only where a `using` of its module is in effect.
     def discovered_refinements = @discovery.discovered_refinements
+
+    # Issue #1673 (ADR-121 WD1) — the in-effect refinements at `node`: the refining-module names whose refinements
+    # Ruby applies there, ordered so a later activation comes later (the later one wins), each once at its first
+    # position, each `using`'d module expanded through its includes and prepends in CRuby's activation order.
+    # `declared` is a block source's modules, appended and expanded on the same terms; it defaults to this scope's
+    # {#declared_refinements}, a plugin-declared refined block's (#1667). An entry may be
+    # `Inference::InEffectRefinements::UNKNOWN`, which means any refinement may be in effect. A node another file
+    # wrote (a callee body typed under this file's scope) answers `declared` alone. Reads include edges, so it records
+    # the dependencies `Inference::InEffectRefinements.activated_modules` names; a consumer that asks for a method
+    # name also records `refinement:<name>` (`Inference::InEffectRefinements.refining_modules`).
+    def in_effect_refinements(node, declared = @declared_refinements)
+      Inference::InEffectRefinements.for_node(self, node, declared)
+    end
+
     # Issue #1367 — the project's `Inference::GlobalWriteCensus`, a `Set` of frozen entries.
     def discovered_global_write_census = @discovery.discovered_global_write_census
     def discovered_includes = @discovery.discovered_includes
@@ -182,7 +197,9 @@ module Rigor
     #   today.
     # - `receiver_name` is the variable's Symbol.
     # - `key` is the Ruby value of the literal index (Symbol / String / Integer). Non-literal keys
-    #   (`params[field]`) are not recorded; they have no stable address.
+    #   (`params[field]`) have no stable address for a recorded value. A `key?` guard with a non-literal key
+    #   (issue #1703) records an {Inference::KeyPresenceGuard::KeyExpr} here instead, with `receiver_kind`
+    #   `:const` allowed; its entry marks presence only.
     IndexedKey = Data.define(:receiver_kind, :receiver_name, :key)
 
     # Narrowing key for a no-arg / no-block method-call chain `receiver.method_name` (a "single-hop" chain per A1
@@ -234,11 +251,11 @@ module Rigor
     # class in a project that publishes nothing) allocates none.
     EMPTY_PUBLISHED_CONSTANT_IVARS = Set.new.freeze
     # The index `||=` sites of a repeating block body whose slot an earlier run of the body may have filled,
-    # keyed by node identity and laid by a block-return pass at the body's entry
-    # ({#with_repeated_or_writes}; `Inference::RepeatedOrWrites` decides which). The memoizing `||=` reading
-    # (`StatementEvaluator#index_compound_write_value`) is withheld at such a site. The mark belongs to the
-    # site, so no rebind or narrowing of a variable drops it, and a join keeps a site either arm holds: the
-    # mark only ever withholds that reading, whose answer is the narrower one.
+    # keyed by node identity and laid at the body's entry by a block-return pass or by `StatementEvaluator`'s
+    # statement and write-back passes ({#with_repeated_or_writes}; `Inference::RepeatedOrWrites` decides which).
+    # The memoizing `||=` reading (`StatementEvaluator#index_compound_write_value`) is withheld at such a site.
+    # The mark belongs to the site, so no rebind or narrowing of a variable drops it, and a join keeps a site
+    # either arm holds: the mark only ever withholds that reading, whose answer is the narrower one.
     EMPTY_REPEATED_OR_WRITES = {}.compare_by_identity.freeze
     # Issue #1429 — the narrowing a guard leaves on a constant reference (`STDOUT.is_a?(StringIO)`, `if CONFIG`),
     # keyed by the reference's spelling ({Inference::Narrowing.constant_key}: `"STDOUT"`, `"::Foo::BAR"`). A constant
@@ -320,6 +337,7 @@ module Rigor
       source_path: nil,
       struct_fold_safe_locals: EMPTY_FOLD_SAFE,
       opaque_block_self: false,
+      block_self_unknown: false,
       singleton_class_body: false,
       lexical_nesting: nil,
       dynamic_origins: {}.compare_by_identity,
@@ -334,7 +352,8 @@ module Rigor
       match_frame: nil,
       constant_narrowings: EMPTY_CONSTANT_NARROWINGS,
       guard_records: EMPTY_GUARD_RECORDS,
-      bot_guard_classes: EMPTY_BOT_GUARD_CLASSES
+      bot_guard_classes: EMPTY_BOT_GUARD_CLASSES,
+      declared_refinements: Inference::InEffectRefinements::EMPTY
     )
       @environment = environment
       @locals = locals
@@ -351,6 +370,7 @@ module Rigor
       @source_path = source_path
       @struct_fold_safe_locals = struct_fold_safe_locals
       @opaque_block_self = opaque_block_self
+      @block_self_unknown = block_self_unknown
       @singleton_class_body = singleton_class_body
       @lexical_nesting = lexical_nesting
       @dynamic_origins = dynamic_origins
@@ -366,6 +386,7 @@ module Rigor
       @constant_narrowings = constant_narrowings
       @guard_records = guard_records
       @bot_guard_classes = bot_guard_classes
+      @declared_refinements = declared_refinements
       freeze
     end
 
@@ -378,6 +399,14 @@ module Rigor
       self
     end
 
+    # Issue #1703 — this scope with private copies of the identity-keyed side tables (dynamic, void and optimistic
+    # origins, plugin-typed calls), so a second walk from it — the `key?`-guarded re-walk — records into its own
+    # tables and never into the ones the file's analysis reads.
+    def with_isolated_side_tables
+      rebuild(dynamic_origins: @dynamic_origins.dup, void_origins: @void_origins.dup,
+              plugin_typed_calls: @plugin_typed_calls.dup, optimistic_origins: @optimistic_origins.dup)
+    end
+
     def optimistic_local(name) = Inference::OptimisticOrigin.bound_cause(@optimistic_locals[name.to_sym])
     def optimistic_ivar(name) = Inference::OptimisticOrigin.bound_cause(@optimistic_ivars[name.to_sym])
 
@@ -428,6 +457,13 @@ module Rigor
       @locals[name.to_sym]
     end
 
+    # Issue #1840 — replaces the joined bindings of locals a branch merge only narrowed with their pre-branch
+    # binding ({Inference::UntypedRejoin}). Unlike {#with_local} this is not a write: the value is the one the
+    # branches started from, so every fact, narrowing and mark the join kept about it still holds.
+    def with_rejoined_locals(bindings)
+      rebuild(locals: @locals.merge(bindings).freeze)
+    end
+
     def with_local(name, type)
       bind_local(name, type, keep_marks: false)
     end
@@ -476,6 +512,39 @@ module Rigor
       rebuild(self_type: type)
     end
 
+    # Issue #1717 — installs the `self` a block body runs with when the engine KNOWS it: an ADR-16
+    # `block_as_methods:` match, `define_method`, or a `Class.new` / `refine` body (#319). Like
+    # {#with_self_type} it leaves the #316 mark alone; it also sets {#block_self_unknown?} to `keeps_unknown`,
+    # which a caller passes from {#block_self_narrowing_unknown?}. A nil `type` narrows nothing and keeps it.
+    #
+    # Issue #1695 — instance variables belong to `self`, so a narrowing onto a DIFFERENT `self` than the enclosing
+    # scope's also drops every instance-variable binding the body would otherwise inherit ({#without_ivar_bindings}):
+    # a `define_method` block in a class body runs on an instance, and the class body's `@label = nil` is the class
+    # object's ivar, not the one the block reads. The body's reads answer `Dynamic` until it writes them. A narrowing
+    # that keeps the caller's `self` (an ADR-16 `:lexical` entry) keeps them.
+    def with_block_self_type(type, keeps_unknown: false)
+      unknown = type.nil? ? @block_self_unknown : keeps_unknown
+      return rebuild(self_type: type, block_self_unknown: unknown) if type.nil? || type == @self_type
+
+      without_ivar_bindings(type, unknown)
+    end
+
+    # Issue #1717 — whether a block-self narrowing for `call_node`, asked from this (the CALLER's) scope, is
+    # built on an unknown `self`. `define_method` and an implicit- or `self`-receiver `block_as_methods:` match
+    # read the lexical `self`, which inside a block of unknown `self` is the enclosing method's, not the
+    # block's; a narrowing keyed on an explicit receiver (`Grape::API.namespace do`) does not depend on it.
+    #
+    # Issue #1759 — one narrowing is not: a `define_method` written directly in a `refine X` block
+    # ({REFINEMENT_BLOCK_SELF}) defines a method of the refinement, which runs on an instance of X, and the
+    # `Nominal[X]` it reads off the block's lexical `Singleton[X]` is that `self`.
+    def block_self_narrowing_unknown?(call_node)
+      return false unless @block_self_unknown
+      return false if @block_self_unknown == REFINEMENT_BLOCK_SELF && call_node.name == :define_method
+
+      receiver = call_node.receiver
+      receiver.nil? || receiver.is_a?(Prism::SelfNode)
+    end
+
     # Issue #652 — installs the body's REAL `Module.nesting`, innermost first, as recorded at declaration
     # time by `Inference::StatementEvaluator` (`["Admin::UsersController"]` for a compact
     # `class Admin::UsersController`, `["Admin::UsersController", "Admin"]` for the nested spelling). A
@@ -518,15 +587,52 @@ module Rigor
     # `Array#each` without knowing the callee. The flag is set at every block entry that leaves `self_type`
     # unnarrowed and is inherited by every scope derived inside the block; it never leaks past the block,
     # because `eval_call` returns the caller's scope unchanged.
+    #
+    # Entering also sets {#block_self_unknown?} (issue #1717), the separate mark `call.undefined-method` reads.
     def entering_opaque_block
-      return self if @opaque_block_self
+      return self if @opaque_block_self && @block_self_unknown == true
 
-      rebuild(opaque_block_self: true)
+      rebuild(opaque_block_self: true, block_self_unknown: true)
     end
 
     # True when this scope sits inside a block whose `self` is unmodelled ({#entering_opaque_block}).
     def opaque_block_self? = @opaque_block_self
 
+    # Issue #1717 — true when this scope sits in a block whose `self` the engine does not know, so an explicit
+    # `self.m` there is no evidence `m` is missing: the yielding method may `instance_exec` the block on another
+    # object. Read ONLY by `call.undefined-method`'s explicit-`self` exemption, and kept apart from
+    # {#opaque_block_self?} so that mark's reach (the top-level-def bind gate) is untouched. Set with
+    # {#entering_opaque_block} on the evaluator's block entries and by the indexer's walk of an unentered block
+    # ({#with_block_self_unknown}); cleared where a block's `self` is narrowed ({#with_block_self_type}) and, on
+    # the indexer's walk, at a `def` / `class` / `module` body, which the evaluator starts from a fresh scope.
+    def block_self_unknown? = @block_self_unknown ? true : false
+
+    # Issue #1759 — the {#block_self_unknown?} value a `refine X do … end` block body is entered with
+    # (`with_block_self_type(Singleton[X], keeps_unknown: REFINEMENT_BLOCK_SELF)`). It reads as unknown everywhere
+    # `true` does; what it adds is that the body's lexical `self` is X's singleton, which a `define_method` in it
+    # reads correctly ({#block_self_narrowing_unknown?}). A block nested in the body takes plain `true`.
+    REFINEMENT_BLOCK_SELF = :refinement
+
+    # Issue #1763 — true directly in a `refine X do … end` block body ({REFINEMENT_BLOCK_SELF}). The body's
+    # `self_type` is the `Singleton[X]` its implicit-self calls and `define_method` read, but the block runs on the
+    # refinement module, so a `self` read as a value (`x = self`) types as `Dynamic[top]` there.
+    def refinement_block_self? = @block_self_unknown == REFINEMENT_BLOCK_SELF
+
+    # The join of two arms' {#block_self_unknown?} values: `true` if either has it, else either's mark.
+    def merged_block_self_unknown(other)
+      return true if @block_self_unknown == true || other == true
+
+      @block_self_unknown || other
+    end
+    private :merged_block_self_unknown
+
+    # Issue #1717 — sets {#block_self_unknown?} to `flag`, leaving every other field (the #316 mark included).
+    def with_block_self_unknown(flag)
+      return self if @block_self_unknown == flag
+
+      rebuild(block_self_unknown: flag)
+    end
+
     # Issue #963 — marks the body of a `class << ...` as such. Inside it `self` is the SINGLETON class, which
     # Rigor models with the same `Singleton[X]` carrier a `class X` body gets, so the carrier alone cannot say
     # which of the two a scope came from. The distinction decides what `define_method` does: in a `class << self`
@@ -544,6 +650,19 @@ module Rigor
       rebuild(singleton_class_body: flag)
     end
 
+    # Issue #1667 (ADR-121 WD5) — this scope with `names` appended to {#declared_refinements}, each once at its first
+    # position: the modules a plugin-declared refined block (`block_as_methods:` `refinements:`) runs under. Stamped
+    # at block entry and inherited by every scope derived inside the body, nested blocks included, and by a `def` or
+    # class body written in it (`StatementEvaluator#build_fresh_body_scope`), as CRuby's cref is.
+    def with_declared_refinements(names)
+      return self if names.empty?
+
+      merged = (@declared_refinements | names).freeze
+      return self if merged == @declared_refinements
+
+      rebuild(declared_refinements: merged)
+    end
+
     # True when this scope IS a `class << ...` body (not merely inside one lexically — a `def` reached from it
     # answers false).
     def singleton_class_body? = @singleton_class_body
@@ -600,6 +719,45 @@ module Rigor
     end
     private :bind_ivar
 
+    # Issue #1695 — this scope with no instance-variable binding and none of the per-ivar state that rides on one:
+    # the narrowings keyed on or rooted at an ivar, its ADR-58 and #667 marks, ADR-82 origins, #286 optimistic marks
+    # and #1446 guard records, the state {#bind_ivar} drops for one name. It installs {#with_block_self_type}'s
+    # `self_type` and unknown-`self` mark in the same rebuild.
+    def without_ivar_bindings(self_type, block_self_unknown)
+      rebuild(
+        self_type: self_type,
+        block_self_unknown: block_self_unknown,
+        ivars: EMPTY_VAR_BINDINGS,
+        indexed_narrowings: reject_kept(@indexed_narrowings) { |k, _| ivar_indexed_key?(k) },
+        method_chain_narrowings: reject_kept(@method_chain_narrowings) { |k, _| k.receiver_kind == :ivar },
+        declaration_sourced: reject_kept(@declaration_sourced) { |ref| ref[0] == :ivar },
+        published_constant_sourced: reject_kept(@published_constant_sourced) { |ref| ref[0] == :ivar },
+        ivar_origins: EMPTY_ORIGINS,
+        optimistic_ivars: EMPTY_ORIGINS,
+        guard_records: reject_kept(@guard_records) { |key, _| key[0] == :ivar },
+        bot_guard_classes: reject_kept(@bot_guard_classes) { |key, _| key[0] == :ivar }
+      )
+    end
+    private :without_ivar_bindings
+
+    # `collection` without the entries the block selects, or `collection` itself when it selects none. It keeps the
+    # collection's class: `Set#reject` answers an Array, which a Set carrier's readers (`merge`, `|`, `==`) reject.
+    def reject_kept(collection, &)
+      return collection if collection.empty? || collection.none?(&)
+
+      collection.dup.delete_if(&).freeze
+    end
+    private :reject_kept
+
+    # An indexed narrowing of an ivar, or of a `key?` guard's key read from one ({#key_guard_rooted_at?}).
+    def ivar_indexed_key?(indexed_key)
+      return true if indexed_key.receiver_kind == :ivar
+
+      key = indexed_key.key
+      key.is_a?(Inference::KeyPresenceGuard::KeyExpr) && key.root[0] == :ivar
+    end
+    private :ivar_indexed_key?
+
     # 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.
     def seed_declaration_sourced_ivar(name, type)
@@ -904,20 +1062,22 @@ module Rigor
       @repeated_or_writes.key?(node)
     end
 
-    # Regex match-data globals (`$~`, `$&`, `$1..$9`, the pre/post-match and last-paren back-references). Narrowed
+    # Regex match-data globals (`$~`, `$&`, `$1..$N`, the pre/post-match and last-paren back-references). Narrowed
     # on a successful-`=~` / `case`-`when` match edge (see `Narrowing#regex_match_predicate_scopes`). They live in
     # the method frame's special-variable slot, which the method's blocks and closures share (issue #1358), so a
     # later call that may run a match in this frame — a match-capable call, a block that may match, a call once
     # the frame has made a closure that may — rebinds every one of them, and `eval_call` forgets the narrowed
     # facts here. Always safe — only drops facts, so a subsequent read falls back to the default `String | nil`.
     # Program-level `$GLOBAL = ...` seeds use other names and are untouched.
-    MATCH_DATA_GLOBALS = %i[$~ $& $` $' $+ $1 $2 $3 $4 $5 $6 $7 $8 $9].freeze
-    private_constant :MATCH_DATA_GLOBALS
+    # Issue #1384 — the numbered groups are matched by name, not listed: a regex may carry more than nine captures, and
+    # `$10` and above are the same slot as `$1`..`$9`, so forgetting must clear them too.
+    MATCH_DATA_GLOBAL_NAME = /\A\$(?:~|&|`|'|\+|[1-9]\d*)\z/
+    private_constant :MATCH_DATA_GLOBAL_NAME
 
     def forget_match_globals
       return self unless match_globals_bound?
 
-      rebuild(globals: @globals.except(*MATCH_DATA_GLOBALS).freeze)
+      rebuild(globals: @globals.reject { |name, _| MATCH_DATA_GLOBAL_NAME.match?(name.name) }.freeze)
     end
 
     # Issue #1361 — this scope with every bound match-data global rebound to `Dynamic[top]`, and an unbound one left
@@ -928,14 +1088,16 @@ module Rigor
       return self unless match_globals_bound?
 
       untyped = Type::Combinator.untyped
-      rebound = MATCH_DATA_GLOBALS.each_with_object({}) { |name, acc| acc[name] = untyped if @globals.key?(name) }
+      rebound = @globals.each_with_object({}) do |(name, _), acc|
+        acc[name] = untyped if MATCH_DATA_GLOBAL_NAME.match?(name.name)
+      end
       rebuild(globals: @globals.merge(rebound).freeze)
     end
 
     # True when any match-data global holds a binding, which a match edge or {#untyped_match_globals} makes: the only
     # state {#forget_match_globals} can drop, and so the gate on every scan that decides whether to.
     def match_globals_bound?
-      !@globals.empty? && MATCH_DATA_GLOBALS.any? { |name| @globals.key?(name) }
+      !@globals.empty? && @globals.any? { |name, _| MATCH_DATA_GLOBAL_NAME.match?(name.name) }
     end
 
     # Issue #1359 — the last line read, `$_`, lives in the same frame slot as the match globals, and so on the same
@@ -1954,6 +2116,7 @@ module Rigor
       source_path: @source_path,
       struct_fold_safe_locals: @struct_fold_safe_locals,
       opaque_block_self: @opaque_block_self,
+      block_self_unknown: @block_self_unknown,
       singleton_class_body: @singleton_class_body,
       lexical_nesting: @lexical_nesting,
       dynamic_origins: @dynamic_origins,
@@ -1968,7 +2131,8 @@ module Rigor
       match_frame: @match_frame,
       constant_narrowings: @constant_narrowings,
       guard_records: @guard_records,
-      bot_guard_classes: @bot_guard_classes
+      bot_guard_classes: @bot_guard_classes,
+      declared_refinements: @declared_refinements
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -1982,6 +2146,7 @@ module Rigor
         source_path: source_path,
         struct_fold_safe_locals: struct_fold_safe_locals,
         opaque_block_self: opaque_block_self,
+        block_self_unknown: block_self_unknown,
         singleton_class_body: singleton_class_body,
         lexical_nesting: lexical_nesting,
         dynamic_origins: dynamic_origins,
@@ -1996,7 +2161,8 @@ module Rigor
         match_frame: match_frame,
         constant_narrowings: constant_narrowings,
         guard_records: guard_records,
-        bot_guard_classes: bot_guard_classes
+        bot_guard_classes: bot_guard_classes,
+        declared_refinements: declared_refinements
       )
     end
 
@@ -2014,7 +2180,8 @@ module Rigor
       result.freeze
     end
 
-    def build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other)
+    # One keyword per Scope field, each with its join rule beside it; the size is the field count.
+    def build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       self.class.new(
         environment: @environment,
         locals: joined_locals.freeze,
@@ -2062,6 +2229,9 @@ module Rigor
         # block entry by `entering_opaque_block` and inherited through `rebuild`), so both arms usually carry
         # the same value and the `||` is that value.
         opaque_block_self: @opaque_block_self || other.opaque_block_self,
+        # Issue #1717 — the same body property, and `||` keeps the exemption it grants (the FP-safe side).
+        # A plain `true` outranks the refine body's {REFINEMENT_BLOCK_SELF} for the same reason.
+        block_self_unknown: merged_block_self_unknown(other.block_self_unknown),
         # Issue #963 — a body property like the two above, so both arms of an in-body merge carry the identical
         # value and the `||` is that value. `||` is also the safe direction on its own terms: keeping the mark
         # declines the `define_method` narrowing, which is the pre-#963 answer.
@@ -2086,12 +2256,24 @@ module Rigor
         # of a merge inside one body carry the same one; `||` keeps it should either arm lack it, since dropping
         # it only loses the frame's resets.
         match_frame: @match_frame || other.match_frame,
+        # Issue #1667 — a body property stamped at block entry like the frame above, so both arms of a merge carry
+        # the same list; the union keeps either arm's modules, the declining direction.
+        declared_refinements: join_declared_refinements(other),
         # Issue #1429 — the guard narrowings of globals and constants and their pre-guard records, and of instance
         # variables (#1446).
         **join_guard_narrowings(other, joined_globals, joined_ivars)
       )
     end
 
+    def join_declared_refinements(other)
+      mine = @declared_refinements
+      theirs = other.declared_refinements
+      return mine if theirs.equal?(mine) || theirs.empty?
+      return theirs if mine.empty?
+
+      (mine | theirs).freeze
+    end
+
     def join_guard_narrowings(other, joined_globals, joined_ivars)
       joined_constants = join_constant_narrowings(other)
       joined = { global: joined_globals, ivar: joined_ivars, constant: joined_constants }
@@ -2246,11 +2428,19 @@ module Rigor
       sym_kind = receiver_kind.to_sym
       sym_name = receiver_name.to_sym
       filtered = @indexed_narrowings.reject do |k, _|
-        k.receiver_kind == sym_kind && k.receiver_name == sym_name
+        (k.receiver_kind == sym_kind && k.receiver_name == sym_name) || key_guard_rooted_at?(k.key, sym_kind, sym_name)
       end
       filtered.size == @indexed_narrowings.size ? @indexed_narrowings : filtered.freeze
     end
 
+    # Issue #1703 — whether `key` is a `key?` guard's key that is the variable `kind`/`name`, or a chain read from it.
+    def key_guard_rooted_at?(key, kind, name)
+      return false unless key.is_a?(Inference::KeyPresenceGuard::KeyExpr)
+
+      root = key.root
+      root[0] == kind && root[1] == name
+    end
+
     # ADR-58 WD1 — set/clear the declaration-sourced provenance mark.
     # Issue #667 — the #667 carrier's add/drop pair. Deliberately not reusing
     # {#add_declaration_sourced} / {#drop_declaration_sourced_for}: the two sets are joined by opposite

data/lib/rigor/sig_gen/classification.rb

@@ -57,7 +57,10 @@ module Rigor
         inline_generic_class: "sig.skipped.inline-generic-class",
         # ADR-112 WD4 — the member is declared inline and in `sig/`, and the two disagree. A refusal, not a
         # skip: `--write` and `--check` exit 1 until a person reconciles them or passes `--overwrite`.
-        inline_differs: "sig.skipped.inline-differs"
+        inline_differs: "sig.skipped.inline-differs",
+        # #1676 — a plain top-level `def` defines a private `Object` method and has no class to write a
+        # declaration under, so it is reported rather than silently dropped. Whether to emit it stays open.
+        top_level_def: "sig.skipped.top-level-def"
       }.freeze
     end
   end

data/lib/rigor/sig_gen/generator.rb

@@ -57,7 +57,8 @@ module Rigor
     #   a parameter-only inline `# @rbs` annotation) is the ABSENCE of a return statement, not the author's
     #   word about it — the opposite of `void`. It is treated like no declaration at all: the inferred return
     #   is proposed as `tighter-return`, carrying `untyped` as the declared spelling so `--diff` still shows a
-    #   declaration existed (#995; see {#declared_untyped?}).
+    #   declaration existed (#995; see {#declared_untyped?}). A value literal the body proves (Integer, String,
+    #   Symbol) is widened to its class there unless the `untyped` is only the inline reader's synthesis (#1489).
     # - A `tighter-return` over the class's own declaration replaces the return and nothing else: the rest of
     #   the line is the declaration's, spelled as written, so `--overwrite` never changes which calls the
     #   signature accepts. A declaration with more than one overload, or one spelled as an `alias`, is left
@@ -100,6 +101,9 @@ module Rigor
         @class_shells = Set.new
         @class_superclasses = {}
         @meta_layouts = {}
+        # Issue #1763 — the walked file's tree, and its refine-call query, built only when a `refine` call is walked.
+        @walk_root = nil
+        @in_effect_refinements = nil
         # Whole-run, NOT per-file: a rendering defect is reported once at the end of the run.
         @unrenderable = []
         # Issue #735 — whole-run too: `{ class name => the superclass token that resolves nowhere }`.
@@ -475,7 +479,7 @@ module Rigor
           # `rigor sig-gen` run. The `check` path recovers each *file* this way (worker_session.rb); sig-gen
           # recovers per-def so the rest of the file's candidates still emit.
 
-          classify_def(path, def_node, class_name, kind, scope_index)
+          classify_collected_def(path, def_node, class_name, kind, scope_index)
         rescue StandardError
           nil
         end
@@ -486,8 +490,9 @@ module Rigor
 
       # Walks the AST collecting `(def_node, class_name, kind)` tuples for every `def` Rigor can re-type. Slice 1
       # covered instance `def foo` methods inside a nameable `class` / `module` body. Slice 4 extends this to
-      # singleton-side methods via `def self.foo` and `class << self; def foo; end`; top-level / DSL-block defs
-      # still degrade silently (no nameable receiver).
+      # singleton-side methods via `def self.foo` and `class << self; def foo; end`. A plain top-level `def` is
+      # collected with a nil class and reported as skipped (#1676); DSL-block defs still degrade silently (no
+      # nameable receiver).
       #
       # ADR-14 gap-#3 follow-up tracks two extra pieces during the same walk so the Writer can emit kind-correct
       # RBS without guessing:
@@ -500,7 +505,10 @@ module Rigor
       #   RBS spelling that matches the dual instance + singleton dispatch the runtime produces.
       def collect_method_definitions(root, scope_index)
         @declared_types = scope_index[root].declared_types
+        @walk_root = root
+        @in_effect_refinements = nil
         out = []
+        @block_depth = 0
         walk_defs(root, [], false, false, out)
         out
       end
@@ -530,9 +538,22 @@ module Rigor
           return
         end
 
+        walk_def_children(node, prefix, in_singleton_class, module_function_active, out)
+      end
+
+      # #1676 — a block body is a DSL scope, not the file's top level, so a `def` inside one is not reported
+      # as a top-level def. Neither is a `def` in `class << obj` (a non-`self` singleton body reaches here,
+      # the `self` one returns above): it defines a singleton method on `obj`, not a private `Object` method.
+      def walk_def_children(node, prefix, in_singleton_class, module_function_active, out)
+        return if refine_block_call?(node)
+
+        in_block = node.is_a?(Prism::BlockNode) || node.is_a?(Prism::LambdaNode) ||
+                   node.is_a?(Prism::SingletonClassNode)
+        @block_depth += 1 if in_block
         node.rigor_each_child do |child|
           walk_defs(child, prefix, in_singleton_class, module_function_active, out)
         end
+        @block_depth -= 1 if in_block
       end
 
       # [#722](https://github.com/rigortype/rigor/issues/722) residue 3 — the qualified name is built by
@@ -559,6 +580,20 @@ module Rigor
         true
       end
 
+      # Issue #1763 — a `def` (or an `attr_*`) in a `refine X do … end` block defines a method of the refinement
+      # module, not of the namespace the block is written in, and RBS has no declaration for a refinement, so both
+      # walks skip the whole block: writing `def shout: () -> String` under the enclosing module declared a method
+      # that module does not have. Statement and value position alike, since the walks descend every child. The
+      # skip is silent, as for a top-level `def`: a `sig.skipped.*` row would name the enclosing class, the very
+      # misattribution this avoids. A `refine` call the engine reads as a class's own method (`Class` undefines
+      # `refine`, #1689) walks as any other block, as the engine treats it.
+      def refine_block_call?(node)
+        return false unless node.is_a?(Prism::CallNode) && Inference::ScopeIndexer.refine_call?(node)
+
+        @in_effect_refinements ||= Inference::InEffectRefinements.new(@walk_root)
+        !@in_effect_refinements.class_body_refine?(node)
+      end
+
       def declined_self_header?(node)
         path = node.constant_path
         path.is_a?(Prism::ConstantPathNode) && path.parent.is_a?(Prism::SelfNode) &&
@@ -661,7 +696,8 @@ module Rigor
         return nil unless node.value.is_a?(Prism::CallNode)
         return nil unless @meta_layouts.key?((prefix + [node.name.to_s]).join("::"))
 
-        node.value.block&.body
+        block = node.value.block
+        block.body if block.is_a?(Prism::BlockNode)
       end
 
       # Module / class bodies are walked through the `walk_statements` path so `module_function` (no-args)
@@ -684,7 +720,13 @@ module Rigor
       end
 
       def collect_def_node(node, prefix, in_singleton_class, module_function_active, out)
-        return if prefix.empty?
+        if prefix.empty?
+          # #1676 — a plain top-level `def` defines a private `Object` method. It is surfaced as a skipped
+          # candidate (no class to write it under) rather than dropped; `def self.x` and block-body defs stay
+          # unreported.
+          out << [node, nil, :instance] if node.receiver.nil? && !in_singleton_class && @block_depth.zero?
+          return
+        end
 
         kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
         class_name = prefix.join("::")
@@ -915,6 +957,13 @@ module Rigor
         end
       end
 
+      # #1676 — a top-level `def` is collected with no class; it is reported, never typed.
+      def classify_collected_def(path, def_node, class_name, kind, scope_index)
+        return skipped(path, def_node, class_name, kind, :top_level_def) if class_name.nil?
+
+        classify_def(path, def_node, class_name, kind, scope_index)
+      end
+
       def classify_def(path, def_node, class_name, kind, scope_index)
         return nil if visibility_excludes?(def_node, class_name, kind, scope_index)
         return nil if initialize_excludes?(def_node, kind)
@@ -1368,14 +1417,53 @@ module Rigor
         declared.is_a?(Type::Dynamic)
       end
 
-      # Proposed without {#compare_against_declared}'s tightening guards: a declared `untyped` return carries no
-      # information to weigh {#tighter?} or {#literal_decline?} against, the same position a method with no
-      # declaration at all is in. The line is built as for any tightening ({#tighter_return_line}), and
-      # `declared_return_rbs` carries `"untyped"` so the `[tighter, was: untyped]` print tag says one existed.
+      # Proposed without {#tighter?}: a declared `untyped` return carries no information to weigh it against, the
+      # same position a method with no declaration at all is in. Over a declaration the author wrote, though, a
+      # VALUE literal the body proves (`-> 1`, `-> "x"`, `-> :k`) is an implementation detail the `untyped` was
+      # abstracting over, so it is widened to its class (`1 | 2` to `Integer`, `"S" | nil` to `(String | nil)`; #1489).
+      # `nil`, `true` and `false` are honest types and stay, as does a computed `Float`. An `untyped` that is only
+      # the inline reader's synthesis ({#synthesized_declaration?}) is no word of the author's and keeps the
+      # strictest carrier. `declared_return_rbs` carries `"untyped"` so the `[tighter, was: untyped]` print tag
+      # says a declaration existed.
       def declared_untyped_candidate(path, def_node, class_name, kind, inferred, method_def, rendered: nil)
+        unless synthesized_declaration?(method_def)
+          widened = widen_value_literals(inferred)
+          unless widened.equal?(inferred)
+            # A `rendered` line was spelled from the unwidened type; there is nothing to rebuild it from.
+            return equivalent(path, def_node, class_name, kind, inferred, "untyped") if rendered
+
+            inferred = widened
+          end
+        end
+
         tighter_return_candidate(path, def_node, class_name, kind, inferred, method_def, "untyped", rendered)
       end
 
+      VALUE_LITERAL_CLASSES = [Integer, String, Symbol].freeze
+      private_constant :VALUE_LITERAL_CLASSES
+
+      # The same object back when nothing needed widening.
+      def widen_value_literals(type)
+        case type
+        when Type::Constant
+          return type unless VALUE_LITERAL_CLASSES.any? { |klass| type.value.instance_of?(klass) }
+
+          Type::Combinator.nominal_of(type.value.class.name)
+        when Type::Union
+          members = type.members.map { |member| widen_value_literals(member) }
+          members.each_with_index.all? { |m, i| m.equal?(type.members[i]) } ? type : Type::Combinator.union(*members)
+        else
+          type
+        end
+      end
+
+      # A declaration only the inline reader's synthesis (a `virtual:` buffer) supplies — ADR-93 gives every `def` an
+      # `untyped` member, annotated or not — is no word of the author's about the return, so it keeps the proposal
+      # a method with no declaration at all gets: the strictest carrier the body proves.
+      def synthesized_declaration?(method_def)
+        method_def.defs.all? { |type_def| type_def.member.location&.buffer&.name.to_s.start_with?("virtual:") }
+      end
+
       def build_declared_return(method_def)
         translated = method_def.method_types.filter_map { |mt| translate_method_type_return(mt) }
         return nil if translated.empty?
@@ -1712,6 +1800,8 @@ module Rigor
             return
           end
         when Prism::CallNode
+          return if refine_block_call?(node)
+
           collect_attr_call(node, prefix, in_singleton_class, ctx)
         end
 

data/lib/rigor/sig_gen/method_candidate.rb

@@ -11,8 +11,8 @@ module Rigor
     # applicable to that classification.
     #
     # - `path` — the source `.rb` file the def came from.
-    # - `class_name` — qualified receiver class name (e.g. `"Foo::Bar"`). `nil` for top-level / DSL-block defs
-    #   the MVP skips.
+    # - `class_name` — qualified receiver class name (e.g. `"Foo::Bar"`). `nil` for a top-level `def`, which is only
+    #   ever `skipped` (`sig.skipped.top-level-def`, #1676).
     # - `method_name` — the def's `Symbol` name.
     # - `kind` — `:instance` or `:singleton`.
     # - `inferred_return` — `Rigor::Type` instance (or `nil` when the inference pass disqualified the def).