RBI Central

Overview

RBI Central is a cumulative repository of RBI ("Ruby Interface") file annotations for public gems which can be imported by Tapioca. This repository can be used to annotate gem RBIs that Tapioca can’t represent fully and even fix type checking errors as a result.

Annotations

Annotations are hand-written RBI files for commonly used gems that tell Sorbet information about the gem (e.g., constants, ancestors, methods) that isn't already generated by Tapioca. In other words, annotations are shareable shims.

In this repository, annotations are placed in the rbi/annotations folder.

Index

Each annotation from the rbi/annotations folder must be defined in the index.json file at the root of this repository:

{
    "gemA": { // gem name
        "dependencies": [ // optional: list of gems that need to be installed to test gemA RBI
            "gemB",
            "gemC"
        ],
        "requires": [ // optional: list of files that need to be required to test gemA RBI
            "file1",
            "file2",
        ]
    }
}

See the index validation schema for more details.

Pulling annotations

To pull relevant gem annotations into your project, run Tapioca's annotations command inside your project:

$ bin/tapioca annotations

CI checks

The CI for this repository is written using GitHub Actions. Here is a list of currently available CI checks:

CLI Command	Description
`bundle exec repo check index`	Lint `index.json` and check entries match `rbi/annotations/*.rbi` files
`bundle exec repo check rubygems`	Check new RBI files belong to public gems
`bundle exec repo check rubocop`	Lint RBI files
`bundle exec repo check runtime`	Check RBI annotations against runtime behavior
`bundle exec repo check static`	Check RBI annotations against Tapioca generated RBIs and Sorbet

To avoid pushing a PR with errors, configure the pre-push git hook by running:

$ git config core.hooksPath gem/hooks

This git hook will run most of the CI checks and block the push if you don't pass all the tests.

Runtime checks

Ensure the constants (constants, classes, modules) and properties (methods, attribute accessors) exist at runtime.

For each gem the test works as follows:

Create a temporary directory
Add a Gemfile pointing to the gem (and possible dependencies, listed in index key dependencies)
Add a Ruby script that:
1. Requires the gem (and possible other requirements, listed in index key requires)
2. Tries to const_get each constant defined in the RBI file
3. Tries to call instance_method for each method and attribute accessor (or method for singleton methods) in the RBI file

It is possible to allow necessary shims for non-existing runtime definitions by using a comment tag:

@shim to indicate that a definition doesn't actually exist at runtime but is needed to allow type checking. Example usage

Static checks

Ensure the constants (constants, classes, modules) and properties (methods, attribute accessors) exist are not duplicated from Tapioca generated RBIs and do not create type errors when running Sorbet.

For each gem the test works as follows:

Create a temporary directory
Add a Gemfile pointing to the gem (and possible dependencies, listed in index key dependencies)
Generate the RBIs for gems using tapioca gems
Check duplication with RBIs from gems using tapioca check-shims
Check for type errors using srb tc

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/rbi-central.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

gabrieltaylor/rbi-central