zeitwerk 2.7.4 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c652e42a3b3a3a92704f1924bac194dc9b9c2db94641e6a9a3daf192480e7c7e
-  data.tar.gz: f24017f36733460e4c09ebc7d31de8ee95efda8c7e4f6aede34d4824f4922c3f
+  metadata.gz: 071170ec551e69be67c517af6e04ae2788d6f81f6451a7da0dfab49be8f0c52b
+  data.tar.gz: 96fd655043bee86c5f57567a01b5f5282e315b72bde7e5ca370ee8fd5e7917fb
 SHA512:
-  metadata.gz: d1a853bd6e7b638dc60203e6ba515646260913925ff8d30aa7edcb817253e61a534beadca02159ee7dffa78204d5c0dff652a056d2be2d688b9ec52fc1f9ac91
-  data.tar.gz: 26824d767e2f18ef128b66b2b354a6fc7bc16754734eb27bc3c6bf20c8a3ed36a06e2d20c1cbed6b932a327cbb70f4aa58cedd88ed81bf3f8074ebdf90a52e27
+  metadata.gz: 2b74298014af2753fbb19ad36f2a5d484cfbe364beb6aa583fe43d1f2cdf2fc3135bd5aaa16bedeb45a4a4ecbae95fc9d2e62aae5b59fd3df7cf5422693a947f
+  data.tar.gz: 242710104b8d2fba905cb65d1382080d098f4ff6c3d8b982d1cf53e9ea877612b22ee07b9d3f8f155a17b354e8412f2f350d835e7418f6eef7cf33a324a5ea4a

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)
@@ -58,6 +60,7 @@
   - [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)
@@ -97,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!
 
@@ -180,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`.
@@ -219,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)
 ```
 
@@ -263,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`.
+
+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 the namespace are already available in the body of the class or module defining it:
+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 +293,54 @@ end
 
 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.
 
-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.
+<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 styles are not exclusive. Some parts of the project 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.
+
+A project file whose basename is equal to the nsfile is always considered to be an nsfile. 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`.
+
+While configurable, `ns.rb` is the recommended convention:
+
+* `ns.rb` is short.
+* `ns.rb` suggests "namespace".
+* Needing an `Ns` constant is unlikely.
 
 <a id="markdown-collapsing-directories" name="collapsing-directories"></a>
 ### Collapsing directories
@@ -371,9 +428,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 +440,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 +486,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 +499,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 +520,7 @@ end
 # lib/net/http/niche_feature/version.rb
 
 module Net::HTTP::NicheFeature
-  VERSION = "1.0.0"
+  VERSION = '1.0.0'
 end
 ```
 
@@ -485,7 +542,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 +551,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 +738,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 +783,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 +813,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 +869,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 +900,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 +969,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 +1019,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 +1104,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 +1160,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 +1174,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 +1212,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.
@@ -1224,10 +1281,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)
@@ -1246,23 +1303,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`
 
@@ -1271,18 +1340,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.
@@ -1290,16 +1359,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.
 
@@ -1316,10 +1387,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
 ```
 
@@ -1327,27 +1398,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
@@ -1408,12 +1481,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
 ```
 
@@ -1427,7 +1506,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/core_ext/kernel.rb

@@ -22,7 +22,7 @@ module Kernel
   #: (String) -> bool
   def require(path)
     if loader = Zeitwerk::Registry.autoloads.registered?(path)
-      if path.end_with?(".rb")
+      if path.end_with?('.rb')
         required = zeitwerk_original_require(path)
         loader.__on_file_autoloaded(path) if required
         required

data/lib/zeitwerk/cref/map.rb

@@ -27,7 +27,7 @@
 # 1. We could also use a 1-level hash whose keys are constant paths. In the
 #    example above it would be:
 #
-#      { "M::X" => 0, "M::Y" => 1, "N::Z" => 2 }
+#      { 'M::X' => 0, 'M::Y' => 1, 'N::Z' => 2 }
 #
 #    The gem used this approach for several years.
 #

data/lib/zeitwerk/cref.rb

@@ -11,7 +11,7 @@
 #
 # The constant may or may not exist in `mod`.
 class Zeitwerk::Cref
-  require_relative "cref/map"
+  require_relative 'cref/map'
 
   include Zeitwerk::RealModName
 
@@ -66,4 +66,11 @@ class Zeitwerk::Cref
   def remove
     @mod.__send__(:remove_const, @cname)
   end
+
+  #: () -> String?
+  def location
+    if (location = @mod.const_source_location(@cname)) && !location.empty?
+      location.join(':')
+    end
+  end
 end

data/lib/zeitwerk/error.rb

@@ -17,7 +17,18 @@ module Zeitwerk
   class SetupRequired < Error
     #: () -> void
     def initialize
-      super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
+      super('please, finish your configuration and call Zeitwerk::Loader#setup once all is ready')
+    end
+  end
+
+  class ConflictingNamespaceDefinitionError < Error
+    #: (String, location: String?, conflicting_file: String) -> void
+    def initialize(cpath, location:, conflicting_file:)
+      if location
+        super("conflicting namespace definition for #{cpath}: #{conflicting_file} conflicts with #{location}")
+      else
+        super("conflicting namespace definition for #{cpath}: #{conflicting_file} conflicts with an already defined namespace")
+      end
     end
   end
 end

data/lib/zeitwerk/gem_inflector.rb

@@ -4,14 +4,14 @@ module Zeitwerk
   class GemInflector < Inflector
     #: (String) -> void
     def initialize(root_file)
-      namespace     = File.basename(root_file, ".rb")
+      namespace     = File.basename(root_file, '.rb')
       root_dir      = File.dirname(root_file)
-      @version_file = File.join(root_dir, namespace, "version.rb")
+      @version_file = File.join(root_dir, namespace, 'version.rb')
     end
 
     #: (String, String) -> String
     def camelize(basename, abspath)
-      abspath == @version_file ? "VERSION" : super
+      abspath == @version_file ? 'VERSION' : super
     end
   end
 end

data/lib/zeitwerk/gem_loader.rb

@@ -19,8 +19,8 @@ module Zeitwerk
     def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
-      @tag = File.basename(root_file, ".rb")
-      @tag = real_mod_name(namespace) + "-" + @tag unless namespace.equal?(Object)
+      @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)
@@ -40,14 +40,14 @@ module Zeitwerk
 
     #: () -> void
     def warn_on_extra_files
-      expected_namespace_dir = @root_file.delete_suffix(".rb")
+      expected_namespace_dir = @root_file.delete_suffix('.rb')
 
-      ls(@root_dir) do |basename, abspath, ftype|
+      @fs.ls(@root_dir) do |basename, abspath, ftype|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 
-        basename_without_ext = basename.delete_suffix(".rb")
-        cname = inflector.camelize(basename_without_ext, abspath).to_sym
+        basename_without_ext = basename.delete_suffix('.rb')
+        cname = cname_for(basename_without_ext, abspath)
 
         warn(<<~EOS)
           WARNING: Zeitwerk defines the constant #{cname} after the #{ftype}