zeitwerk 2.4.2 → 2.5.0.beta4

data/lib/zeitwerk/loader.rb

@@ -5,78 +5,31 @@ require "securerandom"
 
 module Zeitwerk
   class Loader
+    require_relative "loader/helpers"
     require_relative "loader/callbacks"
-    include Callbacks
-    include RealModName
-
-    # @sig String
-    attr_reader :tag
+    require_relative "loader/config"
 
-    # @sig #camelize
-    attr_accessor :inflector
-
-    # @sig #call | #debug | nil
-    attr_accessor :logger
+    include RealModName
+    include Callbacks
+    include Helpers
+    include 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.
+    # Keeps track of autoloads defined by the loader which have not been
+    # executed so far.
     #
-    #   "/Users/fxn/blog/app/assets"   => true,
-    #   "/Users/fxn/blog/app/channels" => true,
-    #   ...
+    # This metadata helps us implement a few things:
     #
-    # This is a private collection maintained by the loader. The public
-    # interface for it is `push_dir` and `dirs`.
+    # 1. When autoloads are triggered, ensure they define the expected constant
+    #    and invoke user callbacks. If reloading is enabled, remember cref and
+    #    abspath for later unloading logic.
     #
-    # @private
-    # @sig Hash[String, true]
-    attr_reader :root_dirs
-
-    # Absolute paths of files or directories that have to be preloaded.
+    # 2. When unloading, remove autoloads that have not been executed.
     #
-    # @private
-    # @sig Array[String]
-    attr_reader :preloads
-
-    # Absolute paths of files, directories, or glob patterns to be totally
-    # ignored.
+    # 3. Eager load with a recursive const_get, rather than a recursive require,
+    #    for consistency with lazy loading.
     #
     # @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
-
-    # Maps real absolute paths for which an autoload has been set ---and not
-    # executed--- to their corresponding parent class or module and constant
-    # name.
-    #
-    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
-    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
-    #   ...
-    #
-    # @private
-    # @sig Hash[String, [Module, Symbol]]
+    # @sig Zeitwerk::Autoloads
     attr_reader :autoloads
 
     # We keep track of autoloaded directories to remove them from the registry
@@ -93,8 +46,8 @@ module Zeitwerk
     #
     #   "Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
     #
-    # The cpath as key helps implementing unloadable_cpath? The real file name
-    # is stored in order to be able to delete it from $LOADED_FEATURES, and the
+    # The cpath as key helps implementing unloadable_cpath? The file name is
+    # stored in order to be able to delete it from $LOADED_FEATURES, and the
     # pair [Module, Symbol] is used to remove_const the constant from the class
     # or module object.
     #
@@ -123,15 +76,6 @@ module Zeitwerk
     # @sig Hash[String, Array[String]]
     attr_reader :lazy_subdirs
 
-    # 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 when a constant is loaded.
-    attr_reader :on_load_callbacks
-
     # @private
     # @sig Mutex
     attr_reader :mutex
@@ -141,150 +85,21 @@ module Zeitwerk
     attr_reader :mutex2
 
     def initialize
-      @initialized_at = Time.now
-
-      @tag       = SecureRandom.hex(3)
-      @inflector = Inflector.new
-      @logger    = self.class.default_logger
-
-      @root_dirs              = {}
-      @preloads               = []
-      @ignored_glob_patterns  = Set.new
-      @ignored_paths          = Set.new
-      @collapse_glob_patterns = Set.new
-      @collapse_dirs          = Set.new
-      @autoloads              = {}
-      @autoloaded_dirs        = []
-      @to_unload              = {}
-      @lazy_subdirs           = {}
-      @eager_load_exclusions  = Set.new
-      @on_load_callbacks      = {}
-
-      # TODO: find a better name for these mutexes.
-      @mutex        = Mutex.new
-      @mutex2       = Mutex.new
-      @setup        = false
-      @eager_loaded = false
-
-      @reloading_enabled = false
-
-      Registry.register_loader(self)
-    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
-
-    # 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 Error, "#{namespace.inspect} is not a class or module object, should be"
-      end
+      super
 
