rigortype 0.3.2 → 0.3.4

data/lib/rigor/plugin.rb

@@ -15,6 +15,7 @@ require_relative "plugin/load_error"
 require_relative "plugin/box"
 require_relative "plugin/isolation"
 require_relative "plugin/inflector"
+require_relative "plugin/first_party"
 
 module Rigor
   module Plugin

data/lib/rigor/protection/closure_kill_oracle.rb

@@ -4,6 +4,7 @@ require "tempfile"
 
 require_relative "../analysis/buffer_binding"
 require_relative "../analysis/runner"
+require_relative "../inference/fork_map"
 require_relative "diagnostic_oracle"
 require_relative "discovery_seed"
 require_relative "kill_signature"
@@ -111,6 +112,18 @@ module Rigor
         [path, *(@dependents[path] || [])]
       end
 
+      # Release the process-private mutant file now, instead of waiting for `Tempfile`'s finalizer at process
+      # exit. A one-shot `rigor coverage` run does not need this — the process ends and the file goes with it —
+      # but a caller that outlives the oracle does: the spec suite's `after(:suite)` residue check (issue #330)
+      # runs while the process is still alive, so an un-released file reads as a leak there even though it
+      # would have been reclaimed a moment later. Idempotent, and safe on an oracle that never mutated
+      # anything (the file is created lazily).
+      def release!
+        @mutant_file&.close!
+        @mutant_file = nil
+        @mutant_pid = nil
+      end
+
       private
 
       # The diagnostic signatures the dependents of `path` report while `source` stands in for it. Empty (and
@@ -136,11 +149,17 @@ module Rigor
 
       # The process-private mutant file. Created lazily, and re-created after a fork ({CLI::MutationForkScan}
       # workers must not share one path), which the pid guard detects.
+      #
+      # A worker's copy goes in {Inference::ForkMap.child_scratch_dir} rather than the system temp dir: the
+      # worker ends at `exit!`, which runs neither `at_exit` nor `Tempfile`'s finalizer, so a file placed
+      # anywhere else survives the run with nobody left who knows its name (issue #330). On the parent — and
+      # on the sequential path — that reader answers `nil`, which is `Tempfile.new`'s own default, and the
+      # finalizer reclaims the file at normal exit as before.
       def mutant_file
         return @mutant_file if @mutant_file && @mutant_pid == Process.pid
 
         @mutant_pid = Process.pid
-        @mutant_file = Tempfile.new(["rigor-mutant-", ".rb"])
+        @mutant_file = Tempfile.new(["rigor-mutant-", ".rb"], Inference::ForkMap.child_scratch_dir)
       end
 
       def seed_for(buffer)

data/lib/rigor/rbs_extended/envelope_scanner.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+require_relative "../rbs_extended"
+require_relative "reporter"
+
+module Rigor
+  module RbsExtended
+    # Collects every effect envelope the project's own RBS declares (ADR-103 WD5 / WD14; #383).
+    #
+    # It produces values, never diagnostics — the check that compares a bound against the proven
+    # summaries is {Rigor::Effects::EnvelopeCheck}. Two tables come out, because they are consumed
+    # differently:
+    #
+    # - {Result#method_envelopes} — keyed by method key (`Class#m` / `Class.m`), applied as written.
+    # - {Result#class_envelopes} — keyed by class / module name, DISTRIBUTED by the check to every
+    #   method of that Ruby class discovery knows (reopenings, other files, synthesized `attr_*` and
+    #   `define_method` members), never to subclasses. A per-method envelope wins over a distributed
+    #   one; nearest wins, and no `-except` syntax is needed.
+    #
+    # ## Why it parses rather than reading the built environment
+    #
+    # {ConformanceChecker}, the obvious model, walks `RbsLoader`'s built env. An envelope cannot: the
+    # diagnostic has to name **where the bound was written** (`sig/foo.rbs:12`), and the ADR-54 env
+    # cache dumps every `RBS::Location` to a zero-range `<cached>` sentinel, so a warm run would lose
+    # both the position and the only evidence of which file a declaration came from. Parsing the
+    # project's own signature sources is a few milliseconds over a tree Rigor already globs, it is
+    # identical warm and cold, and it enforces ADR-103 WD6's trust rule structurally: a `%a{pure}` in
+    # rbs core or in a gem's shipped RBS is never read, so it cannot bound a project method that
+    # happens to share its key.
+    #
+    # Malformed payloads and `pure`-versus-`effect` contradictions are recorded on a {Reporter} the
+    # scanner owns and ride out on {Result#unresolved}. They surface no diagnostic in this slice:
+    # `effect.unknown-label` and the annotation-in-a-project-without-`effects:` residual are #384's.
+    module EnvelopeScanner
+      Result = Data.define(:method_envelopes, :class_envelopes, :unresolved) do
+        def empty? = method_envelopes.empty? && class_envelopes.empty?
+      end
+
+      EMPTY = Result.new(method_envelopes: {}.freeze, class_envelopes: {}.freeze, unresolved: [].freeze)
+
+      # RBS's kind for a `def self?.x` member — it declares BOTH sides, so the envelope binds both.
+      SINGLETON_INSTANCE = :singleton_instance
+      private_constant :SINGLETON_INSTANCE
+
+      module_function
+
+      # @param sources [Array<Array(String, String)>] `[buffer name, RBS source]` pairs — the project's
+      #   `.rbs` files, plus the virtual entries rbs-inline and plugin `source_rbs` synthesis contribute.
+      # @param registry [Rigor::Effects::Registry] the vocabulary an unknown label is judged against.
+      # @return [Result]
+      def scan(sources:, registry:)
+        reporter = Reporter.new
+        methods = {}
+        classes = {}
+        sources.each do |name, content|
+          declarations(name, content).each do |decl|
+            walk(decl, [], methods, classes, registry, reporter)
+          end
+        end
+        Result.new(
+          method_envelopes: methods.freeze, class_envelopes: classes.freeze,
+          unresolved: reporter.unresolved_payloads
+        )
+      rescue StandardError
+        EMPTY
+      end
+
+      # The **accepted-signature** reader: every per-method envelope declared anywhere in a BUILT
+      # `RBS::Environment` — a gem's shipped signatures, Rigor's bundled overlays, core RBS
+      # (ADR-103 WD6; #386).
+      #
+      # It exists for one purpose and is usable for exactly one: importing a `≤` bound at a call site
+      # that resolves into un-analysed code ({Rigor::Effects::EnvelopeIndex}). It MUST NOT feed a
+      # contract check. Two facts make that a structural guarantee rather than a convention —
+      # {.scan}, which the check reads, never opens this door, and the values here carry no
+      # `location` at all (the ADR-54 env cache dumps every `RBS::Location` to a `<cached>` sentinel,
+      # so a warm run could not name where the bound was written even if a diagnostic wanted to).
+      # There is also no body to check: a gem method is un-analysed by definition, which is why WD6
+      # trusts the declaration instead, exactly as it already trusts the gem's *types*.
+      #
+      # Class-level annotations are deliberately not read. Distribution needs "every method of the
+      # class discovery knows", which is a project fact; a gem's class-level tag would have to
+      # distribute over a definition set this reader does not have.
+      #
+      # @param loader [Rigor::Environment::RbsLoader] the run's loader; it owns the env walk
+      #   ({Rigor::Environment::RbsLoader#each_annotated_method_member}), so the environment itself never
+      #   leaves it.
+      # @param registry [Rigor::Effects::Registry]
+      # @return [Hash{String => Rigor::Effects::Envelope}] keyed `Class#m` / `Class.m`
+      def from_loader(loader:, registry:)
+        out = {}
+        loader.each_annotated_method_member do |class_name, member|
+          keys_for(class_name, member).each do |key|
+            next if out.key?(key)
+
+            envelope = RbsExtended.read_effect_envelope(
+              member.annotations, owner_key: key, source: :effect_annotation, registry: registry
+            )
+            out[key] = envelope if envelope
+          end
+        end
+        out.freeze
+      rescue StandardError
+        {}.freeze
+      end
+
+      # Fail-soft per file: an unparseable `.rbs` is already quarantined by the loader and reported as
+      # `rbs.coverage.quarantined-signature`; contributing no envelope is the consistent answer here.
+      def declarations(name, content)
+        _, _, decls = ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: name, content: content))
+        decls || []
+      rescue StandardError
+        []
+      end
+
+      # Descends the declaration tree, carrying the lexical prefix so a nested `class Bar` inside
+      # `module Foo` keys as `Foo::Bar` — the same spelling the effects scanner gives its units.
+      def walk(decl, prefix, methods, classes, registry, reporter)
+        return unless decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
+
+        nested = prefix + [decl.name.to_s.sub(/\A::/, "")]
+        class_name = nested.join("::")
+        envelope = RbsExtended.read_effect_envelope(
+          decl.annotations, owner_key: class_name, source: :class_annotation,
+                            registry: registry, reporter: reporter
+        )
+        classes[class_name] = envelope if envelope
+        decl.members.each { |member| absorb_member(member, nested, methods, classes, registry, reporter) }
+      end
+
+      def absorb_member(member, prefix, methods, classes, registry, reporter)
+        return walk(member, prefix, methods, classes, registry, reporter) unless
+          member.is_a?(::RBS::AST::Members::MethodDefinition)
+        return if member.annotations.nil? || member.annotations.empty?
+
+        keys_for(prefix.join("::"), member).each do |key|
+          envelope = RbsExtended.read_effect_envelope(
+            member.annotations, owner_key: key, source: :effect_annotation,
+                                registry: registry, reporter: reporter
+          )
+          methods[key] = envelope if envelope
+        end
+      end
+
+      # The effect-unit keys one RBS member declares. `def self?.x` declares both sides, so its
+      # envelope binds both; every other kind declares one.
+      def keys_for(class_name, member)
+        case member.kind
+        when :singleton then ["#{class_name}.#{member.name}"]
+        when SINGLETON_INSTANCE then ["#{class_name}##{member.name}", "#{class_name}.#{member.name}"]
+        else ["#{class_name}##{member.name}"]
+        end
+      end
+
+      private_class_method :declarations, :walk, :absorb_member, :keys_for
+    end
+  end
+end

