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
`scripts/check_index`	Lint `index.json` and check entries match `rbi/annotations/*.rbi` files
`scripts/run_on_changed_rbis "bundle exec rubocop"`	Lint RBI files
`scripts/run_on_changed_rbis scripts/check_runtime`	Check RBI annotations against runtime behavior
`scripts/run_on_changed_rbis scripts/check_static`	Check RBI annotations against Tapioca generated RBIs and Sorbet
`scripts/run_on_changed_rbis scripts/check_gems_are_public`	Check new RBI files belong to public gems

All scripts used in the CI checks are located in the scripts folder.

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

$ git config core.hooksPath .githooks

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 comment tags:

@missing_method to indicate that a method is delegated to another receiver using method_missing
@shim to indicate that a definition doesn't actually exist at runtime but is needed to allow type checking

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.

johnernaut/rbi-central