tapioca 0.11.8 → 0.11.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e1d35be8426874dde08ba495772d5076d85167f24fa5cfa16b59f424ca3c820
-  data.tar.gz: ce7b53d0399658d9ecfdcda6e42f030b2316bfcd75c3c02ee018dbab966bce30
+  metadata.gz: d9a73b205d42dc103e1e4816c7915a3b4764cdeb6894f384a66e500e95bfbc5a
+  data.tar.gz: ff14910658ef17ebe542f8adb67c70e24ed755b41f31860071425d95917c9172
 SHA512:
-  metadata.gz: 6dd882c66362cc1666f9e89a9634c38b3131fba7a10b0c5fabe19f5675e98adf308132b07c09b3f62d3035f4fc7ab05f36693de13cb74701324aee3933c43234
-  data.tar.gz: 74f78ab7a8d5f284b4a1efbcb7eaf098d609294b3c201e227890d3f1276a5c689ee528b5a610a8a4039eaf549c1e0655c71da04631d62b174a16baf23e312bf4
+  metadata.gz: 34217744dc8a5ae07940fbd4c6a6c6f1a513d6d6169d9fb9ff1785c9bced7b57022cc4573857f70cbbe24b744915e019ad57bdffe349c981a4bc2e675ab23bc6
+  data.tar.gz: 141e26b30087b8573d13b739e52ad5dd9b4934d14dcb1870135e4b91efcc1e3205410e6b625b295be879d6c230a44d95b0a495a8a0bffa7b208d2d6c4efd1df1

data/README.md

@@ -47,9 +47,8 @@ Tapioca makes it easy to work with [Sorbet](https://sorbet.org) in your codebase
   * [Generating RBI files for Rails and other DSLs](#generating-rbi-files-for-rails-and-other-dsls)
     * [Keeping RBI files for DSLs up-to-date](#keeping-rbi-files-for-dsls-up-to-date)
     * [Writing custom DSL compilers](#writing-custom-dsl-compilers)
+    * [Writing custom DSL extensions](#writing-custom-dsl-extensions)
   * [RBI files for missing constants and methods](#rbi-files-for-missing-constants-and-methods)
-    * [Generating the RBI file for missing constants](#generating-the-rbi-file-for-missing-constants)
-    * [Manually writing RBI definitions (shims)](#manually-writing-rbi-definitions-shims)
   * [Configuration](#configuration)
 * [Contributing](#contributing)
 * [License](#license)
@@ -60,7 +59,7 @@ Tapioca makes it easy to work with [Sorbet](https://sorbet.org) in your codebase
 Add this line to your application's `Gemfile`:
 
 ```rb
-group :development do
+group :development, :test do
   gem 'tapioca', require: false
 end
 ```
@@ -72,16 +71,16 @@ Run `bundle install` and make sure Tapioca is properly installed:
 $ tapioca help
 
 Commands:
-  tapioca --version, -v      # show version
+  tapioca --version, -v      # Show version
   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 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               # 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
+  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
 
 Options:
   -c, [--config=<config file path>]  # Path to the Tapioca configuration file
@@ -121,7 +120,7 @@ Options:
                                      # Default: sorbet/tapioca/config.yml
   -V, [--verbose], [--no-verbose]    # Verbose output for debugging purposes
 
-get project ready for type checking
+Get project ready for type checking
 ```
 <!-- END_HELP_COMMAND_INIT -->
 
@@ -172,6 +171,7 @@ Options:
   --post, -a,  [--postrequire=file]                                   # A file to be required after Bundler.require is called
                                                                       # Default: sorbet/tapioca/require.rb
   -x,          [--exclude=gem [gem ...]]                              # Exclude the given gem(s) from RBI generation
+               [--include-dependencies], [--no-include-dependencies]  # Generate RBI files for dependencies of the given gem(s)
   --typed, -t, [--typed-overrides=gem:level [gem:level ...]]          # Override for typed sigils for generated gem RBIs
                                                                       # Default: {"activesupport"=>"false"}
                [--verify], [--no-verify]                              # Verify RBIs are up-to-date
@@ -196,11 +196,11 @@ Options:
                                                                       # Default: sorbet/tapioca/config.yml
   -V,          [--verbose], [--no-verbose]                            # Verbose output for debugging purposes
 
-generate RBIs from gems
+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 previously generated. This can be done with the `--all` option:
+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. If you want to force the regeneration you can supply gem names to the `tapioca gem` command. When supplying gem names if you want to generate RBI files for their dependencies as well, you can use the `--include-dependencies` option. When changing Tapioca configuration or bumping its version, it may be useful to force the regeneration of all the RBI files previously generated. This can be done with the `--all` option:
 
 ```shell
 bin/tapioca gems --all
@@ -483,7 +483,7 @@ Options:
                                                                     # Default: sorbet/tapioca/config.yml
   -V,        [--verbose], [--no-verbose]                            # Verbose output for debugging purposes
 
-generate RBIs for dynamic methods
+Generate RBIs for dynamic methods
 ```
 <!-- END_HELP_COMMAND_DSL -->
 
@@ -667,57 +667,121 @@ No errors! Great job.
 
 For more concrete and advanced examples, take a look at [Tapioca's default DSL compilers](https://github.com/Shopify/tapioca/tree/main/lib/tapioca/dsl/compilers).
 
-### RBI files for missing constants and methods
+#### Writing custom DSL extensions
 
-Even after generating the RBIs, it is possible that some constants or methods are still undefined for Sorbet.
+When writing custom DSL compilers, it is sometimes necessary to rely on an extension, i.e. a bit of code that is being loaded before the application in order to override some behavior. This is typically useful when a DSL's implementation does not store enough information for the compiler to properly define signatures.
 
-This might be for multiple reasons, with the most frequents ones being:
+Let's reuse the previous `Encryptable` module as an example, but this time let's imagine that the implementation of `attr_encrypted` does not store attribute names:
 
-* The constant or method comes from a part of the gem that Tapioca cannot load (optional dependency, wrong architecture, etc.)
-* The constant or method comes from a DSL or meta-programming that Tapioca doesn't support yet
-* The constant or method only exists when a specific code path is executed
 
-The best way to deal with such occurrences is to manually create RBI files (shims) for them so you can also add types but depending on the amount of meta-programming used in your project this can mean an overwhelming amount of manual work.
+```rb
+module Encryptable
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
 
-#### Generating the RBI file for missing constants
+  module ClassMethods
+    def attr_encrypted(attr_name)
+      attr_accessor(attr_name)
 
-To get you started quickly, Tapioca can create a RBI file containing a stub of all the missing constants so you can typecheck your project without missing constants and shim them later as you need them.
+      encrypted_attr_name = :"#{attr_name}_encrypted"
 
-To generate the RBI file for the missing constants used in your application run the following command:
+      define_method(encrypted_attr_name) do
+        value = send(attr_name)
+        encrypt(value)
+      end
 
-```shell
-$ bin/tapioca todo
+      define_method("#{encrypted_attr_name}=") do |value|
+        send("#{attr_name}=", decrypt(value))
+      end
+    end
+  end
 
-Compiling sorbet/rbi/todo.rbi, this may take a few seconds... Done
-All unresolved constants have been written to sorbet/rbi/todo.rbi.
-Please review changes and commit them.
+  private
+
+  def encrypt(value)
+    value.unpack("H*").first
+  end
+
+  def decrypt(value)
+    [value].pack("H*")
+  end
+end
 ```
 
-This will generate the file `sorbet/rbi/todo.rbi` defining all unresolved constants as empty modules. Since the constants are "missing", Tapioca does not know if they should be marked as modules or classes and will use modules as a safer default. This file should be reviewed, corrected, if necessary, and then committed in your repository.
+Without the `attribute_names` array, the compiler has no way of knowing which methods were defined by the `attr_encrypted` DSL. This can be solved by defining an extension that will override the behavior of `attr_encrypted`:
 
-<!-- START_HELP_COMMAND_TODO -->
-```shell
-$ tapioca help todo
+```rb
+require "encryptable"
 
-Usage:
-  tapioca todo
+module Tapioca
+  module Extensions
+    module Encryptable
+      attr_reader :__tapioca_encrypted_attributes
 
-Options:
-      [--todo-file=TODO_FILE]              # Path to the generated todo RBI file
-                                           # Default: sorbet/rbi/todo.rbi
-      [--file-header], [--no-file-header]  # Add a "This file is generated" header on top of each generated RBI file
-                                           # 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
+      def attr_encrypted(attr_name)
+        @__tapioca_encrypted_attributes ||= []
+        @__tapioca_encrypted_attributes << attr_name.to_s
 
-generate the list of unresolved constants
+        super
+      end
+
+      ::Encryptable::ClassMethods.prepend(self)
+    end
+  end
+end
 ```
-<!-- END_HELP_COMMAND_TODO -->
 
-#### Manually writing RBI definitions (shims)
+The compiler can now use the `__tapioca_encrypted_attributes` array managed by the extension:
 
-A _shim_ is a hand-crafted RBI file that tells Sorbet about constants, ancestors, methods, etc. that it can't understand statically and aren't already generated by Tapioca.
+```rb
+module Tapioca
+  module Compilers
+    class Encryptable < Tapioca::Dsl::Compiler
+      extend T::Sig
+
+      ConstantType = type_member {{ fixed: T.class_of(Encryptable) }}
+
+      sig { override.returns(T::Enumerable[Module]) }
+      def self.gather_constants
+        # Collect all the classes that include Encryptable
+        all_classes.select { |c| c < ::Encryptable }
+      end
+
+      sig { override.void }
+      def decorate
+        # Create a RBI definition for each class that includes Encryptable
+        root.create_path(constant) do |klass|
+          # For each encrypted attribute we find in the class
+          constant.__tapioca_encrypted_attributes.each do |attr_name|
+            # Create the RBI definitions for all the missing methods
+            klass.create_method(attr_name, return_type: "String")
+            klass.create_method("#{attr_name}=", parameters: [ create_param("value", type: "String") ], return_type: "void")
+            klass.create_method("#{attr_name}_encrypted", return_type: "String")
+            klass.create_method("#{attr_name}_encrypted=", parameters: [ create_param("value", type: "String") ], return_type: "void")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+In order for DSL extensions to be discovered by Tapioca, they either needs to be placed inside the `sorbet/tapioca/extensions` directory of your application or be inside a `tapioca/dsl/extensions` folder on the load path.
+
+For more concrete and advanced examples, take a look at [Tapioca's default DSL extensions](https://github.com/Shopify/tapioca/tree/main/lib/tapioca/dsl/extensions).
+
+### RBI files for missing constants and methods
+
+Even after generating the RBIs, it is possible that some constants or methods are still undefined for Sorbet.
+
+This might be for multiple reasons, with the most frequents ones being:
+
+* The constant or method comes from a part of the gem that Tapioca cannot load (optional dependency, wrong architecture, etc.)
+* The constant or method comes from a DSL or meta-programming that Tapioca doesn't support yet
+* The constant or method only exists when a specific code path is executed
+
+The best way to deal with such occurrences is _shims_. A shim is a hand-crafted RBI file that tells Sorbet about constants, ancestors, methods, etc. that it can't understand statically and aren't already generated by Tapioca.
 
 These shims are usually placed in the `sorbet/rbi/shims` directory. From there, conventionally, you should follow the directory structure of the project to the file you'd like to shim. For example, say you had a `person.rb` file found at `app/models/person.rb`. If you were to add a shim for it, you'd want to create your RBI file at `sorbet/rbi/shims/app/models/person.rbi`.
 
@@ -782,10 +846,12 @@ Options:
                                                    # Default: sorbet/tapioca/config.yml
   -V, [--verbose], [--no-verbose]                  # Verbose output for debugging purposes
 
-check duplicated definitions in shim RBIs
+Check duplicated definitions in shim RBIs
 ```
 <!-- END_HELP_COMMAND_CHECK_SHIMS -->
 
+Depending on the amount of meta-programming used in your project this can mean an overwhelming amount of manual work. In this case, you should consider [writting a custom DSL compiler](#writing-custom-dsl-compilers).
+
 ### Configuration
 
 Tapioca supports loading command defaults from a configuration file. The default configuration file location is `sorbet/tapioca/config.yml` but this default can be changed using the `--config` flag and supplying an alternative configuration file path.
@@ -839,6 +905,7 @@ gem:
   prerequire: ''
   postrequire: sorbet/tapioca/require.rb
   exclude: []
+  include_dependencies: false
   typed_overrides:
     activesupport: 'false'
   verify: false

data/lib/tapioca/cli.rb

@@ -23,7 +23,7 @@ module Tapioca
       desc: "Verbose output for debugging purposes",
       default: false
 
-    desc "init", "get project ready for type checking"
+    desc "init", "Get project ready for type checking"
     def init
       # We need to make sure that trackers stay enabled until the `gem` command is invoked
       Runtime::Trackers.with_trackers_enabled do
@@ -31,12 +31,17 @@ module Tapioca
         invoke(:annotations)
         invoke(:gem)
       end
-      invoke(:todo)
+
+      # call the command directly to skip deprecation warning
+      Commands::Todo.new(
+        todo_file: DEFAULT_TODO_FILE,
+        file_header: true,
+      ).run
 
       print_init_next_steps
     end
 
-    desc "configure", "initialize folder structure and type checking configuration"
+    desc "configure", "Initialize folder structure and type checking configuration"
     option :postrequire, type: :string, default: DEFAULT_POSTREQUIRE_FILE
     def configure
       command = Commands::Configure.new(
@@ -44,22 +49,20 @@ module Tapioca
         tapioca_config: options[:config],
         default_postrequire: options[:postrequire],
       )
-      command.execute
+      command.run
     end
 
-    desc "require", "generate the list of files to be required by tapioca"
+    desc "require", "Generate the list of files to be required by tapioca"
     option :postrequire, type: :string, default: DEFAULT_POSTREQUIRE_FILE
     def require
       command = Commands::Require.new(
         requires_path: options[:postrequire],
         sorbet_config_path: SORBET_CONFIG_FILE,
       )
-      Tapioca.silence_warnings do
-        command.execute
-      end
+      command.run
     end
 
-    desc "todo", "generate the list of unresolved constants"
+    desc "todo", "Generate the list of unresolved constants"
     option :todo_file,
       type: :string,
       desc: "Path to the generated todo RBI file",
@@ -73,12 +76,10 @@ module Tapioca
         todo_file: options[:todo_file],
         file_header: options[:file_header],
       )
-      Tapioca.silence_warnings do
-        command.execute
-      end
+      command.run_with_deprecation
     end
 
-    desc "dsl [constant...]", "generate RBIs for dynamic methods"
+    desc "dsl [constant...]", "Generate RBIs for dynamic methods"
     option :outdir,
       aliases: ["--out", "-o"],
       banner: "directory",
@@ -140,7 +141,7 @@ module Tapioca
       # Assume anything starting with a capital letter or colon is a class, otherwise a path
       constants, paths = constant_or_paths.partition { |c| c =~ /\A[A-Z:]/ }
 
-      command = Commands::Dsl.new(
+      command_args = {
         requested_constants: constants,
         requested_paths: paths.map { |p| Pathname.new(p) },
         outpath: Pathname.new(options[:outdir]),
@@ -148,25 +149,26 @@ module Tapioca
         exclude: options[:exclude],
         file_header: options[:file_header],
         tapioca_path: TAPIOCA_DIR,
-        should_verify: options[:verify],
         quiet: options[:quiet],
         verbose: options[:verbose],
         number_of_workers: options[:workers],
         rbi_formatter: rbi_formatter(options),
         app_root: options[:app_root],
         halt_upon_load_error: options[:halt_upon_load_error],
-      )
-
-      Tapioca.silence_warnings do
-        if options[:list_compilers]
-          command.list_compilers
-        else
-          command.execute
-        end
+      }
+
+      command = if options[:verify]
+        Commands::DslVerify.new(**command_args)
+      elsif options[:list_compilers]
+        Commands::DslCompilerList.new(**command_args)
+      else
+        Commands::DslGenerate.new(**command_args)
       end
+
+      command.run
     end
 
-    desc "gem [gem...]", "generate RBIs from gems"
+    desc "gem [gem...]", "Generate RBIs from gems"
     option :outdir,
       aliases: ["--out", "-o"],
       banner: "directory",
@@ -196,6 +198,10 @@ module Tapioca
       banner: "gem [gem ...]",
       desc: "Exclude the given gem(s) from RBI generation",
       default: []
+    option :include_dependencies,
+      type: :boolean,
+      desc: "Generate RBI files for dependencies of the given gem(s)",
+      default: false
     option :typed_overrides,
       aliases: ["--typed", "-t"],
       type: :hash,
@@ -245,47 +251,54 @@ module Tapioca
       desc: "Halt upon a load error while loading the Rails application",
       default: true
     def gem(*gems)
-      Tapioca.silence_warnings do
-        set_environment(options)
-
-        all = options[:all]
-        verify = options[:verify]
-
-        command = Commands::Gem.new(
-          gem_names: all ? [] : gems,
-          exclude: options[:exclude],
-          prerequire: options[:prerequire],
-          postrequire: options[:postrequire],
-          typed_overrides: options[:typed_overrides],
-          outpath: Pathname.new(options[:outdir]),
-          file_header: options[:file_header],
-          include_doc: options[:doc],
-          include_loc: options[:loc],
-          include_exported_rbis: options[:exported_gem_rbis],
-          number_of_workers: options[:workers],
-          auto_strictness: options[:auto_strictness],
-          dsl_dir: options[:dsl_dir],
-          rbi_formatter: rbi_formatter(options),
-          halt_upon_load_error: options[:halt_upon_load_error],
-        )
-
-        raise MalformattedArgumentError, "Options '--all' and '--verify' are mutually exclusive" if all && verify
-
-        unless gems.empty?
-          raise MalformattedArgumentError, "Option '--all' must be provided without any other arguments" if all
-          raise MalformattedArgumentError, "Option '--verify' must be provided without any other arguments" if verify
-        end
+      set_environment(options)
 
-        if gems.empty? && !all
-          command.sync(should_verify: verify, exclude: options[:exclude])
-        else
-          command.execute
-        end
+      all = options[:all]
+      verify = options[:verify]
+      include_dependencies = options[:include_dependencies]
+
+      raise MalformattedArgumentError, "Options '--all' and '--verify' are mutually exclusive" if all && verify
+
+      if gems.empty?
+        raise MalformattedArgumentError,
+          "Option '--include-dependencies' must be provided with gems" if include_dependencies
+      else
+        raise MalformattedArgumentError, "Option '--all' must be provided without any other arguments" if all
+        raise MalformattedArgumentError, "Option '--verify' must be provided without any other arguments" if verify
       end
+
+      command_args = {
+        gem_names: all ? [] : gems,
+        exclude: options[:exclude],
+        include_dependencies: options[:include_dependencies],
+        prerequire: options[:prerequire],
+        postrequire: options[:postrequire],
+        typed_overrides: options[:typed_overrides],
+        outpath: Pathname.new(options[:outdir]),
+        file_header: options[:file_header],
+        include_doc: options[:doc],
+        include_loc: options[:loc],
+        include_exported_rbis: options[:exported_gem_rbis],
+        number_of_workers: options[:workers],
+        auto_strictness: options[:auto_strictness],
+        dsl_dir: options[:dsl_dir],
+        rbi_formatter: rbi_formatter(options),
+        halt_upon_load_error: options[:halt_upon_load_error],
+      }
+
+      command = if verify
+        Commands::GemVerify.new(**command_args)
+      elsif !gems.empty? || all
+        Commands::GemGenerate.new(**command_args)
+      else
+        Commands::GemSync.new(**command_args)
+      end
+
+      command.run
     end
     map "gems" => :gem
 
-    desc "check-shims", "check duplicated definitions in shim RBIs"
+    desc "check-shims", "Check duplicated definitions in shim RBIs"
     option :gem_rbi_dir, type: :string, desc: "Path to gem RBIs", default: DEFAULT_GEM_DIR
     option :dsl_rbi_dir, type: :string, desc: "Path to DSL RBIs", default: DEFAULT_DSL_DIR
     option :shim_rbi_dir, type: :string, desc: "Path to shim RBIs", default: DEFAULT_SHIM_DIR
@@ -304,9 +317,7 @@ module Tapioca
         number_of_workers: options[:workers],
       )
 
-      Tapioca.silence_warnings do
-        command.execute
-      end
+      command.run
     end
 
     desc "annotations", "Pull gem RBI annotations from remote sources"
@@ -335,14 +346,12 @@ module Tapioca
         typed_overrides: options[:typed_overrides],
       )
 
-      Tapioca.silence_warnings do
-        command.execute
-      end
+      command.run
     end
 
     map ["--version", "-v"] => :__print_version
 
-    desc "--version, -v", "show version"
+    desc "--version, -v", "Show version"
     def __print_version
       puts "Tapioca v#{Tapioca::VERSION}"
     end