zeitwerk 2.5.4 → 2.6.18

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

data/lib/zeitwerk/loader/eager_load.rb

@@ -0,0 +1,232 @@
+module Zeitwerk::Loader::EagerLoad
+  # Eager loads all files in the root directories, recursively. Files do not
+  # need to be in `$LOAD_PATH`, absolute file names are used. Ignored and
+  # shadowed files are not eager loaded. You can opt-out specifically in
+  # specific files and directories with `do_not_eager_load`, and that can be
+  # overridden passing `force: true`.
+  #
+  # @sig (true | false) -> void
+  def eager_load(force: false)
+    mutex.synchronize do
+      break if @eager_loaded
+      raise Zeitwerk::SetupRequired unless @setup
+
+      log("eager load start") if logger
+
+      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|
+        Zeitwerk::Registry.unregister_autoload(autoloaded_dir)
+      end
+      autoloaded_dirs.clear
+
+      @eager_loaded = true
+
+      log("eager load end") if logger
+    end
+  end
+
+  # @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)
+
+    cnames = []
+
+    root_namespace = nil
+    walk_up(abspath) do |dir|
+      return if ignored_path?(dir)
+      return if eager_load_exclusions.member?(dir)
+
+      break if root_namespace = roots[dir]
+
+      basename = File.basename(dir)
+      return if hidden?(basename)
+
+      unless collapse?(dir)
+        cnames << inflector.camelize(basename, dir).to_sym
+      end
+    end
+
+    raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
+
+    return if @eager_loaded
+
+    namespace = root_namespace
+    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 namespace.const_defined?(cname, false)
+      namespace = namespace.const_get(cname, false)
+    end
+
+    # A shortcircuiting test depends on the invocation of this method. Please
+    # keep them in sync if refactored.
+    actual_eager_load_dir(abspath, namespace)
+  end
+
+  # @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
+
+    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, mod_name, root_dir, root_namespace)
+      else
+        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, mod_name, root_dir, root_namespace)
+        else
+          # Unrelated constant hierarchies, do nothing.
+        end
+      end
+    end
+  end
+
+  # Loads the given Ruby file.
+  #
+  # Raises if the argument is ignored, shadowed, or not managed by the receiver.
+  #
+  # 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
+  def load_file(path)
+    abspath = File.expand_path(path)
+
+    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_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_path?(dir)
+
+      break if root_namespace = roots[dir]
+
+      basename = File.basename(dir)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+
+      unless collapse?(dir)
+        cnames << inflector.camelize(basename, dir).to_sym
+      end
+    end
+
+    raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
+
+    namespace = root_namespace
+    cnames.reverse_each do |cname|
+      namespace = namespace.const_get(cname, false)
+    end
+
+    raise Zeitwerk::Error.new("#{abspath} is shadowed") if shadowed_file?(abspath)
+
+    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
+  private def actual_eager_load_dir(dir, namespace, force: false)
+    honour_exclusions = !force
+    return if honour_exclusions && excluded_from_eager_load?(dir)
+
+    log("eager load directory #{dir} start") if logger
+
+    queue = [[dir, namespace]]
+    while (current_dir, namespace = queue.shift)
+      ls(current_dir) do |basename, abspath, ftype|
+        next if honour_exclusions && eager_load_exclusions.member?(abspath)
+
+        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, namespace.const_get(cname, false)]
+          end
+        end
+      end
+    end
+
+    log("eager load directory #{dir} end") if logger
+  end
+
+  # 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
+  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
+
+    # These directories are at the same namespace level, there may be more if
+    # we find collapsed ones. As we scan, we look for matches for the first
+    # segment, and store them in `next_dirs`. If there are any, we look for
+    # the next segments in those matches. Repeat.
+    #
+    # If we exhaust the search locating directories that match all segments,
+    # we just need to eager load those ones.
+    dirs = [root_dir]
+    next_dirs = []
+
+    suffix.split("::").each do |segment|
+      while (dir = dirs.shift)
+        ls(dir) do |basename, abspath, ftype|
+          next unless ftype == :directory
+
+          if collapse?(abspath)
+            dirs << abspath
+          elsif segment == inflector.camelize(basename, abspath)
+            next_dirs << abspath
+          end
+        end
+      end
+
+      return if next_dirs.empty?
+
+      dirs.replace(next_dirs)
+      next_dirs.clear
+    end
+
+    dirs.each do |dir|
+      actual_eager_load_dir(dir, child)
+    end
+  end
+end