react_on_rails 14.2.1 → 16.1.1

data/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+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**
+4. **ALWAYS let Prettier and RuboCop handle ALL formatting - never manually format**
+
+These requirements are non-negotiable. CI will fail if not followed.
+
+**🚀 AUTOMATIC: Git hooks are installed automatically during setup**
+
+Git hooks will automatically run linting on **all changed files (staged + unstaged + untracked)** before each commit - making it fast while preventing CI failures!
+
+**Note:** Git hooks are for React on Rails gem developers only, not for users who install the gem.
+
+## Development Commands
+
+### Essential Commands
+
+- **Install dependencies**: `bundle && yarn`
+- **Run tests**:
+  - 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** (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: `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
+- Never run `npm` commands, only equivalent Yarn Classic ones
+
+## ⚠️ FORMATTING RULES
+
+**Prettier is the SOLE authority for formatting non-Ruby files, and RuboCop for formatting Ruby files. NEVER manually format code.**
+
+### Standard Workflow
+1. Make code changes
+2. Run `rake autofix` or `yarn start format`
+3. Commit changes
+
+### Merge Conflict Resolution Workflow
+**CRITICAL**: When resolving merge conflicts, follow this exact sequence:
+
+1. **Resolve logical conflicts only** - don't worry about formatting
+2. **Add resolved files**: `git add .` (or specific files)
+3. **Auto-fix everything**: `rake autofix`
+4. **Add any formatting changes**: `git add .`
+5. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+
+**❌ NEVER manually format during conflict resolution** - this causes formatting wars between tools.
+
+### Debugging Formatting Issues
+- Check current formatting: `yarn start format.listDifferent`
+- Fix all formatting: `rake autofix`
+- If CI fails on formatting, always run automated fixes, never manual fixes
+
+### Development Setup Commands
+
+- **Initial setup**: `bundle && yarn && rake shakapacker_examples:gen_all && rake node_package && rake`
+- **Prepare examples**: `rake shakapacker_examples:gen_all`
+- **Generate node package**: `rake node_package`
+- **Run single test example**: `rake run_rspec:example_basic`
+
+### Test Environment Commands
+
+- **Dummy app tests**: `rake run_rspec:dummy`
+- **Gem-only tests**: `rake run_rspec:gem`
+- **All tests except examples**: `rake all_but_examples`
+
+## Project Architecture
+
+### Dual Package Structure
+
+This project maintains both a Ruby gem and an NPM package:
+
+- **Ruby gem**: Located in `lib/`, provides Rails integration and server-side rendering
+- **NPM package**: Located in `node_package/src/`, provides client-side React integration
+
+### Core Components
+
+#### Ruby Side (`lib/react_on_rails/`)
+
+- **`helper.rb`**: Rails view helpers for rendering React components
+- **`server_rendering_pool.rb`**: Manages Node.js processes for server-side rendering
+- **`configuration.rb`**: Global configuration management
+- **`engine.rb`**: Rails engine integration
+- **Generators**: Located in `lib/generators/react_on_rails/`
+
+#### JavaScript/TypeScript Side (`node_package/src/`)
+
+- **`ReactOnRails.ts`**: Main entry point for client-side functionality
+- **`serverRenderReactComponent.ts`**: Server-side rendering logic
+- **`ComponentRegistry.ts`**: Manages React component registration
+- **`StoreRegistry.ts`**: Manages Redux store registration
+
+### Build System
+
+- **Ruby**: Standard gemspec-based build
+- **JavaScript**: TypeScript compilation to `node_package/lib/`
+- **Testing**: Jest for JS, RSpec for Ruby
+- **Linting**: ESLint for JS/TS, RuboCop for Ruby
+
+### Examples and Testing
+
+- **Dummy app**: `spec/dummy/` - Rails app for testing integration
+- **Examples**: Generated via rake tasks for different webpack configurations
+- **Rake tasks**: Defined in `rakelib/` for various development operations
+
+## Important Notes
+
+- Use `yalc` for local development when testing with external apps
+- Server-side rendering uses isolated Node.js processes
+- React Server Components support available in Pro version
+- Generated examples are in `gen-examples/` (ignored by git)
+- Only use `yarn` as the JS package manager, never `npm`
+
+## IDE Configuration
+
+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`

data/CODING_AGENTS.md

@@ -0,0 +1,313 @@
+# 🤖 Coding Agents & AI Contributors Guide
+
+This guide provides specific guidelines for AI coding agents (like Claude Code) contributing to React on Rails. It supplements the main [CONTRIBUTING.md](./CONTRIBUTING.md) with AI-specific workflows and patterns.
+
+## Quick Reference Commands
+
+### Essential Commands
+
+```bash
+# Install dependencies
+bundle && yarn
+
+# Run tests
+bundle exec rspec                    # All tests (from project root)
+cd spec/dummy && bundle exec rspec   # Dummy app tests only
+
+# Linting & Formatting
+bundle exec rubocop                  # Ruby linting
+bundle exec rubocop [file_path]     # Lint specific file
+# Note: yarn format requires local setup, format manually
+
+# Development
+cd spec/dummy && foreman start       # Start dummy app with webpack
+```
+
+### CI Compliance Checklist
+
+- [ ] `bundle exec rubocop` passes with no offenses
+- [ ] All RSpec tests pass
+- [ ] No trailing whitespace
+- [ ] Line length ≤120 characters
+- [ ] Security violations properly scoped with disable comments
+- [ ] No `package-lock.json` or other non-Yarn lock files (except `Gemfile.lock`)
+
+## Development Patterns for AI Contributors
+
+### 1. Task Management
+
+Always use TodoWrite tool for multi-step tasks to:
+
+- Track progress transparently
+- Show the user what's being worked on
+- Ensure no steps are forgotten
+- Mark tasks complete as you finish them
+
+```markdown
+Example workflow:
+
+1. Analyze the problem
+2. Create test cases
+3. Implement the fix
+4. Run tests
+5. Fix linting issues
+6. Update documentation
+```
+
+### 2. Test-Driven Development
+
+When fixing bugs or adding features:
+
+1. **Create failing tests first** that reproduce the issue
+2. **Implement the minimal fix** to make tests pass
+3. **Add comprehensive test coverage** for edge cases
+4. **Verify all existing tests still pass**
+
+### 3. File Processing Guidelines
+
+When working with file generation or processing:
+
+- **Filter by extension**: Only process relevant files (e.g., `.js/.jsx/.ts/.tsx` for React components)
+- **Validate assumptions**: Don't assume all files in a directory are components
+- **Handle edge cases**: CSS modules, config files, etc. should be excluded appropriately
+
+Example from CSS module fix:
+
+```ruby
+COMPONENT_EXTENSIONS = /\.(jsx?|tsx?)$/
+
+def filter_component_files(paths)
+  paths.grep(COMPONENT_EXTENSIONS)
+end
+```
+
+## RuboCop Compliance Patterns
+
+### Common Fixes
+
+1. **Trailing Whitespace**
+
+   ```ruby
+   # Bad
+   let(:value) { "test" }
+
+   # Good
+   let(:value) { "test" }
+   ```
+
+2. **Line Length (120 chars max)**
+
+   ```ruby
+   # Bad
+   expect { eval(pack_content.gsub(/import.*from.*['"];/, "").gsub(/ReactOnRails\.register.*/, "")) }.not_to raise_error
+
+   # Good
+   sanitized_content = pack_content.gsub(/import.*from.*['"];/, "")
+                                   .gsub(/ReactOnRails\.register.*/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   ```
+
+3. **Named Subjects (RSpec)**
+
+   ```ruby
+   # Bad
+   describe "#method_name" do
+     subject { instance.method_name(arg) }
+
+     it "does something" do
+       expect(subject).to eq "result"
+     end
+   end
+
+   # Good
+   describe "#method_name" do
+     subject(:method_result) { instance.method_name(arg) }
+
+     it "does something" do
+       expect(method_result).to eq "result"
+     end
+   end
+   ```
+
+4. **Security/Eval Violations**
+
+   ```ruby
+   # Bad
+   expect { eval(dangerous_code) }.not_to raise_error
+
+   # Good
+   # rubocop:disable Security/Eval
+   sanitized_content = dangerous_code.gsub(/harmful_pattern/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   # rubocop:enable Security/Eval
+   ```
+
+### RuboCop Workflow
+
+1. Run `bundle exec rubocop [file]` to see violations
+2. Fix violations manually or with auto-correct where safe
+3. Re-run to verify fixes
+4. Use disable comments sparingly and with good reason
+
+## Testing Best Practices
+
+### Test Structure
+
+```ruby
+describe "FeatureName" do
+  context "when condition A" do
+    let(:setup) { create_test_condition }
+
+    before do
+      # Setup code
+    end
+
+    it "does expected behavior" do
+      # Arrange, Act, Assert
+    end
+  end
+end
+```
+
+### Test Fixtures
+
+- Create realistic test data that represents edge cases
+- Use descriptive names for fixtures and variables
+- Clean up after tests (handled by RSpec automatically in most cases)
+
+### CSS Module Testing Example
+
+```ruby
+# Create test fixtures
+Write.create("ComponentWithCSSModule.module.css", css_content)
+Write.create("ComponentWithCSSModule.jsx", jsx_content)
+
+# Test the behavior
+it "ignores CSS module files during pack generation" do
+  generated_packs = PacksGenerator.instance.generate_packs_if_stale
+  expect(generated_packs).not_to include("ComponentWithCSSModule.module.js")
+end
+```
+
+## Git & PR Workflow
+
+### Branch Management
+
+```bash
+git checkout -b fix/descriptive-name
+# Make changes
+git add .
+git commit -m "Descriptive commit message
+
+- Bullet points for major changes
+- Reference issue numbers
+- Include 🤖 Generated with Claude Code signature"
+
+git push -u origin fix/descriptive-name
+```
+
+### Commit Message Format
+
+```
+Brief description of the change
+
+- Detailed bullet points of what changed
+- Why the change was needed
+- Any breaking changes or considerations
+
+Fixes #issue_number
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### PR Creation
+
+Use `gh pr create` with:
+
+- Clear title referencing the issue
+- Comprehensive description with summary and test plan
+- Link to the issue being fixed
+- Include the Claude Code signature
+
+## Common Pitfalls & Solutions
+
+### 1. File Path Issues
+
+- Always use absolute paths in tools
+- Check current working directory with `pwd`
+- Use proper path joining methods
+
+### 2. Test Environment
+
+- Run tests from correct directory (often project root)
+- Understand the difference between gem tests vs dummy app tests
+- Clean up test artifacts appropriately
+
+### 3. Dependency Management
+
+- Don't assume packages are installed globally
+- Use `bundle exec` for Ruby commands
+- Verify setup with `bundle && yarn` when needed
+
+### 4. RuboCop Configuration
+
+- Different rules may apply to different directories
+- Use `bundle exec rubocop` (not global rubocop)
+- Check `.rubocop.yml` files for project-specific rules
+
+## Debugging Workflow
+
+1. **Understand the Problem**
+
+   - Read the issue carefully
+   - Reproduce the bug if possible
+   - Identify root cause
+
+2. **Create Minimal Test Case**
+
+   - Write failing test that demonstrates issue
+   - Keep it focused and minimal
+
+3. **Implement Fix**
+
+   - Make smallest change possible
+   - Ensure fix doesn't break existing functionality
+   - Follow existing code patterns
+
+4. **Verify Solution**
+   - All new tests pass
+   - All existing tests still pass
+   - RuboCop compliance maintained
+   - Manual testing if applicable
+
+## IDE Configuration for AI Context
+
+When analyzing codebases, ignore these directories to avoid confusion:
+
+- `/coverage`, `/tmp`, `/gen-examples`
+- `/node_package/lib`, `/node_modules`
+- `/spec/dummy/app/assets/webpack`
+- `/spec/dummy/log`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
+- `/spec/react_on_rails/dummy-for-generators`
+
+## Communication with Human Maintainers
+
+- Be transparent about AI-generated changes
+- Explain reasoning behind implementation choices
+- Ask for clarification when requirements are ambiguous
+- Provide comprehensive commit messages and PR descriptions
+- Include test plans and verification steps
+
+## Resources
+
+- [Main Contributing Guide](./CONTRIBUTING.md)
+- [Pull Request Guidelines](./docs/contributor-info/pull-requests.md)
+- [Generator Testing](./docs/contributor-info/generator-testing.md)
+- [RuboCop Documentation](https://docs.rubocop.org/)
+- [RSpec Best Practices](https://rspec.info/)
+
+---
+
+This guide evolves based on AI contributor experiences. Suggest improvements via issues or PRs!