solargraph 0.58.3 → 0.60.0

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## 0.60.0 - June 15, 2026
+- Add YARD macro support for DSL methods (#1187)
+- YARD macros - More typecheck fixes (#1188)
+- Macro fixes (#1189)
+- Unused macro methods (#1191)
+- Transitive macros (#1203)
+- Allow CTRL-C interruption of profile command + macro debug logs (#1206)
+- Support for Inline RBS (#1173)
+- Make typechecker errors vim quickfix friendly (#1072)
+- Generate RBS (#812)
+
+## 0.59.2 - May 22, 2026
+- Convert RBS implicit nil annotations (#1197)
+- Temporary job stubs (#1200)
+- Limit pin combination to doc maps (#1195)
+- Ignore literal values in type inference (#1201)
+- Fix for clips with flaky node recipients
+
+## 0.59.1 - May 18, 2026
+- Fix signatureHelp bug (#1185)
+- Linting fixes for Ruby 3.1 (#1193)
+- Parameters shadow local variables with same name (#1192)
+
+## 0.59.0 - May 13, 2026
+- Ensure pathname is required for rbs in shell caching processes (#1183)
+- Pre-release branch 2026-01-12 (#1152)
+- 2026-01-27 dev branch (#1165)
+- Position linting (#1179)
+- Revert YARD and RBS pin caching (#1180)
+- Ensure pathname is required for rbs in shell caching processes (#1183)
+- Limit default include glob to current directory (#1184) 
+- Require Ruby >= 3.1.0
+- Require RBS >= 3.10.0
+- Stub combine_same_type_arity_signatures (#1186)
+
 ## 0.58.3 - March 9, 2026
 - Ignore workspace dependencies in cache processes (#1174)
 

data/Gemfile

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec name: 'solargraph'
 
+# Test fixture gems
+gem 'gem-with-yard-macros', path: 'spec/fixtures/gem-with-yard-macros'
+
 # Local gemfile for development tools, etc.
-local_gemfile = File.expand_path(".Gemfile", __dir__)
+local_gemfile = File.expand_path('.Gemfile', __dir__)
 instance_eval File.read local_gemfile if File.exist? local_gemfile

data/README.md

@@ -51,6 +51,8 @@ Plug-ins and extensions are available for the following editors:
 
 Solargraph's behavior can be controlled via optional [configuration](https://solargraph.org/guides/configuration) files. The highest priority file is a `.solargraph.yml` file at the root of the project. If not present, any global configuration at `~/.config/solargraph/config.yml` will apply. The path to the global configuration can be overridden with the `SOLARGRAPH_GLOBAL_CONFIG` environment variable.
 
+Use `bundle exec solargraph config` to create a configuration file.
+
 ### Plugins
 
 Solargraph supports [plugins](https://solargraph.org/guides/plugins) that implement their own Solargraph features, such as diagnostics reporters and conventions to provide LSP features and type-checking, e.g. for frameworks which use metaprogramming and/or DSLs.
@@ -132,9 +134,7 @@ See [https://solargraph.org/guides](https://solargraph.org/guides) for more tips
 
 ### Development
 
-To see more logging when typechecking or running specs, set the
-`SOLARGRAPH_LOG` environment variable to `debug` or `info`.  `warn` is
-the default value.
+To see more logging when typechecking or running specs, set the `SOLARGRAPH_LOG` environment variable to `debug` or `info`.  `warn` is the default value.
 
 Code contributions are always appreciated. Feel free to fork the repo and submit pull requests. Check for open issues that could use help. Start new issues to discuss changes that have a major impact on the code or require large time commitments.
 

data/Rakefile

@@ -1,42 +1,44 @@
+# frozen_string_literal: true
+
 require 'rake'
 require 'bundler/gem_tasks'
 require 'fileutils'
 require 'open3'
 
-desc "Open a Pry session preloaded with this library"
+desc 'Open a Pry session preloaded with this library'
 task :console do
-  sh "pry -I lib -r solargraph.rb"
+  sh 'pry -I lib -r solargraph.rb'
 end
 
-desc "Run the type checker"
+desc 'Run the type checker'
 task typecheck: [:typecheck_strong]
 
-desc "Run the type checker at typed level - return code issues provable without annotations being correct"
+desc 'Run the type checker at typed level - return code issues provable without annotations being correct'
 task :typecheck_typed do
-  sh "SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level typed"
+  sh 'SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level typed'
 end
 
-desc "Run the type checker at strict level - report issues using type annotations"
+desc 'Run the type checker at strict level - report issues using type annotations'
 task :typecheck_strict do
-  sh "SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level strict"
+  sh 'SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level strict'
 end
 
-desc "Run the type checker at strong level - enforce that type annotations exist"
+desc 'Run the type checker at strong level - enforce that type annotations exist'
 task :typecheck_strong do
-  sh "SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level strong"
+  sh 'SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level strong'
 end
 
-desc "Run the type checker at alpha level - run high-false-alarm checks"
+desc 'Run the type checker at alpha level - run high-false-alarm checks'
 task :typecheck_alpha do
-  sh "SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level alpha"
+  sh 'SOLARGRAPH_ASSERTS=on bundle exec solargraph typecheck --level alpha'
 end
 
-desc "Run RSpec tests, starting with the ones that failed last time"
+desc 'Run RSpec tests, starting with the ones that failed last time'
 task spec: %i[spec_failed undercover_no_fail full_spec] do
   undercover
 end
 
-desc "Run all RSpec tests"
+desc 'Run all RSpec tests'
 task :full_spec do
   warn 'starting spec'
   sh 'TEST_COVERAGE_COMMAND_NAME=full-new bundle exec rspec' #  --profile'
@@ -63,19 +65,20 @@ def undercover
   status
 rescue StandardError => e
   warn "hit error: #{e.message}"
+  # @sg-ignore Need to add nil check here
   warn "Backtrace:\n#{e.backtrace.join("\n")}"
   warn "output: #{output}"
-  puts "Flushing"
+  puts 'Flushing'
   $stdout.flush
   raise
 end
 
-desc "Check PR coverage"
+desc 'Check PR coverage'
 task :undercover do
-  raise "Undercover failed" unless undercover.success?
+  raise 'Undercover failed' unless undercover.success?
 end
 
-desc "Branch-focused fast-feedback quality/spec/coverage checks"
+desc 'Branch-focused fast-feedback quality/spec/coverage checks'
 task test: %i[overcommit spec typecheck] do
   # do these in order
   Rake::Task['typecheck_strict'].invoke
@@ -83,18 +86,18 @@ task test: %i[overcommit spec typecheck] do
   Rake::Task['typecheck_alpha'].invoke
 end
 
-desc "Re-run failed specs.  Add --fail-fast in your .rspec-local file if desired."
+desc 'Re-run failed specs.  Add --fail-fast in your .rspec-local file if desired.'
 task :spec_failed do
   # allow user to check out any persistent failures while looking for
   # more in the whole test suite
   sh 'TEST_COVERAGE_COMMAND_NAME=next-failure bundle exec rspec --only-failures || true'
 end
 
-desc "Run undercover and show output without failing the task if it fails"
+desc 'Run undercover and show output without failing the task if it fails'
 task :undercover_no_fail do
   undercover
 rescue StandardError
-  puts "Undercover failed, but continuing with other tasks."
+  puts 'Undercover failed, but continuing with other tasks.'
 end
 
 # @return [void]
@@ -103,7 +106,7 @@ def simplecov_collate
   require 'simplecov-lcov'
   require 'undercover/simplecov_formatter'
 
-  SimpleCov.collate(Dir["coverage/{next-failure,full,ad-hoc}/.resultset.json"]) do
+  SimpleCov.collate(Dir['coverage/{next-failure,full,ad-hoc}/.resultset.json']) do
     cname = 'combined'
     command_name cname
     new_dir = File.join('coverage', cname)
@@ -118,7 +121,7 @@ def simplecov_collate
              ])
     SimpleCov::Formatter::LcovFormatter.config.report_with_single_file = true
   end
-  puts "Simplecov collated results into coverage/combined/.resultset.json"
+  puts 'Simplecov collated results into coverage/combined/.resultset.json'
 rescue StandardError => e
   puts "Simplecov collate failed: #{e.message}"
 ensure
@@ -130,7 +133,7 @@ task :simplecov_collate do
   simplecov_collate
 end
 
-desc "Show quality checks on this development branch so far, including any staged files"
+desc 'Show quality checks on this development branch so far, including any staged files'
 task :overcommit do
   # OVERCOMMIT_DEBUG=1 will show more detail
   sh 'SOLARGRAPH_ASSERTS=on bundle exec overcommit --run --diff origin/master'

data/bin/solargraph

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 # turn off warning diagnostics from Ruby
-$VERBOSE=nil
+$VERBOSE = nil
 
 require 'solargraph'
 

data/lib/solargraph/api_map/cache.rb

@@ -8,7 +8,7 @@ module Solargraph
         @methods = {}
         # @type [Hash{String, Array<String> => Array<Pin::Base>}]
         @constants = {}
-        # @type [Hash{String => String}]
+        # @type [Hash{String => String, nil}]
         @qualified_namespaces = {}
         # @type [Hash{String => Pin::Method}]
         @receiver_definitions = {}
@@ -61,14 +61,14 @@ module Solargraph
 
       # @param name [String]
       # @param context [String]
-      # @return [String]
+      # @return [String, nil]
       def get_qualified_namespace name, context
         @qualified_namespaces["#{name}|#{context}"]
       end
 
       # @param name [String]
       # @param context [String]
-      # @param value [String]
+      # @param value [String, nil]
       # @return [void]
       def set_qualified_namespace name, context, value
         @qualified_namespaces["#{name}|#{context}"] = value

data/lib/solargraph/api_map/constants.rb

@@ -27,9 +27,11 @@ module Solargraph
       # @param name [String] Namespace which may relative and not be rooted.
       # @param gates [Array<Array<String>, String>] Namespaces to search while resolving the name
       #
+      # @sg-ignore flow sensitive typing needs to eliminate literal from union with return if foo == :bar
       # @return [String, nil] fully qualified namespace (i.e., is
       #   absolute, but will not start with ::)
       def resolve(name, *gates)
+        # @sg-ignore Need to add nil check here
         return store.get_path_pins(name[2..]).first&.path if name.start_with?('::')
 
         flat = gates.flatten
@@ -86,6 +88,7 @@ module Solargraph
         return unless fqns
         pin = store.get_path_pins(fqns).first
         if pin.is_a?(Pin::Constant)
+          # @sg-ignore Need to add nil check here
           const = Solargraph::Parser::NodeMethods.unpack_name(pin.assignment)
           return unless const
           fqns = resolve(const, *pin.gates)
@@ -105,6 +108,7 @@ module Solargraph
 
       # @param name [String]
       # @param gates [Array<String>]
+      # @sg-ignore flow sensitive typing should be able to handle redefinition
       # @return [String, nil]
       def resolve_and_cache name, gates
         cached_resolve[[name, gates]] = :in_process
@@ -125,6 +129,7 @@ module Solargraph
           if resolved
             base = [resolved]
           else
+            # @sg-ignore flow sensitive typing needs better handling of ||= on lvars
             return resolve(name, first) unless first.empty?
           end
         end
@@ -138,7 +143,7 @@ module Solargraph
       # @param name [String]
       # @param gates [Array<String>]
       # @param internal [Boolean] True if the name is not the last in the namespace
-      # @return [Array(Object, Array<String>)]
+      # @return [Array(String, Array<String>), Array(nil, Array<String>), String]
       def complex_resolve name, gates, internal
         resolved = nil
         gates.each.with_index do |gate, idx|
@@ -165,6 +170,7 @@ module Solargraph
         here = "#{gate}::#{name}".sub(/^::/, '').sub(/::$/, '')
         pin = store.get_path_pins(here).first
         if pin.is_a?(Pin::Constant) && internal
+          # @sg-ignore Need to add nil check here
           const = Solargraph::Parser::NodeMethods.unpack_name(pin.assignment)
           return unless const
           resolve(const, pin.gates)
@@ -197,13 +203,14 @@ module Solargraph
       # will start the search in the specified context until it finds a
       # match for the namespace.
       #
-      # @param namespace [String, nil] The namespace to
+      # @param namespace [String] The namespace to
       #   match
       # @param context_namespace [String] The context namespace in which the
       #   tag was referenced; start from here to resolve the name
       # @return [String, nil] fully qualified namespace
       def qualify_namespace namespace, context_namespace = ''
         if namespace.start_with?('::')
+          # @sg-ignore Need to add nil check here
           inner_qualify(namespace[2..], '', Set.new)
         else
           inner_qualify(namespace, context_namespace, Set.new)
@@ -249,7 +256,7 @@ module Solargraph
         end
       end
 
-      # @param fqns [String]
+      # @param fqns [String, nil]
       # @param visibility [Array<Symbol>]
       # @param skip [Set<String>]
       # @return [Array<Solargraph::Pin::Namespace, Solargraph::Pin::Constant>]
@@ -259,11 +266,13 @@ module Solargraph
         result = []
 
         store.get_prepends(fqns).each do |pre|
+          # @sg-ignore Need to add nil check here
           pre_fqns = resolve(pre.name, pre.closure.gates - skip.to_a)
           result.concat inner_get_constants(pre_fqns, [:public], skip)
         end
         result.concat(store.get_constants(fqns, visibility).sort { |a, b| a.name <=> b.name })
         store.get_includes(fqns).each do |pin|
+          # @sg-ignore Need to add nil check here
           inc_fqns = resolve(pin.name, pin.closure.gates - skip.to_a)
           result.concat inner_get_constants(inc_fqns, [:public], skip)
         end

data/lib/solargraph/api_map/index.rb

@@ -5,6 +5,12 @@ module Solargraph
     class Index
       include Logging
 
+      # @return [Array<String>]
+      attr_reader :macro_method_names
+
+      # @return [Hash{String => Array<Pin::Method>}]
+      attr_reader :macro_method_name_pins
+
       # @param pins [Array<Pin::Base>]
       def initialize pins = []
         catalog pins
@@ -36,17 +42,22 @@ module Solargraph
         @path_pin_hash ||= Hash.new { |h, k| h[k] = [] }
       end
 
+      # @return [Hash{String => ComplexType}]
+      def alias_hash
+        @alias_hash ||= {}
+      end
+
       # @generic T
       # @param klass [Class<generic<T>>]
       # @return [Set<generic<T>>]
       def pins_by_class klass
-        # @type [Set<Solargraph::Pin::Base>]
+        # @type [Set<generic<T>>]
         s = Set.new
         # @sg-ignore need to support destructured args in blocks
         @pin_select_cache[klass] ||= pin_class_hash.each_with_object(s) { |(key, o), n| n.merge(o) if key <= klass }
       end
 
-      # @return [Hash{String => Array<String>}]
+      # @return [Hash{String => Array<Pin::Reference::Include>}]
       def include_references
         # @param h [String]
         # @param k [Array<String>]
@@ -60,21 +71,21 @@ module Solargraph
         @include_reference_pins ||= Hash.new { |h, k| h[k] = [] }
       end
 
-      # @return [Hash{String => Array<String>}]
+      # @return [Hash{String => Array<Pin::Reference::Extend>}]
       def extend_references
         # @param h [String]
         # @param k [Array<String>]
         @extend_references ||= Hash.new { |h, k| h[k] = [] }
       end
 
-      # @return [Hash{String => Array<String>}]
+      # @return [Hash{String => Array<Pin::Reference::Prepend>}]
       def prepend_references
         # @param h [String]
         # @param k [Array<String>]
         @prepend_references ||= Hash.new { |h, k| h[k] = [] }
       end
 
-      # @return [Hash{String => Array<String>}]
+      # @return [Hash{String => Array<Pin::Reference::Superclass>}]
       def superclass_references
         # @param h [String]
         # @param k [Array<String>]
@@ -90,16 +101,18 @@ module Solargraph
       protected
 
       attr_writer :pins, :pin_select_cache, :namespace_hash, :pin_class_hash, :path_pin_hash, :include_references,
-                  :extend_references, :prepend_references, :superclass_references
+                  :extend_references, :prepend_references, :superclass_references, :macro_method_names,
+                  :macro_method_name_pins
 
       # @return [self]
       def deep_clone
         Index.allocate.tap do |copy|
           copy.pin_select_cache = {}
           copy.pins = pins.clone
+          copy.macro_method_names = macro_method_names
           %i[
             namespace_hash pin_class_hash path_pin_hash include_references extend_references prepend_references
-            superclass_references
+            superclass_references macro_method_name_pins
           ].each do |sym|
             copy.send("#{sym}=", send(sym).clone)
             copy.send(sym)&.transform_values!(&:clone)
@@ -118,27 +131,31 @@ module Solargraph
         # @param k [String]
         # @param v [Set<Pin::Base>]
         set.classify(&:class)
-          .map { |k, v| pin_class_hash[k].concat v.to_a }
+           .map { |k, v| pin_class_hash[k].concat v.to_a }
         # @param k [String]
         # @param v [Set<Pin::Namespace>]
         set.classify(&:namespace)
-          .map { |k, v| namespace_hash[k].concat v.to_a }
+           .map { |k, v| namespace_hash[k].concat v.to_a }
         # @param k [String]
         # @param v [Set<Pin::Base>]
         set.classify(&:path)
-          .map { |k, v| path_pin_hash[k].concat v.to_a }
+           .map { |k, v| path_pin_hash[k].concat v.to_a }
         @namespaces = path_pin_hash.keys.compact.to_set
         map_references Pin::Reference::Include, include_references
         map_references Pin::Reference::Prepend, prepend_references
         map_references Pin::Reference::Extend, extend_references
         map_references Pin::Reference::Superclass, superclass_references
+        macro_pins = pins_by_class(Pin::Method).select { |pin| pin.macros.any? }
+        @macro_method_names = macro_pins.to_set(&:name)
+        @macro_method_name_pins = macro_pins.to_set.classify(&:name)
         map_overrides
+        pins_by_class(Pin::Reference::TypeAlias).each { |pin| alias_hash[pin.name] = pin.return_type }
         self
       end
 
       # @generic T
       # @param klass [Class<generic<T>>]
-      # @param hash [Hash{String => generic<T>}]
+      # @param hash [Hash{String => Array<generic<T>>}]
       #
       # @return [void]
       def map_references klass, hash
@@ -150,26 +167,32 @@ module Solargraph
 
       # @return [void]
       def map_overrides
+        # @todo should complain when type for 'ovr' is not provided
         # @param ovr [Pin::Reference::Override]
         pins_by_class(Pin::Reference::Override).each do |ovr|
           logger.debug { "ApiMap::Index#map_overrides: Looking at override #{ovr} for #{ovr.name}" }
           pins = path_pin_hash[ovr.name]
           logger.debug { "ApiMap::Index#map_overrides: pins for path=#{ovr.name}: #{pins}" }
           pins.each do |pin|
-            new_pin = if pin.path.end_with?('#initialize')
-                        path_pin_hash[pin.path.sub(/#initialize/, '.new')].first
-                      end
+            new_pin = (path_pin_hash[pin.path.sub('#initialize', '.new')].first if pin.path.end_with?('#initialize'))
             (ovr.tags.map(&:tag_name) + ovr.delete).uniq.each do |tag|
+              # @sg-ignore Wrong argument type for
+              #   YARD::Docstring#delete_tags: name expected String,
+              #   received String, Symbol - delete_tags is ok with a
+              #   _ToS, but we should fix anyway
               pin.docstring.delete_tags tag
-              new_pin.docstring.delete_tags tag if new_pin
+              new_pin&.docstring&.delete_tags tag
             end
             ovr.tags.each do |tag|
               pin.docstring.add_tag(tag)
               redefine_return_type pin, tag
-              if new_pin
-                new_pin.docstring.add_tag(tag)
-                redefine_return_type new_pin, tag
-              end
+              pin.reset_generated!
+
+              next unless new_pin
+
+              new_pin.docstring.add_tag(tag)
+              redefine_return_type new_pin, tag
+              new_pin.reset_generated!
             end
           end
         end
@@ -186,7 +209,6 @@ module Solargraph
         pin.signatures.each do |sig|
           sig.instance_variable_set(:@return_type, ComplexType.try_parse(tag.type))
         end
-        pin.reset_generated!
       end
     end
   end

data/lib/solargraph/api_map/source_to_yard.rb

@@ -3,16 +3,18 @@
 module Solargraph
   class ApiMap
     module SourceToYard
-
       # Get the YARD CodeObject at the specified path.
       #
+      # @sg-ignore Declared return type generic<T>, nil does not match
+      #   inferred type ::YARD::CodeObjects::Base, nil for
+      #   Solargraph::ApiMap::SourceToYard#code_object_at
       # @generic T
       # @param path [String]
       # @param klass [Class<generic<T>>]
       # @return [generic<T>, nil]
       def code_object_at path, klass = YARD::CodeObjects::Base
         obj = code_object_map[path]
-        obj if obj&.is_a?(klass)
+        obj if obj.is_a?(klass)
       end
 
       # @return [Array<String>]
@@ -33,16 +35,20 @@ module Solargraph
           end
           if pin.type == :class
             # @param obj [YARD::CodeObjects::RootObject]
-            code_object_map[pin.path] ||= YARD::CodeObjects::ClassObject.new(root_code_object, pin.path) { |obj|
+            code_object_map[pin.path] ||= YARD::CodeObjects::ClassObject.new(root_code_object, pin.path) do |obj|
+              # @sg-ignore flow sensitive typing needs to handle attrs
               next if pin.location.nil? || pin.location.filename.nil?
+              # @sg-ignore flow sensitive typing needs to handle attrs
               obj.add_file(pin.location.filename, pin.location.range.start.line, !pin.comments.empty?)
-            }
+            end
           else
             # @param obj [YARD::CodeObjects::RootObject]
-            code_object_map[pin.path] ||= YARD::CodeObjects::ModuleObject.new(root_code_object, pin.path) { |obj|
+            code_object_map[pin.path] ||= YARD::CodeObjects::ModuleObject.new(root_code_object, pin.path) do |obj|
+              # @sg-ignore flow sensitive typing needs to handle attrs
               next if pin.location.nil? || pin.location.filename.nil?
+              # @sg-ignore flow sensitive typing needs to handle attrs
               obj.add_file(pin.location.filename, pin.location.range.start.line, !pin.comments.empty?)
-            }
+            end
           end
           code_object_map[pin.path].docstring = pin.docstring
           store.get_includes(pin.path).each do |ref|
@@ -57,7 +63,6 @@ module Solargraph
             code_object = code_object_map[ref.type.to_s]
             next unless code_object
             extend_object.class_mixins.push code_object
-            # @todo add spec showing why this next line is necessary
             extend_object.instance_mixins.push code_object
           end
         end
@@ -67,14 +72,22 @@ module Solargraph
             next
           end
 
+          # @sg-ignore Need to add nil check here
           # @param obj [YARD::CodeObjects::RootObject]
-          code_object_map[pin.path] ||= YARD::CodeObjects::MethodObject.new(code_object_at(pin.namespace, YARD::CodeObjects::NamespaceObject), pin.name, pin.scope) { |obj|
+          code_object_map[pin.path] ||= YARD::CodeObjects::MethodObject.new(
+            code_object_at(pin.namespace, YARD::CodeObjects::NamespaceObject), pin.name, pin.scope
+          ) do |obj|
+            # @sg-ignore flow sensitive typing needs to handle attrs
             next if pin.location.nil? || pin.location.filename.nil?
+            # @sg-ignore flow sensitive typing needs to handle attrs
             obj.add_file pin.location.filename, pin.location.range.start.line
-          }
+          end
           method_object = code_object_at(pin.path, YARD::CodeObjects::MethodObject)
+          # @sg-ignore Need to add nil check here
           method_object.docstring = pin.docstring
+          # @sg-ignore Need to add nil check here
           method_object.visibility = pin.visibility || :public
+          # @sg-ignore Need to add nil check here
           method_object.parameters = pin.parameters.map do |p|
             [p.full_name, p.asgn_code]
           end