zeitwerk 2.2.0 → 2.8.2

data/lib/zeitwerk/loader.rb

@@ -1,70 +1,59 @@
 # frozen_string_literal: true
 
-require "set"
-require "securerandom"
+require 'monitor'
+require 'set'
 
 module Zeitwerk
   class Loader
-    require_relative "loader/callbacks"
-    include Callbacks
-    include RealModName
+    require_relative 'loader/helpers'
+    require_relative 'loader/callbacks'
+    require_relative 'loader/config'
+    require_relative 'loader/eager_load'
+    require_relative 'loader/file_system'
+    require_relative 'loader/constant_path_validator'
 
-    # @return [String]
-    attr_reader :tag
+    extend Internal
 
-    # @return [#camelize]
-    attr_accessor :inflector
-
-    # @return [#call, #debug, nil]
-    attr_accessor :logger
+    include RealModName
+    include Callbacks
+    include Helpers
+    include Config
+    include EagerLoad
 
-    # 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.
+    # Maps absolute paths for which an autoload has been set ---and not
+    # executed--- to their corresponding Zeitwerk::Cref object.
     #
-    #   "/Users/fxn/blog/app/assets"   => true,
-    #   "/Users/fxn/blog/app/channels" => true,
+    #   '/Users/fxn/blog/app/models/user.rb'          => #<Zeitwerk::Cref:... @mod=Object, @cname=:User, ...>,
+    #   '/Users/fxn/blog/app/models/hotel/pricing.rb' => #<Zeitwerk::Cref:... @mod=Hotel, @cname=:Pricing, ...>,
     #   ...
     #
-    # This is a private collection maintained by the loader. The public
-    # interface for it is `push_dir` and `dirs`.
-    #
-    # @private
-    # @return [{String => true}]
-    attr_reader :root_dirs
+    #: Hash[String, Zeitwerk::Cref]
+    attr_reader :autoloads
+    internal :autoloads
 
-    # Absolute paths of files or directories that have to be preloaded.
+    # When the path passed to Module#autoload is in the stack of features being
+    # loaded at the moment, Ruby passes. For example, Module#autoload? returns
+    # `nil` even if the autoload has not been attempted. See
     #
-    # @private
-    # @return [<String>]
-    attr_reader :preloads
-
-    # Absolute paths of files, directories, of glob patterns to be totally
-    # ignored.
+    #     https://bugs.ruby-lang.org/issues/21035
     #
-    # @private
-    # @return [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.
+    # We call these "inceptions".
     #
-    # @private
-    # @return [Set<String>]
-    attr_reader :ignored_paths
-
-    # Maps real absolute paths for which an autoload has been set ---and not
-    # executed--- to their corresponding parent class or module and constant
-    # name.
+    # A common case is the entry point of gems managed by Zeitwerk. Their main
+    # file is normally required and, while doing so, the loader sets an autoload
+    # on the gem namespace. That autoload hits this edge case.
     #
-    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
-    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
-    #   ...
+    # There is some logic that needs to know if an autoload for a given constant
+    # already exists. We check Module#autoload? first, and fallback to the
+    # inceptions just in case.
     #
-    # @private
-    # @return [{String => (Module, Symbol)}]
-    attr_reader :autoloads
+    # This map keeps track of pairs (cref, autoload_path) found by the loader.
+    # The object Zeitwerk::Registry.inceptions, on the other hand, acts as a
+    # global registry for them.
+    #
+    #: Zeitwerk::Cref::Map[String]
+    attr_reader :inceptions
+    internal :inceptions
 
     # We keep track of autoloaded directories to remove them from the registry
     # at the end of eager loading.
@@ -72,176 +61,81 @@ module Zeitwerk
     # Files are removed as they are autoloaded, but directories need to wait due
     # to concurrency (see why in Zeitwerk::Loader::Callbacks#on_dir_autoloaded).
     #
-    # @private
-    # @return [<String>]
+    #: Array[String]
     attr_reader :autoloaded_dirs
+    internal :autoloaded_dirs
 
-    # Stores metadata needed for unloading. Its entries look like this:
-    #
-    #   "Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
+    # If reloading is enabled, this collection maps autoload paths to their
+    # autoloaded crefs.
     #
-    # 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
-    # pair [Module, Symbol] is used to remove_const the constant from the class
-    # or module object.
+    # On unload, the autoload paths are passed to callbacks, files deleted from
+    # $LOADED_FEATURES, and the crefs are deleted.
     #
-    # If reloading is enabled, this hash is filled as constants are autoloaded
-    # or eager loaded. Otherwise, the collection remains empty.
-    #
-    # @private
-    # @return [{String => (String, (Module, Symbol))}]
+    #: Hash[String, Zeitwerk::Cref]
     attr_reader :to_unload
+    internal :to_unload
 
-    # Maps constant paths of namespaces to arrays of corresponding directories.
-    #
-    # For example, given this mapping:
+    # Maps namespace crefs to the directories that conform the namespace.
     #
-    #   "Admin" => [
-    #     "/Users/fxn/blog/app/controllers/admin",
-    #     "/Users/fxn/blog/app/models/admin",
-    #     ...
-    #   ]
+    # When these crefs get defined we know their children are spread over those
+    # directories. We'll visit them to set up the corresponding autoloads.
     #
-    # when `Admin` gets defined we know that it plays the role of a namespace and
-    # that its children are spread over those directories. We'll visit them to set
-    # up the corresponding autoloads.
-    #
-    # @private
-    # @return [{String => <String>}]
-    attr_reader :lazy_subdirs
+    #: Zeitwerk::Cref::Map[String]
+    attr_reader :namespace_dirs
+    internal :namespace_dirs
 
-    # Absolute paths of files or directories not to be eager loaded.
+    # A shadowed file is a file managed by this loader that is ignored when
+    # setting autoloads because its matching constant is already taken.
+    #
+    # This private set is populated lazily, as we descend. For example, if the
+    # loader has only scanned the top-level, `shadowed_files` does not have the
+    # shadowed files that may exist deep in the project tree.
     #
-    # @private
-    # @return [Set<String>]
-    attr_reader :eager_load_exclusions
+    #: Set[String]
+    attr_reader :shadowed_files
+    internal :shadowed_files
 
-    # @private
-    # @return [Mutex]
+    #: Mutex
     attr_reader :mutex
+    private :mutex
 
-    # @private
-    # @return [Mutex]
-    attr_reader :mutex2
+    #: Monitor
+    attr_reader :dirs_autoload_monitor
+    private :dirs_autoload_monitor
 
+    #: () -> void
     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
-      @autoloads             = {}
-      @autoloaded_dirs       = []
-      @to_unload             = {}
-      @lazy_subdirs          = {}
-      @eager_load_exclusions = Set.new
-
-      # 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.
-    #
-    # @return [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`.
-    #
-    # @return [<String>]
-    def dirs
-      root_dirs.keys.freeze
-    end
+      super
 
-    # 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.
-    #
-    # @param path [<String, Pathname>]
-    # @raise [Zeitwerk::Error]
-    # @return [void]
-    def push_dir(path)
-      abspath = File.expand_path(path)
-      if dir?(abspath)
-        raise_if_conflicting_directory(abspath)
-        root_dirs[abspath] = true
-      else
-        raise Error, "the root directory #{abspath} does not exist"
-      end
-    end
+      @autoloads       = {}
+      @inceptions      = Zeitwerk::Cref::Map.new
+      @autoloaded_dirs = []
+      @to_unload       = {}
+      @namespace_dirs  = Zeitwerk::Cref::Map.new
+      @shadowed_files  = Set.new
+      @setup           = false
+      @eager_loaded    = false
+      @fs              = FileSystem.new(self)
+      @cpv             = ConstantPathValidator.new
 
-    # 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]
-    # @return [void]
-    def enable_reloading
-      mutex.synchronize do
-        break if @reloading_enabled
+      @mutex = Mutex.new
+      @dirs_autoload_monitor = Monitor.new
 
-        if @setup
-          raise Error, "cannot enable reloading after setup"
-        else
-          @reloading_enabled = true
-        end
-      end
+      Registry.loaders.register(self)
     end
 
-    # @return [Boolean]
-    def reloading_enabled?
-      @reloading_enabled
-    end
-
-    # Files or directories to be preloaded instead of lazy loaded.
-    #
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [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.
+    # Sets autoloads in the root namespaces.
     #
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [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
-
-    # Sets autoloads in the root namespace and preloads files, if any.
-    #
-    # @return [void]
+    #: () -> void
     def setup
       mutex.synchronize do
         break if @setup
 
-        actual_root_dirs.each { |root_dir| set_autoloads_in_dir(root_dir, Object) }
-        do_preload
+        actual_roots.each do |root_dir, root_namespace|
+          define_autoloads_for_dir(root_dir, root_namespace, external: true)
+        end
+
+        on_setup_callbacks.each(&:call)
 
         @setup = true
       end
@@ -254,60 +148,87 @@ module Zeitwerk
     # else, they are eligible for garbage collection, which would effectively
     # unload them.
     #
-    # @private
-    # @return [void]
+    # This method is public but undocumented. Main interface is `reload`, which
+    # means `unload` + `setup`. This one is available to be used together with
+    # `unregister`, which is undocumented too.
+    #
+    #: () -> void
     def unload
       mutex.synchronize do
-        # We are going to keep track of the files that were required by our
-        # autoloads to later remove them from $LOADED_FEATURES, thus making them
-        # loadable by Kernel#require again.
-        #
-        # Directories are not stored in $LOADED_FEATURES, keeping track of files
-        # is enough.
-        unloaded_files = Set.new
+        raise SetupRequired unless @setup
+        __unload
+      end
+    end
+
+    # This is an internal method.
+    #
+    #: () -> void
+    def __unload
+      # We are going to keep track of the files that were required by our
+      # autoloads to later remove them from $LOADED_FEATURES, thus making them
+      # loadable by Kernel#require again.
+      #
+      # Directories are not stored in $LOADED_FEATURES, keeping track of files
+      # is enough.
+      unloaded_files = Set.new
 
-        autoloads.each do |realpath, (parent, cname)|
-          if parent.autoload?(cname)
-            unload_autoload(parent, cname)
+      autoloads.each do |abspath, cref|
+        if cref.autoload?
+          unload_autoload(cref)
+        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(cref)
+          unloaded_files.add(abspath) if @fs.rb_extension?(abspath)
+        end
+      end
+
+      to_unload.each do |abspath, cref|
+        unless on_unload_callbacks.empty?
+          begin
+            value = cref.get
+          rescue ::NameError
+            # Perhaps the user deleted the constant by hand, or perhaps an
+            # autoload failed to define the expected constant but the user
+            # rescued the exception.
           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)
+            run_on_unload_callbacks(cref, value, 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)
-        end
+        unload_cref(cref)
+        unloaded_files.add(abspath) if @fs.rb_extension?(abspath)
+      end
 
-        unless unloaded_files.empty?
-          # Bootsnap decorates Kernel#require to speed it up using a cache and
-          # this optimization does not check if $LOADED_FEATURES has the file.
-          #
-          # To make it aware of changes, the gem defines singleton methods in
-          # $LOADED_FEATURES:
-          #
-          #   https://github.com/Shopify/bootsnap/blob/master/lib/bootsnap/load_path_cache/core_ext/loaded_features.rb
-          #
-          # Rails applications may depend on bootsnap, so for unloading to work
-          # in that setting it is preferable that we restrict our API choice to
-          # one of those methods.
-          $LOADED_FEATURES.reject! { |file| unloaded_files.member?(file) }
-        end
+      unless unloaded_files.empty?
+        # Bootsnap decorates Kernel#require to speed it up using a cache and
+        # this optimization does not check if $LOADED_FEATURES has the file.
+        #
+        # To make it aware of changes, the gem defines singleton methods in
+        # $LOADED_FEATURES:
+        #
+        #   https://github.com/rails/bootsnap/blob/main/lib/bootsnap/load_path_cache/core_ext/loaded_features.rb
+        #
+        # Rails applications may depend on bootsnap, so for unloading to work
+        # in that setting it is preferable that we restrict our API choice to
+        # one of those methods.
+        $LOADED_FEATURES.reject! { |file| unloaded_files.member?(file) }
+      end
 
-        autoloads.clear
-        autoloaded_dirs.clear
-        to_unload.clear
-        lazy_subdirs.clear
+      autoloads.clear
+      autoloaded_dirs.clear
+      to_unload.clear
+      namespace_dirs.clear
+      shadowed_files.clear
 
-        Registry.on_unload(self)
-        ExplicitNamespace.unregister(self)
+      unregister_inceptions
+      unregister_explicit_namespaces
 
-        @setup = false
-      end
+      Registry.autoloads.unregister_loader(self)
+
+      @setup        = false
+      @eager_loaded = false
     end
 
     # Unloads all loaded code, and calls setup again so that the loader is able
@@ -316,444 +237,447 @@ module Zeitwerk
     # This method is not thread-safe, please see how this can be achieved by
     # client code in the README of the project.
     #
-    # @raise [Zeitwerk::Error]
-    # @return [void]
+    #: () -> void ! Zeitwerk::Error
     def reload
-      if reloading_enabled?
-        unload
-        recompute_ignored_paths
-        setup
-      else
-        raise ReloadingDisabledError, "can't reload, please call loader.enable_reloading before setup"
-      end
+      raise ReloadingDisabledError unless reloading_enabled?
+      raise SetupRequired unless @setup
+
+      unload
+
+      recompute_ignored_paths
+      recompute_collapse_dirs
+      recompute_collapse_parents
+
+      setup
     end
 
-    # Eager loads all files in the root directories, recursively. Files do not
-    # need to be in `$LOAD_PATH`, absolute file names are used. Ignored files
-    # are not eager loaded. You can opt-out specifically in specific files and
-    # directories with `do_not_eager_load`.
+    # Returns a hash that maps the absolute paths of the managed files and
+    # directories to their respective expected constant paths.
     #
-    # @return [void]
-    def eager_load
-      mutex.synchronize do
-        break if @eager_loaded
+    #: () -> Hash[String, String]
+    def all_expected_cpaths
+      result = {}
+
+      actual_roots.each do |root_dir, root_namespace|
+        queue = [[root_dir, real_mod_name(root_namespace)]]
 
-        queue = actual_root_dirs.reject { |dir| eager_load_exclusions.member?(dir) }
-        queue.map! { |dir| [Object, dir] }
-        while to_eager_load = queue.shift
-          namespace, dir = to_eager_load
+        while (dir, cpath = queue.shift)
+          result[dir] = cpath
 
-          ls(dir) do |basename, abspath|
-            next if eager_load_exclusions.member?(abspath)
+          prefix = cpath == 'Object' ? '' : cpath + '::'
 
-            if ruby?(abspath)
-              if cref = autoloads[File.realpath(abspath)]
-                cref[0].const_get(cref[1], false)
+          @fs.ls(dir, collapse: false) do |basename, abspath, ftype|
+            if ftype == :file
+              if basename == @nsfile
+                result[abspath] = cpath
+              else
+                basename.delete_suffix!('.rb')
+                result[abspath] = "#{prefix}#{cname_for(basename, abspath)}"
               end
-            elsif dir?(abspath) && !root_dirs.key?(abspath)
-              cname = inflector.camelize(basename, abspath)
-              queue << [namespace.const_get(cname, false), abspath]
+            elsif collapse?(abspath)
+              queue.unshift([abspath, cpath])
+            else
+              queue.push([abspath, "#{prefix}#{cname_for(basename, abspath)}"])
             end
           end
         end
+      end
 
-        autoloaded_dirs.each do |autoloaded_dir|
-          Registry.unregister_autoload(autoloaded_dir)
-        end
-        autoloaded_dirs.clear
+      result
+    end
+
+    #: (String | Pathname) -> String?
+    def cpath_expected_at(path)
+      abspath = File.expand_path(path)
+
+      raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
+
+      ftype = @fs.supported_ftype?(abspath)
+      return unless ftype
+
+      return if ignored_path?(abspath)
 
-        @eager_loaded = true
+      paths = []
+
+      if ftype == :file
+        basename = File.basename(abspath)
+        return if @fs.hidden?(basename)
+
+        paths << [basename.delete_suffix('.rb'), abspath] unless basename == @nsfile
+        walk_up_from = File.dirname(abspath)
+      else
+        walk_up_from = abspath
       end
-    end
 
-    # 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]
-    def do_not_eager_load(*paths)
-      mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
+      root_namespace = nil
+
+      @fs.walk_up(walk_up_from) do |dir|
+        break if root_namespace = roots[dir]
+        return if ignored_path?(dir)
+
+        basename = File.basename(dir)
+        return if @fs.hidden?(basename)
+
+        paths << [basename, dir] unless collapse?(dir)
+      end
+
+      return unless root_namespace
+
+      if paths.empty?
+        real_mod_name(root_namespace)
+      else
+        cnames = paths.reverse_each.map { cname_for(_1, _2) }
+
+        if root_namespace == Object
+          cnames.join('::')
+        else
+          "#{real_mod_name(root_namespace)}::#{cnames.join('::')}"
+        end
+      end
     end
 
     # Says if the given constant path would be unloaded on reload. This
     # predicate returns `false` if reloading is disabled.
     #
-    # @param cpath [String]
-    # @return [Boolean]
+    # This is an undocumented method that I wrote to help transition from the
+    # classic autoloader in Rails. Its usage was removed from Rails in 7.0.
+    #
+    #: (String) -> bool
     def unloadable_cpath?(cpath)
-      to_unload.key?(cpath)
+      unloadable_cpaths.include?(cpath)
     end
 
     # 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>]
+    # This is an undocumented method that I wrote to help transition from the
+    # classic autoloader in Rails. Its usage was removed from Rails in 7.0.
+    #
+    #: () -> Array[String]
     def unloadable_cpaths
-      to_unload.keys.freeze
+      to_unload.values.map(&:path)
     end
 
-    # Logs to `$stdout`, handy shortcut for debugging.
+    # This is a dangerous method.
     #
-    # @return [void]
-    def log!
-      @logger = ->(msg) { puts msg }
+    # @experimental
+    #: () -> void
+    def unregister
+      unregister_inceptions
+      unregister_explicit_namespaces
+      Registry.loaders.unregister(self)
+      Registry.autoloads.unregister_loader(self)
+      Registry.unregister_loader(self)
     end
 
-    # @private
-    # @param dir [String]
-    # @return [Boolean]
-    def manages?(dir)
-      dir = dir + "/"
-      ignored_paths.each do |ignored_path|
-        return false if dir.start_with?(ignored_path + "/")
-      end
+    # The return value of this predicate is only meaningful if the loader has
+    # scanned the file. This is the case in the spots where we use it.
+    #
+    #: (String) -> bool
+    internal def shadowed_file?(file)
+      shadowed_files.member?(file)
+    end
 
-      root_dirs.each_key do |root_dir|
-        return true if root_dir.start_with?(dir) || dir.start_with?(root_dir + "/")
-      end
+    #: { () -> String } -> void
+    internal def log
+      return unless logger
 
-      false
+      message = yield
+      method_name = logger.respond_to?(:debug) ? :debug : :call
+      logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
     end
 
+
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
-      # @return [#call, #debug, nil]
-      attr_accessor :default_logger
+      include RealModName
 
-      # @private
-      # @return [Mutex]
-      attr_accessor :mutex
+      #: call(String) -> void | debug(String) -> void | nil
+      attr_accessor :default_logger
 
       # This is a shortcut for
       #
-      #   require "zeitwerk"
+      #   require 'zeitwerk'
+      #
       #   loader = Zeitwerk::Loader.new
-      #   loader.tag = File.basename(__FILE__, ".rb")
-      #   loader.inflector = Zeitwerk::GemInflector.new
+      #   loader.tag = File.basename(__FILE__, '.rb')
+      #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
       #   loader.push_dir(__dir__)
       #
       # 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]
-      def for_gem
+      # This method returns a subclass of Zeitwerk::Loader, but the exact type
+      # is private, client code can only rely on the interface.
+      #
+      #: (?warn_on_extra_files: boolish) -> Zeitwerk::GemLoader
+      def for_gem(warn_on_extra_files: true)
+        called_from = caller_locations(1, 1).first.path
+        Registry.loader_for_gem(called_from, namespace: Object, warn_on_extra_files: warn_on_extra_files)
+      end
+
+      # This is a shortcut for
+      #
+      #   require 'zeitwerk'
+      #
+      #   loader = Zeitwerk::Loader.new
+      #   loader.tag = namespace.name + '-' + File.basename(__FILE__, '.rb')
+      #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+      #   loader.push_dir(__dir__, namespace: namespace)
+      #
+      # 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.
+      #
+      # This method returns a subclass of Zeitwerk::Loader, but the exact type
+      # is private, client code can only rely on the interface.
+      #
+      #: (Module) -> Zeitwerk::GemLoader
+      def for_gem_extension(namespace)
+        unless namespace.is_a?(Module) # Note that Class < Module.
+          raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
+        end
+
+        unless real_mod_name(namespace)
+          raise Zeitwerk::Error, 'extending anonymous namespaces is unsupported'
+        end
+
         called_from = caller_locations(1, 1).first.path
-        Registry.loader_for_gem(called_from)
+        Registry.loader_for_gem(called_from, namespace: namespace, warn_on_extra_files: false)
       end
 
-      # Broadcasts `eager_load` to all loaders.
+      # Broadcasts `eager_load` to all loaders. Those that have not been setup
+      # are skipped.
       #
-      # @return [void]
+      #: () -> void
       def eager_load_all
-        Registry.loaders.each(&:eager_load)
+        Registry.loaders.each do |loader|
+          begin
+            loader.eager_load
+          rescue SetupRequired
+            # This is fine, we eager load what can be eager loaded.
+          end
+        end
+      end
+
+      # Broadcasts `eager_load_namespace` to all loaders. Those that have not
+      # been setup are skipped.
+      #
+      #: (Module) -> void
+      def eager_load_namespace(mod)
+        Registry.loaders.each do |loader|
+          begin
+            loader.eager_load_namespace(mod)
+          rescue SetupRequired
+            # This is fine, we eager load what can be eager loaded.
+          end
+        end
       end
 
       # Returns an array with the absolute paths of the root directories of all
       # registered loaders. This is a read-only collection.
       #
-      # @return [<String>]
+      #: () -> Array[String]
       def all_dirs
-        Registry.loaders.flat_map(&:dirs).freeze
-      end
-    end
-
-    self.mutex = Mutex.new
-
-    private # -------------------------------------------------------------------------------------
-
-    # @return [<String>]
-    def actual_root_dirs
-      root_dirs.keys.delete_if do |root_dir|
-        !dir?(root_dir) || ignored_paths.member?(root_dir)
+        dirs = []
+        Registry.loaders.each do |loader|
+          dirs.concat(loader.dirs)
+        end
+        dirs.freeze
       end
     end
 
-    # @param dir [String]
-    # @param parent [Module]
-    # @return [void]
-    def set_autoloads_in_dir(dir, parent)
-      ls(dir) do |basename, abspath|
-        begin
-          if ruby?(basename)
-            basename.slice!(-3, 3)
-            cname = inflector.camelize(basename, abspath).to_sym
-            autoload_file(parent, cname, abspath)
-          elsif dir?(abspath)
-            # In a Rails application, `app/models/concerns` is a subdirectory of
-            # `app/models`, but both of them are root directories.
-            #
-            # 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)
-              cname = inflector.camelize(basename, abspath).to_sym
-              autoload_subdir(parent, cname, abspath)
+    # Scans `dir` and sets autoloads in `mod` for the constants its contents are
+    # expected to define.
+    #
+    # The `external` flag indicates whether `mod` has been externally defined,
+    # as is the case with root namespaces or reopened third-party namespaces.
+    #
+    #: (String, Module, external: boolish) -> void
+    private def define_autoloads_for_dir(dir, mod, external:)
+      @fs.ls(dir) do |basename, abspath, ftype|
+        if ftype == :file
+          if basename == @nsfile
+            if external
+              cpath = real_mod_name(mod)
+              location = Object.const_source_location(cpath)&.join(':')
+              location = nil if location&.empty?
+              raise Zeitwerk::ConflictingNamespaceDefinitionError.new(cpath, location: location, conflicting_file: abspath)
             end
+            next # Pass if this is a managed namespace, the nsfile was already probed when visiting the parent directory.
           end
-        rescue ::NameError => error
-          path_type = ruby?(abspath) ? "file" : "directory"
-
-          raise NameError, <<~MESSAGE
-            #{error.message} inferred by #{inflector.class} from #{path_type}
 
-              #{abspath}
-
-            Possible ways to address this:
-
-              * Tell Zeitwerk to ignore this particular #{path_type}.
-              * Tell Zeitwerk to ignore one of its parent directories.
-              * Rename the #{path_type} to comply with the naming conventions.
-              * Modify the inflector to handle this case.
-          MESSAGE
+          basename.delete_suffix!('.rb')
+          cref = Cref.new(mod, cname_for(basename, abspath))
+          visit_file(cref, abspath)
+        else
+          cref = Cref.new(mod, cname_for(basename, abspath))
+          visit_subdir(cref, abspath, external:)
         end
       end
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @param subdir [String]
-    # @return [void]
-    def autoload_subdir(parent, cname, subdir)
-      if autoload_path = autoload_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
-      elsif !cdef?(parent, cname)
-        # First time we find this namespace, set an autoload for it.
-        (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
-        set_autoload(parent, cname, subdir)
+    #: (Zeitwerk::Cref, String) -> void
+    private def visit_file(cref, file)
+      if autoload_path = cref.autoload? || Registry.inceptions.registered?(cref)
+        if @fs.rb_extension?(autoload_path)
+          if File.basename(autoload_path) == @nsfile && autoload_path_set_by_me_for?(cref)
+            raise Zeitwerk::ConflictingNamespaceDefinitionError.new(cref.path, location: autoload_path, conflicting_file: file)
+          end
+          shadowed_files << file
+          log { "file #{file} is ignored because #{autoload_path} has precedence" }
+        else
+          promote_namespace_from_implicit_to_explicit(dir: autoload_path, file: file, cref: cref)
+        end
+      elsif cref.defined?
+        shadowed_files << file
+        if location = cref.location
+          log { "file #{file} is ignored because #{cref} is already defined in #{location}" }
+        else
+          log { "file #{file} is ignored because #{cref} is already defined (unknown location)" }
+        end
       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))
+        define_autoload(cref, file)
       end
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @param file [String]
-    # @return [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.
-        if ruby?(autoload_path)
-          log("file #{file} is ignored because #{autoload_path} has precedence") if logger
+    #: (Zeitwerk::Cref, String, external: boolish) -> void
+    private def visit_subdir(cref, subdir, external:)
+      if autoload_path = autoload_path_set_by_me_for?(cref)
+        if @fs.rb_extension?(autoload_path)
+          # The namespace that corresponds to this subdirectory is defined in a
+          # file, either regular or nsfile. Therefore, a nsfile would be a
+          # duplication.
+          if nsfile_abspath = @fs.has_exactly_one_nsfile?(cref, subdir)
+            raise Zeitwerk::ConflictingNamespaceDefinitionError.new(cref.path, location: autoload_path, conflicting_file: nsfile_abspath)
+          end
+          # Scanning visited a Ruby file first, and now a directory for the same
+          # constant has been found. This is an explicit namespace.
+          #
+          # The namespace may be spread over multiple directories and perhaps it
+          # was already registered, but registering is idempotent, just do it.
+          register_explicit_namespace(cref)
+        elsif nsfile_abspath = @fs.has_exactly_one_nsfile?(cref, subdir)
+          # Scanning found a matching directory first, and now we saw a nsfile.
+          promote_namespace_from_implicit_to_explicit(dir: subdir, file: nsfile_abspath, cref: cref)
+        end
+        namespace_dirs.get_or_set(cref) { [] } << subdir
+      elsif !cref.defined?
+        if nsfile_abspath = @fs.has_exactly_one_nsfile?(cref, subdir)
+          define_autoload(cref, nsfile_abspath)
+          register_explicit_namespace(cref)
         else
-          promote_namespace_from_implicit_to_explicit(
-            dir:    autoload_path,
-            file:   file,
-            parent: parent,
-            cname:  cname
-          )
+          define_autoload(cref, subdir)
         end
-      elsif cdef?(parent, cname)
-        log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
+        namespace_dirs.get_or_set(cref) { [] } << subdir
       else
-        set_autoload(parent, cname, file)
+        # For whatever reason the constant that corresponds to this namespace has
+        # already been defined, we have to recurse.
+        log { "the namespace #{cref} already exists, descending into #{subdir}" }
+        define_autoloads_for_dir(subdir, cref.get, external:)
       end
     end
 
-    # @param dir [String] directory that would have autovivified a module
-    # @param file [String] the file where the namespace is explictly defined
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [void]
-    def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
+    # `dir` is the directory that would have autovivified a namespace. `file` is
+    # the file where we've found the namespace is explicitly defined.
+    #
+    #: (dir: String, file: String, cref: Zeitwerk::Cref) -> void
+    private def promote_namespace_from_implicit_to_explicit(dir:, file:, cref:)
       autoloads.delete(dir)
-      Registry.unregister_autoload(dir)
+      Registry.autoloads.unregister(dir)
+
+      log { "earlier autoload for #{cref} discarded, it is actually an explicit namespace defined in #{file}" }
 
