react_on_rails 16.1.2 → 16.2.0

data/rakelib/example_type.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "rake"
+
+require_relative "task_helpers"
+require_relative File.join(__dir__, "..", "lib", "react_on_rails", "utils")
+
+# Defines the ExampleType class, where each object represents a unique type of example
+# app that we can generate.
+module ReactOnRails
+  module TaskHelpers
+    class ExampleType
+      def self.all
+        @all ||= { shakapacker_examples: [] }
+      end
+
+      # Supported React versions for compatibility testing
+      # Keys are major version strings, values are specific version to pin to (nil = latest)
+      REACT_VERSIONS = {
+        "16" => "16.14.0",
+        "17" => "17.0.2",
+        "18" => "18.0.0",
+        "19" => nil # nil means use latest (default)
+      }.freeze
+
+      # Supported React major versions (we test with latest patch of each)
+      MINIMUM_SUPPORTED_REACT_MAJOR_VERSION = "16"
+      LATEST_REACT_MAJOR_VERSION = "19"
+
+      # Minimum Shakapacker version for compatibility testing
+      MINIMUM_SHAKAPACKER_VERSION = "8.2.0"
+
+      attr_reader :packer_type, :name, :generator_options, :react_version
+
+      # Returns true if this example uses a pinned (non-latest) React version
+      def pinned_react_version?
+        !react_version.nil?
+      end
+
+      # Returns the actual React version string to use
+      def react_version_string
+        return nil unless react_version
+
+        REACT_VERSIONS[react_version.to_s] || react_version
+      end
+
+      def initialize(packer_type: nil, name: nil, generator_options: nil, react_version: nil)
+        @packer_type = packer_type
+        @name = name
+        @generator_options = generator_options
+        @react_version = react_version
+
+        # Validate react_version is a known version to catch configuration errors early
+        if @react_version && !REACT_VERSIONS.key?(@react_version.to_s)
+          valid_versions = REACT_VERSIONS.keys.join(", ")
+          raise ArgumentError, "Invalid react_version '#{@react_version}' for example '#{name}'. " \
+                               "Valid versions: #{valid_versions}"
+        end
+
+        self.class.all[packer_type.to_sym] << self
+      end
+
+      def name_pretty
+        "#{@name} example app"
+      end
+
+      def dir
+        File.join(examples_dir, name)
+      end
+
+      def dir_exist?
+        Dir.exist?(dir)
+      end
+
+      def gemfile
+        File.join(dir, "Gemfile")
+      end
+
+      # Options we pass when running `rails new` from the command-line.
+      attr_writer :rails_options
+
+      def rails_options
+        @rails_options ||= if ReactOnRails::Utils.rails_version_less_than("7.0")
+                             "--skip-bundle --skip-spring --skip-git --skip-test-unit --skip-active-record -J"
+                           else
+                             "--skip-bundle --skip-spring --skip-git --skip-test-unit --skip-active-record -j webpack"
+                           end
+      end
+
+      %w[gen clobber npm_install build_webpack_bundles].each do |task_type|
+        method_name_normal = "#{task_type}_task_name"          # ex: `clean_task_name`
+        method_name_short = "#{method_name_normal}_short"      # ex: `clean_task_name_short`
+
+        define_method(method_name_normal) { "#{@packer_type}:#{task_type}_#{name}" }
+        define_method(method_name_short) { "#{task_type}_#{name}" }
+      end
+
+      def rspec_task_name_short
+        "#{packer_type}_#{name}"
+      end
+
+      def rspec_task_name
+        "run_rspec:#{rspec_task_name_short}"
+      end
+
+      # Assumes we are inside a rails app's folder and necessary gems have been installed
+      def generator_shell_commands
+        shell_commands = []
+        shell_commands << "rails generate react_on_rails:install #{generator_options} --ignore-warnings --force"
+        shell_commands << "rails generate react_on_rails:dev_tests #{generator_options}"
+      end
+
+      private
+
+      # Defines globs that scoop up all files (including dotfiles) in given directory
+      def all_files_in_dir(p_dir)
+        [File.join(p_dir, "**", "*"), File.join(p_dir, "**", ".*")]
+      end
+    end
+  end
+end

data/rakelib/examples_config.yml

@@ -0,0 +1,52 @@
+# Example Type Configuration for React on Rails Generator Tests
+#
+# CI Test Coverage:
+# -----------------
+# - Latest CI (all PRs): Runs shakapacker_examples_latest (React 19, Shakapacker 9.x)
+#                        Examples: basic, basic-server-rendering, redux, redux-server-rendering
+#
+# - Pinned CI (master):  Runs shakapacker_examples_pinned (React 16, 17, 18 with Shakapacker 8.2.0)
+#                        Examples: basic-react16, basic-server-rendering-react16,
+#                                  basic-react17, basic-server-rendering-react17,
+#                                  basic-react18, basic-server-rendering-react18
+#
+# Terminology:
+# - "Latest" = Current React version (19) with latest Shakapacker (9.x)
+# - "Pinned" = Specific older React versions (16, 17, 18) for backward compatibility testing
+#
+# Note: We support React 16+ but test with latest patch of each major version.
+
+example_type_data:
+  # Latest versions (React 19, Shakapacker 9.x)
+  - name: basic
+    generator_options: ''
+  - name: basic-server-rendering
+    generator_options: --example-server-rendering
+  - name: redux
+    generator_options: --redux
+  - name: redux-server-rendering
+    generator_options: --redux --example-server-rendering
+
+  # React 18 compatibility tests (uses Root API introduced in React 18)
+  - name: basic-react18
+    generator_options: ''
+    react_version: '18'
+  - name: basic-server-rendering-react18
+    generator_options: --example-server-rendering
+    react_version: '18'
+
+  # React 17 compatibility tests (legacy render/hydrate API)
+  - name: basic-react17
+    generator_options: ''
+    react_version: '17'
+  - name: basic-server-rendering-react17
+    generator_options: --example-server-rendering
+    react_version: '17'
+
+  # React 16 compatibility tests (oldest supported legacy API)
+  - name: basic-react16
+    generator_options: ''
+    react_version: '16'
+  - name: basic-server-rendering-react16
+    generator_options: --example-server-rendering
+    react_version: '16'

data/rakelib/lint.rake

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "task_helpers"
+
+namespace :lint do # rubocop:disable Metrics/BlockLength
+  include ReactOnRails::TaskHelpers
+
+  desc "Run Rubocop as shell"
+  task :rubocop do
+    sh_in_dir(gem_root, "bundle exec rubocop --version", "bundle exec rubocop .")
+  end
+
+  desc "Run stylelint as shell"
+  task :scss do
+    sh_in_dir(gem_root, stylelint_command)
+  end
+
+  desc "Run eslint as shell"
+  task :eslint do
+    sh_in_dir(gem_root, "pnpm run eslint --version", "pnpm run eslint .")
+  end
+
+  desc "Run all eslint, rubocop & stylelint linters"
+  task lint: %i[eslint rubocop scss] do
+    puts "Completed all linting"
+  end
+
+  desc "Auto-fix all linting violations"
+  task :autofix do
+    sh_in_dir(gem_root, "pnpm run eslint . --fix")
+    sh_in_dir(gem_root, "pnpm run prettier --write .")
+    sh_in_dir(gem_root, stylelint_fix_command)
+    sh_in_dir(gem_root, "bundle exec rubocop -A")
+    puts "Completed auto-fixing all linting violations"
+  end
+
+  private
+
+  def stylelint_command
+    "pnpm run stylelint \"spec/dummy/app/assets/stylesheets/**/*.scss\" \"spec/dummy/client/**/*.scss\""
+  end
+
+  def stylelint_fix_command
+    "#{stylelint_command} --fix"
+  end
+end
+
+desc "Runs all linters. Run `rake -D lint` to see all available lint options"
+task lint: ["lint:lint"]
+
+desc "Auto-fix all linting violations (eslint --fix, prettier --write, rubocop -A)"
+task autofix: ["lint:autofix"]

data/rakelib/node_package.rake

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "task_helpers"
+
+namespace :node_package do
+  include ReactOnRails::TaskHelpers
+
+  task :build do
+    puts "Building Node Package and running 'yalc publish'"
+    sh "pnpm run build && pnpm yalc:publish"
+  end
+end
+
+desc "Prepares node_package by building and symlinking any example/dummy apps present"
+task node_package: "node_package:build"

data/rakelib/rbs.rake

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+# rubocop:disable Metrics/BlockLength
+namespace :rbs do
+  desc "Validate RBS type signatures"
+  task :validate do
+    require "rbs"
+    require "rbs/cli"
+
+    puts "Validating RBS type signatures..."
+
+    # Use Open3 for better error handling - captures stdout, stderr, and exit status separately
+    # This allows us to distinguish between actual validation errors and warnings
+    # Note: Must use bundle exec even though rake runs in bundle context because
+    # spawned shell commands via Open3.capture3() do NOT inherit bundle context
+    # Wrap in Timeout to prevent hung processes in CI environments (60 second timeout)
+    stdout, stderr, status = Timeout.timeout(60) do
+      Open3.capture3("bundle exec rbs -I sig validate")
+    end
+
+    if status.success?
+      puts "✓ RBS validation passed"
+    else
+      puts "✗ RBS validation failed"
+      puts stdout unless stdout.empty?
+      warn stderr unless stderr.empty?
+      exit 1
+    end
+  end
+
+  desc "Check RBS type signatures (alias for validate)"
+  task check: :validate
+
+  desc "List all RBS files"
+  task :list do
+    sig_files = Dir.glob("sig/**/*.rbs")
+    puts "RBS type signature files:"
+    sig_files.each { |f| puts "  #{f}" }
+    puts "\nTotal: #{sig_files.count} files"
+  end
+
+  desc "Run Steep type checker"
+  task :steep do
+    puts "Running Steep type checker..."
+
+    # Use Open3 for better error handling
+    # Note: Must use bundle exec even though rake runs in bundle context because
+    # spawned shell commands via Open3.capture3() do NOT inherit bundle context
+    # Wrap in Timeout to prevent hung processes in CI environments (60 second timeout)
+    stdout, stderr, status = Timeout.timeout(60) do
+      Open3.capture3("bundle exec steep check")
+    end
+
+    if status.success?
+      puts "✓ Steep type checking passed"
+    else
+      puts "✗ Steep type checking failed"
+      puts stdout unless stdout.empty?
+      warn stderr unless stderr.empty?
+      exit 1
+    end
+  end
+
+  desc "Run all RBS checks (validate + steep)"
+  task all: %i[validate steep]
+end
+# rubocop:enable Metrics/BlockLength

data/rakelib/run_rspec.rake

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "coveralls/rake/task" if ENV["USE_COVERALLS"] == "TRUE"
+
+require "pathname"
+require "yaml"
+
+require_relative "task_helpers"
+require_relative "example_type"
+
+# rubocop:disable Metrics/BlockLength
+namespace :run_rspec do
+  include ReactOnRails::TaskHelpers
+
+  # Loads data from examples_config.yml and instantiates corresponding ExampleType objects
+  examples_config_file = File.expand_path("examples_config.yml", __dir__)
+  examples_config = symbolize_keys(YAML.safe_load_file(examples_config_file))
+  examples_config[:example_type_data].each do |example_type_data|
+    ExampleType.new(packer_type: "shakapacker_examples", **symbolize_keys(example_type_data))
+  end
+
+  spec_dummy_dir = File.join(gem_root, "spec", "dummy")
+
+  # RBS Runtime Type Checking Configuration
+  # ========================================
+  # Runtime type checking is ENABLED BY DEFAULT when RBS gem is available
+  # Use ENV["DISABLE_RBS_RUNTIME_CHECKING"] = "true" to disable
+  #
+  # Coverage Strategy:
+  # - :gem task - Enables checking for ReactOnRails::* (direct gem unit tests)
+  # - :dummy tasks - Enables checking (integration tests exercise gem code paths)
+  # - :example tasks - No checking (examples are user-facing demo apps)
+  #
+  # Rationale per Evil Martians best practices:
+  # Runtime checking catches type errors in actual execution paths that static
+  # analysis might miss. Dummy/integration tests exercise more code paths than
+  # unit tests alone, providing comprehensive type safety validation.
+  def rbs_runtime_env_vars
+    return "" if ENV["DISABLE_RBS_RUNTIME_CHECKING"] == "true"
+
+    begin
+      require "rbs"
+      # Preserve existing RUBYOPT flags (e.g., --enable-yjit, --jit, warnings toggles)
+      # by appending RBS runtime hook instead of replacing
+      existing_rubyopt = ENV.fetch("RUBYOPT", nil)
+      rubyopt_parts = ["-rrbs/test/setup", existing_rubyopt].compact.reject(&:empty?)
+      "RBS_TEST_TARGET='ReactOnRails::*' RUBYOPT='#{rubyopt_parts.join(' ')}'"
+    rescue LoadError
+      # RBS not available - silently skip runtime checking
+      # This is expected in environments without the rbs gem
+      ""
+    end
+  end
+
+  desc "Run RSpec for top level only"
+  task :gem do
+    run_tests_in("",
+                 rspec_args: File.join("spec", "react_on_rails"),
+                 env_vars: rbs_runtime_env_vars)
+  end
+
+  desc "Runs dummy rspec with turbolinks"
+  task dummy: ["dummy_apps:dummy_app"] do
+    run_tests_in(spec_dummy_dir,
+                 env_vars: rbs_runtime_env_vars)
+  end
+
+  desc "Runs dummy rspec without turbolinks"
+  task dummy_no_turbolinks: ["dummy_apps:dummy_app"] do
+    # Build env vars array for robustness with complex environment variables
+    env_vars_array = []
+    env_vars_array << rbs_runtime_env_vars unless rbs_runtime_env_vars.empty?
+    env_vars_array << "DISABLE_TURBOLINKS=TRUE"
+    env_vars = env_vars_array.join(" ")
+    run_tests_in(spec_dummy_dir,
+                 env_vars: env_vars,
+                 command_name: "dummy_no_turbolinks")
+  end
+
+  # Dynamically define Rake tasks for each example app found in the examples directory
+  ExampleType.all[:shakapacker_examples].each do |example_type|
+    puts "Creating #{example_type.rspec_task_name} task"
+    desc "Runs RSpec for #{example_type.name_pretty} only"
+    task example_type.rspec_task_name_short => example_type.gen_task_name do
+      # Use unbundled mode for pinned React version examples to ensure the example app's
+      # Gemfile and gem versions are used, not the parent workspace's bundle
+      run_tests_in(File.join(examples_dir, example_type.name),
+                   unbundled: example_type.pinned_react_version?)
+    end
+  end
+
+  desc "Runs Rspec for shakapacker example apps only"
+  task shakapacker_examples: "shakapacker_examples:gen_all" do
+    ExampleType.all[:shakapacker_examples].each { |example_type| Rake::Task[example_type.rspec_task_name].invoke }
+  end
+
+  # Helper methods for filtering examples by React version
+  def latest_examples
+    ExampleType.all[:shakapacker_examples].reject(&:pinned_react_version?)
+  end
+
+  def react18_examples
+    ExampleType.all[:shakapacker_examples].select { |e| e.react_version == "18" }
+  end
+
+  def react17_examples
+    ExampleType.all[:shakapacker_examples].select { |e| e.react_version == "17" }
+  end
+
+  def react16_examples
+    ExampleType.all[:shakapacker_examples].select { |e| e.react_version == "16" }
+  end
+
+  def pinned_version_examples
+    ExampleType.all[:shakapacker_examples].select(&:pinned_react_version?)
+  end
+
+  desc "Runs Rspec for latest version example apps only (React 19, Shakapacker 9.x)"
+  task shakapacker_examples_latest: latest_examples.map(&:gen_task_name) do
+    latest_examples.each { |example_type| Rake::Task[example_type.rspec_task_name].invoke }
+  end
+
+  desc "Runs Rspec for React 18 example apps only (Shakapacker 8.2.0)"
+  task shakapacker_examples_react18: react18_examples.map(&:gen_task_name) do
+    react18_examples.each { |example_type| Rake::Task[example_type.rspec_task_name].invoke }
+  end
+
+  desc "Runs Rspec for React 17 example apps only (legacy render API)"
+  task shakapacker_examples_react17: react17_examples.map(&:gen_task_name) do
+    react17_examples.each { |example_type| Rake::Task[example_type.rspec_task_name].invoke }
+  end
+
+  desc "Runs Rspec for React 16 example apps only (oldest supported legacy API)"
+  task shakapacker_examples_react16: react16_examples.map(&:gen_task_name) do
+    react16_examples.each { |example_type| Rake::Task[example_type.rspec_task_name].invoke }
+  end
+
+  desc "Runs Rspec for all pinned version example apps (React 16, 17, and 18)"
+  task shakapacker_examples_pinned: pinned_version_examples.map(&:gen_task_name) do
+    pinned_version_examples.each { |example_type| Rake::Task[example_type.rspec_task_name].invoke }
+  end
+
+  Coveralls::RakeTask.new if ENV["USE_COVERALLS"] == "TRUE"
+
+  desc "run all tests no examples"
+  task all_but_examples: %i[gem dummy_no_turbolinks dummy js_tests] do
+    puts "Completed all RSpec tests"
+  end
+
+  desc "run all dummy tests"
+  task all_dummy: %i[dummy_no_turbolinks dummy] do
+    puts "Completed all RSpec tests"
+  end
+
+  desc "run all tests"
+  task :run_rspec, [:packer] => ["all_but_examples"] do
+    Rake::Task["run_rspec:#{packer}_examples"].invoke
+    puts "Completed all RSpec tests"
+  end
+end
+# rubocop:enable Metrics/BlockLength
+
+desc "js tests (same as 'pnpm run test')"
+task :js_tests do
+  sh "pnpm run test"
+end
+
+msg = <<~DESC
+  Runs all tests, run `rake -D run_rspec` to see all available test options.
+  "rake run_rspec:example_basic" is a good way to run only one generator test.
+DESC
+desc msg
+task run_rspec: ["run_rspec:run_rspec"]
+
+def calc_path(dir)
+  if dir.is_a?(String)
+    if dir.start_with?(File::SEPARATOR)
+      Pathname.new(dir)
+    else
+      Pathname.new(File.join(gem_root, dir))
+    end
+  else
+    dir
+  end
+end
+
+# Runs rspec in the given directory.
+# If string is passed and it's not absolute, it's converted relative to root of the gem.
+# TEST_ENV_COMMAND_NAME is used to make SimpleCov.command_name unique in order to
+# prevent a name collision. Defaults to the given directory's name.
+# Options:
+#   :command_name - name for SimpleCov (default: dir basename)
+#   :rspec_args - additional rspec arguments (default: "")
+#   :env_vars - additional environment variables (default: "")
+#   :unbundled - run with unbundled_sh_in_dir for Bundler isolation (default: false)
+#                This is required for pinned version examples because they have different
+#                gem versions (e.g., Shakapacker 8.2.0) pinned in their Gemfile than the
+#                parent workspace (Shakapacker 9.x). Without bundle isolation, Bundler
+#                would inherit the parent's gem resolution and use the wrong versions.
+#                Latest version examples don't need this because they use the same versions
+#                as the parent workspace.
+def run_tests_in(dir, options = {})
+  path = calc_path(dir)
+
+  command_name = options.fetch(:command_name, path.basename)
+  rspec_args = options.fetch(:rspec_args, "")
+  unbundled = options.fetch(:unbundled, false)
+
+  # Build environment variables as an array for proper spacing
+  env_tokens = []
+  env_tokens << options.fetch(:env_vars, "").strip unless options.fetch(:env_vars, "").strip.empty?
+  env_tokens << "TEST_ENV_COMMAND_NAME=\"#{command_name}\""
+  env_tokens << "COVERAGE=true" if ENV["USE_COVERALLS"]
+
+  env_vars = env_tokens.join(" ")
+  command = "#{env_vars} bundle exec rspec #{rspec_args}"
+
+  if unbundled
+    unbundled_sh_in_dir(path.realpath, command)
+  else
+    sh_in_dir(path.realpath, command)
+  end
+end