rigortype 0.3.5 → 0.3.7

data/lib/rigor/scope.rb

@@ -16,16 +16,16 @@ module Rigor
   # #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
+  # rubocop:disable-next Metrics/ClassLength,Metrics/ParameterLists
   class Scope
     attr_reader :environment, :locals, :fact_store, :self_type,
                 :ivars, :cvars, :globals,
                 :indexed_narrowings, :method_chain_narrowings,
                 :declaration_sourced,
                 :source_path, :discovery, :struct_fold_safe_locals,
-                :opaque_block_self,
+                :opaque_block_self, :lexical_nesting,
                 :dynamic_origins, :local_origins, :ivar_origins,
-                :void_origins,
+                :void_origins, :plugin_typed_calls,
                 :optimistic_origins, :optimistic_locals, :optimistic_ivars
 
     # ADR-53 Track A — the seed-time discovery tables live on the {DiscoveryIndex} the scope carries by a single
@@ -50,6 +50,50 @@ module Rigor
     def discovered_superclasses = @discovery.discovered_superclasses
     def discovered_includes = @discovery.discovered_includes
     def discovered_class_sources = @discovery.discovered_class_sources
+    # Issue #644 — `{qualified constant name => Set[declaring file]}`; seeded only on an ADR-46 recording run.
+    def constant_sources = @discovery.constant_sources
+    def published_constant_names = @discovery.published_constant_names
+    def local_constant_names = @discovery.local_constant_names
+
+    # Issue #644 — true when the constant reference `name` (as written: `MODE` or `AppConfig::MODE`) is
+    # published by the cross-file value-constant table and is NOT assigned by the file being analysed: a
+    # value this file's author cannot see the declaration of. {Analysis::CheckRules::PublishedConstantGuard}
+    # is the only caller — a rule MUST ask through the guard rather than re-derive the question here, exactly
+    # as ADR-58's mark is asked through `DeclarationSourcedGuard`.
+    #
+    # The two halves match at deliberately different granularities, because the two errors are not
+    # symmetric. The PUBLISHED half matches on the last segment and so over-answers (a reader of a nested
+    # `MyApp::MODE` answers true for a top-level `MODE`) — over-answering only ever WITHHOLDS a firing, the
+    # safe direction, and it is the grammar the ADR-46 negative keys already use. The LOCAL half is an
+    # exemption, so over-answering there would UN-withhold: matching it on the last segment too would let an
+    # unrelated `Local::MODE` in this file make a read of `AppConfig::MODE` fire.
+    #
+    # The exemption therefore matches a **suffix relation on qualified names**, not the spelling and not the
+    # last segment: a local assignment exempts a reference when it IS that reference or ENDS with `::` plus
+    # it. That is what a lexically relative spelling resolves to — inside `module AppConfig`, the reference
+    # `Nested::X` is the file's own `AppConfig::Nested::X` — and it subsumes the bare case (`OWNED` matched
+    # by `Owner::OWNED`) without matching the unrelated `Local::MODE` above. It is deliberately a relation
+    # over already-qualified names rather than a second lexical ladder: the engine's ladder
+    # (`Reflection.resolve_constant_type`) answers with a TYPE and not with the candidate that won, and
+    # reimplementing the walk here is the very thing that made the receiver resolution wrong once already.
+    def published_constant?(name)
+      names = @discovery.published_constant_names
+      return false if names.empty?
+      return false unless names.include?(name.split("::").last)
+
+      !locally_declared_constant?(name)
+    end
+
+    def locally_declared_constant?(reference_name)
+      local = @discovery.local_constant_names
+      return false if local.empty?
+      return true if local.include?(reference_name)
+
+      suffix = "::#{reference_name}"
+      local.any? { |name| name.end_with?(suffix) }
+    end
+    private :locally_declared_constant?
+
     def data_member_layouts = @discovery.data_member_layouts
     def struct_member_layouts = @discovery.struct_member_layouts
     # ADR-67 WD3 — call-site-inferred parameter types, keyed by `[class_name, method_name, kind]`.
@@ -135,6 +179,23 @@ module Rigor
       self
     end
 
+    # Issue #653 — records that a plugin's `dynamic_return` answered the return type for `node`, i.e. that
+    # `MethodDispatcher`'s plugin tier (which sits ABOVE `RbsDispatch`) is where the site's type came from.
+    # `Analysis::CheckRules` consults it so `call.undefined-method` does not then read the receiver's RBS to
+    # prove the same call undefined: the engine already decided the plugin outranks the signature here, and a
+    # partially-declared receiver is not a closed world (ADR-5). Mirrors {#record_void_origin} exactly —
+    # identity-keyed advisory metadata on a table threaded by reference through `#join` / `#rebuild`,
+    # excluded from `==` / `hash`, so it never forks a flow-dedup or cache key.
+    def record_plugin_typed_call(node)
+      @plugin_typed_calls[node] = true
+      self
+    end
+
+    # Issue #653 — whether a plugin answered the return type for `node` on this run.
+    def plugin_typed_call?(node)
+      @plugin_typed_calls.key?(node)
+    end
+
     def initialize(
       environment:, locals:,
       fact_store: Analysis::FactStore.empty,
@@ -149,10 +210,12 @@ module Rigor
       source_path: nil,
       struct_fold_safe_locals: EMPTY_FOLD_SAFE,
       opaque_block_self: false,
+      lexical_nesting: nil,
       dynamic_origins: {}.compare_by_identity,
       local_origins: EMPTY_ORIGINS,
       ivar_origins: EMPTY_ORIGINS,
       void_origins: {}.compare_by_identity,
+      plugin_typed_calls: {}.compare_by_identity,
       optimistic_origins: {}.compare_by_identity,
       optimistic_locals: EMPTY_ORIGINS,
       optimistic_ivars: EMPTY_ORIGINS
@@ -171,10 +234,12 @@ module Rigor
       @source_path = source_path
       @struct_fold_safe_locals = struct_fold_safe_locals
       @opaque_block_self = opaque_block_self
+      @lexical_nesting = lexical_nesting
       @dynamic_origins = dynamic_origins
       @local_origins = local_origins
       @ivar_origins = ivar_origins
       @void_origins = void_origins
+      @plugin_typed_calls = plugin_typed_calls
       @optimistic_origins = optimistic_origins
       @optimistic_locals = optimistic_locals
       @optimistic_ivars = optimistic_ivars
@@ -264,6 +329,29 @@ module Rigor
       rebuild(self_type: type)
     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
+    # qualified name cannot be un-flattened back into the chain that produced it, so the chain has to travel
+    # with the scope; `Reflection.lexical_nesting_chain` is the single reader.
+    #
+    # The value is THREE-valued, and issue #716 is what the third state is for:
+    #
+    # - a non-empty chain — the body's real `Module.nesting`, recorded at declaration time;
+    # - `[]` — recorded, and the body is written at the TOP LEVEL. Ruby's `Module.nesting` there is empty,
+    #   so a top-level `def helper = Post.new` names `::Post` no matter which namespace calls it.
+    #   `Reflection.resolve_constant_type` consults the top level FIRST for such a scope and only then the
+    #   caller-derived rungs, instead of letting the caller's namespace answer;
+    # - `nil` — NOT recorded, for a scope built outside a declaration walk (a callee body re-entered through
+    #   `Scope#evaluate`, a plugin-constructed scope). The reader then peels `self_type`'s class name — a
+    #   gradual answer, never a new firing.
+    #
+    # Collapsing `[]` into `nil` is precisely the bug #716 fixed, so a writer that has an empty chain must
+    # pass it rather than skip the stamp.
+    def with_lexical_nesting(chain)
+      rebuild(lexical_nesting: chain)
+    end
+
     # 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.
@@ -602,6 +690,15 @@ module Rigor
       site
     end
 
+    # Issue #735 — the singleton-side mirror of {#user_def_site_for}: the `"path:line"` where the project
+    # defines `class_name.method_name`, or nil. Records the same cross-file edge, keyed `"Class.method"`.
+    def user_singleton_def_site_for(class_name, method_name)
+      table = @discovery.discovered_singleton_def_sources[class_name.to_s]
+      site = table && table[method_name.to_sym]
+      record_cross_file_method(class_name, method_name, site, singleton: true) if Analysis::DependencyRecorder.active?
+      site
+    end
+
     # 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
@@ -647,6 +744,223 @@ module Rigor
       @discovery.discovered_includes[class_name.to_s] || []
     end
 
+    # ADR-24 slice 2 — the user-side ancestor walk: resolves `method_name` against `class_name`'s own `def`s,
+    # then breadth-first through its included / prepended modules (mixins first, as Ruby orders them) and its
+    # superclass chain. Returns `[def_node, owner]`, or `[nil, nil]` when nothing in the project defines it.
+    # RBS-known / third-party ancestors resolve to no discovered class and end that branch.
+    #
+    # It lives HERE, not in a consumer, because it reads nothing but this scope's frozen discovery index
+    # (`user_def_for` / `includes_of` / `superclass_of` / the `discovered_*` tables) — the same property that
+    # lets `ExpressionTyper` memoise its results run-wide. Two callers depend on that single answer:
+    # `ExpressionTyper#compute_user_def_with_owner`, which wraps it in the run-scoped memo for the dispatch hot
+    # path, and {Inference::MethodDispatcher::StructMaterialization}, whose `.with` guard must see a `with`
+    # contributed by an included module. They forked once — the guard resolved own-class-only while the
+    # dispatcher walked ancestors — and answered differently about the same receiver expression (#598 review).
+    #
+    # `name_memo` is a CACHE, not semantics: the per-edge as-written-name resolutions, so a caller resolving
+    # many methods against one class pays each ancestor edge once. Omit it and the walk is identical, just
+    # uncached.
+    def user_def_through_ancestors(class_name, method_name, name_memo: {})
+      queue = [class_name.to_s]
+      seen = {}
+      visited = 0
+      until queue.empty?
+        current = queue.shift
+        next if current.nil? || seen[current]
+
+        seen[current] = true
+        visited += 1
+        return ancestor_walk_gave_up if visited > ANCESTOR_WALK_LIMIT
+
+        found = user_def_for(current, method_name)
+        return [found, current] if found
+
+        enqueue_ancestors(current, queue, name_memo)
+      end
+      [nil, nil]
+    end
+
+    # Issue #731 — the singleton-side twin of {#user_def_through_ancestors}: resolves `method_name` against
+    # `class_name`'s own `def self.` / `class << self` bodies, then up the SUPERCLASS chain. Returns
+    # `[def_node, owner]`, or `[nil, nil]`.
+    #
+    # Superclasses only, and that is the whole shape of class-method inheritance in Ruby: a subclass
+    # inherits its parent's class methods, while an `include`d module contributes INSTANCE methods and its
+    # own `def self.x` is not callable on the includer. `extend M` needs no walk either — `ScopeIndexer`
+    # folds an extend into the extender's own singleton entries before the table is frozen — so the one
+    # edge this misses is a module's singleton surface reached through some other route, which nothing
+    # resolves today.
+    def singleton_def_through_ancestors(class_name, method_name, name_memo: {})
+      queue = [class_name.to_s]
+      seen = {}
+      visited = 0
+      until queue.empty?
+        current = queue.shift
+        next if current.nil? || seen[current]
+
+        seen[current] = true
+        visited += 1
+        return ancestor_walk_gave_up if visited > ANCESTOR_WALK_LIMIT
+
+        found = singleton_def_for(current, method_name)
+        return [found, current] if found
+
+        enqueue_ancestors(current, queue, name_memo, mixins: false)
+      end
+      [nil, nil]
+    end
+
+    # The BFS node cap; a hierarchy past it gives up rather than walking unboundedly (ADR-41 WD4).
+    ANCESTOR_WALK_LIMIT = 100
+
+    def ancestor_walk_gave_up
+      Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
+      [nil, nil]
+    end
+
+    # Issue #723 — the same ancestor walk as {#user_def_through_ancestors}, asked of the DISCOVERY table
+    # rather than the def-node table: does the project define `method_name` on `class_name` or on any
+    # ancestor the project itself declares? The two tables are not interchangeable —
+    # `discovered_methods` also carries `define_method`, `attr_*` and the whole singleton side, none of
+    # which contributes a `Prism::DefNode` — and the suppression probe shared by the `call.*` check rules
+    # needs the broader one.
+    #
+    # Why it must walk at all: `Analysis::CheckRules#source_declared_method?` asked `discovered_method?`,
+    # which is keyed on the receiver's OWN name, while the typer resolves the same call through this
+    # ancestry. A project class whose `sig/` declares it without its project superclass therefore drew
+    # `call.undefined-method` on a method `dump_type` resolved on the same line of the same run — writing
+    # MORE RBS made the run worse, the incentive #653 removed for plugin-typed calls.
+    #
+    # `kind: :singleton` follows the superclass chain ONLY: a class method is inherited by a subclass, but
+    # an `include`d module contributes instance methods and its own `def self.x` is not callable on the
+    # includer. `extend M` is not lost to that narrowing — `Inference::ScopeIndexer` folds an extend into
+    # the extender's own singleton entries before this table is frozen.
+    def discovered_method_through_ancestors?(class_name, method_name, kind, name_memo: {})
+      return false if class_name.nil?
+
+      queue = [class_name.to_s]
+      seen = {}
+      visited = 0
+      until queue.empty?
+        current = queue.shift
+        next if current.nil? || seen[current]
+
+        seen[current] = true
+        visited += 1
+        # Budget exhaustion is uncertainty, not absence: answering "not declared" here would hand a
+        # `call.undefined-method` a fired verdict it has no evidence for. Suppress and record the hit.
+        if visited > ANCESTOR_WALK_LIMIT
+          Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
+          return true
+        end
+
+        return true if discovered_method?(current, method_name, kind)
+
+        enqueue_ancestors(current, queue, name_memo, mixins: kind != :singleton)
+      end
+      false
+    end
+
+    # Pushes `current`'s direct ancestors onto the BFS queue: included / prepended modules first (Ruby places
+    # mixins nearer than the superclass), then the superclass. Each as-written name is resolved against the
+    # nesting `current`'s declaration header is written in ({#ancestor_name_candidates}); names that resolve
+    # to no project class/module are dropped. `mixins: false` walks the superclass chain alone, for the
+    # singleton-side question where an `include` contributes nothing.
+    def enqueue_ancestors(current, queue, name_memo, mixins: true)
+      if mixins
+        includes_of(current).each do |raw|
+          resolved = resolve_ancestor_class_name(current, raw, name_memo)
+          queue.push(resolved) if resolved
+        end
+      end
+      raw_super = superclass_of(current)
+      return if raw_super.nil?
+
+      resolved_super = resolve_ancestor_class_name(current, raw_super, name_memo)
+      queue.push(resolved_super) if resolved_super
+    end
+
+    # Resolves an ancestor name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) to a project-discovered class,
+    # following Ruby's `Module.nesting` constant lookup from the subclass's declaration HEADER, innermost
+    # first, then bare. nil when no candidate names a discovered user class.
+    def resolve_ancestor_class_name(subclass_qualified, raw_ancestor, name_memo)
+      by_subclass = (name_memo[subclass_qualified] ||= {})
+      return by_subclass[raw_ancestor] if by_subclass.key?(raw_ancestor)
+
+      by_subclass[raw_ancestor] = compute_ancestor_class_name(subclass_qualified, raw_ancestor)
+    end
+    private :ancestor_walk_gave_up, :resolve_ancestor_class_name
+
+    # Issue #682 — the candidate names an ancestor spelled `raw_ancestor` can denote in `subclass_qualified`,
+    # in Ruby's lookup order, most-qualified first and the bare name last. The single owner of the question:
+    # three walks resolved a superclass / include name apiece ({#enqueue_ancestors} for method lookup,
+    # `Reflection.resolve_ancestor_name` for the constant ladder's ancestor rung, and
+    # `Analysis::CheckRules`' override-visibility rule), and each derived the order by PEELING the
+    # subclass's qualified name one `::` segment at a time.
+    #
+    # That peel is the NESTED spelling's answer, given to both spellings. Ruby evaluates a superclass
+    # expression before entering the body, so the cref that governs it is the one the declaration's HEADER
+    # is written in — `Module.nesting` minus the declaration's own entry. For `module Admin; class Widget <
+    # Base` that is `["Admin"]` and the peel agrees; for the compact `class Admin::Widget < Base` written at
+    # the top level it is EMPTY, and the peel searched an `Admin::Base` Ruby never looks at — a wrong class
+    # for the ancestor rung of constant lookup and for method dispatch alike.
+    #
+    # The header nesting is a property of the DECLARATION, not of the reader, so it is read from the
+    # discovery table `Inference::ScopeIndexer` records it in rather than from this scope's own
+    # `#lexical_nesting`. Answering off the reader's chain would be wrong past the first hop of the ancestor
+    # BFS (the chain describes the reader's class, not the ancestor being resolved) and would silently
+    # corrupt the run-scoped ancestor memos in `Inference::ExpressionTyper#class_graph_buckets` and
+    # `Reflection.ancestor_constant_scopes`, both of which key on the class name alone because this walk is
+    # a pure function of the frozen discovery tables.
+    #
+    # The peel survives as the FALLBACK, for a class no declaration walk recorded — a scope seeded without
+    # the table, an anonymous `Class.new` name, a class reached only through RBS. It is the same answer this
+    # walk gave before, so an unrecorded class is unchanged rather than degraded.
+    #
+    # An include / prepend name is written INSIDE the body, so Ruby also tries `<subclass>::<raw>` ahead of
+    # everything here. That rung is deliberately still missing — it was missing from the peel too, and
+    # adding it is a widening this change does not need.
+    def ancestor_name_candidates(subclass_qualified, raw_ancestor)
+      # Issue #722 residue 1 / #637 — a ROOTED ancestor name is anchored at the top level and has no
+      # candidate list: `class Rooted < ::Base` names `::Base` wherever it is written, exactly as
+      # `Source::ConstantPath.declaration_prefix` already re-anchors a rooted HEADER. The marker is the
+      # leading `::` `Inference::ScopeIndexer.recorded_ancestor_name` preserves.
+      raw = raw_ancestor.to_s
+      return [raw.delete_prefix("::")] if raw.start_with?("::")
+
+      recorded = @discovery.discovered_header_nestings[subclass_qualified.to_s]
+      entries = recorded || peeled_header_nesting(subclass_qualified)
+      entries.map { |entry| "#{entry}::#{raw_ancestor}" } << raw_ancestor.to_s
+    end
+
+    # The pre-#682 reading of a qualified class name: every proper prefix of it, innermost first, as if the
+    # class had been declared one `module` keyword per segment.
+    def peeled_header_nesting(subclass_qualified)
+      segments = subclass_qualified.to_s.split("::")
+      (segments.length - 1).downto(1).map { |i| segments[0, i].join("::") }
+    end
+    private :peeled_header_nesting
+
+    def compute_ancestor_class_name(subclass_qualified, raw_ancestor)
+      ancestor_name_candidates(subclass_qualified, raw_ancestor).find { |c| known_user_class?(c) }
+    end
+
+    # Issue #723 — `discovered_methods` is in the list because the other three miss a class whose only
+    # project-side content is CLASS methods: `class Base; def self.build = :built; end` records no instance
+    # def node, no superclass and no include, so the ancestor-name resolver did not recognise `Base` as a
+    # project class at all and every walk through it ended one hop early. The table that answers "the
+    # project defines something here" on both sides is this one.
+    def known_user_class?(name)
+      discovered_superclasses.key?(name) || discovered_def_nodes.key?(name) ||
+        discovered_includes.key?(name) || discovered_methods.key?(name)
+    end
+    # `known_user_class?` is PUBLIC (issue #530): `Inference::ExpressionTyper`'s external-gem ancestry probe
+    # has to ask the same "is this name a project class?" question this walk asks, and answering it with a
+    # narrower predicate (`discovered_classes` alone) would read a project class as having left the project
+    # and attribute its root name to a same-named locked gem — a WRONG provenance label, which is the one
+    # direction ADR-82 forbids.
+    private :ancestor_walk_gave_up, :compute_ancestor_class_name
+
     # Records, for a resolved cross-class ancestry read, every file that declares `class_name` (its declaration /
     # reopening / superclass / include sites). The `discovered_class_sources` table it reads is populated only by
     # the cross-file project pre-pass ({Inference::ScopeIndexer.discovered_def_index_for_paths}) and only when
@@ -660,6 +974,22 @@ module Rigor
     end
     private :record_class_dependency
 
+    # Issue #644 — the positive ADR-46 edge for a cross-file VALUE constant. `Reflection.constant_type_at`
+    # calls this the moment a candidate resolves through `in_source_constants`, so the reader depends on the
+    # file that wrote the constant: editing the literal, or deleting the file, re-checks the reader. Recorded
+    # WITHOUT a symbol (a file-granularity / ancestry edge) because a constant's published value is a
+    # declaration-level fact of the whole file, which is also the granularity
+    # `ScopeIndexer#append_constant_signature` moves the declaration signature at.
+    #
+    # `constant_sources` is seeded only when dependency recording is on, so on every ordinary run the table
+    # is empty and this is one Hash miss; the caller additionally gates on the recorder being active.
+    def record_constant_dependency(name)
+      sites = @discovery.constant_sources[name]
+      return if sites.nil?
+
+      sites.each { |site| Analysis::DependencyRecorder.read_site(site) }
+    end
+
     # 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
@@ -815,10 +1145,12 @@ module Rigor
       source_path: @source_path,
       struct_fold_safe_locals: @struct_fold_safe_locals,
       opaque_block_self: @opaque_block_self,
+      lexical_nesting: @lexical_nesting,
       dynamic_origins: @dynamic_origins,
       local_origins: @local_origins,
       ivar_origins: @ivar_origins,
       void_origins: @void_origins,
+      plugin_typed_calls: @plugin_typed_calls,
       optimistic_origins: @optimistic_origins,
       optimistic_locals: @optimistic_locals,
       optimistic_ivars: @optimistic_ivars
@@ -834,10 +1166,12 @@ module Rigor
         source_path: source_path,
         struct_fold_safe_locals: struct_fold_safe_locals,
         opaque_block_self: opaque_block_self,
+        lexical_nesting: lexical_nesting,
         dynamic_origins: dynamic_origins,
         local_origins: local_origins,
         ivar_origins: ivar_origins,
         void_origins: void_origins,
+        plugin_typed_calls: plugin_typed_calls,
         optimistic_origins: optimistic_origins,
         optimistic_locals: optimistic_locals,
         optimistic_ivars: optimistic_ivars
@@ -875,16 +1209,64 @@ module Rigor
         # flow-live and `possible-nil-receiver` fires as before.
         declaration_sourced: join_declaration_sourced(other),
         source_path: source_path,
+        # Issue #589 — the fold-safe set MUST survive a merge. It was simply absent from this constructor
+        # call, so it fell back to the empty default and every `if` / `while` in a method silently revoked
+        # struct member folding for the whole body after it: `s = S.new("r"); while c; i += 1; end; s.raw`
+        # answered `Dynamic[top]` while the straight-line sibling folded to `"r"`. The carrier was never
+        # the casualty — `s` still reads `S(raw: "r")` at the merge — only the grant that lets a read
+        # consult it, which is why the shape looked like carrier erasure from the outside.
+        #
+        # The set is a property of the method BODY (a static scan over its root, stamped once by
+        # `ScopeIndexer` / `StatementEvaluator` and threaded by `rebuild`), so both arms of a merge
+        # normally carry the identical set and the intersection below is that set. Intersecting rather
+        # than unioning is the FP-safe direction anyway: the grant licenses a FOLD, so retaining one an
+        # arm did not have could fold a stale constant, while dropping one only costs precision.
+        struct_fold_safe_locals: join_struct_fold_safe(other),
+        # Issue #600 — the sibling omission of the same class, and the same failure mode: absent from this
+        # constructor call, the flag fell back to `false`, so ANY merge inside a block re-armed the #316/#319
+        # decline gate. `RSpec.describe do; if c; end; output; end` bound a cross-file top-level `def output`
+        # again after the `if`, which is the wrong-bind direction the gate exists to prevent — the block's real
+        # `self` may have gained a public same-named method by `include`, and that wins the MRO over the
+        # private `Object` def.
+        #
+        # `||`, not `&&`: opacity is the DECLINING state, so keeping it once either arm has it is the FP-safe
+        # merge. Like the fold-safe set this is normally a property of the enclosing block (stamped once at
+        # 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 #652 — the recorded `Module.nesting`, stamped once at body entry and threaded by `rebuild`
+        # exactly as the fold-safe set is. A join is a control-flow merge INSIDE one body, so both arms
+        # always carry the identical chain; taking this scope's is that chain. Dropping it would silently
+        # re-enable the name-peel for everything after the first `if` in a body.
+        lexical_nesting: @lexical_nesting,
         dynamic_origins: @dynamic_origins,
         local_origins: join_origins(@local_origins, other.local_origins),
         ivar_origins: join_origins(@ivar_origins, other.ivar_origins),
         void_origins: @void_origins,
+        plugin_typed_calls: @plugin_typed_calls,
         optimistic_origins: @optimistic_origins,
         optimistic_locals: join_origins(@optimistic_locals, other.optimistic_locals),
         optimistic_ivars: join_origins(@optimistic_ivars, other.optimistic_ivars)
       )
     end
 
+    # Issue #589 — intersect the struct fold-safe grants. Zero-alloc on the common path, where both arms
+    # carry the same frozen set the body scan stamped.
+    # A `nil` on EITHER side yields no grants. The field is keyword-defaulted to `EMPTY_FOLD_SAFE` and
+    # threaded by `rebuild`, so `nil` should be unreachable — but the two sides are deliberately symmetric
+    # rather than one arm trusting the other, because the asymmetric form kept every grant when the OTHER
+    # side was nil, which is the one direction that can fold a stale value.
+    def join_struct_fold_safe(other)
+      mine = @struct_fold_safe_locals
+      theirs = other.struct_fold_safe_locals
+      return EMPTY_FOLD_SAFE if mine.nil? || theirs.nil?
+      return mine if mine.equal?(theirs) || mine == theirs
+      return EMPTY_FOLD_SAFE if mine.empty? || theirs.empty?
+
+      intersected = mine & theirs
+      intersected.empty? ? EMPTY_FOLD_SAFE : intersected.freeze
+    end
+
     # ADR-82 WD1 — merge two branches' propagated origins (self wins on a name conflict; advisory metadata, so
     # a disagreement is harmless). Zero-alloc when either side is empty — the common case, keeping the join
     # hot-path cost negligible.
@@ -986,5 +1368,4 @@ module Rigor
       filtered.size == @method_chain_narrowings.size ? @method_chain_narrowings : filtered.freeze
     end
   end
-  # rubocop:enable Metrics/ClassLength,Metrics/ParameterLists
 end

data/lib/rigor/sig_gen/classification.rb

@@ -16,6 +16,11 @@ module Rigor
       EQUIVALENT = :equivalent
       SKIPPED = :skipped
 
+      # The classifications that actually produce a line in a generated `sig/`. Consulted by the renderer,
+      # the writer and the generator's own post-passes; it lived as a private constant in the first two,
+      # which is one fork too many for a list this load-bearing.
+      EMITTABLE = [NEW_FILE, NEW_METHOD, TIGHTER_RETURN].freeze
+
       DIAGNOSTIC_IDS = {
         NEW_FILE => "sig.generated.new-file",
         NEW_METHOD => "sig.generated.new-method",
@@ -29,7 +34,13 @@ module Rigor
         # The generator rendered a line `rbs` itself rejects. Skipping the method keeps sig-gen useful on a
         # project with one pathological def, where failing the command outright would deny the user every other
         # signature; the count is reported so the defect is not silent. See {SigGen::RbsValidity}.
-        unrenderable_rbs: "sig.skipped.unrenderable-rbs"
+        unrenderable_rbs: "sig.skipped.unrenderable-rbs",
+        # Issue #735 — the class's superclass chain does not terminate in a class the RBS environment knows,
+        # so emitting the declaration would collapse the class on the next run rather than type it.
+        unresolvable_superclass: "sig.skipped.unresolvable-superclass",
+        # Issue #744 — a project subclass overrides this method and its override is NOT emitted, so the
+        # declaration would be inherited by a subclass it does not describe.
+        overridden_by_unsigned_subclass: "sig.skipped.overridden-by-unsigned-subclass"
       }.freeze
     end
   end