Skip to content

Latest commit

 

History

History
116 lines (77 loc) · 5.18 KB

README.md

File metadata and controls

116 lines (77 loc) · 5.18 KB
Raw

RBI Central

Build Status

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.

Usage

The RBIs in this repository are used by Tapioca.

The rbi-central gem exists only to prevent name squatting - it should not be installed.

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
        // optional: list of gems that need to be installed to test gemA RBI
        "dependencies": [
            "gemB",
            "gemC"
        ],
        // optional: list of files that need to be required to test gemA RBI
        "requires": [
            "file1",
            "file2",
        ]
    }
}

If you're copying this into your own index.json, make sure you strip out the comments.

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:

  1. Create a temporary directory
  2. Add a Gemfile pointing to the gem (and possible dependencies, listed in index key dependencies)
  3. 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:

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

Contributing

If you working on the gem using VS Code, change into the gem/ directory then run code .. This ensures that Sorbet and vscode-rdbg will work correctly.

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.