zeitwerk 2.6.18 → 2.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1fa60f08c282d8471eaf321deba97207ce56d2cba32619cff78f09e65f2f258
-  data.tar.gz: 1c803846848fc8830913acfd8fbf04bfa59f26c3c8806d4fa5bed9c751f48c5a
+  metadata.gz: 1a07f90eb2f155582d05f58527ffcbc2f4d76c9a1983260ca8d527becaeb7972
+  data.tar.gz: 65e8dc78ca8e6de674f0fc7d88aad5c9bad0d7687bc9ed26f93d6fa0e6d18e90
 SHA512:
-  metadata.gz: abb7134976f1ae00cafd77dcaa39fe2239632639c136d866ac75e55c8ec15f1c157ff0e434969dade286ee36e6422856799acd3e86dcd61e4ef39d1fd23909a4
-  data.tar.gz: 42e2309bd69f0bba3bfc74acecf2fcf3b3206a6cd26583afdc1012d34a063431bc03ec4ec42e1cf452f41bfa0de43a4d171cb2e99c7ca3e64b61412fbef83819
+  metadata.gz: d7b9d13e3d3d5bf0497ec259bf0817256586e245f7d47c951b8392784f715bc71c20d0ec3c9e465077da6d8e729ca6888fbaaa24820fe4459771e29340ee6d05
+  data.tar.gz: 8b1322d36bc9115a56b6abab6be9549c868e0edd2025fe82dd2c5d0abb082fac8532c82ed03f895d34f2875f27b160f4861185112c4aef2a3129e46569115c0f

data/README.md

@@ -54,7 +54,6 @@
     - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
     - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
   - [Shadowed files](#shadowed-files)
-  - [Edge cases](#edge-cases)
   - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Introspection](#introspection)
@@ -63,7 +62,6 @@
     - [`Zeitwerk::Loader#all_expected_cpaths`](#zeitwerkloaderall_expected_cpaths)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
-  - [Debuggers](#debuggers)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Testing](#testing)
@@ -283,6 +281,8 @@ class Hotel < ApplicationRecord
 end
 ```
 
+When autoloaded, Zeitwerk verifies the expected constant (`Hotel` in the example) stores a class or module object. If it doesn't, `Zeitwerk::Error` is raised.
+
 An explicit namespace must be managed by one single loader. Loaders that reopen namespaces owned by other projects are responsible for loading their constants before setup.
 
 <a id="markdown-collapsing-directories" name="collapsing-directories"></a>
@@ -1178,36 +1178,6 @@ file #{file} is ignored because #{constant_path} is already defined
 
 Shadowing only applies to Ruby files, namespace definition can be spread over multiple directories. And you can also reopen third-party namespaces if done [orderly](#reopening-third-party-namespaces).
 
-<a id="markdown-edge-cases" name="edge-cases"></a>
-### Edge cases
-
-[Explicit namespaces](#explicit-namespaces) like `Trip` here:
-
-```ruby
-# trip.rb
-class Trip
-  include Geolocation
-end
-
-# trip/geolocation.rb
-module Trip::Geolocation
-  ...
-end
-```
-
-have to be defined with the `class`/`module` keywords, as in the example above.
-
-For technical reasons, raw constant assignment is not supported:
-
-```ruby
-# trip.rb
-Trip = Class { ...}        # NOT SUPPORTED
-Trip = Struct.new { ... }  # NOT SUPPORTED
-Trip = Data.define { ... } # NOT SUPPORTED
-```
-
-This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
-
 <a id="markdown-beware-of-circular-dependencies" name="beware-of-circular-dependencies"></a>
 ### Beware of circular dependencies
 
@@ -1406,15 +1376,6 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 
 6. In a given process, ideally, there should be at most one loader with reloading enabled. Technically, you can have more, but it may get tricky if one refers to constants managed by the other one. Do that only if you know what you are doing.
 
-<a id="markdown-debuggers" name="debuggers"></a>
-### Debuggers
-
-Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if CRuby is ≥ 3.1 (see [ruby/debug#558](https://github.com/ruby/debug/pull/558)).
-
-[Byebug](https://github.com/deivid-rodriguez/byebug) is compatible except for an edge case explained in [deivid-rodriguez/byebug#564](https://github.com/deivid-rodriguez/byebug/issues/564). Prior to CRuby 3.1, `debug.rb` has a similar edge incompatibility.
-
-[Break](https://github.com/gsamokovarov/break) is fully compatible.
-
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation
 
@@ -1423,9 +1384,12 @@ Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if C
 <a id="markdown-supported-ruby-versions" name="supported-ruby-versions"></a>
 ## Supported Ruby versions
 
-Zeitwerk works with CRuby 2.5 and above.
+Starting with version 2.7, Zeitwerk requires Ruby 3.2 or newer.
 
-On TruffleRuby all is good except for thread-safety. Right now, in TruffleRuby `Module#autoload` does not block threads accessing a constant that is being autoloaded. CRuby prevents such access to avoid concurrent threads from seeing partial evaluations of the corresponding file. Zeitwerk inherits autoloading thread-safety from this property. This is not an issue if your project gets eager loaded, or if you lazy load in single-threaded environments. (See https://github.com/oracle/truffleruby/issues/2431.)
+Zeitwerk 2.7 requires TruffleRuby 24.1.2+ due to https://github.com/oracle/truffleruby/issues/3683.
+Alternatively, TruffleRuby users can use a `< 2.7` version constraint for the `zeitwerk` gem.
+As of this writing, [autoloading is not fully thread-safe yet on TruffleRuby](https://github.com/oracle/truffleruby/issues/2431).
+If your program is multi-threaded, you need to eager load before threads are created.
 
 JRuby 9.3.0.0 is almost there. As of this writing, the test suite of Zeitwerk passes on JRuby except for three tests. (See https://github.com/jruby/jruby/issues/6781.)
 

data/lib/zeitwerk/core_ext/module.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Zeitwerk::ConstAdded # :nodoc:
+  # @sig (Symbol) -> void
+  def const_added(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} is expected to be a namespace, should be a class or module (got #{namespace.class})"
+      end
+
+      loader.__on_namespace_loaded(Zeitwerk::Cref.new(self, cname), namespace)
+    end
+    super
+  end
+
+  Module.prepend(self)
+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,8 +11,13 @@
 #
 # The constant may or may not exist in mod.
 class Zeitwerk::Cref
+  require_relative "cref/map"
+
   include Zeitwerk::RealModName
 
+  # @sig Module
+  attr_reader :mod
+
   # @sig Symbol
   attr_reader :cname
 
@@ -26,48 +31,15 @@ class Zeitwerk::Cref
     @path  = nil
   end
 
-  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.
-    #
-    # @sig () -> String
-    def path
-      @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}"
-    end
-  else
-    # @sig () -> String
-    def path
-      @path ||= Object.equal?(@mod) ? @cname.to_s : "#{real_mod_name(@mod)}::#{@cname}"
-    end
+  # @sig () -> String
+  def path
+    @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
   end
+  alias to_s path
 
-  # 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 retrieve it ignoring ancestors.
-  #
   # @sig () -> String?
-  if method(:autoload?).arity == 1
-    # @sig () -> String?
-    def autoload?
-      @mod.autoload?(@cname) if self.defined?
-    end
-  else
-    # @sig () -> String?
-    def autoload?
-      @mod.autoload?(@cname, false)
-    end
+  def autoload?
+    @mod.autoload?(@cname, false)
   end
 
   # @sig (String) -> bool
@@ -80,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,11 +1,11 @@
 # 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.
   #
+  # @raise [Zeitwerk::NameError]
   # @sig (String) -> void
   internal def on_file_autoloaded(file)
     cref = autoloads.delete(file)
@@ -13,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
@@ -27,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
@@ -56,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
@@ -64,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
-  # tracer 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
@@ -87,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/eager_load.rb

@@ -84,7 +84,7 @@ module Zeitwerk::Loader::EagerLoad
     return unless mod_name
 
     actual_roots.each do |root_dir, root_namespace|
-      if mod.equal?(Object)
+      if Object.equal?(mod)
         # A shortcircuiting test depends on the invocation of this method.
         # Please keep them in sync if refactored.
         actual_eager_load_dir(root_dir, root_namespace)

data/lib/zeitwerk/loader/helpers.rb

@@ -57,9 +57,7 @@ module Zeitwerk::Loader::Helpers
     to_visit = [dir]
 
     while (dir = to_visit.shift)
-      children = Dir.children(dir)
-
-      children.each do |basename|
+      Dir.each_child(dir) do |basename|
         next if hidden?(basename)
 
         abspath = File.join(dir, basename)

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
@@ -469,27 +486,27 @@ 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(cref.path)
+          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[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,10 +530,12 @@ 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.
       define_autoload(cref, file)
-      register_explicit_namespace(cref.path)
+      register_explicit_namespace(cref)
     end
 
     # @sig (Module, Symbol, String) -> void
@@ -525,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?
@@ -545,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 (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
@@ -578,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
@@ -600,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/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

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.6.18"
+  VERSION = "2.7.2"
 end

data/lib/zeitwerk.rb

@@ -7,14 +7,15 @@ 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"
-  require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
   require_relative "zeitwerk/version"
 
+  require_relative "zeitwerk/core_ext/kernel"
+  require_relative "zeitwerk/core_ext/module"
+
   # This is a dangerous method.
   #
   # @experimental

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.18
+  version: 2.7.2
 platform: ruby
 authors:
 - Xavier Noria
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-02 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
@@ -23,14 +22,15 @@ files:
 - MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
+- 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
 - lib/zeitwerk/internal.rb
-- lib/zeitwerk/kernel.rb
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
 - lib/zeitwerk/loader/config.rb
@@ -39,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:
@@ -48,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
@@ -56,15 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-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,93 +0,0 @@
-# frozen_string_literal: true
-
-module Zeitwerk
-  # Centralizes the logic for the trace point used to detect the creation of
-  # explicit namespaces, needed to descend into matching subdirectories right
-  # after the constant has been defined.
-  #
-  # 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
-    class << self
-      include RealModName
-      extend Internal
-
-      # Maps constant paths that correspond to explicit namespaces according to
-      # the file system, to the loader responsible for them.
-      #
-      # @sig Hash[String, Zeitwerk::Loader]
-      attr_reader :cpaths
-      private :cpaths
-
-      # @sig Mutex
-      attr_reader :mutex
-      private :mutex
-
-      # @sig TracePoint
-      attr_reader :tracer
-      private :tracer
-
-      # Asserts `cpath` corresponds to an explicit namespace for which `loader`
-      # is responsible.
-      #
-      # @sig (String, Zeitwerk::Loader) -> void
-      internal def register(cpath, loader)
-        mutex.synchronize do
-          cpaths[cpath] = loader
-          # We check enabled? because, looking at the C source code, enabling an
-          # enabled tracer does not seem to be a simple no-op.
-          tracer.enable unless tracer.enabled?
-        end
-      end
-
-      # @sig (Zeitwerk::Loader) -> void
-      internal def unregister_loader(loader)
-        cpaths.delete_if { |_cpath, l| l == loader }
-        disable_tracer_if_unneeded
-      end
-
-      # This is an internal method only used by the test suite.
-      #
-      # @sig (String) -> bool
-      internal def registered?(cpath)
-        cpaths.key?(cpath)
-      end
-
-      # @sig () -> void
-      private def disable_tracer_if_unneeded
-        mutex.synchronize do
-          tracer.disable if cpaths.empty?
-        end
-      end
-
-      # @sig (TracePoint) -> void
-      private def tracepoint_class_callback(event)
-        # If the class is a singleton class, we won't do anything with it so we
-        # can bail out immediately. This is several orders of magnitude faster
-        # than accessing its name.
-        return if event.self.singleton_class?
-
-        # It might be tempting to return if name.nil?, to avoid the computation
-        # of a hash code and delete call. But Ruby does not trigger the :class
-        # event on Class.new or Module.new, so that would incur in an extra call
-        # for nothing.
-        #
-        # On the other hand, if we were called, cpaths is not empty. Otherwise
-        # the tracer is disabled. So we do need to go ahead with the hash code
-        # computation and delete call.
-        if loader = cpaths.delete(real_mod_name(event.self))
-          loader.on_namespace_loaded(event.self)
-          disable_tracer_if_unneeded
-        end
-      end
-    end
-
-    @cpaths = {}
-    @mutex  = Mutex.new
-
-    # We go through a method instead of defining a block mainly to have a better
-    # label when profiling.
-    @tracer = TracePoint.new(:class, &method(:tracepoint_class_callback))
-  end
-end