rigortype 0.4.5 → 0.4.7

data/lib/rigor/environment/deferred_signature_plan.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+module Rigor
+  class Environment
+    # Issue #2422 — what a bundled plugin's deferred signature file loads as, against the environment every other
+    # signature source has already built. The #610 arity check stands a file down whole first
+    # (`RbsLoader.generic_arity_conflict`); {.plan} decides the rest declaration by declaration and member by
+    # member, with {GatedSignaturePlan}'s #1713 helpers:
+    #
+    # - a method another source declares (a `def`, an attribute or an alias), where that source is NOT the project's own
+    #   (an `rbs collection install`, a gem's `sig/`, a vendored or another plugin's file), is *composed*: the plugin's
+    #   `def` becomes an overload continuation, `def m: <plugin overloads> | ...`, so RBS puts the plugin's overloads
+    #   first and keeps the other source's as the fallback. The plugin's signatures are often written wider on purpose
+    #   (`Object#html_safe?: () -> bool` where the collection says `-> false`), and standing them down would let the
+    #   narrower one fold correct code into dead branches;
+    # - any other method, attribute or alias another source declares stands down: the project's own `sig/` or
+    #   inline RBS binds by #610's rule, and an attribute, an alias or one side of a `def self?.m` cannot be
+    #   continued ({GatedSignaturePlan.untaken} narrows an `attr_accessor` or `self?` to its untaken half);
+    # - a constant, global, type alias, interface or class alias another source already declares, and a type
+    #   whose kind (class or module) contradicts another source's, stands down on its own, where adding it would
+    #   have raised `RBS::DuplicatedDeclarationError` and dropped the plugin's whole file;
+    # - a class header's superclass clause another source already gives the class one stands down (#2439), where two
+    #   different clauses would have raised `RBS::SuperclassMismatchError`; the plugin's declaration reopens the class.
+    #
+    # A declaration with nothing taken comes back as the same object, so a file with no collision loads as it
+    # stands. {.standdown_rows} reads what stood down back off the built environment, so a warm run off the env
+    # cache reports what the cold run decided.
+    module DeferredSignaturePlan
+      module_function
+
+      # @param own — the buffer names that are the project's own sources: its `signature_paths:` files (not the
+      #   collection or gem directories also on that list) and its inline RBS.
+      def plan(decls, env, own, namespace = nil)
+        planned = decls.filter_map { |decl| plan_declaration(decl, env, own, namespace) }
+        same?(planned, decls) ? decls : planned
+      end
+
+      def plan_declaration(decl, env, own, namespace)
+        name = GatedSignaturePlan.qualify(namespace, declared_name(decl))
+        if GatedSignaturePlan.type_declaration?(decl)
+          return nil if kind_clash?(env, decl, name)
+
+          return plan_type(decl, env, own, name)
+        end
+        declared_elsewhere(env, decl, name) ? nil : decl
+      end
+
+      def plan_type(decl, env, own, name)
+        others = GatedSignaturePlan.other_declarations(env, name)
+        taken = GatedSignaturePlan.declared_keys(others)
+        external = others.reject { |other| own.include?(buffer_of(other)) }
+        defined = GatedSignaturePlan.declared_keys(external) | definition_keys(external)
+        members = decl.members.filter_map do |member|
+          next plan_declaration(member, env, own, name) if declaration?(member)
+          next member if taken.empty?
+
+          composed(member, defined) || GatedSignaturePlan.untaken(member, taken)
+        end
+        drop = superclass_given?(decl, others)
+        return decl if same?(members, decl.members) && !drop
+
+        GatedSignaturePlan.rebuild(decl, members: members, drop_super_class: drop)
+      end
+
+      # Issue #2439 — true when `decl` is a class with a superclass clause and another source (`others`) already
+      # gives the class one. Two different clauses raise `RBS::SuperclassMismatchError` and the class and every
+      # descendant read `Dynamic[top]`, so the plugin's header stands down and reopens the class without one. The
+      # two names are not compared: they are not resolved yet, and the other source's superclass binds either way.
+      def superclass_given?(decl, others)
+        super_class?(decl) && others.any? { |other| super_class?(other) }
+      end
+
+      # `member` as an overload continuation, or nil when it cannot be one: only a plain one-sided `def` can, and
+      # only onto a method — a `def`, an attribute or an alias, all of which RBS continues — that a source other
+      # than the project's own declares.
+      def composed(member, defined)
+        return nil unless member.is_a?(::RBS::AST::Members::MethodDefinition) && !member.overloading?
+        return nil if member.kind == :singleton_instance
+
+        key = [member.name, member.kind]
+        return nil unless defined.include?(key)
+
+        member.update(overloading: true)
+      end
+
+      # The `[name, kind]` keys a plain or continued `def` in `decls` declares — what a continuation can extend.
+      def definition_keys(decls)
+        decls.each_with_object(Set.new) do |decl, keys|
+          decl.members.each do |member|
+            next unless member.is_a?(::RBS::AST::Members::MethodDefinition)
+
+            sides = member.kind == :singleton_instance ? %i[instance singleton] : [member.kind]
+            sides.each { |side| keys << [member.name, side] }
+          end
+        end
+      end
+
+      def kind_clash?(env, decl, name)
+        type_name = ::RBS::TypeName.parse("::#{name}")
+        return true if env.class_alias_decls.key?(type_name)
+
+        first = GatedSignaturePlan.other_declarations(env, name).first
+        !first.nil? && !first.instance_of?(decl.class)
+      end
+
+      # The buffer of the declaration another source already makes under `decl`'s name, or nil.
+      def declared_elsewhere(env, decl, name)
+        entry = declaration_entry(env, decl, name)
+        entry && (RbsLoader.declaration_buffer_name(entry.decl) || "")
+      end
+
+      def declaration_entry(env, decl, name)
+        type_name = -> { ::RBS::TypeName.parse("::#{name}") }
+        case decl
+        when ::RBS::AST::Declarations::Constant then env.constant_decls[type_name.call]
+        when ::RBS::AST::Declarations::Global then env.global_decls[decl.name]
+        when ::RBS::AST::Declarations::TypeAlias then env.type_alias_decls[type_name.call]
+        when ::RBS::AST::Declarations::Interface then env.interface_decls[type_name.call]
+        when ::RBS::AST::Declarations::ClassAlias, ::RBS::AST::Declarations::ModuleAlias
+          env.class_alias_decls[type_name.call] || env.class_decls[type_name.call]
+        end
+      end
+
+      # A class or module alias names itself as `new_name`; every other declaration as `name`.
+      def declared_name(decl)
+        decl.respond_to?(:new_name) ? decl.new_name : decl.name
+      end
+
+      def declaration?(member)
+        member.is_a?(::RBS::AST::Declarations::Base)
+      end
+
+      def same?(planned, original)
+        planned.size == original.size && planned.zip(original).all? { |a, b| a.equal?(b) }
+      end
+
+      def buffer_of(decl)
+        RbsLoader.declaration_buffer_name(decl)
+      end
+
+      # One {.standdown_rows} walk over a deferred file: the built env, the file's buffer name, the rows so far, and
+      # the env's type-name resolver, built on first use (only a dropped superclass clause needs it).
+      class Walk
+        attr_reader :env, :file, :rows
+
+        def initialize(env, file)
+          @env = env
+          @file = file
+          @rows = []
+        end
+
+        # rbs 4.x builds the resolver with `TypeNameResolver.build(env)`; rbs 3.x's constructor takes the env, which
+        # the 4.x signature Rigor reads (`new(all_names, aliases)`) does not describe.
+        def resolver
+          @resolver ||= begin
+            klass = ::RBS::Resolver::TypeNameResolver
+            if klass.respond_to?(:build)
+              klass.build(env)
+            else
+              klass.new(env) # rigor:disable call.wrong-arity
+            end
+          end
+        end
+      end
+
+      # What {.plan} left out of the deferred `file` (its parsed `decls`) in the built `env`, as `[declaration,
+      # cause_file]` rows — `Object#acts_like?`, `Time.at`, `FFI::Pointer::NULL`, `Foo < Bar`, or a type name — with
+      # the buffer of the other source's declaration, or nil when it cannot be named. A composed method is not a row:
+      # the plugin's overloads still bind.
+      def standdown_rows(env, file, decls)
+        walk = Walk.new(env, file)
+        decls.each { |decl| declaration_rows(walk, decl, nil) }
+        walk.rows.uniq
+      end
+
+      # `context` is RBS's resolver context for where `decl` is written: nil at the top level, else `[outer,
+      # absolute name of the enclosing declaration]`, as `RBS::Environment#append_context` builds it.
+      def declaration_rows(walk, decl, context)
+        name = GatedSignaturePlan.qualify(namespace_of(context), declared_name(decl))
+        return type_rows(walk, decl, name, context) if GatedSignaturePlan.type_declaration?(decl)
+
+        cause = displaced_by(walk.env, decl, name, walk.file)
+        walk.rows << [decl.is_a?(::RBS::AST::Declarations::Global) ? decl.name.to_s : name, cause] if cause
+      end
+
+      def namespace_of(context)
+        context && context.last.to_s.delete_prefix("::")
+      end
+
+      # A non-nil buffer name (possibly empty) when another source's declaration of `decl` is the one loaded.
+      def displaced_by(env, decl, name, file)
+        entry = declaration_entry(env, decl, name)
+        return nil if entry.nil?
+
+        buffer = RbsLoader.declaration_buffer_name(entry.decl)
+        buffer == file ? nil : buffer
+      end
+
+      def type_rows(walk, decl, name, context)
+        loaded, others = loaded_and_others(walk, name)
+        if loaded.empty?
+          cause = others.empty? ? alias_cause(walk.env, name) : buffer_of(others.first)
+          walk.rows << [name, cause] if cause
+          return
+        end
+
+        walk.rows.concat(superclass_rows(walk, decl, name, context, others))
+        walk.rows.concat(member_rows(decl, name, loaded, others))
+        inner = [context, ::RBS::TypeName.parse("::#{name}")]
+        decl.members.each { |member| declaration_rows(walk, member, inner) if declaration?(member) }
+      end
+
+      # The declarations of `name` the walked file loaded, and the ones other sources made (synthesized stubs left out).
+      def loaded_and_others(walk, name)
+        entry = walk.env.class_decls[::RBS::TypeName.parse("::#{name}")]
+        declarations = entry.nil? ? [] : RbsLoader.entry_declarations(entry)
+        loaded = declarations.select { |other| buffer_of(other) == walk.file }
+        [loaded, declarations.reject { |other| loaded.include?(other) || GatedSignaturePlan.synthetic?(other) }]
+      end
+
+      # The buffer of a class or module alias declaring `name` (empty when it cannot be named), or nil.
+      def alias_cause(env, name)
+        entry = env.class_alias_decls[::RBS::TypeName.parse("::#{name}")]
+        entry && (RbsLoader.declaration_buffer_name(entry.decl) || "")
+      end
+
+      # The plugin's superclass clause as a row (`ActiveRecord::StatementInvalid < ActiveRecordError`) when the plan
+      # dropped it for another source's ({.superclass_given?}) and that source's names a different class or type
+      # arguments. The plan drops an identical clause too, but nothing is lost, so no row.
+      def superclass_rows(walk, decl, name, context, others)
+        return [] unless superclass_given?(decl, others)
+
+        cause = others.find { |other| super_class?(other) }
+        return [] if same_super_class?(walk, decl.super_class, context, cause.super_class)
+
+        written = decl.super_class
+        args = written.args.empty? ? "" : "[#{written.args.join(', ')}]"
+        [["#{name} < #{written.name}#{args}", buffer_of(cause)]]
+      end
+
+      # Whether the plugin's clause `written`, resolved as RBS resolves a superclass (in the context the class is
+      # written in, not its own), names the class and type arguments of `other`, the built env's already-absolute
+      # clause, class aliases normalised on both sides. An unresolvable name differs.
+      def same_super_class?(walk, written, context, other)
+        name = absolute_name(walk, written.name, context)
+        return false if name.nil? || normalized(walk.env, name) != normalized(walk.env, other.name)
+
+        written.args.map { |arg| normalized_type(walk, arg, context) } ==
+          other.args.map { |arg| normalized_type(walk, arg, nil) }
+      end
+
+      def absolute_name(walk, name, context)
+        name.absolute? ? name : walk.resolver.resolve(name, context: context)
+      end
+
+      def normalized(env, name)
+        name.class? ? env.normalize_module_name(name) : name
+      end
+
+      def normalized_type(walk, type, context)
+        return type.to_s unless type.respond_to?(:map_type_name)
+
+        type.map_type_name { |name, _, _| normalized(walk.env, absolute_name(walk, name, context) || name) }.to_s
+      end
+
+      def super_class?(decl)
+        decl.is_a?(::RBS::AST::Declarations::Class) && !decl.super_class.nil?
+      end
+
+      def member_rows(decl, name, loaded, others)
+        present = GatedSignaturePlan.declared_keys(loaded) | definition_keys(loaded)
+        decl.members.flat_map do |member|
+          RbsLoader.member_method_keys(member).reject { |key| present.include?(key) }.filter_map do |key|
+            cause = others.find { |other| other.members.any? { |m| RbsLoader.member_method_keys(m).include?(key) } }
+            cause && [GatedSignaturePlan.member_label(name, key), buffer_of(cause)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/environment/gated_signature_guard.rb

@@ -13,7 +13,7 @@ module Rigor
     module GatedSignatureGuard
       module_function
 
-      # @param dir — the vendored directory (Pathname).
+      # @param dir — the vendored directory.
       # @return the absolute-less names (`"Prime::PseudoPrimeGenerator"`) of every class and module it declares.
       def type_names(dir)
         RootedGlob.glob(dir, "*.rbs").flat_map do |file|

data/lib/rigor/environment/gated_signature_plan.rb

@@ -213,10 +213,13 @@ module Rigor
         end
       end
 
-      def rebuild(decl, members:)
+      # `decl` with `members` in place of its own. A class keeps its superclass unless `drop_super_class` (#2439: a
+      # plugin's class header another source already gives a superclass reopens the class without one).
+      def rebuild(decl, members:, drop_super_class: false)
         if decl.is_a?(::RBS::AST::Declarations::Class)
           ::RBS::AST::Declarations::Class.new(
-            name: decl.name, type_params: decl.type_params, super_class: decl.super_class, members: members,
+            name: decl.name, type_params: decl.type_params, super_class: drop_super_class ? nil : decl.super_class,
+            members: members,
             annotations: decl.annotations, location: decl.location, comment: decl.comment
           )
         else

data/lib/rigor/environment/lockfile_resolver.rb

@@ -7,7 +7,7 @@ module Rigor
     # Gemfile.lock parser for target-project bundler awareness (O4 Layer 3, implemented).
     #
     # Parses a target project's `Gemfile.lock` via Bundler's `LockfileParser` and exposes the locked gem set
-    # as a frozen `Hash[String, LockfileResolver::LockedGem]` keyed by gem name. Used by
+    # as a frozen map from gem name to `LockedGem`. Used by
     # {Rigor::Environment::BundleSigDiscovery} as a filter so the discovered `sig/` directories under the
     # bundler install root are limited to gems the project actually declares (and at the version it declared
     # them).
@@ -38,8 +38,12 @@ module Rigor
       # variant for the readers that want a single version (coverage report, doctor): the `ruby` one when the
       # lockfile has it, otherwise the last parsed. Defaults to the single `[version, platform]` pair, and the
       # pair must be one of `variants`.
-      LockedGem = Data.define(:name, :version, :platform, :git_source, :variants) do
-        def initialize(name:, version:, platform:, git_source: false, variants: nil)
+      #
+      # `path_source` is the absolute directory a lockfile `PATH` stanza resolved this gem from (its `remote:`
+      # expanded against the lockfile's directory), and `nil` for every other source, `GIT` included. Issue
+      # #2441 reads it to tell the project's own path gems apart from the rest of the bundle. Defaults `nil`.
+      LockedGem = Data.define(:name, :version, :platform, :git_source, :variants, :path_source) do
+        def initialize(name:, version:, platform:, git_source: false, variants: nil, path_source: nil)
           version = -version.to_s
           platform = -platform.to_s
           variants = (variants || [[version, platform]]).map { |v, p| [-v.to_s, -p.to_s].freeze }.uniq.freeze
@@ -52,7 +56,8 @@ module Rigor
             version: version,
             platform: platform,
             git_source: git_source ? true : false,
-            variants: variants
+            variants: variants,
+            path_source: path_source && -path_source.to_s
           )
         end
       end
@@ -115,9 +120,9 @@ module Rigor
       def self.do_parse_dependency_names(path)
         parser = Bundler::LockfileParser.new(File.read(path.to_s))
         # `#dependencies` is the parsed `DEPENDENCIES` section keyed by gem name, so the version constraint
-        # and the pinned-source `!` suffix are already stripped for us. The upstream bundler RBS shim does
-        # not declare it.
-        parser.dependencies.keys.to_set { |name| -name.to_s }.freeze # rigor:disable undefined-method
+        # and the pinned-source `!` suffix are already stripped for us. Rigor's vendored bundler
+        # signature declares it as a Hash keyed by gem name.
+        parser.dependencies.keys.to_set { |name| -name.to_s }.freeze
       rescue ::Ractor::IsolationError => e
         warn_isolated(path, e)
         EMPTY_NAMES
@@ -171,10 +176,9 @@ module Rigor
         parser = Bundler::LockfileParser.new(body)
         locked = parser.specs.each_with_object({}) do |spec, h|
           # `Bundler::LazySpecification` carries name, version, platform. Platform is `Gem::Platform` or the
-          # symbol `:ruby`; both stringify cleanly. The upstream bundler RBS shim
-          # (references/rbs/sig/shims/bundler.rbs) does NOT declare `LazySpecification#platform` so the call
-          # site needs a suppression marker.
-          platform = spec.platform.to_s # rigor:disable undefined-method
+          # symbol `:ruby`; both stringify cleanly. Rigor's vendored bundler signature declares
+          # `LazySpecification#platform`, so the call needs no suppression.
+          platform = spec.platform.to_s
           # `#source` is the `Bundler::Source::*` this spec resolved from — `Git` for a `GIT` lockfile
           # stanza, `Rubygems` for a `GEM` one, `Path`/`Gemspec` for `path:`. Only `Git` sources land under
           # {BundleSigDiscovery}'s `bundler/gems/` walk.
@@ -182,7 +186,8 @@ module Rigor
           # instead of letting the last one overwrite the rest (#1844).
           entry = LockedGem.new(
             name: spec.name, version: spec.version.to_s, platform: platform,
-            git_source: spec.source.is_a?(Bundler::Source::Git)
+            git_source: spec.source.is_a?(Bundler::Source::Git),
+            path_source: path_source_dir(spec.source, path)
           )
           h[entry.name] = (prior = h[entry.name]) ? merge_variant(prior, entry) : entry
         end
@@ -196,6 +201,17 @@ module Rigor
       end
       private_class_method :do_parse
 
+      # The absolute directory a `PATH` stanza names, resolved against the lockfile's own directory — never
+      # against `Bundler.root`, which is Rigor's process and not the analysed project. `Bundler::Source::Git`
+      # subclasses `Path`, so a `GIT` stanza is excluded by name.
+      def self.path_source_dir(source, lockfile_path)
+        return nil unless source.is_a?(Bundler::Source::Path)
+        return nil if source.is_a?(Bundler::Source::Git)
+
+        File.expand_path(source.path.to_s, File.dirname(File.expand_path(lockfile_path.to_s)))
+      end
+      private_class_method :path_source_dir
+
       # Folds a further platform variant of an already-parsed name into it. The representative keeps a `ruby`
       # variant once seen; otherwise the last variant wins, as it did before variants were kept.
       def self.merge_variant(prior, entry)