-      set_autoload(parent, cname, file)
-      register_explicit_namespace(cpath(parent, cname))
+      # Order matters: When Module#const_added is triggered by the autoload, we
+      # don't want the namespace to be registered yet.
+      define_autoload(cref, file)
+      register_explicit_namespace(cref)
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @param abspath [String]
-    # @return [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.
-      realpath = File.realpath(abspath)
-      parent.autoload(cname, realpath)
+    #: (Zeitwerk::Cref, String) -> void
+    private def define_autoload(cref, abspath)
+      cref.autoload(abspath)
+
       if logger
-        if ruby?(realpath)
-          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{realpath}")
+        if @fs.rb_extension?(abspath)
+          log { "autoload set for #{cref}, to be loaded from #{abspath}" }
         else
-          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{realpath}")
+          log { "autoload set for #{cref}, to be autovivified from #{abspath}" }
         end
       end
 
-      autoloads[realpath] = [parent, cname]
-      Registry.register_autoload(self, realpath)
-
-      # See why in the documentation of Zeitwerk::Registry.inceptions.
-      unless parent.autoload?(cname)
-        Registry.register_inception(cpath(parent, cname), realpath, self)
-      end
-    end
+      autoloads[abspath] = cref
+      Registry.autoloads.register(abspath, self)
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [String, nil]
-    def autoload_for?(parent, cname)
-      strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
+      register_inception(cref, abspath) unless cref.autoload?
     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.
