2025-06-24 dev branch

.yardopts

@@ -1,2 +1,3 @@
 lib/**/*.rb
 --plugin yard-solargraph
+--plugin activesupport-concern

README.md

@@ -132,6 +132,10 @@ 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.
+
 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.
 
 ### Sponsorship and Donation

lib/solargraph/api_map.rb

@@ -168,8 +168,12 @@ def cursor_at filename, position
     # @param position [Position, Array(Integer, Integer)]
     # @return [SourceMap::Clip]
     def clip_at filename, position
+      logger.debug { "ApiMap#clip_at(filename=#{filename}, position=#{position}) - start" }
+
       position = Position.normalize(position)
-      clip(cursor_at(filename, position))
+      out = clip(cursor_at(filename, position))
+      logger.debug { "ApiMap#clip_at(filename=#{filename}, position=#{position}) => #{out}" }
+      out
     end
 
     # Create an ApiMap with a workspace in the specified directory.
@@ -254,6 +258,7 @@ def namespace_exists? name, context = ''
     # @param contexts [Array<String>] The contexts
     # @return [Array<Solargraph::Pin::Base>]
     def get_constants namespace, *contexts
+      logger.debug { "ApiMap#get_constants(namespace=#{namespace.inspect}, contexts=#{contexts.inspect})" }
       namespace ||= ''
       contexts.push '' if contexts.empty?
       cached = cache.get_constants(namespace, contexts)
@@ -262,11 +267,13 @@ def get_constants namespace, *contexts
       result = []
       contexts.each do |context|
         fqns = qualify(namespace, context)
+        logger.debug { "ApiMap#get_constants(namespace=#{namespace.inspect}, contexts=#{contexts.inspect}) - fqns=#{fqns}" }
         visibility = [:public]
         visibility.push :private if fqns == context
         result.concat inner_get_constants(fqns, visibility, skip)
       end
       cache.set_constants(namespace, contexts, result)
+      logger.debug { "ApiMap#get_constants(namespace=#{namespace.inspect}, contexts=#{contexts.inspect}) => #{result}" }
       result
     end
 
@@ -323,13 +330,15 @@ def qualify tag, context_tag = ''
     # @return [String, nil] fully qualified namespace
     def qualify_namespace(namespace, context_namespace = '')
       cached = cache.get_qualified_namespace(namespace, context_namespace)
+      logger.debug { "ApiMap#qualify_namespace(namespace=#{namespace.inspect}, context_namespace=#{context_namespace.inspect}) - cached=#{cached.inspect}" }
       return cached.clone unless cached.nil?
       result = if namespace.start_with?('::')
                  inner_qualify(namespace[2..-1], '', Set.new)
                else
                  inner_qualify(namespace, context_namespace, Set.new)
                end
       cache.set_qualified_namespace(namespace, context_namespace, result)
+      logger.debug { "ApiMap#qualify_namespace(namespace=#{namespace.inspect}, context_namespace=#{context_namespace.inspect}) => #{result.inspect}" }
       result
     end
 
@@ -362,7 +371,9 @@ def visible_pins(*args, **kwargs, &blk)
     # @param namespace [String] A fully qualified namespace
     # @return [Enumerable<Solargraph::Pin::ClassVariable>]
     def get_class_variable_pins(namespace)
-      prefer_non_nil_variables(store.get_class_variables(namespace))
+      out = prefer_non_nil_variables(store.get_class_variables(namespace))
+      logger.debug { "ApiMap#get_class_variable_pins(namespace=#{namespace.inspect}) => #{out}" }
+      out
     end
 
     # @return [Enumerable<Solargraph::Pin::Base>]
@@ -707,6 +718,8 @@ def inner_get_methods rooted_tag, scope, visibility, deep, skip, no_core = false
       # namespaces; resolving the generics in the method pins is this
       # class' responsibility
       methods = store.get_methods(fqns, scope: scope, visibility: visibility).sort{ |a, b| a.name <=> b.name }
+      methods = methods.map(&:as_virtual_class_method) if store.get_includes(fqns).include?('ActiveSupport::Concern') && scope == :class
+      logger.info { "ApiMap#inner_get_methods(rooted_tag=#{rooted_tag.inspect}, scope=#{scope.inspect}, visibility=#{visibility.inspect}, deep=#{deep.inspect}, skip=#{skip.inspect}, fqns=#{fqns}) - added from store: #{methods}" }
       result.concat methods
       if deep
         if scope == :instance
@@ -719,6 +732,31 @@ def inner_get_methods rooted_tag, scope, visibility, deep, skip, no_core = false
             result.concat inner_get_methods_from_reference(rooted_sc_tag, namespace_pin, rooted_type, scope, visibility, true, skip, no_core)
           end
         else
+          store.get_includes(fqns).reverse.each do |include_tag|
+            rooted_include_tag = qualify(include_tag, rooted_tag)
+            logger.debug { "ApiMap#inner_get_methods(#{fqns}, #{scope}, #{visibility}, #{deep}) - Handling class include include_tag=#{include_tag}" }
+            module_extends = store.get_extends(rooted_include_tag)
+            # ActiveSupport::Concern is syntactic sugar for a common
+            # pattern to include class methods while mixing-in a Module
+
+            # See https://api.rubyonrails.org/classes/ActiveSupport/Concern.html
+            logger.debug { "ApiMap#inner_get_methods(#{fqns}, #{scope}, #{visibility}, #{deep}) - Handling class include include_tag=#{include_tag}" }
+            if module_extends.include? 'ActiveSupport::Concern'
+              unless rooted_include_tag.nil?
+                # yard-activesupport-concern pulls methods inside
+                # 'class_methods' blocks into main class visible from YARD
+                included_class_pins = inner_get_methods_from_reference(rooted_include_tag, namespace_pin, rooted_type, :class, visibility, deep, skip, true)
+                result.concat included_class_pins
+
+                # another pattern is to put class methods inside a submodule
+                classmethods_include_tag = rooted_include_tag + "::ClassMethods"
+                included_classmethods_pins = inner_get_methods_from_reference(classmethods_include_tag, namespace_pin, rooted_type, :instance, visibility, deep, skip, true)
+                result.concat included_classmethods_pins
+              end
+            end
+          end
+
+          logger.info { "ApiMap#inner_get_methods(#{fqns}, #{scope}, #{visibility}, #{deep}, #{skip}) - looking for get_extends() from #{fqns}" }
           store.get_extends(fqns).reverse.each do |em|
             fqem = qualify(em, fqns)
             result.concat inner_get_methods(fqem, :instance, visibility, deep, skip, true) unless fqem.nil?
