zeitwerk 2.6.8 → 2.7.5

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,8 +105,7 @@ 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)
     unless namespace.is_a?(Module) # Note that Class < Module.
       raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
@@ -118,8 +116,8 @@ module Zeitwerk::Loader::Config
     end
 
     abspath = File.expand_path(path)
-    if dir?(abspath)
-      raise_if_conflicting_directory(abspath)
+    if @fs.dir?(abspath)
+      raise_if_conflicting_root_dir(abspath)
       roots[abspath] = namespace
     else
       raise Zeitwerk::Error, "the root directory #{abspath} does not exist"
@@ -131,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
@@ -152,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?
@@ -172,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
@@ -186,7 +183,7 @@ module Zeitwerk::Loader::Config
     end
   end
 
-  # @sig () -> bool
+  #: () -> bool
   def reloading_enabled?
     @reloading_enabled
   end
@@ -194,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
@@ -212,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
@@ -224,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
@@ -246,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
 
@@ -271,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
 
@@ -284,7 +277,7 @@ module Zeitwerk::Loader::Config
 
   # Logs to `$stdout`, handy shortcut for debugging.
   #
-  # @sig () -> void
+  #: () -> void
   def log!
     @logger = ->(msg) { puts msg }
   end
@@ -292,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 |path|
+    @fs.walk_up(abspath) do |path|
       return true  if ignored_path?(path)
-      return false if roots.key?(path)
+      return false if root_dir?(path)
     end
 
     false
   end
 
-  # @sig (String) -> bool
-  private def ignored_path?(abspath)
+  #: (String) -> bool
+  internal 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)
+      !@fs.dir?(root_dir) || ignored_path?(root_dir)
     end
   end
 
-  # @sig (String) -> bool
-  private def root_dir?(dir)
+  #: (String) -> bool
+  internal 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 |path|
+    @fs.walk_up(abspath) do |path|
       return true  if eager_load_exclusions.member?(path)
-      return false if roots.key?(path)
+      return false if root_dir?(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,50 +5,50 @@ 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
       raise Zeitwerk::SetupRequired unless @setup
 
-      log("eager load start") if logger
+      log { "eager load start" }
 
       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)
+        Zeitwerk::Registry.autoloads.unregister(autoloaded_dir)
       end
       autoloaded_dirs.clear
 
       @eager_loaded = true
 
-      log("eager load end") if logger
+      log { "eager load end" }
     end
   end
 
-  # @sig (String | Pathname) -> void
+  #: (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)
+    raise Zeitwerk::Error.new("#{abspath} is not a directory") unless @fs.dir?(abspath)
 
-    cnames = []
+    paths = []
 
     root_namespace = nil
-    walk_up(abspath) do |dir|
+    @fs.walk_up(abspath) do |dir|
       return if ignored_path?(dir)
       return if eager_load_exclusions.member?(dir)
 
       break if root_namespace = roots[dir]
 
-      unless collapse?(dir)
-        basename = File.basename(dir)
-        cnames << inflector.camelize(basename, dir).to_sym
-      end
+      basename = File.basename(dir)
+      return if @fs.hidden?(basename)
+
+      paths << [basename, dir] unless collapse?(dir)
     end
 
     raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
@@ -56,11 +56,12 @@ module Zeitwerk::Loader::EagerLoad
     return if @eager_loaded
 
     namespace = root_namespace
-    cnames.reverse_each do |cname|
+    paths.reverse_each do |basename, dir|
+      cname = cname_for(basename, dir)
       # 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 +69,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 +83,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,82 +111,83 @@ 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)
 
     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 not a Ruby file") if !@fs.rb_extension?(abspath)
     raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
 
-    basename = File.basename(abspath, ".rb")
-    base_cname = inflector.camelize(basename, abspath).to_sym
+    file_basename = File.basename(abspath, ".rb")
+    raise Zeitwerk::Error.new("#{abspath} is ignored") if @fs.hidden?(file_basename)
 
     root_namespace = nil
-    cnames = []
+    paths = []
 
-    walk_up(File.dirname(abspath)) do |dir|
+    @fs.walk_up(File.dirname(abspath)) do |dir|
       raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(dir)
 
       break if root_namespace = roots[dir]
 
-      unless collapse?(dir)
-        basename = File.basename(dir)
-        cnames << inflector.camelize(basename, dir).to_sym
-      end
+      basename = File.basename(dir)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if @fs.hidden?(basename)
+
+      paths << [basename, dir] unless collapse?(dir)
     end
 
     raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
 
+    base_cname = cname_for(file_basename, abspath)
+
     namespace = root_namespace
-    cnames.reverse_each do |cname|
-      namespace = cget(namespace, cname)
+    paths.reverse_each do |basename, dir|
+      cname = cname_for(basename, dir)
+      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)
 
-    log("eager load directory #{dir} start") if logger
+    log { "eager load directory #{dir} start" }
 
     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)
+      @fs.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)]
+            cname = cname_for(basename, abspath)
+            queue << [abspath, namespace.const_get(cname, false)]
           end
         end
       end
     end
 
-    log("eager load directory #{dir} end") if logger
+    log { "eager load directory #{dir} end" }
   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
+  #: (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,13 +205,13 @@ 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)
+        @fs.ls(dir) do |basename, abspath, ftype|
+          next unless ftype == :directory
 
           if collapse?(abspath)
             dirs << abspath
-          elsif segment == inflector.camelize(basename, abspath)
+          elsif segment == cname_for(basename, abspath).to_s
             next_dirs << abspath
           end
         end

data/lib/zeitwerk/loader/file_system.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# This private class encapsulates interactions with the file system.
+#
+# It is used to list directories and check file types, and it encodes the
+# conventions documented in the README.
+#
+# @private
+class Zeitwerk::Loader::FileSystem # :nodoc:
+  #: (Zeitwerk::Loader) -> void
+  def initialize(loader)
+    @loader = loader
+  end
+
+  #: (String) { (String, String, Symbol) -> void } -> void
+  def ls(dir)
+    children = relevant_dir_entries(dir)
+
+    # The order in which a directory is listed depends on the file system.
+    #
+    # Since client code may run on different platforms, it seems convenient to
+    # sort directory entries. This provides more deterministic behavior, with
+    # consistent eager loading in particular.
+    children.sort_by!(&:first)
+
+    children.each do |basename, abspath, ftype|
+      if :directory == ftype && !has_at_least_one_ruby_file?(abspath)
+        @loader.__log { "directory #{abspath} is ignored because it has no Ruby files" }
+        next
+      end
+
+      yield basename, abspath, ftype
+    end
+  end
+
+  #: (String) { (String) -> void } -> void
+  def walk_up(abspath)
+    loop do
+      yield abspath
+      abspath, basename = File.split(abspath)
+      break if basename == "/"
+    end
+  end
+
+  # Encodes the documented conventions.
+  #
+  #: (String) -> Symbol?
+  def supported_ftype?(abspath)
+    if rb_extension?(abspath)
+      :file # By convention, we can avoid a syscall here.
+    elsif dir?(abspath)
+      :directory
+    end
+  end
+
+  #: (String) -> bool
+  def rb_extension?(path)
+    path.end_with?(".rb")
+  end
+
+  #: (String) -> bool
+  def dir?(path)
+    File.directory?(path)
+  end
+
+  #: (String) -> bool
+  def hidden?(basename)
+    basename.start_with?(".")
+  end
+
+  private
+
+  # 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 in the passed directory.
+  #
+  #: (String) -> bool
+  def has_at_least_one_ruby_file?(dir)
+    to_visit = [dir]
+
+    while (dir = to_visit.shift)
+      relevant_dir_entries(dir) do |_, abspath, ftype|
+        return true if :file == ftype
+        to_visit << abspath
+      end
+    end
+
+    false
+  end
+
+  #: (String) { (String, String, Symbol) -> void } -> void
+  #: (String) -> [[String, String, Symbol]]
+  def relevant_dir_entries(dir)
+    return enum_for(__method__, dir).to_a unless block_given?
+
+    each_ruby_file_or_directory(dir) do |basename, abspath, ftype|
+      next if @loader.__ignored_path?(abspath)
+
+      if :link == ftype
+        begin
+          ftype = File.stat(abspath).ftype.to_sym
+        rescue Errno::ENOENT
+          warn "ignoring broken symlink #{abspath}"
+          next
+        end
+      end
+
+      if :file == ftype
+        yield basename, abspath, ftype if rb_extension?(basename)
+      elsif :directory == ftype
+        # Conceptually, root directories represent a separate project tree.
+        yield basename, abspath, ftype unless @loader.__root_dir?(abspath)
+      end
+    end
+  end
+
+  # Dir.scan is more efficient in common platforms, but it is going to take a
+  # while for it to be available.
+  #
+  # The following compatibility methods have the same semantics but are written
+  # to favor the performance of the Ruby fallback, which can save syscalls.
+  #
+  # In particular, by convention, any directory entry with a .rb extension is
+  # assumed to be a file or a symlink to a file.
+  #
+  # These methods also freeze abspaths because that saves allocations when
+  # passed later to File methods. See https://github.com/fxn/zeitwerk/pull/125.
+
+  if Dir.respond_to?(:scan) # Available in Ruby 4.1.
+    #: (String) { (String, String, Symbol) -> void } -> void
+    def each_ruby_file_or_directory(dir)
+      Dir.scan(dir) do |basename, ftype|
+        next if hidden?(basename)
+
+        if rb_extension?(basename)
+          abspath = File.join(dir, basename).freeze
+          yield basename, abspath, :file # By convention.
+        elsif :directory == ftype
+          abspath = File.join(dir, basename).freeze
+          yield basename, abspath, :directory
+        elsif :link == ftype
+          abspath = File.join(dir, basename).freeze
+          yield basename, abspath, :directory if dir?(abspath)
+        end
+      end
+    end
+  else
+    #: (String) { (String, String, Symbol) -> void } -> void
+    def each_ruby_file_or_directory(dir)
+      Dir.each_child(dir) do |basename|
+        next if hidden?(basename)
+
+        if rb_extension?(basename)
+          abspath = File.join(dir, basename).freeze
+          yield basename, abspath, :file # By convention.
+        else
+          abspath = File.join(dir, basename).freeze
+          if dir?(abspath)
+            yield basename, abspath, :directory
+          end
+        end
+      end
+    end
+  end
+end