react_on_rails 16.6.0 → 16.7.0.rc.0

data/lib/react_on_rails/doctor.rb

@@ -3,12 +3,14 @@
 require "json"
 require "erb"
 require "stringio"
+require "timeout"
 require "yaml"
 require_relative "utils"
 require_relative "config_path_resolver"
 require_relative "version_syntax_converter"
 require_relative "version_synchronizer"
 require_relative "system_checker"
+require_relative "pro_migration"
 
 begin
   require "rainbow"
@@ -55,6 +57,59 @@ module ReactOnRails
     MINITEST_HELPER_FILE = "test/test_helper.rb"
     DEFAULT_BUILD_TEST_COMMAND = 'config.build_test_command = "RAILS_ENV=test bin/shakapacker"'
     DEFAULT_SHAKAPACKER_CONFIG_PATH = "config/shakapacker.yml"
+    SERVER_BUNDLE_SOURCE_EXTENSIONS = %w[.js .jsx .ts .tsx .mjs .cjs].freeze
+    CUSTOM_LAUNCHER_INDICATOR_FILES = %w[dev].freeze
+
+    # Deprecated-renderer-cache scan (used by check_deprecated_renderer_cache_task):
+    # look for references to the old pre_stage_bundle_for_node_renderer task in
+    # common deploy-script locations so users on older Procfile/Dockerfile entries
+    # get a migration nudge before the task is removed.
+    DEPRECATED_RENDERER_CACHE_TASK = "pre_stage_bundle_for_node_renderer"
+    # Fixed allowlist of single-file deploy-script paths. Each entry is a literal
+    # path that may host a deploy hook referencing the deprecated task. Directory
+    # globs (e.g., per-stage Capistrano files or per-workflow GitHub Actions YAML)
+    # live in RENDERER_CACHE_DEPLOY_SCRIPT_GLOBS so they stay bounded.
+    RENDERER_CACHE_DEPLOY_SCRIPT_PATHS = [
+      "Procfile",
+      "Procfile.dev",
+      "Procfile.dev-static-assets",
+      "Procfile.production",
+      "Dockerfile",
+      "Dockerfile.production",
+      "Dockerfile.staging",
+      "Dockerfile.review",
+      "docker-compose.yml",
+      "docker-compose.yaml",
+      "compose.yml",
+      "compose.yaml",
+      "bin/deploy",
+      "bin/release",
+      "bin/docker-entrypoint",
+      "config/deploy.rb",
+      "config/deploy/production.rb",
+      "config/deploy/staging.rb",
+      ".kamal/deploy.yml",
+      "scripts/deploy.sh",
+      ".circleci/config.yml",
+      ".gitlab-ci.yml",
+      "bitbucket-pipelines.yml"
+    ].freeze
+    # Bounded glob allowlist for deploy manifests that live in a known directory
+    # but use per-environment or per-workflow filenames. Each pattern matches
+    # only one directory level (no `**`) so the scan never recurses into the
+    # project tree, and the expansion is capped by
+    # RENDERER_CACHE_DEPLOY_SCRIPT_GLOB_MAX_MATCHES.
+    RENDERER_CACHE_DEPLOY_SCRIPT_GLOBS = [
+      ".github/workflows/*.yml",
+      ".github/workflows/*.yaml",
+      "config/deploy/*.rb"
+    ].freeze
+    # Per-file safety gate to bound IO during the scan, not a meaningful size limit.
+    RENDERER_CACHE_DEPLOY_SCRIPT_MAX_BYTES = 1_048_576
+    # Defense-in-depth cap on how many files a single glob may contribute.
+    # Realistic repos have a handful of workflow / deploy-stage files; far more
+    # than this is a sign of an unexpectedly broad pattern, not legitimate config.
+    RENDERER_CACHE_DEPLOY_SCRIPT_GLOB_MAX_MATCHES = 100
 
     def initialize(verbose: false, fix: false)
       @verbose = verbose
@@ -180,7 +235,7 @@ module ReactOnRails
 
     def check_bin_dev_launcher
       checker.add_info("🚀 bin/dev Launcher:")
-      check_bin_dev_launcher_setup
+      return unless check_bin_dev_launcher_setup
 
       checker.add_info("\n📄 Launcher Procfiles:")
       check_launcher_procfiles
@@ -489,8 +544,8 @@ module ReactOnRails
     end
 
     def check_npm_package_version
