Add RBS type signatures

Introduces comprehensive RBS type signatures for the entire public API
and internal classes. This provides improved type checking, better IDE
support, and documentation for gem users.

All type signatures have been validated through runtime type checking
using `rbs test` against the full RSpec test suite (291 examples, 0 failures).

Changes:
- Add RBS signatures for all core classes (Zxcvbn, Tester, Score, Match, etc.)
- Add rake tasks for RBS validation and testing (rbs:validate, rbs:test, rbs:list, rbs:parse)
- Configure rbs_collection.yaml for dependency type signatures
- Update gemspec to exclude rbs_collection.yaml from gem package
- Add sig/README.md with usage instructions
- Fix type signatures based on runtime validation:
  - Use Numeric instead of Float for entropy calculations (handles both Integer and Float)
  - Accept nullable parameters where nil is valid (password, Match in year_entropy)
  - Support Symbol keys in DictionaryRanker for test compatibility
  - Allow untyped arrays in user_inputs for proper sanitization

Author: orien

.github/workflows/ci.yml

@@ -8,11 +8,32 @@ jobs:
         ruby: ['2.5', '2.6', '2.7', '3.0', '3.1', '3.2', '3.3', '3.4', '4.0']
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
+    - uses: actions/checkout@v6
+    - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
         bundler-cache: true
-    - run: bundle exec rake
+    - name: Run tests
+      run: bundle exec rake spec
+
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '4.0'
+        bundler-cache: true
+    - name: Run RuboCop
+      run: bundle exec rake rubocop
+
+  rbs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '4.0'
+        bundler-cache: true
+    - name: Validate RBS signatures
+      run: bundle exec rake rbs:validate

.gitignore

@@ -15,4 +15,7 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
-bin/
+bin/
+
+# RBS
+.gem_rbs_collection

CHANGELOG.md

@@ -6,11 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+ - RBS type signatures for improved type checking and IDE support ([#68])
+
 ### Changed
  - Minor fixups in gem metadata ([#67]).
 
 [Unreleased]: https://github.com/envato/zxcvbn-ruby/compare/v1.3.0...HEAD
 [#67]: https://github.com/envato/zxcvbn-ruby/pull/67
+[#68]: https://github.com/envato/zxcvbn-ruby/pull/68
 
 ## [1.3.0] - 2026-01-02
 

Gemfile

@@ -10,6 +10,7 @@ group :development do
   gem 'guard-bundler', require: false
   gem 'guard-rspec', require: false
   gem 'rake'
+  gem 'rbs'
 end
 
 group :test do

Rakefile

@@ -8,7 +8,35 @@ require 'rubocop/rake_task'
 RSpec::Core::RakeTask.new('spec')
 RuboCop::RakeTask.new('rubocop')
 
-task default: %i[spec rubocop]
+begin
+  require 'rbs/cli'
+
+  namespace :rbs do
+    desc 'Validate RBS type signatures'
+    task :validate do
+      sh 'rbs -I sig validate'
+    end
+
+    desc 'Run RBS runtime type checker with RSpec'
+    task :test do
+      sh "rbs -I sig test --target 'Zxcvbn::*' rspec"
+    end
+
+    desc 'List RBS types'
+    task :list do
+      sh 'rbs -I sig list | grep Zxcvbn'
+    end
+
+    desc 'Check RBS syntax'
+    task :parse do
+      sh 'rbs -I sig parse sig/**/*.rbs'
+    end
+  end
+rescue LoadError
+  # RBS is not available
+end
+
+task default: %i[spec rubocop rbs:validate]
 
 task :console do
   require 'zxcvbn'

rbs_collection.yaml

@@ -0,0 +1,11 @@
+# RBS collection configuration
+# This file specifies which type signature repositories to use
+
+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

sig/README.md

@@ -0,0 +1,65 @@
+# RBS Type Signatures
+
+This directory contains [RBS](https://github.com/ruby/rbs) type signatures for the zxcvbn-ruby gem.
+
+## What is RBS?
+
+RBS is Ruby's type signature language. It provides a way to describe the structure of Ruby programs with:
+- Class and module definitions
+- Method signatures with parameter and return types
+- Instance variables and constants
+- Duck typing and union types
+
+## Usage
+
+### Validating Type Signatures
+
+To validate that the RBS files are syntactically correct:
+
+```bash
+bundle exec rake rbs:validate
+```
+
+### Runtime Type Checking
+
+To run runtime type checking against the actual Ruby code during tests:
+
+```bash
+bundle exec rake rbs:test
+```
+
+This runs the RSpec test suite with RBS type checking enabled, verifying that method calls match their type signatures at runtime. Note: This takes about 2 minutes to run.
+
+### Other Useful Commands
+
+List all Zxcvbn types:
+```bash
+bundle exec rake rbs:list
+```
+
+Check syntax of RBS files:
+```bash
+bundle exec rake rbs:parse
+```
+
+## File Structure
+
+The signatures mirror the structure of the `lib/` directory:
+
+- `sig/zxcvbn.rbs` - Main Zxcvbn module
+- `sig/zxcvbn/*.rbs` - Core classes (Tester, Score, Match, etc.)
+- `sig/zxcvbn/matchers/*.rbs` - Pattern matcher classes
+
+## Adding New Signatures
+
+When adding new classes or methods to the codebase, remember to:
+
+1. Create or update the corresponding `.rbs` file in the `sig/` directory
+2. Run `bundle exec rake rbs_validate` to ensure the syntax is correct
+3. Keep type signatures in sync with the actual implementation
+
+## Resources
+
+- [RBS Documentation](https://github.com/ruby/rbs)
+- [RBS Syntax Guide](https://github.com/ruby/rbs/blob/master/docs/syntax.md)
+- [Ruby Signature Collection](https://github.com/ruby/gem_rbs_collection)

sig/zxcvbn.rbs

@@ -0,0 +1,10 @@
+module Zxcvbn
+  VERSION: String
+
+  DATA_PATH: Pathname
+
+  type word_list = Hash[String, Array[String]]
+  type user_inputs = Array[String]
+
+  def self.test: (String? password, ?user_inputs user_inputs, ?word_list word_lists) -> Score
+end

sig/zxcvbn/crack_time.rbs

@@ -0,0 +1,13 @@
+module Zxcvbn
+  module CrackTime
+    SINGLE_GUESS: Float
+    NUM_ATTACKERS: Integer
+    SECONDS_PER_GUESS: Float
+
+    def entropy_to_crack_time: (Numeric entropy) -> Float
+
+    def crack_time_to_score: (Numeric seconds) -> Integer
+
+    def display_time: (Numeric seconds) -> String
+  end
+end

sig/zxcvbn/data.rbs

@@ -0,0 +1,31 @@
+module Zxcvbn
+  class Data
+    type ranked_dictionary = Hash[String, Integer]
+    type adjacency_graph = Hash[String, Array[String?]]
+    type graph_stats = Hash[String, { average_degree: Float, starting_positions: Integer }]
+
+    @ranked_dictionaries: Hash[String, ranked_dictionary]
+    @adjacency_graphs: Hash[String, adjacency_graph]
+    @dictionary_tries: Hash[String, Trie]
+    @graph_stats: graph_stats
+
+    attr_reader ranked_dictionaries: Hash[String, ranked_dictionary]
+    attr_reader adjacency_graphs: Hash[String, adjacency_graph]
+    attr_reader dictionary_tries: Hash[String, Trie]
+    attr_reader graph_stats: graph_stats
+
+    def initialize: () -> void
+
+    def add_word_list: (String name, Array[String] list) -> void
+
+    private
+
+    def read_word_list: (String file) -> Array[String]
+
+    def build_tries: () -> Hash[String, Trie]
+
+    def build_trie: (ranked_dictionary ranked_dictionary) -> Trie
+
+    def compute_graph_stats: () -> graph_stats
+  end
+end