Add 'solargraph pin' command for debugging

.github/workflows/rspec.yml

@@ -29,6 +29,14 @@ jobs:
             rbs-version: '3.9.4'
           - ruby-version: '3.0'
             rbs-version: '4.0.0.dev.4'
+          # Missing require in 'rbs collection update' - hopefully
+          # fixed in next RBS release
+          - ruby-version: 'head'
+            rbs-version: '4.0.0.dev.4'
+          - ruby-version: 'head'
+            rbs-version: '3.9.4'
+          - ruby-version: 'head'
+            rbs-version: '3.6.1'
     steps:
     - uses: actions/checkout@v3
     - name: Set up Ruby
@@ -48,6 +56,9 @@ jobs:
       run: |
         bundle install
         bundle update rbs # use latest available for this Ruby version
+    - name: Update types
+      run: |
+        bundle exec rbs collection update
     - name: Run tests
       run: bundle exec rake spec
   undercover:

.rubocop_todo.yml

@@ -34,7 +34,6 @@ Gemspec/OrderedDependencies:
 # Configuration parameters: Severity.
 Gemspec/RequireMFA:
   Exclude:
-    - 'solargraph.gemspec'
     - 'spec/fixtures/rdoc-lib/rdoc-lib.gemspec'
     - 'spec/fixtures/rubocop-custom-version/specifications/rubocop-0.0.0.gemspec'
 
@@ -664,14 +663,6 @@ RSpec/LetBeforeExamples:
   Exclude:
     - 'spec/complex_type_spec.rb'
 
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: have_received, receive
-RSpec/MessageSpies:
-  Exclude:
-    - 'spec/doc_map_spec.rb'
-    - 'spec/language_server/host/diagnoser_spec.rb'
-    - 'spec/language_server/host/message_worker_spec.rb'
-
 RSpec/MissingExampleGroupArgument:
   Exclude:
     - 'spec/diagnostics/rubocop_helpers_spec.rb'
@@ -732,10 +723,6 @@ RSpec/ScatteredLet:
   Exclude:
     - 'spec/complex_type_spec.rb'
 
-RSpec/StubbedMock:
-  Exclude:
-    - 'spec/language_server/host/message_worker_spec.rb'
-
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Enabled: false

lib/solargraph/api_map.rb

