tapioca 0.8.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb8747fff200d370504c4ae3119ab567335b4dc6b02a163a50217084a66bbe0d
-  data.tar.gz: 551715f2806d1038d4ed4d7ac9f23e7ca31051a8db153cf854878ad1aa529510
+  metadata.gz: 590bba5b82c68fea817819ca7d749a8527cc74915df1989639d6b9a23792f4ac
+  data.tar.gz: 1209c829aca470f50a86db985e3764827c679fca90c312f39daac81b3389d196
 SHA512:
-  metadata.gz: 1a854413aaaa4f50464fd5be89cfd5de4770f9468a70627e8af556d2c953a0b1e4f86901a1907bebf8f367c2d94429bd52fe38ae977797582e1bf2e35432f00b
-  data.tar.gz: 00671d2d35d2e40fd7f2761c7e7b4994bb88b051311520b042fc950c0f1ce8c62017a8e79605f4397819f2233cb5c4342fe03f8f65b39c3fd25ca71e56a31db1
+  metadata.gz: 151fb7e27e03ffaab3a9f7723333154bff8b773d5d98c24e048c726966a2e8c37ea59781d9fc2d445e2b0dd98bbb932461ad525aeb262b97ff56468da693e515
+  data.tar.gz: 81e6a1f2f25ccd489ae50076a3b07082e53cf279375d5dbd5219916591a3c49b743bc022aea97cef5ff7f88fe919e2d5d1a632892a8596fcb5e888032096e7de

data/Gemfile

@@ -11,7 +11,6 @@ gem("pry-byebug")
 gem("rubocop-shopify", require: false)
 gem("rubocop-sorbet", ">= 0.4.1")
 gem("rubocop-rspec", require: false)
-gem("sorbet")
 gem("ruby-lsp", require: false)
 
 group(:deployment, :development) do
@@ -38,7 +37,7 @@ group(:development, :test) do
   gem("shopify-money", require: false)
   gem("sidekiq", require: false)
   gem("nokogiri", require: false)
-  gem("config", require: false)
+  gem("config", github: "rubyconfig/config", branch: "master", require: false)
   gem("aasm", require: false)
   gem("bcrypt", require: false)
   gem("xpath", require: false)
@@ -48,3 +47,7 @@ group(:development, :test) do
   # https://github.com/rails/rails/blob/0919aa97260ab8240150278d3b07a1547489e3fd/Gemfile#L178-L191
   gem("net-smtp", "0.3.1", require: false)
 end
+
+group :test do
+  gem("webmock")
+end

data/README.md

@@ -42,15 +42,19 @@ end
 
 Run `bundle install` and make sure Tapioca is properly installed:
 
-```sh
-$ bundle exec tapioca help
+<!-- START_HELP -->
+```shell
+$ tapioca help
+
 Commands:
   tapioca --version, -v      # show version
-  tapioca clean-shims        # clean duplicated definitions in shim RBIs
+  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               # initializes folder structure
+  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
 
@@ -58,24 +62,27 @@ Options:
   -c, [--config=<config file path>]  # Path to the Tapioca configuration file
                                      # Default: sorbet/tapioca/config.yml
   -V, [--verbose], [--no-verbose]    # Verbose output for debugging purposes
+
 ```
+<!-- END_HELP -->
 
 ## Getting started
 
 Execute this command to get started:
 
-```sh
+```shell
 $ bundle exec tapioca init
-      create  sorbet/config
-      create  sorbet/tapioca/config.yml
-      create  sorbet/tapioca/require.rb
-      create  bin/tapioca
 ```
 
 This will:
 