data/lib/rigor/environment/member_consistency/comparator.rb

@@ -14,7 +14,7 @@ module Rigor
       # declared types. See {MemberConsistency} for the rule; this class holds the type work.
       #
       # A contradiction is reported only where it is PROVEN: no value, and no call, satisfies both sides.
-      # Everything short of a proof is undecided. Four places carry that burden:
+      # Everything short of a proof is undecided. Five places carry that burden:
       #
       # - {#disjoint?} proves two types share no value, from the RBS hierarchy of Ruby core and stdlib
       #   classes ({RbsProof}) only: two such classes neither of which is an RBS ancestor of the other, or a
@@ -103,6 +103,7 @@ module Rigor
         #   `:inline` (the inline side is more precise), `:contradiction` or `:undecided`; `detail` names the
         #   deciding position for the two reported outcomes and is nil otherwise.
         def compare(signature_member, inline_member, method_name)
+          return compare_variables(signature_member, inline_member) if variable?(signature_member)
           return EQUAL if same_declaration?(signature_member, inline_member)
           return SIGNATURE_MORE_PRECISE if inferred_signature?(inline_member)
 
@@ -174,6 +175,22 @@ module Rigor
           member_annotation_strings(member).include?(INFERRED_SIGNATURE_DIRECTIVE)
         end
 
+        def variable?(member)
+          member.is_a?(::RBS::AST::Members::InstanceVariable) ||
+            member.is_a?(::RBS::AST::Members::ClassInstanceVariable)
+        end
+
+        # Issue #2440 — an instance variable (or class instance variable) declared on both sides. Two
+        # declarations of one type are equal and merge silently. Any other pair is undecided, never ranked
+        # and never a contradiction: `sig/` binds and the inline declaration is reported at `:info`. A
+        # variable has no call to satisfy, so "more precise" has no reader to favour, and the committed
+        # `.rbs` (typically `rbs-inline --output`'s own) is the declaration the project's other tools read.
+        def compare_variables(signature_member, inline_member)
+          return EQUAL if signature_member.type == inline_member.type
+
+          [:undecided, "the type is `#{signature_member.type}` in `sig/` and `#{inline_member.type}` inline"]
+        end
+
         def compare_aliases(signature_member, inline_member)
           both = signature_member.is_a?(::RBS::AST::Members::Alias) && inline_member.is_a?(::RBS::AST::Members::Alias)
           return EQUAL if both && signature_member.old_name == inline_member.old_name

data/lib/rigor/environment/member_consistency.rb

@@ -59,6 +59,9 @@ module Rigor
       NO_RECORDS = [].freeze
       private_constant :NO_RECORDS
 
+      # The key kinds {.member_keys} gives a variable member.
+      VARIABLE_KINDS = %i[instance_variable class_instance_variable].freeze
+
       # What a disjointness proof may lean on (ADR-112 WD5, #1075): the RBS class hierarchy the analysis
       # itself uses, restricted to classes Ruby core and the stdlib declare. Never Ruby constants loaded in
       # the analyzer process — those depend on which libraries happen to be required, and rbs and Ruby
@@ -115,8 +118,8 @@ module Rigor
       class << self
         # @param signature_members — `{[class, method, kind] => [signature_path, member, visibility]}`, the
         #   first project `.rbs` member declaring each key, with its effective visibility.
-        # @param inline_members — `[[virtual_name, class_name, member, visibility], ...]`, every member the
-        #   inline sources declare.
+        # @param inline_members — `[[virtual_name, class_name, member, visibility, nesting], ...]`, every member
+        #   the inline sources declare, with the lexical nesting {.member_keys} keys a mixin by.
         # @param shadowable — the first segment of every class / module name the project's inputs declare
         #   ({Comparator#initialize}).
         # @param proof — an {RbsProof} for the reported rows, or nil for the environment build.
@@ -131,9 +134,9 @@ module Rigor
 
           state = { comparator: Comparator.new(shadowable, proof: proof), records: [], inline: Set.new,
                     signature: Hash.new { |hash, file| hash[file] = Set.new }, checked: {}.compare_by_identity }
-          inline_members.each do |virtual_name, class_name, member, visibility|
+          inline_members.each do |virtual_name, class_name, member, visibility, nesting|
             state[:records].concat(refinement_records(state, class_name, member, nil, virtual_name))
-            resolve_member(state, signature_members, [virtual_name, class_name, member, visibility])
+            resolve_member(state, signature_members, [virtual_name, class_name, member, visibility, nesting])
           end
           Resolution.new(
             records: state[:records].uniq.sort_by { |r| record_sort_key(r) }.freeze,
@@ -159,11 +162,57 @@ module Rigor
           end
         end
 
+        # Issue #2440 — every key one RBS member contributes to a definition build: its method keys
+        # ({.member_method_keys}) and, for an instance variable (`@x: T`) or a class instance variable
+        # (`self.@x: T`), `[:@x, :instance_variable]` / `[:@x, :class_instance_variable]`. rbs 4.2 raises
+        # `InstanceVariableDuplicationError` / `ClassInstanceVariableDuplicationError` for two of those in one
+        # class even when the types agree, so a `sig/` and an inline declaration of one has to be reconciled
+        # like a method. A method name never starts with `@`, so the two key spaces cannot meet. A class
+        # variable (`@@x`) contributes nothing: rbs does not reject a duplicate. Neither does an attribute's
+        # implied instance variable, which rbs lets an explicit `@x` declaration override.
+        #
+        # A mixin (`include M`, `extend M`, `prepend M`) is keyed by the lexical nesting of the declaration
+        # it sits in and the module and type arguments exactly as written, `[:"A/C|M[String]", :include]`:
+        # rbs 4.2 counts every instance variable `M` declares once per declaration of the class that mixes it
+        # in, so the same `include M` in `sig/` and inline raises `InstanceVariableDuplicationError ... in ::M`
+        # for the class. A relative name resolves through the nesting it is written in, so `include M` inside
+        # `module A; class C` (`A::M` when that exists) and inside `class A::C` (`::M`) are different mixins,
+        # and so are `M` and `::M`; only an identical spelling in an identical nesting is the same member and
+        # stands down. `rbs-inline --output` mirrors the Ruby file's nesting, so its committed output still
+        # pairs with the inline buffer. A mixin with different arguments keys differently and is left alone.
+        # Two members sharing a mixin key declare no method types to compare, so they read as equal.
+        #
+        # `nesting` is the declaration names as written, outermost first, joined by `/`
+        # ({RbsLoader.each_declared_member}); nil keys a mixin by its spelling alone.
+        #
+        # Kept apart from {.member_method_keys} on purpose: the plugin-signature plans key collisions by
+        # method only, and this rule is the inline-vs-`sig/` one.
+        def member_keys(member, nesting = nil)
+          case member
+          when ::RBS::AST::Members::InstanceVariable then [[member.name, :instance_variable]]
+          when ::RBS::AST::Members::ClassInstanceVariable then [[member.name, :class_instance_variable]]
+          when ::RBS::AST::Members::Include then [[mixin_key(member, nesting), :include]]
+          when ::RBS::AST::Members::Extend then [[mixin_key(member, nesting), :extend]]
+          when ::RBS::AST::Members::Prepend then [[mixin_key(member, nesting), :prepend]]
+          else member_method_keys(member)
+          end
+        end
+
+        # Whether a key `kind` names a variable rather than a method.
+        def variable_kind?(kind)
+          VARIABLE_KINDS.include?(kind)
+        end
+
         private
 
+        def mixin_key(member, nesting)
+          args = member.args.empty? ? "" : "[#{member.args.join(', ')}]"
+          :"#{nesting}|#{member.name}#{args}"
+        end
+
         def resolve_member(state, signature_members, inline)
-          _virtual_name, class_name, member, = inline
-          overlapping = member_method_keys(member).filter_map do |method_name, kind|
+          _virtual_name, class_name, member, _visibility, nesting = inline
+          overlapping = member_keys(member, nesting).filter_map do |method_name, kind|
             key = [class_name, method_name, kind]
             owner = signature_members[key]
             owner && [key, *owner]
@@ -235,7 +284,7 @@ module Rigor
         end
 
         def full_keys(class_name, member)
-          member_method_keys(member).map { |method_name, kind| [class_name, method_name, kind] }
+          member_keys(member).map { |method_name, kind| [class_name, method_name, kind] }
         end
 
         # The `.rbs` line is read only for an outcome that reports it: asking an `RBS::Buffer` for a line

data/lib/rigor/environment/missing_gem_constant_index.rb

@@ -107,8 +107,9 @@ module Rigor
       # difference is worth stating because the two look like the same problem. There, a stale
       # `bundler/gems/` directory left behind by a gem that moved to a released version made the loader
       # load the WRONG SIGNATURES, collapsing the RBS environment. Here the index's whole output is a gem
-      # NAME, so reading a stale checkout of the same gem yields the same answer; and the rubygems lookup
-      # is consulted FIRST in {.build}, so a gem now installed from RubyGems never reaches this map at all.
+      # NAME, so reading a stale checkout of the same gem yields the same answer; and the RubyGems-layout
+      # bundle directory is consulted FIRST in {.build}, so a gem installed from RubyGems at its locked
+      # version never reaches this map.
       def git_gem_dirs(bundle_path)
         return {} if bundle_path.nil?