zeitwerk 2.6.0 → 2.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7c15f85768f681d78dd0a96b23e5bb92fe8955fe74d9ae0cefeb1b0a55b76f1
-  data.tar.gz: 212a4b236b7d67c9413bd583bef540c0c9c090f5d0457af38b0681405bba3244
+  metadata.gz: 220865ab50f0336d05c8b907a08a94a8bf92843ba688c1a9686163a190b0754e
+  data.tar.gz: a9d62662351c60a3b264a68726a84c41fc4b6f92eaae855fb4887e3eb4cf14a1
 SHA512:
-  metadata.gz: 4feeb02e4ec695895035a39d1a46d45bd8eb77a1d72e732c28387ff16f4c3e2ac10735195fa246179cfce2fe072ada05c0f661b599fd4bc44763d300e485b12d
-  data.tar.gz: 0bd284cdfd10b1f27c7ad31ecd79c7bce9d76be46d3644941259ac7ee22ed425baac0cbcc340653547c873aecca6d5833c908e3009f58c4f0376be5402c9645b
+  metadata.gz: b802eaabb27e6268eafa8d35d4402819551203c5fd2a1692d9a9bae65075bf668f5aecfaf3fa6c763987796b60fd5bde4704aebda4a8bfa1c74a526c27264ab5
+  data.tar.gz: c4a53a60b49e5cb83aee148271b26fee8de15fd072327e52363438b0531d9953961305375ec727cc3a0ff2c021254eb081056350165922bd9f6f8b1e1b3e96f3

data/README.md

@@ -27,8 +27,14 @@
   - [Autoloading](#autoloading)
   - [Eager loading](#eager-loading)
     - [Eager load exclusions](#eager-load-exclusions)
+    - [Eager load directories](#eager-load-directories)
+    - [Eager load namespaces](#eager-load-namespaces)
+    - [Eager load namespaces shared by several loaders](#eager-load-namespaces-shared-by-several-loaders)
     - [Global eager load](#global-eager-load)
+  - [Loading individual files](#loading-individual-files)
   - [Reloading](#reloading)
+    - [Configuration and usage](#configuration-and-usage)
+    - [Thread-safety](#thread-safety)
   - [Inflection](#inflection)
     - [Zeitwerk::Inflector](#zeitwerkinflector)
     - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
@@ -44,9 +50,11 @@
     - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
     - [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)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
@@ -205,7 +213,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 class or module object in the optional `namespace` keyword argument.
+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.
 
 For example, given:
 
@@ -249,7 +257,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, directly or recursively, otherwise it is ignored. This condition is evaluated again on reloads.
+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.
 
 <a id="markdown-explicit-namespaces" name="explicit-namespaces"></a>
 ### Explicit namespaces
@@ -441,6 +449,8 @@ In gems, the method needs to be invoked after the main namespace has been define
 
 Eager loading is synchronized and idempotent.
 
+Attempting to eager load without previously calling `setup` raises `Zeitwerk::SetupRequired`.
+
 <a id="markdown-eager-load-exclusions" name="eager-load-exclusions"></a>
 #### Eager load exclusions
 
@@ -463,6 +473,81 @@ Which may be handy if the project eager loads in the test suite to [ensure proje
 
 The `force` flag does not affect ignored files and directories, those are still ignored.
 
+<a id="markdown-eager-load-directories" name="eager-load-directories"></a>
+#### Eager load directories
+
+The method `Zeitwerk::Loader#eager_load_dir` eager loads a given directory, recursively:
+
+```ruby
+loader.eager_load_dir("#{__dir__}/custom_web_app/routes")
+```
+
+This is useful when the loader is not eager loading the entire project, but you still need some subtree to be loaded for things to function properly.
+
+Both strings and `Pathname` objects are supported as arguments. If the argument is not a directory managed by the receiver, the method raises `Zeitwerk::Error`.
+
+[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](https://github.com/fxn/zeitwerk#shadowed-files) are not eager loaded.
+
+`Zeitwerk::Loader#eager_load_dir` is idempotent, but compatible with reloading. If you eager load a directory and then reload, eager loading that directory will load its (current) contents again.
+
+The method checks if a regular eager load was already executed, in which case it returns fast.
+
+Nested root directories which are descendants of the argument are skipped. Those subtrees are considered to be conceptually apart.
+
+Attempting to eager load a directory without previously calling `setup` raises `Zeitwerk::SetupRequired`.
+
+<a id="markdown-eager-load-namespaces" name="eager-load-namespaces"></a>
+#### Eager load namespaces
+
+The method `Zeitwerk::Loader#eager_load_namespace` eager loads a given namespace, recursively:
+
+```ruby
+loader.eager_load_namespace(MyApp::Routes)
+```
+
+This is useful when the loader is not eager loading the entire project, but you still need some namespace to be loaded for things to function properly.
+
+The argument has to be a class or module object and the method raises `Zeitwerk::Error` otherwise.
+
+If the namespace is spread over multiple directories in the receiver's source tree, they are all eager loaded. For example, if you have a structure like
+
+```
+root_dir1/my_app/routes
+root_dir2/my_app/routes
+root_dir3/my_app/routes
+```
+
+where `root_directory{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
+
+There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
+
+This method is flexible about what it accepts. Its semantics have to be interpreted as: "_If_ you manage this namespace, or part of this namespace, please eager load what you got". In particular, if the receiver does not manage the namespace, it will simply do nothing, this is not an error condition.
+
+[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](https://github.com/fxn/zeitwerk#shadowed-files) are not eager loaded.
+
+`Zeitwerk::Loader#eager_load_namespace` is idempotent, but compatible with reloading. If you eager load a namespace and then reload, eager loading that namespace will load its (current) descendants again.
+
+The method checks if a regular eager load was already executed, in which case it returns fast.
+
+If root directories are assigned to custom namespaces, the method behaves as you'd expect, according to the namespacing relationship between the custom namespace and the argument.
+
+Attempting to eager load a namespace without previously calling `setup` raises `Zeitwerk::SetupRequired`.
+
+<a id="markdown-eager-load-namespaces-shared-by-several-loaders" name="eager-load-namespaces-shared-by-several-loaders"></a>
+#### Eager load namespaces shared by several loaders
+
+The method `Zeitwerk::Loader.eager_load_namespace` broadcasts `eager_load_namespace` to all loaders.
+
+```ruby
+Zeitwerk::Loader.eager_load_namespace(MyFramework::Routes)
+```
+
+This may be handy, for example, if a framework supports plugins and a shared namespace needs to be eager loaded for the framework to function properly.
+
+Please, note that loaders only eager load namespaces they manage, as documented above. Therefore, this method does not allow you to eager load namespaces not managed by Zeitwerk loaders.
+
+This method does not require that all registered loaders have `setup` already invoked, since that is out of your control. If there's any in that state, it is simply skipped.
+
 <a id="markdown-global-eager-load" name="global-eager-load"></a>
 #### Global eager load
 
@@ -478,9 +563,31 @@ Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager lo
 
 This method does not accept the `force` flag, since in general it wouldn't be a good idea to force eager loading in 3rd party code.
 
+This method does not require that all registered loaders have `setup` already invoked, since that is out of your control. If there's any in that state, it is simply skipped.
+
+<a id="markdown-loading-individual-files" name="loading-individual-files"></a>
+### Loading individual files
+
+The method `Zeitwerk::Loader#load_file` loads an individual Ruby file:
+
+```ruby
+loader.load_file("#{__dir__}/custom_web_app/routes.rb")
+```
+
+This is useful when the loader is not eager loading the entire project, but you still need an individual file to be loaded for things to function properly.
+
+Both strings and `Pathname` objects are supported as arguments. The method raises `Zeitwerk::Error` if the argument is not a Ruby file, is [ignored](#ignoring-parts-of-the-project), is [shadowed](https://github.com/fxn/zeitwerk#shadowed-files), or is not managed by the receiver.
+
+`Zeitwerk::Loader#load_file` is idempotent, but compatible with reloading. If you load a file and then reload, a new call will load its (current) contents again.
+
+If you want to eager load a directory, `Zeitwerk::Loader#eager_load_dir` is more efficient than invoking `Zeitwerk::Loader#load_file` on its files.
+
 <a id="markdown-reloading" name="reloading"></a>
 ### Reloading
 
+<a id="markdown-configuration-and-usage" name="configuration-and-usage"></a>
+#### Configuration and usage
+
 Zeitwerk is able to reload code, but you need to enable this feature:
 
 ```ruby
@@ -494,7 +601,7 @@ loader.reload
 
 There is no way to undo this, either you want to reload or you don't.
 
-Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`.
+Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`. Attempting to reload without previously calling `setup` raises `Zeitwerk::SetupRequired`.
 
 Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, or services running in testing or production environments, won't normally have a use case for reloading. If reloading is not enabled, Zeitwerk is able to use less memory.
 
@@ -502,12 +609,34 @@ Reloading removes the currently loaded classes and modules and resets the loader
 
 It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
 
-Reloading is not thread-safe:
+<a id="markdown-thread-safety" name="thread-safety"></a>
+#### Thread-safety
+
+In order to reload safely, no other thread can be autoloading or reloading concurrently. Client code is responsible for this coordination.
+
+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"
+
+MyFramework::RELOAD_RW_LOCK = Concurrent::ReadWriteLock.new
+```
+
+You acquire the lock for reading for serving each individual request:
+
+```ruby
+MyFramework::RELOAD_RW_LOCK.with_read_lock do
+  serve(request)
+end
+```
 
-* You should not reload while another thread is reloading.
-* You should not autoload while another thread is reloading.
+Then, when a reload is triggered, just acquire the lock for writing in order to execute the method call safely:
 
-In order to reload in a thread-safe manner, frameworks need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible read/write lock: When a request comes in, the framework acquires the lock for reading at the beginning, and releases it at the end. On the other hand, the code in the framework responsible for the call to `Zeitwerk::Loader#reload` needs to acquire the lock for writing.
+```ruby
+MyFramework::RELOAD_RW_LOCK.with_write_lock do
+  loader.reload
+end
+```
 
 On reloading, client code has to update anything that would otherwise be storing a stale object. For example, if the routing layer of a web framework stores reloadable controller class objects or instances in internal structures, on reload it has to refresh them somehow, possibly reevaluating routes.
 
@@ -904,10 +1033,39 @@ loader.ignore(tests)
 loader.setup
 ```
 
+<a id="markdown-shadowed-files" name="shadowed-files"></a>
+### Shadowed files
+
+In Ruby, if you have several files called `foo.rb` in different directories of `$LOAD_PATH` and execute
+
+```ruby
+require "foo"
+```
+
+the first one found gets loaded, and the rest are ignored.
+
+Zeitwerk behaves in a similar way. If `foo.rb` is present in several root directories (at the same namespace level), the constant `Foo` is autoloaded from the first one, and the rest of the files are not evaluated. If logging is enabled, you'll see something like
+
+```
+file #{file} is ignored because #{previous_occurrence} has precedence
+```
+
+(This message is not public interface and may change, you cannot rely on that exact wording.)
+
+Even if there's only one `foo.rb`, if the constant `Foo` is already defined when Zeitwerk finds `foo.rb`, then the file is ignored too. This could happen if `Foo` was defined by a dependency, for example. If logging is enabled, you'll see something like
+
+```
+file #{file} is ignored because #{constant_path} is already defined
+```
+
+(This message is not public interface and may change, you cannot rely on that exact wording.)
+
+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
 
-A class or module that acts as a namespace:
+[Explicit namespaces](#explicit-namespaces) like `Trip` here:
 
 ```ruby
 # trip.rb
@@ -921,7 +1079,7 @@ module Trip::Geolocation
 end
 ```
 
-has to be defined with the `class` or `module` keywords, as in the example above.
+have to be defined with the `class`/`module` keywords, as in the example above.
 
 For technical reasons, raw constant assignment is not supported:
 
@@ -983,12 +1141,36 @@ require "active_job"
 require "active_job/queue_adapters"
 
 require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
+# 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)
 loader.setup
 ```
 
 With that, when Zeitwerk scans the file system and reaches the gem directories `lib/active_job` and `lib/active_job/queue_adapters`, it detects the corresponding modules already exist and therefore understands it does not have to manage them. The loader just descends into those directories. Eventually will reach `lib/active_job/queue_adapters/awesome_queue.rb`, and since `ActiveJob::QueueAdapters::AwesomeQueue` is unknown, Zeitwerk will manage it. Which is what happens regularly with the files in your gem. On reload, the namespaces are safe, won't be reloaded. The loader only reloads what it manages, which in this case is the adapter itself.
 
+<a id="markdown-introspection" name="introspection"></a>
+### Introspection
+
+The method `Zeitwerk::Loader#dirs` returns an array with the absolute paths of the root directories as strings:
+
+```ruby
+loader = Zeitwerk::Loader.new
+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 }
+```
+
+These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
+
 <a id="markdown-encodings" name="encodings"></a>
 ### Encodings
 

data/lib/zeitwerk/error.rb

@@ -12,4 +12,10 @@ module Zeitwerk
 
   class NameError < ::NameError
   end
+
+  class SetupRequired < Error
+    def initialize
+      super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
+    end
+  end
 end

data/lib/zeitwerk/explicit_namespace.rb

@@ -11,28 +11,28 @@ module Zeitwerk
   module ExplicitNamespace # :nodoc: all
     class << self
       include RealModName
+      extend Internal
 
       # Maps constant paths that correspond to explicit namespaces according to
       # the file system, to the loader responsible for them.
       #
-      # @private
       # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :cpaths
+      private :cpaths
 
-      # @private
       # @sig Mutex
       attr_reader :mutex
+      private :mutex
 
-      # @private
       # @sig TracePoint
       attr_reader :tracer
+      private :tracer
 
       # Asserts `cpath` corresponds to an explicit namespace for which `loader`
       # is responsible.
       #
-      # @private
       # @sig (String, Zeitwerk::Loader) -> void
-      def register(cpath, loader)
+      internal def register(cpath, loader)
         mutex.synchronize do
           cpaths[cpath] = loader
           # We check enabled? because, looking at the C source code, enabling an
@@ -41,24 +41,21 @@ module Zeitwerk
         end
       end
 
-      # @private
       # @sig (Zeitwerk::Loader) -> void
-      def unregister_loader(loader)
+      internal def unregister_loader(loader)
         cpaths.delete_if { |_cpath, l| l == loader }
         disable_tracer_if_unneeded
       end
 
-      private
-
       # @sig () -> void
-      def disable_tracer_if_unneeded
+      private def disable_tracer_if_unneeded
         mutex.synchronize do
           tracer.disable if cpaths.empty?
         end
       end
 
       # @sig (TracePoint) -> void
-      def tracepoint_class_callback(event)
+      private def tracepoint_class_callback(event)
         # If the class is a singleton class, we won't do anything with it so we
         # can bail out immediately. This is several orders of magnitude faster
         # than accessing its name.

data/lib/zeitwerk/gem_loader.rb

@@ -43,7 +43,7 @@ module Zeitwerk
         next if abspath == expected_namespace_dir
 
         basename_without_ext = basename.delete_suffix(".rb")
-        cname = inflector.camelize(basename_without_ext, abspath)
+        cname = inflector.camelize(basename_without_ext, abspath).to_sym
         ftype = dir?(abspath) ? "directory" : "file"
 
         warn(<<~EOS)

data/lib/zeitwerk/internal.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# This is a private module.
+module Zeitwerk::Internal
+  def internal(method_name)
+    private method_name
+
+    mangled = "__#{method_name}"
+    alias_method mangled, method_name
+    public mangled
+  end
+end

data/lib/zeitwerk/kernel.rb

@@ -19,6 +19,9 @@ module Kernel
   # included in Object, and changes in ancestors don't get propagated into
   # already existing ancestor chains on Ruby < 3.0.
   alias_method :zeitwerk_original_require, :require
+  class << self
+    alias_method :zeitwerk_original_require, :require
+  end
 
   # @sig (String) -> true | false
   def require(path)

data/lib/zeitwerk/loader/callbacks.rb

@@ -42,7 +42,7 @@ module Zeitwerk::Loader::Callbacks
     # Without the mutex and subsequent delete call, t2 would reset the module.
     # 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 lazy_subdirs entry.
+    # children, since t1 would have correctly deleted its namespace_dirs entry.
     mutex2.synchronize do
       if cref = autoloads.delete(dir)
         autovivified_module = cref[0].const_set(cref[1], Module.new)
@@ -71,9 +71,9 @@ module Zeitwerk::Loader::Callbacks
   # @private
   # @sig (Module) -> void
   def on_namespace_loaded(namespace)
-    if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
-      subdirs.each do |subdir|
-        set_autoloads_in_dir(subdir, namespace)
+    if dirs = namespace_dirs.delete(real_mod_name(namespace))
+      dirs.each do |dir|
+        set_autoloads_in_dir(dir, namespace)
       end
     end
   end