steep

Steep - Gradual Typing for Ruby

Installation

Install via RubyGems.

$ gem install steep

Requirements

Steep requires Ruby 2.6 or later.

Usage

Steep does not infer types from Ruby programs, but requires declaring types and writing annotations. You have to go on the following three steps.

0. steep init

Run steep init to generate a configuration file.

$ steep init       # Generates Steepfile

Edit the Steepfile:

target :app do
  check "lib"
  signature "sig"
end

RBSs for the gems in Gemfile.lock are loaded via rbs collection, which you set up with rbs collection init and rbs collection install. Add a library call only for an RBS that rbs collection doesn't manage.

1. Declare Types

Declare types in .rbs files in sig directory.

class Person
  @name: String
  @contacts: Array[Email | Phone]

  def initialize: (name: String) -> untyped
  def name: -> String
  def contacts: -> Array[Email | Phone]
  def guess_country: -> (String | nil)
end

class Email
  @address: String

  def initialize: (address: String) -> untyped
  def address: -> String
end

class Phone
  @country: String
  @number: String

  def initialize: (country: String, number: String) -> untyped
  def country: -> String
  def number: -> String

  def self.countries: -> Hash[String, String]
end

• You can use simple generics, like Hash[String, String].
• You can use union types, like Email | Phone.
• You have to declare not only public methods but also private methods and instance variables.
• You can declare singleton methods, like self.countries.
• There is nil type to represent nullable types.

2. Write Ruby Code

Write Ruby code with annotations.

…

3. Type Check

Run steep check command to type check.

$ steep check
lib/phone.rb:46:0: MethodDefinitionMissing: module=::Phone, method=self.countries (class Phone)

You now find Phone.countries method is not implemented yet.

Prototyping signature

You can use rbs prototype command to generate a signature declaration.

$ rbs prototype rb lib/person.rb lib/email.rb lib/phone.rb
class Person
  @name: untyped
  @contacts: Array[untyped]
  def initialize: (name: untyped) -> Array[untyped]
  def guess_country: () -> untyped
end

class Email
  @address: untyped
  def initialize: (address: untyped) -> untyped
  def ==: (untyped) -> untyped
  def hash: () -> untyped
end

class Phone
  @country: untyped
  @number: untyped
  def initialize: (country: untyped, number: untyped) -> untyped
  def ==: (untyped) -> void
  def hash: () -> untyped
end

It prints all methods, classes, instance variables, and constants. It can be a good starting point to writing signatures.

Because it just prints all defs, you may find some odd points:

• The type of initialize in Person looks strange.
• There are no attr_reader methods extracted.

Generally, these are by our design.

rbs prototype offers options: rbi to generate prototype from Sorbet RBI and runtime to generate from runtime API.

Docs

There are some documents in the manual and guides directories.

• Guides
• Manual

The doc directory contains a few internal design docs.

• Internal docs

Examples

You can find examples in smoke directory.

IDEs

Steep implements some of the Language Server Protocol features.

• For VSCode please install the plugin.
• For SublimeText please install LSP package and follow instructions.
• For Vim or Neovim please install ALE. You may want to let g:ale_ruby_steep_executable = 'bundle' to use your bundled steep version.

Other LSP supporting tools may work with Steep where it starts the server as steep langserver.

Rake Tasks

Steep comes with a set of configurable Rake tasks.

# Rakefile

require "steep/rake_task"
Steep::RakeTask.new do |t|
  t.check.severity_level = :error
  t.watch.verbose
end

task default: [:steep]

Use bundle exec rake -T to see all available tasks.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. Releases are cut by the Release gem workflow rather than from a working copy -- see doc/release.md.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/soutaro/steep.