type-guessr 0.0.1 → 0.0.3

data/lib/ruby_lsp/type_guessr/runtime_adapter.rb

@@ -1,14 +1,9 @@
 # frozen_string_literal: true
 
 require "prism"
-require_relative "../../type_guessr/core/converter/prism_converter"
-require_relative "../../type_guessr/core/index/location_index"
-require_relative "../../type_guessr/core/registry/method_registry"
-require_relative "../../type_guessr/core/registry/variable_registry"
-require_relative "../../type_guessr/core/inference/resolver"
-require_relative "../../type_guessr/core/signature_provider"
-require_relative "../../type_guessr/core/rbs_provider"
-require_relative "../../type_guessr/core/type_simplifier"
+require_relative "../../type_guessr/core"
+require_relative "dsl_type_registrar"
+require_relative "code_index_adapter"
 require_relative "type_inferrer"
 
 module RubyLsp
@@ -16,56 +11,52 @@ module RubyLsp
     # RuntimeAdapter manages the IR graph and inference for TypeGuessr
     # Converts files to IR graphs and provides type inference
     class RuntimeAdapter
-      attr_reader :signature_provider
+      attr_reader :signature_registry, :location_index, :resolver, :method_registry
 
       def initialize(global_state, message_queue = nil)
         @global_state = global_state
         @message_queue = message_queue
         @converter = ::TypeGuessr::Core::Converter::PrismConverter.new
         @location_index = ::TypeGuessr::Core::Index::LocationIndex.new
-        @signature_provider = build_signature_provider
         @indexing_completed = false
         @mutex = Mutex.new
         @original_type_inferrer = nil
 
-        # Create shared ancestry provider
-        ancestry_provider = ->(class_name) { get_class_ancestors(class_name) }
+        # Create CodeIndexAdapter wrapping RubyIndexer
+        @code_index = CodeIndexAdapter.new(global_state&.index)
 
-        # Create method registry with ancestry provider
+        # Create SignatureRegistry with code_index for ancestor chain traversal
+        @signature_registry = ::TypeGuessr::Core::Registry::SignatureRegistry.new(code_index: @code_index)
+        ::TypeGuessr::Core::Registry::SignatureRegistry.instance = @signature_registry
+
+        # Create method registry with code_index for inheritance lookup
         @method_registry = ::TypeGuessr::Core::Registry::MethodRegistry.new(
-          ancestry_provider: ancestry_provider
+          code_index: @code_index
+        )
+
+        # Create variable registries (ivar needs code_index for inheritance lookup)
+        @ivar_registry = ::TypeGuessr::Core::Registry::InstanceVariableRegistry.new(
+          code_index: @code_index
         )
+        @cvar_registry = ::TypeGuessr::Core::Registry::ClassVariableRegistry.new
 
-        # Create variable registry with ancestry provider
-        @variable_registry = ::TypeGuessr::Core::Registry::VariableRegistry.new(
-          ancestry_provider: ancestry_provider
+        # Create type simplifier with code_index for inheritance lookup
+        type_simplifier = ::TypeGuessr::Core::TypeSimplifier.new(
+          code_index: @code_index
         )
 
-        # Create resolver with injected registries
+        # Create resolver with signature_registry and registries
         @resolver = ::TypeGuessr::Core::Inference::Resolver.new(
-          @signature_provider,
+          @signature_registry,
+          code_index: @code_index,
           method_registry: @method_registry,
-          variable_registry: @variable_registry
+          ivar_registry: @ivar_registry,
+          cvar_registry: @cvar_registry,
+          type_simplifier: type_simplifier
         )
 
-        # Set up method list resolver callback
-        @resolver.method_list_resolver = ->(methods) { resolve_methods_to_class(methods) }
-
-        # Set up ancestry provider callback
-        @resolver.ancestry_provider = ancestry_provider
-
-        # Set up constant kind provider callback
-        @resolver.constant_kind_provider = ->(name) { get_constant_kind(name) }
-
-        # Set up class method lookup provider callback
-        @resolver.class_method_lookup_provider = lambda do |class_name, method_name|
-          lookup_class_method_owner(class_name, method_name)
-        end
-
-        # Set up type simplifier with ancestry provider
-        @resolver.type_simplifier = ::TypeGuessr::Core::TypeSimplifier.new(
-          ancestry_provider: ancestry_provider
-        )
+        # Build method signatures from DefNodes using resolver
+        @signature_builder = ::TypeGuessr::Core::SignatureBuilder.new(@resolver)
       end
 
       # Swap ruby-lsp's TypeInferrer with TypeGuessr's custom implementation
@@ -99,27 +90,9 @@ module RubyLsp
         file_path = uri.to_standardized_path
         return unless file_path
 
-        # Parse and convert to IR outside mutex
         parsed = document.parse_result
-        return unless parsed.value
-
-        # Create a shared context for all statements
-        context = ::TypeGuessr::Core::Converter::PrismConverter::Context.new
-        nodes = parsed.value.statements&.body&.filter_map do |stmt|
-          @converter.convert(stmt, context)
-        end
 
-        @mutex.synchronize do
-          # Clear existing index for this file
-          @location_index.remove_file(file_path)
-          @resolver.clear_cache
-
-          # Index all nodes recursively with scope tracking
-          nodes&.each { |node| index_node_recursively(file_path, node, "") }
-
-          # Finalize the index for efficient lookups
-          @location_index.finalize!
-        end
+        index_file_with_prism_result(file_path, parsed)
       rescue StandardError => e
         log_message("Error in index_file #{uri}: #{e.message}\n#{e.backtrace.first(5).join("\n")}")
       end
@@ -134,26 +107,26 @@ module RubyLsp
         file_path ||= uri_string.sub(%r{^file://}, "")
         return unless file_path
 
-        @mutex.synchronize do
-          # Clear existing index for this file
-          @location_index.remove_file(file_path)
-          @resolver.clear_cache
-
-          # Parse source code
-          parsed = Prism.parse(source)
-          return unless parsed.value
+        parsed = Prism.parse(source)
 
-          # Create a shared context for all statements
-          context = ::TypeGuessr::Core::Converter::PrismConverter::Context.new
+        index_file_with_prism_result(file_path, parsed)
+      end
 
-          # Convert statements to IR nodes and index with scope tracking
-          parsed.value.statements&.body&.each do |stmt|
-            node = @converter.convert(stmt, context)
-            index_node_recursively(file_path, node, "") if node
-          end
+      # Build member_index for duck type resolution (exposed for testing)
+      def build_member_index!
+        @code_index.build_member_index!
+      end
 
-          # Finalize the index for efficient lookups
-          @location_index.finalize!
+      # Remove indexed data for a file
+      # @param file_path [String] File path to remove
+      def remove_indexed_file(file_path)
+        @mutex.synchronize do
+          @location_index.remove_file(file_path)
+          @method_registry.remove_file(file_path)
+          @ivar_registry.remove_file(file_path)
+          @cvar_registry.remove_file(file_path)
+          @resolver.clear_cache
+          @code_index.refresh_member_index!(URI::Generic.from_path(path: file_path))
         end
       end
 
@@ -175,6 +148,51 @@ module RubyLsp
         end
       end
 
+      # Build a MethodSignature from a DefNode
+      # @param def_node [TypeGuessr::Core::IR::DefNode] Method definition node
+      # @return [TypeGuessr::Core::Types::MethodSignature] Structured method signature
+      def build_method_signature(def_node)
+        @mutex.synchronize do
+          @signature_builder.build_from_def_node(def_node)
+        end
+      end
+
+      # Build a constructor signature for Class.new calls
+      # Maps .new to #initialize and returns ClassName instance
+      # Checks project methods first, then falls back to RBS
+      # @param class_name [String] Class name (e.g., "User")
+      # @return [Hash] { signature: MethodSignature, source: :project | :rbs | :default }
+      def build_constructor_signature(class_name)
+        @mutex.synchronize do
+          instance_type = ::TypeGuessr::Core::Types::ClassInstance.for(class_name)
+
+          # 1. Try project methods first
+          init_def = @method_registry.lookup(class_name, "initialize")
+          if init_def
+            sig = @signature_builder.build_from_def_node(init_def)
+            return {
+              signature: ::TypeGuessr::Core::Types::MethodSignature.new(sig.params, instance_type),
+              source: :project
+            }
+          end
+
+          # 2. Fall back to RBS
+          rbs_sigs = @signature_registry.get_method_signatures(class_name, "initialize")
+          if rbs_sigs.any?
+            return {
+              rbs_signature: rbs_sigs.first,
+              source: :rbs
+            }
+          end
+
+          # 3. Default: no initialize found
+          {
+            signature: ::TypeGuessr::Core::Types::MethodSignature.new([], instance_type),
+            source: :default
+          }
+        end
+      end
+
       # Look up a method definition by class name and method name
       # @param class_name [String] Class name (e.g., "User", "Admin::User")
       # @param method_name [String] Method name (e.g., "initialize", "save")
@@ -185,35 +203,17 @@ module RubyLsp
         end
       end
 
-      # Resolve method list to a type (for use during inference)
-      # @param methods [Array<Symbol>] Method names called on the parameter
-      # @return [Type, nil] Resolved type or nil if not resolvable
-      def resolve_methods_to_class(methods)
-        matching_classes = find_classes_defining_methods(methods)
-        @resolver.classes_to_type(matching_classes)
+      # Check if a method should skip stdlib/gem RBS lookup in hover.
+      # Returns true for entries registered by DSL adapters (e.g., AR column accessor)
+      # so that hover goes directly to the resolver fallback instead of showing RBS signatures.
+      def skip_stdlib_rbs_method?(class_name, method_name)
+        entry = @signature_registry.lookup(class_name, method_name)
+        entry.is_a?(::TypeGuessr::Core::Registry::SignatureRegistry::GemMethodEntry) && entry.skip_stdlib_rbs?
       end
 
-      # Find classes that define all given methods
-      def find_classes_defining_methods(methods)
-        return [] if methods.empty?
-
-        index = @global_state.index
-        return [] unless index
-
-        # For each method, find classes that define it using fuzzy_search
-        method_sets = methods.map do |method_name|
-          entries = index.fuzzy_search(method_name.to_s) do |entry|
-            entry.is_a?(RubyIndexer::Entry::Method) && entry.name == method_name.to_s
-          end
-          entries.filter_map do |entry|
-            entry.owner.name if entry.respond_to?(:owner) && entry.owner
-          end.uniq
-        end
-
-        return [] if method_sets.empty? || method_sets.any?(&:empty?)
-
-        # Find intersection - classes that define ALL methods
-        method_sets.reduce(:&) || []
+      def skip_stdlib_rbs_class_method?(class_name, method_name)
+        entry = @signature_registry.lookup_class_method(class_name, method_name)
+        entry.is_a?(::TypeGuessr::Core::Registry::SignatureRegistry::GemMethodEntry) && entry.skip_stdlib_rbs?
       end
 
       # Start background indexing of all project files
@@ -224,34 +224,48 @@ module RubyLsp
           # Wait for Ruby LSP's initial indexing to complete
           log_message("Waiting for Ruby LSP initial indexing to complete...")
           sleep(0.1) until index.initial_indexing_completed
-          log_message("Ruby LSP indexing completed. Starting TypeGuessr file indexing.")
+          log_message("Ruby LSP indexing completed.")
 
-          # Get all indexable files (project + gems)
-          indexable_uris = index.configuration.indexable_uris
-          total = indexable_uris.size
-          log_message("Found #{total} files to process.")
+          # Preload RBS signatures while waiting for other addons to finish
+          @signature_registry.preload
 
-          # Index each file with progress reporting
-          processed = 0
-          last_report = 0
-          report_interval = [total / 10, 50].max
+          # Wait for other addons (ruby-lsp-rails, etc.) to finish registering entries
+          wait_for_index_stabilization(index)
 
-          indexable_uris.each do |uri|
-            traverse_file(uri)
-            processed += 1
+          # Build member_index AFTER all entries are registered
+          @code_index.build_member_index!
+          log_message("Member index built.")
 
-            next unless processed - last_report >= report_interval
+          # Get all indexable files (project + gems)
+          indexable_uris = index.configuration.indexable_uris
+          file_paths = indexable_uris.filter_map(&:to_standardized_path)
+          total = file_paths.size
+          log_message("Found #{total} files to process.")
 
-            percent = (processed * 100.0 / total).round(1)
-            log_message("Indexing progress: #{processed}/#{total} (#{percent}%)")
-            last_report = processed
+          # Try cache-first flow if Gemfile.lock exists
+          lockfile_path = find_lockfile
+          result = nil
+          if lockfile_path
+            result = index_with_gem_cache(file_paths, lockfile_path)
+          else
+            index_all_files(file_paths)
           end
+          # Connect on-demand inference callback for Unguessed gem methods
+          @signature_registry.on_demand_inferrer = method(:infer_gem_file_on_demand)
 
-          # Finalize the index ONCE after all files are processed
-          @mutex.synchronize { @location_index.finalize! }
+          # Register DSL types (AR column accessors, enums, associations, scopes)
+          register_dsl_types
 
-          log_message("File indexing completed. Processed #{total} files.")
           @indexing_completed = true
+
+          # Start schema watch loop for auto-refresh
+          start_schema_watch_loop
+
+          # Background inference: fully infer gems that have Unguessed entries (opt-in)
+          if ::TypeGuessr::Core::Config.background_gem_indexing? && result && result[:unguessed_gems].any?
+            background_infer_gems(result[:unguessed_gems],
+                                  result[:cache])
+          end
         rescue StandardError => e
           log_message("Error during file indexing: #{e.message}\n#{e.backtrace.first(10).join("\n")}")
           @indexing_completed = true
@@ -269,12 +283,6 @@ module RubyLsp
         @location_index.stats
       end
 
-      # Get all registered class names (thread-safe)
-      # @return [Array<String>] List of class names
-      def registered_classes
-        @mutex.synchronize { @method_registry.registered_classes }
-      end
-
       # Get all methods for a specific class (thread-safe)
       # @param class_name [String] Class name
       # @return [Hash<String, DefNode>] Methods hash
@@ -299,200 +307,528 @@ module RubyLsp
         end
       end
 
-      private
-
-      # Traverse and index a single file
-      def traverse_file(uri)
-        file_path = uri.to_standardized_path
-        return unless file_path && File.exist?(file_path)
+      # Resolve a short constant name to fully qualified name
+      # @param short_name [String] Short constant name
+      # @param nesting [Array<String>] Nesting context
+      # @return [String, nil] Fully qualified name or nil
+      def resolve_constant_name(short_name, nesting)
+        @code_index&.resolve_constant_name(short_name, nesting)
+      end
 
-        # Parse outside mutex (CPU-bound, no shared state)
-        source = File.read(file_path)
-        parsed = Prism.parse(source)
-        return unless parsed.value
+      # Look up RBS method signatures with owner resolution
+      # Finds the actual class that defines the method (e.g., Object for #tap)
+      # @param class_name [String] Receiver class name
+      # @param method_name [String] Method name
+      # @return [Hash] { signatures: Array<Signature>, owner: String }
+      def get_rbs_method_signatures(class_name, method_name)
+        @mutex.synchronize do
+          # Find actual owner class (e.g., Object for tap on MyClass)
+          owner_class = @code_index&.instance_method_owner(class_name, method_name) || class_name
 
-        # Create context and convert nodes outside mutex
-        context = ::TypeGuessr::Core::Converter::PrismConverter::Context.new
-        nodes = parsed.value.statements&.body&.filter_map do |stmt|
-          @converter.convert(stmt, context)
+          signatures = @signature_registry.get_method_signatures(owner_class, method_name)
+          { signatures: signatures, owner: owner_class }
         end
+      end
 
-        # Only hold mutex while modifying shared state
+      # Look up RBS class method signatures with owner resolution
+      # @param class_name [String] Class name
+      # @param method_name [String] Method name
+      # @return [Hash] { signatures: Array<Signature>, owner: String }
+      def get_rbs_class_method_signatures(class_name, method_name)
         @mutex.synchronize do
-          @location_index.remove_file(file_path)
-          nodes&.each { |node| index_node_recursively(file_path, node, "") }
+          # Find actual owner class for class methods
+          owner_class = @code_index&.class_method_owner(class_name, method_name) || class_name
+
+          # Convert singleton format (e.g., "File::<Class:File>") to simple class name ("File")
+          # SignatureRegistry expects simple class names for RBS lookup
+          owner_class = extract_class_from_singleton(owner_class)
+
+          signatures = @signature_registry.get_class_method_signatures(owner_class, method_name)
+          { signatures: signatures, owner: owner_class }
         end
-        # NOTE: finalize! is called once after ALL files are indexed in start_indexing
-      rescue StandardError => e
-        bt = e.backtrace&.first(5)&.join("\n") || "(no backtrace)"
-        log_message("Error indexing #{uri}: #{e.class}: #{e.message}\n#{bt}")
-      end
-
-      # Recursively index a node and all its children with scope tracking
-      # @param file_path [String] Absolute file path
-      # @param node [TypeGuessr::Core::IR::Node] IR node to index
-      # @param scope_id [String] Current scope identifier (e.g., "User#save")
-      def index_node_recursively(file_path, node, scope_id)
-        return unless node
-
-        case node
-        when ::TypeGuessr::Core::IR::DefNode
-          index_def_node(file_path, node, scope_id)
-
-        when ::TypeGuessr::Core::IR::ClassModuleNode
-          index_class_module_node(file_path, node, scope_id)
-
-        when ::TypeGuessr::Core::IR::CallNode
-          @location_index.add(file_path, node, scope_id)
-          index_node_recursively(file_path, node.receiver, scope_id) if node.receiver
-          node.args&.each { |arg| index_node_recursively(file_path, arg, scope_id) }
-          node.block_params&.each { |param| index_node_recursively(file_path, param, scope_id) }
-          index_node_recursively(file_path, node.block_body, scope_id) if node.block_body
-
-        when ::TypeGuessr::Core::IR::MergeNode
-          @location_index.add(file_path, node, scope_id)
-          node.branches&.each { |branch| index_node_recursively(file_path, branch, scope_id) }
-
-        when ::TypeGuessr::Core::IR::InstanceVariableWriteNode
-          @location_index.add(file_path, node, scope_id)
-          @variable_registry.register_instance_variable(node.class_name, node.name, node) if node.class_name
-          index_node_recursively(file_path, node.value, scope_id) if node.value
-
-        when ::TypeGuessr::Core::IR::ClassVariableWriteNode
-          @location_index.add(file_path, node, scope_id)
-          @variable_registry.register_class_variable(node.class_name, node.name, node) if node.class_name
-          index_node_recursively(file_path, node.value, scope_id) if node.value
-
-        when ::TypeGuessr::Core::IR::LocalWriteNode
-          @location_index.add(file_path, node, scope_id)
-          index_node_recursively(file_path, node.value, scope_id) if node.value
-
-        when ::TypeGuessr::Core::IR::ParamNode
-          @location_index.add(file_path, node, scope_id)
-          index_node_recursively(file_path, node.default_value, scope_id) if node.default_value
-
-        when ::TypeGuessr::Core::IR::ReturnNode
-          @location_index.add(file_path, node, scope_id)
-          index_node_recursively(file_path, node.value, scope_id) if node.value
-
-        when ::TypeGuessr::Core::IR::ConstantNode
-          @location_index.add(file_path, node, scope_id)
-          index_node_recursively(file_path, node.dependency, scope_id) if node.dependency
-
-        when ::TypeGuessr::Core::IR::LiteralNode
-          @location_index.add(file_path, node, scope_id)
-          # Index value nodes (e.g., variable references in arrays/hashes/keyword args)
-          node.values&.each { |value| index_node_recursively(file_path, value, scope_id) }
+      end
+
+      # Cache-first indexing: process gems with cache, then project files
+      # @return [Hash] { cache:, unguessed_gems: [...] }
+      private def index_with_gem_cache(file_paths, lockfile_path)
+        resolver_class = ::TypeGuessr::Core::Cache::GemDependencyResolver
+        dep_resolver = resolver_class.new(lockfile_path)
+        partitioned = dep_resolver.partition(file_paths)
+        gems = partitioned[:gems]
+        project_files = partitioned[:project_files]
+
+        log_message("Partitioned: #{gems.size} gems, #{project_files.size} project files.")
+
+        cache = ::TypeGuessr::Core::Cache::GemSignatureCache.new
+        ordered = dep_resolver.topological_order(gems.keys)
+
+        # Process each gem in dependency order, collecting those needing background inference
+        unguessed_gems = []
+        ordered.each do |gem_name|
+          gem_info = gems[gem_name]
+          needs_inference = process_gem(gem_name, gem_info, cache)
+          unguessed_gems << { name: gem_name, info: gem_info } if needs_inference
+        end
+
+        # Index project files into main registries
+        index_all_files(project_files)
+
+        { cache: cache, unguessed_gems: unguessed_gems }
+      end
+
+      # Process a single gem: cache hit → load, cache miss → save unguessed cache
+      # @return [Boolean] Whether background inference is needed for this gem
+      private def process_gem(gem_name, gem_info, cache)
+        version = gem_info[:version]
+        deps = gem_info[:transitive_deps]
+        file_count = gem_info[:files].size
+
+        log_message("Processing #{gem_name}-#{version} (#{file_count} files)...")
 
+        if cache.cached?(gem_name, version, deps)
+          data = load_gem_from_cache(gem_name, version, deps, cache)
+          return false unless data
+
+          # Previously timed out — don't retry background inference
+          return false if data["inference_timeout"]
+
+          !data["fully_inferred"]
         else
-          # LocalReadNode, InstanceVariableReadNode, ClassVariableReadNode, etc.
-          @location_index.add(file_path, node, scope_id)
+          save_unguessed_cache(gem_name, gem_info, cache)
+          true
+        end
+      end
+
+      # Load gem signatures from disk cache into SignatureRegistry
+      # @return [Hash, nil] Loaded cache data or nil on failure
+      private def load_gem_from_cache(gem_name, version, deps, cache)
+        data = cache.load(gem_name, version, deps)
+        unless data
+          log_message("Cache corrupt for #{gem_name}-#{version}, skipping.")
+          return nil
         end
+
+        @signature_registry.load_gem_cache(data["instance_methods"], kind: :instance)
+        @signature_registry.load_gem_cache(data["class_methods"], kind: :class)
+        log_message(
+          "Loaded cached signatures for #{gem_name}-#{version} " \
+          "(fully_inferred=#{data["fully_inferred"]}, inference_timeout=#{data["inference_timeout"]})."
+        )
+        data
       end
 
-      def index_def_node(file_path, node, scope_id)
-        method_scope = singleton_scope_for(scope_id, singleton: node.singleton)
-        @location_index.add(file_path, node, method_scope)
+      # Infer gem method signatures using temporary registries, then cache
+      # @return [Hash, nil] { instance_methods:, class_methods: } or nil on error
+      private def infer_and_cache_gem(gem_name, gem_info, cache)
+        version = gem_info[:version]
+        files = gem_info[:files]
+        deps = gem_info[:transitive_deps]
+
+        # Phase A: Parse + IR conversion
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        temp_location_index = ::TypeGuessr::Core::Index::LocationIndex.new
+        temp_method_registry = ::TypeGuessr::Core::Registry::MethodRegistry.new(code_index: @code_index)
+        temp_ivar_registry = ::TypeGuessr::Core::Registry::InstanceVariableRegistry.new(code_index: @code_index)
+        temp_cvar_registry = ::TypeGuessr::Core::Registry::ClassVariableRegistry.new
+
+        converter = ::TypeGuessr::Core::Converter::PrismConverter.new
+        files.each do |file_path|
+          parse_and_index_file(file_path, converter, temp_location_index,
+                               temp_method_registry, temp_ivar_registry, temp_cvar_registry)
+        end
+        temp_location_index.finalize!
+
+        t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # Phase B: Inference (extract signatures)
+        type_simplifier = ::TypeGuessr::Core::TypeSimplifier.new(code_index: @code_index)
+        temp_resolver = ::TypeGuessr::Core::Inference::Resolver.new(
+          @signature_registry,
+          code_index: @code_index,
+          method_registry: temp_method_registry,
+          ivar_registry: temp_ivar_registry,
+          cvar_registry: temp_cvar_registry,
+          type_simplifier: type_simplifier
+        )
+        temp_builder = ::TypeGuessr::Core::SignatureBuilder.new(temp_resolver)
+
+        extractor = ::TypeGuessr::Core::Cache::GemSignatureExtractor.new(
+          signature_builder: temp_builder,
+          method_registry: temp_method_registry,
+          location_index: temp_location_index
+        )
+        timeout = ::TypeGuessr::Core::Config.gem_inference_timeout
+        signatures = extractor.extract(files, timeout: timeout)
+
+        t2 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # Inference timed out — save as unguessed with timeout flag
+        unless signatures
+          log_message(
+            "Inference timeout for #{gem_name}-#{version} " \
+            "(#{files.size} files, parse=#{(t1 - t0).round(2)}s, " \
+            "infer>#{timeout}s), deferring to on-demand"
+          )
+          save_unguessed_cache(gem_name, gem_info, cache, inference_timeout: true)
+          return nil
+        end
 
-        new_scope = method_scope.empty? ? "##{node.name}" : "#{method_scope}##{node.name}"
-        @method_registry.register("", node.name.to_s, node) if scope_id.empty?
+        # Phase C: Disk save
+        cache.save(gem_name, version, deps,
+                   instance_methods: signatures[:instance_methods],
+                   class_methods: signatures[:class_methods])
 
-        node.params&.each { |param| index_node_recursively(file_path, param, new_scope) }
-        node.body_nodes&.each { |body_node| index_node_recursively(file_path, body_node, new_scope) }
+        t3 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # Phase D: Registry load
+        @signature_registry.load_gem_cache(signatures[:instance_methods], kind: :instance)
+        @signature_registry.load_gem_cache(signatures[:class_methods], kind: :class)
+
+        t4 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        log_message(
+          "Cached #{gem_name}-#{version} (#{files.size} files, " \
+          "#{signatures[:instance_methods].size} classes) " \
+          "[parse=#{(t1 - t0).round(2)}s infer=#{(t2 - t1).round(2)}s " \
+          "save=#{(t3 - t2).round(2)}s load=#{(t4 - t3).round(2)}s]"
+        )
+
+        signatures
       end
 
-      def index_class_module_node(file_path, node, scope_id)
-        @location_index.add(file_path, node, scope_id)
+      # Generate an Unguessed cache from member_index entries (no parse/infer needed).
+      # Method names and parameter structure come from RubyIndexer; types are set to Unguessed.
+      private def save_unguessed_cache(gem_name, gem_info, cache, inference_timeout: false)
+        version = gem_info[:version]
+        files = gem_info[:files]
+        deps = gem_info[:transitive_deps]
+
+        instance_methods = {}
+        class_methods = {}
+
+        files.each do |file_path|
+          @code_index.member_entries_for_file(file_path).each do |entry|
+            owner_name = entry.owner.name
+
+            if owner_name.match?(/::<Class:[^>]+>\z/)
+              class_name = extract_class_from_singleton(owner_name)
+              target = class_methods
+            else
+              class_name = owner_name
+              target = instance_methods
+            end
+
+            target[class_name] ||= {}
+            target[class_name][entry.name] = {
+              "return_type" => { "_type" => "Unguessed" },
+              "params" => build_params_from_entry(entry)
+            }
+          end
+        end
 
-        new_scope = scope_id.empty? ? node.name : "#{scope_id}::#{node.name}"
+        cache.save(gem_name, version, deps,
+                   instance_methods: instance_methods,
+                   class_methods: class_methods,
+                   fully_inferred: false,
+                   inference_timeout: inference_timeout)
 
-        node.methods&.each do |method|
-          if method.is_a?(::TypeGuessr::Core::IR::ClassModuleNode)
-            index_node_recursively(file_path, method, new_scope)
-          else
-            index_node_recursively(file_path, method, new_scope)
+        @signature_registry.load_gem_cache(instance_methods, kind: :instance)
+        @signature_registry.load_gem_cache(class_methods, kind: :class)
 
-            method_scope = singleton_scope_for(new_scope, singleton: method.singleton)
-            @method_registry.register(method_scope, method.name.to_s, method)
+        log_message(
+          "Saved unguessed cache for #{gem_name}-#{version} " \
+          "(#{instance_methods.size} instance classes, #{class_methods.size} class method classes)"
+        )
+      end
+
+      # Build serialized params array from a RubyIndexer::Entry::Member
+      private def build_params_from_entry(entry)
+        sigs = entry.signatures
+        return [] if sigs.empty?
+
+        sigs.first.parameters.filter_map do |p|
+          kind = case p
+                 when RubyIndexer::Entry::RequiredParameter then "required"
+                 when RubyIndexer::Entry::OptionalParameter then "optional"
+                 when RubyIndexer::Entry::RestParameter then "rest"
+                 when RubyIndexer::Entry::KeywordParameter then "keyword_required"
+                 when RubyIndexer::Entry::OptionalKeywordParameter then "keyword_optional"
+                 when RubyIndexer::Entry::KeywordRestParameter then "keyword_rest"
+                 when RubyIndexer::Entry::BlockParameter then "block"
+                 else next
+                 end
+          { "name" => p.name.to_s, "kind" => kind, "type" => { "_type" => "Unguessed" } }
+        end
+      end
+
+      # Fallback: index all files into main registries (no cache)
+      private def index_all_files(file_paths)
+        file_paths.each do |file_path|
+          next unless File.exist?(file_path)
+
+          source = File.read(file_path)
+          parsed = Prism.parse(source)
+          next unless parsed.value
+
+          @mutex.synchronize do
+            @location_index.remove_file(file_path)
+            @method_registry.remove_file(file_path)
+            @ivar_registry.remove_file(file_path)
+            @cvar_registry.remove_file(file_path)
+
+            context = ::TypeGuessr::Core::Converter::PrismConverter::Context.new(
+              file_path: file_path,
+              location_index: @location_index,
+              method_registry: @method_registry,
+              ivar_registry: @ivar_registry,
+              cvar_registry: @cvar_registry
+            )
+
+            parsed.value.statements&.body&.each do |stmt|
+              @converter.convert(stmt, context)
+            end
           end
+        rescue StandardError => e
+          log_message("Error indexing #{file_path}: #{e.class}: #{e.message}")
         end
+
+        @mutex.synchronize { @location_index.finalize! }
+        log_message("Indexed #{file_paths.size} files.")
       end
 
-      # Build SignatureProvider with configured type sources
-      # Currently uses RBSProvider for stdlib types
-      # Can be extended to add project RBS, Sorbet, etc.
-      def build_signature_provider
-        provider = ::TypeGuessr::Core::SignatureProvider.new
+      # Parse and index a file into given registries (no mutex, used for temp gem registries)
+      private def parse_and_index_file(file_path, converter, location_index,
+                                       method_registry, ivar_registry, cvar_registry)
+        return unless File.exist?(file_path)
 
-        # Add stdlib RBS provider (lowest priority)
-        provider.add_provider(::TypeGuessr::Core::RBSProvider.instance)
+        source = File.read(file_path)
+        parsed = Prism.parse(source)
+        return unless parsed.value
 
-        # Future: Add project RBS provider (high priority)
-        # provider.add_provider(ProjectRBSProvider.new, priority: :high)
+        context = ::TypeGuessr::Core::Converter::PrismConverter::Context.new(
+          file_path: file_path,
+          location_index: location_index,
+          method_registry: method_registry,
+          ivar_registry: ivar_registry,
+          cvar_registry: cvar_registry
+        )
 
-        provider
+        parsed.value.statements&.body&.each do |stmt|
+          converter.convert(stmt, context)
+        end
+      rescue StandardError => e
+        log_message("Error indexing gem file #{file_path}: #{e.class}: #{e.message}")
       end
 
-      # Build singleton class scope for method registration/lookup
-      # Singleton methods use "<Class:ClassName>" suffix to match RubyIndexer convention
-      # @param scope [String] Base scope (e.g., "RBS::Environment2")
-      # @param singleton [Boolean] Whether the method is a singleton method
-      # @return [String] Scope with singleton class suffix if applicable
-      def singleton_scope_for(scope, singleton:)
-        return scope unless singleton
+      # Find Gemfile.lock in the workspace
+      private def find_lockfile
+        workspace_path = @global_state.workspace_path
+        return nil unless workspace_path
 
-        parent_name = scope.split("::").last || "Object"
-        scope.empty? ? "<Class:Object>" : "#{scope}::<Class:#{parent_name}>"
+        lockfile = File.join(workspace_path, "Gemfile.lock")
+        File.exist?(lockfile) ? lockfile : nil
       end
 
-      # Get class ancestors from RubyIndexer
-      # @param class_name [String] Class name
-      # @return [Array<String>] Array of ancestor names
-      def get_class_ancestors(class_name)
-        return [] unless @global_state.index
+      private def index_file_with_prism_result(file_path, prism_result)
+        return unless prism_result.value
+
+        @mutex.synchronize do
+          # Clear existing index for this file
+          @location_index.remove_file(file_path)
+          @method_registry.remove_file(file_path)
+          @ivar_registry.remove_file(file_path)
+          @cvar_registry.remove_file(file_path)
+          @resolver.clear_cache
+
+          # Create context with index/registry injection - nodes are registered during conversion
+          context = ::TypeGuessr::Core::Converter::PrismConverter::Context.new(
+            file_path: file_path,
+            location_index: @location_index,
+            method_registry: @method_registry,
+            ivar_registry: @ivar_registry,
+            cvar_registry: @cvar_registry
+          )
+
+          prism_result.value.statements&.body&.each do |stmt|
+            @converter.convert(stmt, context)
+          end
 
-        @global_state.index.linearized_ancestors_of(class_name)
-      rescue RubyIndexer::Index::NonExistingNamespaceError
-        []
+          # Finalize the index for efficient lookups
+          @location_index.finalize!
+
+          # Update member_index (RubyIndexer is already updated by ruby-lsp)
+          @code_index.refresh_member_index!(URI::Generic.from_path(path: file_path))
+        end
+      end
+
+      # Extract simple class name from singleton format
+      # "File::<Class:File>" -> "File"
+      # "Namespace::MyClass::<Class:MyClass>" -> "Namespace::MyClass"
+      # @param owner_class [String] Owner class name (may be singleton format)
+      # @return [String] Simple class name
+      private def extract_class_from_singleton(owner_class)
+        # Match singleton pattern: "ClassName::<Class:ClassName>"
+        if owner_class.match?(/::<Class:[^>]+>\z/)
+          owner_class.sub(/::<Class:[^>]+>\z/, "")
+        else
+          owner_class
+        end
+      end
+
+      # Background inference: fully infer gems with Unguessed entries after indexing.
+      # Runs in the same indexing thread after @indexing_completed = true.
+      # Replaces in-memory Unguessed entries and updates disk cache to fully_inferred.
+      private def background_infer_gems(unguessed_gems, cache)
+        log_message("Starting background inference for #{unguessed_gems.size} gems...")
+
+        unguessed_gems.each do |entry|
+          signatures = infer_and_cache_gem(entry[:name], entry[:info], cache)
+          next unless signatures
+
+          @signature_registry.replace_unguessed_entries(signatures[:instance_methods], kind: :instance)
+          @signature_registry.replace_unguessed_entries(signatures[:class_methods], kind: :class)
+        rescue StandardError => e
+          log_message("Background inference failed for #{entry[:name]}: #{e.message}")
+        end
+
+        log_message("Background inference completed.")
+      end
+
+      # On-demand inference for a single gem file.
+      # Triggered when SignatureRegistry encounters an Unguessed return type.
+      # Parses and infers the file containing the method definition,
+      # then replaces Unguessed entries with actual inferred types.
+      private def infer_gem_file_on_demand(class_name, method_name, kind)
+        return if @inferring_on_demand # re-entrancy guard
+
+        singleton = kind == :class
+        file_path = @code_index.method_definition_file_path(class_name, method_name, singleton: singleton)
+        return unless file_path
+
+        @inferring_on_demand = true
+        begin
+          temp_location_index = ::TypeGuessr::Core::Index::LocationIndex.new
+          temp_method_registry = ::TypeGuessr::Core::Registry::MethodRegistry.new(code_index: @code_index)
+          temp_ivar_registry = ::TypeGuessr::Core::Registry::InstanceVariableRegistry.new(code_index: @code_index)
+          temp_cvar_registry = ::TypeGuessr::Core::Registry::ClassVariableRegistry.new
+
+          converter = ::TypeGuessr::Core::Converter::PrismConverter.new
+          parse_and_index_file(file_path, converter, temp_location_index,
+                               temp_method_registry, temp_ivar_registry, temp_cvar_registry)
+          temp_location_index.finalize!
+
+          type_simplifier = ::TypeGuessr::Core::TypeSimplifier.new(code_index: @code_index)
+          temp_resolver = ::TypeGuessr::Core::Inference::Resolver.new(
+            @signature_registry,
+            code_index: @code_index,
+            method_registry: temp_method_registry,
+            ivar_registry: temp_ivar_registry,
+            cvar_registry: temp_cvar_registry,
+            type_simplifier: type_simplifier
+          )
+          temp_builder = ::TypeGuessr::Core::SignatureBuilder.new(temp_resolver)
+          extractor = ::TypeGuessr::Core::Cache::GemSignatureExtractor.new(
+            signature_builder: temp_builder,
+            method_registry: temp_method_registry,
+            location_index: temp_location_index
+          )
+
+          signatures = extractor.extract([file_path])
+
+          @signature_registry.replace_unguessed_entries(signatures[:instance_methods], kind: :instance)
+          @signature_registry.replace_unguessed_entries(signatures[:class_methods], kind: :class)
+        rescue StandardError => e
+          log_message("On-demand inference failed for #{class_name}##{method_name}: #{e.message}")
+        ensure
+          @inferring_on_demand = false
+        end
       end
 
-      # Get constant kind from RubyIndexer
-      # @param constant_name [String] Constant name
-      # @return [Symbol, nil] :class, :module, or nil
-      def get_constant_kind(constant_name)
-        return nil unless @global_state.index
+      # Poll index entry count until it stops growing for stable_threshold consecutive checks.
+      # Other addons (ruby-lsp-rails, etc.) may register entries after initial_indexing_completed.
+      private def wait_for_index_stabilization(index, interval: 1, stable_threshold: 3)
+        previous_count = index.length
+        stable_ticks = 0
 
-        entries = @global_state.index[constant_name]
-        return nil if entries.nil? || entries.empty?
+        loop do
+          sleep(interval)
+          current_count = index.length
 
-        entry = entries.first
-        case entry
-        when RubyIndexer::Entry::Class then :class
-        when RubyIndexer::Entry::Module then :module
+          if current_count == previous_count
+            stable_ticks += 1
+            break if stable_ticks >= stable_threshold
+          else
+            log_message("Index still growing: #{current_count} entries (+#{current_count - previous_count})")
+            stable_ticks = 0
+            previous_count = current_count
+          end
         end
+
+        log_message("Index stabilized at #{previous_count} entries.")
+      end
+
+      private def discover_runner_client
+        rails_addon = ::RubyLsp::Addon.get("Ruby LSP Rails", ">= 0.4.0", "< 0.5.0")
+        rails_addon.rails_runner_client
+      rescue ::RubyLsp::Addon::AddonNotFoundError, ::RubyLsp::Addon::IncompatibleApiError
+        nil
+      rescue StandardError => e
+        log_message("Failed to discover RunnerClient: #{e.message}")
+        nil
+      end
+
+      private def register_dsl_types
+        workspace_path = @global_state.workspace_path
+        return unless workspace_path
+
+        @dsl_registrar = DslTypeRegistrar.new(
+          signature_registry: @signature_registry,
+          code_index: @code_index,
+          project_root: workspace_path
+        )
+        @dsl_registrar.on_log { |msg| log_message("[DSL] #{msg}") }
+
+        runner_client = wait_for_runner_client
+        @dsl_registrar.register_all(runner_client: runner_client)
+      rescue StandardError => e
+        log_message("DSL type registration failed: #{e.message}\n#{e.backtrace.first(3).join("\n")}")
       end
 
-      # Look up class method owner via RubyIndexer singleton class ancestry
-      # @param class_name [String] Class name (e.g., "C")
-      # @param method_name [String] Method name (e.g., "foo")
-      # @return [String, nil] Owner name (module or singleton class name) or nil
-      def lookup_class_method_owner(class_name, method_name)
-        return nil unless @global_state.index
+      # Wait for ruby-lsp-rails RunnerClient to transition from NullClient.
+      # 3s interval × max 10 attempts = max 30s.
+      private def wait_for_runner_client
+        log_message("[DSL] Waiting for RunnerClient...")
+        max_attempts = 10
+
+        max_attempts.times do |_i|
+          client = discover_runner_client
+          if client.respond_to?(:connected?) && client.connected?
+            log_message("[DSL] RunnerClient ready (#{client.class})")
+            return client
+          end
 
-        # Query singleton class (e.g., "C::<Class:C>") for the method
-        # Ruby LSP uses unqualified name for singleton class (e.g., "RBS::Environment::<Class:Environment>")
-        unqualified_name = class_name.split("::").last
-        singleton_name = "#{class_name}::<Class:#{unqualified_name}>"
-        entries = @global_state.index.resolve_method(method_name, singleton_name)
-        return nil if entries.nil? || entries.empty?
+          sleep(3)
+        end
 
-        entry = entries.first
-        entry.owner&.name
-      rescue RubyIndexer::Index::NonExistingNamespaceError
+        log_message("[DSL] RunnerClient timeout after #{max_attempts} attempts")
         nil
       end
 
-      def log_message(message)
+      private def start_schema_watch_loop
+        return unless @dsl_registrar
+
+        Thread.new do
+          loop do
+            sleep(45)
+            @dsl_registrar.check_and_refresh(runner_client: discover_runner_client)
+          rescue StandardError => e
+            log_message("Schema watch error: #{e.message}")
+          end
+        end
+      end
+
+      private def log_message(message)
         return unless @message_queue
         return if @message_queue.closed?