zeitwerk 2.7.4 → 2.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c652e42a3b3a3a92704f1924bac194dc9b9c2db94641e6a9a3daf192480e7c7e
-  data.tar.gz: f24017f36733460e4c09ebc7d31de8ee95efda8c7e4f6aede34d4824f4922c3f
+  metadata.gz: '06683acd85eeb772fdb9757ae20bfb05e42ec465acfff3edcada546a399d9131'
+  data.tar.gz: 80e3cdede4e05607ef5c58c60a3f7824c6750dd1d19d8786352356025bde1d65
 SHA512:
-  metadata.gz: d1a853bd6e7b638dc60203e6ba515646260913925ff8d30aa7edcb817253e61a534beadca02159ee7dffa78204d5c0dff652a056d2be2d688b9ec52fc1f9ac91
-  data.tar.gz: 26824d767e2f18ef128b66b2b354a6fc7bc16754734eb27bc3c6bf20c8a3ed36a06e2d20c1cbed6b932a327cbb70f4aa58cedd88ed81bf3f8074ebdf90a52e27
+  metadata.gz: b37beb740e461d73a1bd1ae21ec4f2bf63bb5022f3a193e2718bb8e5d4f172bf9c1222ff2a33acc47fb390a34e50b8b4b65b5b762dc5f71c1971b25720081437
+  data.tar.gz: 02c85e17a3ab801c925157239386c9a5a105cc1b8b9d735f64c27c89d3a0371613f2cb3f27d49647d98bf3ad8220d3a3538c2bdae215a5890145136374eb1d3e

data/README.md

@@ -58,6 +58,7 @@
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Introspection](#introspection)
     - [`Zeitwerk::Loader#dirs`](#zeitwerkloaderdirs)
+    - [Autoloaded Constants](#autoloaded-constants)
     - [`Zeitwerk::Loader#cpath_expected_at`](#zeitwerkloadercpath_expected_at)
     - [`Zeitwerk::Loader#all_expected_cpaths`](#zeitwerkloaderall_expected_cpaths)
   - [Encodings](#encodings)
@@ -1263,6 +1264,18 @@ By default, ignored root directories are filtered out. If you want them included
 
 These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
 
+<a id="markdown-autoloaded-constants" name="autoloaded-constants"></a>
+#### Autoloaded Constants
+
+Zeitwerk does not keep track of autoloaded constants to minimize its memory footprint, but you can collect them with `on_load` if you will:
+
+```ruby
+autoloaded_cpaths = []
+loader.on_load do |cpath, _value, _abspath|
+  autoloaded_cpaths << cpath
+end
+```
+
 <a id="markdown-zeitwerkloadercpath_expected_at" name="zeitwerkloadercpath_expected_at"></a>
 #### `Zeitwerk::Loader#cpath_expected_at`
 
@@ -1408,6 +1421,12 @@ To run one particular suite, pass its file name as an argument:
 bin/test test/lib/zeitwerk/test_eager_load.rb
 ```
 
+That also accepts a line number:
+
+```
+bin/test test/lib/zeitwerk/test_eager_load.rb:52
+```
+
 Furthermore, the project has a development dependency on [`minitest-focus`](https://github.com/seattlerb/minitest-focus). To run an individual test mark it with `focus`:
 
 ```ruby

data/lib/zeitwerk/gem_loader.rb

@@ -42,12 +42,12 @@ module Zeitwerk
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@root_dir) do |basename, abspath, ftype|
+      @fs.ls(@root_dir) do |basename, abspath, ftype|
         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
+        cname = cname_for(basename_without_ext, abspath)
 
         warn(<<~EOS)
           WARNING: Zeitwerk defines the constant #{cname} after the #{ftype}

data/lib/zeitwerk/loader/callbacks.rb

@@ -12,12 +12,12 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
     Zeitwerk::Registry.autoloads.unregister(file)
 
     if cref.defined?
-      log("constant #{cref} loaded from file #{file}") if logger
+      log { "constant #{cref} loaded from file #{file}" }
       to_unload[file] = cref if reloading_enabled?
       run_on_load_callbacks(cref.path, cref.get, file) unless on_load_callbacks.empty?
     else
       msg = "expected file #{file} to define constant #{cref}, but didn't"
-      log(msg) if logger
+      log { msg }
 
       # Ruby still keeps the autoload defined, but we remove it because the
       # contract in Zeitwerk is more strict.
@@ -52,7 +52,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
     dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
         implicit_namespace = cref.set(Module.new)
-        log("module #{cref} autovivified from directory #{dir}") if logger
+        log { "module #{cref} autovivified from directory #{dir}" }
 
         to_unload[dir] = cref if reloading_enabled?
 

data/lib/zeitwerk/loader/config.rb

@@ -116,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"
@@ -290,28 +290,28 @@ module Zeitwerk::Loader::Config
     # 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
 
   #: (String) -> bool
-  private def ignored_path?(abspath)
+  internal def ignored_path?(abspath)
     ignored_paths.member?(abspath)
   end
 
   #: () -> 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
 
   #: (String) -> bool
-  private def root_dir?(dir)
+  internal def root_dir?(dir)
     roots.key?(dir)
   end
 
@@ -320,9 +320,9 @@ module Zeitwerk::Loader::Config
     # 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

data/lib/zeitwerk/loader/eager_load.rb

@@ -11,7 +11,7 @@ module Zeitwerk::Loader::EagerLoad
       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)
@@ -24,7 +24,7 @@ module Zeitwerk::Loader::EagerLoad
 
       @eager_loaded = true
 
-      log("eager load end") if logger
+      log { "eager load end" }
     end
   end
 
@@ -34,23 +34,21 @@ module Zeitwerk::Loader::EagerLoad
 
     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]
 
       basename = File.basename(dir)
-      return if hidden?(basename)
+      return if @fs.hidden?(basename)
 
-      unless collapse?(dir)
-        cnames << inflector.camelize(basename, dir).to_sym
-      end
+      paths << [basename, dir] unless collapse?(dir)
     end
 
     raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
@@ -58,7 +56,8 @@ 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 namespace.const_defined?(cname, false)
@@ -117,34 +116,33 @@ module Zeitwerk::Loader::EagerLoad
     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")
-    raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
-
-    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]
 
       basename = File.basename(dir)
-      raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if @fs.hidden?(basename)
 
-      unless collapse?(dir)
-        cnames << inflector.camelize(basename, dir).to_sym
-      end
+      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|
+    paths.reverse_each do |basename, dir|
+      cname = cname_for(basename, dir)
       namespace = namespace.const_get(cname, false)
     end
 
@@ -161,11 +159,11 @@ module Zeitwerk::Loader::EagerLoad
     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 (current_dir, namespace = queue.shift)
-      ls(current_dir) do |basename, abspath, ftype|
+      @fs.ls(current_dir) do |basename, abspath, ftype|
         next if honour_exclusions && eager_load_exclusions.member?(abspath)
 
         if ftype == :file
@@ -176,14 +174,14 @@ module Zeitwerk::Loader::EagerLoad
           if collapse?(abspath)
             queue << [abspath, namespace]
           else
-            cname = inflector.camelize(basename, abspath).to_sym
+            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
@@ -208,12 +206,12 @@ module Zeitwerk::Loader::EagerLoad
 
     suffix.split("::").each do |segment|
       while (dir = dirs.shift)
-        ls(dir) do |basename, abspath, ftype|
+        @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

data/lib/zeitwerk/loader/helpers.rb

@@ -1,105 +1,6 @@
 # frozen_string_literal: true
 
 module Zeitwerk::Loader::Helpers
-  # --- Logging -----------------------------------------------------------------------------------
-
-  #: (to_s() -> String) -> void
-  private def log(message)
-    method_name = logger.respond_to?(:debug) ? :debug : :call
-    logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
-  end
-
-  # --- Files and directories ---------------------------------------------------------------------
-
-  #: (String) { (String, String, Symbol) -> void } -> void
-  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_path?(abspath)
-
-      if dir?(abspath)
-        next if roots.key?(abspath)
-
-        if !has_at_least_one_ruby_file?(abspath)
-          log("directory #{abspath} is ignored because it has no Ruby files") if logger
-          next
-        end
-
-        ftype = :directory
-      else
-        next unless ruby?(abspath)
-        ftype = :file
-      end
-
-      # We freeze abspath because that saves allocations when passed later to
-      # File methods. See #125.
-      yield basename, abspath.freeze, ftype
-    end
-  end
-
-  # 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.
-  #
-  #: (String) -> bool
-  private def has_at_least_one_ruby_file?(dir)
-    to_visit = [dir]
-
-    while (dir = to_visit.shift)
-      Dir.each_child(dir) do |basename|
-        next if hidden?(basename)
-
-        abspath = File.join(dir, basename)
-        next if ignored_path?(abspath)
-
-        if dir?(abspath)
-          to_visit << abspath unless roots.key?(abspath)
-        else
-          return true if ruby?(abspath)
-        end
-      end
-    end
-
-    false
-  end
-
-  #: (String) -> bool
-  private def ruby?(path)
-    path.end_with?(".rb")
-  end
-
-  #: (String) -> bool
-  private def dir?(path)
-    File.directory?(path)
-  end
-
-  #: (String) -> bool
-  private def hidden?(basename)
-    basename.start_with?(".")
-  end
-
-  #: (String) { (String) -> void } -> void
-  private def walk_up(abspath)
-    loop do
-      yield abspath
-      abspath, basename = File.split(abspath)
-      break if basename == "/"
-    end
-  end
-
-  # --- Inflection --------------------------------------------------------------------------------
-
   CNAME_VALIDATOR = Module.new #: Module
   private_constant :CNAME_VALIDATOR
 
@@ -124,7 +25,7 @@ module Zeitwerk::Loader::Helpers
     begin
       CNAME_VALIDATOR.const_defined?(cname, false)
     rescue ::NameError => error
-      path_type = ruby?(abspath) ? "file" : "directory"
+      path_type = @fs.rb_extension?(abspath) ? "file" : "directory"
 
       raise Zeitwerk::NameError.new(<<~MESSAGE, error.name)
         #{error.message} inferred by #{inflector.class} from #{path_type}

data/lib/zeitwerk/loader.rb

@@ -9,6 +9,7 @@ module Zeitwerk
     require_relative "loader/callbacks"
     require_relative "loader/config"
     require_relative "loader/eager_load"
+    require_relative "loader/file_system"
 
     extend Internal
 
@@ -18,9 +19,6 @@ module Zeitwerk
     include Config
     include EagerLoad
 
-    MUTEX = Mutex.new #: Mutex
-    private_constant :MUTEX
-
     # Maps absolute paths for which an autoload has been set ---and not
     # executed--- to their corresponding Zeitwerk::Cref object.
     #
@@ -115,6 +113,7 @@ module Zeitwerk
       @shadowed_files  = Set.new
       @setup           = false
       @eager_loaded    = false
+      @fs              = FileSystem.new(self)
 
       @mutex = Mutex.new
       @dirs_autoload_monitor = Monitor.new
@@ -171,7 +170,7 @@ module Zeitwerk
             # and the constant path would escape unloadable_cpath? This is just
             # defensive code to clean things up as much as we are able to.
             unload_cref(cref)
-            unloaded_files.add(abspath) if ruby?(abspath)
+            unloaded_files.add(abspath) if @fs.rb_extension?(abspath)
           end
         end
 
@@ -189,7 +188,7 @@ module Zeitwerk
           end
 
           unload_cref(cref)
-          unloaded_files.add(abspath) if ruby?(abspath)
+          unloaded_files.add(abspath) if @fs.rb_extension?(abspath)
         end
 
         unless unloaded_files.empty?
@@ -199,7 +198,7 @@ module Zeitwerk
           # To make it aware of changes, the gem defines singleton methods in
           # $LOADED_FEATURES:
           #
-          #   https://github.com/Shopify/bootsnap/blob/main/lib/bootsnap/load_path_cache/core_ext/loaded_features.rb
+          #   https://github.com/rails/bootsnap/blob/main/lib/bootsnap/load_path_cache/core_ext/loaded_features.rb
           #
           # Rails applications may depend on bootsnap, so for unloading to work
           # in that setting it is preferable that we restrict our API choice to
@@ -255,15 +254,15 @@ module Zeitwerk
 
           prefix = cpath == "Object" ? "" : cpath + "::"
 
-          ls(dir) do |basename, abspath, ftype|
+          @fs.ls(dir) do |basename, abspath, ftype|
             if ftype == :file
               basename.delete_suffix!(".rb")
-              result[abspath] = prefix + inflector.camelize(basename, abspath)
+              result[abspath] = "#{prefix}#{cname_for(basename, abspath)}"
             else
               if collapse?(abspath)
                 queue << [abspath, cpath]
               else
-                queue << [abspath, prefix + inflector.camelize(basename, abspath)]
+                queue << [abspath, "#{prefix}#{cname_for(basename, abspath)}"]
               end
             end
           end
@@ -279,14 +278,16 @@ module Zeitwerk
 
       raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
 
-      return unless dir?(abspath) || ruby?(abspath)
+      ftype = @fs.supported_ftype?(abspath)
+      return unless ftype
+
       return if ignored_path?(abspath)
 
       paths = []
 
-      if ruby?(abspath)
+      if :file == ftype
         basename = File.basename(abspath, ".rb")
-        return if hidden?(basename)
+        return if @fs.hidden?(basename)
 
         paths << [basename, abspath]
         walk_up_from = File.dirname(abspath)
@@ -296,12 +297,12 @@ module Zeitwerk
 
       root_namespace = nil
 
-      walk_up(walk_up_from) do |dir|
+      @fs.walk_up(walk_up_from) do |dir|
         break if root_namespace = roots[dir]
         return if ignored_path?(dir)
 
         basename = File.basename(dir)
-        return if hidden?(basename)
+        return if @fs.hidden?(basename)
 
         paths << [basename, dir] unless collapse?(dir)
       end
@@ -363,6 +364,16 @@ module Zeitwerk
       shadowed_files.member?(file)
     end
 
+    #: { () -> String } -> void
+    internal def log
+      return unless logger
+
+      message = yield
+      method_name = logger.respond_to?(:debug) ? :debug : :call
+      logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
+    end
+
+
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
@@ -464,7 +475,7 @@ module Zeitwerk
 
     #: (String, Module) -> void
     private def define_autoloads_for_dir(dir, parent)
-      ls(dir) do |basename, abspath, ftype|
+      @fs.ls(dir) do |basename, abspath, ftype|
         if ftype == :file
           basename.delete_suffix!(".rb")
           cref = Cref.new(parent, cname_for(basename, abspath))
@@ -483,7 +494,7 @@ module Zeitwerk
     #: (Zeitwerk::Cref, String) -> void
     private def autoload_subdir(cref, subdir)
       if autoload_path = autoload_path_set_by_me_for?(cref)
-        if ruby?(autoload_path)
+        if @fs.rb_extension?(autoload_path)
           # Scanning visited a Ruby file first, and now a directory for the same
           # constant has been found. This means we are dealing with an explicit
           # namespace whose definition was seen first.
@@ -504,7 +515,7 @@ module Zeitwerk
       else
         # For whatever reason the constant that corresponds to this namespace has
         # already been defined, we have to recurse.
-        log("the namespace #{cref} already exists, descending into #{subdir}") if logger
+        log { "the namespace #{cref} already exists, descending into #{subdir}" }
         define_autoloads_for_dir(subdir, cref.get)
       end
     end
@@ -513,15 +524,15 @@ module Zeitwerk
     private def autoload_file(cref, file)
       if autoload_path = cref.autoload? || Registry.inceptions.registered?(cref)
         # First autoload for a Ruby file wins, just ignore subsequent ones.
-        if ruby?(autoload_path)
+        if @fs.rb_extension?(autoload_path)
           shadowed_files << file
-          log("file #{file} is ignored because #{autoload_path} has precedence") if logger
+          log { "file #{file} is ignored because #{autoload_path} has precedence" }
         else
           promote_namespace_from_implicit_to_explicit(dir: autoload_path, file: file, cref: cref)
         end
       elsif cref.defined?
         shadowed_files << file
-        log("file #{file} is ignored because #{cref} is already defined") if logger
+        log { "file #{file} is ignored because #{cref} is already defined" }
       else
         define_autoload(cref, file)
       end
@@ -535,7 +546,7 @@ module Zeitwerk
       autoloads.delete(dir)
       Registry.autoloads.unregister(dir)
 
-      log("earlier autoload for #{cref} discarded, it is actually an explicit namespace defined in #{file}") if logger
+      log { "earlier autoload for #{cref} discarded, it is actually an explicit namespace defined in #{file}" }
 
       # Order matters: When Module#const_added is triggered by the autoload, we
       # don't want the namespace to be registered yet.
@@ -548,10 +559,10 @@ module Zeitwerk
       cref.autoload(abspath)
 
       if logger
-        if ruby?(abspath)
-          log("autoload set for #{cref}, to be loaded from #{abspath}")
+        if @fs.rb_extension?(abspath)
+          log { "autoload set for #{cref}, to be loaded from #{abspath}" }
         else
-          log("autoload set for #{cref}, to be autovivified from #{abspath}")
+          log { "autoload set for #{cref}, to be autovivified from #{abspath}" }
         end
       end
 
@@ -595,28 +606,12 @@ module Zeitwerk
     end
 
     #: (String) -> void
-    private def raise_if_conflicting_directory(dir)
-      MUTEX.synchronize do
-        Registry.loaders.each do |loader|
-          next if loader == self
-
-          loader.__roots.each_key do |root_dir|
-            # Conflicting directories are rare, optimize for the common case.
-            next if !dir.start_with?(root_dir) && !root_dir.start_with?(dir)
-
-            dir_slash = dir + "/"
-            root_dir_slash = root_dir + "/"
-            next if !dir_slash.start_with?(root_dir_slash) && !root_dir_slash.start_with?(dir_slash)
-
-            next if ignores?(root_dir)
-            break if loader.__ignores?(dir)
-
-            require "pp" # Needed to have pretty_inspect available.
-            raise Error,
-              "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
-              " which is already managed by\n\n#{loader.pretty_inspect}\n"
-          end
-        end
+    private def raise_if_conflicting_root_dir(root_dir)
+      if loader = Registry.conflicting_root_dir?(self, root_dir)
+        require "pp" # Needed to have pretty_inspect available.
+        raise Error,
+          "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{root_dir}," \
+          " which is already managed by\n\n#{loader.pretty_inspect}\n"
       end
     end
 
@@ -630,7 +625,7 @@ module Zeitwerk
     #: (Zeitwerk::Cref) -> void
     private def unload_autoload(cref)
       cref.remove
-      log("autoload for #{cref} removed") if logger
+      log { "autoload for #{cref} removed" }
     end
 
     #: (Zeitwerk::Cref) -> void
@@ -642,7 +637,7 @@ module Zeitwerk
       # There are a few edge scenarios in which this may happen. If the constant
       # is gone, that is OK, anyway.
     else
-      log("#{cref} unloaded") if logger
+      log { "#{cref} unloaded" }
     end
   end
 end

data/lib/zeitwerk/real_mod_name.rb

@@ -7,7 +7,7 @@ module Zeitwerk::RealModName
 
   # Returns the real name of the class or module.
   #
-  # We need this indirection becasue the `name` method can be overridden, and
+  # We need this indirection because the `name` method can be overridden, and
   # because in practice what we really need is the constant paths of modules
   # with a permanent name, not so much what the user considers to be the name of
   # a certain class or module of theirs.

data/lib/zeitwerk/registry/loaders.rb

@@ -6,8 +6,8 @@ module Zeitwerk::Registry
     end
 
     #: ({ (Zeitwerk::Loader) -> void }) -> void
-    def each(&block)
-      @loaders.each(&block)
+    def each(&)
+      @loaders.each(&)
     end
 
     #: (Zeitwerk::Loader) -> void

data/lib/zeitwerk/registry.rb

@@ -44,6 +44,31 @@ module Zeitwerk
         gem_loaders_by_root_file.delete_if { |_, l| l == loader }
       end
 
+      #: (Zeitwerk::Loader, String) -> Zeitwerk::Loader?
+      def conflicting_root_dir?(loader, new_root_dir)
+        @mutex.synchronize do
+          loaders.each do |existing_loader|
+            next if existing_loader == loader
+
+            existing_loader.__roots.each_key do |existing_root_dir|
+              # Conflicting directories are rare, optimize for the common case.
+              next if !new_root_dir.start_with?(existing_root_dir) && !existing_root_dir.start_with?(new_root_dir)
+
+              new_root_dir_slash = new_root_dir + "/"
+              existing_root_dir_slash = existing_root_dir + "/"
+              next if !new_root_dir_slash.start_with?(existing_root_dir_slash) && !existing_root_dir_slash.start_with?(new_root_dir_slash)
+
+              next if loader.__ignores?(existing_root_dir)
+              break if existing_loader.__ignores?(new_root_dir)
+
+              return existing_loader
+            end
+          end
+
+          nil
+        end
+      end
+
       # This method returns always a loader, the same instance for the same root
       # file. That is how Zeitwerk::Loader.for_gem is idempotent.
       #
@@ -59,5 +84,6 @@ module Zeitwerk
     @autoloads                = Autoloads.new
     @explicit_namespaces      = ExplicitNamespaces.new
     @inceptions               = Inceptions.new
+    @mutex                    = Mutex.new
   end
 end

data/lib/zeitwerk/version.rb

@@ -2,5 +2,5 @@
 
 module Zeitwerk
   #: String
-  VERSION = "2.7.4"
+  VERSION = "2.7.5"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.7.4
+  version: 2.7.5
 platform: ruby
 authors:
 - Xavier Noria
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -36,6 +35,7 @@ files:
 - lib/zeitwerk/loader/callbacks.rb
 - lib/zeitwerk/loader/config.rb
 - lib/zeitwerk/loader/eager_load.rb
+- lib/zeitwerk/loader/file_system.rb
 - lib/zeitwerk/loader/helpers.rb
 - lib/zeitwerk/null_inflector.rb
 - lib/zeitwerk/real_mod_name.rb
@@ -53,7 +53,6 @@ metadata:
   changelog_uri: https://github.com/fxn/zeitwerk/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/fxn/zeitwerk
   bug_tracker_uri: https://github.com/fxn/zeitwerk/issues
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -68,8 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader
 test_files: []