sorbet-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 319136a77de53915ea8e2999617f3942dc9913dd
-  data.tar.gz: e3cd87219252f35701df8647edcf752244bf0534
+SHA256:
+  metadata.gz: cdf5c9e5cc4d021af0e9206c53d9682288bb204f85179bffc2f041b2b783f8c8
+  data.tar.gz: 72de625982952376be79c47926266d7d25767b3b015b463c9302e75421643278
 SHA512:
-  metadata.gz: fbd53d9c25ae7d561d1a817f07c042fc7f014a3765726dfdefc7d2ab528a0321463d3f2511bbcdf1dcc4a9a6d10b973eaf4f0497f2b59b3edd6fe947f0ca178e
-  data.tar.gz: b5e9cdb6b32400026629532bdb75da9aee0518432dac9608ac68b7587ec8d04c602a0aa2983ff9ff905f8220fe2a89ad4ea5b479d302cfda2dd5349dbf74b892
+  metadata.gz: 3e59b36bf6be3ee5f8eb15db96a0b51a624557a4c1debebfeffe49b764b9670763e4437b6eba08137995126c07d150898f0cdceaa486b103f265929917a514ad
+  data.tar.gz: 5ae9763e3c5d1bafbfe6d847077abd8af4a7a80cabaa626ed723a66a036f8cc383dd26e242bffb055adedf40f5ee000d40394cadb405dd23c5dd1449748a722c

data/.gitignore

@@ -79,8 +79,20 @@ build-iPhoneSimulator/
 # Ignore sorbet-rails generated files
 /spec/support/**/sorbet/rails-rbi/*
 /spec/support/**/sorbet/rails-rbi/**/*
+# Ignore hidden-definition.rbi because we will rerun it
+/spec/support/**/sorbet/rbi/hidden-definitions/*
+/spec/support/**/sorbet/rbi/hidden-definitions/**/*
 
 # Ignore sorbet files in v5.2-no-sorbet
-/spec/support/v5.2-no-sorbet/sorbet_test_cases.rb
 /spec/support/v5.2-no-sorbet/sorbet/*
 /spec/support/v5.2-no-sorbet/sorbet/**/*
+
+# editor swap files
+*.swp
+*.swo
+*.swn
+*.swm
+*.swl
+*.swk
+
+lib/sorbet/rbi/hidden-definitions/errors.txt

data/.travis.yml

@@ -17,7 +17,7 @@ rvm:
 matrix:
   include:
   - rvm: 2.5
-    env: RAILS_VERSION=5.2 SORBET_VERSION=0.4.4386
+    env: RAILS_VERSION=5.2 SORBET_VERSION=0.4.4602
   - rvm: 2.5
     env: TEST_SRB_INIT=true
   exclude:
@@ -27,12 +27,12 @@ matrix:
     env: RAILS_VERSION=6.0
   allow_failures:
   - rvm: ruby-head
-  - env: RAILS_VERSION=5.2
 before_install:
 - gem install bundler -v 2.0.1 --no-doc
 - gem install bundler -v 1.17.3 --no-doc
 install: "./spec/bin/install.sh"
 script:
+- (cd lib && bundle exec srb tc)
 - "./spec/bin/run_spec.sh"
 deploy:
   provider: rubygems

data/Gemfile

@@ -48,4 +48,4 @@ else
   # prefer to test against latest version because sorbet is updated frequently
   gem 'sorbet'
   gem 'sorbet-runtime'
-end
+end

data/README.md

@@ -25,17 +25,22 @@ gem 'sorbet-rails'
 ❯ bundle install
 ```
 
-3. Generate RBI files for your routes and models:
+3. Generate RBI files for your routes, models, and helpers:
 ```sh
 ❯ rake rails_rbi:routes
 ❯ rake rails_rbi:models
+❯ rake rails_rbi:helpers
+
+# or run them all at once
+❯ rake rails_rbi:all
 ```
 
-4. Automatically upgrade each file's typecheck level:
+4. Update hidden-definition files and automatically upgrade each file's typecheck level:
 ```sh
