zeitwerk 2.6.6 → 2.7.0

data/lib/zeitwerk/cref.rb

@@ -0,0 +1,65 @@
+# 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 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,86 +1,84 @@
 # 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.
+  # Centralizes the logic needed to descend into matching subdirectories right
+  # after the constant for an explicit namespace 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
+    # Maps cpaths of explicit namespaces with their corresponding loader.
+    # Entries are added as the namespaces are found, and removed as they are
+    # autoloaded.
+    #
+    # @sig Hash[String => Zeitwerk::Loader]
+    @cpaths = {}
+
     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 `cpath` 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?
-        end
+        @cpaths[cpath] = loader
+      end
+
+      # @sig (String) -> Zeitwerk::Loader?
+      internal def loader_for(mod, cname)
+        cpath = mod.equal?(Object) ? cname.name : "#{real_mod_name(mod)}::#{cname}"
+        @cpaths.delete(cpath)
       end
 
       # @sig (Zeitwerk::Loader) -> void
       internal def unregister_loader(loader)
-        cpaths.delete_if { |_cpath, l| l == loader }
-        disable_tracer_if_unneeded
+        @cpaths.delete_if { _2.equal?(loader) }
       end
 
+      # This is an internal method only used by the test suite.
+      #
+      # @sig (String) -> Zeitwerk::Loader?
+      internal def registered?(cpath)
+        @cpaths[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
+        @cpaths.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
 
-        # 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
+        MUTEX = Mutex.new
+
+        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_inflector.rb

@@ -5,8 +5,8 @@ module Zeitwerk
     # @sig (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
-      lib_dir       = File.dirname(root_file)
-      @version_file = File.join(lib_dir, namespace, "version.rb")
+      root_dir      = File.dirname(root_file)
+      @version_file = File.join(root_dir, namespace, "version.rb")
     end
 
     # @sig (String, String) -> String

data/lib/zeitwerk/gem_loader.rb

@@ -3,27 +3,31 @@
 module Zeitwerk
   # @private
   class GemLoader < Loader
+    include RealModName
+
     # Users should not create instances directly, the public interface is
     # `Zeitwerk::Loader.for_gem`.
     private_class_method :new
 
     # @private
     # @sig (String, bool) -> Zeitwerk::GemLoader
-    def self._new(root_file, warn_on_extra_files:)
-      new(root_file, warn_on_extra_files: warn_on_extra_files)
+    def self.__new(root_file, namespace:, warn_on_extra_files:)
+      new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
     end
 
     # @sig (String, bool) -> void
-    def initialize(root_file, warn_on_extra_files:)
+    def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
-      @tag                 = File.basename(root_file, ".rb")
+      @tag = File.basename(root_file, ".rb")
+      @tag = real_mod_name(namespace) + "-" + @tag unless namespace.equal?(Object)
+
       @inflector           = GemInflector.new(root_file)
       @root_file           = File.expand_path(root_file)
-      @lib                 = File.dirname(root_file)
+      @root_dir            = File.dirname(root_file)
       @warn_on_extra_files = warn_on_extra_files
 
-      push_dir(@lib)
+      push_dir(@root_dir, namespace: namespace)
     end
 
     # @sig () -> void
@@ -38,13 +42,12 @@ module Zeitwerk
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@lib) 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

@@ -2,38 +2,46 @@
 
 module Zeitwerk::Loader::Callbacks
   include Zeitwerk::RealModName
+  extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @private
+  # @raise [Zeitwerk::NameError]
   # @sig (String) -> void
-  def on_file_autoloaded(file)
-    cref  = autoloads.delete(file)
-    cpath = cpath(*cref)
-
-    # If reloading is enabled, we need to put this constant for unloading
-    # regardless of what cdef? says. In Ruby < 3.1 the internal state is not
-    # fully cleared. Module#constants still includes it, and you need to
-    # remove_const. See https://github.com/ruby/ruby/pull/4715.
-    to_unload[cpath] = [file, cref] if reloading_enabled?
+  internal def on_file_autoloaded(file)
+    cref = autoloads.delete(file)
+
     Zeitwerk::Registry.unregister_autoload(file)
 
-    if cdef?(*cref)
-      log("constant #{cpath} loaded from file #{file}") if logger
-      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
-      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
+      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.
+      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[cref.path] = [file, cref] if reloading_enabled?
+
+      raise Zeitwerk::NameError.new(msg, cref.cname)
     end
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
-  # @private
   # @sig (String) -> void
-  def on_dir_autoloaded(dir)
-    # Module#autoload does not serialize concurrent requires, and we handle
-    # directories ourselves, so the callback needs to account for concurrency.
+  internal def on_dir_autoloaded(dir)
+    # Module#autoload does not serialize concurrent requires in CRuby < 3.2, and
+    # we handle directories ourselves without going through Kernel#require, so
+    # the callback needs to account for concurrency.
     #
     # Multi-threading would introduce a race condition here in which thread t1
     # autovivifies the module, and while autoloads for its children are being
@@ -43,10 +51,10 @@ module Zeitwerk::Loader::Callbacks
     # That not only would reassign the constant (undesirable per se) but, worse,
     # the module object created by t2 wouldn't have any of the autoloads for its
     # children, since t1 would have correctly deleted its namespace_dirs entry.
-    mutex2.synchronize do
+    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?
@@ -57,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
@@ -73,7 +81,7 @@ module Zeitwerk::Loader::Callbacks
   def on_namespace_loaded(namespace)
     if dirs = namespace_dirs.delete(real_mod_name(namespace))
       dirs.each do |dir|
-        set_autoloads_in_dir(dir, namespace)
+        define_autoloads_for_dir(dir, namespace)
       end
     end
   end

data/lib/zeitwerk/loader/config.rb

@@ -109,8 +109,7 @@ module Zeitwerk::Loader::Config
   # @raise [Zeitwerk::Error]
   # @sig (String | Pathname, Module) -> void
   def push_dir(path, namespace: Object)
-    # Note that Class < Module.
-    unless namespace.is_a?(Module)
+    unless namespace.is_a?(Module) # Note that Class < Module.
       raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
     end
 
@@ -149,14 +148,24 @@ module Zeitwerk::Loader::Config
   # instead. Keys are the absolute paths of the root directories as strings,
   # values are their corresponding namespaces, class or module objects.
   #
+  # If `ignored` is falsey (default), ignored root directories are filtered out.
+  #
   # These are read-only collections, please add to them with `push_dir`.
   #
   # @sig () -> Array[String] | Hash[String, Module]
-  def dirs(namespaces: false)
+  def dirs(namespaces: false, ignored: false)
     if namespaces
-      roots.clone
+      if ignored || ignored_paths.empty?
+        roots.clone
+      else
+        roots.reject { |root_dir, _namespace| ignored_path?(root_dir) }
+      end
     else
-      roots.keys
+      if ignored || ignored_paths.empty?
+        roots.keys
+      else
+        roots.keys.reject { |root_dir| ignored_path?(root_dir) }
+      end
     end.freeze
   end
 
@@ -288,9 +297,9 @@ module Zeitwerk::Loader::Config
     # Common use case.
     return false if ignored_paths.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if ignored_path?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if ignored_path?(path)
+      return false if roots.key?(path)
     end
 
     false
@@ -318,9 +327,9 @@ module Zeitwerk::Loader::Config
     # Optimize this common use case.
     return false if eager_load_exclusions.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if eager_load_exclusions.member?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if eager_load_exclusions.member?(path)
+      return false if roots.key?(path)
     end
 
     false

data/lib/zeitwerk/loader/eager_load.rb

@@ -45,8 +45,10 @@ module Zeitwerk::Loader::EagerLoad
 
       break if root_namespace = roots[dir]
 
+      basename = File.basename(dir)
+      return if hidden?(basename)
+
       unless collapse?(dir)
-        basename = File.basename(dir)
         cnames << inflector.camelize(basename, dir).to_sym
       end
     end
@@ -59,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
@@ -119,6 +121,8 @@ module Zeitwerk::Loader::EagerLoad
     raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
 
     basename = File.basename(abspath, ".rb")
+    raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+
     base_cname = inflector.camelize(basename, abspath).to_sym
 
     root_namespace = nil
@@ -129,8 +133,10 @@ module Zeitwerk::Loader::EagerLoad
 
       break if root_namespace = roots[dir]
 
+      basename = File.basename(dir)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+
       unless collapse?(dir)
-        basename = File.basename(dir)
         cnames << inflector.camelize(basename, dir).to_sym
       end
     end
@@ -139,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
@@ -158,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 (cref = autoloads[abspath]) && !shadowed_file?(abspath)
-            cget(*cref)
+        if ftype == :file
+          if (cref = autoloads[abspath])
+            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
@@ -183,7 +187,7 @@ module Zeitwerk::Loader::EagerLoad
   end
 
   # In order to invoke this method, the caller has to ensure `child` is a
-  # strict namespace descendendant of `root_namespace`.
+  # strict namespace descendant of `root_namespace`.
   #
   # @sig (Module, String, Module, Boolean) -> void
   private def eager_load_child_namespace(child, child_name, root_dir, root_namespace)
@@ -203,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