zeitwerk 2.6.18 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1fa60f08c282d8471eaf321deba97207ce56d2cba32619cff78f09e65f2f258
-  data.tar.gz: 1c803846848fc8830913acfd8fbf04bfa59f26c3c8806d4fa5bed9c751f48c5a
+  metadata.gz: f6f3971296735d2ad5ae2d2621b5f26d6f480e7b69fde7e6eb21679a2b0c795c
+  data.tar.gz: 41ce43ff32412f63d21fb5bd9f45dc070e48e96f03be1e49eb2a5c6c5ef107ba
 SHA512:
-  metadata.gz: abb7134976f1ae00cafd77dcaa39fe2239632639c136d866ac75e55c8ec15f1c157ff0e434969dade286ee36e6422856799acd3e86dcd61e4ef39d1fd23909a4
-  data.tar.gz: 42e2309bd69f0bba3bfc74acecf2fcf3b3206a6cd26583afdc1012d34a063431bc03ec4ec42e1cf452f41bfa0de43a4d171cb2e99c7ca3e64b61412fbef83819
+  metadata.gz: 2b543e2a0db16c3dcdf8318faeaae7e1a72b0001b6116fa0081fa991266fbcc75da8ebdecaf9cf17568d9b169688810f411fb5d578a6ce7f5fad60a5fea37380
+  data.tar.gz: 021343c474a12a015071b20eaff22c53fdf9d0a49e606ee460be809fd731be065e72573ffb082bfab19b14f432000b309cc3e8e44e75669b97d91fa5b275519a

data/README.md

@@ -19,6 +19,8 @@
     - [Nested root directories](#nested-root-directories)
   - [Implicit namespaces](#implicit-namespaces)
   - [Explicit namespaces](#explicit-namespaces)
+    - [Explicit namespaces defined in ordinary files](#explicit-namespaces-defined-in-ordinary-files)
+    - [Explicit namespaces defined in nsfiles](#explicit-namespaces-defined-in-nsfiles)
   - [Collapsing directories](#collapsing-directories)
   - [Testing compliance](#testing-compliance)
 - [Usage](#usage)
@@ -54,16 +56,15 @@
     - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
     - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
   - [Shadowed files](#shadowed-files)
-  - [Edge cases](#edge-cases)
   - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Introspection](#introspection)
     - [`Zeitwerk::Loader#dirs`](#zeitwerkloaderdirs)
+    - [Autoloaded Constants](#autoloaded-constants)
     - [`Zeitwerk::Loader#cpath_expected_at`](#zeitwerkloadercpath_expected_at)
     - [`Zeitwerk::Loader#all_expected_cpaths`](#zeitwerkloaderall_expected_cpaths)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
-  - [Debuggers](#debuggers)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Testing](#testing)
@@ -99,7 +100,7 @@ Main interface for gems:
 ```ruby
 # lib/my_gem.rb (main file)
 
-require "zeitwerk"
+require 'zeitwerk'
 loader = Zeitwerk::Loader.for_gem
 loader.setup # ready!
 
@@ -182,7 +183,7 @@ end
 The first example needs a custom [inflection](#inflection) rule:
 
 ```ruby
-loader.inflector.inflect("max_retries" => "MAX_RETRIES")
+loader.inflector.inflect('max_retries' => 'MAX_RETRIES')
 ```
 
 Otherwise, Zeitwerk would expect the file to define `MaxRetries`.
@@ -203,7 +204,7 @@ For example, given
 
 ```ruby
 loader.push_dir("#{__dir__}/models")
-loader.push_dir("#{__dir__}/serializers"))
+loader.push_dir("#{__dir__}/serializers")
 ```
 
 these are the expected classes and modules being defined by these files:
@@ -221,8 +222,8 @@ Although `Object` is the most common root namespace, you have the flexibility to
 For example, given:
 
 ```ruby
-require "active_job"
-require "active_job/queue_adapters"
+require 'active_job'
+require 'active_job/queue_adapters'
 loader.push_dir("#{__dir__}/adapters", namespace: ActiveJob::QueueAdapters)
 ```
 
@@ -265,16 +266,23 @@ To trigger this behavior, the directory must contain non-ignored Ruby files with
 <a id="markdown-explicit-namespaces" name="explicit-namespaces"></a>
 ### Explicit namespaces
 
-Classes and modules that act as namespaces can also be explicitly defined, though. For instance, consider
+Classes and modules that act as namespaces can also be explicitly defined in a file. This can be done with ordinary files named after the corresponding constant path, or with special namespace files, or _nsfiles_ for short.
+
+<a id="markdown-explicit-namespaces-defined-in-ordinary-files" name="explicit-namespaces-defined-in-ordinary-files"></a>
+#### Explicit namespaces defined in ordinary files
+
+Let's consider:
 
 ```
 app/models/hotel.rb         -> Hotel
 app/models/hotel/pricing.rb -> Hotel::Pricing
 ```
 
-There, `app/models/hotel.rb` defines `Hotel`, and thus Zeitwerk does not autovivify a module.
+Since there is a file `app/models/hotel.rb` and also a directory `app/models/hotel`, Zeitwerk realizes `Hotel` is a namespace that is defined in `app/models/hotel.rb`.
 
-The classes and modules from the namespace are already available in the body of the class or module defining it:
+In order to realize this, the directory or directories conforming the namespace do not need to be next to the file, as in the example, they could be in some other root directory.
+
+The classes and modules from an explicit namespace are already available in the body of the class or module that defines it:
 
 ```ruby
 class Hotel < ApplicationRecord
@@ -283,7 +291,50 @@ class Hotel < ApplicationRecord
 end
 ```
 
-An explicit namespace must be managed by one single loader. Loaders that reopen namespaces owned by other projects are responsible for loading their constants before setup.
+When autoloaded, Zeitwerk verifies the expected constant (`Hotel` in the example) stores a class or module object. If it doesn't, `Zeitwerk::Error` is raised.
+
+<a id="markdown-explicit-namespaces-defined-in-nsfiles" name="explicit-namespaces-defined-in-nsfiles"></a>
+#### Explicit namespaces defined in nsfiles
+
+If the loader has an nsfile configured (defaults to `nil`):
+
+```ruby
+loader.nsfile = 'ns.rb' # must be set before setup
+```
+
+you can alternatively define the explicit namespace inside its directory:
+
+```
+my_component/ns.rb     -> MyComponent
+my_component/widget.rb -> MyComponent::Widget
+```
+
+This may be handy for self-contained units for which a `my_component.rb` file in the parent directory would feel unnatural.
+
+A loader's nsfile has to be a non-hidden basename with a `.rb` extension, as in the example above. Nsfiles are not inflected, so as long as those conditions hold, they may contain leading underscores, hyphens, etc.
+
+Collapsed directories work as expected. For example, if we assume that `src` is collapsed, and that `assets` and `tests` are ignored, you could have the code organized this way:
+
+```
+my_component/src/ns.rb            -> MyComponent
+my_component/src/widget.rb        -> MyComponent::Widget
+my_component/assets/widget.js
+my_component/tests/test_widget.rb
+```
+
+Loaders with an nsfile configured also support explicit namespaces defined in ordinary files. The conventions are not exclusive project-wide. Some parts may be component-oriented, while in other parts ordinary files may feel more natural. That works.
+
+However, attempting to define the same namespace using an ordinary file and an nsfile is an error condition that raises `Zeitwerk::ConflictingNamespaceDefinitionError`.
+
+Nsfiles in root directories raise `Zeitwerk::ConflictingNamespaceDefinitionError` too, since the namespace in a root directory is externally defined.
+
+Non-ignored files whose basename is equal to the nsfile are always considered to be nsfiles. You cannot opt out. Therefore, if we have:
+
+```ruby
+loader.nsfile = 'index.rb'
+```
+
+there is no way `foo/index.rb` can define `Foo::Index` in any part of the project, it must define `Foo`.
 
 <a id="markdown-collapsing-directories" name="collapsing-directories"></a>
 ### Collapsing directories
@@ -371,9 +422,9 @@ Conceptually, `for_gem` translates to:
 ```ruby
 # lib/my_gem.rb
 
-require "zeitwerk"
+require 'zeitwerk'
 loader = Zeitwerk::Loader.new
-loader.tag = File.basename(__FILE__, ".rb")
+loader.tag = File.basename(__FILE__, '.rb')
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
 loader.push_dir(File.dirname(__FILE__))
 ```
@@ -383,7 +434,7 @@ If the main module references project constants at the top-level, Zeitwerk has t
 ```ruby
 # lib/my_gem.rb (main file)
 
-require "zeitwerk"
+require 'zeitwerk'
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
@@ -429,7 +480,7 @@ Let's suppose you are writing a gem to extend `Net::HTTP` with some niche featur
 The top-level file mentioned in the last point is optional. In particular, from
 
 ```ruby
-gem "net-http-niche_feature"
+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`.
@@ -442,13 +493,13 @@ The structure of the gem would be like this:
 # lib/net-http-niche_feature.rb (optional)
 
 # For technical reasons, this cannot be require_relative.
-require "net/http/niche_feature"
+require 'net/http/niche_feature'
 
 
 # lib/net/http/niche_feature.rb
 
-require "net/http"
-require "zeitwerk"
+require 'net/http'
+require 'zeitwerk'
 
 loader = Zeitwerk::Loader.for_gem_extension(Net::HTTP)
 loader.setup
@@ -463,7 +514,7 @@ end
 # lib/net/http/niche_feature/version.rb
 
 module Net::HTTP::NicheFeature
-  VERSION = "1.0.0"
+  VERSION = '1.0.0'
 end
 ```
 
@@ -485,7 +536,7 @@ Let's revisit the example above:
 ```ruby
 # lib/my_gem.rb (main file)
 
-require "zeitwerk"
+require 'zeitwerk'
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
@@ -494,7 +545,7 @@ module MyGem
 end
 ```
 
-That works, and there is no `require "my_gem/my_logger"`. When `(*)` is reached, Zeitwerk seamlessly autoloads `MyGem::MyLogger`.
+That works, and there is no `require 'my_gem/my_logger'`. When `(*)` is reached, Zeitwerk seamlessly autoloads `MyGem::MyLogger`.
 
 If autoloading a file does not define the expected class or module, Zeitwerk raises `Zeitwerk::NameError`, which is a subclass of `NameError`.
 
@@ -681,7 +732,7 @@ In order to reload safely, no other thread can be autoloading or reloading concu
 For example, a web framework that serves each request in its own thread and has reloading enabled could create a read-write lock on boot like this:
 
 ```ruby
-require "concurrent/atomic/read_write_lock"
+require 'concurrent/atomic/read_write_lock'
 
 MyFramework::RELOAD_RW_LOCK = Concurrent::ReadWriteLock.new
 ```
@@ -726,22 +777,22 @@ The camelize logic can be overridden easily for individual basenames:
 
 ```ruby
 loader.inflector.inflect(
-  "html_parser"   => "HTMLParser",
-  "mysql_adapter" => "MySQLAdapter"
+  'html_parser'   => 'HTMLParser',
+  'mysql_adapter' => 'MySQLAdapter'
 )
 ```
 
 The `inflect` method can be invoked several times if you prefer this other style:
 
 ```ruby
-loader.inflector.inflect "html_parser" => "HTMLParser"
-loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
+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")
+loader.inflector.inflect('xml' => 'XML')
 ```
 
 then the following constants are expected:
@@ -756,8 +807,8 @@ As you see, any directory whose basename is exactly `xml`, and any file whose ba
 
 ```ruby
 loader.inflector.inflect(
-  "xml"        => "XML",
-  "xml_parser" => "XMLParser"
+  'xml'        => 'XML',
+  'xml_parser' => 'XMLParser'
 )
 ```
 
@@ -812,7 +863,7 @@ The inflectors that ship with Zeitwerk are deterministic and simple. But you can
 class MyInflector < Zeitwerk::Inflector
   def camelize(basename, abspath)
     if basename =~ /\Ahtml_(.*)/
-      "HTML" + super($1, abspath)
+      'HTML' + super($1, abspath)
     else
       super
     end
@@ -843,8 +894,8 @@ module MyGem
 end
 
 # lib/my_gem.rb
-require "zeitwerk"
-require_relative "my_gem/inflector"
+require 'zeitwerk'
+require_relative 'my_gem/inflector'
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector = MyGem::Inflector.new(__FILE__)
@@ -912,13 +963,13 @@ With `on_load`, it is easy to schedule code at boot time that initializes `endpo
 
 ```ruby
 # config/environments/development.rb
-loader.on_load("SomeApiClient") do |klass, _abspath|
-  klass.endpoint = "https://api.dev"
+loader.on_load('SomeApiClient') do |klass, _abspath|
+  klass.endpoint = 'https://api.dev'
 end
 
 # config/environments/production.rb
-loader.on_load("SomeApiClient") do |klass, _abspath|
-  klass.endpoint = "https://api.prod"
+loader.on_load('SomeApiClient') do |klass, _abspath|
+  klass.endpoint = 'https://api.prod'
 end
 ```
 
@@ -962,7 +1013,7 @@ When reloading is enabled, you may occasionally need to execute something before
 For example, let's imagine that a `Country` class fetches a list of countries and caches them when it is loaded. You might want to clear that cache if unloaded:
 
 ```ruby
-loader.on_unload("Country") do |klass, _abspath|
+loader.on_unload('Country') do |klass, _abspath|
   klass.clear_cache
 end
 ```
@@ -1047,7 +1098,7 @@ Zeitwerk@9fa54b: autoload set for User, to be loaded from ...
 By default, a random tag like the one above is assigned, but you can change it:
 
 ```
-loader.tag = "grep_me"
+loader.tag = 'grep_me'
 ```
 
 The tag of a loader returned by `for_gem` is the basename of the root file without extension:
@@ -1103,7 +1154,7 @@ loader.setup
 Now, that file has to be loaded manually with `require` or `require_relative`:
 
 ```ruby
-require_relative "my_gem/core_ext/kernel"
+require_relative 'my_gem/core_ext/kernel'
 ```
 
 and you can do that anytime, before configuring the loader, or after configuring the loader, does not matter.
@@ -1117,7 +1168,7 @@ Let's imagine your project talks to databases, supports several, and has adapter
 
 ```ruby
 # my_gem/db_adapters/postgresql.rb
-require "pg"
+require 'pg'
 ```
 
 but you don't want your users to install them all, only the one they are going to use.
@@ -1155,7 +1206,7 @@ loader.setup
 In Ruby, if you have several files called `foo.rb` in different directories of `$LOAD_PATH` and execute
 
 ```ruby
-require "foo"
+require 'foo'
 ```
 
 the first one found gets loaded, and the rest are ignored.
@@ -1178,36 +1229,6 @@ file #{file} is ignored because #{constant_path} is already defined
 
 Shadowing only applies to Ruby files, namespace definition can be spread over multiple directories. And you can also reopen third-party namespaces if done [orderly](#reopening-third-party-namespaces).
 
-<a id="markdown-edge-cases" name="edge-cases"></a>
-### Edge cases
-
-[Explicit namespaces](#explicit-namespaces) like `Trip` here:
-
-```ruby
-# trip.rb
-class Trip
-  include Geolocation
-end
-
-# trip/geolocation.rb
-module Trip::Geolocation
-  ...
-end
-```
-
-have to be defined with the `class`/`module` keywords, as in the example above.
-
-For technical reasons, raw constant assignment is not supported:
-
-```ruby
-# trip.rb
-Trip = Class { ...}        # NOT SUPPORTED
-Trip = Struct.new { ... }  # NOT SUPPORTED
-Trip = Data.define { ... } # NOT SUPPORTED
-```
-
-This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
-
 <a id="markdown-beware-of-circular-dependencies" name="beware-of-circular-dependencies"></a>
 ### Beware of circular dependencies
 
@@ -1254,10 +1275,10 @@ In order to do so, you need to make sure those modules are loaded before calling
 
 ```ruby
 # Ensure these namespaces are reopened, not defined.
-require "active_job"
-require "active_job/queue_adapters"
+require 'active_job'
+require 'active_job/queue_adapters'
 
-require "zeitwerk"
+require 'zeitwerk'
 # By passing the flag, we acknowledge the extra directory lib/active_job
 # has to be managed by the loader and no warning has to be issued for it.
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
@@ -1276,23 +1297,35 @@ The method `Zeitwerk::Loader#dirs` returns an array with the absolute paths of t
 
 ```ruby
 loader = Zeitwerk::Loader.new
-loader.push_dir(Pathname.new("/foo"))
-loader.dirs # => ["/foo"]
+loader.push_dir(Pathname.new('/foo'))
+loader.dirs # => ['/foo']
 ```
 
 This method accepts an optional `namespaces` keyword argument. If truthy, the method returns a hash table instead. Keys are the absolute paths of the root directories as strings. Values are their corresponding namespaces, class or module objects:
 
 ```ruby
 loader = Zeitwerk::Loader.new
-loader.push_dir(Pathname.new("/foo"))
-loader.push_dir(Pathname.new("/bar"), namespace: Bar)
-loader.dirs(namespaces: true) # => { "/foo" => Object, "/bar" => Bar }
+loader.push_dir(Pathname.new('/foo'))
+loader.push_dir(Pathname.new('/bar'), namespace: Bar)
+loader.dirs(namespaces: true) # => { '/foo' => Object, '/bar' => Bar }
 ```
 
 By default, ignored root directories are filtered out. If you want them included, please pass `ignored: true`.
 
 These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
 
+<a id="markdown-autoloaded-constants" name="autoloaded-constants"></a>
+#### Autoloaded Constants
+
+Zeitwerk does not keep track of autoloaded constants to minimize its memory footprint, but you can collect them with `on_load` if you will:
+
+```ruby
+autoloaded_cpaths = []
+loader.on_load do |cpath, _value, _abspath|
+  autoloaded_cpaths << cpath
+end
+```
+
 <a id="markdown-zeitwerkloadercpath_expected_at" name="zeitwerkloadercpath_expected_at"></a>
 #### `Zeitwerk::Loader#cpath_expected_at`
 
@@ -1301,18 +1334,18 @@ Given a path as a string or `Pathname` object, `Zeitwerk::Loader#cpath_expected_
 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"
+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"
+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.
@@ -1320,16 +1353,18 @@ If the argument corresponds to an [ignored file or directory](#ignoring-parts-of
 `Zeitwerk::Error` is raised if the given path does not exist:
 
 ```ruby
-loader.cpath_expected_at("non_existing_file.rb") # => Zeitwerk::Error
+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
+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.
+This method does not parse file contents and does not guarantee files define the returned constant path.
+
+Similarly, this method does not validate the project tree. If the project has conflicting oridinary and nsfiles for the same namespace, for example, the call will return the expected constant path for each of them without raising.
 
 `Zeitwerk::Loader#cpath_expected_at` is designed to be used with individual paths. If you want to know all the expected constant paths in the project, please use `Zeitwerk::Loader#all_expected_cpaths`, documented next.
 
@@ -1346,10 +1381,10 @@ For example, if `lib` is the root directory of a gem with the following contents
 lib/.DS_Store
 lib/my_gem.rb
 lib/my_gem/version.rb
-lib/my_gem/ignored.rb
 lib/my_gem/drivers/unix.rb
 lib/my_gem/drivers/windows.rb
 lib/my_gem/collapsed/foo.rb
+lib/my_gem/ignored.rb
 lib/tasks/my_gem.rake
 ```
 
@@ -1357,27 +1392,29 @@ lib/tasks/my_gem.rake
 
 ```ruby
 {
-  "/.../lib"                           => "Object",
-  "/.../lib/my_gem.rb"                 => "MyGem",
-  "/.../lib/my_gem"                    => "MyGem",
-  "/.../lib/my_gem/version.rb"         => "MyGem::VERSION",
-  "/.../lib/my_gem/drivers"            => "MyGem::Drivers",
-  "/.../lib/my_gem/drivers/unix.rb"    => "MyGem::Drivers::Unix",
-  "/.../lib/my_gem/drivers/windows.rb" => "MyGem::Drivers::Windows",
-  "/.../lib/my_gem/collapsed"          => "MyGem"
-  "/.../lib/my_gem/collapsed/foo.rb"   => "MyGem::Foo"
+  '/.../lib'                           => 'Object',
+  '/.../lib/my_gem.rb'                 => 'MyGem',
+  '/.../lib/my_gem'                    => 'MyGem',
+  '/.../lib/my_gem/version.rb'         => 'MyGem::VERSION',
+  '/.../lib/my_gem/drivers'            => 'MyGem::Drivers',
+  '/.../lib/my_gem/drivers/unix.rb'    => 'MyGem::Drivers::Unix',
+  '/.../lib/my_gem/drivers/windows.rb' => 'MyGem::Drivers::Windows',
+  '/.../lib/my_gem/collapsed'          => 'MyGem',
+  '/.../lib/my_gem/collapsed/foo.rb'   => 'MyGem::Foo'
 }
 ```
 
 In the previous example we assume `lib/my_gem/ignored.rb` is ignored, and therefore it is not present in the returned hash. Also, `lib/my_gem/collapsed` is a collapsed directory, so the expected namespace at that level is still `MyGem` (this is an edge case).
 
-The file `lib/.DS_Store` is hidden, hence excluded. The directory `lib/tasks` is also not present because it contains no files with extension ".rb".
+The file `lib/.DS_Store` is hidden, hence excluded. The directory `lib/tasks` is also excluded because it contains no files with extension ".rb".
 
 Directory paths do not have trailing slashes.
 
 The order of the hash entries is undefined.
 
-This method does not parse or execute file contents and does not guarantee files define the corresponding constant paths. It just says which are the _expected_ ones.
+This method does not parse file contents and does not guarantee files define the returned constant path.
+
+Similarly, this method does not validate the project tree. If the project has conflicting oridinary and nsfiles for the same namespace, for example, the call will return the expected constant path for each of them without raising.
 
 <a id="markdown-encodings" name="encodings"></a>
 ### Encodings
@@ -1406,15 +1443,6 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 
 6. In a given process, ideally, there should be at most one loader with reloading enabled. Technically, you can have more, but it may get tricky if one refers to constants managed by the other one. Do that only if you know what you are doing.
 
-<a id="markdown-debuggers" name="debuggers"></a>
-### Debuggers
-
-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.
-
-[Break](https://github.com/gsamokovarov/break) is fully compatible.
-
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation
 
@@ -1423,9 +1451,12 @@ Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if C
 <a id="markdown-supported-ruby-versions" name="supported-ruby-versions"></a>
 ## Supported Ruby versions
 
-Zeitwerk works with CRuby 2.5 and above.
+Starting with version 2.7, Zeitwerk requires Ruby 3.2 or newer.
 
-On TruffleRuby all is good except for thread-safety. Right now, in TruffleRuby `Module#autoload` does not block threads accessing a constant that is being autoloaded. CRuby prevents such access to avoid concurrent threads from seeing partial evaluations of the corresponding file. Zeitwerk inherits autoloading thread-safety from this property. This is not an issue if your project gets eager loaded, or if you lazy load in single-threaded environments. (See https://github.com/oracle/truffleruby/issues/2431.)
+Zeitwerk 2.7 requires TruffleRuby 24.1.2+ due to https://github.com/oracle/truffleruby/issues/3683.
+Alternatively, TruffleRuby users can use a `< 2.7` version constraint for the `zeitwerk` gem.
+As of this writing, [autoloading is not fully thread-safe yet on TruffleRuby](https://github.com/oracle/truffleruby/issues/2431).
+If your program is multi-threaded, you need to eager load before threads are created.
 
 JRuby 9.3.0.0 is almost there. As of this writing, the test suite of Zeitwerk passes on JRuby except for three tests. (See https://github.com/jruby/jruby/issues/6781.)
 
@@ -1444,12 +1475,18 @@ To run one particular suite, pass its file name as an argument:
 bin/test test/lib/zeitwerk/test_eager_load.rb
 ```
 
+That also accepts a line number:
+
+```
+bin/test test/lib/zeitwerk/test_eager_load.rb:52
+```
+
 Furthermore, the project has a development dependency on [`minitest-focus`](https://github.com/seattlerb/minitest-focus). To run an individual test mark it with `focus`:
 
 ```ruby
 focus
-test "capitalizes the first letter" do
-  assert_equal "User", camelize("user")
+test 'capitalizes the first letter' do
+  assert_equal 'User', camelize('user')
 end
 ```
 
@@ -1463,7 +1500,7 @@ and run `bin/test`.
 
 Since `require` has global side-effects, and there is no static way to verify that you have issued the `require` calls for code that your file depends on, in practice it is very easy to forget some. That introduces bugs that depend on the load order.
 
-Also, if the project has namespaces, setting things up and getting client code to load things in a consistent way needs discipline. For example, `require "foo/bar"` may define `Foo`, instead of reopen it. That may be a broken window, giving place to superclass mismatches or partially-defined namespaces.
+Also, if the project has namespaces, setting things up and getting client code to load things in a consistent way needs discipline. For example, `require 'foo/bar'` may define `Foo`, instead of reopen it. That may be a broken window, giving place to superclass mismatches or partially-defined namespaces.
 
 With Zeitwerk, you just name things following conventions and done. Things are available everywhere, and descend is always orderly. Without effort and without broken windows.
 

data/lib/zeitwerk/{kernel.rb → core_ext/kernel.rb}

@@ -19,10 +19,10 @@ module Kernel
     alias_method :zeitwerk_original_require, :require
   end
 
-  # @sig (String) -> true | false
+  #: (String) -> bool
   def require(path)
-    if loader = Zeitwerk::Registry.loader_for(path)
-      if path.end_with?(".rb")
+    if loader = Zeitwerk::Registry.autoloads.registered?(path)
+      if path.end_with?('.rb')
         required = zeitwerk_original_require(path)
         loader.__on_file_autoloaded(path) if required
         required
@@ -34,7 +34,7 @@ module Kernel
       required = zeitwerk_original_require(path)
       if required
         abspath = $LOADED_FEATURES.last
-        if loader = Zeitwerk::Registry.loader_for(abspath)
+        if loader = Zeitwerk::Registry.autoloads.registered?(abspath)
           loader.__on_file_autoloaded(abspath)
         end
       end

data/lib/zeitwerk/core_ext/module.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Zeitwerk::ConstAdded # :nodoc:
+  #: (Symbol) -> void
+  def const_added(cname)
+    if loader = Zeitwerk::Registry.explicit_namespaces.loader_for(self, cname)
+      namespace = const_get(cname, false)
+      cref = Zeitwerk::Cref.new(self, cname)
+
+      unless namespace.is_a?(Module)
+        raise Zeitwerk::Error, "#{cref} is expected to be a namespace, should be a class or module (got #{namespace.class})"
+      end
+
+      loader.__on_namespace_loaded(cref, namespace)
+    end
+    super
+  end
+
+  Module.prepend(self)
+end