@@ -781,21 +819,28 @@ def inner_get_methods_from_reference(fq_reference_tag, namespace_pin, type, scop
     # @param skip [Set<String>]
     # @return [Array<Pin::Base>]
     def inner_get_constants fqns, visibility, skip
-      return [] if fqns.nil? || skip.include?(fqns)
+      logger.debug { "ApiMap#inner_get_constants(fqns=#{fqns.inspect}, visibility=#{visibility.inspect}, skip=#{skip.inspect}) - starting" }
+      if fqns.nil? || skip.include?(fqns)
+        logger.debug { "ApiMap#inner_get_constants(fqns=#{fqns.inspect}, visibility=#{visibility.inspect}, skip=#{skip.inspect}) => [] - fqns=#{fqns.inspect}, skip=#{skip}" }
+        return []
+      end
       skip.add fqns
       result = []
       store.get_prepends(fqns).each do |is|
         result.concat inner_get_constants(qualify(is, fqns), [:public], skip)
       end
-      result.concat store.get_constants(fqns, visibility)
-                    .sort { |a, b| a.name <=> b.name }
+      constants = store.get_constants(fqns, visibility)
+                      .sort { |a, b| a.name <=> b.name }
+      logger.debug { "Constants in #{fqns} with visibility #{visibility}, constants=#{constants}" }
+      result.concat constants
       store.get_includes(fqns).each do |is|
         result.concat inner_get_constants(qualify(is, fqns), [:public], skip)
       end
       fqsc = qualify_superclass(fqns)
       unless %w[Object BasicObject].include?(fqsc)
         result.concat inner_get_constants(fqsc, [:public], skip)
       end
+      logger.debug { "ApiMap#inner_get_constants(fqns=#{fqns.inspect}, visibility=#{visibility.inspect}, skip=#{skip.inspect}) => #{result}" }
       result
     end
 
@@ -831,6 +876,7 @@ def qualify_superclass fq_sub_tag
     # @param skip [Set<String>] Contexts already searched
     # @return [String, nil] Fully qualified ("rooted") namespace
     def inner_qualify name, root, skip
+      logger.debug { "ApiMap#inner_qualify(name=#{name.inspect}, root=#{root.inspect}, skip=#{skip.inspect}) - starting" }
       return name if name == ComplexType::GENERIC_TAG_NAME
       return nil if name.nil?
       return nil if skip.include?(root)

lib/solargraph/api_map/store.rb

@@ -129,7 +129,9 @@ def get_symbols
       # @param fqns [String]
       # @return [Boolean]
       def namespace_exists?(fqns)
-        fqns_pins(fqns).any?
+        out = fqns_pins(fqns).any?
+        logger.debug { "Store#namespace_exists?(#{fqns.inspect}) => #{out}" }
+        out
       end
 
       # @return [Set<String>]
@@ -195,9 +197,13 @@ def fqns_pins fqns
           base = ''
           name = fqns
         end
-        fqns_pins_map[[base, name]]
+        out = fqns_pins_map[[base, name]]
+        logger.debug { "Store#fqns_pins(#{fqns.inspect}) => #{out}" }
+        out
       end
 
+      include Logging
+
       private
 
       def index

lib/solargraph/complex_type.rb

@@ -34,13 +34,16 @@ def initialize types = [UniqueType::UNDEFINED]
     # @param context [String]
     # @return [ComplexType]
     def qualify api_map, context = ''
+      logger.debug { "ComplexType#qualify(self=#{self.rooted_tags}, context=#{context.inspect}) - starting" }
       red = reduce_object
       types = red.items.map do |t|
         next t if ['nil', 'void', 'undefined'].include?(t.name)
         next t if ['::Boolean'].include?(t.rooted_name)
         t.qualify api_map, context
       end
-      ComplexType.new(types).reduce_object
+      out = ComplexType.new(types).reduce_object
+      logger.debug { "ComplexType#qualify(self=#{self.rooted_tags}, context=#{context.inspect}) => #{out.rooted_tags}" }
+      out
     end
 
     # @param generics_to_resolve [Enumerable<String>]]
@@ -225,7 +228,9 @@ def force_rooted
     # @return [ComplexType]
     def resolve_generics definitions, context_type
       result = @items.map { |i| i.resolve_generics(definitions, context_type) }
-      ComplexType.new(result)
+      out = ComplexType.new(result)
+      # logger.debug { "ComplexType#resolve_generics(self=#{rooted_tags}, definitions=#{definitions}, context_type=#{context_type.rooted_tags} => #{out.rooted_tags}" }
+      out
     end
 
     def nullable?
@@ -405,6 +410,8 @@ def try_parse *strings
     BOOLEAN = ComplexType.parse('::Boolean')
     BOT = ComplexType.parse('bot')
 
+    include Logging
+
     private
 
     # @todo This is a quick and dirty hack that forces `self` keywords

lib/solargraph/complex_type/unique_type.rb

@@ -311,7 +311,7 @@ def resolve_param_generics_from_context(generics_to_resolve, context_type, resol
       def resolve_generics definitions, context_type
         return self if definitions.nil? || definitions.generics.empty?
 
-        transform(name) do |t|
+        out = transform(name) do |t|
           if t.name == GENERIC_TAG_NAME
             generic_name = t.subtypes.first&.name
             idx = definitions.generics.index(generic_name)
@@ -337,6 +337,8 @@ def resolve_generics definitions, context_type
             t
           end
         end
+        # logger.debug { "UniqueType#resolve_generics(self=#{self.rooted_tag}, definitions=#{definitions}, context_type=#{context_type.rooted_tags}) => #{out}" }
+        out
       end
 
       # @yieldparam t [self]
@@ -410,7 +412,7 @@ def transform(new_name = nil, &transform_type)
       # @param context [String] The namespace from which to resolve names
       # @return [self, ComplexType, UniqueType] The generated ComplexType
       def qualify api_map, context = ''
-        transform do |t|
+        out = transform do |t|
           next t if t.name == GENERIC_TAG_NAME
           next t if t.duck_type? || t.void? || t.undefined?
           recon = (t.rooted? ? '' : context)
@@ -421,6 +423,8 @@ def qualify api_map, context = ''
           end
           t.recreate(new_name: fqns, make_rooted: true)
         end
+        logger.debug { "UniqueType#qualify(self=#{rooted_tags.inspect}, context=#{context}) => #{out.rooted_tags.inspect}" }
+        out
       end
 
       def selfy?
@@ -468,7 +472,6 @@ def self.can_root_name?(name)
         '::NilClass' => UniqueType::NIL
       }.freeze
 
-
       include Logging
     end
   end

lib/solargraph/convention/gemspec.rb

@@ -12,7 +12,8 @@ def local source_map
               'Gem::Specification.new',
               %(
 @yieldparam [self]
-              )
+              ),
+              source: :gemspec,
             )
           ]
         )

lib/solargraph/doc_map.rb

@@ -90,9 +90,16 @@ def cache_rbs_collection_pins(gemspec, out)
 
     # @param gemspec [Gem::Specification]
     def cache(gemspec, rebuild: false, out: nil)
-      out.puts("Caching pins for gem #{gemspec.name}:#{gemspec.version}") if out
-      cache_yard_pins(gemspec, out) if uncached_yard_gemspecs.include?(gemspec) || rebuild
-      cache_rbs_collection_pins(gemspec, out) if uncached_rbs_collection_gemspecs.include?(gemspec) || rebuild
+      build_yard = uncached_yard_gemspecs.include?(gemspec) || rebuild
+      build_rbs_collection = uncached_rbs_collection_gemspecs.include?(gemspec) || rebuild
+      if build_yard || build_rbs_collection
+        type = []
+        type << 'YARD' if build_yard
+        type << 'RBS collection' if build_rbs_collection
+        out.puts("Caching #{type.join(' and ')} pins for gem #{gemspec.name}:#{gemspec.version}") if out
+      end
+      cache_yard_pins(gemspec, out) if build_yard
+      cache_rbs_collection_pins(gemspec, out) if build_rbs_collection
     end
 
     # @return [Array<Gem::Specification>]
@@ -121,10 +128,14 @@ def rbs_collection_pins_in_memory
       self.class.all_rbs_collection_gems_in_memory[rbs_collection_path] ||= {}
     end
 
-    def combined_pins_in_memory
+    def self.all_combined_pins_in_memory
       @combined_pins_in_memory ||= {}
     end
 
+    def combined_pins_in_memory
+      self.class.all_combined_pins_in_memory
+    end
+
     # @return [Set<Gem::Specification>]
     def dependencies
       @dependencies ||= (gemspecs.flat_map { |spec| fetch_dependencies(spec) } - gemspecs).to_set

lib/solargraph/gem_pins.rb

@@ -46,7 +46,7 @@ def self.combine_method_pins(*pins)
     end
 
     # @param yard_pins [Array<Pin::Base>]
-    # @param rbs_map [RbsMap]
+    # @param rbs_pins [Array<Pin::Base>]
     # @return [Array<Pin::Base>]
     def self.combine(yard_pins, rbs_pins)
       in_yard = Set.new

lib/solargraph/library.rb

@@ -436,17 +436,6 @@ def bench
       )
     end
 
-    # Get an array of foldable ranges for the specified file.
-    #
-    # @deprecated The library should not need to handle folding ranges. The
-    #   source itself has all the information it needs.
-    #
-    # @param filename [String]
-    # @return [Array<Range>]
-    def folding_ranges filename
-      read(filename).folding_ranges
-    end
-
     # Create a library from a directory.
     #
     # @param directory [String] The path to be used for the workspace
@@ -587,7 +576,7 @@ def cache_errors
 
     # @return [void]
     def cache_next_gemspec
-      return if @cache_progres
+      return if @cache_progress
       spec = (api_map.uncached_yard_gemspecs + api_map.uncached_rbs_collection_gemspecs).
                find { |spec| !cache_errors.include?(spec) }
       return end_cache_progress unless spec

lib/solargraph/logging.rb

@@ -11,18 +11,42 @@ module Logging
       'info' => Logger::INFO,
       'debug' => Logger::DEBUG
     }
-
-    @@logger = Logger.new(STDERR, level: DEFAULT_LOG_LEVEL)
+    configured_level = ENV['SOLARGRAPH_LOG']
+    level = if LOG_LEVELS.keys.include?(configured_level)
+              LOG_LEVELS.fetch(configured_level)
+            else
+              STDERR.puts("Invalid value for SOLARGRAPH_LOG: #{configured_level.inspect} - valid values are #{LOG_LEVELS.keys}") if configured_level
+              DEFAULT_LOG_LEVEL
+            end
+    @@logger = Logger.new(STDERR, level: level)
     # @sg-ignore Fix cvar issue
     @@logger.formatter = proc do |severity, datetime, progname, msg|
       "[#{severity}] #{msg}\n"
     end
+    @@dev_null_logger = Logger.new('/dev/null')
+
 
     module_function
 
+    # override this in your class to temporarily set a custom
+    # filtering log level for the class (e.g., suppress any debug
+    # message by setting it to :info even if it is set elsewhere, or
+    # show existing debug messages by setting to :debug).  @return
+    # [Symbol]
+    def log_level
+      :warn
+    end
+
     # @return [Logger]
     def logger
-      @@logger
+      if LOG_LEVELS[log_level.to_s] == DEFAULT_LOG_LEVEL
+        @@logger
+      else
+        new_log_level = LOG_LEVELS[log_level.to_s]
+        logger = Logger.new(STDERR, level: new_log_level)
+        logger.formatter = @@logger.formatter
+        logger
+      end
     end
   end
 end