zeitwerk 2.6.13 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d4ce4eb7136dafe17130fc5d895e525d80ae947f02dd9420b5bc85a4d6f0dfd
-  data.tar.gz: edcac638955fef258ad36a358b78da6831a715ed46446848e39f9f1d8fb7de0b
+  metadata.gz: aba46812169c8e26085b099c708093b00a29bfd39e8d8210d29bc99e7df0e7fa
+  data.tar.gz: 0fc20386009d52d21a0cb79a64c5d800f7aecfce5a38e8430a10dc5d04c2609d
 SHA512:
-  metadata.gz: f0a6e64c56635c9c6a8c9b24bdeb7509e4a7f14489f32aae18b02221c23b95b34096184c78d2d1509130ce75031ed0f3a7751b78e43d9b72122440f07cf980bc
-  data.tar.gz: 06440147c101a95ac2c8b7dcd43920a3efc3da2f58b902c157730a449d57b6ef74e0d3db7f3d2735be816a74ceb774e2d4075741556c7e2ba7fa00b8130c1723
+  metadata.gz: 3edac5ad6f940caa70c4cac093bf271b8399b078d7124f450513c963ec5099e9b9082841ceb9893b81f1edf8e34dc642ec811403415fb230211670c63a950766
+  data.tar.gz: 47339a8b35dc06108fde9aadd62e83b1ea4e4ef22854c31849069f09ece1115dce07d63ec354fe96fbc599bba411ecff48db6a8b0c8b150ad7ee016787e9d75c

data/README.md

