zeitwerk 2.5.0.beta → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ac5e0ce2eba71a2099ead24de8762e3e737656ff4bcae57c83bb5797e922f72
-  data.tar.gz: 85e7c762a5164301ba5bcce82a31e6c49bc7c6caff2b4abff23c425f10374c69
+  metadata.gz: 1f424f7f7538a469affa93fbe0c24533d146eb8dfe7289f3c5167b36abd0e362
+  data.tar.gz: 8aa11ee61f57a965e3fbb705713f6a4dcf0e3586dc8a3e90f35801b8e8ff9e12
 SHA512:
-  metadata.gz: f258acabd660f54702eb904550a109b08bdacff2cecc92d610376376f77ccf70ed421e09c64144930d2a145ebbedb7e9c3c26ff21ad2c1b40dd0537d9947b4d4
-  data.tar.gz: 1612dc2d505fe37b748d81a9055e36a91f9f73267ac273b39a4cbea3736cdd1baa4c557e3059d8f3a9a9807d450e29f3d75c7cb18c94c37ded70768444313336
+  metadata.gz: 70022bbaa975835042e6550a3e1f8ca8e09e7e1f764d29c659adc9d6c727765fea276da4425ae43e7f4baaaaae6f167d9f4c567e63c0d322ac553603f2d6063b
+  data.tar.gz: 7144f057043a326be20b866b2a23dc3c2b5cd3274a084a73770e6b643f65e308ba2eacfbf87701092ee20d440e256d0afe37066933d396cb332d28e5108775a7

data/README.md

@@ -19,19 +19,24 @@
   - [Implicit namespaces](#implicit-namespaces)
   - [Explicit namespaces](#explicit-namespaces)
   - [Collapsing directories](#collapsing-directories)
+  - [Testing compliance](#testing-compliance)
 - [Usage](#usage)
   - [Setup](#setup)
     - [Generic](#generic)
     - [for_gem](#for_gem)
   - [Autoloading](#autoloading)
   - [Eager loading](#eager-loading)
+    - [Eager load exclusions](#eager-load-exclusions)
+    - [Global eager load](#global-eager-load)
   - [Reloading](#reloading)
   - [Inflection](#inflection)
     - [Zeitwerk::Inflector](#zeitwerkinflector)
     - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
     - [Custom inflector](#custom-inflector)
-  - [The on_load callback](#the-on_load-callback)
-  - [The on_unload callback](#the-on_unload-callback)
+  - [Callbacks](#callbacks)
+    - [The on_setup callback](#the-on_setup-callback)
+    - [The on_load callback](#the-on_load-callback)
+    - [The on_unload callback](#the-on_unload-callback)
     - [Technical details](#technical-details)
   - [Logging](#logging)
     - [Loader tag](#loader-tag)
@@ -40,15 +45,19 @@
     - [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)
   - [Edge cases](#edge-cases)
+  - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
+    - [debug.rb](#debugrb)
     - [Break](#break)
     - [Byebug](#byebug)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Testing](#testing)
 - [Motivation](#motivation)
+  - [Kernel#require is brittle](#kernelrequire-is-brittle)
+  - [Rails autoloading was brittle](#rails-autoloading-was-brittle)
 - [Thanks](#thanks)
 - [License](#license)
 
@@ -157,6 +166,16 @@ class HttpCrawler
 end
 ```
 
+The first example needs a custom [inflection](https://github.com/fxn/zeitwerk#inflection) rule:
+
+```ruby
+loader.inflector.inflect("max_retries" => "MAX_RETRIES")
+```
+
+Otherwise, Zeitwerk would expect the file to define `MaxRetries`.
+
+In the second example, no custom rule is needed.
+
 <a id="markdown-root-directories-and-root-namespaces" name="root-directories-and-root-namespaces"></a>
 ### Root directories and root namespaces
 
@@ -275,6 +294,23 @@ To illustrate usage of glob patterns, if `actions` in the example above is part
 loader.collapse("#{__dir__}/*/actions")
 ```
 
+<a id="markdown-testing-compliance" name="testing-compliance"></a>
+### Testing compliance
+
+When a managed file is loaded, Zeitwerk verifies the expected constant is defined. If it is not, `Zeitwerk::NameError` is raised.
+
+So, an easy way to ensure compliance in the test suite is to eager load the project:
+
+```ruby
+begin
+  loader.eager_load(force: true)
+rescue Zeitwerk::NameError => e
+  flunk e.message
+else
+  assert true
+end
+```
+
 <a id="markdown-usage" name="usage"></a>
 ## Usage
 
@@ -377,7 +413,16 @@ Zeitwerk instances are able to eager load their managed files:
 loader.eager_load
 ```
 
-That skips [ignored files and directories](#ignoring-parts-of-the-project), and you can also tell Zeitwerk that certain files or directories are autoloadable, but should not be eager loaded:
+That skips [ignored files and directories](#ignoring-parts-of-the-project).
+
+In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](https://github.com/fxn/zeitwerk#synopsis).
+
+Eager loading is synchronized and idempotent.
+
+<a id="markdown-eager-load-exclusions" name="eager-load-exclusions"></a>
+#### Eager load exclusions
+
+ You can tell Zeitwerk that certain files or directories are autoloadable, but should not be eager loaded:
 
 ```ruby
 db_adapters = "#{__dir__}/my_gem/db_adapters"
@@ -386,13 +431,20 @@ loader.setup
 loader.eager_load # won't eager load the database adapters
 ```
 
-In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](https://github.com/fxn/zeitwerk#synopsis).
+However, that can be overridden with `force`:
 
-Eager loading is synchronized and idempotent.
+```ruby
+loader.eager_load(force: true) # database adapters are eager loaded
+```
+
+Which may be handy if the project eager loads in the test suite to [ensure project layour compliance](#testing-compliance).
 
-If eager loading a file does not define the expected class or module, Zeitwerk raises `Zeitwerk::NameError`, which is a subclass of `NameError`.
+The `force` flag does not affect ignored files and directories, those are still ignored.
 
-If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
+<a id="markdown-global-eager-load" name="global-eager-load"></a>
+#### Global eager load
+
+If you want to eager load yourself and all dependencies that use Zeitwerk, you can broadcast the `eager_load` call to all instances:
 
 ```ruby
 Zeitwerk::Loader.eager_load_all
@@ -402,6 +454,8 @@ This may be handy in top-level services, like web applications.
 
 Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager load twice if any of the instances already eager loaded.
 
+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-reloading" name="reloading"></a>
 ### Reloading
 
@@ -433,11 +487,13 @@ On reloading, client code has to update anything that would otherwise be storing
 <a id="markdown-inflection" name="inflection"></a>
 ### Inflection
 
-Each individual loader needs an inflector to figure out which constant path would a given file or directory map to. Zeitwerk ships with two basic inflectors.
+Each individual loader needs an inflector to figure out which constant path would a given file or directory map to. Zeitwerk ships with two basic inflectors, and you can define your own.
 
 <a id="markdown-zeitwerkinflector" name="zeitwerkinflector"></a>
 #### Zeitwerk::Inflector
 
+Each loader instantiated with `Zeitwerk::Loader.new` has an inflector of this type by default.
+
 This is a very basic inflector that converts snake case to camel case:
 
 ```
@@ -464,16 +520,16 @@ loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
 
 Overrides need to be configured before calling `setup`.
 
-There are no inflection rules or global configuration that can affect this inflector. It is deterministic.
-
-Loaders instantiated with `Zeitwerk::Loader.new` have an inflector of this type, independent of each other.
+ The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
 
 <a id="markdown-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
 #### Zeitwerk::GemInflector
 
+Each loader instantiated with `Zeitwerk::Loader.for_gem` has an inflector of this type by default.
+
 This inflector is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
 
-Loaders instantiated with `Zeitwerk::Loader.for_gem` have an inflector of this type, independent of each other.
+The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
 
 <a id="markdown-custom-inflector" name="custom-inflector"></a>
 #### Custom inflector
@@ -549,8 +605,26 @@ class MyGem::Inflector < Zeitwerk::GemInflector
 end
 ```
 
+<a id="markdown-callbacks" name="callbacks"></a>
+### Callbacks
+
+<a id="markdown-the-on_setup-callback" name="the-on_setup-callback"></a>
+#### The on_setup callback
+
+The `on_setup` callback is fired on setup and on each reload:
+
+```ruby
+loader.on_setup do
+  # Ready to autoload here.
+end
+```
+
+Multiple `on_setup` callbacks are supported, and they run in order of definition.
+
+If `setup` was already executed, the callback is fired immediately.
+
 <a id="markdown-the-on_load-callback" name="the-on_load-callback"></a>
-### The on_load callback
+#### The on_load callback
 
 The usual place to run something when a file is loaded is the file itself. However, sometimes you'd like to be called, and this is possible with the `on_load` callback.
 
@@ -580,7 +654,7 @@ end
 
 Some uses cases:
 
-* Doing something with an autoloadable class or module in a Rails application during initialization, in a way that plays well with reloading. As in the previous example.
+* Doing something with a reloadable class or module in a Rails application during initialization, in a way that plays well with reloading. As in the previous example.
 * Delaying the execution of the block until the class is loaded for performance.
 * Delaying the execution of the block until the class is loaded because it follows the adapter pattern and better not to load the class if the user does not need it.
 
@@ -608,8 +682,10 @@ There are use cases for this last catch-all callback, but they are rare. If you
 
 If both types of callbacks are defined, the specific ones run first.
 
+Since `on_load` callbacks are executed right after files are loaded, even if the loading context seems to be far away, in practice **the block is subject to [circular dependencies](#beware-of-circular-dependencies)**. As a rule of thumb, as far as loading order and its interdependencies is concerned, you have to program as if the block was executed at the bottom of the file just loaded.
+
 <a id="markdown-the-on_unload-callback" name="the-on_unload-callback"></a>
-### The on_unload callback
+#### The on_unload callback
 
 When reloading is enabled, you may occasionally need to execute something before a certain autoloaded class or module is unloaded. The `on_unload` callback allows you to do that.
 
@@ -820,6 +896,26 @@ Trip = Struct.new { ... } # NOT SUPPORTED
 
 This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
 
+<a id="markdown-beware-of-circular-dependencies" name="beware-of-circular-dependencies"></a>
+### Beware of circular dependencies
+
+In Ruby, you can't have certain top-level circular dependencies. Take for example:
+
+```ruby
+# c.rb
+class C < D
+end
+
+# d.rb
+class D
+  C
+end
+```
+
+In order to define `C`, you need to load `D`. However, the body of `D` refers to `C`.
+
+Circular dependencies like those do not work in plain Ruby, and therefore do not work in projects managed by Zeitwerk either.
+
 <a id="markdown-reopening-third-party-namespaces" name="reopening-third-party-namespaces"></a>
 ### Reopening third-party namespaces
 
@@ -874,6 +970,11 @@ With that, when Zeitwerk scans the file system and reaches the gem directories `
 <a id="markdown-debuggers" name="debuggers"></a>
 ### Debuggers
 
+<a id="markdown-debugrb" name="debugrb"></a>
+#### debug.rb
+
+The new [debug.rb](https://github.com/ruby/debug) gem and Zeitwerk seem to be compatible, as far as I can tell. This is the new debugger that is going to ship with Ruby 3.1.
+
 <a id="markdown-break" name="break"></a>
 #### Break
 
@@ -892,7 +993,11 @@ Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) are incompatib
 <a id="markdown-supported-ruby-versions" name="supported-ruby-versions"></a>
 ## Supported Ruby versions
 
-Zeitwerk works with MRI 2.4.4 and above.
+Zeitwerk works with CRuby 2.5 and above.
+
+On TruffleRuby all is good except for thread-safety. Right now, in TruffleRuby `Module#autoload` does not block threads accessing a constant that is being autoloaded. CRuby prevents such access to avoid concurrent threads from seeing partial evaluations of the corresponding file. Zeitwerk inherits autoloading thread-safety from this property. This is not an issue if your project gets eager loaded, or if you lazy load in single-threaded environments. (See https://github.com/oracle/truffleruby/issues/2431.)
+
+JRuby 9.3.0.0 is almost there. As of this writing, the test suite of Zeitwerk passes on JRuby except for three tests. (See https://github.com/jruby/jruby/issues/6781.)
 
 <a id="markdown-testing" name="testing"></a>
 ## Testing
@@ -923,9 +1028,19 @@ and run `bin/test`.
 <a id="markdown-motivation" name="motivation"></a>
 ## Motivation
 
-Since `require` has global side-effects, and there is no static way to verify that you have issued the `require` calls for code that your file depends on, in practice it is very easy to forget some. That introduces bugs that depend on the load order. Zeitwerk provides a way to forget about `require` in your own code, just name things following conventions and done.
+<a id="markdown-kernelrequire-is-brittle" name="kernelrequire-is-brittle"></a>
+### Kernel#require is brittle
+
+Since `require` has global side-effects, and there is no static way to verify that you have issued the `require` calls for code that your file depends on, in practice it is very easy to forget some. That introduces bugs that depend on the load order.
+
+Also, if the project has namespaces, setting things up and getting client code to load things in a consistent way needs discipline. For example, `require "foo/bar"` may define `Foo`, instead of reopen it. That may be a broken window, giving place to superclass mismatches or partially-defined namespaces.
+
+With Zeitwerk, you just name things following conventions and done. Things are available everywhere, and descend is always orderly. Without effort and without broken windows.
+
+<a id="markdown-rails-autoloading-was-brittle" name="rails-autoloading-was-brittle"></a>
+### Rails autoloading was brittle
 
-On the other hand, autoloading in Rails is based on `const_missing`, which lacks fundamental information like the nesting and the resolution algorithm that was being used. Because of that, Rails autoloading is not able to match Ruby's semantics and that introduces a series of gotchas. The original goal of this project was to bring a better autoloading mechanism for Rails 6.
+Autoloading in Rails was based on `const_missing` up to Rails 5. That callback lacks fundamental information like the nesting or the resolution algorithm being used. Because of that, Rails autoloading was not able to match Ruby's semantics, and that introduced a [series of issues](https://guides.rubyonrails.org/v5.2/autoloading_and_reloading_constants.html#common-gotchas). Zeitwerk is based on a different technique and fixed Rails autoloading starting with Rails 6.
 
 <a id="markdown-thanks" name="thanks"></a>
 ## Thanks

data/lib/zeitwerk/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zeitwerk
   class Error < StandardError
   end

data/lib/zeitwerk/explicit_namespace.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zeitwerk
   # Centralizes the logic for the trace point used to detect the creation of
   # explicit namespaces, needed to descend into matching subdirectories right
@@ -41,7 +43,7 @@ module Zeitwerk
 
       # @private
       # @sig (Zeitwerk::Loader) -> void
-      def unregister(loader)
+      def unregister_loader(loader)
         cpaths.delete_if { |_cpath, l| l == loader }
         disable_tracer_if_unneeded
       end

data/lib/zeitwerk/kernel.rb

@@ -3,7 +3,7 @@
 module Kernel
   module_function
 
-  # We are going to decorate Kerner#require with two goals.
+  # We are going to decorate Kernel#require with two goals.
   #
   # First, by intercepting Kernel#require calls, we are able to autovivify
   # modules on required directories, and also do internal housekeeping when

data/lib/zeitwerk/loader/callbacks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zeitwerk::Loader::Callbacks
   include Zeitwerk::RealModName
 
@@ -9,16 +11,19 @@ module Zeitwerk::Loader::Callbacks
     cref  = autoloads.delete(file)
     cpath = cpath(*cref)
 
+    # If reloading is enabled, we need to put this constant for unloading
+    # regardless of what cdef? says. In Ruby < 3.1 the internal state is not
+    # fully cleared. Module#constants still includes it, and you need to
+    # remove_const. See https://github.com/ruby/ruby/pull/4715.
     to_unload[cpath] = [file, cref] if reloading_enabled?
     Zeitwerk::Registry.unregister_autoload(file)
 
-    if logger && cdef?(*cref)
-      log("constant #{cpath} loaded from file #{file}")
-    elsif !cdef?(*cref)
+    if cdef?(*cref)
+      log("constant #{cpath} loaded from file #{file}") if logger
+      run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
+    else
       raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
     end
-
-    run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is

data/lib/zeitwerk/loader/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "set"
 require "securerandom"
 
@@ -54,6 +56,12 @@ module Zeitwerk::Loader::Config
   # @sig Set[String]
   attr_reader :eager_load_exclusions
 
+  # User-oriented callbacks to be fired on setup and on reload.
+  #
+  # @private
+  # @sig Array[{ () -> void }]
+  attr_reader :on_setup_callbacks
+
   # User-oriented callbacks to be fired when a constant is loaded.
   #
   # @private
@@ -81,6 +89,7 @@ module Zeitwerk::Loader::Config
     @collapse_dirs          = Set.new
     @eager_load_exclusions  = Set.new
     @reloading_enabled      = false
+    @on_setup_callbacks     = []
     @on_load_callbacks      = {}
     @on_unload_callbacks    = {}
     @logger                 = self.class.default_logger
@@ -188,6 +197,17 @@ module Zeitwerk::Loader::Config
     end
   end
 
+  # Configure a block to be called after setup and on each reload.
+  # If setup was already done, the block runs immediately.
+  #
+  # @sig () { () -> void } -> void
+  def on_setup(&block)
+    mutex.synchronize do
+      on_setup_callbacks << block
+      block.call if @setup
+    end
+  end
+
   # Configure a block to be invoked once a certain constant path is loaded.
   # Supports multiple callbacks, and if there are many, they are executed in
   # the order in which they were defined.
@@ -247,17 +267,10 @@ module Zeitwerk::Loader::Config
 
   # @private
   # @sig (String) -> bool
-  def manages?(dir)
-    dir = dir + "/"
-    ignored_paths.each do |ignored_path|
-      return false if dir.start_with?(ignored_path + "/")
+  def ignores?(abspath)
+    ignored_paths.any? do |ignored_path|
+      ignored_path == abspath || (dir?(ignored_path) && abspath.start_with?(ignored_path + "/"))
     end
-
-    root_dirs.each_key do |root_dir|
-      return true if root_dir.start_with?(dir) || dir.start_with?(root_dir + "/")
-    end
-
-    false
   end
 
   private

data/lib/zeitwerk/loader/helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zeitwerk::Loader::Helpers
   private
 

data/lib/zeitwerk/loader.rb

@@ -14,22 +14,16 @@ module Zeitwerk
     include Helpers
     include Config
 
-    # Keeps track of autoloads defined by the loader which have not been
-    # executed so far.
+    # Maps absolute paths for which an autoload has been set ---and not
+    # executed--- to their corresponding parent class or module and constant
+    # name.
     #
-    # This metadata helps us implement a few things:
-    #
-    # 1. When autoloads are triggered, ensure they define the expected constant
-    #    and invoke user callbacks. If reloading is enabled, remember cref and
-    #    abspath for later unloading logic.
-    #
-    # 2. When unloading, remove autoloads that have not been executed.
-    #
-    # 3. Eager load with a recursive const_get, rather than a recursive require,
-    #    for consistency with lazy loading.
+    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
+    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
+    #   ...
     #
     # @private
-    # @sig Zeitwerk::Autoloads
+    # @sig Hash[String, [Module, Symbol]]
     attr_reader :autoloads
 
     # We keep track of autoloaded directories to remove them from the registry
@@ -87,7 +81,7 @@ module Zeitwerk
     def initialize
       super
 
-      @autoloads       = Autoloads.new
+      @autoloads       = {}
       @autoloaded_dirs = []
       @to_unload       = {}
       @lazy_subdirs    = Hash.new { |h, cpath| h[cpath] = [] }
@@ -110,6 +104,8 @@ module Zeitwerk
           set_autoloads_in_dir(root_dir, namespace)
         end
 
+        on_setup_callbacks.each(&:call)
+
         @setup = true
       end
     end
@@ -121,7 +117,10 @@ module Zeitwerk
     # else, they are eligible for garbage collection, which would effectively
     # unload them.
     #
-    # @private
+    # This method is public but undocumented. Main interface is `reload`, which
+    # means `unload` + `setup`. This one is avaiable to be used together with
+    # `unregister`, which is undocumented too.
+    #
     # @sig () -> void
     def unload
       mutex.synchronize do
@@ -133,14 +132,14 @@ module Zeitwerk
         # is enough.
         unloaded_files = Set.new
 
-        autoloads.each do |(parent, cname), abspath|
+        autoloads.each do |abspath, (parent, cname)|
           if parent.autoload?(cname)
             unload_autoload(parent, cname)
           else
             # Could happen if loaded with require_relative. That is unsupported,
             # 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(parent, cname)  if cdef?(parent, cname)
+            unload_cref(parent, cname)
             unloaded_files.add(abspath) if ruby?(abspath)
           end
         end
@@ -151,7 +150,7 @@ module Zeitwerk
             run_on_unload_callbacks(cpath, value, abspath)
           end
 
-          unload_cref(parent, cname)  if cdef?(parent, cname)
+          unload_cref(parent, cname)
           unloaded_files.add(abspath) if ruby?(abspath)
         end
 
@@ -176,7 +175,7 @@ module Zeitwerk
         lazy_subdirs.clear
 
         Registry.on_unload(self)
-        ExplicitNamespace.unregister(self)
+        ExplicitNamespace.unregister_loader(self)
 
         @setup        = false
         @eager_loaded = false
@@ -205,28 +204,31 @@ module Zeitwerk
     # 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`.
+    # directories with `do_not_eager_load`, and that can be overridden passing
+    # `force: true`.
     #
-    # @sig () -> void
-    def eager_load
+    # @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 excluded_from_eager_load?(root_dir)
+          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 excluded_from_eager_load?(abspath)
+            next if honour_exclusions && excluded_from_eager_load?(abspath)
 
             if ruby?(abspath)
-              if cref = autoloads.cref_for(abspath)
+              if cref = autoloads[abspath]
                 cget(*cref)
               end
             elsif dir?(abspath) && !root_dirs.key?(abspath)
@@ -267,6 +269,15 @@ module Zeitwerk
       to_unload.keys.freeze
     end
 
+    # This is a dangerous method.
+    #
+    # @experimental
+    # @sig () -> void
+    def unregister
+      Registry.unregister_loader(self)
+      ExplicitNamespace.unregister_loader(self)
+    end
+
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
@@ -359,7 +370,7 @@ module Zeitwerk
 
     # @sig (Module, Symbol, String) -> void
     def autoload_subdir(parent, cname, subdir)
-      if autoload_path = autoloads.abspath_for(parent, cname)
+      if autoload_path = autoload_path_set_by_me_for?(parent, cname)
         cpath = cpath(parent, cname)
         register_explicit_namespace(cpath) if ruby?(autoload_path)
         # We do not need to issue another autoload, the existing one is enough
@@ -415,7 +426,7 @@ module Zeitwerk
 
     # @sig (Module, Symbol, String) -> void
     def set_autoload(parent, cname, abspath)
-      autoloads.define(parent, cname, abspath)
+      parent.autoload(cname, abspath)
 
       if logger
         if ruby?(abspath)
@@ -425,6 +436,7 @@ module Zeitwerk
         end
       end
 
+      autoloads[abspath] = [parent, cname]
       Registry.register_autoload(self, abspath)
 
       # See why in the documentation of Zeitwerk::Registry.inceptions.
@@ -433,6 +445,15 @@ module Zeitwerk
       end
     end
 
+    # @sig (Module, Symbol) -> String?
+    def autoload_path_set_by_me_for?(parent, cname)
+      if autoload_path = strict_autoload_path(parent, cname)
+        autoload_path if autoloads.key?(autoload_path)
+      else
+        Registry.inception?(cpath(parent, cname))
+      end
+    end
+
     # @sig (String) -> void
     def register_explicit_namespace(cpath)
       ExplicitNamespace.register(cpath, self)
@@ -442,12 +463,21 @@ module Zeitwerk
     def raise_if_conflicting_directory(dir)
       self.class.mutex.synchronize do
         Registry.loaders.each do |loader|
-          if loader != self && loader.manages?(dir)
-            require "pp"
-            raise Error,
-              "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
-              " which is already managed by\n\n#{loader.pretty_inspect}\n"
-            EOS
+          next if loader == self
+          next if loader.ignores?(dir)
+
+          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)
+              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}," \
+                " which is already managed by\n\n#{loader.pretty_inspect}\n"
+              EOS
+            end
           end
         end
       end
@@ -468,7 +498,13 @@ module Zeitwerk
 
     # @sig (Module, Symbol) -> void
     def unload_cref(parent, cname)
+      # Let's optimistically remove_const. The way we use it, this is going to
+      # succeed always if all is good.
       parent.__send__(:remove_const, cname)
+    rescue ::NameError
+      # There are a few edge scenarios in which this may happen. If the constant
+      # is gone, that is OK, anyway.
+    else
       log("#{cpath(parent, cname)} unloaded") if logger
     end
   end

data/lib/zeitwerk/real_mod_name.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zeitwerk::RealModName
   UNBOUND_METHOD_MODULE_NAME = Module.instance_method(:name)
   private_constant :UNBOUND_METHOD_MODULE_NAME

data/lib/zeitwerk/registry.rb

@@ -73,6 +73,15 @@ module Zeitwerk
         loaders << loader
       end
 
+      # @private
+      # @sig (Zeitwerk::Loader) -> void
+      def unregister_loader(loader)
+        loaders.delete(loader)
+        loaders_managing_gems.delete_if { |_, l| l == loader }
+        autoloads.delete_if { |_, l| l == loader }
+        inceptions.delete_if { |_, (_, l)| l == loader }
+      end
+
       # This method returns always a loader, the same instance for the same root
       # file. That is how Zeitwerk::Loader.for_gem is idempotent.
       #

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.5.0.beta"
+  VERSION = "2.5.1"
 end

data/lib/zeitwerk.rb

@@ -3,7 +3,6 @@
 module Zeitwerk
   require_relative "zeitwerk/real_mod_name"
   require_relative "zeitwerk/loader"
-  require_relative "zeitwerk/autoloads"
   require_relative "zeitwerk/registry"
   require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"
@@ -11,4 +10,15 @@ module Zeitwerk
   require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
   require_relative "zeitwerk/version"
+
+  # This is a dangerous method.
+  #
+  # @experimental
+  # @sig () -> void
+  def self.with_loader
+    loader = Zeitwerk::Loader.new
+    yield loader
+  ensure
+    loader.unregister
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.5.0.beta
+  version: 2.5.1
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-03 00:00:00.000000000 Z
+date: 2021-10-20 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -23,7 +23,6 @@ files:
 - MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
-- lib/zeitwerk/autoloads.rb
 - lib/zeitwerk/error.rb
 - lib/zeitwerk/explicit_namespace.rb
 - lib/zeitwerk/gem_inflector.rb
@@ -55,11 +54,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader

data/lib/zeitwerk/autoloads.rb

@@ -1,69 +0,0 @@
-module Zeitwerk
-  # @private
-  class Autoloads
-    # Maps crefs for which an autoload has been defined to the corresponding
-    # absolute path.
-    #
-    #   [Object, :User]  => "/Users/fxn/blog/app/models/user.rb"
-    #   [Object, :Hotel] => "/Users/fxn/blog/app/models/hotel"
-    #   ...
-    #
-    # This colection is transient, callbacks delete its entries as autoloads get
-    # executed.
-    #
-    # @sig Hash[[Module, Symbol], String]
-    attr_reader :c2a
-
-    # This is the inverse of c2a, for inverse lookups.
-    #
-    # @sig Hash[String, [Module, Symbol]]
-    attr_reader :a2c
-
-    # @sig () -> void
-    def initialize
-      @c2a = {}
-      @a2c = {}
-    end
-
-    # @sig (Module, Symbol, String) -> void
-    def define(parent, cname, abspath)
-      parent.autoload(cname, abspath)
-      cref = [parent, cname]
-      c2a[cref] = abspath
-      a2c[abspath] = cref
-    end
-
-    # @sig () { () -> [[Module, Symbol], String] } -> void
-    def each(&block)
-      c2a.each(&block)
-    end
-
-    # @sig (Module, Symbol) -> String?
-    def abspath_for(parent, cname)
-      c2a[[parent, cname]]
-    end
-
-    # @sig (String) -> [Module, Symbol]?
-    def cref_for(abspath)
-      a2c[abspath]
-    end
-
-    # @sig (String) -> [Module, Symbol]?
-    def delete(abspath)
-      cref = a2c.delete(abspath)
-      c2a.delete(cref)
-      cref
-    end
-
-    # @sig () -> void
-    def clear
-      c2a.clear
-      a2c.clear
-    end
-
-    # @sig () -> bool
-    def empty?
-      c2a.empty? && a2c.empty?
-    end
-  end
-end