Add react_on_rails:doctor generator for setup diagnostics

CHANGELOG.md

@@ -58,6 +58,10 @@ Changes since the last non-beta release.
 - **Cleaner generated code**: Streamlined templates following modern React and TypeScript best practices
 - **Improved helper methods**: Added reusable `component_extension` helper for consistent file extension handling
 
+#### Added
+
+- **`react_on_rails:doctor` rake task**: New diagnostic command to validate React on Rails setup and identify configuration issues. Provides comprehensive checks for environment prerequisites, dependencies, Rails integration, and Webpack configuration. Use `rake react_on_rails:doctor` to diagnose your setup, with optional `VERBOSE=true` for detailed output.
+
 ### [16.0.0] - 2025-09-16
 
 **React on Rails v16 is a major release that modernizes the library with ESM support, removes legacy Webpacker compatibility, and introduces significant performance improvements. This release builds on the foundation of v14 with enhanced RSC (React Server Components) support and streamlined configuration.**

CLAUDE.md

@@ -2,6 +2,15 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## ⚠️ CRITICAL REQUIREMENTS
+
+**BEFORE EVERY COMMIT/PUSH:**
+1. **ALWAYS run `bundle exec rubocop` and fix ALL violations**
+2. **ALWAYS ensure files end with a newline character**
+3. **NEVER push without running full lint check first**
+
+These requirements are non-negotiable. CI will fail if not followed.
+
 ## Development Commands
 
 ### Essential Commands
@@ -11,15 +20,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   - Ruby tests: `rake run_rspec`
   - JavaScript tests: `yarn run test` or `rake js_tests`
   - All tests: `rake` (default task runs lint and all tests except examples)
-- **Linting**:
+- **Linting** (MANDATORY BEFORE EVERY COMMIT):
+  - **REQUIRED**: `bundle exec rubocop` - Must pass with zero offenses
   - All linters: `rake lint` (runs ESLint and RuboCop)
   - ESLint only: `yarn run lint` or `rake lint:eslint`
   - RuboCop only: `rake lint:rubocop`
 - **Code Formatting**:
-  - Format code with Prettier: `yarn start format`
+  - Format code with Prettier: `rake autofix`
   - Check formatting without fixing: `yarn start format.listDifferent`
 - **Build**: `yarn run build` (compiles TypeScript to JavaScript in node_package/lib)
 - **Type checking**: `yarn run type-check`
+- **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines
 
 ### Development Setup Commands
 
@@ -88,3 +99,4 @@ Exclude these directories to prevent IDE slowdowns:
 - `/coverage`, `/tmp`, `/gen-examples`, `/node_package/lib`
 - `/node_modules`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
 - `/spec/dummy/app/assets/webpack`, `/spec/dummy/log`
+

README.md

@@ -62,6 +62,16 @@ rails generate react_on_rails:install
 - `shakapacker.yml` settings
 - other configuration files
 
+### Troubleshooting Setup Issues
+
+If you encounter issues during installation or after upgrading, use the doctor command to diagnose your setup:
+
+```bash
+rake react_on_rails:doctor
+```
+
+The doctor command checks your environment, dependencies, and configuration files to identify potential issues. Use `VERBOSE=true rake react_on_rails:doctor` for detailed output.
+
 For detailed upgrade instructions, see [upgrade guide documentation](docs/guides/upgrading-react-on-rails.md).
 
 ## React on Rails Pro

lib/generators/react_on_rails/USAGE

@@ -0,0 +1,65 @@
+Description:
+    The `react_on_rails:doctor` generator diagnoses your React on Rails setup
+    and identifies potential configuration issues. It performs comprehensive
+    checks on your environment, dependencies, and configuration files.
+
+    This command is especially useful for:
+    • Troubleshooting setup issues
+    • Verifying installation after running react_on_rails:install
+    • Ensuring compatibility after upgrades
+    • Getting help with configuration problems
+
+Example:
+    # Basic diagnosis
+    rails generate react_on_rails:doctor
+
+    # Verbose output showing all checks
+    rails generate react_on_rails:doctor --verbose
+
+    # Show help
+    rails generate react_on_rails:doctor --help
+
+Checks performed:
+    Environment Prerequisites:
+    • Node.js installation and version compatibility
+    • JavaScript package manager availability (npm, yarn, pnpm, bun)
+    • Git working directory status
+
+    React on Rails Packages:
+    • React on Rails gem installation
+    • react-on-rails NPM package installation
+    • Version synchronization between gem and NPM package
+    • Shakapacker configuration and installation
+
+    Dependencies:
+    • React and React DOM installation
+    • Babel preset configuration
+    • Required development dependencies
+
+    Rails Integration:
+    • React on Rails initializer configuration
+    • Route and controller setup (Hello World example)
+    • View helper integration
+
+    Webpack Configuration:
+    • Webpack config file existence and structure
+    • React on Rails compatibility checks
+    • Environment-specific configuration validation
+
+    Development Environment:
+    • JavaScript bundle files
+    • Procfile.dev for development workflow
+    • .gitignore configuration for generated files
+
+Options:
+    --verbose, -v: Show detailed output for all checks, including successful ones
+    --fix, -f:     Attempt to fix simple issues automatically (planned feature)
+
+Exit codes:
+    0: All checks passed or only warnings found
+    1: Critical errors found that prevent React on Rails from working
+
+For more help:
+    • Documentation: https://github.com/shakacode/react_on_rails
+    • Issues: https://github.com/shakacode/react_on_rails/issues
+    • Discord: https://discord.gg/reactrails