+❯ srb rbi hidden-definitions
 ❯ srb rbi suggest-typed
 ```
-Because we've generated RBI files for routes and models, a lot more files should be typecheckable now.
+Because we've generated RBI files for routes, models, and helpers, a lot more files should be typecheckable now. Many methods in `hidden.rbi` may be removed because they are now typed.
 
 ## RBI Files
 
@@ -66,6 +71,16 @@ The generation task currently creates the following signatures:
 - Named scopes
 - Model relation class
 
+It is possible to add custom RBI generation logic for your custom module or gems via the plugin system. Check out the [plugins section](#extending-model-generation-task-with-custom-plugins) below if you are interested.
+
+### Helpers
+
+This Rake task generates a `helpers.rbi` file that includes a basic module definition which includes the `Kernel` module, to allow for some basic Ruby methods to be used in helpers without Sorbet complaining.
+
+```sh
+❯ rake rails_rbi:helpers
+```
+
 ## Tips & Tricks
 
 ### Overriding generated signatures
@@ -154,6 +169,67 @@ with:
 Model.unscoped.scoping do … end
 ```
 
+## Extending Model Generation Task with Custom Plugins
+
+`sorbet-rails` support a customizable plugin system that you can use to generate additional RBI for each model. This will be useful to generate RBI for methods dynamically added by gems or private concerns. If you write plugins for public gems, please feel free to contribute it to this repo.
+
+### Defining a Custom `ModelPlugin` 
+
+A custom plugin should be a subclass of `SorbetRails::ModelPlugins::Base`. Each plugin would implement a `generate(root)` method that generate additional rbi for the model.
+
+At a high level, here is the structure of a plugin:
+```ruby
+# -- lib/my_custom_plugin.rb
+class MyCustomPlugin < SorbetRails::ModelPlugins::Base
+  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  def generate(root)
+    # TODO: implement the generation logic
+    # You can use @model_class and @available_classes here
+  end
+end
+```
+During the generation phase, the system will create a new instance of the plugin, with the `model_class` to be generated and a set of all `available_classes` (available models) detected in the Rails App.
+
+We use [Parlour gem](https://github.com/AaronC81/parlour) to generate the RBI for a model. Please check out [Parlour wiki](https://github.com/AaronC81/parlour/wiki/Using-and-creating-RBI-objects) for guide to add RBI, eg create a new module, class, or method in the generated file.
+
+At a high level, you'd usually want to create a model-scoped module for your methods, and include or extend it in the base model class. The generation logic usually looks like this:
+```ruby
+  def generate(root)
+    # Make sure this is only run for relevant class
+    return unless @model_class.include?(CustomModule)
+
+    custom_module_name = self.model_module_name("CustomModule")
+    custom_module_rbi = root.create_module(custom_module_name)
+
+    # here we re-create the model class!
+    model_class_rbi = root.create_class(self.model_class_name)
+    model_class_rbi.create_extend(custom_module_name)
+    
+    # then create custom methods, constants, etc. for this module.
+    custom_module_rbi.create_method(...)
+    
+    # this is allowed but not recommended, because it limit the ability to override the method.
+    model_class_rbi.create_method(...)
+  end
+```
+Notice that we re-create `model_class_rbi` here. Parlour's [ConflictResolver](https://github.com/AaronC81/parlour/wiki/Internals#overall-flow) will merge the classes or modules with the same name together to generate 1 beautiful RBI file. It'll also flag and skip if any method is created multiple times with conflict signatures. Check-out useful predefined module names & helper methods in [model_utils](https://github.com/chanzuckerberg/sorbet-rails/blob/master/lib/sorbet-rails/model_utils.rb).
+
+It is also allowed to put methods into a model class directly. However, it is not recommended because it'll be harder to override the method. `sorbet` will enforce that the overriding method match the signature generated. It also makes the generated RBI file less modularized.  
+
+However, sometimes this is required to make `sorbet` recognize the signature. This is the case for class methods added by `ActiveRecord::Concerns`. Because `ActiveSupport::Concern` class methods will be inserted to the class directly, you need to also put the sig in the model class rbi directly.
+
+It is also recommended to check if the generated methods are detected by `sorbet` as a gem method (in `sorbet/rbi/gem/gem_name.rbi`) or hidden methods (in `sorbet/rbi/hidden-definitions/hidden.rbi`). If so, you may need to re-run `srb rbi hidden-definition` or put method in the model class directly.
+
+Check out the [plugins](https://github.com/chanzuckerberg/sorbet-rails/tree/master/lib/sorbet-rails/model_plugins) written for `sorbet-rails`'s own model RBI generation logic for examples.
+
+### Registering new plugins
+You can register your plugins in an initializer:
+```
+# -- config/initializers/sorbet_rails.rb
+SorbetRails::ModelRbiFormatter.register_plugin(MyCustomPlugin)
+```
+The default plugins and other customizations are defined [here](https://github.com/chanzuckerberg/sorbet-rails/blob/master/lib/sorbet-rails/model_plugins/plugins.rb).
+
 ## Contributing
 
 Contributions and ideas are welcome! Please see [our contributing guide](CONTRIBUTING.md) and don't hesitate to open an issue or send a pull request to improve the functionality of this gem.

data/lib/sorbet-rails.rb

@@ -1,3 +1,7 @@
+# typed: strong
 module SorbetRails
-  require 'sorbet-rails/railtie' if defined?(Rails)
+  if defined?(Rails)
+    require 'sorbet-rails/railtie'
+    require 'sorbet-rails/model_rbi_formatter'
+  end
 end

data/lib/sorbet-rails/activerecord.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+class ActiveRecord::Base < Object
+  extend T::Sig
+
+  sig { returns(T::Boolean) }
+  def self.table_exists?; end
+
+  sig { returns(T::Hash[String, T::Hash[String, T.untyped]]) }
+  def self.defined_enums; end
+
+  sig { returns(T::Hash[String, T.untyped]) }
+  def self.columns_hash; end
+
+  sig { returns(T::Hash[String, T.untyped]) }
+  def self.reflections; end
+
+  sig { returns(T.untyped) }
+  def self.connection; end
+
+  sig { returns(T::Boolean) }
+  def self.abstract_class?; end
+end
+
+class ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter;
+  def klass; end
+end

data/lib/sorbet-rails/custom_finder_methods.rb

@@ -1,3 +1,4 @@
+# typed: false
 module SorbetRails
   module CustomFinderMethods
     def find_n(*ids)
@@ -11,5 +12,15 @@ module SorbetRails
     def last_n(n)
       last(n)
     end
+
+    # Redeclare these dynamic methods here otherwise they will be generated by
+    # `srb rbi hidden-definitions`
+    def find_by_id(id)
+      find_by(id: id)
+    end
+
+    def find_by_id!(id)
+      find_by!(id: id)
+    end
   end
 end

data/lib/sorbet-rails/helper_rbi_formatter.rb

@@ -0,0 +1,33 @@
+# typed: strict
+require 'parlour'
+class SorbetRails::HelperRbiFormatter
+  extend T::Sig
+  # @param [Array<Module>] helpers
+  # @return [void]
+  sig { params(helpers: T::Array[Module]).void }
+  def initialize(helpers)
+    @parlour = T.let(Parlour::RbiGenerator.new, Parlour::RbiGenerator)
+    @helpers = T.let(helpers, T::Array[Module])
+  end
+
+  # Generates RBI file's contents.
+  # @return [String]
+  sig {returns(String)}
+  def generate_rbi
+    puts "-- Generate sigs for helpers --"
+
+    @parlour.root.add_comments([
+      'This is an autogenerated file for Rails helpers.',
+      'Please rerun rake rails_rbi:helpers to regenerate.'
+    ])
+
+    @helpers.each do |helper|
+      @parlour.root.create_module(helper.to_s) do |mod|
+        mod.create_include('Kernel')
+        mod.create_include('ActionView::Helpers')
+      end
+    end
+
+    return @parlour.rbi
+  end
+end

data/lib/sorbet-rails/model_plugins/active_record_assoc.rb

@@ -0,0 +1,91 @@
+# typed: true
+require ('sorbet-rails/model_plugins/base')
+class SorbetRails::ModelPlugins::ActiveRecordAssoc < SorbetRails::ModelPlugins::Base
+  sig {params(model_class: T.class_of(ActiveRecord::Base), available_classes: T::Set[String]).void}
+  def initialize(model_class, available_classes)
+    super
+    @columns_hash = @model_class.table_exists? ? @model_class.columns_hash : {}
+  end
+
+  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  def generate(root)
+    return unless @model_class.reflections.length > 0
+
+    assoc_module_name = self.model_module_name("GeneratedAssociationMethods")
+    assoc_module_rbi = root.create_module(assoc_module_name)
+    assoc_module_rbi.create_extend("T::Sig")
+
+    model_class_rbi = root.create_class(self.model_class_name)
+    model_class_rbi.create_include(assoc_module_name)
+
+    @model_class.reflections.sort.each do |assoc_name, reflection|
+      reflection.collection? ?
+        populate_collection_assoc_getter_setter(assoc_module_rbi, assoc_name, reflection) :
+        populate_single_assoc_getter_setter(assoc_module_rbi, assoc_name, reflection)
+    end
+  end
+
+  def populate_single_assoc_getter_setter(assoc_module_rbi, assoc_name, reflection)
+    # TODO allow people to specify the possible values of polymorphic associations
+    assoc_class = assoc_should_be_untyped?(reflection) ? "T.untyped" : "::#{reflection.klass.name}"
+    assoc_type = "T.nilable(#{assoc_class})"
+    if reflection.belongs_to?
+      # if this is a belongs_to connection, we may be able to detect whether
+      # this field is required & use a stronger type
+      column_def = @columns_hash[reflection.foreign_key.to_s]
+      if column_def
+        assoc_type = assoc_class if !column_def.null
+      end
+    end
+
+    assoc_module_rbi.create_method(
+      assoc_name.to_s,
+      return_type: assoc_type,
+    )
+    assoc_module_rbi.create_method(
+      "#{assoc_name}=",
+      parameters: [
+        Parameter.new("value", type: assoc_type)
+      ],
+      return_type: nil,
+    )
+  end
+
+  def populate_collection_assoc_getter_setter(assoc_module_rbi, assoc_name, reflection)
+    # TODO allow people to specify the possible values of polymorphic associations
+    assoc_class = assoc_should_be_untyped?(reflection) ? "T.untyped" : "::#{reflection.klass.name}"
+    relation_class = relation_should_be_untyped?(reflection) ?
+      "ActiveRecord::Associations::CollectionProxy" :
+      "#{assoc_class}::ActiveRecord_Associations_CollectionProxy"
+
+    assoc_module_rbi.create_method(
+      assoc_name.to_s,
+      return_type: relation_class,
+    )
+    assoc_module_rbi.create_method(
+      "#{assoc_name}=",
+      parameters: [
+        Parameter.new("value", type: "T.any(T::Array[#{assoc_class}], #{relation_class})")
+      ],
+      return_type: nil,
+    )
+  end
+
+  sig { params(reflection: T.untyped).returns(T.nilable(T::Boolean)) }
+  def assoc_should_be_untyped?(reflection)
+    polymorphic_assoc?(reflection) || !@available_classes.include?(reflection.klass.name)
+  end
+
+  sig { params(reflection: T.untyped).returns(T.nilable(T::Boolean)) }
+  def relation_should_be_untyped?(reflection)
+    # only type the relation we'll generate
+    assoc_should_be_untyped?(reflection) || !@available_classes.include?(reflection.klass.name)
+  end
+
+  sig { params(reflection: T.untyped).returns(T.nilable(T::Boolean)) }
+  def polymorphic_assoc?(reflection)
+    reflection.through_reflection ?
+      polymorphic_assoc?(reflection.source_reflection) :
+      reflection.polymorphic?
+  end
+end

data/lib/sorbet-rails/model_plugins/active_record_attribute.rb

@@ -0,0 +1,111 @@
+# typed: strict
+require ('sorbet-rails/model_plugins/base')
+class SorbetRails::ModelPlugins::ActiveRecordAttribute < SorbetRails::ModelPlugins::Base
+
+  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  def generate(root)
+    columns_hash = @model_class.table_exists? ? @model_class.columns_hash : {}
+    return unless columns_hash.size > 0
+
+    attribute_module_name = self.model_module_name("GeneratedAttributeMethods")
+    attribute_module_rbi = root.create_module(attribute_module_name)
+    attribute_module_rbi.create_extend("T::Sig")
+
+    model_class_rbi = root.create_class(self.model_class_name)
+    model_class_rbi.create_include(attribute_module_name)
+
+    columns_hash.sort.each do |column_name, column_def|
+      if @model_class.defined_enums.has_key?(column_name)
+        # enum attribute is treated differently
+        assignable_type = "T.any(Integer, String, Symbol)"
+        assignable_type = "T.nilable(#{assignable_type})" if column_def.null
+        return_type = "String"
+        return_type = "T.nilable(#{return_type})" if column_def.null
+
+        attribute_module_rbi.create_method(
+          column_name.to_s,
+          return_type: return_type,
+        )
+        attribute_module_rbi.create_method(
+          "#{column_name}=",
+          parameters: [
+            Parameter.new("value", type: assignable_type)
+          ],
+          return_type: nil,
+        )
+      else
+        column_type = type_for_column_def(column_def)
+        attribute_module_rbi.create_method(
+          column_name.to_s,
+          return_type: column_type.to_s,
+        )
+        attribute_module_rbi.create_method(
+          "#{column_name}=",
+          parameters: [
+            Parameter.new("value", type: column_type.to_s)
+          ],
+          return_type: nil,
+        )
+      end
+
+      attribute_module_rbi.create_method(
+        "#{column_name}?",
+        return_type: "T::Boolean",
+      )
+    end
+  end
+
+  sig {params(column_def: T.untyped).returns(T.any(String, Class))}
+  def type_for_column_def(column_def)
+    cast_type = ActiveRecord::Base.connection.respond_to?(:lookup_cast_type_from_column) ?
+      ActiveRecord::Base.connection.lookup_cast_type_from_column(column_def) :
+      column_def.cast_type
+
+    strict_type = active_record_type_to_sorbet_type(cast_type)
+
+    if column_def.respond_to?(:array?) && column_def.array?
+      strict_type = "T::Array[#{strict_type}]"
+    end
+    column_def.null ? "T.nilable(#{strict_type})" : strict_type
+  end
+
+  sig {
+    params(
+      # in v4.2, datetime can be TimeZoneConverter
+      klass: T.any(Object, ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter)
+    ).
+    returns(T.any(String, Class))
+  }
+  def active_record_type_to_sorbet_type(klass)
+    case klass
+    when ActiveRecord::Type::Boolean
+      "T::Boolean"
+    when ActiveRecord::Type::DateTime
+      DateTime
+    when ActiveRecord::Type::Date
+      Date
+    when ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter
+      klass.klass
+    when ActiveRecord::Type::Decimal
+      BigDecimal
+    when ActiveRecord::Type::Float
+      Float
+    when ActiveRecord::Type::Time
+      Time
+    when ActiveRecord::Type::BigInteger, ActiveRecord::Type::Integer, ActiveRecord::Type::DecimalWithoutScale, ActiveRecord::Type::UnsignedInteger
+      Integer
+    when ActiveRecord::Type::Binary, ActiveRecord::Type::String, ActiveRecord::Type::Text
+      String
+    else
+      # Json type is only supported in Rails 5.2 and above
+      case
+      when Object.const_defined?('ActiveRecord::Type::Json') && klass.is_a?(ActiveRecord::Type::Json)
+        "T.any(T::Array[T.untyped], T::Boolean, Float, T::Hash[T.untyped, T.untyped], Integer, String)"
+      when Object.const_defined?('ActiveRecord::Enum::EnumType') && klass.is_a?(ActiveRecord::Enum::EnumType)
+        String
+      else
+        "T.untyped"
+      end
+    end
+  end
+end