tapioca 0.19.1 → 0.20.0

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/compilers/active_record_fixtures.rb

@@ -26,13 +26,21 @@ module Tapioca
       # # test_case.rbi
       # # typed: true
       # class ActiveSupport::TestCase
-      #   sig { params(fixture_name: NilClass, other_fixtures: NilClass).returns(T::Array[Post]) }
-      #   sig { params(fixture_name: T.any(String, Symbol), other_fixtures: NilClass).returns(Post) }
-      #   sig { params(fixture_name: T.any(String, Symbol), other_fixtures: T.any(String, Symbol))
-      #           .returns(T::Array[Post]) }
+      #   include ActiveRecord::TestFixtures
+      #
+      #   sig { returns(T::Array[Post]) }                                                          #   No names: returns an Array of all fixtures
+      #   sig { params(fixture_name: T.any(String, Symbol)).returns(Post) }                        #   One name: returns the requested fixture
+      #   sig { params(fixture_name: T.any(String, Symbol), other_fixtures: T.any(String, Symbol)) # Many names: returns an Array of the requested fixtures
+      #   .returns(T::Array[Post]) }
       #   def posts(fixture_name = nil, *other_fixtures); end
       # end
       # ~~~
+      #
+      # The `include` is generated because Rails mixes `ActiveRecord::TestFixtures` into
+      # `ActiveSupport::TestCase` through the `:active_support_test_case` load hook in
+      # `rails/test_help.rb`. Since RBI generation does not load an app's test helper, this runtime
+      # include is not captured. Without it, Sorbet does not see the class methods the module
+      # contributes via `mixes_in_class_methods`, such as `fixtures`.
       #: [ConstantType = singleton(ActiveSupport::TestCase)]
       class ActiveRecordFixtures < Compiler
         MISSING = Object.new
@@ -47,9 +55,10 @@ module Tapioca
           end
 
           method_names.select! { |name| fixture_class_mapping_from_fixture_files[name] != MISSING }
-          return if method_names.empty?
 
           root.create_path(constant) do |mod|
+            mod.create_include("ActiveRecord::TestFixtures")
+
             method_names.each do |name|
               create_fixture_method(mod, name.to_s)
             end
@@ -110,19 +119,16 @@ module Tapioca
             node.add_opt_param("fixture_name", "nil")
             node.add_rest_param("other_fixtures")
 
-            node.add_sig do |sig|
-              sig.add_param("fixture_name", "NilClass")
-              sig.add_param("other_fixtures", "NilClass")
+            node.add_sig do |sig| # No-parameter overload: returns an Array of all fixtures
               sig.return_type = "T::Array[#{return_type}]"
             end
 
-            node.add_sig do |sig|
+            node.add_sig do |sig| # One parameter overload: returns the requested fixture
               sig.add_param("fixture_name", "T.any(String, Symbol)")
-              sig.add_param("other_fixtures", "NilClass")
               sig.return_type = return_type
             end
 
-            node.add_sig do |sig|
+            node.add_sig do |sig| # Multi-parameter overload: returns an Array of the requested fixtures
               sig.add_param("fixture_name", "T.any(String, Symbol)")
               sig.add_param("other_fixtures", "T.any(String, Symbol)")
               sig.return_type = "T::Array[#{return_type}]"

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

@@ -224,10 +224,10 @@ module Tapioca
           order: ["T.any(Symbol, T::Array[Symbol])", ":asc"],
           cursor: ["T.untyped", "primary_key"],
           use_ranges: ["T.untyped", "nil"],
-        } #: Hash[Symbol, [String, String]]
+        }.freeze #: Hash[Symbol, [String, String]]
         CALCULATION_METHODS = ActiveRecord::Calculations.instance_methods(false) #: Array[Symbol]
         RELATION_METHODS = ActiveRecord::Relation.instance_methods(false) #: Array[Symbol]
-        TO_ARRAY_METHODS = [:to_ary, :to_a] #: Array[Symbol]
+        TO_ARRAY_METHODS = [:to_ary, :to_a].freeze #: Array[Symbol]
 
         private
 

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

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-return unless defined?(Config) && defined?(Config::VERSION) && defined?(Config.const_name)
+return unless defined?(Config::VERSION) && defined?(Config.const_name)
 
 module Tapioca
   module Dsl

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

@@ -120,7 +120,7 @@ module Tapioca
           schema = constant.schema
 
           # empty? does not exist on JsonApiClient::Schema
