im 0.1.6 → 0.2.0

data/lib/im/kernel.rb

@@ -1,19 +1,44 @@
 # frozen_string_literal: true
 
 module Kernel
-  alias_method :im_original_require, :require
+  module_function
 
-  def require(path)
-    Im.handle_require(path, caller_locations(1, 1).first.path) do
-      im_original_require(path)
-    end
+  alias_method :im_original_require, :require
+  class << self
+    alias_method :im_original_require, :require
   end
 
-  alias_method :im_original_autoload, :autoload
+  # @sig (String) -> true | false
+  def require(path)
+    filetype, feature_path = $:.resolve_feature_path(path)
 
-  def autoload(name, path)
-    Im.handle_autoload(path) do
-      im_original_autoload(name, path)
+    if (loader = Im::Registry.loader_for(path)) ||
+        ((loader = Im::Registry.loader_for(feature_path)) && (path = feature_path))
+      if :rb == filetype
+        if loaded = !$LOADED_FEATURES.include?(feature_path)
+          $LOADED_FEATURES << feature_path
+          begin
+            load path, loader
+          rescue => e
+            $LOADED_FEATURES.delete(feature_path)
+            raise e
+          end
+          loader.on_file_autoloaded(path)
+        end
+        loaded
+      else
+        loader.on_dir_autoloaded(path)
+        true
+      end
+    else
+      required = im_original_require(path)
+      if required
+        abspath = $LOADED_FEATURES.last
+        if loader = Im::Registry.loader_for(abspath)
+          loader.on_file_autoloaded(abspath)
+        end
+      end
+      required
     end
   end
 end

data/lib/im/loader/callbacks.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Im::Loader::Callbacks
+  # 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)
+
+    relative_cpath = relative_cpath(*cref)
+    to_unload[relative_cpath] = [file, cref] if reloading_enabled?
+    Im::Registry.unregister_autoload(file)
+
+    if cdef?(*cref)
+      obj = cget(*cref)
+      if obj.is_a?(Module)
+        register_module_name(obj, relative_cpath)
+        Im::Registry.register_autoloaded_module(obj, relative_cpath, self)
+      end
+      log("constant #{relative_cpath} loaded from file #{file}") if logger
+      run_on_load_callbacks(relative_cpath, obj, file) unless on_load_callbacks.empty?
+    else
+      raise Im::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
+  # @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 namespace_dirs entry.
+    mutex2.synchronize do
+      if cref = autoloads.delete(dir)
+        autovivified_module = cref[0].const_set(cref[1], Module.new)
+        relative_cpath = relative_cpath(*cref)
+        register_module_name(autovivified_module, relative_cpath)
+        Im::Registry.register_autoloaded_module(autovivified_module, relative_cpath, self)
+        log("module #{relative_cpath} autovivified from directory #{dir}") if logger
+
+        to_unload[relative_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(relative_cpath)
+
+        run_on_load_callbacks(relative_cpath, autovivified_module, dir) unless on_load_callbacks.empty?
+      end
+    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(module_name)
+    if dirs = namespace_dirs.delete(module_name)
+      dirs.each do |dir|
+        set_autoloads_in_dir(dir, cget(self, module_name))
+      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

data/lib/im/loader/config.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+require "set"
+require "securerandom"
+
+module Im::Loader::Config
+  extend Im::Internal
+
+  # @sig #camelize
+  attr_accessor :inflector
+
+  # @sig #call | #debug | nil
+  attr_accessor :logger
+
+  # Absolute paths of the root directories, as a set:
+  #
+  #   #<Set: {
+  #     "/Users/fxn/blog/app/channels",
+  #     "/Users/fxn/blog/app/adapters",
+  #     ...
+  #   }>
+  #
+  # This is a private collection maintained by the loader. The public
+  # interface for it is `push_dir` and `dirs`.
+  #
+  # @sig Array[String]
+  attr_reader :root_dirs
+  internal :root_dirs
+
+  # Absolute paths of files, directories, or glob patterns to be totally
+  # ignored.
+  #
+  # @sig Set[String]
+  attr_reader :ignored_glob_patterns
+  private :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.
+  #
+  # @sig Set[String]
+  attr_reader :ignored_paths
+  private :ignored_paths
+
+  # Absolute paths of directories or glob patterns to be collapsed.
+  #
+  # @sig Set[String]
+  attr_reader :collapse_glob_patterns
+  private :collapse_glob_patterns
+
+  # The actual collection of absolute directory names at the time the collapse
+  # glob patterns were expanded. Computed on setup, and recomputed on reload.
+  #
+  # @sig Set[String]
+  attr_reader :collapse_dirs
+  private :collapse_dirs
+
+  # Absolute paths of files or directories not to be eager loaded.
+  #
+  # @sig Set[String]
+  attr_reader :eager_load_exclusions
+  private :eager_load_exclusions
+
+  # User-oriented callbacks to be fired on setup and on reload.
+  #
+  # @sig Array[{ () -> void }]
+  attr_reader :on_setup_callbacks
+  private :on_setup_callbacks
+
+  # User-oriented callbacks to be fired when a constant is loaded.
+  #
+  # @sig Hash[String, Array[{ (Object, String) -> void }]]
+  #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
+  attr_reader :on_load_callbacks
+  private :on_load_callbacks
+
+  # User-oriented callbacks to be fired before constants are removed.
+  #
+  # @sig Hash[String, Array[{ (Object, String) -> void }]]
+  #      Hash[Symbol, Array[{ (String, Object, String) -> void }]]
+  attr_reader :on_unload_callbacks
+  private :on_unload_callbacks
+
+  def initialize
+    @inflector              = Im::Inflector.new
+    @logger                 = self.class.default_logger
+    @tag                    = SecureRandom.hex(3)
+    @initialized_at         = Time.now
+    @root_dirs              = Set.new
+    @ignored_glob_patterns  = Set.new
+    @ignored_paths          = Set.new
+    @collapse_glob_patterns = Set.new
+    @collapse_dirs          = Set.new
+    @eager_load_exclusions  = Set.new
+    @reloading_enabled      = false
+    @on_setup_callbacks     = []
+    @on_load_callbacks      = {}
+    @on_unload_callbacks    = {}
+  end
+
+  # Pushes `path` to the list of root directories.
+  #
+  # Raises `Im::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.
+  #
+  # @raise [Im::Error]
+  # @sig (String | Pathname, Module) -> void
+  def push_dir(path)
+    abspath = File.expand_path(path)
+    if dir?(abspath)
+      raise_if_conflicting_directory(abspath)
+      root_dirs << abspath
+    else
+      raise Im::Error, "the root directory #{abspath} does not exist"
+    end
+  end
+
+  # Returns the loader's tag.
+  #
+  # Implemented as a method instead of via attr_reader for symmetry with the
+  # writer below.
+  #
+  # @sig () -> String
+  def tag
+    @tag
+  end
+
+  # Sets a tag for the loader, useful for logging.
+  #
+  # @sig (#to_s) -> void
+  def tag=(tag)
+    @tag = tag.to_s
+  end
+
+  # Rturns an array with the absolute paths of the root directories as strings.
+  # If `ignored` is falsey (default), ignored root directories are filtered out.
+  #
+  # These are read-only collections, please add to them with `push_dir`.
+  #
+  # @sig () -> Array[String] | Hash[String, Module]
+  def dirs(ignored: false)
+    if ignored || ignored_paths.empty?
+      root_dirs
+    else
+      root_dirs.reject { |root_dir| ignored_path?(root_dir) }
+    end.freeze
+  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 [Im::Error]
+  # @sig () -> void
+  def enable_reloading
+    mutex.synchronize do
+      break if @reloading_enabled
+
+      if @setup
+        raise Im::Error, "cannot enable reloading after setup"
+      else
+        @reloading_enabled = true
+      end
+    end
+  end
+
+  # @sig () -> bool
+  def reloading_enabled?
+    @reloading_enabled
+  end
+
+  # Let eager load ignore the given files or directories. The constants defined
+  # in those files are still autoloadable.
+  #
+  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  def do_not_eager_load(*paths)
+    mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
+  end
+
+  # Configure files, directories, or glob patterns to be totally ignored.
+  #
+  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  def ignore(*glob_patterns)
+    glob_patterns = expand_paths(glob_patterns)
+    mutex.synchronize do
+      ignored_glob_patterns.merge(glob_patterns)
+      ignored_paths.merge(expand_glob_patterns(glob_patterns))
+    end
+  end
+
+  # Configure directories or glob patterns to be collapsed.
+  #
+  # @sig (*(String | Pathname | Array[String | Pathname])) -> void
+  def collapse(*glob_patterns)
+    glob_patterns = expand_paths(glob_patterns)
+    mutex.synchronize do
+      collapse_glob_patterns.merge(glob_patterns)
+      collapse_dirs.merge(expand_glob_patterns(glob_patterns))
+    end
+  end
+
+  # Configure a block to be called after setup and on each reload.
+  # If setup was already done, the block runs immediately.
+  #
+  # @sig () { () -> void } -> void
+  def on_setup(&block)
+    mutex.synchronize do
+      on_setup_callbacks << block
+      block.call if @setup
+    end
+  end
+
+  # Configure a block to be invoked once a certain constant path is loaded.
+  # Supports multiple callbacks, and if there are many, they are executed in
+  # the order in which they were defined.
+  #
+  #   loader.on_load("SomeApiClient") do |klass, _abspath|
+  #     klass.endpoint = "https://api.dev"
+  #   end
+  #
+  # Can also be configured for any constant loaded:
+  #
+  #   loader.on_load do |cpath, value, abspath|
+  #     # ...
+  #   end
+  #
+  # @raise [TypeError]
+  # @sig (String) { (Object, String) -> void } -> void
+  #      (:ANY) { (String, Object, String) -> void } -> void
+  def on_load(cpath = :ANY, &block)
+    raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
+
+    mutex.synchronize { _on_load(cpath, &block) }
+  end
+
+  # @sig (String) { (Object, String) -> void } -> void
+  #      (:ANY) { (String, Object, String) -> void } -> void
+  private def _on_load(cpath, &block)
+    (on_load_callbacks[cpath] ||= []) << block
+  end
+
+  # Configure a block to be invoked right before a certain constant is removed.
+  # Supports multiple callbacks, and if there are many, they are executed in the
+  # order in which they were defined.
+  #
+  #   loader.on_unload("Country") do |klass, _abspath|
+  #     klass.clear_cache
+  #   end
+  #
+  # Can also be configured for any removed constant:
+  #
+  #   loader.on_unload do |cpath, value, abspath|
+  #     # ...
+  #   end
+  #
+  # @raise [TypeError]
+  # @sig (String) { (Object) -> void } -> void
+  #      (:ANY) { (String, Object) -> void } -> void
+  def on_unload(cpath = :ANY, &block)
+    raise TypeError, "on_unload only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
+
+    mutex.synchronize do
+      (on_unload_callbacks[cpath] ||= []) << block
+    end
+  end
+
+  # Logs to `$stdout`, handy shortcut for debugging.
+  #
+  # @sig () -> void
+  def log!
+    @logger = ->(msg) { puts msg }
+  end
+
+  # Returns true if the argument has been configured to be ignored, or is a
+  # descendant of an ignored directory.
+  #
+  # @sig (String) -> bool
+  internal def ignores?(abspath)
+    # Common use case.
+    return false if ignored_paths.empty?
+
+    walk_up(abspath) do |abspath|
+      return true  if ignored_path?(abspath)
+      return false if root_dir?(abspath)
+    end
+
+    false
+  end
+
+  # @sig (String) -> bool
+  private def ignored_path?(abspath)
+    ignored_paths.member?(abspath)
+  end
+
+  # @sig () -> Array[String]
+  private def actual_roots
+    root_dirs.reject do |root_dir|
+      !dir?(root_dir) || ignored_path?(root_dir)
+    end
+  end
+
+  # @sig (String) -> bool
+  private def root_dir?(dir)
+    root_dirs.include?(dir)
+  end
+
+  # @sig (String) -> bool
+  private def excluded_from_eager_load?(abspath)
+    # Optimize this common use case.
+    return false if eager_load_exclusions.empty?
+
+    walk_up(abspath) do |abspath|
+      return true  if eager_load_exclusions.member?(abspath)
+      return false if root_dir?(abspath)
+    end
+
+    false
+  end
+
+  # @sig (String) -> bool
+  private def collapse?(dir)
+    collapse_dirs.member?(dir)
+  end
+
+  # @sig (String | Pathname | Array[String | Pathname]) -> Array[String]
+  private def expand_paths(paths)
+    paths.flatten.map! { |path| File.expand_path(path) }
+  end
+
+  # @sig (Array[String]) -> Array[String]
+  private 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
+
+  # @sig () -> void
+  private def recompute_ignored_paths
+    ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
+  end
+
+  # @sig () -> void
+  private def recompute_collapse_dirs
+    collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
+  end
+end

data/lib/im/loader/eager_load.rb

@@ -0,0 +1,214 @@
+module Im::Loader::EagerLoad
+  # Eager loads all files in the root directories, recursively. Files do not
+  # need to be in `$LOAD_PATH`, absolute file names are used. Ignored and
+  # shadowed files are not eager loaded. You can opt-out specifically in
+  # specific files and directories with `do_not_eager_load`, and that can be
+  # overridden passing `force: true`.
+  #
+  # @sig (true | false) -> void
+  def eager_load(force: false)
+    mutex.synchronize do
+      break if @eager_loaded
+      raise Im::SetupRequired unless @setup
+
+      log("eager load start") if logger
+
+      actual_roots.each do |root_dir|
+        actual_eager_load_dir(root_dir, self, force: force)
+      end
+
+      autoloaded_dirs.each do |autoloaded_dir|
+        Im::Registry.unregister_autoload(autoloaded_dir)
+      end
+      autoloaded_dirs.clear
+
+      @eager_loaded = true
+
+      log("eager load end") if logger
+    end
+  end
+
+  # @sig (String | Pathname) -> void
+  def eager_load_dir(path)
+    raise Im::SetupRequired unless @setup
+
+    abspath = File.expand_path(path)
+
+    raise Im::Error.new("#{abspath} is not a directory") unless dir?(abspath)
+
+    cnames = []
+
+    found_root = false
+    walk_up(abspath) do |dir|
+      return if ignored_path?(dir)
+      return if eager_load_exclusions.member?(dir)
+
+      break if found_root = root_dirs.include?(dir)
+
+      unless collapse?(dir)
+        basename = File.basename(dir)
+        cnames << inflector.camelize(basename, dir).to_sym
+      end
+    end
+
+    raise Im::Error.new("I do not manage #{abspath}") unless found_root
+
+    return if @eager_loaded
+
+    namespace = self
+    cnames.reverse_each do |cname|
+      # Can happen if there are no Ruby files. This is not an error condition,
+      # the directory is actually managed. Could have Ruby files later.
+      return unless cdef?(namespace, cname)
+      namespace = cget(namespace, cname)
+    end
+
+    # A shortcircuiting test depends on the invocation of this method. Please
+    # keep them in sync if refactored.
+    actual_eager_load_dir(abspath, namespace)
+  end
+
+  # @sig (Module) -> void
+  def eager_load_namespace(mod)
+    raise Im::SetupRequired unless @setup
+
+    unless mod.is_a?(Module)
+      raise Im::Error, "#{mod.inspect} is not a class or module object"
+    end
+
+    return if @eager_loaded
+
+    mod_name = Im.cpath(mod)
+
+    actual_roots.each do |root_dir|
+      if mod.equal?(self)
+        # A shortcircuiting test depends on the invocation of this method.
+        # Please keep them in sync if refactored.
+        actual_eager_load_dir(root_dir, self)
+      else
+        eager_load_child_namespace(mod, mod_name, root_dir)
+      end
+    end
+  end
+
+  # Loads the given Ruby file.
+  #
+  # Raises if the argument is ignored, shadowed, or not managed by the receiver.
+  #
+  # The method is implemented as `constantize` for files, in a sense, to be able
+  # to descend orderly and make sure the file is loadable.
+  #
+  # @sig (String | Pathname) -> void
+  def load_file(path)
+    abspath = File.expand_path(path)
+
+    raise Im::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
+    raise Im::Error.new("#{abspath} is not a Ruby file") if dir?(abspath) || !ruby?(abspath)
+    raise Im::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
+
+    basename = File.basename(abspath, ".rb")
+    base_cname = inflector.camelize(basename, abspath).to_sym
+
+    root_included = false
+    cnames = []
+
+    walk_up(File.dirname(abspath)) do |dir|
+      raise Im::Error.new("#{abspath} is ignored") if ignored_path?(dir)
+
+      break if root_included = root_dirs.include?(dir)
+
+      unless collapse?(dir)
+        basename = File.basename(dir)
+        cnames << inflector.camelize(basename, dir).to_sym
+      end
+    end
+
+    raise Im::Error.new("I do not manage #{abspath}") unless root_included
+
+    namespace = self
+    cnames.reverse_each do |cname|
+      namespace = cget(namespace, cname)
+    end
+
+    raise Im::Error.new("#{abspath} is shadowed") if shadowed_file?(abspath)
+
+    cget(namespace, base_cname)
+  end
+
+  # The caller is responsible for making sure `namespace` is the namespace that
+  # corresponds to `dir`.
+  #
+  # @sig (String, Module, Boolean) -> void
+  private def actual_eager_load_dir(dir, namespace, force: false)
+    honour_exclusions = !force
+    return if honour_exclusions && excluded_from_eager_load?(dir)
+
+    log("eager load directory #{dir} start") if logger
+
+    queue = [[dir, namespace]]
+    while to_eager_load = queue.shift
+      dir, namespace = to_eager_load
+
+      ls(dir) do |basename, abspath|
+        next if honour_exclusions && eager_load_exclusions.member?(abspath)
+
+        if ruby?(abspath)
+          if (cref = autoloads[abspath]) && !shadowed_file?(abspath)
+            cget(*cref)
+          end
+        else
+          if collapse?(abspath)
+            queue << [abspath, namespace]
+          else
+            cname = inflector.camelize(basename, abspath).to_sym
+            queue << [abspath, cget(namespace, cname)]
+          end
+        end
+      end
+    end
+
+    log("eager load directory #{dir} end") if logger
+  end
+
+  # In order to invoke this method, the caller has to ensure `child` is a
+  # strict namespace descendendant of `root_namespace`.
+  #
+  # @sig (Module, String, Module, Boolean) -> void
+  private def eager_load_child_namespace(child, child_name, root_dir)
+    suffix = child_name
+    suffix = suffix.delete_prefix("#{self}::")
+
+    # These directories are at the same namespace level, there may be more if
+    # we find collapsed ones. As we scan, we look for matches for the first
+    # segment, and store them in `next_dirs`. If there are any, we look for
+    # the next segments in those matches. Repeat.
+    #
+    # If we exhaust the search locating directories that match all segments,
+    # we just need to eager load those ones.
+    dirs = [root_dir]
+    next_dirs = []
+
+    suffix.split("::").each do |segment|
+      while dir = dirs.shift
+        ls(dir) do |basename, abspath|
+          next unless dir?(abspath)
+
+          if collapse?(abspath)
+            dirs << abspath
+          elsif segment == inflector.camelize(basename, abspath)
+            next_dirs << abspath
+          end
+        end
+      end
+
+      return if next_dirs.empty?
+
+      dirs.replace(next_dirs)
+      next_dirs.clear
+    end
+
+    dirs.each do |dir|
+      actual_eager_load_dir(dir, child)
+    end
+  end
+end