zeitwerk 2.7.0 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79a3e282ee7602f7d40c75c1299b24de4de890ee90a22cd37ed9c7a660936074
-  data.tar.gz: bd60115bc776137770e16ee527e4a07e815af547d1d5de851039e0187d50eff8
+  metadata.gz: aba46812169c8e26085b099c708093b00a29bfd39e8d8210d29bc99e7df0e7fa
+  data.tar.gz: 0fc20386009d52d21a0cb79a64c5d800f7aecfce5a38e8430a10dc5d04c2609d
 SHA512:
-  metadata.gz: ebdab4575a6e35591d1603ed11dc31f77eeffb15c8270f54719eb0850f3641efa968bebd8f02c32330ca768b8211d9aeb972fd41e0efac710faa023a0d62a841
-  data.tar.gz: 6d58d0256f35d6ac6445cba6619943aa4b3974905eb28588284f14aadd27304b1f11fc46d4f0905074c8888e52eabc03e312054930b702c875856d6c0a6a0694
+  metadata.gz: 3edac5ad6f940caa70c4cac093bf271b8399b078d7124f450513c963ec5099e9b9082841ceb9893b81f1edf8e34dc642ec811403415fb230211670c63a950766
+  data.tar.gz: 47339a8b35dc06108fde9aadd62e83b1ea4e4ef22854c31849069f09ece1115dce07d63ec354fe96fbc599bba411ecff48db6a8b0c8b150ad7ee016787e9d75c

data/README.md

@@ -281,6 +281,8 @@ class Hotel < ApplicationRecord
 end
 ```
 
+When autoloaded, Zeitwerk verifies the expected constant (`Hotel` in the example) stores a class or module object. If it doesn't, `Zeitwerk::Error` is raised.
+
 An explicit namespace must be managed by one single loader. Loaders that reopen namespaces owned by other projects are responsible for loading their constants before setup.
 
 <a id="markdown-collapsing-directories" name="collapsing-directories"></a>
@@ -1382,9 +1384,12 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 <a id="markdown-supported-ruby-versions" name="supported-ruby-versions"></a>
 ## Supported Ruby versions
 
-Zeitwerk works with CRuby 2.5 and above.
+Starting with version 2.7, Zeitwerk requires Ruby 3.2 or newer.
 
-On TruffleRuby all is good except for thread-safety. Right now, in TruffleRuby `Module#autoload` does not block threads accessing a constant that is being autoloaded. CRuby prevents such access to avoid concurrent threads from seeing partial evaluations of the corresponding file. Zeitwerk inherits autoloading thread-safety from this property. This is not an issue if your project gets eager loaded, or if you lazy load in single-threaded environments. (See https://github.com/oracle/truffleruby/issues/2431.)
+Zeitwerk 2.7 requires TruffleRuby 24.1.2+ due to https://github.com/oracle/truffleruby/issues/3683.
+Alternatively, TruffleRuby users can use a `< 2.7` version constraint for the `zeitwerk` gem.
+As of this writing, [autoloading is not fully thread-safe yet on TruffleRuby](https://github.com/oracle/truffleruby/issues/2431).
+If your program is multi-threaded, you need to eager load before threads are created.
 
 JRuby 9.3.0.0 is almost there. As of this writing, the test suite of Zeitwerk passes on JRuby except for three tests. (See https://github.com/jruby/jruby/issues/6781.)
 

data/lib/zeitwerk/core_ext/module.rb

@@ -3,7 +3,14 @@
 module Zeitwerk::ConstAdded
   def const_added(cname)
     if loader = Zeitwerk::ExplicitNamespace.__loader_for(self, cname)
-      loader.on_namespace_loaded(const_get(cname, false))
+      namespace = const_get(cname, false)
+
+      unless namespace.is_a?(Module)
+        cref = Zeitwerk::Cref.new(self, cname)
+        raise Zeitwerk::Error, "#{cref.path} is expected to be a namespace, should be a class or module (got #{namespace.class})"
+      end
+
+      loader.on_namespace_loaded(namespace)
     end
     super
   end

data/lib/zeitwerk/cref.rb

@@ -13,6 +13,9 @@
 class Zeitwerk::Cref
   include Zeitwerk::RealModName
 
+  # @sig Module
+  attr_reader :mod
+
   # @sig Symbol
   attr_reader :cname
 

data/lib/zeitwerk/explicit_namespace.rb

@@ -1,55 +1,84 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  # Centralizes the logic needed to descend into matching subdirectories right
-  # after the constant for an explicit namespace has been defined.
+  # This module is essentially 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.
+  #
+  # If the namespace is autoloaded, our const_added callback retrieves its
+  # loader by calling loader_for. That way, the loader is able to scan the
+  # subdirectories that conform the namespace and set autoloads for their
+  # expected constants just in time.
+  #
+  # Once autoloaded, the namespace is unregistered.
   #
   # 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 ExplicitNamespace # :nodoc: all
-    # Maps cpaths of explicit namespaces with their corresponding loader.
+    # Maps cnames or cpaths of explicit namespaces with their corresponding
+    # loader. They are symbols for top-level ones, and strings for nested ones:
+    #
+    #   {
+    #     :Admin => #<Zeitwerk::Loader:...>,
+    #     "Hotel::Pricing" => #<Zeitwerk::Loader:...>
+    #   }
+    #
+    # There are two types of keys to make loader_for as fast as possible, since
+    # it is invoked by our const_added for all autoloads and constant actually
+    # added. Globally. With this trick, for top-level constants we do not need
+    # to call Symbol#name and perform a string lookup. Instead, we can directly
+    # perform a fast symbol lookup.
+    #
     # Entries are added as the namespaces are found, and removed as they are
     # autoloaded.
     #
-    # @sig Hash[String => Zeitwerk::Loader]
-    @cpaths = {}
+    # @sig Hash[(Symbol | String) => Zeitwerk::Loader]
+    @loaders = {}
 
     class << self
       include RealModName
       extend Internal
 
-      # Registers `cpath` as being the constant path of an explicit namespace
+      # Registers `cref` as being the constant path of an explicit namespace
       # managed by `loader`.
       #
       # @sig (String, Zeitwerk::Loader) -> void
-      internal def register(cpath, loader)
-        @cpaths[cpath] = loader
+      internal def register(cref, loader)
+        if Object.equal?(cref.mod)
+          @loaders[cref.cname] = loader
+        else
+          @loaders[cref.path] = loader
+        end
       end
 
-      # @sig (String) -> Zeitwerk::Loader?
+      # @sig (Module, Symbol) -> Zeitwerk::Loader?
       internal def loader_for(mod, cname)
-        cpath = mod.equal?(Object) ? cname.name : "#{real_mod_name(mod)}::#{cname}"
-        @cpaths.delete(cpath)
+        if Object.equal?(mod)
+          @loaders.delete(cname)
+        else
+          @loaders.delete("#{real_mod_name(mod)}::#{cname}")
+        end
       end
 
       # @sig (Zeitwerk::Loader) -> void
       internal def unregister_loader(loader)
-        @cpaths.delete_if { _2.equal?(loader) }
+        @loaders.delete_if { _2.equal?(loader) }
       end
 
       # This is an internal method only used by the test suite.
       #
       # @sig (String) -> Zeitwerk::Loader?
-      internal def registered?(cpath)
-        @cpaths[cpath]
+      internal def registered?(cname_or_cpath)
+        @loaders[cname_or_cpath]
       end
 
       # This is an internal method only used by the test suite.
       #
       # @sig () -> void
       internal def clear
-        @cpaths.clear
+        @loaders.clear
       end
 
       module Synchronized

data/lib/zeitwerk/loader/eager_load.rb

@@ -84,7 +84,7 @@ module Zeitwerk::Loader::EagerLoad
     return unless mod_name
 
     actual_roots.each do |root_dir, root_namespace|
-      if mod.equal?(Object)
+      if Object.equal?(mod)
         # A shortcircuiting test depends on the invocation of this method.
         # Please keep them in sync if refactored.
         actual_eager_load_dir(root_dir, root_namespace)

data/lib/zeitwerk/loader.rb

@@ -553,7 +553,7 @@ module Zeitwerk
 
     # @sig (Zeitwerk::Cref) -> void
     private def register_explicit_namespace(cref)
-      ExplicitNamespace.__register(cref.path, self)
+      ExplicitNamespace.__register(cref, self)
     end
 
     # @sig (String) -> void

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.7.1
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2024-10-18 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -64,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader