zeitwerk 2.7.1 → 2.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aba46812169c8e26085b099c708093b00a29bfd39e8d8210d29bc99e7df0e7fa
-  data.tar.gz: 0fc20386009d52d21a0cb79a64c5d800f7aecfce5a38e8430a10dc5d04c2609d
+  metadata.gz: 1a07f90eb2f155582d05f58527ffcbc2f4d76c9a1983260ca8d527becaeb7972
+  data.tar.gz: 65e8dc78ca8e6de674f0fc7d88aad5c9bad0d7687bc9ed26f93d6fa0e6d18e90
 SHA512:
-  metadata.gz: 3edac5ad6f940caa70c4cac093bf271b8399b078d7124f450513c963ec5099e9b9082841ceb9893b81f1edf8e34dc642ec811403415fb230211670c63a950766
-  data.tar.gz: 47339a8b35dc06108fde9aadd62e83b1ea4e4ef22854c31849069f09ece1115dce07d63ec354fe96fbc599bba411ecff48db6a8b0c8b150ad7ee016787e9d75c
+  metadata.gz: d7b9d13e3d3d5bf0497ec259bf0817256586e245f7d47c951b8392784f715bc71c20d0ec3c9e465077da6d8e729ca6888fbaaa24820fe4459771e29340ee6d05
+  data.tar.gz: 8b1322d36bc9115a56b6abab6be9549c868e0edd2025fe82dd2c5d0abb082fac8532c82ed03f895d34f2875f27b160f4861185112c4aef2a3129e46569115c0f

data/lib/zeitwerk/core_ext/module.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-module Zeitwerk::ConstAdded
+module Zeitwerk::ConstAdded # :nodoc:
+  # @sig (Symbol) -> void
   def const_added(cname)
-    if loader = Zeitwerk::ExplicitNamespace.__loader_for(self, cname)
+    if loader = Zeitwerk::Registry::ExplicitNamespaces.__loader_for(self, cname)
       namespace = const_get(cname, false)
 
       unless namespace.is_a?(Module)
         cref = Zeitwerk::Cref.new(self, cname)
-        raise Zeitwerk::Error, "#{cref.path} is expected to be a namespace, should be a class or module (got #{namespace.class})"
+        raise Zeitwerk::Error, "#{cref} is expected to be a namespace, should be a class or module (got #{namespace.class})"
       end
 
-      loader.on_namespace_loaded(namespace)
+      loader.__on_namespace_loaded(Zeitwerk::Cref.new(self, cname), namespace)
     end
     super
   end

data/lib/zeitwerk/cref/map.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# This class emulates a hash table whose keys are of type Zeitwerk::Cref.
+#
+# It is a synchronized 2-level hash. The keys of the top one, stored in `@map`,
+# are class and module objects, but their hash code is forced to be their object
+# IDs (see why below). Then, each one of them stores a hash table keyed on
+# constant names as symbols. We finally store the values in those.
+#
+# For example, if we store values 0, 1, and 2 for the crefs that would
+# correspond to `M::X`, `M::Y`, and `N::Z`, the map will look like this:
+#
+#   { M => { X: 0, :Y => 1 }, N => { Z: 2 } }
+#
+# This structure is internal, so only the needed interface is implemented.
+#
+# Why not use tables that map pairs [Module, Symbol] to their values? Because
+# class and module objects are not guaranteed to be hashable, the `hash` method
+# may have been overridden:
+#
+#   https://github.com/fxn/zeitwerk/issues/188
+#
+# We can also use a 1-level hash whose keys are the corresponding class and
+# module names. In the example above it would be:
+#
+#   { "M::X" => 0, "M::Y" => 1, "N::Z" => 2 }
+#
+# The gem used this approach for several years.
+#
+# Another option would be to make crefs hashable. I tried with hash code
+#
+#   real_mod_hash(mod) ^ cname.hash
+#
+# and the matching eql?, but that was about 1.8x slower.
+#
+# Finally, I came with this solution which is 1.6x faster than the previous one
+# based on class and module names, even being synchronized. Also, client code
+# feels natural, since crefs are central objects in Zeitwerk's implementation.
+class Zeitwerk::Cref::Map # :nodoc: all
+  def initialize
+    @map = {}
+    @map.compare_by_identity
+    @mutex = Mutex.new
+  end
+
+  # @sig (Zeitwerk::Cref, V) -> V
+  def []=(cref, value)
+    @mutex.synchronize do
+      cnames = (@map[cref.mod] ||= {})
+      cnames[cref.cname] = value
+    end
+  end
+
+  # @sig (Zeitwerk::Cref) -> top?
+  def [](cref)
+    @mutex.synchronize do
+      @map[cref.mod]&.[](cref.cname)
+    end
+  end
+
+  # @sig (Zeitwerk::Cref, { () -> V }) -> V
+  def get_or_set(cref, &block)
+    @mutex.synchronize do
+      cnames = (@map[cref.mod] ||= {})
+      cnames.fetch(cref.cname) { cnames[cref.cname] = block.call }
+    end
+  end
+
+  # @sig (Zeitwerk::Cref) -> top?
+  def delete(cref)
+    delete_mod_cname(cref.mod, cref.cname)
+  end
+
+  # Ad-hoc for loader_for, called from const_added. That is a hot path, I prefer
+  # to not create a cref in every call, since that is global.
+  #
+  # @sig (Module, Symbol) -> top?
+  def delete_mod_cname(mod, cname)
+    @mutex.synchronize do
+      if cnames = @map[mod]
+        value = cnames.delete(cname)
+        @map.delete(mod) if cnames.empty?
+        value
+      end
+    end
+  end
+
+  # @sig (top) -> void
+  def delete_by_value(value)
+    @mutex.synchronize do
+      @map.delete_if do |mod, cnames|
+        cnames.delete_if { _2 == value }
+        cnames.empty?
+      end
+    end
+  end
+
+  # Order of yielded crefs is undefined.
+  #
+  # @sig () { (Zeitwerk::Cref) -> void } -> void
+  def each_key
+    @mutex.synchronize do
+      @map.each do |mod, cnames|
+        cnames.each_key do |cname|
+          yield Zeitwerk::Cref.new(mod, cname)
+        end
+      end
+    end
+  end
+
+  # @sig () -> void
+  def clear
+    @mutex.synchronize do
+      @map.clear
+    end
+  end
+
+  # @sig () -> bool
+  def empty? # for tests
+    @mutex.synchronize do
+      @map.empty?
+    end
+  end
+end

data/lib/zeitwerk/cref.rb

@@ -3,7 +3,7 @@
 # This private class encapsulates pairs (mod, cname).
 #
 # Objects represent the constant cname in the class or module object mod, and
-# have API to manage them that encapsulates the constants API. Examples:
+# have API to manage them. Examples:
 #
 #   cref.path
 #   cref.set(value)
@@ -11,6 +11,8 @@
 #
 # The constant may or may not exist in mod.
 class Zeitwerk::Cref
+  require_relative "cref/map"
+
   include Zeitwerk::RealModName
 
   # @sig Module
@@ -33,6 +35,7 @@ class Zeitwerk::Cref
   def path
     @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
   end
+  alias to_s path
 
   # @sig () -> String?
   def autoload?
@@ -49,13 +52,13 @@ class Zeitwerk::Cref
     @mod.const_defined?(@cname, false)
   end
 
-  # @sig (Object) -> Object
+  # @sig (top) -> top
   def set(value)
     @mod.const_set(@cname, value)
   end
 
   # @raise [NameError]
-  # @sig () -> Object
+  # @sig () -> top
   def get
     @mod.const_get(@cname, false)
   end

data/lib/zeitwerk/internal.rb

@@ -2,6 +2,7 @@
 
 # This is a private module.
 module Zeitwerk::Internal
+  # @sig (Symbol) -> void
   def internal(method_name)
     private method_name
 

data/lib/zeitwerk/loader/callbacks.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-module Zeitwerk::Loader::Callbacks
-  include Zeitwerk::RealModName
+module Zeitwerk::Loader::Callbacks # :nodoc: all
   extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
@@ -14,11 +13,11 @@ module Zeitwerk::Loader::Callbacks
     Zeitwerk::Registry.unregister_autoload(file)
 
     if cref.defined?
-      log("constant #{cref.path} loaded from file #{file}") if logger
-      to_unload[cref.path] = [file, cref] if reloading_enabled?
+      log("constant #{cref} loaded from file #{file}") if logger
+      to_unload[file] = cref if reloading_enabled?
       run_on_load_callbacks(cref.path, cref.get, file) unless on_load_callbacks.empty?
     else
-      msg = "expected file #{file} to define constant #{cref.path}, but didn't"
+      msg = "expected file #{file} to define constant #{cref}, but didn't"
       log(msg) if logger
 
       # Ruby still keeps the autoload defined, but we remove it because the
@@ -28,7 +27,7 @@ module Zeitwerk::Loader::Callbacks
       # Since the expected constant was not defined, there is nothing to unload.
       # However, if the exception is rescued and reloading is enabled, we still
       # need to deleted the file from $LOADED_FEATURES.
-      to_unload[cref.path] = [file, cref] if reloading_enabled?
+      to_unload[file] = cref if reloading_enabled?
 
       raise Zeitwerk::NameError.new(msg, cref.cname)
     end
@@ -57,7 +56,7 @@ module Zeitwerk::Loader::Callbacks
         cpath = implicit_namespace.name
         log("module #{cpath} autovivified from directory #{dir}") if logger
 
-        to_unload[cpath] = [dir, cref] if reloading_enabled?
+        to_unload[dir] = cref if reloading_enabled?
 
         # We don't unregister `dir` in the registry because concurrent threads
         # wouldn't find a loader associated to it in Kernel#require and would
@@ -65,21 +64,20 @@ module Zeitwerk::Loader::Callbacks
         # these to be able to unregister later if eager loading.
         autoloaded_dirs << dir
 
-        on_namespace_loaded(implicit_namespace)
+        on_namespace_loaded(cref, implicit_namespace)
 
         run_on_load_callbacks(cpath, implicit_namespace, dir) unless on_load_callbacks.empty?
       end
     end
   end
 
-  # Invoked when a class or module is created or reopened, either from the
-  # const_added or from module autovivification. If the namespace has matching
-  # subdirectories, we descend into them now.
+  # Invoked when a namespace is created, either from const_added or from module
+  # autovivification. If the namespace has matching subdirectories, we descend
+  # into them now.
   #
-  # @private
-  # @sig (Module) -> void
-  def on_namespace_loaded(namespace)
-    if dirs = namespace_dirs.delete(real_mod_name(namespace))
+  # @sig (Zeitwerk::Cref, Module) -> void
+  internal def on_namespace_loaded(cref, namespace)
+    if dirs = namespace_dirs.delete(cref)
       dirs.each do |dir|
         define_autoloads_for_dir(dir, namespace)
       end
@@ -88,7 +86,7 @@ module Zeitwerk::Loader::Callbacks
 
   private
 
-  # @sig (String, Object) -> void
+  # @sig (String, top, String) -> void
   def run_on_load_callbacks(cpath, value, abspath)
     # Order matters. If present, run the most specific one.
     callbacks = reloading_enabled? ? on_load_callbacks[cpath] : on_load_callbacks.delete(cpath)

data/lib/zeitwerk/loader/config.rb

@@ -71,15 +71,15 @@ module Zeitwerk::Loader::Config
 
   # User-oriented callbacks to be fired when a constant is loaded.
   #
-  # @sig Hash[String, Array[{ (Object, String) -> void }]]
-  #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
+  # @sig Hash[String, Array[{ (top, String) -> void }]]
+  #      Hash[Symbol, Array[{ (String, top, String) -> void }]]
   attr_reader :on_load_callbacks
   private :on_load_callbacks
 
   # User-oriented callbacks to be fired before constants are removed.
   #
-  # @sig Hash[String, Array[{ (Object, String) -> void }]]
-  #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
+  # @sig Hash[String, Array[{ (top, String) -> void }]]
+  #      Hash[Symbol, Array[{ (String, top, String) -> void }]]
   attr_reader :on_unload_callbacks
   private :on_unload_callbacks
 
@@ -247,8 +247,8 @@ module Zeitwerk::Loader::Config
   #   end
   #
   # @raise [TypeError]
-  # @sig (String) { (Object, String) -> void } -> void
-  #      (:ANY) { (String, Object, String) -> void } -> void
+  # @sig (String) { (top, String) -> void } -> void
+  #      (:ANY) { (String, top, String) -> void } -> void
   def on_load(cpath = :ANY, &block)
     raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
 
@@ -272,8 +272,8 @@ module Zeitwerk::Loader::Config
   #   end
   #
   # @raise [TypeError]
-  # @sig (String) { (Object) -> void } -> void
-  #      (:ANY) { (String, Object) -> void } -> void
+  # @sig (String) { (top) -> void } -> void
+  #      (:ANY) { (String, top) -> void } -> void
   def on_unload(cpath = :ANY, &block)
     raise TypeError, "on_unload only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
 

data/lib/zeitwerk/loader.rb

@@ -32,6 +32,30 @@ module Zeitwerk
     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.
     #
@@ -42,48 +66,31 @@ module Zeitwerk
     attr_reader :autoloaded_dirs
     internal :autoloaded_dirs
 
-    # Stores metadata needed for unloading. Its entries look like this:
+    # If reloading is enabled, this collection maps autoload paths to their
+    # autoloaded crefs.
     #
-    #   "Admin::Role" => [
-    #     ".../admin/role.rb",
-    #     #<Zeitwerk::Cref:... @mod=Admin, @cname=:Role, ...>
-    #   ]
+    # On unload, the autoload paths are passed to callbacks, files deleted from
+    # $LOADED_FEATURES, and the crefs are deleted.
     #
-    # 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
-    # cref is used to remove the constant from the parent class or module.
-    #
-    # If reloading is enabled, this hash is filled as constants are autoloaded
-    # or eager loaded. Otherwise, the collection remains empty.
-    #
-    # @sig Hash[String, [String, Zeitwerk::Cref]]
+    # @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
@@ -101,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
@@ -167,7 +175,7 @@ module Zeitwerk
           end
         end
 
-        to_unload.each do |cpath, (abspath, cref)|
+        to_unload.each do |abspath, cref|
           unless on_unload_callbacks.empty?
             begin
               value = cref.get
@@ -176,7 +184,7 @@ module Zeitwerk
               # 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
 
@@ -205,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
@@ -315,17 +325,23 @@ module Zeitwerk
     # 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.
@@ -333,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
@@ -474,22 +491,22 @@ module Zeitwerk
         # 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[cref.path] << subdir
+        namespace_dirs.get_or_set(cref) { [] } << subdir
       elsif !cref.defined?
         # First time we find this namespace, set an autoload for it.
-        namespace_dirs[cref.path] << 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 #{cref.path} already exists, descending into #{subdir}") if logger
+        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(cref, file)
-      if autoload_path = cref.autoload? || Registry.inception?(cref.path)
+      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
@@ -499,7 +516,7 @@ module Zeitwerk
         end
       elsif cref.defined?
         shadowed_files << file
-        log("file #{file} is ignored because #{cref.path} is already defined") if logger
+        log("file #{file} is ignored because #{cref} is already defined") if logger
       else
         define_autoload(cref, file)
       end
@@ -513,7 +530,7 @@ module Zeitwerk
       autoloads.delete(dir)
       Registry.unregister_autoload(dir)
 
