solargraph 0.58.2 → 0.59.0.dev.2

data/lib/solargraph/workspace.rb

@@ -2,6 +2,7 @@
 
 require 'open3'
 require 'json'
+require 'yaml'
 
 module Solargraph
   # A workspace consists of the files in a project's directory and the
@@ -9,7 +10,10 @@ module Solargraph
   # in an associated Library or ApiMap.
   #
   class Workspace
+    include Logging
+
     autoload :Config, 'solargraph/workspace/config'
+    autoload :Gemspecs, 'solargraph/workspace/gemspecs'
     autoload :RequirePaths, 'solargraph/workspace/require_paths'
 
     # @return [String]
@@ -19,7 +23,8 @@ module Solargraph
     attr_reader :gemnames
     alias source_gems gemnames
 
-    # @param directory [String] TODO: Remove '' and '*' special cases
+    # @todo Remove '' and '*' special cases
+    # @param directory [String]
     # @param config [Config, nil]
     # @param server [Hash]
     def initialize directory = '', config = nil, server = {}
@@ -50,9 +55,71 @@ module Solargraph
       @config ||= Solargraph::Workspace::Config.new(directory)
     end
 
+    # @param stdlib_name [String]
+    #
+    # @return [Array<String>]
+    def stdlib_dependencies stdlib_name
+      gemspecs.stdlib_dependencies(stdlib_name)
+    end
+
+    # @param out [IO, nil] output stream for logging
+    # @param gemspec [Gem::Specification]
+    # @return [Array<Gem::Specification>]
+    def fetch_dependencies gemspec, out: $stderr
+      gemspecs.fetch_dependencies(gemspec, out: out)
+    end
+
+    # @param require [String] The string sent to 'require' in the code to resolve, e.g. 'rails', 'bundler/require'
+    # @return [Array<Gem::Specification>, nil]
+    def resolve_require require
+      gemspecs.resolve_require(require)
+    end
+
+    # @return [Solargraph::PinCache]
+    def pin_cache
+      @pin_cache ||= fresh_pincache
+    end
+
+    # @return [Environ]
+    def global_environ
+      # empty docmap, since the result needs to work in any possible
+      # context here
+      @global_environ ||= Convention.for_global(DocMap.new([], self, out: nil))
+    end
+
+    # @param gemspec [Gem::Specification]
+    # @param out [StringIO, IO, nil] output stream for logging
+    # @param rebuild [Boolean] whether to rebuild the pins even if they are cached
+    #
+    # @return [void]
+    def cache_gem gemspec, out: nil, rebuild: false
+      pin_cache.cache_gem(gemspec: gemspec, out: out, rebuild: rebuild)
+    end
+
+    # @param gemspec [Gem::Specification, Bundler::LazySpecification]
+    # @param out [StringIO, IO, nil] output stream for logging
+    #
+    # @return [void]
+    def uncache_gem gemspec, out: nil
+      pin_cache.uncache_gem(gemspec, out: out)
+    end
+
+    # @return [Solargraph::PinCache]
+    def fresh_pincache
+      PinCache.new(rbs_collection_path: rbs_collection_path,
+                   rbs_collection_config_path: rbs_collection_config_path,
+                   yard_plugins: yard_plugins,
+                   directory: directory)
+    end
+
+    # @return [Array<String>]
+    def yard_plugins
+      @yard_plugins ||= global_environ.yard_plugins.sort.uniq
+    end
+
     # @param level [Symbol]
     # @return [TypeChecker::Rules]
-    def rules(level)
+    def rules level
       @rules ||= TypeChecker::Rules.new(level, config.type_checker_rules)
     end
 
@@ -63,6 +130,7 @@ module Solargraph
     # @param sources [Array<Solargraph::Source>]
     # @return [Boolean] True if the source was added to the workspace
     def merge *sources
+      # @sg-ignore Need to add nil check here
       unless directory == '*' || sources.all? { |source| source_hash.key?(source.filename) }
         # Reload the config to determine if a new source should be included
         @config = Solargraph::Workspace::Config.new(directory)
@@ -70,10 +138,12 @@ module Solargraph
 
       includes_any = false
       sources.each do |source|
-        if directory == "*" || config.calculated.include?(source.filename)
-          source_hash[source.filename] = source
-          includes_any = true
-        end
+        # @sg-ignore Need to add nil check here
+        next unless directory == '*' || config.calculated.include?(source.filename)
+
+        # @sg-ignore Need to add nil check here
+        source_hash[source.filename] = source
+        includes_any = true
       end
 
       includes_any
@@ -121,24 +191,76 @@ module Solargraph
     def would_require? path
       require_paths.each do |rp|
         full = File.join rp, path
-        return true if File.file?(full) || File.file?(full << ".rb")
+        return true if File.file?(full) || File.file?(full << '.rb')
       end
       false
     end
 
+    # True if the workspace contains at least one gemspec file.
+    #
+    # @return [Boolean]
+    def gemspec?
+      !gemspec_files.empty?
+    end
+
+    # Get an array of all gemspec files in the workspace.
+    #
+    # @return [Array<String>]
+    def gemspec_files
+      return [] if directory.empty? || directory == '*'
+      @gemspec_files ||= Dir[File.join(directory, '**/*.gemspec')].select do |gs|
+        config.allow? gs
+      end
+    end
+
     # @return [String, nil]
     def rbs_collection_path
-      @gem_rbs_collection ||= read_rbs_collection_path
+      @rbs_collection_path ||= read_rbs_collection_path
     end
 
     # @return [String, nil]
     def rbs_collection_config_path
-      @rbs_collection_config_path ||= begin
+      @rbs_collection_config_path ||=
         unless directory.empty? || directory == '*'
           yaml_file = File.join(directory, 'rbs_collection.yaml')
           yaml_file if File.file?(yaml_file)
         end
+    end
+
+    # @param name [String]
+    # @param version [String, nil]
+    # @param out [IO, nil]
+    #
+    # @return [Gem::Specification, nil]
+    def find_gem name, version = nil, out: nil
+      gemspecs.find_gem(name, version, out: out)
+    end
+
+    # @return [Array<Gem::Specification>]
+    def all_gemspecs_from_bundle
+      gemspecs.all_gemspecs_from_bundle
+    end
+
+    # @param out [StringIO, IO, nil] output stream for logging
+    # @param rebuild [Boolean] whether to rebuild the pins even if they are cached
+    # @return [void]
+    def cache_all_for_workspace! out, rebuild: false
+      PinCache.cache_core(out: out) unless PinCache.core? && !rebuild
+
+      gem_specs = all_gemspecs_from_bundle
+      # try any possible standard libraries, but be quiet about it
+      stdlib_specs = pin_cache.possible_stdlibs.map { |stdlib| find_gem(stdlib, out: nil) }.compact
+      specs = (gem_specs + stdlib_specs)
+      specs.each do |spec|
+        pin_cache.cache_gem(gemspec: spec, rebuild: rebuild, out: out) unless pin_cache.cached?(spec)
       end
+      out&.puts "Documentation cached for all #{specs.length} gems."
+
+      # do this after so that we prefer stdlib requires from gems,
+      # which are likely to be newer and have more pins
+      pin_cache.cache_all_stdlibs(out: out, rebuild: rebuild)
+
+      out&.puts 'Documentation cached for core, standard library and gems.'
     end
 
     # Synchronize the workspace from the provided updater.
@@ -149,7 +271,9 @@ module Solargraph
       source_hash[updater.filename] = source_hash[updater.filename].synchronize(updater)
     end
 
+    # @sg-ignore Need to validate config
     # @return [String]
+    # @sg-ignore Need to validate config
     def command_path
       server['commandPath'] || 'solargraph'
     end
@@ -160,12 +284,9 @@ module Solargraph
       directory
     end
 
-    # True if the workspace has a root Gemfile.
-    #
-    # @todo Handle projects with custom Bundler/Gemfile setups (see DocMap#gemspecs_required_from_bundler)
-    #
-    def gemfile?
-      directory && File.file?(File.join(directory, 'Gemfile'))
+    # @return [Solargraph::Workspace::Gemspecs]
+    def gemspecs
+      @gemspecs ||= Solargraph::Workspace::Gemspecs.new(directory_or_nil)
     end
 
     private
@@ -184,27 +305,25 @@ module Solargraph
     # @return [void]
     def load_sources
       source_hash.clear
-      unless directory.empty? || directory == '*'
-        size = config.calculated.length
-        raise WorkspaceTooLargeError, "The workspace is too large to index (#{size} files, #{config.max_files} max)" if config.max_files > 0 and size > config.max_files
-        config.calculated.each do |filename|
-          begin
-            source_hash[filename] = Solargraph::Source.load(filename)
-          rescue Errno::ENOENT => e
-            Solargraph.logger.warn("Error loading #{filename}: [#{e.class}] #{e.message}")
-          end
-        end
+      return if directory.empty? || directory == '*'
+      size = config.calculated.length
+      if config.max_files.positive? && (size > config.max_files)
+        raise WorkspaceTooLargeError,
+              "The workspace is too large to index (#{size} files, #{config.max_files} max)"
+      end
+      config.calculated.each do |filename|
+        source_hash[filename] = Solargraph::Source.load(filename)
+      rescue Errno::ENOENT => e
+        Solargraph.logger.warn("Error loading #{filename}: [#{e.class}] #{e.message}")
       end
     end
 
     # @return [void]
     def require_plugins
       config.plugins.each do |plugin|
-        begin
-          require plugin
-        rescue LoadError
-          Solargraph.logger.warn "Failed to load plugin '#{plugin}'"
-        end
+        require plugin
+      rescue LoadError
+        Solargraph.logger.warn "Failed to load plugin '#{plugin}'"
       end
     end
 

data/lib/solargraph/yard_map/helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Solargraph
   class YardMap
     module Helpers
@@ -5,7 +7,7 @@ module Solargraph
 
       # @param code_object [YARD::CodeObjects::Base]
       # @param spec [Gem::Specification, nil]
-      # @return [Solargraph::Location, nil]
+      # @return [Solargraph::Location]
       def object_location code_object, spec
         if spec.nil? || code_object.nil? || code_object.file.nil? || code_object.line.nil?
           if code_object.namespace.is_a?(YARD::CodeObjects::NamespaceObject)
@@ -14,6 +16,7 @@ module Solargraph
           end
           return Solargraph::Location.new(__FILE__, Solargraph::Range.from_to(__LINE__ - 1, 0, __LINE__ - 1, 0))
         end
+        # @sg-ignore flow sensitive typing should be able to identify more blocks that always return
         file = File.join(spec.full_gem_path, code_object.file)
         Solargraph::Location.new(file, Solargraph::Range.from_to(code_object.line - 1, 0, code_object.line - 1, 0))
       end
@@ -21,10 +24,12 @@ module Solargraph
       # @param code_object [YARD::CodeObjects::Base]
       # @param spec [Gem::Specification, nil]
       # @return [Solargraph::Pin::Namespace]
-      def create_closure_namespace_for(code_object, spec)
+      def create_closure_namespace_for code_object, spec
         code_object_for_location = code_object
         # code_object.namespace is sometimes a YARD proxy object pointing to a method path ("Object#new")
-        code_object_for_location = code_object.namespace if code_object.namespace.is_a?(YARD::CodeObjects::NamespaceObject)
+        if code_object.namespace.is_a?(YARD::CodeObjects::NamespaceObject)
+          code_object_for_location = code_object.namespace
+        end
         namespace_location = object_location(code_object_for_location, spec)
         ns_name = code_object.namespace.to_s
         if ns_name.empty?

data/lib/solargraph/yard_map/mapper/to_method.rb

@@ -6,10 +6,11 @@ module Solargraph
       module ToMethod
         extend YardMap::Helpers
 
+        # @type [Hash{Array<String, Symbol, String> => Symbol}]
         VISIBILITY_OVERRIDE = {
           # YARD pays attention to 'private' statements prior to class methods but shouldn't
-          ["Rails::Engine", :class, "find_root_with_flag"] => :public
-        }
+          ['Rails::Engine', :class, 'find_root_with_flag'] => :public
+        }.freeze
 
         # @param code_object [YARD::CodeObjects::MethodObject]
         # @param name [String, nil]
@@ -25,10 +26,15 @@ module Solargraph
           return_type = ComplexType::SELF if name == 'new'
           comments = code_object.docstring ? code_object.docstring.all.to_s : ''
           final_scope = scope || code_object.scope
+          # @sg-ignore Need to add nil check here
           override_key = [closure.path, final_scope, name]
           final_visibility = VISIBILITY_OVERRIDE[override_key]
+          # @sg-ignore Need to add nil check here
           final_visibility ||= VISIBILITY_OVERRIDE[[closure.path, final_scope]]
-          final_visibility ||= :private if closure.path == 'Kernel' && Kernel.private_instance_methods(false).include?(name.to_sym)
+          # @sg-ignore Need to add nil check here
+          if closure.path == 'Kernel' && Kernel.private_instance_methods(false).include?(name.to_sym)
+            final_visibility ||= :private
+          end
           final_visibility ||= visibility
           final_visibility ||= :private if code_object.module_function? && final_scope == :instance
           final_visibility ||= :public if code_object.module_function? && final_scope == :class
@@ -46,9 +52,10 @@ module Solargraph
               explicit: code_object.is_explicit?,
               return_type: return_type,
               parameters: [],
-              source: :yardoc,
+              source: :yardoc
             )
           else
+            # @sg-ignore Need to add nil check here
             pin = Pin::Method.new(
               location: location,
               closure: closure,
@@ -61,7 +68,7 @@ module Solargraph
               return_type: return_type,
               attribute: code_object.is_attribute?,
               parameters: [],
-              source: :yardoc,
+              source: :yardoc
             )
             pin.parameters.concat get_parameters(code_object, location, comments, pin)
             pin.parameters.freeze
@@ -85,7 +92,6 @@ module Solargraph
             # HACK: Skip `nil` and `self` parameters that are sometimes emitted
             # for methods defined in C
             # See https://github.com/castwide/solargraph/issues/345
-            # @sg-ignore https://github.com/castwide/solargraph/pull/1114
             code_object.parameters.select { |a| a[0] && a[0] != 'self' }.map do |a|
               Solargraph::Pin::Parameter.new(
                 location: location,
@@ -95,7 +101,7 @@ module Solargraph
                 presence: nil,
                 decl: arg_type(a),
                 asgn_code: a[1],
-                source: :yardoc,
+                source: :yardoc
               )
             end
           end

data/lib/solargraph/yard_map/mapper/to_namespace.rb

@@ -21,8 +21,9 @@ module Solargraph
             type: code_object.is_a?(YARD::CodeObjects::ClassObject) ? :class : :module,
             visibility: code_object.visibility,
             closure: closure,
+            # @sg-ignore need to add a nil check here
             gates: closure.gates,
-            source: :yardoc,
+            source: :yardoc
           )
         end
       end

data/lib/solargraph/yard_map/mapper.rb

@@ -24,6 +24,7 @@ module Solargraph
         end
         # Some yardocs contain documentation for dependencies that can be
         # ignored here. The YardMap will load dependencies separately.
+        # @sg-ignore Need to add nil check here
         @pins.keep_if { |pin| pin.location.nil? || File.file?(pin.location.filename) } if @spec
         @pins
       end
@@ -34,24 +35,27 @@ module Solargraph
       # @return [Array<Pin::Base>]
       def generate_pins code_object
         result = []
-        if code_object.is_a?(YARD::CodeObjects::NamespaceObject)
+        case code_object
+        when YARD::CodeObjects::NamespaceObject
           nspin = ToNamespace.make(code_object, @spec, @namespace_pins[code_object.namespace.to_s])
           @namespace_pins[code_object.path] = nspin
           result.push nspin
-          if code_object.is_a?(YARD::CodeObjects::ClassObject) and !code_object.superclass.nil?
+          if code_object.is_a?(YARD::CodeObjects::ClassObject) && !code_object.superclass.nil?
             # This method of superclass detection is a bit of a hack. If
             # the superclass is a Proxy, it is assumed to be undefined in its
             # yardoc and converted to a fully qualified namespace.
             superclass = if code_object.superclass.is_a?(YARD::CodeObjects::Proxy)
-              "::#{code_object.superclass}"
-            else
-              code_object.superclass.to_s
-            end
+                           "::#{code_object.superclass}"
+                         else
+                           code_object.superclass.to_s
+                         end
             result.push Solargraph::Pin::Reference::Superclass.new(name: superclass, closure: nspin, source: :yard_map)
           end
+          # @sg-ignore flow sensitive typing ought to be able to handle 'when ClassName'
           code_object.class_mixins.each do |m|
             result.push Solargraph::Pin::Reference::Extend.new(closure: nspin, name: m.path, source: :yard_map)
           end
+          # @sg-ignore flow sensitive typing ought to be able to handle 'when ClassName'
           code_object.instance_mixins.each do |m|
             result.push Solargraph::Pin::Reference::Include.new(
               closure: nspin, # @todo Fix this
@@ -59,8 +63,9 @@ module Solargraph
               source: :yard_map
             )
           end
-        elsif code_object.is_a?(YARD::CodeObjects::MethodObject)
+        when YARD::CodeObjects::MethodObject
           closure = @namespace_pins[code_object.namespace.to_s]
+          # @sg-ignore flow sensitive typing ought to be able to handle 'when ClassName'
           if code_object.name == :initialize && code_object.scope == :instance
             # @todo Check the visibility of <Class>.new
             result.push ToMethod.make(code_object, 'new', :class, :public, closure, @spec)
@@ -68,7 +73,7 @@ module Solargraph
           else
             result.push ToMethod.make(code_object, nil, nil, nil, closure, @spec)
           end
-        elsif code_object.is_a?(YARD::CodeObjects::ConstantObject)
+        when YARD::CodeObjects::ConstantObject
           closure = @namespace_pins[code_object.namespace]
           result.push ToConstant.make(code_object, closure, @spec)
         end

data/lib/solargraph/yard_tags.rb

@@ -1,20 +1,20 @@
-# frozen_string_literal: true
-
-require 'yard'
-
-# Change YARD log IO to avoid sending unexpected messages to STDOUT
-YARD::Logger.instance.io = File.new(File::NULL, 'w')
-
-module Solargraph
-  # A placeholder for the @!domain directive. It doesn't need to do anything
-  # for yardocs. It's only used for Solargraph API maps.
-  class DomainDirective < YARD::Tags::Directive
-    def call; end
-  end
-end
-
-# Define a @type tag for documenting variables
-YARD::Tags::Library.define_tag("Type", :type, :with_types_and_name)
-
-# Define an @!override directive for overriding method tags
-YARD::Tags::Library.define_directive("override", :with_name, Solargraph::DomainDirective)
+# frozen_string_literal: true
+
+require 'yard'
+
+# Change YARD log IO to avoid sending unexpected messages to STDOUT
+YARD::Logger.instance.io = File.new(File::NULL, 'w')
+
+module Solargraph
+  # A placeholder for the @!domain directive. It doesn't need to do anything
+  # for yardocs. It's only used for Solargraph API maps.
+  class DomainDirective < YARD::Tags::Directive
+    def call; end
+  end
+end
+
+# Define a @type tag for documenting variables
+YARD::Tags::Library.define_tag('Type', :type, :with_types_and_name)
+
+# Define an @!override directive for overriding method tags
+YARD::Tags::Library.define_directive('override', :with_name, Solargraph::DomainDirective)

data/lib/solargraph/yardoc.rb

@@ -8,15 +8,15 @@ module Solargraph
   module Yardoc
     module_function
 
-    # Build and cache a gem's yardoc and return the path. If the cache already
-    # exists, do nothing and return the path.
+    # Build and save a gem's yardoc into a given path.
     #
-    # @param yard_plugins [Array<String>] The names of YARD plugins to use.
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
+    # @param yard_plugins [Array<String>]
     # @param gemspec [Gem::Specification]
-    # @return [String] The path to the cached yardoc.
-    def cache(yard_plugins, gemspec)
-      path = PinCache.yardoc_path gemspec
-      return path if cached?(gemspec)
+    #
+    # @return [void]
+    def build_docs gem_yardoc_path, yard_plugins, gemspec
+      return if docs_built?(gem_yardoc_path)
 
       unless Dir.exist? gemspec.gem_dir
         # Can happen in at least some (old?) RubyGems versions when we
@@ -24,35 +24,44 @@ module Solargraph
         #
         # https://github.com/apiology/solargraph/actions/runs/17650140201/job/50158676842?pr=10
         Solargraph.logger.info { "Bad info from gemspec - #{gemspec.gem_dir} does not exist" }
-        return path
+        return
       end
 
       Solargraph.logger.info "Caching yardoc for #{gemspec.name} #{gemspec.version}"
-      cmd = "yardoc --db #{path} --no-output --plugin solargraph"
+      cmd = "yardoc --db #{gem_yardoc_path} --no-output --plugin solargraph"
       yard_plugins.each { |plugin| cmd << " --plugin #{plugin}" }
       Solargraph.logger.debug { "Running: #{cmd}" }
       # @todo set these up to run in parallel
+      # @sg-ignore Our fill won't work properly due to an issue in
+      #   Callable#arity_matches? - see comment there
       stdout_and_stderr_str, status = Open3.capture2e(current_bundle_env_tweaks, cmd, chdir: gemspec.gem_dir)
-      unless status.success?
-        Solargraph.logger.warn { "YARD failed running #{cmd.inspect} in #{gemspec.gem_dir}" }
-        Solargraph.logger.info stdout_and_stderr_str
-      end
-      path
+      return if status.success?
+      Solargraph.logger.warn { "YARD failed running #{cmd.inspect} in #{gemspec.gem_dir}" }
+      Solargraph.logger.info stdout_and_stderr_str
+    end
+
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
+    # @param gemspec [Gem::Specification, Bundler::LazySpecification]
+    # @param out [StringIO, IO, nil] where to log messages
+    # @return [Array<Pin::Base>]
+    def build_pins gem_yardoc_path, gemspec, out: $stderr
+      yardoc = load!(gem_yardoc_path)
+      YardMap::Mapper.new(yardoc, gemspec).map
     end
 
     # True if the gem yardoc is cached.
     #
-    # @param gemspec [Gem::Specification]
-    def cached?(gemspec)
-      yardoc = File.join(PinCache.yardoc_path(gemspec), 'complete')
+    # @param gem_yardoc_path [String]
+    def docs_built? gem_yardoc_path
+      yardoc = File.join(gem_yardoc_path, 'complete')
       File.exist?(yardoc)
     end
 
     # True if another process is currently building the yardoc cache.
     #
-    # @param gemspec [Gem::Specification]
-    def processing?(gemspec)
-      yardoc = File.join(PinCache.yardoc_path(gemspec), 'processing')
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
+    def processing? gem_yardoc_path
+      yardoc = File.join(gem_yardoc_path, 'processing')
       File.exist?(yardoc)
     end
 
@@ -60,10 +69,10 @@ module Solargraph
     #
     # @note This method modifies the global YARD registry.
     #
-    # @param gemspec [Gem::Specification]
+    # @param gem_yardoc_path [String] the path to the yardoc cache of a particular gem
     # @return [Array<YARD::CodeObjects::Base>]
-    def load!(gemspec)
-      YARD::Registry.load! PinCache.yardoc_path gemspec
+    def load! gem_yardoc_path
+      YARD::Registry.load! gem_yardoc_path
       YARD::Registry.all
     end
 
@@ -78,6 +87,7 @@ module Solargraph
     # @return [Hash{String => String}] a hash of environment variables to override
     def current_bundle_env_tweaks
       tweaks = {}
+      # @sg-ignore Translate to something flow sensitive typing understands
       if ENV['BUNDLE_GEMFILE'] && !ENV['BUNDLE_GEMFILE'].empty?
         tweaks['BUNDLE_GEMFILE'] = File.expand_path(ENV['BUNDLE_GEMFILE'])
       end

data/lib/solargraph.rb

@@ -55,8 +55,8 @@ module Solargraph
 
   CHDIR_MUTEX = Mutex.new
 
-  # @param type [Symbol] Type of assert.
-  def self.asserts_on?(type)
+  def self.asserts_on?
+    # @sg-ignore Translate to something flow sensitive typing understands
     if ENV['SOLARGRAPH_ASSERTS'].nil? || ENV['SOLARGRAPH_ASSERTS'].empty?
       false
     elsif ENV['SOLARGRAPH_ASSERTS'] == 'on'
@@ -71,8 +71,29 @@ module Solargraph
   # @param msg [String, nil] An optional message to log
   # @param block [Proc] A block that returns a message to log
   # @return [void]
-  def self.assert_or_log(type, msg = nil, &block)
-    raise (msg || block.call) if asserts_on?(type) && ![:combine_with_visibility].include?(type)
+  def self.assert_or_log type, msg = nil, &block
+    if asserts_on?
+      # @type [String, nil]
+      msg ||= block.call
+
+      raise "No message given for #{type.inspect}" if msg.nil?
+
+      # conditional aliases to handle compatibility corner cases
+      # @sg-ignore flow sensitive typing needs to handle 'raise if'
+      return if type == :alias_target_missing && msg.include?('highline/compatibility.rb')
+      # @sg-ignore flow sensitive typing needs to handle 'raise if'
+      return if type == :alias_target_missing && msg.include?('lib/json/add/date.rb')
+      # @todo :combine_with_visibility is not ready for prime time -
+      #  lots of disagreements found in practice that heuristics need
+      #  to be created for and/or debugging needs to resolve in pin
+      #  generation.
+      # @todo :api_map_namespace_pin_stack triggers in a badly handled
+      #   self type case - 'keeps track of self type in method
+      #   parameters in subclass' in call_spec.rb
+      return if %i[api_map_namespace_pin_stack combine_with_visibility].include?(type)
+
+      raise msg
+    end
     logger.info msg, &block
   end
 
@@ -92,10 +113,10 @@ module Solargraph
   # @return [generic<T>]
   def self.with_clean_env &block
     meth = if Bundler.respond_to?(:with_original_env)
-      :with_original_env
-    else
-      :with_clean_env
-    end
+             :with_original_env
+           else
+             :with_clean_env
+           end
     Bundler.send meth, &block
   end
 end