Migrate from separate RBS files to inline annotations (#83)

* refactor: migrate from separate RBS files to inline annotations

- Add rbs-inline annotations to source files
- Remove separate sig/*.rbs files (now generated from source)
- Update CI to generate RBS with rbs-inline before validation
- Configure RuboCop to allow #: inline annotation syntax
- Skip RBS generation for stdlib extensions (Array, Vector, Matrix)
  to avoid generic parameter conflicts

Fixes #57

* refactor: add proper parameter types to RBS inline annotations

Updated method signatures in lsi.rb and word_hash.rb to include proper
parameter types instead of empty (). Methods now have full type signatures
like `# @RBS (String, ?Float) -> ReturnType` instead of `# @RBS () -> ReturnType`.

This completes the migration to inline RBS annotations with proper types
for all method parameters.

* feat: add Steep static type checking

- Add steep gem for static type analysis
- Create Steepfile configuration (ignoring stdlib extension files and
  complex LSI dual-mode code for now)
- Add vendor RBS stubs for fast-stemmer, GSL, and Matrix dependencies
- Fix type issues in Bayes#classify (handle nil from min_by)
- Fix respond_to_missing? to return proper boolean
- Add steep check to CI workflow

* style: use single quotes in Steepfile

* fix: skip steep on Ruby 4.0 (ffi incompatible)

* chore: use Ruby 3.4 as default for lint job

* fix: use install_if for steep to avoid lockfile conflict

* fix: raise explicit error when no classifications available

* fix: remove duplicate @categories RBS annotation

Author: cardmagic

.github/workflows/ruby.yml

@@ -25,7 +25,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3'
+        ruby-version: '3.4'
         bundler-cache: true
     - name: Run RuboCop
       run: bundle exec rubocop
@@ -45,7 +45,10 @@ jobs:
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
     - name: Run tests
       run: bundle exec rake test
-    - name: Install RBS
-      run: gem install rbs
+    - name: Generate RBS from inline annotations
+      run: bundle exec rbs-inline --output sig lib/
     - name: Validate RBS types
-      run: rbs -I sig validate
+      run: bundle exec rbs -I sig validate
+    - name: Type check with Steep
+      if: matrix.ruby-version != '4.0'
+      run: bundle exec steep check

.gitignore

@@ -16,3 +16,4 @@ pkg/
 
 # Claude Code local settings
 .claude/
+sig/generated/

.rubocop.yml

@@ -1,6 +1,10 @@
 plugins:
   - rubocop-minitest
 
+# Allow rbs-inline #: comments without space after #
+Layout/LeadingCommentSpace:
+  AllowRBSInlineAnnotation: true
+
 AllCops:
   TargetRubyVersion: 3.1
   NewCops: enable

Gemfile

@@ -13,4 +13,8 @@ end
 group :development do
   gem 'rubocop', require: false
   gem 'rubocop-minitest', require: false
+  # steep's ffi dependency doesn't support Ruby 4.0 yet
+  install_if -> { RUBY_VERSION < '4.0' } do
+    gem 'steep', require: false
+  end
 end

Gemfile.lock

@@ -10,16 +10,44 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (8.1.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    csv (3.3.5)
     docile (1.4.1)
+    drb (2.2.3)
     fast-stemmer (1.0.2)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    fileutils (1.8.0)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
     json (2.18.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     matrix (0.4.2)
     minitest (6.0.1)
       prism (~> 1.5)
-    mutex_m (0.2.0)
+    mutex_m (0.3.0)
     ostruct (0.6.3)
     parallel (1.27.0)
     parser (3.3.10.0)
@@ -31,6 +59,14 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rbs (3.10.0)
+      logger
+    rbs-inline (0.12.0)
+      prism (>= 0.29)
+      rbs (>= 3.8.0)
     rdoc (6.5.1.1)
       psych (>= 4.0.0)
     regexp_parser (2.11.3)
@@ -53,16 +89,40 @@ GEM
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
     ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    steep (1.10.0)
+      activesupport (>= 5.1)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.17.0.4, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      mutex_m (>= 0.3.0)
+      parser (>= 3.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (~> 3.9)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 5)
+      uri (>= 0.12.0)
     stringio (3.1.0)
+    strscan (3.1.6)
+    terminal-table (4.0.0)
+      unicode-display_width (>= 1.1.1, < 4)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
+    uri (1.1.1)
 
 PLATFORMS
   arm64-darwin-22
@@ -77,10 +137,12 @@ DEPENDENCIES
   minitest
   mutex_m
   ostruct
+  rbs-inline
   rdoc
   rubocop
   rubocop-minitest
   simplecov
+  steep
 
 BUNDLED WITH
    2.4.17

Steepfile

@@ -0,0 +1,18 @@
+D = Steep::Diagnostic
+
+target :lib do
+  signature 'sig'
+
+  check 'lib'
+
+  # Ignore files that patch stdlib classes (these cause conflicts)
+  ignore 'lib/classifier/extensions/vector.rb'
+  ignore 'lib/classifier/extensions/vector_serialize.rb'
+  ignore 'lib/classifier/extensions/string.rb'
+  ignore 'lib/classifier/extensions/word_hash.rb'
+
+  # Ignore LSI files for now due to complex GSL/Matrix dual-mode typing
+  ignore 'lib/classifier/lsi.rb'
+  ignore 'lib/classifier/lsi/content_node.rb'
+  ignore 'lib/classifier/lsi/summary.rb'
+end

classifier.gemspec

@@ -14,5 +14,6 @@ Gem::Specification.new do |s|
   s.add_dependency 'rake'
   s.add_dependency 'matrix'
   s.add_development_dependency 'minitest'
+  s.add_development_dependency 'rbs-inline'
   s.add_development_dependency 'rdoc'
 end

lib/classifier/bayes.rb

@@ -1,12 +1,20 @@
+# rbs_inline: enabled
+
 # Author::    Lucas Carlson  (mailto:lucas@rufy.com)
 # Copyright:: Copyright (c) 2005 Lucas Carlson
 # License::   LGPL
 
 module Classifier
   class Bayes
+    # @rbs @categories: Hash[Symbol, Hash[Symbol, Integer]]
+    # @rbs @total_words: Integer
+    # @rbs @category_counts: Hash[Symbol, Integer]
+    # @rbs @category_word_count: Hash[Symbol, Integer]
+
     # The class can be created with one or more categories, each of which will be
     # initialized and given a training method. E.g.,
     #      b = Classifier::Bayes.new 'Interesting', 'Uninteresting', 'Spam'
+    # @rbs (*String | Symbol) -> void
     def initialize(*categories)
       @categories = {}
       categories.each { |category| @categories[category.prepare_category_name] = {} }
@@ -15,13 +23,14 @@ def initialize(*categories)
       @category_word_count = Hash.new(0)
     end
 
-    #
     # Provides a general training method for all categories specified in Bayes#new
     # For example:
     #     b = Classifier::Bayes.new 'This', 'That', 'the_other'
     #     b.train :this, "This text"
     #     b.train "that", "That text"
     #     b.train "The other", "The other text"
+    #
+    # @rbs (String | Symbol, String) -> void
     def train(category, text)
       category = category.prepare_category_name
       @category_counts[category] += 1
@@ -33,14 +42,15 @@ def train(category, text)
       end
     end
 
-    #
     # Provides a untraining method for all categories specified in Bayes#new
     # Be very careful with this method.
     #
     # For example:
     #     b = Classifier::Bayes.new 'This', 'That', 'the_other'
     #     b.train :this, "This text"
     #     b.untrain :this, "This text"
+    #
+    # @rbs (String | Symbol, String) -> void
     def untrain(category, text)
       category = category.prepare_category_name
       @category_counts[category] -= 1
@@ -59,11 +69,12 @@ def untrain(category, text)
       end
     end
 
-    #
     # Returns the scores in each category the provided +text+. E.g.,
     #    b.classifications "I hate bad words and you"
     #    =>  {"Uninteresting"=>-12.6997928013932, "Interesting"=>-18.4206807439524}
     # The largest of these scores (the one closest to 0) is the one picked out by #classify
+    #
+    # @rbs (String) -> Hash[String, Float]
     def classifications(text)
       words = text.word_hash.keys
       training_count = @category_counts.values.sum.to_f
@@ -80,13 +91,17 @@ def classifications(text)
       end
     end
 
-    #
     # Returns the classification of the provided +text+, which is one of the
     # categories given in the initializer. E.g.,
     #    b.classify "I hate bad words and you"
     #    =>  'Uninteresting'
+    #
+    # @rbs (String) -> String
     def classify(text)
-      classifications(text).min_by { |a| -a[1] }[0]
+      best = classifications(text).min_by { |a| -a[1] }
+      raise StandardError, 'No classifications available' unless best
+
+      best.first.to_s
     end
 
     #
@@ -107,20 +122,21 @@ def method_missing(name, *args)
       args.each { |text| send(method, category, text) }
     end
 
+    # @rbs (Symbol, ?bool) -> bool
     def respond_to_missing?(name, include_private = false)
-      name.to_s =~ /(un)?train_(\w+)/ || super
+      !!(name.to_s =~ /(un)?train_(\w+)/) || super
     end
 
-    #
     # Provides a list of category names
     # For example:
     #     b.categories
     #     =>   ['This', 'That', 'the_other']
-    def categories # :nodoc:
+    #
+    # @rbs () -> Array[String]
+    def categories
       @categories.keys.collect(&:to_s)
     end
 
-    #
     # Allows you to add categories to the classifier.
     # For example:
     #     b.add_category "Not spam"
@@ -129,20 +145,23 @@ def categories # :nodoc:
     # result in an undertrained category that will tend to match
     # more criteria than the trained selective categories. In short,
     # try to initialize your categories at initialization.
+    #
+    # @rbs (String | Symbol) -> Hash[Symbol, Integer]
     def add_category(category)
       @categories[category.prepare_category_name] = {}
     end
 
     alias append_category add_category
 
-    #
     # Allows you to remove categories from the classifier.
     # For example:
     #     b.remove_category "Spam"
     #
     # WARNING: Removing categories from a trained classifier will
     # result in the loss of all training data for that category.
     # Make sure you really want to do this before calling this method.
+    #
+    # @rbs (String | Symbol) -> void
     def remove_category(category)
       category = category.prepare_category_name
       raise StandardError, "No such category: #{category}" unless @categories.key?(category)

lib/classifier/extensions/vector.rb

@@ -1,10 +1,13 @@
+# rbs_inline: enabled
+
 # Author::    Ernest Ellingson
 # Copyright:: Copyright (c) 2005
 
 # These are extensions to the std-lib 'matrix' to allow an all ruby SVD
 
 require 'matrix'
 
+# @rbs skip
 class Array
   def sum_with_identity(identity = 0.0, &)
     return identity unless size.to_i.positive?
@@ -14,6 +17,7 @@ def sum_with_identity(identity = 0.0, &)
   end
 end
 
+# @rbs skip
 class Vector
   EPSILON = 1e-10
 
@@ -37,6 +41,7 @@ def normalize
   end
 end
 
+# @rbs skip
 class Matrix
   def self.diag(diagonal_elements)
     Matrix.diagonal(*diagonal_elements)