Add RBS type signatures for improved type safety (#1945)

## Summary

This PR adds comprehensive RBS (Ruby Signature) type definitions for the
React on Rails gem to improve type safety, IDE support, and developer
experience.

## What is RBS?

RBS is Ruby's official type signature language that provides type
information for Ruby code. It enables:
- Better IDE autocomplete and IntelliSense
- Static type checking with tools like Steep
- Improved API documentation
- Early detection of type-related bugs

## Changes

### Type Signatures Added
- **ReactOnRails module**: Core module, VERSION constant, configuration
methods
- **Configuration class**: All attributes and initialization parameters
- **Helper module**: All view helper methods (react_component,
redux_store, etc.)
- **ServerRenderingPool**: Server rendering methods and delegation
- **Utils module**: Utility methods and helper functions
- **PackerUtils**: Shakapacker integration methods
- **TestHelper**: Testing utilities
- **Controller**: Controller extension methods
- **GitUtils**: Git-related utilities
- **VersionChecker**: Version checking methods

### Infrastructure
- Added RBS gem to development dependencies
- Created `sig/` directory with organized type signatures
- Added rake tasks:
  - `rake rbs:validate` - Validate type signatures
  - `rake rbs:check` - Alias for validate
  - `rake rbs:list` - List all RBS files
- Included comprehensive README in `sig/` directory

## Benefits

1. **Better IDE Support**: Developers using IDEs with RBS support will
get better autocomplete and type hints
2. **Type Safety**: Optional static type checking with tools like Steep
3. **Documentation**: RBS signatures serve as machine-readable API
documentation
4. **Future-Proof**: Prepares the gem for Ruby's evolving type system
ecosystem

## Testing

- ✅ All RBS signatures validate with `bundle exec rbs -I sig validate`
- ✅ No breaking changes to existing code
- ✅ RuboCop passes
- ✅ Pre-commit hooks pass

## Additional Notes

The RBS signatures cover the main public API of the gem. Internal
methods and private APIs have minimal signatures to reduce maintenance
burden while still providing value to gem users.

Type signatures use conservative types (`untyped` for complex hashes)
where the actual types are highly dynamic to avoid over-constraining the
API.

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

<!-- Reviewable:start -->
- - -
This change is [<img src="https://reviewable.io/review_button.svg"
height="34" align="absmiddle"
alt="Reviewable"/>](https://reviewable.io/reviews/shakacode/react_on_rails/1945)
<!-- Reviewable:end -->


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Chores**
* Added extensive Ruby type signature coverage across the ReactOnRails
public API and new tooling to validate, check, and list signatures.
  * Added a development-only dependency for RBS.
* **Documentation**
* Added RBS guidance covering signature structure, validation and
listing commands, and development guidelines.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: justin808

Gemfile.development_dependencies

@@ -33,6 +33,7 @@ group :development, :test do
   gem "pry-doc"
   gem "pry-rails"
   gem "pry-rescue"
+  gem "rbs", require: false
   gem "rubocop", "1.61.0", require: false
   gem "rubocop-performance", "~>1.20.0", require: false
   gem "rubocop-rspec", "~>2.26", require: false

Gemfile.lock

@@ -267,6 +267,8 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
+    rbs (3.9.5)
+      logger
     rdoc (6.15.1)
       erb
       psych (>= 4.0.0)
@@ -437,6 +439,7 @@ DEPENDENCIES
   pry-rescue
   puma (~> 6.0)
   rails (~> 7.1)
+  rbs
   react_on_rails!
   rspec-rails
   rspec-retry

rakelib/rbs.rake

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+namespace :rbs do
+  desc "Validate RBS type signatures"
+  task :validate do
+    require "rbs"
+    require "rbs/cli"
+
+    puts "Validating RBS type signatures..."
+
+    # Run RBS validate
+    result = system("bundle exec rbs -I sig validate")
+
+    case result
+    when true
+      puts "✓ RBS validation passed"
+    when false
+      puts "✗ RBS validation failed"
+      exit 1
+    when nil
+      puts "✗ RBS command not found or could not be executed"
+      exit 1
+    end
+  end
+
+  desc "Check RBS type signatures (alias for validate)"
+  task check: :validate
+
+  desc "List all RBS files"
+  task :list do
+    sig_files = Dir.glob("sig/**/*.rbs")
+    puts "RBS type signature files:"
+    sig_files.each { |f| puts "  #{f}" }
+    puts "\nTotal: #{sig_files.count} files"
+  end
+end
+# rubocop:enable Metrics/BlockLength

sig/README.md

@@ -0,0 +1,52 @@
+# RBS Type Signatures
+
+This directory contains RBS (Ruby Signature) type definitions for the React on Rails gem.
+
+## What is RBS?
+
+RBS is Ruby's official type signature language. It provides type information for Ruby code, enabling:
+
+- Better IDE support and autocomplete
+- Static type checking with tools like Steep
+- Improved documentation
+- Early detection of type-related bugs
+
+## Structure
+
+The signatures are organized to mirror the `lib/` directory structure:
+
+- `react_on_rails.rbs` - Main module and core classes
+- `react_on_rails/configuration.rbs` - Configuration class types
+- `react_on_rails/helper.rbs` - View helper method signatures
+- `react_on_rails/server_rendering_pool.rbs` - Server rendering types
+- `react_on_rails/utils.rbs` - Utility method signatures
+- And more...
+
+## Validation
+
+To validate the RBS signatures:
+
+```bash
+bundle exec rake rbs:validate
+```
+
+Or directly:
+
+```bash
+bundle exec rbs -I sig validate
+```
+
+To list all RBS files:
+
+```bash
+bundle exec rake rbs:list
+```
+
+## Development
+
+When adding new public methods or classes to the gem, please also add corresponding RBS signatures.
+
+For more information about RBS:
+
+- [RBS Documentation](https://github.com/ruby/rbs)
+- [RBS Syntax Guide](https://github.com/ruby/rbs/blob/master/docs/syntax.md)

sig/react_on_rails.rbs

@@ -0,0 +1,38 @@
+# Type signatures for ReactOnRails gem
+
+module ReactOnRails
+  VERSION: String
+
+  DEFAULT_GENERATED_ASSETS_DIR: String
+  DEFAULT_COMPONENT_REGISTRY_TIMEOUT: Integer
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+
+  class Error < StandardError
+  end
+
+  class PrerenderError < Error
+    attr_reader component_name: String?
+    attr_reader js_code: String?
+    attr_reader err: Hash[Symbol, untyped]?
+    attr_reader props: (Hash[Symbol, untyped] | String)?
+    attr_reader console_messages: Array[String]?
+
+    def initialize: (
+      ?component_name: String?,
+      ?js_code: String?,
+      ?err: Hash[Symbol, untyped]?,
+      ?props: (Hash[Symbol, untyped] | String)?,
+      ?console_messages: Array[String]?
+    ) -> void
+
+    def to_honeybadger_context: () -> Hash[Symbol, untyped]
+    def raven_context: () -> Hash[Symbol, untyped]
+    def to_error_context: () -> Hash[Symbol, untyped]
+  end
+
+  class JsonParseError < Error
+    def initialize: (Hash[Symbol, untyped] err) -> void
+  end
+end

sig/react_on_rails/configuration.rbs

@@ -0,0 +1,96 @@
+module ReactOnRails
+  class Configuration
+    attr_accessor node_modules_location: String?
+    attr_accessor server_bundle_js_file: String
+    attr_accessor prerender: bool
+    attr_accessor replay_console: bool
+    attr_accessor trace: bool
+    attr_accessor development_mode: bool
+    attr_accessor logging_on_server: bool
+    attr_accessor server_renderer_pool_size: Integer
+    attr_accessor server_renderer_timeout: Integer
+    attr_accessor skip_display_none: bool?
+    attr_accessor raise_on_prerender_error: bool
+    attr_accessor generated_assets_dirs: Array[String]?
+    attr_accessor generated_assets_dir: String
+    attr_accessor components_subdirectory: String?
+    attr_accessor webpack_generated_files: Array[String]
+    attr_accessor rendering_extension: String?
+    attr_accessor build_test_command: String
+    attr_accessor build_production_command: String
+    attr_accessor i18n_dir: String?
+    attr_accessor i18n_yml_dir: String?
+    attr_accessor i18n_output_format: Symbol?
+    attr_accessor i18n_yml_safe_load_options: Hash[Symbol, untyped]?
+    attr_accessor defer_generated_component_packs: bool
+    attr_accessor server_render_method: String?
+    attr_accessor random_dom_id: bool
+    attr_accessor auto_load_bundle: bool
+    attr_accessor same_bundle_for_client_and_server: bool
+    attr_accessor rendering_props_extension: String?
+    attr_accessor make_generated_server_bundle_the_entrypoint: bool
+    attr_accessor generated_component_packs_loading_strategy: Symbol?
+    attr_accessor immediate_hydration: bool
+    attr_accessor component_registry_timeout: Integer
+    attr_accessor server_bundle_output_path: String?
+    attr_accessor enforce_private_server_bundles: bool
+
+    def initialize: (
+      ?node_modules_location: String?,
+      ?server_bundle_js_file: String?,
+      ?prerender: bool?,
+      ?replay_console: bool?,
+      ?make_generated_server_bundle_the_entrypoint: bool?,
+      ?trace: bool?,
+      ?development_mode: bool?,
+      ?defer_generated_component_packs: bool?,
+      ?logging_on_server: bool?,
+      ?server_renderer_pool_size: Integer?,
+      ?server_renderer_timeout: Integer?,
+      ?raise_on_prerender_error: bool?,
+      ?skip_display_none: bool?,
+      ?generated_assets_dirs: Array[String]?,
+      ?generated_assets_dir: String?,
+      ?webpack_generated_files: Array[String]?,
+      ?rendering_extension: String?,
+      ?build_test_command: String?,
+      ?build_production_command: String?,
+      ?generated_component_packs_loading_strategy: Symbol?,
+      ?same_bundle_for_client_and_server: bool?,
+      ?i18n_dir: String?,
+      ?i18n_yml_dir: String?,
+      ?i18n_output_format: Symbol?,
+      ?i18n_yml_safe_load_options: Hash[Symbol, untyped]?,
+      ?random_dom_id: bool?,
+      ?server_render_method: String?,
+      ?rendering_props_extension: String?,
+      ?components_subdirectory: String?,
+      ?auto_load_bundle: bool?,
+      ?immediate_hydration: bool?,
+      ?component_registry_timeout: Integer?,
+      ?server_bundle_output_path: String?,
+      ?enforce_private_server_bundles: bool?
+    ) -> void
+
+    def setup_config_values: () -> void
+
+    private
+
+    def check_component_registry_timeout: () -> void
+    def validate_generated_component_packs_loading_strategy: () -> void
+    def validate_enforce_private_server_bundles: () -> void
+    def check_minimum_shakapacker_version: () -> void
+    def check_autobundling_requirements: () -> void
+    def adjust_precompile_task: () -> void
+    def error_if_using_packer_and_generated_assets_dir_not_match_public_output_path: () -> void
+    def check_server_render_method_is_only_execjs: () -> void
+    def configure_generated_assets_dirs_deprecation: () -> void
+    def ensure_webpack_generated_files_exists: () -> void
+    def configure_skip_display_none_deprecation: () -> void
+    def raise_missing_components_subdirectory: () -> void
+    def compile_command_conflict_message: () -> String
+    def rsc_bundle_js_file: () -> String?
+    def react_client_manifest_file: () -> String?
+    def react_server_client_manifest_file: () -> String?
+  end
+end

sig/react_on_rails/controller.rbs

@@ -0,0 +1,15 @@
+module ReactOnRails
+  module Controller
+    # Type alias for ActiveSupport::SafeBuffer (html_safe strings)
+    type safe_buffer = String
+
+    def redux_store: (
+      String store_name,
+      ?props: untyped,
+      ?immediate_hydration: bool
+    ) -> void
+
+    # Returns html_safe string (ActiveSupport::SafeBuffer)
+    def redux_store_hydration_data: () -> safe_buffer
+  end
+end

sig/react_on_rails/git_utils.rbs

@@ -0,0 +1,8 @@
+module ReactOnRails
+  module GitUtils
+    def self.uncommitted_changes?: (String path) -> bool
+    def self.git_installed?: () -> bool
+    def self.current_branch: () -> String?
+    def self.rspec_fixture_branches: () -> Array[String]
+  end
+end

sig/react_on_rails/helper.rbs

@@ -0,0 +1,65 @@
+module ReactOnRails
+  module Helper
+    # Type alias for ActiveSupport::SafeBuffer (html_safe strings)
+    type safe_buffer = String
+
+    COMPONENT_HTML_KEY: String
+
+    # Main helper methods
+    # Returns html_safe string (ActiveSupport::SafeBuffer)
+    def react_component: (
+      String component_name,
+      ?Hash[Symbol, untyped] options
+    ) ?{ () -> untyped } -> safe_buffer
+
+    # Returns hash with html_safe strings (ActiveSupport::SafeBuffer)
+    def react_component_hash: (
+      String component_name,
+      ?Hash[Symbol, untyped] options
+    ) ?{ () -> untyped } -> Hash[String, safe_buffer]
+
+    # Returns html_safe string (ActiveSupport::SafeBuffer)
+    def redux_store: (
+      String store_name,
+      ?Hash[Symbol, untyped] props
+    ) -> safe_buffer
+
+    # Returns html_safe string (ActiveSupport::SafeBuffer)
+    def redux_store_hydration_data: () -> safe_buffer
+
+    # Returns html_safe string (ActiveSupport::SafeBuffer)
+    def server_render_js: (
+      String js_expression,
+      ?Hash[Symbol, untyped] options
+    ) -> safe_buffer
+
+    def sanitized_props_string: (untyped props) -> String
+
+    def rails_context: (
+      ?server_side: bool
+    ) -> Hash[Symbol, untyped]
+
+    private
+
+    def internal_react_component: (
+      String component_name,
+      Hash[Symbol, untyped] options
+    ) ?{ () -> untyped } -> Hash[Symbol, untyped]
+
+    def build_react_component_result_for_server_rendered_string: (
+      server_rendered_html: String,
+      component_specification_tag: String,
+      console_script: String,
+      render_options: Hash[Symbol, untyped]
+    ) -> safe_buffer
+
+    def build_react_component_result_for_server_rendered_hash: (
+      server_rendered_html: Hash[String, untyped],
+      component_specification_tag: String,
+      console_script: String,
+      render_options: Hash[Symbol, untyped]
+    ) -> Hash[String, safe_buffer]
+
+    def prepend_render_rails_context: (String result) -> safe_buffer
+  end
+end

sig/react_on_rails/packer_utils.rbs

@@ -0,0 +1,15 @@
+module ReactOnRails
+  module PackerUtils
+    def self.supports_autobundling?: () -> bool
+    def self.supports_basic_pack_generation?: () -> bool
+    def self.supports_async_loading?: () -> bool
+    def self.nested_entries?: () -> bool
+    def self.packer_public_output_path: () -> String
+    def self.precompile?: () -> bool
+    def self.shakapacker_precompile_hook_configured?: () -> bool
+    def self.shakapacker_precompile_hook_value: () -> String
+    def self.raise_shakapacker_version_incompatible_for_autobundling: () -> void
+    def self.raise_shakapacker_version_incompatible_for_basic_pack_generation: () -> void
+    def self.raise_nested_entries_disabled: () -> void
+  end
+end