tapioca 0.19.0 → 0.19.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1af20de26e446268513156110cac416ce7ba2b35f96f4bb7898960d640aa4333
-  data.tar.gz: 4d760ed85be418d9c9dc166d61ea59ccaf312c929bd4930709abc4b946f3876f
+  metadata.gz: 0b165a37e65e25d71de2a502703464d1f877232f4b1d1a173052821e0c7e2170
+  data.tar.gz: f75734a7d89e0dba3f4fbee6c86ab3754dfad69cdaa0bd2575c872ec3020bb65
 SHA512:
-  metadata.gz: 1bf6bbf64b782f072a23109ca90cf9c3743b82501bf304badcd97b816583f2fff3ec3574d58df22f05af716d750ba86589074f43a1ee5d3f9e383fdb83c8ee02
-  data.tar.gz: a4d066179177ee84ee349bb7a8514d9b2ad8836051b33adc45ca3708948ddc01a002d6d54fd9c42cc0993ca5e30f74a61f5f5ad8a603ef493b50bee0c7d6ef93
+  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
@@ -162,7 +167,7 @@ module Tapioca
         filenames.to_set
       end
 
-      #: (Array[String] constant_names, ?ignore_missing: bool) -> Array[T::Module[top]]
+      #: (Array[String] constant_names, ?ignore_missing: bool) -> Array[Module[top]]
       def constantize(constant_names, ignore_missing: false)
         constant_map = constant_names.to_h do |name|
           [name, Object.const_get(name)]

data/lib/tapioca/commands/check_shims.rb

@@ -53,6 +53,9 @@ module Tapioca
         if @payload
           Dir.mktmpdir do |dir|
             payload_path = dir
+
+            # No need for `--stop-after`, because Sorbet exits immediately after dumping the payload.
+            # https://github.com/sorbet/sorbet/blob/41ae325/main/realmain.cc#L522-L552
             result = sorbet("--no-config --print=payload-sources:#{payload_path}")
 
             unless result.status

data/lib/tapioca/commands/configure.rb

@@ -38,6 +38,7 @@ module Tapioca
           .
           --ignore=tmp/
           --ignore=vendor/
+          --parser=prism
         CONTENT
       end
 

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/commands/todo.rb

@@ -83,12 +83,18 @@ module Tapioca
       #: -> Array[String]
       def unresolved_constants
         # Taken from https://github.com/sorbet/sorbet/blob/master/gems/sorbet/lib/todo-rbi.rb
-        sorbet("--print=missing-constants", "--quiet", "--stdout-hup-hack", "--no-error-count")
+        sorbet(
+          "--print=missing-constants",
+          "--stop-after=resolver",
+          "--quiet",
+          "--stdout-hup-hack",
+          "--no-error-count",
+        )
           .out
           .strip
           .each_line
           .filter_map do |line|
-            next if line.include?("<")
+            next if line.include?("<") # Skip singleton classes like `#<Class:String>`
 
             line.strip
               .gsub(/T\.class_of\(([:\w]+)\)/, '\1') # Turn T.class_of(Foo)::Bar into Foo::Bar

data/lib/tapioca/dsl/compiler.rb

@@ -4,7 +4,7 @@
 module Tapioca
   module Dsl
     # @abstract
-    #: [ConstantType < T::Module[top]]
+    #: [ConstantType < Module[top]]
     class Compiler
       include RBIHelper
       include Runtime::Reflection
@@ -19,24 +19,24 @@ module Tapioca
       #: Hash[String, untyped]
       attr_reader :options
 
-      @@requested_constants = [] #: Array[T::Module[top]] # rubocop:disable Style/ClassVars
+      @@requested_constants = [] #: Array[Module[top]] # rubocop:disable Style/ClassVars
 
       class << self
-        #: (T::Module[top] constant) -> bool
+        #: (Module[top] constant) -> bool
         def handles?(constant)
           processable_constants.include?(constant)
         end
 
         # @abstract
-        #: -> Enumerable[T::Module[top]]
+        #: -> Enumerable[Module[top]]
         def gather_constants = raise NotImplementedError, "Abstract method called"
 
-        #: -> Set[T::Module[top]]
+        #: -> Set[Module[top]]
         def processable_constants
-          @processable_constants ||= T::Set[T::Module[T.anything]].new.compare_by_identity.merge(gather_constants) #: Set[T::Module[top]]?
+          @processable_constants ||= T::Set[T::Module[T.anything]].new.compare_by_identity.merge(gather_constants) #: Set[Module[top]]?
         end
 
-        #: (Array[T::Module[top]] constants) -> void
+        #: (Array[Module[top]] constants) -> void
         def requested_constants=(constants)
           @@requested_constants = constants # rubocop:disable Style/ClassVars
         end
@@ -69,13 +69,13 @@ module Tapioca
           @all_classes ||= all_modules.grep(Class).freeze #: Enumerable[Class[top]]?
         end
 
-        #: -> Enumerable[T::Module[top]]
+        #: -> Enumerable[Module[top]]
         def all_modules
           @all_modules ||= if @@requested_constants.any?
             @@requested_constants.grep(Module)
           else
             ObjectSpace.each_object(Module).to_a
-          end.freeze #: Enumerable[T::Module[top]]?
+          end.freeze #: Enumerable[Module[top]]?
         end
       end
 
@@ -124,10 +124,12 @@ module Tapioca
         signature.kwarg_types.each { |_, kwarg_type| params << kwarg_type.to_s }
 
         # rest parameter type
-        params << signature.rest_type.to_s if signature.has_rest
+        rest_type = signature.rest_type
+        params << rest_type.to_s if rest_type
 
         # keyrest parameter type
-        params << signature.keyrest_type.to_s if signature.has_keyrest
+        keyrest_type = signature.keyrest_type
+        params << keyrest_type.to_s if keyrest_type
 
         # special case `.void` in a proc
         unless signature.block_name.nil?
@@ -141,14 +143,12 @@ module Tapioca
       def create_method_from_def(scope, method_def, class_method: false)
         parameters = compile_method_parameters_to_rbi(method_def)
         return_type = compile_method_return_type_to_rbi(method_def)
-        type_params = extract_type_parameters(parameters.map(&:type).push(return_type))
 
         scope.create_method(
           method_def.name.to_s,
           parameters: parameters,
           return_type: return_type,
           class_method: class_method,
-          type_params: type_params,
         )
       end
 

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

@@ -202,7 +202,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             T.cast(ObjectSpace.each_object(::AASM::ClassMethods), T::Enumerable[T::Module[T.anything]])
           end

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

@@ -117,7 +117,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActionController::Base).select(&:name).select do |klass|
               klass.const_defined?(:HelperMethods, false)
@@ -148,7 +148,7 @@ module Tapioca
           )
         end
 
-        #: (T::Module[top] mod) -> Array[String]
+        #: (Module[top] mod) -> Array[String]
         def gather_includes(mod)
           mod.ancestors
             .reject { |ancestor| ancestor.is_a?(Class) || ancestor == mod || name_of(ancestor).nil? }

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

@@ -50,7 +50,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActionMailer::Base).reject(&:abstract?)
           end

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

@@ -80,7 +80,7 @@ module Tapioca
           end
 
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActiveRecord::Base)
               .reject(&:abstract_class?)

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

@@ -84,7 +84,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActiveJob::Base)
           end

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

@@ -59,7 +59,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             all_classes.grep(::ActiveModel::Attributes::ClassMethods)
           end

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

@@ -89,7 +89,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             # In some versions of Rails 8.1, `ActiveModel::SecurePassword` uses `Numeric#minutes`
             # which isn't explicitly required in the gem, and it might not be loaded already.

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

@@ -44,7 +44,7 @@ module Tapioca
       class ActiveModelValidationsConfirmation < Compiler
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             # Collect all the classes that include ActiveModel::Validations
             all_classes.select { |c| ActiveModel::Validations > c }

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

@@ -136,7 +136,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActiveRecord::Base).reject(&:abstract_class?)
           end

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

@@ -163,7 +163,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActiveRecord::Base).reject(&:abstract_class?)
           end

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
 
@@ -88,7 +94,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActiveRecord::Base).reject(&:abstract_class?)
           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/compilers/active_record_enum.rb

@@ -74,7 +74,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             descendants_of(::ActiveRecord::Base)
           end

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

@@ -58,7 +58,7 @@ module Tapioca
 
         class << self
           # @override
-          #: -> Enumerable[T::Module[top]]
+          #: -> Enumerable[Module[top]]
           def gather_constants
             return [] unless defined?(Rails.application) && Rails.application