-      package_json_path = resolved_package_json_path
-      return unless File.exist?(package_json_path)
+      package_json_path = package_json_path_for("react-on-rails npm package version")
+      return unless package_json_path
 
       begin
         package_json = JSON.parse(File.read(package_json_path))
@@ -605,8 +660,8 @@ module ReactOnRails
     end
 
     def check_npm_wildcards
-      package_json_path = resolved_package_json_path
-      return unless File.exist?(package_json_path)
+      package_json_path = package_json_path_for("npm package version constraints")
+      return unless package_json_path
 
       begin
         package_json = JSON.parse(File.read(package_json_path))
@@ -719,8 +774,8 @@ module ReactOnRails
     end
 
     def auto_fix_versions
-      package_json_path = resolved_package_json_path
-      return unless File.exist?(package_json_path)
+      package_json_path = package_json_path_for("package version auto-sync")
+      return unless package_json_path
 
       synchronizer = ReactOnRails::VersionSynchronizer.new(package_json_path: package_json_path, io: StringIO.new)
       result = synchronizer.sync(write: true)
@@ -764,8 +819,8 @@ module ReactOnRails
     end
 
     def check_pro_package_consistency
-      package_json_path = resolved_package_json_path
-      return unless File.exist?(package_json_path)
+      package_json_path = package_json_path_for("Pro package consistency")
+      return unless package_json_path
 
       package_json = JSON.parse(File.read(package_json_path))
       all_deps = (package_json["dependencies"] || {}).merge(package_json["devDependencies"] || {})
@@ -1423,12 +1478,24 @@ module ReactOnRails
       checker.add_info("  • Modern React patterns recommended")
     end
 
+    # Returns true if bin/dev exists, false otherwise.
+    # Used by check_bin_dev_launcher to decide whether to check Procfiles.
     def check_bin_dev_launcher_setup
       bin_dev_path = "bin/dev"
 
       unless File.exist?(bin_dev_path)
-        checker.add_error("  🚫 bin/dev script not found")
-        return
+        checker.add_warning("  ⚠️  Official React on Rails bin/dev launcher not found")
+        custom_launchers = detected_custom_launcher_paths
+        if custom_launchers.any?
+          checker.add_info(
+            "    ℹ️  Custom launcher detected (#{custom_launchers.join(', ')}). " \
+            "This is OK if your project intentionally manages its own dev workflow."
+          )
+          checker.add_info("    💡 To use the official launcher instead, run: rails generate react_on_rails:install")
+        else
+          checker.add_info("    💡 Generate the official launcher with: rails generate react_on_rails:install")
+        end
+        return false
       end
 
       content = File.read(bin_dev_path)
@@ -1441,6 +1508,8 @@ module ReactOnRails
         checker.add_warning("  ⚠️  bin/dev exists but doesn't use ReactOnRails Launcher")
         checker.add_info("    💡 Consider upgrading: rails generate react_on_rails:install")
       end
+
+      true
     end
 
     def check_launcher_procfiles
@@ -1468,6 +1537,14 @@ module ReactOnRails
       end
     end
 
+    def detected_custom_launcher_paths
+      CUSTOM_LAUNCHER_INDICATOR_FILES.filter_map do |path|
+        next unless File.file?(path)
+
+        path == "dev" ? "./dev" : path
+      end
+    end
+
     def check_test_helper_setup
       framework_status = test_helper_status_by_framework
 
@@ -1535,11 +1612,12 @@ module ReactOnRails
         source_entry_path = source_entry_path.sub("#{source_path}/", "")
       end
 
-      File.join(source_path, source_entry_path, bundle_filename)
+      bundle_path = File.join(source_path, source_entry_path, bundle_filename)
+      resolve_server_bundle_source_path(bundle_path)
     rescue LoadError, StandardError
       # Handle missing Shakapacker gem or other configuration errors
       bundle_filename = server_bundle_filename
-      "app/javascript/packs/#{bundle_filename}"
+      resolve_server_bundle_source_path("app/javascript/packs/#{bundle_filename}")
     end
 
     def server_bundle_filename
@@ -1562,6 +1640,27 @@ module ReactOnRails
       "server-bundle.js"
     end
 
+    def resolve_server_bundle_source_path(bundle_path)
+      return bundle_path if File.exist?(bundle_path)
+
+      base_path = bundle_path.sub(%r{\.[^./]+\z}, "")
+
+      candidate_extensions = server_bundle_source_extensions_for(bundle_path)
+      candidate_extensions.each do |extension|
+        candidate_path = "#{base_path}#{extension}"
+        return candidate_path if File.exist?(candidate_path)
+      end
+
+      bundle_path
+    end
+
+    def server_bundle_source_extensions_for(bundle_path)
+      extension = File.extname(bundle_path)
+      return SERVER_BUNDLE_SOURCE_EXTENSIONS if extension.empty?
+
+      SERVER_BUNDLE_SOURCE_EXTENSIONS.reject { |candidate_extension| candidate_extension == extension }
+    end
+
     def exit_with_status
       if checker.errors?
         puts Rainbow("❌ Doctor found critical issues. Please address errors above.").red.bold
@@ -2670,7 +2769,9 @@ module ReactOnRails
       check_pro_initializer_existence
       ensure_rails_environment_loaded
       check_pro_renderer_mode
-      check_base_package_imports
+      check_base_package_references
+      check_deprecated_renderer_cache_task
+      check_rolling_deploy_adapter
     end
 
     def check_pro_initializer_existence
@@ -2700,45 +2801,389 @@ module ReactOnRails
       checker.add_warning("⚠️  Could not detect Pro renderer mode: #{e.message}")
     end
 
-    # The base 'react-on-rails' npm package is a transitive dependency of 'react-on-rails-pro',
-    # so `import ... from 'react-on-rails'` resolves silently — loading the base package instead
-    # of Pro. Components registered through the base package won't have Pro features (streaming,
-    # caching, RSC), and may cause "component not registered" errors at runtime.
-    BASE_PACKAGE_IMPORT_PATTERN = %r{\bfrom\s+['"]react-on-rails(?:/[^'"]*)?['"]}
-    BASE_PACKAGE_REQUIRE_PATTERN = %r{\brequire\s*\(\s*['"]react-on-rails(?:/[^'"]*)?['"]\s*\)}
+    def check_deprecated_renderer_cache_task
+      # Resolve against Rails.root (not Dir.pwd) so the scan still fires when
+      # doctor is invoked from a subdirectory — otherwise the checks silently
+      # find nothing and the deprecation warning never surfaces.
+      #
+      # Read in binary mode (the task name is pure ASCII) so a non-UTF-8 byte
+      # in a deploy script does not raise Encoding::InvalidByteSequenceError
+      # and mask the file via the rescue below.
+      #
+      # Skip leading-comment lines (`#` is the comment prefix for all scanned
+      # file types: Procfile, Dockerfile, shell scripts, YAML, and Ruby) so
+      # files that mention the old task only inside a comment do not trip the
+      # migration nudge.
+      # Per-file rescue so a transient failure on one path (e.g. Errno::EACCES)
+      # does not abort the whole scan and silently skip the rest. The outer
+      # rescue catches anything that escapes the per-file guard. Globs are
+      # expanded under their own rescue so a failure expanding one pattern
+      # cannot stop other patterns or fixed paths from being scanned.
+      candidate_paths = (
+        RENDERER_CACHE_DEPLOY_SCRIPT_PATHS + expand_renderer_cache_deploy_script_globs
+      ).uniq
+
+      matches = candidate_paths.select do |path|
+        deploy_script_path_references_deprecated_task?(path)
+      end
+
+      return if matches.empty?
 
-    def check_base_package_imports # rubocop:disable Metrics/CyclomaticComplexity
-      source_path = resolve_js_source_path
-      js_extensions = %w[js jsx ts tsx]
-      js_patterns = js_extensions.map { |ext| "#{source_path}/**/*.#{ext}" }
-      files_with_base_import = []
+      checker.add_warning(<<~MSG.strip)
+        ⚠️  Deprecated rake task '#{DEPRECATED_RENDERER_CACHE_TASK}' referenced in:
+        #{matches.map { |p| format_renderer_cache_migration_bullet(p) }.join("\n")}
 
