zeitwerk 2.6.7 → 2.7.3

data/lib/zeitwerk/loader/config.rb

@@ -7,10 +7,10 @@ module Zeitwerk::Loader::Config
   extend Zeitwerk::Internal
   include Zeitwerk::RealModName
 
-  # @sig #camelize
+  #: camelize(String, String) -> String
   attr_accessor :inflector
 
-  # @sig #call | #debug | nil
+  #: call(String) -> void | debug(String) -> void | nil
   attr_accessor :logger
 
   # Absolute paths of the root directories, mapped to their respective root namespaces:
@@ -25,14 +25,13 @@ module Zeitwerk::Loader::Config
   # This is a private collection maintained by the loader. The public
   # interface for it is `push_dir` and `dirs`.
   #
-  # @sig Hash[String, Module]
+  #: Hash[String, Module]
   attr_reader :roots
   internal :roots
 
-  # Absolute paths of files, directories, or glob patterns to be totally
-  # ignored.
+  # Absolute paths of files, directories, or glob patterns to be ignored.
   #
-  # @sig Set[String]
+  #: Set[String]
   attr_reader :ignored_glob_patterns
   private :ignored_glob_patterns
 
@@ -40,46 +39,46 @@ module Zeitwerk::Loader::Config
   # ignored glob patterns were expanded. Computed on setup, and recomputed on
   # reload.
   #
-  # @sig Set[String]
+  #: Set[String]
   attr_reader :ignored_paths
   private :ignored_paths
 
   # Absolute paths of directories or glob patterns to be collapsed.
   #
-  # @sig Set[String]
+  #: Set[String]
   attr_reader :collapse_glob_patterns
   private :collapse_glob_patterns
 
   # The actual collection of absolute directory names at the time the collapse
   # glob patterns were expanded. Computed on setup, and recomputed on reload.
   #
-  # @sig Set[String]
+  #: Set[String]
   attr_reader :collapse_dirs
   private :collapse_dirs
 
   # Absolute paths of files or directories not to be eager loaded.
   #
-  # @sig Set[String]
+  #: Set[String]
   attr_reader :eager_load_exclusions
   private :eager_load_exclusions
 
   # User-oriented callbacks to be fired on setup and on reload.
   #
-  # @sig Array[{ () -> void }]
+  #: Array[{ () -> void }]
   attr_reader :on_setup_callbacks
   private :on_setup_callbacks
 
   # 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 }]]
+  #: 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 }]]
+  #: Hash[String, Array[{ (top, String) -> void }]]
+  #| Hash[Symbol, Array[{ (String, top, String) -> void }]]
   attr_reader :on_unload_callbacks
   private :on_unload_callbacks
 
@@ -106,11 +105,9 @@ module Zeitwerk::Loader::Config
   # the same process already manages that directory or one of its ascendants or
   # descendants.
   #
-  # @raise [Zeitwerk::Error]
-  # @sig (String | Pathname, Module) -> void
+  #: (String | Pathname, namespace: Module) -> void ! Zeitwerk::Error
   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
 
@@ -132,14 +129,14 @@ module Zeitwerk::Loader::Config
   # Implemented as a method instead of via attr_reader for symmetry with the
   # writer below.
   #
-  # @sig () -> String
+  #: () -> String
   def tag
     @tag
   end
 
   # Sets a tag for the loader, useful for logging.
   #
-  # @sig (#to_s) -> void
+  #: (to_s() -> String) -> void
   def tag=(tag)
     @tag = tag.to_s
   end
@@ -153,7 +150,7 @@ module Zeitwerk::Loader::Config
   #
   # These are read-only collections, please add to them with `push_dir`.
   #
-  # @sig () -> Array[String] | Hash[String, Module]
+  #: (?namespaces: boolish, ?ignored: boolish) -> Array[String] | Hash[String, Module]
   def dirs(namespaces: false, ignored: false)
     if namespaces
       if ignored || ignored_paths.empty?
@@ -173,8 +170,7 @@ module Zeitwerk::Loader::Config
   # You need to call this method before setup in order to be able to reload.
   # There is no way to undo this, either you want to reload or you don't.
   #
-  # @raise [Zeitwerk::Error]
-  # @sig () -> void
+  #: () -> void ! Zeitwerk::Error
   def enable_reloading
     mutex.synchronize do
       break if @reloading_enabled
@@ -187,7 +183,7 @@ module Zeitwerk::Loader::Config
     end
   end
 
-  # @sig () -> bool
+  #: () -> bool
   def reloading_enabled?
     @reloading_enabled
   end
@@ -195,14 +191,14 @@ module Zeitwerk::Loader::Config
   # Let eager load ignore the given files or directories. The constants defined
   # in those files are still autoloadable.
   #
-  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  #: (*(String | Pathname | Array[String | Pathname])) -> void
   def do_not_eager_load(*paths)
     mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
   end
 
   # Configure files, directories, or glob patterns to be totally ignored.
   #
-  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  #: (*(String | Pathname | Array[String | Pathname])) -> void
   def ignore(*glob_patterns)
     glob_patterns = expand_paths(glob_patterns)
     mutex.synchronize do
@@ -213,7 +209,7 @@ module Zeitwerk::Loader::Config
 
   # Configure directories or glob patterns to be collapsed.
   #
-  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  #: (*(String | Pathname | Array[String | Pathname])) -> void
   def collapse(*glob_patterns)
     glob_patterns = expand_paths(glob_patterns)
     mutex.synchronize do
@@ -225,7 +221,7 @@ module Zeitwerk::Loader::Config
   # Configure a block to be called after setup and on each reload.
   # If setup was already done, the block runs immediately.
   #
-  # @sig () { () -> void } -> void
+  #: () { () -> void } -> void
   def on_setup(&block)
     mutex.synchronize do
       on_setup_callbacks << block
@@ -247,9 +243,7 @@ module Zeitwerk::Loader::Config
   #     # ...
   #   end
   #
-  # @raise [TypeError]
-  # @sig (String) { (Object, String) -> void } -> void
-  #      (:ANY) { (String, Object, String) -> void } -> void
+  #: (String?) { (top, String) -> void } -> void ! TypeError
   def on_load(cpath = :ANY, &block)
     raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
 
@@ -272,9 +266,7 @@ module Zeitwerk::Loader::Config
   #     # ...
   #   end
   #
-  # @raise [TypeError]
-  # @sig (String) { (Object) -> void } -> void
-  #      (:ANY) { (String, Object) -> void } -> void
+  #: (String?) { (top, String) -> void } -> void ! TypeError
   def on_unload(cpath = :ANY, &block)
     raise TypeError, "on_unload only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
 
@@ -285,7 +277,7 @@ module Zeitwerk::Loader::Config
 
   # Logs to `$stdout`, handy shortcut for debugging.
   #
-  # @sig () -> void
+  #: () -> void
   def log!
     @logger = ->(msg) { puts msg }
   end
@@ -293,72 +285,72 @@ module Zeitwerk::Loader::Config
   # Returns true if the argument has been configured to be ignored, or is a
   # descendant of an ignored directory.
   #
-  # @sig (String) -> bool
+  #: (String) -> bool
   internal def ignores?(abspath)
     # 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
   end
 
-  # @sig (String) -> bool
+  #: (String) -> bool
   private def ignored_path?(abspath)
     ignored_paths.member?(abspath)
   end
 
-  # @sig () -> Array[String]
+  #: () -> Array[String]
   private def actual_roots
     roots.reject do |root_dir, _root_namespace|
       !dir?(root_dir) || ignored_path?(root_dir)
     end
   end
 
-  # @sig (String) -> bool
+  #: (String) -> bool
   private def root_dir?(dir)
     roots.key?(dir)
   end
 
-  # @sig (String) -> bool
+  #: (String) -> bool
   private def excluded_from_eager_load?(abspath)
     # 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
   end
 
-  # @sig (String) -> bool
+  #: (String) -> bool
   private def collapse?(dir)
     collapse_dirs.member?(dir)
   end
 
-  # @sig (String | Pathname | Array[String | Pathname]) -> Array[String]
+  #: (String | Pathname | Array[String | Pathname]) -> Array[String]
   private def expand_paths(paths)
     paths.flatten.map! { |path| File.expand_path(path) }
   end
 
-  # @sig (Array[String]) -> Array[String]
+  #: (Array[String]) -> Array[String]
   private def expand_glob_patterns(glob_patterns)
     # Note that Dir.glob works with regular file names just fine. That is,
     # glob patterns technically need no wildcards.
     glob_patterns.flat_map { |glob_pattern| Dir.glob(glob_pattern) }
   end
 
-  # @sig () -> void
+  #: () -> void
   private def recompute_ignored_paths
     ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
   end
 
-  # @sig () -> void
+  #: () -> void
   private def recompute_collapse_dirs
     collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
   end

data/lib/zeitwerk/loader/eager_load.rb

@@ -5,7 +5,7 @@ module Zeitwerk::Loader::EagerLoad
   # specific files and directories with `do_not_eager_load`, and that can be
   # overridden passing `force: true`.
   #
-  # @sig (true | false) -> void
+  #: (?force: boolish) -> void
   def eager_load(force: false)
     mutex.synchronize do
       break if @eager_loaded
@@ -18,7 +18,7 @@ module Zeitwerk::Loader::EagerLoad
       end
 
       autoloaded_dirs.each do |autoloaded_dir|
-        Zeitwerk::Registry.unregister_autoload(autoloaded_dir)
+        Zeitwerk::Registry.autoloads.unregister(autoloaded_dir)
       end
       autoloaded_dirs.clear
 
@@ -28,7 +28,7 @@ module Zeitwerk::Loader::EagerLoad
     end
   end
 
-  # @sig (String | Pathname) -> void
+  #: (String | Pathname) -> void
   def eager_load_dir(path)
     raise Zeitwerk::SetupRequired unless @setup
 
@@ -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
@@ -68,7 +70,7 @@ module Zeitwerk::Loader::EagerLoad
     actual_eager_load_dir(abspath, namespace)
   end
 
-  # @sig (Module) -> void
+  #: (Module) -> void
   def eager_load_namespace(mod)
     raise Zeitwerk::SetupRequired unless @setup
 
@@ -82,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)
@@ -110,7 +112,7 @@ module Zeitwerk::Loader::EagerLoad
   # The method is implemented as `constantize` for files, in a sense, to be able
   # to descend orderly and make sure the file is loadable.
   #
-  # @sig (String | Pathname) -> void
+  #: (String | Pathname) -> void
   def load_file(path)
     abspath = File.expand_path(path)
 
@@ -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,18 +145,18 @@ 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
   # corresponds to `dir`.
   #
-  # @sig (String, Module, Boolean) -> void
+  #: (String, Module, ?force: boolish) -> void
   private def actual_eager_load_dir(dir, namespace, force: false)
     honour_exclusions = !force
     return if honour_exclusions && excluded_from_eager_load?(dir)
@@ -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
@@ -185,7 +189,7 @@ module Zeitwerk::Loader::EagerLoad
   # In order to invoke this method, the caller has to ensure `child` is a
   # strict namespace descendant of `root_namespace`.
   #
-  # @sig (Module, String, Module, Boolean) -> void
+  #: (Module, String, String, Module) -> void
   private def eager_load_child_namespace(child, child_name, root_dir, root_namespace)
     suffix = child_name
     unless root_namespace.equal?(Object)
@@ -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

@@ -3,7 +3,7 @@
 module Zeitwerk::Loader::Helpers
   # --- Logging -----------------------------------------------------------------------------------
 
-  # @sig (String) -> void
+  #: (to_s() -> String) -> void
   private def log(message)
     method_name = logger.respond_to?(:debug) ? :debug : :call
     logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
@@ -11,7 +11,7 @@ module Zeitwerk::Loader::Helpers
 
   # --- Files and directories ---------------------------------------------------------------------
 
-  # @sig (String) { (String, String) -> void } -> void
+  #: (String) { (String, String, Symbol) -> void } -> void
   private def ls(dir)
     children = Dir.children(dir)
 
@@ -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
 
-  # @sig (String) -> bool
+  # 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.
+  #
+  #: (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
@@ -58,22 +74,22 @@ module Zeitwerk::Loader::Helpers
     false
   end
 
-  # @sig (String) -> bool
+  #: (String) -> bool
   private def ruby?(path)
     path.end_with?(".rb")
   end
 
-  # @sig (String) -> bool
+  #: (String) -> bool
   private def dir?(path)
     File.directory?(path)
   end
 
-  # @sig (String) -> bool
+  #: (String) -> bool
   private def hidden?(basename)
     basename.start_with?(".")
   end
 
-  # @sig (String) { (String) -> void } -> void
+  #: (String) { (String) -> void } -> void
   private def walk_up(abspath)
     loop do
       yield abspath
@@ -82,62 +98,48 @@ 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 #: Module
+  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}"
+  #: (String, String) -> Symbol ! Zeitwerk::NameError
+  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