zeitwerk 2.6.7 → 2.6.17

data/lib/zeitwerk/loader.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "monitor"
 require "set"
 
 module Zeitwerk
@@ -21,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
 
@@ -44,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
 
@@ -91,9 +93,9 @@ module Zeitwerk
     attr_reader :mutex
     private :mutex
 
-    # @sig Mutex
-    attr_reader :mutex2
-    private :mutex2
+    # @sig Monitor
+    attr_reader :dirs_autoload_monitor
+    private :dirs_autoload_monitor
 
     def initialize
       super
@@ -103,11 +105,12 @@ module Zeitwerk
       @to_unload       = {}
       @namespace_dirs  = Hash.new { |h, cpath| h[cpath] = [] }
       @shadowed_files  = Set.new
-      @mutex           = Mutex.new
-      @mutex2          = Mutex.new
       @setup           = false
       @eager_loaded    = false
 
+      @mutex = Mutex.new
+      @dirs_autoload_monitor = Monitor.new
+
       Registry.register_loader(self)
     end
 
@@ -119,7 +122,7 @@ module Zeitwerk
         break if @setup
 
         actual_roots.each do |root_dir, root_namespace|
-          set_autoloads_in_dir(root_dir, root_namespace)
+          define_autoloads_for_dir(root_dir, root_namespace)
         end
 
         on_setup_callbacks.each(&:call)
@@ -152,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
@@ -177,7 +180,7 @@ module Zeitwerk
             end
           end
 
-          unload_cref(parent, cname)
+          unload_cref(cref)
           unloaded_files.add(abspath) if ruby?(abspath)
         end
 
@@ -228,6 +231,87 @@ module Zeitwerk
       setup
     end
 
+    # Returns a hash that maps the absolute paths of the managed files and
+    # directories to their respective expected constant paths.
+    #
+    # @sig () -> Hash[String, String]
+    def all_expected_cpaths
+      result = {}
+
+      actual_roots.each do |root_dir, root_namespace|
+        queue = [[root_dir, real_mod_name(root_namespace)]]
+
+        while (dir, cpath = queue.shift)
+          result[dir] = cpath
+
+          prefix = cpath == "Object" ? "" : cpath + "::"
+
+          ls(dir) do |basename, abspath, ftype|
+            if ftype == :file
+              basename.delete_suffix!(".rb")
+              result[abspath] = prefix + inflector.camelize(basename, abspath)
+            else
+              if collapse?(abspath)
+                queue << [abspath, cpath]
+              else
+                queue << [abspath, prefix + inflector.camelize(basename, abspath)]
+              end
+            end
+          end
+        end
+      end
+
+      result
+    end
+
+    # @sig (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)
+
+      return unless dir?(abspath) || ruby?(abspath)
+      return if ignored_path?(abspath)
+
+      paths = []
+
+      if ruby?(abspath)
+        basename = File.basename(abspath, ".rb")
+        return if hidden?(basename)
+
+        paths << [basename, abspath]
+        walk_up_from = File.dirname(abspath)
+      else
+        walk_up_from = abspath
+      end
+
+      root_namespace = nil
+
+      walk_up(walk_up_from) do |dir|
+        break if root_namespace = roots[dir]
+        return if ignored_path?(dir)
+
+        basename = File.basename(dir)
+        return if hidden?(basename)
+
+        paths << [basename, abspath] unless collapse?(dir)
+      end
+
+      return unless root_namespace
+
+      if paths.empty?
+        real_mod_name(root_namespace)
+      else
+        cnames = paths.reverse_each.map { |b, a| cname_for(b, a) }
+
+        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.
     #
@@ -264,12 +348,15 @@ module Zeitwerk
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
+      include RealModName
+
       # @sig #call | #debug | nil
       attr_accessor :default_logger
 
       # This is a shortcut for
       #
       #   require "zeitwerk"
+      #
       #   loader = Zeitwerk::Loader.new
       #   loader.tag = File.basename(__FILE__, ".rb")
       #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
@@ -284,7 +371,36 @@ module Zeitwerk
       # @sig (bool) -> Zeitwerk::GemLoader
       def for_gem(warn_on_extra_files: true)
         called_from = caller_locations(1, 1).first.path
-        Registry.loader_for_gem(called_from, warn_on_extra_files: warn_on_extra_files)
+        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.
+      #
+      # @sig (bool) -> 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, namespace: namespace, warn_on_extra_files: false)
       end
 
       # Broadcasts `eager_load` to all loaders. Those that have not been setup
@@ -325,44 +441,26 @@ module Zeitwerk
     end
 
     # @sig (String, Module) -> void
-    private def set_autoloads_in_dir(dir, parent)
-      ls(dir) do |basename, abspath|
-        begin
-          if ruby?(basename)
-            basename.delete_suffix!(".rb")
-            cname = inflector.camelize(basename, abspath).to_sym
-            autoload_file(parent, cname, abspath)
+    private def define_autoloads_for_dir(dir, parent)
+      ls(dir) do |basename, abspath, ftype|
+        if ftype == :file
+          basename.delete_suffix!(".rb")
+          cref = Cref.new(parent, cname_for(basename, abspath))
+          autoload_file(cref, abspath)
+        else
+          if collapse?(abspath)
+            define_autoloads_for_dir(abspath, parent)
           else
-            if collapse?(abspath)
-              set_autoloads_in_dir(abspath, parent)
-            else
-              cname = inflector.camelize(basename, abspath).to_sym
-              autoload_subdir(parent, cname, abspath)
-            end
+            cref = Cref.new(parent, cname_for(basename, abspath))
+            autoload_subdir(cref, abspath)
           end
-        rescue ::NameError => error
-          path_type = ruby?(abspath) ? "file" : "directory"
-
-          raise NameError.new(<<~MESSAGE, error.name)
-            #{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
         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
@@ -371,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
-        set_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
-        set_autoloads_in_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
-        set_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
 
-      set_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 set_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
 
@@ -479,7 +572,6 @@ module Zeitwerk
               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
@@ -494,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/null_inflector.rb

@@ -0,0 +1,5 @@
+class Zeitwerk::NullInflector
+  def camelize(basename, _abspath)
+    basename
+  end
+end

data/lib/zeitwerk/registry.rb

@@ -86,8 +86,8 @@ module Zeitwerk
       #
       # @private
       # @sig (String) -> Zeitwerk::Loader
-      def loader_for_gem(root_file, warn_on_extra_files:)
-        gem_loaders_by_root_file[root_file] ||= GemLoader._new(root_file, warn_on_extra_files: warn_on_extra_files)
+      def loader_for_gem(root_file, namespace:, warn_on_extra_files:)
+        gem_loaders_by_root_file[root_file] ||= GemLoader.__new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
       end
 
       # @private

data/lib/zeitwerk/version.rb

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

data/lib/zeitwerk.rb

@@ -3,12 +3,14 @@
 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"
   require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
+  require_relative "zeitwerk/null_inflector"
   require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
   require_relative "zeitwerk/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.7
+  version: 2.6.17
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-10 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
@@ -35,6 +36,7 @@ files:
 - lib/zeitwerk/loader/config.rb
 - lib/zeitwerk/loader/eager_load.rb
 - lib/zeitwerk/loader/helpers.rb
+- lib/zeitwerk/null_inflector.rb
 - lib/zeitwerk/real_mod_name.rb
 - lib/zeitwerk/registry.rb
 - lib/zeitwerk/version.rb
@@ -61,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.3
+rubygems_version: 3.5.15
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader