admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

docs/Typechecking: update to latest code standards

Browse Source
This commit is contained in:
Bo Anderson 2024-08-20 15:55:57 +01:00
parent 9d4000b15c
commit 7117233e5f
No known key found for this signature in database
1 changed files with 11 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/Typechecking.md
View File

@ -30,11 +30,11 @@ For more information on how to express more complex types, refer to the official
### Ruby interface files (`.rbi`) ### Ruby interface files (`.rbi`)
[RBI files](https://sorbet.org/docs/rbi) help Sorbet learn about constants, ancestors and methods defined in ways it doesn’t understand natively. We can also create an RBI file to help Sorbet understand dynamic definitions. [RBI files](https://sorbet.org/docs/rbi) help Sorbet learn about constants, ancestors and methods defined in ways it doesn’t understand natively. We can also create an RBI file to help Sorbet understand dynamic definitions. Some of these files are autogenerated (see the next section) and some are manually written ([example]).
Sometimes it is necessary to explicitly include the `Kernel` module in order for Sorbet to know that methods such as `puts` are available in a given context. This is mostly necessary for modules since they can be used in both `BasicObject`s (which don't include `Kernel`) and `Object`s (which include `Kernel` by default). In this case, it is necessary to create an `.rbi` file ([example]) since re-including the `Kernel` module in actual code can break things. There are also a very small number of files that Homebrew loads before sorbet-runtime, such as `utils/gems.rb`. Those files cannot have type signatures alongside the code itself, so RBI files are used there instead to retain static type checking.
[example]: https://github.com/Homebrew/brew/blob/61b79318ed089b5010501e2cbf163fd8e48e2dfc/Library/Homebrew/global.rbi [example]: https://github.com/Homebrew/brew/blob/9d4000b15cb6ffa8c11f49372f7016d05aaa0851/Library/Homebrew/extend/ENV.rbi
### The [`Library/Homebrew/sorbet`] directory ### The [`Library/Homebrew/sorbet`] directory
@ -42,9 +42,10 @@ Sometimes it is necessary to explicitly include the `Kernel` module in order for
- The `rbi` directory contains all Ruby Interface (`.rbi`) files auto-generated by running `brew typecheck --update`: - The `rbi` directory contains all Ruby Interface (`.rbi`) files auto-generated by running `brew typecheck --update`:
- RBI files for all gems are generated using [Tapioca](https://github.com/Shopify/tapioca#tapioca). - `gems`: RBI files for all gems are generated using [Tapioca](https://github.com/Shopify/tapioca#tapioca).
- Definitions for dynamic code (i.e. meta-programming) are generated using `srb rbi hidden-definitions`. - `dsl`: RBI files autogenerated by our [Tapioca compilers](https://github.com/Homebrew/brew/tree/master/Library/Homebrew/sorbet/tapioca/compilers).
- Definitions for missing constants are generated using `srb rbi todo`. - `parlour.rbi`: RBI files generated by Parlour that have not yet been migrated to Tapioca compilers
- `upstream.rbi`: This file is not auto-generated and is a manually written file that contains temporary workarounds for upstream Sorbet issues. This file is typically empty.
- The `config` file is a newline-separated list of arguments to pass to `srb tc`, the same as if they’d been passed on the command line. Arguments in the config file are always passed first, followed by arguments provided on the command line. We use it to ignore Gem directories which we do not wish to type check. - The `config` file is a newline-separated list of arguments to pass to `srb tc`, the same as if they’d been passed on the command line. Arguments in the config file are always passed first, followed by arguments provided on the command line. We use it to ignore Gem directories which we do not wish to type check.
@ -64,7 +65,10 @@ Sorbet reports type errors along with an error reference code, which can be used
- One of the most frequent errors that we've encountered is `7003: Method does not exist.` Since Ruby is a very dynamic language, methods can be defined in ways Sorbet cannot see statically. In such cases, check if the method exists at runtime; if not, then Sorbet has caught a future bug! But, it is also possible that even though a method exists at runtime, Sorbet cannot see it. In such cases, we use [`.rbi` files](#ruby-interface-files-rbi). - One of the most frequent errors that we've encountered is `7003: Method does not exist.` Since Ruby is a very dynamic language, methods can be defined in ways Sorbet cannot see statically. In such cases, check if the method exists at runtime; if not, then Sorbet has caught a future bug! But, it is also possible that even though a method exists at runtime, Sorbet cannot see it. In such cases, we use [`.rbi` files](#ruby-interface-files-rbi).
- Since Sorbet does not automatically assume that Kernel is to be included in Modules, we may encounter many errors while trying to use methods like `puts`, `ohai`, `odebug` etc. A simple workaround for this is to add an extra `include Kernel` line in the respective RBI file. - Since Sorbet does not automatically assume that Kernel is to be included in Modules, we may encounter many errors while trying to use methods like `puts`, `ohai`, `odebug` etc. There are generally two approaches to fixing this:
- If you are using `module_function` but never run `include ModuleName` anywhere, remove the `module_definition` and convert all methods to class methods (prepend the name with `self.`)
- If you do include the module elsewhere, add a `requires_ancestor` to the module defining what types of classes this module can be included in. This may be as simple as a `requires_ancestor { Kernel }`, which most classes are a descendant from.
- The tips above are very generic and apply to lots of cases. For some common gotchas when using Sorbet, refer to the [Sorbet Error Reference](https://sorbet.org/docs/error-reference) and [FAQ](https://sorbet.org/docs/faq). - The tips above are very generic and apply to lots of cases. For some common gotchas when using Sorbet, refer to the [Sorbet Error Reference](https://sorbet.org/docs/error-reference) and [FAQ](https://sorbet.org/docs/faq).