zeitwerk 2.5.0.beta4 → 2.5.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4012f73de9387546f477e8254668d450c00310666bde922b90a6b2be8d4b9740
-  data.tar.gz: 7c403df9ea53494c2eb1a01b3fb81f70ce1a6488a420728f134c7c32ab4cb444
+  metadata.gz: a57a618cc6c371488c6b2a1360b3bfb37b4914e7c44addd688dd9ff6d245f92b
+  data.tar.gz: 927300a0bec3a2941e79e3065068cb3359ced9a368a23204e31eb76c1de347bc
 SHA512:
-  metadata.gz: f2222619050df7f4271a73b2abdc258d541249ed34a75738afb1661ba17460dc2a0c53690f33a85e33b5925e28a6e2d292fa9d12711722261ae517d6d38f7520
-  data.tar.gz: 77679e246700480f751e0bce8373d5fe648a78f41a2b8bd97cc0d9c0bdff52651bd64be59ad56809b2785539fd7439f3b9ad554d9ddb8f668fbca9b187d51a24
+  metadata.gz: 2c26a751d80bcf719e2705c30c24e78300141b8cfe4a57e3bed2a9bf26e80534755a0fe067b6f32e6c1f4e7bbaf7693232640a76ff710e868c07f11128e9da6d
+  data.tar.gz: 270a9053e7ecccf58366272d6e60d2d3967d80f3d9777a0825700efcacf95e468a31c29924436df4231a53a971d31b0b4157d9f8bb8b82a91bd6fb6b2fdfb592

data/README.md

@@ -19,12 +19,15 @@
   - [Implicit namespaces](#implicit-namespaces)
   - [Explicit namespaces](#explicit-namespaces)
   - [Collapsing directories](#collapsing-directories)
+  - [Testing compliance](#testing-compliance)
 - [Usage](#usage)
   - [Setup](#setup)
     - [Generic](#generic)
     - [for_gem](#for_gem)
   - [Autoloading](#autoloading)
   - [Eager loading](#eager-loading)
+    - [Eager load exclusions](#eager-load-exclusions)
+    - [Global eager load](#global-eager-load)
   - [Reloading](#reloading)
   - [Inflection](#inflection)
     - [Zeitwerk::Inflector](#zeitwerkinflector)
@@ -42,9 +45,11 @@
     - [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)
   - [Edge cases](#edge-cases)
+  - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
+    - [debug.rb](#debugrb)
     - [Break](#break)
     - [Byebug](#byebug)
 - [Pronunciation](#pronunciation)
@@ -289,6 +294,23 @@ To illustrate usage of glob patterns, if `actions` in the example above is part
 loader.collapse("#{__dir__}/*/actions")
 ```
 
+<a id="markdown-testing-compliance" name="testing-compliance"></a>
+### Testing compliance
+
+When a managed file is loaded, Zeitwerk verifies the expected constant is defined. If it is not, `Zeitwerk::NameError` is raised.
+
+So, an easy way to ensure compliance in the test suite is to eager load the project:
+
+```ruby
+begin
+  loader.eager_load(force: true)
+rescue Zeitwerk::NameError => e
+  flunk e.message
+else
+  assert true
+end
+```
+
 <a id="markdown-usage" name="usage"></a>
 ## Usage
 
@@ -391,7 +413,16 @@ Zeitwerk instances are able to eager load their managed files:
 loader.eager_load
 ```
 
-That skips [ignored files and directories](#ignoring-parts-of-the-project), and you can also tell Zeitwerk that certain files or directories are autoloadable, but should not be eager loaded:
+That skips [ignored files and directories](#ignoring-parts-of-the-project).
+
+In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](https://github.com/fxn/zeitwerk#synopsis).
+
+Eager loading is synchronized and idempotent.
+
+<a id="markdown-eager-load-exclusions" name="eager-load-exclusions"></a>
+#### Eager load exclusions
+
+ You can tell Zeitwerk that certain files or directories are autoloadable, but should not be eager loaded:
 
 ```ruby
 db_adapters = "#{__dir__}/my_gem/db_adapters"
@@ -400,13 +431,20 @@ loader.setup
 loader.eager_load # won't eager load the database adapters
 ```
 
-In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](https://github.com/fxn/zeitwerk#synopsis).
+However, that can be overridden with `force`:
 
-Eager loading is synchronized and idempotent.
+```ruby
+loader.eager_load(force: true) # database adapters are eager loaded
+```
+
+Which may be handy if the project eager loads in the test suite to [ensure project layour compliance](#testing-compliance).
 
-If eager loading a file does not define the expected class or module, Zeitwerk raises `Zeitwerk::NameError`, which is a subclass of `NameError`.
+The `force` flag does not affect ignored files and directories, those are still ignored.
 
-If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
+<a id="markdown-global-eager-load" name="global-eager-load"></a>
+#### Global eager load
+
+If you want to eager load yourself and all dependencies that use Zeitwerk, you can broadcast the `eager_load` call to all instances:
 
 ```ruby
 Zeitwerk::Loader.eager_load_all
@@ -416,6 +454,8 @@ This may be handy in top-level services, like web applications.
 
 Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager load twice if any of the instances already eager loaded.
 
+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.
+
 <a id="markdown-reloading" name="reloading"></a>
 ### Reloading
 
@@ -642,6 +682,8 @@ There are use cases for this last catch-all callback, but they are rare. If you
 
 If both types of callbacks are defined, the specific ones run first.
 
+Since `on_load` callbacks are executed right after files are loaded, even if the loading context seems to be far away, in practice **the block is subject to [circular dependencies](#beware-of-circular-dependencies)**. As a rule of thumb, as far as loading order and its interdependencies is concerned, you have to program as if the block was executed at the bottom of the file just loaded.
+
 <a id="markdown-the-on_unload-callback" name="the-on_unload-callback"></a>
 #### The on_unload callback
 
@@ -854,6 +896,26 @@ Trip = Struct.new { ... } # 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
+
+In Ruby, you can't have certain top-level circular dependencies. Take for example:
+
+```ruby
+# c.rb
+class C < D
+end
+
+# d.rb
+class D
+  C
+end
+```
+
+In order to define `C`, you need to load `D`. However, the body of `D` refers to `C`.
+
+Circular dependencies like those do not work in plain Ruby, and therefore do not work in projects managed by Zeitwerk either.
+
 <a id="markdown-reopening-third-party-namespaces" name="reopening-third-party-namespaces"></a>
 ### Reopening third-party namespaces
 
@@ -908,6 +970,11 @@ With that, when Zeitwerk scans the file system and reaches the gem directories `
 <a id="markdown-debuggers" name="debuggers"></a>
 ### Debuggers
 
+<a id="markdown-debugrb" name="debugrb"></a>
+#### debug.rb
+
+The new [debug.rb](https://github.com/ruby/debug) gem and Zeitwerk seem to be compatible, as far as I can tell. This is the new debugger that is going to ship with Ruby 3.1.
+
 <a id="markdown-break" name="break"></a>
 #### Break
 
@@ -926,7 +993,11 @@ Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) are incompatib
 <a id="markdown-supported-ruby-versions" name="supported-ruby-versions"></a>
 ## Supported Ruby versions
 
-Zeitwerk works with MRI 2.4.4 and above.
+Zeitwerk works with CRuby 2.5 and above.
+
+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.)
+
+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.)
 
 <a id="markdown-testing" name="testing"></a>
 ## Testing

data/lib/zeitwerk/loader.rb

@@ -210,25 +210,28 @@ module Zeitwerk
     # Eager loads all files in the root directories, recursively. Files do not
     # need to be in `$LOAD_PATH`, absolute file names are used. Ignored files
     # are not eager loaded. You can opt-out specifically in specific files and
-    # directories with `do_not_eager_load`.
+    # directories with `do_not_eager_load`, and that can be overridden passing
+    # `force: true`.
     #
-    # @sig () -> void
-    def eager_load
+    # @sig (true | false) -> void
+    def eager_load(force: false)
       mutex.synchronize do
         break if @eager_loaded
 
         log("eager load start") if logger
 
+        honour_exclusions = !force
+
         queue = []
         actual_root_dirs.each do |root_dir, namespace|
-          queue << [namespace, root_dir] unless excluded_from_eager_load?(root_dir)
+          queue << [namespace, root_dir] unless honour_exclusions && excluded_from_eager_load?(root_dir)
         end
 
         while to_eager_load = queue.shift
           namespace, dir = to_eager_load
 
           ls(dir) do |basename, abspath|
-            next if excluded_from_eager_load?(abspath)
+            next if honour_exclusions && excluded_from_eager_load?(abspath)
 
             if ruby?(abspath)
               if cref = autoloads.cref_for(abspath)

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.5.0.beta4"
+  VERSION = "2.5.0.beta5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.5.0.beta4
+  version: 2.5.0.beta5
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-22 00:00:00.000000000 Z
+date: 2021-09-29 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem