zeitwerk 2.6.2 → 2.6.10

data/lib/zeitwerk/loader/config.rb

@@ -4,85 +4,91 @@ require "set"
 require "securerandom"
 
 module Zeitwerk::Loader::Config
-  # Absolute paths of the root directories. Stored in a hash to preserve order,
-  # easily handle duplicates, have a fast lookup needed for detecting nested
-  # paths, and store namespaces as values.
+  extend Zeitwerk::Internal
+  include Zeitwerk::RealModName
+
+  # @sig #camelize
+  attr_accessor :inflector
+
+  # @sig #call | #debug | nil
+  attr_accessor :logger
+
+  # Absolute paths of the root directories, mapped to their respective root namespaces:
   #
   #   "/Users/fxn/blog/app/channels" => Object,
   #   "/Users/fxn/blog/app/adapters" => ActiveJob::QueueAdapters,
   #   ...
   #
+  # Stored in a hash to preserve order, easily handle duplicates, and have a
+  # fast lookup by directory.
+  #
   # This is a private collection maintained by the loader. The public
   # interface for it is `push_dir` and `dirs`.
   #
-  # @private
   # @sig Hash[String, Module]
-  attr_reader :root_dirs
-
-  # @sig #camelize
-  attr_accessor :inflector
+  attr_reader :roots
+  internal :roots
 
   # Absolute paths of files, directories, or glob patterns to be totally
   # ignored.
   #
-  # @private
   # @sig Set[String]
   attr_reader :ignored_glob_patterns
+  private :ignored_glob_patterns
 
   # The actual collection of absolute file and directory names at the time the
   # ignored glob patterns were expanded. Computed on setup, and recomputed on
   # reload.
   #
-  # @private
   # @sig Set[String]
   attr_reader :ignored_paths
+  private :ignored_paths
 
   # Absolute paths of directories or glob patterns to be collapsed.
   #
-  # @private
   # @sig 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.
   #
-  # @private
   # @sig Set[String]
   attr_reader :collapse_dirs
+  private :collapse_dirs
 
   # Absolute paths of files or directories not to be eager loaded.
   #
-  # @private
   # @sig Set[String]
   attr_reader :eager_load_exclusions
+  private :eager_load_exclusions
 
   # User-oriented callbacks to be fired on setup and on reload.
   #
-  # @private
   # @sig Array[{ () -> void }]
   attr_reader :on_setup_callbacks
+  private :on_setup_callbacks
 
   # User-oriented callbacks to be fired when a constant is loaded.
   #
-  # @private
   # @sig Hash[String, Array[{ (Object, String) -> void }]]
   #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
   attr_reader :on_load_callbacks
+  private :on_load_callbacks
 
   # User-oriented callbacks to be fired before constants are removed.
   #
-  # @private
   # @sig Hash[String, Array[{ (Object, String) -> void }]]
   #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
   attr_reader :on_unload_callbacks
-
-  # @sig #call | #debug | nil
-  attr_accessor :logger
+  private :on_unload_callbacks
 
   def initialize
-    @initialized_at         = Time.now
-    @root_dirs              = {}
     @inflector              = Zeitwerk::Inflector.new
+    @logger                 = self.class.default_logger
+    @tag                    = SecureRandom.hex(3)
+    @initialized_at         = Time.now
+    @roots                  = {}
     @ignored_glob_patterns  = Set.new
     @ignored_paths          = Set.new
     @collapse_glob_patterns = Set.new
@@ -92,8 +98,6 @@ module Zeitwerk::Loader::Config
     @on_setup_callbacks     = []
     @on_load_callbacks      = {}
     @on_unload_callbacks    = {}
-    @logger                 = self.class.default_logger
-    @tag                    = SecureRandom.hex(3)
   end
 
   # Pushes `path` to the list of root directories.
@@ -105,15 +109,18 @@ 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
 
+    unless real_mod_name(namespace)
+      raise Zeitwerk::Error, "root namespaces cannot be anonymous"
+    end
+
     abspath = File.expand_path(path)
     if dir?(abspath)
       raise_if_conflicting_directory(abspath)
-      root_dirs[abspath] = namespace
+      roots[abspath] = namespace
     else
       raise Zeitwerk::Error, "the root directory #{abspath} does not exist"
     end
@@ -141,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
-      root_dirs.clone
+      if ignored || ignored_paths.empty?
+        roots.clone
+      else
+        roots.reject { |root_dir, _namespace| ignored_path?(root_dir) }
+      end
     else
-      root_dirs.keys
+      if ignored || ignored_paths.empty?
+        roots.keys
+      else
+        roots.keys.reject { |root_dir| ignored_path?(root_dir) }
+      end
     end.freeze
   end
 
@@ -275,71 +292,73 @@ module Zeitwerk::Loader::Config
   # Returns true if the argument has been configured to be ignored, or is a
   # descendant of an ignored directory.
   #
-  # @private
   # @sig (String) -> bool
-  def ignores?(abspath)
+  internal def ignores?(abspath)
     # Common use case.
     return false if ignored_paths.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if ignored_paths.member?(abspath)
-      return false if root_dirs.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if ignored_path?(path)
+      return false if roots.key?(path)
     end
 
     false
   end
 
-  private
+  # @sig (String) -> bool
+  private def ignored_path?(abspath)
+    ignored_paths.member?(abspath)
+  end
 
   # @sig () -> Array[String]
-  def actual_root_dirs
-    root_dirs.reject do |root_dir, _namespace|
-      !dir?(root_dir) || ignored_paths.member?(root_dir)
+  private def actual_roots
+    roots.reject do |root_dir, _root_namespace|
+      !dir?(root_dir) || ignored_path?(root_dir)
     end
   end
 
   # @sig (String) -> bool
-  def root_dir?(dir)
-    root_dirs.key?(dir)
+  private def root_dir?(dir)
+    roots.key?(dir)
   end
 
   # @sig (String) -> bool
-  def excluded_from_eager_load?(abspath)
+  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 root_dirs.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
-  def collapse?(dir)
+  private def collapse?(dir)
     collapse_dirs.member?(dir)
   end
 
   # @sig (String | Pathname | Array[String | Pathname]) -> Array[String]
-  def expand_paths(paths)
+  private def expand_paths(paths)
     paths.flatten.map! { |path| File.expand_path(path) }
   end
 
   # @sig (Array[String]) -> Array[String]
-  def expand_glob_patterns(glob_patterns)
+  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
-  def recompute_ignored_paths
+  private def recompute_ignored_paths
     ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
   end
 
   # @sig () -> void
-  def recompute_collapse_dirs
+  private def recompute_collapse_dirs
     collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
   end
 end

data/lib/zeitwerk/loader/eager_load.rb

@@ -9,11 +9,12 @@ module Zeitwerk::Loader::EagerLoad
   def eager_load(force: false)
     mutex.synchronize do
       break if @eager_loaded
+      raise Zeitwerk::SetupRequired unless @setup
 
       log("eager load start") if logger
 
-      actual_root_dirs.each do |root_dir, namespace|
-        actual_eager_load_dir(root_dir, namespace, force: force)
+      actual_roots.each do |root_dir, root_namespace|
+        actual_eager_load_dir(root_dir, root_namespace, force: force)
       end
 
       autoloaded_dirs.each do |autoloaded_dir|
@@ -29,6 +30,8 @@ module Zeitwerk::Loader::EagerLoad
 
   # @sig (String | Pathname) -> void
   def eager_load_dir(path)
+    raise Zeitwerk::SetupRequired unless @setup
+
     abspath = File.expand_path(path)
 
     raise Zeitwerk::Error.new("#{abspath} is not a directory") unless dir?(abspath)
@@ -37,13 +40,15 @@ module Zeitwerk::Loader::EagerLoad
 
     root_namespace = nil
     walk_up(abspath) do |dir|
-      return if ignored_paths.member?(dir)
+      return if ignored_path?(dir)
       return if eager_load_exclusions.member?(dir)
 
-      break if root_namespace = root_dirs[dir]
+      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
@@ -67,29 +72,32 @@ module Zeitwerk::Loader::EagerLoad
 
   # @sig (Module) -> void
   def eager_load_namespace(mod)
+    raise Zeitwerk::SetupRequired unless @setup
+
     unless mod.is_a?(Module)
       raise Zeitwerk::Error, "#{mod.inspect} is not a class or module object"
     end
 
     return if @eager_loaded
 
-    actual_root_dirs.each do |root_dir, root_namespace|
+    mod_name = real_mod_name(mod)
+    return unless mod_name
+
+    actual_roots.each do |root_dir, root_namespace|
       if mod.equal?(Object)
         # 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)
       elsif root_namespace.equal?(Object)
-        eager_load_child_namespace(mod, root_dir, root_namespace)
+        eager_load_child_namespace(mod, mod_name, root_dir, root_namespace)
       else
-        mod_name = real_mod_name(mod)
         root_namespace_name = real_mod_name(root_namespace)
-
         if root_namespace_name.start_with?(mod_name + "::")
           actual_eager_load_dir(root_dir, root_namespace)
         elsif mod_name == root_namespace_name
           actual_eager_load_dir(root_dir, root_namespace)
         elsif mod_name.start_with?(root_namespace_name + "::")
-          eager_load_child_namespace(mod, root_dir, root_namespace)
+          eager_load_child_namespace(mod, mod_name, root_dir, root_namespace)
         else
           # Unrelated constant hierarchies, do nothing.
         end
@@ -110,21 +118,25 @@ module Zeitwerk::Loader::EagerLoad
 
     raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
     raise Zeitwerk::Error.new("#{abspath} is not a Ruby file") if dir?(abspath) || !ruby?(abspath)
-    raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_paths.member?(abspath)
+    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
     cnames = []
 
     walk_up(File.dirname(abspath)) do |dir|
-      raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_paths.member?(dir)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(dir)
+
+      break if root_namespace = roots[dir]
 
-      break if root_namespace = root_dirs[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
@@ -177,11 +189,11 @@ 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, root_dir, root_namespace)
-    suffix = real_mod_name(child)
+  private def eager_load_child_namespace(child, child_name, root_dir, root_namespace)
+    suffix = child_name
     unless root_namespace.equal?(Object)
       suffix = suffix.delete_prefix(real_mod_name(root_namespace) + "::")
     end
@@ -202,7 +214,7 @@ module Zeitwerk::Loader::EagerLoad
           next unless dir?(abspath)
 
           if collapse?(abspath)
-            current_dirs << abspath
+            dirs << abspath
           elsif segment == inflector.camelize(basename, abspath)
             next_dirs << abspath
           end

data/lib/zeitwerk/loader/helpers.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
 module Zeitwerk::Loader::Helpers
-  private
-
   # --- Logging -----------------------------------------------------------------------------------
 
   # @sig (String) -> void
-  def log(message)
+  private def log(message)
     method_name = logger.respond_to?(:debug) ? :debug : :call
     logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
   end
@@ -14,7 +12,7 @@ module Zeitwerk::Loader::Helpers
   # --- Files and directories ---------------------------------------------------------------------
 
   # @sig (String) { (String, String) -> void } -> void
-  def ls(dir)
+  private def ls(dir)
     children = Dir.children(dir)
 
     # The order in which a directory is listed depends on the file system.
@@ -28,10 +26,10 @@ module Zeitwerk::Loader::Helpers
       next if hidden?(basename)
 
       abspath = File.join(dir, basename)
-      next if ignored_paths.member?(abspath)
+      next if ignored_path?(abspath)
 
       if dir?(abspath)
-        next if root_dirs.key?(abspath)
+        next if roots.key?(abspath)
         next if !has_at_least_one_ruby_file?(abspath)
       else
         next unless ruby?(abspath)
@@ -44,7 +42,7 @@ module Zeitwerk::Loader::Helpers
   end
 
   # @sig (String) -> bool
-  def has_at_least_one_ruby_file?(dir)
+  private def has_at_least_one_ruby_file?(dir)
     to_visit = [dir]
 
     while dir = to_visit.shift
@@ -61,22 +59,22 @@ module Zeitwerk::Loader::Helpers
   end
 
   # @sig (String) -> bool
-  def ruby?(path)
+  private def ruby?(path)
     path.end_with?(".rb")
   end
 
   # @sig (String) -> bool
-  def dir?(path)
+  private def dir?(path)
     File.directory?(path)
   end
 
   # @sig (String) -> bool
-  def hidden?(basename)
+  private def hidden?(basename)
     basename.start_with?(".")
   end
 
   # @sig (String) { (String) -> void } -> void
-  def walk_up(abspath)
+  private def walk_up(abspath)
     loop do
       yield abspath
       abspath, basename = File.split(abspath)
@@ -104,11 +102,11 @@ module Zeitwerk::Loader::Helpers
   #
   # @sig (Module, Symbol) -> String?
   if method(:autoload?).arity == 1
-    def strict_autoload_path(parent, cname)
+    private def strict_autoload_path(parent, cname)
       parent.autoload?(cname) if cdef?(parent, cname)
     end
   else
-    def strict_autoload_path(parent, cname)
+    private def strict_autoload_path(parent, cname)
       parent.autoload?(cname, false)
     end
   end
@@ -117,23 +115,73 @@ module Zeitwerk::Loader::Helpers
   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.
-    def cpath(parent, cname)
+    private def cpath(parent, cname)
       Object == parent ? cname.name : "#{real_mod_name(parent)}::#{cname.name}"
     end
   else
-    def cpath(parent, cname)
+    private def cpath(parent, cname)
       Object == parent ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
     end
   end
 
   # @sig (Module, Symbol) -> bool
-  def cdef?(parent, cname)
+  private def cdef?(parent, cname)
     parent.const_defined?(cname, false)
   end
 
   # @raise [NameError]
   # @sig (Module, Symbol) -> Object
-  def cget(parent, cname)
+  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
+
+  CNAME_VALIDATOR = Module.new
+  private_constant :CNAME_VALIDATOR
+
+  # @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
+
+    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
+
+    begin
+      CNAME_VALIDATOR.const_defined?(cname, false)
+    rescue ::NameError => error
+      path_type = ruby?(abspath) ? "file" : "directory"
+
+      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
+
+    cname.to_sym
+  end
 end