zeitwerk 2.5.0 → 2.6.12

data/lib/zeitwerk/error.rb

@@ -5,8 +5,17 @@ module Zeitwerk
   end
 
   class ReloadingDisabledError < Error
+    def initialize
+      super("can't reload, please call loader.enable_reloading before setup")
+    end
   end
 
   class NameError < ::NameError
   end
+
+  class SetupRequired < Error
+    def initialize
+      super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
+    end
+  end
 end

data/lib/zeitwerk/explicit_namespace.rb

@@ -11,28 +11,28 @@ module Zeitwerk
   module ExplicitNamespace # :nodoc: all
     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.
       #
-      # @private
       # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :cpaths
+      private :cpaths
 
-      # @private
       # @sig Mutex
       attr_reader :mutex
+      private :mutex
 
-      # @private
       # @sig TracePoint
       attr_reader :tracer
+      private :tracer
 
       # Asserts `cpath` corresponds to an explicit namespace for which `loader`
       # is responsible.
       #
-      # @private
       # @sig (String, Zeitwerk::Loader) -> void
-      def register(cpath, loader)
+      internal def register(cpath, loader)
         mutex.synchronize do
           cpaths[cpath] = loader
           # We check enabled? because, looking at the C source code, enabling an
@@ -41,24 +41,28 @@ module Zeitwerk
         end
       end
 
-      # @private
       # @sig (Zeitwerk::Loader) -> void
-      def unregister_loader(loader)
+      internal def unregister_loader(loader)
         cpaths.delete_if { |_cpath, l| l == loader }
         disable_tracer_if_unneeded
       end
 
-      private
+      # This is an internal method only used by the test suite.
+      #
+      # @sig (String) -> bool
+      internal def registered?(cpath)
+        cpaths.key?(cpath)
+      end
 
       # @sig () -> void
-      def disable_tracer_if_unneeded
+      private def disable_tracer_if_unneeded
         mutex.synchronize do
           tracer.disable if cpaths.empty?
         end
       end
 
       # @sig (TracePoint) -> void
-      def tracepoint_class_callback(event)
+      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.

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+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, 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, namespace:, warn_on_extra_files:)
+      super()
+
+      @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)
+      @root_dir            = File.dirname(root_file)
+      @warn_on_extra_files = warn_on_extra_files
+
+      push_dir(@root_dir, namespace: namespace)
+    end
+
+    # @sig () -> void
+    def setup
+      warn_on_extra_files if @warn_on_extra_files
+      super
+    end
+
+    private
+
+    # @sig () -> void
+    def warn_on_extra_files
+      expected_namespace_dir = @root_file.delete_suffix(".rb")
+
+      ls(@root_dir) do |basename, abspath|
+        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}
+
+              #{abspath}
+
+          To prevent that, please configure the loader to ignore it:
+
+              loader.ignore("\#{__dir__}/#{basename}")
+
+          Otherwise, there is a flag to silence this warning:
+
+              Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+        EOS
+      end
+    end
+  end
+end

data/lib/zeitwerk/internal.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# This is a private module.
+module Zeitwerk::Internal
+  def internal(method_name)
+    private method_name
+
+    mangled = "__#{method_name}"
+    alias_method mangled, method_name
+    public mangled
+  end
+end

data/lib/zeitwerk/kernel.rb

@@ -3,11 +3,11 @@
 module Kernel
   module_function
 
-  # We are going to decorate Kernel#require with two goals.
+  # Zeitwerk's main idea is to define autoloads for project constants, and then
+  # intercept them when triggered in this thin `Kernel#require` wrapper.
   #
-  # First, by intercepting Kernel#require calls, we are able to autovivify
-  # modules on required directories, and also do internal housekeeping when
-  # managed files are loaded.
+  # That allows us to complete the circle, invoke callbacks, autovivify modules,
+  # define autoloads for just autoloaded namespaces, update internal state, etc.
   #
   # On the other hand, if you publish a new version of a gem that is now managed
   # by Zeitwerk, client code can reference directly your classes and modules and
@@ -17,29 +17,32 @@ module Kernel
   #
   # We cannot decorate with prepend + super because Kernel has already been
   # included in Object, and changes in ancestors don't get propagated into
-  # already existing ancestor chains.
+  # already existing ancestor chains on Ruby < 3.0.
   alias_method :zeitwerk_original_require, :require
+  class << self
+    alias_method :zeitwerk_original_require, :require
+  end
 
   # @sig (String) -> true | false
   def require(path)
     if loader = Zeitwerk::Registry.loader_for(path)
       if path.end_with?(".rb")
-        zeitwerk_original_require(path).tap do |required|
-          loader.on_file_autoloaded(path) if required
-        end
+        required = zeitwerk_original_require(path)
+        loader.__on_file_autoloaded(path) if required
+        required
       else
-        loader.on_dir_autoloaded(path)
+        loader.__on_dir_autoloaded(path)
         true
       end
     else
-      zeitwerk_original_require(path).tap do |required|
-        if required
-          abspath = $LOADED_FEATURES.last
-          if loader = Zeitwerk::Registry.loader_for(abspath)
-            loader.on_file_autoloaded(abspath)
-          end
+      required = zeitwerk_original_require(path)
+      if required
+        abspath = $LOADED_FEATURES.last
+        if loader = Zeitwerk::Registry.loader_for(abspath)
+          loader.__on_file_autoloaded(abspath)
         end
       end
+      required
     end
   end
 

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
   # @sig (String) -> void
-  def on_file_autoloaded(file)
+  internal 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?
     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?
     else
-      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
+      msg = "expected file #{file} to define constant #{cpath}, 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)
+
+      # 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?
+
+      raise Zeitwerk::NameError.new(msg, cref.last)
     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
@@ -42,8 +50,8 @@ module Zeitwerk::Loader::Callbacks
     # Without the mutex and subsequent delete call, t2 would reset the module.
     # 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 lazy_subdirs entry.
-    mutex2.synchronize do
+    # 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
@@ -71,9 +79,9 @@ module Zeitwerk::Loader::Callbacks
   # @private
   # @sig (Module) -> void
   def on_namespace_loaded(namespace)
-    if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
-      subdirs.each do |subdir|
-        set_autoloads_in_dir(subdir, namespace)
+    if dirs = namespace_dirs.delete(real_mod_name(namespace))
+      dirs.each do |dir|
+        define_autoloads_for_dir(dir, namespace)
       end
     end
   end

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, and also be able to have a fast lookup,
-  # needed for detecting nested paths.
+  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/assets"   => true,
-  #   "/Users/fxn/blog/app/channels" => true,
+  #   "/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, true]
-  attr_reader :root_dirs
-
-  # @sig #camelize
-  attr_accessor :inflector
+  # @sig Hash[String, Module]
+  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
@@ -131,18 +138,35 @@ module Zeitwerk::Loader::Config
 
   # Sets a tag for the loader, useful for logging.
   #
-  # @param tag [#to_s]
   # @sig (#to_s) -> void
   def tag=(tag)
     @tag = tag.to_s
   end
 
-  # Absolute paths of the root directories. This is a read-only collection,
-  # please push here via `push_dir`.
+  # If `namespaces` is falsey (default), returns an array with the absolute
+  # paths of the root directories as strings. If truthy, returns a hash table
+  # instead. Keys are the absolute paths of the root directories as strings,
+  # values are their corresponding namespaces, class or module objects.
   #
-  # @sig () -> Array[String]
-  def dirs
-    root_dirs.keys.freeze
+  # 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, ignored: false)
+    if namespaces
+      if ignored || ignored_paths.empty?
+        roots.clone
+      else
+        roots.reject { |root_dir, _namespace| ignored_path?(root_dir) }
+      end
+    else
+      if ignored || ignored_paths.empty?
+        roots.keys
+      else
+        roots.keys.reject { |root_dir| ignored_path?(root_dir) }
+      end
+    end.freeze
   end
 
   # You need to call this method before setup in order to be able to reload.
@@ -265,57 +289,76 @@ module Zeitwerk::Loader::Config
     @logger = ->(msg) { puts msg }
   end
 
-  # @private
+  # Returns true if the argument has been configured to be ignored, or is a
+  # descendant of an ignored directory.
+  #
   # @sig (String) -> bool
-  def ignores?(abspath)
-    ignored_paths.any? do |ignored_path|
-      ignored_path == abspath || (dir?(ignored_path) && abspath.start_with?(ignored_path + "/"))
+  internal def ignores?(abspath)
+    # Common use case.
+    return false if ignored_paths.empty?
+
+    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)
-    eager_load_exclusions.member?(abspath)
+  private def excluded_from_eager_load?(abspath)
+    # Optimize this common use case.
+    return false if eager_load_exclusions.empty?
+
+    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