-      log("earlier autoload for #{cref.path} 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
 
       # Order matters: When Module#const_added is triggered by the autoload, we
       # don't want the namespace to be registered yet.
@@ -527,19 +544,16 @@ module Zeitwerk
 
       if logger
         if ruby?(abspath)
-          log("autoload set for #{cref.path}, to be loaded from #{abspath}")
+          log("autoload set for #{cref}, to be loaded from #{abspath}")
         else
-          log("autoload set for #{cref.path}, to be autovivified from #{abspath}")
+          log("autoload set for #{cref}, to be autovivified from #{abspath}")
         end
       end
 
       autoloads[abspath] = cref
       Registry.register_autoload(self, abspath)
 
-      # See why in the documentation of Zeitwerk::Registry.inceptions.
-      unless cref.autoload?
-        Registry.register_inception(cref.path, abspath, self)
-      end
+      register_inception(cref, abspath) unless cref.autoload?
     end
 
     # @sig (Module, Symbol) -> String?
@@ -547,13 +561,32 @@ module Zeitwerk
       if autoload_path = cref.autoload?
         autoload_path if autoloads.key?(autoload_path)
       else
-        Registry.inception?(cref.path, self)
+        inceptions[cref]
       end
     end
 
     # @sig (Zeitwerk::Cref) -> void
     private def register_explicit_namespace(cref)
-      ExplicitNamespace.__register(cref, self)
+      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
@@ -580,17 +613,17 @@ 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(cref)
       cref.remove
-      log("autoload for #{cref.path} removed") if logger
+      log("autoload for #{cref} removed") if logger
     end
 
     # @sig (Module, Symbol) -> void
@@ -602,7 +635,7 @@ module Zeitwerk
       # There are a few edge scenarios in which this may happen. If the constant
       # is gone, that is OK, anyway.
     else
-      log("#{cref.path} 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/registry/explicit_namespaces.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Zeitwerk::Registry
+  # This module is a registry for explicit namespaces.
+  #
+  # When a loader determines that a certain file should define an explicit
+  # namespace, it registers it here, associating its cref with itself.
+  #
+  # If the namespace is autoloaded, our const_added callback retrieves its
+  # loader by calling loader_for. That way, the loader is able to scan the
+  # subdirectories that conform the namespace and set autoloads for their
+  # expected constants just in time.
+  #
+  # Once autoloaded, the namespace is unregistered.
+  #
+  # The implementation assumes an explicit namespace is managed by one loader.
+  # Loaders that reopen namespaces owned by other projects are responsible for
+  # loading their constant before setup. This is documented.
+  module ExplicitNamespaces # :nodoc: all
+    # Maps crefs of explicit namespaces with their corresponding loader.
+    #
+    # Entries are added as the namespaces are found, and removed as they are
+    # autoloaded.
+    #
+    # @sig Zeitwerk::Cref::Map[Zeitwerk::Loader]
+    @loaders = Zeitwerk::Cref::Map.new
+
+    class << self
+      extend Zeitwerk::Internal
+
+      # Registers `cref` as being the constant path of an explicit namespace
+      # managed by `loader`.
+      #
+      # @sig (Zeitwerk::Cref, Zeitwerk::Loader) -> void
+      internal def register(cref, loader)
+        @loaders[cref] = loader
+      end
+
+      # @sig (Module, Symbol) -> Zeitwerk::Loader?
+      internal def loader_for(mod, cname)
+        @loaders.delete_mod_cname(mod, cname)
+      end
+
+      # @sig (Zeitwerk::Loader) -> void
+      internal def unregister_loader(loader)
+        @loaders.delete_by_value(loader)
+      end
+
+      # This is an internal method only used by the test suite.
+      #
+      # @sig (Symbol | String) -> Zeitwerk::Loader?
+      internal def registered?(cref)
+        @loaders[cref]
+      end
+
+      # This is an internal method only used by the test suite.
+      #
+      # @sig () -> void
+      internal def clear
+        @loaders.clear
+      end
+    end
+  end
+end

data/lib/zeitwerk/registry/inceptions.rb

@@ -0,0 +1,31 @@
+module Zeitwerk::Registry
+  # Loaders know their own inceptions, but there is a use case in which we need
+  # to know if a given cpath is an inception globally. This is what this
+  # registry is for.
+  module Inceptions # :nodoc: all
+    # @sig Zeitwerk::Cref::Map[String]
+    @inceptions = Zeitwerk::Cref::Map.new
+
+    class << self
+      # @sig (Zeitwerk::Cref, String) -> void
+      def register(cref, autoload_path)
+        @inceptions[cref] = autoload_path
+      end
+
+      # @sig (String) -> String?
+      def registered?(cref)
+        @inceptions[cref]
+      end
+
+      # @sig (String) -> void
+      def unregister(cref)
+        @inceptions.delete(cref)
+      end
+
+      # @sig () -> void
+      def clear # for tests
+        @inceptions.clear
+      end
+    end
+  end
+end

data/lib/zeitwerk/registry.rb

@@ -2,6 +2,9 @@
 
 module Zeitwerk
   module Registry # :nodoc: all
+    require_relative "registry/explicit_namespaces"
+    require_relative "registry/inceptions"
+
     class << self
       # Keeps track of all loaders. Useful to broadcast messages and to prevent
       # them from being garbage collected.
@@ -25,45 +28,6 @@ module Zeitwerk
       # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :autoloads
 
-      # This hash table addresses an edge case in which an autoload is ignored.
-      #
-      # For example, let's suppose we want to autoload in a gem like this:
-      #
-      #   # lib/my_gem.rb
-      #   loader = Zeitwerk::Loader.new
-      #   loader.push_dir(__dir__)
-      #   loader.setup
-      #
-      #   module MyGem
-      #   end
-      #
-      # if you require "my_gem", as Bundler would do, this happens while setting
-      # up autoloads:
-      #
-      #   1. Object.autoload?(:MyGem) returns `nil` because the autoload for
-      #      the constant is issued by Zeitwerk while the same file is being
-      #      required.
-      #   2. The constant `MyGem` is undefined while setup runs.
-      #
-      # Therefore, a directory `lib/my_gem` would autovivify a module according to
-      # the existing information. But that would be wrong.
-      #
-      # To overcome this fundamental limitation, we keep track of the constant
-      # paths that are in this situation ---in the example above, "MyGem"--- and
-      # take this collection into account for the autovivification logic.
-      #
-      # Note that you cannot generally address this by moving the setup code
-      # below the constant definition, because we want libraries to be able to
-      # use managed constants in the module body:
-      #
-      #   module MyGem
-      #     include MyConcern
-      #   end
-      #
-      # @private
-      # @sig Hash[String, [String, Zeitwerk::Loader]]
-      attr_reader :inceptions
-
       # Registers a loader.
       #
       # @private
@@ -78,7 +42,6 @@ module Zeitwerk
         loaders.delete(loader)
         gem_loaders_by_root_file.delete_if { |_, l| l == loader }
         autoloads.delete_if { |_, l| l == loader }
-        inceptions.delete_if { |_, (_, l)| l == loader }
       end
 
       # This method returns always a loader, the same instance for the same root
@@ -102,23 +65,6 @@ module Zeitwerk
         autoloads.delete(abspath)
       end
 
-      # @private
-      # @sig (String, String, Zeitwerk::Loader) -> void
-      def register_inception(cpath, abspath, loader)
-        inceptions[cpath] = [abspath, loader]
-      end
-
-      # @private
-      # @sig (String) -> String?
-      def inception?(cpath, registered_by_loader=nil)
-        if pair = inceptions[cpath]
-          abspath, loader = pair
-          if registered_by_loader.nil? || registered_by_loader.equal?(loader)
-            abspath
-          end
-        end
-      end
-
       # @private
       # @sig (String) -> Zeitwerk::Loader?
       def loader_for(path)
@@ -129,13 +75,11 @@ module Zeitwerk
       # @sig (Zeitwerk::Loader) -> void
       def on_unload(loader)
         autoloads.delete_if { |_path, object| object == loader }
-        inceptions.delete_if { |_cpath, (_path, object)| object == loader }
       end
     end
 
     @loaders                  = []
     @gem_loaders_by_root_file = {}
     @autoloads                = {}
-    @inceptions               = {}
   end
 end

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.7.1"
+  VERSION = "2.7.2"
 end

data/lib/zeitwerk.rb

@@ -7,7 +7,6 @@ module Zeitwerk
   require_relative "zeitwerk/loader"
   require_relative "zeitwerk/gem_loader"
   require_relative "zeitwerk/registry"
-  require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
   require_relative "zeitwerk/null_inflector"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.7.1
+  version: 2.7.2
 platform: ruby
 authors:
 - Xavier Noria
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-18 00:00:00.000000000 Z
+date: 2025-02-18 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -26,8 +25,8 @@ files:
 - lib/zeitwerk/core_ext/kernel.rb
 - lib/zeitwerk/core_ext/module.rb
 - lib/zeitwerk/cref.rb
+- lib/zeitwerk/cref/map.rb
 - lib/zeitwerk/error.rb
-- lib/zeitwerk/explicit_namespace.rb
 - lib/zeitwerk/gem_inflector.rb
 - lib/zeitwerk/gem_loader.rb
 - lib/zeitwerk/inflector.rb
@@ -40,6 +39,8 @@ files:
 - lib/zeitwerk/null_inflector.rb
 - lib/zeitwerk/real_mod_name.rb
 - lib/zeitwerk/registry.rb
+- lib/zeitwerk/registry/explicit_namespaces.rb
+- lib/zeitwerk/registry/inceptions.rb
 - lib/zeitwerk/version.rb
 homepage: https://github.com/fxn/zeitwerk
 licenses:
@@ -49,7 +50,6 @@ metadata:
   changelog_uri: https://github.com/fxn/zeitwerk/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/fxn/zeitwerk
   bug_tracker_uri: https://github.com/fxn/zeitwerk/issues
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -64,8 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-signing_key:
+rubygems_version: 3.6.4
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader
 test_files: []

data/lib/zeitwerk/explicit_namespace.rb

@@ -1,113 +0,0 @@
-# frozen_string_literal: true
-
-module Zeitwerk
-  # This module is essentially a registry for explicit namespaces.
-  #
-  # When a loader determines that a certain file should define an explicit
-  # namespace, it registers it here, associating its cref with itself.
-  #
-  # If the namespace is autoloaded, our const_added callback retrieves its
-  # loader by calling loader_for. That way, the loader is able to scan the
-  # subdirectories that conform the namespace and set autoloads for their
-  # expected constants just in time.
-  #
-  # Once autoloaded, the namespace is unregistered.
-  #
-  # The implementation assumes an explicit namespace is managed by one loader.
-  # Loaders that reopen namespaces owned by other projects are responsible for
-  # loading their constant before setup. This is documented.
-  module ExplicitNamespace # :nodoc: all
-    # Maps cnames or cpaths of explicit namespaces with their corresponding
-    # loader. They are symbols for top-level ones, and strings for nested ones:
-    #
-    #   {
-    #     :Admin => #<Zeitwerk::Loader:...>,
-    #     "Hotel::Pricing" => #<Zeitwerk::Loader:...>
-    #   }
-    #
-    # There are two types of keys to make loader_for as fast as possible, since
-    # it is invoked by our const_added for all autoloads and constant actually
-    # added. Globally. With this trick, for top-level constants we do not need
-    # to call Symbol#name and perform a string lookup. Instead, we can directly
-    # perform a fast symbol lookup.
-    #
-    # Entries are added as the namespaces are found, and removed as they are
-    # autoloaded.
-    #
-    # @sig Hash[(Symbol | String) => Zeitwerk::Loader]
-    @loaders = {}
-
-    class << self
-      include RealModName
-      extend Internal
-
-      # Registers `cref` as being the constant path of an explicit namespace
-      # managed by `loader`.
-      #
-      # @sig (String, Zeitwerk::Loader) -> void
-      internal def register(cref, loader)
-        if Object.equal?(cref.mod)
-          @loaders[cref.cname] = loader
-        else
-          @loaders[cref.path] = loader
-        end
-      end
-
-      # @sig (Module, Symbol) -> Zeitwerk::Loader?
-      internal def loader_for(mod, cname)
-        if Object.equal?(mod)
-          @loaders.delete(cname)
-        else
-          @loaders.delete("#{real_mod_name(mod)}::#{cname}")
-        end
-      end
-
-      # @sig (Zeitwerk::Loader) -> void
-      internal def unregister_loader(loader)
-        @loaders.delete_if { _2.equal?(loader) }
-      end
-
-      # This is an internal method only used by the test suite.
-      #
-      # @sig (String) -> Zeitwerk::Loader?
-      internal def registered?(cname_or_cpath)
-        @loaders[cname_or_cpath]
-      end
-
-      # This is an internal method only used by the test suite.
-      #
-      # @sig () -> void
-      internal def clear
-        @loaders.clear
-      end
-
-      module Synchronized
-        extend Internal
-
-        MUTEX = Mutex.new
-
-        internal def register(...)
-          MUTEX.synchronize { super }
-        end
-
-        internal def loader_for(...)
-          MUTEX.synchronize { super }
-        end
-
-        internal def unregister_loader(...)
-          MUTEX.synchronize { super }
-        end
-
-        internal def registered?(...)
-          MUTEX.synchronize { super }
-        end
-
-        internal def clear
-          MUTEX.synchronize { super }
-        end
-      end
-
-      prepend Synchronized unless RUBY_ENGINE == "ruby"
-    end
-  end
-end