opal-zeitwerk 0.3.0 → 0.4.0

data/lib/opal/zeitwerk/version.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-module Opal
-  module Zeitwerk
-    VERSION = "0.3.0"
-  end
-end
+# frozen_string_literal: true
+module Opal
+  module Zeitwerk
+    VERSION = "0.4.0"
+  end
+end

data/lib/opal-zeitwerk.rb

@@ -1,4 +1,4 @@
-require 'opal'
-require 'opal/zeitwerk/version'
-
-Opal.append_path File.expand_path(File.join(File.dirname(__FILE__), '..', 'opal')).untaint
+require 'opal'
+require 'opal/zeitwerk/version'
+
+Opal.append_path File.expand_path(File.join(File.dirname(__FILE__), '..', 'opal')).untaint

data/opal/zeitwerk/error.rb

@@ -1,10 +1,10 @@
-module Zeitwerk
-  class Error < StandardError
-  end
-
-  class ReloadingDisabledError < Error
-  end
-
-  class NameError < ::NameError
-  end
-end
+module Zeitwerk
+  class Error < StandardError
+  end
+
+  class ReloadingDisabledError < Error
+  end
+
+  class NameError < ::NameError
+  end
+end

data/opal/zeitwerk/explicit_namespace.rb

@@ -1,71 +1,78 @@
-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 [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)
-        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
-
-      # @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
-        tracer.disable if cpaths.empty?
-      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 = {}
-
-    # 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
+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
+      # @sig Hash[String, Zeitwerk::Loader]
+      attr_reader :cpaths
+
+      # @private
+      # @sig TracePoint
+      attr_reader :tracer
+
+      # Asserts `cpath` corresponds to an explicit namespace for which `loader`
+      # is responsible.
+      #
+      # @private
+      # @sig (String, Zeitwerk::Loader) -> void
+      def register(cpath, loader)
+        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
+
+      # @private
+      # @sig (Zeitwerk::Loader) -> void
+      def unregister_loader(loader)
+        cpaths.delete_if { |_cpath, l| l == loader }
+        disable_tracer_if_unneeded
+      end
+
+      private
+
+      # @sig () -> void
+      def disable_tracer_if_unneeded
+        tracer.disable if cpaths.empty?
+      end
+
+      # @sig (TracePoint) -> void
+      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?
+
+        # 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
+        end
+      end
+    end
+
+    @cpaths = {}
+
+    # 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/opal/zeitwerk/gem_inflector.rb

@@ -0,0 +1,15 @@
+module Zeitwerk
+  class GemInflector < Inflector
+    # @sig (String) -> void
+    def initialize(root_file)
+      namespace     = File.basename(root_file, ".rb")
+      lib_dir       = File.dirname(root_file)
+      @version_file = File.join(lib_dir, namespace, "version")
+    end
+
+    # @sig (String, String) -> String
+    def camelize(basename, abspath)
+      abspath == @version_file ? "VERSION" : super
+    end
+  end
+end

data/opal/zeitwerk/inflector.rb

@@ -1,47 +1,44 @@
-module Zeitwerk
-  class Inflector
-    # Very basic snake case -> camel case conversion.
-    #
-    #   inflector = Zeitwerk::Inflector.new
-    #   inflector.camelize("post", ...)             # => "Post"
-    #   inflector.camelize("users_controller", ...) # => "UsersController"
-    #   inflector.camelize("api", ...)              # => "Api"
-    #
-    # Takes into account hard-coded mappings configured with `inflect`.
-    #
-    # @param basename [String]
-    # @param _abspath [String]
-    # @return [String]
-    def camelize(basename, _abspath)
-      overrides[basename] || basename.split('_').map!(&:capitalize).join
-    end
-
-    # Configures hard-coded inflections:
-    #
-    #   inflector = Zeitwerk::Inflector.new
-    #   inflector.inflect(
-    #     "html_parser"   => "HTMLParser",
-    #     "mysql_adapter" => "MySQLAdapter"
-    #   )
-    #
-    #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
-    #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
-    #   inflector.camelize("users_controller", abspath) # => "UsersController"
-    #
-    # @param inflections [{String => String}]
-    # @return [void]
-    def inflect(inflections)
-      overrides.merge!(inflections)
-    end
-
-    private
-
-    # Hard-coded basename to constant name user maps that override the default
-    # inflection logic.
-    #
-    # @return [{String => String}]
-    def overrides
-      @overrides ||= {}
-    end
-  end
-end
+module Zeitwerk
+  class Inflector
+    # Very basic snake case -> camel case conversion.
+    #
+    #   inflector = Zeitwerk::Inflector.new
+    #   inflector.camelize("post", ...)             # => "Post"
+    #   inflector.camelize("users_controller", ...) # => "UsersController"
+    #   inflector.camelize("api", ...)              # => "Api"
+    #
+    # Takes into account hard-coded mappings configured with `inflect`.
+    #
+    # @sig (String, String) -> String
+    def camelize(basename, _abspath)
+      overrides[basename] || basename.split('_').map!(&:capitalize).join
+    end
+
+    # Configures hard-coded inflections:
+    #
+    #   inflector = Zeitwerk::Inflector.new
+    #   inflector.inflect(
+    #     "html_parser"   => "HTMLParser",
+    #     "mysql_adapter" => "MySQLAdapter"
+    #   )
+    #
+    #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
+    #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
+    #   inflector.camelize("users_controller", abspath) # => "UsersController"
+    #
+    # @sig (Hash[String, String]) -> void
+    def inflect(inflections)
+      overrides.merge!(inflections)
+    end
+
+    private
+
+    # Hard-coded basename to constant name user maps that override the default
+    # inflection logic.
+    #
+    # @sig () -> Hash[String, String]
+    def overrides
+      @overrides ||= {}
+    end
+  end
+end

data/opal/zeitwerk/kernel.rb

@@ -1,32 +1,64 @@
-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)
-    path = `Opal.normalize(#{path})`
-    if loader = Zeitwerk::Registry.loader_for(path)
-      if `Opal.modules.hasOwnProperty(path)`
-        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
+module Kernel
+  module_function
+
+  # Zeitwerk's main idea is to define autoloads for project constants, and then
+  # intercept them when triggered in this thin `Kernel#require` wrapper.
+  #
+  # That allows us to complete the circle, invoke callbacks, autovivify modules,
+  # define autoloads for just autoloaded namespaces, update internal state, etc.
+  #
+  # On the other hand, if you publish a new version of a gem that is now managed
+  # by Zeitwerk, client code can reference directly your classes and modules and
+  # should not require anything. But if someone has legacy require calls around,
+  # they will work as expected, and in a compatible way. This feature is by now
+  # EXPERIMENTAL and UNDOCUMENTED.
+  #
+  # 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 on Ruby < 3.0.
+  alias_method :zeitwerk_original_require, :require
+
+  # @sig (String) -> true | false
+  def require(path)
+    path = `Opal.normalize(#{path})`
+    if loader = Zeitwerk::Registry.loader_for(path)
+      if `Opal.modules.hasOwnProperty(path)`
+        required = zeitwerk_original_require(path)
+        loader.on_file_autoloaded(path) if required
+        required
+      else
+        loader.on_dir_autoloaded(path)
+        true
+      end
+    else
+      required = zeitwerk_original_require(path)
+      if required
+        realpath = $LOADED_FEATURES.last
+        if loader = Zeitwerk::Registry.loader_for(realpath)
+          loader.on_file_autoloaded(realpath)
+        end
+      end
+      required
+    end
+  end
+
+  # By now, I have seen no way so far to decorate require_relative.
+  #
+  # For starters, at least in CRuby, require_relative does not delegate to
+  # require. Both require and require_relative delegate the bulk of their work
+  # to an internal C function called rb_require_safe. So, our require wrapper is
+  # not executed.
+  #
+  # On the other hand, we cannot use the aliasing technique above because
+  # require_relative receives a path relative to the directory of the file in
+  # which the call is performed. If a wrapper here invoked the original method,
+  # Ruby would resolve the relative path taking lib/zeitwerk as base directory.
+  #
+  # A workaround could be to extract the base directory from caller_locations,
+  # but what if someone else decorated require_relative before us? You can't
+  # really know with certainty where's the original call site in the stack.
+  #
+  # However, the main use case for require_relative is to load files from your
+  # own project. Projects managed by Zeitwerk don't do this for files managed by
+  # Zeitwerk, precisely.
+end

data/opal/zeitwerk/loader/callbacks.rb

@@ -1,58 +1,88 @@
-module Zeitwerk::Loader::Callbacks
-  include Zeitwerk::RealModName
-
-  # Invoked from our decorated Kernel#require when a managed file is autoloaded.
-  #
-  # @private
-  # @param file [String]
-  # @return [void]
-  def on_file_autoloaded(file)
-    cref = autoloads.delete(file)
-    to_unload[cpath(*cref)] = [file, cref] if reloading_enabled?
-    Zeitwerk::Registry.unregister_autoload(file)
-
-    # "constant #{cpath(*cref)} loaded from file #{file}" if cdef?(*cref)
-    if !cdef?(*cref)
-      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath(*cref)}, but didn't", cref.last)
-    end
-  end
-
-  # Invoked from our decorated Kernel#require when a managed directory is
-  # autoloaded.
-  #
-  # @private
-  # @param dir [String]
-  # @return [void]
-  def on_dir_autoloaded(dir)
-    if cref = autoloads.delete(dir)
-      autovivified_module = cref[0].const_set(cref[1], Module.new)
-
-      # "module #{autovivified_module.name} autovivified from directory #{dir}"
-
-      to_unload[autovivified_module.name] = [dir, cref] if reloading_enabled?
-
-      # We don't unregister `dir` in the registry because concurrent threads
-      # wouldn't find a loader associated to it in Kernel#require and would
-      # try to require the directory. Instead, we are going to keep track of
-      # these to be able to unregister later if eager loading.
-      autoloaded_dirs << dir
-
-      on_namespace_loaded(autovivified_module)
-    end
-  end
-
-  # Invoked when a class or module is created or reopened, either from the
-  # tracer or from module autovivification. If the namespace has matching
-  # subdirectories, we descend into them now.
-  #
-  # @private
-  # @param namespace [Module]
-  # @return [void]
-  def on_namespace_loaded(namespace)
-    if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
-      subdirs.each do |subdir|
-        set_autoloads_in_dir(subdir, namespace)
-      end
-    end
-  end
-end
+module Zeitwerk::Loader::Callbacks
+  include Zeitwerk::RealModName
+
+  # Invoked from our decorated Kernel#require when a managed file is autoloaded.
+  #
+  # @private
+  # @sig (String) -> void
+  def on_file_autoloaded(file)
+    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 cdef?(*cref)
+      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
+  end
+
+  # Invoked from our decorated Kernel#require when a managed directory is
+  # autoloaded.
+  #
+  # @private
+  # @sig (String) -> void
+  def on_dir_autoloaded(dir)
+    # Module#autoload does not serialize concurrent requires, and we handle
+    # directories ourselves, so the callback needs to account for concurrency.
+    #
+    # Multi-threading would introduce a race condition here in which thread t1
+    # autovivifies the module, and while autoloads for its children are being
+    # set, thread t2 autoloads the same namespace.
+    #
+    # Without the mutex and subsequent delete call, t2 would reset the module.
+    # That not only would reassign the constant (undesirable per se) but, worse,
+    # the module object created by t2 wouldn't have any of the autoloads for its
+    # children, since t1 would have correctly deleted its lazy_subdirs entry.
+
+    # Well, on Opal no mutexes.
+    if cref = autoloads.delete(dir)
+      autovivified_module = cref[0].const_set(cref[1], Module.new)
+      cpath = autovivified_module.name
+
+      to_unload[cpath] = [dir, cref] if reloading_enabled?
+
+      # We don't unregister `dir` in the registry because concurrent threads
+      # wouldn't find a loader associated to it in Kernel#require and would
+      # try to require the directory. Instead, we are going to keep track of
+      # these to be able to unregister later if eager loading.
+      autoloaded_dirs << dir
+
+      on_namespace_loaded(autovivified_module)
+
+      run_on_load_callbacks(cpath, autovivified_module, dir) unless on_load_callbacks.empty?
+    end
+  end
+
+  # Invoked when a class or module is created or reopened, either from the
+  # tracer or from module autovivification. If the namespace has matching
+  # subdirectories, we descend into them now.
+  #
+  # @private
+  # @sig (Module) -> void
+  def on_namespace_loaded(namespace)
+    if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
+      subdirs.each do |subdir|
+        set_autoloads_in_dir(subdir, namespace)
+      end
+    end
+  end
+
+  private
+
+  # @sig (String, Object) -> void
+  def run_on_load_callbacks(cpath, value, abspath)
+    # Order matters. If present, run the most specific one.
+    callbacks = reloading_enabled? ? on_load_callbacks[cpath] : on_load_callbacks.delete(cpath)
+    callbacks&.each { |c| c.call(value, abspath) }
+
+    callbacks = on_load_callbacks[:ANY]
+    callbacks&.each { |c| c.call(cpath, value, abspath) }
+  end
+end