-      abspath = File.expand_path(path)
-      if dir?(abspath)
-        raise_if_conflicting_directory(abspath)
-        root_dirs[abspath] = namespace
-      else
-        raise Error, "the root directory #{abspath} does not exist"
-      end
-    end
+      @autoloads       = Autoloads.new
+      @autoloaded_dirs = []
+      @to_unload       = {}
+      @lazy_subdirs    = Hash.new { |h, cpath| h[cpath] = [] }
+      @mutex           = Mutex.new
+      @mutex2          = Mutex.new
+      @setup           = false
+      @eager_loaded    = false
 
-    # 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 Error, "cannot enable reloading after setup"
-        else
-          @reloading_enabled = true
-        end
-      end
-    end
-
-    # @sig () -> bool
-    def reloading_enabled?
-      @reloading_enabled
-    end
-
-    # Files or directories to be preloaded instead of lazy loaded.
-    #
-    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
-    def preload(*paths)
-      mutex.synchronize do
-        expand_paths(paths).each do |abspath|
-          preloads << abspath
-          do_preload_abspath(abspath) if @setup
-        end
-      end
-    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 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
+      Registry.register_loader(self)
     end
 
-    # Sets autoloads in the root namespace and preloads files, if any.
+    # Sets autoloads in the root namespace.
     #
     # @sig () -> void
     def setup
@@ -294,7 +109,8 @@ module Zeitwerk
         actual_root_dirs.each do |root_dir, namespace|
           set_autoloads_in_dir(root_dir, namespace)
         end
-        do_preload
+
+        on_setup_callbacks.each(&:call)
 
         @setup = true
       end
@@ -307,7 +123,10 @@ module Zeitwerk
     # else, they are eligible for garbage collection, which would effectively
     # unload them.
     #
-    # @private
+    # This method is public but undocumented. Main interface is `reload`, which
+    # means `unload` + `setup`. This one is avaiable to be used together with
+    # `unregister`, which is undocumented too.
+    #
     # @sig () -> void
     def unload
       mutex.synchronize do
@@ -319,21 +138,26 @@ module Zeitwerk
         # is enough.
         unloaded_files = Set.new
 
-        autoloads.each do |realpath, (parent, cname)|
+        autoloads.each do |(parent, cname), abspath|
           if parent.autoload?(cname)
             unload_autoload(parent, cname)
           else
             # Could happen if loaded with require_relative. That is unsupported,
             # and the constant path would escape unloadable_cpath? This is just
             # defensive code to clean things up as much as we are able to.
-            unload_cref(parent, cname)   if cdef?(parent, cname)
-            unloaded_files.add(realpath) if ruby?(realpath)
+            unload_cref(parent, cname)  if cdef?(parent, cname)
+            unloaded_files.add(abspath) if ruby?(abspath)
           end
         end
 
-        to_unload.each_value do |(realpath, (parent, cname))|
-          unload_cref(parent, cname)   if cdef?(parent, cname)
-          unloaded_files.add(realpath) if ruby?(realpath)
+        to_unload.each do |cpath, (abspath, (parent, cname))|
+          unless on_unload_callbacks.empty?
+            value = parent.const_get(cname)
+            run_on_unload_callbacks(cpath, value, abspath)
+          end
+
+          unload_cref(parent, cname)  if cdef?(parent, cname)
+          unloaded_files.add(abspath) if ruby?(abspath)
         end
 
         unless unloaded_files.empty?
@@ -357,7 +181,7 @@ module Zeitwerk
         lazy_subdirs.clear
 
         Registry.on_unload(self)
-        ExplicitNamespace.unregister(self)
+        ExplicitNamespace.unregister_loader(self)
 
         @setup        = false
         @eager_loaded = false
@@ -393,27 +217,29 @@ module Zeitwerk
       mutex.synchronize do
         break if @eager_loaded
 
+        log("eager load start") if logger
+
         queue = []
         actual_root_dirs.each do |root_dir, namespace|
-          queue << [namespace, root_dir] unless eager_load_exclusions.member?(root_dir)
+          queue << [namespace, root_dir] unless excluded_from_eager_load?(root_dir)
         end
 
         while to_eager_load = queue.shift
           namespace, dir = to_eager_load
 
           ls(dir) do |basename, abspath|
-            next if eager_load_exclusions.member?(abspath)
+            next if excluded_from_eager_load?(abspath)
 
             if ruby?(abspath)
-              if cref = autoloads[File.realpath(abspath)]
-                cref[0].const_get(cref[1], false)
+              if cref = autoloads.cref_for(abspath)
+                cget(*cref)
               end
             elsif dir?(abspath) && !root_dirs.key?(abspath)
-              if collapse_dirs.member?(abspath)
+              if collapse?(abspath)
                 queue << [namespace, abspath]
               else
                 cname = inflector.camelize(basename, abspath)
-                queue << [namespace.const_get(cname, false), abspath]
+                queue << [cget(namespace, cname), abspath]
               end
             end
           end
@@ -425,15 +251,9 @@ module Zeitwerk
         autoloaded_dirs.clear
 
         @eager_loaded = true
-      end
-    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)) }
+        log("eager load end") if logger
+      end
     end
 
     # Says if the given constant path would be unloaded on reload. This
@@ -452,26 +272,13 @@ module Zeitwerk
       to_unload.keys.freeze
     end
 
-    # Logs to `$stdout`, handy shortcut for debugging.
+    # This is a dangerous method.
     #
+    # @experimental
     # @sig () -> void
-    def log!
-      @logger = ->(msg) { puts msg }
-    end
-
-    # @private
-    # @sig (String) -> bool
-    def manages?(dir)
-      dir = dir + "/"
-      ignored_paths.each do |ignored_path|
-        return false if dir.start_with?(ignored_path + "/")
-      end
-
-      root_dirs.each_key do |root_dir|
-        return true if root_dir.start_with?(dir) || dir.start_with?(root_dir + "/")
-      end
-
-      false
+    def unregister
+      Registry.unregister_loader(self)
+      ExplicitNamespace.unregister_loader(self)
     end
 
     # --- Class methods ---------------------------------------------------------------------------
@@ -521,19 +328,12 @@ module Zeitwerk
 
     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, Module) -> void
     def set_autoloads_in_dir(dir, parent)
       ls(dir) do |basename, abspath|
         begin
           if ruby?(basename)
-            basename[-3..-1] = ''
+            basename.delete_suffix!(".rb")
             cname = inflector.camelize(basename, abspath).to_sym
             autoload_file(parent, cname, abspath)
           elsif dir?(abspath)
@@ -543,9 +343,9 @@ module Zeitwerk
             # To resolve the ambiguity file name -> constant path this introduces,
             # the `app/models/concerns` directory is totally ignored as a namespace,
             # it counts only as root. The guard checks that.
-            unless root_dirs.key?(abspath)
+            unless root_dir?(abspath)
               cname = inflector.camelize(basename, abspath).to_sym
-              if collapse_dirs.member?(abspath)
+              if collapse?(abspath)
                 set_autoloads_in_dir(abspath, parent)
               else
                 autoload_subdir(parent, cname, abspath)
@@ -573,27 +373,28 @@ module Zeitwerk
 
     # @sig (Module, Symbol, String) -> void
     def autoload_subdir(parent, cname, subdir)
-      if autoload_path = autoload_for?(parent, cname)
+      if autoload_path = autoloads.abspath_for(parent, cname)
         cpath = cpath(parent, cname)
         register_explicit_namespace(cpath) if ruby?(autoload_path)
         # We do not need to issue another autoload, the existing one is enough
         # no matter if it is for a file or a directory. Just remember the
         # subdirectory has to be visited if the namespace is used.
-        (lazy_subdirs[cpath] ||= []) << subdir
+        lazy_subdirs[cpath] << subdir
       elsif !cdef?(parent, cname)
         # First time we find this namespace, set an autoload for it.
