In my current Neovim configuration, I’m using ruby-lsp, Shopify’s Ruby/Rails language server. Before this language server came along, there was solargraph. While ruby-lsp seems to work great for things like go to definition and hover on Ruby and locally defined classes/methods, I really want to see hover documentation on my installed gems. For example, I want to press Shift+k on an ActiveRecord method. Here’s an example of what I’d like to achieve:

report = Report.create!(report_type: report_type)

In this one line, I’m calling .create! on an ActiveRecord model. I’d really like to Shift+k on that specific method and get documentation about how .create! works, how it differs from .create. With ruby-lsp, it seems to be the case that every gem method returns a No information available message in the status bar.

When I was looking into solargraph, I came across this page that describes how it uses YARD to “gather information about your project and its gem dependencies”. I work on a team where we’re pretty strict about our YARD compliance, so this development excited me. My first instinct was to look into whether ruby-lsp supported this kind of parsing. I found this issue that stated the following:

Thank you for the feature suggestion.

However, we will not add support for YARD annotations. There are multiple reasons for that

1. We try to keep the Ruby LSP's concerns related only to Ruby itself. YARD is a separate gem and not every Ruby developer uses it

2. When it comes to adding type annotations, a complete gradual type system like Sorbet or Steep yields significantly better results. They provide the ability to narrow types, widen types, use generics, interfaces, etc - things that are not possible to do with YARD annotations

3. For handling declarations that occur via meta-programming, we are going to explore both options through our [addon system](https://github.com/Shopify/ruby-lsp/blob/main/ADDONS.md) and through RBS files. RBS is significantly more expressive and thus we will favor support for that for manually written annotations. And with the addon system we hope to provide APIs for other gems to teach the indexer how to handle their meta-programming DSLs

While slightly disappointed to find that the team was not adding support for YARD annotations, their reasoning is understandable. Not everyone uses YARD and the focus of ruby-lsp should be Ruby. Support for YARD parsing through the add-on system is an interesting idea, and one that I may pursue myself. From my limited research (searching ruby-lsp- on rubygems) I was not able to find any relevant addons for my area of interest.

The Solution (maybe?)

Due to this limitation, I think I’d like to try solargraph with the solargraph-rails extension. I found this Reddit comment to be insightful:

Ruby-LSP and Solargraph take fundamentally different approaches. While Ruby-LSP relies more on fuzzy searching for class and method definitions (based on my observation as a user), Solargraph takes a more “sophisticated” approach, closely mimicking how Ruby itself resolves definitions. It accounts for module inclusions, extensions, and other language features, making its results more precise. Additionally, it supports YARD annotations, which help infer return types and handle metaprogramming gaps.

For these reasons, Solargraph remains my LSP of choice—so much so that I even created the solargraph-rspec plugin (apologies for the self-promotion!).

With the release of version 0.51.0, Solargraph now supports Ruby 3.4:
🔗 Changelog

As I mentioned here, thanks to prism’s translation support for the parser gem interface, transitioning to prism might not be as difficult as it sounds. I’m optimistic that this transition will happen in the near future. 🤞

Given this information, I think it’s only fair that I give solargraph a go and see what happens. For the purposes of this demonstration, I’m going to use bundler to see if I can get accurate information for the gems in my project, instead of all gems installed in the local version. It would be nice to avoid including solargraph in my Gemfile (since my team members don’t use it), but I’m just experimenting. There are a couple things I have to do to switch over:

• Uninstall ruby-lsp and ruby-lsp-rails in my local Rails app environment with gem uninstall ruby-lsp ruby-lsp-rails
• Remove .ruby-lsp directory (don’t think this is necessary, but I’m going to do it anyways)
• Update my nvim-lspconfig to use solargraph instead of ruby-lsp for ruby filetypes
  • This includes configuring the cmd parameter to run bundle like this: `

lspconfig.solargraph.setup({
    -- capabilities are coming from my blink.cmp config
    capabilities = capabilities,
    cmd = { "bundle", "exec", "solargraph", "stdio" },
})

• Add solargraph and solargraph-rails to my Gemfile and bundle install
• Configure solargraph with .solargraph.yml
• I’m using the config from the aforementioned Reddit user as inspiration. A default config can be generated in the Rails app directory with solargraph config.
• Cache gem documentation with bundle exec solargraph gems

I’d prefer not to include solargraph in my Gemfile, but it may be the case that I need to run bundle exec solargraph gems to cache gem documentation for my specific project instead of all gems in the local Ruby version.

After solargraph has been installed and configured, I test that it has attached to my buffer by running :LspInfo:

vim.lsp: Active Clients ~
- solargraph (id: 1)
  - Version: ? (no serverInfo.version response)
  - Root directory: ~/code/w/apotheca/rails_app
  - Command: { "~/.local/share/mise/installs/ruby/3.4.1/bin/bundle", "exec", "solargraph", "stdio" }
  - Settings: {
      solargraph = {
        diagnostics = true
      }
    }
  - Attached buffers: 2, 11

Yay! solargraph is up and running. Let’s see if I get documentation on my aforementioned .create! method. Dang… “No information available” :(

I’m able to get comprehensive LSP logs by enabling vim.lsp.set_log_level("debug") in my init.lua Neovim config. Here’s the output after pressing Shift+k:

[DEBUG][2025-03-31 15:54:24] ...m/lsp/client.lua:677	"LSP[solargraph]"	"client.request"	1	"textDocument/hover"	{ position = { character = 20, line = 8 }, textDocument = { uri = "rails_app/app/jobs/generate_report_job.rb" } }	<function 1>	11
[DEBUG][2025-03-31 15:54:24] .../vim/lsp/rpc.lua:277	"rpc.send"	{ id = 5, jsonrpc = "2.0", method = "textDocument/hover", params = { position = { character = 20, line = 8 }, textDocument = { uri = "rails_app/app/jobs/generate_report_job.rb" } } }
[DEBUG][2025-03-31 15:54:24] .../vim/lsp/rpc.lua:391	"rpc.receive"	{ id = 5, jsonrpc = "2.0" }

We can see here that there’s no content in the response from the LSP. Let’s see what happens if we try another method. I went to my model and hovered over the following line:

"ReportService::#{report_type.to_s.camelize}".safe_constantize.new

which outputted the following in my LSP log:

[DEBUG][2025-03-31 16:15:33] ...m/lsp/client.lua:677	"LSP[solargraph]"	"client.request"	1	"textDocument/hover"	{ position = { character = 50, line = 52 }, textDocument = { uri = "rails_app/app/models/report.rb" } }	<function 1>	2
[DEBUG][2025-03-31 16:15:33] .../vim/lsp/rpc.lua:277	"rpc.send"	{ id = 54, jsonrpc = "2.0", method = "textDocument/hover", params = { position = { character = 50, line = 52 }, textDocument = { uri = "rails_app/app/models/report.rb" } } }
[DEBUG][2025-03-31 16:15:33] .../vim/lsp/rpc.lua:391	"rpc.receive"	{ id = 54, jsonrpc = "2.0", result = { contents = { kind = "markdown", value = "String#safe_constantize\n\n+safe\\_constantize+ tries to find a declared constant with the name specified  \nin the string. It returns +nil+ when the name is not in CamelCase  \nor is not initialized.\n\n\n```ruby\n'Module'.safe_constantize  # => Module\n'Class'.safe_constantize   # => Class\n'blargle'.safe_constantize # => nil\n```\n\nSee ActiveSupport::Inflector.safe\\_constantize.\n\nVisibility: public" } } }

From the logs, we can see that triggering a textDocument/hover event on .safe_constantize returns the documentation in the result key.

Let’s dig into both of these examples and see if we can figure out why one is working and the other isn’t. First, let’s start with my Report.create!(...) call. .create! In Rails v7.1.5.1, .create! is a method inside ActiveRecord::Persistence::ClassMethods. Here’s the source code from the Rails v7.1.5.1 tag on GitHub:

# Creates an object (or multiple objects) and saves it to the database,
# if validations pass. Raises a RecordInvalid error if validations fail,
# unlike Base#create.
#
# The +attributes+ parameter can be either a Hash or an Array of Hashes.
# These describe which attributes to be created on the object, or
# multiple objects when given an Array of Hashes.
def create!(attributes = nil, &block)
  if attributes.is_a?(Array)
    attributes.collect { |attr| create!(attr, &block) }
  else
    object = new(attributes, &block)
    object.save!
    object
  end
end

We can see here that the documentation is clearly defined. Given solargraph’s ability to parse YARD docs into LSP documentation, this should show up IF solargraph is able to figure out that the .create! that I’m calling is, in fact, the one defined in ActiveRecord::Persistence::ClassMethods. If I run bundle exec yard server --gems in the root of my project directory, I get interactive YARD docs for my installed gems at localhost::8808. If I navigate to ActiveRecord::Persistence::ClassMethods, I see docs for the .create! method! Something is not right…

Digging around in the solargraph repo, I found this gist. A comment at the top reveals what might be going wrong:

# The following comments fill some of the gaps in Solargraph's understanding of
# Rails apps. Since they're all in YARD, they get mapped in Solargraph but
# ignored at runtime.

Adding the gist to the root of the directory “fills some of the gaps” in how solargraph works with Rails apps. If we can trick solargraph into parsing this file as valid Ruby code, we should be able to get intellisense and hover definitions, even if we don’t explicitly include/extend these modules/classes in other places.

After adding the contents of the gist to a file called solargraph_extensions.rb to the root of my directory and restarting solargraph, I was praying that Shift+k on my Report.create!(...) would give me hover docs. And…

“No information available.”

I’m starting to run out of steam on this. As a last ditch effort, I tried running solargraph scan -v. This command does the following, according to the command line documentation:

A scan loads the entire workspace to make sure that the ASTs and maps do not raise errors during analysis. It does not perform any type checking or validation; it only confirms that the analysis itself is error-free.

After a mostly successful scan, I noticed an error when parsing Thor, the tool used to build CLIs in Rails apps. The scan outputted the following error:

[Solargraph::ComplexTypeError]: Invalid close in type DidYouMean::SpellChecker)

You can view the whole stack trace in the error I reported in the solargraph repo. For now, I’m going to tell myself that my additional documentation isn’t loading because I’m erroring out during the solargraph indexing process. Whether or not this is true, I’m not sure. I am definitely sure that I’m done for the night…

The Next Day

Something extraordinary has occurred. I have figured something out. This problem may have been unique to my development setup for the project I’m working on. At my place of work, we have a standardized setup for our development environments. It looks like this:

1. Boot up a Vagrant machine
2. Spin up all the application services using a Docker Swarm
3. Boot up the Rails app after everything is set up
4. Sync the local rails_app folder with the rails_app folder in the Vagrant box

This allows for a development environment that can be developed locally in an editor, but we have to run our Rails commands, like bundle exec rspec inside the Docker container INSIDE the Vagrant box. This isn’t too bad, it just takes a couple extra steps.

LSP (Language Server Protocol) integration was the tricky part of this setup. After some experimentation with connecting to the LSP running inside the Vagrant box, I decided I would just run the same version of ruby-lsp locally, as it was close enough.

The whole reason I decided I wanted to switch over to solargraph was because I believed that ruby-lsp didn’t support any Rails documentation, just raw Ruby stuff. This was a misinformed assumption, as I didn’t really understand how ruby-lsp-rails worked.

Upon a little more reading, I read something that piqued my interest:

Runtime Introspection

LSP tooling is typically based on static analysis, but ruby-lsp-rails actually communicates with your Rails app for some features.

When Ruby LSP Rails starts, it spawns a rails runner instance which runs server.rb. The add-on communicates with this process over a pipe (i.e. stdin and stdout) to fetch runtime information about the application.

When extension is stopped (e.g. by quitting the editor), the server instance is shut down.

When I read this, the thought occurred to me: “What if rails runner isn’t working because of my complicated development environment?”

I tried this command:

bin/rails rails runner ~/.local/share/mise/installs/ruby/3.4.1/lib/ruby/gems/3.4.0/gems/ruby-lsp-rails-0.4.0/lib/ruby_lsp/ruby_lsp_rails/server.rb start

and I got the following output:

.local/share/mise/installs/ruby/3.4.1/lib/ruby/gems/3.4.0/gems/activesupport-7.1.5.1/lib/active_support/message_encryptor.rb:307:in 'OpenSSL::Cipher#key=': key must be 16 bytes (ArgumentError)

What if something about my local credentials file wasn’t being synced correctly and this was preventing ruby-lsp-rails from spinning up the Runtime Introspection? What if that was preventing my LSP client from receiving better documentation for Rails classes/methods?

After sshing into my virtual machine, copying the encrypted key, removing my current development.key(which was empty) and replacing it with the contents of the remote file, I watched the LSP logs for signs of life.

[INFO][2025-04-01 13:37:23] ...lsp/handlers.lua:566	"Finished booting Ruby LSP Rails server"

Ok… This looks good. I haven’t seen this in the logs before. Let’s try Shift+k on my .create! method.

😭

The gist is this: the “more” modal that pops up on the advanced search page is the same one that it used for basic search. However, the advanced search facets differ from the basic search facets because they are multi-select, resulting in a functional inconsistency. Clicking on a facet within this modal links to a search instead of checking a checkbox.

I chose to implement a custom JS solution that would give the user a clean, searchable interface that falls in line with what one would expect from a multi-select dropdown. For my implementation, I chose TomSelect - It’s small, functional, and has a Bootstrap 5 theme that blends nicely with our catalog. It’s likely that you could implement another JS dropdown fairly easily, but this guide will focus on TomSelect specifically.

Removing the Facet Limit

The first step in this implementation is to remove the default limit of 10 facets on the advanced search page. Without doing this, only the first 10 facets will show up in our dropdown. For this guide, I’m using Blacklight 8.3.0, which has Advanced Search built in. Because this built-in version is slightly less configurable than the Advanced Search plugin, we need to add some configuration options to our search builder.

# This class extends Blacklight::SearchBuilder to add additional functionality
class SearchBuilder < Blacklight::SearchBuilder
  include Blacklight::Solr::SearchBuilderBehavior

  self.default_processor_chain += [:facets_for_advanced_search_form]

  # Merge the advanced search form parameters into the solr parameters
  # @param [Hash] solr_p the current solr parameters
  # @return [Hash] the solr parameters with the additional advanced search form parameters
  def facets_for_advanced_search_form(solr_p)
    return unless search_state.controller&.action_name == 'advanced_search' &&
                  blacklight_config.advanced_search[:form_solr_parameters]

    solr_p.merge!(blacklight_config.advanced_search[:form_solr_parameters])
  end
end

We add a new step to our default_processor_chain that merges in some new advanced search parameters to our existing Solr parameters. With this configuration in place, we can add the following configuration to our catalog_controller.rb:

# Remove facet limits on the advanced search form; if we limit these, we see the modal that does not allow for
# multiple selection, which is essential to the advanced search facet functionality.
config.advanced_search = Blacklight::OpenStructWithHashAccess.new(
  enabled: true,
  form_solr_parameters: {
    'facet.field': %w[access_facet format_facet language_facet library_facet
                      location_facet classification_facet recently_published_facet],
    'f.access_facet.facet.limit': '-1',
    'f.format_facet.facet.limit': '-1',
    'f.language_facet.facet.limit': '-1',
    'f.library_facet.facet.limit': '-1',
    'f.location_facet.facet.limit': '-1',
    'f.classification_facet.facet.limit': '-1',
    'f.recently_published_facet.facet.limit': '-1'
  }
)

By setting the facet limit to -1, we effectively disable the limit altogether and receive a comprehensive list of all facets with our query. In this example, I’m setting these params for the specific facets that I chose to include on my advanced search form. You’ll have to decide which facets you’d like to include and update this config accordingly.

Creating a Custom Component

We’ll need a custom component for our multi-select facet. I chose to name mine MultiSelectFacetComponent. Here’s what mine looks like:

module Catalog
  module AdvancedSearch
    # Multi select facet component using TomSelect
    class MultiSelectFacetComponent < Blacklight::Component
      def initialize(facet_field:, layout: nil)
        @facet_field = facet_field
        @layout = layout == false ? FacetFieldNoLayoutComponent : Blacklight::FacetFieldComponent
      end

      # @return [Boolean] whether to render the component
      def render?
        presenters.any?
      end

      # @return [Array<Blacklight::FacetFieldPresenter>] array of facet field presenters
      def presenters
        return [] unless @facet_field.paginator

        return to_enum(:presenters) unless block_given?

        @facet_field.paginator.items.each do |item|
          yield @facet_field.facet_field
                            .item_presenter
                            .new(item, @facet_field.facet_field, helpers, @facet_field.key, @facet_field.search_state)
        end
      end

      # @return [Hash] HTML attributes for the select element
      def select_attributes
        {
          class: "#{@facet_field.key}-select",
          name: "f_inclusive[#{@facet_field.key}][]",
          placeholder: I18n.t('facets.advanced_search.placeholder'),
          multiple: true,
          data: {
            controller: 'multi-select',
            multi_select_plugins_value: select_plugins.to_json
          }
        }
      end

      # @return [Hash] HTML attributes for the option elements within the select element
      def option_attributes(presenter:)
        {
          value: presenter.value,
          selected: presenter.selected? ? 'selected' : nil
        }
      end

      # TomSelect functionality can be expanded with plugins. `checkbox_options`
      # allow us to use the existing advanced search facet logic by using checkboxes.
      # More plugins can be found here: https://tom-select.js.org/plugins/
      #
      # @return [Array<String>] array of TomSelect plugins
      def select_plugins
        %w[checkbox_options caret_position input_autogrow clear_button]
      end
    end
  end
end

The presenters, render, and initialize method are copied over from the default Blacklight FacetFieldCheckboxesComponent which can be found here. Let’s expand on some of the other methods.

# @return [Hash] HTML attributes for the select element
def select_attributes
  {
    class: "#{@facet_field.key}-select",
    name: "f_inclusive[#{@facet_field.key}][]",
    placeholder: I18n.t('facets.advanced_search.placeholder'),
    multiple: true,
    data: {
  	controller: 'multi-select',
  	multi_select_plugins_value: select_plugins.to_json
    }
  }
end

As you might be able to tell, these are attributes on the select element in the generated HTML. The most important value here is the name - in order for the facets to work correctly, we have to name this parameter properly. This allows us to properly facet on form submission. class and placeholer will depend on the specifics of your implementation. multiple should always be enabled if we want the select box to work as a multi-select. data allows us to connect to our Stimulus controller (called multi_select_controller.js), which we’ll go over later. TomSelect allows for expanded functionality using plugins - I chose to specify these in the component like this:

def select_plugins
  %w[checkbox_options caret_position input_autogrow clear_button]
end

These values will be read into the Stimulus controller and used when we instantiate TomSelect.

The View

<%= render(@layout.new(facet_field: @facet_field)) do |component| %>  
  <% component.with_label do %>  
    <%= @facet_field.label %>  
  <% end %>  
  <% component.with_body do %>  
    <div class="facet-multi-select">  
      <select <%= tag.attributes(select_attributes) %>>  
        <% presenters.each do |presenter| %>  
          <option <%= tag.attributes(option_attributes(presenter: presenter)) %>>  
            <%= "#{presenter.label} (#{number_with_delimiter(presenter.hits)})" %>  
          </option>  
        <% end %>  
      </select>  
    </div>  
  <% end %>  
<% end %>

This code should be mostly self-explanatory. We pass the attributes mentioned before to the select element with tag.attributes, which takes that hash and turns it into HTML attributes.

After this component has been created, we must tell Blacklight to use our component instead of the default one. This can be done with a simple configuration in our catalog_controller.rb. This is just one facet, but this must be done for each facet on the advanced search page that you’d like to use the custom component for:

config.add_facet_field :language_facet, label: I18n.t('facets.language'), limit: true do |field|  
  field.advanced_search_component = Catalog::AdvancedSearch::MultiSelectFacetComponent  
end

The Javascript

Lastly, we need the actual JS to make this work. For this example, we’re utilizing importmap-rails. We’ll download the TomSelect JS to our /vendor/javascript folder with the following console command:

./bin/importmap pin tom-select

We’ll pin it in importmap.rb:

pin 'tom-select', preload: true # @2.3.1

And import it in our application.js:

import "tom-select";

To use the Bootstrap 5 theme, we’ll need to pull that CSS in separately into our application.scss:

@import url("https://cdn.jsdelivr.net/npm/tom-select@2.3.1/dist/css/tom-select.bootstrap5.min.css");

I’m trying to recall why exactly we chose to download the JS and pull in the CSS - I think our CSS pre-processor didn’t like the vendor SCSS - this may become easier in the future with new Rails asset pipeline stuff in the works.

The Stimulus Controller

Using Stimulus, we’ll connect the select element on the page to a JS controller that will instantiate the TomSelect behavior. I’m going to post the whole controller below and break it down:

import { Controller } from "@hotwired/stimulus";
import TomSelect from "tom-select";

export default class extends Controller {
  static values = {
    plugins: Array,
  };

  connect() {
    this.select = new TomSelect(this.element, {
      plugins: this.pluginsValue,
      // Passing the `item` function to the `render` arg allows us to customize what the selected item looks like when it's
      // added to the list of selected items. In this case, we're just wrapping the value (coming from the data set) in a
      // div to remove the count that's displayed in the option list.
      render: {
        item: function (data, escape) {
          return `<div>${escape(data.value)}</div>`;
        },
      },
    });
  }

  disconnect() {
    this.select?.destroy();
  }
}

After importing the Stimulus code and pulling in the TomSelect element, we instantiate the plugins array that we passed in as part of our MultiSelectFacetComponent. The connect lifecycle method is called when the Stimulus controller connects to the DOM element (in this case, it’s attached to the <select> element). Here’s what happens:

1. We assign this.select to be a new TomSelect which takes the element that our Stimulus controller is attached to (in this case, the <select> element) as the first argument and a configuration object as its second argument.
2. In this configuration, we tell it to use the plugins that we specified in our component.
3. We also tell it to render each item (when selected) as just the bare data.value - or the facet value - without the result counter.
4. On disconnect, we destroy the custom select element. You can find all the configuration options on the TomSelect documentation page.

That’s it! You should have a working custom JS multi-select on your Advanced Search page. If you’re having trouble with setting this up yourself or just need some assistance in your own implementation, feel free to send me an email at pperkins@upenn.edu.