zeitwerk 2.6.1 → 2.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf4acabb8b402560402158aced0f30ae6bae5120dc65d719f4fb15c1385a2454
-  data.tar.gz: 0a297687455cf8c3924a64c5e36223c35b0f69712c807ee9bc70748f8c42ff37
+  metadata.gz: a554ef9e7a26b8edb48779c400a620aa694e54313626505d231fa3c72d4f66fe
+  data.tar.gz: 779e40bff86dbb627aef9dfd3ed897620994f7578a3673b640fad2a449c61a61
 SHA512:
-  metadata.gz: 1d6666a098ae430f452edcd8b5e458541f20b20c4ee5903c4d18fe19cdce5afe81d6311a1bff5f9412b18ae57274e9b13132f8d59d9189b0ccd6cf7711337d6e
-  data.tar.gz: a131561faa463e489f7e9c4898bc8e212b2f6814ba3ce634b7ef62e25467f38b88e4c63106e8d53ee933681e1f0dc196244d16f13c299d2ca0771ee4031655a1
+  metadata.gz: a9038b69db15d5800aec43f5e6d2367df5ea04f19b00f0cd9a76c36eebac1f7cc2e085442e05b4ece448ef0a717b8f10c5c75367d63dbdbfb916a3e2bf505fed
+  data.tar.gz: 065c3b61d2cc6fb82ae3e98ddca31c4d6842cb3d7f68187c822c7b6c97720cdbfa8de9c11b5b1ff749fc655d408cc98f72dd1107e08979a5249ba6451e2539ed

data/README.md

@@ -27,8 +27,14 @@
   - [Autoloading](#autoloading)
   - [Eager loading](#eager-loading)
     - [Eager load exclusions](#eager-load-exclusions)
+    - [Eager load directories](#eager-load-directories)
+    - [Eager load namespaces](#eager-load-namespaces)
+    - [Eager load namespaces shared by several loaders](#eager-load-namespaces-shared-by-several-loaders)
     - [Global eager load](#global-eager-load)
+  - [Loading individual files](#loading-individual-files)
   - [Reloading](#reloading)
+    - [Configuration and usage](#configuration-and-usage)
+    - [Thread-safety](#thread-safety)
   - [Inflection](#inflection)
     - [Zeitwerk::Inflector](#zeitwerkinflector)
     - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
@@ -44,6 +50,7 @@
     - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
     - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
     - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
+  - [Shadowed files](#shadowed-files)
   - [Edge cases](#edge-cases)
   - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
@@ -464,6 +471,75 @@ Which may be handy if the project eager loads in the test suite to [ensure proje
 
 The `force` flag does not affect ignored files and directories, those are still ignored.
 
+<a id="markdown-eager-load-directories" name="eager-load-directories"></a>
+#### Eager load directories
+
+The method `Zeitwerk::Loader#eager_load_dir` eager loads a given directory, recursively:
+
+```ruby
+loader.eager_load_dir("#{__dir__}/custom_web_app/routes")
+```
+
+This is useful when the loader is not eager loading the entire project, but you still need some subtree to be loaded for things to function properly.
+
+Both strings and `Pathname` objects are supported as arguments. If the argument is not a directory managed by the receiver, the method raises `Zeitwerk::Error`.
+
+[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](https://github.com/fxn/zeitwerk#shadowed-files) are not eager loaded.
+
+`Zeitwerk::Loader#eager_load_dir` is idempotent, but compatible with reloading. If you eager load a directory and then reload, eager loading that directory will load its (current) contents again.
+
+The method checks if a regular eager load was already executed, in which case it returns fast.
+
+Nested root directories which are descendants of the argument are skipped. Those subtrees are considered to be conceptually apart.
+
+<a id="markdown-eager-load-namespaces" name="eager-load-namespaces"></a>
+#### Eager load namespaces
+
+The method `Zeitwerk::Loader#eager_load_namespace` eager loads a given namespace, recursively:
+
+```ruby
+loader.eager_load_namespace(MyApp::Routes)
+```
+
+This is useful when the loader is not eager loading the entire project, but you still need some namespace to be loaded for things to function properly.
+
+The argument has to be a class or module object and the method raises `Zeitwerk::Error` otherwise.
+
+If the namespace is spread over multiple directories in the receiver's source tree, they are all eager loaded. For example, if you have a structure like
+
+```
+root_dir1/my_app/routes
+root_dir2/my_app/routes
+root_dir3/my_app/routes
+```
+
+where `root_directory{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
+
+There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
+
+This method is flexible about what it accepts. Its semantics have to be interpreted as: "_If_ you manage this namespace, or part of this namespace, please eager load what you got". In particular, if the receiver does not manage the namespace, it will simply do nothing, this is not an error condition.
+
+[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](https://github.com/fxn/zeitwerk#shadowed-files) are not eager loaded.
+
+`Zeitwerk::Loader#eager_load_namespace` is idempotent, but compatible with reloading. If you eager load a namespace and then reload, eager loading that namespace will load its (current) descendants again.
+
+The method checks if a regular eager load was already executed, in which case it returns fast.
+
+If root directories are assigned to custom namespaces, the method behaves as you'd expect, according to the namespacing relationship between the custom namespace and the argument.
+
+<a id="markdown-eager-load-namespaces-shared-by-several-loaders" name="eager-load-namespaces-shared-by-several-loaders"></a>
+#### Eager load namespaces shared by several loaders
+
+The method `Zeitwerk::Loader.eager_load_namespace` broadcasts `eager_load_namespace` to all loaders.
+
+```ruby
+Zeitwerk::Loader.eager_load_namespace(MyFramework::Routes)
+```
+
+This may be handy, for example, if a framework supports plugins and a shared namespace needs to be eager loaded for the framework to function properly.
+
+Please, note that loaders only eager load namespaces they manage, as documented above. Therefore, this method does not allow you to eager load namespaces not managed by Zeitwerk loaders.
+
 <a id="markdown-global-eager-load" name="global-eager-load"></a>
 #### Global eager load
 
@@ -479,9 +555,29 @@ Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager lo
 
 This method does not accept the `force` flag, since in general it wouldn't be a good idea to force eager loading in 3rd party code.
 
+<a id="markdown-loading-individual-files" name="loading-individual-files"></a>
+### Loading individual files
+
+The method `Zeitwerk::Loader#load_file` loads an individual Ruby file:
+
+```ruby
+loader.load_file("#{__dir__}/custom_web_app/routes.rb")
+```
+
+This is useful when the loader is not eager loading the entire project, but you still need an individual file to be loaded for things to function properly.
+
+Both strings and `Pathname` objects are supported as arguments. The method raises `Zeitwerk::Error` if the argument is not a Ruby file, is [ignored](#ignoring-parts-of-the-project), is [shadowed](https://github.com/fxn/zeitwerk#shadowed-files), or is not managed by the receiver.
+
+`Zeitwerk::Loader#load_file` is idempotent, but compatible with reloading. If you load a file and then reload, a new call will load its (current) contents again.
+
+If you want to eager load a directory, `Zeitwerk::Loader#eager_load_dir` is more efficient than invoking `Zeitwerk::Loader#load_file` on its files.
+
 <a id="markdown-reloading" name="reloading"></a>
 ### Reloading
 
+<a id="markdown-configuration-and-usage" name="configuration-and-usage"></a>
+#### Configuration and usage
+
 Zeitwerk is able to reload code, but you need to enable this feature:
 
 ```ruby
@@ -503,12 +599,34 @@ Reloading removes the currently loaded classes and modules and resets the loader
 
 It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
 
-Reloading is not thread-safe:
+<a id="markdown-thread-safety" name="thread-safety"></a>
+#### Thread-safety
+
+In order to reload safely, no other thread can be autoloading or reloading concurrently. Client code is responsible for this coordination.
 
-* You should not reload while another thread is reloading.
-* You should not autoload while another thread is reloading.
+For example, a web framework that serves each request in its own thread and has reloading enabled could create a read-write lock on boot like this:
+
+```ruby
+require "concurrent/atomic/read_write_lock"
 
-In order to reload in a thread-safe manner, frameworks need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible read/write lock: When a request comes in, the framework acquires the lock for reading at the beginning, and releases it at the end. On the other hand, the code in the framework responsible for the call to `Zeitwerk::Loader#reload` needs to acquire the lock for writing.
+MyFramework::RELOAD_RW_LOCK = Concurrent::ReadWriteLock.new
+```
+
+You acquire the lock for reading for serving each individual request:
+
+```ruby
+MyFramework::RELOAD_RW_LOCK.with_read_lock do
+  serve(request)
+end
+```
+
+Then, when a reload is triggered, just acquire the lock for writing in order to execute the method call safely:
+
+```ruby
+MyFramework::RELOAD_RW_LOCK.with_write_lock do
+  loader.reload
+end
+```
 
 On reloading, client code has to update anything that would otherwise be storing a stale object. For example, if the routing layer of a web framework stores reloadable controller class objects or instances in internal structures, on reload it has to refresh them somehow, possibly reevaluating routes.
 
@@ -905,10 +1023,39 @@ loader.ignore(tests)
 loader.setup
 ```
 
+<a id="markdown-shadowed-files" name="shadowed-files"></a>
+### Shadowed files
+
+In Ruby, if you have several files called `foo.rb` in different directories of `$LOAD_PATH` and execute
+
+```ruby
+require "foo"
+```
+
+the first one found gets loaded, and the rest are ignored.
+
+Zeitwerk behaves in a similar way. If `foo.rb` is present in several root directories (at the same namespace level), the constant `Foo` is autoloaded from the first one, and the rest of the files are not evaluated. If logging is enabled, you'll see something like
+
+```
+file #{file} is ignored because #{previous_occurrence} has precedence
+```
+
+(This message is not public interface and may change, you cannot rely on that exact wording.)
+
+Even if there's only one `foo.rb`, if the constant `Foo` is already defined when Zeitwerk finds `foo.rb`, then the file is ignored too. This could happen if `Foo` was defined by a dependency, for example. If logging is enabled, you'll see something like
+
+```
+file #{file} is ignored because #{constant_path} is already defined
+```
+
+(This message is not public interface and may change, you cannot rely on that exact wording.)
+
+Shadowing only applies to Ruby files, namespace definition can be spread over multiple directories. And you can also reopen third-party namespaces if done [orderly](#reopening-third-party-namespaces).
+
 <a id="markdown-edge-cases" name="edge-cases"></a>
 ### Edge cases
 
-A class or module that acts as a namespace:
+[Explicit namespaces](#explicit-namespaces) like `Trip` here:
 
 ```ruby
 # trip.rb
@@ -922,7 +1069,7 @@ module Trip::Geolocation
 end
 ```
 
-has to be defined with the `class` or `module` keywords, as in the example above.
+have to be defined with the `class`/`module` keywords, as in the example above.
 
 For technical reasons, raw constant assignment is not supported:
 
@@ -984,7 +1131,7 @@ require "active_job"
 require "active_job/queue_adapters"
 
 require "zeitwerk"
-# By passign the flag, we acknowledge the extra directory lib/active_job
+# By passing the flag, we acknowledge the extra directory lib/active_job
 # has to be managed by the loader and no warning has to be issued for it.
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.setup

data/lib/zeitwerk/gem_loader.rb

@@ -43,7 +43,7 @@ module Zeitwerk
         next if abspath == expected_namespace_dir
 
         basename_without_ext = basename.delete_suffix(".rb")
-        cname = inflector.camelize(basename_without_ext, abspath)
+        cname = inflector.camelize(basename_without_ext, abspath).to_sym
         ftype = dir?(abspath) ? "directory" : "file"
 
         warn(<<~EOS)

data/lib/zeitwerk/kernel.rb

@@ -19,6 +19,9 @@ module Kernel
   # included in Object, and changes in ancestors don't get propagated into
   # 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)

data/lib/zeitwerk/loader/callbacks.rb

@@ -42,7 +42,7 @@ 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.
+    # children, since t1 would have correctly deleted its namespace_dirs entry.
     mutex2.synchronize do
       if cref = autoloads.delete(dir)
         autovivified_module = cref[0].const_set(cref[1], Module.new)
@@ -71,9 +71,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|
+        set_autoloads_in_dir(dir, namespace)
       end
     end
   end

data/lib/zeitwerk/loader/config.rb

@@ -4,13 +4,12 @@ require "set"
 require "securerandom"
 
 module Zeitwerk::Loader::Config
-  # Absolute paths of the root directories. Stored in a hash to preserve
-  # order, easily handle duplicates, have a fast lookup needed for detecting
-  # nested paths, and store custom namespaces as values.
+  # Absolute paths of the root directories. Stored in a hash to preserve order,
+  # easily handle duplicates, have a fast lookup needed for detecting nested
+  # paths, and store namespaces as values.
   #
-  #   "/Users/fxn/blog/app/assets"   => Object,
   #   "/Users/fxn/blog/app/channels" => Object,
-  #   "/Users/fxn/blog/adapters"     => ActiveJob::QueueAdapters,
+  #   "/Users/fxn/blog/app/adapters" => ActiveJob::QueueAdapters,
   #   ...
   #
   # This is a private collection maintained by the loader. The public
@@ -273,12 +272,21 @@ module Zeitwerk::Loader::Config
     @logger = ->(msg) { puts msg }
   end
 
+  # Returns true if the argument has been configured to be ignored, or is a
+  # descendant of an ignored directory.
+  #
   # @private
   # @sig (String) -> bool
   def ignores?(abspath)
-    ignored_paths.any? do |ignored_path|
-      ignored_path == abspath || (dir?(ignored_path) && abspath.start_with?(ignored_path + "/"))
+    # Common use case.
+    return false if ignored_paths.empty?
+
+    walk_up(abspath) do |abspath|
+      return true  if ignored_paths.member?(abspath)
+      return false if root_dirs.key?(abspath)
     end
+
+    false
   end
 
   private
@@ -297,7 +305,15 @@ module Zeitwerk::Loader::Config
 
   # @sig (String) -> bool
   def excluded_from_eager_load?(abspath)
-    eager_load_exclusions.member?(abspath)
+    # Optimize this common use case.
+    return false if eager_load_exclusions.empty?
+
+    walk_up(abspath) do |abspath|
+      return true  if eager_load_exclusions.member?(abspath)
+      return false if root_dirs.key?(abspath)
+    end
+
+    false
   end
 
   # @sig (String) -> bool

data/lib/zeitwerk/loader/eager_load.rb

@@ -0,0 +1,222 @@
+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
+
+      log("eager load start") if logger
+
+      actual_root_dirs.each do |root_dir, namespace|
+        actual_eager_load_dir(root_dir, 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)
+    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_paths.member?(dir)
+      return if eager_load_exclusions.member?(dir)
+
+      break if root_namespace = root_dirs[dir]
+
+      unless collapse?(dir)
+        basename = File.basename(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)
+    unless mod.is_a?(Module)
+      raise Zeitwerk::Error, "#{mod.inspect} is not a class or module object"
+    end
+
+    return if @eager_loaded
+
+    actual_root_dirs.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, root_dir, root_namespace)
+      else
+        mod_name = real_mod_name(mod)
+        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, 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_paths.member?(abspath)
+
+    basename = File.basename(abspath, ".rb")
+    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_paths.member?(dir)
+
+      break if root_namespace = root_dirs[dir]
+
+      unless collapse?(dir)
+        basename = File.basename(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]) && !shadowed_file?(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 descendendant of `root_namespace`.
+  #
+  # @sig (Module, String, Module, Boolean) -> void
+  private def eager_load_child_namespace(child, root_dir, root_namespace)
+    suffix = real_mod_name(child)
+    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)
+            current_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

@@ -31,7 +31,8 @@ module Zeitwerk::Loader::Helpers
       next if ignored_paths.member?(abspath)
 
       if dir?(abspath)
-        next unless has_at_least_one_ruby_file?(abspath)
+        next if root_dirs.key?(abspath)
+        next if !has_at_least_one_ruby_file?(abspath)
       else
         next unless ruby?(abspath)
       end
@@ -74,6 +75,15 @@ module Zeitwerk::Loader::Helpers
     basename.start_with?(".")
   end
 
+  # @sig (String) { (String) -> void } -> void
+  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

data/lib/zeitwerk/loader.rb

@@ -7,11 +7,13 @@ module Zeitwerk
     require_relative "loader/helpers"
     require_relative "loader/callbacks"
     require_relative "loader/config"
+    require_relative "loader/eager_load"
 
     include RealModName
     include Callbacks
     include Helpers
     include Config
+    include EagerLoad
 
     MUTEX = Mutex.new
     private_constant :MUTEX
@@ -54,7 +56,7 @@ module Zeitwerk
     # @sig Hash[String, [String, [Module, Symbol]]]
     attr_reader :to_unload
 
-    # Maps constant paths of namespaces to arrays of corresponding directories.
+    # Maps namespace constant paths to their respective directories.
     #
     # For example, given this mapping:
     #
@@ -64,13 +66,24 @@ module Zeitwerk
     #     ...
     #   ]
     #
-    # when `Admin` gets defined we know that it plays the role of a namespace and
-    # that its children are spread over those directories. We'll visit them to set
-    # up the corresponding autoloads.
+    # when `Admin` gets defined we know that it plays the role of a namespace
+    # and that its children are spread over those directories. We'll visit them
+    # to set up the corresponding autoloads.
     #
     # @private
     # @sig Hash[String, Array[String]]
-    attr_reader :lazy_subdirs
+    attr_reader :namespace_dirs
+
+    # A shadowed file is a file managed by this loader that is ignored when
+    # setting autoloads because its matching constant is already taken.
+    #
+    # This private set is populated as we descend. For example, if the loader
+    # has only scanned the top-level, `shadowed_files` does not have shadowed
+    # files that may exist deep in the project tree yet.
+    #
+    # @private
+    # @sig Set[String]
+    attr_reader :shadowed_files
 
     # @private
     # @sig Mutex
@@ -86,7 +99,8 @@ module Zeitwerk
       @autoloads       = {}
       @autoloaded_dirs = []
       @to_unload       = {}
-      @lazy_subdirs    = Hash.new { |h, cpath| h[cpath] = [] }
+      @namespace_dirs  = Hash.new { |h, cpath| h[cpath] = [] }
+      @shadowed_files  = Set.new
       @mutex           = Mutex.new
       @mutex2          = Mutex.new
       @setup           = false
@@ -181,7 +195,8 @@ module Zeitwerk
         autoloads.clear
         autoloaded_dirs.clear
         to_unload.clear
-        lazy_subdirs.clear
+        namespace_dirs.clear
+        shadowed_files.clear
 
         Registry.on_unload(self)
         ExplicitNamespace.unregister_loader(self)
@@ -208,58 +223,6 @@ module Zeitwerk
       setup
     end
 
-    # Eager loads all files in the root directories, recursively. Files do not
-    # need to be in `$LOAD_PATH`, absolute file names are used. Ignored 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
-
-        log("eager load start") if logger
-
-        honour_exclusions = !force
-
-        queue = []
-        actual_root_dirs.each do |root_dir, namespace|
-          queue << [namespace, root_dir] unless honour_exclusions && excluded_from_eager_load?(root_dir)
-        end
-
-        while to_eager_load = queue.shift
-          namespace, dir = to_eager_load
-
-          ls(dir) do |basename, abspath|
-            next if honour_exclusions && excluded_from_eager_load?(abspath)
-
-            if ruby?(abspath)
-              if cref = autoloads[abspath]
-                cget(*cref)
-              end
-            elsif !root_dirs.key?(abspath)
-              if collapse?(abspath)
-                queue << [namespace, abspath]
-              else
-                cname = inflector.camelize(basename, abspath)
-                queue << [cget(namespace, cname), abspath]
-              end
-            end
-          end
-        end
-
-        autoloaded_dirs.each do |autoloaded_dir|
-          Registry.unregister_autoload(autoloaded_dir)
-        end
-        autoloaded_dirs.clear
-
-        @eager_loaded = true
-
-        log("eager load end") if logger
-      end
-    end
-
     # Says if the given constant path would be unloaded on reload. This
     # predicate returns `false` if reloading is disabled.
     #
@@ -285,6 +248,15 @@ module Zeitwerk
       ExplicitNamespace.unregister_loader(self)
     end
 
+    # The return value of this predicate is only meaningful if the loader has
+    # scanned the file. This is the case in the spots where we use it.
+    #
+    # @private
+    # @sig (String) -> Boolean
+    def shadowed_file?(file)
+      shadowed_files.member?(file)
+    end
+
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
@@ -318,6 +290,15 @@ module Zeitwerk
         Registry.loaders.each(&:eager_load)
       end
 
+      # Broadcasts `eager_load_namespace` to all loaders.
+      #
+      # @sig (Module) -> void
+      def eager_load_namespace(mod)
+        Registry.loaders.each do |loader|
+          loader.eager_load_namespace(mod)
+        end
+      end
+
       # Returns an array with the absolute paths of the root directories of all
       # registered loaders. This is a read-only collection.
       #
@@ -338,19 +319,11 @@ module Zeitwerk
             cname = inflector.camelize(basename, abspath).to_sym
             autoload_file(parent, cname, abspath)
           else
-            # In a Rails application, `app/models/concerns` is a subdirectory of
-            # `app/models`, but both of them are root directories.
-            #
-            # To resolve the ambiguity file name -> constant path this introduces,
-            # the `app/models/concerns` directory is totally ignored as a namespace,
-            # it counts only as root. The guard checks that.
-            unless root_dir?(abspath)
+            if collapse?(abspath)
+              set_autoloads_in_dir(abspath, parent)
+            else
               cname = inflector.camelize(basename, abspath).to_sym
-              if collapse?(abspath)
-                set_autoloads_in_dir(abspath, parent)
-              else
-                autoload_subdir(parent, cname, abspath)
-              end
+              autoload_subdir(parent, cname, abspath)
             end
           end
         rescue ::NameError => error
@@ -380,10 +353,10 @@ module Zeitwerk
         # We do not need to issue another autoload, the existing one is enough
         # no matter if it is for a file or a directory. Just remember the
         # subdirectory has to be visited if the namespace is used.
-        lazy_subdirs[cpath] << subdir
+        namespace_dirs[cpath] << subdir
       elsif !cdef?(parent, cname)
         # First time we find this namespace, set an autoload for it.
-        lazy_subdirs[cpath(parent, cname)] << subdir
+        namespace_dirs[cpath(parent, cname)] << subdir
         set_autoload(parent, cname, subdir)
       else
         # For whatever reason the constant that corresponds to this namespace has
@@ -398,6 +371,7 @@ module Zeitwerk
       if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
+          shadowed_files << file
           log("file #{file} is ignored because #{autoload_path} has precedence") if logger
         else
           promote_namespace_from_implicit_to_explicit(
@@ -408,6 +382,7 @@ module Zeitwerk
           )
         end
       elsif cdef?(parent, cname)
+        shadowed_files << file
         log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
       else
         set_autoload(parent, cname, file)
@@ -470,15 +445,15 @@ module Zeitwerk
           next if loader == self
           next if loader.ignores?(dir)
 
-          dir = dir + "/"
+          suffixed_dir = dir + "/"
           loader.root_dirs.each do |root_dir, _namespace|
             next if ignores?(root_dir)
 
             root_dir = root_dir + "/"
-            if dir.start_with?(root_dir) || root_dir.start_with?(dir)
+            if suffixed_dir.start_with?(root_dir) || root_dir.start_with?(suffixed_dir)
               require "pp" # Needed for pretty_inspect, even in Ruby 2.5.
               raise Error,
-                "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir.chop}," \
+                "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
                 " which is already managed by\n\n#{loader.pretty_inspect}\n"
               EOS
             end

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.6.1"
+  VERSION = "2.6.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.6.3
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-30 00:00:00.000000000 Z
+date: 2022-10-31 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -32,6 +32,7 @@ files:
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
 - lib/zeitwerk/loader/config.rb
+- lib/zeitwerk/loader/eager_load.rb
 - lib/zeitwerk/loader/helpers.rb
 - lib/zeitwerk/real_mod_name.rb
 - lib/zeitwerk/registry.rb