zeitwerk 2.6.7 → 2.6.18

data/lib/zeitwerk/loader/callbacks.rb

@@ -2,38 +2,45 @@
 
 module Zeitwerk::Loader::Callbacks
   include Zeitwerk::RealModName
+  extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @private
   # @sig (String) -> void
-  def on_file_autoloaded(file)
-    cref  = autoloads.delete(file)
-    cpath = cpath(*cref)
+  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
-      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
-      crem(*cref)
-      to_unload[cpath] = [file, cref] if reloading_enabled?
-      raise Zeitwerk::NameError.new(msg, cref.last)
+
+      # 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 +50,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,9 +64,9 @@ 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
@@ -73,7 +80,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
 
@@ -298,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
@@ -328,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
@@ -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

data/lib/zeitwerk/loader/helpers.rb

@@ -30,27 +30,45 @@ 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)
+      children = Dir.children(dir)
+
+      children.each 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,62 +100,49 @@ module Zeitwerk::Loader::Helpers
     end
   end
 
-  # --- Constants ---------------------------------------------------------------------------------
+  # --- Inflection --------------------------------------------------------------------------------
 
-  # 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
+  CNAME_VALIDATOR = Module.new
+  private_constant :CNAME_VALIDATOR
 
-  # @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}"
+  # @raise [Zeitwerk::NameError]
+  # @sig (String, String) -> Symbol
+  private def cname_for(basename, abspath)
+    cname = inflector.camelize(basename, abspath)
+
+    unless cname.is_a?(String)
+      raise TypeError, "#{inflector.class}#camelize must return a String, received #{cname.inspect}"
     end
-  else
-    private def cpath(parent, cname)
-      Object == parent ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
+
+    if cname.include?("::")
+      raise Zeitwerk::NameError.new(<<~MESSAGE, cname)
+        wrong constant name #{cname} inferred by #{inflector.class} from
+
+          #{abspath}
+
+        #{inflector.class}#camelize should return a simple constant name without "::"
+      MESSAGE
     end
-  end
 
-  # @sig (Module, Symbol) -> bool
-  private def cdef?(parent, cname)
-    parent.const_defined?(cname, false)
-  end
+    begin
+      CNAME_VALIDATOR.const_defined?(cname, false)
+    rescue ::NameError => error
+      path_type = ruby?(abspath) ? "file" : "directory"
 
-  # @raise [NameError]
-  # @sig (Module, Symbol) -> Object
-  private def cget(parent, cname)
-    parent.const_get(cname, false)
-  end
+      raise Zeitwerk::NameError.new(<<~MESSAGE, error.name)
+        #{error.message} inferred by #{inflector.class} from #{path_type}
+
+          #{abspath}
+
+        Possible ways to address this:
+
+          * Tell Zeitwerk to ignore this particular #{path_type}.
+          * Tell Zeitwerk to ignore one of its parent directories.
+          * Rename the #{path_type} to comply with the naming conventions.
+          * Modify the inflector to handle this case.
+      MESSAGE
+    end
 
-  # @raise [NameError]
-  # @sig (Module, Symbol) -> Object
-  private def crem(parent, cname)
-    parent.__send__(:remove_const, cname)
+    cname.to_sym
   end
 end