Add gemspec validation and documentation

Adds comprehensive gemspec file exclusion validation to prevent Pro code
from leaking into the MIT gem. This addresses the critical bug where the
MIT gem was accidentally including Pro files.

Changes:

1. **New RSpec test** (spec/react_on_rails/gemspec_file_inclusion_spec.rb):
   - Validates MIT gem excludes all Pro files
   - Validates Pro gem includes all necessary Pro files
   - Prevents cross-contamination between packages
   - Tests run automatically in CI

2. **Updated MIT gemspec** (react_on_rails.gemspec):
   - Added explicit exclusions for CHANGELOG_PRO.md
   - Added explicit exclusion for react_on_rails_pro.gemspec
   - These files were being included in MIT gem due to default glob patterns

3. **Documentation** (CONTRIBUTING.md):
   - Added section on gemspec file management
   - Explains whitelisting approach for Pro package
   - Provides troubleshooting guidance
   - Documents how to validate changes

4. **GitHub Actions documentation** (.github/read-me.md):
   - Documents REACT_ON_RAILS_PRO_LICENSE_V2 secret requirement
   - Lists workflows that need this secret
   - Provides setup instructions for new contributors

These changes ensure that:
- ✅ MIT gem never includes Pro code (licensing violation)
- ✅ Pro gem includes all necessary Pro files
- ✅ CI automatically validates file inclusion
- ✅ Contributors have clear guidance on gemspec management

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: justin808

.github/read-me.md

@@ -105,6 +105,36 @@ Most workflows use minimal permissions. The comment-triggered workflows require:
 - `pull-requests: write` - To post comments and reactions
 - `actions: write` - To trigger other workflows
 
+## Required Secrets for Pro Workflows
+
+Workflows that test React on Rails Pro features require the following repository secret:
+
+### `REACT_ON_RAILS_PRO_LICENSE_V2`
+
+This secret contains the Pro license key needed to run Pro features during CI. It must be configured as a repository secret in GitHub Actions.
+
+**Workflows that require this secret:**
+
+- `examples.yml` - When generating/testing examples with Pro features
+- `integration-tests.yml` - When running integration tests that may use Pro features
+- Any workflow that runs example apps or tests that might invoke Pro functionality
+
+**Setting up the secret:**
+
+1. Go to repository Settings → Secrets and variables → Actions
+2. Add a new secret named `REACT_ON_RAILS_PRO_LICENSE_V2`
+3. Set the value to a valid React on Rails Pro license key
+
+**When adding new workflows:**
+If your workflow runs any Rails application that might have the Pro gem available (example apps, dummy apps, integration tests), add this environment variable:
+
+```yaml
+env:
+  REACT_ON_RAILS_PRO_LICENSE: ${{ secrets.REACT_ON_RAILS_PRO_LICENSE_V2 }}
+```
+
+This prevents license validation failures during test runs in the monorepo where both MIT and Pro packages are present.
+
 ## Conditional Execution
 
 Many workflows use change detection to skip unnecessary jobs:

CONTRIBUTING.md

@@ -193,6 +193,60 @@ npm install <tarball path/URL>
 
 or the equivalent command for your package manager.
 
+## Gemspec File Management
+
+**Important for Pro package contributors:**
+
+The React on Rails Pro gemspec (`react_on_rails_pro.gemspec`) uses **explicit whitelisting** for included files rather than blacklisting. This is a security measure to ensure no unintended files are included in the Pro gem.
+
+### What this means
+
+When you add new Ruby files to the Pro package (`lib/react_on_rails_pro/`), they will **NOT** be automatically included in the gem. You must explicitly add them to the gemspec.
+
+### How to update the gemspec
+
+When adding new files to the Pro package:
+
+1. **Add new Ruby files** to `lib/react_on_rails_pro/` as needed
+2. **Update `react_on_rails_pro.gemspec`** to include them:
+
+```ruby
+s.files = Dir.glob("{lib/react_on_rails_pro.rb,lib/react_on_rails_pro/**/*}") +
+          Dir.glob("lib/tasks/{assets_pro.rake,v8_log_processor.rake}") +
+          # ... other files
+```
+
+The glob patterns should automatically pick up new files under `lib/react_on_rails_pro/`, but if you add new directories or file types, verify they're included.
+
+3. **Run the gemspec validation test** to ensure your files are included:
+
+```bash
+bundle exec rspec spec/react_on_rails/gemspec_file_inclusion_spec.rb
+```
+
+This test verifies:
+
+- MIT gem doesn't include any Pro files
+- Pro gem includes all intended Pro files
+- No cross-contamination between MIT and Pro packages
+
+### Why whitelisting?
+
+The previous blacklist approach accidentally included Pro files in the MIT gem, which is a licensing violation. Whitelisting ensures:
+
+- ✅ Only intended files are included
+- ✅ New files require conscious decision to include
+- ✅ Prevents licensing violations
+- ✅ CI will catch missing files via automated tests
+
+### Troubleshooting
+
+If you see test failures about missing files in the Pro gem:
+
+1. Check if your new files are under `lib/react_on_rails_pro/`
+2. Verify the glob patterns in `react_on_rails_pro.gemspec` match your file structure
+3. Run `gem build react_on_rails_pro.gemspec` and inspect the built gem with `gem specification <gem-file>.gem files`
+
 # Development Setup for Gem and Node Package Contributors
 
 ## Dev Initial Setup

react_on_rails.gemspec

@@ -22,7 +22,9 @@ Gem::Specification.new do |s|
       # Exclude Pro-only files from MIT gem
       f.match(/^react_on_rails_pro/) ||
       f.match(%r{^lib/react_on_rails_pro}) ||
-      f.match(%r{^lib/tasks/(assets_pro|v8_log_processor)\.rake$})
+      f.match(%r{^lib/tasks/(assets_pro|v8_log_processor)\.rake$}) ||
+      f == "CHANGELOG_PRO.md" ||
+      f == "react_on_rails_pro.gemspec"
   end
   s.bindir        = "exe"
   s.executables   = s.files.grep(%r{^exe/}) { |f| File.basename(f) }

spec/react_on_rails/gemspec_file_inclusion_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+RSpec.describe "Gemspec file inclusion" do
+  describe "react_on_rails.gemspec" do
+    let(:gemspec_path) { File.expand_path("../../react_on_rails.gemspec", __dir__) }
+    let(:gemspec) { Gem::Specification.load(gemspec_path) }
+
+    it "exists and is valid" do
+      expect(gemspec).not_to be_nil
+      expect(gemspec.name).to eq("react_on_rails")
+    end
+
+    context "when checking Pro file exclusion" do
+      it "does not include any files from lib/react_on_rails_pro/" do
+        pro_lib_files = gemspec.files.select { |f| f.start_with?("lib/react_on_rails_pro") }
+        expect(pro_lib_files).to be_empty,
+                                  "MIT gem should not include Pro lib files, but found: #{pro_lib_files.join(', ')}"
+      end
+
+      it "does not include any files from react_on_rails_pro/ directory" do
+        pro_dir_files = gemspec.files.select { |f| f.start_with?("react_on_rails_pro/") }
+        expect(pro_dir_files).to be_empty,
+                                  "MIT gem should not include Pro directory files, " \
+                                  "but found: #{pro_dir_files.join(', ')}"
+      end
+
+      it "does not include Pro-specific rake tasks" do
+        pro_rake_tasks = gemspec.files.grep(%r{^lib/tasks/(assets_pro|v8_log_processor)\.rake$})
+        expect(pro_rake_tasks).to be_empty,
+                                   "MIT gem should not include Pro rake tasks, but found: #{pro_rake_tasks.join(', ')}"
+      end
+
+      it "does not include Pro gemspec file" do
+        pro_gemspec = gemspec.files.select { |f| f == "react_on_rails_pro.gemspec" }
+        expect(pro_gemspec).to be_empty,
+                               "MIT gem should not include Pro gemspec"
+      end
+
+      it "does not include CHANGELOG_PRO.md" do
+        pro_changelog = gemspec.files.select { |f| f == "CHANGELOG_PRO.md" }
+        expect(pro_changelog).to be_empty,
+                                 "MIT gem should not include Pro changelog"
+      end
+
+      it "does not include spec/pro/ test files" do
+        pro_specs = gemspec.files.select { |f| f.start_with?("spec/pro/") }
+        expect(pro_specs).to be_empty,
+                             "MIT gem should not include Pro spec files, but found: #{pro_specs.join(', ')}"
+      end
+    end
+
+    context "when checking MIT file inclusion" do
+      it "includes lib/react_on_rails.rb" do
+        expect(gemspec.files).to include("lib/react_on_rails.rb")
+      end
+
+      it "includes files from lib/react_on_rails/ directory" do
+        ror_files = gemspec.files.select { |f| f.start_with?("lib/react_on_rails/") }
+        expect(ror_files).not_to be_empty
+      end
+
+      it "includes standard MIT rake tasks" do
+        rake_tasks = gemspec.files.grep(%r{^lib/tasks/.*\.rake$})
+        # Should include standard tasks but not Pro tasks
+        expect(rake_tasks).not_to be_empty
+        expect(rake_tasks).to all(satisfy { |f| !f.match?(/assets_pro|v8_log_processor/) })
+      end
+    end
+  end
+
+  describe "react_on_rails_pro.gemspec" do
+    let(:gemspec_path) { File.expand_path("../../react_on_rails_pro.gemspec", __dir__) }
+    let(:gemspec) do
+      # The Pro gemspec requires the version files, so we need to allow that
+      Gem::Specification.load(gemspec_path)
+    end
+
+    it "exists and is valid" do
+      expect(gemspec).not_to be_nil
+      expect(gemspec.name).to eq("react_on_rails_pro")
+    end
+
+    context "when checking Pro file inclusion" do
+      it "includes lib/react_on_rails_pro.rb main file" do
+        expect(gemspec.files).to include("lib/react_on_rails_pro.rb")
+      end
+
+      it "includes all files from lib/react_on_rails_pro/ directory" do
+        # Get actual files in the directory
+        actual_pro_files = Dir.glob("lib/react_on_rails_pro/**/*")
+                              .reject { |f| File.directory?(f) }
+                              .sort
+
+        # Get files included in gemspec
+        included_pro_files = gemspec.files.select { |f| f.start_with?("lib/react_on_rails_pro/") }
+                                    .sort
+
+        missing_files = actual_pro_files - included_pro_files
+
+        expect(missing_files).to be_empty,
+                                 "Pro gemspec is missing files: #{missing_files.join(', ')}"
+      end
+
+      it "includes Pro-specific rake tasks" do
+        expect(gemspec.files).to include("lib/tasks/assets_pro.rake")
+        expect(gemspec.files).to include("lib/tasks/v8_log_processor.rake")
+      end
+
+      it "includes CHANGELOG_PRO.md" do
+        expect(gemspec.files).to include("CHANGELOG_PRO.md")
+      end
+
+      it "includes react_on_rails_pro.gemspec" do
+        expect(gemspec.files).to include("react_on_rails_pro.gemspec")
+      end
+    end
+
+    context "when checking file exclusions" do
+      it "does not include test infrastructure from react_on_rails_pro/ directory" do
+        # Should not include the dummy app or test infrastructure
+        test_files = gemspec.files.select do |f|
+          f.start_with?("react_on_rails_pro/") && !f.match?(%r{^react_on_rails_pro/(README|LICENSE|CHANGELOG)})
+        end
+        expect(test_files).to be_empty,
+                              "Pro gem should not include test infrastructure, but found: #{test_files.join(', ')}"
+      end
+
+      it "does not include spec/pro/ files (they're test files, not library code)" do
+        # NOTE: spec/pro/ contains the Pro *tests*, not the Pro library code
+        # The Pro library code is in lib/react_on_rails_pro/
+        spec_files = gemspec.files.select { |f| f.start_with?("spec/pro/") }
+        expect(spec_files).to be_empty,
+                              "Pro gem should not include spec files, but found: #{spec_files.join(', ')}"
+      end
+
+      it "does not include MIT-only files" do
+        # Make sure we're not accidentally including the base gem's files
+        mit_files = gemspec.files.select do |f|
+          f.start_with?("lib/react_on_rails/") || f == "lib/react_on_rails.rb"
+        end
+        expect(mit_files).to be_empty,
+                             "Pro gem should not include MIT gem files, but found: #{mit_files.join(', ')}"
+      end
+    end
+  end
+end