Improve RBS type checking implementation and documentation

Critical Fixes:
- Fix bundle exec consistency in rbs.rake for both rbs and steep tasks
- Add comprehensive error handling for runtime type checking in run_rspec.rake
- Fix type signature accuracy: Array[untyped] -> Array[String] in Pro configuration
- Rewrite cache.rbs to match actual implementation (was describing non-existent method)

Enhanced Runtime Type Checking:
- Extract runtime checking into reusable rbs_runtime_env_vars helper
- Extend coverage to :dummy and :dummy_no_turbolinks tasks
- Add opt-in mechanism via ENV["ENABLE_RBS_RUNTIME_CHECKING"]
- Add comprehensive documentation explaining coverage strategy per Evil Martians best practices

Documentation Improvements:
- Add extensive Steepfile documentation explaining positive-list approach
- Document all intentionally excluded files/directories with reasons
- Add step-by-step guide for adding new files to type checking
- Explain why bundle exec is necessary even in rake context

Configuration:
- Add Steepfile to RuboCop Naming/FileName exclusions
- Alphabetically order checked files for easy maintenance

All changes improve type safety, prevent silent failures, and make the
system more maintainable for future developers.

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

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

Author: justin808

.rubocop.yml

@@ -39,6 +39,7 @@ Naming/FileName:
   Exclude:
     - '**/Gemfile'
     - '**/Rakefile'
+    - '**/Steepfile'
 
 Layout/LineLength:
   Max: 120

Steepfile

@@ -2,12 +2,29 @@
 
 # Steepfile - Configuration for Steep type checker
 # See https://github.com/soutaro/steep for documentation
+#
+# IMPORTANT: This file lists only the files that are ready for type checking.
+# We use a positive list (explicit check statements) rather than checking all files
+# because not all files have RBS signatures yet.
+#
+# Files/directories intentionally excluded (no RBS signatures yet):
+# - lib/generators/**/*           - Rails generators (complex Rails integration)
+# - lib/react_on_rails/engine.rb  - Rails engine setup
+# - lib/react_on_rails/doctor.rb  - Diagnostic tool
+# - lib/react_on_rails/locales/**/* - I18n files
+# - lib/react_on_rails/props_js_builder.rb - TODO: Add signature
+# - lib/react_on_rails/shakapacker/**/* - Shakapacker integration (complex)
+#
+# To add a new file to type checking:
+# 1. Create corresponding RBS signature in sig/react_on_rails/filename.rbs
+# 2. Add `check "lib/react_on_rails/filename.rb"` below
+# 3. Run `bundle exec rake rbs:steep` to verify
+# 4. Fix any type errors before committing
 
 D = Steep::Diagnostic
 
 target :lib do
-  # Only check files that have corresponding RBS signatures in sig/
-  # This prevents type errors in files without type definitions (generators, doctor, etc.)
+  # Core files with RBS signatures (alphabetically ordered for easy maintenance)
   check "lib/react_on_rails.rb"
   check "lib/react_on_rails/configuration.rb"
   check "lib/react_on_rails/controller.rb"
@@ -25,7 +42,7 @@ target :lib do
   # Configure libraries (gems) - Steep will load their RBS signatures
   configure_code_diagnostics(D::Ruby.default)
 
-  # Library configuration
+  # Library configuration - standard library gems used by checked files
   library "pathname"
   library "singleton"
   library "logger"

rakelib/rbs.rake

@@ -9,14 +9,19 @@ namespace :rbs do
 
     puts "Validating RBS type signatures..."
 
-    # Run RBS validate (use rbs directly, not bundle exec since we're already in bundle context)
-    result = system("rbs -I sig validate")
+    # IMPORTANT: Always use 'bundle exec' even though rake runs in bundle context
+    # Reason: Direct 'rake' calls (without 'bundle exec rake') won't have gems in path
+    # This ensures the task works regardless of how the user invokes rake
+    # Redirect stderr to suppress bundler warnings that don't affect validation
+    result = system("bundle exec rbs -I sig validate 2>/dev/null")
 
     case result
     when true
       puts "✓ RBS validation passed"
     when false
-      puts "✗ RBS validation failed"
+      # Re-run with stderr to show actual validation errors
+      puts "Validation errors detected:"
+      system("bundle exec rbs -I sig validate")
       exit 1
     when nil
       puts "✗ RBS command not found or could not be executed"
@@ -39,14 +44,19 @@ namespace :rbs do
   task :steep do
     puts "Running Steep type checker..."
 
-    # Use steep directly, not bundle exec since we're already in bundle context
-    result = system("steep check")
+    # IMPORTANT: Always use 'bundle exec' even though rake runs in bundle context
+    # Reason: Direct 'rake' calls (without 'bundle exec rake') won't have gems in path
+    # This ensures the task works regardless of how the user invokes rake
+    # Redirect stderr to suppress bundler warnings
+    result = system("bundle exec steep check 2>/dev/null")
 
     case result
     when true
       puts "✓ Steep type checking passed"
     when false
-      puts "✗ Steep type checking failed"
+      # Re-run with stderr to show actual type errors
+      puts "Type checking errors detected:"
+      system("bundle exec steep check")
       exit 1
     when nil
       puts "✗ Steep command not found or could not be executed"

rakelib/run_rspec.rake

@@ -20,22 +20,50 @@ namespace :run_rspec do
 
   spec_dummy_dir = File.join("spec", "dummy")
 
+  # RBS Runtime Type Checking Configuration
+  # ========================================
+  # Runtime type checking is opt-in via ENV["ENABLE_RBS_RUNTIME_CHECKING"]
+  # This prevents silent failures and allows disabling when RBS isn't available
+  #
+  # Coverage Strategy:
+  # - :gem task - Enables checking for ReactOnRails::* (direct gem unit tests)
+  # - :dummy tasks - Enables checking (integration tests exercise gem code paths)
+  # - :example tasks - No checking (examples are user-facing demo apps)
+  #
+  # Rationale per Evil Martians best practices:
+  # Runtime checking catches type errors in actual execution paths that static
+  # analysis might miss. Dummy/integration tests exercise more code paths than
+  # unit tests alone, providing comprehensive type safety validation.
+  def rbs_runtime_env_vars
+    return "" unless ENV["ENABLE_RBS_RUNTIME_CHECKING"]
+
+    begin
+      require "rbs"
+      "RBS_TEST_TARGET='ReactOnRails::*' RUBYOPT='-rrbs/test/setup'"
+    rescue LoadError
+      warn "Warning: RBS gem not available, skipping runtime type checking"
+      ""
+    end
+  end
+
   desc "Run RSpec for top level only"
   task :gem do
     run_tests_in("",
                  rspec_args: File.join("spec", "react_on_rails"),
-                 env_vars: "RBS_TEST_TARGET='ReactOnRails::*' RUBYOPT='-rrbs/test/setup'")
+                 env_vars: rbs_runtime_env_vars)
   end
 
   desc "Runs dummy rspec with turbolinks"
   task dummy: ["dummy_apps:dummy_app"] do
-    run_tests_in(spec_dummy_dir)
+    run_tests_in(spec_dummy_dir,
+                 env_vars: rbs_runtime_env_vars)
   end
 
   desc "Runs dummy rspec without turbolinks"
   task dummy_no_turbolinks: ["dummy_apps:dummy_app"] do
+    env_vars = [rbs_runtime_env_vars, "DISABLE_TURBOLINKS=TRUE"].reject(&:empty?).join(" ")
     run_tests_in(spec_dummy_dir,
-                 env_vars: "DISABLE_TURBOLINKS=TRUE",
+                 env_vars: env_vars,
                  command_name: "dummy_no_turbolinks")
   end
 

react_on_rails_pro/sig/react_on_rails_pro/cache.rbs

@@ -1,7 +1,13 @@
 module ReactOnRailsPro
-  module Cache
-    def self.fetch: (String key) { () -> String } -> String
+  class Cache
+    def self.fetch_react_component: (String component_name, Hash[Symbol, untyped] options) { () -> untyped } -> untyped
 
-    def self.enabled?: () -> bool
+    def self.use_cache?: (Hash[Symbol, untyped] options) -> bool
+
+    def self.base_cache_key: (String type, ?prerender: bool?) -> Array[String]
+
+    def self.dependencies_cache_key: () -> String?
+
+    def self.react_component_cache_key: (String component_name, Hash[Symbol, untyped] options) -> Array[untyped]
   end
 end

react_on_rails_pro/sig/react_on_rails_pro/configuration.rbs

@@ -9,8 +9,8 @@ module ReactOnRailsPro
     DEFAULT_SSR_TIMEOUT: Integer
     DEFAULT_PRERENDER_CACHING: bool
     DEFAULT_TRACING: bool
-    DEFAULT_DEPENDENCY_GLOBS: Array[untyped]
-    DEFAULT_EXCLUDED_DEPENDENCY_GLOBS: Array[untyped]
+    DEFAULT_DEPENDENCY_GLOBS: Array[String]
+    DEFAULT_EXCLUDED_DEPENDENCY_GLOBS: Array[String]
     DEFAULT_REMOTE_BUNDLE_CACHE_ADAPTER: nil
     DEFAULT_RENDERER_REQUEST_RETRY_LIMIT: Integer
     DEFAULT_THROW_JS_ERRORS: bool