-    #
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [String, nil]
-    def strict_autoload_path(parent, cname)
-      parent.autoload?(cname) if cdef?(parent, cname)
-    end
-
-    # This method is called this way because I prefer `preload` to be the method
-    # name to configure preloads in the public interface.
-    #
-    # @return [void]
-    def do_preload
-      preloads.each do |abspath|
-        do_preload_abspath(abspath)
+    #: (Zeitwerk::Cref) -> String?
+    private def autoload_path_set_by_me_for?(cref)
+      if autoload_path = cref.autoload?
+        autoload_path if autoloads.key?(autoload_path)
+      else
+        inceptions[cref]
       end
     end
 
-    # @param abspath [String]
-    # @return [void]
-    def do_preload_abspath(abspath)
-      if ruby?(abspath)
-        do_preload_file(abspath)
-      elsif dir?(abspath)
-        do_preload_dir(abspath)
-      end
+    #: (Zeitwerk::Cref) -> void
+    private def register_explicit_namespace(cref)
+      Registry.explicit_namespaces.register(cref, self)
     end
 
-    # @param dir [String]
-    # @return [void]
-    def do_preload_dir(dir)
-      ls(dir) do |_basename, abspath|
-        do_preload_abspath(abspath)
-      end
+    #: () -> void
+    private def unregister_explicit_namespaces
+      Registry.explicit_namespaces.unregister_loader(self)
     end
 
-    # @param file [String]
-    # @return [Boolean]
-    def do_preload_file(file)
-      log("preloading #{file}") if logger
-      require file
+    #: (Zeitwerk::Cref, String) -> void
+    private def register_inception(cref, abspath)
+      inceptions[cref] = abspath
+      Registry.inceptions.register(cref, abspath)
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [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]
-    def ls(dir)
-      Dir.foreach(dir) do |basename|
-        next if basename.start_with?(".")
-        abspath = File.join(dir, basename)
-        yield basename, abspath unless ignored_paths.member?(abspath)
+    #: () -> void
+    private def unregister_inceptions
+      inceptions.each_key do |cref|
+        Registry.inceptions.unregister(cref)
       end
+      inceptions.clear
     end
 
-    # @param path [String]
-    # @return [Boolean]
-    def ruby?(path)
-      path.end_with?(".rb")
-    end
-
-    # @param path [String]
-    # @return [Boolean]
-    def dir?(path)
-      File.directory?(path)
-    end
-
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [<String>]
-    def expand_paths(paths)
-      paths.flatten.map! { |path| File.expand_path(path) }
-    end
-
-    # @param glob_patterns [<String>]
-    # @return [<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]
-    def recompute_ignored_paths
-      ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
-    end
-
-    # @param message [String]
-    # @return [void]
-    def log(message)
-      method_name = logger.respond_to?(:debug) ? :debug : :call
-      logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
-    end
-
-    def cdef?(parent, cname)
-      parent.const_defined?(cname, false)
-    end
-
-    def register_explicit_namespace(cpath)
-      ExplicitNamespace.register(cpath, self)
+    #: (String) -> void
+    private def raise_if_conflicting_root_dir(root_dir)
+      if loader = Registry.conflicting_root_dir?(self, root_dir)
+        require 'pp' # Needed to have pretty_inspect available.
+        raise Error,
+          "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{root_dir}," \
+          " which is already managed by\n\n#{loader.pretty_inspect}\n"
+      end
     end
 
-    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
-          end
-        end
-      end
+    #: (String, top, String) -> void
+    private def run_on_unload_callbacks(cref, value, abspath)
+      # Order matters. If present, run the most specific one.
+      on_unload_callbacks[cref.path]&.each { |c| c.call(value, abspath) }
+      on_unload_callbacks[:ANY]&.each { |c| c.call(cref.path, value, abspath) }
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [void]
-    def unload_autoload(parent, cname)
-      parent.send(:remove_const, cname)
-      log("autoload for #{cpath(parent, cname)} removed") if logger
+    #: (Zeitwerk::Cref) -> void
+    private def unload_autoload(cref)
+      cref.remove
+      log { "autoload for #{cref} removed" }
     end
 
-    # @param parent [Module]
-    # @param cname [Symbol]
-    # @return [void]
-    def unload_cref(parent, cname)
-      parent.send(:remove_const, cname)
-      log("#{cpath(parent, cname)} unloaded") if logger
+    #: (Zeitwerk::Cref) -> void
+    private def unload_cref(cref)
+      # Let's optimistically remove_const. The way we use it, this is going to
+      # succeed always if all is good.
+      cref.remove
+    rescue ::NameError
+      # There are a few edge scenarios in which this may happen. If the constant
+      # is gone, that is OK, anyway.
+    else
+      log { "#{cref} unloaded" }
     end
   end
 end