-        (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
+        lazy_subdirs[cpath(parent, cname)] << subdir
         set_autoload(parent, cname, subdir)
       else
         # For whatever reason the constant that corresponds to this namespace has
         # already been defined, we have to recurse.
-        set_autoloads_in_dir(subdir, parent.const_get(cname))
+        log("the namespace #{cpath(parent, cname)} already exists, descending into #{subdir}") if logger
+        set_autoloads_in_dir(subdir, cget(parent, cname))
       end
     end
 
     # @sig (Module, Symbol, String) -> void
     def autoload_file(parent, cname, file)
-      if autoload_path = autoload_for?(parent, cname)
+      if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
           log("file #{file} is ignored because #{autoload_path} has precedence") if logger
@@ -620,163 +421,32 @@ module Zeitwerk
       autoloads.delete(dir)
       Registry.unregister_autoload(dir)
 
+      log("earlier autoload for #{cpath(parent, cname)} discarded, it is actually an explicit namespace defined in #{file}") if logger
+
       set_autoload(parent, cname, file)
       register_explicit_namespace(cpath(parent, cname))
     end
 
     # @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
-      # be able to do a lookup later in Kernel#require for manual require calls.
-      #
-      # We freeze realpath because that saves allocations in Module#autoload.
-      # See #125.
-      realpath = File.realpath(abspath).freeze
-      parent.autoload(cname, realpath)
+      autoloads.define(parent, cname, abspath)
+
       if logger
-        if ruby?(realpath)
-          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{realpath}")
+        if ruby?(abspath)
+          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{abspath}")
         else
-          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{realpath}")
+          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{abspath}")
         end
       end
 
-      autoloads[realpath] = [parent, cname]
-      Registry.register_autoload(self, realpath)
+      Registry.register_autoload(self, abspath)
 
       # See why in the documentation of Zeitwerk::Registry.inceptions.
       unless parent.autoload?(cname)
-        Registry.register_inception(cpath(parent, cname), realpath, self)
-      end
-    end
-
-    # @sig (Module, Symbol) -> String?
-    def autoload_for?(parent, cname)
-      strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
-    end
-
-    # 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
-
-    # This method is called this way because I prefer `preload` to be the method
-    # name to configure preloads in the public interface.
-    #
-    # @sig () -> void
-    def do_preload
-      preloads.each do |abspath|
-        do_preload_abspath(abspath)
-      end
-    end
-
-    # @sig (String) -> void
-    def do_preload_abspath(abspath)
-      if ruby?(abspath)
-        do_preload_file(abspath)
-      elsif dir?(abspath)
-        do_preload_dir(abspath)
+        Registry.register_inception(cpath(parent, cname), abspath, self)
       end
     end
 
-    # @sig (String) -> void
-    def do_preload_dir(dir)
-      ls(dir) do |_basename, abspath|
-        do_preload_abspath(abspath)
-      end
-    end
-
-    # @sig (String) -> bool
-    def do_preload_file(file)
-      log("preloading #{file}") if logger
-      require file
-    end
-
-    # @sig (Module, Symbol) -> String
-    def cpath(parent, cname)
-      parent.equal?(Object) ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
-    end
-
-    # @sig (String) { (String, String) -> void } -> void
-    def ls(dir)
-      Dir.foreach(dir) do |basename|
-        next if basename.start_with?(".")
-
-        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 | 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
-
-    # @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)
@@ -786,17 +456,33 @@ module Zeitwerk
     def raise_if_conflicting_directory(dir)
       self.class.mutex.synchronize do
         Registry.loaders.each do |loader|
-          if loader != self && loader.manages?(dir)
-            require "pp"
-            raise Error,
-              "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
-              " which is already managed by\n\n#{loader.pretty_inspect}\n"
-            EOS
+          next if loader == self
+          next if loader.ignores?(dir)
+
+          dir = dir + "/"
+          loader.root_dirs.each do |root_dir, _namespace|
+            next if ignores?(root_dir)
+
+            root_dir = root_dir + "/"
+            if dir.start_with?(root_dir) || root_dir.start_with?(dir)
+              require "pp" # Needed for pretty_inspect, even in Ruby 2.5.
+              raise Error,
+                "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir.chop}," \
+                " which is already managed by\n\n#{loader.pretty_inspect}\n"
+              EOS
+            end
           end
         end
       end
     end
 
+    # @sig (String, Object, String) -> void
+    def run_on_unload_callbacks(cpath, value, abspath)
+      # Order matters. If present, run the most specific one.
+      on_unload_callbacks[cpath]&.each { |c| c.call(value, abspath) }
+      on_unload_callbacks[:ANY]&.each { |c| c.call(cpath, value, abspath) }
+    end
+
     # @sig (Module, Symbol) -> void
     def unload_autoload(parent, cname)
       parent.__send__(:remove_const, cname)