[restful-api] Introduce Steep Typechecking

[hayat01sh1da]

1. Why (Purpose)

Introducing rbs-inline + Steep brings static type checking to Ruby/Rails codebases that otherwise rely entirely on runtime behavior. The goals are:

• Reliability — Catch type mismatches, nil errors, and argument arity bugs before running code or tests
• Maintainability — Type signatures serve as machine-verifiable documentation, making refactoring safer and onboarding easier
• Incremental adoption — The # rbs_inline: enabled opt-in comment lets you roll it out file-by-file without disrupting existing code

2. What (Procedures)

2-1. Scope

12 projects total — 8 pure Ruby CLI projects and 4 Rails projects.

#	Project	Type	Files typed
1	coding-tests/ruby	Ruby CLI	18
2	pr-title-printers/ruby	Ruby CLI	3
3	json-data-sorters/ruby	Ruby CLI	4
4	itunes-file-delimiter-replacer/ruby	Ruby CLI	3
5	template-creators/ruby	Ruby CLI	3
6	file-extension-converters/ruby	Ruby CLI	3
7	file-cleaners/ruby	Ruby CLI	3
8	github-wiki-organisers/ruby	Ruby CLI	13
9	tutorials/.../restful-api	Rails	40
10	tutorials/.../perfect-ruby-on-rails	Rails	26
11	tutorials/.../e-navigator	Rails	31
12	botpress-accuracy-checkers/ruby-on-rails	Rails	20
	Total		167

2-2. Steps performed

1. Added rbs-inline and steep gems to each Rails project's Gemfile (in :development, :test group with require: false)
2. Added # rbs_inline: enabled magic comment to every .rb file under app/, spec/, test/, src/, exec/ — respecting existing # frozen_string_literal: true placement
3. Generated RBS signatures via rbs-inline → output stored in sig/generated/ mirroring source tree
4. Created/updated Steepfile in each project root, declaring:
   • check targets (source + test directories)
   • signature "sig" for generated .rbs files
   • library entries for stdlib/gems with RBS definitions (e.g. minitest, csv, json, fileutils, net-smtp, observer, ostruct, psych)

2-3. Steepfile library declarations per project

#	Project	Libraries
1	botpress-accuracy-checkers (Rails)	csv, ostruct
2	restful-api (Rails)	net-smtp, observer, ostruct
3	perfect-ruby-on-rails (Rails)	minitest, net-smtp, observer, ostruct, psych
4	e-navigator (Rails)	minitest
5	coding-tests	json, net-http
6	json-data-sorters	fileutils, json
7	template-creators	date, fileutils
8	itunes-file-delimiter-replacer	fileutils
9	file-extension-converters	fileutils
10	file-cleaners	fileutils
11	github-wiki-organisers	fileutils
12	pr-title-printers	(none)

3. How (Operation and Maintenance)

3-1. Regenerating signatures after code changes

bundle exec rbs-inline --output sig/generated app/   # Rails: app code
bundle exec rbs-inline --output sig/generated spec/   # Rails: spec code
bundle exec rbs-inline --output sig/generated test/   # Rails: test code

For pure Ruby projects (no Bundler): rbs-inline --output sig/generated src/ exec/ test/

3-2. Running type checks

bundle exec steep check   # Rails projects
steep check               # pure Ruby projects

3-3. When adding new files

1. Add # rbs_inline: enabled as the first line (after # frozen_string_literal: true if present)
2. Re-run rbs-inline to generate the .rbs file
3. Run steep check to verify

3-4. When adding new gems

If a new gem provides RBS types (check ruby/gem_rbs_collection), add a library "<gem>" entry to Steepfile.

4. Pros & Cons

4-1. Pros

#	Advantage	Detail
1	Early bug detection	Catches NoMethodError, nil misuse, wrong argument types at analysis time
2	Living documentation	.rbs signatures stay in sync with code via rbs-inline regeneration
3	Incremental adoption	Per-file opt-in with # rbs_inline: enabled — no big-bang migration
4	Zero runtime overhead	All checking happens offline; no performance cost in production
5	IDE integration	Steep provides editor feedback (completion, hover types) in supported editors

4-2. Cons

#	Disadvantage	Detail
1	Manual regeneration	No Rake task automation yet — developers must remember to run rbs-inline after changes
2	Limited gem coverage	Many Rails gems (Devise, FactoryBot, Faker, etc.) lack RBS definitions — Steep cannot type-check across those boundaries
3	Generated sigs are shallow	Without explicit type annotations in source, generated .rbs files contain only structure (class/module/method names) with untyped signatures
4	Learning curve	Developers need to learn RBS annotation syntax to get full value
5	CI integration needed	Currently no CI step enforces steep check — regressions can slip through