zeitwerk 2.4.0 → 2.5.0

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
@@ -14,24 +16,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,27 +42,36 @@ module Zeitwerk
       end
 
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
-      def unregister(loader)
+      # @sig (Zeitwerk::Loader) -> void
+      def unregister_loader(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
         # 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/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

@@ -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,15 +12,15 @@ 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
   # 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,13 +29,14 @@ module Kernel
         end
       else
         loader.on_dir_autoloaded(path)
+        true
       end
     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,20 +1,28 @@
+# frozen_string_literal: true
+
 module Zeitwerk::Loader::Callbacks
   include Zeitwerk::RealModName
 
   # 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)
+
+    # 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(*cref)} loaded from file #{file}")
-    elsif !cdef?(*cref)
-      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath(*cref)}, but didn't", cref.last)
+    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
   end
 
@@ -22,8 +30,7 @@ module Zeitwerk::Loader::Callbacks
   # 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 +46,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 +58,8 @@ module Zeitwerk::Loader::Callbacks
         autoloaded_dirs << dir
 
         on_namespace_loaded(autovivified_module)
+
+        run_on_load_callbacks(cpath, autovivified_module, dir) unless on_load_callbacks.empty?
       end
     end
   end
@@ -59,8 +69,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 +77,16 @@ module Zeitwerk::Loader::Callbacks
       end
     end
   end
+
+  private
+
+  # @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 { |c| c.call(value, abspath) }
+
+    callbacks = on_load_callbacks[:ANY]
+    callbacks&.each { |c| c.call(cpath, value, abspath) }
+  end
 end

data/lib/zeitwerk/loader/config.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+require "set"
+require "securerandom"
+
+module Zeitwerk::Loader::Config
+  # Absolute paths of the root directories. Stored in a hash to preserve
+  # order, easily handle duplicates, and also be able to have a fast lookup,
+  # needed for detecting nested paths.
+  #
+  #   "/Users/fxn/blog/app/assets"   => true,
+  #   "/Users/fxn/blog/app/channels" => true,
+  #   ...
+  #
+  # This is a private collection maintained by the loader. The public
+  # interface for it is `push_dir` and `dirs`.
+  #
+  # @private
+  # @sig Hash[String, true]
+  attr_reader :root_dirs
+
+  # @sig #camelize
+  attr_accessor :inflector
+
+  # Absolute paths of files, directories, or glob patterns to be totally
+  # ignored.
+  #
+  # @private
+  # @sig Set[String]
+  attr_reader :ignored_glob_patterns
+
+  # The actual collection of absolute file and directory names at the time the
+  # ignored glob patterns were expanded. Computed on setup, and recomputed on
+  # reload.
+  #
+  # @private
+  # @sig Set[String]
+  attr_reader :ignored_paths
+
+  # Absolute paths of directories or glob patterns to be collapsed.
+  #
+  # @private
+  # @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
+  # @sig Set[String]
+  attr_reader :collapse_dirs
+
+  # Absolute paths of files or directories not to be eager loaded.
+  #
+  # @private
+  # @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
+  # @sig Hash[String, Array[{ (Object, String) -> void }]]
+  #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
+  attr_reader :on_load_callbacks
+
+  # User-oriented callbacks to be fired before constants are removed.
+  #
+  # @private
+  # @sig Hash[String, Array[{ (Object, String) -> void }]]
+  #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
+  attr_reader :on_unload_callbacks
+
+  # @sig #call | #debug | nil
+  attr_accessor :logger
+
+  def initialize
+    @initialized_at         = Time.now
+    @root_dirs              = {}
+    @inflector              = Zeitwerk::Inflector.new
+    @ignored_glob_patterns  = Set.new
+    @ignored_paths          = Set.new
+    @collapse_glob_patterns = Set.new
+    @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
+    @tag                    = SecureRandom.hex(3)
+  end
+
+  # Pushes `path` to the list of root directories.
+  #
+  # Raises `Zeitwerk::Error` if `path` does not exist, or if another loader in
+  # the same process already manages that directory or one of its ascendants or
+  # descendants.
+  #
+  # @raise [Zeitwerk::Error]
+  # @sig (String | Pathname, Module) -> void
+  def push_dir(path, namespace: Object)
+    # Note that Class < Module.
+    unless namespace.is_a?(Module)
+      raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
+    end
+
+    abspath = File.expand_path(path)
+    if dir?(abspath)
+      raise_if_conflicting_directory(abspath)
+      root_dirs[abspath] = namespace
+    else
+      raise Zeitwerk::Error, "the root directory #{abspath} does not exist"
+    end
+  end
+
+  # Returns the loader's tag.
+  #
+  # Implemented as a method instead of via attr_reader for symmetry with the
+  # writer below.
+  #
+  # @sig () -> String
+  def tag
+    @tag
+  end
+
+  # Sets a tag for the loader, useful for logging.
+  #
+  # @param tag [#to_s]
+  # @sig (#to_s) -> void
+  def tag=(tag)
+    @tag = tag.to_s
+  end
+
+  # Absolute paths of the root directories. This is a read-only collection,
+  # please push here via `push_dir`.
+  #
+  # @sig () -> Array[String]
+  def dirs
+    root_dirs.keys.freeze
+  end
+
+  # You need to call this method before setup in order to be able to reload.
+  # There is no way to undo this, either you want to reload or you don't.
+  #
+  # @raise [Zeitwerk::Error]
+  # @sig () -> void
+  def enable_reloading
+    mutex.synchronize do
+      break if @reloading_enabled
+
+      if @setup
+        raise Zeitwerk::Error, "cannot enable reloading after setup"
+      else
+        @reloading_enabled = true
+      end
+    end
+  end
+
+  # @sig () -> bool
+  def reloading_enabled?
+    @reloading_enabled
+  end
+
+  # Let eager load ignore the given files or directories. The constants defined
+  # in those files are still autoloadable.
+  #
+  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  def do_not_eager_load(*paths)
+    mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
+  end
+
+  # Configure files, directories, or glob patterns to be totally ignored.
+  #
+  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  def ignore(*glob_patterns)
+    glob_patterns = expand_paths(glob_patterns)
+    mutex.synchronize do
+      ignored_glob_patterns.merge(glob_patterns)
+      ignored_paths.merge(expand_glob_patterns(glob_patterns))
+    end
+  end
+
+  # Configure directories or glob patterns to be collapsed.
+  #
+  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  def collapse(*glob_patterns)
+    glob_patterns = expand_paths(glob_patterns)
+    mutex.synchronize do
+      collapse_glob_patterns.merge(glob_patterns)
+      collapse_dirs.merge(expand_glob_patterns(glob_patterns))
+    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.
+  #
+  #   loader.on_load("SomeApiClient") do |klass, _abspath|
+  #     klass.endpoint = "https://api.dev"
+  #   end
+  #
+  # Can also be configured for any constant loaded:
+  #
+  #   loader.on_load do |cpath, value, abspath|
+  #     # ...
+  #   end
+  #
+  # @raise [TypeError]
+  # @sig (String) { (Object, String) -> void } -> void
+  #      (:ANY) { (String, Object, String) -> void } -> void
+  def on_load(cpath = :ANY, &block)
+    raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
+
+    mutex.synchronize do
+      (on_load_callbacks[cpath] ||= []) << block
+    end
+  end
+
+  # Configure a block to be invoked right before a certain constant is removed.
+  # Supports multiple callbacks, and if there are many, they are executed in the
+  # order in which they were defined.
+  #
+  #   loader.on_unload("Country") do |klass, _abspath|
+  #     klass.clear_cache
+  #   end
+  #
+  # Can also be configured for any removed constant:
+  #
+  #   loader.on_unload do |cpath, value, abspath|
+  #     # ...
+  #   end
+  #
+  # @raise [TypeError]
+  # @sig (String) { (Object) -> void } -> void
+  #      (:ANY) { (String, Object) -> void } -> void
+  def on_unload(cpath = :ANY, &block)
+    raise TypeError, "on_unload only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
+
+    mutex.synchronize do
+      (on_unload_callbacks[cpath] ||= []) << block
+    end
+  end
+
+  # Logs to `$stdout`, handy shortcut for debugging.
+  #
+  # @sig () -> void
+  def log!
+    @logger = ->(msg) { puts msg }
+  end
+
+  # @private
+  # @sig (String) -> bool
+  def ignores?(abspath)
+    ignored_paths.any? do |ignored_path|
+      ignored_path == abspath || (dir?(ignored_path) && abspath.start_with?(ignored_path + "/"))
+    end
+  end
+
+  private
+
+  # @sig () -> Array[String]
+  def actual_root_dirs
+    root_dirs.reject do |root_dir, _namespace|
+      !dir?(root_dir) || ignored_paths.member?(root_dir)
+    end
+  end
+
+  # @sig (String) -> bool
+  def root_dir?(dir)
+    root_dirs.key?(dir)
+  end
+
+  # @sig (String) -> bool
+  def excluded_from_eager_load?(abspath)
+    eager_load_exclusions.member?(abspath)
+  end
+
+  # @sig (String) -> bool
+  def collapse?(dir)
+    collapse_dirs.member?(dir)
+  end
+
+  # @sig (String | Pathname | Array[String | Pathname]) -> Array[String]
+  def expand_paths(paths)
+    paths.flatten.map! { |path| File.expand_path(path) }
+  end
+
+  # @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
+
+  # @sig () -> void
+  def recompute_ignored_paths
+    ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
+  end
+
+  # @sig () -> void
+  def recompute_collapse_dirs
+    collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
+  end
+end

data/lib/zeitwerk/loader/helpers.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Zeitwerk::Loader::Helpers
+  private
+
+  # --- Logging -----------------------------------------------------------------------------------
+
+  # @sig (String) -> void
+  def log(message)
+    method_name = logger.respond_to?(:debug) ? :debug : :call
+    logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
+  end
+
+  # --- Files and directories ---------------------------------------------------------------------
+
+  # @sig (String) { (String, String) -> void } -> void
+  def ls(dir)
+    Dir.each_child(dir) do |basename|
+      next if hidden?(basename)
+
+      abspath = File.join(dir, basename)
+      next if ignored_paths.member?(abspath)
+
+      # We freeze abspath because that saves allocations when passed later to
+      # File methods. See #125.
+      yield basename, abspath.freeze
+    end
+  end
+
+  # @sig (String) -> bool
+  def ruby?(path)
+    path.end_with?(".rb")
+  end
+
+  # @sig (String) -> bool
+  def dir?(path)
+    File.directory?(path)
+  end
+
+  # @sig String -> bool
+  def hidden?(basename)
+    basename.start_with?(".")
+  end
+
+  # --- Constants ---------------------------------------------------------------------------------
+
+  # The autoload? predicate takes into account the ancestor chain of the
+  # receiver, like const_defined? and other methods in the constants API do.
+  #
+  # For example, given
+  #
+  #   class A
+  #     autoload :X, "x.rb"
+  #   end
+  #
+  #   class B < A
+  #   end
+  #
+  # B.autoload?(:X) returns "x.rb".
+  #
+  # We need a way to strictly check in parent ignoring ancestors.
+  #
+  # @sig (Module, Symbol) -> String?
+  if method(:autoload?).arity == 1
+    def strict_autoload_path(parent, cname)
+      parent.autoload?(cname) if cdef?(parent, cname)
+    end
+  else
+    def strict_autoload_path(parent, cname)
+      parent.autoload?(cname, false)
+    end
+  end
+
+  # @sig (Module, Symbol) -> String
+  if Symbol.method_defined?(:name)
+    # Symbol#name was introduced in Ruby 3.0. It returns always the same
+    # frozen object, so we may save a few string allocations.
+    def cpath(parent, cname)
+      Object == parent ? cname.name : "#{real_mod_name(parent)}::#{cname.name}"
+    end
+  else
+    def cpath(parent, cname)
+      Object == parent ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
+    end
+  end
+
+  # @sig (Module, Symbol) -> bool
+  def cdef?(parent, cname)
+    parent.const_defined?(cname, false)
+  end
+
+  # @raise [NameError]
+  # @sig (Module, Symbol) -> Object
+  def cget(parent, cname)
+    parent.const_get(cname, false)
+  end
+end