solargraph 0.59.2 → 0.60.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d71c58a0d918c5c6c034e7011a8bf543e0bc4adc5046936fa57cc4f698ccda05
-  data.tar.gz: c16b441272fb5aa6f908fdf643d524ff3e5f955dc8b636fd7bf7927836085047
+  metadata.gz: e3eff86e8759fbaaa9526cf9cceb70827c701f3b1925d58e1575870989d60e60
+  data.tar.gz: a60b5c8e9598afdca808c94fa68e2551d17f970b812ca64c3f00d530d0498fff
 SHA512:
-  metadata.gz: e7f83cd6982410d73623b44dd7b69bb5513266f778aeb33574b30155ccea7a4f53d9649150df2685efee70bdc5ae8227bd02ccdabbf9b633b66809be7c838307
-  data.tar.gz: 83b5822ecf5528f3196e1fbd283ac474d27cbc603f2bb81b8d8bff1b0b99d32023fec6e50b691bb390e5c8873875376d28f182ccb12498513f34a0fa4cb575e8
+  metadata.gz: 201861185888f275b0c7690887cca60a76d0bb90955c514ba4336e23f2adb9907d305f5e930b08f03c3c388d81bfd40996cd54c0f854035aab5a60703c40f954
+  data.tar.gz: b37cc2ed827560a2365b77af0921c0240498dcb287e1a1ba064f0879a748c2d365f0e61cec610233b11521206ab402e83aebbdec5c897a21eb3e9f7313fba602

data/.github/workflows/rspec.yml

@@ -21,7 +21,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.1', '3.2', '3.3', '3.4', '4.0', 'head']
+        # @todo Restore 'head' once ruby/setup-ruby publishes it for ubuntu-24.04.
+        #   It currently 404s ("Unavailable version head for ruby"), failing CI:
+        #   https://github.com/castwide/solargraph/actions/runs/25863741955/job/76000137015?pr=1187
+        ruby-version: ['3.1', '3.2', '3.3', '3.4', '4.0']
         rbs-version: ['3.10.0', '4.0.0', '4.0.1', '4.0.2']
         exclude:
           - ruby-version: '3.1'

data/.rubocop.yml

@@ -17,6 +17,7 @@ AllCops:
     - "spec/fixtures/invalid_byte.rb"
     - "spec/fixtures/invalid_node_comment.rb"
     - "spec/fixtures/invalid_utf8.rb"
+    - "spec/fixtures/gem-with-yard-macros/**/*"
     - "vendor/**/*"
     - "vendor/**/.*"
   TargetRubyVersion: 3.1

data/.rubocop_todo.yml

@@ -118,7 +118,7 @@ Metrics/MethodLength:
 
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 167
+  Max: 195
 
 # Configuration parameters: Max, CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 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)

data/Gemfile

@@ -4,6 +4,9 @@ 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__)
 instance_eval File.read local_gemfile if File.exist? local_gemfile

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
@@ -95,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)
@@ -137,6 +145,9 @@ module Solargraph
         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

data/lib/solargraph/api_map/store.rb

@@ -21,11 +21,11 @@ module Solargraph
       #   - pinsets[0] = core Ruby pins
       #   - pinsets[1] = documentation/gem pins
       #   - pinsets[2] = convention pins
-      #   - pinsets[3] = workspace source pins
+      #   - pinsets[3] = workspace source pins (aka. "iced_pins")
       #   - pinsets[4] = currently open file pins
       # @return [Boolean] True if the index was updated
-      def update *pinsets
-        return catalog(pinsets) if pinsets.length != @pinsets.length
+      def update *pinsets, &block
+        return catalog(pinsets, &block) if pinsets.length != @pinsets.length
 
         changed = pinsets.find_index.with_index { |pinset, idx| @pinsets[idx] != pinset }
         return false unless changed
@@ -43,6 +43,9 @@ module Solargraph
                                       @indexes[changed + idx - 1].merge(pins)
                                     end
         end
+        # @type [Index]
+        @index = @indexes.last.clone
+        @index = @index.merge(block.call) if block
         constants.clear
         cached_qualify_superclass.clear
         true
@@ -174,7 +177,7 @@ module Solargraph
         result
       end
 
-      # @return [Hash{String => YARD::Tags::MacroDirective}]
+      # @return [Hash{String => YardMap::Macro}]
       def named_macros
         @named_macros ||= begin
           result = {}
@@ -276,17 +279,27 @@ module Solargraph
         index.alias_hash[name]
       end
 
+      # @return [Array<String>]
+      def macro_method_names
+        index.macro_method_names
+      end
+
+      # @return [Hash{String => Array<Pin::Method>}]
+      def macro_method_name_pins
+        index.macro_method_name_pins
+      end
+
       private
 
       # @return [Index]
       def index
-        @indexes.last
+        @index ||= Index.new
       end
 
       # @param pinsets [Array<Array<Pin::Base>>]
       #
       # @return [true]
-      def catalog pinsets
+      def catalog pinsets, &block
         @pinsets = pinsets
         # @type [Array<Index>]
         @indexes = []
@@ -297,6 +310,8 @@ module Solargraph
             @indexes.push(@indexes.last&.merge(pins) || Solargraph::ApiMap::Index.new(pins))
           end
         end
+        @index = @indexes.last.clone
+        @index = @index.merge(block.call) if block
         constants.clear
         cached_qualify_superclass.clear
         true

data/lib/solargraph/api_map.rb

@@ -107,6 +107,7 @@ module Solargraph
     # @return [self]
     def catalog bench
       @source_map_hash = bench.source_map_hash
+      # @type [Array<Pin::Base>]
       iced_pins = bench.icebox.flat_map(&:pins)
       live_pins = bench.live_map&.all_pins || []
       conventions_environ.clear
@@ -123,11 +124,42 @@ module Solargraph
         @doc_map = DocMap.new(unresolved_requires, bench.workspace, out: nil) # @todo Implement gem preferences
         @unresolved_requires = @doc_map.unresolved_requires
       end
-      @cache.clear if store.update(@@core_map.pins, @doc_map.pins, conventions_environ.pins, iced_pins, live_pins)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      Solargraph.logger.info 'Cataloging ApiMap started'
+      @cache.clear if store.update(@@core_map.pins, @doc_map.pins, conventions_environ.pins, iced_pins, live_pins) { process_macros }
       @missing_docs = [] # @todo Implement missing docs
+      Solargraph.logger.info "Cataloging ApiMap finished in #{Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time} seconds"
       self
     end
 
+    # @return [Array<Pin::Base>]
+    def process_macros
+      macro_pins = []
+      Solargraph.logger.debug { "ApiMap#process_macros: processing macros for #{source_maps.size} source maps" }
+      Solargraph.logger.debug { "ApiMap#process_macros: store has #{store.macro_method_name_pins.size} macro method name pins" }
+      Solargraph.logger.debug { "ApiMap#process_macros: named macros: #{store.named_macros.keys.join(', ')}" }
+      source_maps.each do |source_map|
+        method_candidates = source_map.macro_method_candidates(store.macro_method_names)
+        Solargraph.logger.debug { "ApiMap#process_macros: processing source map for #{source_map.filename} with #{method_candidates.size} macro method candidates" }
+        method_candidates.each do |node|
+          closure = source_map.locate_closure_pin(node.location.line, node.location.column)
+          chain = Solargraph::Parser::ParserGem::NodeChainer.chain(node)
+          if node.children[0].nil? && store.macro_method_name_pins.key?(node.children[1].to_s)
+            match = store.macro_method_name_pins[node.children[1].to_s].find do |pin|
+              super_and_sub?(pin.namespace, closure.name)
+            end
+            if match
+              match.macros.each do |macro|
+                macro_pins.concat macro.generate_pins_from(chain, match, source_map)
+              end
+              next
+            end
+          end
+        end
+      end
+      macro_pins
+    end
+
     # @return [DocMap]
     def doc_map
       @doc_map ||= DocMap.new([], Workspace.new('.'))
@@ -154,7 +186,7 @@ module Solargraph
     end
 
     # @param name [String, nil]
-    # @return [YARD::Tags::MacroDirective, nil]
+    # @return [Solargraph::YardMap::Macro, nil]
     def named_macro name
       # @sg-ignore Need to add nil check here
       store.named_macros[name]

data/lib/solargraph/complex_type/unique_type.rb

@@ -547,6 +547,10 @@ module Solargraph
         yield new_type
       end
 
+      def expand named_types
+        named_types[name] || self
+      end
+
       # Generate a ComplexType that fully qualifies this type's namespaces.
       #
       # @param api_map [ApiMap] The ApiMap that performs qualification

data/lib/solargraph/complex_type.rb

@@ -298,6 +298,10 @@ module Solargraph
       ComplexType.new(map { |ut| ut.transform(new_name, &transform_type) })
     end
 
+    def expand named_types
+      ComplexType.new(map { |ut| ut.expand(named_types) })
+    end
+
     # @return [self]
     def force_rooted
       transform do |t|

data/lib/solargraph/doc_map.rb

@@ -317,6 +317,7 @@ module Solargraph
       gemspec = Gem::Specification.find_by_path(path)
       if gemspec.nil?
         gem_name_guess = path.split('/').first
+        return nil if gem_name_guess.to_s.empty?
         begin
           # this can happen when the gem is included via a local path in
           # a Gemfile; Gem doesn't try to index the paths in that case.

data/lib/solargraph/parser/parser_gem/node_methods.rb

@@ -102,6 +102,48 @@ module Solargraph
           signature
         end
 
+        # Convert a DSL method call argument with directly inferrable simple params.
+        # @param node [Parser::AST::Node]
+        # @return [String, Integer, Float, Symbol, Array, Hash, Source::Chain, nil]
+        # @sg-ignore "does not match inferred type ::String, ::Parser::AST::Node" - this probably comes from the
+        # `.children[0]` call, which is not recognized as returning a literal value.
+        def simple_convert node
+          return nil unless Parser.is_ast_node?(node)
+
+          case node.type
+          when :const
+            unpack_name(node)
+          when :str, :dstr, :int, :float, :sym, true, false
+            node.children[0]
+          when :array
+            simple_convert_array(node)
+          when :hash
+            simple_convert_hash(node)
+          else
+            Solargraph::Parser.chain(node)
+          end
+        end
+
+        # @param node [Parser::AST::Node]
+        # @return [Array]
+        def simple_convert_array node
+          return [] unless Parser.is_ast_node?(node) && node.type == :array
+          node.children.compact.map { |c| simple_convert(c) }
+        end
+
+        # @param node [Parser::AST::Node]
+        # @return [Hash]
+        def simple_convert_hash node
+          return {} unless Parser.is_ast_node?(node) && node.type == :hash
+          result = {}
+          # @param pair [Parser::AST::Node]
+          node.children.each do |pair|
+            next unless Parser.is_ast_node?(pair) && pair.children[0]
+            result[pair.children[0].children[0]] = simple_convert(pair.children[1])
+          end
+          result
+        end
+
         # @param node [Parser::AST::Node, nil]
         # @return [Hash{Symbol => Chain}]
         def convert_hash node

data/lib/solargraph/parser/parser_gem/node_processors/namespace_node.rb

@@ -8,22 +8,27 @@ module Solargraph
           include ParserGem::NodeMethods
 
           def process
-            superclass_name = nil
-            superclass_name = unpack_name(node.children[1]) if node.type == :class && node.children[1]&.type == :const
+            name = unpack_name(node.children[0])
+            comments = comments_for(node)
+
+            superclass_name = if node.type == :class && node.children[1]&.type == :const
+              "#{type_from_node}#{parameters_from_inline_rbs}"
+            end
 
             loc = get_node_location(node)
             nspin = Solargraph::Pin::Namespace.new(
               type: node.type,
               location: loc,
               closure: region.closure,
-              name: unpack_name(node.children[0]),
-              comments: comments_for(node),
+              name: name,
+              comments: comments,
               visibility: :public,
               gates: region.closure.gates.freeze,
               source: :parser
             )
             pins.push nspin
-            unless superclass_name.nil?
+            Solargraph.logger.warn "Superclass: #{superclass_name}" if superclass_name&.start_with?('Array')
+            if superclass_name
               pins.push Pin::Reference::Superclass.new(
                 location: loc,
                 closure: pins.last,
@@ -33,6 +38,25 @@ module Solargraph
             end
             process_children region.update(closure: nspin, visibility: :public)
           end
+
+          private
+
+          # @param comments [String]
+          # @return [String, nil]
+          def parameters_from_inline_rbs
+            source = region.source.code_for(node)
+            match = source.match(/[^\n]*?#\s?+\[([^\]]*)/)
+            return unless match && match[1]
+
+            code = match[1].strip
+            return if code.empty?
+
+            "<#{code}>"
+          end
+
+          def type_from_node
+            unpack_name(node.children[1]) if node.children[1]&.type == :const
+          end
         end
       end
     end

data/lib/solargraph/pin/base.rb

@@ -534,11 +534,20 @@ module Solargraph
         @directives
       end
 
-      # @return [::Array<YARD::Tags::MacroDirective>]
+      # @return [::Array<Solargraph::YardMap::Macro>]
       def macros
         @macros ||= collect_macros
       end
 
+      def macro_names
+        parse_comments unless @macro_names
+        @macro_names ||= collect_macro_names
+      end
+
+      def macro_names?
+        macro_names.any?
+      end
+
       # Perform a quick check to see if this pin possibly includes YARD
       # directives. This method does not require parsing the comments.
       #
@@ -569,6 +578,15 @@ module Solargraph
         return_type.qualify(api_map, *(closure&.gates || ['']))
       end
 
+      # @todo Candidate for deprecation (see ApiMap#process_macros)
+      def maybe_macros?
+        comments.include?('@macro')        
+      end
+
+      def macros_names?
+        macro_names.any?
+      end
+
       # Infer the pin's return type via static code analysis.
       #
       # @param api_map [ApiMap]
@@ -619,6 +637,8 @@ module Solargraph
         result = dup
         result.return_type = return_type
         result.proxied = true
+        # Macros should have been processed already
+        result.macro_names.clear
         result
       end
 
@@ -717,12 +737,14 @@ module Solargraph
         if comments.nil? || comments.empty? || comments.strip.end_with?('@overload')
           @docstring = nil
           @directives = []
+          @macro_names = []
         else
           # HACK: Pass a dummy code object to the parser for plugins that
           # expect it not to be nil
           parse = Solargraph::Source.parse_docstring(comments)
           @docstring = parse.to_docstring
           @directives = parse.directives
+          @macro_names = collect_macro_names
         end
       end
 
@@ -762,11 +784,17 @@ module Solargraph
           tag1.types == tag2.types
       end
 
-      # @return [::Array<YARD::Tags::Handlers::Directive>]
+      # @return [::Array<Solargraph::YardMap::Macro>]
       def collect_macros
         return [] unless maybe_directives?
         parse = Solargraph::Source.parse_docstring(comments)
-        parse.directives.select { |d| d.tag.tag_name == 'macro' }
+        parse.directives.select { |d| d.tag.tag_name == 'macro' }.map do |macro_directive|
+          Solargraph::YardMap::Macro.from_directive macro_directive, self
+        end
+      end
+
+      def collect_macro_names
+        "#{comments}\n".scan(/\s*?@macro +(\S+).*?[\n]/).map { |match| match[0] }
       end
     end
   end

data/lib/solargraph/pin/callable.rb

@@ -161,8 +161,8 @@ module Solargraph
       end
 
       def typify api_map
-        type = super
-        return type if type.defined?
+        type = return_type
+        return type.qualify(api_map, *gates) if type.defined?
         if method_name.end_with?('?')
           logger.debug { "Callable#typify(self=#{self}) => Boolean (? suffix)" }
           ComplexType::BOOLEAN

data/lib/solargraph/pin/common.rb

@@ -72,6 +72,18 @@ module Solargraph
         @path ||= name.empty? ? context.namespace : "#{context.namespace}::#{name}"
       end
 
+      # @yieldparam [Pin::Base]
+      # @return [void, Enumerator<Pin::Base>]
+      def each_closure &block
+        return enum_for(:each_closure) unless block_given?
+
+        here = closure
+        until here.nil?
+          yield here
+          here = here&.closure
+        end
+      end
+
       protected
 
       attr_writer :context

data/lib/solargraph/pin/method.rb

@@ -143,7 +143,7 @@ module Solargraph
       end
 
       def return_type
-        @return_type ||= ComplexType.new(signatures.map(&:return_type).flat_map(&:items))
+        @return_type ||= return_type_from_inline_rbs || ComplexType.new(signatures.map(&:return_type).flat_map(&:items))
       end
 
       # @param parameters [::Array<Parameter>]
@@ -188,18 +188,11 @@ module Solargraph
 
       # @return [::Array<Signature>]
       def signatures
-        @signatures ||= begin
-          top_type = generate_complex_type
-          result = []
-          result.push generate_signature(parameters, top_type) if top_type.defined?
-          unless overloads.empty?
-            result.concat(overloads.map do |meth|
-              generate_signature(meth.parameters, meth.return_type)
-            end)
-          end
-          result.push generate_signature(parameters, @return_type || ComplexType::UNDEFINED) if result.empty?
-          result
-        end
+        @signatures ||= if inline_rbs.empty?
+                          signatures_from_yard
+                        else
+                          signatures_from_inline_rbs
+                        end
       end
 
       # @param return_type [ComplexType]
@@ -279,7 +272,19 @@ module Solargraph
           # @sg-ignore Need to add nil check here
           "Method#typify(self=#{self}, binder=#{binder}, closure=#{closure}, context=#{context.rooted_tags}, return_type=#{return_type.rooted_tags}) - starting"
         end
-        decl = super
+        decl = if macro_names?
+          types = macro_names.flat_map do |mac|
+            directive = api_map.named_macro(mac)
+            next unless directive
+            macro = Solargraph::YardMap::Macro.from_directive(directive, self)
+            expanded = macro.macro_object.expand([name, *parameter_names])
+            docstring = Solargraph::Source.parse_docstring(expanded).to_docstring
+            docstring.tags(:return).flat_map(&:types)
+          end
+          ComplexType.try_parse(*types)
+        else
+          super
+        end
         unless decl.undefined?
           logger.debug do
             "Method#typify(self=#{self}, binder=#{binder}, closure=#{closure}, context=#{context}) => #{decl.rooted_tags.inspect} - decl found"
@@ -451,7 +456,6 @@ module Solargraph
 
       attr_writer :block, :signature_help, :documentation, :return_type
 
-      # @sg-ignore Need to add nil check here
       def dodgy_visibility_source?
         # as of 2025-03-12, the RBS generator used for
         # e.g. activesupport did not understand 'private' markings
@@ -505,7 +509,8 @@ module Solargraph
       #
       # @return [Array<Pin::Signature>]
       def combine_same_type_arity_signatures same_type_arity_signatures
-        # @todo Stubbing this method while we debug an infinite loop bug in Ruby 3.x
+        # @todo Stubbing this method while we debug an infinite loop bug in Ruby 3.x.
+        #   The body below is intentionally preserved for when the stub is removed.
         return same_type_arity_signatures
 
         # rubocop:disable Lint/UnreachableCode
@@ -721,6 +726,41 @@ module Solargraph
         .join("\n")
         .concat("```\n")
       end
+
+      # @return [ComplexType, nil]
+      def return_type_from_inline_rbs
+        return nil if inline_rbs.empty?
+        method_type = RBS::Parser.parse_method_type(inline_rbs)
+        RbsTranslator.to_complex_type(method_type.type.return_type)
+      rescue RBS::ParsingError
+        nil
+      end
+
+      # @return [Array<Pin::Signature>]
+      def signatures_from_inline_rbs
+        method_type = RBS::Parser.parse_method_type(inline_rbs)
+        [RbsTranslator.to_signature(method_type, self, parameter_names)]
+      rescue RBS::ParsingError
+        signatures_from_yard
+      end
+
+      # @return [Array<Pin::Signature>]
+      def signatures_from_yard
+        top_type = generate_complex_type
+        result = []
+        result.push generate_signature(parameters, top_type) if top_type.defined?
+        result.concat(overloads.map { |meth| generate_signature(meth.parameters, meth.return_type) }) unless overloads.empty?
+        result.push generate_signature(parameters, @return_type || ComplexType::UNDEFINED) if result.empty?
+        result
+      end
+
+      # @return [String]
+      def inline_rbs
+        comments.lines
+                .select { |line| line.start_with?(': ') }
+                .map { |line| line[2..].strip }
+                .join("\n")
+      end
     end
   end
 end