Walkthrough

Adds lazy Rails environment loading and new Pro and React Server Components (RSC) diagnostics to ReactOnRails::Doctor: initializer and renderer checks, JS/TS source import scanning, bundler config and route validation, React version detection, Procfile watcher checks, and extensive specs for these flows.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant CLI as Doctor (rsc:doctor)
    participant Rails as Rails Env
    participant FS as File System
    participant Bundler as Bundler Configs
    participant Procfile as Procfile.dev
    participant Console as Console Output

    CLI->>Rails: ensure_rails_environment_loaded()
    Rails-->>CLI: loaded / failed (cached `@rails_environment_loaded`)
    CLI->>FS: resolve_js_source_path() and scan imports
    FS-->>CLI: report import findings
    CLI->>Bundler: check RSC bundler config paths
    Bundler-->>CLI: present / missing
    CLI->>FS: check_rsc_payload_route() in routes.rb
    FS-->>CLI: route present / missing
    CLI->>FS: detect_react_version_from_deps()
    FS-->>CLI: react version or compatibility warning
    CLI->>Procfile: inspect Procfile.dev for RSC watcher (RSC_BUNDLE_ONLY)
    Procfile-->>CLI: watcher present / missing
    CLI->>Console: emit aggregated success/info/warning/error messages

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

"I hopped through configs, files, and logs, 🐇
I sniffed for routes, bundles, and pro-blogs,
From package.json to Procfile's tune,
I found the gaps beneath the moon,
Fix them quick — then dance by noon! ✨"

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Code Review

Overall this is a well-structured addition. The gating logic (react_on_rails_pro? / enable_rsc_support) correctly ensures zero noise for base installs, error messages include actionable fix steps, and the test coverage is thorough with proper tmpdir isolation.

Issues

1. check_base_package_imports misses the client/ JS root (inline comment)
The scan only covers app/javascript/, but the existing doctor at line 1019 also checks client/**/*.{js,ts,jsx,tsx}. Projects using that layout will get a false "✅ No base imports found". Fix: add the client/ glob (and align to the brace-expansion style used elsewhere).

2. Regex matches commented-out imports — false positives (inline comment)
BASE_PACKAGE_IMPORT_PATTERN will flag // import ReactOnRails from 'react-on-rails'; as a live import. This produces a false-positive warning with the file name listed, which is confusing to users mid-migration. At minimum the warning could note that commented-out lines are included in the scan.

3. check_pro_setup lacks a top-level rescue (inline comment)
check_rsc_setup has rescue StandardError => e at the method level; check_pro_setup does not. If check_pro_initializer_existence throws outside its own rescue, the error propagates through the check runner rather than producing a friendly warning.

4. "NodeRenderer" string duplicated across two methods (inline comment)
The literal is used in check_pro_renderer_mode and check_rsc_renderer_mode. A single constant alongside RSC_BUNDLER_CONFIG_PATHS would make future renames safe.

5. Missing File.exist? guard in glob loop (inline comment)
The existing doctor guards each globbed path at line 1021 with next unless File.exist?(file). The new loop skips this, which is inconsistent and could bite on symlink edge cases.

Minor / nits

• detect_react_version_from_deps doesn't check peerDependencies — unlikely to matter in practice since react is almost always in dependencies, but worth a comment.
• The check_rsc_react_version branch major == 19 && minor.positive? will also catch React 20+ (e.g. 20.0.0) with a "not verified" warning rather than an error. This might be intentional but could surprise users on a future major.

🤖 Generated with Claude Code

Greptile Summary

This PR extends react_on_rails:doctor with two new diagnostic sections — React on Rails Pro Setup (3 checks) and React Server Components (5 checks) — both gated behind ReactOnRails::Utils.react_on_rails_pro? so OSS users see zero additional output. The implementation is well-structured, uses runtime config instead of brittle regex parsing, and comes with thorough spec coverage (7 new describe groups, ~611 lines).

Key issues found during review:

• React version false-positive warning (P1): detect_react_version_from_deps strips the semver operator from the declared dependency range (e.g. "^19.0.0" → "19.0.0"), so it always checks the lower-bound of the range rather than the resolved/installed version. A project pinned to ^19.0.0 will see a "security vulnerabilities" warning on every doctor run even though their lock file likely resolves to 19.0.4+. Reading from node_modules/react/package.json (or the lock file) would give the actually-installed version.
• check_pro_setup missing a top-level rescue: Unlike the sibling check_rsc_setup, there is no outer rescue StandardError in check_pro_setup. Unexpected I/O errors (e.g. Errno::EACCES) propagate unhandled and crash the entire doctor run.
• React 20+ falls into a hard error branch: The else clause in check_rsc_react_version fires for any version that is not explicitly covered, including future major > 19 releases. This would report a categorical "not compatible" error for hypothetically compatible React 20+ versions rather than an "unverified" warning.
• Top-level rescue in check_rsc_setup silently discards remaining sub-checks: A single rescue wrapping all five sub-check calls means the first unexpected exception causes the rest (routes, bundler config, procfile watcher) to be silently skipped.

Confidence Score: 3/5

• Safe to merge with awareness of the version-range false-positive, which will produce misleading security warnings for the common ^19.0.0 package.json pattern.
• The new checks are gated on Pro gem presence so there is zero regression risk for OSS users. Test coverage is solid and the overall design is correct. However, the detect_react_version_from_deps false-positive is a user-facing issue (misleading security warning shown on every doctor run for a common semver pattern), the missing top-level rescue is an unhandled crash path, and the React 20+ error branch will mislead future users. These are not blocking for a diagnostic/informational tool, but they lower confidence.
• react_on_rails/lib/react_on_rails/doctor.rb — specifically detect_react_version_from_deps, check_pro_setup, and the else branch in check_rsc_react_version.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[run_all_checks] --> B{check_pro_setup}
    B -->|react_on_rails_pro? = false| SKIP1[skip — no output]
    B -->|react_on_rails_pro? = true| C[check_pro_initializer_existence]
    C --> D[check_pro_renderer_mode]
    D -->|NodeRenderer| D1[add_success]
    D -->|other| D2[add_info x2]
    D -->|raises| D3[add_warning rescue]
    D1 & D2 & D3 --> E[check_base_package_imports]
    E -->|no base imports| E1[add_success]
    E -->|base imports found| E2[add_warning with file list]
    E -->|raises| E3[add_warning rescue]

    A --> F{check_rsc_setup}
    F -->|react_on_rails_pro? = false| SKIP2[skip — no output]
    F -->|RSC disabled| SKIP3[skip — no output]
    F -->|RSC enabled| G[add_info x3]
    G --> H[check_rsc_renderer_mode]
    H -->|NodeRenderer| H1[pass — no message]
    H -->|other| H2[add_error]
    H1 & H2 --> I[check_rsc_payload_route]
    I -->|route present| I1[add_success]
    I -->|missing| I2[add_error]
    I1 & I2 --> J[check_rsc_bundler_config]
    J -->|config found| J1[add_success]
    J -->|missing| J2[add_error]
    J1 & J2 --> K[check_rsc_react_version]
    K -->|19.0.4+| K1[add_success]
    K -->|19.0.0-19.0.3| K2[add_warning — security vulns]
    K -->|19.1+| K3[add_warning — unverified]
    K -->|lt 19| K4[add_error]
    K -->|undetectable| K5[add_info skip]
    K1 & K2 & K3 & K4 & K5 --> L[check_rsc_procfile_watcher]
    L -->|RSC_BUNDLE_ONLY present| L1[add_success]
    L -->|missing| L2[add_warning]
    F -->|raises anywhere| ERR[add_warning rescue]

_{Last reviewed commit: "Remove redundant RSC..."}

Code Review

Overall this is a solid, well-structured addition. The separation of concerns is clean, the messages are actionable, and gating the new sections on Pro detection avoids noise for OSS users. A few things worth addressing before merge:

Bug: detect_react_version_from_deps reads the declared version, not the installed version. package.json frequently contains ranges like caret-19.0.0. After stripping the prefix the method yields 19.0.0 and the RSC check warns/errors even though 19.0.4 is actually installed. Reading from package-lock.json (.packages[node_modules/react].version) or yarn.lock would give the accurate installed version.

Bug: check_base_package_imports can abort early on encoding errors. The inner File.read loop has no per-file encoding rescue. A single binary asset or non-UTF-8 file inside the source path raises Encoding::InvalidByteSequenceError and silently skips all remaining files; the outer rescue on line 2294 only surfaces a generic warning for the whole method. The existing scan_pattern_for_async already rescues encoding errors per file -- the same pattern should apply here.

Fragile implicit ordering: check_rsc_setup depends on check_pro_setup having run first. check_rsc_setup reads ReactOnRailsPro.configuration but never calls ensure_rails_environment_loaded. It works today because check_pro_setup appears earlier in the checks array and calls it. If the order ever changes, or check_rsc_setup is invoked standalone in a test, it reads uninitialised default config values. Adding an explicit ensure_rails_environment_loaded call at the top of check_rsc_setup (mirroring check_pro_setup) makes the dependency self-contained.

Minor: check_rsc_react_version errors on React 20+. The version logic covers major == 19 but has no branch for major >= 20. Future users on React 20 hit the else-branch and see a hard error claiming incompatibility. Worth adding a major >= 20 warning (unverified) or at minimum a comment noting the conservative intent.

Nit: check_rsc_payload_route and check_rsc_procfile_watcher do not filter comments. String#include? will match a commented-out rsc_payload_route or RSC_BUNDLE_ONLY line and report a false success. Low likelihood in practice, but easy to address with a line-by-line filter similar to config_has_async_loading_strategy?.

Review: Add Pro/RSC setup checks to react_on_rails:doctor

Good addition overall. The gating logic (skip entirely for non-Pro installs), the fallback chain for detecting the JS source path, and the decision to use Node module resolution instead of stripping semver ranges are all solid choices. Test coverage is thorough. Four issues to address (see inline comments for details):

Bugs

1. Duplicate warnings from ensure_rails_environment_loaded (line 2196)
On failure (missing file or boot error), the @rails_environment_loaded flag is never set, so the idempotency guard never fires on subsequent calls. Both check_pro_setup and check_rsc_setup call this method, meaning a broken boot emits the warning twice. The comment says "only loads once" but that only holds on the success path. A tri-state (:unknown/:loaded/:failed) fixes this.

2. Unreadable file aborts the entire import scan (line 2274)
File.read(file) without explicit encoding raises Encoding::UndefinedConversionError on non-UTF-8 or binary files. The method-level rescue StandardError swallows this along with all previously accumulated results, rather than just skipping the bad file.

Minor issues

3. Side-effect imports not detected (line 2263)
The bare import form without a from clause bypasses both regex patterns. Worth documenting as a known gap.

4. devDependencies silently wins in declared_react_version (line 2459)
(dependencies || {}).merge(devDependencies || {}) means the dev-declared version overrides the production one when react appears in both. Reversing the merge order makes the production dependency take priority.

Nits

• The rubocop:disable Metrics/CyclomaticComplexity on check_base_package_imports appears unnecessary: the method has a single if/else and one unless, well below the threshold.
• Missing blank line between the closing end of report_configure_private_output_path and the helpers section separator at line 2176.

Review: Add Pro/RSC setup checks to react_on_rails:doctor

Overall this is solid work — the implementation is well-structured, the gating logic (skip for base installs) is clean, the test coverage is thorough, and the iterative fixes across commits (YAML alias handling, duplicate warning dedup, \z anchor, Open3 migration) show good attention to detail.

Three issues worth addressing before merge (inline comments attached):

Bugs

1. installed_react_version regex missing \z (line 2452)
The match /\A\d+\.\d+\.\d+/ passes for prerelease tags like 19.0.4-rc.1. Ruby's "4-rc".to_i == 4, so prerelease versions silently compare as their stable equivalent. declared_react_version correctly uses \z — apply the same fix here.

2. Open3.capture3("node", ...) has no timeout (line 2444–2445)
If node is on PATH but hangs (broken Node install, Docker environment with a mounted but unresponsive socket), the doctor command blocks indefinitely. A 5-second Timeout.timeout wrapper would keep the tool snappy even in edge cases.

3. Mid-scan error in check_base_package_imports loses partial results (line 2299)
A File.read failure (encoding error on a binary, permission issue) triggers the outer rescue, which discards any files_with_base_import already collected. Moving the rescue inside the per-file loop lets the scan continue and preserve matches found before the failure.

Minor observations (no action required)

• @rails_environment_attempted is not initialised in initialize alongside @rails_environment_loaded. Works correctly since nil is falsy, but the asymmetry is slightly surprising when reading initialize.
• check_base_package_imports carries a # rubocop:disable Metrics/CyclomaticComplexity comment, but the method has at most one conditional branch — the complexity disable appears unnecessary.
• ensure_rails_environment_loaded's return value is not checked in check_pro_setup/check_rsc_setup. Downstream methods already rescue their own errors so this works in practice, but an explicit return after the failed-load case would make the control flow more obvious.

Thanks @ihabadham