rigortype 0.4.1 → 0.4.2

data/plugins/rigor-minitest/lib/rigor/plugin/minitest/assertion_analyzer.rb

@@ -18,7 +18,7 @@ module Rigor
       #   assert_kind_of(T, x)        →  narrow x to T
       #   assert_instance_of(T, x)    →  narrow x to T
       #   assert_nil(x)               →  narrow x to Constant<nil>
-      #   assert_equal(literal, x)    →  narrow x to Constant<literal>
+      #   assert_equal(literal, x)    →  meet x with Constant<literal> (see "Equality is not identity")
       #   assert_match(regex, x)      →  narrow x to String
       #
       # ### (2) Minitest / Test::Unit `refute_*` / `assert_not_*` (negative) ###
@@ -26,7 +26,7 @@ module Rigor
       #   refute_kind_of(T, x)        →  narrow x AWAY from T
       #   refute_instance_of(T, x)    →  narrow x AWAY from T
       #   refute_nil(x)               →  narrow x AWAY from nil
-      #   refute_equal(literal, x)    →  narrow x AWAY from Constant<literal>
+      #   refute_equal(literal, x)    →  negative Constant<literal> fact (the engine keeps x unchanged)
       #
       # Test::Unit's `assert_not_nil(x)` / `assert_not_equal(...)` / `assert_not_kind_of(...)` /
       # `assert_not_instance_of(...)` share the recognizer with `refute_*` (they're aliases).
@@ -36,7 +36,7 @@ module Rigor
       #   _(x).must_be_kind_of(T)     →  narrow x to T
       #   _(x).must_be_instance_of(T) →  narrow x to T
       #   _(x).must_be_nil            →  narrow x to Constant<nil>
-      #   _(x).must_equal(literal)    →  narrow x to Constant<literal>
+      #   _(x).must_equal(literal)    →  meet x with Constant<literal> (see "Equality is not identity")
       #   _(x).must_match(regex)      →  narrow x to String
       #
       # The legacy bare `x.must_be_kind_of(T)` form (Minitest < 6.0 monkey-patched onto Object) is
@@ -48,7 +48,25 @@ module Rigor
       #
       #   _(x).wont_be_kind_of(T)     →  narrow x AWAY from T
       #   _(x).wont_be_nil            →  narrow x AWAY from nil
-      #   _(x).wont_equal(literal)    →  narrow x AWAY from Constant<literal>
+      #   _(x).wont_equal(literal)    →  negative Constant<literal> fact (the engine keeps x unchanged)
+      #
+      # ## Equality is not identity
+      #
+      # Both `assert_equal(exp, act)` and `_(act).must_equal(exp)` pass when `exp == act`, with the literal as
+      # the receiver. A positive equality fact never replaces the local's type (issue #1678):
+      #
+      # - `nil` / `true` / `false` / Symbol literals inherit identity `==` (`BasicObject#==`, `Symbol#==`),
+      #   so `exp == act` holds only for the literal object itself and the local narrows to it.
+      # - Integer, Float and String literals compare across classes: `Integer#==` and `Float#==` defer to
+      #   `act == exp` for a non-numeric argument (a `ModInt` with its own `==` passes `assert_equal 9, m`),
+      #   numerics compare by value (`1 == 1.0`, `1 == 1r`, `0.0 == -0.0`), and `String#==` defers to
+      #   `act == exp` for an argument that responds to `to_str`. The local narrows only when every member of
+      #   its current type is already of the literal's own class, or a `nil` / boolean / Symbol the literal
+      #   cannot equal; it is then a meet (`Integer` or `0..9` to `Constant<9>`, `1 | 2` to `Constant<2>`).
+      #   A `Dynamic` local, a member of any other class, and a `0.0` literal keep the local unchanged.
+      #
+      # The negative forms emit a negative `Constant` fact, which the engine's fact narrowing does not act
+      # on, so `refute_equal` / `wont_equal` leave the local unchanged.
       #
       # ## Not yet recognised
       #
@@ -59,12 +77,14 @@ module Rigor
       module AssertionAnalyzer
         module_function
 
-        def contribution_for(call_node, environment:)
+        # @param scope — the scope at the call, or nil. The environment resolves class arguments; the local's
+        #   current type decides whether an equality assertion narrows (nil scope: only identity literals do).
+        def contribution_for(call_node, scope:)
           return nil unless call_node.is_a?(Prism::CallNode)
 
           fact =
-            assert_form_fact(call_node, environment: environment) ||
-            spec_form_fact(call_node, environment: environment)
+            assert_form_fact(call_node, scope: scope) ||
+            spec_form_fact(call_node, scope: scope)
           return nil if fact.nil?
 
           Rigor::FlowContribution.new(post_return_facts: [fact])
@@ -96,7 +116,7 @@ module Rigor
         Ractor.make_shareable(ASSERT_FORM)
         private_constant :ASSERT_FORM
 
-        def assert_form_fact(call_node, environment:)
+        def assert_form_fact(call_node, scope:)
           return nil unless call_node.receiver.nil?
 
           shape_negative = ASSERT_FORM[call_node.name]
@@ -104,7 +124,7 @@ module Rigor
 
           shape, negative = shape_negative
           args = call_node.arguments&.arguments || []
-          fact_for_shape(shape, args, negative: negative, environment: environment)
+          fact_for_shape(shape, args, negative: negative, scope: scope)
         end
 
         # --- _(x).must_* / .wont_* form ---
@@ -134,7 +154,7 @@ module Rigor
         # `narrowing_facts methods:` gate.
         SUPPORTED_METHODS = (ASSERT_FORM.keys + SPEC_MATCHER_FORM.keys).freeze
 
-        def spec_form_fact(call_node, environment:)
+        def spec_form_fact(call_node, scope:)
           shape_negative = SPEC_MATCHER_FORM[call_node.name]
           return nil if shape_negative.nil?
 
@@ -143,7 +163,7 @@ module Rigor
 
           shape, negative = shape_negative
           args = call_node.arguments&.arguments || []
-          fact_for_spec_shape(shape, target_local, args, negative: negative, environment: environment)
+          fact_for_spec_shape(shape, target_local, args, negative: negative, scope: scope)
         end
 
         # `_(x)` returns a `Minitest::Expectation` wrapping x. Some specs use `value(x)` or `expect(x)`
@@ -166,7 +186,8 @@ module Rigor
 
         # --- shape resolvers ---
 
-        def fact_for_shape(shape, args, negative:, environment:)
+        def fact_for_shape(shape, args, negative:, scope:)
+          environment = scope&.environment
           case shape
           when :class_then_local
             return nil unless args.size == 2
@@ -183,10 +204,7 @@ module Rigor
             return nil unless args.size == 2
             return nil unless args[1].is_a?(Prism::LocalVariableReadNode)
 
-            literal = literal_value_for(args[0])
-            return nil if literal.equal?(NO_LITERAL)
-
-            fact_for(args[1].name, Rigor::Type::Combinator.constant_of(literal), negative: negative)
+            equality_fact(args[1].name, args[0], negative: negative, scope: scope)
           when :regex_then_local
             return nil unless args.size == 2
             return nil unless args[1].is_a?(Prism::LocalVariableReadNode)
@@ -196,7 +214,8 @@ module Rigor
           end
         end
 
-        def fact_for_spec_shape(shape, target_local, args, negative:, environment:)
+        def fact_for_spec_shape(shape, target_local, args, negative:, scope:)
+          environment = scope&.environment
           case shape
           when :class_arg
             return nil unless args.size == 1
@@ -210,10 +229,7 @@ module Rigor
           when :literal_arg
             return nil unless args.size == 1
 
-            literal = literal_value_for(args[0])
-            return nil if literal.equal?(NO_LITERAL)
-
-            fact_for(target_local, Rigor::Type::Combinator.constant_of(literal), negative: negative)
+            equality_fact(target_local, args[0], negative: negative, scope: scope)
           when :regex_arg
             return nil unless args.size == 1
             return nil unless regex_literal?(args[0])
@@ -222,6 +238,99 @@ module Rigor
           end
         end
 
+        # --- equality (`assert_equal` / `must_equal` and their negations) ---
+
+        # Classes whose `==` is identity (`BasicObject#==`, or `Symbol#==`), so `literal == act` holds only
+        # for the literal object itself, whatever `act` is.
+        IDENTITY_EQUALITY_CLASSES = [NilClass, TrueClass, FalseClass, Symbol].freeze
+        Ractor.make_shareable(IDENTITY_EQUALITY_CLASSES)
+        private_constant :IDENTITY_EQUALITY_CLASSES
+
+        IDENTITY_EQUALITY_CLASS_NAMES = IDENTITY_EQUALITY_CLASSES.map(&:name).freeze
+        Ractor.make_shareable(IDENTITY_EQUALITY_CLASS_NAMES)
+        private_constant :IDENTITY_EQUALITY_CLASS_NAMES
+
+        # Marks a member whose equality with the literal cannot be decided, so the whole meet gives up.
+        UNDECIDED = Object.new.freeze
+        private_constant :UNDECIDED
+
+        def equality_fact(local_name, literal_node, negative:, scope:)
+          literal = literal_value_for(literal_node)
+          return nil if literal.equal?(NO_LITERAL)
+
+          constant = Rigor::Type::Combinator.constant_of(literal)
+          return fact_for(local_name, constant, negative: true) if negative
+          return fact_for(local_name, constant, negative: false) if identity_equality?(literal)
+
+          fact_for(local_name, equality_meet(scope&.local(local_name), literal), negative: false)
+        end
+
+        def identity_equality?(value)
+          IDENTITY_EQUALITY_CLASSES.any? { |klass| value.is_a?(klass) }
+        end
+
+        # The members of `current` that `literal == act` admits, or nil when any member's equality with the
+        # literal cannot be decided (a Dynamic, a class with its own `==`, a numeric of another class) or no
+        # member survives. `0.0 == -0.0`, so a zero Float literal does not pin the sign and never narrows.
+        def equality_meet(current, literal)
+          return nil if current.nil?
+          return nil if literal.is_a?(Float) && literal.zero?
+
+          kept = meet_members(current, literal)
+          return nil if kept.nil? || kept.empty?
+
+          Rigor::Type::Combinator.union(*kept)
+        end
+
+        def meet_members(type, literal)
+          members = type.is_a?(Rigor::Type::Union) ? type.members : [type]
+          kept = []
+          members.each do |member|
+            met = meet_member(member, literal)
+            return nil if met.equal?(UNDECIDED)
+
+            kept << met unless met.nil?
+          end
+          kept
+        end
+
+        # One member's part of the meet: the narrowed carrier, nil when no value of the member equals the
+        # literal, or UNDECIDED.
+        def meet_member(member, literal)
+          case member
+          when Rigor::Type::Constant then meet_constant(member, literal)
+          when Rigor::Type::Nominal then meet_nominal(member, literal)
+          when Rigor::Type::IntegerRange
+            return UNDECIDED unless literal.is_a?(Integer)
+
+            member.covers?(literal) ? Rigor::Type::Combinator.constant_of(literal) : nil
+          else UNDECIDED
+          end
+        end
+
+        def meet_constant(member, literal)
+          value = member.value
+          if value.instance_of?(literal.class)
+            value == literal ? member : nil
+          elsif identity_equality?(value)
+            nil
+          else
+            UNDECIDED
+          end
+        end
+
+        def meet_nominal(member, literal)
+          return UNDECIDED unless member.type_args.empty?
+
+          if member.class_name == literal.class.name
+            Rigor::Type::Combinator.constant_of(literal)
+          elsif IDENTITY_EQUALITY_CLASS_NAMES.include?(member.class_name)
+            nil
+          else
+            UNDECIDED
+          end
+        end
+
         def fact_for(local_name, type, negative:)
           return nil if type.nil?
 

data/plugins/rigor-minitest/lib/rigor/plugin/minitest.rb

@@ -61,12 +61,14 @@ module Rigor
       # ADR-37 slice 2 — emits `post_return_facts` for every recognised assertion, method-gated by the
       # engine. The engine routes `:local`-kind facts through `StatementEvaluator#apply_local_post_return_fact`.
       narrowing_facts methods: AssertionAnalyzer::SUPPORTED_METHODS do |call_node, scope|
-        AssertionAnalyzer.contribution_for(call_node, environment: scope&.environment)&.post_return_facts
+        AssertionAnalyzer.contribution_for(call_node, scope: scope)&.post_return_facts
       end
 
-      # ADR-88 WD1 — the narrowing facts this plugin contributes are derived purely from each assertion call's
-      # own AST at its call site (`assert_kind_of(String, x)` ⇒ `x` is `String` on the continuation); there is
-      # no cross-file catalog a cached diagnostic could depend on. A change to a file's assertions changes that
+      # ADR-88 WD1 — the narrowing facts this plugin contributes are derived from each assertion call's own AST
+      # at its call site (`assert_kind_of(String, x)` ⇒ `x` is `String` on the continuation) and, for
+      # `assert_equal` / `must_equal`, from the local's current type in the call's scope, which the engine
+      # derives and already tracks as a dependency; there is no cross-file catalog of the plugin's own that a
+      # cached diagnostic could depend on. A change to a file's assertions changes that
       # file's own content (re-analysed by the incremental graph already). A stable sentinel declares "no
       # cross-file fact surface", keeping the plugin incremental-capable (a contributing plugin with NO
       # fact / producer / hook makes the incremental snapshot un-reusable every run); `--verify-incremental`

data/plugins/rigor-pundit/lib/rigor/plugin/pundit/analyzer.rb

@@ -126,10 +126,10 @@ module Rigor
         end
 
         def literal_symbol_or_string(node)
-          case node
-          when Prism::SymbolNode then node.unescaped
-          when Prism::StringNode then node.unescaped
-          end
+          return nil unless node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+
+          # nil for bytes no Symbol holds: the name is later interned (`PolicyIndex#normalize`), which would raise.
+          Rigor::Source::SymbolName.of(node.unescaped)&.to_s
         end
 
         def constant_receiver_name(node)

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/analyzer.rb

@@ -237,7 +237,7 @@ module Rigor
             key_node = element.key
             case key_node
             when Prism::SymbolNode then key_node.unescaped.to_sym
-            when Prism::StringNode then key_node.unescaped.to_sym
+            when Prism::StringNode then Rigor::Source::Literals.symbol_or_string(key_node)
             end
           end
         end

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/routes_parser.rb

@@ -1184,7 +1184,7 @@ module Rigor
         def load_drawn_routes(node, context)
           return unless context.file_reader
 
-          name = symbol_argument(node, 0) || string_argument(node, 0)&.to_sym
+          name = symbol_argument(node, 0) || Rigor::Source::SymbolName.of(string_argument(node, 0))
           return unless name
 
           sub_contents = context.file_reader.call("#{name}.rb")

data/plugins/rigor-rbs-inline/lib/rigor/plugin/rbs_inline.rb

@@ -123,6 +123,7 @@ module Rigor
           return nil if source.empty?
 
           result = ::Prism.parse(source)
+          source, result = scrub_stray_comment_bytes(source, result)
           _, result = neutralize_rdoc_directives(source, result)
           return nil if !@require_magic_comment && !annotated?(result)
 
@@ -504,6 +505,36 @@ module Rigor
           end
         end
 
+        # A comment is not validated by Ruby, so a byte that is invalid in UTF-8 can sit in an ordinary one
+        # (`# caf\xFF`), and upstream's annotation grammar raises on it — which {#call}'s rescue would report as a
+        # `source-rbs-synthesis-failed` notice about "the inline-RBS comment grammar" for a file that has none.
+        # Such a comment is repaired in place (each bad byte becomes one `?`, so every offset stays identical) and
+        # the file re-parsed. A comment upstream would read as an annotation — exactly `#:`, `#[` and `#\s*@rbs`
+        # (rbs-inline `annotation_parser.rb`) — is left alone, so a genuinely corrupt annotation still reaches the
+        # WD6 fail-soft path. An RDoc directive (`#:nodoc:`) is not an annotation: {#neutralize_rdoc_directives}
+        # rewrites it, so it is repaired like any other comment.
+        STRAY_COMMENT_ANNOTATION = /\A#(?::|\[|\s*@rbs\b)/
+        private_constant :STRAY_COMMENT_ANNOTATION
+
+        def scrub_stray_comment_bytes(source, prism_result)
+          return [source, prism_result] if source.valid_encoding?
+
+          broken = prism_result.comments.reject { |comment| comment.location.slice.valid_encoding? }
+          annotation_like = broken.any? do |comment|
+            text = comment.location.slice.scrub
+            STRAY_COMMENT_ANNOTATION.match?(text) && !RDOC_DIRECTIVE_COMMENT.match?(text)
+          end
+          return [source, prism_result] if broken.empty? || annotation_like
+
+          bytes = source.b
+          broken.sort_by { |comment| -comment.location.start_offset }.each do |comment|
+            location = comment.location
+            bytes[location.start_offset, location.length] = location.slice.scrub { |run| "?" * run.bytesize }.b
+          end
+          repaired = bytes.force_encoding(source.encoding)
+          [repaired, ::Prism.parse(repaired)]
+        end
+
         # Rewrite every RDoc directive comment to its spaced spelling (`#:nodoc:` -> `# :nodoc:`) so
         # upstream's annotation grammar never sees it, and re-parse. Two reasons this happens here rather
         # than in {#annotated?}: the directive must not gate a file in, AND it must not reach the synthesis,

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_collector.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require "rigor/inference/declaration_walk"
+
+require_relative "serializer_index"
+
+module Rigor
+  module Plugin
+    class Typelizer < Rigor::Plugin::Base
+      # A {Rigor::Inference::DeclarationWalk} collector over one file: the classes it declares, and whether each
+      # one's own body says `include Typelizer::DSL` / `extend Typelizer::DSL`.
+      #
+      # A `module` that includes the DSL is deliberately not recorded: typelizer registers the module's own
+      # name and `target_serializers` then calls `.descendants` on it, which a plain Module lacks. A class that
+      # reaches the DSL through a module's `included do ... end` hook is a known missed root (see the README).
+      #
+      # Only a statement of the class body itself counts, because only there is `self` the class: the walk is
+      # over the body's own statements (through `if` / `unless` / `begin`), never into a `def`, a block, a
+      # lambda or a nested class, so `Class.new { include Typelizer::DSL }`, `Other.class_eval { include ... }`,
+      # `included do include Typelizer::DSL end` and a `def` that includes it credit nothing to the lexical
+      # class. A `class << self` body is a different node and is not entered either.
+      class SerializerCollector
+        include Rigor::Inference::DeclarationWalk::Collector
+
+        DSL_MODULE = "Typelizer::DSL"
+        DSL_CALLS = %i[include extend].freeze
+
+        def initialize
+          @entries = {}
+          @nestings = {}
+          @dsl = {}
+        end
+
+        def on_declaration(node, context, body_context)
+          return Rigor::Inference::DeclarationWalk::DESCEND unless node.is_a?(Prism::ClassNode)
+
+          name = body_context.prefix.join("::")
+          unless name.empty?
+            superclass = superclass_name(node.superclass)
+            @entries[name] = superclass if superclass || !@entries.key?(name)
+            @nestings[name] = context.nesting || []
+            @dsl[name] = true if dsl_in?(node.body) && !body_context.singleton_cref
+          end
+          Rigor::Inference::DeclarationWalk::DESCEND
+        end
+
+        # The classes this file declares, as {SerializerIndex::ClassEntry} values.
+        def class_entries
+          @entries.map do |name, superclass|
+            SerializerIndex::ClassEntry.new(
+              name: name, superclass: superclass, nesting: @nestings.fetch(name), dsl: @dsl.fetch(name, false),
+              in_dirs: false
+            )
+          end
+        end
+
+        private
+
+        # Whether a statement reachable without entering a def, block, lambda or nested declaration is a
+        # receiverless `include` / `extend` of the DSL module.
+        def dsl_in?(node)
+          case node
+          when Prism::StatementsNode then node.body.any? { |child| dsl_in?(child) }
+          when Prism::BeginNode then dsl_in?(node.statements) || dsl_in?(node.else_clause)
+          when Prism::ElseNode then dsl_in?(node.statements)
+          when Prism::IfNode then dsl_in?(node.statements) || dsl_in?(node.subsequent)
+          when Prism::UnlessNode then dsl_in?(node.statements) || dsl_in?(node.else_clause)
+          when Prism::CallNode then dsl_call?(node)
+          else false
+          end
+        end
+
+        def dsl_call?(node)
+          DSL_CALLS.include?(node.name) && node.receiver.nil? && node.block.nil? && dsl_argument?(node)
+        end
+
+        def dsl_argument?(node)
+          arguments = node.arguments&.arguments || []
+          arguments.any? { |argument| constant_name(argument)&.delete_prefix("::") == DSL_MODULE }
+        end
+
+        def superclass_name(node)
+          node && constant_name(node)
+        end
+
+        def constant_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parent = node.parent
+            return "::#{node.name}" if parent.nil?
+
+            prefix = constant_name(parent)
+            prefix && "#{prefix}::#{node.name}"
+          end
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_discoverer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require "rigor/inference/declaration_walk"
+
+require_relative "serializer_collector"
+require_relative "serializer_index"
+
+module Rigor
+  module Plugin
+    class Typelizer < Rigor::Plugin::Base
+      # Reads every `.rb` file under the configured typelizer dirs and the project's `paths:` through the plugin's `IoBoundary`, runs a
+      # {SerializerCollector} over each and merges the results into one {SerializerIndex}.
+      class SerializerDiscoverer
+        def initialize(io_boundary:, dirs:, project_paths: [])
+          @io_boundary = io_boundary
+          @dirs = dirs
+          @project_paths = project_paths
+        end
+
+        def discover
+          entries = []
+          dir_files = ruby_files_under(@dirs)
+          (dir_files | project_files).each do |path|
+            contents = read_safely(path)
+            next if contents.nil?
+
+            parsed = Prism.parse(contents)
+            next unless parsed.success?
+
+            collector = SerializerCollector.new
+            Rigor::Inference::DeclarationWalk.run(
+              parsed.value, [collector], Rigor::Inference::DeclarationWalk::Context.root(nesting: [])
+            )
+            in_dirs = dir_files.include?(path)
+            entries.concat(collector.class_entries.map { |entry| entry.with(in_dirs: in_dirs) })
+          end
+          SerializerIndex.new(classes: merge(entries))
+        end
+
+        private
+
+        # A class reopened across files: it registers with typelizer if any opening says so.
+        def merge(entries)
+          entries.group_by(&:name).map do |name, openings|
+            headed = openings.find(&:superclass) || openings.first
+            SerializerIndex::ClassEntry.new(
+              name: name, superclass: headed.superclass, nesting: headed.nesting,
+              dsl: openings.any?(&:dsl), in_dirs: openings.any?(&:in_dirs)
+            )
+          end
+        end
+
+        def read_safely(path)
+          @io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          nil
+        end
+
+        # The project's `paths:` entries: a directory contributes its `.rb` tree, a `.rb` file itself.
+        def project_files
+          @project_paths.flat_map do |entry|
+            absolute = File.expand_path(entry)
+            if @io_boundary.directory?(absolute)
+              Dir.glob(File.join(absolute, "**", "*.rb"))
+            elsif absolute.end_with?(".rb") && @io_boundary.file?(absolute)
+              [absolute]
+            else
+              []
+            end
+          end
+        end
+
+        def ruby_files_under(roots)
+          roots.flat_map do |root|
+            absolute = File.expand_path(root)
+            # ADR-45 WD1b (#613) — boundary-probed: a root that appears later invalidates the warm run.
+            next [] unless @io_boundary.directory?(absolute)
+
+            Dir.glob(File.join(absolute, "**", "*.rb"))
+          end
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_index.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    class Typelizer < Rigor::Plugin::Base
+      # The project's classes (every file of the project's `paths:` and the typelizer `dirs`), as the {SerializerCollector} found them. A frozen value
+      # object the `:serializer_index` producer caches.
+      #
+      # {#roots} answers the one question, conservatively — a wrong "no" costs a missing root, a wrong "yes"
+      # hides a dead class.
+      class SerializerIndex
+        # A class the project declares. `superclass` is the constant as written (`nil` when absent) and
+        # `nesting` the `Module.nesting` chain (innermost first) its header was written under, which is where
+        # Ruby resolves that constant. `dsl` is true when its body includes or extends `Typelizer::DSL`; `in_dirs` when a file under the
+        # typelizer `dirs` declares it (only such a class is published as a root).
+        ClassEntry = Data.define(:name, :superclass, :nesting, :dsl, :in_dirs)
+
+        def initialize(classes:)
+          @classes = classes.to_h { |entry| [entry.name, entry] }.freeze
+          freeze
+        end
+
+        def empty?
+          @classes.empty?
+        end
+
+        # Every class typelizer generates an interface for: a class that registered itself through the DSL, and
+        # each subclass of one (`Typelizer.target_serializers` takes `descendants`).
+        def roots
+          @classes.keys.select { |name| @classes[name].in_dirs && typelized?(name, {}) }.sort
+        end
+
+        private
+
+        def typelized?(name, seen)
+          entry = @classes[name]
+          return false if entry.nil? || seen[name]
+
+          seen[name] = true
+          return true if entry.dsl
+
+          parent = superclass_of(entry)
+          !parent.nil? && typelized?(parent, seen)
+        end
+
+        # Resolves the superclass as written the way Ruby does: against the `Module.nesting` chain of the header,
+        # innermost first, then the top level. A compact header (`class Admin::UserSerializer < Base`) does not
+        # put `Admin` on the chain, so `Base` is not looked up under it. The first match wins, so a class that
+        # shadows the DSL base (`Admin::Base` with no DSL) ends the walk there.
+        #
+        # Ruby also searches the ancestors of the innermost cref before the top level. That is not modelled, so a
+        # name that is not found on the lexical chain is declined (nil: not typelized) when the innermost scope
+        # is a class with a superclass, since the constant might live on that superclass.
+        def superclass_of(entry)
+          written = entry.superclass
+          return nil if written.nil?
+
+          if written.start_with?("::")
+            rooted = written.delete_prefix("::")
+            return @classes.key?(rooted) ? rooted : nil
+          end
+
+          lexical = entry.nesting.map { |scope| "#{scope}::#{written}" }.find { |name| @classes.key?(name) }
+          return lexical if lexical
+          return nil if cref_has_ancestors?(entry.nesting.first)
+
+          @classes.key?(written) ? written : nil
+        end
+
+        def cref_has_ancestors?(scope)
+          !scope.nil? && !@classes[scope]&.superclass.nil?
+        end
+      end
+    end
+  end
+end