zeitwerk 2.6.2 → 2.6.10

data/lib/zeitwerk/loader.rb

@@ -9,6 +9,8 @@ module Zeitwerk
     require_relative "loader/config"
     require_relative "loader/eager_load"
 
+    extend Internal
+
     include RealModName
     include Callbacks
     include Helpers
@@ -26,9 +28,9 @@ module Zeitwerk
     #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
     #   ...
     #
-    # @private
     # @sig Hash[String, [Module, Symbol]]
     attr_reader :autoloads
+    internal :autoloads
 
     # We keep track of autoloaded directories to remove them from the registry
     # at the end of eager loading.
@@ -36,9 +38,9 @@ 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).
     #
-    # @private
     # @sig Array[String]
     attr_reader :autoloaded_dirs
+    internal :autoloaded_dirs
 
     # Stores metadata needed for unloading. Its entries look like this:
     #
@@ -52,9 +54,9 @@ module Zeitwerk
     # If reloading is enabled, this hash is filled as constants are autoloaded
     # or eager loaded. Otherwise, the collection remains empty.
     #
-    # @private
     # @sig Hash[String, [String, [Module, Symbol]]]
     attr_reader :to_unload
+    internal :to_unload
 
     # Maps namespace constant paths to their respective directories.
     #
@@ -70,9 +72,9 @@ module Zeitwerk
     # and that its children are spread over those directories. We'll visit them
     # to set up the corresponding autoloads.
     #
-    # @private
     # @sig Hash[String, Array[String]]
     attr_reader :namespace_dirs
+    internal :namespace_dirs
 
     # A shadowed file is a file managed by this loader that is ignored when
     # setting autoloads because its matching constant is already taken.
@@ -81,17 +83,17 @@ module Zeitwerk
     # has only scanned the top-level, `shadowed_files` does not have shadowed
     # files that may exist deep in the project tree yet.
     #
-    # @private
     # @sig Set[String]
     attr_reader :shadowed_files
+    internal :shadowed_files
 
-    # @private
     # @sig Mutex
     attr_reader :mutex
+    private :mutex
 
-    # @private
     # @sig Mutex
     attr_reader :mutex2
+    private :mutex2
 
     def initialize
       super
@@ -109,15 +111,15 @@ module Zeitwerk
       Registry.register_loader(self)
     end
 
-    # Sets autoloads in the root namespace.
+    # Sets autoloads in the root namespaces.
     #
     # @sig () -> void
     def setup
       mutex.synchronize do
         break if @setup
 
-        actual_root_dirs.each do |root_dir, namespace|
-          set_autoloads_in_dir(root_dir, namespace)
+        actual_roots.each do |root_dir, root_namespace|
+          set_autoloads_in_dir(root_dir, root_namespace)
         end
 
         on_setup_callbacks.each(&:call)
@@ -134,12 +136,14 @@ module Zeitwerk
     # unload them.
     #
     # This method is public but undocumented. Main interface is `reload`, which
-    # means `unload` + `setup`. This one is avaiable to be used together with
+    # means `unload` + `setup`. This one is available to be used together with
     # `unregister`, which is undocumented too.
     #
     # @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 +203,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 +220,7 @@ module Zeitwerk
     # @sig () -> void
     def reload
       raise ReloadingDisabledError unless reloading_enabled?
+      raise SetupRequired unless @setup
 
       unload
       recompute_ignored_paths
@@ -223,6 +228,54 @@ module Zeitwerk
       setup
     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.
     #
@@ -245,27 +298,29 @@ 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
     # scanned the file. This is the case in the spots where we use it.
     #
-    # @private
     # @sig (String) -> Boolean
-    def shadowed_file?(file)
+    internal def shadowed_file?(file)
       shadowed_files.member?(file)
     end
 
     # --- 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__)
@@ -280,22 +335,63 @@ 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.
+      # 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
 
@@ -308,51 +404,39 @@ module Zeitwerk
       end
     end
 
-    private # -------------------------------------------------------------------------------------
-
     # @sig (String, Module) -> void
-    def set_autoloads_in_dir(dir, parent)
+    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)
+        if ruby?(basename)
+          basename.delete_suffix!(".rb")
+          autoload_file(parent, cname_for(basename, abspath), abspath)
+        else
+          if collapse?(abspath)
+            set_autoloads_in_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
+            autoload_subdir(parent, cname_for(basename, abspath), 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
-    def autoload_subdir(parent, cname, subdir)
+    private def autoload_subdir(parent, cname, subdir)
       if autoload_path = autoload_path_set_by_me_for?(parent, cname)
         cpath = cpath(parent, cname)
-        register_explicit_namespace(cpath) if ruby?(autoload_path)
-        # We do not need to issue another autoload, the existing one is enough
-        # no matter if it is for a file or a directory. Just remember the
-        # subdirectory has to be visited if the namespace is used.
+        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
+          # namespace whose definition was seen first.
+          #
+          # 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)
+        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)
         # First time we find this namespace, set an autoload for it.
@@ -367,7 +451,7 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol, String) -> void
-    def autoload_file(parent, cname, file)
+    private def autoload_file(parent, cname, file)
       if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
@@ -393,7 +477,7 @@ module Zeitwerk
     # the file where we've found the namespace is explicitly defined.
     #
     # @sig (dir: String, file: String, parent: Module, cname: Symbol) -> void
-    def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
+    private def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
       autoloads.delete(dir)
       Registry.unregister_autoload(dir)
 
@@ -404,7 +488,7 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol, String) -> void
-    def set_autoload(parent, cname, abspath)
+    private def set_autoload(parent, cname, abspath)
       parent.autoload(cname, abspath)
 
       if logger
@@ -425,7 +509,7 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol) -> String?
-    def autoload_path_set_by_me_for?(parent, cname)
+    private def autoload_path_set_by_me_for?(parent, cname)
       if autoload_path = strict_autoload_path(parent, cname)
         autoload_path if autoloads.key?(autoload_path)
       else
@@ -434,28 +518,28 @@ module Zeitwerk
     end
 
     # @sig (String) -> void
-    def register_explicit_namespace(cpath)
-      ExplicitNamespace.register(cpath, self)
+    private def register_explicit_namespace(cpath)
+      ExplicitNamespace.__register(cpath, self)
     end
 
     # @sig (String) -> void
-    def raise_if_conflicting_directory(dir)
+    private def raise_if_conflicting_directory(dir)
       MUTEX.synchronize do
+        dir_slash = dir + "/"
+
         Registry.loaders.each do |loader|
           next if loader == self
-          next if loader.ignores?(dir)
+          next if loader.__ignores?(dir)
 
-          dir = dir + "/"
-          loader.root_dirs.each do |root_dir, _namespace|
+          loader.__roots.each_key do |root_dir|
             next if ignores?(root_dir)
 
-            root_dir = root_dir + "/"
-            if dir.start_with?(root_dir) || root_dir.start_with?(dir)
+            root_dir_slash = root_dir + "/"
+            if dir_slash.start_with?(root_dir_slash) || root_dir_slash.start_with?(dir_slash)
               require "pp" # Needed for pretty_inspect, even in Ruby 2.5.
               raise Error,
-                "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir.chop}," \
+                "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
@@ -463,23 +547,23 @@ module Zeitwerk
     end
 
     # @sig (String, Object, String) -> void
-    def run_on_unload_callbacks(cpath, value, abspath)
+    private def run_on_unload_callbacks(cpath, value, abspath)
       # Order matters. If present, run the most specific one.
       on_unload_callbacks[cpath]&.each { |c| c.call(value, abspath) }
       on_unload_callbacks[:ANY]&.each { |c| c.call(cpath, value, abspath) }
     end
 
     # @sig (Module, Symbol) -> void
-    def unload_autoload(parent, cname)
-      parent.__send__(:remove_const, cname)
+    private def unload_autoload(parent, cname)
+      crem(parent, cname)
       log("autoload for #{cpath(parent, cname)} removed") if logger
     end
 
     # @sig (Module, Symbol) -> void
-    def unload_cref(parent, cname)
+    private def unload_cref(parent, cname)
       # Let's optimistically remove_const. The way we use it, this is going to
       # succeed always if all is good.
-      parent.__send__(:remove_const, cname)
+      crem(parent, cname)
     rescue ::NameError
       # There are a few edge scenarios in which this may happen. If the constant
       # is gone, that is OK, anyway.

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.2"
+  VERSION = "2.6.10"
 end

data/lib/zeitwerk.rb

@@ -2,6 +2,7 @@
 
 module Zeitwerk
   require_relative "zeitwerk/real_mod_name"
+  require_relative "zeitwerk/internal"
   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.2
+  version: 2.6.10
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-31 00:00:00.000000000 Z
+date: 2023-07-30 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -28,6 +28,7 @@ files:
 - lib/zeitwerk/gem_inflector.rb
 - lib/zeitwerk/gem_loader.rb
 - lib/zeitwerk/inflector.rb
+- lib/zeitwerk/internal.rb
 - lib/zeitwerk/kernel.rb
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
@@ -60,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.16
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader