tapioca 0.19.1 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d3606b2440f453c78a226d8beec0ce61673d416fa74dba7d0380cd31404feaa
-  data.tar.gz: c290cccb23e39c3423913357b187d74de382de4c818194676b206e0981f21c17
+  metadata.gz: 16f43e72a4dc002c9e6dcfa922274e3aff4de57318d48774eb7592ca4d548d8e
+  data.tar.gz: '03464479e0edf22b0abfe21536b674fd9000d2e7bd980585b4df01ab17f176e9'
 SHA512:
-  metadata.gz: 4d655006a08405d41158b918625eadbcf7eec8b43da4c9077a7a9fe3ad94ee549865c27f0c66ae1fc0424afc8e6f30806e60f2ed661067264d920e52c6f04b70
-  data.tar.gz: 96c0d237d2fda54650e919d74fc838b5121b714dcb3a4d35d60836911895265b99b29848f399b7f529050d4c930c3669e52ca3787dfbf1671b883883f39b6bba
+  metadata.gz: 9ffbfb1deb3d1e54ed3d3d4a0301a6adcd81dbdba981f187223065d2e9bf67c406db3bde657103dd66b12e8a96ecb4953e0491a3c79feb104b95cbc5608270af
+  data.tar.gz: 548838d69fd2fe5f1be747aef82748362ce4394a3844fefca09037ab8bc33972cc70bcd869c4e22fb09112e2483e8703b3738e96c4e58f5e75004f7729e83087

data/README.md

@@ -41,6 +41,7 @@ Tapioca makes it easy to work with [Sorbet](https://sorbet.org) in your codebase
     * [Changing the strictness level of the RBI for a gem](#changing-the-strictness-level-of-the-rbi-for-a-gem)
     * [Keeping RBI files for gems up-to-date](#keeping-rbi-files-for-gems-up-to-date)
     * [Importing hand written signatures from gem's `rbi/` folder](#importing-hand-written-signatures-from-gems-rbi-folder)
+    * [Writing custom gem extensions](#writing-custom-gem-extensions)
   * [Pulling RBI annotations from remote sources](#pulling-rbi-annotations-from-remote-sources)
     * [Basic authentication](#basic-authentication)
     * [Using a .netrc file](#using-a-netrc-file)
@@ -50,6 +51,8 @@ Tapioca makes it easy to work with [Sorbet](https://sorbet.org) in your codebase
     * [Using DSL compiler options](#using-dsl-compiler-options)
     * [Writing custom DSL compilers](#writing-custom-dsl-compilers)
     * [Writing custom DSL extensions](#writing-custom-dsl-extensions)
+  * [Rewriting RBS comments to Sorbet signatures](#rewriting-rbs-comments-to-sorbet-signatures)
+    * [Caching rewrites with Bootsnap](#caching-rewrites-with-bootsnap)
   * [RBI files for missing constants and methods](#rbi-files-for-missing-constants-and-methods)
   * [Configuration](#configuration)
 * [Editor Integration](#editor-integration)
@@ -343,6 +346,55 @@ This option can be used in CI to make sure the RBI files are *up-to-date* and en
 
 Tapioca will import any signatures found in the `rbi/` folder of a given gem and combine them with the RBIs it generates. This is useful when a gem doesn't want to depend on `sorbet-runtime` but still wants to provide type safety to users during static checks. Note that the `rbi/` folder needs to be included in the gem release using the `.gemspec` file. Applications can choose not to import these signatures using the `--no-exported-gem-rbis` flag.
 
+#### Writing custom gem extensions
+
+Similar to [DSL extensions](#writing-custom-dsl-extensions), it is sometimes useful to patch and modify certain behavior
+from gems to ensure that RBIs are generated correctly. Gem RBIs are generated by reflecting over what the gem defines at
+runtime, which means that anything the gem never really defines is invisible to Tapioca. A common example is methods
+handled by `method_missing`:
+
+```ruby
+# my_gem/lib/my_gem/settings.rb
+
+module MyGem
+  class Settings
+    SETTINGS = [:host, :port, :timeout]
+
+    def method_missing(name, *args)
+      SETTINGS.include?(name) ? @config[name] : super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      SETTINGS.include?(name) || super
+    end
+  end
+end
+```
+
+Since `host`, `port` and `timeout` are never defined as real methods, they will be missing from the generated RBI. An
+extension can define them, so that Tapioca is able to see them:
+
+```ruby
+# my_gem/lib/tapioca/gem/extensions/my_gem.rb
+
+require "my_gem"
+
+module MyGem
+  class Settings
+    SETTINGS.each do |name|
+      define_method(name) { @config[name] }
+    end
+  end
+end
+```
+
+Extensions are only loaded during RBI generation, so they never change the behavior of the gem for applications using
+it. They are also loaded before the bundle is required, which is why the extension has to require what it wants to
+patch.
+
+Applications can also define their own gem extensions by placing them inside the `sorbet/tapioca/gem/extensions`
+directory.
+
 ### 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.
@@ -502,6 +554,8 @@ Options:
   -w,        [--workers=N]                                                                         # Number of parallel workers to use when generating RBIs (default: auto)
              [--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
+             [--max-diff-lines=N]                                                                  # Max number of diff lines to include in the `dsl --verify` output
+                                                                                                   # Default: 250
   -e,        [--environment=ENVIRONMENT]                                                           # The Rack/Rails environment to use when generating RBIs
                                                                                                    # Default: development
   -l,        [--list-compilers], [--no-list-compilers], [--skip-list-compilers]                    # List all loaded compilers
@@ -836,6 +890,35 @@ In order for DSL extensions to be discovered by Tapioca, they either needs to be
 
 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).
 
+### Rewriting RBS comments to Sorbet signatures
+
+Tapioca translates [RBS comments](https://sorbet.org/docs/rbs-comments) into Sorbet `sig {}` blocks at file load time, so `sorbet-runtime` wraps the methods as if they had been written with native sigs. This is what lets the DSL command introspect signatures that were originally documented as RBS comments.
+
+The rewriting is automatic on every `tapioca` invocation: [`require-hooks`](https://github.com/Shopify/require-hooks) intercepts `.rb` loads and `Spoom::Sorbet::Translate.rbs_comments_to_sorbet_sigs` translates the source before Ruby compiles it to bytecode.
+
+#### Caching rewrites with Bootsnap
+
+`tapioca dsl` boots the app and eager-loads source files for introspection, so the rewrite runs across the whole codebase. On large applications this adds noticeable overhead. To cache the rewrite output across runs using [bootsnap](https://github.com/Shopify/bootsnap)'s iseq cache, you can set `TAPIOCA_RBS_CACHE=1`:
+
+```shell
+$ TAPIOCA_RBS_CACHE=1 bin/tapioca dsl
+```
+
+Tapioca configures Bootsnap's iseq cache against a dedicated directory (`tmp/cache/bootsnap-tapioca-rbs` by
+default; override with `TAPIOCA_BOOTSNAP_CACHE_DIR`).
+
+Tapioca writes the current `Gemfile.lock` digest to `.gemfile-lock-digest` inside that cache directory. When the
+lockfile changes, Tapioca sees the digest mismatch and resets Bootsnap's cache payload before configuring Bootsnap.
+This lets gem bumps that affect rewriting, such as `tapioca`, start from a fresh cache without accumulating old cache
+directories.
+
+`Bootsnap.setup` mutates a process-wide singleton, and a second call would overwrite Tapioca's dedicated cache directory and start writing rewritten iseqs into the host's normal cache. Tapioca enforces this under `TAPIOCA_RBS_CACHE=1`: after its own setup runs, any subsequent `Bootsnap.setup` raises a clear error pointing at the fix. Gate your host's `Bootsnap.setup` on the same env var. Rails apps do this in `config/boot.rb`:
+
+```ruby
+# e.g. config/boot.rb
+require "bootsnap/setup" unless ENV["TAPIOCA_RBS_CACHE"] == "1"
+```
+
 ### 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.
@@ -960,6 +1043,7 @@ dsl:
   quiet: false
   workers: 1
   rbi_max_line_length: 120
+  max_diff_lines: 250
   environment: development
   list_compilers: false
   app_root: "."

data/lib/ruby_lsp/tapioca/run_gem_rbi_check.rb

@@ -116,7 +116,7 @@ module RubyLsp
 
       #: (*untyped flags) -> Array[String]
       def git_ls_gem_rbis(*flags)
-        self #: as untyped # rubocop:disable Style/RedundantSelf
+        self #: as untyped
           .execute_in_project_path("git", "ls-files", *flags, "sorbet/rbi/gems/")
           .lines
           .map(&:strip)

data/lib/tapioca/cli.rb

@@ -116,6 +116,10 @@ module Tapioca
       type: :numeric,
       desc: "Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped",
       default: DEFAULT_RBI_MAX_LINE_LENGTH
+    option :max_diff_lines,
+      type: :numeric,
+      desc: "Max number of diff lines to include in the `dsl --verify` output",
+      default: DEFAULT_MAX_DIFF_LINES
     option :environment,
       aliases: ["-e"],
       type: :string,
@@ -149,6 +153,10 @@ 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:]/ }
 
+      unless options[:max_diff_lines].positive?
+        raise MalformattedArgumentError, "Option '--max-diff-lines' must be a positive number"
+      end
+
       command_args = {
         requested_constants: constants,
         requested_paths: paths.map { |p| Pathname.new(p) },
@@ -166,6 +174,7 @@ module Tapioca
         halt_upon_load_error: options[:halt_upon_load_error],
         compiler_options: options[:compiler_options],
         lsp_addon: self.class.addon_mode,
+        max_diff_lines: options[:max_diff_lines],
       }
 
       command = if options[:verify]

data/lib/tapioca/commands/abstract_dsl.rb

@@ -5,6 +5,7 @@ module Tapioca
   module Commands
     # @abstract
     class AbstractDsl < CommandWithoutTracker
+      include FileHelper
       include SorbetHelper
       include RBIFilesHelper
 
@@ -26,7 +27,8 @@ module Tapioca
       #|   ?app_root: String,
       #|   ?halt_upon_load_error: bool,
       #|   ?compiler_options: Hash[String, untyped],
-      #|   ?lsp_addon: bool
+      #|   ?lsp_addon: bool,
+      #|   ?max_diff_lines: Integer
       #| ) -> void
       def initialize(
         requested_constants:,
@@ -46,7 +48,8 @@ module Tapioca
         app_root: ".",
         halt_upon_load_error: true,
         compiler_options: {},
-        lsp_addon: false
+        lsp_addon: false,
+        max_diff_lines: DEFAULT_MAX_DIFF_LINES
       )
         @requested_constants = requested_constants
         @requested_paths = requested_paths
@@ -66,6 +69,7 @@ module Tapioca
         @skip_constant = skip_constant
         @compiler_options = compiler_options
         @lsp_addon = lsp_addon
+        @max_diff_lines = max_diff_lines
 
         super()
       end
@@ -95,6 +99,11 @@ module Tapioca
           )
         end.compact
 
+        if @only.any?
+          say("Skipping stale RBI removal because `--only` is set.", :yellow)
+          return Set.new
+        end
+
         files_to_purge = existing_rbi_files - generated_files
 
         files_to_purge
@@ -242,7 +251,7 @@ module Tapioca
       def perform_dsl_verification(dir)
         diff = verify_dsl_rbi(tmp_dir: dir)
 
-        report_diff_and_exit_if_out_of_date(diff, :dsl)
+        report_diff_and_exit_if_out_of_date(diff, tmp_dir: dir, command: :dsl)
       ensure
         FileUtils.remove_entry(dir)
       end
@@ -264,7 +273,7 @@ module Tapioca
         @outpath / "#{underscore(constant_name)}.rbi"
       end
 
-      #: (tmp_dir: Pathname) -> Hash[String, Symbol]
+      #: (tmp_dir: Pathname) -> Hash[Pathname, Symbol]
       def verify_dsl_rbi(tmp_dir:)
         diff = {}
 
@@ -296,7 +305,7 @@ module Tapioca
         diff
       end
 
-      #: (Symbol cause, Array[String] files) -> String
+      #: (Symbol cause, Array[Pathname] files) -> String
       def build_error_for_files(cause, files)
         filenames = files.map do |file|
           @outpath / file
@@ -305,26 +314,73 @@ module Tapioca
         "  File(s) #{cause}:\n  - #{filenames}"
       end
 
-      #: (Hash[String, Symbol] diff, Symbol command) -> void
-      def report_diff_and_exit_if_out_of_date(diff, command)
+      #: (Hash[Pathname, Symbol] diff, tmp_dir: Pathname, command: Symbol) -> void
+      def report_diff_and_exit_if_out_of_date(diff, tmp_dir:, command:)
         if diff.empty?
           say("Nothing to do, all RBIs are up-to-date.")
-        else
-          reasons = diff.group_by(&:last).sort.map do |cause, diff_for_cause|
-            build_error_for_files(cause, diff_for_cause.map(&:first))
-          end.join("\n")
+          return
+        end
+
+        reasons = diff.group_by(&:last).sort.map do |cause, diff_for_cause|
+          build_error_for_files(cause, diff_for_cause.map(&:first))
+        end.join("\n")
+
+        diff_output, diff_truncated = build_diff_output(diff, tmp_dir)
+
+        diff_section =
+          if diff_truncated
+            "#{set_color("Diff truncated to #{@max_diff_lines} lines.\nChange the number of displayed lines using the `--max-diff-lines` flag.", :red)}\n#{diff_output.rstrip}"
+          elsif !diff_output.empty?
+            "#{set_color("Diff:", :red)}\n#{diff_output.rstrip}"
+          else
+            ""
+          end
 
-          raise Tapioca::Error, <<~ERROR
-            #{set_color("RBI files are out-of-date. In your development environment, please run:", :green)}
-              #{set_color("`#{default_command(command)}`", :green, :bold)}
-            #{set_color("Once it is complete, be sure to commit and push any changes", :green)}
-            If you don't observe any changes after running the command locally, ensure your database is in a good
-            state e.g. run `bin/rails db:reset`
+        raise Tapioca::Error, <<~ERROR.rstrip
+          #{set_color("RBI files are out-of-date. In your development environment, please run:", :green)}
+            #{set_color("`#{default_command(command)}`", :green, :bold)}
+          #{set_color("Once it is complete, be sure to commit and push any changes", :green)}
+          If you don't observe any changes after running the command locally, ensure your database is in a good
+          state e.g. run `bin/rails db:reset`
 
-            #{set_color("Reason:", :red)}
-            #{reasons}
-          ERROR
+          #{set_color("Reason:", :red)}
+          #{reasons}
+
+          #{diff_section}
+        ERROR
+      end
+
+      #: (Hash[Pathname, Symbol] diff, Pathname tmp_dir) -> [String, bool]
+      def build_diff_output(diff, tmp_dir)
+        out = String.new
+        truncated = false #: bool
+        line_count = 0
+
+        diff.each do |file, status|
+          old_path = (@outpath / file)
+          new_path = (tmp_dir / file)
+
+          chunk = case status
+          when :added then file_diff(file, File::NULL, new_path)
+          when :removed then file_diff(file, old_path, File::NULL)
+          when :changed then file_diff(file, old_path, new_path)
+          else ""
+          end
+
+          next if chunk.nil?
+
+          remaining_lines = @max_diff_lines - line_count
+          if chunk.lines.count > remaining_lines
+            out << chunk.lines.first(remaining_lines).join
+            truncated = true
+            break
+          end
+
+          out << chunk
+          line_count += chunk.lines.count
         end
+
+        [out, truncated]
       end
 
       #: (Pathname path) -> Array[Pathname]

data/lib/tapioca/commands/abstract_gem.rb

@@ -71,6 +71,7 @@ module Tapioca
         @include_doc = include_doc #: bool
         @include_loc = include_loc #: bool
         @include_exported_rbis = include_exported_rbis
+        @skipped_gems = [] #: Array[String]
         @halt_upon_load_error = halt_upon_load_error
       end
 

data/lib/tapioca/commands/annotations.rb

@@ -187,7 +187,7 @@ module Tapioca
           say_http_error(path, repo_uri, message: response.class)
           nil
         end
-      rescue SocketError, Errno::ECONNREFUSED => e
+      rescue => e
         say_http_error(path, repo_uri, message: e.message)
         nil
       end

data/lib/tapioca/commands/gem_generate.rb

@@ -30,6 +30,18 @@ module Tapioca
           end
         end
 
+        unless @skipped_gems.empty?
+          say("\nNote: Tapioca skipped RBI generation for the following gems because they are ignored by default:", [:yellow, :bold])
+          say(@skipped_gems.join(", "), [:yellow, :bold])
+        end
+
+        user_excluded_gems = @gem_names & @exclude
+
+        unless user_excluded_gems.empty?
+          say("\nNote: Tapioca skipped RBI generation for the following gems because they were excluded:", [:yellow, :bold])
+          say(user_excluded_gems.join(", "), [:yellow, :bold])
+        end
+
         if anything_done
           validate_rbi_files(
             command: default_command(:gem, @gem_names.join(" ")),
@@ -56,11 +68,15 @@ module Tapioca
           gem = @bundle.gem(gem_name)
 
           if gem.nil?
-            next if @lsp_addon
-
-            raise Tapioca::Error, set_color("Error: Cannot find gem '#{gem_name}'", :red)
+            if @lsp_addon
+              next
+            elsif Gemfile::GemSpec::IGNORED_GEMS.include?(gem_name)
+              @skipped_gems << gem_name
+              next
+            else
+              raise Tapioca::Error, set_color("Error: Cannot find gem '#{gem_name}'", :red)
+            end
           end
-
           gems.concat(gem_dependencies(gem)) if @include_dependencies
           gems << gem
         end

data/lib/tapioca/dsl/compiler.rb

@@ -74,9 +74,21 @@ module Tapioca
           @all_modules ||= if @@requested_constants.any?
             @@requested_constants.grep(Module)
           else
-            ObjectSpace.each_object(Module).to_a
+            ObjectSpace.each_object(Module).reject { |mod| deprecated_constant_proxy?(mod) }.to_a
           end.freeze #: Enumerable[Module[top]]?
         end
+
+        # Rails 8.1+ wraps deprecated constants in DeprecatedConstantProxy, which
+        # undefines most instance methods and warns from method_missing. Inspecting
+        # those modules during DSL discovery (is_a?, singleton_class, etc.) emits
+        # deprecation warnings even though Tapioca is only enumerating ObjectSpace.
+        # class_of uses Kernel#class so we can recognize the proxy without warning.
+        #: (Module[top] mod) -> bool
+        def deprecated_constant_proxy?(mod)
+          proxy_class_name = name_of(class_of(mod))
+          proxy_class_name == "ActiveSupport::Deprecation::DeprecatedConstantProxy" ||
+            proxy_class_name == "ActiveSupport::DeprecatedConstantProxy"
+        end
       end
 
       #: (
@@ -163,25 +175,27 @@ module Tapioca
         parameters.each_with_index.map do |(type, name), index|
           fallback_arg_name = "_arg#{index}"
 
-          name = name ? name.to_s : fallback_arg_name
-          name = fallback_arg_name unless valid_parameter_name?(name)
+          sig_name = name ? name.to_s : fallback_arg_name
+          is_anonymous_parameter = anonymous_parameter_name?(type, sig_name)
+          sig_name = fallback_arg_name unless is_anonymous_parameter || valid_parameter_name?(sig_name)
+          param_name = is_anonymous_parameter ? nil : sig_name
           method_type = T.must(method_types[index])
 
           case type
           when :req
-            create_param(name, type: method_type)
+            create_param(sig_name, type: method_type)
           when :opt
-            create_opt_param(name, type: method_type, default: "T.unsafe(nil)")
+            create_opt_param(sig_name, type: method_type, default: "T.unsafe(nil)")
           when :rest
-            create_rest_param(name, type: method_type)
+            create_rest_param(param_name, type: method_type)
           when :keyreq
-            create_kw_param(name, type: method_type)
+            create_kw_param(sig_name, type: method_type)
           when :key
-            create_kw_opt_param(name, type: method_type, default: "T.unsafe(nil)")
+            create_kw_opt_param(sig_name, type: method_type, default: "T.unsafe(nil)")
           when :keyrest
-            create_kw_rest_param(name, type: method_type)
+            create_kw_rest_param(param_name, type: method_type)
           when :block
-            create_block_param(name, type: method_type)
+            create_block_param(param_name, type: method_type)
           else
             raise "Unknown type `#{type}`."
           end

data/lib/tapioca/dsl/compilers/aasm.rb

@@ -10,18 +10,20 @@ module Tapioca
       # This gem dynamically defines constants and methods at runtime. For
       # example, given a class:
       #
-      #   class MyClass
-      #     include AASM
+      # ~~~rb
+      # class MyClass
+      #   include AASM
       #
-      #     aasm do
-      #       state :sleeping, initial: true
-      #       state :running, :cleaning
+      #   aasm do
+      #     state :sleeping, initial: true
+      #     state :running, :cleaning
       #
-      #       event :run do
-      #         transitions from: :sleeping, to: :running
-      #       end
+      #     event :run do
+      #       transitions from: :sleeping, to: :running
       #     end
       #   end
+      # end
+      # ~~~
       #
       # This will result in the following constants being defined:
       #
@@ -94,14 +96,19 @@ module Tapioca
                 create_rest_param("opts", type: "T.untyped"),
                 create_block_param("block", type: "T.nilable(T.proc.void)"),
               ]
+              aasm_6_or_newer = ::Gem::Requirement.new(">= 6").satisfied_by?(::Gem::Version.new(::AASM::VERSION))
+
               state_machine.events.each do |event|
-                model.create_method(event.name.to_s, parameters: parameters)
-                model.create_method("#{event.name}!", parameters: parameters)
-                model.create_method("#{event.name}_without_validation!", parameters: parameters)
-                model.create_method("may_#{event.name}?", return_type: "T::Boolean")
+                # As of aasm 6.0 a namespaced state machine defines only the
+                # namespaced event methods (e.g. `run_foo!`) and not the plain
+                # methods (`run!`) as aliases.
+                unless namespace && aasm_6_or_newer
+                  model.create_method(event.name.to_s, parameters: parameters)
+                  model.create_method("#{event.name}!", parameters: parameters)
+                  model.create_method("#{event.name}_without_validation!", parameters: parameters)
+                  model.create_method("may_#{event.name}?", return_type: "T::Boolean")
+                end
 
-                # For events, if there's a namespace the default methods are created in addition to
-                # namespaced ones.
                 next unless namespace
 
                 name = "#{event.name}_#{namespace}"
@@ -110,9 +117,9 @@ module Tapioca
                 model.create_method("#{name}!", parameters: parameters)
                 model.create_method("may_#{name}?", return_type: "T::Boolean")
 
-                # There's no namespaced method created for `_without_validation`, so skip
-                # defining a method for:
-                #   "#{name}_without_validation!"
+                # aasm < 6 does not define a namespaced `_without_validation!`
+                # method.
+                model.create_method("#{name}_without_validation!", parameters: parameters) if aasm_6_or_newer
               end
             end
 

data/lib/tapioca/dsl/compilers/active_job.rb

@@ -43,7 +43,7 @@ module Tapioca
         # @override
         #: -> void
         def decorate
-          return unless constant.instance_methods(false).include?(:perform)
+          return unless constant.method_defined?(:perform, false)
 
           root.create_path(constant) do |job|
             method = constant.instance_method(:perform)

data/lib/tapioca/dsl/compilers/active_model_attributes.rb

@@ -67,7 +67,7 @@ module Tapioca
 
         private
 
-        HANDLED_METHOD_TARGETS = ["attribute", "attribute="] #: Array[String]
+        HANDLED_METHOD_TARGETS = ["attribute", "attribute="].freeze #: Array[String]
 
         #: -> Array[[::String, ::String]]
         def attribute_methods_for_constant