Clarify RSC client references rewrite flow

react_on_rails/lib/generators/react_on_rails/rsc_setup/client_references.rb

@@ -121,36 +121,41 @@ def js_line_ending(content)
         end
 
         def update_existing_rsc_webpack_config(config_path, content, is_server:)
-          return unless rsc_plugin_sections_safe_to_rewrite?(config_path, content, is_server: is_server)
+          return unless rsc_plugin_sections_safe_to_rewrite?(config_path, content)
           return if rsc_plugin_uses_scoped_client_references?(content, is_server: is_server)
-          return unless rsc_client_references_rewrite_needed?(config_path, content, is_server: is_server)
+
+          # May inject the scoped helper before the rewrite step re-reads the config from disk.
+          return unless prepare_rsc_client_references_setup(config_path, content, is_server: is_server)
+          return unless rsc_plugin_needs_client_references_rewrite?(content, is_server: is_server)
 
           return if rewrite_rsc_plugin_client_references(config_path, is_server: is_server)
 
           rollback_incomplete_rsc_client_references_setup(config_path, content)
           warn_missing_rsc_plugin_target(config_path, is_server: is_server)
         end
 
-        def rsc_client_references_rewrite_needed?(config_path, content, is_server:)
-          # This predicate prepares the rewrite too: when it returns true, the scoped helper
-          # may already have been injected on disk so `rewrite_rsc_plugin_client_references`
-          # can re-read fresh content with valid offsets.
+        def prepare_rsc_client_references_setup(config_path, content, is_server:)
           if rsc_plugin_references_any_scoped_client_references?(content, is_server: is_server)
-            return false unless ensure_rsc_client_references_setup(config_path, content, is_server: is_server)
-
-            return rsc_plugin_without_client_references?(content, is_server: is_server)
+            return ensure_rsc_client_references_setup(config_path, content, is_server: is_server)
           end
 
           rewritable_rsc_plugin?(config_path, content, is_server: is_server) &&
             ensure_rsc_client_references_setup(config_path, content, is_server: is_server)
         end
 
+        def rsc_plugin_needs_client_references_rewrite?(content, is_server:)
+          rsc_plugin_without_client_references?(content, is_server: is_server)
+        end
+
         # Detects RSCWebpackPlugin option blocks that the lightweight JS scanner could not parse
         # cleanly (most often a regex literal with an unmatched `{` / `}` that walks the depth
         # counter past the real closing brace). When found, we warn and refuse to rewrite anything
         # in the file so a sibling rewrite cannot accidentally splice into a wrong location.
-        def rsc_plugin_sections_safe_to_rewrite?(config_path, content, is_server:)
-          unparseable = rsc_plugin_option_sections_partition(content, is_server: is_server).fetch(:unparseable)
+        def rsc_plugin_sections_safe_to_rewrite?(config_path, content)
+          # The unparseable count is file-wide: the partition increments it for every invocation
+          # that cannot be parsed, regardless of the `is_server` argument. The argument only
+          # filters the target-specific safe bucket, which is ignored here.
+          unparseable = rsc_plugin_option_sections_partition(content, is_server: true).fetch(:unparseable)
           return true if unparseable.zero?
 
           warn_unparseable_rsc_plugin_sections(config_path, unparseable)

react_on_rails/spec/react_on_rails/generators/rsc_generator_spec.rb

@@ -2069,7 +2069,7 @@
       )
       content = File.read(File.join(destination_root, config_path))
 
-      expect(generator.send(:rsc_plugin_sections_safe_to_rewrite?, config_path, content, is_server: true))
+      expect(generator.send(:rsc_plugin_sections_safe_to_rewrite?, config_path, content))
         .to be(false)
 
       messages = GeneratorMessages.messages.join("\n")
@@ -2113,6 +2113,57 @@
       expect(false_partition.fetch(:safe).length).to eq(1)
     end
 
+    it "keeps the client references rewrite predicate free of file writes" do
+      config_path = "config/webpack/clientWebpackConfig.js"
+      simulate_existing_file(
+        config_path,
+        <<~JS
+          const commonWebpackConfig = require('./commonWebpackConfig');
+          const { RSCWebpackPlugin } = require('react-on-rails-rsc/WebpackPlugin');
+
+          const configureClient = () => {
+            const clientConfig = commonWebpackConfig();
+            clientConfig.plugins.push(
+              new RSCWebpackPlugin({
+                isServer: false,
+                clientReferences: rscClientReferences,
+              }),
+            );
+
+            return clientConfig;
+          };
+
+          module.exports = configureClient;
+        JS
+      )
+
+      full_path = File.join(destination_root, config_path)
+      content = File.read(full_path)
+
+      expect(generator.send(:rsc_plugin_needs_client_references_rewrite?, content, is_server: false))
+        .to be(false)
+      expect(File.read(full_path)).to eq(content)
+    end
+
+    it "returns true from the client references rewrite predicate without file writes" do
+      config_path = "config/webpack/clientWebpackConfig.js"
+      simulate_existing_file(
+        config_path,
+        <<~JS
+          const { RSCWebpackPlugin } = require('react-on-rails-rsc/WebpackPlugin');
+
+          clientConfig.plugins.push(new RSCWebpackPlugin({ isServer: false }));
+        JS
+      )
+
+      full_path = File.join(destination_root, config_path)
+      content = File.read(full_path)
+
+      expect(generator.send(:rsc_plugin_needs_client_references_rewrite?, content, is_server: false))
+        .to be(true)
+      expect(File.read(full_path)).to eq(content)
+    end
+
     it "does not inject duplicate imports for legacy let or var CommonJS destructuring" do
       config_path = "config/webpack/clientWebpackConfig.js"
       simulate_existing_file(