zeitwerk 2.6.13 → 2.7.2

data/lib/zeitwerk/loader/helpers.rb

@@ -30,27 +30,43 @@ module Zeitwerk::Loader::Helpers
 
       if dir?(abspath)
         next if roots.key?(abspath)
-        next if !has_at_least_one_ruby_file?(abspath)
+
+        if !has_at_least_one_ruby_file?(abspath)
+          log("directory #{abspath} is ignored because it has no Ruby files") if logger
+          next
+        end
+
+        ftype = :directory
       else
         next unless ruby?(abspath)
+        ftype = :file
       end
 
       # We freeze abspath because that saves allocations when passed later to
       # File methods. See #125.
-      yield basename, abspath.freeze
+      yield basename, abspath.freeze, ftype
     end
   end
 
+  # Looks for a Ruby file using breadth-first search. This type of search is
+  # important to list as less directories as possible and return fast in the
+  # common case in which there are Ruby files.
+  #
   # @sig (String) -> bool
   private def has_at_least_one_ruby_file?(dir)
     to_visit = [dir]
 
-    while dir = to_visit.shift
-      ls(dir) do |_basename, abspath|
+    while (dir = to_visit.shift)
+      Dir.each_child(dir) do |basename|
+        next if hidden?(basename)
+
+        abspath = File.join(dir, basename)
+        next if ignored_path?(abspath)
+
         if dir?(abspath)
-          to_visit << abspath
+          to_visit << abspath unless roots.key?(abspath)
         else
-          return true
+          return true if ruby?(abspath)
         end
       end
     end
@@ -82,64 +98,7 @@ module Zeitwerk::Loader::Helpers
     end
   end
 
-  # --- Constants ---------------------------------------------------------------------------------
-
-  # The autoload? predicate takes into account the ancestor chain of the
-  # receiver, like const_defined? and other methods in the constants API do.
-  #
-  # For example, given
-  #
-  #   class A
-  #     autoload :X, "x.rb"
-  #   end
-  #
-  #   class B < A
-  #   end
-  #
-  # B.autoload?(:X) returns "x.rb".
-  #
-  # We need a way to strictly check in parent ignoring ancestors.
-  #
-  # @sig (Module, Symbol) -> String?
-  if method(:autoload?).arity == 1
-    private def strict_autoload_path(parent, cname)
-      parent.autoload?(cname) if cdef?(parent, cname)
-    end
-  else
-    private def strict_autoload_path(parent, cname)
-      parent.autoload?(cname, false)
-    end
-  end
-
-  # @sig (Module, Symbol) -> String
-  if Symbol.method_defined?(:name)
-    # Symbol#name was introduced in Ruby 3.0. It returns always the same
-    # frozen object, so we may save a few string allocations.
-    private def cpath(parent, cname)
-      Object == parent ? cname.name : "#{real_mod_name(parent)}::#{cname.name}"
-    end
-  else
-    private def cpath(parent, cname)
-      Object == parent ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
-    end
-  end
-
-  # @sig (Module, Symbol) -> bool
-  private def cdef?(parent, cname)
-    parent.const_defined?(cname, false)
-  end
-
-  # @raise [NameError]
-  # @sig (Module, Symbol) -> Object
-  private def cget(parent, cname)
-    parent.const_get(cname, false)
-  end
-
-  # @raise [NameError]
-  # @sig (Module, Symbol) -> Object
-  private def crem(parent, cname)
-    parent.__send__(:remove_const, cname)
-  end
+  # --- Inflection --------------------------------------------------------------------------------
 
   CNAME_VALIDATOR = Module.new
   private_constant :CNAME_VALIDATOR

data/lib/zeitwerk/loader.rb

@@ -22,17 +22,40 @@ module Zeitwerk
     private_constant :MUTEX
 
     # Maps absolute paths for which an autoload has been set ---and not
-    # executed--- to their corresponding parent class or module and constant
-    # name.
+    # executed--- to their corresponding Zeitwerk::Cref object.
     #
-    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
-    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
+    #   "/Users/fxn/blog/app/models/user.rb"          => #<Zeitwerk::Cref:... @mod=Object, @cname=:User, ...>,
+    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => #<Zeitwerk::Cref:... @mod=Hotel, @cname=:Pricing, ...>,
     #   ...
     #
-    # @sig Hash[String, [Module, Symbol]]
+    # @sig Hash[String, Zeitwerk::Cref]
     attr_reader :autoloads
     internal :autoloads
 
+    # When the path passed to Module#autoload is in the stack of features being
+    # loaded at the moment, Ruby passes. For example, Module#autoload? returns
+    # `nil` even if the autoload has not been attempted. See
+    #
+    #     https://bugs.ruby-lang.org/issues/21035
+    #
+    # We call these "inceptions".
+    #
+    # A common case is the entry point of gems managed by Zeitwerk. Their main
+    # file is normally required and, while doing so, the loader sets an autoload
+    # on the gem namespace. That autoload hits this edge case.
+    #
+    # There is some logic that neeeds to know if an autoload for a given
+    # constant already exists. We check Module#autoload? first, and fallback to
+    # the inceptions just in case.
+    #
+    # This map keeps track of pairs (cref, autoload_path) found by the loader.
+    # The module Zeitwerk::Registry::Inceptions, on the other hand, acts as a
+    # global registry for them.
+    #
+    # @sig Zeitwerk::Cref::Map[String]
+    attr_reader :inceptions
+    internal :inceptions
+
     # We keep track of autoloaded directories to remove them from the registry
     # at the end of eager loading.
     #
@@ -43,46 +66,31 @@ module Zeitwerk
     attr_reader :autoloaded_dirs
     internal :autoloaded_dirs
 
-    # Stores metadata needed for unloading. Its entries look like this:
-    #
-    #   "Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
-    #
-    # The cpath as key helps implementing unloadable_cpath? The file name is
-    # stored in order to be able to delete it from $LOADED_FEATURES, and the
-    # pair [Module, Symbol] is used to remove_const the constant from the class
-    # or module object.
+    # If reloading is enabled, this collection maps autoload paths to their
+    # autoloaded crefs.
     #
-    # If reloading is enabled, this hash is filled as constants are autoloaded
-    # or eager loaded. Otherwise, the collection remains empty.
+    # On unload, the autoload paths are passed to callbacks, files deleted from
+    # $LOADED_FEATURES, and the crefs are deleted.
     #
-    # @sig Hash[String, [String, [Module, Symbol]]]
+    # @sig Hash[String, Zeitwerk::Cref]
     attr_reader :to_unload
     internal :to_unload
 
-    # Maps namespace constant paths to their respective directories.
+    # Maps namespace crefs to the directories that conform the namespace.
     #
-    # For example, given this mapping:
+    # When these crefs get defined we know their children are spread over those
+    # directories. We'll visit them to set up the corresponding autoloads.
     #
-    #   "Admin" => [
-    #     "/Users/fxn/blog/app/controllers/admin",
-    #     "/Users/fxn/blog/app/models/admin",
-    #     ...
-    #   ]
-    #
-    # when `Admin` gets defined we know that it plays the role of a namespace
-    # and that its children are spread over those directories. We'll visit them
-    # to set up the corresponding autoloads.
-    #
-    # @sig Hash[String, Array[String]]
+    # @sig Zeitwerk::Cref::Map[String]
     attr_reader :namespace_dirs
     internal :namespace_dirs
 
     # A shadowed file is a file managed by this loader that is ignored when
     # setting autoloads because its matching constant is already taken.
     #
-    # This private set is populated as we descend. For example, if the loader
-    # has only scanned the top-level, `shadowed_files` does not have shadowed
-    # files that may exist deep in the project tree yet.
+    # This private set is populated lazily, as we descend. For example, if the
+    # loader has only scanned the top-level, `shadowed_files` does not have the
+    # shadowed files that may exist deep in the project tree.
     #
     # @sig Set[String]
     attr_reader :shadowed_files
@@ -100,9 +108,10 @@ module Zeitwerk
       super
 
       @autoloads       = {}
+      @inceptions      = Zeitwerk::Cref::Map.new
       @autoloaded_dirs = []
       @to_unload       = {}
-      @namespace_dirs  = Hash.new { |h, cpath| h[cpath] = [] }
+      @namespace_dirs  = Zeitwerk::Cref::Map.new
       @shadowed_files  = Set.new
       @setup           = false
       @eager_loaded    = false
@@ -154,32 +163,32 @@ module Zeitwerk
         # is enough.
         unloaded_files = Set.new
 
-        autoloads.each do |abspath, (parent, cname)|
-          if parent.autoload?(cname)
-            unload_autoload(parent, cname)
+        autoloads.each do |abspath, cref|
+          if cref.autoload?
+            unload_autoload(cref)
           else
             # Could happen if loaded with require_relative. That is unsupported,
             # and the constant path would escape unloadable_cpath? This is just
             # defensive code to clean things up as much as we are able to.
-            unload_cref(parent, cname)
+            unload_cref(cref)
             unloaded_files.add(abspath) if ruby?(abspath)
           end
         end
 
-        to_unload.each do |cpath, (abspath, (parent, cname))|
+        to_unload.each do |abspath, cref|
           unless on_unload_callbacks.empty?
             begin
-              value = cget(parent, cname)
+              value = cref.get
             rescue ::NameError
               # Perhaps the user deleted the constant by hand, or perhaps an
               # autoload failed to define the expected constant but the user
               # rescued the exception.
             else
-              run_on_unload_callbacks(cpath, value, abspath)
+              run_on_unload_callbacks(cref, value, abspath)
             end
           end
 
-          unload_cref(parent, cname)
+          unload_cref(cref)
           unloaded_files.add(abspath) if ruby?(abspath)
         end
 
@@ -204,8 +213,10 @@ module Zeitwerk
         namespace_dirs.clear
         shadowed_files.clear
 
+        unregister_inceptions
+        unregister_explicit_namespaces
+
         Registry.on_unload(self)
-        ExplicitNamespace.__unregister_loader(self)
 
         @setup        = false
         @eager_loaded = false
@@ -230,68 +241,107 @@ module Zeitwerk
       setup
     end
 
-  # @sig (String | Pathname) -> String?
-  def cpath_expected_at(path)
-    abspath = File.expand_path(path)
+    # Returns a hash that maps the absolute paths of the managed files and
+    # directories to their respective expected constant paths.
+    #
+    # @sig () -> Hash[String, String]
+    def all_expected_cpaths
+      result = {}
 
-    raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
+      actual_roots.each do |root_dir, root_namespace|
+        queue = [[root_dir, real_mod_name(root_namespace)]]
 
-    return unless dir?(abspath) || ruby?(abspath)
-    return if ignored_path?(abspath)
+        while (dir, cpath = queue.shift)
+          result[dir] = cpath
 
-    paths = []
+          prefix = cpath == "Object" ? "" : cpath + "::"
 
-    if ruby?(abspath)
-      basename = File.basename(abspath, ".rb")
-      return if hidden?(basename)
+          ls(dir) do |basename, abspath, ftype|
+            if ftype == :file
+              basename.delete_suffix!(".rb")
+              result[abspath] = prefix + inflector.camelize(basename, abspath)
+            else
+              if collapse?(abspath)
+                queue << [abspath, cpath]
+              else
+                queue << [abspath, prefix + inflector.camelize(basename, abspath)]
+              end
+            end
+          end
+        end
+      end
 
-      paths << [basename, abspath]
-      walk_up_from = File.dirname(abspath)
-    else
-      walk_up_from = abspath
+      result
     end
 
-    root_namespace = nil
+    # @sig (String | Pathname) -> String?
+    def cpath_expected_at(path)
+      abspath = File.expand_path(path)
 
-    walk_up(walk_up_from) do |dir|
-      break if root_namespace = roots[dir]
-      return if ignored_path?(dir)
+      raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
 
-      basename = File.basename(dir)
-      return if hidden?(basename)
+      return unless dir?(abspath) || ruby?(abspath)
+      return if ignored_path?(abspath)
 
-      paths << [basename, abspath] unless collapse?(dir)
-    end
+      paths = []
 
-    return unless root_namespace
+      if ruby?(abspath)
+        basename = File.basename(abspath, ".rb")
+        return if hidden?(basename)
 
-    if paths.empty?
-      real_mod_name(root_namespace)
-    else
-      cnames = paths.reverse_each.map { |b, a| cname_for(b, a) }
+        paths << [basename, abspath]
+        walk_up_from = File.dirname(abspath)
+      else
+        walk_up_from = abspath
+      end
 
-      if root_namespace == Object
-        cnames.join("::")
+      root_namespace = nil
+
+      walk_up(walk_up_from) do |dir|
+        break if root_namespace = roots[dir]
+        return if ignored_path?(dir)
+
+        basename = File.basename(dir)
+        return if hidden?(basename)
+
+        paths << [basename, abspath] unless collapse?(dir)
+      end
+
+      return unless root_namespace
+
+      if paths.empty?
+        real_mod_name(root_namespace)
       else
-        "#{real_mod_name(root_namespace)}::#{cnames.join("::")}"
+        cnames = paths.reverse_each.map { |b, a| cname_for(b, a) }
+
+        if root_namespace == Object
+          cnames.join("::")
+        else
+          "#{real_mod_name(root_namespace)}::#{cnames.join("::")}"
+        end
       end
     end
-  end
 
     # Says if the given constant path would be unloaded on reload. This
     # predicate returns `false` if reloading is disabled.
     #
+    # This is an undocumented method that I wrote to help transition from the
+    # classic autoloader in Rails. Its usage was removed from Rails in 7.0.
+    #
     # @sig (String) -> bool
     def unloadable_cpath?(cpath)
-      to_unload.key?(cpath)
+      unloadable_cpaths.include?(cpath)
     end
 
     # Returns an array with the constant paths that would be unloaded on reload.
     # This predicate returns an empty array if reloading is disabled.
     #
+    # This is an undocumented method that I wrote to help transition from the
+    # classic autoloader in Rails. Its usage was removed from Rails in 7.0.
+    #
     # @sig () -> Array[String]
     def unloadable_cpaths
-      to_unload.keys.freeze
+      to_unload.values.map(&:path)
     end
 
     # This is a dangerous method.
@@ -299,8 +349,9 @@ module Zeitwerk
     # @experimental
     # @sig () -> void
     def unregister
+      unregister_inceptions
+      unregister_explicit_namespaces
       Registry.unregister_loader(self)
-      ExplicitNamespace.__unregister_loader(self)
     end
 
     # The return value of this predicate is only meaningful if the loader has
@@ -408,24 +459,25 @@ module Zeitwerk
 
     # @sig (String, Module) -> void
     private def define_autoloads_for_dir(dir, parent)
-      ls(dir) do |basename, abspath|
-        if ruby?(basename)
+      ls(dir) do |basename, abspath, ftype|
+        if ftype == :file
           basename.delete_suffix!(".rb")
-          autoload_file(parent, cname_for(basename, abspath), abspath)
+          cref = Cref.new(parent, cname_for(basename, abspath))
+          autoload_file(cref, abspath)
         else
           if collapse?(abspath)
             define_autoloads_for_dir(abspath, parent)
           else
-            autoload_subdir(parent, cname_for(basename, abspath), abspath)
+            cref = Cref.new(parent, cname_for(basename, abspath))
+            autoload_subdir(cref, abspath)
           end
         end
       end
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def autoload_subdir(parent, cname, subdir)
-      if autoload_path = autoload_path_set_by_me_for?(parent, cname)
-        cpath = cpath(parent, cname)
+    private def autoload_subdir(cref, subdir)
+      if autoload_path = autoload_path_set_by_me_for?(cref)
         if ruby?(autoload_path)
           # Scanning visited a Ruby file first, and now a directory for the same
           # constant has been found. This means we are dealing with an explicit
@@ -434,94 +486,107 @@ module Zeitwerk
           # Registering is idempotent, and we have to keep the autoload pointing
           # to the file. This may run again if more directories are found later
           # on, no big deal.
-          register_explicit_namespace(cpath)
+          register_explicit_namespace(cref)
         end
         # If the existing autoload points to a file, it has to be preserved, if
         # not, it is fine as it is. In either case, we do not need to override.
         # Just remember the subdirectory conforms this namespace.
-        namespace_dirs[cpath] << subdir
-      elsif !cdef?(parent, cname)
+        namespace_dirs.get_or_set(cref) { [] } << subdir
+      elsif !cref.defined?
         # First time we find this namespace, set an autoload for it.
-        namespace_dirs[cpath(parent, cname)] << subdir
-        define_autoload(parent, cname, subdir)
+        namespace_dirs.get_or_set(cref) { [] } << subdir
+        define_autoload(cref, subdir)
       else
         # For whatever reason the constant that corresponds to this namespace has
         # already been defined, we have to recurse.
-        log("the namespace #{cpath(parent, cname)} already exists, descending into #{subdir}") if logger
-        define_autoloads_for_dir(subdir, cget(parent, cname))
+        log("the namespace #{cref} already exists, descending into #{subdir}") if logger
+        define_autoloads_for_dir(subdir, cref.get)
       end
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def autoload_file(parent, cname, file)
-      if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
+    private def autoload_file(cref, file)
+      if autoload_path = cref.autoload? || Registry::Inceptions.registered?(cref)
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
           shadowed_files << file
           log("file #{file} is ignored because #{autoload_path} has precedence") if logger
         else
-          promote_namespace_from_implicit_to_explicit(
-            dir:    autoload_path,
-            file:   file,
-            parent: parent,
-            cname:  cname
-          )
+          promote_namespace_from_implicit_to_explicit(dir: autoload_path, file: file, cref: cref)
         end
-      elsif cdef?(parent, cname)
+      elsif cref.defined?
         shadowed_files << file
-        log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
+        log("file #{file} is ignored because #{cref} is already defined") if logger
       else
-        define_autoload(parent, cname, file)
+        define_autoload(cref, file)
       end
     end
 
     # `dir` is the directory that would have autovivified a namespace. `file` is
     # the file where we've found the namespace is explicitly defined.
     #
-    # @sig (dir: String, file: String, parent: Module, cname: Symbol) -> void
-    private def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
+    # @sig (dir: String, file: String, cref: Zeitwerk::Cref) -> void
+    private def promote_namespace_from_implicit_to_explicit(dir:, file:, cref:)
       autoloads.delete(dir)
       Registry.unregister_autoload(dir)
 
-      log("earlier autoload for #{cpath(parent, cname)} discarded, it is actually an explicit namespace defined in #{file}") if logger
+      log("earlier autoload for #{cref} discarded, it is actually an explicit namespace defined in #{file}") if logger
 
-      define_autoload(parent, cname, file)
-      register_explicit_namespace(cpath(parent, cname))
+      # Order matters: When Module#const_added is triggered by the autoload, we
+      # don't want the namespace to be registered yet.
+      define_autoload(cref, file)
+      register_explicit_namespace(cref)
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def define_autoload(parent, cname, abspath)
-      parent.autoload(cname, abspath)
+    private def define_autoload(cref, abspath)
+      cref.autoload(abspath)
 
       if logger
         if ruby?(abspath)
-          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{abspath}")
+          log("autoload set for #{cref}, to be loaded from #{abspath}")
         else
-          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{abspath}")
+          log("autoload set for #{cref}, to be autovivified from #{abspath}")
         end
       end
 
-      autoloads[abspath] = [parent, cname]
+      autoloads[abspath] = cref
       Registry.register_autoload(self, abspath)
 
-      # See why in the documentation of Zeitwerk::Registry.inceptions.
-      unless parent.autoload?(cname)
-        Registry.register_inception(cpath(parent, cname), abspath, self)
-      end
+      register_inception(cref, abspath) unless cref.autoload?
     end
 
     # @sig (Module, Symbol) -> String?
-    private def autoload_path_set_by_me_for?(parent, cname)
-      if autoload_path = strict_autoload_path(parent, cname)
+    private def autoload_path_set_by_me_for?(cref)
+      if autoload_path = cref.autoload?
         autoload_path if autoloads.key?(autoload_path)
       else
-        Registry.inception?(cpath(parent, cname))
+        inceptions[cref]
       end
     end
 
-    # @sig (String) -> void
-    private def register_explicit_namespace(cpath)
-      ExplicitNamespace.__register(cpath, self)
+    # @sig (Zeitwerk::Cref) -> void
+    private def register_explicit_namespace(cref)
+      Registry::ExplicitNamespaces.__register(cref, self)
+    end
+
+    # @sig () -> void
+    private def unregister_explicit_namespaces
+      Registry::ExplicitNamespaces.__unregister_loader(self)
+    end
+
+    # @sig (Zeitwerk::Cref, String) -> void
+    private def register_inception(cref, abspath)
+      inceptions[cref] = abspath
+      Registry::Inceptions.register(cref, abspath)
+    end
+
+    # @sig () -> void
+    private def unregister_inceptions
+      inceptions.each_key do |cref|
+        Registry::Inceptions.unregister(cref)
+      end
+      inceptions.clear
     end
 
     # @sig (String) -> void
@@ -548,29 +613,29 @@ module Zeitwerk
       end
     end
 
-    # @sig (String, Object, String) -> void
-    private def run_on_unload_callbacks(cpath, value, abspath)
+    # @sig (String, top, String) -> void
+    private def run_on_unload_callbacks(cref, value, abspath)
       # Order matters. If present, run the most specific one.
-      on_unload_callbacks[cpath]&.each { |c| c.call(value, abspath) }
-      on_unload_callbacks[:ANY]&.each { |c| c.call(cpath, value, abspath) }
+      on_unload_callbacks[cref.path]&.each { |c| c.call(value, abspath) }
+      on_unload_callbacks[:ANY]&.each { |c| c.call(cref.path, value, abspath) }
     end
 
     # @sig (Module, Symbol) -> void
-    private def unload_autoload(parent, cname)
-      crem(parent, cname)
-      log("autoload for #{cpath(parent, cname)} removed") if logger
+    private def unload_autoload(cref)
+      cref.remove
+      log("autoload for #{cref} removed") if logger
     end
 
     # @sig (Module, Symbol) -> void
-    private def unload_cref(parent, cname)
+    private def unload_cref(cref)
       # Let's optimistically remove_const. The way we use it, this is going to
       # succeed always if all is good.
-      crem(parent, cname)
+      cref.remove
     rescue ::NameError
       # There are a few edge scenarios in which this may happen. If the constant
       # is gone, that is OK, anyway.
     else
-      log("#{cpath(parent, cname)} unloaded") if logger
+      log("#{cref} unloaded") if logger
     end
   end
 end

data/lib/zeitwerk/null_inflector.rb

@@ -1,4 +1,5 @@
 class Zeitwerk::NullInflector
+  # @sig (String, String) -> String
   def camelize(basename, _abspath)
     basename
   end

data/lib/zeitwerk/real_mod_name.rb

@@ -10,13 +10,7 @@ module Zeitwerk::RealModName
   # The name method can be overridden, hence the indirection in this method.
   #
   # @sig (Module) -> String?
-  if UnboundMethod.method_defined?(:bind_call)
-    def real_mod_name(mod)
-      UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
-    end
-  else
-    def real_mod_name(mod)
-      UNBOUND_METHOD_MODULE_NAME.bind(mod).call
-    end
+  def real_mod_name(mod)
+    UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
   end
 end