feat: add type checking using ruby rbs

Author: sncalvo

.github/workflows/rbs.yml

@@ -0,0 +1,30 @@
+name: RBS
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    name: Validate Type Signatures
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Install RBS
+        run: gem install rbs
+
+      - name: Install RBS collection
+        run: rbs collection install
+
+      - name: Validate RBS signatures
+        run: rbs -I sig validate

.gitignore

@@ -34,3 +34,7 @@ tmp/
 *.tmp
 
 Gemfile.lock
+
+# RBS type collection
+.gem_rbs_collection/
+rbs_collection.lock.yaml

README.md

@@ -4,6 +4,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/staging_table.svg)](https://badge.fury.io/rb/staging_table)
 [![Test Status](https://github.com/eagerworks/staging_table/actions/workflows/test.yml/badge.svg)](https://github.com/eagerworks/staging_table/actions)
+[![RBS](https://github.com/eagerworks/staging_table/actions/workflows/rbs.yml/badge.svg)](https://github.com/eagerworks/staging_table/actions/workflows/rbs.yml)
 
 Stop shoving data directly into your production tables like a savage. Give it a dressing room first! 
 
@@ -237,6 +238,48 @@ end
 
 ---
 
+## 🔍 Type Checking (RBS)
+
+This gem ships with [RBS](https://github.com/ruby/rbs) type signatures for static type checking. The signatures are located in the `sig/` directory and are validated in CI.
+
+### Using the Type Signatures
+
+If you want to type-check your own code that uses StagingTable:
+
+```bash
+# Install RBS and the collection for dependencies
+gem install rbs
+rbs collection install
+
+# Validate signatures
+rbs -I sig validate
+```
+
+### Using with Steep
+
+For full type checking with [Steep](https://github.com/soutaro/steep):
+
+```ruby
+# Gemfile
+gem 'steep', group: :development
+```
+
+```ruby
+# Steepfile
+target :lib do
+  signature "sig"
+  check "lib"
+  library "activerecord"
+  library "activesupport"
+end
+```
+
+```bash
+bundle exec steep check
+```
+
+---
+
 ## 💾 Supported Databases
 
 We speak your language.

rbs_collection.yaml

@@ -0,0 +1,18 @@
+# Run `rbs collection install` to install required type definitions
+# See: https://github.com/ruby/rbs/blob/master/docs/collection.md
+
+sources:
+  - type: git
+    name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+path: .gem_rbs_collection
+
+gems:
+  - name: activerecord
+  - name: activesupport
+  # Ignore gems without RBS definitions in the collection
+  - name: prism
+    ignore: true

sig/manifest.yaml

@@ -0,0 +1,5 @@
+# RBS manifest file
+# Defines gem dependencies for type checking
+dependencies:
+  - name: activerecord
+  - name: activesupport

sig/staging_table.rbs

@@ -0,0 +1,9 @@
+# Type signatures for staging_table gem
+# See https://github.com/ruby/rbs for more information
+
+module StagingTable
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.stage: (singleton(ActiveRecord::Base) source_model, **untyped options) -> Session
+                | [T] (singleton(ActiveRecord::Base) source_model, **untyped options) { (Session) -> T } -> TransferResult
+end

sig/staging_table/adapters/base.rbs

@@ -0,0 +1,18 @@
+module StagingTable
+  module Adapters
+    class Base
+      attr_reader connection: ActiveRecord::ConnectionAdapters::AbstractAdapter
+
+      def initialize: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> void
+
+      # Create a staging table based on the source table structure
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+
+      # Drop the staging table
+      def drop_table: (String temp_table_name) -> void
+
+      # Factory method to get the appropriate adapter for a connection
+      def self.for: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> Base
+    end
+  end
+end

sig/staging_table/adapters/mysql.rbs

@@ -0,0 +1,7 @@
+module StagingTable
+  module Adapters
+    class Mysql < Base
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+    end
+  end
+end

sig/staging_table/adapters/postgresql.rbs

@@ -0,0 +1,7 @@
+module StagingTable
+  module Adapters
+    class Postgresql < Base
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+    end
+  end
+end

sig/staging_table/adapters/sqlite.rbs

@@ -0,0 +1,11 @@
+module StagingTable
+  module Adapters
+    class Sqlite < Base
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+
+      private
+
+      def copy_indexes: (String temp_table_name, String source_table_name) -> void
+    end
+  end
+end