-          schema if schema.size > 0 # rubocop:disable Style/ZeroLengthPredicate
+          schema if schema.size > 0
         end
 
         #: (RBI::Scope mod, ::JsonApiClient::Schema::Property property) -> void

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

@@ -46,7 +46,7 @@ module Tapioca
         # @override
         #: -> void
         def decorate
-          return unless constant.instance_methods.include?(:perform)
+          return unless constant.method_defined?(:perform)
 
           root.create_path(constant) do |worker|
             method_def = constant.instance_method(:perform)

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

@@ -7,7 +7,22 @@ module Tapioca
   module Dsl
     module Compilers
       # `Tapioca::Dsl::Compilers::UrlHelpers` generates RBI files for classes that include or extend
-      # [`Rails.application.routes.url_helpers`](https://api.rubyonrails.org/v5.1.7/classes/ActionDispatch/Routing/UrlFor.html#module-ActionDispatch::Routing::UrlFor-label-URL+generation+for+named+routes).
+      # [`Rails.application.routes.url_helpers`](https://api.rubyonrails.org/classes/ActionDispatch/Routing/UrlFor.html#module-ActionDispatch::Routing::UrlFor-label-URL+generation+for+named+routes).
+      #
+      # The compiler registers generated constants to represent the Rails route helper modules:
+      #
+      # 1. `GeneratedPathHelpersModule` holds the main application's path helpers, such as `post_path`.
+      #
+      # 2. `GeneratedUrlHelpersModule` holds the main application's URL helpers, such as `post_url`.
+      #
+      # 3. `GeneratedMountedHelpers` is a synthetic module for mounted application and engine helpers, such as
+      # `main_app` and `articles`. Rails exposes these helpers through an anonymous dynamic module, so the compiler creates
+      # a named RBI module that can be included or extended by classes that receive mounted helpers at runtime. It is
+      # only generated for applications that mount an engine that defines its own routes.
+      #
+      # For mounted engines, the compiler also registers engine-scoped `GeneratedPathHelpersModule` and
+      # `GeneratedUrlHelpersModule` constants. Mounted engine helper methods return a synthetic
+      # `GeneratedRoutesProxy` subclass that includes those engine-scoped helper modules.
       #
       # For example, with the following setup:
       #
@@ -16,6 +31,8 @@ module Tapioca
       # class Application < Rails::Application
       #   routes.draw do
       #     resource :index
+      #
+      #     mount Blog::Engine, at: "/blog", as: "articles"
       #   end
       # end
       # ~~~
@@ -42,6 +59,9 @@ module Tapioca
       #   include ActionDispatch::Routing::UrlFor
       #
       #   sig { params(args: T.untyped).returns(String) }
+      #   def articles_path(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
       #   def edit_index_path(*args); end
       #
       #   sig { params(args: T.untyped).returns(String) }
@@ -60,6 +80,9 @@ module Tapioca
       #   include ActionDispatch::Routing::UrlFor
       #
       #   sig { params(args: T.untyped).returns(String) }
+      #   def articles_url(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
       #   def edit_index_url(*args); end
       #
       #   sig { params(args: T.untyped).returns(String) }
@@ -78,6 +101,86 @@ module Tapioca
       #   include GeneratedUrlHelpersModule
       # end
       # ~~~
+      #
+      # ~~~rb
+      # # blog/config/routes.rb
+      # Blog::Engine.routes.draw do
+      #   resources :posts
+      # end
+      # ~~~
+      #
+      # ~~~rbi
+      # # blog/engine/generated_path_helpers_module.rbi
+      # # typed: true
+      # module Blog::Engine::GeneratedPathHelpersModule
+      #   include ActionDispatch::Routing::PolymorphicRoutes
+      #   include ActionDispatch::Routing::UrlFor
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def edit_post_path(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def new_post_path(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def post_path(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def posts_path(*args); end
+      # end
+      # ~~~
+      #
+      # ~~~rbi
+      # # blog/engine/generated_url_helpers_module.rbi
+      # # typed: true
+      # module Blog::Engine::GeneratedUrlHelpersModule
+      #   include ActionDispatch::Routing::PolymorphicRoutes
+      #   include ActionDispatch::Routing::UrlFor
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def edit_post_url(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def new_post_url(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def post_url(*args); end
+      #
+      #   sig { params(args: T.untyped).returns(String) }
+      #   def posts_url(*args); end
+      # end
+      # ~~~
+      #
+      # ~~~rbi
+      # # generated_mounted_helpers.rbi
+      # # typed: true
+      # module GeneratedMountedHelpers
+      #   sig { returns(Blog::Engine::GeneratedRoutesProxy) }
+      #   def articles; end
+      #
+      #   sig { returns(GeneratedRoutesProxy) }
+      #   def main_app; end
+      # end
+      # ~~~
+      #
+      # ~~~rbi
+      # # generated_routes_proxy.rbi
+      # # typed: true
+      # class GeneratedRoutesProxy < ::ActionDispatch::Routing::RoutesProxy
+      #   include GeneratedPathHelpersModule
+      #   include GeneratedUrlHelpersModule
+      # end
+      # ~~~
+      #
+      # ~~~rbi
+      # # blog/engine/generated_routes_proxy.rbi
+      # # typed: true
+      # class Blog::Engine::GeneratedRoutesProxy < ::ActionDispatch::Routing::RoutesProxy
+      #   include Blog::Engine::GeneratedPathHelpersModule
+      #   include Blog::Engine::GeneratedUrlHelpersModule
+      # end
+      # ~~~
+      #
       #: [ConstantType = Module[top]]
       class UrlHelpers < Compiler
         # @override
@@ -87,14 +190,25 @@ module Tapioca
           when GeneratedPathHelpersModule.singleton_class, GeneratedUrlHelpersModule.singleton_class
             generate_module_for(root, constant)
           else
-            root.create_path(constant) do |mod|
-              create_mixins_for(mod, GeneratedUrlHelpersModule)
-              create_mixins_for(mod, GeneratedPathHelpersModule)
+            # `GeneratedMountedHelpers` is only defined when an engine is mounted (see `gather_constants`).
+            if defined?(::GeneratedMountedHelpers) && GeneratedMountedHelpers.singleton_class === constant
+              generate_mounted_helpers_module(root)
+            elsif engine_helper_module?(constant)
+              generate_module_for(root, constant)
+            else
+              generate_url_helper_includer
             end
           end
         end
 
+        # Maps each engine's mount name to its class, e.g. `{ blog: Blog::Engine }`.
+        # Populated by `gather_constants` and read when generating the mounted helpers module.
+        @engine_mount_names = {} #: Hash[Symbol, singleton(::Rails::Engine)]
+
         class << self
+          #: Hash[Symbol, singleton(::Rails::Engine)]
+          attr_reader :engine_mount_names
+
           # @override
           #: -> Enumerable[Module[top]]
           def gather_constants
@@ -110,24 +224,55 @@ module Tapioca
             Object.const_set(:GeneratedUrlHelpersModule, url_helpers_module)
             Object.const_set(:GeneratedPathHelpersModule, path_helpers_module)
 
+            @engine_mount_names = mounted_engine_names
+            engine_helper_modules = register_engine_route_helpers
+
+            # Only synthesize the mounted helpers module when at least one mounted engine
+            # contributes its own route helpers. A mount of a routeless engine (or an app with
+            # no mounts) would leave nothing but `main_app`, which we don't generate on its own.
+            # This predicate mirrors `proxied_engines` in `generate_mounted_helpers_module`.
+            mounts_engine_with_helpers = @engine_mount_names.values.any? do |engine_class|
+              name_of(engine_class) && engine_class.const_defined?(:GeneratedPathHelpersModule, false)
+            end
+
+            if mounts_engine_with_helpers
+              Object.const_set(:GeneratedMountedHelpers, Module.new)
+            end
+
             constants = all_modules.select do |mod|
               next unless name_of(mod)
 
               # Fast-path to quickly disqualify most cases
-              next false unless url_helpers_module > mod || # rubocop:disable Style/InvertibleUnlessCondition
+              has_helpers = url_helpers_module > mod ||
                 path_helpers_module > mod ||
                 url_helpers_module > mod.singleton_class ||
                 path_helpers_module > mod.singleton_class
 
+              has_helpers ||= engine_helper_modules.any? do |engine_mod|
+                engine_mod > mod || engine_mod > mod.singleton_class
+              end
+
+              next false unless has_helpers
+
               includes_helper?(mod, url_helpers_module) ||
                 includes_helper?(mod, path_helpers_module) ||
                 includes_helper?(mod.singleton_class, url_helpers_module) ||
-                includes_helper?(mod.singleton_class, path_helpers_module)
+                includes_helper?(mod.singleton_class, path_helpers_module) ||
+                engine_helper_modules.any? { |engine_mod| includes_helper?(mod, engine_mod) || includes_helper?(mod.singleton_class, engine_mod) }
             end
 
-            constants.concat(NON_DISCOVERABLE_INCLUDERS).push(GeneratedUrlHelpersModule, GeneratedPathHelpersModule)
+            constants
+              .concat(NON_DISCOVERABLE_INCLUDERS)
+              .push(GeneratedUrlHelpersModule, GeneratedPathHelpersModule)
+              .concat(engine_helper_modules)
+
+            constants.push(GeneratedMountedHelpers) if defined?(GeneratedMountedHelpers)
+
+            constants
           end
 
+          private
+
           #: -> Array[Module[top]]
           def gather_non_discoverable_includers
             [].tap do |includers|
@@ -141,10 +286,59 @@ module Tapioca
             end.freeze
           end
 
+          # Maps each mounted engine's mount name to its class (e.g. `{ articles: Blog::Engine }`).
+          # Reads the same route table that `bin/rails routes` inspects: a mounted engine appears
+          # as a route whose endpoint is the engine (`app.engine?`), with the mount name (or `as:`
+          # alias) as the route name.
+          #: -> Hash[Symbol, singleton(::Rails::Engine)]
+          def mounted_engine_names
+            Rails.application.routes.routes.each_with_object({}) do |route, mapping|
+              app = route.app
+              next unless app.respond_to?(:engine?) && app.engine?
+
+              name = route.name
+              next unless name
+
+              mapping[name.to_sym] = app.rack_app
+            end
+          end
+
+          # Registers engine-scoped `GeneratedPathHelpersModule`/`GeneratedUrlHelpersModule`
+          # constants on each engine with routes, and returns those helper modules.
+          #: -> Array[Module[top]]
+          def register_engine_route_helpers
+            engine_helper_modules = [] #: Array[Module[top]]
+
+            Rails.application.railties.grep(::Rails::Engine).each do |engine_instance|
+              engine_class = engine_instance.class
+              next if engine_class == Rails.application.class
+
+              engine_path_helpers = engine_instance.routes.named_routes.path_helpers_module
+              engine_url_helpers = engine_instance.routes.named_routes.url_helpers_module
+
+              # Skip engines with no routes
+              next if engine_path_helpers.instance_methods(false).empty? &&
+                engine_url_helpers.instance_methods(false).empty?
+
+              unless engine_class.const_defined?(:GeneratedPathHelpersModule, false)
+                engine_class.const_set(:GeneratedPathHelpersModule, engine_path_helpers)
+              end
+
+              unless engine_class.const_defined?(:GeneratedUrlHelpersModule, false)
+                engine_class.const_set(:GeneratedUrlHelpersModule, engine_url_helpers)
+              end
+
+              engine_helper_modules << engine_class.const_get(:GeneratedPathHelpersModule)
+              engine_helper_modules << engine_class.const_get(:GeneratedUrlHelpersModule)
+            end
+
+            engine_helper_modules
+          end
+
           # Returns `true` if `mod` "directly" includes `helper`.
           # For classes, this method will return false if the `helper` is included only by a superclass
           #: (Module[top] mod, Module[top] helper) -> bool
-          private def includes_helper?(mod, helper)
+          def includes_helper?(mod, helper)
             ancestors = ancestors_of(mod)
 
             own_ancestors = if Class === mod && (superclass = superclass_of(mod))
@@ -178,6 +372,116 @@ module Tapioca
           end
         end
 
+        #: (RBI::Tree root) -> void
+        def generate_mounted_helpers_module(root)
+          # Mount name => engine name, for mounted engines that actually expose helper modules.
+          # Routeless engines (no `GeneratedPathHelpersModule`) and anonymous engines get no proxy.
+          # (If *every* mounted engine is routeless, `gather_constants` doesn't generate this module.)
+          proxied_engines = self.class.engine_mount_names.filter_map do |mount_name, engine_class|
+            engine_name = name_of(engine_class)
+            next unless engine_name
+            next unless engine_class.const_defined?(:GeneratedPathHelpersModule, false)
+
+            [mount_name, engine_name]
+          end
+
+          root.create_module("GeneratedMountedHelpers") do |mod|
+            mod.create_method(
+              "main_app",
+              return_type: "GeneratedRoutesProxy",
+            )
+
+            proxied_engines.each do |mount_name, engine_name|
+              mod.create_method(
+                mount_name.to_s,
+                return_type: "#{engine_name}::GeneratedRoutesProxy",
+              )
+            end
+          end
+
+          # The application's own RoutesProxy subclass, returned by `main_app`. Mirrors the
+          # engine proxies below so that `main_app.post_path` & co. type-check.
+          root.create_class("GeneratedRoutesProxy", superclass_name: "::ActionDispatch::Routing::RoutesProxy") do |klass|
+            klass.create_include("GeneratedPathHelpersModule")
+            klass.create_include("GeneratedUrlHelpersModule")
+          end
+
+          # One RoutesProxy subclass per engine, `uniq` since an engine can be mounted under
+          # several names but needs only a single proxy class.
+          proxied_engines.map { |_mount_name, engine_name| engine_name }.uniq.each do |engine_name|
+            proxy_class_name = "#{engine_name}::GeneratedRoutesProxy"
+            path_helpers_name = "#{engine_name}::GeneratedPathHelpersModule"
+            url_helpers_name = "#{engine_name}::GeneratedUrlHelpersModule"
+
+            root.create_class(proxy_class_name, superclass_name: "::ActionDispatch::Routing::RoutesProxy") do |klass|
+              klass.create_include(path_helpers_name)
+              klass.create_include(url_helpers_name)
+            end
+          end
+        end
+
+        #: (Module[top] mod) -> bool
+        def engine_helper_module?(mod)
+          Rails.application.railties.grep(::Rails::Engine).any? do |engine_instance|
+            engine_class = engine_instance.class
+            next false if engine_class == Rails.application.class
+            next false unless engine_class.const_defined?(:GeneratedPathHelpersModule, false)
+
+            mod == engine_class.const_get(:GeneratedPathHelpersModule) ||
+              mod == engine_class.const_get(:GeneratedUrlHelpersModule)
+          end
+        end
+
+        #: -> void
+        def generate_url_helper_includer
+          root.create_path(constant) do |mod|
+            create_mixins_for(mod, GeneratedUrlHelpersModule)
+            create_mixins_for(mod, GeneratedPathHelpersModule)
+
+            # GeneratedMountedHelpers is only synthesized when an engine is mounted (see
+            # `gather_constants`). It is a fresh `Module.new` used purely for naming, so we
+            # check against the real `mounted_helpers` module for ancestor detection. Only
+            # controllers/framework classes actually have `mounted_helpers` in their ancestor
+            # chain; plain url_helpers includers do not.
+            if defined?(::GeneratedMountedHelpers)
+              mounted_helpers = Rails.application.routes.mounted_helpers
+              include_mounted = constant.ancestors.include?(mounted_helpers) ||
+                NON_DISCOVERABLE_INCLUDERS.include?(constant)
+              extend_mounted = constant.singleton_class.ancestors.include?(mounted_helpers)
+
+              mod.create_include("GeneratedMountedHelpers") if include_mounted
+              mod.create_extend("GeneratedMountedHelpers") if extend_mounted
+            end
+
+            create_engine_helper_mixins(mod)
+          end
+        end
+
+        #: (RBI::Scope mod) -> void
+        def create_engine_helper_mixins(mod)
+          Rails.application.railties.grep(::Rails::Engine).each do |engine_instance|
+            engine_class = engine_instance.class
+            next if engine_class == Rails.application.class
+            next unless engine_class.const_defined?(:GeneratedPathHelpersModule, false)
+
+            create_engine_helper_mixin(mod, engine_class.const_get(:GeneratedUrlHelpersModule))
+            create_engine_helper_mixin(mod, engine_class.const_get(:GeneratedPathHelpersModule))
+          end
+        end
+
+        #: (RBI::Scope mod, Module[top] helper_module) -> void
+        def create_engine_helper_mixin(mod, helper_module)
+          # Engine helpers must be added only when actually present; the
+          # NON_DISCOVERABLE_INCLUDERS fallback is only valid for main app helpers.
+          if constant.ancestors.include?(helper_module)
+            mod.create_include(T.must(helper_module.name))
+          end
+
+          if constant.singleton_class.ancestors.include?(helper_module)
+            mod.create_extend(T.must(helper_module.name))
+          end
+        end
+
         #: (RBI::Scope mod, Module[top] helper_module) -> void
         def create_mixins_for(mod, helper_module)
           include_helper = constant.ancestors.include?(helper_module) || NON_DISCOVERABLE_INCLUDERS.include?(constant)

data/lib/tapioca/dsl/compilers.rb

@@ -13,7 +13,7 @@ module Tapioca
       NAMESPACES = [
         "#{name}::", # compilers in this namespace
         "::", # compilers that need to be fully namespaced
-      ] #: Array[String]
+      ].freeze #: Array[String]
     end
   end
 end