-* create the [configuration file for Sorbet](https://sorbet.org/docs/cli#config-file), the [configuration file for Tapioca](#Configuration) and the [require.rb file](#manually-requiring-parts-of-a-gem)
-* install the [binstub](https://bundler.io/man/bundle-binstubs.1.html#DESCRIPTION) for Tapioca in your app's `bin/` folder, so that you can use `bin/tapioca` to run commands in your app
+1. create the [configuration file for Sorbet](https://sorbet.org/docs/cli#config-file), the [configuration file for Tapioca](#Configuration) and the [require.rb file](#manually-requiring-parts-of-a-gem)
+2. install the [binstub](https://bundler.io/man/bundle-binstubs.1.html#DESCRIPTION) 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](https://github.com/Shopify/rbi-central) 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 -->
 ```shell
@@ -89,7 +96,7 @@ Options:
                                      # Default: sorbet/tapioca/config.yml
   -V, [--verbose], [--no-verbose]    # Verbose output for debugging purposes
 
-initializes folder structure
+get project ready for type checking
 ```
 <!-- END_HELP_COMMAND_INIT -->
 
@@ -101,7 +108,7 @@ Sorbet does not read the code in your gem dependencies, so it does not know the
 
 In order to generate the RBI files for the gems used in your application, run the following command:
 
-```sh
+```shell
 $ bin/tapioca gems [gems...]
 
 Removing RBI files of gems that have been removed:
@@ -155,6 +162,8 @@ Options:
                                                               # Default: sorbet/rbi/dsl
           [--rbi-max-line-length=N]                           # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
                                                               # Default: 120
+  -e, [--environment=ENVIRONMENT]                             # The Rack/Rails environment to use when generating RBIs
+                                                              # Default: development
   -c, [--config=<config file path>]                           # Path to the Tapioca configuration file
                                                               # Default: sorbet/tapioca/config.yml
   -V, [--verbose], [--no-verbose]                             # Verbose output for debugging purposes
@@ -163,11 +172,17 @@ generate RBIs from gems
 ```
 <!-- END_HELP_COMMAND_GEM -->
 
+By default, running `tapioca gem` will only generate the RBI files for gems that have been added to or removed from the project's `Gemfile` this means that Tapioca will not regenerate the RBI files for untouched gems. However, when changing Tapioca configuration or bumping its version, it may be useful to force the regeneration of the RBI files previsouly generated. This can be done with the `--all` option:
+
+```shell
+bin/tapioca gems --all
+```
+
 > Are you coming from `srb rbi`? [See how `tapioca gem` compares to `srb rbi`](https://github.com/Shopify/tapioca/wiki/How-does-tapioca-compare-to-%22srb-rbi-gems%22-%3F).
 
 #### Manually requiring parts of a gem
 
-It may happen that the RBI file generated for a gem listed inside your `Gemfile.lock` is missing some definitions taht you would expect it to be exporting.
+It may happen that the RBI file generated for a gem listed inside your `Gemfile.lock` is missing some definitions that you would expect it to be exporting.
 
 For gems that have a normal default `require` and that load all of their constants through that, everything should work seamlessly. However, for gems that are marked as `require: false` in the `Gemfile`, or for gems that export constants optionally via different requires, where a single require does not load the whole gem code into memory, Tapioca will not be able to load some of the types into memory and, thus, won't be able to generate complete RBIs for them. For this reason, we need to keep a small external file named `sorbet/tapioca/require.rb` that is executed after all the gems in the `Gemfile` have been required and before generation of gem RBIs have started. This file is responsible for adding the requires for additional files from gems, which are not covered by the default require.
 
@@ -210,7 +225,7 @@ If you ever run into a case, where you add a gem or update the version of a gem
 
 To help you get started, you can use the command `tapioca require` to auto-populate the contents of the `sorbet/tapioca/require.rb` file with all the requires found in your application:
 
-```sh
+```shell
 $ bin/tapioca require
 
 Compiling sorbet/tapioca/require.rb, this may take a few seconds... Done
@@ -223,11 +238,11 @@ Once the file is generated, you should review it, remove all unnecessary require
 
 #### Excluding a gem from RBI generation
 
-It may be useful to exclude some gems from the generation process. For example for gems that are in Bundle's debug group or gems of which the contents are dependent on the architecture they are loaded on. A typical example is `fakefs`, which, if loaded into memory, changes `File` operations to be no-ops and breaks Tapioca RBI file generation altogether.
+It may be useful to exclude some gems from the generation process. For example for gems that are in Bundle's debug group or gems of which the contents are dependent on the architecture they are loaded on.
 
 To do so you can pass the list of gems you want to exclude in the command line with the `--exclude` option:
 
-```sh
+```shell
 $ bin/tapioca gems --exclude gemA gemB
 ```
 
@@ -240,13 +255,18 @@ gem:
     - gemB
 ```
 
+There are a few development/test environment gems that can cause RBI generation issues, so Tapioca skips them by default:
+
+* `debug`
+* `fakefs`
+
 #### Changing the strictness level of the RBI for a gem
 
 By default, all RBI files for gems are generated with the [strictness level](https://sorbet.org/docs/static#file-level-granularity-strictness-levels) `typed: true`. Sometimes, this strictness level can create type-checking errors when a gem contains definitions that conflict with [Sorbet internal definitions for Ruby core and standard library](https://sorbet.org/docs/faq#it-looks-like-sorbets-types-for-the-stdlib-are-wrong).
 
 Tapioca comes with an automatic detection (option `--auto-strictness`, enabled by default) of such cases and will switch the strictness level to `typed: false` in RBI files containing conflicts with the core and standard library definitions. It is nonetheless possible to manually switch the strictness level for a gem using the `--typed-overrides` option:
 
-```sh
+```shell
 $ bin/tapioca gems --typed-overrides gemA:false gemB:false
 ```
 
@@ -263,7 +283,7 @@ gem:
 
 To ensure all RBI files for gems are up-to-date with the latest changes in your `Gemfile.lock`, Tapioca provides a `--verify` option:
 
-```sh
+```shell
 $ bin/tapioca gems --verify
 
 Checking for out-of-date RBIs...
@@ -273,6 +293,115 @@ Nothing to do, all RBIs are up-to-date.
 
 This option can be used on CI to make sure the RBI files are always up-to-date and ensure accurate type checking. **Warning**: doing so will break your normal Dependabot workflow as every pull-request opened to bump a gem version will fail CI since the RBI will be out-of-date and will require you to manually run `bin/tapioca gems` to update them.
 
+### Pulling RBI annotations from remote sources
+
+Since Tapioca does not perform any type inference, the RBI files generated for the gems do not contain any type signatures. Instead, Tapioca relies on the community to provide high-quality, manually written RBI annotations for public gems.
+
+To pull the annotations relevant to your project from the central repository, run the `annotations` command:
+
+```shell
+$ bin/tapioca annotations
+
+Retrieving index from central repository... Done
+Listing gems from Gemfile.lock... Done
+Removing annotations for gems that have been removed...  Nothing to do
+Fetching gem annotations from central repository...
+
+  Fetched activesupport
+   created  sorbet/rbi/annotations/activesupport.rbi
+
+Done
+```
+
+<!-- START_HELP_COMMAND_ANNOTATIONS -->
+```shell
+$ tapioca help annotations
+
+Usage:
+  tapioca annotations
+
+Options:
+          [--sources=one two three]                           # URIs of the sources to pull gem RBI annotations from
+                                                              # Default: ["https://raw.githubusercontent.com/Shopify/rbi-central/main"]
+          [--netrc], [--no-netrc]                             # Use .netrc to authenticate to private sources
+                                                              # Default: true
+          [--netrc-file=NETRC_FILE]                           # Path to .netrc file
+          [--auth=AUTH]                                       # HTTP authorization header for private sources
+  --typed, -t, [--typed-overrides=gem:level [gem:level ...]]  # Override for typed sigils for pulled annotations
+  -c, [--config=<config file path>]                           # Path to the Tapioca configuration file
+                                                              # Default: sorbet/tapioca/config.yml
+  -V, [--verbose], [--no-verbose]                             # Verbose output for debugging purposes
+
+Pull gem RBI annotations from remote sources
+```
+<!-- END_HELP_COMMAND_ANNOTATIONS -->
+
+By default, Tapioca will pull the annotations stored in the central repository located at https://github.com/Shopify/rbi-central. It is possible to use a custom repository by changing the value of the `--sources` options. For example if your repository is stored on Github:
+
+```shell
+$ bin/tapioca annotations --sources https://raw.githubusercontent.com/$USER/$REPO/$BRANCH
+```
+
+Tapioca also supports pulling annotations from multiple sources:
+
+```shell
+$ bin/tapioca annotations --sources https://raw.githubusercontent.com/$USER/$REPO1/$BRANCH https://raw.githubusercontent.com/$USER/$REPO2/$BRANCH
+```
+
+#### Basic authentication
+
+Private repositories can be used as sources by passing the option `--auth` with an authentication string. For Github, this string is `token $TOKEN` where `$TOKEN` is a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token):
+
+```shell
+$ bin/tapioca annotations --sources https://raw.githubusercontent.com/$USER/$PRIVATE_REPO/$BRANCH --auth "token $TOKEN"
+```
+
+#### Using a .netrc file
+
+Tapioca supports reading credentials from a [netrc](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html) file (defaulting to `~/.netrc`).
+
+Given these lines in your netrc:
+
+```netrc
+machine raw.githubusercontent.com
+  login $USERNAME
+  password $TOKEN
+```
+
+where `$USERNAME` is your Github username and `$TOKEN` is a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), then, if you run Tapioca with the `--netrc` option (enabled by default), your annotation requests should be authenticated properly.
+
+The `--netrc-file` option can be specified to read from a file other than `~/.netrc`:
+
+```shell
+$ bin/tapioca annotations --netrc-file /path/to/my/netrc/file
+```
+
+Similar to `--netrc-file`, you can also specify an alternative netrc file by using the `TAPIOCA_NETRC_FILE` environment variable:
+
+```shell
+$ TAPIOCA_NETRC_FILE=/path/to/my/netrc/file bin/tapioca annotations
+```
+
+Tapioca will first try to find the netrc file as specified by the `--netrc-file` option. If that option is not supplied, it will try the `TAPIOCA_NETRC_FILE` environment variable value. If that value is not supplied either, it will fallback to `~/.netrc`.
+
+#### Changing the typed strictness of annotations files
+
+Sometimes the annotations files pulled by Tapioca will create type errors in your project because of incompatibilities.
+It is possible to ignore such files by switching their strictness level `--typed-overrides` option:
+
+```shell
+$ bin/tapioca annotations --typed-overrides gemA:ignore gemB:false
+```
+
+Or through the configuration file:
+
+```yaml
+annotations:
+  typed_overrides:
+    gemA: "ignore"
+    gemB: "false"
+```
+
 ### Generating RBI files for Rails and other DSLs
 
 Sorbet by itself does not understand DSLs involving meta-programming, such as Rails. This means that Sorbet won't know about constants and methods generated by `ActiveRecord` or `ActiveSupport`.
@@ -280,7 +409,7 @@ To solve this, Tapioca can load your application and introspect it to find the c
 
 To generate the RBI files for the DSLs used in your application, run the following command:
 
-```sh
+```shell
 $ bin/tapioca dsl
 
 Loading Rails application... Done
@@ -315,6 +444,8 @@ Options:
                                                # Default: 1
           [--rbi-max-line-length=N]            # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
                                                # Default: 120
+  -e, [--environment=ENVIRONMENT]              # The Rack/Rails environment to use when generating RBIs
+                                               # Default: development
   -c, [--config=<config file path>]            # Path to the Tapioca configuration file
                                                # Default: sorbet/tapioca/config.yml
   -V, [--verbose], [--no-verbose]              # Verbose output for debugging purposes
@@ -327,7 +458,7 @@ generate RBIs for dynamic methods
 
 To ensure all RBI files for DSLs are up-to-date with the latest changes in your application or database, Tapioca provide a `--verify` option:
 
-```sh
+```shell
 $ bin/tapioca dsl --verify
 
 Loading Rails application... Done
@@ -517,7 +648,7 @@ To get you started quickly, Tapioca can create a RBI file containing a stub of a
 
 To generate the RBI file for the missing constants used in your application run the following command:
 
-```sh
+```shell
 $ bin/tapioca todo
 
 Compiling sorbet/rbi/todo.rbi, this may take a few seconds... Done
@@ -566,13 +697,14 @@ end
 
 As you migrate to newer versions of Sorbet or Tapioca, some shims may become useless as Sorbet's internal definitions for Ruby's core and standard library is enhanced or Tapioca is able to generate definitions for new DSLs. To avoid keeping outdated or useless definitions inside your application shims, Tapioca provides the `check-shims` command:
 
-```sh
+```shell
 $ bin/tapioca check-shims
 
 Loading Sorbet payload...  Done
 Loading shim RBIs from sorbet/rbi/shims...  Done
 Loading gem RBIs from sorbet/rbi/gems...  Done
 Loading gem RBIs from sorbet/rbi/dsl...  Done
+Loading annotation RBIs from sorbet/rbi/annotations...  Done
 Looking for duplicates...  Done
 
 Duplicated RBI for ::MyModel#title:
@@ -588,27 +720,33 @@ Please remove the duplicated definitions from the sorbet/rbi/shims directory.
 
 This command can be used on CI to make sure the RBI shims are always up-to-date and non-redundant with generated files.
 
-<!-- START_HELP_COMMAND_CHECK-SHIMS -->
+<!-- START_HELP_COMMAND_CHECK_SHIMS -->
 ```shell
-$ bin/tapioca help check-shims
+$ tapioca help check_shims
 
 Usage:
   tapioca check-shims
 
 Options:
-      [--gem-rbi-dir=GEM_RBI_DIR]    # Path to gem RBIs
-                                     # Default: sorbet/rbi/gems
-      [--dsl-rbi-dir=DSL_RBI_DIR]    # Path to DSL RBIs
-                                     # Default: sorbet/rbi/dsl
-      [--shim-rbi-dir=SHIM_RBI_DIR]  # Path to shim RBIs
-                                     # Default: sorbet/rbi/shims
-  -c, [--config=<config file path>]  # Path to the Tapioca configuration file
-                                     # Default: sorbet/tapioca/config.yml
-  -V, [--verbose], [--no-verbose]    # Verbose output for debugging purposes
+      [--gem-rbi-dir=GEM_RBI_DIR]                  # Path to gem RBIs
+                                                   # Default: sorbet/rbi/gems
+      [--dsl-rbi-dir=DSL_RBI_DIR]                  # Path to DSL RBIs
+                                                   # Default: sorbet/rbi/dsl
+      [--shim-rbi-dir=SHIM_RBI_DIR]                # Path to shim RBIs
+                                                   # Default: sorbet/rbi/shims
+      [--annotations-rbi-dir=ANNOTATIONS_RBI_DIR]  # Path to annotations RBIs
+                                                   # Default: sorbet/rbi/annotations
+      [--todo-rbi-file=TODO_RBI_FILE]              # Path to the generated todo RBI file
+                                                   # Default: sorbet/rbi/todo.rbi
+      [--payload], [--no-payload]                  # Check shims against Sorbet's payload
+                                                   # Default: true
+  -c, [--config=<config file path>]                # Path to the Tapioca configuration file
+                                                   # Default: sorbet/tapioca/config.yml
+  -V, [--verbose], [--no-verbose]                  # Verbose output for debugging purposes
 
 check duplicated definitions in shim RBIs
 ```
-<!-- END_HELP_COMMAND_CHECK-SHIMS -->
+<!-- END_HELP_COMMAND_CHECK_SHIMS -->
 
 ### Configuration
 
@@ -652,6 +790,7 @@ dsl:
   quiet: false
   workers: 1
   rbi_max_line_length: 120
+  environment: development
 gem:
   outdir: sorbet/rbi/gems
   file_header: true
@@ -668,13 +807,20 @@ gem:
   auto_strictness: true
   dsl_dir: sorbet/rbi/dsl
   rbi_max_line_length: 120
+  environment: development
 check_shims:
   gem_rbi_dir: sorbet/rbi/gems
   dsl_rbi_dir: sorbet/rbi/dsl
   shim_rbi_dir: sorbet/rbi/shims
+  annotations_rbi_dir: sorbet/rbi/annotations
+  todo_rbi_file: sorbet/rbi/todo.rbi
   payload: true
 annotations:
-  repo_uri: https://raw.githubusercontent.com/Shopify/rbi-central/main
+  sources:
+  - https://raw.githubusercontent.com/Shopify/rbi-central/main
+  netrc: true
+  netrc_file: ''
+  typed_overrides: {}
 ```
 <!-- END_CONFIG_TEMPLATE -->