solargraph-rails 1.1.2 → 1.2.1

data/lib/solargraph/rails/annotations/active_job.rb

@@ -0,0 +1,276 @@
+module ActiveJob
+  module Callbacks
+    # These methods will be included into any Active Job object, adding
+    # callbacks for +perform+ and +enqueue+ methods.
+    module ClassMethods
+      # Defines a callback that will get called right before the
+      # job's perform method is executed.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     before_perform do |job|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def before_perform(*filters, &blk); end
+
+      # Defines a callback that will get called right after the
+      # job's perform method has finished.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     after_perform do |job|
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def after_perform(*filters, &blk); end
+
+      # Defines a callback that will get called around the job's perform method.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     around_perform do |job, block|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #       block.call
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      # You can access the return value of the job only if the execution wasn't halted.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     around_perform do |job, block|
+      #       value = block.call
+      #       puts value # => "Hello World!"
+      #     end
+      #
+      #     def perform
+      #       "Hello World!"
+      #     end
+      #   end
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def around_perform(*filters, &blk); end
+
+      # Defines a callback that will get called right before the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     before_enqueue do |job|
+      #       $statsd.increment "enqueue-video-job.try"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def before_enqueue(*filters, &blk); end
+
+      # Defines a callback that will get called right after the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     after_enqueue do |job|
+      #       $statsd.increment "enqueue-video-job.success"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def after_enqueue(*filters, &blk); end
+
+      # Defines a callback that will get called around the enqueuing
+      # of the job.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     around_enqueue do |job, block|
+      #       $statsd.time "video-job.process" do
+      #         block.call
+      #       end
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def around_enqueue(*filters, &blk); end
+    end
+  end
+
+  module Exceptions
+    module ClassMethods
+      # Catch the exception and reschedule job for re-execution after so many seconds, for a specific number of attempts.
+      # If the exception keeps getting raised beyond the specified number of attempts, the exception is allowed to
+      # bubble up to the underlying queuing system, which may have its own retry mechanism or place it in a
+      # holding queue for inspection.
+      #
+      # You can also pass a block that'll be invoked if the retry attempts fail for custom logic rather than letting
+      # the exception bubble up. This block is yielded with the job instance as the first and the error instance as the second parameter.
+      #
+      # ==== Options
+      # * <tt>:wait</tt> - Re-enqueues the job with a delay specified either in seconds (default: 3 seconds),
+      #   as a computing proc that takes the number of executions so far as an argument, or as a symbol reference of
+      #   <tt>:exponentially_longer</tt>, which applies the wait algorithm of <tt>((executions**4) + (Kernel.rand * (executions**4) * jitter)) + 2</tt>
+      #   (first wait ~3s, then ~18s, then ~83s, etc)
+      # * <tt>:attempts</tt> - Re-enqueues the job the specified number of times (default: 5 attempts) or a symbol reference of <tt>:unlimited</tt>
+      #   to retry the job until it succeeds
+      # * <tt>:queue</tt> - Re-enqueues the job on a different queue
+      # * <tt>:priority</tt> - Re-enqueues the job with a different priority
+      # * <tt>:jitter</tt> - A random delay of wait time used when calculating backoff. The default is 15% (0.15) which represents the upper bound of possible wait time (expressed as a percentage)
+      #
+      # ==== Examples
+      #
+      #  class RemoteServiceJob < ActiveJob::Base
+      #    retry_on CustomAppException # defaults to ~3s wait, 5 attempts
+      #    retry_on AnotherCustomAppException, wait: ->(executions) { executions * 2 }
+      #    retry_on CustomInfrastructureException, wait: 5.minutes, attempts: :unlimited
+      #
+      #    retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3
+      #    retry_on Net::OpenTimeout, Timeout::Error, wait: :exponentially_longer, attempts: 10 # retries at most 10 times for Net::OpenTimeout and Timeout::Error combined
+      #    # To retry at most 10 times for each individual exception:
+      #    # retry_on Net::OpenTimeout, wait: :exponentially_longer, attempts: 10
+      #    # retry_on Net::ReadTimeout, wait: 5.seconds, jitter: 0.30, attempts: 10
+      #    # retry_on Timeout::Error, wait: :exponentially_longer, attempts: 10
+      #
+      #    retry_on(YetAnotherCustomAppException) do |job, error|
+      #      ExceptionNotifier.caught(error)
+      #    end
+      #
+      #    def perform(*args)
+      #      # Might raise CustomAppException, AnotherCustomAppException, or YetAnotherCustomAppException for something domain specific
+      #      # Might raise ActiveRecord::Deadlocked when a local db deadlock is detected
+      #      # Might raise Net::OpenTimeout or Timeout::Error when the remote service is down
+      #    end
+      #  end
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def retry_on(*exceptions, wait: 3.seconds, attempts: 5, queue: nil, priority: nil, jitter: JITTER_DEFAULT); end
+
+      # Discard the job with no attempts to retry, if the exception is raised. This is useful when the subject of the job,
+      # like an Active Record, is no longer available, and the job is thus no longer relevant.
+      #
+      # You can also pass a block that'll be invoked. This block is yielded with the job instance as the first and the error instance as the second parameter.
+      #
+      # ==== Example
+      #
+      #  class SearchIndexingJob < ActiveJob::Base
+      #    discard_on ActiveJob::DeserializationError
+      #    discard_on(CustomAppException) do |job, error|
+      #      ExceptionNotifier.caught(error)
+      #    end
+      #
+      #    def perform(record)
+      #      # Will raise ActiveJob::DeserializationError if the record can't be deserialized
+      #      # Might raise CustomAppException for something domain specific
+      #    end
+      #  end
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      def discard_on(*exceptions); end
+    end
+  end
+
+  module QueueName
+    extend ActiveSupport::Concern
+
+    # Includes the ability to override the default queue name and prefix.
+    module ClassMethods
+      mattr_accessor :default_queue_name, default: "default"
+
+      # Specifies the name of the queue to process the job on.
+      #
+      #   class PublishToFeedJob < ActiveJob::Base
+      #     queue_as :feeds
+      #
+      #     def perform(post)
+      #       post.to_feed!
+      #     end
+      #   end
+      #
+      # Can be given a block that will evaluate in the context of the job
+      # so that a dynamic queue name can be applied:
+      #
+      #   class PublishToFeedJob < ApplicationJob
+      #     queue_as do
+      #       post = self.arguments.first
+      #
+      #       if post.paid?
+      #         :paid_feeds
+      #       else
+      #         :feeds
+      #       end
+      #     end
+      #
+      #     def perform(post)
+      #       post.to_feed!
+      #     end
+      #   end
+      #
+      # @return [void]
+      def queue_as(part_name = nil, &block); end
+    end
+  end
+
+  module QueuePriority
+    extend ActiveSupport::Concern
+
+    # Includes the ability to override the default queue priority.
+    module ClassMethods
+      # Specifies the priority of the queue to create the job with.
+      #
+      #   class PublishToFeedJob < ActiveJob::Base
+      #     queue_with_priority 50
+      #
+      #     def perform(post)
+      #       post.to_feed!
+      #     end
+      #   end
+      #
+      # Specify either an argument or a block.
+      #
+      # @return [void]
+      def queue_with_priority(priority = nil, &block); end
+    end
+  end
+end

data/lib/solargraph/rails/annotations/active_model.rb

@@ -0,0 +1,18 @@
+module ActiveModel
+  module Translation
+    # @param options [Hash] options to customize the output
+    # @param attribute [Symbol, String] the name of the attribute
+    # @return [String]
+    def human_attribute_name(attribute, options = {}); end
+  end
+
+  module Naming
+    # @return [ActiveModel::Name] the model name for the class
+    def model_name; end
+  end
+
+  module Validations
+    # @return [Boolean]
+    def validate; end
+  end
+end

data/lib/solargraph/rails/annotations/active_record.rb

@@ -1,10 +1,25 @@
+require 'active_record'
+
 class ActiveRecord::ConnectionAdapters::SchemaStatements
   # @yieldparam [ActiveRecord::ConnectionAdapters::TableDefinition]
-  def create_table; end
+  # @return [void]
+  def create_table(table_name, id: nil, primary_key: nil, force: false, **options); end
   # @yieldparam [ActiveRecord::ConnectionAdapters::TableDefinition]
-  def create_join_table; end
+  # @param table_1 [String, Symbol]
+  # @param table_2 [String, Symbol]
+  # @param column_options [Hash]
+  # @param options [Hash{Symbol => undefined}]
+  # @return [void]
+  def create_join_table(table_1, table_2, column_options: {}, **options); end
   # @yieldparam [ActiveRecord::ConnectionAdapters::Table]
-  def change_table; end
+  # @return [void]
+  def change_table(table_name, **options); end
+end
+
+module ActiveRecord::Core
+  # @param methods [Symbol]
+  # @return [ActiveSupport::HashWithIndifferentAccess<Symbol>]
+  def slice(*methods); end
 end
 
 # this module doesn't really exist, it's here to avoid repeating these mixins
@@ -33,6 +48,40 @@ class ActiveRecord::Base
   extend ActiveRecord::Scoping::Named::ClassMethods
   extend ActiveRecord::RelationMethods
   include ActiveRecord::Persistence
+  extend ActiveModel::AttributeRegistration::ClassMethods
+  # note: this supplies set_callback() - after Rails 7.1, this is no
+  #  longer used and is replaced entirely by ActiveRecord::Callbacks
+  #  below
+  include ActiveRecord::Callbacks
+  extend ActiveRecord::Callbacks::ClassMethods
+  extend ActiveRecord::Translation
+
+  # copied from .gem_rbs_collection/activestorage/7.0/lib/engine.rbs
+  # which for some reason does not get included
+  include ::ActiveStorage::Attached::Model
+  extend ::ActiveStorage::Attached::Model::ClassMethods
+  include ::ActiveStorage::Reflection::ActiveRecordExtensions
+
+  class << self
+    # included in ActiveRecordExtensions
+    # @return [Hash{String => ActiveStorage::Reflection::HasOneAttachedReflection, ActiveStorage::Reflection::HasManyAttachedReflection}]
+    attr_accessor :attachment_reflections
+  end
+
+  extend ::ActiveStorage::Reflection::ActiveRecordExtensions::ClassMethods
+
+  def self.set_callback; end
+
+  # @return [:activerecord]
+  def self.i18n_scope; end
+
+  # @return [self]
+  def reload(); end
+end
+
+module ActiveRecord::Validations
+  # @return [Boolean]
+  def validate(); end
 end
 
 # @!override ActiveRecord::Batches#find_each
@@ -52,3 +101,5 @@ end
 #   @return_single_parameter
 # @!override ActiveRecord::QueryMethods::WhereChain#associated
 #   @return_single_parameter
+# @!override ActiveRecord::ConnectionAdapters::SchemaStatements#create_table
+#   @yieldparam [ActiveRecord::ConnectionAdapters::TableDefinition]

data/lib/solargraph/rails/annotations/active_storage.rb

@@ -0,0 +1,113 @@
+module ActiveStorage
+  # Provides the class-level DSL for declaring an Active Record model's attachments.
+  module Attached
+    module Model
+      # NOTE: the below would normally be in a ClassMethods module -
+      #   but Solargraph currently uses yard-activesupport-concern,
+      #   which jams the method in as class methods under this module.
+      #
+      # Specifies the relation between a single attachment and the model.
+      #
+      #   class User < ApplicationRecord
+      #     has_one_attached :avatar
+      #   end
+      #
+      # There is no column defined on the model side, Active Storage takes
+      # care of the mapping between your records and the attachment.
+      #
+      # To avoid N+1 queries, you can include the attached blobs in your query like so:
+      #
+      #   User.with_attached_avatar
+      #
+      # Under the covers, this relationship is implemented as a +has_one+ association to a
+      # ActiveStorage::Attachment record and a +has_one-through+ association to a
+      # ActiveStorage::Blob record. These associations are available as +avatar_attachment+
+      # and +avatar_blob+. But you shouldn't need to work with these associations directly in
+      # most circumstances.
+      #
+      # The system has been designed to having you go through the ActiveStorage::Attached::One
+      # proxy that provides the dynamic proxy to the associations and factory methods, like +attach+.
+      #
+      # If the +:dependent+ option isn't set, the attachment will be purged
+      # (i.e. destroyed) whenever the record is destroyed.
+      #
+      # If you need the attachment to use a service which differs from the globally configured one,
+      # pass the +:service+ option. For instance:
+      #
+      #   class User < ActiveRecord::Base
+      #     has_one_attached :avatar, service: :s3
+      #   end
+      #
+      # If you need to enable +strict_loading+ to prevent lazy loading of attachment,
+      # pass the +:strict_loading+ option. You can do:
+      #
+      #   class User < ApplicationRecord
+      #     has_one_attached :avatar, strict_loading: true
+      #   end
+      #
+
+      # @param name [String, Symbol]
+      # @param dependent [Symbol] the action to take on the attachment when the record is destroyed
+      # @param strict_loading [Boolean]
+      # @param service [String, Symbol, nil] the service to use for the attachment
+      # @return [void]
+      def self.has_one_attached(name, dependent: :default, service: nil, strict_loading: false); end
+
+      # Specifies the relation between multiple attachments and the model.
+      #
+      #   class Gallery < ApplicationRecord
+      #     has_many_attached :photos
+      #   end
+      #
+      # There are no columns defined on the model side, Active Storage takes
+      # care of the mapping between your records and the attachments.
+      #
+      # To avoid N+1 queries, you can include the attached blobs in your query like so:
+      #
+      #   Gallery.where(user: Current.user).with_attached_photos
+      #
+      # Under the covers, this relationship is implemented as a +has_many+ association to a
+      # ActiveStorage::Attachment record and a +has_many-through+ association to a
+      # ActiveStorage::Blob record. These associations are available as +photos_attachments+
+      # and +photos_blobs+. But you shouldn't need to work with these associations directly in
+      # most circumstances.
+      #
+      # The system has been designed to having you go through the ActiveStorage::Attached::Many
+      # proxy that provides the dynamic proxy to the associations and factory methods, like +#attach+.
+      #
+      # If the +:dependent+ option isn't set, all the attachments will be purged
+      # (i.e. destroyed) whenever the record is destroyed.
+      #
+      # If you need the attachment to use a service which differs from the globally configured one,
+      # pass the +:service+ option. For instance:
+      #
+      #   class Gallery < ActiveRecord::Base
+      #     has_many_attached :photos, service: :s3
+      #   end
+      #
+      # If you need to enable +strict_loading+ to prevent lazy loading of attachments,
+      # pass the +:strict_loading+ option. You can do:
+      #
+      #   class Gallery < ApplicationRecord
+      #     has_many_attached :photos, strict_loading: true
+      #   end
+      #
+      # @param name [String, Symbol]
+      # @param dependent [Symbol] the action to take on the attachment when the record is destroyed
+      # @param strict_loading [Boolean]
+      # @param service [String, Symbol, nil] the service to use for the attachment
+      # @return [void]
+      def self.has_many_attached(name, dependent: :default, service: nil, strict_loading: false); end
+
+      # @return [void]
+      def self.attachment_changes(); end
+
+      # @return [Boolean]
+      def self.changed_for_autosave?; end
+
+      # @param lock [BasicObject]
+      # @return [self]
+      def self.reload(lock = false); end
+    end
+  end
+end

data/lib/solargraph/rails/annotations/active_support.rb

@@ -3,3 +3,6 @@
 
 # @!override ActiveSupport::DescendantsTracker#subclasses
 #   @return [Array<Class>]
+
+# @!override ActiveSupport::DescendantsTracker::ReloadedClassesFiltering#subclasses
+#   @return [Array<Class>]

data/lib/solargraph/rails/annotations/array.rb

@@ -0,0 +1,7 @@
+class Array
+  def sum; end
+
+  # @param format [Symbol]
+  # @return [String]
+  def to_formatted_s(format = :some_default); end
+end

data/lib/solargraph/rails/annotations/class.rb

@@ -0,0 +1,2 @@
+# @!override Class#subclasses
+#   @return [Array<Class>]

data/lib/solargraph/rails/annotations/date.rb

@@ -23,9 +23,17 @@ class Date
 
   # @return [::Time]
   def to_time; end
+
+  # @param format [Symbol]
+  # @return [String]
+  def to_formatted_s(format = :some_default); end
 end
 
 class DateTime
   # @return [String]
   def readable_inspect; end
+
+  # @param format [Symbol]
+  # @return [String]
+  def to_formatted_s(format = :some_default); end
 end

data/lib/solargraph/rails/annotations/module.rb

@@ -0,0 +1,13 @@
+class Module
+  # @return [self, nil]
+  def self.presence; end
+
+  # @return [self, nil]
+  def self.presence_in(x); end
+
+  # @return [self, nil]
+  def presence; end
+
+  # @return [self, nil]
+  def presence_in(x); end
+end

data/lib/solargraph/rails/annotations/object.rb

@@ -5,3 +5,6 @@ class Object
   # @return [self, nil]
   def presence_in(x); end
 end
+
+# @!override Object#present?
+#   @return [Boolean]

data/lib/solargraph/rails/annotations/rails.rb

@@ -11,4 +11,8 @@ end
 class Rails::Application
   # @return [ActionDispatch::Routing::RouteSet]
   def routes; end
+  # @return [Rails::Application::Configuration]
+  def config; end
+  # @return [Rails::Application::Configuration]
+  def self.config; end
 end

data/lib/solargraph/rails/annotations/time.rb

@@ -25,6 +25,10 @@ class Time
   # @return [Time]
   def to_time; end
 
-  # @return [Time]
-  def +(other); end
+  # @param format [Symbol]
+  # @return [String]
+  def to_formatted_s(format = :some_default); end
 end
+
+# @!override Time#+
+#   @return [Time]

data/lib/solargraph/rails/delegate.rb

@@ -1,3 +1,5 @@
+require 'parser'
+
 module Solargraph
   module Rails
     class Delegate
@@ -5,25 +7,57 @@ module Solargraph
         @instance ||= self.new
       end
 
+      def self.supported?
+        Solargraph::Pin.const_defined?(:DelegatedMethod)
+      end
+
       def process(source_map, ns)
+        return [] unless self.class.supported?
         return [] unless source_map.code.include?('delegate')
 
         walker = Walker.from_source(source_map.source)
         pins = []
 
         walker.on :send, [nil, :delegate] do |ast|
-          methods =
-            ast.children[2..-1]
-              .map { |c| c.children.first }
-              .select { |s| s.is_a?(Symbol) }
+          last_child = ast.children[-1]
+          next unless last_child.instance_of?(::Parser::AST::Node) && last_child.type == :hash
+
+          methods = ast.children[2...-1].select { |c| c.type == :sym }
+
+          delegate_node = Util.extract_option(ast, :to)
+          next unless delegate_node
+
+          chain = if delegate_node.type == :sym
+            # `delegate ..., to: :bar` means call the #bar method to get the delegate object
+            call = Solargraph::Source::Chain::Call.new(delegate_node.children[0].to_s)
+            Solargraph::Source::Chain.new([call], delegate_node)
+          else
+            # for any other type of delegate, we create a chain from the AST node
+            Solargraph::Parser::Legacy::NodeChainer.chain(delegate_node, ns.filename)
+          end
+
+          prefix_node = Util.extract_option(ast, :prefix)
+
+          prefix = nil
+          if prefix_node
+            if prefix_node.type == :sym
+              prefix = prefix_node.children[0]
+            elsif prefix_node.type == :true && delegate_node.type == :sym
+              prefix = delegate_node.children[0]
+            end
+          end
 
+          location = Util.build_location(delegate_node, ns.filename)
           methods.each do |meth|
-            pins <<
-              Util.build_public_method(
-                ns,
-                meth.to_s,
-                location: Util.build_location(ast, ns.filename)
-              )
+            method_name = meth.children[0]
+            pins << Solargraph::Pin::DelegatedMethod.new(
+              closure: ns,
+              scope: :instance,
+              name: [prefix, method_name].select(&:itself).join("_"),
+              node: meth,
+              receiver: chain,
+              receiver_method_name: method_name.to_s,
+            )
           end
         end