Implement code review recommendations: improve thread-safety, tests, and deprecation detection

- Add comprehensive unit tests for ReactOnRails::Utils.normalize_immediate_hydration
  - Tests for Pro/non-Pro license scenarios
  - Tests for invalid value type validation
  - Tests for warning messages with component/store names

- Add tests for deprecated config.immediate_hydration setter/getter
  - Tests for deprecation warnings on both setter and getter
  - Tests for warning suppression (only warns once)
  - Tests for setter/getter interaction scenarios

- Fix thread-safety of deprecation warning flag
  - Implement Mutex-based synchronization for @immediate_hydration_warned flag
  - Ensures safe access in multi-threaded environments (Puma, Sidekiq, etc.)

- Add doctor.rb detection for deprecated config.immediate_hydration
  - Helps users identify and remove deprecated configuration during migration
  - Provides clear guidance on automatic behavior for Pro users

- Remove unnecessary blank line in controller.rb for cleaner code

All tests passing. Zero RuboCop violations.

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

Co-Authored-By: Claude <[email protected]>

Author: justin808

lib/react_on_rails/configuration.rb

@@ -66,18 +66,25 @@ class Configuration
                   :component_registry_timeout,
                   :server_bundle_output_path, :enforce_private_server_bundles
 
-    # Class instance variable to track if deprecation warning has been shown
+    # Class instance variable and mutex to track if deprecation warning has been shown
+    # Using mutex to ensure thread-safety in multi-threaded environments
     @immediate_hydration_warned = false
+    @immediate_hydration_mutex = Mutex.new
 
     class << self
-      attr_accessor :immediate_hydration_warned
+      attr_accessor :immediate_hydration_warned, :immediate_hydration_mutex
     end
 
     # Deprecated: immediate_hydration configuration has been removed
     def immediate_hydration=(value)
-      return if self.class.immediate_hydration_warned
+      warned = false
+      self.class.immediate_hydration_mutex.synchronize do
+        warned = self.class.immediate_hydration_warned
+        self.class.immediate_hydration_warned = true unless warned
+      end
+
+      return if warned
 
-      self.class.immediate_hydration_warned = true
       Rails.logger.warn <<~WARNING
         [REACT ON RAILS] The 'config.immediate_hydration' configuration option is deprecated and no longer used.
         Immediate hydration is now automatically enabled for React on Rails Pro users.
@@ -87,9 +94,14 @@ def immediate_hydration=(value)
     end
 
     def immediate_hydration
-      return nil if self.class.immediate_hydration_warned
+      warned = false
+      self.class.immediate_hydration_mutex.synchronize do
+        warned = self.class.immediate_hydration_warned
+        self.class.immediate_hydration_warned = true unless warned
+      end
+
+      return nil if warned
 
-      self.class.immediate_hydration_warned = true
       Rails.logger.warn <<~WARNING
         [REACT ON RAILS] The 'config.immediate_hydration' configuration option is deprecated and no longer used.
         Immediate hydration is now automatically enabled for React on Rails Pro users.

lib/react_on_rails/controller.rb

@@ -16,7 +16,6 @@ module Controller
     # or else there will be no client side hydration of your stores.
     def redux_store(store_name, props: {}, immediate_hydration: nil)
       immediate_hydration = ReactOnRails::Utils.normalize_immediate_hydration(immediate_hydration, store_name, "Store")
-
       redux_store_data = { store_name: store_name,
                            props: props,
                            immediate_hydration: immediate_hydration }

lib/react_on_rails/doctor.rb

@@ -701,7 +701,7 @@ def analyze_server_rendering_config(content)
     end
     # rubocop:enable Metrics/AbcSize
 
-    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
     def analyze_performance_config(content)
       checker.add_info("\n⚡ Performance & Loading:")
 
@@ -732,13 +732,21 @@ def analyze_performance_config(content)
       auto_load_match = content.match(/config\.auto_load_bundle\s*=\s*([^\s\n,]+)/)
       checker.add_info("  auto_load_bundle: #{auto_load_match[1]}") if auto_load_match
 
+      # Deprecated immediate_hydration setting
+      immediate_hydration_match = content.match(/config\.immediate_hydration\s*=\s*([^\s\n,]+)/)
+      if immediate_hydration_match
+        checker.add_warning("  ⚠️  immediate_hydration: #{immediate_hydration_match[1]} (DEPRECATED)")
+        checker.add_info("    💡 This setting is no longer used. Immediate hydration is now automatic for Pro users.")
+        checker.add_info("    💡 Remove this line from your config/initializers/react_on_rails.rb file.")
+      end
+
       # Component registry timeout
       timeout_match = content.match(/config\.component_registry_timeout\s*=\s*([^\s\n,]+)/)
       return unless timeout_match
 
       checker.add_info("  component_registry_timeout: #{timeout_match[1]}ms")
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
     # rubocop:disable Metrics/AbcSize
     def analyze_development_config(content)

spec/react_on_rails/configuration_spec.rb

@@ -366,6 +366,118 @@ module ReactOnRails
       end
     end
 
+    describe ".immediate_hydration (deprecated)" do
+      before do
+        # Reset the warning flag before each test
+        described_class.immediate_hydration_warned = false
+        allow(Rails.logger).to receive(:warn)
+      end
+
+      after do
+        # Reset the warning flag after each test
+        described_class.immediate_hydration_warned = false
+      end
+
+      describe "setter" do
+        it "logs a deprecation warning when setting to true" do
+          ReactOnRails.configure do |config|
+            config.immediate_hydration = true
+          end
+
+          expect(Rails.logger).to have_received(:warn)
+            .with(/immediate_hydration' configuration option is deprecated/)
+        end
+
+        it "logs a deprecation warning when setting to false" do
+          ReactOnRails.configure do |config|
+            config.immediate_hydration = false
+          end
+
+          expect(Rails.logger).to have_received(:warn)
+            .with(/immediate_hydration' configuration option is deprecated/)
+        end
+
+        it "mentions the value in the warning message" do
+          ReactOnRails.configure do |config|
+            config.immediate_hydration = true
+          end
+
+          expect(Rails.logger).to have_received(:warn) do |message|
+            expect(message).to include("config.immediate_hydration = true")
+          end
+        end
+
+        it "only logs the warning once even if called multiple times" do
+          ReactOnRails.configure do |config|
+            config.immediate_hydration = true
+            config.immediate_hydration = false
+            config.immediate_hydration = true
+          end
+
+          expect(Rails.logger).to have_received(:warn).once
+        end
+      end
+
+      describe "getter" do
+        it "logs a deprecation warning when accessed" do
+          ReactOnRails.configure {} # rubocop:disable Lint/EmptyBlock
+
+          ReactOnRails.configuration.immediate_hydration
+
+          expect(Rails.logger).to have_received(:warn)
+            .with(/immediate_hydration' configuration option is deprecated/)
+        end
+
+        it "returns nil" do
+          ReactOnRails.configure {} # rubocop:disable Lint/EmptyBlock
+
+          result = ReactOnRails.configuration.immediate_hydration
+
+          expect(result).to be_nil
+        end
+
+        it "only logs the warning once even if called multiple times" do
+          ReactOnRails.configure {} # rubocop:disable Lint/EmptyBlock
+
+          ReactOnRails.configuration.immediate_hydration
+          ReactOnRails.configuration.immediate_hydration
+          ReactOnRails.configuration.immediate_hydration
+
+          expect(Rails.logger).to have_received(:warn).once
+        end
+      end
+
+      describe "setter and getter interactions" do
+        it "does not warn again on getter if setter already warned" do
+          ReactOnRails.configure do |config|
+            config.immediate_hydration = true
+          end
+
+          expect(Rails.logger).to have_received(:warn).once
+
+          ReactOnRails.configuration.immediate_hydration
+
+          # Still only one warning total
+          expect(Rails.logger).to have_received(:warn).once
+        end
+
+        it "does not warn again on setter if getter already warned" do
+          ReactOnRails.configure {} # rubocop:disable Lint/EmptyBlock
+
+          ReactOnRails.configuration.immediate_hydration
+
+          expect(Rails.logger).to have_received(:warn).once
+
+          ReactOnRails.configure do |config|
+            config.immediate_hydration = true
+          end
+
+          # Still only one warning total
+          expect(Rails.logger).to have_received(:warn).once
+        end
+      end
+    end
+
     describe "enforce_private_server_bundles validation" do
       context "when enforce_private_server_bundles is true" do
         before do

spec/react_on_rails/utils_spec.rb

@@ -898,6 +898,100 @@ def self.configuration=(config)
     end
 
     # RSC utility method tests moved to react_on_rails_pro/spec/react_on_rails_pro/utils_spec.rb
+
+    describe ".normalize_immediate_hydration" do
+      context "with Pro license" do
+        before do
+          allow(described_class).to receive(:react_on_rails_pro?).and_return(true)
+        end
+
+        it "returns true when value is explicitly true" do
+          result = described_class.normalize_immediate_hydration(true, "TestComponent", "Component")
+          expect(result).to be true
+        end
+
+        it "returns false when value is explicitly false" do
+          result = described_class.normalize_immediate_hydration(false, "TestComponent", "Component")
+          expect(result).to be false
+        end
+
+        it "returns true when value is nil (Pro default)" do
+          result = described_class.normalize_immediate_hydration(nil, "TestComponent", "Component")
+          expect(result).to be true
+        end
+
+        it "does not log a warning for any valid value" do
+          expect(Rails.logger).not_to receive(:warn)
+
+          described_class.normalize_immediate_hydration(true, "TestComponent", "Component")
+          described_class.normalize_immediate_hydration(false, "TestComponent", "Component")
+          described_class.normalize_immediate_hydration(nil, "TestComponent", "Component")
+        end
+      end
+
+      context "without Pro license" do
+        before do
+          allow(described_class).to receive(:react_on_rails_pro?).and_return(false)
+        end
+
+        it "returns false and logs warning when value is explicitly true" do
+          expect(Rails.logger).to receive(:warn)
+            .with(/immediate_hydration: true requires a React on Rails Pro license/)
+
+          result = described_class.normalize_immediate_hydration(true, "TestComponent", "Component")
+          expect(result).to be false
+        end
+
+        it "returns false when value is explicitly false" do
+          expect(Rails.logger).not_to receive(:warn)
+
+          result = described_class.normalize_immediate_hydration(false, "TestComponent", "Component")
+          expect(result).to be false
+        end
+
+        it "returns false when value is nil (non-Pro default)" do
+          expect(Rails.logger).not_to receive(:warn)
+
+          result = described_class.normalize_immediate_hydration(nil, "TestComponent", "Component")
+          expect(result).to be false
+        end
+
+        it "includes component name and type in warning message" do
+          expect(Rails.logger).to receive(:warn) do |message|
+            expect(message).to include("TestStore")
+            expect(message).to include("Store")
+          end
+
+          described_class.normalize_immediate_hydration(true, "TestStore", "Store")
+        end
+      end
+
+      context "with invalid values" do
+        it "raises ArgumentError for string values" do
+          expect do
+            described_class.normalize_immediate_hydration("yes", "TestComponent", "Component")
+          end.to raise_error(ArgumentError, /immediate_hydration must be true, false, or nil/)
+        end
+
+        it "raises ArgumentError for numeric values" do
+          expect do
+            described_class.normalize_immediate_hydration(1, "TestComponent", "Component")
+          end.to raise_error(ArgumentError, /immediate_hydration must be true, false, or nil/)
+        end
+
+        it "raises ArgumentError for hash values" do
+          expect do
+            described_class.normalize_immediate_hydration({}, "TestComponent", "Component")
+          end.to raise_error(ArgumentError, /immediate_hydration must be true, false, or nil/)
+        end
+
+        it "includes the invalid value in error message" do
+          expect do
+            described_class.normalize_immediate_hydration("invalid", "TestComponent", "Component")
+          end.to raise_error(ArgumentError, /Got: "invalid" \(String\)/)
+        end
+      end
+    end
   end
 end
 # rubocop:enable Metrics/ModuleLength, Metrics/BlockLength