zeitwerk 2.5.4 → 2.6.12

data/lib/zeitwerk/loader/eager_load.rb

@@ -0,0 +1,234 @@
+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 cdef?(namespace, cname)
+      namespace = cget(namespace, cname)
+    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 = cget(namespace, cname)
+    end
+
+    raise Zeitwerk::Error.new("#{abspath} is shadowed") if shadowed_file?(abspath)
+
+    cget(namespace, base_cname)
+  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 to_eager_load = queue.shift
+      dir, namespace = to_eager_load
+
+      ls(dir) do |basename, abspath|
+        next if honour_exclusions && eager_load_exclusions.member?(abspath)
+
+        if ruby?(abspath)
+          if (cref = autoloads[abspath])
+            cget(*cref)
+          end
+        else
+          if collapse?(abspath)
+            queue << [abspath, namespace]
+          else
+            cname = inflector.camelize(basename, abspath).to_sym
+            queue << [abspath, cget(namespace, cname)]
+          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|
+          next unless dir?(abspath)
+
+          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

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,12 +12,28 @@ module Zeitwerk::Loader::Helpers
   # --- Files and directories ---------------------------------------------------------------------
 
   # @sig (String) { (String, String) -> void } -> void
-  def ls(dir)
-    Dir.each_child(dir) do |basename|
+  private def ls(dir)
+    children = Dir.children(dir)
+
+    # The order in which a directory is listed depends on the file system.
+    #
+    # Since client code may run in different platforms, it seems convenient to
+    # order directory entries. This provides consistent eager loading across
+    # platforms, for example.
+    children.sort!
+
+    children.each do |basename|
       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 roots.key?(abspath)
+        next if !has_at_least_one_ruby_file?(abspath)
+      else
+        next unless ruby?(abspath)
+      end
 
       # We freeze abspath because that saves allocations when passed later to
       # File methods. See #125.
@@ -28,20 +42,46 @@ module Zeitwerk::Loader::Helpers
   end
 
   # @sig (String) -> bool
-  def ruby?(path)
+  private def has_at_least_one_ruby_file?(dir)
+    to_visit = [dir]
+
+    while dir = to_visit.shift
+      ls(dir) do |_basename, abspath|
+        if dir?(abspath)
+          to_visit << abspath
+        else
+          return true
+        end
+      end
+    end
+
+    false
+  end
+
+  # @sig (String) -> bool
+  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)
+  # @sig (String) -> bool
+  private def hidden?(basename)
     basename.start_with?(".")
   end
 
+  # @sig (String) { (String) -> void } -> void
+  private def walk_up(abspath)
+    loop do
+      yield abspath
+      abspath, basename = File.split(abspath)
+      break if basename == "/"
+    end
+  end
+
   # --- Constants ---------------------------------------------------------------------------------
 
   # The autoload? predicate takes into account the ancestor chain of the
@@ -62,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
@@ -75,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