zeitwerk 2.6.18 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1fa60f08c282d8471eaf321deba97207ce56d2cba32619cff78f09e65f2f258
-  data.tar.gz: 1c803846848fc8830913acfd8fbf04bfa59f26c3c8806d4fa5bed9c751f48c5a
+  metadata.gz: 79a3e282ee7602f7d40c75c1299b24de4de890ee90a22cd37ed9c7a660936074
+  data.tar.gz: bd60115bc776137770e16ee527e4a07e815af547d1d5de851039e0187d50eff8
 SHA512:
-  metadata.gz: abb7134976f1ae00cafd77dcaa39fe2239632639c136d866ac75e55c8ec15f1c157ff0e434969dade286ee36e6422856799acd3e86dcd61e4ef39d1fd23909a4
-  data.tar.gz: 42e2309bd69f0bba3bfc74acecf2fcf3b3206a6cd26583afdc1012d34a063431bc03ec4ec42e1cf452f41bfa0de43a4d171cb2e99c7ca3e64b61412fbef83819
+  metadata.gz: ebdab4575a6e35591d1603ed11dc31f77eeffb15c8270f54719eb0850f3641efa968bebd8f02c32330ca768b8211d9aeb972fd41e0efac710faa023a0d62a841
+  data.tar.gz: 6d58d0256f35d6ac6445cba6619943aa4b3974905eb28588284f14aadd27304b1f11fc46d4f0905074c8888e52eabc03e312054930b702c875856d6c0a6a0694

data/README.md

@@ -54,7 +54,6 @@
     - [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)
@@ -63,7 +62,6 @@
     - [`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)
@@ -1178,36 +1176,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
 
@@ -1406,15 +1374,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
 

data/lib/zeitwerk/core_ext/module.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Zeitwerk::ConstAdded
+  def const_added(cname)
+    if loader = Zeitwerk::ExplicitNamespace.__loader_for(self, cname)
+      loader.on_namespace_loaded(const_get(cname, false))
+    end
+    super
+  end
+
+  Module.prepend(self)
+end

data/lib/zeitwerk/cref.rb

@@ -26,48 +26,14 @@ class Zeitwerk::Cref
     @path  = nil
   end
 
-  if Symbol.method_defined?(:name)
-    # Symbol#name was introduced in Ruby 3.0. It returns always the same
-    # frozen object, so we may save a few string allocations.
-    #
-    # @sig () -> String
-    def path
-      @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}"
-    end
-  else
-    # @sig () -> String
-    def path
-      @path ||= Object.equal?(@mod) ? @cname.to_s : "#{real_mod_name(@mod)}::#{@cname}"
-    end
+  # @sig () -> String
+  def path
+    @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
   end
 
-  # The autoload? predicate takes into account the ancestor chain of the
-  # receiver, like const_defined? and other methods in the constants API do.
-  #
-  # For example, given
-  #
-  #   class A
-  #     autoload :X, "x.rb"
-  #   end
-  #
-  #   class B < A
-  #   end
-  #
-  # B.autoload?(:X) returns "x.rb".
-  #
-  # We need a way to retrieve it ignoring ancestors.
-  #
   # @sig () -> String?
-  if method(:autoload?).arity == 1
-    # @sig () -> String?
-    def autoload?
-      @mod.autoload?(@cname) if self.defined?
-    end
-  else
-    # @sig () -> String?
-    def autoload?
-      @mod.autoload?(@cname, false)
-    end
+  def autoload?
+    @mod.autoload?(@cname, false)
   end
 
   # @sig (String) -> bool

data/lib/zeitwerk/explicit_namespace.rb

@@ -1,93 +1,84 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  # Centralizes the logic for the trace point used to detect the creation of
-  # explicit namespaces, needed to descend into matching subdirectories right
-  # after the constant has been defined.
+  # Centralizes the logic needed to descend into matching subdirectories right
+  # after the constant for an explicit namespace has been defined.
   #
   # The implementation assumes an explicit namespace is managed by one loader.
   # Loaders that reopen namespaces owned by other projects are responsible for
   # loading their constant before setup. This is documented.
   module ExplicitNamespace # :nodoc: all
+    # Maps cpaths of explicit namespaces with their corresponding loader.
+    # Entries are added as the namespaces are found, and removed as they are
+    # autoloaded.
+    #
+    # @sig Hash[String => Zeitwerk::Loader]
+    @cpaths = {}
+
     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.
-      #
-      # @sig Hash[String, Zeitwerk::Loader]
-      attr_reader :cpaths
-      private :cpaths
-
-      # @sig Mutex
-      attr_reader :mutex
-      private :mutex
-
-      # @sig TracePoint
-      attr_reader :tracer
-      private :tracer
-
-      # Asserts `cpath` corresponds to an explicit namespace for which `loader`
-      # is responsible.
+      # Registers `cpath` as being the constant path of an explicit namespace
+      # managed by `loader`.
       #
       # @sig (String, Zeitwerk::Loader) -> void
       internal def register(cpath, loader)
-        mutex.synchronize do
-          cpaths[cpath] = loader
-          # We check enabled? because, looking at the C source code, enabling an
-          # enabled tracer does not seem to be a simple no-op.
-          tracer.enable unless tracer.enabled?
-        end
+        @cpaths[cpath] = loader
+      end
+
+      # @sig (String) -> Zeitwerk::Loader?
+      internal def loader_for(mod, cname)
+        cpath = mod.equal?(Object) ? cname.name : "#{real_mod_name(mod)}::#{cname}"
+        @cpaths.delete(cpath)
       end
 
       # @sig (Zeitwerk::Loader) -> void
       internal def unregister_loader(loader)
-        cpaths.delete_if { |_cpath, l| l == loader }
-        disable_tracer_if_unneeded
+        @cpaths.delete_if { _2.equal?(loader) }
       end
 
       # This is an internal method only used by the test suite.
       #
-      # @sig (String) -> bool
+      # @sig (String) -> Zeitwerk::Loader?
       internal def registered?(cpath)
-        cpaths.key?(cpath)
+        @cpaths[cpath]
       end
 
+      # This is an internal method only used by the test suite.
+      #
       # @sig () -> void
-      private def disable_tracer_if_unneeded
-        mutex.synchronize do
-          tracer.disable if cpaths.empty?
-        end
+      internal def clear
+        @cpaths.clear
       end
 
-      # @sig (TracePoint) -> void
-      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.
-        return if event.self.singleton_class?
+      module Synchronized
+        extend Internal
+
+        MUTEX = Mutex.new
 
-        # It might be tempting to return if name.nil?, to avoid the computation
-        # of a hash code and delete call. But Ruby does not trigger the :class
-        # event on Class.new or Module.new, so that would incur in an extra call
-        # for nothing.
-        #
-        # On the other hand, if we were called, cpaths is not empty. Otherwise
-        # the tracer is disabled. So we do need to go ahead with the hash code
-        # computation and delete call.
-        if loader = cpaths.delete(real_mod_name(event.self))
-          loader.on_namespace_loaded(event.self)
-          disable_tracer_if_unneeded
+        internal def register(...)
+          MUTEX.synchronize { super }
         end
-      end
-    end
 
-    @cpaths = {}
-    @mutex  = Mutex.new
+        internal def loader_for(...)
+          MUTEX.synchronize { super }
+        end
+
+        internal def unregister_loader(...)
+          MUTEX.synchronize { super }
+        end
 
-    # We go through a method instead of defining a block mainly to have a better
-    # label when profiling.
-    @tracer = TracePoint.new(:class, &method(:tracepoint_class_callback))
+        internal def registered?(...)
+          MUTEX.synchronize { super }
+        end
+
+        internal def clear
+          MUTEX.synchronize { super }
+        end
+      end
+
+      prepend Synchronized unless RUBY_ENGINE == "ruby"
+    end
   end
 end

data/lib/zeitwerk/loader/callbacks.rb

@@ -6,6 +6,7 @@ module Zeitwerk::Loader::Callbacks
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
+  # @raise [Zeitwerk::NameError]
   # @sig (String) -> void
   internal def on_file_autoloaded(file)
     cref = autoloads.delete(file)
@@ -72,7 +73,7 @@ module Zeitwerk::Loader::Callbacks
   end
 
   # Invoked when a class or module is created or reopened, either from the
-  # tracer or from module autovivification. If the namespace has matching
+  # const_added or from module autovivification. If the namespace has matching
   # subdirectories, we descend into them now.
   #
   # @private

data/lib/zeitwerk/loader/helpers.rb

@@ -57,9 +57,7 @@ module Zeitwerk::Loader::Helpers
     to_visit = [dir]
 
     while (dir = to_visit.shift)
-      children = Dir.children(dir)
-
-      children.each do |basename|
+      Dir.each_child(dir) do |basename|
         next if hidden?(basename)
 
         abspath = File.join(dir, basename)

data/lib/zeitwerk/loader.rb

@@ -469,7 +469,7 @@ module Zeitwerk
           # Registering is idempotent, and we have to keep the autoload pointing
           # to the file. This may run again if more directories are found later
           # on, no big deal.
-          register_explicit_namespace(cref.path)
+          register_explicit_namespace(cref)
         end
         # If the existing autoload points to a file, it has to be preserved, if
         # not, it is fine as it is. In either case, we do not need to override.
@@ -515,8 +515,10 @@ module Zeitwerk
 
       log("earlier autoload for #{cref.path} discarded, it is actually an explicit namespace defined in #{file}") if logger
 
+      # Order matters: When Module#const_added is triggered by the autoload, we
+      # don't want the namespace to be registered yet.
       define_autoload(cref, file)
-      register_explicit_namespace(cref.path)
+      register_explicit_namespace(cref)
     end
 
     # @sig (Module, Symbol, String) -> void
@@ -549,9 +551,9 @@ module Zeitwerk
       end
     end
 
-    # @sig (String) -> void
-    private def register_explicit_namespace(cpath)
-      ExplicitNamespace.__register(cpath, self)
+    # @sig (Zeitwerk::Cref) -> void
+    private def register_explicit_namespace(cref)
+      ExplicitNamespace.__register(cref.path, self)
     end
 
     # @sig (String) -> void

data/lib/zeitwerk/real_mod_name.rb

@@ -10,13 +10,7 @@ module Zeitwerk::RealModName
   # The name method can be overridden, hence the indirection in this method.
   #
   # @sig (Module) -> String?
-  if UnboundMethod.method_defined?(:bind_call)
-    def real_mod_name(mod)
-      UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
-    end
-  else
-    def real_mod_name(mod)
-      UNBOUND_METHOD_MODULE_NAME.bind(mod).call
-    end
+  def real_mod_name(mod)
+    UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
   end
 end

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.6.18"
+  VERSION = "2.7.0"
 end

data/lib/zeitwerk.rb

@@ -11,10 +11,12 @@ module Zeitwerk
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
   require_relative "zeitwerk/null_inflector"
-  require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
   require_relative "zeitwerk/version"
 
+  require_relative "zeitwerk/core_ext/kernel"
+  require_relative "zeitwerk/core_ext/module"
+
   # This is a dangerous method.
   #
   # @experimental

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.18
+  version: 2.7.0
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-02 00:00:00.000000000 Z
+date: 2024-10-11 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -23,6 +23,8 @@ files:
 - MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
+- lib/zeitwerk/core_ext/kernel.rb
+- lib/zeitwerk/core_ext/module.rb
 - lib/zeitwerk/cref.rb
 - lib/zeitwerk/error.rb
 - lib/zeitwerk/explicit_namespace.rb
@@ -30,7 +32,6 @@ files:
 - lib/zeitwerk/gem_loader.rb
 - lib/zeitwerk/inflector.rb
 - lib/zeitwerk/internal.rb
-- lib/zeitwerk/kernel.rb
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
 - lib/zeitwerk/loader/config.rb
@@ -56,7 +57,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="