Speed-up LSP completion response times

[lekemula]

Warning

DISCLAIMER: @claude was used to generate the code of the new methods, but mostly because I knew what I was looking for, and I was too lazy to figure out the methods needed to be called to make it work.

Problem

In my current work project (with 7,140 Ruby files with 109,664 total lines), I've noticed that initial or cold LSP completions were taking an extremely long time. By initial or cold completions, I mean:

1. First requests after LSP boot (> ~40s)
2. First requests after opening a new file (~10-20s)
3. First requests after editing an open file (~10-20s)

The subsequent completions were fine up until the next edit, I'm assuming due to the caching ( less than typically ~0.5-1s)

# .solargraph.yml
---
include:
  - "**/*.rb"
exclude:
  - "**/spec/**/*"
  - test/**/*
  - vendor/**/*
  - ".bundle/**/*"
domains: []
plugins:
  - solargraph-rspec
  - solargraph-rails
rspec:
  let_methods:
    - let_it_be
reporters:
  - rubocop
  - require_not_found
formatter:
  rubocop:
    cops: all
max_files: 20000

Coming from the #1028, I initially thought the issue might be related to the indexing store update. However after using the excellent profiler, vernier, I came to find that the bottleneck seemed to be the Solargraph::ApiMap#resolve_method_aliases particularly its recursive usage of #get_method_stack inside Solargraph::ApiMap#resolve_method_alias

solargraph/lib/solargraph/api_map.rb

Line 970 in 91bdc32

origin = get_method_stack(pin.full_context.tag, pin.original, scope: pin.scope, preserve_generics: true).first

Vernier screenshot

---

Solution

Replace recursive get_method_stack and linear search with direct indexed method lookup via Store and Index.

• Add indexed lookups for methods and aliases by name
  • Assume that the method names are relatively distinct enough to reduce the search space -> turned out redundant.
• Reuse Cached ancestor traversal to avoid repeated computations via get_method_stack
• Add fast path for creating resolved alias pins without individual lookups

Results 🚀

Before

Vernier Profile

Screenshots

First request after LSP boot

• Total Go-to-definition completion time (~47s)

• Solargraph::Library#definitions_at time (~4.3s)

[!NOTE]
As we can see, most of the time is spent on cataloging initially, which makes sense.

---

First request after opening a new file

• Total Go-to-definition completion time (~9.6s)

• Solargraph::Library#definitions_at time (~7.9s)

After

Vernier Profile

Screenshots

First request after LSP boot

• Total Go-to-definition completion time (~13.8s)

• Solargraph::Library#definitions_at time (0.92s)

[!NOTE]
As we can see, most of the time is spent on cataloging initially, which makes sense.

---

First request after opening a new file

• Total Go-to-definition completion time (4.6s)

• Solargraph::Library#definitions_at time (0.6s)

---

Summary

Performance improvements (measured on a large Ruby project with ~7,100 files):

• First request after LSP boot: ⏱️ 47s → 13.8s (~3.6x faster)

• First request after opening a new file: ⏱️ 9.6s → 4.6s (~2x faster)

• Solargraph::Library#definitions_at hot path: ⏱️ 4.3s → 0.9s (~4.6x faster)

Cached responses seem not to be impacted by this change, and they remain fast as before.

Further potential Improvements

Example completion after file open:

From the samples above (with the new implementation), cataloging accounts for roughly 75-85% of the total time in cold completion responses. There may be room for improvement here - for example, by making cataloging run asynchronously. I recall some recent changes in this area, so the implications aren’t entirely clear. That said, my hunch is that for code completion specifically, developer experience often benefits more from speed than from perfect accuracy (just my personal opinion).

Vernier quick how-tos

Assuming that you've already installed the gem locally, to run the solargraph with vernier use:

vernier run -- solargraph stdio

Use https://vernier.prof/ to upload the profiles above.

If Vernier is a new tool for you, this video stream from Aaron is highly recommended!

[lekemula]

I think this was accidentally included from my other branch 🙈, I'll remove it.

[lekemula]

I'm not sure I know what I need to do for type-checking lint:
https://github.com/castwide/solargraph/actions/runs/17138672729/job/48620888903?pr=1035

Could you please instruct?

[apiology]

I'd suggest creating a spec demonstrating creating an alias in a subclass to a method defined in the superclass - that'd show that if you can't find the method the easy way, you fall back to the old way

[apiology]

/home/runner/work/solargraph/solargraph/lib/solargraph/api_map/store.rb:55 - Not enough arguments to Kernel#select

Probably another good spec to add - these select methods are on arrays, which implement Enumerable. Enumerable#select is an alias for Enumerable#find_all, and I'm guessing the logic to find that alias and use it isn't working right with this change.

[lekemula]

Hi, thanks for the great hints @apiology! It was not immediately evident to me where that might be coming from. I think I know where the culprit might be.

I'd suggest creating a spec demonstrating creating an alias in a subclass to a method defined in the superclass - that'd show that if you can't find the method the easy way, you fall back to the old way

Probably I should have mentioned, but the reason why there were no specs added is that it seemed like we have sufficient coverage in api_map_spec.rb.

This should cover your above case, right?

solargraph/spec/api_map_spec.rb

Lines 488 to 504 in 3f7e25b

	it 'detects method aliases with origins in other sources' do
	source1 = Solargraph::SourceMap.load_string(%(
	class Sup
	# @return [String]
	def foo; end
	end
	), 'source1.rb')
	source2 = Solargraph::SourceMap.load_string(%(
	class Sub < Sup
	alias bar foo
	end
	), 'source2.rb')
	@api_map.catalog Solargraph::Bench.new(source_maps: [source1, source2])
	pin = @api_map.get_path_pins('Sub#bar').first
	expect(pin).not_to be_nil
	expect(pin.return_type.tag).to eq('String')
	end

