zeitwerk 2.4.2 → 2.5.4

data/lib/zeitwerk/kernel.rb

@@ -3,42 +3,43 @@
 module Kernel
   module_function
 
-  # We are going to decorate Kerner#require with two goals.
+  # Zeitwerk's main idea is to define autoloads for project constants, and then
+  # intercept them when triggered in this thin `Kernel#require` wrapper.
   #
-  # First, by intercepting Kernel#require calls, we are able to autovivify
-  # modules on required directories, and also do internal housekeeping when
-  # managed files are loaded.
+  # That allows us to complete the circle, invoke callbacks, autovivify modules,
+  # define autoloads for just autoloaded namespaces, update internal state, etc.
   #
   # 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.
+  # already existing ancestor chains on Ruby < 3.0.
   alias_method :zeitwerk_original_require, :require
 
   # @sig (String) -> true | false
   def require(path)
     if loader = Zeitwerk::Registry.loader_for(path)
       if path.end_with?(".rb")
-        zeitwerk_original_require(path).tap do |required|
-          loader.on_file_autoloaded(path) if required
-        end
+        required = zeitwerk_original_require(path)
+        loader.on_file_autoloaded(path) if required
+        required
       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)
-          end
+      required = zeitwerk_original_require(path)
+      if required
+        abspath = $LOADED_FEATURES.last
+        if loader = Zeitwerk::Registry.loader_for(abspath)
+          loader.on_file_autoloaded(abspath)
         end
       end
+      required
     end
   end
 

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)
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is
@@ -54,7 +59,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 +80,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

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