data/lib/rigor/rbs_extended.rb

@@ -3,6 +3,10 @@
 require_relative "type"
 require_relative "builtins/imported_refinements"
 require_relative "flow_contribution"
+require_relative "effects/envelope"
+require_relative "effects/label"
+require_relative "effects/label_set"
+require_relative "effects/signature_sources"
 require_relative "rbs_extended/reporter"
 require_relative "rbs_extended/hkt_directives"
 
@@ -621,6 +625,170 @@ module Rigor
       facts.empty? ? nil : facts
     end
 
+    # ── Effect envelopes (ADR-103 WD1 / WD5 / WD14; #383) ──────────────────────────────────────────
+    #
+    # Two spellings reach the same value. `%a{pure}` is the ecosystem's existing purity annotation
+    # (rbs core and Steep both carry it) and reads as the EMPTY envelope; `%a{rigor:v1:effect …}` is
+    # Rigor's labelled bound. `rigor:v1:pure` is deliberately NOT implemented — WD14 fixed `%a{pure}`
+    # as the only purity spelling.
+
+    # The bare rbs-native purity annotation. Matched whole, with surrounding whitespace tolerated, so
+    # `%a{purely}` and `%a{pure io}` are not it.
+    PURE_ANNOTATION_PATTERN = /\A\s*pure\s*\z/
+    private_constant :PURE_ANNOTATION_PATTERN
+
+    # `%a{rigor:v1:effect io.db, nondet.time}` — a space-separated head (the `assert` / `conforms-to`
+    # family), then a comma-separated list of BARE label tokens. There is no parenthesised comment
+    # form: RBS has real comments. The payload group is optional so that `%a{rigor:v1:effect}` still
+    # MATCHES the directive and is reported as malformed rather than read as "not a directive".
+    EFFECT_DIRECTIVE_PATTERN = /\Arigor:v1:effect(?:\s+(?<labels>.*?))?\s*\z/
+    private_constant :EFFECT_DIRECTIVE_PATTERN
+
+    # The outcome of reading one `%a{rigor:v1:effect …}` payload.
+    #
+    # `bound` is the declared {Rigor::Effects::LabelSet}, or {Effects::LabelSet::TOP} when the tag
+    # could not be given a meaning. `malformed` says the grammar was violated (an empty list, a token
+    # that is not a label); `unknown_labels` says the grammar held but the registry does not
+    # recognise a spelling — a different condition with different handling, and what #384's
+    # `effect.unknown-label` reads. `labels` is the list exactly as written, recognised or not, which
+    # is what lets the diagnostic ask whether some OTHER member of the list was known.
+    EffectAnnotation = Data.define(:bound, :labels, :unknown_labels, :malformed) do
+      def malformed? = malformed
+      def top? = bound.top?
+    end
+
+    NO_EFFECT_LABELS = [].freeze
+    private_constant :NO_EFFECT_LABELS
+
+    # Whether `string` is the bare `%a{pure}` annotation.
+    def pure_annotation?(string)
+      !string.nil? && PURE_ANNOTATION_PATTERN.match?(string)
+    end
+
+    # Reads one annotation string as an effect-envelope payload.
+    #
+    # Returns `nil` when the string is not a `rigor:v1:effect` directive at all (so a caller can walk
+    # an annotation list without pre-filtering). Otherwise an {EffectAnnotation}:
+    #
+    # - well-formed and fully recognised → the declared bound;
+    # - malformed (empty list, a token outside the label grammar) → {Effects::LabelSet::TOP}, and a
+    #   `record_unresolved` event on `reporter`;
+    # - well-formed but carrying a spelling `registry` does not know → {Effects::LabelSet::TOP} and
+    #   the unrecognised spellings, because an unknown label makes the WHOLE tag ⊤ rather than the
+    #   subset that happened to parse. Narrowing to the recognised subset would turn a typo into
+    #   findings on correct code; widening suppresses them, which is the direction the false-positive
+    #   budget runs (ADR-5).
+    def parse_effect_annotation(string, registry: nil, reporter: nil, source_location: nil)
+      match = EFFECT_DIRECTIVE_PATTERN.match(string.to_s)
+      return nil if match.nil?
+
+      tokens = match[:labels].to_s.split(",", -1).map(&:strip)
+      if tokens.empty? || tokens.any? { |token| !Effects::Label.valid?(token) }
+        record_unresolved(reporter, string, source_location)
+        return EffectAnnotation.new(
+          bound: Effects::LabelSet::TOP, labels: NO_EFFECT_LABELS, unknown_labels: NO_EFFECT_LABELS, malformed: true
+        )
+      end
+
+      tokens = tokens.freeze
+      unknown = registry.nil? ? [] : tokens.reject { |token| registry.known?(token) }
+      EffectAnnotation.new(
+        bound: unknown.empty? ? Effects::LabelSet.new(tokens) : Effects::LabelSet::TOP,
+        labels: tokens, unknown_labels: unknown.uniq.sort.freeze, malformed: false
+      )
+    end
+
+    # Reads the effect envelope off an annotation list — `RBS::Definition::Method#annotations`, or the
+    # `#annotations` of an `RBS::AST::Members::MethodDefinition` / class declaration, which carry the
+    # same `(string, location)` shape.
+    #
+    # Precedence, per the spec: `%a{pure}` and `%a{rigor:v1:effect …}` on ONE declaration are
+    # contradictory and `pure` wins; the contradiction is recorded on `reporter` (the existing
+    # `RBS::Extended` conflict channel) rather than silently resolved. Returns `nil` when the list
+    # carries neither spelling.
+    #
+    # @param annotations [Array<#string>] the node's annotations, in source order.
+    # @param owner_key [String] the method key (`Class#m` / `Class.m`) or class name the bound binds.
+    # @param source [Symbol] {Effects::Envelope::SOURCES} member to stamp when the labelled spelling
+    #   matched; `%a{pure}` always stamps `:pure_annotation`, and a class-level read overrides both.
+    def read_effect_envelope(annotations, owner_key:, source: :effect_annotation, registry: nil, reporter: nil)
+      return nil if annotations.nil? || annotations.empty?
+
+      pure = annotations.find { |annotation| pure_annotation?(annotation.string) }
+      labelled = nil
+      parsed = nil
+      annotations.each do |annotation|
+        result = parse_effect_annotation(
+          annotation.string, registry: registry, reporter: reporter, source_location: annotation_location(annotation)
+        )
+        next if result.nil?
+
+        labelled = annotation
+        parsed = result
+        break
+      end
+      return nil if pure.nil? && labelled.nil?
+
+      if pure && labelled
+        record_unresolved(
+          reporter,
+          "`%a{pure}` and `%a{#{labelled.string}}` on one declaration are contradictory; `pure` wins",
+          annotation_location(pure)
+        )
+      end
+      return build_pure_envelope(pure, owner_key: owner_key, source: source) if pure
+
+      build_effect_envelope(labelled, parsed, owner_key: owner_key, source: source)
+    end
+
+    def build_pure_envelope(annotation, owner_key:, source:)
+      Effects::Envelope.build(
+        owner_key: owner_key,
+        bound: Effects::LabelSet::EMPTY,
+        source: source == :class_annotation ? :class_annotation : :pure_annotation,
+        location: render_annotation_location(annotation),
+        spelling: "%a{#{annotation.string}}"
+      )
+    end
+
+    def build_effect_envelope(annotation, parsed, owner_key:, source:)
+      Effects::Envelope.build(
+        owner_key: owner_key,
+        bound: parsed.bound,
+        source: source,
+        location: render_annotation_location(annotation),
+        spelling: "%a{#{annotation.string}}",
+        unknown_labels: parsed.unknown_labels,
+        declared_labels: parsed.labels
+      )
+    end
+
+    def annotation_location(annotation)
+      annotation.respond_to?(:location) ? annotation.location : nil
+    end
+
+    # `path:line` for the annotation, project-relative when it sits under the working directory, so a
+    # diagnostic message names `sig/foo.rbs:12` rather than an absolute path.
+    def render_annotation_location(annotation)
+      location = annotation_location(annotation)
+      return nil if location.nil?
+
+      buffer = location.respond_to?(:buffer) ? location.buffer : nil
+      name = buffer.respond_to?(:name) ? buffer.name.to_s : nil
+      return nil if name.nil? || name.empty?
+
+      line = location.respond_to?(:start_line) ? location.start_line : 1
+      "#{relative_annotation_path(name)}:#{line}"
+    rescue StandardError
+      nil
+    end
+
+    # The buffer-name → readable-path rule lives with the walk that produces the buffers
+    # ({Effects::SignatureSources}), so a `virtual:` name is stripped identically wherever it surfaces.
+    def relative_annotation_path(name)
+      Effects::SignatureSources.source_path(name)
+    end
+
     # ADR-13 slice 3b — guards every reporter call so the in-RbsExtended-module call sites can record events
     # uniformly without nil-checking each time. When the reporter is nil (the v0.1.0 → v0.1.3 default for call
     # sites that do not yet thread `environment:`), the call is a no-op and the parser stays fail-soft.

data/lib/rigor/reflection.rb

@@ -44,6 +44,10 @@ module Rigor
   # out of scope for the v0.0.7 first pass; v0.1.0's plugin API added it as a separate
   # concern.
   module Reflection
+    # #354 — thread-local slot for the per-run ancestor-scope memo. See {.ancestor_constant_scopes}.
+    ANCESTOR_SCOPES_KEY = :__rigor_ancestor_constant_scopes__
+    private_constant :ANCESTOR_SCOPES_KEY
+
     module_function
 
     # @param class_name [String, Symbol]
@@ -118,42 +122,139 @@ module Rigor
     # reads it to type a constant read, and `Inference::Narrowing` reads it to recognise a
     # value-pinned `Constant[Regexp]` match-predicate operand.
     def resolve_constant_type(name, scope: Scope.empty)
+      prefix = enclosing_class_path(scope)
+
+      # Step 1 — `Module.nesting`, innermost first. Each entry contributes only its OWN constants.
+      walker = prefix
+      while walker && !walker.empty?
+        hit = constant_type_at("#{walker}::#{name}", scope)
+        return hit if hit
+
+        idx = walker.rindex("::")
+        walker = idx ? walker[0, idx] : nil
+      end
+
+      # Step 2 (#354) — the ancestors of the innermost cresting scope, which Ruby consults BEFORE
+      # falling back to the top level. Skipping this step did not merely lose a resolution: when the
+      # same name also exists at top level, step 3 answered a lookup Ruby gives to the ancestor, so
+      # `KEY` inside `class Sub < Base` typed as the top-level constant rather than `Base::KEY` — a
+      # wrong type on correct code, which outranks any worst-case reading (AGENTS.md
+      # § "Implementation Guidelines"). Only project ancestors are walked; an RBS-known superclass
+      # contributes no name here (see {.ancestor_constant_scopes}).
+      if prefix
+        ancestor_constant_scopes(prefix, scope).each do |ancestor|
+          hit = constant_type_at("#{ancestor}::#{name}", scope)
+          return hit if hit
+        end
+      end
+
+      # Step 3 — the bare name (top level).
+      constant_type_at(name, scope)
+    end
+
+    # One candidate name, consulted in source-precedence order: the class registry (yielding a
+    # `Singleton[C]`), source-discovered classes, in-source value constants, then RBS-side
+    # constants. In-source values win over RBS constant decls because the user's source is
+    # authoritative for its own constants. Returns nil when no source knows `candidate`.
+    def constant_type_at(candidate, scope)
       env = scope.environment
-      discovered = scope.discovered_classes
-      in_source = scope.in_source_constants
-      lexical_constant_candidates(name, scope: scope).each do |candidate|
-        singleton = env.singleton_for_name(candidate)
-        return singleton if singleton
-
-        in_source_class = discovered[candidate]
-        return in_source_class if in_source_class
-
-        # In-source value-bearing constants take precedence over RBS constant decls because
-        # user code is the authoritative source for its own constants.
-        in_source_value = in_source[candidate]
-        return in_source_value if in_source_value
-
-        value = env.constant_for_name(candidate)
-        return value if value
+
+      singleton = env.singleton_for_name(candidate)
+      return singleton if singleton
+
+      in_source_class = scope.discovered_classes[candidate]
+      return in_source_class if in_source_class
+
+      in_source_value = scope.in_source_constants[candidate]
+      return in_source_value if in_source_value
+
+      env.constant_for_name(candidate)
+    end
+    private_class_method :constant_type_at
+
+    # #354 — the project classes and modules whose own constants `class_name` inherits, in Ruby's
+    # ancestor order: included / prepended modules before the superclass (Ruby places mixins nearer),
+    # transitively, breadth-first. `class_name` itself is excluded — step 1 already covered it.
+    #
+    # Only PROJECT ancestors appear. `Scope#superclass_of` / `#includes_of` carry as-written names
+    # from the discovery pre-pass, and an as-written name that resolves to no discovered class or
+    # module is dropped — so a `class Foo < ActiveRecord::Base` contributes nothing and a constant
+    # owned by an RBS-known ancestor still resolves only if the bare name reaches it at step 3. That
+    # gap is deliberate for this slice: widening to the RBS ancestor graph is a separate question
+    # with its own FP surface.
+    #
+    # Memoised per run because step 2 runs on every constant reference whose lexical candidates all
+    # miss — which is the common case for a core-class reference (`String` inside `class Foo`). The
+    # bucket keys on the identity of the runner-seeded run-generation token (ADR-84 WD2), falling
+    # back to the per-file discovery table for runner-less scopes, so a re-run in one process (LSP,
+    # ADR-62 warm loop) cannot hit stale entries.
+    def ancestor_constant_scopes(class_name, scope)
+      # ADR-46: `superclass_of` / `includes_of` record a cross-file class dependency per consumer
+      # file, and the memo is run-scoped rather than file-scoped — a hit would skip the recording and
+      # under-record the edge for every later file. Recording runs are rare (incremental only), so
+      # they simply bypass the memo rather than complicate its key.
+      return compute_ancestor_constant_scopes(class_name, scope) if Analysis::DependencyRecorder.active?
+
+      generation = scope.run_generation || scope.discovered_superclasses
+      slot = Thread.current[ANCESTOR_SCOPES_KEY]
+      unless slot && slot[0].equal?(generation)
+        slot = [generation, {}]
+        Thread.current[ANCESTOR_SCOPES_KEY] = slot
       end
-      nil
+      bucket = slot[1]
+      bucket.fetch(class_name) { bucket[class_name] = compute_ancestor_constant_scopes(class_name, scope) }
     end
+    private_class_method :ancestor_constant_scopes
 
-    # The candidate qualified names to try, in Ruby's lexical order: most-qualified first (the
-    # enclosing class path joined to `name`), then progressively less-qualified, then the bare
-    # `name`. A top-level scope (no `self_type`) yields only `[name]`.
-    def lexical_constant_candidates(name, scope: Scope.empty)
-      prefix = enclosing_class_path(scope)
-      candidates = []
-      while prefix && !prefix.empty?
-        candidates << "#{prefix}::#{name}"
-        idx = prefix.rindex("::")
-        prefix = idx ? prefix[0, idx] : nil
+    def compute_ancestor_constant_scopes(class_name, scope)
+      queue = [class_name]
+      seen = { class_name => true }
+      out = []
+      until queue.empty?
+        current = queue.shift
+        # Mixins first, then the superclass — Ruby's ancestor order.
+        scope.includes_of(current).each do |raw|
+          resolved = resolve_ancestor_name(current, raw, scope)
+          next if resolved.nil? || seen[resolved]
+
+          seen[resolved] = true
+          out << resolved
+          queue << resolved
+        end
+        raw_super = scope.superclass_of(current)
+        next if raw_super.nil?
+
+        resolved_super = resolve_ancestor_name(current, raw_super, scope)
+        next if resolved_super.nil? || seen[resolved_super]
+
+        seen[resolved_super] = true
+        out << resolved_super
+        queue << resolved_super
+      end
+      out.freeze
+    end
+    private_class_method :compute_ancestor_constant_scopes
+
+    # Resolves an ancestor name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) against the
+    # subclass's lexical nesting, innermost first — the same walk
+    # `ExpressionTyper#compute_ancestor_class_name` performs for method lookup. Returns nil when no
+    # candidate names a discovered project class or module.
+    def resolve_ancestor_name(subclass_qualified, raw, scope)
+      segments = subclass_qualified.split("::")
+      (segments.length - 1).downto(0) do |i|
+        candidate = (segments[0, i] + [raw]).join("::")
+        return candidate if known_project_namespace?(candidate, scope)
       end
-      candidates << name
-      candidates
+      nil
+    end
+    private_class_method :resolve_ancestor_name
+
+    def known_project_namespace?(name, scope)
+      scope.discovered_superclasses.key?(name) ||
+        scope.discovered_includes.key?(name) ||
+        scope.discovered_classes.key?(name)
     end
-    private_class_method :lexical_constant_candidates
+    private_class_method :known_project_namespace?
 
     # Pulls the enclosing qualified class name out of `scope.self_type` when one is set.
     # `Nominal[T]` and `Singleton[T]` both expose `class_name`. Returns nil at the top level.