Doctor command shows false version mismatch warning for beta/prerelease versions

[ihabadham]

A bug is a crash or incorrect behavior. If you have a debugging or troubleshooting question, please open a discussion.

Environment

1. Ruby version: 3.3.7
2. Rails version: 8.0.4
3. Shakapacker/Webpacker version: Not required for reproduction (bug occurs during version check before Shakapacker setup)
4. React on Rails version: 16.2.0.beta.10

Expected behavior

When running rake react_on_rails:doctor with matching gem and NPM package versions (both at 16.2.0.beta.10), the doctor should report that versions match.

Actual behavior

Doctor incorrectly shows a version mismatch warning even when versions are identical:

⚠️  Version mismatch detected:
• Gem version: 16.2.0.beta.10
• NPM version: 16.2.0-beta.10

Root cause: NPM uses -beta format while Ruby gems use .beta format. The version comparison code in lib/react_on_rails/system_checker.rb:217-220 removes all non-numeric/non-dot characters from the NPM version (turning 16.2.0-beta.10 into 16.2.0.10) but compares it against the uncleaned gem version (16.2.0.beta.10), causing them to never match.

Impact: All beta/alpha/rc/pre versions trigger false warnings. Only stable versions work correctly.

Small, reproducible repo

rails new test_app --skip-javascript && cd test_app
bundle add react_on_rails --version "16.2.0.beta.10" --strict
yarn add react-on-rails@16.2.0-beta.10
bundle exec rake react_on_rails:doctor

You'll see the false version mismatch warning despite both packages being at the same version.

[ihabadham]

Code Details

File: lib/react_on_rails/system_checker.rb
Method: check_package_version_sync
Lines: 217-220

Current problematic code:

# Clean version strings for comparison (remove ^, ~, =, etc.)
clean_npm_version = npm_version.gsub(/[^0-9.]/, "")
gem_version = ReactOnRails::VERSION

if clean_npm_version == gem_version

Suggested Fix

Normalize the NPM prerelease format to match Ruby gem format before comparison:

# Clean version strings for comparison (remove ^, ~, =, etc.)
# Also normalize NPM prerelease format (-beta/-alpha/-rc) to Ruby format (.beta/.alpha/.rc)
clean_npm_version = npm_version
  .gsub(/^[^0-9]+/, '')      # Remove version prefixes (^, ~, =)
  .gsub(/-beta\./, '.beta.')  # Convert -beta. to .beta.
  .gsub(/-alpha\./, '.alpha.')
  .gsub(/-rc\./, '.rc.')
  .gsub(/-pre\./, '.pre.')

gem_version = ReactOnRails::VERSION

if clean_npm_version == gem_version

This correctly handles:

• ✅ Stable versions: 16.2.0 → 16.2.0
• ✅ Prefixed stable: ^16.2.0 → 16.2.0
• ✅ Beta versions: 16.2.0-beta.10 → 16.2.0.beta.10
• ✅ Alpha versions: ^16.2.0-alpha.5 → 16.2.0.alpha.5
• ✅ RC versions: ~16.2.0-rc.1 → 16.2.0.rc.1

I'll test this fix locally and can submit a PR if it works correctly.

[ihabadham]

Fix Verified

I tested the proposed fix with all version formats:

✅ Fixed (now matches correctly):

• 16.2.0-beta.10 → 16.2.0.beta.10 ✓
• ^16.2.0-beta.10 → 16.2.0.beta.10 ✓
• 16.2.0-alpha.5 → 16.2.0.alpha.5 ✓
• 16.2.0-rc.1 → 16.2.0.rc.1 ✓
• All prerelease formats work

✅ Still works (no regression):

• 16.2.0 → 16.2.0 ✓
• ^16.2.0 → 16.2.0 ✓
• Stable versions still match

✅ Still detects real mismatches:

• 16.2.0-beta.10 vs 16.2.0.alpha.10 ✗
• 16.2.0-beta.10 vs 16.2.0.beta.9 ✗
• 16.2.0 vs 16.2.1 ✗

The fix is ready. I can submit a PR if needed.

[ihabadham]

Update: Root Cause Identified

This bug was actually caught during code review but not fixed!

In the original PR #1787 that introduced the doctor feature, CodeRabbit identified this exact issue in their review:

Version comparison: parse semver; avoid gsub stripping that corrupts pre-release versions

However, the suggestion was not implemented and the code was merged with the bug.

Better Fix: Use Existing VersionSyntaxConverter

React on Rails already has a VersionSyntaxConverter utility class that handles this conversion perfectly. Instead of writing new code, we should use the existing tested utility:

Current code (buggy):

clean_npm_version = npm_version.gsub(/[^0-9.]/, "")
gem_version = ReactOnRails::VERSION

if clean_npm_version == gem_version

Proposed fix:

converter = ReactOnRails::VersionSyntaxConverter.new
clean_npm_version = converter.npm_to_rubygem(npm_version)
gem_version = ReactOnRails::VERSION

if clean_npm_version == gem_version

This approach:

• ✅ Uses existing, battle-tested code
• ✅ Already has spec coverage
• ✅ Handles all edge cases (tested with 16/16 scenarios)
• ✅ Consistent with how version conversion is done elsewhere in the codebase
• ✅ No code duplication