tapioca 0.19.1 → 0.19.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d3606b2440f453c78a226d8beec0ce61673d416fa74dba7d0380cd31404feaa
-  data.tar.gz: c290cccb23e39c3423913357b187d74de382de4c818194676b206e0981f21c17
+  metadata.gz: 0b165a37e65e25d71de2a502703464d1f877232f4b1d1a173052821e0c7e2170
+  data.tar.gz: f75734a7d89e0dba3f4fbee6c86ab3754dfad69cdaa0bd2575c872ec3020bb65
 SHA512:
-  metadata.gz: 4d655006a08405d41158b918625eadbcf7eec8b43da4c9077a7a9fe3ad94ee549865c27f0c66ae1fc0424afc8e6f30806e60f2ed661067264d920e52c6f04b70
-  data.tar.gz: 96c0d237d2fda54650e919d74fc838b5121b714dcb3a4d35d60836911895265b99b29848f399b7f529050d4c930c3669e52ca3787dfbf1671b883883f39b6bba
+  metadata.gz: 54ab42e4c24755c84f831c8fc5f40db823061558507f4b810af16f7b98c3adac9e02a53b64f9be1f0fb824efec2ca87bec4d6b133b63c37ddb247af1e38b3c45
+  data.tar.gz: 8465d7d2a74d715a966addd29069ec850f4d002662674dab172d0165f5d22228ba9855d70c16a15e8564613b758c76921f9919995da079ad04d8d03e039c47ba

data/README.md

@@ -50,6 +50,9 @@ Tapioca makes it easy to work with [Sorbet](https://sorbet.org) in your codebase
     * [Using DSL compiler options](#using-dsl-compiler-options)
     * [Writing custom DSL compilers](#writing-custom-dsl-compilers)
     * [Writing custom DSL extensions](#writing-custom-dsl-extensions)
+  * [Rewriting RBS comments to Sorbet signatures](#rewriting-rbs-comments-to-sorbet-signatures)
+    * [Caching rewrites with Bootsnap](#caching-rewrites-with-bootsnap)
+    * [Priming the cache from CI](#priming-the-cache-from-ci)
   * [RBI files for missing constants and methods](#rbi-files-for-missing-constants-and-methods)
   * [Configuration](#configuration)
 * [Editor Integration](#editor-integration)
@@ -489,33 +492,35 @@ Usage:
   tapioca dsl [constant...]
 
 Options:
-  --out, -o, [--outdir=directory]                                                                  # The output directory for generated DSL RBI files
-                                                                                                   # Default: sorbet/rbi/dsl
-             [--file-header], [--no-file-header], [--skip-file-header]                             # Add a "This file is generated" header on top of each generated RBI file
-                                                                                                   # Default: true
-             [--only=compiler [compiler ...]]                                                      # Only run supplied DSL compiler(s)
-             [--exclude=compiler [compiler ...]]                                                   # Exclude supplied DSL compiler(s)
-             [--verify], [--no-verify], [--skip-verify]                                            # Verifies RBIs are up-to-date
-                                                                                                   # Default: false
-  -q,        [--quiet], [--no-quiet], [--skip-quiet]                                               # Suppresses file creation output
-                                                                                                   # Default: false
-  -w,        [--workers=N]                                                                         # Number of parallel workers to use when generating RBIs (default: auto)
-             [--rbi-max-line-length=N]                                                             # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
-                                                                                                   # Default: 120
-  -e,        [--environment=ENVIRONMENT]                                                           # The Rack/Rails environment to use when generating RBIs
-                                                                                                   # Default: development
-  -l,        [--list-compilers], [--no-list-compilers], [--skip-list-compilers]                    # List all loaded compilers
-                                                                                                   # Default: false
-             [--app-root=APP_ROOT]                                                                 # The path to the Rails application
-                                                                                                   # Default: .
-             [--halt-upon-load-error], [--no-halt-upon-load-error], [--skip-halt-upon-load-error]  # Halt upon a load error while loading the Rails application
-                                                                                                   # Default: true
-             [--skip-constant=constant [constant ...]]                                             # Do not generate RBI definitions for the given application constant(s)
-             [--compiler-options=key:value]                                                        # Options to pass to the DSL compilers
-  -c,        [--config=<config file path>]                                                         # Path to the Tapioca configuration file
-                                                                                                   # Default: sorbet/tapioca/config.yml
-  -V,        [--verbose], [--no-verbose], [--skip-verbose]                                         # Verbose output for debugging purposes
-                                                                                                   # Default: false
+  --out, -o, [--outdir=directory]                                                                           # The output directory for generated DSL RBI files
+                                                                                                            # Default: sorbet/rbi/dsl
+             [--file-header], [--no-file-header], [--skip-file-header]                                      # Add a "This file is generated" header on top of each generated RBI file
+                                                                                                            # Default: true
+             [--only=compiler [compiler ...]]                                                               # Only run supplied DSL compiler(s)
+             [--exclude=compiler [compiler ...]]                                                            # Exclude supplied DSL compiler(s)
+             [--verify], [--no-verify], [--skip-verify]                                                     # Verifies RBIs are up-to-date
+                                                                                                            # Default: false
+             [--only-bootsnap-rbs-cache], [--no-only-bootsnap-rbs-cache], [--skip-only-bootsnap-rbs-cache]  # Only boot the application and load DSL extensions/compilers to populate the bootsnap iseq cache, then exit. Skips compiler execution and RBI generation. Mutually exclusive with --verify and --list-compilers.
+                                                                                                            # Default: false
+  -q,        [--quiet], [--no-quiet], [--skip-quiet]                                                        # Suppresses file creation output
+                                                                                                            # Default: false
+  -w,        [--workers=N]                                                                                  # Number of parallel workers to use when generating RBIs (default: auto)
+             [--rbi-max-line-length=N]                                                                      # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
+                                                                                                            # Default: 120
+  -e,        [--environment=ENVIRONMENT]                                                                    # The Rack/Rails environment to use when generating RBIs
+                                                                                                            # Default: development
+  -l,        [--list-compilers], [--no-list-compilers], [--skip-list-compilers]                             # List all loaded compilers
+                                                                                                            # Default: false
+             [--app-root=APP_ROOT]                                                                          # The path to the Rails application
+                                                                                                            # Default: .
+             [--halt-upon-load-error], [--no-halt-upon-load-error], [--skip-halt-upon-load-error]           # Halt upon a load error while loading the Rails application
+                                                                                                            # Default: true
+             [--skip-constant=constant [constant ...]]                                                      # Do not generate RBI definitions for the given application constant(s)
+             [--compiler-options=key:value]                                                                 # Options to pass to the DSL compilers
+  -c,        [--config=<config file path>]                                                                  # Path to the Tapioca configuration file
+                                                                                                            # Default: sorbet/tapioca/config.yml
+  -V,        [--verbose], [--no-verbose], [--skip-verbose]                                                  # Verbose output for debugging purposes
+                                                                                                            # Default: false
 
 Generate RBIs for dynamic methods
 ```
@@ -836,6 +841,42 @@ In order for DSL extensions to be discovered by Tapioca, they either needs to be
 
 For more concrete and advanced examples, take a look at [Tapioca's default DSL extensions](https://github.com/Shopify/tapioca/tree/main/lib/tapioca/dsl/extensions).
 
+### Rewriting RBS comments to Sorbet signatures
+
+Tapioca translates [RBS comments](https://sorbet.org/docs/rbs-comments) into Sorbet `sig {}` blocks at file load time, so `sorbet-runtime` wraps the methods as if they had been written with native sigs. This is what lets the DSL command introspect signatures that were originally documented as RBS comments.
+
+The rewriting is automatic on every `tapioca` invocation: [`require-hooks`](https://github.com/Shopify/require-hooks) intercepts `.rb` loads and `Spoom::Sorbet::Translate.rbs_comments_to_sorbet_sigs` translates the source before Ruby compiles it to bytecode.
+
+#### Caching rewrites with Bootsnap
+
+`tapioca dsl` boots the app and eager-loads source files for introspection, so the rewrite runs across the whole codebase. On large applications this adds noticeable overhead. To cache the rewrite output across runs using [bootsnap](https://github.com/Shopify/bootsnap)'s iseq cache, you can set `TAPIOCA_RBS_CACHE=1`:
+
+```shell
+$ TAPIOCA_RBS_CACHE=1 bin/tapioca dsl
+```
+
+Tapioca configures Bootsnap's iseq cache against a dedicated directory (`tmp/cache/bootsnap-tapioca-rbs` by default; override with `TAPIOCA_BOOTSNAP_CACHE_DIR`). The first run is slower because every file is rewritten and the result is baked into the iseq cache; subsequent runs against the same directory skip the rewrite entirely.
+
+`Bootsnap.setup` mutates a process-wide singleton, and a second call would overwrite Tapioca's dedicated cache directory and start writing rewritten iseqs into the host's normal cache. Tapioca enforces this under `TAPIOCA_RBS_CACHE=1`: after its own setup runs, any subsequent `Bootsnap.setup` raises a clear error pointing at the fix. Gate your host's `Bootsnap.setup` on the same env var. Rails apps do this in `config/boot.rb`:
+
+```ruby
+# e.g. config/boot.rb
+require "bootsnap/setup" unless ENV["TAPIOCA_RBS_CACHE"] == "1"
+```
+
+#### Priming the cache from CI
+
+For CI pipelines that want to populate the cache once and have downstream jobs read from a warm copy, use `--only-bootsnap-rbs-cache`. This pattern lets you scope cache writes to a single job (the prime) so PR-side jobs read from it without uploading on every successful build:
+
+```shell
+# Prime: populate the cache.
+$ TAPIOCA_RBS_CACHE=1 bin/tapioca dsl --only-bootsnap-rbs-cache
+
+# Consumer: read from the populated cache.
+# BOOTSNAP_READONLY=1 prevents bootsnap from writing back to a read-only mount.
+$ TAPIOCA_RBS_CACHE=1 BOOTSNAP_READONLY=1 bin/tapioca dsl
+```
+
 ### RBI files for missing constants and methods
 
 Even after generating the RBIs, it is possible that some constants or methods are still undefined for Sorbet.
@@ -957,6 +998,7 @@ dsl:
   only: []
   exclude: []
   verify: false
+  only_bootsnap_rbs_cache: false
   quiet: false
   workers: 1
   rbi_max_line_length: 120

data/lib/tapioca/cli.rb

@@ -103,6 +103,10 @@ module Tapioca
       type: :boolean,
       default: false,
       desc: "Verifies RBIs are up-to-date"
+    option :only_bootsnap_rbs_cache,
+      type: :boolean,
+      default: false,
+      desc: "Only boot the application and load DSL extensions/compilers to populate the bootsnap iseq cache, then exit. Skips compiler execution and RBI generation. Mutually exclusive with --verify and --list-compilers."
     option :quiet,
       aliases: ["-q"],
       type: :boolean,
@@ -146,6 +150,12 @@ module Tapioca
     def dsl(*constant_or_paths)
       set_environment(options)
 
+      if options[:only_bootsnap_rbs_cache] && (options[:verify] || options[:list_compilers])
+        conflicting = options[:verify] ? "--verify" : "--list-compilers"
+        raise MalformattedArgumentError,
+          "Options '--only-bootsnap-rbs-cache' and '#{conflicting}' are mutually exclusive"
+      end
+
       # Assume anything starting with a capital letter or colon is a class, otherwise a path
       constants, paths = constant_or_paths.partition { |c| c =~ /\A[A-Z:]/ }
 
@@ -173,7 +183,7 @@ module Tapioca
       elsif options[:list_compilers]
         Commands::DslCompilerList.new(**command_args)
       else
-        Commands::DslGenerate.new(**command_args)
+        Commands::DslGenerate.new(**command_args, only_bootsnap_rbs_cache: options[:only_bootsnap_rbs_cache])
       end
 
       command.run

data/lib/tapioca/commands/abstract_dsl.rb

@@ -95,6 +95,11 @@ module Tapioca
           )
         end.compact
 
+        if @only.any?
+          say("Skipping stale RBI removal because `--only` is set.", :yellow)
+          return Set.new
+        end
+
         files_to_purge = existing_rbi_files - generated_files
 
         files_to_purge

data/lib/tapioca/commands/dsl_generate.rb

@@ -4,6 +4,12 @@
 module Tapioca
   module Commands
     class DslGenerate < AbstractDsl
+      #: (?only_bootsnap_rbs_cache: bool, **untyped) -> void
+      def initialize(only_bootsnap_rbs_cache: false, **kwargs)
+        @only_bootsnap_rbs_cache = only_bootsnap_rbs_cache
+        super(**T.unsafe(kwargs))
+      end
+
       private
 
       # @override
@@ -11,6 +17,15 @@ module Tapioca
       def execute
         load_application
 
+        if @only_bootsnap_rbs_cache
+          if ENV["TAPIOCA_RBS_CACHE"] == "1"
+            say("Bootsnap RBS cache populated, exiting before RBI generation.", :green)
+          else
+            say_error("Warning: --only-bootsnap-rbs-cache requires TAPIOCA_RBS_CACHE=1 to populate the cache", :yellow)
+          end
+          return
+        end
+
         say("Compiling DSL RBI files...")
         say("")
 

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

@@ -33,7 +33,7 @@ module Tapioca
       #   include GeneratedDelegatedTypeMethods
       #
       #   module GeneratedDelegatedTypeMethods
-      #     sig { params(args: T.untyped).returns(T.any(Message, Comment)) }
+      #     sig { params(args: T.untyped).returns(T.any(::Message, ::Comment)) }
       #     def build_entryable(*args); end
       #
       #     sig { returns(Class) }
@@ -45,7 +45,7 @@ module Tapioca
       #     sig { returns(T::Boolean) }
       #     def message?; end
       #
-      #     sig { returns(T.nilable(Message)) }
+      #     sig { returns(T.nilable(::Message)) }
       #     def message; end
       #
       #     sig { returns(T.nilable(Integer)) }
@@ -54,7 +54,7 @@ module Tapioca
       #     sig { returns(T::Boolean) }
       #     def comment?; end
       #
-      #     sig { returns(T.nilable(Comment)) }
+      #     sig { returns(T.nilable(::Comment)) }
       #     def comment; end
       #
       #     sig { returns(T.nilable(Integer)) }
@@ -67,6 +67,9 @@ module Tapioca
       class ActiveRecordDelegatedTypes < Compiler
         include Helpers::ActiveRecordConstantsHelper
 
+        # A delegated type entry paired with the fully-qualified constant name it resolves to.
+        ResolvedType = Struct.new(:raw_name, :qualified_name, keyword_init: true)
+
         # @override
         #: -> void
         def decorate
@@ -77,8 +80,11 @@ module Tapioca
               constant.__tapioca_delegated_types.each do |role, data|
                 types = data.fetch(:types)
                 options = data.fetch(:options, {})
-                populate_role_accessors(mod, role, types)
-                populate_type_helpers(mod, role, types, options)
+                resolved_types = types.map do |type|
+                  ResolvedType.new(raw_name: type, qualified_name: qualified_type_name(type, role))
+                end
+                populate_role_accessors(mod, role, resolved_types)
+                populate_type_helpers(mod, role, resolved_types, options)
               end
             end
 
@@ -96,8 +102,8 @@ module Tapioca
 
         private
 
-        #: (RBI::Scope mod, Symbol role, Array[String] types) -> void
-        def populate_role_accessors(mod, role, types)
+        #: (RBI::Scope mod, Symbol role, Array[ResolvedType] resolved_types) -> void
+        def populate_role_accessors(mod, role, resolved_types)
           mod.create_method(
             "#{role}_name",
             parameters: [],
@@ -113,20 +119,20 @@ module Tapioca
           mod.create_method(
             "build_#{role}",
             parameters: [create_rest_param("args", type: "T.untyped")],
-            return_type: types.size == 1 ? types.first : "T.any(#{types.join(", ")})",
+            return_type: build_return_type(resolved_types),
           )
         end
 
-        #: (RBI::Scope mod, Symbol role, Array[String] types, Hash[Symbol, untyped] options) -> void
-        def populate_type_helpers(mod, role, types, options)
-          types.each do |type|
-            populate_type_helper(mod, role, type, options)
+        #: (RBI::Scope mod, Symbol role, Array[ResolvedType] resolved_types, Hash[Symbol, untyped] options) -> void
+        def populate_type_helpers(mod, role, resolved_types, options)
+          resolved_types.each do |resolved_type|
+            populate_type_helper(mod, role, resolved_type, options)
           end
         end
 
-        #: (RBI::Scope mod, Symbol role, String type, Hash[Symbol, untyped] options) -> void
-        def populate_type_helper(mod, role, type, options)
-          singular   = type.tableize.tr("/", "_").singularize
+        #: (RBI::Scope mod, Symbol role, ResolvedType resolved_type, Hash[Symbol, untyped] options) -> void
+        def populate_type_helper(mod, role, resolved_type, options)
+          singular   = resolved_type.raw_name.tableize.tr("/", "_").singularize
           query      = "#{singular}?"
           primary_key = options[:primary_key] || "id"
           role_id = options[:foreign_key] || "#{role}_id"
@@ -142,7 +148,7 @@ module Tapioca
           mod.create_method(
             singular,
             parameters: [],
-            return_type: "T.nilable(#{type})",
+            return_type: "T.nilable(#{resolved_type.qualified_name})",
           )
 
           mod.create_method(
@@ -151,6 +157,48 @@ module Tapioca
             return_type: as_nilable_type(getter_type),
           )
         end
+
+        # Collapses to `T.untyped` if any member is `T.untyped`, since `T.any(::Foo, T.untyped)`
+        # is equivalent to `T.untyped` in Sorbet and the per-type error has already been recorded.
+        #: (Array[ResolvedType] resolved_types) -> String
+        def build_return_type(resolved_types)
+          qualified_types = resolved_types.map(&:qualified_name)
+          if qualified_types.include?("T.untyped")
+            "T.untyped"
+          elsif qualified_types.size == 1
+            qualified_types.fetch(0)
+          else
+            "T.any(#{qualified_types.join(", ")})"
+          end
+        end
+
+        # Resolves a delegated type entry to a fully-qualified constant name. The strings passed
+        # to `delegated_type(..., types: %w[...])` are written verbatim into the generated RBI,
+        # but the surrounding `class A::B::C` scope omits `A` and `A::B` from Sorbet's lexical
+        # nesting, so a bare `D` reference fails to resolve to `A::B::D` even when that constant
+        # exists. `compute_type` is `ActiveRecord::Base`'s own (private) namespace-walking lookup
+        # — the same one Rails uses for STI and polymorphic associations — so it resolves both
+        # bare and fully-qualified names. When the constant can't be resolved (NameError) or its
+        # qualified name can't be derived (anonymous class) we record a compiler error and emit
+        # `T.untyped`, which both surfaces the problem and keeps the generated RBI type-checkable.
+        #: (String type, Symbol role) -> String
+        def qualified_type_name(type, role)
+          klass = constant.send(:compute_type, type)
+          qualified_name = qualified_name_of(klass)
+          return qualified_name if qualified_name
+
+          add_unresolvable_type_error(type, role)
+        rescue NameError, LoadError
+          add_unresolvable_type_error(type, role)
+        end
+
+        #: (String type, Symbol role) -> String
+        def add_unresolvable_type_error(type, role)
+          add_error(<<~MSG.strip)
+            Cannot generate delegated_type `#{role}` on `#{constant}` since the type `#{type}` could not be resolved.
+          MSG
+          "T.untyped"
+        end
       end
     end
   end

data/lib/tapioca/dsl/helpers/graphql_type_helper.rb

@@ -80,7 +80,9 @@ module Tapioca
             signature = Runtime::Reflection.signature_of(method)
             return_type = signature&.return_type
 
-            valid_return_type?(return_type) ? return_type.to_s : "T.untyped"
+            # Wrap as non-nilable for required arguments. `coerce_input` supports both
+            # required and optional; optional arguments are re-wrapped below based on `type.non_null?`
+            valid_return_type?(return_type) ? (T::Utils.unwrap_nilable(return_type) || return_type).to_s : "T.untyped"
           when GraphQL::Schema::InputObject.singleton_class
             type_for_constant(unwrapped_type)
           when Module

data/lib/tapioca/dsl/pipeline.rb

@@ -138,7 +138,7 @@ module Tapioca
         active_compilers.each do |compiler|
           constants.merge(compiler.processable_constants)
         end
-        constants = filter_anonymous_and_reloaded_constants(constants)
+        constants = filter_anonymous_constants(constants)
         constants -= skipped_constants
 
         unless requested_constants.empty? && requested_paths.empty?
@@ -154,32 +154,8 @@ module Tapioca
       end
 
       #: (Set[Module[top]] constants) -> Set[Module[top]]
-      def filter_anonymous_and_reloaded_constants(constants)
-        # Group constants by their names
-        constants_by_name = constants
-          .group_by { |c| Runtime::Reflection.name_of(c) }
-          .select { |name, _| !name.nil? }
-
-        constants_by_name = T.cast(constants_by_name, T::Hash[String, T::Array[T::Module[T.anything]]])
-
-        # Find the constants that have been reloaded
-        reloaded_constants = constants_by_name.select { |_, constants| constants.size > 1 }.keys
-
-        unless reloaded_constants.empty? || @lsp_addon
-          reloaded_constant_names = reloaded_constants.map { |name| "`#{name}`" }.join(", ")
-
-          $stderr.puts("WARNING: Multiple constants with the same name: #{reloaded_constant_names}")
-          $stderr.puts("Make sure some object is not holding onto these constants during an app reload.")
-        end
-
-        # Look up all the constants back from their names. The resulting constant set will be the
-        # set of constants that are actually in memory with those names.
-        filtered_constants = constants_by_name
-          .keys
-          .map { |name| T.cast(Runtime::Reflection.constantize(name), T::Module[T.anything]) }
-          .select { |mod| Runtime::Reflection.constant_defined?(mod) }
-
-        Set.new.compare_by_identity.merge(filtered_constants)
+      def filter_anonymous_constants(constants)
+        constants.keep_if { |constant| Runtime::Reflection.name_of(constant) }
       end
 
       #: (Module[top] constant) -> RBI::File?

data/lib/tapioca/internal.rb

@@ -12,6 +12,7 @@ require "tapioca/runtime/dynamic_mixin_compiler"
 require "tapioca/sorbet_ext/backcompat_patches"
 require "tapioca/sorbet_ext/name_patch"
 require "tapioca/sorbet_ext/generic_name_patch"
+require "tapioca/sorbet_ext/generic_type_patch"
 require "tapioca/sorbet_ext/proc_bind_patch"
 require "tapioca/sorbet_ext/void_patch"
 require "tapioca/runtime/generic_type_registry"

data/lib/tapioca/rbs/rewriter.rb

@@ -1,39 +1,93 @@
 # typed: strict
 # frozen_string_literal: true
 
-require "require-hooks/setup"
-
 # This code rewrites RBS comments back into Sorbet's signatures as the files are being loaded.
 # This will allow `sorbet-runtime` to wrap the methods as if they were originally written with the `sig{}` blocks.
 # This will in turn allow Tapioca to use this signatures to generate typed RBI files.
 
-begin
-  # When in a `bootsnap` environment, files are loaded from the cache and won't trigger the `source_transform` method.
-  # The `require-hooks` gem comes with a `bootsnap` mode that will disable the `bootsnap/compile_cache/iseq` caching.
-  # Sadly, we're way to early in the boot process to use it as bootsnap won't be loaded yet and the `require-hooks`
-  # setup won't pick it up.
-  #
-  # As a workaround, if we can preemptively require `bootsnap` and `bootsnap/compile_cache/iseq` we manually override
-  # the `load_iseq` method to disable the caching mechanism.
-  #
-  # This will make the Rails app load slower but allows us to trigger the RBS -> RBI source transform.
-  require "bootsnap"
-  require "bootsnap/compile_cache/iseq"
-
-  module Bootsnap
-    module CompileCache
-      module ISeq
-        module InstructionSequenceMixin
-          #: (String) -> RubyVM::InstructionSequence
-          def load_iseq(path)
-            super if defined?(super)
+module Tapioca
+  module RBS
+    class HostBootsnapSetupError < StandardError; end
+
+    # Raises when the host calls `Bootsnap.setup` after tapioca's setup. Host's call
+    # would overwrite tapioca's cache directory, so rewritten iseqs would end up in
+    # the host's regular cache.
+    module BootsnapGuard
+      extend T::Sig
+
+      sig { params(_kwargs: T.untyped).void }
+      def setup(**_kwargs)
+        Kernel.raise HostBootsnapSetupError, <<~MSG
+          Bootsnap.setup was called while TAPIOCA_RBS_CACHE=1 is set. Tapioca already
+          configured bootsnap with a dedicated cache directory; re-running setup
+          would overwrite that config and start writing rewritten iseqs into your
+          host's cache.
+
+          Gate your host's Bootsnap.setup on the env var, e.g. in config/boot.rb:
+
+            require "bootsnap/setup" unless ENV["TAPIOCA_RBS_CACHE"] == "1"
+        MSG
+      end
+    end
+  end
+end
+
+# When TAPIOCA_RBS_CACHE=1, set up bootsnap with a dedicated cache directory
+# and load require-hooks so the RBS-rewritten iseqs get cached. Subsequent
+# runs read the rewritten iseq directly and skip the rewrite.
+#
+# After our setup, BootsnapGuard is prepended so the host application can't
+# replace our cache directory.
+if ENV["TAPIOCA_RBS_CACHE"] == "1"
+  begin
+    require "bootsnap"
+    # Respect BOOTSNAP_READONLY for consumers reading a pre-populated cache
+    # (e.g. a CI prime step).
+    readonly = !["0", "false", false].include?(ENV.fetch("BOOTSNAP_READONLY") { false })
+    Bootsnap.setup(
+      cache_dir: ENV.fetch("TAPIOCA_BOOTSNAP_CACHE_DIR", File.join(Dir.pwd, "tmp/cache/bootsnap-tapioca-rbs")),
+      development_mode: true,
+      load_path_cache: true,
+      compile_cache_iseq: true,
+      compile_cache_yaml: true,
+      readonly: readonly,
+      revalidation: true,
+    )
+    Bootsnap.log_stats!
+    Bootsnap.singleton_class.prepend(Tapioca::RBS::BootsnapGuard)
+  rescue LoadError
+    # Bootsnap is not in the bundle, skip iseq caching.
+  end
+
+  require "require-hooks/setup"
+else
+  require "require-hooks/setup"
+
+  begin
+    # Disable Bootsnap's iseq cache unless TAPIOCA_RBS_CACHE=1 enabled the separate cache above.
+    #
+    # This is necessary because host apps can call Bootsnap.setup after tapioca loads this file. When that happens,
+    # Bootsnap installs `load_iseq` and serves files from its cache, which bypasses RequireHooks.source_transform.
+    # Preloading bootsnap's iseq support lets us override `load_iseq` before setup installs it, preserving the default
+    # RBS rewrite behavior at the cost of slower app boot.
+    require "bootsnap"
+    require "bootsnap/compile_cache/iseq"
+
+    module Bootsnap
+      module CompileCache
+        module ISeq
+          module InstructionSequenceMixin
+            #: (String) -> RubyVM::InstructionSequence
+            def load_iseq(path)
+              super if defined?(super) # Disable Bootsnap's hook, but trigger any others.
+            end
           end
         end
       end
     end
+  rescue LoadError
+    # Bootsnap is not in the bundle, we don't need to do anything.
   end
-rescue LoadError
-  # Bootsnap is not in the bundle, we don't need to do anything.
 end
 
 # We need to include `T::Sig` very early to make sure that the `sig` method is available since gems using RBS comments
@@ -47,7 +101,8 @@ RequireHooks.source_transform(patterns: ["**/*.rb"]) do |path, source|
 
   # For performance reasons, we only rewrite files that use Sorbet.
   if source =~ /^\s*#\s*typed: (ignore|false|true|strict|strong|__STDLIB_INTERNAL)/
-    Spoom::Sorbet::Translate.rbs_comments_to_sorbet_sigs(source, file: path)
+    # Sorbet runtime only supports one signature per method, so keep the last overload.
+    Spoom::Sorbet::Translate.rbs_comments_to_sorbet_sigs(source, file: path, overloads_strategy: :translate_last)
   end
 rescue Spoom::Sorbet::Translate::Error
   # If we can't translate the RBS comments back into Sorbet's signatures, we just skip the file.

data/lib/tapioca/runtime/generic_type_registry.rb

@@ -6,7 +6,7 @@ module Tapioca
     # This class is responsible for storing and looking up information related to generic types.
     #
     # The class stores 2 different kinds of data, in two separate lookup tables:
-    #   1. a lookup of generic type instances by name: `@generic_instances`
+    #   1. a lookup of generic type instances by constant and name: `@generic_instances`
     #   2. a lookup of type variable serializer by constant and type variable
     #      instance: `@type_variables`
     #
@@ -21,7 +21,7 @@ module Tapioca
     # variable to type variable serializers. This allows us to associate type variables
     # to the constant names that represent them, easily.
     module GenericTypeRegistry
-      @generic_instances = {} #: Hash[String, Module[top]]
+      @generic_instances = {}.compare_by_identity #: Hash[Module[top], Hash[String, Module[top]]]
 
       @type_variables = {}.compare_by_identity #: Hash[Module[top], Array[TypeVariableModule]]
 
@@ -45,8 +45,9 @@ module Tapioca
         # and cloning the given constant so that we can return a type that is the same
         # as the current type but is a different instance and has a different name method.
         #
-        # We cache those cloned instances by their name in `@generic_instances`, so that
-        # we don't keep instantiating a new type every single time it is referenced.
+        # We cache those cloned instances by their original constant and their name in
+        # `@generic_instances`, so that we don't keep instantiating a new type every single
+        # time it is referenced.
         # For example, `[Foo[Integer], Foo[Integer], Foo[Integer], Foo[String]]` will only
         # result in 2 clones (1 for `Foo[Integer]` and another for `Foo[String]`) and
         # 2 hash lookups (for the other two `Foo[Integer]`s).
@@ -64,12 +65,15 @@ module Tapioca
           #
           # Also, we try to memoize the generic type based on the name, so that
           # we don't have to keep recreating them all the time.
-          @generic_instances[name] ||= create_generic_type(constant, name)
+          generic_instances = @generic_instances[constant] ||= {}
+          generic_instances[name] ||= create_generic_type(constant, name)
         end
 
         #: (Object instance) -> bool
         def generic_type_instance?(instance)
-          @generic_instances.values.any? { |generic_type| generic_type === instance }
+          @generic_instances.values.any? do |generic_instances|
+            generic_instances.values.any? { |generic_type| generic_type === instance }
+          end
         end
 
         #: (Module[top] constant) -> Array[TypeVariableModule]?
@@ -88,7 +92,7 @@ module Tapioca
         # can return it from the original methods as well.
         #: (untyped constant, TypeVariableModule type_variable) -> void
         def register_type_variable(constant, type_variable)
-          type_variables = lookup_or_initialize_type_variables(constant)
+          type_variables = @type_variables[constant] ||= []
 
           type_variables << type_variable
         end
@@ -163,11 +167,6 @@ module Tapioca
             owner.send(:define_method, :inherited, inherited_method)
           end
         end
-
-        #: (Module[top] constant) -> Array[TypeVariableModule]
-        def lookup_or_initialize_type_variables(constant)
-          @type_variables[constant] ||= []
-        end
       end
     end
   end

data/lib/tapioca/sorbet_ext/generic_name_patch.rb

@@ -82,26 +82,6 @@ module T
       prepend GenericPatch
     end
   end
-
-  module Utils
-    module Private
-      module PrivateCoercePatch
-        def coerce_and_check_module_types(val, check_val, check_module_type)
-          if val.is_a?(Tapioca::TypeVariableModule)
-            val.coerce_to_type_variable
-          elsif val.respond_to?(:__tapioca_override_type)
-            val.__tapioca_override_type
-          else
-            super
-          end
-        end
-      end
-
-      class << self
-        prepend(PrivateCoercePatch)
-      end
-    end
-  end
 end
 
 module Tapioca

data/lib/tapioca/sorbet_ext/generic_type_patch.rb

@@ -0,0 +1,48 @@
+# typed: true
+# frozen_string_literal: true
+
+module T
+  module Utils
+    module Private
+      # Preserve Tapioca's generic type variables and instantiated generic
+      # names when Sorbet coerces them into runtime types.
+      module TapiocaGenericTypeCoercePatch
+        def coerce_and_check_module_types(val, check_val, check_module_type)
+          if val.is_a?(Tapioca::TypeVariableModule)
+            val.coerce_to_type_variable
+          elsif val.respond_to?(:__tapioca_override_type)
+            val.__tapioca_override_type
+          else
+            super
+          end
+        end
+      end
+
+      class << self
+        prepend(TapiocaGenericTypeCoercePatch)
+      end
+    end
+  end
+
+  module Private
+    module Casts
+      module TapiocaGenericTypeCastPatch
+        # https://github.com/sorbet/sorbet/commit/b8d64c7fd9a08e2b9159b5d592bc2de6d586b44a
+        # inlines the Module fast path in `T.let`, `T.cast`, `T.bind`, and
+        # `T.assert_type!`, so generic module clones can reach this cast path
+        # without going through `T::Utils::Private::TapiocaGenericTypeCoercePatch`.
+        def cast(value, type, cast_method)
+          if type.respond_to?(:__tapioca_override_type)
+            type = type.__tapioca_override_type
+          end
+
+          super(value, type, cast_method)
+        end
+      end
+
+      class << self
+        prepend(TapiocaGenericTypeCastPatch)
+      end
+    end
+  end
+end

data/lib/tapioca/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Tapioca
-  VERSION = "0.19.1"
+  VERSION = "0.19.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tapioca
 version: !ruby/object:Gem::Version
-  version: 0.19.1
+  version: 0.19.2
 platform: ruby
 authors:
 - Ufuk Kayserilioglu
@@ -144,14 +144,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.9
+        version: 1.7.16
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.9
+        version: 1.7.16
 - !ruby/object:Gem::Dependency
   name: tsort
   requirement: !ruby/object:Gem::Requirement
@@ -305,6 +305,7 @@ files:
 - lib/tapioca/runtime/trackers/tracker.rb
 - lib/tapioca/sorbet_ext/backcompat_patches.rb
 - lib/tapioca/sorbet_ext/generic_name_patch.rb
+- lib/tapioca/sorbet_ext/generic_type_patch.rb
 - lib/tapioca/sorbet_ext/name_patch.rb
 - lib/tapioca/sorbet_ext/proc_bind_patch.rb
 - lib/tapioca/sorbet_ext/void_patch.rb