zeitwerk 2.7.2 → 2.7.3

data/lib/zeitwerk/loader.rb

@@ -18,7 +18,7 @@ module Zeitwerk
     include Config
     include EagerLoad
 
-    MUTEX = Mutex.new
+    MUTEX = Mutex.new #: Mutex
     private_constant :MUTEX
 
     # Maps absolute paths for which an autoload has been set ---and not
@@ -28,7 +28,7 @@ module Zeitwerk
     #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => #<Zeitwerk::Cref:... @mod=Hotel, @cname=:Pricing, ...>,
     #   ...
     #
-    # @sig Hash[String, Zeitwerk::Cref]
+    #: Hash[String, Zeitwerk::Cref]
     attr_reader :autoloads
     internal :autoloads
 
@@ -49,10 +49,10 @@ module Zeitwerk
     # the inceptions just in case.
     #
     # This map keeps track of pairs (cref, autoload_path) found by the loader.
-    # The module Zeitwerk::Registry::Inceptions, on the other hand, acts as a
+    # The object Zeitwerk::Registry.inceptions, on the other hand, acts as a
     # global registry for them.
     #
-    # @sig Zeitwerk::Cref::Map[String]
+    #: Zeitwerk::Cref::Map[String]
     attr_reader :inceptions
     internal :inceptions
 
@@ -62,7 +62,7 @@ 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).
     #
-    # @sig Array[String]
+    #: Array[String]
     attr_reader :autoloaded_dirs
     internal :autoloaded_dirs
 
@@ -72,7 +72,7 @@ module Zeitwerk
     # On unload, the autoload paths are passed to callbacks, files deleted from
     # $LOADED_FEATURES, and the crefs are deleted.
     #
-    # @sig Hash[String, Zeitwerk::Cref]
+    #: Hash[String, Zeitwerk::Cref]
     attr_reader :to_unload
     internal :to_unload
 
@@ -81,7 +81,7 @@ module Zeitwerk
     # When these crefs get defined we know their children are spread over those
     # directories. We'll visit them to set up the corresponding autoloads.
     #
-    # @sig Zeitwerk::Cref::Map[String]
+    #: Zeitwerk::Cref::Map[String]
     attr_reader :namespace_dirs
     internal :namespace_dirs
 
@@ -92,15 +92,15 @@ module Zeitwerk
     # loader has only scanned the top-level, `shadowed_files` does not have the
     # shadowed files that may exist deep in the project tree.
     #
-    # @sig Set[String]
+    #: Set[String]
     attr_reader :shadowed_files
     internal :shadowed_files
 
-    # @sig Mutex
+    #: Mutex
     attr_reader :mutex
     private :mutex
 
-    # @sig Monitor
+    #: Monitor
     attr_reader :dirs_autoload_monitor
     private :dirs_autoload_monitor
 
@@ -119,12 +119,12 @@ module Zeitwerk
       @mutex = Mutex.new
       @dirs_autoload_monitor = Monitor.new
 
-      Registry.register_loader(self)
+      Registry.loaders.register(self)
     end
 
     # Sets autoloads in the root namespaces.
     #
-    # @sig () -> void
+    #: () -> void
     def setup
       mutex.synchronize do
         break if @setup
@@ -150,7 +150,7 @@ module Zeitwerk
     # means `unload` + `setup`. This one is available to be used together with
     # `unregister`, which is undocumented too.
     #
-    # @sig () -> void
+    #: () -> void
     def unload
       mutex.synchronize do
         raise SetupRequired unless @setup
@@ -216,7 +216,7 @@ module Zeitwerk
         unregister_inceptions
         unregister_explicit_namespaces
 
-        Registry.on_unload(self)
+        Registry.autoloads.unregister_loader(self)
 
         @setup        = false
         @eager_loaded = false
@@ -229,8 +229,7 @@ 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]
-    # @sig () -> void
+    #: () -> void ! Zeitwerk::Error
     def reload
       raise ReloadingDisabledError unless reloading_enabled?
       raise SetupRequired unless @setup
@@ -244,7 +243,7 @@ module Zeitwerk
     # Returns a hash that maps the absolute paths of the managed files and
     # directories to their respective expected constant paths.
     #
-    # @sig () -> Hash[String, String]
+    #: () -> Hash[String, String]
     def all_expected_cpaths
       result = {}
 
@@ -274,7 +273,7 @@ module Zeitwerk
       result
     end
 
-    # @sig (String | Pathname) -> String?
+    #: (String | Pathname) -> String?
     def cpath_expected_at(path)
       abspath = File.expand_path(path)
 
@@ -304,7 +303,7 @@ module Zeitwerk
         basename = File.basename(dir)
         return if hidden?(basename)
 
-        paths << [basename, abspath] unless collapse?(dir)
+        paths << [basename, dir] unless collapse?(dir)
       end
 
       return unless root_namespace
@@ -312,7 +311,7 @@ module Zeitwerk
       if paths.empty?
         real_mod_name(root_namespace)
       else
-        cnames = paths.reverse_each.map { |b, a| cname_for(b, a) }
+        cnames = paths.reverse_each.map { cname_for(_1, _2) }
 
         if root_namespace == Object
           cnames.join("::")
@@ -328,7 +327,7 @@ module Zeitwerk
     # 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.
     #
-    # @sig (String) -> bool
+    #: (String) -> bool
     def unloadable_cpath?(cpath)
       unloadable_cpaths.include?(cpath)
     end
@@ -339,7 +338,7 @@ module Zeitwerk
     # 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.
     #
-    # @sig () -> Array[String]
+    #: () -> Array[String]
     def unloadable_cpaths
       to_unload.values.map(&:path)
     end
@@ -347,17 +346,19 @@ module Zeitwerk
     # This is a dangerous method.
     #
     # @experimental
-    # @sig () -> void
+    #: () -> void
     def unregister
       unregister_inceptions
       unregister_explicit_namespaces
+      Registry.loaders.unregister(self)
+      Registry.autoloads.unregister_loader(self)
       Registry.unregister_loader(self)
     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.
     #
-    # @sig (String) -> Boolean
+    #: (String) -> bool
     internal def shadowed_file?(file)
       shadowed_files.member?(file)
     end
@@ -367,7 +368,7 @@ module Zeitwerk
     class << self
       include RealModName
 
-      # @sig #call | #debug | nil
+      #: call(String) -> void | debug(String) -> void | nil
       attr_accessor :default_logger
 
       # This is a shortcut for
@@ -385,7 +386,7 @@ module Zeitwerk
       # This method returns a subclass of Zeitwerk::Loader, but the exact type
       # is private, client code can only rely on the interface.
       #
-      # @sig (bool) -> Zeitwerk::GemLoader
+      #: (?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)
@@ -406,7 +407,7 @@ module Zeitwerk
       # This method returns a subclass of Zeitwerk::Loader, but the exact type
       # is private, client code can only rely on the interface.
       #
-      # @sig (bool) -> Zeitwerk::GemLoader
+      #: (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"
@@ -423,7 +424,7 @@ module Zeitwerk
       # Broadcasts `eager_load` to all loaders. Those that have not been setup
       # are skipped.
       #
-      # @sig () -> void
+      #: () -> void
       def eager_load_all
         Registry.loaders.each do |loader|
           begin
@@ -437,7 +438,7 @@ module Zeitwerk
       # Broadcasts `eager_load_namespace` to all loaders. Those that have not
       # been setup are skipped.
       #
-      # @sig (Module) -> void
+      #: (Module) -> void
       def eager_load_namespace(mod)
         Registry.loaders.each do |loader|
           begin
@@ -451,13 +452,17 @@ module Zeitwerk
       # Returns an array with the absolute paths of the root directories of all
       # registered loaders. This is a read-only collection.
       #
-      # @sig () -> Array[String]
+      #: () -> Array[String]
       def all_dirs
-        Registry.loaders.flat_map(&:dirs).freeze
+        dirs = []
+        Registry.loaders.each do |loader|
+          dirs.concat(loader.dirs)
+        end
+        dirs.freeze
       end
     end
 
-    # @sig (String, Module) -> void
+    #: (String, Module) -> void
     private def define_autoloads_for_dir(dir, parent)
       ls(dir) do |basename, abspath, ftype|
         if ftype == :file
@@ -475,7 +480,7 @@ module Zeitwerk
       end
     end
 
-    # @sig (Module, Symbol, String) -> void
+    #: (Zeitwerk::Cref, String) -> void
     private def autoload_subdir(cref, subdir)
       if autoload_path = autoload_path_set_by_me_for?(cref)
         if ruby?(autoload_path)
@@ -504,9 +509,9 @@ module Zeitwerk
       end
     end
 
-    # @sig (Module, Symbol, String) -> void
+    #: (Zeitwerk::Cref, String) -> void
     private def autoload_file(cref, file)
-      if autoload_path = cref.autoload? || Registry::Inceptions.registered?(cref)
+      if autoload_path = cref.autoload? || Registry.inceptions.registered?(cref)
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
           shadowed_files << file
@@ -525,10 +530,10 @@ module Zeitwerk
     # `dir` is the directory that would have autovivified a namespace. `file` is
     # the file where we've found the namespace is explicitly defined.
     #
-    # @sig (dir: String, file: String, cref: Zeitwerk::Cref) -> void
+    #: (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}") if logger
 
@@ -538,7 +543,7 @@ module Zeitwerk
       register_explicit_namespace(cref)
     end
 
-    # @sig (Module, Symbol, String) -> void
+    #: (Zeitwerk::Cref, String) -> void
     private def define_autoload(cref, abspath)
       cref.autoload(abspath)
 
@@ -551,12 +556,12 @@ module Zeitwerk
       end
 
       autoloads[abspath] = cref
-      Registry.register_autoload(self, abspath)
+      Registry.autoloads.register(abspath, self)
 
       register_inception(cref, abspath) unless cref.autoload?
     end
 
-    # @sig (Module, Symbol) -> String?
+    #: (Zeitwerk::Cref) -> String?
     private def autoload_path_set_by_me_for?(cref)
       if autoload_path = cref.autoload?
         autoload_path if autoloads.key?(autoload_path)
@@ -565,31 +570,31 @@ module Zeitwerk
       end
     end
 
-    # @sig (Zeitwerk::Cref) -> void
+    #: (Zeitwerk::Cref) -> void
     private def register_explicit_namespace(cref)
-      Registry::ExplicitNamespaces.__register(cref, self)
+      Registry.explicit_namespaces.register(cref, self)
     end
 
-    # @sig () -> void
+    #: () -> void
     private def unregister_explicit_namespaces
-      Registry::ExplicitNamespaces.__unregister_loader(self)
+      Registry.explicit_namespaces.unregister_loader(self)
     end
 
-    # @sig (Zeitwerk::Cref, String) -> void
+    #: (Zeitwerk::Cref, String) -> void
     private def register_inception(cref, abspath)
       inceptions[cref] = abspath
-      Registry::Inceptions.register(cref, abspath)
+      Registry.inceptions.register(cref, abspath)
     end
 
-    # @sig () -> void
+    #: () -> void
     private def unregister_inceptions
       inceptions.each_key do |cref|
-        Registry::Inceptions.unregister(cref)
+        Registry.inceptions.unregister(cref)
       end
       inceptions.clear
     end
 
-    # @sig (String) -> void
+    #: (String) -> void
     private def raise_if_conflicting_directory(dir)
       MUTEX.synchronize do
         dir_slash = dir + "/"
@@ -613,20 +618,20 @@ module Zeitwerk
       end
     end
 
-    # @sig (String, top, String) -> void
+    #: (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
 
-    # @sig (Module, Symbol) -> void
+    #: (Zeitwerk::Cref) -> void
     private def unload_autoload(cref)
       cref.remove
       log("autoload for #{cref} removed") if logger
     end
 
-    # @sig (Module, Symbol) -> void
+    #: (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.

data/lib/zeitwerk/null_inflector.rb

@@ -1,5 +1,5 @@
 class Zeitwerk::NullInflector
-  # @sig (String, String) -> String
+  #: (String, String) -> String
   def camelize(basename, _abspath)
     basename
   end

data/lib/zeitwerk/real_mod_name.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 module Zeitwerk::RealModName
+  #: UnboundMethod
   UNBOUND_METHOD_MODULE_NAME = Module.instance_method(:name)
   private_constant :UNBOUND_METHOD_MODULE_NAME
 
-  # Returns the real name of the class or module, as set after the first
-  # constant to which it was assigned (or nil).
+  # Returns the real name of the class or module.
   #
-  # The name method can be overridden, hence the indirection in this method.
+  # We need this indirection becasue the `name` method can be overridden, and
+  # because in practice what we really need is the constant paths of modules
+  # with a permanent name, not so much what the user considers to be the name of
+  # a certain class or module of theirs.
   #
-  # @sig (Module) -> String?
+  #: (Module) -> String?
   def real_mod_name(mod)
     UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
   end

data/lib/zeitwerk/registry/autoloads.rb

@@ -0,0 +1,38 @@
+module Zeitwerk::Registry
+  class Autoloads # :nodoc:
+    #: () -> void
+    def initialize
+      @autoloads = {} #: Hash[String, Zeitwerk::Loader]
+    end
+
+    #: (String, Zeitwerk::Loader) -> Zeitwerk::Loader
+    def register(abspath, loader)
+      @autoloads[abspath] = loader
+    end
+
+    #: (String) -> Zeitwerk::Loader?
+    def registered?(path)
+      @autoloads[path]
+    end
+
+    #: (String) -> Zeitwerk::Loader?
+    def unregister(abspath)
+      @autoloads.delete(abspath)
+    end
+
+    #: (Zeitwerk::Loader) -> void
+    def unregister_loader(loader)
+      @autoloads.delete_if { _2 == loader }
+    end
+
+    #: () -> bool
+    def empty? # for tests
+      @autoloads.empty?
+    end
+
+    #: () -> void
+    def clear # for tests
+      @autoloads.clear
+    end
+  end
+end

data/lib/zeitwerk/registry/explicit_namespaces.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk::Registry
-  # This module is a registry for explicit namespaces.
+  # A registry for explicit namespaces.
   #
   # When a loader determines that a certain file should define an explicit
   # namespace, it registers it here, associating its cref with itself.
@@ -16,49 +16,46 @@ module Zeitwerk::Registry
   # The implementation assumes an explicit namespace is managed by one loader.
   # Loaders that reopen namespaces owned by other projects are responsible for
   # loading their constant before setup. This is documented.
-  module ExplicitNamespaces # :nodoc: all
-    # Maps crefs of explicit namespaces with their corresponding loader.
-    #
-    # Entries are added as the namespaces are found, and removed as they are
-    # autoloaded.
-    #
-    # @sig Zeitwerk::Cref::Map[Zeitwerk::Loader]
-    @loaders = Zeitwerk::Cref::Map.new
-
-    class << self
-      extend Zeitwerk::Internal
-
-      # Registers `cref` as being the constant path of an explicit namespace
-      # managed by `loader`.
+  #
+  # **This is a private module.**
+  class ExplicitNamespaces # :nodoc: all
+    #: () -> void
+    def initialize
+      # Maps crefs of explicit namespaces with their corresponding loader.
       #
-      # @sig (Zeitwerk::Cref, Zeitwerk::Loader) -> void
-      internal def register(cref, loader)
-        @loaders[cref] = loader
-      end
+      # Entries are added as the namespaces are found, and removed as they are
+      # autoloaded.
+      @loaders = Zeitwerk::Cref::Map.new
+    end
 
-      # @sig (Module, Symbol) -> Zeitwerk::Loader?
-      internal def loader_for(mod, cname)
-        @loaders.delete_mod_cname(mod, cname)
-      end
+    # Registers `cref` as being the constant path of an explicit namespace
+    # managed by `loader`.
+    #
+    #: (Zeitwerk::Cref, Zeitwerk::Loader) -> void
+    def register(cref, loader)
+      @loaders[cref] = loader
+    end
 
-      # @sig (Zeitwerk::Loader) -> void
-      internal def unregister_loader(loader)
-        @loaders.delete_by_value(loader)
-      end
+    #: (Module, Symbol) -> Zeitwerk::Loader?
+    def loader_for(mod, cname)
+      @loaders.delete_mod_cname(mod, cname)
+    end
 
-      # This is an internal method only used by the test suite.
-      #
-      # @sig (Symbol | String) -> Zeitwerk::Loader?
-      internal def registered?(cref)
-        @loaders[cref]
-      end
+    #: (Zeitwerk::Loader) -> void
+    def unregister_loader(loader)
+      @loaders.delete_by_value(loader)
+    end
 
-      # This is an internal method only used by the test suite.
-      #
-      # @sig () -> void
-      internal def clear
-        @loaders.clear
-      end
+    # This is an internal method only used by the test suite.
+    #
+    #: (Zeitwerk::Cref) -> Zeitwerk::Loader?
+    def registered?(cref)
+      @loaders[cref]
+    end
+
+    #: () -> void
+    def clear # for tests
+      @loaders.clear
     end
   end
 end

data/lib/zeitwerk/registry/inceptions.rb

@@ -2,30 +2,30 @@ module Zeitwerk::Registry
   # Loaders know their own inceptions, but there is a use case in which we need
   # to know if a given cpath is an inception globally. This is what this
   # registry is for.
-  module Inceptions # :nodoc: all
-    # @sig Zeitwerk::Cref::Map[String]
-    @inceptions = Zeitwerk::Cref::Map.new
+  class Inceptions # :nodoc:
+    #: () -> void
+    def initialize
+      @inceptions = Zeitwerk::Cref::Map.new #: Zeitwerk::Cref::Map[String]
+    end
 
-    class << self
-      # @sig (Zeitwerk::Cref, String) -> void
-      def register(cref, autoload_path)
-        @inceptions[cref] = autoload_path
-      end
+    #: (Zeitwerk::Cref, String) -> void
+    def register(cref, abspath)
+      @inceptions[cref] = abspath
+    end
 
-      # @sig (String) -> String?
-      def registered?(cref)
-        @inceptions[cref]
-      end
+    #: (Zeitwerk::Cref) -> String?
+    def registered?(cref)
+      @inceptions[cref]
+    end
 
-      # @sig (String) -> void
-      def unregister(cref)
-        @inceptions.delete(cref)
-      end
+    #: (Zeitwerk::Cref) -> void
+    def unregister(cref)
+      @inceptions.delete(cref)
+    end
 
-      # @sig () -> void
-      def clear # for tests
-        @inceptions.clear
-      end
+    #: () -> void
+    def clear # for tests
+      @inceptions.clear
     end
   end
 end

data/lib/zeitwerk/registry/loaders.rb

@@ -0,0 +1,33 @@
+module Zeitwerk::Registry
+  class Loaders # :nodoc:
+    #: () -> void
+    def initialize
+      @loaders = [] #: Array[Zeitwerk::Loader]
+    end
+
+    #: ({ (Zeitwerk::Loader) -> void }) -> void
+    def each(&block)
+      @loaders.each(&block)
+    end
+
+    #: (Zeitwerk::Loader) -> void
+    def register(loader)
+      @loaders << loader
+    end
+
+    #: (Zeitwerk::Loader) -> Zeitwerk::Loader?
+    def unregister(loader)
+      @loaders.delete(loader)
+    end
+
+    #: (Zeitwerk::Loader) -> bool
+    def registered?(loader) # for tests
+      @loaders.include?(loader)
+    end
+
+    #: () -> void
+    def clear # for tests
+      @loaders.clear
+    end
+  end
+end