:warning: Note: This software is currently under active development. The API and interface should be considered unstable until a v1.0.0 release.

<p align="center"> <img alt="Tapioca logo" width="200" src="misc/tapioca-logo.svg" /> </p>

Tapioca - The swiss army knife of RBI generation

Tapioca makes it easy to work with Sorbet in your codebase. It surfaces types and methods from many sources that Sorbet cannot otherwise see – such as gems, Rails and other DSLs – compiles them into RBI files and makes it easy for you to add gradual typing to your application.

Features:

• Easy installation and configuration
• Generation of RBI files for the gems used in your application
  • Automatic generation from your application's Gemfile
  • Importing of signatures from the source code of gems
  • Importing of documentation from the source code of gems
  • Synchronization validation for your CI
• Generation of RBI files for various DSL patterns that relies on meta-programming
  • Automatic generation from your application's content
  • Support many DSL patterns such as Rails, Google Protobuf, SmartProperties and more out of the box
  • Extensible interface that allows you to write your own DSL compilers for other DSL patterns
  • Automatic generation of signatures for methods from known DSLs
  • Synchronization validation for your CI
• Management of shim RBI files
  • Find useless definitions in shim RBI files from gems generated RBI files
  • Find useless definitions in shim RBI files from DSL generated RBI files
  • Find useless definitions in shim RBI files from Sorbet's embedded RBI for core and stdlib
  • Synchronization validation for your CI

Table of Contents <!-- no_toc -->

<!-- START_TOC -->

• Installation
• Getting started
• Usage
  • Generating RBI files for gems
    • Manually requiring parts of a gem
    • Excluding a gem from RBI generation
    • Changing the strictness level of the RBI for a gem
    • Keeping RBI files for gems up-to-date
    • Importing hand written signatures from gem's rbi/ folder
  • Pulling RBI annotations from remote sources
    • Basic authentication
    • Using a .netrc file
    • Changing the typed strictness of annotations files
  • Generating RBI files for Rails and other DSLs
    • Keeping RBI files for DSLs up-to-date
    • Using DSL compiler options
    • Writing custom DSL compilers
    • Writing custom DSL extensions
  • RBI files for missing constants and methods
  • Configuration
• Editor Integration
  • Setup
  • Features
• Contributing
  • DSL compilers
• License

<!-- END_TOC -->

Installation

Add this line to your application's Gemfile:

group :development, :test do
  gem 'tapioca', require: false
end

Run bundle install and make sure Tapioca is properly installed:

<!-- START_HELP -->

$ tapioca help

Commands:
  tapioca --version, -v      # Show version
  tapioca annotations        # Pull gem RBI annotations from remote sources
  tapioca check-shims        # Check duplicated definitions in shim RBIs
  tapioca configure          # Initialize folder structure and type checking configuration
  tapioca dsl [constant...]  # Generate RBIs for dynamic methods
  tapioca gem [gem...]       # Generate RBIs from gems
  tapioca help [COMMAND]     # Describe available commands or one specific command
  tapioca init               # Get project ready for type checking
  tapioca require            # Generate the list of files to be required by tapioca
  tapioca todo               # Generate the list of unresolved constants
  tapioca tree               # Print a tree of all available commands

Options:
  -c, [--config=<config file path>]                  # Path to the Tapioca configuration file
                                                     # Default: sorbet/tapioca/config.yml
  -V, [--verbose], [--no-verbose], [--skip-verbose]  # Verbose output for debugging purposes
                                                     # Default: false

<!-- END_HELP -->

Getting started

Execute this command to get started:

$ bundle exec tapioca init

This will:

1. create the configuration file for Sorbet, the configuration file for Tapioca and the require.rb file
2. install the binstub for Tapioca in your app's bin/ folder, so that you can use bin/tapioca to run commands in your app
3. pull the community RBI annotations from the central repository matching your app's gems
4. generate the RBIs for your app's gems
5. generate the RBI file for missing constants

See the following sections for more details about each step.

<!-- START_HELP_COMMAND_INIT -->

$ tapioca help init

Usage:
  tapioca init

Options:
  -c, [--config=<config file path>]                  # Path to the Tapioca configuration file
                                                     # Default: sorbet/tapioca/config.yml
  -V, [--verbose], [--no-verbose], [--skip-verbose]  # Verbose output for debugging purposes
                                                     # Default: false

Get project ready for type checking

<!-- END_HELP_COMMAND_INIT -->

Usage

Generating RBI files for gems

Sorbet does not read the code in your gem dependencies, so it does not know the constants and methods declared inside gems. Tapioca is able to load your gem dependencies from your application's Gemfile and compile RBI files to represent their content.

In order to generate the RBI files for the gems used in your application, run the following command:

$ bin/tapioca gems [gems...]

Removing RBI files of gems that have been removed:

  Nothing to do.

Generating RBI files of gems that are added or updated:

  Requiring all gems to prepare for compiling...    Done

  Compiled ansi
      create  sorbet/rbi/gems/ansi@1.5.0.rbi

  ...

All operations performed in working directory.
Please review changes and commit them.

This will load your application, find all the gems required by it and generate an RBI file for each gem under the sorbet/rbi/gems directory for each of those gems. This process will also import signatures that can be found inside each gem sources, and, optionally, any documentation inside the gem.

<!-- START_HELP_COMMAND_GEM -->

$ tapioca help gem

Usage:
  tapioca gem [gem...]

Options:
  --out, -o,   [--outdir=directory]                                                                  # The output directory for generated gem RBI files
                                                                                                     # Default: sorbet/rbi/gems
               [--file-header], [--no-file-header], [--skip-file-header]                             # Add a "This file is generated" header on top of each generated RBI file
                                                                                                     # Default: true
               [--all], [--no-all], [--skip-all]                                                     # Regenerate RBI files for all gems
                                                                                                     # Default: false
  --pre, -b,   [--prerequire=file]                                                                   # A file to be required before Bundler.require is called
  --post, -a,  [--postrequire=file]                                                                  # A file to be required after Bundler.require is called
                                                                                                     # Default: sorbet/tapioca/require.rb
  -x,          [--exclude=gem [gem ...]]                                                             # Exclude the given gem(s) from RBI generation
               [--include-dependencies], [--no-include-dependencies], [--skip-include-dependencies]  # Generate RBI files for dependencies of the given gem(s)
                                                                                                     # Default: false
  --typed, -t, [--typed-overrides=gem:level [gem:level ...]]                                         # Override for typed sigils for generated gem RBIs
                                                                                                     # Default: {"activesupport" => "false"}
               [--verify], [--no-verify], [--skip-verify]                                            # Verify RBIs are up-to-date
                                                                                                     # Default: false
               [--doc], [--no-doc], [--skip-doc]                                                     # Include documentation from sources when generating RBIs
                                                                                                     # Default: true
               [--loc], [--no-loc