zeitwerk 2.4.2 → 2.5.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f45a7c3caf48f06e10dd513a7b074da7ec059fa3299751d361514aadc83d995e
-  data.tar.gz: c8c29793e95245b47b1283891791d2c20365b8c694b3dcdfb7daab0b74c16bdb
+  metadata.gz: 4012f73de9387546f477e8254668d450c00310666bde922b90a6b2be8d4b9740
+  data.tar.gz: 7c403df9ea53494c2eb1a01b3fb81f70ce1a6488a420728f134c7c32ab4cb444
 SHA512:
-  metadata.gz: 6194d326b268c9333ed9d2ac1c62b65756fa9af844c5fb7ad8272ecec33aa439015506758bcd329e421508facb4153e04e45da0efb0a2a42001a6f2e0a0d3b6a
-  data.tar.gz: 656009f40e777f641ff1dc80f54b63559514439538c73965aa9226b6c3e33c6be71c07eb30adfe7f4cd4b3be72aa6e42918392ba27167fb9502b9aed037f36d3
+  metadata.gz: f2222619050df7f4271a73b2abdc258d541249ed34a75738afb1661ba17460dc2a0c53690f33a85e33b5925e28a6e2d292fa9d12711722261ae517d6d38f7520
+  data.tar.gz: 77679e246700480f751e0bce8373d5fe648a78f41a2b8bd97cc0d9c0bdff52651bd64be59ad56809b2785539fd7439f3b9ad554d9ddb8f668fbca9b187d51a24

data/README.md

@@ -3,45 +3,56 @@
 
 
 [![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
-[![Build Status](https://img.shields.io/travis/com/fxn/zeitwerk/master?style=for-the-badge)](https://travis-ci.com/fxn/zeitwerk)
+[![Build Status](https://img.shields.io/github/workflow/status/fxn/zeitwerk/CI?event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions?query=event%3Apush)
 
 <!-- TOC -->
 
 - [Introduction](#introduction)
 - [Synopsis](#synopsis)
 - [File structure](#file-structure)
-    - [Implicit namespaces](#implicit-namespaces)
-    - [Explicit namespaces](#explicit-namespaces)
-    - [Collapsing directories](#collapsing-directories)
+  - [The idea: File paths match constant paths](#the-idea-file-paths-match-constant-paths)
+  - [Inner simple constants](#inner-simple-constants)
+  - [Root directories and root namespaces](#root-directories-and-root-namespaces)
+    - [The default root namespace is `Object`](#the-default-root-namespace-is-object)
+    - [Custom root namespaces](#custom-root-namespaces)
     - [Nested root directories](#nested-root-directories)
+  - [Implicit namespaces](#implicit-namespaces)
+  - [Explicit namespaces](#explicit-namespaces)
+  - [Collapsing directories](#collapsing-directories)
 - [Usage](#usage)
-    - [Setup](#setup)
-        - [Generic](#generic)
-        - [for_gem](#for_gem)
-    - [Autoloading](#autoloading)
-    - [Eager loading](#eager-loading)
-    - [Reloading](#reloading)
-    - [Inflection](#inflection)
-        - [Zeitwerk::Inflector](#zeitwerkinflector)
-        - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
-        - [Custom inflector](#custom-inflector)
+  - [Setup](#setup)
+    - [Generic](#generic)
+    - [for_gem](#for_gem)
+  - [Autoloading](#autoloading)
+  - [Eager loading](#eager-loading)
+  - [Reloading](#reloading)
+  - [Inflection](#inflection)
+    - [Zeitwerk::Inflector](#zeitwerkinflector)
+    - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
+    - [Custom inflector](#custom-inflector)
+  - [Callbacks](#callbacks)
+    - [The on_setup callback](#the-on_setup-callback)
     - [The on_load callback](#the-on_load-callback)
-    - [Logging](#logging)
-        - [Loader tag](#loader-tag)
-    - [Ignoring parts of the project](#ignoring-parts-of-the-project)
-        - [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)
-    - [Edge cases](#edge-cases)
-    - [Reopening third-party namespaces](#reopening-third-party-namespaces)
-    - [Rules of thumb](#rules-of-thumb)
-    - [Debuggers](#debuggers)
-        - [Break](#break)
-        - [Byebug](#byebug)
+    - [The on_unload callback](#the-on_unload-callback)
+    - [Technical details](#technical-details)
+  - [Logging](#logging)
+    - [Loader tag](#loader-tag)
+  - [Ignoring parts of the project](#ignoring-parts-of-the-project)
+    - [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)
+  - [Edge cases](#edge-cases)
+  - [Reopening third-party namespaces](#reopening-third-party-namespaces)
+  - [Rules of thumb](#rules-of-thumb)
+  - [Debuggers](#debuggers)
+    - [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)
 
@@ -117,6 +128,9 @@ Zeitwerk::Loader.eager_load_all
 <a id="markdown-file-structure" name="file-structure"></a>
 ## File structure
 
+<a id="markdown-the-idea-file-paths-match-constant-paths" name="the-idea-file-paths-match-constant-paths"></a>
+### The idea: File paths match constant paths
+
 To have a file structure Zeitwerk can work with, just name files and directories after the name of the classes and modules they define:
 
 ```
@@ -126,25 +140,67 @@ lib/my_gem/bar_baz.rb -> MyGem::BarBaz
 lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo
 ```
 
-Every directory configured with `push_dir` acts as root namespace. There can be several of them. For example, given
+You can tune that a bit by [collapsing directories](#collapsing-directories), or by [ignoring parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
+
+<a id="markdown-inner-simple-constants" name="inner-simple-constants"></a>
+### Inner simple constants
+
+While a simple constant like `HttpCrawler::MAX_RETRIES` can be defined in its own file:
 
 ```ruby
-loader.push_dir(Rails.root.join("app/models"))
-loader.push_dir(Rails.root.join("app/controllers"))
+# http_crawler/max_retries.rb
+HttpCrawler::MAX_RETRIES = 10
 ```
 
-Zeitwerk understands that their respective files and subdirectories belong to the root namespace:
+that is not required, you can also define it the regular way:
 
+```ruby
+# http_crawler.rb
+class HttpCrawler
+  MAX_RETRIES = 10
+end
 ```
-app/models/user.rb                        -> User
-app/controllers/admin/users_controller.rb -> Admin::UsersController
+
+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
+
+Every directory configured with `push_dir` is called a _root directory_, and they represent _root namespaces_.
+
+<a id="markdown-the-default-root-namespace-is-object" name="the-default-root-namespace-is-object"></a>
+#### The default root namespace is `Object`
+
+By default, the namespace associated to a root directory is the top-level one: `Object`.
+
+For example, given
+
+```ruby
+loader.push_dir("#{__dir__}/models")
+loader.push_dir("#{__dir__}/serializers"))
 ```
 
-Alternatively, you can associate a custom namespace to a root directory by passing a class or module object in the optional `namespace` keyword argument.
+these are the expected classes and modules being defined by these files:
 
-For example, Active Job queue adapters have to define a constant after their name in `ActiveJob::QueueAdapters`.
+```
+models/user.rb                 -> User
+serializers/user_serializer.rb -> UserSerializer
+```
+
+<a id="markdown-custom-root-namespaces" name="custom-root-namespaces"></a>
+#### Custom root namespaces
+
+While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a class or module object in the optional `namespace` keyword argument.
 
-So, if you declare
+For example, given:
 
 ```ruby
 require "active_job"
@@ -152,9 +208,26 @@ require "active_job/queue_adapters"
 loader.push_dir("#{__dir__}/adapters", namespace: ActiveJob::QueueAdapters)
 ```
 
-your adapter can be stored directly in that directory instead of the canonical `#{__dir__}/active_job/queue_adapters`.
+a file defining `ActiveJob::QueueAdapters::MyQueueAdapter` does not need the conventional parent directories, you can (and have to) store the file directly below `adapters`:
+
+```
+adapters/my_queue_adapter.rb -> ActiveJob::QueueAdapters::MyQueueAdapter
+```
+
+Please, note that the given root namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::Deliveries`, that one can be reloaded.
+
+<a id="markdown-nested-root-directories" name="nested-root-directories"></a>
+#### Nested root directories
 
-Please, note that the given namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::V2::Deliveries`, that one can be reloaded.
+Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
+
+Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
+
+```
+app/models/concerns/geolocatable.rb
+```
+
+should define `Geolocatable`, not `Concerns::Geolocatable`.
 
 <a id="markdown-implicit-namespaces" name="implicit-namespaces"></a>
 ### Implicit namespaces
@@ -216,19 +289,6 @@ To illustrate usage of glob patterns, if `actions` in the example above is part
 loader.collapse("#{__dir__}/*/actions")
 ```
 
-<a id="markdown-nested-root-directories" name="nested-root-directories"></a>
-### Nested root directories
-
-Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
-
-Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
-
-```
-app/models/concerns/geolocatable.rb
-```
-
-should define `Geolocatable`, not `Concerns::Geolocatable`.
-
 <a id="markdown-usage" name="usage"></a>
 ## Usage
 
@@ -387,11 +447,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:
 
 ```
@@ -418,16 +480,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
@@ -503,8 +565,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.
 
@@ -522,26 +602,23 @@ With `on_load`, it is easy to schedule code at boot time that initializes `endpo
 
 ```ruby
 # config/environments/development.rb
-loader.on_load("SomeApiClient") do
-  SomeApiClient.endpoint = "https://api.dev"
+loader.on_load("SomeApiClient") do |klass, _abspath|
+  klass.endpoint = "https://api.dev"
 end
 
 # config/environments/production.rb
-loader.on_load("SomeApiClient") do
-  SomeApiClient.endpoint = "https://api.prod"
+loader.on_load("SomeApiClient") do |klass, _abspath|
+  klass.endpoint = "https://api.prod"
 end
 ```
 
-Uses cases:
+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.
-* Etc.
 
-However, let me stress that the easiest way to accomplish that is to write whatever you have to do in the actual target file. `on_load` use cases are edgy, use it only if appropriate.
-
-`on_load` receives the name of the target class or module as a string. The given block is executed every time its corresponding file is loaded. That includes reloads.
+`on_load` gets a target constant path as a string (e.g., "User", or "Service::NotificationsGateway"). When fired, its block receives the stored value, and the absolute path to the corresponding file or directory as a string. The callback is executed every time the target is loaded. That includes reloads.
 
 Multiple callbacks on the same target are supported, and they run in order of definition.
 
@@ -549,6 +626,66 @@ The block is executed once the loader has loaded the target. In particular, if t
 
 Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
 
+It is also possible to be called when any constant managed by the loader is loaded:
+
+```ruby
+loader.on_load do |cpath, value, abspath|
+  # ...
+end
+```
+
+The block gets the constant path as a string (e.g., "User", or "Foo::VERSION"), the value it stores (e.g., the class object stored in `User`, or "2.5.0"), and the absolute path to the corresponding file or directory as a string.
+
+Multiple callbacks like these are supported, and they run in order of definition.
+
+There are use cases for this last catch-all callback, but they are rare. If you just need to understand how things are being loaded for debugging purposes, please remember that `Zeitwerk::Loader#log!` logs plenty of information.
+
+If both types of callbacks are defined, the specific ones run first.
+
+<a id="markdown-the-on_unload-callback" name="the-on_unload-callback"></a>
+#### 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.
+
+For example, let's imagine that a `Country` class fetches a list of countries and caches them when it is loaded. You might want to clear that cache if unloaded:
+
+```ruby
+loader.on_unload("Country") do |klass, _abspath|
+  klass.clear_cache
+end
+```
+
+`on_unload` gets a target constant path as a string (e.g., "User", or "Service::NotificationsGateway"). When fired, its block receives the stored value, and the absolute path to the corresponding file or directory as a string. The callback is executed every time the target is unloaded.
+
+`on_unload` blocks are executed before the class is unloaded, but in the middle of unloading, which happens in an unspecified order. Therefore, **that callback should not refer to any reloadable constant because there is no guarantee the constant works there**. Those blocks should rely on objects only, as in the example above, or regular constants not managed by the loader. This remark is transitive, applies to any methods invoked within the block.
+
+Multiple callbacks on the same target are supported, and they run in order of definition.
+
+Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
+
+It is also possible to be called when any constant managed by the loader is unloaded:
+
+```ruby
+loader.on_unload do |cpath, value, abspath|
+  # ...
+end
+```
+
+The block gets the constant path as a string (e.g., "User", or "Foo::VERSION"), the value it stores (e.g., the class object stored in `User`, or "2.5.0"), and the absolute path to the corresponding file or directory as a string.
+
+Multiple callbacks like these are supported, and they run in order of definition.
+
+If both types of callbacks are defined, the specific ones run first.
+
+<a id="markdown-technical-details" name="technical-details"></a>
+#### Technical details
+
+Zeitwerk uses the word "unload" to ease communication and for symmetry with `on_load`. However, in Ruby you cannot unload things for real. So, when does `on_unload` technically happen?
+
+When unloading, Zeitwerk issues `Module#remove_const` calls. Classes and modules are no longer reachable through their constants, and `on_unload` callbacks are executed right before those calls.
+
+Technically, though, the objects themselves are still alive, but if everything is used as expected and they are not stored in any non-reloadable place (don't do that), they are ready for garbage collection, which is when the real unloading happens.
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 
@@ -820,9 +957,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/autoloads.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+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

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
@@ -62,8 +64,14 @@ module Zeitwerk
         # than accessing its name.
         return if event.self.singleton_class?
 
-        # Note that it makes sense to compute the hash code unconditionally,
-        # because the trace point is disabled if cpaths is empty.
+        # It might be tempting to return if name.nil?, to avoid the computation
+        # of a hash code and delete call. But Ruby does not trigger the :class
+        # event on Class.new or Module.new, so that would incur in an extra call
+        # for nothing.
+        #
+        # On the other hand, if we were called, cpaths is not empty. Otherwise
+        # the tracer is disabled. So we do need to go ahead with the hash code
+        # computation and delete call.
         if loader = cpaths.delete(real_mod_name(event.self))
           loader.on_namespace_loaded(event.self)
           disable_tracer_if_unneeded

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
@@ -12,7 +12,8 @@ module Kernel
   # On the other hand, if you publish a new version of a gem that is now managed
   # by Zeitwerk, client code can reference directly your classes and modules and
   # should not require anything. But if someone has legacy require calls around,
-  # they will work as expected, and in a compatible way.
+  # they will work as expected, and in a compatible way. This feature is by now
+  # EXPERIMENTAL and UNDOCUMENTED.
   #
   # We cannot decorate with prepend + super because Kernel has already been
   # included in Object, and changes in ancestors don't get propagated into
@@ -33,9 +34,9 @@ module Kernel
     else
       zeitwerk_original_require(path).tap do |required|
         if required
-          realpath = $LOADED_FEATURES.last
-          if loader = Zeitwerk::Registry.loader_for(realpath)
-            loader.on_file_autoloaded(realpath)
+          abspath = $LOADED_FEATURES.last
+          if loader = Zeitwerk::Registry.loader_for(abspath)
+            loader.on_file_autoloaded(abspath)
           end
         end
       end

data/lib/zeitwerk/loader/callbacks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zeitwerk::Loader::Callbacks
   include Zeitwerk::RealModName
 
@@ -18,7 +20,7 @@ module Zeitwerk::Loader::Callbacks
       raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
     end
 
-    run_on_load_callbacks(cpath)
+    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
@@ -54,7 +56,7 @@ module Zeitwerk::Loader::Callbacks
 
         on_namespace_loaded(autovivified_module)
 
-        run_on_load_callbacks(cpath)
+        run_on_load_callbacks(cpath, autovivified_module, dir) unless on_load_callbacks.empty?
       end
     end
   end
@@ -75,12 +77,13 @@ module Zeitwerk::Loader::Callbacks
 
   private
 
-  # @sig (String) -> void
-  def run_on_load_callbacks(cpath)
-    # Very common, do not even compute a hash code.
-    return if on_load_callbacks.empty?
-
+  # @sig (String, Object) -> void
+  def run_on_load_callbacks(cpath, value, abspath)
+    # Order matters. If present, run the most specific one.
     callbacks = reloading_enabled? ? on_load_callbacks[cpath] : on_load_callbacks.delete(cpath)
-    callbacks.each(&:call) if callbacks
+    callbacks&.each { |c| c.call(value, abspath) }
+
+    callbacks = on_load_callbacks[:ANY]
+    callbacks&.each { |c| c.call(cpath, value, abspath) }
   end
 end