zeitwerk 2.2.0 → 2.8.2

data/lib/zeitwerk/null_inflector.rb

@@ -0,0 +1,6 @@
+class Zeitwerk::NullInflector
+  #: (String, String) -> String
+  def camelize(basename, _abspath)
+    basename
+  end
+end

data/lib/zeitwerk/real_mod_name.rb

@@ -1,15 +1,19 @@
+# frozen_string_literal: true
+
 module Zeitwerk::RealModName
+  #: UnboundMethod
   UNBOUND_METHOD_MODULE_NAME = Module.instance_method(:name)
   private_constant :UNBOUND_METHOD_MODULE_NAME
 
-  # Returns the real name of the class or module, as set after the first
-  # constant to which it was assigned (or nil).
+  # Returns the real name of the class or module.
   #
-  # The name method can be overridden, hence the indirection in this method.
+  # We need this indirection because the `name` method can be overridden, and
+  # because in practice what we really need is the constant paths of modules
+  # with a permanent name, not so much what the user considers to be the name of
+  # a certain class or module of theirs.
   #
-  # @param mod [Class, Module]
-  # @return [String, nil]
+  #: (Module) -> String?
   def real_mod_name(mod)
-    UNBOUND_METHOD_MODULE_NAME.bind(mod).call
+    UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
   end
 end

data/lib/zeitwerk/registry/autoloads.rb

@@ -0,0 +1,38 @@
+module Zeitwerk::Registry
+  class Autoloads # :nodoc:
+    #: () -> void
+    def initialize
+      @autoloads = {} #: Hash[String, Zeitwerk::Loader]
+    end
+
+    #: (String, Zeitwerk::Loader) -> Zeitwerk::Loader
+    def register(abspath, loader)
+      @autoloads[abspath] = loader
+    end
+
+    #: (String) -> Zeitwerk::Loader?
+    def registered?(path)
+      @autoloads[path]
+    end
+
+    #: (String) -> Zeitwerk::Loader?
+    def unregister(abspath)
+      @autoloads.delete(abspath)
+    end
+
+    #: (Zeitwerk::Loader) -> void
+    def unregister_loader(loader)
+      @autoloads.delete_if { _2 == loader }
+    end
+
+    #: () -> bool
+    def empty? # for tests
+      @autoloads.empty?
+    end
+
+    #: () -> void
+    def clear # for tests
+      @autoloads.clear
+    end
+  end
+end

data/lib/zeitwerk/registry/explicit_namespaces.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Zeitwerk::Registry
+  # A registry for explicit namespaces.
+  #
+  # When a loader determines that a certain file should define an explicit
+  # namespace, it registers it here, associating its cref with itself.
+  #
+  # If the namespace is autoloaded, our const_added callback retrieves its
+  # loader by calling loader_for. That way, the loader is able to scan the
+  # subdirectories that conform the namespace and set autoloads for their
+  # expected constants just in time.
+  #
+  # Once autoloaded, the namespace is unregistered.
+  #
+  # 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.
+  #
+  # **This is a private module.**
+  class ExplicitNamespaces # :nodoc: all
+    #: () -> void
+    def initialize
+      # Maps crefs of explicit namespaces with their corresponding loader.
+      #
+      # Entries are added as the namespaces are found, and removed as they are
+      # autoloaded.
+      @loaders = Zeitwerk::Cref::Map.new
+    end
+
+    # Registers `cref` as being the constant path of an explicit namespace
+    # managed by `loader`.
+    #
+    #: (Zeitwerk::Cref, Zeitwerk::Loader) -> void
+    def register(cref, loader)
+      @loaders[cref] = loader
+    end
+
+    #: (Module, Symbol) -> Zeitwerk::Loader?
+    def loader_for(mod, cname)
+      @loaders.delete_mod_cname(mod, cname)
+    end
+
+    #: (Zeitwerk::Loader) -> void
+    def unregister_loader(loader)
+      @loaders.delete_by_value(loader)
+    end
+
+    # This is an internal method only used by the test suite.
+    #
+    #: (Zeitwerk::Cref) -> Zeitwerk::Loader?
+    def registered?(cref)
+      @loaders[cref]
+    end
+
+    #: () -> void
+    def clear # for tests
+      @loaders.clear
+    end
+  end
+end

data/lib/zeitwerk/registry/inceptions.rb

@@ -0,0 +1,31 @@
+module Zeitwerk::Registry
+  # Loaders know their own inceptions, but there is a use case in which we need
+  # to know if a given cpath is an inception globally. This is what this
+  # registry is for.
+  class Inceptions # :nodoc:
+    #: () -> void
+    def initialize
+      @inceptions = Zeitwerk::Cref::Map.new #: Zeitwerk::Cref::Map[String]
+    end
+
+    #: (Zeitwerk::Cref, String) -> void
+    def register(cref, abspath)
+      @inceptions[cref] = abspath
+    end
+
+    #: (Zeitwerk::Cref) -> String?
+    def registered?(cref)
+      @inceptions[cref]
+    end
+
+    #: (Zeitwerk::Cref) -> void
+    def unregister(cref)
+      @inceptions.delete(cref)
+    end
+
+    #: () -> void
+    def clear # for tests
+      @inceptions.clear
+    end
+  end
+end

data/lib/zeitwerk/registry/loaders.rb

@@ -0,0 +1,33 @@
+module Zeitwerk::Registry
+  class Loaders # :nodoc:
+    #: () -> void
+    def initialize
+      @loaders = [] #: Array[Zeitwerk::Loader]
+    end
+
+    #: ({ (Zeitwerk::Loader) -> void }) -> void
+    def each(&block)
+      @loaders.each(&block)
+    end
+
+    #: (Zeitwerk::Loader) -> void
+    def register(loader)
+      @loaders << loader
+    end
+
+    #: (Zeitwerk::Loader) -> Zeitwerk::Loader?
+    def unregister(loader)
+      @loaders.delete(loader)
+    end
+
+    #: (Zeitwerk::Loader) -> bool
+    def registered?(loader) # for tests
+      @loaders.include?(loader)
+    end
+
+    #: () -> void
+    def clear # for tests
+      @loaders.clear
+    end
+  end
+end

data/lib/zeitwerk/registry.rb

@@ -2,146 +2,88 @@
 
 module Zeitwerk
   module Registry # :nodoc: all
+    require_relative 'registry/autoloads'
+    require_relative 'registry/explicit_namespaces'
+    require_relative 'registry/inceptions'
+    require_relative 'registry/loaders'
+
     class << self
       # Keeps track of all loaders. Useful to broadcast messages and to prevent
       # them from being garbage collected.
       #
       # @private
-      # @return [<Zeitwerk::Loader>]
+      #: Zeitwerk::Registry::Loaders
       attr_reader :loaders
 
-      # Registers loaders created with `for_gem` to make the method idempotent
-      # in case of reload.
+      # Registers gem loaders to let `for_gem` be idempotent in case of reload.
       #
       # @private
-      # @return [{String => Zeitwerk::Loader}]
-      attr_reader :loaders_managing_gems
+      #: Hash[String, Zeitwerk::Loader]
+      attr_reader :gem_loaders_by_root_file
 
-      # Maps real paths to the loaders responsible for them.
+      # Maps absolute paths to the loaders responsible for them.
       #
       # This information is used by our decorated `Kernel#require` to be able to
       # invoke callbacks and autovivify modules.
       #
       # @private
-      # @return [{String => Zeitwerk::Loader}]
+      #: Zeitwerk::Registry::Autoloads
       attr_reader :autoloads
 
-      # This hash table addresses an edge case in which an autoload is ignored.
-      #
-      # For example, let's suppose we want to autoload in a gem like this:
-      #
-      #   # lib/my_gem.rb
-      #   loader = Zeitwerk::Loader.new
-      #   loader.push_dir(__dir__)
-      #   loader.setup
-      #
-      #   module MyGem
-      #   end
-      #
-      # if you require "my_gem", as Bundler would do, this happens while setting
-      # up autoloads:
-      #
-      #   1. Object.autoload?(:MyGem) returns `nil` because the autoload for
-      #      the constant is issued by Zeitwerk while the same file is being
-      #      required.
-      #   2. The constant `MyGem` is undefined while setup runs.
-      #
-      # Therefore, a directory `lib/my_gem` would autovivify a module according to
-      # the existing information. But that would be wrong.
-      #
-      # To overcome this fundamental limitation, we keep track of the constant
-      # paths that are in this situation ---in the example above, "MyGem"--- and
-      # take this collection into account for the autovivification logic.
-      #
-      # Note that you cannot generally address this by moving the setup code
-      # below the constant definition, because we want libraries to be able to
-      # use managed constants in the module body:
-      #
-      #   module MyGem
-      #     include MyConcern
-      #   end
-      #
       # @private
-      # @return [{String => (String, Zeitwerk::Loader)}]
-      attr_reader :inceptions
+      #: Zeitwerk::Registry::ExplicitNamespaces
+      attr_reader :explicit_namespaces
 
-      # Registers a loader.
-      #
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
-      def register_loader(loader)
-        loaders << loader
-      end
+      #: Zeitwerk::Registry::Inceptions
+      attr_reader :inceptions
 
-      # This method returns always a loader, the same instance for the same root
-      # file. That is how Zeitwerk::Loader.for_gem is idempotent.
-      #
       # @private
-      # @param root_file [String]
-      # @return [Zeitwerk::Loader]
-      def loader_for_gem(root_file)
-        loaders_managing_gems[root_file] ||= begin
-          Loader.new.tap do |loader|
-            loader.tag = File.basename(root_file, ".rb")
-            loader.inflector = GemInflector.new(root_file)
-            loader.push_dir(File.dirname(root_file))
-          end
-        end
+      #: (Zeitwerk::Loader) -> void
+      def unregister_loader(loader)
+        gem_loaders_by_root_file.delete_if { |_, l| l == loader }
       end
 
-      # @private
-      # @param loader [Zeitwerk::Loader]
-      # @param realpath [String]
-      # @return [void]
-      def register_autoload(loader, realpath)
-        autoloads[realpath] = loader
-      end
+      #: (Zeitwerk::Loader, String) -> Zeitwerk::Loader?
+      def conflicting_root_dir?(loader, new_root_dir)
+        @mutex.synchronize do
+          loaders.each do |existing_loader|
+            next if existing_loader == loader
 
-      # @private
-      # @param realpath [String]
-      # @return [void]
-      def unregister_autoload(realpath)
-        autoloads.delete(realpath)
-      end
+            existing_loader.__roots.each_key do |existing_root_dir|
+              # Conflicting directories are rare, optimize for the common case.
+              next if !new_root_dir.start_with?(existing_root_dir) && !existing_root_dir.start_with?(new_root_dir)
 
-      # @private
-      # @param cpath [String]
-      # @param realpath [String]
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
-      def register_inception(cpath, realpath, loader)
-        inceptions[cpath] = [realpath, loader]
-      end
+              new_root_dir_slash = new_root_dir + '/'
+              existing_root_dir_slash = existing_root_dir + '/'
+              next if !new_root_dir_slash.start_with?(existing_root_dir_slash) && !existing_root_dir_slash.start_with?(new_root_dir_slash)
 
-      # @private
-      # @param cpath [String]
-      # @return [String, nil]
-      def inception?(cpath)
-        if pair = inceptions[cpath]
-          pair.first
-        end
-      end
+              next if loader.__ignores?(existing_root_dir)
+              break if existing_loader.__ignores?(new_root_dir)
 
-      # @private
-      # @param path [String]
-      # @return [Zeitwerk::Loader, nil]
-      def loader_for(path)
-        autoloads[path]
+              return existing_loader
+            end
+          end
+
+          nil
+        end
       end
 
+      # This method returns always a loader, the same instance for the same root
+      # file. That is how Zeitwerk::Loader.for_gem is idempotent.
+      #
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
-      def on_unload(loader)
-        autoloads.delete_if { |_path, object| object == loader }
-        inceptions.delete_if { |_cpath, (_path, object)| object == loader }
+      #: (String, namespace: Module, warn_on_extra_files: boolish) -> Zeitwerk::Loader
+      def loader_for_gem(root_file, namespace:, warn_on_extra_files:)
+        gem_loaders_by_root_file[root_file] ||= GemLoader.__new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
       end
     end
 
-    @loaders               = []
-    @loaders_managing_gems = {}
-    @autoloads             = {}
-    @inceptions            = {}
+    @loaders                  = Loaders.new
+    @gem_loaders_by_root_file = {}
+    @autoloads                = Autoloads.new
+    @explicit_namespaces      = ExplicitNamespaces.new
+    @inceptions               = Inceptions.new
+    @mutex                    = Mutex.new
   end
 end

data/lib/zeitwerk/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.2.0"
+  #: String
+  VERSION = '2.8.2'
 end

data/lib/zeitwerk.rb

@@ -1,12 +1,29 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  require_relative "zeitwerk/real_mod_name"
-  require_relative "zeitwerk/loader"
-  require_relative "zeitwerk/registry"
-  require_relative "zeitwerk/explicit_namespace"
-  require_relative "zeitwerk/inflector"
-  require_relative "zeitwerk/gem_inflector"
-  require_relative "zeitwerk/kernel"
-  require_relative "zeitwerk/error"
+  require_relative 'zeitwerk/real_mod_name'
+  require_relative 'zeitwerk/internal'
+  require_relative 'zeitwerk/cref'
+  require_relative 'zeitwerk/loader'
+  require_relative 'zeitwerk/gem_loader'
+  require_relative 'zeitwerk/registry'
+  require_relative 'zeitwerk/inflector'
+  require_relative 'zeitwerk/gem_inflector'
+  require_relative 'zeitwerk/null_inflector'
+  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
+  #: () -> void
+  def self.with_loader
+    loader = Zeitwerk::Loader.new
+    yield loader
+  ensure
+    loader.unregister
+  end
 end

metadata

@@ -1,19 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.8.2
 platform: ruby
 authors:
 - Xavier Noria
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
       and application may have their own independent autoloader, with its own
-      configuration, inflector, and logger. Supports autoloading, preloading,
+      configuration, inflector, and logger. Supports autoloading,
       reloading, and eager loading.
 email: fxn@hashref.com
 executables: []
@@ -23,21 +22,38 @@ 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/cref/map.rb
 - lib/zeitwerk/error.rb
-- lib/zeitwerk/explicit_namespace.rb
 - lib/zeitwerk/gem_inflector.rb
+- lib/zeitwerk/gem_loader.rb
 - lib/zeitwerk/inflector.rb
-- lib/zeitwerk/kernel.rb
+- lib/zeitwerk/internal.rb
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
+- lib/zeitwerk/loader/config.rb
+- lib/zeitwerk/loader/constant_path_validator.rb
+- lib/zeitwerk/loader/eager_load.rb
+- lib/zeitwerk/loader/file_system.rb
+- lib/zeitwerk/loader/helpers.rb
+- lib/zeitwerk/null_inflector.rb
 - lib/zeitwerk/real_mod_name.rb
 - lib/zeitwerk/registry.rb
+- lib/zeitwerk/registry/autoloads.rb
+- lib/zeitwerk/registry/explicit_namespaces.rb
+- lib/zeitwerk/registry/inceptions.rb
+- lib/zeitwerk/registry/loaders.rb
 - lib/zeitwerk/version.rb
 homepage: https://github.com/fxn/zeitwerk
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/fxn/zeitwerk
+  changelog_uri: https://github.com/fxn/zeitwerk/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/fxn/zeitwerk
+  bug_tracker_uri: https://github.com/fxn/zeitwerk/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -45,15 +61,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.4
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader
 test_files: []

data/lib/zeitwerk/explicit_namespace.rb

@@ -1,80 +0,0 @@
-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.
-  #
-  # 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
-    class << self
-      include RealModName
-
-      # Maps constant paths that correspond to explicit namespaces according to
-      # the file system, to the loader responsible for them.
-      #
-      # @private
-      # @return [{String => Zeitwerk::Loader}]
-      attr_reader :cpaths
-
-      # @private
-      # @return [Mutex]
-      attr_reader :mutex
-
-      # @private
-      # @return [TracePoint]
-      attr_reader :tracer
-
-      # Asserts `cpath` corresponds to an explicit namespace for which `loader`
-      # is responsible.
-      #
-      # @private
-      # @param cpath [String]
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
-      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
-      end
-
-      # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
-      def unregister(loader)
-        cpaths.delete_if { |_cpath, l| l == loader }
-        disable_tracer_if_unneeded
-      end
-
-      def disable_tracer_if_unneeded
-        mutex.synchronize do
-          tracer.disable if cpaths.empty?
-        end
-      end
-
-      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?
-
-        # Note that it makes sense to compute the hash code unconditionally,
-        # because the trace point is disabled if cpaths is empty.
-        if loader = cpaths.delete(real_mod_name(event.self))
-          loader.on_namespace_loaded(event.self)
-          disable_tracer_if_unneeded
-        end
-      end
-    end
-
-    @cpaths = {}
-    @mutex  = Mutex.new
-
-    # 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))
-  end
-end

data/lib/zeitwerk/kernel.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Kernel
-  module_function
-
-  # We cannot decorate with prepend + super because Kernel has already been
-  # included in Object, and changes in ancestors don't get propagated into
-  # already existing ancestor chains.
-  alias_method :zeitwerk_original_require, :require
-
-  # @param path [String]
-  # @return [Boolean]
-  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
-      else
-        loader.on_dir_autoloaded(path)
-      end
-    else
-      zeitwerk_original_require(path).tap do |required|
-        if required
-          realpath = $LOADED_FEATURES.last
-          if loader = Zeitwerk::Registry.loader_for(realpath)
-            loader.on_file_autoloaded(realpath)
-          end
-        end
-      end
-    end
-  end
-end