zeitwerk 2.4.0 → 2.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 682fa352a9d6d4bf68d07cf2cbfbb539de3cfec4e8af2f930894ab27c707ca93
-  data.tar.gz: 1e7ce6157e6046cdb60f0f1b531f1f39fb97cad3537392114be5cf84dae672c9
+  metadata.gz: f45a7c3caf48f06e10dd513a7b074da7ec059fa3299751d361514aadc83d995e
+  data.tar.gz: c8c29793e95245b47b1283891791d2c20365b8c694b3dcdfb7daab0b74c16bdb
 SHA512:
-  metadata.gz: e308baba1a8fbe4d7c64d7195c753d795a53caefa7264d2404117cb620f2081f6b0fc05c056dafb035b44430102e4472b7eb9fb3a4fd9d70aa124b7f9a3a8313
-  data.tar.gz: 5139d5abaeed86e256493b592460b13b19fd7602f7c099f7017b55af9f16a91429e84074a4e31fe79bf28235e02cbba3055cc4bda579bbc7de2a391c5997a393
+  metadata.gz: 6194d326b268c9333ed9d2ac1c62b65756fa9af844c5fb7ad8272ecec33aa439015506758bcd329e421508facb4153e04e45da0efb0a2a42001a6f2e0a0d3b6a
+  data.tar.gz: 656009f40e777f641ff1dc80f54b63559514439538c73965aa9226b6c3e33c6be71c07eb30adfe7f4cd4b3be72aa6e42918392ba27167fb9502b9aed037f36d3

data/README.md

@@ -25,6 +25,7 @@
         - [Zeitwerk::Inflector](#zeitwerkinflector)
         - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
         - [Custom inflector](#custom-inflector)
+    - [The on_load callback](#the-on_load-callback)
     - [Logging](#logging)
         - [Loader tag](#loader-tag)
     - [Ignoring parts of the project](#ignoring-parts-of-the-project)
@@ -151,7 +152,7 @@ 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 `lib/active_job/queue_adapters`.
+your adapter can be stored directly in that directory instead of the canonical `#{__dir__}/active_job/queue_adapters`.
 
 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.
 
@@ -202,7 +203,7 @@ booking/actions/create.rb -> Booking::Create
 To make it work that way, configure Zeitwerk to collapse said directory:
 
 ```ruby
-loader.collapse("booking/actions")
+loader.collapse("#{__dir__}/booking/actions")
 ```
 
 This method accepts an arbitrary number of strings or `Pathname` objects, and also an array of them.
@@ -212,7 +213,7 @@ You can pass directories and glob patterns. Glob patterns are expanded when they
 To illustrate usage of glob patterns, if `actions` in the example above is part of a standardized structure, you could use a wildcard:
 
 ```ruby
-loader.collapse("*/actions")
+loader.collapse("#{__dir__}/*/actions")
 ```
 
 <a id="markdown-nested-root-directories" name="nested-root-directories"></a>
@@ -502,6 +503,52 @@ class MyGem::Inflector < Zeitwerk::GemInflector
 end
 ```
 
+<a id="markdown-the-on_load-callback" name="the-on_load-callback"></a>
+### 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.
+
+For example, let's imagine this class belongs to a Rails application:
+
+```ruby
+class SomeApiClient
+  class << self
+    attr_accessor :endpoint
+  end
+end
+```
+
+With `on_load`, it is easy to schedule code at boot time that initializes `endpoint` according to the configuration:
+
+```ruby
+# config/environments/development.rb
+loader.on_load("SomeApiClient") do
+  SomeApiClient.endpoint = "https://api.dev"
+end
+
+# config/environments/production.rb
+loader.on_load("SomeApiClient") do
+  SomeApiClient.endpoint = "https://api.prod"
+end
+```
+
+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.
+* 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.
+
+Multiple callbacks on the same target are supported, and they run in order of definition.
+
+The block is executed once the loader has loaded the target. In particular, if the target was already loaded when the callback is defined, the block won't run. But if you reload and load the target again, then it will. Normally, you'll want to define `on_load` callbacks before `setup`.
+
+Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 

data/lib/zeitwerk/explicit_namespace.rb

@@ -14,24 +14,22 @@ module Zeitwerk
       # the file system, to the loader responsible for them.
       #
       # @private
-      # @return [{String => Zeitwerk::Loader}]
+      # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :cpaths
 
       # @private
-      # @return [Mutex]
+      # @sig Mutex
       attr_reader :mutex
 
       # @private
-      # @return [TracePoint]
+      # @sig TracePoint
       attr_reader :tracer
 
       # Asserts `cpath` corresponds to an explicit namespace for which `loader`
       # is responsible.
       #
       # @private
-      # @param cpath [String]
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
+      # @sig (String, Zeitwerk::Loader) -> void
       def register(cpath, loader)
         mutex.synchronize do
           cpaths[cpath] = loader
@@ -42,19 +40,22 @@ module Zeitwerk
       end
 
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
+      # @sig (Zeitwerk::Loader) -> void
       def unregister(loader)
         cpaths.delete_if { |_cpath, l| l == loader }
         disable_tracer_if_unneeded
       end
 
+      private
+
+      # @sig () -> void
       def disable_tracer_if_unneeded
         mutex.synchronize do
           tracer.disable if cpaths.empty?
         end
       end
 
+      # @sig (TracePoint) -> void
       def tracepoint_class_callback(event)
         # If the class is a singleton class, we won't do anything with it so we
         # can bail out immediately. This is several orders of magnitude faster

data/lib/zeitwerk/gem_inflector.rb

@@ -2,16 +2,14 @@
 
 module Zeitwerk
   class GemInflector < Inflector
-    # @param root_file [String]
+    # @sig (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
       lib_dir       = File.dirname(root_file)
       @version_file = File.join(lib_dir, namespace, "version.rb")
     end
 
-    # @param basename [String]
-    # @param abspath [String]
-    # @return [String]
+    # @sig (String, String) -> String
     def camelize(basename, abspath)
       abspath == @version_file ? "VERSION" : super
     end

data/lib/zeitwerk/inflector.rb

@@ -11,9 +11,7 @@ module Zeitwerk
     #
     # Takes into account hard-coded mappings configured with `inflect`.
     #
-    # @param basename [String]
-    # @param _abspath [String]
-    # @return [String]
+    # @sig (String, String) -> String
     def camelize(basename, _abspath)
       overrides[basename] || basename.split('_').each(&:capitalize!).join
     end
@@ -30,8 +28,7 @@ module Zeitwerk
     #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
     #   inflector.camelize("users_controller", abspath) # => "UsersController"
     #
-    # @param inflections [{String => String}]
-    # @return [void]
+    # @sig (Hash[String, String]) -> void
     def inflect(inflections)
       overrides.merge!(inflections)
     end
@@ -41,7 +38,7 @@ module Zeitwerk
     # Hard-coded basename to constant name user maps that override the default
     # inflection logic.
     #
-    # @return [{String => String}]
+    # @sig () -> Hash[String, String]
     def overrides
       @overrides ||= {}
     end

data/lib/zeitwerk/kernel.rb

@@ -19,8 +19,7 @@ module Kernel
   # already existing ancestor chains.
   alias_method :zeitwerk_original_require, :require
 
-  # @param path [String]
-  # @return [Boolean]
+  # @sig (String) -> true | false
   def require(path)
     if loader = Zeitwerk::Registry.loader_for(path)
       if path.end_with?(".rb")
@@ -29,6 +28,7 @@ module Kernel
         end
       else
         loader.on_dir_autoloaded(path)
+        true
       end
     else
       zeitwerk_original_require(path).tap do |required|

data/lib/zeitwerk/loader.rb

@@ -9,13 +9,13 @@ module Zeitwerk
     include Callbacks
     include RealModName
 
-    # @return [String]
+    # @sig String
     attr_reader :tag
 
-    # @return [#camelize]
+    # @sig #camelize
     attr_accessor :inflector
 
-    # @return [#call, #debug, nil]
+    # @sig #call | #debug | nil
     attr_accessor :logger
 
     # Absolute paths of the root directories. Stored in a hash to preserve
@@ -30,20 +30,20 @@ module Zeitwerk
     # interface for it is `push_dir` and `dirs`.
     #
     # @private
-    # @return [{String => true}]
+    # @sig Hash[String, true]
     attr_reader :root_dirs
 
     # Absolute paths of files or directories that have to be preloaded.
     #
     # @private
-    # @return [<String>]
+    # @sig Array[String]
     attr_reader :preloads
 
     # Absolute paths of files, directories, or glob patterns to be totally
     # ignored.
     #
     # @private
-    # @return [Set<String>]
+    # @sig Set[String]
     attr_reader :ignored_glob_patterns
 
     # The actual collection of absolute file and directory names at the time the
@@ -51,20 +51,20 @@ module Zeitwerk
     # reload.
     #
     # @private
-    # @return [Set<String>]
+    # @sig Set[String]
     attr_reader :ignored_paths
 
     # Absolute paths of directories or glob patterns to be collapsed.
     #
     # @private
-    # @return [Set<String>]
+    # @sig Set[String]
     attr_reader :collapse_glob_patterns
 
     # The actual collection of absolute directory names at the time the collapse
     # glob patterns were expanded. Computed on setup, and recomputed on reload.
     #
     # @private
-    # @return [Set<String>]
+    # @sig Set[String]
     attr_reader :collapse_dirs
 
     # Maps real absolute paths for which an autoload has been set ---and not
@@ -76,7 +76,7 @@ module Zeitwerk
     #   ...
     #
     # @private
-    # @return [{String => (Module, Symbol)}]
+    # @sig Hash[String, [Module, Symbol]]
     attr_reader :autoloads
 
     # We keep track of autoloaded directories to remove them from the registry
@@ -86,7 +86,7 @@ module Zeitwerk
     # to concurrency (see why in Zeitwerk::Loader::Callbacks#on_dir_autoloaded).
     #
     # @private
-    # @return [<String>]
+    # @sig Array[String]
     attr_reader :autoloaded_dirs
 
     # Stores metadata needed for unloading. Its entries look like this:
@@ -102,7 +102,7 @@ module Zeitwerk
     # or eager loaded. Otherwise, the collection remains empty.
     #
     # @private
-    # @return [{String => (String, (Module, Symbol))}]
+    # @sig Hash[String, [String, [Module, Symbol]]]
     attr_reader :to_unload
 
     # Maps constant paths of namespaces to arrays of corresponding directories.
@@ -120,21 +120,24 @@ module Zeitwerk
     # up the corresponding autoloads.
     #
     # @private
-    # @return [{String => <String>}]
+    # @sig Hash[String, Array[String]]
     attr_reader :lazy_subdirs
 
     # Absolute paths of files or directories not to be eager loaded.
     #
     # @private
-    # @return [Set<String>]
+    # @sig Set[String]
     attr_reader :eager_load_exclusions
 
+    # User-oriented callbacks to be fired when a constant is loaded.
+    attr_reader :on_load_callbacks
+
     # @private
-    # @return [Mutex]
+    # @sig Mutex
     attr_reader :mutex
 
     # @private
-    # @return [Mutex]
+    # @sig Mutex
     attr_reader :mutex2
 
     def initialize
@@ -155,6 +158,7 @@ module Zeitwerk
       @to_unload              = {}
       @lazy_subdirs           = {}
       @eager_load_exclusions  = Set.new
+      @on_load_callbacks      = {}
 
       # TODO: find a better name for these mutexes.
       @mutex        = Mutex.new
@@ -170,7 +174,7 @@ module Zeitwerk
     # Sets a tag for the loader, useful for logging.
     #
     # @param tag [#to_s]
-    # @return [void]
+    # @sig (#to_s) -> void
     def tag=(tag)
       @tag = tag.to_s
     end
@@ -178,7 +182,7 @@ module Zeitwerk
     # Absolute paths of the root directories. This is a read-only collection,
     # please push here via `push_dir`.
     #
-    # @return [<String>]
+    # @sig () -> Array[String]
     def dirs
       root_dirs.keys.freeze
     end
@@ -189,10 +193,8 @@ module Zeitwerk
     # the same process already manages that directory or one of its ascendants
     # or descendants.
     #
-    # @param path [<String, Pathname>]
-    # @param namespace [Class, Module]
     # @raise [Zeitwerk::Error]
-    # @return [void]
+    # @sig (String | Pathname, Module) -> void
     def push_dir(path, namespace: Object)
       # Note that Class < Module.
       unless namespace.is_a?(Module)
@@ -212,7 +214,7 @@ module Zeitwerk
     # There is no way to undo this, either you want to reload or you don't.
     #
     # @raise [Zeitwerk::Error]
-    # @return [void]
+    # @sig () -> void
     def enable_reloading
       mutex.synchronize do
         break if @reloading_enabled
@@ -225,15 +227,14 @@ module Zeitwerk
       end
     end
 
-    # @return [Boolean]
+    # @sig () -> bool
     def reloading_enabled?
       @reloading_enabled
     end
 
     # Files or directories to be preloaded instead of lazy loaded.
     #
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [void]
+    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
     def preload(*paths)
       mutex.synchronize do
         expand_paths(paths).each do |abspath|
@@ -245,8 +246,7 @@ module Zeitwerk
 
     # Configure files, directories, or glob patterns to be totally ignored.
     #
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [void]
+    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
     def ignore(*glob_patterns)
       glob_patterns = expand_paths(glob_patterns)
       mutex.synchronize do
@@ -257,8 +257,7 @@ module Zeitwerk
 
     # Configure directories or glob patterns to be collapsed.
     #
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [void]
+    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
     def collapse(*glob_patterns)
       glob_patterns = expand_paths(glob_patterns)
       mutex.synchronize do
@@ -267,9 +266,27 @@ module Zeitwerk
       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.
+    #
+    #   loader.on_load("SomeApiClient") do
+    #     SomeApiClient.endpoint = "https://api.dev"
+    #   end
+    #
+    # @raise [TypeError]
+    # @sig (String) { () -> void } -> void
+    def on_load(cpath, &block)
+      raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String)
+
+      mutex.synchronize do
+        (on_load_callbacks[cpath] ||= []) << block
+      end
+    end
+
     # Sets autoloads in the root namespace and preloads files, if any.
     #
-    # @return [void]
+    # @sig () -> void
     def setup
       mutex.synchronize do
         break if @setup
@@ -291,7 +308,7 @@ module Zeitwerk
     # unload them.
     #
     # @private
-    # @return [void]
+    # @sig () -> void
     def unload
       mutex.synchronize do
         # We are going to keep track of the files that were required by our
@@ -354,7 +371,7 @@ module Zeitwerk
     # client code in the README of the project.
     #
     # @raise [Zeitwerk::Error]
-    # @return [void]
+    # @sig () -> void
     def reload
       if reloading_enabled?
         unload
@@ -371,7 +388,7 @@ module Zeitwerk
     # are not eager loaded. You can opt-out specifically in specific files and
     # directories with `do_not_eager_load`.
     #
-    # @return [void]
+    # @sig () -> void
     def eager_load
       mutex.synchronize do
         break if @eager_loaded
@@ -414,8 +431,7 @@ module Zeitwerk
     # Let eager load ignore the given files or directories. The constants
     # defined in those files are still autoloadable.
     #
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [void]
+    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
     def do_not_eager_load(*paths)
       mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
     end
@@ -423,8 +439,7 @@ module Zeitwerk
     # Says if the given constant path would be unloaded on reload. This
     # predicate returns `false` if reloading is disabled.
     #
-    # @param cpath [String]
-    # @return [Boolean]
+    # @sig (String) -> bool
     def unloadable_cpath?(cpath)
       to_unload.key?(cpath)
     end
@@ -432,21 +447,20 @@ module Zeitwerk
     # Returns an array with the constant paths that would be unloaded on reload.
     # This predicate returns an empty array if reloading is disabled.
     #
-    # @return [<String>]
+    # @sig () -> Array[String]
     def unloadable_cpaths
       to_unload.keys.freeze
     end
 
     # Logs to `$stdout`, handy shortcut for debugging.
     #
-    # @return [void]
+    # @sig () -> void
     def log!
       @logger = ->(msg) { puts msg }
     end
 
     # @private
-    # @param dir [String]
-    # @return [Boolean]
+    # @sig (String) -> bool
     def manages?(dir)
       dir = dir + "/"
       ignored_paths.each do |ignored_path|
@@ -463,11 +477,11 @@ module Zeitwerk
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
-      # @return [#call, #debug, nil]
+      # @sig #call | #debug | nil
       attr_accessor :default_logger
 
       # @private
-      # @return [Mutex]
+      # @sig Mutex
       attr_accessor :mutex
 
       # This is a shortcut for
@@ -481,7 +495,7 @@ module Zeitwerk
       # except that this method returns the same object in subsequent calls from
       # the same file, in the unlikely case the gem wants to be able to reload.
       #
-      # @return [Zeitwerk::Loader]
+      # @sig () -> Zeitwerk::Loader
       def for_gem
         called_from = caller_locations(1, 1).first.path
         Registry.loader_for_gem(called_from)
@@ -489,7 +503,7 @@ module Zeitwerk
 
       # Broadcasts `eager_load` to all loaders.
       #
-      # @return [void]
+      # @sig () -> void
       def eager_load_all
         Registry.loaders.each(&:eager_load)
       end
@@ -497,7 +511,7 @@ module Zeitwerk
       # Returns an array with the absolute paths of the root directories of all
       # registered loaders. This is a read-only collection.
       #
-      # @return [<String>]
+      # @sig () -> Array[String]
       def all_dirs
         Registry.loaders.flat_map(&:dirs).freeze
       end
@@ -507,16 +521,14 @@ module Zeitwerk
 
     private # -------------------------------------------------------------------------------------
 
-    # @return [<String>]
+    # @sig () -> Array[String]
     def actual_root_dirs
       root_dirs.reject do |root_dir, _namespace|
         !dir?(root_dir) || ignored_paths.member?(root_dir)
       end
     end
 
-    # @param dir [String]
-    # @param parent [Module]
-    # @return [void]
+    # @sig (String, Module) -> void
     def set_autoloads_in_dir(dir, parent)
       ls(dir) do |basename, abspath|
         begin
@@ -559,10 +571,7 @@ module Zeitwerk
       end
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @param subdir [String]
-    # @return [void]
+    # @sig (Module, Symbol, String) -> void
     def autoload_subdir(parent, cname, subdir)
       if autoload_path = autoload_for?(parent, cname)
         cpath = cpath(parent, cname)
@@ -582,10 +591,7 @@ module Zeitwerk
       end
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @param file [String]
-    # @return [void]
+    # @sig (Module, Symbol, String) -> void
     def autoload_file(parent, cname, file)
       if autoload_path = autoload_for?(parent, cname)
         # First autoload for a Ruby file wins, just ignore subsequent ones.
@@ -606,11 +612,10 @@ module Zeitwerk
       end
     end
 
-    # @param dir [String] directory that would have autovivified a module
-    # @param file [String] the file where the namespace is explicitly defined
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [void]
+    # `dir` is the directory that would have autovivified a namespace. `file` is
+    # the file where we've found the namespace is explicitly defined.
+    #
+    # @sig (dir: String, file: String, parent: Module, cname: Symbol) -> void
     def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
       autoloads.delete(dir)
       Registry.unregister_autoload(dir)
@@ -619,10 +624,7 @@ module Zeitwerk
       register_explicit_namespace(cpath(parent, cname))
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @param abspath [String]
-    # @return [void]
+    # @sig (Module, Symbol, String) -> void
     def set_autoload(parent, cname, abspath)
       # $LOADED_FEATURES stores real paths since Ruby 2.4.4. We set and save the
       # real path to be able to delete it from $LOADED_FEATURES on unload, and to
@@ -649,9 +651,7 @@ module Zeitwerk
       end
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [String, nil]
+    # @sig (Module, Symbol) -> String?
     def autoload_for?(parent, cname)
       strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
     end
@@ -672,9 +672,7 @@ module Zeitwerk
     #
     # We need a way to strictly check in parent ignoring ancestors.
     #
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [String, nil]
+    # @sig (Module, Symbol) -> String?
     if method(:autoload?).arity == 1
       def strict_autoload_path(parent, cname)
         parent.autoload?(cname) if cdef?(parent, cname)
@@ -688,15 +686,14 @@ module Zeitwerk
     # This method is called this way because I prefer `preload` to be the method
     # name to configure preloads in the public interface.
     #
-    # @return [void]
+    # @sig () -> void
     def do_preload
       preloads.each do |abspath|
         do_preload_abspath(abspath)
       end
     end
 
-    # @param abspath [String]
-    # @return [void]
+    # @sig (String) -> void
     def do_preload_abspath(abspath)
       if ruby?(abspath)
         do_preload_file(abspath)
@@ -705,31 +702,25 @@ module Zeitwerk
       end
     end
 
-    # @param dir [String]
-    # @return [void]
+    # @sig (String) -> void
     def do_preload_dir(dir)
       ls(dir) do |_basename, abspath|
         do_preload_abspath(abspath)
       end
     end
 
-    # @param file [String]
-    # @return [Boolean]
+    # @sig (String) -> bool
     def do_preload_file(file)
       log("preloading #{file}") if logger
       require file
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [String]
+    # @sig (Module, Symbol) -> String
     def cpath(parent, cname)
       parent.equal?(Object) ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
     end
 
-    # @param dir [String]
-    # @yieldparam path [String, String]
-    # @return [void]
+    # @sig (String) { (String, String) -> void } -> void
     def ls(dir)
       Dir.foreach(dir) do |basename|
         next if basename.start_with?(".")
@@ -743,57 +734,55 @@ module Zeitwerk
       end
     end
 
-    # @param path [String]
-    # @return [Boolean]
+    # @sig (String) -> bool
     def ruby?(path)
       path.end_with?(".rb")
     end
 
-    # @param path [String]
-    # @return [Boolean]
+    # @sig (String) -> bool
     def dir?(path)
       File.directory?(path)
     end
 
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [<String>]
+    # @sig (String | Pathname | Array[String | Pathname]) -> Array[String]
     def expand_paths(paths)
       paths.flatten.map! { |path| File.expand_path(path) }
     end
 
-    # @param glob_patterns [<String>]
-    # @return [<String>]
+    # @sig (Array[String]) -> Array[String]
     def expand_glob_patterns(glob_patterns)
       # Note that Dir.glob works with regular file names just fine. That is,
       # glob patterns technically need no wildcards.
       glob_patterns.flat_map { |glob_pattern| Dir.glob(glob_pattern) }
     end
 
-    # @return [void]
+    # @sig () -> void
     def recompute_ignored_paths
       ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
     end
 
-    # @return [void]
+    # @sig () -> void
     def recompute_collapse_dirs
       collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
     end
 
-    # @param message [String]
-    # @return [void]
+    # @sig (String) -> void
     def log(message)
       method_name = logger.respond_to?(:debug) ? :debug : :call
       logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
     end
 
+    # @sig (Module, Symbol) -> bool
     def cdef?(parent, cname)
       parent.const_defined?(cname, false)
     end
 
+    # @sig (String) -> void
     def register_explicit_namespace(cpath)
       ExplicitNamespace.register(cpath, self)
     end
 
+    # @sig (String) -> void
     def raise_if_conflicting_directory(dir)
       self.class.mutex.synchronize do
         Registry.loaders.each do |loader|
@@ -808,19 +797,15 @@ module Zeitwerk
       end
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [void]
+    # @sig (Module, Symbol) -> void
     def unload_autoload(parent, cname)
-      parent.send(:remove_const, cname)
+      parent.__send__(:remove_const, cname)
       log("autoload for #{cpath(parent, cname)} removed") if logger
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [void]
+    # @sig (Module, Symbol) -> void
     def unload_cref(parent, cname)
-      parent.send(:remove_const, cname)
+      parent.__send__(:remove_const, cname)
       log("#{cpath(parent, cname)} unloaded") if logger
     end
   end

data/lib/zeitwerk/loader/callbacks.rb

@@ -4,26 +4,28 @@ module Zeitwerk::Loader::Callbacks
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
   # @private
-  # @param file [String]
-  # @return [void]
+  # @sig (String) -> void
   def on_file_autoloaded(file)
-    cref = autoloads.delete(file)
-    to_unload[cpath(*cref)] = [file, cref] if reloading_enabled?
+    cref  = autoloads.delete(file)
+    cpath = cpath(*cref)
+
+    to_unload[cpath] = [file, cref] if reloading_enabled?
     Zeitwerk::Registry.unregister_autoload(file)
 
     if logger && cdef?(*cref)
-      log("constant #{cpath(*cref)} loaded from file #{file}")
+      log("constant #{cpath} loaded from file #{file}")
     elsif !cdef?(*cref)
-      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath(*cref)}, but didn't", cref.last)
+      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
     end
+
+    run_on_load_callbacks(cpath)
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
   # @private
-  # @param dir [String]
-  # @return [void]
+  # @sig (String) -> void
   def on_dir_autoloaded(dir)
     # Module#autoload does not serialize concurrent requires, and we handle
     # directories ourselves, so the callback needs to account for concurrency.
@@ -39,9 +41,10 @@ module Zeitwerk::Loader::Callbacks
     mutex2.synchronize do
       if cref = autoloads.delete(dir)
         autovivified_module = cref[0].const_set(cref[1], Module.new)
-        log("module #{autovivified_module.name} autovivified from directory #{dir}") if logger
+        cpath = autovivified_module.name
+        log("module #{cpath} autovivified from directory #{dir}") if logger
 
-        to_unload[autovivified_module.name] = [dir, cref] if reloading_enabled?
+        to_unload[cpath] = [dir, cref] if reloading_enabled?
 
         # We don't unregister `dir` in the registry because concurrent threads
         # wouldn't find a loader associated to it in Kernel#require and would
@@ -50,6 +53,8 @@ module Zeitwerk::Loader::Callbacks
         autoloaded_dirs << dir
 
         on_namespace_loaded(autovivified_module)
+
+        run_on_load_callbacks(cpath)
       end
     end
   end
@@ -59,8 +64,7 @@ module Zeitwerk::Loader::Callbacks
   # subdirectories, we descend into them now.
   #
   # @private
-  # @param namespace [Module]
-  # @return [void]
+  # @sig (Module) -> void
   def on_namespace_loaded(namespace)
     if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
       subdirs.each do |subdir|
@@ -68,4 +72,15 @@ module Zeitwerk::Loader::Callbacks
       end
     end
   end
+
+  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?
+
+    callbacks = reloading_enabled? ? on_load_callbacks[cpath] : on_load_callbacks.delete(cpath)
+    callbacks.each(&:call) if callbacks
+  end
 end

data/lib/zeitwerk/real_mod_name.rb

@@ -7,8 +7,7 @@ module Zeitwerk::RealModName
   #
   # The name method can be overridden, hence the indirection in this method.
   #
-  # @param mod [Class, Module]
-  # @return [String, nil]
+  # @sig (Module) -> String?
   if UnboundMethod.method_defined?(:bind_call)
     def real_mod_name(mod)
       UNBOUND_METHOD_MODULE_NAME.bind_call(mod)

data/lib/zeitwerk/registry.rb

@@ -7,14 +7,14 @@ module Zeitwerk
       # them from being garbage collected.
       #
       # @private
-      # @return [<Zeitwerk::Loader>]
+      # @sig Array[Zeitwerk::Loader]
       attr_reader :loaders
 
       # Registers loaders created with `for_gem` to make the method idempotent
       # in case of reload.
       #
       # @private
-      # @return [{String => Zeitwerk::Loader}]
+      # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :loaders_managing_gems
 
       # Maps real paths to the loaders responsible for them.
@@ -23,7 +23,7 @@ module Zeitwerk
       # invoke callbacks and autovivify modules.
       #
       # @private
-      # @return [{String => Zeitwerk::Loader}]
+      # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :autoloads
 
       # This hash table addresses an edge case in which an autoload is ignored.
@@ -62,14 +62,13 @@ module Zeitwerk
       #   end
       #
       # @private
-      # @return [{String => (String, Zeitwerk::Loader)}]
+      # @sig Hash[String, [String, Zeitwerk::Loader]]
       attr_reader :inceptions
 
       # Registers a loader.
       #
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
+      # @sig (Zeitwerk::Loader) -> void
       def register_loader(loader)
         loaders << loader
       end
@@ -78,8 +77,7 @@ module Zeitwerk
       # file. That is how Zeitwerk::Loader.for_gem is idempotent.
       #
       # @private
-      # @param root_file [String]
-      # @return [Zeitwerk::Loader]
+      # @sig (String) -> Zeitwerk::Loader
       def loader_for_gem(root_file)
         loaders_managing_gems[root_file] ||= begin
           Loader.new.tap do |loader|
@@ -91,32 +89,25 @@ module Zeitwerk
       end
 
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @param realpath [String]
-      # @return [void]
+      # @sig (Zeitwerk::Loader, String) -> String
       def register_autoload(loader, realpath)
         autoloads[realpath] = loader
       end
 
       # @private
-      # @param realpath [String]
-      # @return [void]
+      # @sig (String) -> void
       def unregister_autoload(realpath)
         autoloads.delete(realpath)
       end
 
       # @private
-      # @param cpath [String]
-      # @param realpath [String]
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
+      # @sig (String, String, Zeitwerk::Loader) -> void
       def register_inception(cpath, realpath, loader)
         inceptions[cpath] = [realpath, loader]
       end
 
       # @private
-      # @param cpath [String]
-      # @return [String, nil]
+      # @sig (String) -> String?
       def inception?(cpath)
         if pair = inceptions[cpath]
           pair.first
@@ -124,15 +115,13 @@ module Zeitwerk
       end
 
       # @private
-      # @param path [String]
-      # @return [Zeitwerk::Loader, nil]
+      # @sig (String) -> Zeitwerk::Loader?
       def loader_for(path)
         autoloads[path]
       end
 
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
+      # @sig (Zeitwerk::Loader) -> void
       def on_unload(loader)
         autoloads.delete_if { |_path, object| object == loader }
         inceptions.delete_if { |_cpath, (_path, object)| object == loader }

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.4.2
 platform: ruby
 authors:
 - Xavier Noria
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-14 00:00:00.000000000 Z
+date: 2020-11-27 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -41,7 +41,7 @@ metadata:
   changelog_uri: https://github.com/fxn/zeitwerk/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/fxn/zeitwerk
   bug_tracker_uri: https://github.com/fxn/zeitwerk/issues
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -57,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader
 test_files: []