@@ -537,7 +537,7 @@ def get_method_stack rooted_tag, name, scope: :instance, visibility: [:private,
     # @deprecated Use #get_path_pins instead.
     #
     # @param path [String] The path to find
-    # @return [Enumerable<Solargraph::Pin::Base>]
+    # @return [Array<Solargraph::Pin::Base>]
     def get_path_suggestions path
       return [] if path.nil?
       resolve_method_aliases store.get_path_pins(path)
@@ -546,7 +546,7 @@ def get_path_suggestions path
     # Get an array of pins that match the specified path.
     #
     # @param path [String]
-    # @return [Enumerable<Pin::Base>]
+    # @return [Array<Pin::Base>]
     def get_path_pins path
       get_path_suggestions(path)
     end

lib/solargraph/shell.rb

@@ -241,8 +241,94 @@ def list
       puts "#{workspace.filenames.length} files total."
     end
 
+    # @sg-ignore Unresolved call to desc
+    desc 'pin [PATH]', 'Describe a pin', hide: true
+    # @sg-ignore Unresolved call to option
+    option :rbs, type: :boolean, desc: 'Output the pin as RBS', default: false
+    # @sg-ignore Unresolved call to option
+    option :typify, type: :boolean, desc: 'Output the calculated return type of the pin from annotations', default: false
+    # @sg-ignore Unresolved call to option
+    option :references, type: :boolean, desc: 'Show references', default: false
+    # @sg-ignore Unresolved call to option
+    option :probe, type: :boolean, desc: 'Output the calculated return type of the pin from annotations and inference', default: false
+    # @sg-ignore Unresolved call to option
+    option :stack, type: :boolean, desc: 'Show entire stack of a method pin by including definitions in superclasses', default: false
+    # @param path [String] The path to the method pin, e.g. 'Class#method' or 'Class.method'
+    # @return [void]
+    def pin path
+      api_map = Solargraph::ApiMap.load_with_cache('.', $stderr)
+      is_method = path.include?('#') || path.include?('.')
+      # @sg-ignore Unresolved call to options
+      if is_method && options[:stack]
+        scope, ns, meth = if path.include? '#'
+                            [:instance, *path.split('#', 2)]
+                          else
+                            [:class, *path.split('.', 2)]
+                          end
+
+        # @sg-ignore Wrong argument type for
+        #   Solargraph::ApiMap#get_method_stack: rooted_tag
+        #   expected String, received Array<String>
+        pins = api_map.get_method_stack(ns, meth, scope: scope)
+      else
+        pins = api_map.get_path_pins path
+      end
+      references = {}
+      pin = pins.first
+      case pin
+      when nil
+        $stderr.puts "Pin not found for path '#{path}'"
+        exit 1
+      when Pin::Namespace
+        # @sg-ignore Unresolved call to options
+        if options[:references]
+          superclass_tag = api_map.qualify_superclass(pin.return_type.tag)
+          superclass_pin = api_map.get_path_pins(superclass_tag).first if superclass_tag
+          references[:superclass] = superclass_pin if superclass_pin
+        end
+      when Pin::Method
+        # @sg-ignore Unresolved call to options
+        if options[:references]
+          ([pin] + pin.signatures).compact.each do |sig|
+            sig.parameters.each do |param|
+              references[param.name] = param
+            end
+            if sig.block
+              references[:block] = sig.block
+            end
+          end
+        end
+      end
+
+      pins.each do |pin|
+        present_pin(pin, api_map)
+      end
+
+      references.each do |key, refpin|
+        puts "\n# #{key.to_s.capitalize}:\n\n"
+        present_pin(refpin, api_map)
+      end
+    end
+
     private
 
+    # @param pin [Solargraph::Pin::Base]
+    # @param api_map [Solargraph::ApiMap]
+    # @return [void]
+    def present_pin pin, api_map
+      # @sg-ignore Unresolved call to options
+      if options[:typify] || options[:probe]
+          type = ComplexType::UNDEFINED
+          # @sg-ignore Unresolved call to options
+          type = pin.typify(api_map) if options[:typify]
+          # @sg-ignore Unresolved call to options
+          type = pin.probe(api_map) if options[:probe] && type.undefined?
+          print_type(type)
+      else
+        print_pin(pin)
+      end
+    end
+
     # @param pin [Solargraph::Pin::Base]
     # @return [String]
     def pin_description pin
@@ -267,5 +353,27 @@ def do_cache gemspec, api_map
       #   typecheck doesn't complain on the below line
       api_map.cache_gem(gemspec, rebuild: options.rebuild, out: $stdout)
     end
+
+    # @param type [ComplexType]
+    # @return [void]
+    def print_type(type)
+      # @sg-ignore Unresolved call to options
+      if options[:rbs]
+        puts type.to_rbs
+      else
+        puts type.rooted_tag
+      end
+    end
+
+    # @param pin [Solargraph::Pin::Base]
+    # @return [void]
+    def print_pin(pin)
+      # @sg-ignore Unresolved call to options
+      if options[:rbs]
+        puts pin.to_rbs
+      else
+        puts pin.inspect
+      end
+    end
   end
 end

spec/doc_map_spec.rb

@@ -42,8 +42,9 @@
   it 'does not warn for redundant requires' do
     # Requiring 'set' is unnecessary because it's already included in core. It
     # might make sense to log redundant requires, but a warning is overkill.
-    expect(Solargraph.logger).not_to receive(:warn).with(/path set/)
+    allow(Solargraph.logger).to receive(:warn).and_call_original
     Solargraph::DocMap.new(['set'], [])
+    expect(Solargraph.logger).not_to have_received(:warn).with(/path set/)
   end
 
   it 'ignores nil requires' do

spec/language_server/host/diagnoser_spec.rb

@@ -3,7 +3,8 @@
     host = double(Solargraph::LanguageServer::Host, options: { 'diagnostics' => true }, synchronizing?: false)
     diagnoser = Solargraph::LanguageServer::Host::Diagnoser.new(host)
     diagnoser.schedule 'file.rb'
-    expect(host).to receive(:diagnose).with('file.rb')
+    allow(host).to receive(:diagnose)
     diagnoser.tick
+    expect(host).to have_received(:diagnose).with('file.rb')
   end
 end

spec/language_server/host/message_worker_spec.rb

@@ -2,11 +2,12 @@
   it "handle requests on queue" do
     host = double(Solargraph::LanguageServer::Host)
     message = {'method' => '$/example'}
-    expect(host).to receive(:receive).with(message).and_return(nil)
+    allow(host).to receive(:receive).with(message).and_return(nil)
 
     worker = Solargraph::LanguageServer::Host::MessageWorker.new(host)
     worker.queue(message)
     expect(worker.messages).to eq [message]
     worker.tick
+    expect(host).to have_received(:receive).with(message)
   end
 end

spec/shell_spec.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 require 'tmpdir'
 require 'open3'
 
 describe Solargraph::Shell do
+  let(:shell) { described_class.new }
+
   let(:temp_dir) { Dir.mktmpdir }
 
   before do
@@ -41,4 +45,114 @@ def bundle_exec(*cmd)
       expect(output).to include('Clearing pin cache in')
     end
   end
+
+  # @type cmd [Array<String>]
+  # @return [String]
+  def bundle_exec(*cmd)
+    # run the command in the temporary directory with bundle exec
+    Bundler.with_unbundled_env do
+      output, status = Open3.capture2e("bundle exec #{cmd.join(' ')}")
+      expect(status.success?).to be(true), "Command failed: #{output}"
+      output
+    end
+  end
+
+  describe 'pin' do
+    let(:api_map) { instance_double(Solargraph::ApiMap) }
+    let(:to_s_pin) { instance_double(Solargraph::Pin::Method, return_type: Solargraph::ComplexType.parse('String')) }
+
+    before do
+      allow(Solargraph::Pin::Method).to receive(:===).with(to_s_pin).and_return(true)
+      allow(Solargraph::ApiMap).to receive(:load_with_cache).and_return(api_map)
+      allow(api_map).to receive(:get_path_pins).with('String#to_s').and_return([to_s_pin])
+    end
+
+    context 'with no options' do
+      it 'prints a pin' do
+        allow(to_s_pin).to receive(:inspect).and_return('pin inspect result')
+
+        out = capture_both { shell.pin('String#to_s') }
+
+        expect(out).to eq("pin inspect result\n")
+      end
+    end
+
+    context 'with --rbs option' do
+      it 'prints a pin with RBS type' do
+        allow(to_s_pin).to receive(:to_rbs).and_return('pin RBS result')
+
+        out = capture_both do
+          shell.options = { rbs: true }
+          shell.pin('String#to_s')
+        end
+        expect(out).to eq("pin RBS result\n")
+      end
+    end
+
+    context 'with --stack option' do
+      it 'prints a pin using stack results' do
+        allow(to_s_pin).to receive(:to_rbs).and_return('pin RBS result')
+
+        allow(api_map).to receive(:get_method_stack).and_return([to_s_pin])
+        capture_both do
+          shell.options = { stack: true }
+          shell.pin('String#to_s')
+        end
+        expect(api_map).to have_received(:get_method_stack).with('String', 'to_s', scope: :instance)
+      end
+
+      it 'prints a static pin using stack results' do
+        # allow(to_s_pin).to receive(:to_rbs).and_return('pin RBS result')
+        string_new_pin = instance_double(Solargraph::Pin::Method, return_type: Solargraph::ComplexType.parse('String'))
+
+        allow(api_map).to receive(:get_method_stack).with('String', 'new', scope: :class).and_return([string_new_pin])
+        allow(Solargraph::Pin::Method).to receive(:===).with(string_new_pin).and_return(true)
+        allow(api_map).to receive(:get_path_pins).with('String.new').and_return([string_new_pin])
+        capture_both do
+          shell.options = { stack: true }
+          shell.pin('String.new')
+        end
+        expect(api_map).to have_received(:get_method_stack).with('String', 'new', scope: :class)
+      end
+    end
+
+    context 'with --typify option' do
+      it 'prints a pin with typify type' do
+        allow(to_s_pin).to receive(:typify).and_return(Solargraph::ComplexType.parse('::String'))
+
+        out = capture_both do
+          shell.options = { typify: true }
+          shell.pin('String#to_s')
+        end
+        expect(out).to eq("::String\n")
+      end
+    end
+
+    context 'with --typify --rbs options' do
+      it 'prints a pin with typify type' do
+        allow(to_s_pin).to receive(:typify).and_return(Solargraph::ComplexType.parse('::String'))
+
+        out = capture_both do
+          shell.options = { typify: true, rbs: true }
+          shell.pin('String#to_s')
+        end
+        expect(out).to eq("::String\n")
+      end
+    end
+
+    context 'with no pin' do
+      it 'prints error' do
+        allow(api_map).to receive(:get_path_pins).with('Not#found').and_return([])
+        allow(Solargraph::Pin::Method).to receive(:===).with(nil).and_return(false)
+
+        out = capture_both do
+          shell.options = {}
+          shell.pin('Not#found')
+        rescue SystemExit
+          # Ignore the SystemExit raised by the shell when no pin is found
+        end
+        expect(out).to include("Pin not found for path 'Not#found'")
+      end
+    end
+  end
 end

spec/spec_helper.rb

@@ -43,3 +43,29 @@ def with_env_var(name, value)
     ENV[name] = old_value  # Restore the old value
   end
 end
+
+def capture_stdout &block
+  original_stdout = $stdout
+  $stdout = StringIO.new
+  begin
+    block.call
+    $stdout.string
+  ensure
+    $stdout = original_stdout
+  end
+end
+
+def capture_both &block
+  original_stdout = $stdout
+  original_stderr = $stderr
+  stringio = StringIO.new
+  $stdout = stringio
+  $stderr = stringio
+  begin
+    block.call
+  ensure
+    $stdout = original_stdout
+    $stderr = original_stderr
+  end
+  stringio.string
+end