onload 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51cfb4df59e2a2560f42b4e8e12635bba647e53c49f0246be381bf0b4202461e
+  data.tar.gz: 48baf94964ddd076934dd84b36338cec01ff8446a023ef0aca703a84c269ed6c
+SHA512:
+  metadata.gz: b4335856e653c8022fae229cae2ecb880dbb6a36ef3340bb8c2685fa44cd7b6874efbd6a632d4134ae6f7e1377dd6929208eb122b78eb62c7c30a46f46d0d700
+  data.tar.gz: cafd4311f223a8f8a29eefad15743c164a39f6904e38d7564e87d978d6feb1e765ed99cfe9c178f1310302aa37585f77e7012c201b1dda144b7ca89383340fb8

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+* Birthday!

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'debug'
+  gem 'rake'
+end
+
+group :development do
+  gem 'appraisal'
+  gem 'benchmark-ips'
+end
+
+group :test do
+  gem 'rspec'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Cameron Dutro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,64 @@
+## onload
+
+![Tests](https://github.com/camertron/onload/actions/workflows/test.yml/badge.svg?branch=main)
+
+A preprocessor system for Ruby.
+
+## Intro
+
+Onload makes it possible to preprocess Ruby files before they are loaded into the interpreter. It works with plain 'ol Ruby code, within Rails, or wherever Zeitwerk is used.
+
+### What is preprocessing?
+
+Preprocessing has been around for a long time in the C world. The idea is to be able to compile the code differently depending on operating system, architecture, etc. In interpreted languages, preprocessing is most useful for transpilation, i.e. converting code from one dialect to another. Maybe the most familiar example of this is translating TypeScript to JavaScript. The JavaScript interpreters inside web browsers and Node.js can't run TypeScript directly - it has to be converted into JavaScript first.
+
+In the JavaScript ecosystem it's very common for your code to pass through a build step, but not so in Ruby. That's where onload comes in.
+
+### Why onload
+
+Onload lets you transform Ruby code just before it's loaded into the Ruby interpreter. You give it a file extension and a callable object, and it does the rest. Onload is the transpilation system behind [rux](https://github.com/camertron/rux), a tool that let's you write HTML tags inside your [view components](https://viewcomponent.org) (think if it like jsx for Ruby).
+
+## Usage
+
+Let's write an (admittedly contrived) preprocessor that upcases literal strings in Ruby files. We'll use the file extension .up to indicate which files to process.
+
+Preprocessors can be any Ruby object that responds to the `#call` method.
+
+```ruby
+class UpcasePreprocessor
+  def self.call(source)
+    source.gsub(/(\"\w+\")/, '\1.upcase')
+  end
+end
+```
+
+Next we'll tell onload about our preprocessor.
+
+```ruby
+Onload.register(".up", UpcasePreprocessor)
+```
+
+Finally, we'll load the necessary monkeypatches by "installing" onload into the interpreter. In Rails environments you can skip this step, as it is done for you via the included railtie.
+
+```ruby
+Onload.install!
+```
+
+Now, the contents of any file with a .up file extension will be passed to `UpcasePreprocessor.call`. The return value will be written to a separate Ruby file and loaded instead of the original .up file.
+
+## Running Tests
+
+If you're using [asdf](https://asdf-vm.com/), run `./script/run_appraisal.rb` to run Rails and plain Ruby tests for all supported versions.
+
+Otherwise, use Appraisal to run tests for Rails or plain ruby:
+
+1. Plain ruby: `bundle exec appraisal ruby rake spec:ruby`
+1. Rails: `bundle exec appraisal <version> rake spec:rails`. Run `bundle exec appraisal list` to see the available versions. To run tests for Rails 7.0, try `bundle exec appraisal rails-7.0 rake spec:rails`
+
+## License
+
+Licensed under the MIT license. See LICENSE for details.
+
+## Authors
+
+* Cameron C. Dutro: http://github.com/camertron

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler"
+require "rspec/core/rake_task"
+require "rubygems/package_task"
+
+require "onload"
+
+Bundler::GemHelper.install_tasks
+
+task default: :spec
+
+task spec: ["spec:ruby", "spec:rails"]
+
+desc "Run specs"
+RSpec::Core::RakeTask.new("spec:ruby") do |t|
+  t.pattern = "./spec/ruby/**/*_spec.rb"
+end
+
+desc "Run Rails specs"
+RSpec::Core::RakeTask.new("spec:rails") do |t|
+  t.pattern = "./spec/rails/**/*_spec.rb"
+end

data/lib/onload/core_ext/kernel.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Onload
+  module KernelLoadPatch
+    def load(file, *args)
+      # ActiveSupport::Dependencies adds an extra .rb to the end
+      if Onload.process?(file.chomp('.rb'))
+        file = file.chomp('.rb')
+      end
+
+      if Onload.process?(file) && Onload.enabled?
+        f = Onload::File.new(file)
+        f.write
+
+        return super(f.outfile, *args)
+      end
+
+      super(file, *args)
+    end
+  end
+
+  module KernelRequirePatch
+    def require(file)
+      # check to see if there's an unprocessed file somewhere on the load path
+      to_load = nil
+
+      if ::File.absolute_path(file) == file
+        to_load = Onload.unprocessed_file_for(file)
+      elsif file.start_with?(".#{::File::SEPARATOR}")
+        abs_path = ::File.expand_path(file)
+        to_load = Onload.unprocessed_file_for(abs_path)
+      else
+        [$LOAD_PATH[-1]].each do |lp|
+          check_path = ::File.expand_path(::File.join(lp, file))
+
+          if (unprocessed_file = Onload.unprocessed_file_for(check_path))
+            to_load = unprocessed_file
+            break
+          end
+        end
+      end
+
+      return super(file) unless to_load
+      return false if $LOADED_FEATURES.include?(to_load)
+
+      # Must call the Kernel.load class method here because that's the one
+      # activesupport doesn't mess with, and in fact the one activesupport
+      # itself uses to actually load files. In case you were curious,
+      # activesupport redefines Object#load and Object#require i.e. the
+      # instance versions that get inherited by all other objects. Yeah,
+      # it's pretty awful stuff. Although honestly we're not much better lol.
+      Kernel.load(to_load)
+      $LOADED_FEATURES << to_load
+
+      return true
+    end
+  end
+end
+
+module Kernel
+  class << self
+    prepend Onload::KernelLoadPatch
+  end
+end
+
+class Object
+  prepend Onload::KernelRequirePatch
+end

data/lib/onload/core_ext/kernel_zeitwerk.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+module Kernel
+  alias_method :onload_orig_require, :require
+  alias_method :onload_orig_load, :load
+
+  def load(file, *args)
+    if Onload.process?(file) && Onload.enabled?
+      f = Onload::File.new(file)
+      f.write
+
+      # I don't understand why, but it's necessary to delete the constant
+      # in order to load the resulting file. Otherwise you get an error about
+      # an uninitialized constant, and it's like... yeah, I _know_ it's
+      # uninitialized, that's why I'm loading this file. Whatevs.
+      loader = Zeitwerk::Registry.loader_for(file)
+      parent, cname = loader.send(:autoloads)[file]
+      parent.send(:remove_const, cname)
+
+      return onload_orig_load(f.outfile, *args)
+    end
+
+    onload_orig_load(file, *args)
+  end
+
+  def require(file)
+    to_load = nil
+
+    if File.absolute_path(file) == file
+      to_load = Onload.unprocessed_file_for(file)
+    elsif file.start_with?(".#{File::SEPARATOR}")
+      abs_path = File.expand_path(file)
+      to_load = Onload.unprocessed_file_for(abs_path)
+    else
+      $LOAD_PATH.each do |lp|
+        check_path = File.expand_path(File.join(lp, file))
+
+        if (unprocessed_file = Onload.unprocessed_file_for(check_path))
+          to_load = unprocessed_file
+          break
+        end
+      end
+    end
+
+    unless to_load
+      # This will be either Ruby's original require or bootsnap's monkeypatched
+      # require in setups that use bootsnap. Lord help us with all these layers
+      # of patches.
+      return onload_orig_require(file)
+    end
+
+    return false if $LOADED_FEATURES.include?(to_load)
+
+    load to_load
+    $LOADED_FEATURES << to_load
+
+    return true
+  end
+end

data/lib/onload/ext/activesupport/dependencies.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support/dependencies"
+
+module Onload
+  module ActiveSupportDependenciesPatch
+    # Allow activesupport to find unprocessed files.
+    def search_for_file(path_suffix)
+      autoload_paths.each do |root|
+        path = ::File.join(root, path_suffix)
+        unprocessed_path = Onload.unprocessed_file_for(path)
+        return unprocessed_path if unprocessed_path
+      end
+
+      super
+    end
+
+    # For some reason, using autoload and a patched Kernel#load doesn't work
+    # by itself for automatically loading unprocessed files. Due to what I can
+    # only surmise is one of the side-effects of autoload, requiring any
+    # unprocessed file that's been marked by autoload will result in a NameError,
+    # i.e. Ruby reports the constant isn't defined. Pretty surprising considering
+    # we're literally in the process of _defining_ that constant. The trick is to
+    # essentially undo the autoload by removing the constant just before
+    # loading the unprocessed file that defines it.
+    def load_missing_constant(from_mod, const_name)
+      if require_path = from_mod.autoload?(const_name)
+        path = search_for_file(require_path)
+
+        if path && Onload.process?(path)
+          from_mod.send(:remove_const, const_name)
+          require require_path
+          return from_mod.const_get(const_name)
+        end
+      end
+
+      super
+    end
+  end
+end
+
+module ActiveSupport
+  module Dependencies
+    class << self
+      prepend Onload::ActiveSupportDependenciesPatch
+    end
+  end
+end

data/lib/onload/ext/bootsnap/autoload.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Onload
+  module BootsnapAutoloadPatch
+    def autoload(const, path)
+      # Bootsnap monkeypatches Module.autoload in order to leverage its load
+      # path cache, which effectively converts a relative path into an absolute
+      # one without incurring the cost of searching the load path.
+      # Unfortunately, if an unprocessed file has already been transpiled, the
+      # cache seems to always return the corresponding .rb file. Bootsnap's
+      # autoload patch passes the .rb file to Ruby's original autoload,
+      # effectively wiping out the previous autoload that pointed to the
+      # unprocessed file. To fix this we have to intercept the cache lookup and
+      # force autoloading the unprocessed file if one exists.
+      cached_path = Bootsnap::LoadPathCache.load_path_cache.find(path)
+
+      if (unprocessed_path = Onload.unprocessed_file_for(cached_path))
+        return autoload_without_bootsnap(const, unprocessed_path)
+      end
+
+      super
+    end
+  end
+end
+
+class Module
+  prepend Onload::BootsnapAutoloadPatch
+end

data/lib/onload/ext/zeitwerk/loader.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "zeitwerk/loader"
+
+module Onload
+  module ZeitwerkLoaderPatch
+    private
+
+    def ruby?(path)
+      super || Onload.process?(path)
+    end
+
+    def autoload_file(parent, cname, file)
+      if Onload.process?(file)
+        # Some older versions of Zeitwerk very naïvely try to remove only the
+        # last 3 characters in an attempt to strip off the .rb file extension,
+        # while newer ones only remove it if it's actually there. This line is
+        # necessary to remove the trailing leftover period for older versions,
+        # and remove the entire extension for newer versions. Although cname
+        # means "constant name," we use Onload.basename to remove all residual
+        # file extensions that were left over from the conversion from a file
+        # name to a cname.
+        cname = Onload.basename(cname.to_s).to_sym
+      else
+        # if there is a corresponding unprocessed file, autoload it instead of
+        # the .rb file
+        if (unprocessed_file = Onload.unprocessed_file_for(file))
+          file = unprocessed_file
+        end
+      end
+
+      super
+    end
+  end
+end
+
+module Zeitwerk
+  class Loader
+    prepend Onload::ZeitwerkLoaderPatch
+  end
+end

data/lib/onload/file.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Onload
+  class File
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    def write
+      source = ::File.read(path)
+
+      ::File.extname(path).scan(/\.\w+/).each do |ext|
+        source = Onload.processors[ext].call(source)
+      end
+
+      ::File.write(outfile, source)
+    end
+
+    def outfile
+      @outfile ||= begin
+        base_name = "#{Onload.basename(path)}.rb"
+        ::File.join(::File.dirname(path), base_name)
+      end
+    end
+  end
+end

data/lib/onload/railtie.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Onload
+  class Railtie < Rails::Railtie
+    initializer "onload.initialize", before: :set_autoload_paths do |app|
+      Onload.install! if Onload.enabled?
+
+      if Onload.enabled? && app.config.file_watcher
+        paths = Set.new(app.config.eager_load_paths + app.config.autoload_paths)
+
+        dirs = paths.each_with_object({}) do |path, ret|
+          ret[path] = Onload.each_extension.map { |ext| ext.delete_prefix(".") }
+        end
+
+        app.reloaders << app.config.file_watcher.new([], dirs) do
+          # empty block, watcher seems to need it?
+        end
+      end
+    end
+
+    rake_tasks do
+      load ::File.expand_path(::File.join(*%w(. tasks transpile_rails.rake)), __dir__)
+    end
+  end
+end

data/lib/onload/tasks/transpile.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+namespace :onload do
+  task :transpile do
+    Dir.glob(File.join("**", Onload.glob)).each do |file|
+      f = Onload::File.new(file).tap(&:write)
+      puts "Wrote #{f.outfile}"
+    end
+  end
+end

data/lib/onload/tasks/transpile_rails.rake

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'set'
+
+namespace :onload do
+  task transpile: :environment do
+    config = Rails.application.config
+    paths = Set.new(config.autoload_paths + config.eager_load_paths)
+
+    paths.each do |path|
+      Dir.glob(File.join(path, "**", Onload.glob)).each do |file|
+        f = Onload::File.new(file).tap(&:write)
+        puts "Wrote #{f.outfile}"
+      end
+    end
+  end
+end

data/lib/onload/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Onload
+  VERSION = "1.0.0"
+end

data/lib/onload.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Onload
+  autoload :File, "onload/file"
+
+  class << self
+    attr_accessor :enabled
+    alias enabled? enabled
+
+    def register(extension, processor_klass)
+      processors[extension] = processor_klass
+    end
+
+    def install!
+      if Kernel.const_defined?(:Rails)
+        require "onload/railtie"
+
+        if Rails.respond_to?(:autoloaders) && Rails.autoloaders.zeitwerk_enabled?
+          require "onload/core_ext/kernel_zeitwerk"
+          require "onload/ext/zeitwerk/loader"
+        else
+          require "onload/core_ext/kernel"
+          require "onload/ext/activesupport/dependencies"
+        end
+      else
+        begin
+          require "zeitwerk"
+        rescue LoadError
+          require "onload/core_ext/kernel"
+        else
+          require "onload/core_ext/kernel_zeitwerk"
+          require "onload/ext/zeitwerk/loader"
+        end
+      end
+
+      begin
+        require "bootsnap"
+      rescue LoadError
+      else
+        require "onload/ext/bootsnap/autoload"
+      end
+    end
+
+    def process?(path)
+      each_extension.any? { |ext| path.end_with?(ext) }
+    end
+
+    def each_extension
+      return to_enum(__method__) unless block_given?
+
+      processors.each { |ext, _| yield ext }
+    end
+
+    def unprocessed_file_for(file)
+      base_name = basename(file)
+
+      unprocessed_files_in(::File.dirname(file)).each do |existing_file|
+        if basename(existing_file) == base_name
+          return existing_file
+        end
+      end
+
+      nil
+    end
+
+    def unprocessed_files_in(path)
+      path_cache[path] ||= begin
+        Dir.glob(::File.join(path, glob))
+      end
+    end
+
+    def processors
+      @processors ||= {}
+    end
+
+    def basename(file)
+      basename = ::File.basename(file)
+
+      if (idx = basename.index("."))
+        return basename[0...idx]
+      end
+
+      basename
+    end
+
+    def disable
+      old_enabled = enabled?
+      self.enabled = false
+      yield
+    ensure
+      self.enabled = old_enabled
+    end
+
+    def enable
+      old_enabled = enabled?
+      self.enabled = true
+      yield
+    ensure
+      self.enabled = old_enabled
+    end
+
+    def glob
+      @glob ||= "*{#{each_extension.to_a.join(",")}}"
+    end
+
+    private
+
+    def path_cache
+      @path_cache ||= {}
+    end
+  end
+
+  self.enabled = true
+end
+
+if Kernel.const_defined?(:Rails)
+  require "onload/railtie"
+end

data/onload.gemspec

@@ -0,0 +1,16 @@
+$:.unshift File.join(File.dirname(__FILE__), 'lib')
+require "onload/version"
+
+Gem::Specification.new do |s|
+  s.name     = "onload"
+  s.version  = ::Onload::VERSION
+  s.authors  = ["Cameron Dutro"]
+  s.email    = ["camertron@gmail.com"]
+  s.homepage = "http://github.com/camertron/onload"
+  s.description = s.summary = "A preprocessor system for Ruby."
+  s.platform = Gem::Platform::RUBY
+
+  s.require_path = "lib"
+
+  s.files = Dir["{lib,spec}/**/*", "Gemfile", "LICENSE", "CHANGELOG.md", "README.md", "Rakefile", "onload.gemspec"]
+end

data/spec/fixtures/hello.rb.up

@@ -0,0 +1,5 @@
+class Hello
+  def hello
+    "hello"
+  end
+end

data/spec/rails/controllers/home_controller_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/spec_helper"
+
+describe HomeController, type: :request do
+  describe "#index" do
+    it "transpiles the file" do
+      get "/"
+
+      expect(response).to have_http_status(:ok)
+      expect(response.body).to(
+        have_selector("div", text: "HELLO")
+      )
+    end
+
+    it "allows hot reloading" do
+      get "/"
+
+      expect(response).to have_http_status(:ok)
+      expect(response.body).to(
+        have_selector("div", text: "HELLO")
+      )
+
+      new_contents = <<~RUBY
+        class Hello
+          def hello
+            "goodbye"
+          end
+        end
+      RUBY
+
+      with_file_contents(File.join(Onload::TestHelpers.fixtures_path, "hello.rb.up"), new_contents) do
+        get "/"
+
+        expect(response).to have_http_status(:ok)
+        expect(response.body).to(
+          have_selector("div", text: "GOODBYE")
+        )
+      end
+    end
+  end
+end

data/spec/rails/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/spec/rails/dummy/app/controllers/home_controller.rb

@@ -0,0 +1,4 @@
+class HomeController < ApplicationController
+  def index
+  end
+end

data/spec/rails/dummy/app/views/home/index.html.erb

@@ -0,0 +1 @@
+<div><%= Hello.new.hello %></div>

data/spec/rails/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1 @@
+<%= yield %>