zeitwerk 2.6.4 → 2.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c7bbcbb7fa03b5ef6389335805145cabf2a4fdd203c15b3c6ecdf68f229e499
-  data.tar.gz: 3581c99a8d4431eeeed3b6139aca5363f9c13d136dddb22aa5c88b55d2ff2dac
+  metadata.gz: 6811a58f4992b66a3625b1b931f070463619e806c0e044611df1f706a0cb1477
+  data.tar.gz: 07dd0a9133025560ad914dca656d0ed1044cc791d6e09586dbd03c0a72929751
 SHA512:
-  metadata.gz: 3575d2cd414fe45f4c42ce286fbf9cbf648ed0cf5c3643db82167023adde590058cbe88c2348fe2c9f6f8d56f04858ef49441115544dca88b18b48f2eb36d886
-  data.tar.gz: 4d9fc1a1c72df9233e742f22ad2a0bd636301e55cd9078e856cdfb9a8b2727345d86f278e592fb0294959e9aad92895619e69133050afa943192a61477bad64d
+  metadata.gz: 0a360aad989a229b0a315d6d38690401f18ef55b45e8ae30e05db81eb85f9954f8ec1e4fa738b774175c06736f44bcecf2dcfbca74b7d79a049d59071489a7b9
+  data.tar.gz: 851ecb2490e716aac571f140f51bedbaf1f1eb99761d1c98a9afe1982099bddc9455efedcd243ff770b7d08c616dd48efce20a7e2378e41ef2844e197cc085f2

data/README.md

@@ -213,7 +213,7 @@ serializers/user_serializer.rb -> UserSerializer
 <a id="markdown-custom-root-namespaces" name="custom-root-namespaces"></a>
 #### Custom root namespaces
 
-While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a class or module object in the optional `namespace` keyword argument.
+While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a non-anonymous class or module object in the optional `namespace` keyword argument.
 
 For example, given:
 
@@ -449,6 +449,8 @@ In gems, the method needs to be invoked after the main namespace has been define
 
 Eager loading is synchronized and idempotent.
 
+Attempting to eager load without previously calling `setup` raises `Zeitwerk::SetupRequired`.
+
 <a id="markdown-eager-load-exclusions" name="eager-load-exclusions"></a>
 #### Eager load exclusions
 
@@ -492,6 +494,8 @@ The method checks if a regular eager load was already executed, in which case it
 
 Nested root directories which are descendants of the argument are skipped. Those subtrees are considered to be conceptually apart.
 
+Attempting to eager load a directory without previously calling `setup` raises `Zeitwerk::SetupRequired`.
+
 <a id="markdown-eager-load-namespaces" name="eager-load-namespaces"></a>
 #### Eager load namespaces
 
@@ -527,6 +531,8 @@ The method checks if a regular eager load was already executed, in which case it
 
 If root directories are assigned to custom namespaces, the method behaves as you'd expect, according to the namespacing relationship between the custom namespace and the argument.
 
+Attempting to eager load a namespace without previously calling `setup` raises `Zeitwerk::SetupRequired`.
+
 <a id="markdown-eager-load-namespaces-shared-by-several-loaders" name="eager-load-namespaces-shared-by-several-loaders"></a>
 #### Eager load namespaces shared by several loaders
 
@@ -540,6 +546,8 @@ This may be handy, for example, if a framework supports plugins and a shared nam
 
 Please, note that loaders only eager load namespaces they manage, as documented above. Therefore, this method does not allow you to eager load namespaces not managed by Zeitwerk loaders.
 
+This method does not require that all registered loaders have `setup` already invoked, since that is out of your control. If there's any in that state, it is simply skipped.
+
 <a id="markdown-global-eager-load" name="global-eager-load"></a>
 #### Global eager load
 
@@ -555,6 +563,8 @@ Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager lo
 
 This method does not accept the `force` flag, since in general it wouldn't be a good idea to force eager loading in 3rd party code.
 
+This method does not require that all registered loaders have `setup` already invoked, since that is out of your control. If there's any in that state, it is simply skipped.
+
 <a id="markdown-loading-individual-files" name="loading-individual-files"></a>
 ### Loading individual files
 
@@ -591,7 +601,7 @@ loader.reload
 
 There is no way to undo this, either you want to reload or you don't.
 
-Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`.
+Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`. Attempting to reload without previously calling `setup` raises `Zeitwerk::SetupRequired`.
 
 Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, or services running in testing or production environments, won't normally have a use case for reloading. If reloading is not enabled, Zeitwerk is able to use less memory.
 

data/lib/zeitwerk/error.rb

@@ -12,4 +12,10 @@ module Zeitwerk
 
   class NameError < ::NameError
   end
+
+  class SetupRequired < Error
+    def initialize
+      super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
+    end
+  end
 end

data/lib/zeitwerk/explicit_namespace.rb

@@ -11,28 +11,28 @@ module Zeitwerk
   module ExplicitNamespace # :nodoc: all
     class << self
       include RealModName
+      extend Internal
 
       # Maps constant paths that correspond to explicit namespaces according to
       # the file system, to the loader responsible for them.
       #
-      # @private
       # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :cpaths
+      private :cpaths
 
-      # @private
       # @sig Mutex
       attr_reader :mutex
+      private :mutex
 
-      # @private
       # @sig TracePoint
       attr_reader :tracer
+      private :tracer
 
       # Asserts `cpath` corresponds to an explicit namespace for which `loader`
       # is responsible.
       #
-      # @private
       # @sig (String, Zeitwerk::Loader) -> void
-      def register(cpath, loader)
+      internal def register(cpath, loader)
         mutex.synchronize do
           cpaths[cpath] = loader
           # We check enabled? because, looking at the C source code, enabling an
@@ -41,24 +41,21 @@ module Zeitwerk
         end
       end
 
-      # @private
       # @sig (Zeitwerk::Loader) -> void
-      def unregister_loader(loader)
+      internal def unregister_loader(loader)
         cpaths.delete_if { |_cpath, l| l == loader }
         disable_tracer_if_unneeded
       end
 
-      private
-
       # @sig () -> void
-      def disable_tracer_if_unneeded
+      private def disable_tracer_if_unneeded
         mutex.synchronize do
           tracer.disable if cpaths.empty?
         end
       end
 
       # @sig (TracePoint) -> void
-      def tracepoint_class_callback(event)
+      private def tracepoint_class_callback(event)
         # If the class is a singleton class, we won't do anything with it so we
         # can bail out immediately. This is several orders of magnitude faster
         # than accessing its name.

data/lib/zeitwerk/loader/config.rb

@@ -5,6 +5,7 @@ require "securerandom"
 
 module Zeitwerk::Loader::Config
   extend Zeitwerk::Internal
+  include Zeitwerk::RealModName
 
   # @sig #camelize
   attr_accessor :inflector
@@ -12,14 +13,15 @@ module Zeitwerk::Loader::Config
   # @sig #call | #debug | nil
   attr_accessor :logger
 
-  # Absolute paths of the root directories. Stored in a hash to preserve order,
-  # easily handle duplicates, have a fast lookup needed for detecting nested
-  # paths, and store namespaces as values.
+  # Absolute paths of the root directories, mapped to their respective root namespaces:
   #
   #   "/Users/fxn/blog/app/channels" => Object,
   #   "/Users/fxn/blog/app/adapters" => ActiveJob::QueueAdapters,
   #   ...
   #
+  # Stored in a hash to preserve order, easily handle duplicates, and have a
+  # fast lookup by directory.
+  #
   # This is a private collection maintained by the loader. The public
   # interface for it is `push_dir` and `dirs`.
   #
@@ -112,6 +114,10 @@ module Zeitwerk::Loader::Config
       raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
     end
 
+    unless real_mod_name(namespace)
+      raise Zeitwerk::Error, "root namespaces cannot be anonymous"
+    end
+
     abspath = File.expand_path(path)
     if dir?(abspath)
       raise_if_conflicting_directory(abspath)
@@ -283,17 +289,22 @@ module Zeitwerk::Loader::Config
     return false if ignored_paths.empty?
 
     walk_up(abspath) do |abspath|
-      return true  if ignored_paths.member?(abspath)
+      return true  if ignored_path?(abspath)
       return false if roots.key?(abspath)
     end
 
     false
   end
 
+  # @sig (String) -> bool
+  private def ignored_path?(abspath)
+    ignored_paths.member?(abspath)
+  end
+
   # @sig () -> Array[String]
   private def actual_roots
     roots.reject do |root_dir, _root_namespace|
-      !dir?(root_dir) || ignored_paths.member?(root_dir)
+      !dir?(root_dir) || ignored_path?(root_dir)
     end
   end
 

data/lib/zeitwerk/loader/eager_load.rb

@@ -9,6 +9,7 @@ module Zeitwerk::Loader::EagerLoad
   def eager_load(force: false)
     mutex.synchronize do
       break if @eager_loaded
+      raise Zeitwerk::SetupRequired unless @setup
 
       log("eager load start") if logger
 
@@ -29,6 +30,8 @@ module Zeitwerk::Loader::EagerLoad
 
   # @sig (String | Pathname) -> void
   def eager_load_dir(path)
+    raise Zeitwerk::SetupRequired unless @setup
+
     abspath = File.expand_path(path)
 
     raise Zeitwerk::Error.new("#{abspath} is not a directory") unless dir?(abspath)
@@ -37,7 +40,7 @@ module Zeitwerk::Loader::EagerLoad
 
     root_namespace = nil
     walk_up(abspath) do |dir|
-      return if ignored_paths.member?(dir)
+      return if ignored_path?(dir)
       return if eager_load_exclusions.member?(dir)
 
       break if root_namespace = roots[dir]
@@ -67,6 +70,8 @@ module Zeitwerk::Loader::EagerLoad
 
   # @sig (Module) -> void
   def eager_load_namespace(mod)
+    raise Zeitwerk::SetupRequired unless @setup
+
     unless mod.is_a?(Module)
       raise Zeitwerk::Error, "#{mod.inspect} is not a class or module object"
     end
@@ -111,7 +116,7 @@ module Zeitwerk::Loader::EagerLoad
 
     raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
     raise Zeitwerk::Error.new("#{abspath} is not a Ruby file") if dir?(abspath) || !ruby?(abspath)
-    raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_paths.member?(abspath)
+    raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
 
     basename = File.basename(abspath, ".rb")
     base_cname = inflector.camelize(basename, abspath).to_sym
@@ -120,7 +125,7 @@ module Zeitwerk::Loader::EagerLoad
     cnames = []
 
     walk_up(File.dirname(abspath)) do |dir|
-      raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_paths.member?(dir)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(dir)
 
       break if root_namespace = roots[dir]
 

data/lib/zeitwerk/loader/helpers.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
 module Zeitwerk::Loader::Helpers
-  private
-
   # --- Logging -----------------------------------------------------------------------------------
 
   # @sig (String) -> void
-  def log(message)
+  private def log(message)
     method_name = logger.respond_to?(:debug) ? :debug : :call
     logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
   end
@@ -14,7 +12,7 @@ module Zeitwerk::Loader::Helpers
   # --- Files and directories ---------------------------------------------------------------------
 
   # @sig (String) { (String, String) -> void } -> void
-  def ls(dir)
+  private def ls(dir)
     children = Dir.children(dir)
 
     # The order in which a directory is listed depends on the file system.
@@ -28,7 +26,7 @@ module Zeitwerk::Loader::Helpers
       next if hidden?(basename)
 
       abspath = File.join(dir, basename)
-      next if ignored_paths.member?(abspath)
+      next if ignored_path?(abspath)
 
       if dir?(abspath)
         next if roots.key?(abspath)
@@ -44,7 +42,7 @@ module Zeitwerk::Loader::Helpers
   end
 
   # @sig (String) -> bool
-  def has_at_least_one_ruby_file?(dir)
+  private def has_at_least_one_ruby_file?(dir)
     to_visit = [dir]
 
     while dir = to_visit.shift
@@ -61,22 +59,22 @@ module Zeitwerk::Loader::Helpers
   end
 
   # @sig (String) -> bool
-  def ruby?(path)
+  private def ruby?(path)
     path.end_with?(".rb")
   end
 
   # @sig (String) -> bool
-  def dir?(path)
+  private def dir?(path)
     File.directory?(path)
   end
 
   # @sig (String) -> bool
-  def hidden?(basename)
+  private def hidden?(basename)
     basename.start_with?(".")
   end
 
   # @sig (String) { (String) -> void } -> void
-  def walk_up(abspath)
+  private def walk_up(abspath)
     loop do
       yield abspath
       abspath, basename = File.split(abspath)
@@ -104,11 +102,11 @@ module Zeitwerk::Loader::Helpers
   #
   # @sig (Module, Symbol) -> String?
   if method(:autoload?).arity == 1
-    def strict_autoload_path(parent, cname)
+    private def strict_autoload_path(parent, cname)
       parent.autoload?(cname) if cdef?(parent, cname)
     end
   else
-    def strict_autoload_path(parent, cname)
+    private def strict_autoload_path(parent, cname)
       parent.autoload?(cname, false)
     end
   end
@@ -117,23 +115,23 @@ module Zeitwerk::Loader::Helpers
   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)
+    private def cpath(parent, cname)
       Object == parent ? cname.name : "#{real_mod_name(parent)}::#{cname.name}"
     end
   else
-    def cpath(parent, cname)
+    private def cpath(parent, cname)
       Object == parent ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
     end
   end
 
   # @sig (Module, Symbol) -> bool
-  def cdef?(parent, cname)
+  private def cdef?(parent, cname)
     parent.const_defined?(cname, false)
   end
 
   # @raise [NameError]
   # @sig (Module, Symbol) -> Object
-  def cget(parent, cname)
+  private def cget(parent, cname)
     parent.const_get(cname, false)
   end
 end

data/lib/zeitwerk/loader.rb

@@ -109,7 +109,7 @@ module Zeitwerk
       Registry.register_loader(self)
     end
 
-    # Sets autoloads in the root namespace.
+    # Sets autoloads in the root namespaces.
     #
     # @sig () -> void
     def setup
@@ -140,6 +140,8 @@ module Zeitwerk
     # @sig () -> void
     def unload
       mutex.synchronize do
+        raise SetupRequired unless @setup
+
         # 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.
@@ -199,7 +201,7 @@ module Zeitwerk
         shadowed_files.clear
 
         Registry.on_unload(self)
-        ExplicitNamespace.unregister_loader(self)
+        ExplicitNamespace.__unregister_loader(self)
 
         @setup        = false
         @eager_loaded = false
@@ -216,6 +218,7 @@ module Zeitwerk
     # @sig () -> void
     def reload
       raise ReloadingDisabledError unless reloading_enabled?
+      raise SetupRequired unless @setup
 
       unload
       recompute_ignored_paths
@@ -245,7 +248,7 @@ module Zeitwerk
     # @sig () -> void
     def unregister
       Registry.unregister_loader(self)
-      ExplicitNamespace.unregister_loader(self)
+      ExplicitNamespace.__unregister_loader(self)
     end
 
     # The return value of this predicate is only meaningful if the loader has
@@ -283,19 +286,31 @@ module Zeitwerk
         Registry.loader_for_gem(called_from, warn_on_extra_files: warn_on_extra_files)
       end
 
-      # Broadcasts `eager_load` to all loaders.
+      # Broadcasts `eager_load` to all loaders. Those that have not been setup
+      # are skipped.
       #
       # @sig () -> 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.
+      # Broadcasts `eager_load_namespace` to all loaders. Those that have not
+      # been setup are skipped.
       #
       # @sig (Module) -> void
       def eager_load_namespace(mod)
         Registry.loaders.each do |loader|
-          loader.eager_load_namespace(mod)
+          begin
+            loader.eager_load_namespace(mod)
+          rescue SetupRequired
+            # This is fine, we eager load what can be eager loaded.
+          end
         end
       end
 
@@ -435,7 +450,7 @@ module Zeitwerk
 
     # @sig (String) -> void
     def register_explicit_namespace(cpath)
-      ExplicitNamespace.register(cpath, self)
+      ExplicitNamespace.__register(cpath, self)
     end
 
     # @sig (String) -> void

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.6.4"
+  VERSION = "2.6.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.4
+  version: 2.6.5
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-01 00:00:00.000000000 Z
+date: 2022-11-05 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem