solargraph-rails 1.1.2 → 1.2.0

data/lib/solargraph/rails/model.rb

@@ -9,11 +9,35 @@ module Solargraph
         filename.include?('app/models')
       end
 
+      # @param source_map [Solargraph::SourceMap]
+      # @param ns [Solargraph::Pin::Namespace]
       def process(source_map, ns)
         return [] unless self.class.valid_filename?(source_map.filename)
 
-        walker = Walker.from_source(source_map.source)
         pins = []
+        abstract = false
+
+        # ActiveRecord defines a hidden subclass of ActiveRecord::Relation for
+        # each model class that inherits from ActiveRecord::Base.
+        pins << relation = Solargraph::Pin::Namespace.new(
+          name: 'ActiveRecord_Relation',
+          type: :class,
+          visibility: :private,
+          closure: ns,
+        )
+        pins << Solargraph::Pin::Reference::Superclass.new(
+          name: "ActiveRecord::Relation",
+          closure: relation,
+        )
+
+        pins << Solargraph::Pin::Method.new(
+          name: 'model',
+          scope: :instance,
+          closure: relation,
+          comments: "@return [Class<#{ns.name}>]"
+        )
+
+        walker = Walker.from_source(source_map.source)
 
         walker.on :send, [nil, :belongs_to] do |ast|
           pins << singular_association(ns, ast)
@@ -31,75 +55,272 @@ module Solargraph
           pins << plural_association(ns, ast)
         end
 
+        walker.on :send, [:self, :abstract_class=, :true] do |ast|
+          abstract = true
+        end
+
         walker.on :send, [nil, :scope] do |ast|
           next if ast.children[2].nil?
           name = ast.children[2].children.last
 
-          method_pin =
-            Util.build_public_method(
-              ns,
-              name.to_s,
-              types: ns.return_type.map(&:tag),
-              scope: :class,
-              location: Util.build_location(ast, ns.filename)
-            )
+          parameters = []
 
           if ast.children.last.type == :block
             location = ast.children.last.location
-            block_pin =
-              source_map.locate_block_pin(location.line, location.column)
-            method_pin.parameters.concat(block_pin.parameters.clone)
+            block_pin = source_map.locate_block_pin(location.line, location.column)
+            parameters.concat(block_pin.parameters.clone)
+            block_pin.instance_variable_set(:@binder, ComplexType.parse(relation.path))
           end
-          pins << method_pin
+
+          location = Util.build_location(ast, ns.filename)
+          # define scopes as a class methods on the model, and instance methods
+          # on the hidden relation class
+          pins << Util.build_public_method(
+            ns,
+            name.to_s,
+            scope: :class,
+            parameters: parameters,
+            types: [relation_type(ns.name)],
+            location: location
+          )
+          pins << Util.build_public_method(
+            relation,
+            name.to_s,
+            scope: :instance,
+            parameters: parameters,
+            types: [relation_type(ns.name)],
+            location: location
+          )
         end
 
         walker.walk
-        if pins.any?
-          Solargraph.logger.debug(
-            "[Rails][Model] added #{pins.map(&:name)} to #{ns.path}"
-          )
+
+        # Class methods on the model are exposed as *instance* methods on the
+        # hidden ActiveRecord_Relation class.
+        #
+        # Uses DelegatedMethod pins (instead of build_public_method) so Solargraph
+        # will show the "real" method pin for type inference, probing, docs etc.
+        source_map.pins.each do |pin|
+          next unless Delegate.supported?
+          next unless pin.is_a?(Solargraph::Pin::Method) && pin.scope == :class && pin.closure == ns
+
+          pins << Solargraph::Pin::DelegatedMethod.new(closure: relation, scope: :instance, method: pin)
+        end
+
+        unless abstract
+          pins += relation_method_pins(ns, :class, ns.path)
+          pins += relation_method_pins(relation, :instance, ns.path)
         end
+
+        Solargraph.logger.debug("[Rails][Model] added #{pins.map(&:name)} to #{ns.path}")
+
         pins
       end
 
+
       def plural_association(ns, ast)
-        relation_name = ast.children[2].children.first
+        association_name = ast.children[2].children.first
         class_name =
           extract_custom_class_name(ast) ||
-            relation_name.to_s.singularize.camelize
+            association_name.to_s.singularize.camelize
 
         Util.build_public_method(
           ns,
-          relation_name.to_s,
-          types: ["ActiveRecord::Associations::CollectionProxy<#{class_name}>"],
+          association_name.to_s,
+          types: [relation_type(class_name)],
           location: Util.build_location(ast, ns.filename)
         )
       end
 
       def singular_association(ns, ast)
-        relation_name = ast.children[2].children.first
+        association_name = ast.children[2].children.first
         class_name =
-          extract_custom_class_name(ast) || relation_name.to_s.camelize
+          extract_custom_class_name(ast) || association_name.to_s.camelize
 
         Util.build_public_method(
           ns,
-          relation_name.to_s,
+          association_name.to_s,
           types: [class_name],
           location: Util.build_location(ast, ns.filename)
         )
       end
 
       def extract_custom_class_name(ast)
-        options = ast.children[3..-1].find { |n| n.type == :hash }
-        return unless options
+        node = Util.extract_option(ast, :class_name)
+        return unless node && node.type == :str
+
+        node.children.last
+      end
+
+      # Generate method pins for ActiveRecord methods in the given namespace/scope, where the
+      # the return types will be templated with the provided model class.
+      #
+      # These method pins don't need to include any documentation, as Solargraph will merge
+      # documentation from Rails when it resolves the "method stack" for each pin.
+      #
+      # @param ns [Solargraph::Pin::Namespace] the namespace (model or relation class) in which to define methods.
+      # @param scope [:instance, :class] the method scope (:class for the model and :instance for the relation).
+      # @param model_class [String] the model class (e.g. "Person") that should be used in return types.
+      # @return [Array<Solargraph::Pin::Method>]
+      def relation_method_pins(namespace, scope, model_class)
+        pins = []
+        finalize_type = ->(template) { template.gsub '$T', model_class }
+        RETURNS_RELATION.each do |method_name, params|
+          next if OVERLOADED.key(method_name)
 
-        class_name_pair =
-          options.children.find do |n|
-            n.children[0].deconstruct == %i[sym class_name] &&
-              n.children[1].type == :str
+          method = Util.build_public_method(namespace, method_name, scope: scope, parameters: [], types: [relation_type(model_class)])
+          params.each do |name, type|
+            decl = :arg
+            # TODO: maybe I can remove this and go back to letting solargraph parse a comment block
+            # @see https://github.com/castwide/solargraph/pull/601
+            if name.start_with?('**')
+              name = name[2..]
+              decl = :kwrestarg
+            elsif name.start_with?('*')
+              name = name[1..]
+              decl = :restarg
+            end
+            method.parameters << Solargraph::Pin::Parameter.new(name: name, decl: decl, closure: method,
+                                                                comments: "@return [#{type}]")
           end
-        class_name_pair && class_name_pair.children.last.children.last
+          pins << method
+        end
+
+        RETURNS_INSTANCE.each do |method|
+          pins << Util.build_public_method(namespace, method, scope: scope, types: [model_class])
+        end
+
+        OVERLOADED.each do |method, overloads|
+          comments = overloads.map do |arg_list, lines|
+            lines = ["@return [#{lines}]"] if lines.is_a?(String)
+            lines = ["@overload #{method}#{arg_list}"] + lines
+            lines.map(&finalize_type).join("\n  ")
+          end
+          pins << Util.build_public_method(namespace, method, scope: scope, comments: comments.join("\n"))
+        end
+        pins
+      end
+
+      # construct the type name for the models hidden relation class.
+      # the additional type parameter is _not_ redundant, it makes enumerable methods work.
+      def relation_type(model_path)
+        "#{model_path}::ActiveRecord_Relation"
       end
+
+      ANY_ARGS = {"*args" => nil}
+
+      # @todo can this be replaced with rbs_collection's
+      #   _ActiveRecord_Relation interface?  Potential leads:
+      #   https://github.com/pocke/rbs_rails
+      #   https://github.com/ruby/gem_rbs_collection/blob/6f2d93ab244008bec51db7b4fffae68b40232502/gems/paranoia/2.5/paranoia.rbs#L6C1-L7C1
+      #   https://github.com/ksss/orthoses-rails
+      #   https://github.com/PawCorp/walltaker/blob/728682baa56a267611aca1ddb9f44fdcd97f6c80/sig/rbs_rails/app/models/user.rbs#L2
+      RETURNS_RELATION = {
+        "all" => {},
+        "and" => {"other" => "ActiveRecord::Relation"},
+        "annotate" => ANY_ARGS,
+        "distinct" => ANY_ARGS,
+        "eager_load" => ANY_ARGS,
+        "excluding" => ANY_ARGS,
+        "from" => {"source" => "ActiveRecord::Relation"},
+        "group" => ANY_ARGS,
+        "having" => ANY_ARGS,
+        "in_order_of" => ANY_ARGS,
+        "includes" => ANY_ARGS,
+        "invert_where" => {},
+        "joins" => ANY_ARGS,
+        "left_joins" => ANY_ARGS,
+        "left_outer_joins" => ANY_ARGS,
+        "limit" => {"value" => "Integer"},
+        "lock" => {"locks" => "true, false"},
+        "none" => {},
+        "offset" => {"value" => "Integer"},
+        "or" => {"other" => "ActiveRecord::Relation"},
+        "order" => ANY_ARGS,
+        "preload" => ANY_ARGS,
+        "readonly" => {"value" => "true, false"},
+        "references" => {"*table_names" => nil},
+        "reorder" => ANY_ARGS,
+        "reselect" => ANY_ARGS,
+        "reverse_order" => {},
+        "rewhere" => {"conditions" => "Hash"},
+        "select" => ANY_ARGS,
+        "strict_loading" => {"value" => "true, false"},
+        "unscope" => ANY_ARGS,
+        "without" => ANY_ARGS,
+      }
+
+      RETURNS_INSTANCE = %w[
+        take take! sole
+        first  second  third  fourth  fifth  third_to_last  second_to_last  last
+        first! second! third! fourth! fifth! third_to_last! second_to_last! last!
+        forty_two forty_two!
+      ]
+
+      OVERLOADED = {
+        "where" => {
+          "()" => "ActiveRecord::QueryMethods::WhereChain<$T::ActiveRecord_Relation>",
+          "(sql, *args)" => [
+            "@return [$T::ActiveRecord_Relation]",
+          ],
+        },
+        "select" => {
+          "()" => [
+            "@yieldparam [$T]",
+            "@return [Array<$T>]",
+          ],
+          "(*args)" => "$T::ActiveRecord_Relation",
+        },
+        "find" => {
+          "(id)" => [
+            "@param id [Integer, String]",
+            "@return [$T]"
+          ],
+          "(*ids)" => "Array<$T>",
+        },
+        "find_by" => {
+          "(hash)" => [
+            "@param hash [Hash] attributes to match by",
+            "@return [$T, nil]",
+          ],
+          "(sql, *args)" => [
+            "@param sql [String] a SQL snippet for the WHERE clause",
+            "@return [$T, nil]"
+          ]
+        },
+        "find_by!" => {
+          "(hash)" => [
+            "@param hash [Hash] attributes to match by",
+            "@return [$T]",
+          ],
+          "(sql, *args)" => [
+            "@param sql [String] a SQL snippet for the WHERE clause",
+            "@return [$T]"
+          ]
+        },
+        "find_sole_by" => {
+          "(hash)" => [
+            "@param hash [Hash] attributes to match by",
+            "@return [$T]",
+          ],
+          "(sql, *args)" => [
+            "@param sql [String] a SQL snippet for the WHERE clause",
+            "@return [$T]"
+          ]
+        },
+        "take" => {
+          "()" => "T, nil",
+          "(limit)" => "Array<$T>",
+        },
+        "first" => {
+          "()" => "$T, nil",
+          "(limit)" => "Array<$T>",
+        },
+        "last" => {
+          "()" => "$T, nil",
+          "(limit)" => "Array<$T>"
+        },
+      }
     end
   end
 end

data/lib/solargraph/rails/rails_api.rb

@@ -14,8 +14,8 @@ module Solargraph
         end
       end
 
-      # @param yard_map [YardMap]
-      def global(_yard_map)
+      # @param yard_map [Solargraph::DocMap]
+      def global(_doc_map)
         extra_source_maps.values.flat_map(&:pins)
       end
 

data/lib/solargraph/rails/schema.rb

@@ -43,15 +43,34 @@ module Solargraph
 
         return [] unless table
 
-        pins =
-          table.map do |column, data|
-            Util.build_public_method(
-              ns,
-              column,
-              types: [RUBY_TYPES.fetch(data.type.to_sym)],
-              location: Util.build_location(data.ast, 'db/schema.rb')
-            )
+        pins = []
+        table.each do |column, data|
+          location = Util.build_location(data.ast, 'db/schema.rb')
+          type = RUBY_TYPES[data.type.to_sym] || 'String'
+          %w[% %_in_database %_before_last_save].each do |tpl|
+            name = tpl.sub('%', column)
+            pins << Util.build_public_method(ns, name, types: [type], location: location)
           end
+          %w[%? %_changed? saved_change_to_%? will_save_change_to_%?].each do |tpl|
+            name = tpl.sub('%', column)
+            pins << Util.build_public_method(ns, name, types: ['Boolean'], location: location)
+          end
+          %w[%_change_to_be_saved saved_change_to_%].each do |tpl|
+            name = tpl.sub('%', column)
+            types = ["Array(#{type}, #{type})"]
+            pins << Util.build_public_method(ns, name, types: types, location: location)
+          end
+          pins << Util.build_public_method(ns, "#{column}=", types: [type],
+                                           params: { 'value' => [type] },
+                                           location: location)
+
+          # Note on this: its the starting step of dynamic filters. Technically, you can also do Model.find_by_col1_and_col2(val1, val2)
+          # However, if we start suggestion all of those possibilities, it will simply be bad UX because of having too many suggestions
+          pins << Util.build_public_method(ns, "find_by_#{column}", types: ['self', 'nil'],
+                                          params: { 'value' => [type] },
+                                          location: location,
+                                          scope: :class)
+        end
 
         if pins.any?
           Solargraph.logger.debug(

data/lib/solargraph/rails/util.rb

@@ -4,25 +4,45 @@ module Solargraph
       def self.build_public_method(
         ns,
         name,
+        comments: nil,
+        parameters: [],
         types: nil,
+        params: {},
         location: nil,
         attribute: false,
         scope: :instance
       )
         opts = {
           name: name,
+          parameters: parameters,
           location: location,
           closure: ns,
           scope: scope,
           attribute: attribute
         }
 
-        comments = []
-        comments << "@return [#{types.join(',')}]" if types
+        comments_arr = [comments].compact
+        params.each do |name, types|
+          comments_arr << "@param [#{types.join(',')}] #{name}"
+        end
+        comments_arr << "@return [#{types.join(',')}]" if types
 
-        opts[:comments] = comments.join("\n")
+        opts[:comments] ||= comments_arr.join("\n")
 
-        Solargraph::Pin::Method.new(**opts)
+        m = Solargraph::Pin::Method.new(**opts)
+        parameters = parameters + params.map do |name, type|
+            Solargraph::Pin::Parameter.new(
+              location: nil,
+              closure: m,
+              comments: '',
+              name: name,
+              presence: nil,
+              decl: :arg,
+              asgn_code: nil
+            )
+        end
+        m.parameters.concat(parameters)
+        m
       end
 
       def self.build_module_include(ns, module_name, location)
@@ -63,6 +83,27 @@ module Solargraph
       def self.method_return(path, type)
         Solargraph::Pin::Reference::Override.method_return(path, type)
       end
+
+      # Extract the value of a given option from a :send syntax node.
+      #
+      # E.g. given an AST node for `foo(:bar, baz: qux)`, you can use
+      # `extract_option(node, :baz)` to get the AST node for `qux`.
+      #
+      # @param call_node [AST::Node]
+      # @param option_name [Symbol]
+      # @return [AST::Node, nil]
+      def self.extract_option(call_node, option_name)
+        options = call_node.children[3..-1].find { |n| n.type == :hash }
+        return unless options
+
+        pair =
+          options.children.find do |n|
+            n.children[0] && n.children[0].deconstruct == [:sym, option_name]
+          end
+        return unless pair
+
+        pair.children[1]
+      end
     end
   end
 end

data/lib/solargraph/rails/version.rb

@@ -1,5 +1,5 @@
 module Solargraph
   module Rails
-    VERSION = '1.1.2'
+    VERSION = '1.2.0'
   end
 end

data/lib/solargraph-rails.rb

@@ -50,7 +50,7 @@ module Solargraph
         pins += run_feature { Storage.instance.process(source_map, ns) }
         pins += run_feature { Autoload.instance.process(source_map, ns, ds) }
         pins += run_feature { Devise.instance.process(source_map, ns) }
-        pins += run_feature { Delegate.instance.process(source_map, ns) }
+        pins += run_feature { Delegate.instance.process(source_map, ns) } if Delegate.supported?
         pins += run_feature { RailsApi.instance.local(source_map, ns) }
 
         Solargraph::Environ.new(pins: pins)

data/script/generate_definitions.rb

@@ -1,28 +1,42 @@
 require File.join(Dir.pwd, ARGV.first, 'config/environment')
 
-class Model < ActiveRecord::Base
+require 'method_source'
+
+def _instance_methods(klass, test = klass.new)
+  klass
+    .instance_methods(true)
+    .sort
+    .reject { |m| m.to_s.start_with?('_') || (test && !test.respond_to?(m)) }
+    .map { |m| klass.instance_method(m) }
 end
 
 def own_instance_methods(klass, test = klass.new)
-  (instance_methods(klass, test) - Object.methods).select do |m|
-    m.source_location && m.source_location.first.include?('gem')
+  reject_meth_names = (Module.methods + Module.private_methods + [:to_yaml, :to_json]).to_set
+  _instance_methods(klass, test).select do |m|
+    !reject_meth_names.include?(m.name) &&
+      m.source_location &&
+      m.source_location.first.include?('gem') &&
+      m.source_location &&
+      m.source_location.first.include?('gem') &&
+      !m.source_location.first.include?('/pp-') &&
+      m.comment &&
+      !m.comment.empty? &&
+      m.comment != ':nodoc:'
   end
 end
 
 def own_class_methods(klass)
-  (class_methods(klass) - Object.methods).select do |m|
-    m.source_location && m.source_location.first.include?('gem')
+  reject_meth_names = (Module.methods + Module.private_methods + [:to_yaml, :to_json]).to_set
+  class_methods(klass).select do |m|
+    !reject_meth_names.include?(m.name) &&
+      m.source_location &&
+      m.source_location.first.include?('gem') &&
+      m.comment &&
+      !m.comment.empty? &&
+      m.comment != ':nodoc:'
   end
 end
 
-def instance_methods(klass, test = klass.new)
-  klass
-    .instance_methods(true)
-    .sort
-    .reject { |m| m.to_s.start_with?('_') || (test && !test.respond_to?(m)) }
-    .map { |m| klass.instance_method(m) }
-end
-
 def class_methods(klass)
   klass
     .methods(true)
@@ -53,6 +67,18 @@ def build_report(klass, test: klass.new)
   result
 end
 
+def add_new_methods(klass, test, yaml_filename)
+  new_report = build_report(klass, test: test)
+  existing_report = {}
+  existing_report = YAML.load_file(yaml_filename) if File.exist?(yaml_filename)
+  report = { **new_report, **existing_report }
+  class_methods, instance_methods = report.partition { |k, _| k.include?('.') }
+  class_methods = class_methods.sort_by { |k, _v| k }.to_h
+  instance_methods = instance_methods.sort_by { |k, _v| k }.to_h
+  report = { **class_methods, **instance_methods }
+  File.write(yaml_filename, report.deep_stringify_keys.to_yaml)
+end
+
 def core_ext_report(klass, test = klass.new)
   result = {}
   distribution = {}
@@ -73,7 +99,7 @@ def core_ext_report(klass, test = klass.new)
       }
     end
 
-  instance_methods(klass, test)
+  _instance_methods(klass, test)
     .select(&:source_location)
     .select do |meth|
       loc = meth.source_location.first
@@ -92,18 +118,18 @@ def core_ext_report(klass, test = klass.new)
   result
 end
 
-report = build_report(ActiveRecord::Base, test: Model.new)
-File.write('activerecord.yml', report.deep_stringify_keys.to_yaml)
+add_new_methods(ActiveRecord::Base, Model.new, '../definitions/activerecord.yml')
+add_new_methods(ActionController::Base, false, '../definitions/actioncontroller.yml')
+add_new_methods(ActiveJob::Base, false, '../definitions/activejob.yml')
 
-report = build_report(ActionController::Base)
-File.write('actioncontroller.yml', report.deep_stringify_keys.to_yaml)
+Rails.application.routes.draw do
+  add_new_methods(self.class, false, '../definitions/routes.yml')
+end
 
-report = build_report(ActiveJob::Base)
-File.write('activejob.yml', report.deep_stringify_keys.to_yaml)
+add_new_methods(Rails::Application, false, '../definitions/application.yml')
 
 Rails.application.routes.draw do
-  report = build_report(self.class, test: false)
-  File.write('routes.yml', report.deep_stringify_keys.to_yaml)
+  add_new_methods(self.class, false, '../definitions/routes.yml')
 end
 
 [
@@ -134,8 +160,7 @@ end
       end
     end
 
-  report = core_ext_report(klass, test = test)
-  File.write("#{klass.to_s}.yml", report.deep_stringify_keys.to_yaml)
+  add_new_methods(klass, test, "../definitions/core/#{klass.to_s}.yml")
 end
 
 # binding.pry

data/solargraph-rails.gemspec

@@ -4,7 +4,23 @@ require 'solargraph/rails/version'
 
 
 solargraph_force_ci_version = (ENV['CI'] && ENV['MATRIX_SOLARGRAPH_VERSION'])
-solargraph_version = solargraph_force_ci_version ? [solargraph_force_ci_version] : [">= 0.48.0", '<0.53.0']
+solargraph_version =
+  if solargraph_force_ci_version
+    [solargraph_force_ci_version]
+  else
+    [
+      # below this isn't tested in CI
+      '>= 0.48.0',
+      # did not have support for global conventions
+      '!=0.53.0', '!=0.53.1', '!=0.53.2', '!=0.53.3', '!=0.53.4',
+      # did not have support for global conventions
+      '!=0.54.0', '!=0.54.1', '!=0.54.2', '!=0.54.3', '!=0.54.4', '!=0.54.5',
+      # did not have support for global conventions
+      '!=0.55.0', '!=0.55.1', '!=0.55.2', '!=0.55.3', '!=0.55.4', '!=0.55.5', '!=0.55.6', '!=0.55.7',
+      # above this hasn't been tested
+      '< 0.57'
+    ]
+  end
 
 Gem::Specification.new do |spec|
   spec.name = 'solargraph-rails'
@@ -30,11 +46,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 2.3'
   spec.add_development_dependency 'rake', '~> 12.3.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.76'
+  spec.add_development_dependency 'simplecov', '~> 0.22.0'
+  spec.add_development_dependency 'simplecov-lcov', '~> 0.8.0'
 
-  # Solargraph temporarily dropped support for Convention.global in
-  # 0.53 - this should be lifted after it returns:
-  #
-  # https://github.com/castwide/solargraph/pull/877
   spec.add_runtime_dependency 'solargraph', *solargraph_version
 
   spec.add_runtime_dependency 'activesupport'