Add doctor checks to detect :async usage without React on Rails Pro

Adds proactive detection of :async loading strategy usage in projects
without React on Rails Pro, which can cause component registration race
conditions.

The doctor now checks for:
1. javascript_pack_tag with :async in view files
2. config.generated_component_packs_loading_strategy = :async in initializer

When detected without Pro, provides clear guidance:
- Upgrade to React on Rails Pro (recommended)
- Change to :defer or :sync loading strategy

This complements PR #1993's configuration validation by adding runtime
doctor checks that help users identify and fix async usage issues during
development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: justin808

lib/react_on_rails/doctor.rb

@@ -173,6 +173,7 @@ def check_development
       check_procfile_dev
       check_bin_dev_script
       check_gitignore
+      check_async_usage
     end
 
     def check_javascript_bundles
@@ -1146,6 +1147,72 @@ def safe_display_config_value(label, config, method_name)
         checker.add_info("  #{label}: <error reading value: #{e.message}>")
       end
     end
+
+    def check_async_usage
+      # When Pro is installed, async is fully supported and is the default behavior
+      # No need to check for async usage in this case
+      return if ReactOnRails::Utils.react_on_rails_pro?
+
+      async_issues = []
+
+      # Check 1: javascript_pack_tag with :async in view files
+      view_files_with_async = scan_view_files_for_async_pack_tag
+      unless view_files_with_async.empty?
+        async_issues << "javascript_pack_tag with :async found in view files:"
+        view_files_with_async.each do |file|
+          async_issues << "  • #{file}"
+        end
+      end
+
+      # Check 2: generated_component_packs_loading_strategy = :async
+      if config_has_async_loading_strategy?
+        async_issues << "config.generated_component_packs_loading_strategy = :async in initializer"
+      end
+
+      return if async_issues.empty?
+
+      # Report errors if async usage is found without Pro
+      checker.add_error("🚫 :async usage detected without React on Rails Pro")
+      async_issues.each { |issue| checker.add_error("  #{issue}") }
+      checker.add_info("  💡 :async can cause race conditions. Options:")
+      checker.add_info("    1. Upgrade to React on Rails Pro (recommended for :async support)")
+      checker.add_info("    2. Change to :defer or :sync loading strategy")
+      checker.add_info("  📖 https://www.shakacode.com/react-on-rails/docs/guides/configuration/")
+    end
+
+    def scan_view_files_for_async_pack_tag
+      files_with_async = []
+
+      # Scan app/views for .erb and .haml files
+      view_patterns = ["app/views/**/*.erb", "app/views/**/*.haml"]
+
+      view_patterns.each do |pattern|
+        Dir.glob(pattern).each do |file|
+          next unless File.exist?(file)
+
+          content = File.read(file)
+          # Look for javascript_pack_tag with :async or "async"
+          if content.match?(/javascript_pack_tag.*:async/) || content.match?(/javascript_pack_tag.*["']async["']/)
+            files_with_async << relativize_path(file)
+          end
+        end
+      end
+
+      files_with_async
+    rescue StandardError
+      []
+    end
+
+    def config_has_async_loading_strategy?
+      config_path = "config/initializers/react_on_rails.rb"
+      return false unless File.exist?(config_path)
+
+      content = File.read(config_path)
+      # Check if generated_component_packs_loading_strategy is set to :async
+      content.match?(/config\.generated_component_packs_loading_strategy\s*=\s*:async/)
+    rescue StandardError
+      false
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

spec/lib/react_on_rails/doctor_spec.rb

@@ -188,4 +188,160 @@
       end
     end
   end
+
+  describe "#check_async_usage" do
+    let(:checker) { instance_double(ReactOnRails::SystemChecker) }
+
+    before do
+      allow(doctor).to receive(:checker).and_return(checker)
+      allow(checker).to receive_messages(add_error: true, add_warning: true, add_info: true)
+      allow(File).to receive(:exist?).and_call_original
+      allow(Dir).to receive(:glob).and_return([])
+    end
+
+    context "when Pro gem is installed" do
+      before do
+        allow(ReactOnRails::Utils).to receive(:react_on_rails_pro?).and_return(true)
+      end
+
+      it "skips the check" do
+        doctor.send(:check_async_usage)
+        expect(checker).not_to have_received(:add_error)
+        expect(checker).not_to have_received(:add_warning)
+      end
+    end
+
+    context "when Pro gem is not installed" do
+      before do
+        allow(ReactOnRails::Utils).to receive(:react_on_rails_pro?).and_return(false)
+      end
+
+      context "when async is used in view files" do
+        before do
+          allow(Dir).to receive(:glob).with("app/views/**/*.erb").and_return(["app/views/layouts/application.html.erb"])
+          allow(Dir).to receive(:glob).with("app/views/**/*.haml").and_return([])
+          allow(File).to receive(:exist?).with("app/views/layouts/application.html.erb").and_return(true)
+          allow(File).to receive(:read).with("app/views/layouts/application.html.erb")
+                                       .and_return('<%= javascript_pack_tag "application", :async %>')
+          allow(File).to receive(:exist?).with("config/initializers/react_on_rails.rb").and_return(false)
+          allow(doctor).to receive(:relativize_path).with("app/views/layouts/application.html.erb")
+                                                    .and_return("app/views/layouts/application.html.erb")
+        end
+
+        it "reports an error" do
+          doctor.send(:check_async_usage)
+          expect(checker).to have_received(:add_error).with("🚫 :async usage detected without React on Rails Pro")
+          expect(checker).to have_received(:add_error)
+            .with("  javascript_pack_tag with :async found in view files:")
+        end
+      end
+
+      context "when generated_component_packs_loading_strategy is :async" do
+        before do
+          allow(File).to receive(:exist?).with("config/initializers/react_on_rails.rb").and_return(true)
+          allow(File).to receive(:read).with("config/initializers/react_on_rails.rb")
+                                       .and_return("config.generated_component_packs_loading_strategy = :async")
+        end
+
+        it "reports an error" do
+          doctor.send(:check_async_usage)
+          expect(checker).to have_received(:add_error).with("🚫 :async usage detected without React on Rails Pro")
+          expect(checker).to have_received(:add_error)
+            .with("  config.generated_component_packs_loading_strategy = :async in initializer")
+        end
+      end
+
+      context "when no async usage is detected" do
+        before do
+          allow(File).to receive(:exist?).with("config/initializers/react_on_rails.rb").and_return(true)
+          allow(File).to receive(:read).with("config/initializers/react_on_rails.rb")
+                                       .and_return("config.generated_component_packs_loading_strategy = :defer")
+        end
+
+        it "does not report any issues" do
+          doctor.send(:check_async_usage)
+          expect(checker).not_to have_received(:add_error)
+          expect(checker).not_to have_received(:add_warning)
+        end
+      end
+    end
+  end
+
+  describe "#scan_view_files_for_async_pack_tag" do
+    before do
+      allow(Dir).to receive(:glob).and_call_original
+      allow(File).to receive(:exist?).and_call_original
+      allow(File).to receive(:read).and_call_original
+    end
+
+    context "when view files contain javascript_pack_tag with :async" do
+      before do
+        allow(Dir).to receive(:glob).with("app/views/**/*.erb")
+                                    .and_return(["app/views/layouts/application.html.erb"])
+        allow(Dir).to receive(:glob).with("app/views/**/*.haml").and_return([])
+        allow(File).to receive(:exist?).with("app/views/layouts/application.html.erb").and_return(true)
+        allow(File).to receive(:read).with("app/views/layouts/application.html.erb")
+                                     .and_return('<%= javascript_pack_tag "app", :async %>')
+        allow(doctor).to receive(:relativize_path).with("app/views/layouts/application.html.erb")
+                                                  .and_return("app/views/layouts/application.html.erb")
+      end
+
+      it "returns files with async" do
+        files = doctor.send(:scan_view_files_for_async_pack_tag)
+        expect(files).to include("app/views/layouts/application.html.erb")
+      end
+    end
+
+    context "when view files do not contain async" do
+      before do
+        allow(Dir).to receive(:glob).with("app/views/**/*.erb")
+                                    .and_return(["app/views/layouts/application.html.erb"])
+        allow(Dir).to receive(:glob).with("app/views/**/*.haml").and_return([])
+        allow(File).to receive(:exist?).with("app/views/layouts/application.html.erb").and_return(true)
+        allow(File).to receive(:read).with("app/views/layouts/application.html.erb")
+                                     .and_return('<%= javascript_pack_tag "app" %>')
+      end
+
+      it "returns empty array" do
+        files = doctor.send(:scan_view_files_for_async_pack_tag)
+        expect(files).to be_empty
+      end
+    end
+  end
+
+  describe "#config_has_async_loading_strategy?" do
+    context "when config file has :async strategy" do
+      before do
+        allow(File).to receive(:exist?).with("config/initializers/react_on_rails.rb").and_return(true)
+        allow(File).to receive(:read).with("config/initializers/react_on_rails.rb")
+                                     .and_return("config.generated_component_packs_loading_strategy = :async")
+      end
+
+      it "returns true" do
+        expect(doctor.send(:config_has_async_loading_strategy?)).to be true
+      end
+    end
+
+    context "when config file has different strategy" do
+      before do
+        allow(File).to receive(:exist?).with("config/initializers/react_on_rails.rb").and_return(true)
+        allow(File).to receive(:read).with("config/initializers/react_on_rails.rb")
+                                     .and_return("config.generated_component_packs_loading_strategy = :defer")
+      end
+
+      it "returns false" do
+        expect(doctor.send(:config_has_async_loading_strategy?)).to be false
+      end
+    end
+
+    context "when config file does not exist" do
+      before do
+        allow(File).to receive(:exist?).with("config/initializers/react_on_rails.rb").and_return(false)
+      end
+
+      it "returns false" do
+        expect(doctor.send(:config_has_async_loading_strategy?)).to be false
+      end
+    end
+  end
 end