-      js_patterns.each do |pattern|
-        Dir.glob(pattern).each do |file|
-          content = File.read(file)
-          next unless content.match?(BASE_PACKAGE_IMPORT_PATTERN) || content.match?(BASE_PACKAGE_REQUIRE_PATTERN)
+        The unified 'pre_seed_renderer_cache' task uses MODE=copy by default (for
+        Docker/image builds) and MODE=symlink for same-filesystem workflows.
+      MSG
+    rescue StandardError => e
+      checker.add_warning("⚠️  Could not complete scan for deprecated renderer-cache task references: #{e.message}")
+    end
+
+    def deploy_script_references_deprecated_task?(full_path)
+      # Only `#` comments matter for the scanned file types: Procfile, Dockerfile*,
+      # and bin/* scripts all use `#`. None use `//`, so we don't filter it.
+      # The trailing-comment strip requires whitespace before `#`, so a fragment
+      # like `task#name` stays intact while `cmd # was: <deprecated>` is filtered.
+      full_path.binread.each_line.any? do |line|
+        stripped = line.lstrip
+        next false if stripped.start_with?("#")
+
+        without_inline_comment = stripped.sub(/ +#.*/, "")
+        without_inline_comment.include?(DEPRECATED_RENDERER_CACHE_TASK)
+      end
+    end
 
-          files_with_base_import << file
+    def deploy_script_path_references_deprecated_task?(path)
+      full_path = Rails.root.join(path)
+
+      return false unless full_path.file?
+      # Skip files larger than RENDERER_CACHE_DEPLOY_SCRIPT_MAX_BYTES;
+      # deploy scripts and CI manifests should be tiny.
+      return false if full_path.size > RENDERER_CACHE_DEPLOY_SCRIPT_MAX_BYTES
+
+      deploy_script_references_deprecated_task?(full_path)
+    rescue StandardError => e
+      checker.add_warning(
+        "⚠️  Could not scan #{path} for deprecated renderer-cache task references: #{e.message}"
+      )
+      false
+    end
+
+    def expand_renderer_cache_deploy_script_globs
+      # File::FNM_PATHNAME stops `*` from crossing slashes even though none of
+      # the patterns use `**`. base: scopes the expansion to the project root
+      # and yields paths relative to it. Each pattern is rescued individually
+      # so a permission error on one glob (e.g. an unreadable .github/) does
+      # not silence the rest.
+      root = Rails.root.to_s
+      RENDERER_CACHE_DEPLOY_SCRIPT_GLOBS.flat_map do |pattern|
+        Dir.glob(pattern, File::FNM_PATHNAME, base: root)
+           .sort
+           .first(RENDERER_CACHE_DEPLOY_SCRIPT_GLOB_MAX_MATCHES)
+      rescue StandardError => e
+        checker.add_warning(
+          "⚠️  Could not expand renderer-cache deploy-script glob #{pattern}: #{e.message}"
+        )
+        []
+      end
+    end
+
+    def format_renderer_cache_migration_bullet(path)
+      suggestion = renderer_cache_migration_suggestion(path)
+      lines = suggestion.split("\n")
+      return "  • #{path} → #{suggestion}" if lines.length == 1
+
+      indented = lines.map { |line| "      #{line}" }.join("\n")
+      "  • #{path} →\n#{indented}"
+    end
+
+    def renderer_cache_migration_suggestion(path)
+      # Dockerfile* entries are RUN steps during image build, so copy mode bakes the cache into the layer.
+      # Runtime hooks (Procfile, bin/*, .kamal/deploy.yml, Capistrano config) run after the app is deployed,
+      # where both the app and renderer share the same filesystem, so symlink mode is correct.
+      if path.start_with?("Dockerfile")
+        # /app/.node-renderer-bundles is a placeholder matching the docs' Dockerfile examples;
+        # the user must adjust it to match their image's WORKDIR. Hardcoding Rails.root here would
+        # leak the developer host path (e.g. /Users/alice/myapp/...) into the Dockerfile, which
+        # does not exist inside the container.
+        "ENV RENDERER_SERVER_BUNDLE_CACHE_PATH=/app/.node-renderer-bundles\n" \
+          "RUN bundle exec rake react_on_rails_pro:pre_seed_renderer_cache"
+      elsif path.start_with?(".kamal/")
+        # Kamal hooks run in two contexts: post-deploy hooks on the live server (symlink),
+        # and image-build hooks invoked during the Docker build (copy). The trailing comments
+        # disambiguate so users pick the mode that matches the hook they're editing.
+        "rake react_on_rails_pro:pre_seed_renderer_cache MODE=symlink\n" \
+          "# For Kamal deploy hooks (post-deploy, on the live server): MODE=symlink\n" \
+          "# For Kamal image-build hooks (hook/pre-build inside the Docker build): MODE=copy"
+      else
+        # docker-compose.yml / compose.yaml / bin/* / config/deploy.rb / scripts/deploy.sh
+        # default to symlink (correct for local dev + same-filesystem deploys); call out the
+        # copy alternative for users driving production container builds via Compose.
+        "rake react_on_rails_pro:pre_seed_renderer_cache MODE=symlink # use MODE=copy for Docker/container image builds"
+      end
+    end
+
+    # ── Rolling Deploy Adapter ────────────────────────────────────────
+
+    ROLLING_DEPLOY_REQUIRED_METHODS = %i[previous_bundle_hashes fetch upload].freeze
+
+    def check_rolling_deploy_adapter
+      adapter = ReactOnRailsPro.configuration.rolling_deploy_adapter
+
+      if adapter.nil?
+        env_override = ENV.fetch("PREVIOUS_BUNDLE_HASHES", nil)
+        if env_override && !env_override.empty?
+          checker.add_warning(
+            "⚠️  PREVIOUS_BUNDLE_HASHES=#{truncate_for_warning(env_override).inspect} is set but no " \
+            "rolling_deploy_adapter is configured. Rolling-deploy seeding needs both — the env var " \
+            "overrides *discovery* but the adapter is still required to fetch bundle files. " \
+            "Set config.rolling_deploy_adapter or unset PREVIOUS_BUNDLE_HASHES."
+          )
+        else
+          checker.add_info("ℹ️  No rolling_deploy_adapter configured (rolling-deploy seeding disabled).")
         end
+        return
+      end
+
+      return unless report_adapter_protocol(adapter)
+
+      env_override = ENV.fetch("PREVIOUS_BUNDLE_HASHES", nil)
+      if env_override && !env_override.empty?
+        # PREVIOUS_BUNDLE_HASHES is a full discovery override at runtime, so
+        # probing adapter#previous_bundle_hashes here would surface timeout/error
+        # noise for a code path the deploy will never invoke. Skip the probe and
+        # state the override explicitly so operators see what's happening.
+        checker.add_info(
+          "ℹ️  PREVIOUS_BUNDLE_HASHES=#{truncate_for_warning(env_override).inspect} is set; " \
+          "skipping rolling_deploy_adapter#previous_bundle_hashes probe (env var overrides discovery)."
+        )
+        report_resolved_cache_dir
+        return
       end
 
-      if files_with_base_import.empty?
-        checker.add_success("✅ No base 'react-on-rails' imports found (Pro package used correctly)")
+      report_previous_bundle_hashes_probe(adapter)
+      report_resolved_cache_dir
+    rescue StandardError => e
+      checker.add_warning("⚠️  Could not evaluate rolling_deploy_adapter: #{e.message}")
+    end
+
+    # Cap echoed env-var values so a malformed (or accidentally large)
+    # PREVIOUS_BUNDLE_HASHES value doesn't dump kilobytes into operator output.
+    PREVIOUS_BUNDLE_HASHES_DISPLAY_LIMIT = 80
+    private_constant :PREVIOUS_BUNDLE_HASHES_DISPLAY_LIMIT
+
+    def truncate_for_warning(value)
+      return value if value.length <= PREVIOUS_BUNDLE_HASHES_DISPLAY_LIMIT
+
+      "#{value[0, PREVIOUS_BUNDLE_HASHES_DISPLAY_LIMIT]}… (#{value.length} chars total)"
+    end
+
+    def report_adapter_protocol(adapter)
+      missing = ROLLING_DEPLOY_REQUIRED_METHODS.reject { |m| adapter.respond_to?(m) }
+      if missing.empty?
+        checker.add_success(
+          "✅ rolling_deploy_adapter responds to all required methods " \
+          "(#{ROLLING_DEPLOY_REQUIRED_METHODS.join(', ')})"
+        )
+        true
+      else
+        checker.add_warning(
+          "⚠️  rolling_deploy_adapter is missing required methods: #{missing.join(', ')}. " \
+          "See docs/pro/rolling-deploy-adapters.md."
+        )
+        false
+      end
+    end
+
+    def report_previous_bundle_hashes_probe(adapter)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      timeout_seconds = rolling_deploy_discovery_timeout_seconds
+      hashes = Timeout.timeout(timeout_seconds) { Array(adapter.previous_bundle_hashes) }
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+
+      if hashes.empty?
+        checker.add_warning(
+          "⚠️  rolling_deploy_adapter#previous_bundle_hashes returned []. " \
+          "Usually indicates the upload side has never run on a prior deploy."
+        )
+      else
+        checker.add_success(
+          "✅ rolling_deploy_adapter#previous_bundle_hashes returned #{hashes.length} hash(es) in #{latency_ms}ms"
+        )
+      end
+    rescue Timeout::Error
+      checker.add_warning(
+        "⚠️  rolling_deploy_adapter#previous_bundle_hashes timed out after " \
+        "#{timeout_seconds}s"
+      )
+    rescue StandardError => e
+      checker.add_warning("⚠️  rolling_deploy_adapter#previous_bundle_hashes raised #{e.class}: #{e.message}")
+    end
+
+    def rolling_deploy_discovery_timeout_seconds
+      if defined?(ReactOnRailsPro::RollingDeployCacheStager::DISCOVERY_TIMEOUT_SECONDS)
+        ReactOnRailsPro::RollingDeployCacheStager::DISCOVERY_TIMEOUT_SECONDS
+      else
+        # Must match the canonical Pro constant. Bidirectional pointers:
+        #   Pro file:     react_on_rails_pro/lib/react_on_rails_pro/rolling_deploy_cache_stager.rb
+        #   Pro constant: ReactOnRailsPro::RollingDeployCacheStager::DISCOVERY_TIMEOUT_SECONDS
+        #   Pro guard:    react_on_rails_pro/spec/dummy/spec/rolling_deploy_cache_stager_spec.rb
+        #                 (describe "DISCOVERY_TIMEOUT_SECONDS" → expects this fallback to equal Pro constant)
+        # The Pro spec catches drift in the Pro→OSS direction. If you change
+        # the value here without updating the Pro constant + spec, doctor will
+        # silently use a different timeout from the live stager.
+        10
+      end
+    end
+
+    # Fallback used when the Pro gem isn't loaded. Must match
+    # ReactOnRailsPro::RollingDeployCacheStager::TEMPORARY_DIRECTORY_PATTERN so
+    # doctor still filters staging/backup dirs out of the bundle-hash count.
+    # Drift is caught by:
+    #   react_on_rails_pro/spec/dummy/spec/rolling_deploy_cache_stager_spec.rb
+    #   describe "TEMPORARY_DIRECTORY_PATTERN"
+    # PID is `\d+` to match container deployments (Docker/Kubernetes) where
+    # seeding runs as PID 1.
+    ROLLING_DEPLOY_TEMP_DIR_PATTERN = /\.(?:staging|previous)-\d+-[0-9a-f]{8,}\z/
+
+    def report_resolved_cache_dir
+      cache_dir = ReactOnRailsPro::Utils.resolve_renderer_cache_dir
+      if File.directory?(cache_dir)
+        temp_dir_pattern = rolling_deploy_temp_dir_pattern
+        subdirs = Dir.children(cache_dir).select do |entry|
+          File.directory?(File.join(cache_dir, entry)) && !entry.match?(temp_dir_pattern)
+        end
+        checker.add_info("ℹ️  Resolved renderer cache dir: #{cache_dir} (#{subdirs.length} bundle-hash subdir(s))")
+      else
+        checker.add_info("ℹ️  Resolved renderer cache dir: #{cache_dir} (does not exist yet)")
+      end
+    end
+
+    def rolling_deploy_temp_dir_pattern
+      if defined?(ReactOnRailsPro::RollingDeployCacheStager::TEMPORARY_DIRECTORY_PATTERN)
+        ReactOnRailsPro::RollingDeployCacheStager::TEMPORARY_DIRECTORY_PATTERN
+      else
+        ROLLING_DEPLOY_TEMP_DIR_PATTERN
+      end
+    end
+
+    # The base 'react-on-rails' npm package is a transitive dependency of 'react-on-rails-pro',
+    # so references to 'react-on-rails' resolve silently, loading the base package instead of Pro.
+    # Components registered through the base package won't have Pro features (streaming, caching,
+    # RSC), and may cause "component not registered" errors at runtime.
+    BASE_PACKAGE_IMPORT_PATTERN = %r{\bfrom\s+['"]react-on-rails(?:/[^'"]*)?['"]}
+    BASE_PACKAGE_REQUIRE_PATTERN = %r{\brequire\s*\(\s*['"]react-on-rails(?:/[^'"]*)?['"]\s*\)}
+    BASE_PACKAGE_DYNAMIC_IMPORT_PATTERN = %r{\bimport\s*\(\s*['"]react-on-rails(?:/[^'"]*)?['"]\s*\)}
+    BASE_PACKAGE_SIDE_EFFECT_IMPORT_PATTERN = %r{^\s*import\s+['"]react-on-rails(?:/[^'"]*)?['"]}
+    BASE_PACKAGE_REFERENCE_SOURCE_ROOTS = ReactOnRails::ProMigration::JS_SOURCE_ROOTS
+    BASE_PACKAGE_REFERENCE_EXTENSIONS = ReactOnRails::ProMigration::JS_SOURCE_EXTENSIONS
+    # Explicit allowlist of documented Jest/Vitest APIs whose first argument is a module specifier.
+    BASE_PACKAGE_JEST_MODULE_SPECIFIER_METHOD_PATTERN =
+      ReactOnRails::ProMigration::JEST_MODULE_SPECIFIER_METHOD_PATTERN
+    BASE_PACKAGE_VITEST_MODULE_SPECIFIER_METHOD_PATTERN =
+      ReactOnRails::ProMigration::VITEST_MODULE_SPECIFIER_METHOD_PATTERN
+    # Match known Jest/Vitest module-specifier helpers. Aliased or nested receivers
+    # are intentionally out of scope to avoid warning on arbitrary application methods.
+    #
+    # importActual/importMock exist only as vi.* methods; there is no
+    # `import { importActual } from 'vitest'` form. The bare branch below is a
+    # deliberately broad detector heuristic (the rewriter omits it because
+    # rewriting is destructive while detection is advisory) and accepts that a
+    # user-defined helper of that name taking a 'react-on-rails' string matches.
+    BASE_PACKAGE_MOCK_PATTERN = %r{
+      \b(?:
+        (?:
+          jest\.(?:#{BASE_PACKAGE_JEST_MODULE_SPECIFIER_METHOD_PATTERN})
+          |
+          vi\.(?:#{BASE_PACKAGE_VITEST_MODULE_SPECIFIER_METHOD_PATTERN})
+        )
+        \s*
+        (?:<[^;\n]*>\s*)?
+        |
+        (?:importActual|importMock)
+      )
+      \s*\(\s*['"]react-on-rails(?:/[^'"]*)?['"]
+    }x
+    # In Ruby, ^ matches the start of any line, so this catches declarations anywhere in the file.
+    BASE_PACKAGE_DECLARE_MODULE_PATTERN = %r{^\s*(?:export\s+)?declare\s+module\s+['"]react-on-rails(?:/[^'"]*)?['"]}
+    BASE_PACKAGE_REFERENCE_PATTERNS = [
+      BASE_PACKAGE_IMPORT_PATTERN,
+      BASE_PACKAGE_REQUIRE_PATTERN,
+      BASE_PACKAGE_DYNAMIC_IMPORT_PATTERN,
+      BASE_PACKAGE_SIDE_EFFECT_IMPORT_PATTERN,
+      BASE_PACKAGE_MOCK_PATTERN,
+      BASE_PACKAGE_DECLARE_MODULE_PATTERN
+    ].freeze
+
+    def check_base_package_references
+      files_with_base_reference = files_with_base_package_references(resolve_js_source_path)
+
+      if files_with_base_reference.empty?
+        checker.add_success("✅ No base 'react-on-rails' references found (Pro package used correctly)")
       else
         checker.add_warning(<<~MSG.strip)
-          ⚠️  Found imports from 'react-on-rails' instead of 'react-on-rails-pro':
-          #{files_with_base_import.map { |f| "  • #{f}" }.join("\n")}
+          ⚠️  Found references to 'react-on-rails' instead of 'react-on-rails-pro':
+          #{files_with_base_reference.map { |f| "  • #{f}" }.join("\n")}
 
-          The base package is a transitive dependency of Pro, so these imports resolve
+          Look for static imports, side-effect imports, CommonJS requires, dynamic imports,
+          Jest/Vitest mock helpers, or TypeScript module augmentations.
+          Note: this includes commented-out references; review each file before updating.
+
+          The base package is a transitive dependency of Pro, so these references resolve
           silently but load the base version without Pro features.
 
-          Fix: Update imports to use 'react-on-rails-pro':
-            import ReactOnRails from 'react-on-rails-pro';        // server
-            import ReactOnRails from 'react-on-rails-pro/client';  // client
+          Fix: Replace base-package references with their Pro equivalents:
+            import ReactOnRails from 'react-on-rails-pro';         // ES import (server)
+            import ReactOnRails from 'react-on-rails-pro/client';  // ES import (client)
+            import 'react-on-rails-pro';                           // Side-effect import
+            const ReactOnRails = require('react-on-rails-pro');    // CommonJS require
+            const ReactOnRails = await import('react-on-rails-pro'); // Dynamic import
+            jest.mock('react-on-rails-pro', ...);                  // Jest mock helper
+            vi.mock('react-on-rails-pro', ...);                    // Vitest mock helper
+            declare module 'react-on-rails-pro' { ... }            // TypeScript augmentation
         MSG
       end
     rescue StandardError => e
-      checker.add_warning("⚠️  Could not scan for base package imports: #{e.message}")
+      checker.add_warning("⚠️  Could not scan for base package references: #{e.message}")
+    end
+
+    def files_with_base_package_references(source_path)
+      # Scan every file type the Pro migration rewriter can modify.
+      # **/*.ts naturally matches *.d.ts declaration files because they end in .ts.
+      js_patterns = base_package_reference_source_paths(source_path).flat_map do |source_root|
+        BASE_PACKAGE_REFERENCE_EXTENSIONS.map { |ext| "#{source_root}/**/*.#{ext}" }
+      end
+
+      js_patterns.flat_map do |pattern|
+        Dir.glob(pattern)
+           .reject { |file| file.include?("/node_modules/") }
+           .select { |file| base_package_reference_file?(file) }
+      end.uniq.sort
+    end
+
+    def base_package_reference_source_paths(source_path)
+      ([source_path] + BASE_PACKAGE_REFERENCE_SOURCE_ROOTS)
+        .compact
+        .map(&:to_s)
+        .reject(&:empty?)
+        .uniq
+        .select { |path| Dir.exist?(path) }
+    end
+
+    def base_package_reference_file?(file)
+      content = File.binread(file).force_encoding("UTF-8")
+      return false unless content.valid_encoding?
+
+      base_package_reference?(content)
+    rescue SystemCallError, IOError
+      false
+    end
+
+    def base_package_reference?(content)
+      # Content-based matching intentionally catches comments and string literals
+      # so stale migration references stay visible.
+      BASE_PACKAGE_REFERENCE_PATTERNS.any? { |reference_pattern| content.match?(reference_pattern) }
     end
 
     # ── React Server Components ────────────────────────────────────
@@ -2871,7 +3316,15 @@ module ReactOnRails
       # Prefer the actually installed version from node_modules over the declared
       # range in package.json. Declared ranges like "^19.0.0" would be misleading
       # (stripped to "19.0.0" even though 19.0.4+ may be installed).
-      installed = installed_react_version
+      package_root = resolved_package_root
+      if package_root_missing?(package_root)
+        # This check only needs the directory before Node chdirs into it; an
+        # installed React version can be resolved without package.json.
+        warn_missing_package_root(package_root)
+        return nil
+      end
+
+      installed = installed_react_version(package_root)
       return installed if installed
 
       declared_react_version
@@ -2879,11 +3332,12 @@ module ReactOnRails
       nil
     end
 
-    def installed_react_version
+    def installed_react_version(package_root)
       # Use Node's own module resolution to find the actually installed React,
       # which handles hoisted dependencies in monorepos and pnpm workspaces.
-      stdout, _stderr, status = Open3.capture3("node", "-e",
-                                               "console.log(require.resolve('react/package.json'))")
+      # Resolve from the configured package root so nested client/ layouts work.
+      script = "console.log(require.resolve('react/package.json'))"
+      stdout, _stderr, status = Open3.capture3("node", "-e", script, chdir: package_root)
       return nil unless status.success?
 
       resolved_path = stdout.strip
@@ -2895,10 +3349,24 @@ module ReactOnRails
       nil
     end
 
+    def add_warning(message)
+      checker.add_warning(message)
+    end
+
+    # Delegates the protected registry to checker so warnings emitted from
+    # Doctor share the same de-dupe state as warnings emitted from the checker.
+    # The cross-class call is permitted because both Doctor and SystemChecker
+    # include ConfigPathResolver, which satisfies Ruby's protected-visibility
+    # rule (caller and receiver share an ancestor that defines the method).
+    def config_path_warning_registry
+      checker.config_path_warning_registry
+    end
+
     def declared_react_version
-      return nil unless File.exist?("package.json")
+      package_json_path = package_json_path_for("declared React version")
+      return nil unless package_json_path
 
-      package_json = JSON.parse(File.read("package.json"))
+      package_json = JSON.parse(File.read(package_json_path))
       all_deps = (package_json["dependencies"] || {}).merge(package_json["devDependencies"] || {})
       version_str = all_deps["react"]
       return nil unless version_str