rails-on-sorbet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7a88d217e8a2bfe112e807a62dbef1b05bd767b5d5ddac6f243ab14998aa04a9
+  data.tar.gz: 2aa3723b81525f0edc65c484c5aa461a38d10345367a4ee61eecee6687f48716
+SHA512:
+  metadata.gz: a5b9053282ba1f6336c7720ad0678dd916db7a4da8200e3baf17194a6bd441129771603dbe834e126792ead836dcd299c706a3a5a56ad8d8d3a3f82223d2f6ce
+  data.tar.gz: 80613347aef5646f00f0fe5a7a3a2e67cc236278b8fe41a6418a1f86d26b9de89714f28d2a994680ba4a2beb14320c3bb45f32d0110148ecfb64ff66ee248ca9

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-09-17
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Espago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# Rails::On::Sorbet
+
+This gem is a Rails extension that enhances sorbet support in Rails.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add rails-on-sorbet
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install rails-on-sorbet
+```
+
+## Usage
+
+This gem adds additional signatures to Rails types and builtin Ruby types that
+make using sorbet easier in Rails projects.
+
+It also adds some new utility types and modifies certain Rails DSLs
+to make it possible to strictly type methods defined through metaprogramming.
+
+### Timelike
+
+Rails and Ruby lack a unified type for representing datetime.
+We have `Time`, `DateTime` and `ActiveSupport::TimeWithZone` which basically
+cover really similar use cases but have no common ancestor.
+This makes working with time incredibly frustrating.
+
+We introduced a new utility type called `Timelike` to alleviate this burden.
+
+Definition:
+```rb
+Timelike = T.type_alias { T.any(Time, DateTime, ActiveSupport::TimeWithZone) }
+```
+
+### Map
+
+Rails introduced two hashlike types: `ActionController::Parameters`, `ActiveSupport::HashWithIndifferentAccess`.
+For the most part they behave like `Hash` but they don't inherit from it.
+This causes a lot of issues in sorbet.
+
+Because of that we introduced the `Map` interface.
+It defines all methods that are common to `Hash`, `ActionController::Parameters` and `ActiveSupport::HashWithIndifferentAccess`.
+
+Right now there is a bug in sorbet that causes the typechecker to hang and crash when you include a generic interface/module in `Hash`, `Array`, `Set`, `Range` etc.
+So we couldn't implement `Map` directly in `Hash` :(
+
+Instead, we introduced a casting function.
+
+Example:
+```rb
+# Use the `Map` type in a signature
+#
+#: (Map[String, Integer]) -> void
+def foo(m)
+  m["foo"] #=> Integer?
+end
+
+hash = { "foo" => 4 } #: Hash[String, Integer]
+m = Map(hash) #=> Map[String, Integer]
+foo(m) # OK
+
+hash = { "foo" => 4 }.with_indifferent_access # => ActiveSupport::HashWithIndifferentAccess
+m = Map(hash) #=> Map[String, untyped]
+foo(m) # OK
+
+params = ActionController::Parameters.new # => ActionController::Parameters
+m = Map(params) #=> Map[String, untyped]
+foo(m) # OK
+```
+
+### ActiveRecord::Base::alias_association
+
+This gem adds a new method called `alias_association` on ActiveRecord classes.
+It lets you define aliases for getters and setters of `belongs_to` and `has_one` associations. There is also a tapioca compiler that makes sorbet aware of these aliases.
+
+Example:
+```rb
+  class Foo < ApplicationRecord
+    belongs_to :user
+    alias_association :owner, :user
+  end
+
+  f = Foo.last
+  f.owner == f.user #=> true
+```
+
+### ActiveSupport::CurrentAttributes
+
+New optional keyword arguments have been added to `ActiveSupport::CurrentAttributes::attribute`:
+- `type`: the sorbet type of the getter/setter
+- `doc`: a docstring whose content will be used to generate a comment above the rbi signature created by tapioca
+
+Example:
+```rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session_counter, type: T.nilable(Integer), doc: <<~DOC
+    A counter that gets incremented when a new session is created.
+  DOC
+end
+```
+
+The tapioca compiler will generate an RBI file like this:
+
+```rb
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for dynamic methods in `Current`.
+# Please instead update this file by running `bin/tapioca dsl Current`.
+
+class Current
+  include RailsOnSorbetCurrentAttributeMethods
+  extend RailsOnSorbetCurrentAttributeMethods
+
+  module RailsOnSorbetCurrentAttributeMethods
+    # A counter that gets incremented when a new session is created.
+    sig { returns(T.nilable(::Integer)) }
+    def session_counter; end
+
+    # A counter that gets incremented when a new session is created.
+    sig { params(value: T.nilable(::Integer)).returns(T.nilable(::Integer)) }
+    def session_counter=(value); end
+  end
+end
+```
+
+### ActiveRecord::Base::serialize
+
+Tapioca now has the ability to generate strictly typed and accurate getters and setters for Rails serializers.
+
+New optional keyword arguments have been added to `ActiveRecord::Base::serialize`:
+- `return_type`: the sorbet type returned by the getter
+- `setter_type`: the sorbet type of the parameter of the setter
+- `doc`: a docstring whose content will be used to generate a comment above the rbi signature created by tapioca
+
+If no `return_type` or `setter_type` is given in the arguments, tapioca will try to call `return_type` and `setter_type` on the `coder` given to the serializer.
+
+Example:
+```rb
+module IntegerCoder
+  class << self
+    def return_type = Integer
+
+    #: (String?) -> Integer?
+    def load(val)
+      val&.to_i
+    end
+
+    #: (Integer?) -> String?
+    def dump(val)
+      val&.to_s
+    end
+  end
+end
+
+class Foo < ActiveRecord::Base
+  serialize :bar, coder: IntegerCoder
+  serialize :baz, coder: YAML, return_type: T::Hash[String, String], doc: <<~DOC
+    Additional BAR data for finalizing orders.
+  DOC
+end
+```
+
+The tapioca compiler will generate the following RBI file
+
+```rb
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for dynamic methods in `Foo`.
+# Please instead update this file by running `bin/tapioca dsl Foo`.
+
+class Foo
+  sig { returns(T.nilable(Integer)) }
+  def bar; end
+
+  sig { params(value: T.nilable(Integer)).returns(T.nilable(Integer)) }
+  def bar=(value); end
+
+  # Additional BAR data for finalizing orders.
+  sig { returns(T.nilable(T::Hash[::String, ::String])) }
+  def baz; end
+
+  # Additional BAR data for finalizing orders.
+  sig { params(value: T.nilable(T::Hash[::String, ::String])).returns(T.nilable(T::Hash[::String, ::String])) }
+  def baz=(value); end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/espago/rails-on-sorbet.

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+::Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = ::FileList['test/**/*_test.rb']
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test]

data/lib/rails/on/sorbet/active_record_serializer.rb

@@ -0,0 +1,77 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rails::On::Sorbet
+  # @requires_ancestor: singleton(ActiveRecord::Base)
+  module ActiveRecordSerializer
+    # Contains the data of a serializer definition
+    class Definition
+      #: Symbol
+      attr_reader :name
+      #: untyped
+      attr_reader :coder
+      #: Object
+      attr_reader :return_type
+      #: Object
+      attr_reader :setter_type
+      #: String?
+      attr_reader :doc
+
+      #: (name: Symbol, coder: untyped, ?return_type: untyped, ?setter_type: untyped, ?doc: String?) -> void
+      def initialize(name:, coder:, return_type: nil, setter_type: nil, doc: nil)
+        @name = name
+        @coder = coder
+        @return_type = return_type
+        @setter_type = setter_type
+        @doc = doc
+      end
+    end
+
+    #: (
+    #|  Symbol,
+    #|  ?coder: untyped,
+    #|  ?type: untyped,
+    #|  ?yaml: Hash[Symbol, untyped],
+    #|  ?return_type: untyped,
+    #|  ?setter_type: untyped,
+    #|  ?doc: String?,
+    #|  **untyped
+    #| ) ?{ -> void } -> void
+    def serialize(
+      attr_name,
+      coder: nil,
+      type: Object,
+      yaml: {},
+      return_type: nil,
+      setter_type: nil,
+      doc: nil,
+      **kwargs,
+      &block
+    )
+      super(attr_name, coder: coder, type: type, yaml: yaml, **kwargs, &block)
+
+      _sorbet_serializer_definitions[attr_name] = Definition.new(
+        name:        attr_name,
+        coder:       coder,
+        return_type: return_type,
+        setter_type: setter_type,
+        doc:         doc,
+      )
+    end
+
+    #: -> Hash[Symbol, Definition]
+    def _sorbet_serializer_definitions
+      @_sorbet_serializer_definitions ||= {}
+    end
+  end
+
+end
+
+require 'active_record'
+require 'active_record/base'
+
+module ActiveRecord
+  class Base # rubocop:disable Style/StaticClass
+    extend Rails::On::Sorbet::ActiveRecordSerializer
+  end
+end

data/lib/rails/on/sorbet/alias_association.rb

@@ -0,0 +1,46 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rails::On::Sorbet
+  # @requires_ancestor: singleton(ActiveRecord::Base)
+  module AliasAssociation
+    # Create an alias for an association like `belongs_to` or `has_one`
+    #
+    #     class Foo < ApplicationRecord
+    #       belongs_to :user
+    #       alias_association :owner, :user
+    #     end
+    #     f = Foo.last
+    #     f.owner == f.user #=> true
+    #
+    #: (Symbol, Symbol) -> void
+    def alias_association(alias_name, target_name)
+      @_alias_association_definitions ||= []
+      @_alias_association_definitions << [alias_name, target_name]
+
+      class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def #{alias_name}             # def service
+          self.#{target_name}         #   self.merchant_service
+        end                           # end
+
+        def #{alias_name}=(val)       # def service=(val)
+          self.#{target_name} = val   #   self.merchant_service = val
+        end                           # end
+      RUBY
+    end
+
+    #: -> Array[[Symbol, Symbol]]
+    def _alias_association_definitions
+      @_alias_association_definitions || []
+    end
+  end
+end
+
+require 'active_record'
+require 'active_record/base'
+
+module ActiveRecord
+  class Base # rubocop:disable Style/StaticClass
+    extend Rails::On::Sorbet::AliasAssociation
+  end
+end

data/lib/rails/on/sorbet/current_attributes.rb

@@ -0,0 +1,53 @@
+# typed: false
+# frozen_string_literal: true
+
+module Rails::On::Sorbet
+  # Shim for ActiveSupport::CurrentAttributes to support sorbet
+  #
+  # @requires_ancestor: singleton(ActiveSupport::CurrentAttributes)
+  module CurrentAttributes
+    # Holds the data of a single attribute definition
+    class Attribute
+      #: Symbol
+      attr_accessor :name
+
+      #: Object
+      attr_accessor :type
+
+      #: String?
+      attr_accessor :doc
+
+      #: (Symbol name, Object type, String? doc) -> void
+      def initialize(name, type, doc)
+        @name = name
+        @type = type
+        @doc = doc
+      end
+    end
+
+    # Get a map with all defined attributes and their types
+    #
+    #: -> Hash[Symbol, Attribute]
+    def attribute_map
+      @attribute_map ||= {}
+    end
+
+    # Declare a new attribute with a sorbet type
+    #
+    #: (*Symbol, ?type: untyped, ?doc: String?, ?default: untyped) -> void
+    def attribute(*names, type: nil, doc: nil, default: ::ActiveSupport::CurrentAttributes::NOT_SET)
+      names.each do |name|
+        attribute_map[name] = Attribute.new(name, type, doc)
+      end
+      super(*names, default: default)
+    end
+  end
+end
+
+require 'active_support'
+
+module ActiveSupport
+  class CurrentAttributes # rubocop:disable Style/StaticClass
+    extend Rails::On::Sorbet::CurrentAttributes
+  end
+end

data/lib/rails/on/sorbet/map.rb

@@ -0,0 +1,21 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'action_controller'
+require 'active_support'
+
+module Map
+  extend T::Generic
+end
+
+def Map(val) = val # rubocop:disable Style/TopLevelMethodDefinition,Naming/MethodName
+
+#: [K = String, V = untyped]
+class ActionController::Parameters
+  include Map
+end
+
+#: [K = String, V = untyped]
+class ActiveSupport::HashWithIndifferentAccess
+  include Map
+end