zeitwerk 2.5.0.beta5 → 2.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a57a618cc6c371488c6b2a1360b3bfb37b4914e7c44addd688dd9ff6d245f92b
-  data.tar.gz: 927300a0bec3a2941e79e3065068cb3359ced9a368a23204e31eb76c1de347bc
+  metadata.gz: edfc3d6e8c62e95f5a008e6625b5b7f2ff7e0067e3d311ec352e1bf6c6922c27
+  data.tar.gz: 9087c6cc6524a8fd2b6843c283496e29cc5d9157421f6ba7994feb362f383333
 SHA512:
-  metadata.gz: 2c26a751d80bcf719e2705c30c24e78300141b8cfe4a57e3bed2a9bf26e80534755a0fe067b6f32e6c1f4e7bbaf7693232640a76ff710e868c07f11128e9da6d
-  data.tar.gz: 270a9053e7ecccf58366272d6e60d2d3967d80f3d9777a0825700efcacf95e468a31c29924436df4231a53a971d31b0b4157d9f8bb8b82a91bd6fb6b2fdfb592
+  metadata.gz: 4d31bf02d352d61024f553f21b14093bc4d8cfc9276c106e8a67b499044aaf12bdd076288c89828b342a1980f163706b62c82d9bd21c15cdc4cadacf117e5299
+  data.tar.gz: 89cc85a2efeb95760de195fc2acf854256dba89cdee2208992c33ba5d8cb78ad71adaddc757026660dbc4a2d562e1efa623572b91d2107e9cf30020ea83524ab

data/README.md

@@ -50,8 +50,8 @@
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
     - [debug.rb](#debugrb)
-    - [Break](#break)
     - [Byebug](#byebug)
+    - [Break](#break)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Testing](#testing)
@@ -810,7 +810,9 @@ Kernel.module_eval do
 end
 ```
 
-That file does not define a constant path after the path name and you need to tell Zeitwerk:
+`Kernel` is already defined by Ruby so the module cannot be autoloaded. Also, that file does not define a constant path after the path name. Therefore, Zeitwerk should not process it at all.
+
+The extension can still coexist with the rest of the project, you only need to tell Zeitwerk to ignore it:
 
 ```ruby
 kernel_ext = "#{__dir__}/my_gem/core_ext/kernel.rb"
@@ -826,6 +828,14 @@ loader.ignore(core_ext)
 loader.setup
 ```
 
+Now, that file has to be loaded manually with `require` or `require_relative`:
+
+```ruby
+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.
+
 <a id="markdown-use-case-the-adapter-pattern" name="use-case-the-adapter-pattern"></a>
 #### Use case: The adapter pattern
 
@@ -973,17 +983,19 @@ With that, when Zeitwerk scans the file system and reaches the gem directories `
 <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.
+The new [debug.rb](https://github.com/ruby/debug) gem and Zeitwerk are mostly compatible. This is the new debugger that is going to ship with Ruby 3.1.
 
-<a id="markdown-break" name="break"></a>
-#### Break
-
-Zeitwerk works fine with [@gsamokovarov](https://github.com/gsamokovarov)'s [Break](https://github.com/gsamokovarov/break) debugger.
+There's one exception, though: Due to a technical limitation of tracepoints, explicit namespaces are not autoloaded while expressions are evaluated in the REPL. See [ruby/debug#408](https://github.com/ruby/debug/issues/408).
 
 <a id="markdown-byebug" name="byebug"></a>
 #### Byebug
 
-Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) are incompatible, classes or modules that belong to [explicit namespaces](#explicit-namespaces) are not autoloaded inside a Byebug session. See [this issue](https://github.com/deivid-rodriguez/byebug/issues/564#issuecomment-499413606) for further details.
+Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) have a similar edge incompatibility.
+
+<a id="markdown-break" name="break"></a>
+#### Break
+
+Zeitwerk works fine with [@gsamokovarov](https://github.com/gsamokovarov)'s [Break](https://github.com/gsamokovarov/break) debugger.
 
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation

data/lib/zeitwerk/kernel.rb

@@ -24,22 +24,23 @@ module Kernel
   def require(path)
     if loader = Zeitwerk::Registry.loader_for(path)
       if path.end_with?(".rb")
-        zeitwerk_original_require(path).tap do |required|
-          loader.on_file_autoloaded(path) if required
-        end
+        required = zeitwerk_original_require(path)
+        loader.on_file_autoloaded(path) if required
+        required
       else
         loader.on_dir_autoloaded(path)
+        $LOADED_FEATURES << path
         true
       end
     else
-      zeitwerk_original_require(path).tap do |required|
-        if required
-          abspath = $LOADED_FEATURES.last
-          if loader = Zeitwerk::Registry.loader_for(abspath)
-            loader.on_file_autoloaded(abspath)
-          end
+      required = zeitwerk_original_require(path)
+      if required
+        abspath = $LOADED_FEATURES.last
+        if loader = Zeitwerk::Registry.loader_for(abspath)
+          loader.on_file_autoloaded(abspath)
         end
       end
+      required
     end
   end
 

data/lib/zeitwerk/loader/callbacks.rb

@@ -11,16 +11,19 @@ module Zeitwerk::Loader::Callbacks
     cref  = autoloads.delete(file)
     cpath = cpath(*cref)
 
+    # If reloading is enabled, we need to put this constant for unloading
+    # regardless of what cdef? says. In Ruby < 3.1 the internal state is not
+    # fully cleared. Module#constants still includes it, and you need to
+    # remove_const. See https://github.com/ruby/ruby/pull/4715.
     to_unload[cpath] = [file, cref] if reloading_enabled?
     Zeitwerk::Registry.unregister_autoload(file)
 
-    if logger && cdef?(*cref)
-      log("constant #{cpath} loaded from file #{file}")
-    elsif !cdef?(*cref)
+    if cdef?(*cref)
+      log("constant #{cpath} loaded from file #{file}") if logger
+      run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
+    else
       raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
     end
-
-    run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is

data/lib/zeitwerk/loader.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "set"
-require "securerandom"
 
 module Zeitwerk
   class Loader
@@ -14,22 +13,16 @@ module Zeitwerk
     include Helpers
     include Config
 
-    # Keeps track of autoloads defined by the loader which have not been
-    # executed so far.
+    # Maps absolute paths for which an autoload has been set ---and not
+    # executed--- to their corresponding parent class or module and constant
+    # name.
     #
-    # This metadata helps us implement a few things:
-    #
-    # 1. When autoloads are triggered, ensure they define the expected constant
-    #    and invoke user callbacks. If reloading is enabled, remember cref and
-    #    abspath for later unloading logic.
-    #
-    # 2. When unloading, remove autoloads that have not been executed.
-    #
-    # 3. Eager load with a recursive const_get, rather than a recursive require,
-    #    for consistency with lazy loading.
+    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
+    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
+    #   ...
     #
     # @private
-    # @sig Zeitwerk::Autoloads
+    # @sig Hash[String, [Module, Symbol]]
     attr_reader :autoloads
 
     # We keep track of autoloaded directories to remove them from the registry
@@ -87,7 +80,7 @@ module Zeitwerk
     def initialize
       super
 
-      @autoloads       = Autoloads.new
+      @autoloads       = {}
       @autoloaded_dirs = []
       @to_unload       = {}
       @lazy_subdirs    = Hash.new { |h, cpath| h[cpath] = [] }
@@ -130,23 +123,17 @@ module Zeitwerk
     # @sig () -> void
     def unload
       mutex.synchronize do
-        # We are going to keep track of the files that were required by our
-        # autoloads to later remove them from $LOADED_FEATURES, thus making them
-        # loadable by Kernel#require again.
-        #
-        # Directories are not stored in $LOADED_FEATURES, keeping track of files
-        # is enough.
-        unloaded_files = Set.new
-
-        autoloads.each do |(parent, cname), abspath|
+        abspaths_of_unloaded_crefs = Set.new
+
+        autoloads.each do |abspath, (parent, cname)|
           if parent.autoload?(cname)
             unload_autoload(parent, cname)
           else
             # Could happen if loaded with require_relative. That is unsupported,
             # and the constant path would escape unloadable_cpath? This is just
             # defensive code to clean things up as much as we are able to.
-            unload_cref(parent, cname)  if cdef?(parent, cname)
-            unloaded_files.add(abspath) if ruby?(abspath)
+            unload_cref(parent, cname)
+            abspaths_of_unloaded_crefs.add(abspath)
           end
         end
 
@@ -156,11 +143,15 @@ module Zeitwerk
             run_on_unload_callbacks(cpath, value, abspath)
           end
 
-          unload_cref(parent, cname)  if cdef?(parent, cname)
-          unloaded_files.add(abspath) if ruby?(abspath)
+          unload_cref(parent, cname)
+          abspaths_of_unloaded_crefs.add(abspath)
         end
 
-        unless unloaded_files.empty?
+        unless abspaths_of_unloaded_crefs.empty?
+          # We remove these abspaths from $LOADED_FEATURES because, otherwise,
+          # `require`'s idempotence would prevent newly defined autoloads from
+          # loading them again.
+          #
           # Bootsnap decorates Kernel#require to speed it up using a cache and
           # this optimization does not check if $LOADED_FEATURES has the file.
           #
@@ -172,7 +163,7 @@ module Zeitwerk
           # Rails applications may depend on bootsnap, so for unloading to work
           # in that setting it is preferable that we restrict our API choice to
           # one of those methods.
-          $LOADED_FEATURES.reject! { |file| unloaded_files.member?(file) }
+          $LOADED_FEATURES.reject! { |file| abspaths_of_unloaded_crefs.member?(file) }
         end
 
         autoloads.clear
@@ -234,7 +225,7 @@ module Zeitwerk
             next if honour_exclusions && excluded_from_eager_load?(abspath)
 
             if ruby?(abspath)
-              if cref = autoloads.cref_for(abspath)
+              if cref = autoloads[abspath]
                 cget(*cref)
               end
             elsif dir?(abspath) && !root_dirs.key?(abspath)
@@ -376,7 +367,7 @@ module Zeitwerk
 
     # @sig (Module, Symbol, String) -> void
     def autoload_subdir(parent, cname, subdir)
-      if autoload_path = autoloads.abspath_for(parent, cname)
+      if autoload_path = autoload_path_set_by_me_for?(parent, cname)
         cpath = cpath(parent, cname)
         register_explicit_namespace(cpath) if ruby?(autoload_path)
         # We do not need to issue another autoload, the existing one is enough
@@ -432,7 +423,7 @@ module Zeitwerk
 
     # @sig (Module, Symbol, String) -> void
     def set_autoload(parent, cname, abspath)
-      autoloads.define(parent, cname, abspath)
+      parent.autoload(cname, abspath)
 
       if logger
         if ruby?(abspath)
@@ -442,6 +433,7 @@ module Zeitwerk
         end
       end
 
+      autoloads[abspath] = [parent, cname]
       Registry.register_autoload(self, abspath)
 
       # See why in the documentation of Zeitwerk::Registry.inceptions.
@@ -450,6 +442,15 @@ module Zeitwerk
       end
     end
 
+    # @sig (Module, Symbol) -> String?
+    def autoload_path_set_by_me_for?(parent, cname)
+      if autoload_path = strict_autoload_path(parent, cname)
+        autoload_path if autoloads.key?(autoload_path)
+      else
+        Registry.inception?(cpath(parent, cname))
+      end
+    end
+
     # @sig (String) -> void
     def register_explicit_namespace(cpath)
       ExplicitNamespace.register(cpath, self)
@@ -494,7 +495,13 @@ module Zeitwerk
 
     # @sig (Module, Symbol) -> void
     def unload_cref(parent, cname)
+      # Let's optimistically remove_const. The way we use it, this is going to
+      # succeed always if all is good.
       parent.__send__(:remove_const, cname)
+    rescue ::NameError
+      # There are a few edge scenarios in which this may happen. If the constant
+      # is gone, that is OK, anyway.
+    else
       log("#{cpath(parent, cname)} unloaded") if logger
     end
   end

data/lib/zeitwerk/version.rb

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

data/lib/zeitwerk.rb

@@ -3,7 +3,6 @@
 module Zeitwerk
   require_relative "zeitwerk/real_mod_name"
   require_relative "zeitwerk/loader"
-  require_relative "zeitwerk/autoloads"
   require_relative "zeitwerk/registry"
   require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.5.0.beta5
+  version: 2.5.2
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-29 00:00:00.000000000 Z
+date: 2021-12-27 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -23,7 +23,6 @@ files:
 - MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
-- lib/zeitwerk/autoloads.rb
 - lib/zeitwerk/error.rb
 - lib/zeitwerk/explicit_namespace.rb
 - lib/zeitwerk/gem_inflector.rb
@@ -55,9 +54,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.2.22
 signing_key:

data/lib/zeitwerk/autoloads.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module Zeitwerk
-  # @private
-  class Autoloads
-    # Maps crefs for which an autoload has been defined to the corresponding
-    # absolute path.
-    #
-    #   [Object, :User]  => "/Users/fxn/blog/app/models/user.rb"
-    #   [Object, :Hotel] => "/Users/fxn/blog/app/models/hotel"
-    #   ...
-    #
-    # This colection is transient, callbacks delete its entries as autoloads get
-    # executed.
-    #
-    # @sig Hash[[Module, Symbol], String]
-    attr_reader :c2a
-
-    # This is the inverse of c2a, for inverse lookups.
-    #
-    # @sig Hash[String, [Module, Symbol]]
-    attr_reader :a2c
-
-    # @sig () -> void
-    def initialize
-      @c2a = {}
-      @a2c = {}
-    end
-
-    # @sig (Module, Symbol, String) -> void
-    def define(parent, cname, abspath)
-      parent.autoload(cname, abspath)
-      cref = [parent, cname]
-      c2a[cref] = abspath
-      a2c[abspath] = cref
-    end
-
-    # @sig () { () -> [[Module, Symbol], String] } -> void
-    def each(&block)
-      c2a.each(&block)
-    end
-
-    # @sig (Module, Symbol) -> String?
-    def abspath_for(parent, cname)
-      c2a[[parent, cname]]
-    end
-
-    # @sig (String) -> [Module, Symbol]?
-    def cref_for(abspath)
-      a2c[abspath]
-    end
-
-    # @sig (String) -> [Module, Symbol]?
-    def delete(abspath)
-      cref = a2c.delete(abspath)
-      c2a.delete(cref)
-      cref
-    end
-
-    # @sig () -> void
-    def clear
-      c2a.clear
-      a2c.clear
-    end
-
-    # @sig () -> bool
-    def empty?
-      c2a.empty? && a2c.empty?
-    end
-  end
-end