rigortype 0.3.9 → 0.4.1

data/lib/rigor/analysis/check_rules/source_arity.rb

@@ -0,0 +1,427 @@
+# frozen_string_literal: true
+
+require_relative "../../reflection"
+require_relative "../../inference/definer_resolution"
+require_relative "../../source/parameter_envelope"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #992 — the positional envelope `call.wrong-arity` may check a call against when no signature
+      # declares the method: the {Source::ParameterEnvelope} the project's own `def` records in
+      # `Scope::DiscoveryIndex#discovered_parameter_envelopes`, and only when nothing the project can see
+      # could make a different definition of that name the one that runs.
+      #
+      # Asked in two stages, because every condition past the first can only WITHHOLD a firing:
+      #
+      # 1. {#owner_envelope} walks the receiver's superclass chain to the first class whose own body, or one of
+      #    whose project mixins, records the name. Every record at that level must agree — deliberately wider
+      #    than Ruby's order, so a mixin whose definition may shadow the class's own, or a load-order-dependent
+      #    pair (#986), declines instead of answering — and none may be opaque. A call that fits this envelope
+      #    is silent, and nothing below is consulted.
+      # 2. {#authoritative?} runs only for a call that would fire. It declines when a `method_missing` /
+      #    `respond_to_missing?` hook or a dynamic-surface mark sits anywhere in the chain; when a mixin the
+      #    project does not declare is not a known RBS module that lacks the name; when a `pre_eval:` patch or
+      #    a plugin's synthetic method names it; when the owner does not make the method public; and when any
+      #    project subclass of the receiver — whose instances the receiver's type admits — records a different
+      #    or opaque envelope for it.
+      #
+      # ADR-119 C1b / C2-c — on both sides stage 1 and the subclass check ask `Inference::DefinerResolution`, and a
+      # chain it declines (`UNKNOWN`) answers no envelope: where Ruby's order depends on a fact the tables cannot
+      # prove, the rule is silent instead of checking the call against master's order (#1570, #1607).
+      #
+      # Deliberately NOT in scope: a constructor reached through `Class#new` (nothing records `initialize` as
+      # `[:singleton, :new]`, so `.new` finds no owner unless the class writes `def self.new` itself); keyword
+      # arity (the envelope's required-keyword flag declines, as `compute_arity_envelope` declines an RBS
+      # function with required keywords); and a `class_eval` whose receiver is not a constant, which the
+      # discovery walk cannot name.
+      class SourceArity # rubocop:disable Metrics/ClassLength
+        MISSING_HOOKS = %i[method_missing respond_to_missing?].freeze
+        private_constant :MISSING_HOOKS
+
+        # One class on the walk: its own name, the project modules its mixins resolve to (transitively through
+        # their own `include`s), and the candidate-name lists of the mixins that resolve to no project module.
+        #
+        # Issue #1570 — the level is a SEGMENT of the receiver's `Scope::ResolutionChain` (`:arity` flavor): the
+        # class with the modules Ruby inserts around it before the superclass's entries begin. Ruby skips an
+        # `include` of a module the superclass chain already carries, so `class C < Base; include M` where
+        # `Base` includes `M` leaves `M` at `Base`'s level; collecting every module a class's own `include`s
+        # name put it at `C`'s level instead, where its `def` answered a call `Base#foo` receives.
+        Level = Data.define(:class_name, :modules, :externals)
+        private_constant :Level
+
+        # ADR-119 C1b — the answer of a level whose records are not one non-opaque envelope. It equals itself in
+        # every world, so two worlds that both reach such a level agree, and no envelope equals it.
+        AMBIGUOUS = Object.new.freeze
+        private_constant :AMBIGUOUS
+
+        # What `Inference::DefinerResolution` reads off a candidate: the answer, the entry that gave it, its
+        # position on the chain and its side. The same four readers as `DefinerResolution::Hit`, which a call site
+        # may not name (the case/in contract spec allows no other reference to the module).
+        ArityHit = Data.define(:answer, :owner, :index, :side)
+        private_constant :ArityHit
+
+        # A subclass level the walk cannot read: `subclasses_agree?` reads the nil as a decline.
+        NO_LEVELS = [nil].freeze
+        private_constant :NO_LEVELS
+
+        def initialize(scope, method_name, kind)
+          @scope = scope
+          @method_name = method_name.to_sym
+          @kind = kind
+          @name_memo = {}
+        end
+
+        # The nearest definition's envelope, or nil when there is none or it is not one shape. Remembers the
+        # levels it walked for {#authoritative?}.
+        #
+        # Its ADR-46 reads are withheld ({Analysis::DependencyRecorder.withhold}) until the caller settles
+        # the verdict with {#settle_by_definitions} or {#settle_by_walk}.
+        def owner_envelope(class_name)
+          @owner_entries = []
+          @ambiguous = false
+          @unknown = false
+          envelope, @withheld = Analysis::DependencyRecorder.withhold { walk_to_owner(class_name) }
+          envelope
+        end
+
+        # True when the nearest level recorded the name but not as one envelope.
+        def ambiguous? = @ambiguous
+
+        # For a silent verdict that only a definition can overturn — the call fits, the owner takes a required
+        # keyword, or nothing on the chain records the name: the owner `def`s themselves (their symbol edges)
+        # and a definition appearing at a level the walk passed over (a name-keyed negative edge). A mixin or
+        # reopening added at the owner's level makes it opaque, and everything {#authoritative?} reads can only
+        # withhold, so none of these needs the file-level class edge the bucket reads would otherwise record.
+        def settle_by_definitions
+          return if @withheld.nil?
+          # ADR-119 C1b — a declined chain (`@unknown`) that some level records the name on is silent only until
+          # another file's edit lifts the decline, so its verdict depends on everything the walk read, as an opaque
+          # level's does. A decline over a name no project level records is not `@unknown` (see
+          # {#decline_unless_recorded_nowhere}): it settles by definitions, as an `ABSENT` read does.
+          return settle_by_walk if @unknown
+
+          @owner_entries.each do |name, kind|
+            if kind == :singleton
+              @scope.user_singleton_def_site_for(name, @method_name)
+            else
+              @scope.user_def_site_for(name, @method_name)
+            end
+          end
+          separator = @kind == :singleton ? "." : "#"
+          @passed.each { |name| Analysis::DependencyRecorder.read_missing(:method, "#{name}#{separator}#{@method_name}") }
+        end
+
+        # For every other verdict — a firing, or an opaque owner level whose opacity another file's edit can
+        # lift — the walk's reads are the dependency, so they are recorded as read.
+        def settle_by_walk
+          Analysis::DependencyRecorder.replay(@withheld) unless @withheld.nil?
+        end
+
+        # Stage 2, for the class {#owner_envelope} last answered.
+        def authoritative?(class_name)
+          !load_order_dependent?(class_name) && !object_extension_may_shadow? &&
+            @levels.all? { |level| clean_level?(level) && public_at?(level.class_name) } &&
+            chain_free_of_hooks?(class_name) &&
+            subclasses_agree?(class_name, @envelope)
+        end
+
+        private
+
+        # ADR-119 C1b / C2-c, #1570 / #1607 — the nearest level is asked of {Inference::DefinerResolution}, on the
+        # receiver's own side: the chain stands only where every candidate level gives one envelope in every
+        # world Ruby may have run (a fork, an unproven mixin order, a `possible`-only definer, and on the
+        # singleton side a hook that could have put a definer ahead). Where it does not, the answer is NO
+        # envelope and `@unknown` — the rule stays silent — instead of master's order, which is what #1570 and
+        # #1607 fired on. The levels the walk keeps for {#authoritative?} are the chain's.
+        def walk_to_owner(class_name)
+          @levels = []
+          @passed = []
+          @recorded = false
+
+          case Inference::DefinerResolution.resolve(@scope, class_name, @method_name, side,
+                                                    question: :arity) { |chain, from| arity_hit(chain, from) }
+          in Inference::DefinerResolution::Known(answer: _answer, owner: _owner) then nearest_envelope(class_name)
+          in Inference::DefinerResolution::ABSENT then nearest_envelope(class_name) # rubocop:disable Lint/DuplicateBranch
+          in Inference::DefinerResolution::UNKNOWN then decline_unless_recorded_nowhere(class_name)
+          end
+        end
+
+        # A declined read of a name no project level records (`arity_hit` found no level that does, in any world it
+        # was asked) answers no envelope whether or not it stands, so the walk's reads are not the verdict's
+        # dependency: only a `def` appearing can change it, which {#settle_by_definitions} files, as for an
+        # `ABSENT` read. It can leave a stale false negative in a warm run, never a firing. Without this, every
+        # `Widget.new` (the implicit `Class` tail may answer it) would replay the whole walk as a file-level
+        # class edge.
+        def decline_unless_recorded_nowhere(class_name)
+          nowhere = !@recorded && !arity_chain(class_name).truncated?
+          nowhere ? nearest_envelope(class_name) : decline
+        end
+
+        # The chain's nearest level's envelope. `Known#answer` is that envelope, but {#authoritative?} and
+        # {#settle_by_definitions} also read the levels, passed names and owner entries this walk fills, so the
+        # answer is not used on its own. Run only once the candidate-set read has answered, so the chain stands
+        # for the name.
+        def nearest_envelope(class_name) = owner_in(chain_levels(arity_chain(class_name)).first)
+
+        def decline
+          @levels = []
+          @passed = []
+          @owner_entries = []
+          @envelope = nil
+          @unknown = true
+          nil
+        end
+
+        # The first level at or after entry position `from` whose records name the method: its envelope (or
+        # {AMBIGUOUS}), the entry that recorded it and that entry's position and side on the chain. On the
+        # singleton side the class's own record is a `:singleton` entry and an extended module's an `:instance`
+        # one (`owner_entries` names the kind of each).
+        def arity_hit(chain, from)
+          start = 0
+          chain.levels.each_with_index do |raw, index|
+            level = Level.new(*raw)
+            entries = chain.level_entries(index)
+            first = start
+            start += entries.size
+            next if first < from
+
+            found = level_envelopes(level)
+            next if found.empty?
+
+            envelope = found.first
+            answer = found.all?(envelope) && !Source::ParameterEnvelope.opaque?(envelope) ? envelope : AMBIGUOUS
+            owner, owner_kind = owner_entries(level).first
+            position = first + (entries.index { |entry| entry.name == owner && entry.side == owner_kind } || 0)
+            @recorded = true
+            return ArityHit.new(answer, owner, position, owner_kind)
+          end
+          nil
+        end
+
+        def owner_in(levels)
+          levels.each do |level|
+            @levels << level
+            found = level_envelopes(level)
+            if found.empty?
+              @passed.concat([level.class_name] + level.modules)
+              next
+            end
+
+            envelope = found.first
+            @owner_entries |= owner_entries(level)
+            unless found.all?(envelope) && !Source::ParameterEnvelope.opaque?(envelope)
+              @ambiguous = true
+              return nil
+            end
+
+            return @envelope = envelope
+          end
+          nil
+        end
+
+        def owner_entries(level)
+          own = @scope.parameter_envelopes_of(level.class_name).key?([@kind, @method_name])
+          entries = own ? [[level.class_name, @kind]] : []
+          level.modules.each do |mod|
+            entries << [mod, :instance] if @scope.parameter_envelopes_of(mod).key?([:instance, @method_name])
+          end
+          entries
+        end
+
+        # The survey corpus's own lesson. `PStore.new(path).transaction { … }` inside `module TDiary::IO`
+        # resolves `PStore` to the project's `TDiary::IO::PStore` when that class's file is loaded, and to the
+        # stdlib `::PStore` when it is not — and tdiary loads it only under one `io_class` setting, so under
+        # the default one the call is correct code. The analysis universe holds every file at once, so it
+        # always picks the inner class. Whenever the receiver's class is one of SEVERAL known classes the
+        # call site's `Module.nesting` spells with the same last segment, which one the receiver is depends
+        # on load order, and a verdict against the project class's `def` is not one the program backs.
+        def load_order_dependent?(class_name)
+          segment = class_name.to_s.split("::").last
+          candidates = Rigor::Reflection.lexical_nesting_chain(@scope).map { |entry| "#{entry}::#{segment}" }
+          candidates << segment
+          known = candidates.uniq.select { |name| known_class?(name) }
+          known.include?(class_name.to_s) && known.size > 1
+        end
+
+        # A module some method body hands to `obj.extend` sits ahead of the object's class, so if it defines
+        # the name at all, that object answers with the module's definition.
+        def object_extension_may_shadow?
+          @scope.discovered_parameter_envelopes.any? do |_name, bucket|
+            bucket.key?(Scope::DiscoveryIndex::ENVELOPE_OBJECT_EXTENDED_MARK) && bucket.key?([:instance, @method_name])
+          end
+        end
+
+        def known_class?(name)
+          @scope.discovered_classes.key?(name) || Rigor::Reflection.rbs_class_known?(name, scope: @scope)
+        end
+
+        # Yields each level of `class_name`'s chain. False when the walk stopped at the ADR-41 budget rather than
+        # ending: budget exhaustion is uncertainty, and every caller reads it as a reason to decline.
+        def walked_whole_chain?(class_name, &)
+          levels, whole = chain_levels(arity_chain(class_name))
+          levels.each(&)
+          whole
+        end
+
+        # `[levels, whole]` for one world of the chain, up to the first superclass the project does not declare.
+        def chain_levels(chain) = [chain.levels.map { |level| Level.new(*level) }, !chain.truncated?]
+
+        def side = @kind == :singleton ? :singleton : :instance
+
+        # Instance methods reach a receiver through `include` / `prepend`; class methods through `extend`, and
+        # an extended module's own `include`s reach the same singleton — the chain's singleton side.
+        #
+        # Issue #986 — the `:arity` flavor expands a name the compact-header rename collision left ambiguous
+        # to BOTH classes it names: both are ancestors at runtime and only their MRO order is unknowable. Taking
+        # both into the level is what keeps this rule alive for the rest of the receiver: a method only one of
+        # them declares still has one envelope and still fires, a method they disagree about lands two on the
+        # level's join and declines there, and the class's own `def`s, its superclass's and its unambiguous
+        # mixins are untouched. Letting the decline arrive as an unknown EXTERNAL mixin instead suppressed the
+        # rule for every level of the receiver.
+        def arity_chain(class_name) = Scope::ResolutionChain.for(@scope, class_name.to_s, side, :arity)
+
+        def resolve(owner, raw)
+          return nil if raw.nil?
+
+          bucket = (@name_memo[owner] ||= {})
+          return bucket[raw] if bucket.key?(raw)
+
+          bucket[raw] = @scope.ancestor_name_candidates(owner, raw).find { |name| project_class?(name) }
+        end
+
+        def project_class?(name)
+          @scope.known_user_class?(name) || @scope.discovered_parameter_envelopes.key?(name)
+        end
+
+        # A module's methods reach the receiver as instance methods whichever side the receiver is on.
+        def level_envelopes(level)
+          own = @scope.parameter_envelopes_of(level.class_name)[[@kind, @method_name]]
+          mixed = level.modules.map { |mod| @scope.parameter_envelopes_of(mod)[[:instance, @method_name]] }
+          ([own] + mixed).compact
+        end
+
+        def clean_level?(level)
+          ([level.class_name] + level.modules).none? { |name| dynamic_surface?(name) || project_patched?(name) } &&
+            level.externals.all? { |candidates| external_mixin_lacks_method?(candidates) }
+        end
+
+        def dynamic_surface?(class_name)
+          Scope::DiscoveryIndex.rewritten_surface?(@scope.parameter_envelopes_of(class_name))
+        end
+
+        def project_patched?(class_name)
+          environment = @scope.environment
+          patched = environment&.project_patched_methods
+          return true if patched && !patched.empty? && patch_names_method?(patched, class_name)
+
+          synthetic = environment&.synthetic_method_index
+          return false if synthetic.nil? || synthetic.empty?
+
+          synthetic.knows_class?(class_name) || !synthetic.lookup_instance(class_name, @method_name).empty? ||
+            !synthetic.lookup_singleton(class_name, @method_name).empty?
+        end
+
+        def patch_names_method?(patched, class_name)
+          %i[instance singleton].any? do |kind|
+            !patched.lookup(class_name: class_name, method_name: @method_name, kind: kind).nil?
+          end
+        end
+
+        # A mixin the project does not declare may define the name with any arity, and `prepend` lets it win
+        # over the class's own `def`. Only a module RBS knows, and whose declaration lacks the name, is
+        # evidence that it does not.
+        def external_mixin_lacks_method?(candidates)
+          name = candidates.find { |candidate| Rigor::Reflection.rbs_class_known?(candidate, scope: @scope) }
+          return false if name.nil?
+
+          Rigor::Reflection.instance_method_definition(name, @method_name, scope: @scope).nil?
+        rescue StandardError
+          false
+        end
+
+        def public_at?(class_name)
+          visibility = @scope.discovered_method_visibility(class_name, @method_name)
+          visibility.nil? || visibility == :public
+        end
+
+        # A hook anywhere in the chain, including above the owner, and on either side: a class that answers
+        # names it does not define is a class whose `def`s are not the whole story of what a call reaches.
+        def chain_free_of_hooks?(class_name)
+          walked_whole_chain?(class_name) do |level|
+            ([level.class_name] + level.modules).each do |name|
+              envelopes = @scope.parameter_envelopes_of(name)
+              return false if dynamic_surface?(name)
+              return false if MISSING_HOOKS.any? { |hook| hook_recorded?(envelopes, hook) }
+            end
+          end
+        end
+
+        def hook_recorded?(envelopes, hook)
+          envelopes.key?([:instance, hook]) || envelopes.key?([:singleton, hook])
+        end
+
+        # Every project class whose superclass chain reaches the receiver's class: a value typed as the
+        # receiver may be any of them, and each one's own definition of the name is what runs for it.
+        def subclasses_agree?(class_name, envelope)
+          each_subclass(class_name) do |subclass|
+            subclass_levels(subclass).each do |level|
+              # A subclass whose own level the budget cut cannot be read, which is a reason to decline.
+              return false if level.nil?
+              return false unless clean_level?(level)
+              return false unless level_envelopes(level).all?(envelope)
+            end
+          end
+          true
+        end
+
+        # A subclass's own level (nil where the budget cut it or the chain does not stand for the name). It asks
+        # {Inference::DefinerResolution} on the receiver's side (ADR-119 C1b, C2-c): the subclass's own level
+        # answers, and a fork, an unproven mixin order, a `possible`-only definer or a hook there is `UNKNOWN`,
+        # which `subclasses_agree?` reads as a reason to decline.
+        def subclass_levels(subclass)
+          case Inference::DefinerResolution.resolve(@scope, subclass, @method_name, side, question: :arity,
+                                                    &own_level_answer(subclass))
+          in Inference::DefinerResolution::Known(answer: _answer, owner: _owner) then [first_level(subclass)]
+          in Inference::DefinerResolution::ABSENT then [nil]
+          in Inference::DefinerResolution::UNKNOWN then NO_LEVELS
+          end
+        end
+
+        # The subclass's own level, always a candidate (an empty answer where it records nothing), so that the
+        # read asks whether the chain stands for the subclass and never whether an ancestor defines the name.
+        def own_level_answer(subclass)
+          lambda do |chain, from|
+            next nil unless from.zero? && !chain.levels.empty?
+
+            level = Level.new(*chain.levels.first)
+            ArityHit.new(level_envelopes(level).uniq, subclass, 0, side)
+          end
+        end
+
+        def first_level(class_name) = chain_levels(arity_chain(class_name)).first.first
+
+        def each_subclass(class_name)
+          children = children_by_parent
+          queue = children.fetch(class_name.to_s, []).dup
+          seen = {}
+          until queue.empty?
+            subclass = queue.shift
+            next if seen[subclass]
+
+            seen[subclass] = true
+            yield subclass
+            queue.concat(children.fetch(subclass, []))
+          end
+        end
+
+        def children_by_parent
+          @scope.discovered_superclasses.each_with_object({}) do |(child, raw_parent), children|
+            parent = resolve(child, raw_parent)
+            (children[parent] ||= []) << child if parent
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules/special_global_setters.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #1367 (ADR-117 Decision point 1, WD2) — what the interpreter's setter for each special global accepts:
+      # the envelope `global.write-type-mismatch` and `global.readonly-write` judge a write against.
+      #
+      # The setter is the authority, not the RBS declaration of the global. Where the two differ, the setter wins:
+      # `$;` is declared `Regexp | String | nil`, but its setter also takes any object with `to_str`, and `$stdout` is
+      # declared `IO`, but its setter takes anything that responds to `write`. Each entry names the CRuby function
+      # that enforces it and was confirmed on Ruby 4.0.5, whose error the comment quotes.
+      #
+      # A special whose setter accepts every value is absent, so a write to it is never checked: `$stdin`
+      # (ADR-117 WD2), `$_`, `$VERBOSE` / `$-v` / `$-w`, `$DEBUG` / `$-d` and `$=`. So is `$@`, whose setter raises
+      # `ArgumentError` or `TypeError` depending on whether `$!` is set when it runs. `$&`, `` $` ``, `$'`, `$+`
+      # and `$1`..`$9` cannot be assigned at all: that is a syntax error, not a write.
+      module SpecialGlobalSetters
+        # A setter that raises `TypeError` unless the value is an instance of one of `classes` (a subclass counts,
+        # since the setter tests the object's built-in type) or, when `conversion` names a method, responds to it:
+        # the implicit conversion the setter calls (`to_str`, `to_int`) or the method it asks `respond_to?` about
+        # (`write`). `accepts` is the phrase the diagnostic quotes.
+        Contract = Data.define(:classes, :conversion, :accepts) do
+          # Whether an instance of the core class `class_name` is one the setter takes by type. Both sides are core
+          # classes, whose hierarchy is Ruby's own, so the running interpreter answers it.
+          def accepts_class?(class_name)
+            klass = ::Object.const_get(class_name)
+            classes.any? { |accepted| klass <= ::Object.const_get(accepted) }
+          end
+        end
+
+        # `rb_str_setter` (string.c), reached through `rb_deprecated_str_setter` and io.c's `deprecated_rs_setter`,
+        # tests `T_STRING` and calls no conversion: `$/ = 1` raises "value of $/ must be String", and so do a
+        # `Regexp` and an object with `to_str`.
+        STRING_OR_NIL = Contract.new(classes: %w[String NilClass].freeze, conversion: nil, accepts: "a String or nil")
+        # `rb_fs_setter` (string.c): nil, a String, a Regexp, or an object with `to_str` (`rb_fs_check`).
+        # `$; = 1` raises "value of $; must be String or Regexp".
+        FIELD_SEPARATOR = Contract.new(
+          classes: %w[String Regexp NilClass].freeze, conversion: :to_str,
+          accepts: "a String, a Regexp, nil, or an object with `to_str'"
+        )
+        # `match_setter` (re.c): nil or a MatchData (`Check_Type(val, T_MATCH)`). `$~ = 1` raises
+        # "wrong argument type Integer (expected MatchData)".
+        MATCH_DATA = Contract.new(classes: %w[MatchData NilClass].freeze, conversion: nil,
+                                  accepts: "a MatchData or nil")
+        # `set_arg0` (ruby.c) calls `StringValueCStr`: a String or an object with `to_str`, and not nil. `$0 = 1`
+        # raises "no implicit conversion of Integer into String".
+        PROGRAM_NAME = Contract.new(
+          classes: %w[String].freeze, conversion: :to_str, accepts: "a String or an object with `to_str'"
+        )
+        # `argf_lineno_setter` (io.c) calls `NUM2INT`: an Integer, a Float, or an object with `to_int`, and not nil.
+        # `$. = "1"` raises "no implicit conversion of String into Integer".
+        LINE_NUMBER = Contract.new(
+          classes: %w[Integer
+                      Float].freeze, conversion: :to_int, accepts: "an Integer, a Float, or an object with `to_int'"
+        )
+        # `opt_i_set` (io.c) through `argf_inplace_mode_set`: nil or false turns in-place mode off; anything else
+        # goes through `StringValueCStr`. `$-i = 1` raises "no implicit conversion of Integer into String".
+        INPLACE_MODE = Contract.new(
+          classes: %w[String NilClass FalseClass].freeze, conversion: :to_str,
+          accepts: "a String, nil, false, or an object with `to_str'"
+        )
+        # `stdout_setter` / `stderr_setter` (io.c) call `must_respond_to(id_write, …)`, which asks `respond_to?` and so
+        # honours `respond_to_missing?`. `$stdout = 1` raises "$stdout must have write method, Integer given".
+        # ADR-117 WD2: this `_Writer` requirement is the only contract a stream write is checked against.
+        WRITER = Contract.new(classes: [].freeze, conversion: :write, accepts: "an object that responds to `write'")
+
+        CONTRACTS = {
+          "$/": STRING_OR_NIL,
+          "$-0": STRING_OR_NIL,
+          "$,": STRING_OR_NIL,
+          "$\\": STRING_OR_NIL,
+          "$;": FIELD_SEPARATOR,
+          "$-F": FIELD_SEPARATOR,
+          "$~": MATCH_DATA,
+          "$0": PROGRAM_NAME,
+          "$PROGRAM_NAME": PROGRAM_NAME,
+          "$.": LINE_NUMBER,
+          "$-i": INPLACE_MODE,
+          "$stdout": WRITER,
+          "$>": WRITER,
+          "$stderr": WRITER
+        }.freeze
+
+        # The specials whose setter is `rb_gvar_readonly_setter` — declared with `rb_define_readonly_variable`, as a
+        # virtual variable without a setter, or with that setter by name. Any write raises `NameError`
+        # ("$! is a read-only variable"), whatever the value.
+        #
+        # - `$!` (eval.c); `$$` and `$?` (process.c).
+        # - `$<`, `$FILENAME` and `$*` (io.c, ARGF).
+        # - `$:` / `$LOAD_PATH` / `$-I`, `$"` / `$LOADED_FEATURES` (load.c).
+        # - `$-W`, and the `-p` / `-l` / `-a` switches `$-p`, `$-l` and `$-a` (ruby.c).
+        READ_ONLY = Set[
+          :$!, :$$, :$?, :$<, :$FILENAME, :$*, :$:, :$LOAD_PATH, :$-I, :$", :$LOADED_FEATURES,
+          :$-W, :$-p, :$-l, :$-a
+        ].freeze
+
+        # The literal nodes `global.write-type-mismatch` judges, by the core class of the object each evaluates to.
+        # An interpolated String, Symbol or Regexp is still a new instance of that class.
+        LITERAL_CLASSES = {
+          Prism::IntegerNode => "Integer", Prism::FloatNode => "Float", Prism::RationalNode => "Rational",
+          Prism::ImaginaryNode => "Complex", Prism::StringNode => "String", Prism::InterpolatedStringNode => "String",
+          Prism::SymbolNode => "Symbol", Prism::InterpolatedSymbolNode => "Symbol", Prism::ArrayNode => "Array",
+          Prism::HashNode => "Hash", Prism::RegularExpressionNode => "Regexp",
+          Prism::InterpolatedRegularExpressionNode => "Regexp", Prism::NilNode => "NilClass",
+          Prism::TrueNode => "TrueClass", Prism::FalseNode => "FalseClass"
+        }.freeze
+
+        # How the diagnostic names a literal of each class.
+        LITERAL_DESCRIPTIONS = { "NilClass" => "nil", "TrueClass" => "true", "FalseClass" => "false" }.freeze
+
+        module_function
+
+        # The setter contract a write of `name` is checked against, or nil when its setter accepts every value or the
+        # global is no special.
+        def contract_for(name)
+          CONTRACTS[name]
+        end
+
+        # The core class of the object `node` evaluates to when it is a literal ({LITERAL_CLASSES}), looking
+        # through parentheses around a single expression, or nil for any other expression.
+        def literal_class(node)
+          while node.is_a?(Prism::ParenthesesNode)
+            body = node.body
+            return nil unless body.is_a?(Prism::StatementsNode) && body.body.size == 1
+
+            node = body.body.first
+          end
+          LITERAL_CLASSES[node.class]
+        end
+
+        def literal_description(class_name)
+          LITERAL_DESCRIPTIONS.fetch(class_name) do
+            "#{class_name.start_with?('A', 'E', 'I', 'O', 'U') ? 'an' : 'a'} #{class_name} literal"
+          end
+        end
+
+        def read_only?(name)
+          READ_ONLY.include?(name)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules/unreachable_clause_collector.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../../source/node_children"
+require_relative "../../inference/narrowing"
 require_relative "inferred_param_guard"
 
 module Rigor
@@ -29,6 +30,12 @@ module Rigor
       # The false-positive envelope mirrors `flow.always-truthy-condition`: clauses inside loops / blocks are
       # skipped (mutation tracking through those is incomplete), and the rule reads the engine's own
       # narrowing rather than recomputing it, so the diagnostic and the body typing can never diverge.
+      #
+      # Issue #1429 — a `:disjoint` clause is not reported when its `Bot` rests on a `Nominal` subject member whose
+      # class is disjoint from a condition's ({Inference::Narrowing.disjoint_nominal_guard?}): the `when C` or `in C`
+      # is code evidence that the subject can hold such an object (`io = STDOUT; case io when StringIO`), and Rigor's
+      # reading of the subject's type is what the evidence contradicts. The body scope stays `Bot`, so no call on the
+      # subject in it is checked. A subject that is a literal carrier (`x = 1; case x when String`) is still reported.
       class UnreachableClauseCollector
         LOOP_OR_BLOCK_NODE_CLASSES = [
           Prism::WhileNode, Prism::UntilNode, Prism::ForNode, Prism::BlockNode
@@ -139,13 +146,30 @@ module Rigor
           return if scope.nil?
           return unless scope.local(subject_name).is_a?(Type::Bot)
 
+          kind = when_clause_kind(clause, subject_name)
+          return if kind == :disjoint &&
+                    disjoint_nominal_subject?(@scope_index[clause.conditions.first], subject_name, clause.conditions)
+
           @results << Result.new(
             clause: clause, body: clause.statements, subject_name: subject_name,
             condition_source: clause.conditions.map(&:slice).join(", "),
-            kind: when_clause_kind(clause, subject_name), keyword: "when"
+            kind: kind, keyword: "when"
           )
         end
 
+        # True when the subject, as `entry` binds it, holds a non-literal `Nominal` whose class the class one of
+        # `patterns` names is disjoint from (issue #1429, see the class comment).
+        def disjoint_nominal_subject?(entry, subject_name, patterns)
+          subject_type = entry&.local(subject_name)
+          return false if subject_type.nil?
+
+          patterns.any? do |condition|
+            class_name = Inference::Narrowing.lexical_class_name(condition, entry)
+            class_name &&
+              Inference::Narrowing.disjoint_nominal_guard?(subject_type, class_name, environment: entry.environment)
+          end
+        end
+
         # A dead `when` is `:prior_exhaustion` when the subject was already narrowed to `bot` BEFORE this
         # clause (an earlier clause covered it) — read from the entry scope the engine recorded on the
         # clause's first condition node (ADR-47 WD2). Otherwise the subject was still concrete entering the
@@ -170,13 +194,23 @@ module Rigor
           return if scope.nil?
           return unless scope.local(subject_name).is_a?(Type::Bot)
 
+          kind = in_clause_kind(clause, subject_name)
+          return if kind == :disjoint && disjoint_nominal_pattern?(clause, subject_name)
+
           @results << Result.new(
             clause: clause, body: clause.statements, subject_name: subject_name,
             condition_source: clause.pattern.slice,
-            kind: in_clause_kind(clause, subject_name), keyword: "in"
+            kind: kind, keyword: "in"
           )
         end
 
+        # {#disjoint_nominal_subject?} for a bare class pattern, `in C` or `in C => x`.
+        def disjoint_nominal_pattern?(clause, subject_name)
+          pattern = clause.pattern
+          pattern = pattern.value if pattern.is_a?(Prism::CapturePatternNode)
+          disjoint_nominal_subject?(@scope_index[clause.pattern], subject_name, [pattern])
+        end
+
         def in_clause_kind(clause, subject_name)
           entry = @scope_index[clause.pattern]
           return :prior_exhaustion if entry && entry.local(subject_name).is_a?(Type::Bot)