zeitwerk 2.6.15 → 2.6.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8177bcca0fd5895bbe28b19dc5fd04a810e2905f21f33924786a33a317c96207
-  data.tar.gz: 7e441521285fe28230dadfb4c5c9d40564e376dd651ddae043190c5fdd3ee526
+  metadata.gz: 51e7aed4aef39ce0a2caaea2f23852ea4f2e8fcb7b65819d14a4d92e7aec70d0
+  data.tar.gz: 7e310bac85d85018cb840339a42958b9fbc6fac566fee51e6a5c599a3cb132e3
 SHA512:
-  metadata.gz: 57e0e401c952a13d1b96a8993bbee930132f2b63252ff7cd6646ceeeb5a3de886d1c36a8cdbc06e9add3e16e76bacd08cc8e32b58289fa01e9eabea4dad25581
-  data.tar.gz: e56116c8325ab38f751b8497f8270544543e950f92624c755b5d3d7bb296b48ce4afa668e1b4daae546561ddfa344fd9c650c7114c9cd2c637a514f0ebd38c98
+  metadata.gz: 0274e4685362f6585b9fb90291561926c8b45434ea3df71858ed99c5dfbffd54e814ed6dfcc4c6e8bfd8a9f266dbe4261bf6010856558474ad7e85045851e4cd
+  data.tar.gz: 210f457fad164472582fc67264bed2bd981612588bd3a8cdce265b2f2c67b12d10d9d2b9abb555dead008df20d5a73955072e703305e8f55b9d4dd5877d9b693

data/README.md

@@ -1065,7 +1065,7 @@ However, sometimes it might still be convenient to tell Zeitwerk to completely i
 
 You can ignore file names, directory names, and glob patterns. Glob patterns are expanded when they are added and again on each reload.
 
-There is an edge case related to nested root directories. Conceptually, root directories are independent source trees. If you ignore a parent of a nested root directory, the nested root directory is not affected. You need to ignore it explictly if you want it ignored too.
+There is an edge case related to nested root directories. Conceptually, root directories are independent source trees. If you ignore a parent of a nested root directory, the nested root directory is not affected. You need to ignore it explicitly if you want it ignored too.
 
 Let's see some use cases.
 

data/lib/zeitwerk/cref.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# This private class encapsulates pairs (mod, cname).
+#
+# Objects represent the constant cname in the class or module object mod, and
+# have API to manage them that encapsulates the constants API. Examples:
+#
+#   cref.path
+#   cref.set(value)
+#   cref.get
+#
+# The constant may or may not exist in mod.
+class Zeitwerk::Cref
+  include Zeitwerk::RealModName
+
+  # @sig Symbol
+  attr_reader :cname
+
+  # The type of the first argument is Module because Class < Module, class
+  # objects are also valid.
+  #
+  # @sig (Module, Symbol) -> void
+  def initialize(mod, cname)
+    @mod   = mod
+    @cname = cname
+    @path  = nil
+  end
+
+  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.
+    #
+    # @sig () -> String
+    def path
+      @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}"
+    end
+  else
+    # @sig () -> String
+    def path
+      @path ||= Object.equal?(@mod) ? @cname.to_s : "#{real_mod_name(@mod)}::#{@cname}"
+    end
+  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 retrieve it ignoring ancestors.
+  #
+  # @sig () -> String?
+  if method(:autoload?).arity == 1
+    # @sig () -> String?
+    def autoload?
+      @mod.autoload?(@cname) if self.defined?
+    end
+  else
+    # @sig () -> String?
+    def autoload?
+      @mod.autoload?(@cname, false)
+    end
+  end
+
+  # @sig (String) -> bool
+  def autoload(abspath)
+    @mod.autoload(@cname, abspath)
+  end
+
+  # @sig () -> bool
+  def defined?
+    @mod.const_defined?(@cname, false)
+  end
+
+  # @sig (Object) -> Object
+  def set(value)
+    @mod.const_set(@cname, value)
+  end
+
+  # @raise [NameError]
+  # @sig () -> Object
+  def get
+    @mod.const_get(@cname, false)
+  end
+
+  # @raise [NameError]
+  # @sig () -> void
+  def remove
+    @mod.__send__(:remove_const, @cname)
+  end
+end

data/lib/zeitwerk/loader/callbacks.rb

@@ -8,29 +8,28 @@ module Zeitwerk::Loader::Callbacks
   #
   # @sig (String) -> void
   internal def on_file_autoloaded(file)
-    cref  = autoloads.delete(file)
-    cpath = cpath(*cref)
+    cref = autoloads.delete(file)
 
     Zeitwerk::Registry.unregister_autoload(file)
 
-    if cdef?(*cref)
-      log("constant #{cpath} loaded from file #{file}") if logger
-      to_unload[cpath] = [file, cref] if reloading_enabled?
-      run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
+    if cref.defined?
+      log("constant #{cref.path} loaded from file #{file}") if logger
+      to_unload[cref.path] = [file, cref] if reloading_enabled?
+      run_on_load_callbacks(cref.path, cref.get, file) unless on_load_callbacks.empty?
     else
-      msg = "expected file #{file} to define constant #{cpath}, but didn't"
+      msg = "expected file #{file} to define constant #{cref.path}, but didn't"
       log(msg) if logger
 
       # Ruby still keeps the autoload defined, but we remove it because the
       # contract in Zeitwerk is more strict.
-      crem(*cref)
+      cref.remove
 
       # Since the expected constant was not defined, there is nothing to unload.
       # However, if the exception is rescued and reloading is enabled, we still
       # need to deleted the file from $LOADED_FEATURES.
-      to_unload[cpath] = [file, cref] if reloading_enabled?
+      to_unload[cref.path] = [file, cref] if reloading_enabled?
 
-      raise Zeitwerk::NameError.new(msg, cref.last)
+      raise Zeitwerk::NameError.new(msg, cref.cname)
     end
   end
 
@@ -53,8 +52,8 @@ module Zeitwerk::Loader::Callbacks
     # children, since t1 would have correctly deleted its namespace_dirs entry.
     dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
-        autovivified_module = cref[0].const_set(cref[1], Module.new)
-        cpath = autovivified_module.name
+        implicit_namespace = cref.set(Module.new)
+        cpath = implicit_namespace.name
         log("module #{cpath} autovivified from directory #{dir}") if logger
 
         to_unload[cpath] = [dir, cref] if reloading_enabled?
@@ -65,9 +64,9 @@ module Zeitwerk::Loader::Callbacks
         # these to be able to unregister later if eager loading.
         autoloaded_dirs << dir
 
-        on_namespace_loaded(autovivified_module)
+        on_namespace_loaded(implicit_namespace)
 
-        run_on_load_callbacks(cpath, autovivified_module, dir) unless on_load_callbacks.empty?
+        run_on_load_callbacks(cpath, implicit_namespace, dir) unless on_load_callbacks.empty?
       end
     end
   end

data/lib/zeitwerk/loader/eager_load.rb

@@ -61,8 +61,8 @@ module Zeitwerk::Loader::EagerLoad
     cnames.reverse_each do |cname|
       # Can happen if there are no Ruby files. This is not an error condition,
       # the directory is actually managed. Could have Ruby files later.
-      return unless cdef?(namespace, cname)
-      namespace = cget(namespace, cname)
+      return unless namespace.const_defined?(cname, false)
+      namespace = namespace.const_get(cname, false)
     end
 
     # A shortcircuiting test depends on the invocation of this method. Please
@@ -145,12 +145,12 @@ module Zeitwerk::Loader::EagerLoad
 
     namespace = root_namespace
     cnames.reverse_each do |cname|
-      namespace = cget(namespace, cname)
+      namespace = namespace.const_get(cname, false)
     end
 
     raise Zeitwerk::Error.new("#{abspath} is shadowed") if shadowed_file?(abspath)
 
-    cget(namespace, base_cname)
+    namespace.const_get(base_cname, false)
   end
 
   # The caller is responsible for making sure `namespace` is the namespace that
@@ -164,22 +164,20 @@ module Zeitwerk::Loader::EagerLoad
     log("eager load directory #{dir} start") if logger
 
     queue = [[dir, namespace]]
-    until queue.empty?
-      dir, namespace = queue.shift
-
-      ls(dir) do |basename, abspath, ftype|
+    while (current_dir, namespace = queue.shift)
+      ls(current_dir) do |basename, abspath, ftype|
         next if honour_exclusions && eager_load_exclusions.member?(abspath)
 
         if ftype == :file
           if (cref = autoloads[abspath])
-            cget(*cref)
+            cref.get
           end
         else
           if collapse?(abspath)
             queue << [abspath, namespace]
           else
             cname = inflector.camelize(basename, abspath).to_sym
-            queue << [abspath, cget(namespace, cname)]
+            queue << [abspath, namespace.const_get(cname, false)]
           end
         end
       end

data/lib/zeitwerk/loader/helpers.rb

@@ -30,7 +30,12 @@ module Zeitwerk::Loader::Helpers
 
       if dir?(abspath)
         next if roots.key?(abspath)
-        next if !has_at_least_one_ruby_file?(abspath)
+
+        if !has_at_least_one_ruby_file?(abspath)
+          log("directory #{abspath} is ignored because it has no Ruby files") if logger
+          next
+        end
+
         ftype = :directory
       else
         next unless ruby?(abspath)
@@ -95,64 +100,7 @@ module Zeitwerk::Loader::Helpers
     end
   end
 
-  # --- Constants ---------------------------------------------------------------------------------
-
-  # 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
-    private def strict_autoload_path(parent, cname)
-      parent.autoload?(cname) if cdef?(parent, cname)
-    end
-  else
-    private def strict_autoload_path(parent, cname)
-      parent.autoload?(cname, false)
-    end
-  end
-
-  # @sig (Module, Symbol) -> String
-  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.
-    private def cpath(parent, cname)
-      Object == parent ? cname.name : "#{real_mod_name(parent)}::#{cname.name}"
-    end
-  else
-    private def cpath(parent, cname)
-      Object == parent ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
-    end
-  end
-
-  # @sig (Module, Symbol) -> bool
-  private def cdef?(parent, cname)
-    parent.const_defined?(cname, false)
-  end
-
-  # @raise [NameError]
-  # @sig (Module, Symbol) -> Object
-  private def cget(parent, cname)
-    parent.const_get(cname, false)
-  end
-
-  # @raise [NameError]
-  # @sig (Module, Symbol) -> Object
-  private def crem(parent, cname)
-    parent.__send__(:remove_const, cname)
-  end
+  # --- Inflection --------------------------------------------------------------------------------
 
   CNAME_VALIDATOR = Module.new
   private_constant :CNAME_VALIDATOR

data/lib/zeitwerk/loader.rb

@@ -22,14 +22,13 @@ module Zeitwerk
     private_constant :MUTEX
 
     # Maps absolute paths for which an autoload has been set ---and not
-    # executed--- to their corresponding parent class or module and constant
-    # name.
+    # executed--- to their corresponding Zeitwerk::Cref object.
     #
-    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
-    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
+    #   "/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, ...>,
     #   ...
     #
-    # @sig Hash[String, [Module, Symbol]]
+    # @sig Hash[String, Zeitwerk::Cref]
     attr_reader :autoloads
     internal :autoloads
 
@@ -45,17 +44,19 @@ module Zeitwerk
 
     # Stores metadata needed for unloading. Its entries look like this:
     #
-    #   "Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
+    #   "Admin::Role" => [
+    #     ".../admin/role.rb",
+    #     #<Zeitwerk::Cref:... @mod=Admin, @cname=:Role, ...>
+    #   ]
     #
     # 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.
+    # cref is used to remove the constant from the parent class or module.
     #
     # If reloading is enabled, this hash is filled as constants are autoloaded
     # or eager loaded. Otherwise, the collection remains empty.
     #
-    # @sig Hash[String, [String, [Module, Symbol]]]
+    # @sig Hash[String, [String, Zeitwerk::Cref]]
     attr_reader :to_unload
     internal :to_unload
 
@@ -154,22 +155,22 @@ module Zeitwerk
         # is enough.
         unloaded_files = Set.new
 
-        autoloads.each do |abspath, (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(parent, cname)
+            unload_cref(cref)
             unloaded_files.add(abspath) if ruby?(abspath)
           end
         end
 
-        to_unload.each do |cpath, (abspath, (parent, cname))|
+        to_unload.each do |cpath, (abspath, cref)|
           unless on_unload_callbacks.empty?
             begin
-              value = cget(parent, cname)
+              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
@@ -179,7 +180,7 @@ module Zeitwerk
             end
           end
 
-          unload_cref(parent, cname)
+          unload_cref(cref)
           unloaded_files.add(abspath) if ruby?(abspath)
         end
 
@@ -240,8 +241,7 @@ module Zeitwerk
       actual_roots.each do |root_dir, root_namespace|
         queue = [[root_dir, real_mod_name(root_namespace)]]
 
-        until queue.empty?
-          dir, cpath = queue.shift
+        while (dir, cpath = queue.shift)
           result[dir] = cpath
 
           prefix = cpath == "Object" ? "" : cpath + "::"
@@ -445,21 +445,22 @@ module Zeitwerk
       ls(dir) do |basename, abspath, ftype|
         if ftype == :file
           basename.delete_suffix!(".rb")
-          autoload_file(parent, cname_for(basename, abspath), abspath)
+          cref = Cref.new(parent, cname_for(basename, abspath))
+          autoload_file(cref, abspath)
         else
           if collapse?(abspath)
             define_autoloads_for_dir(abspath, parent)
           else
-            autoload_subdir(parent, cname_for(basename, abspath), abspath)
+            cref = Cref.new(parent, cname_for(basename, abspath))
+            autoload_subdir(cref, abspath)
           end
         end
       end
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def autoload_subdir(parent, cname, subdir)
-      if autoload_path = autoload_path_set_by_me_for?(parent, cname)
-        cpath = cpath(parent, cname)
+    private def autoload_subdir(cref, subdir)
+      if autoload_path = autoload_path_set_by_me_for?(cref)
         if ruby?(autoload_path)
           # Scanning visited a Ruby file first, and now a directory for the same
           # constant has been found. This means we are dealing with an explicit
@@ -468,88 +469,83 @@ module Zeitwerk
           # Registering is idempotent, and we have to keep the autoload pointing
           # to the file. This may run again if more directories are found later
           # on, no big deal.
-          register_explicit_namespace(cpath)
+          register_explicit_namespace(cref.path)
         end
         # If the existing autoload points to a file, it has to be preserved, if
         # not, it is fine as it is. In either case, we do not need to override.
         # Just remember the subdirectory conforms this namespace.
-        namespace_dirs[cpath] << subdir
-      elsif !cdef?(parent, cname)
+        namespace_dirs[cref.path] << subdir
+      elsif !cref.defined?
         # First time we find this namespace, set an autoload for it.
-        namespace_dirs[cpath(parent, cname)] << subdir
-        define_autoload(parent, cname, subdir)
+        namespace_dirs[cref.path] << subdir
+        define_autoload(cref, subdir)
       else
         # For whatever reason the constant that corresponds to this namespace has
         # already been defined, we have to recurse.
-        log("the namespace #{cpath(parent, cname)} already exists, descending into #{subdir}") if logger
-        define_autoloads_for_dir(subdir, cget(parent, cname))
+        log("the namespace #{cref.path} already exists, descending into #{subdir}") if logger
+        define_autoloads_for_dir(subdir, cref.get)
       end
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def autoload_file(parent, cname, file)
-      if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
+    private def autoload_file(cref, file)
+      if autoload_path = cref.autoload? || Registry.inception?(cref.path)
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
           shadowed_files << file
           log("file #{file} is ignored because #{autoload_path} has precedence") if logger
         else
-          promote_namespace_from_implicit_to_explicit(
-            dir:    autoload_path,
-            file:   file,
-            parent: parent,
-            cname:  cname
-          )
+          promote_namespace_from_implicit_to_explicit(dir: autoload_path, file: file, cref: cref)
         end
-      elsif cdef?(parent, cname)
+      elsif cref.defined?
         shadowed_files << file
-        log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
+        log("file #{file} is ignored because #{cref.path} is already defined") if logger
       else
-        define_autoload(parent, cname, file)
+        define_autoload(cref, file)
       end
     end
 
     # `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, parent: Module, cname: Symbol) -> void
-    private def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
+    # @sig (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)
 
-      log("earlier autoload for #{cpath(parent, cname)} discarded, it is actually an explicit namespace defined in #{file}") if logger
+      log("earlier autoload for #{cref.path} discarded, it is actually an explicit namespace defined in #{file}") if logger
 
-      define_autoload(parent, cname, file)
-      register_explicit_namespace(cpath(parent, cname))
+      define_autoload(cref, file)
+      register_explicit_namespace(cref.path)
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def define_autoload(parent, cname, abspath)
-      parent.autoload(cname, abspath)
+    private def define_autoload(cref, abspath)
+      cref.autoload(abspath)
 
       if logger
         if ruby?(abspath)
-          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{abspath}")
+          log("autoload set for #{cref.path}, to be loaded from #{abspath}")
         else
-          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{abspath}")
+          log("autoload set for #{cref.path}, to be autovivified from #{abspath}")
         end
       end
 
-      autoloads[abspath] = [parent, cname]
+      autoloads[abspath] = cref
       Registry.register_autoload(self, abspath)
 
       # See why in the documentation of Zeitwerk::Registry.inceptions.
-      unless parent.autoload?(cname)
-        Registry.register_inception(cpath(parent, cname), abspath, self)
+      unless cref.autoload?
+        Registry.register_inception(cref.path, abspath, self)
       end
     end
 
     # @sig (Module, Symbol) -> String?
-    private def autoload_path_set_by_me_for?(parent, cname)
-      if autoload_path = strict_autoload_path(parent, cname)
+    private def autoload_path_set_by_me_for?(cref)
+      if autoload_path = cref.autoload?
         autoload_path if autoloads.key?(autoload_path)
       else
-        Registry.inception?(cpath(parent, cname))
+        Registry.inception?(cref.path)
       end
     end
 
@@ -590,21 +586,21 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol) -> void
-    private def unload_autoload(parent, cname)
-      crem(parent, cname)
-      log("autoload for #{cpath(parent, cname)} removed") if logger
+    private def unload_autoload(cref)
+      cref.remove
+      log("autoload for #{cref.path} removed") if logger
     end
 
     # @sig (Module, Symbol) -> void
-    private def unload_cref(parent, cname)
+    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.
-      crem(parent, cname)
+      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("#{cpath(parent, cname)} unloaded") if logger
+      log("#{cref.path} unloaded") if logger
     end
   end
 end

data/lib/zeitwerk/version.rb

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

data/lib/zeitwerk.rb

@@ -3,6 +3,7 @@
 module Zeitwerk
   require_relative "zeitwerk/real_mod_name"
   require_relative "zeitwerk/internal"
+  require_relative "zeitwerk/cref"
   require_relative "zeitwerk/loader"
   require_relative "zeitwerk/gem_loader"
   require_relative "zeitwerk/registry"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.15
+  version: 2.6.17
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-26 00:00:00.000000000 Z
+date: 2024-07-29 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -23,6 +23,7 @@ files:
 - MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
+- lib/zeitwerk/cref.rb
 - lib/zeitwerk/error.rb
 - lib/zeitwerk/explicit_namespace.rb
 - lib/zeitwerk/gem_inflector.rb
@@ -62,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
+rubygems_version: 3.5.15
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader