tapioca 0.10.1 → 0.10.3

data/lib/tapioca/dsl/compilers/active_record_associations.rb

@@ -152,7 +152,7 @@ module Tapioca
             mod.create_method(
               "#{association_name}_attributes=",
               parameters: [create_param("attributes", type: "T.untyped")],
-              return_type: "T.untyped"
+              return_type: "T.untyped",
             )
           end
         end
@@ -180,7 +180,7 @@ module Tapioca
           params(
             klass: RBI::Scope,
             association_name: T.any(String, Symbol),
-            reflection: ReflectionType
+            reflection: ReflectionType,
           ).void
         end
         def populate_single_assoc_getter_setter(klass, association_name, reflection)
@@ -194,7 +194,7 @@ module Tapioca
           klass.create_method(
             "#{association_name}=",
             parameters: [create_param("value", type: association_type)],
-            return_type: "void"
+            return_type: "void",
           )
           klass.create_method(
             "reload_#{association_name}",
@@ -207,7 +207,7 @@ module Tapioca
                 create_rest_param("args", type: "T.untyped"),
                 create_block_param("blk", type: "T.untyped"),
               ],
-              return_type: association_class
+              return_type: association_class,
             )
             klass.create_method(
               "create_#{association_name}",
@@ -215,7 +215,7 @@ module Tapioca
                 create_rest_param("args", type: "T.untyped"),
                 create_block_param("blk", type: "T.untyped"),
               ],
-              return_type: association_class
+              return_type: association_class,
             )
             klass.create_method(
               "create_#{association_name}!",
@@ -223,7 +223,7 @@ module Tapioca
                 create_rest_param("args", type: "T.untyped"),
                 create_block_param("blk", type: "T.untyped"),
               ],
-              return_type: association_class
+              return_type: association_class,
             )
           end
         end
@@ -232,7 +232,7 @@ module Tapioca
           params(
             klass: RBI::Scope,
             association_name: T.any(String, Symbol),
-            reflection: ReflectionType
+            reflection: ReflectionType,
           ).void
         end
         def populate_collection_assoc_getter_setter(klass, association_name, reflection)
@@ -241,6 +241,7 @@ module Tapioca
 
           klass.create_method(
             association_name.to_s,
+            comments: association_comments(reflection),
             return_type: relation_class,
           )
           klass.create_method(
@@ -250,18 +251,18 @@ module Tapioca
           )
           klass.create_method(
             "#{association_name.to_s.singularize}_ids",
-            return_type: "T::Array[T.untyped]"
+            return_type: "T::Array[T.untyped]",
           )
           klass.create_method(
             "#{association_name.to_s.singularize}_ids=",
             parameters: [create_param("ids", type: "T::Array[T.untyped]")],
-            return_type: "T::Array[T.untyped]"
+            return_type: "T::Array[T.untyped]",
           )
         end
 
         sig do
           params(
-            reflection: ReflectionType
+            reflection: ReflectionType,
           ).returns(String)
         end
         def type_for(reflection)
@@ -274,7 +275,7 @@ module Tapioca
 
         sig do
           params(
-            reflection: ReflectionType
+            reflection: ReflectionType,
           ).void
         end
         def validate_reflection!(reflection)
@@ -320,9 +321,43 @@ module Tapioca
           end
         end
 
+        sig { params(reflection: ReflectionType).returns(T::Array[RBI::Comment]) }
+        def association_comments(reflection)
+          anchor_name = case reflection
+          when ActiveRecord::Reflection::HasOneReflection
+            "the-has-one-association"
+          when ActiveRecord::Reflection::HasManyReflection
+            "the-has-many-association"
+          when ActiveRecord::Reflection::HasAndBelongsToManyReflection
+            "the-has-and-belongs-to-many-association"
+          when ActiveRecord::Reflection::BelongsToReflection
+            "the-belongs-to-association"
+          when ActiveRecord::Reflection::ThroughReflection
+            delegate_reflection = reflection.send(:delegate_reflection)
+            declaration = declaration(delegate_reflection)
+            if T.must(declaration).match?("has_one")
+              "the-has-one-through-association"
+            else
+              "the-has-many-through-association"
+            end
+          end
+
+          if anchor_name
+            url = "https://guides.rubyonrails.org/association_basics.html##{anchor_name}"
+            association_name = anchor_name.sub(/^the-(.*)-association$/, '\1')
+            comment = <<~MSG
+              This method is created by ActiveRecord on the `#{reflection.active_record.name}` class because it declared `#{declaration(reflection)}`.
+              🔗 [Rails guide for `#{association_name.gsub("-", "_")}` association](#{url})
+            MSG
+            [RBI::Comment.new(comment)]
+          else
+            []
+          end
+        end
+
         sig do
           params(
-            reflection: ReflectionType
+            reflection: ReflectionType,
           ).returns(String)
         end
         def relation_type_for(reflection)
@@ -346,7 +381,7 @@ module Tapioca
 
         sig do
           params(
-            reflection: ReflectionType
+            reflection: ReflectionType,
           ).returns(T::Boolean)
         end
         def polymorphic_association?(reflection)

data/lib/tapioca/dsl/compilers/active_record_columns.rb

@@ -152,14 +152,14 @@ module Tapioca
             name: String,
             methods_to_add: T.nilable(T::Array[String]),
             return_type: String,
-            parameters: T::Array[[String, String]]
+            parameters: T::Array[[String, String]],
           ).void
         end
         def add_method(klass, name, methods_to_add, return_type: "void", parameters: [])
           klass.create_method(
             name,
             parameters: parameters.map { |param, type| create_param(param, type: type) },
-            return_type: return_type
+            return_type: return_type,
           ) if methods_to_add.nil? || methods_to_add.include?(name)
         end
 
@@ -168,7 +168,7 @@ module Tapioca
             klass: RBI::Scope,
             column_name: String,
             attribute_name: String,
-            methods_to_add: T.nilable(T::Array[String])
+            methods_to_add: T.nilable(T::Array[String]),
           ).void
         end
         def add_methods_for_attribute(klass, column_name, attribute_name = column_name, methods_to_add = nil)
@@ -180,7 +180,7 @@ module Tapioca
             klass,
             attribute_name.to_s,
             methods_to_add,
-            return_type: getter_type
+            return_type: getter_type,
           )
 
           # Added by ActiveRecord::AttributeMethods::Write
@@ -190,7 +190,7 @@ module Tapioca
             "#{attribute_name}=",
             methods_to_add,
             parameters: [["value", setter_type]],
-            return_type: setter_type
+            return_type: setter_type,
           )
 
           # Added by ActiveRecord::AttributeMethods::Query
@@ -199,7 +199,7 @@ module Tapioca
             klass,
             "#{attribute_name}?",
             methods_to_add,
-            return_type: "T::Boolean"
+            return_type: "T::Boolean",
           )
 
           # Added by ActiveRecord::AttributeMethods::Dirty
@@ -208,37 +208,37 @@ module Tapioca
             klass,
             "#{attribute_name}_before_last_save",
             methods_to_add,
-            return_type: as_nilable_type(getter_type)
+            return_type: as_nilable_type(getter_type),
           )
           add_method(
             klass,
             "#{attribute_name}_change_to_be_saved",
             methods_to_add,
-            return_type: "T.nilable([#{getter_type}, #{getter_type}])"
+            return_type: "T.nilable([#{getter_type}, #{getter_type}])",
           )
           add_method(
             klass,
             "#{attribute_name}_in_database",
             methods_to_add,
-            return_type: as_nilable_type(getter_type)
+            return_type: as_nilable_type(getter_type),
           )
           add_method(
             klass,
             "saved_change_to_#{attribute_name}",
             methods_to_add,
-            return_type: "T.nilable([#{getter_type}, #{getter_type}])"
+            return_type: "T.nilable([#{getter_type}, #{getter_type}])",
           )
           add_method(
             klass,
             "saved_change_to_#{attribute_name}?",
             methods_to_add,
-            return_type: "T::Boolean"
+            return_type: "T::Boolean",
           )
           add_method(
             klass,
             "will_save_change_to_#{attribute_name}?",
             methods_to_add,
-            return_type: "T::Boolean"
+            return_type: "T::Boolean",
           )
 
           # Added by ActiveModel::Dirty
@@ -247,47 +247,47 @@ module Tapioca
             klass,
             "#{attribute_name}_change",
             methods_to_add,
-            return_type: "T.nilable([#{getter_type}, #{getter_type}])"
+            return_type: "T.nilable([#{getter_type}, #{getter_type}])",
           )
           add_method(
             klass,
             "#{attribute_name}_changed?",
             methods_to_add,
-            return_type: "T::Boolean"
+            return_type: "T::Boolean",
           )
           add_method(
             klass,
             "#{attribute_name}_will_change!",
-            methods_to_add
+            methods_to_add,
           )
           add_method(
             klass,
             "#{attribute_name}_was",
             methods_to_add,
-            return_type: as_nilable_type(getter_type)
+            return_type: as_nilable_type(getter_type),
           )
           add_method(
             klass,
             "#{attribute_name}_previous_change",
             methods_to_add,
-            return_type: "T.nilable([#{getter_type}, #{getter_type}])"
+            return_type: "T.nilable([#{getter_type}, #{getter_type}])",
           )
           add_method(
             klass,
             "#{attribute_name}_previously_changed?",
             methods_to_add,
-            return_type: "T::Boolean"
+            return_type: "T::Boolean",
           )
           add_method(
             klass,
             "#{attribute_name}_previously_was",
             methods_to_add,
-            return_type: as_nilable_type(getter_type)
+            return_type: as_nilable_type(getter_type),
           )
           add_method(
             klass,
             "restore_#{attribute_name}!",
-            methods_to_add
+            methods_to_add,
           )
 
           # Added by ActiveRecord::AttributeMethods::BeforeTypeCast
@@ -296,13 +296,13 @@ module Tapioca
             klass,
             "#{attribute_name}_before_type_cast",
             methods_to_add,
-            return_type: "T.untyped"
+            return_type: "T.untyped",
           )
           add_method(
             klass,
             "#{attribute_name}_came_from_user?",
             methods_to_add,
-            return_type: "T::Boolean"
+            return_type: "T::Boolean",
           )
         end
       end

data/lib/tapioca/dsl/compilers/active_record_fixtures.rb

@@ -100,7 +100,7 @@ module Tapioca
           mod.create_method(
             name,
             parameters: [create_rest_param("fixture_names", type: "T.any(String, Symbol)")],
-            return_type: "T.untyped"
+            return_type: "T.untyped",
           )
         end
       end

data/lib/tapioca/dsl/compilers/active_record_relations.rb

@@ -62,6 +62,16 @@ module Tapioca
       # `Model::PrivateRelation` modules, so that, for example, `find_by` and `all` can be chained off of the
       # `Model` class.
       #
+      # **A note on find**: `find` is typed as `T.untyped` by default.
+      #
+      # While it is often used in the manner of `Model.find(id)`, Rails does support pasing in an array to find, which
+      # would then return a `T::Enumerable[Model]`. This would force a static cast everywhere find is used to avoid type
+      # errors. This is not ideal considering very few users of find use the array syntax over a where. With untyped,
+      # this cast is optional and so it was decided to avoid typing it. If you need runtime guarentees when using `find`
+      # the best method of doing so is by casting the return value to the model: `T.cast(Model.find(id), Model)`.
+      # `find_by` does guarentee a return value of `Model`, so find can can be refactored accordingly:
+      # `Model.find_by!(id: id)`. This will avoid the cast requirement at runtime.
+      #
       # **CAUTION**: The generated relation classes are named `PrivateXXX` intentionally to reflect the fact
       # that they represent private subconstants of the Active Record model. As such, these types do not
       # exist at runtime, and their counterparts that do exist at runtime are marked `private_constant` anyway.
@@ -178,12 +188,12 @@ module Tapioca
         ASSOCIATION_METHODS = T.let(
           ::ActiveRecord::AssociationRelation.instance_methods -
             ::ActiveRecord::Relation.instance_methods,
-          T::Array[Symbol]
+          T::Array[Symbol],
         )
         COLLECTION_PROXY_METHODS = T.let(
           ::ActiveRecord::Associations::CollectionProxy.instance_methods -
             ::ActiveRecord::AssociationRelation.instance_methods,
-          T::Array[Symbol]
+          T::Array[Symbol],
         )
 
         QUERY_METHODS = T.let(begin
@@ -204,14 +214,14 @@ module Tapioca
         end, T::Array[Symbol])
         WHERE_CHAIN_QUERY_METHODS = T.let(
           ActiveRecord::QueryMethods::WhereChain.instance_methods(false),
-          T::Array[Symbol]
+          T::Array[Symbol],
         )
         FINDER_METHODS = T.let(ActiveRecord::FinderMethods.instance_methods(false), T::Array[Symbol])
         CALCULATION_METHODS = T.let(ActiveRecord::Calculations.instance_methods(false), T::Array[Symbol])
         ENUMERABLE_QUERY_METHODS = T.let([:any?, :many?, :none?, :one?], T::Array[Symbol])
         FIND_OR_CREATE_METHODS = T.let(
           [:find_or_create_by, :find_or_create_by!, :find_or_initialize_by, :create_or_find_by, :create_or_find_by!],
-          T::Array[Symbol]
+          T::Array[Symbol],
         )
         BUILDER_METHODS = T.let([:new, :build, :create, :create!], T::Array[Symbol])
 
@@ -233,15 +243,9 @@ module Tapioca
           # The model always extends the generated relation module
           model.create_extend(RelationMethodsModuleName)
 
-          # This feature is only available in versions of Sorbet with special support for
-          # handling `NilClass` returns from `to_ary`. We should not be typing `to_ary` like
-          # this for older versions since it will make all flatten operations be
-          # `T::Array[NilClass]`, otherwise.
-          if sorbet_supports?(:to_ary_nil_support)
-            # Type the `to_ary` method as returning `NilClass` so that flatten stops recursing
-            # See https://github.com/sorbet/sorbet/pull/4706 for details
-            model.create_method("to_ary", return_type: "NilClass", visibility: RBI::Private.new)
-          end
+          # Type the `to_ary` method as returning `NilClass` so that flatten stops recursing
+          # See https://github.com/sorbet/sorbet/pull/4706 for details
+          model.create_method("to_ary", return_type: "NilClass", visibility: RBI::Private.new)
 
           create_relation_class(model)
           create_association_relation_class(model)
@@ -292,7 +296,7 @@ module Tapioca
         def create_association_relation_where_chain_class(model)
           model.create_class(
             AssociationRelationWhereChainClassName,
-            superclass_name: AssociationRelationClassName
+            superclass_name: AssociationRelationClassName,
           ) do |klass|
             create_where_chain_methods(klass, AssociationRelationClassName)
             klass.create_type_variable("Elem", type: "type_member", fixed: constant_name)
@@ -310,7 +314,7 @@ module Tapioca
                   create_param("opts", type: "T.untyped"),
                   create_rest_param("rest", type: "T.untyped"),
                 ],
-                return_type: return_type
+                return_type: return_type,
               )
             when :associated, :missing
               klass.create_method(
@@ -318,7 +322,7 @@ module Tapioca
                 parameters: [
                   create_rest_param("args", type: "T.untyped"),
                 ],
-                return_type: return_type
+                return_type: return_type,
               )
             end
           end
@@ -374,12 +378,12 @@ module Tapioca
                 parameters: [
                   create_rest_param("records", type: model_collection),
                 ],
-                return_type: AssociationsCollectionProxyClassName
+                return_type: AssociationsCollectionProxyClassName,
               )
             when :clear
               klass.create_method(
                 method_name.to_s,
-                return_type: AssociationsCollectionProxyClassName
+                return_type: AssociationsCollectionProxyClassName,
               )
             when :delete, :destroy
               klass.create_method(
@@ -387,12 +391,12 @@ module Tapioca
                 parameters: [
                   create_rest_param("records", type: model_or_id_collection),
                 ],
-                return_type: "T::Array[#{constant_name}]"
+                return_type: "T::Array[#{constant_name}]",
               )
             when :load_target
               klass.create_method(
                 method_name.to_s,
-                return_type: "T::Array[#{constant_name}]"
+                return_type: "T::Array[#{constant_name}]",
               )
             when :replace
               klass.create_method(
@@ -400,19 +404,19 @@ module Tapioca
                 parameters: [
                   create_param("other_array", type: model_collection),
                 ],
-                return_type: "T::Array[#{constant_name}]"
+                return_type: "T::Array[#{constant_name}]",
               )
             when :reset_scope
               # skip
             when :scope
               klass.create_method(
                 method_name.to_s,
-                return_type: AssociationRelationClassName
+                return_type: AssociationRelationClassName,
               )
             when :target
               klass.create_method(
                 method_name.to_s,
-                return_type: "T::Array[#{constant_name}]"
+                return_type: "T::Array[#{constant_name}]",
               )
             end
           end
@@ -441,7 +445,7 @@ module Tapioca
               parameters: [
                 create_rest_param("args", type: "T.untyped"),
                 create_block_param("blk", type: "T.untyped"),
-              ]
+              ],
             )
           end
         end
@@ -467,7 +471,7 @@ module Tapioca
               association_relation_methods_module.create_method(
                 method_name.to_s,
                 parameters: parameters,
-                return_type: "ActiveRecord::Result"
+                return_type: "ActiveRecord::Result",
               )
             when :insert, :insert!, :upsert
               parameters = [
@@ -483,7 +487,7 @@ module Tapioca
               association_relation_methods_module.create_method(
                 method_name.to_s,
                 parameters: parameters,
-                return_type: "ActiveRecord::Result"
+                return_type: "ActiveRecord::Result",
               )
             when :proxy_association
               # skip - private method
@@ -496,7 +500,7 @@ module Tapioca
           create_common_method(
             "destroy_all",
             common_relation_methods_module,
-            return_type: "T::Array[#{constant_name}]"
+            return_type: "T::Array[#{constant_name}]",
           )
 
           FINDER_METHODS.each do |method_name|
@@ -508,7 +512,7 @@ module Tapioca
                 parameters: [
                   create_opt_param("conditions", type: "T.untyped", default: ":none"),
                 ],
-                return_type: "T::Boolean"
+                return_type: "T::Boolean",
               )
             when :include?, :member?
               create_common_method(
@@ -517,7 +521,7 @@ module Tapioca
                 parameters: [
                   create_param("record", type: "T.untyped"),
                 ],
-                return_type: "T::Boolean"
+                return_type: "T::Boolean",
               )
             when :find
               create_common_method(
@@ -526,7 +530,7 @@ module Tapioca
                 parameters: [
                   create_rest_param("args", type: "T.untyped"),
                 ],
-                return_type: "T.untyped"
+                return_type: "T.untyped",
               )
             when :find_by
               create_common_method(
@@ -535,7 +539,7 @@ module Tapioca
                 parameters: [
                   create_rest_param("args", type: "T.untyped"),
                 ],
-                return_type: as_nilable_type(constant_name)
+                return_type: as_nilable_type(constant_name),
               )
             when :find_by!
               create_common_method(
@@ -544,7 +548,7 @@ module Tapioca
                 parameters: [
                   create_rest_param("args", type: "T.untyped"),
                 ],
-                return_type: constant_name
+                return_type: constant_name,
               )
             when :find_sole_by
               create_common_method(
@@ -554,14 +558,14 @@ module Tapioca
                   create_param("arg", type: "T.untyped"),
                   create_rest_param("args", type: "T.untyped"),
                 ],
-                return_type: constant_name
+                return_type: constant_name,
               )
             when :sole
               create_common_method(
                 "sole",
                 common_relation_methods_module,
                 parameters: [],
-                return_type: constant_name
+                return_type: constant_name,
               )
             when :first, :last, :take
               create_common_method(
@@ -570,7 +574,7 @@ module Tapioca
                 parameters: [
                   create_opt_param("limit", type: "T.untyped", default: "nil"),
                 ],
-                return_type: "T.untyped"
+                return_type: "T.untyped",
               )
             when :raise_record_not_found_exception!
               # skip
@@ -584,7 +588,7 @@ module Tapioca
               create_common_method(
                 method_name,
                 common_relation_methods_module,
-                return_type: return_type
+                return_type: return_type,
               )
             end
           end
@@ -598,7 +602,7 @@ module Tapioca
                 parameters: [
                   create_param("column_name", type: "T.any(String, Symbol)"),
                 ],
-                return_type: "T.untyped"
+                return_type: "T.untyped",
               )
             when :calculate
               create_common_method(
@@ -608,7 +612,7 @@ module Tapioca
                   create_param("operation", type: "Symbol"),
                   create_param("column_name", type: "T.any(String, Symbol)"),
                 ],
-                return_type: "T.untyped"
+                return_type: "T.untyped",
               )
             when :count
               create_common_method(
@@ -617,7 +621,7 @@ module Tapioca
                 parameters: [
                   create_opt_param("column_name", type: "T.untyped", default: "nil"),
                 ],
-                return_type: "T.untyped"
+                return_type: "T.untyped",
               )
             when :ids
               create_common_method("ids", common_relation_methods_module, return_type: "Array")
@@ -628,7 +632,7 @@ module Tapioca
                 parameters: [
                   create_rest_param("column_names", type: "T.untyped"),
                 ],
-                return_type: "T.untyped"
+                return_type: "T.untyped",
               )
             when :sum
               create_common_method(
@@ -638,7 +642,7 @@ module Tapioca
                   create_opt_param("column_name", type: "T.nilable(T.any(String, Symbol))", default: "nil"),
                   create_block_param("block", type: "T.nilable(T.proc.params(record: T.untyped).returns(T.untyped))"),
                 ],
-                return_type: "T.untyped"
+                return_type: "T.untyped",
               )
             end
           end
@@ -651,7 +655,7 @@ module Tapioca
               parameters: [
                 create_block_param("block", type: block_type),
               ],
-              return_type: "T::Boolean"
+              return_type: "T::Boolean",
             )
           end
 
@@ -664,7 +668,7 @@ module Tapioca
                 create_param("attributes", type: "T.untyped"),
                 create_block_param("block", type: block_type),
               ],
-              return_type: constant_name
+              return_type: constant_name,
             )
           end
 
@@ -676,7 +680,7 @@ module Tapioca
                 create_opt_param("attributes", type: "T.untyped", default: "nil"),
                 create_block_param("block", type: "T.nilable(T.proc.params(object: #{constant_name}).void)"),
               ],
-              return_type: constant_name
+              return_type: constant_name,
             )
           end
         end
@@ -686,14 +690,14 @@ module Tapioca
             name: T.any(Symbol, String),
             common_relation_methods_module: RBI::Scope,
             parameters: T::Array[RBI::TypedParam],
-            return_type: T.nilable(String)
+            return_type: T.nilable(String),
           ).void
         end
         def create_common_method(name, common_relation_methods_module, parameters: [], return_type: nil)
           common_relation_methods_module.create_method(
             name.to_s,
             parameters: parameters,
-            return_type: return_type || "void"
+            return_type: return_type || "void",
           )
         end
 
@@ -718,12 +722,12 @@ module Tapioca
           relation_methods_module.create_method(
             name.to_s,
             parameters: parameters,
-            return_type: relation_return_type
+            return_type: relation_return_type,
           )
           association_relation_methods_module.create_method(
             name.to_s,
             parameters: parameters,
-            return_type: association_return_type
+            return_type: association_return_type,
           )
         end
       end