@@ -54,15 +54,14 @@
     - [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)
     - [`Zeitwerk::Loader#dirs`](#zeitwerkloaderdirs)
     - [`Zeitwerk::Loader#cpath_expected_at`](#zeitwerkloadercpath_expected_at)
+    - [`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)
@@ -259,7 +258,7 @@ app/controllers/admin/users_controller.rb -> Admin::UsersController
 
 and does not have a file called `admin.rb`, Zeitwerk automatically creates an `Admin` module on your behalf the first time `Admin` is used.
 
-To trigger this behavior, the directory must contain non-ignored Ruby files with the `.rb` extension, either directly or recursively. Otherwise, the directory is ignored. This condition is reevaluated during reloads.
+To trigger this behavior, the directory must contain non-ignored Ruby files with the ".rb" extension, either directly or recursively. Otherwise, the directory is ignored. This condition is reevaluated during reloads.
 
 <a id="markdown-explicit-namespaces" name="explicit-namespaces"></a>
 ### Explicit namespaces
@@ -282,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>
@@ -1064,7 +1065,7 @@ However, sometimes it might still be convenient to tell Zeitwerk to completely i
 
 You can ignore file names, directory names, and glob patterns. Glob patterns are expanded when they are added and again on each reload.
 
-There is an edge case related to nested root directories. Conceptually, root directories are independent source trees. If you ignore a parent of a nested root directory, the nested root directory is not affected. You need to ignore it explictly if you want it ignored too.
+There is an edge case related to nested root directories. Conceptually, root directories are independent source trees. If you ignore a parent of a nested root directory, the nested root directory is not affected. You need to ignore it explicitly if you want it ignored too.
 
 Let's see some use cases.
 
@@ -1177,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
 
@@ -1330,6 +1301,54 @@ loader.cpath_expected_at("8.rb") # => Zeitwerk::NameError
 
 This method does not parse file contents and does not guarantee files define the returned constant path. It just says which is the _expected_ one.
 
+`Zeitwerk::Loader#cpath_expected_at` is designed to be used with individual paths. If you want to know all the expected constant paths in the project, please use `Zeitwerk::Loader#all_expected_cpaths`, documented next.
+
+<a id="markdown-zeitwerkloaderall_expected_cpaths" name="zeitwerkloaderall_expected_cpaths"></a>
+#### `Zeitwerk::Loader#all_expected_cpaths`
+
+The method `Zeitwerk::Loader#all_expected_cpaths` returns a hash that maps the absolute paths of the files and directories managed by the receiver to their expected constant paths.
+
+Ignored files, hidden files, and files whose extension is not ".rb" are not included in the result. Same for directories, hidden or ignored directories are not included in the result. Additionally, directories that contain no files with extension ".rb" (recursively) are also excluded, since those are not considered to represent Ruby namespaces.
+
+For example, if `lib` is the root directory of a gem with the following contents:
+
+```
+lib/.DS_Store
+lib/my_gem.rb
+lib/my_gem/version.rb
+lib/my_gem/ignored.rb
+lib/my_gem/drivers/unix.rb
+lib/my_gem/drivers/windows.rb
+lib/my_gem/collapsed/foo.rb
+lib/tasks/my_gem.rake
+```
+
+`Zeitwerk::Loader#all_expected_cpaths` would return (maybe in a different order):
+
+```ruby
+{
+  "/.../lib"                           => "Object",
+  "/.../lib/my_gem.rb"                 => "MyGem",
+  "/.../lib/my_gem"                    => "MyGem",
+  "/.../lib/my_gem/version.rb"         => "MyGem::VERSION",
+  "/.../lib/my_gem/drivers"            => "MyGem::Drivers",
+  "/.../lib/my_gem/drivers/unix.rb"    => "MyGem::Drivers::Unix",
+  "/.../lib/my_gem/drivers/windows.rb" => "MyGem::Drivers::Windows",
+  "/.../lib/my_gem/collapsed"          => "MyGem"
+  "/.../lib/my_gem/collapsed/foo.rb"   => "MyGem::Foo"
+}
+```
+
+In the previous example we assume `lib/my_gem/ignored.rb` is ignored, and therefore it is not present in the returned hash. Also, `lib/my_gem/collapsed` is a collapsed directory, so the expected namespace at that level is still `MyGem` (this is an edge case).
+
+The file `lib/.DS_Store` is hidden, hence excluded. The directory `lib/tasks` is also not present because it contains no files with extension ".rb".
+
+Directory paths do not have trailing slashes.
+
+The order of the hash entries is undefined.
+
+This method does not parse or execute file contents and does not guarantee files define the corresponding constant paths. It just says which are the _expected_ ones.
+
 <a id="markdown-encodings" name="encodings"></a>
 ### Encodings
 
@@ -1357,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
 
@@ -1374,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,19 @@
+# frozen_string_literal: true
+
+module Zeitwerk::ConstAdded
+  def const_added(cname)
+    if loader = Zeitwerk::ExplicitNamespace.__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})"
+      end
+
+      loader.on_namespace_loaded(namespace)
+    end
+    super
+  end
+
+  Module.prepend(self)
+end

data/lib/zeitwerk/cref.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# 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:
+#
+#   cref.path
+#   cref.set(value)
+#   cref.get
+#
+# The constant may or may not exist in mod.
+class Zeitwerk::Cref
+  include Zeitwerk::RealModName
+
+  # @sig Module
+  attr_reader :mod
+
+  # @sig Symbol
+  attr_reader :cname
+
+  # The type of the first argument is Module because Class < Module, class
+  # objects are also valid.
+  #
+  # @sig (Module, Symbol) -> void
+  def initialize(mod, cname)
+    @mod   = mod
+    @cname = cname
+    @path  = nil
+  end
+
+  # @sig () -> String
+  def path
+    @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
+  end
+
+  # @sig () -> String?
+  def autoload?
+    @mod.autoload?(@cname, false)
+  end
+
+  # @sig (String) -> bool
+  def autoload(abspath)
+    @mod.autoload(@cname, abspath)
+  end
+
+  # @sig () -> bool
+  def defined?
+    @mod.const_defined?(@cname, false)
+  end
+
+  # @sig (Object) -> Object
+  def set(value)
+    @mod.const_set(@cname, value)
+  end
+
+  # @raise [NameError]
+  # @sig () -> Object
+  def get
+    @mod.const_get(@cname, false)
+  end
+
+  # @raise [NameError]
+  # @sig () -> void
+  def remove
+    @mod.__send__(:remove_const, @cname)
+  end
+end

data/lib/zeitwerk/explicit_namespace.rb

@@ -1,93 +1,113 @@
 # 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.
+  # 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
 
-      # 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.
+      # Registers `cref` as being the constant path of an explicit namespace
+      # managed by `loader`.
       #
       # @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?
+      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)
-        cpaths.delete_if { |_cpath, l| l == loader }
-        disable_tracer_if_unneeded
+        @loaders.delete_if { _2.equal?(loader) }
       end
 
       # This is an internal method only used by the test suite.
       #
-      # @sig (String) -> bool
-      internal def registered?(cpath)
-        cpaths.key?(cpath)
+      # @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
-      private def disable_tracer_if_unneeded
-        mutex.synchronize do
-          tracer.disable if cpaths.empty?
-        end
+      internal def clear
+        @loaders.clear
       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?
+      module Synchronized
+        extend Internal
+
+        MUTEX = Mutex.new
 
-        # 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
+        internal def register(...)
+          MUTEX.synchronize { super }
         end
-      end
-    end
 
-    @cpaths = {}
-    @mutex  = Mutex.new
+        internal def loader_for(...)
+          MUTEX.synchronize { super }
+        end
+
+        internal def unregister_loader(...)
+          MUTEX.synchronize { super }
+        end
 
-    # 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))
+        internal def registered?(...)
+          MUTEX.synchronize { super }
+        end
+
+        internal def clear
+          MUTEX.synchronize { super }
+        end
+      end
+
+      prepend Synchronized unless RUBY_ENGINE == "ruby"
+    end
   end
 end

data/lib/zeitwerk/gem_loader.rb

@@ -42,13 +42,12 @@ module Zeitwerk
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@root_dir) do |basename, abspath|
+      ls(@root_dir) do |basename, abspath, ftype|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 
         basename_without_ext = basename.delete_suffix(".rb")
         cname = inflector.camelize(basename_without_ext, abspath).to_sym
-        ftype = dir?(abspath) ? "directory" : "file"
 
         warn(<<~EOS)
           WARNING: Zeitwerk defines the constant #{cname} after the #{ftype}

data/lib/zeitwerk/loader/callbacks.rb

@@ -6,31 +6,31 @@ module Zeitwerk::Loader::Callbacks
 
   # 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)
-    cpath = cpath(*cref)
+    cref = autoloads.delete(file)
 
     Zeitwerk::Registry.unregister_autoload(file)
 
-    if cdef?(*cref)
-      log("constant #{cpath} loaded from file #{file}") if logger
-      to_unload[cpath] = [file, cref] if reloading_enabled?
-      run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
+    if cref.defined?
+      log("constant #{cref.path} loaded from file #{file}") if logger
+      to_unload[cref.path] = [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 #{cpath}, but didn't"
+      msg = "expected file #{file} to define constant #{cref.path}, but didn't"
       log(msg) if logger
 
       # Ruby still keeps the autoload defined, but we remove it because the
       # contract in Zeitwerk is more strict.
-      crem(*cref)
+      cref.remove
 
       # 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[cpath] = [file, cref] if reloading_enabled?
+      to_unload[cref.path] = [file, cref] if reloading_enabled?
 
-      raise Zeitwerk::NameError.new(msg, cref.last)
+      raise Zeitwerk::NameError.new(msg, cref.cname)
     end
   end
 
@@ -53,8 +53,8 @@ module Zeitwerk::Loader::Callbacks
     # children, since t1 would have correctly deleted its namespace_dirs entry.
     dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
-        autovivified_module = cref[0].const_set(cref[1], Module.new)
-        cpath = autovivified_module.name
+        implicit_namespace = cref.set(Module.new)
+        cpath = implicit_namespace.name
         log("module #{cpath} autovivified from directory #{dir}") if logger
 
         to_unload[cpath] = [dir, cref] if reloading_enabled?
@@ -65,15 +65,15 @@ module Zeitwerk::Loader::Callbacks
         # these to be able to unregister later if eager loading.
         autoloaded_dirs << dir
 
-        on_namespace_loaded(autovivified_module)
+        on_namespace_loaded(implicit_namespace)
 
-        run_on_load_callbacks(cpath, autovivified_module, dir) unless on_load_callbacks.empty?
+        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
+  # const_added or from module autovivification. If the namespace has matching
   # subdirectories, we descend into them now.
   #
   # @private

data/lib/zeitwerk/loader/eager_load.rb

@@ -61,8 +61,8 @@ module Zeitwerk::Loader::EagerLoad
     cnames.reverse_each do |cname|
       # Can happen if there are no Ruby files. This is not an error condition,
       # the directory is actually managed. Could have Ruby files later.
-      return unless cdef?(namespace, cname)
-      namespace = cget(namespace, cname)
+      return unless namespace.const_defined?(cname, false)
+      namespace = namespace.const_get(cname, false)
     end
 
     # A shortcircuiting test depends on the invocation of this method. Please
@@ -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)
@@ -145,12 +145,12 @@ module Zeitwerk::Loader::EagerLoad
 
     namespace = root_namespace
     cnames.reverse_each do |cname|
-      namespace = cget(namespace, cname)
+      namespace = namespace.const_get(cname, false)
     end
 
     raise Zeitwerk::Error.new("#{abspath} is shadowed") if shadowed_file?(abspath)
 
-    cget(namespace, base_cname)
+    namespace.const_get(base_cname, false)
   end
 
   # The caller is responsible for making sure `namespace` is the namespace that
@@ -164,22 +164,20 @@ module Zeitwerk::Loader::EagerLoad
     log("eager load directory #{dir} start") if logger
 
     queue = [[dir, namespace]]
-    while to_eager_load = queue.shift
-      dir, namespace = to_eager_load
-
-      ls(dir) do |basename, abspath|
+    while (current_dir, namespace = queue.shift)
+      ls(current_dir) do |basename, abspath, ftype|
         next if honour_exclusions && eager_load_exclusions.member?(abspath)
 
-        if ruby?(abspath)
+        if ftype == :file
           if (cref = autoloads[abspath])
-            cget(*cref)
+            cref.get
           end
         else
           if collapse?(abspath)
             queue << [abspath, namespace]
           else
             cname = inflector.camelize(basename, abspath).to_sym
-            queue << [abspath, cget(namespace, cname)]
+            queue << [abspath, namespace.const_get(cname, false)]
           end
         end
       end
@@ -209,9 +207,9 @@ module Zeitwerk::Loader::EagerLoad
     next_dirs = []
 
     suffix.split("::").each do |segment|
-      while dir = dirs.shift
-        ls(dir) do |basename, abspath|
-          next unless dir?(abspath)
+      while (dir = dirs.shift)
+        ls(dir) do |basename, abspath, ftype|
+          next unless ftype == :directory
 
           if collapse?(abspath)
             dirs << abspath

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,14 +22,13 @@ 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
 
@@ -45,17 +44,19 @@ module Zeitwerk
 
     # Stores metadata needed for unloading. Its entries look like this:
     #
-    #   "Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
+    #   "Admin::Role" => [
+    #     ".../admin/role.rb",
+    #     #<Zeitwerk::Cref:... @mod=Admin, @cname=: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.
+    # 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, [Module, Symbol]]]
+    # @sig Hash[String, [String, Zeitwerk::Cref]]
     attr_reader :to_unload
     internal :to_unload
 
@@ -154,22 +155,22 @@ 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 |cpath, (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
@@ -179,7 +180,7 @@ module Zeitwerk
             end
           end
 
-          unload_cref(parent, cname)
+          unload_cref(cref)
           unloaded_files.add(abspath) if ruby?(abspath)
         end
 
@@ -230,53 +231,86 @@ 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.
@@ -408,24 +442,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 +469,91 @@ 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[cref.path] << 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[cref.path] << 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.path} 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.inception?(cref.path)
         # 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.path} 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.path} 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.path}, to be loaded from #{abspath}")
         else
-          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{abspath}")
+          log("autoload set for #{cref.path}, 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)
+      unless cref.autoload?
+        Registry.register_inception(cref.path, abspath, self)
       end
     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))
+        Registry.inception?(cref.path, self)
       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)
+      ExplicitNamespace.__register(cref, self)
     end
 
     # @sig (String) -> void
@@ -556,21 +588,21 @@ module Zeitwerk
     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.path} 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.path} unloaded") if logger
     end
   end
 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.rb

@@ -110,9 +110,12 @@ module Zeitwerk
 
       # @private
       # @sig (String) -> String?
-      def inception?(cpath)
+      def inception?(cpath, registered_by_loader=nil)
         if pair = inceptions[cpath]
-          pair.first
+          abspath, loader = pair
+          if registered_by_loader.nil? || registered_by_loader.equal?(loader)
+            abspath
+          end
         end
       end
 

data/lib/zeitwerk/version.rb

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

data/lib/zeitwerk.rb

@@ -3,6 +3,7 @@
 module Zeitwerk
   require_relative "zeitwerk/real_mod_name"
   require_relative "zeitwerk/internal"
+  require_relative "zeitwerk/cref"
   require_relative "zeitwerk/loader"
   require_relative "zeitwerk/gem_loader"
   require_relative "zeitwerk/registry"
@@ -10,10 +11,12 @@ module Zeitwerk
   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,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.13
+  version: 2.7.1
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-06 00:00:00.000000000 Z
+date: 2024-10-18 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -23,13 +23,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/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
@@ -55,14 +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.5
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader