zeitwerk 2.6.7 → 2.6.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6c7bf12c3a33195c57541b840ca6d7dbc21b19e0d7b91d8933ad37aa88b325d
-  data.tar.gz: 4b8dd86417dd633b78c02eada9ed6956e8e708397c988237aaddecb9644ba469
+  metadata.gz: 5a9048a5ba05f448e5406080995aab9709a3dd7c8dd32aad3aa0ba4f544b69c4
+  data.tar.gz: 581cf27f70c82b754a1baadf7a41f6c87c069ae2e78bd26b4ec6e02cfa2795b9
 SHA512:
-  metadata.gz: 4f0bc60d9914a9e815aed501a030f7e9bde7927f750f3836f96ac86a52c0699f4ca69456bd381845428f6b09adccaa085443f39bb0fdaa651437742e21d10af2
-  data.tar.gz: 3ba55f7bb24725d156cc4043697bfcd6092e2893f1aa71296965c82ae9ed66b79c30f853b535693b6b884d7d3d26cf1b122545e395ba11c92f65552e14116248
+  metadata.gz: 45327b148bab210d941ffeae022b70e5c2f2be4372f2192a08859faeed81d2cc5702b05d6e4efcf676a8fb7b451c46200ac372051c68ba84cfc31ed9339f3ede
+  data.tar.gz: 8e3266d7641f58b6a8f74abfa913c14ae4a79d4efd177578de4e7e144a21adc33d33279b7d2771cdc57937cfedfb1f5e193bb9e57c18ea90956b342b516e9bd9

data/README.md

@@ -3,7 +3,8 @@
 
 
 [![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/fxn/zeitwerk/ci.yml?branch=main&event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions/workflows/ci.yml?query=branch%3main)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/fxn/zeitwerk/ci.yml?branch=main&event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions/workflows/ci.yml?query=branch%3Amain)
+
 
 <!-- TOC -->
 
@@ -24,6 +25,7 @@
   - [Setup](#setup)
     - [Generic](#generic)
     - [for_gem](#for_gem)
+    - [for_gem_extension](#for_gem_extension)
   - [Autoloading](#autoloading)
   - [Eager loading](#eager-loading)
     - [Eager load exclusions](#eager-load-exclusions)
@@ -55,6 +57,8 @@
   - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Introspection](#introspection)
+    - [`Zeitwerk::Loader#dirs`](#zeitwerkloaderdirs)
+    - [`Zeitwerk::Loader#cpath_expected_at`](#zeitwerkloadercpath_expected_at)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
@@ -75,15 +79,15 @@
 
 Zeitwerk is an efficient and thread-safe code loader for Ruby.
 
-Given a [conventional file structure](#file-structure), Zeitwerk is able to load your project's classes and modules on demand (autoloading), or upfront (eager loading). You don't need to write `require` calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and matches Ruby's semantics for constants.
+Given a [conventional file structure](#file-structure), Zeitwerk is capable of loading your project's classes and modules on demand (autoloading) or upfront (eager loading). You don't need to write `require` calls for your own files; instead, you can streamline your programming by knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and aligns with Ruby's semantics for constants.
 
-Zeitwerk is also able to reload code, which may be handy while developing web applications. Coordination is needed to reload in a thread-safe manner. The documentation below explains how to do this.
+Zeitwerk also supports code reloading, which can be useful during web application development. However, coordination is required to reload in a thread-safe manner. The documentation below explains how to achieve this.
 
-The gem is designed so that any project, gem dependency, application, etc. can have their own independent loader, coexisting in the same process, managing their own project trees, and independent of each other. Each loader has its own configuration, inflector, and optional logger.
+The gem is designed to allow any project, gem dependency, or application to have its own independent loader. Multiple loaders can coexist in the same process, each managing its own project tree and operating independently of each other. Each loader has its own configuration, inflector, and optional logger.
 
-Internally, Zeitwerk issues `require` calls exclusively using absolute file names, so there are no costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk do not even need to be in `$LOAD_PATH`.
+Internally, Zeitwerk exclusively uses absolute file names when issuing `require` calls, eliminating the need for costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk don't even need to be in `$LOAD_PATH`.
 
-Furthermore, Zeitwerk does at most one single scan of the project tree, and it descends into subdirectories lazily, only if their namespaces are used.
+Furthermore, Zeitwerk performs a single scan of the project tree at most, lazily descending into subdirectories only when their namespaces are used.
 
 <a id="markdown-synopsis" name="synopsis"></a>
 ## Synopsis
@@ -143,7 +147,7 @@ Zeitwerk::Loader.eager_load_all
 <a id="markdown-the-idea-file-paths-match-constant-paths" name="the-idea-file-paths-match-constant-paths"></a>
 ### The idea: File paths match constant paths
 
-To have a file structure Zeitwerk can work with, just name files and directories after the name of the classes and modules they define:
+For Zeitwerk to work with your file structure, simply name files and directories after the classes and modules they define:
 
 ```
 lib/my_gem.rb         -> MyGem
@@ -152,7 +156,7 @@ lib/my_gem/bar_baz.rb -> MyGem::BarBaz
 lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo
 ```
 
-You can tune that a bit by [collapsing directories](#collapsing-directories), or by [ignoring parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
+You can fine-tune this behavior by [collapsing directories](#collapsing-directories) or [ignoring specific parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
 
 <a id="markdown-inner-simple-constants" name="inner-simple-constants"></a>
 ### Inner simple constants
@@ -210,7 +214,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 non-anonymous class or module object in the optional `namespace` keyword argument.
+Although `Object` is the most common root namespace, you have the flexibility to associate a different one with a specific root directory. The `push_dir` method accepts a non-anonymous class or module object as the optional `namespace` keyword argument.
 
 For example, given:
 
@@ -226,14 +230,14 @@ a file defining `ActiveJob::QueueAdapters::MyQueueAdapter` does not need the con
 adapters/my_queue_adapter.rb -> ActiveJob::QueueAdapters::MyQueueAdapter
 ```
 
-Please, note that the given root namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::Deliveries`, that one can be reloaded.
+Please note that the provided root namespace must be non-reloadable, while allowing autoloaded constants within that namespace to be reloadable. This means that if you associate the `app/api` directory with an existing `Api` module, the module itself should not be reloadable. However, if the project defines and autoloads the `Api::Deliveries` class, that class can be reloaded.
 
 <a id="markdown-nested-root-directories" name="nested-root-directories"></a>
 #### Nested root directories
 
-Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
+Root directories are recommended not to be nested; however, Zeitwerk provides support for nested root directories since in frameworks like Rails, both `app/models` and `app/models/concerns` belong to the autoload paths.
 
-Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
+Zeitwerk identifies nested root directories and treats them as independent roots. In the given example, `concerns` is not considered a namespace within `app/models`. For instance, consider the following file:
 
 ```
 app/models/concerns/geolocatable.rb
@@ -244,9 +248,9 @@ should define `Geolocatable`, not `Concerns::Geolocatable`.
 <a id="markdown-implicit-namespaces" name="implicit-namespaces"></a>
 ### Implicit namespaces
 
-If a namespace is just a simple module with no code, you do not need to define it in a file: Directories without a matching Ruby file get modules created automatically on your behalf.
+If a namespace consists only of a simple module without any code, there is no need to explicitly define it in a separate file. Zeitwerk automatically creates modules on your behalf for directories without a corresponding Ruby file.
 
-For example, if a project has an `admin` directory:
+For instance, suppose a project includes an `admin` directory:
 
 ```
 app/controllers/admin/users_controller.rb -> Admin::UsersController
@@ -254,7 +258,7 @@ app/controllers/admin/users_controller.rb -> Admin::UsersController
 
 and does not have a file called `admin.rb`, Zeitwerk automatically creates an `Admin` module on your behalf the first time `Admin` is used.
 
-For this to happen, the directory has to contain non-ignored Ruby files with extension `.rb`, directly or recursively, otherwise it is ignored. This condition is evaluated again on reloads.
+To trigger this behavior, the directory must contain non-ignored Ruby files with the `.rb` extension, either directly or recursively. Otherwise, the directory is ignored. This condition is reevaluated during reloads.
 
 <a id="markdown-explicit-namespaces" name="explicit-namespaces"></a>
 ### Explicit namespaces
@@ -410,6 +414,65 @@ Otherwise, there's a flag to say the extra stuff is OK:
 Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 ```
 
+<a id="markdown-for_gem_extension" name="for_gem_extension"></a>
+#### for_gem_extension
+
+Let's suppose you are writing a gem to extend `Net::HTTP` with some niche feature. By [convention](https://guides.rubygems.org/name-your-gem/):
+
+* The gem should be called `net-http-niche_feature`. That is, hyphens for the extended part, a hyphen, and underscores for yours.
+* The namespace should be `Net::HTTP::NicheFeature`.
+* The entry point should be `lib/net/http/niche_feature.rb`.
+* Optionally, the gem could have a top-level `lib/net-http-niche_feature.rb`, but, if defined, that one should have just a `require` call for the entry point.
+
+The top-level file mentioned in the last point is optional. In particular, from
+
+```ruby
+gem "net-http-niche_feature"
+```
+
+if the hyphenated file does not exist, Bundler notes the conventional hyphenated pattern and issues a `require` for `net/http/niche_feature`.
+
+Gem extensions following the conventions above have a dedicated loader constructor: `Zeitwerk::Loader.for_gem_extension`.
+
+The structure of the gem would be like this:
+
+```ruby
+# lib/net-http-niche_feature.rb (optional)
+
+# For technical reasons, this cannot be require_relative.
+require "net/http/niche_feature"
+
+
+# lib/net/http/niche_feature.rb
+
+require "net/http"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem_extension(Net::HTTP)
+loader.setup
+
+module Net::HTTP::NicheFeature
+  # Since the setup has been performed, at this point we are already able
+  # to reference project constants, in this case Net::HTTP::NicheFeature::MyMixin.
+  include MyMixin
+end
+
+
+# lib/net/http/niche_feature/version.rb
+
+module Net::HTTP::NicheFeature
+  VERSION = "1.0.0"
+end
+```
+
+`Zeitwerk::Loader.for_gem_extension` expects as argument the namespace being extended, which has to be a non-anonymous class or module object.
+
+If it exists, `lib/net/http/niche_feature/version.rb` is expected to define `Net::HTTP::NicheFeature::VERSION`.
+
+Due to technical reasons, the entry point of the gem has to be loaded with `Kernel#require`. Loading that file with `Kernel#load` or `Kernel#require_relative` won't generally work. This is important if you load the entry point from the optional hyphenated top-level file.
+
+`Zeitwerk::Loader.for_gem_extension` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
+
 <a id="markdown-autoloading" name="autoloading"></a>
 ### Autoloading
 
@@ -673,9 +736,34 @@ loader.inflector.inflect "html_parser" => "HTMLParser"
 loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
 ```
 
+Overrides have to match exactly directory or file (without extension) _basenames_. For example, if you configure
+
+```ruby
+loader.inflector.inflect("xml" => "XML")
+```
+
+then the following constants are expected:
+
+```
+xml.rb         -> XML
+foo/xml        -> Foo::XML
+foo/bar/xml.rb -> Foo::Bar::XML
+```
+
+As you see, any directory whose basename is exactly `xml`, and any file whose basename is exactly `xml.rb` are expected to define the constant `XML` in the corresponding namespace. On the other hand, partial matches are ignored. For example, `xml_parser.rb` would be inflected as `XmlParser` because `xml_parser` is not equal to `xml`. You'd need an additional override:
+
+```ruby
+loader.inflector.inflect(
+  "xml"        => "XML",
+  "xml_parser" => "XMLParser"
+)
+```
+
+If you need more flexibility, you can define a custom inflector, as explained down below.
+
 Overrides need to be configured before calling `setup`.
 
- The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
+The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
 
 <a id="markdown-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
 #### Zeitwerk::GemInflector
@@ -1154,6 +1242,9 @@ With that, when Zeitwerk scans the file system and reaches the gem directories `
 <a id="markdown-introspection" name="introspection"></a>
 ### Introspection
 
+<a id="markdown-zeitwerkloaderdirs" name="zeitwerkloaderdirs"></a>
+#### `Zeitwerk::Loader#dirs`
+
 The method `Zeitwerk::Loader#dirs` returns an array with the absolute paths of the root directories as strings:
 
 ```ruby
@@ -1175,6 +1266,44 @@ By default, ignored root directories are filtered out. If you want them included
 
 These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
 
+<a id="markdown-zeitwerkloadercpath_expected_at" name="zeitwerkloadercpath_expected_at"></a>
+#### `Zeitwerk::Loader#cpath_expected_at`
+
+Given a path as a string or `Pathname` object, `Zeitwerk::Loader#cpath_expected_at` returns a string with the corresponding expected constant path.
+
+Some examples, assuming that `app/models` is a root directory:
+
+```ruby
+loader.cpath_expected_at("app/models")                  # => "Object"
+loader.cpath_expected_at("app/models/user.rb")          # => "User"
+loader.cpath_expected_at("app/models/hotel")            # => "Hotel"
+loader.cpath_expected_at("app/models/hotel/billing.rb") # => "Hotel::Billing"
+```
+
+If `collapsed` is a collapsed directory:
+
+```ruby
+loader.cpath_expected_at("a/b/collapsed/c") # => "A::B::C"
+loader.cpath_expected_at("a/b/collapsed")   # => "A::B", edge case
+loader.cpath_expected_at("a/b")             # => "A::B"
+```
+
+If the argument corresponds to an [ignored file or directory](#ignoring-parts-of-the-project), the method returns `nil`. Same if the argument is not managed by the loader.
+
+`Zeitwerk::Error` is raised if the given path does not exist:
+
+```ruby
+loader.cpath_expected_at("non_existing_file.rb") # => Zeitwerk::Error
+```
+
+`Zeitwerk::NameError` is raised if a constant path cannot be derived from it:
+
+```ruby
+loader.cpath_expected_at("8.rb") # => Zeitwerk::NameError
+```
+
+This method does not parse file contents and does not guarantee files define the returned constant path. It just says which is the _expected_ one.
+
 <a id="markdown-encodings" name="encodings"></a>
 ### Encodings
 
@@ -1205,9 +1334,11 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 <a id="markdown-debuggers" name="debuggers"></a>
 ### Debuggers
 
-Zeitwerk works fine with [debug.rb](https://github.com/ruby/debug) and [Break](https://github.com/gsamokovarov/break).
+Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if CRuby is ≥ 3.1 (see [ruby/debug#558](https://github.com/ruby/debug/pull/558)).
+
+[Byebug](https://github.com/deivid-rodriguez/byebug) is compatible except for an edge case explained in [deivid-rodriguez/byebug#564](https://github.com/deivid-rodriguez/byebug/issues/564). Prior to CRuby 3.1, `debug.rb` has a similar edge incompatibility.
 
-[Byebug](https://github.com/deivid-rodriguez/byebug) is compatible except for an edge case explained in [deivid-rodriguez/byebug#564](https://github.com/deivid-rodriguez/byebug/issues/564).
+[Break](https://github.com/gsamokovarov/break) is fully compatible.
 
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation

data/lib/zeitwerk/gem_inflector.rb

@@ -5,8 +5,8 @@ module Zeitwerk
     # @sig (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
-      lib_dir       = File.dirname(root_file)
-      @version_file = File.join(lib_dir, namespace, "version.rb")
+      root_dir      = File.dirname(root_file)
+      @version_file = File.join(root_dir, namespace, "version.rb")
     end
 
     # @sig (String, String) -> String

data/lib/zeitwerk/gem_loader.rb

@@ -3,27 +3,31 @@
 module Zeitwerk
   # @private
   class GemLoader < Loader
+    include RealModName
+
     # Users should not create instances directly, the public interface is
     # `Zeitwerk::Loader.for_gem`.
     private_class_method :new
 
     # @private
     # @sig (String, bool) -> Zeitwerk::GemLoader
-    def self._new(root_file, warn_on_extra_files:)
-      new(root_file, warn_on_extra_files: warn_on_extra_files)
+    def self.__new(root_file, namespace:, warn_on_extra_files:)
+      new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
     end
 
     # @sig (String, bool) -> void
-    def initialize(root_file, warn_on_extra_files:)
+    def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
-      @tag                 = File.basename(root_file, ".rb")
+      @tag = File.basename(root_file, ".rb")
+      @tag = real_mod_name(namespace) + "-" + @tag unless namespace.equal?(Object)
+
       @inflector           = GemInflector.new(root_file)
       @root_file           = File.expand_path(root_file)
-      @lib                 = File.dirname(root_file)
+      @root_dir            = File.dirname(root_file)
       @warn_on_extra_files = warn_on_extra_files
 
-      push_dir(@lib)
+      push_dir(@root_dir, namespace: namespace)
     end
 
     # @sig () -> void
@@ -38,7 +42,7 @@ module Zeitwerk
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@lib) do |basename, abspath|
+      ls(@root_dir) do |basename, abspath|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 

data/lib/zeitwerk/kernel.rb

@@ -28,10 +28,10 @@ module Kernel
     if loader = Zeitwerk::Registry.loader_for(path)
       if path.end_with?(".rb")
         required = zeitwerk_original_require(path)
-        loader.on_file_autoloaded(path) if required
+        loader.__on_file_autoloaded(path) if required
         required
       else
-        loader.on_dir_autoloaded(path)
+        loader.__on_dir_autoloaded(path)
         true
       end
     else
@@ -39,7 +39,7 @@ module Kernel
       if required
         abspath = $LOADED_FEATURES.last
         if loader = Zeitwerk::Registry.loader_for(abspath)
-          loader.on_file_autoloaded(abspath)
+          loader.__on_file_autoloaded(abspath)
         end
       end
       required

data/lib/zeitwerk/loader/callbacks.rb

@@ -2,12 +2,12 @@
 
 module Zeitwerk::Loader::Callbacks
   include Zeitwerk::RealModName
+  extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @private
   # @sig (String) -> void
-  def on_file_autoloaded(file)
+  internal def on_file_autoloaded(file)
     cref  = autoloads.delete(file)
     cpath = cpath(*cref)
 
@@ -20,8 +20,16 @@ module Zeitwerk::Loader::Callbacks
     else
       msg = "expected file #{file} to define constant #{cpath}, 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)
+
+      # 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?
+
       raise Zeitwerk::NameError.new(msg, cref.last)
     end
   end
@@ -29,11 +37,11 @@ module Zeitwerk::Loader::Callbacks
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
-  # @private
   # @sig (String) -> void
-  def on_dir_autoloaded(dir)
-    # Module#autoload does not serialize concurrent requires, and we handle
-    # directories ourselves, so the callback needs to account for concurrency.
+  internal def on_dir_autoloaded(dir)
+    # Module#autoload does not serialize concurrent requires in CRuby < 3.2, and
+    # we handle directories ourselves without going through Kernel#require, so
+    # the callback needs to account for concurrency.
     #
     # Multi-threading would introduce a race condition here in which thread t1
     # autovivifies the module, and while autoloads for its children are being
@@ -43,7 +51,7 @@ module Zeitwerk::Loader::Callbacks
     # That not only would reassign the constant (undesirable per se) but, worse,
     # the module object created by t2 wouldn't have any of the autoloads for its
     # children, since t1 would have correctly deleted its namespace_dirs entry.
-    mutex2.synchronize do
+    dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
         autovivified_module = cref[0].const_set(cref[1], Module.new)
         cpath = autovivified_module.name
@@ -73,7 +81,7 @@ module Zeitwerk::Loader::Callbacks
   def on_namespace_loaded(namespace)
     if dirs = namespace_dirs.delete(real_mod_name(namespace))
       dirs.each do |dir|
-        set_autoloads_in_dir(dir, namespace)
+        define_autoloads_for_dir(dir, namespace)
       end
     end
   end

data/lib/zeitwerk/loader/config.rb

@@ -109,8 +109,7 @@ module Zeitwerk::Loader::Config
   # @raise [Zeitwerk::Error]
   # @sig (String | Pathname, Module) -> void
   def push_dir(path, namespace: Object)
-    # Note that Class < Module.
-    unless namespace.is_a?(Module)
+    unless namespace.is_a?(Module) # Note that Class < Module.
       raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
     end
 
@@ -298,9 +297,9 @@ module Zeitwerk::Loader::Config
     # Common use case.
     return false if ignored_paths.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if ignored_path?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if ignored_path?(path)
+      return false if roots.key?(path)
     end
 
     false
@@ -328,9 +327,9 @@ module Zeitwerk::Loader::Config
     # Optimize this common use case.
     return false if eager_load_exclusions.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if eager_load_exclusions.member?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if eager_load_exclusions.member?(path)
+      return false if roots.key?(path)
     end
 
     false

data/lib/zeitwerk/loader/eager_load.rb

@@ -45,8 +45,10 @@ module Zeitwerk::Loader::EagerLoad
 
       break if root_namespace = roots[dir]
 
+      basename = File.basename(dir)
+      return if hidden?(basename)
+
       unless collapse?(dir)
-        basename = File.basename(dir)
         cnames << inflector.camelize(basename, dir).to_sym
       end
     end
@@ -119,6 +121,8 @@ module Zeitwerk::Loader::EagerLoad
     raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
 
     basename = File.basename(abspath, ".rb")
+    raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+
     base_cname = inflector.camelize(basename, abspath).to_sym
 
     root_namespace = nil
@@ -129,8 +133,10 @@ module Zeitwerk::Loader::EagerLoad
 
       break if root_namespace = roots[dir]
 
+      basename = File.basename(dir)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+
       unless collapse?(dir)
-        basename = File.basename(dir)
         cnames << inflector.camelize(basename, dir).to_sym
       end
     end
@@ -165,7 +171,7 @@ module Zeitwerk::Loader::EagerLoad
         next if honour_exclusions && eager_load_exclusions.member?(abspath)
 
         if ruby?(abspath)
-          if (cref = autoloads[abspath]) && !shadowed_file?(abspath)
+          if (cref = autoloads[abspath])
             cget(*cref)
           end
         else

data/lib/zeitwerk/loader/helpers.rb

@@ -140,4 +140,48 @@ module Zeitwerk::Loader::Helpers
   private def crem(parent, cname)
     parent.__send__(:remove_const, cname)
   end
+
+  CNAME_VALIDATOR = Module.new
+  private_constant :CNAME_VALIDATOR
+
+  # @raise [Zeitwerk::NameError]
+  # @sig (String, String) -> Symbol
+  private def cname_for(basename, abspath)
+    cname = inflector.camelize(basename, abspath)
+
+    unless cname.is_a?(String)
+      raise TypeError, "#{inflector.class}#camelize must return a String, received #{cname.inspect}"
+    end
+
+    if cname.include?("::")
+      raise Zeitwerk::NameError.new(<<~MESSAGE, cname)
+        wrong constant name #{cname} inferred by #{inflector.class} from
+
+          #{abspath}
+
+        #{inflector.class}#camelize should return a simple constant name without "::"
+      MESSAGE
+    end
+
+    begin
+      CNAME_VALIDATOR.const_defined?(cname, false)
+    rescue ::NameError => error
+      path_type = ruby?(abspath) ? "file" : "directory"
+
+      raise Zeitwerk::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
+
+    cname.to_sym
+  end
 end

data/lib/zeitwerk/loader.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "monitor"
 require "set"
 
 module Zeitwerk
@@ -91,9 +92,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 +104,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 +121,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)
@@ -228,6 +230,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.
     #
@@ -264,12 +314,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 +337,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,36 +407,17 @@ module Zeitwerk
     end
 
     # @sig (String, Module) -> void
-    private def set_autoloads_in_dir(dir, parent)
+    private def define_autoloads_for_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)
+            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
+            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
@@ -380,12 +443,12 @@ module Zeitwerk
       elsif !cdef?(parent, cname)
         # First time we find this namespace, set an autoload for it.
         namespace_dirs[cpath(parent, cname)] << subdir
-        set_autoload(parent, cname, subdir)
+        define_autoload(parent, cname, 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))
+        define_autoloads_for_dir(subdir, cget(parent, cname))
       end
     end
 
@@ -408,7 +471,7 @@ module Zeitwerk
         shadowed_files << file
         log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
       else
-        set_autoload(parent, cname, file)
+        define_autoload(parent, cname, file)
       end
     end
 
@@ -422,12 +485,12 @@ module Zeitwerk
 
       log("earlier autoload for #{cpath(parent, cname)} discarded, it is actually an explicit namespace defined in #{file}") if logger
 
-      set_autoload(parent, cname, file)
+      define_autoload(parent, cname, file)
       register_explicit_namespace(cpath(parent, cname))
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def set_autoload(parent, cname, abspath)
+    private def define_autoload(parent, cname, abspath)
       parent.autoload(cname, abspath)
 
       if logger
@@ -479,7 +542,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

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.12"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.7
+  version: 2.6.12
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-10 00:00:00.000000000 Z
+date: 2023-09-25 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -61,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.3
+rubygems_version: 3.4.16
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader