opal-zeitwerk 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52b397fd96aa14fd2b196f67db7325010a66d7fb3fd94623d3ed4b957be1181c
-  data.tar.gz: 4e1e32b7c582f1280f7c81c1c7ccbb69091521c0b6f0e1d73d832d1f845b689d
+  metadata.gz: 12375dd273e0ad8de57a3743951866692f94b85f8c9b8a3d0913d85fb19e6448
+  data.tar.gz: b4c8ad57b55115bd275a1006649be4f685db42a3bff85a41ed8a3eabcf88db13
 SHA512:
-  metadata.gz: 436625b6e442aa157c064e6a51501b743d7b419900bb085771411f8c174bdf7ed35c2b79da1eb67f6a50c17f232178b5045545e8d1b70ead2d759ff406588733
-  data.tar.gz: 047c69f853ecac1960a85f2dfd4f608f188cd47cb52ce6a6571ab63c55e6d49a92c6775e22240cf5a6a991726057f94b43608d4b65a5f68723bc946deca0b89e
+  metadata.gz: '012259b3e3b242baa7e372439257c07db34abe59c4b45f1bdd927a9a6cfe91e9084d383f8f16fb356eebff90a7d193b1b2e56ff353b325f71ff87dd24c7da144'
+  data.tar.gz: 9073faf1c136072053b80d0d531494fd95a885cb4013aff5926dad8f630bac705ce21875e270c15d6131575dbf2d1745dfc064791a7e441e31c0b80eef284d5d

data/lib/opal-zeitwerk.rb

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

data/lib/opal/zeitwerk/version.rb

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

data/opal/zeitwerk.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+require 'opal'
+require 'corelib/trace_point'
+require 'securerandom'
+
+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/kernel"
+  require_relative "zeitwerk/error"
+end

data/opal/zeitwerk/error.rb

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

data/opal/zeitwerk/explicit_namespace.rb

@@ -0,0 +1,71 @@
+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

data/opal/zeitwerk/inflector.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+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

data/opal/zeitwerk/kernel.rb

@@ -0,0 +1,33 @@
+# 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 `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

data/opal/zeitwerk/loader.rb

@@ -0,0 +1,731 @@
+# frozen_string_literal: true
+
+require "set"
+require "securerandom"
+
+module Zeitwerk
+  class Loader
+    require_relative "loader/callbacks"
+    include Callbacks
+    include RealModName
+
+    # @return [String]
+    attr_reader :tag
+
+    # @return [#camelize]
+    attr_accessor :inflector
+
+    # Absolute paths of the root directories. Stored in a hash to preserve
+    # order, easily handle duplicates, and also be able to have a fast lookup,
+    # needed for detecting nested paths.
+    #
+    #   "/Users/fxn/blog/app/assets"   => true,
+    #   "/Users/fxn/blog/app/channels" => true,
+    #   ...
+    #
+    # This is a private collection maintained by the loader. The public
+    # interface for it is `push_dir` and `dirs`.
+    #
+    # @private
+    # @return [{String => true}]
+    attr_reader :root_dirs
+
+    # Absolute paths of files or directories that have to be preloaded.
+    #
+    # @private
+    # @return [<String>]
+    attr_reader :preloads
+
+    # Absolute paths of files, directories, of glob patterns to be totally
+    # ignored.
+    #
+    # @private
+    # @return [Set<String>]
+    attr_reader :ignored_glob_patterns
+
+    # The actual collection of absolute file and directory names at the time the
+    # ignored glob patterns were expanded. Computed on setup, and recomputed on
+    # reload.
+    #
+    # @private
+    # @return [Set<String>]
+    attr_reader :ignored_paths
+
+    # Maps real absolute paths for which an autoload has been set ---and not
+    # executed--- to their corresponding parent class or module and constant
+    # name.
+    #
+    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
+    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
+    #   ...
+    #
+    # @private
+    # @return [{String => (Module, Symbol)}]
+    attr_reader :autoloads
+
+    # We keep track of autoloaded directories to remove them from the registry
+    # at the end of eager loading.
+    #
+    # Files are removed as they are autoloaded, but directories need to wait due
+    # to concurrency (see why in Zeitwerk::Loader::Callbacks#on_dir_autoloaded).
+    #
+    # @private
+    # @return [<String>]
+    attr_reader :autoloaded_dirs
+
+    # Stores metadata needed for unloading. Its entries look like this:
+    #
+    #   "Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
+    #
+    # The cpath as key helps implementing unloadable_cpath? The real file name
+    # is stored in order to be able to delete it from $LOADED_FEATURES, and the
+    # pair [Module, Symbol] is used to remove_const the constant from the class
+    # or module object.
+    #
+    # If reloading is enabled, this hash is filled as constants are autoloaded
+    # or eager loaded. Otherwise, the collection remains empty.
+    #
+    # @private
+    # @return [{String => (String, (Module, Symbol))}]
+    attr_reader :to_unload
+
+    # Maps constant paths of namespaces to arrays of corresponding directories.
+    #
+    # For example, given this mapping:
+    #
+    #   "Admin" => [
+    #     "/Users/fxn/blog/app/controllers/admin",
+    #     "/Users/fxn/blog/app/models/admin",
+    #     ...
+    #   ]
+    #
+    # when `Admin` gets defined we know that it plays the role of a namespace and
+    # that its children are spread over those directories. We'll visit them to set
+    # up the corresponding autoloads.
+    #
+    # @private
+    # @return [{String => <String>}]
+    attr_reader :lazy_subdirs
+
+    # Absolute paths of files or directories not to be eager loaded.
+    #
+    # @private
+    # @return [Set<String>]
+    attr_reader :eager_load_exclusions
+
+    attr_accessor :vivify_mod_dir
+    attr_accessor :vivify_mod_class
+
+    def initialize
+      @initialized_at = Time.now
+
+      @tag       = SecureRandom.hex(3)
+      @inflector = Inflector.new
+
+      @root_dirs             = {}
+      @preloads              = []
+      @ignored_glob_patterns = Set.new
+      @ignored_paths         = Set.new
+      @autoloads             = {}
+      @autoloaded_dirs       = []
+      @to_unload             = {}
+      @lazy_subdirs          = {}
+      @eager_load_exclusions = Set.new
+      
+      @setup        = false
+      @eager_loaded = false
+
+      @reloading_enabled = false
+
+      @vivify_mod_dir = false
+      @module_paths
+
+      Registry.register_loader(self)
+    end
+
+    # Sets a tag for the loader, useful for logging.
+    #
+    # @return [void]
+    def tag=(tag)
+      @tag = tag.to_s
+    end
+
+    # Absolute paths of the root directories. This is a read-only collection,
+    # please push here via `push_dir`.
+    #
+    # @return [<String>]
+    def dirs
+      root_dirs.keys.freeze
+    end
+
+    # Pushes `path` to the list of root directories.
+    #
+    # Raises `Zeitwerk::Error` if `path` does not exist, or if another loader in
+    # the same process already manages that directory or one of its ascendants
+    # or descendants.
+    #
+    # @param path [<String, Pathname>]
+    # @raise [Zeitwerk::Error]
+    # @return [void]
+    def push_dir(path)
+      abspath = File.expand_path(path)
+      if dir?(abspath)
+        raise_if_conflicting_directory(abspath)
+        root_dirs[abspath] = true
+      else
+        warn_string = "Zeitwerk: the root path #{abspath} does not exist, not added"
+        `console.warn(warn_string)`
+      end
+    end
+
+    # You need to call this method before setup in order to be able to reload.
+    # There is no way to undo this, either you want to reload or you don't.
+    #
+    # @raise [Zeitwerk::Error]
+    # @return [void]
+    def enable_reloading
+      return if @reloading_enabled
+
+      if @setup
+        raise Error, "cannot enable reloading after setup"
+      else
+        @reloading_enabled = true
+      end
+    end
+
+    # @return [Boolean]
+    def reloading_enabled?
+      @reloading_enabled
+    end
+
+    # Files or directories to be preloaded instead of lazy loaded.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def preload(*paths)
+      expand_paths(paths).each do |abspath|
+        preloads << abspath
+        do_preload_abspath(abspath) if @setup
+      end
+    end
+
+    # Configure files, directories, or glob patterns to be totally ignored.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def ignore(*glob_patterns)
+      glob_patterns = expand_paths(glob_patterns)
+      ignored_glob_patterns.merge(glob_patterns)
+      ignored_paths.merge(expand_glob_patterns(glob_patterns))
+    end
+
+    # Sets autoloads in the root namespace and preloads files, if any.
+    #
+    # @return [void]
+    def setup
+      return if @setup
+
+      actual_root_dirs.each { |root_dir| set_autoloads_in_dir(root_dir, Object) }
+      do_preload
+
+      @setup = true
+    end
+
+    # Removes loaded constants and configured autoloads.
+    #
+    # The objects the constants stored are no longer reachable through them. In
+    # addition, since said objects are normally not referenced from anywhere
+    # else, they are eligible for garbage collection, which would effectively
+    # unload them.
+    #
+    # @private
+    # @return [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 |realpath, (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(realpath) if ruby?(realpath)
+        end
+      end
+
+      to_unload.each_value do |(realpath, (parent, cname))|
+        unload_cref(parent, cname)   if cdef?(parent, cname)
+        unloaded_files.add(realpath) if ruby?(realpath)
+      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/Shopify/bootsnap/blob/master/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
+
+      autoloads.clear
+      autoloaded_dirs.clear
+      to_unload.clear
+      lazy_subdirs.clear
+
+      Registry.on_unload(self)
+      ExplicitNamespace.unregister(self)
+
+      @setup = false
+    end
+
+    # Unloads all loaded code, and calls setup again so that the loader is able
+    # to pick any changes in the file system.
+    #
+    # This method is not thread-safe, please see how this can be achieved by
+    # client code in the README of the project.
+    #
+    # @raise [Zeitwerk::Error]
+    # @return [void]
+    def reload
+      if reloading_enabled?
+        unload
+        recompute_ignored_paths
+        setup
+      else
+        raise ReloadingDisabledError, "can't reload, please call loader.enable_reloading before setup"
+      end
+    end
+
+    # Eager loads all files in the root directories, recursively. Files do not
+    # need to be in `$LOAD_PATH`, absolute file names are used. Ignored files
+    # are not eager loaded. You can opt-out specifically in specific files and
+    # directories with `do_not_eager_load`.
+    #
+    # @return [void]
+    def eager_load
+      return if @eager_loaded
+
+      queue = actual_root_dirs.reject { |dir| eager_load_exclusions.member?(dir) }
+      queue.map! { |dir| [Object, dir] }
+      while to_eager_load = queue.shift
+        namespace, dir = to_eager_load
+
+        ls(dir) do |basename, abspath|
+          next if eager_load_exclusions.member?(abspath)
+
+          if ruby?(abspath)
+            if cref = autoloads[File.realpath(abspath)]
+              cref[0].const_get(cref[1], false)
+            end
+          elsif dir?(abspath) && !root_dirs.key?(abspath)
+            cname = inflector.camelize(basename, abspath)
+            queue << [namespace.const_get(cname, false), abspath]
+          end
+        end
+      end
+
+      autoloaded_dirs.each do |autoloaded_dir|
+        Registry.unregister_autoload(autoloaded_dir)
+      end
+      autoloaded_dirs.clear
+
+      @eager_loaded = true
+    end
+
+    # Let eager load ignore the given files or directories. The constants
+    # defined in those files are still autoloadable.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def do_not_eager_load(*paths)
+      eager_load_exclusions.merge(expand_paths(paths))
+    end
+
+    # Says if the given constant path would be unloaded on reload. This
+    # predicate returns `false` if reloading is disabled.
+    #
+    # @param cpath [String]
+    # @return [Boolean]
+    def unloadable_cpath?(cpath)
+      to_unload.key?(cpath)
+    end
+
+    # Returns an array with the constant paths that would be unloaded on reload.
+    # This predicate returns an empty array if reloading is disabled.
+    #
+    # @return [<String>]
+    def unloadable_cpaths
+      to_unload.keys.freeze
+    end
+
+    # @private
+    # @param dir [String]
+    # @return [Boolean]
+    def manages?(dir)
+      dir = dir + "/"
+      ignored_paths.each do |ignored_path|
+        return false if dir.start_with?(ignored_path + "/")
+      end
+
+      root_dirs.each_key do |root_dir|
+        return true if root_dir.start_with?(dir) || dir.start_with?(root_dir + "/")
+      end
+
+      false
+    end
+
+    # --- Class methods ---------------------------------------------------------------------------
+
+    class << self
+      # Broadcasts `eager_load` to all loaders.
+      #
+      # @return [void]
+      def eager_load_all
+        Registry.loaders.each(&:eager_load)
+      end
+
+      # Returns an array with the absolute paths of the root directories of all
+      # registered loaders. This is a read-only collection.
+      #
+      # @return [<String>]
+      def all_dirs
+        Registry.loaders.flat_map(&:dirs).freeze
+      end
+    end
+
+    # @param dir [String]
+    # @param parent [Module]
+    # @return [void]
+    def set_autoloads_in_dir(dir, parent)
+      ls(dir) do |basename, abspath|
+        begin
+          if ruby?(abspath)
+            # basename = basename.slice(-3, 3)
+            cname = inflector.camelize(basename, abspath).to_sym
+            autoload_file(parent, cname, abspath)
+          elsif dir?(abspath)
+            # In a Rails application, `app/models/concerns` is a subdirectory of
+            # `app/models`, but both of them are root directories.
+            #
+            # To resolve the ambiguity file name -> constant path this introduces,
+            # the `app/models/concerns` directory is totally ignored as a namespace,
+            # it counts only as root. The guard checks that.
+            unless root_dirs.key?(abspath)
+              cname = inflector.camelize(basename, abspath).to_sym
+              autoload_subdir(parent, cname, abspath)
+            end
+          end
+        rescue ::NameError => error
+          path_type = ruby?(abspath) ? "file" : "directory"
+
+          raise NameError, <<~MESSAGE
+            #{error.message} inferred by #{inflector.class} from #{path_type}
+
+              #{abspath}
+
+            Possible ways to address this:
+
+              * Tell Zeitwerk to ignore this particular #{path_type}.
+              * Tell Zeitwerk to ignore one of its parent directories.
+              * Rename the #{path_type} to comply with the naming conventions.
+              * Modify the inflector to handle this case.
+          MESSAGE
+        end
+      end
+    end
+
+    private # -------------------------------------------------------------------------------------
+
+    # @return [<String>]
+    def actual_root_dirs
+      root_dirs.keys.delete_if do |root_dir|
+        !dir?(root_dir) || ignored_paths.member?(root_dir)
+      end
+    end
+
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @param subdir [String]
+    # @return [void]
+    def autoload_subdir(parent, cname, subdir)
+      if autoload_path = autoload_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
+        # no matter if it is for a file or a directory. Just remember the
+        # subdirectory has to be visited if the namespace is used.
+        (lazy_subdirs[cpath] ||= []) << subdir
+      elsif !cdef?(parent, cname)
+        # First time we find this namespace, set an autoload for it.
+        (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
+        set_autoload(parent, cname, subdir)
+      else
+        # For whatever reason the constant that corresponds to this namespace has
+        # already been defined, we have to recurse.
+        set_autoloads_in_dir(subdir, parent.const_get(cname))
+      end
+    end
+
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @param file [String]
+    # @return [void]
+    def autoload_file(parent, cname, file)
+      if autoload_path = autoload_for?(parent, cname)
+        # First autoload for a Ruby file wins, just ignore subsequent ones.
+        if ruby?(autoload_path)
+          # "file #{file} is ignored because #{autoload_path} has precedence"
+        else
+          promote_namespace_from_implicit_to_explicit(
+            dir:    autoload_path,
+            file:   file,
+            parent: parent,
+            cname:  cname
+          )
+        end
+      elsif cdef?(parent, cname)
+        # "file #{file} is ignored because #{cpath(parent, cname)} is already defined"
+      else
+        set_autoload(parent, cname, file)
+      end
+    end
+
+    # @param dir [String] directory that would have autovivified a module
+    # @param file [String] the file where the namespace is explictly defined
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @return [void]
+    def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
+      autoloads.delete(dir)
+      Registry.unregister_autoload(dir)
+
+      set_autoload(parent, cname, file)
+      register_explicit_namespace(cpath(parent, cname))
+    end
+
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @param abspath [String]
+    # @return [void]
+    def set_autoload(parent, cname, abspath)
+      # $LOADED_FEATURES stores real paths since Ruby 2.4.4. We set and save the
+      # real path to be able to delete it from $LOADED_FEATURES on unload, and to
+      # be able to do a lookup later in Kernel#require for manual require calls.
+      realpath = File.realpath(abspath)
+      parent.autoload(cname, realpath)
+
+      autoloads[realpath] = [parent, cname]
+      Registry.register_autoload(self, realpath)
+
+      # See why in the documentation of Zeitwerk::Registry.inceptions.
+      unless parent.autoload?(cname)
+        Registry.register_inception(cpath(parent, cname), realpath, self)
+      end
+    end
+
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @return [String, nil]
+    def autoload_for?(parent, cname)
+      strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
+    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 strictly check in parent ignoring ancestors.
+    #
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @return [String, nil]
+    if method(:autoload?).arity == 1
+      def strict_autoload_path(parent, cname)
+        parent.autoload?(cname) if cdef?(parent, cname)
+      end
+    else
+      def strict_autoload_path(parent, cname)
+        parent.autoload?(cname, false)
+      end
+    end
+
+    # This method is called this way because I prefer `preload` to be the method
+    # name to configure preloads in the public interface.
+    #
+    # @return [void]
+    def do_preload
+      preloads.each do |abspath|
+        do_preload_abspath(abspath)
+      end
+    end
+
+    # @param abspath [String]
+    # @return [void]
+    def do_preload_abspath(abspath)
+      if ruby?(abspath)
+        do_preload_file(abspath)
+      elsif dir?(abspath)
+        do_preload_dir(abspath)
+      end
+    end
+
+    # @param dir [String]
+    # @return [void]
+    def do_preload_dir(dir)
+      ls(dir) do |_basename, abspath|
+        do_preload_abspath(abspath)
+      end
+    end
+
+    # @param file [String]
+    # @return [Boolean]
+    def do_preload_file(file)
+      require file
+    end
+
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @return [String]
+    def cpath(parent, cname)
+      parent.equal?(Object) ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
+    end
+
+    # @param dir [String]
+    # @yieldparam path [String, String]
+    # @return [void]
+    def ls(dir)
+      # `console.log("dir:", dir)`
+      outer_ls = false
+      # cache the Opal.modules keys array for subsequent ls calls during setup
+      if !@module_paths
+        @module_paths = `Object.keys(Opal.modules)`
+        outer_ls = true
+      end
+      visited_abspaths = `{}`
+      dir_first_char = dir[0]
+      path_start = dir.size + 1
+      path_parts = `[]`
+      basename = `''`
+      @module_paths.each do |abspath|
+        %x{
+          if (abspath[0] === dir_first_char) {
+            if (!abspath.startsWith(dir)) { #{next} }
+            path_parts = abspath.slice(path_start).split('/');
+            basename = path_parts[0];
+            abspath = dir + '/' + basename;
+            if (visited_abspaths.hasOwnProperty(abspath)) { #{next} }
+            visited_abspaths[abspath] = true;
+            // console.log("basename:", basename, "abspath:", abspath);
+            #{yield basename, abspath unless ignored_paths.member?(abspath)}
+          }
+        }
+      end
+      # remove cache, because Opal.modules may change after setup
+      if outer_ls
+        @module_paths = nil
+      end
+    end
+
+    # @param path [String]
+    # @return [Boolean]
+    def ruby?(abspath)
+      `Opal.modules.hasOwnProperty(abspath)`
+    end
+
+    # @param path [String]
+    # @return [Boolean]
+    def dir?(path)
+      dir_path = path + '/'
+      module_paths = if @module_paths # possibly set by ls
+                       @module_paths
+                     else
+                       `Object.keys(Opal.modules)`
+                     end
+      path_first = `path[0]`
+      module_paths.each do |m_path|
+        %x{
+          if (m_path[0] !== path_first) { #{ next } }
+          if (m_path.startsWith(dir_path)) { #{return true} }
+        }
+      end
+      return false
+    end
+
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [<String>]
+    def expand_paths(paths)
+      paths.flatten.map! { |path| File.expand_path(path) }
+    end
+
+    # @param glob_patterns [<String>]
+    # @return [<String>]
+    def expand_glob_patterns(glob_patterns)
+      # Note that Dir.glob works with regular file names just fine. That is,
+      # glob patterns technically need no wildcards.
+      glob_patterns.flat_map { |glob_pattern| Dir.glob(glob_pattern) }
+    end
+
+    # @return [void]
+    def recompute_ignored_paths
+      ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
+    end
+
+    def cdef?(parent, cname)
+      parent.const_defined?(cname, false)
+    end
+
+    def register_explicit_namespace(cpath)
+      ExplicitNamespace.register(cpath, self)
+    end
+
+    def raise_if_conflicting_directory(dir)
+      Registry.loaders.each do |loader|
+        if loader != self && loader.manages?(dir)
+          require "pp"
+          raise Error,
+            "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
+            " which is already managed by\n\n#{loader.pretty_inspect}\n"
+          EOS
+        end
+      end
+    end
+
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @return [void]
+    def unload_autoload(parent, cname)
+      parent.send(:remove_const, cname)
+    end
+
+    # @param parent [Module]
+    # @param cname [Symbol]
+    # @return [void]
+    def unload_cref(parent, cname)
+      parent.send(:remove_const, cname)
+    end
+  end
+end

data/opal/zeitwerk/loader/callbacks.rb

@@ -0,0 +1,61 @@
+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, "expected file #{file} to define constant #{cpath(*cref)}, but didn't"
+    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 = if vivify_mod_dir && dir.start_with?(vivify_mod_dir)
+                              cref[0].const_set(cref[1], vivify_mod_class.new)
+                            else
+                              cref[0].const_set(cref[1], Module.new)
+                            end
+      # "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

data/opal/zeitwerk/real_mod_name.rb

@@ -0,0 +1,21 @@
+module Zeitwerk::RealModName
+  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).
+  #
+  # The name method can be overridden, hence the indirection in this method.
+  #
+  # @param mod [Class, Module]
+  # @return [String, nil]
+  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
+  end
+end

data/opal/zeitwerk/registry.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  module Registry # :nodoc: all
+    class << self
+      # Keeps track of all loaders. Useful to broadcast messages and to prevent
+      # them from being garbage collected.
+      #
+      # @private
+      # @return [<Zeitwerk::Loader>]
+      attr_reader :loaders
+
+      # Maps real 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}]
+      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
+
+      # Registers a loader.
+      #
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      # @return [void]
+      def register_loader(loader)
+        loaders << loader
+      end
+
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      # @param realpath [String]
+      # @return [void]
+      def register_autoload(loader, realpath)
+        autoloads[realpath] = loader
+      end
+
+      # @private
+      # @param realpath [String]
+      # @return [void]
+      def unregister_autoload(realpath)
+        autoloads.delete(realpath)
+      end
+
+      # @private
+      # @param cpath [String]
+      # @param realpath [String]
+      # @param loader [Zeitwerk::Loader]
+      # @return [void]
+      def register_inception(cpath, realpath, loader)
+        inceptions[cpath] = [realpath, loader]
+      end
+
+      # @private
+      # @param cpath [String]
+      # @return [String, nil]
+      def inception?(cpath)
+        if pair = inceptions[cpath]
+          pair.first
+        end
+      end
+
+      # @private
+      # @param path [String]
+      # @return [Zeitwerk::Loader, nil]
+      def loader_for(path)
+        autoloads[path]
+      end
+
+      # @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 }
+      end
+    end
+
+    @loaders               = []
+    @autoloads             = {}
+    @inceptions            = {}
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opal-zeitwerk
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Jan Biedermann
@@ -9,7 +9,21 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2019-11-04 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 description: |2
       A port of the Zeitwerk autoloader to Opal.
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -22,6 +36,17 @@ extra_rdoc_files: []
 files:
 - MIT-LICENSE
 - README.md
+- lib/opal-zeitwerk.rb
+- lib/opal/zeitwerk/version.rb
+- opal/zeitwerk.rb
+- opal/zeitwerk/error.rb
+- opal/zeitwerk/explicit_namespace.rb
+- opal/zeitwerk/inflector.rb
+- opal/zeitwerk/kernel.rb
+- opal/zeitwerk/loader.rb
+- opal/zeitwerk/loader/callbacks.rb
+- opal/zeitwerk/real_mod_name.rb
+- opal/zeitwerk/registry.rb
 homepage: https://github.com/isomorfeus/opal-zeitwerk
 licenses:
 - MIT