zeitwerk 2.7.5 → 2.8.2

data/lib/zeitwerk/loader.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
-require "monitor"
-require "set"
+require 'monitor'
+require 'set'
 
 module Zeitwerk
   class Loader
-    require_relative "loader/helpers"
-    require_relative "loader/callbacks"
-    require_relative "loader/config"
-    require_relative "loader/eager_load"
-    require_relative "loader/file_system"
+    require_relative 'loader/helpers'
+    require_relative 'loader/callbacks'
+    require_relative 'loader/config'
+    require_relative 'loader/eager_load'
+    require_relative 'loader/file_system'
+    require_relative 'loader/constant_path_validator'
 
     extend Internal
 
@@ -22,8 +23,8 @@ module Zeitwerk
     # Maps absolute paths for which an autoload has been set ---and not
     # executed--- to their corresponding Zeitwerk::Cref object.
     #
-    #   "/Users/fxn/blog/app/models/user.rb"          => #<Zeitwerk::Cref:... @mod=Object, @cname=:User, ...>,
-    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => #<Zeitwerk::Cref:... @mod=Hotel, @cname=:Pricing, ...>,
+    #   '/Users/fxn/blog/app/models/user.rb'          => #<Zeitwerk::Cref:... @mod=Object, @cname=:User, ...>,
+    #   '/Users/fxn/blog/app/models/hotel/pricing.rb' => #<Zeitwerk::Cref:... @mod=Hotel, @cname=:Pricing, ...>,
     #   ...
     #
     #: Hash[String, Zeitwerk::Cref]
@@ -102,6 +103,7 @@ module Zeitwerk
     attr_reader :dirs_autoload_monitor
     private :dirs_autoload_monitor
 
+    #: () -> void
     def initialize
       super
 
@@ -114,6 +116,7 @@ module Zeitwerk
       @setup           = false
       @eager_loaded    = false
       @fs              = FileSystem.new(self)
+      @cpv             = ConstantPathValidator.new
 
       @mutex = Mutex.new
       @dirs_autoload_monitor = Monitor.new
@@ -129,7 +132,7 @@ module Zeitwerk
         break if @setup
 
         actual_roots.each do |root_dir, root_namespace|
-          define_autoloads_for_dir(root_dir, root_namespace)
+          define_autoloads_for_dir(root_dir, root_namespace, external: true)
         end
 
         on_setup_callbacks.each(&:call)
@@ -153,73 +156,79 @@ module Zeitwerk
     def unload
       mutex.synchronize do
         raise SetupRequired unless @setup
+        __unload
+      end
+    end
 
-        # 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 |abspath, cref|
-          if cref.autoload?
-            unload_autoload(cref)
-          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(cref)
-            unloaded_files.add(abspath) if @fs.rb_extension?(abspath)
-          end
-        end
-
-        to_unload.each do |abspath, cref|
-          unless on_unload_callbacks.empty?
-            begin
-              value = cref.get
-            rescue ::NameError
-              # Perhaps the user deleted the constant by hand, or perhaps an
-              # autoload failed to define the expected constant but the user
-              # rescued the exception.
-            else
-              run_on_unload_callbacks(cref, value, abspath)
-            end
-          end
+    # This is an internal method.
+    #
+    #: () -> void
+    def __unload
+      # 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 |abspath, cref|
+        if cref.autoload?
+          unload_autoload(cref)
+        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(cref)
           unloaded_files.add(abspath) if @fs.rb_extension?(abspath)
         end
+      end
 
-        unless unloaded_files.empty?
-          # Bootsnap decorates Kernel#require to speed it up using a cache and
-          # this optimization does not check if $LOADED_FEATURES has the file.
-          #
-          # To make it aware of changes, the gem defines singleton methods in
-          # $LOADED_FEATURES:
-          #
-          #   https://github.com/rails/bootsnap/blob/main/lib/bootsnap/load_path_cache/core_ext/loaded_features.rb
-          #
-          # 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) }
+      to_unload.each do |abspath, cref|
+        unless on_unload_callbacks.empty?
+          begin
+            value = cref.get
+          rescue ::NameError
+            # Perhaps the user deleted the constant by hand, or perhaps an
+            # autoload failed to define the expected constant but the user
+            # rescued the exception.
+          else
+            run_on_unload_callbacks(cref, value, abspath)
+          end
         end
 
-        autoloads.clear
-        autoloaded_dirs.clear
-        to_unload.clear
-        namespace_dirs.clear
-        shadowed_files.clear
+        unload_cref(cref)
+        unloaded_files.add(abspath) if @fs.rb_extension?(abspath)
+      end
 
-        unregister_inceptions
-        unregister_explicit_namespaces
+      unless unloaded_files.empty?
+        # Bootsnap decorates Kernel#require to speed it up using a cache and
+        # this optimization does not check if $LOADED_FEATURES has the file.
+        #
+        # To make it aware of changes, the gem defines singleton methods in
+        # $LOADED_FEATURES:
+        #
+        #   https://github.com/rails/bootsnap/blob/main/lib/bootsnap/load_path_cache/core_ext/loaded_features.rb
+        #
+        # 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) }
+      end
 
-        Registry.autoloads.unregister_loader(self)
+      autoloads.clear
+      autoloaded_dirs.clear
+      to_unload.clear
+      namespace_dirs.clear
+      shadowed_files.clear
 
-        @setup        = false
-        @eager_loaded = false
-      end
+      unregister_inceptions
+      unregister_explicit_namespaces
+
+      Registry.autoloads.unregister_loader(self)
+
+      @setup        = false
+      @eager_loaded = false
     end
 
     # Unloads all loaded code, and calls setup again so that the loader is able
@@ -234,8 +243,11 @@ module Zeitwerk
       raise SetupRequired unless @setup
 
       unload
+
       recompute_ignored_paths
       recompute_collapse_dirs
+      recompute_collapse_parents
+
       setup
     end
 
@@ -252,18 +264,20 @@ module Zeitwerk
         while (dir, cpath = queue.shift)
           result[dir] = cpath
 
-          prefix = cpath == "Object" ? "" : cpath + "::"
+          prefix = cpath == 'Object' ? '' : cpath + '::'
 
-          @fs.ls(dir) do |basename, abspath, ftype|
+          @fs.ls(dir, collapse: false) do |basename, abspath, ftype|
             if ftype == :file
-              basename.delete_suffix!(".rb")
-              result[abspath] = "#{prefix}#{cname_for(basename, abspath)}"
-            else
-              if collapse?(abspath)
-                queue << [abspath, cpath]
+              if basename == @nsfile
+                result[abspath] = cpath
               else
-                queue << [abspath, "#{prefix}#{cname_for(basename, abspath)}"]
+                basename.delete_suffix!('.rb')
+                result[abspath] = "#{prefix}#{cname_for(basename, abspath)}"
               end
+            elsif collapse?(abspath)
+              queue.unshift([abspath, cpath])
+            else
+              queue.push([abspath, "#{prefix}#{cname_for(basename, abspath)}"])
             end
           end
         end
@@ -285,11 +299,11 @@ module Zeitwerk
 
       paths = []
 
-      if :file == ftype
-        basename = File.basename(abspath, ".rb")
+      if ftype == :file
+        basename = File.basename(abspath)
         return if @fs.hidden?(basename)
 
-        paths << [basename, abspath]
+        paths << [basename.delete_suffix('.rb'), abspath] unless basename == @nsfile
         walk_up_from = File.dirname(abspath)
       else
         walk_up_from = abspath
@@ -315,9 +329,9 @@ module Zeitwerk
         cnames = paths.reverse_each.map { cname_for(_1, _2) }
 
         if root_namespace == Object
-          cnames.join("::")
+          cnames.join('::')
         else
-          "#{real_mod_name(root_namespace)}::#{cnames.join("::")}"
+          "#{real_mod_name(root_namespace)}::#{cnames.join('::')}"
         end
       end
     end
@@ -384,10 +398,10 @@ module Zeitwerk
 
       # This is a shortcut for
       #
-      #   require "zeitwerk"
+      #   require 'zeitwerk'
       #
       #   loader = Zeitwerk::Loader.new
-      #   loader.tag = File.basename(__FILE__, ".rb")
+      #   loader.tag = File.basename(__FILE__, '.rb')
       #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
       #   loader.push_dir(__dir__)
       #
@@ -405,10 +419,10 @@ module Zeitwerk
 
       # This is a shortcut for
       #
-      #   require "zeitwerk"
+      #   require 'zeitwerk'
       #
       #   loader = Zeitwerk::Loader.new
-      #   loader.tag = namespace.name + "-" + File.basename(__FILE__, ".rb")
+      #   loader.tag = namespace.name + '-' + File.basename(__FILE__, '.rb')
       #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
       #   loader.push_dir(__dir__, namespace: namespace)
       #
@@ -425,7 +439,7 @@ module Zeitwerk
         end
 
         unless real_mod_name(namespace)
-          raise Zeitwerk::Error, "extending anonymous namespaces is unsupported"
+          raise Zeitwerk::Error, 'extending anonymous namespaces is unsupported'
         end
 
         called_from = caller_locations(1, 1).first.path
@@ -473,68 +487,94 @@ module Zeitwerk
       end
     end
 
-    #: (String, Module) -> void
-    private def define_autoloads_for_dir(dir, parent)
+    # Scans `dir` and sets autoloads in `mod` for the constants its contents are
+    # expected to define.
+    #
+    # The `external` flag indicates whether `mod` has been externally defined,
+    # as is the case with root namespaces or reopened third-party namespaces.
+    #
+    #: (String, Module, external: boolish) -> void
+    private def define_autoloads_for_dir(dir, mod, external:)
       @fs.ls(dir) do |basename, abspath, ftype|
         if ftype == :file
-          basename.delete_suffix!(".rb")
-          cref = Cref.new(parent, cname_for(basename, abspath))
-          autoload_file(cref, abspath)
-        else
-          if collapse?(abspath)
-            define_autoloads_for_dir(abspath, parent)
-          else
-            cref = Cref.new(parent, cname_for(basename, abspath))
-            autoload_subdir(cref, abspath)
+          if basename == @nsfile
+            if external
+              cpath = real_mod_name(mod)
+              location = Object.const_source_location(cpath)&.join(':')
+              location = nil if location&.empty?
+              raise Zeitwerk::ConflictingNamespaceDefinitionError.new(cpath, location: location, conflicting_file: abspath)
+            end
+            next # Pass if this is a managed namespace, the nsfile was already probed when visiting the parent directory.
           end
+
+          basename.delete_suffix!('.rb')
+          cref = Cref.new(mod, cname_for(basename, abspath))
+          visit_file(cref, abspath)
+        else
+          cref = Cref.new(mod, cname_for(basename, abspath))
+          visit_subdir(cref, abspath, external:)
         end
       end
     end
 
     #: (Zeitwerk::Cref, String) -> void
-    private def autoload_subdir(cref, subdir)
+    private def visit_file(cref, file)
+      if autoload_path = cref.autoload? || Registry.inceptions.registered?(cref)
+        if @fs.rb_extension?(autoload_path)
+          if File.basename(autoload_path) == @nsfile && autoload_path_set_by_me_for?(cref)
+            raise Zeitwerk::ConflictingNamespaceDefinitionError.new(cref.path, location: autoload_path, conflicting_file: file)
+          end
+          shadowed_files << file
+          log { "file #{file} is ignored because #{autoload_path} has precedence" }
+        else
+          promote_namespace_from_implicit_to_explicit(dir: autoload_path, file: file, cref: cref)
+        end
+      elsif cref.defined?
+        shadowed_files << file
+        if location = cref.location
+          log { "file #{file} is ignored because #{cref} is already defined in #{location}" }
+        else
+          log { "file #{file} is ignored because #{cref} is already defined (unknown location)" }
+        end
+      else
+        define_autoload(cref, file)
+      end
+    end
+
+    #: (Zeitwerk::Cref, String, external: boolish) -> void
+    private def visit_subdir(cref, subdir, external:)
       if autoload_path = autoload_path_set_by_me_for?(cref)
         if @fs.rb_extension?(autoload_path)
+          # The namespace that corresponds to this subdirectory is defined in a
+          # file, either regular or nsfile. Therefore, a nsfile would be a
+          # duplication.
+          if nsfile_abspath = @fs.has_exactly_one_nsfile?(cref, subdir)
+            raise Zeitwerk::ConflictingNamespaceDefinitionError.new(cref.path, location: autoload_path, conflicting_file: nsfile_abspath)
+          end
           # Scanning visited a Ruby file first, and now a directory for the same
-          # constant has been found. This means we are dealing with an explicit
-          # namespace whose definition was seen first.
+          # constant has been found. This is an explicit namespace.
           #
-          # 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.
+          # The namespace may be spread over multiple directories and perhaps it
+          # was already registered, but registering is idempotent, just do it.
           register_explicit_namespace(cref)
+        elsif nsfile_abspath = @fs.has_exactly_one_nsfile?(cref, subdir)
+          # Scanning found a matching directory first, and now we saw a nsfile.
+          promote_namespace_from_implicit_to_explicit(dir: subdir, file: nsfile_abspath, cref: 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.
-        # Just remember the subdirectory conforms this namespace.
         namespace_dirs.get_or_set(cref) { [] } << subdir
       elsif !cref.defined?
-        # First time we find this namespace, set an autoload for it.
+        if nsfile_abspath = @fs.has_exactly_one_nsfile?(cref, subdir)
+          define_autoload(cref, nsfile_abspath)
+          register_explicit_namespace(cref)
+        else
+          define_autoload(cref, subdir)
+        end
         namespace_dirs.get_or_set(cref) { [] } << subdir
-        define_autoload(cref, subdir)
       else
         # For whatever reason the constant that corresponds to this namespace has
         # already been defined, we have to recurse.
         log { "the namespace #{cref} already exists, descending into #{subdir}" }
-        define_autoloads_for_dir(subdir, cref.get)
-      end
-    end
-
-    #: (Zeitwerk::Cref, String) -> void
-    private def autoload_file(cref, file)
-      if autoload_path = cref.autoload? || Registry.inceptions.registered?(cref)
-        # First autoload for a Ruby file wins, just ignore subsequent ones.
-        if @fs.rb_extension?(autoload_path)
-          shadowed_files << file
-          log { "file #{file} is ignored because #{autoload_path} has precedence" }
-        else
-          promote_namespace_from_implicit_to_explicit(dir: autoload_path, file: file, cref: cref)
-        end
-      elsif cref.defined?
-        shadowed_files << file
-        log { "file #{file} is ignored because #{cref} is already defined" }
-      else
-        define_autoload(cref, file)
+        define_autoloads_for_dir(subdir, cref.get, external:)
       end
     end
 
@@ -608,7 +648,7 @@ module Zeitwerk
     #: (String) -> void
     private def raise_if_conflicting_root_dir(root_dir)
       if loader = Registry.conflicting_root_dir?(self, root_dir)
-        require "pp" # Needed to have pretty_inspect available.
+        require 'pp' # Needed to have pretty_inspect available.
         raise Error,
           "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{root_dir}," \
           " which is already managed by\n\n#{loader.pretty_inspect}\n"

data/lib/zeitwerk/registry/loaders.rb

@@ -6,8 +6,8 @@ module Zeitwerk::Registry
     end
 
     #: ({ (Zeitwerk::Loader) -> void }) -> void
-    def each(&)
-      @loaders.each(&)
+    def each(&block)
+      @loaders.each(&block)
     end
 
     #: (Zeitwerk::Loader) -> void

data/lib/zeitwerk/registry.rb

@@ -2,10 +2,10 @@
 
 module Zeitwerk
   module Registry # :nodoc: all
-    require_relative "registry/autoloads"
-    require_relative "registry/explicit_namespaces"
-    require_relative "registry/inceptions"
-    require_relative "registry/loaders"
+    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
@@ -54,8 +54,8 @@ module Zeitwerk
               # 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)
 
-              new_root_dir_slash = new_root_dir + "/"
-              existing_root_dir_slash = existing_root_dir + "/"
+              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)
 
               next if loader.__ignores?(existing_root_dir)

data/lib/zeitwerk/version.rb

@@ -2,5 +2,5 @@
 
 module Zeitwerk
   #: String
-  VERSION = "2.7.5"
+  VERSION = '2.8.2'
 end

data/lib/zeitwerk.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  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/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"
+  require_relative 'zeitwerk/core_ext/kernel'
+  require_relative 'zeitwerk/core_ext/module'
 
   # This is a dangerous method.
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.7.5
+  version: 2.8.2
 platform: ruby
 authors:
 - Xavier Noria
@@ -34,6 +34,7 @@ files:
 - 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