That said, we need some more module inclusion/extension cases, which I think also relate to the typechecking failures.

The new method is meant to look up the aliases in the ancestor's tree in the same way as the old one, but I think the ordering in which we do the lookup is not quite right atm. Hence it uses the Kernel.select instead of Enumerable.select

[lekemula]

Alright, this turned out to be a very interesting case.

The reason why the typechecking was failing for Enumerable#select is because the new implementation was changing the ordering of get_method_stack:

From: /Users/lekemula/Projects/solargraph/lib/solargraph/source/chain/call.rb:62 Solargraph::Source::Chain::Call#resolve:

    50: def resolve api_map, name_pin, locals
    51:   return super_pins(api_map, name_pin) if word == 'super'
    52:   return yield_pins(api_map, name_pin) if word == 'yield'
    53:   found = if head?
    54:     api_map.visible_pins(locals, word, name_pin, location)
    55:   else
    56:     []
    57:   end
    58:   return inferred_pins(found, api_map, name_pin, locals) unless found.empty?
    59:   pins = name_pin.binder.each_unique_type.flat_map do |context|
    60:     ns_tag = context.namespace == '' ? '' : context.namespace_type.tag
    61:     stack = api_map.get_method_stack(ns_tag, word, scope: context.scope)
 => 62:     [stack.first].compact
    63:   end
    64:   return [] if pins.empty?
    65:   inferred_pins(pins, api_map, name_pin, locals)
    66: end

[10] pry(#<Solargraph::Source::Chain::Call>)> stack.first
=> #<Solargraph::Pin::Method `name="select" return_type=Kernel#select def select: (read ::Array[::IO], ?write ::Array[::IO], ?error ::Array[::IO], ?timeout ::Time::_Timeout) -> ::Array[::String], context=::Kernel, closure=[name="Kernel" return_type=Kernel module ::Kernel, context=::Class<>, closure=[(top-level)], binder=::Module<Kernel>], binder=::Kernel` at #<Solargraph::Location /Users/lekemula/.rvm/gems/ruby-3.2.2/gems/rbs-3.9.4/core/kernel.rbs, #<Solargraph::Range #<Solargraph::Position 1712, 2> to #<Solargraph::Position 1712, 122>>>) via :rbs>
[11] pry(#<Solargraph::Source::Chain::Call>)> stack
=> [#<Solargraph::Pin::Method `name="select" return_type=Kernel#select def select: (read ::Array[::IO], ?write ::Array[::IO], ?error ::Array[::IO], ?timeout ::Time::_Timeout) -> ::Array[::String], context=::Kernel, closure=[name="Kernel" return_type=Kernel module ::Kernel, context=::Class<>, closure=[(top-level)], binder=::Module<Kernel>], binder=::Kernel` at #<Solargraph::Location /Users/lekemula/.rvm/gems/ruby-3.2.2/gems/rbs-3.9.4/core/kernel.rbs, #<Solargraph::Range #<Solargraph::Position 1712, 2> to #<Solargraph::Position 1712, 122>>>) via :rbs>,
 #<Solargraph::Pin::Method `Enumerable#select
def select: () { (arg_0 Solargraph::Pin::Base) -> ::BasicObject } -> ::Array[Solargraph::Pin::Base]
          | select: () -> ::Enumerator[Solargraph::Pin::Base, ::Array[Solargraph::Pin::Base]]
` at #<Solargraph::Location /Users/lekemula/.rvm/gems/ruby-3.2.2/gems/rbs-3.9.4/core/enumerable.rbs, #<Solargraph::Range #<Solargraph::Position 543, 2> to #<Solargraph::Position 544, 55>>>) via :resolve_method_alias>]
[12] pry(#<Solargraph::Source::Chain::Call>)> stack.count
=> 2
[13] pry(#<Solargraph::Source::Chain::Call>)> stack.map(&:path)
=> ["Kernel#select", "Enumerable#select"]

On the master branch, this was working as expected:

=> ["Enumerable#select", "Kernel#select"]

Keeping the old implementation of def resolve_method_aliases and only changing the def resolve_method_alias seems to fix it. Apparently, I had let the @claude too much out of the leash!

41d99d4 (#1035)

PS. Glad that we're dogfooding typechecking to catch such edge cases! 🙌

[castwide]

Nice work, thanks! Out of curiosity, I tested this branch against a project that had slow completions due to heavy use of dynamic yield receivers. Performance was noticeably improved there, too.

The linting error should go away with the merge. If it doesn't, I'll deal with the fallout.

[lekemula]

@castwide, thanks for merging this already, and I'm happy to hear that you've also noticed the improvements.

I'm curious about your thoughts on further potential Improvements - ie, moving the Library#sync_catalog async? I think that would significantly improve the cold go-to definition, and bring completions in <1s, which I think would be the sweet spot.

We used to have it async before #876.

[castwide]

From what I've determined, there's nothing to be gained from making Library#sync_catalog asynchronous. Ruby threads are always executed in a single process, so it will never run concurrently at the OS level (e.g., POSIX). Any other function within the solargraph process that needs the newest maps will need to wait for the library to synchronize anyway. Ruby threads don't make it any faster. The main reason #sync_catalog exists is to ensure that clients have access to the most current versions of code maps at the moment they're requested.