type_toolkit 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4227c717f707bc4d21aea4b6026e4ec48c62bf48044518b7545b4a12d499662
-  data.tar.gz: afbee5d26bf77e402c0425dc60cfb53b6d8c80ba8af6f69af39bad034459a3bc
+  metadata.gz: 12374ec2c61c2218bb47b3e2f79d1d7c9bf59a7f4d75d2c429ebeecb02d4d51d
+  data.tar.gz: 13ef655859f7305f5ce532d6f9a3ac53513f2fcc8935d1b1c1f85b07c5f9e5d9
 SHA512:
-  metadata.gz: a251f77a0cc924ae2b621f1eda192d24d862406f076c875227ada2f7d16883a8c98e8c8b7310843a00a7d08b2fcab902e0f7bf6bcc5c4262da519a2e7a2721d8
-  data.tar.gz: a93074b2e21d1ea1b7dac91b9cf8e52690f68d1a2ae12e2c898cbd87b3ea71367a4d956d13933faef666e6683d868e7360a5b66a2039c8ccd735bdeefa82ae09
+  metadata.gz: 1ef3a56d5b8838ffcd97adf208f2ce67598dfa6157414ba084a91e146d43669ab1b06810659c9b3226ad5cd80f2ac875f937301238f45ba68d918ddabd177fd4
+  data.tar.gz: df81fdc2a72a0146a244a9a1028c227d789db201d3e1f66300a1cb4ccc9caf5345b27474dac8fe858a6f5753ae20bae184380a4837afd1c45da8a9ec4de1f6cf

data/.github/workflows/ci.yml

@@ -19,12 +19,8 @@ jobs:
           rubygems: 4.0.4
       - name: Run type check
         run: bundle exec rake typecheck
-      - name: Run type check with Prism parser
-        run: bundle exec rake typecheck_prism
-        continue-on-error: true
       - name: Run tests
         run: bundle exec rake test
-        continue-on-error: true
       - name: Lint Ruby files
         run: bundle exec rake rubocop
       - name: Verify gem RBIs are up-to-date

data/README.md

@@ -70,6 +70,24 @@ last_delivery = user.not_nil!
   .deliveries.last.not_nil!
 ```
 
+The `TypeToolkit/PreferNotNil` RuboCop cop autocorrects `T.must` and `T.must_because` to `.not_nil!`.
+For `T.must_because`, the reason block's source is preserved as comments inside a parenthesized expression,
+so the correction also works in chained calls and nested expressions:
+
+```rb
+# Before
+value = T.must_because(foo) { "Proven non-nil by validation." }
+
+# After
+value = (
+  # Proven non-nil by validation.
+  foo.not_nil!
+)
+```
+
+The reason is documentation only after correction: it is no longer evaluated or included in the exception message.
+Calls with heredocs in the value or reason block are reported but not autocorrected, because heredoc bodies can extend beyond the block's source range.
+
 ### Interfaces
 
 Interfaces are modules with abstract methods which a conforming class must implement. They help make duck-typing easier to use in Ruby, by validating that your conforming classes do actually provide the correct methods needed of them.

data/Rakefile

@@ -14,13 +14,6 @@ desc "alias for typecheck"; task tc: :typecheck
 desc "alias for typecheck"; task srb: :typecheck
 desc "alias for typecheck"; task sorbet: :typecheck
 
-desc "Type-check the code base with Sorbet using Prism"
-task :typecheck_prism do
-  sh "bundle exec srb tc --parser=prism" do |ok, _res|
-    abort unless ok
-  end
-end
-
 require "minitest/test_task"
 
 Minitest::TestTask.create do |t|

data/config/default.yml

@@ -4,6 +4,6 @@ TypeToolkit/DontExpectUnexpectedNil:
   VersionAdded: "0.1.0"
 
 TypeToolkit/PreferNotNil:
-  Description: "Replaces T.must assertions with Type Toolkit's not_nil! assertion."
+  Description: "Replaces T.must and T.must_because assertions with Type Toolkit's not_nil! assertion."
   Enabled: true
   VersionAdded: "0.1.0"

data/docs/design/inherited_implementation_problem.md

@@ -6,7 +6,7 @@ Take this example:
 class Parent
   def m = "Parent#m"
 end
-  
+
 module I
   interface!
 
@@ -17,7 +17,7 @@ class Child < Parent
   include I
 end
 
-Child.new.m 
+Child.new.m
 # => Vanilla Ruby:   raises (from `I#m`)
 # => With this gem: `Parent#m`
 ```
@@ -117,3 +117,142 @@ Cons:
   - All the downsides of doing this the hand-written way.
   - To determine if a method is abstract or not, every `sig` needs to have its block evaluated, to see if it calls `abstract`.
   - This used to be slower because it was defined via `defined_methods` with a block body. This produces a slower kind of method (`VM_METHOD_TYPE_BMETHOD`), than the equivalent code via `def` (`VM_METHOD_TYPE_ISEQ`). This was fixed in [this PR](https://github.com/sorbet/sorbet/pull/8238), which switch to using `module_eval` to define the method via `def`.
+
+# Other languages
+
+Most languages with abstract methods are ahead-of-time compiled. They don't have this issue because their compilers eagerly catch issues. Don't have the issue of runtime stub methods clobbering access to inherited implementation.
+
+Python and Elixir are usual comparison points, as interpreted languages with growing static typing features.
+
+## Python
+
+Python has both [Abstract Base Classes](https://typing.python.org/en/latest/guides/libraries.html#abstract-classes-and-methods) and [Protocols](https://typing.python.org/en/latest/spec/protocol.html), and the two work differently.
+
+Abstract classes don't have the inherited implementation problem, because they eagerly defend against instantiating a class with any unimplemented abstract methods. If you circumvent this defence, you just hit the `NotImplementedError` rather than an inherited implementation of the method.
+
+```python
+#!/usr/bin/env python3
+
+from abc import ABC, abstractmethod
+
+class Parent:
+  def m(self) -> str:
+    return "Parent.m"
+
+class I(ABC):
+  @abstractmethod
+  def m(self) -> str:
+    """Subclasses must override"""
+    raise NotImplementedError()
+
+class Child(I, Parent):
+  pass
+
+# print(Child.mro()) # Equivalent to Ruby's ancestor chain
+
+try:
+  Child() # Can't instantiate abstract class Child without an implementation for abstract method 'm'
+except TypeError as e:
+  print(e)
+  pass
+
+# Force the instantiation anyway
+Child.__abstractmethods__ = frozenset()
+Child().m() # => NotImplementedError
+```
+
+[Implicitly implementing a Protocol](https://typing.python.org/en/latest/spec/protocol.html#protocols:~:text=The%20default%20implementations%20cannot%20be%20used%20if%20the%20assignable%2Dto%20relationship%20is%20implicit%20and%20only%20structural%20%E2%80%93%20the%20semantics%20of%20inheritance%20is%20not%20changed%2E) doesn't have the problem, because the Protocol is not made part of the MRO (equivalent to Ruby's ancestor chain):
+
+```python
+#!/usr/bin/env python3
+
+from typing import Protocol
+from abc import abstractmethod
+
+class Parent:
+  def m(self) -> str:
+    return "Parent.m"
+
+class MyProtocol(Protocol):
+  @abstractmethod
+  def m(self) -> str:
+    raise NotImplementedError
+
+class ImplicitChild(Parent): # <- MyProtocol not in this list
+  pass
+
+# Equivalent to Ruby's ancestor chain. `MyProtocol` is not in it.
+print(ImplicitChild.mro()) # => [<class 'ImplicitChild'>, <class 'Parent'>, <class 'object'>]
+
+# Calls the inherited implementation, no problem:
+print(ImplicitChild().m()) # => "Parent.m"
+```
+
+However, the moment you make the Protocol implementation explicit, you get the same problem as the Abstract Base Class case:
+
+```python
+# ... continued from previous script
+
+class ExplicitChild(MyProtocol, Parent):
+  pass
+
+# Equivalent to Ruby's ancestor chain. `MyProtocol` is in it.
+print(ExplicitChild.mro()) # => [<class 'ExplicitChild'>, <class 'MyProtocol'>, <class 'typing.Protocol'>, <class 'typing.Generic'>, <class 'Parent'>, <class 'object'>]
+
+try:
+  ExplicitChild() # Can't instantiate abstract class Child without an implementation for abstract method 'm'
+except TypeError as e:
+  print(e)
+  pass
+
+# Force the instantiation anyway
+ExplicitChild.__abstractmethods__ = frozenset()
+ExplicitChild().m() # => NotImplementedError
+```
+
+The [docs](https://typing.python.org/en/latest/spec/protocol.html#protocols:~:text=defined-,A,instantiated) are explicit about this:
+
+> A class can explicitly inherit from multiple protocols and also from normal classes. In this case methods are resolved using normal MRO and a type checker verifies that all member assignability is correct. The semantics of `@abstractmethod` is not changed; all of them must be implemented by an explicit subclass before it can be instantiated.
+
+## Elixir
+
+Elixir doesn't have class-style inheritance. It's still interesting to see how it handles its equivalent to abstract methods: protocol functions.
+When statically compiled, `elixirc` statically catches unimplemented methods and fails the build.
+
+When dynamically executed (e.g. `iex`, `elixir`) will raise warnings for unimplemented methods. It records extra runtime metadata, used to surface more concrete error messages.
+
+```elixir
+#!/usr/bin/env elixir
+
+defprotocol Size do
+  def size(value)
+  def empty?(value)
+end
+
+# Protocol requirements are reified at runtime, can be reflected:
+IO.inspect Size.__protocol__(:functions) # [empty?: 1, size: 1]
+
+defimpl Size, for: List do
+  def size(value), do: length(value)
+
+  # Intentionally missing `def empty?`, Elixir warns:
+  # > warning: function empty?/1 required by protocol Size is not implemented
+end
+
+# Calling an implemented function
+IO.inspect Size.size([]) # => 0
+
+try do
+  Size.empty?([]) # Calling an unimplemented function
+rescue
+  e in UndefinedFunctionError ->
+    # Replicates what e.g. `iex` would print.
+    {blame, _} = Exception.blame(:error, e, __STACKTRACE__)
+    IO.puts "(UndefinedFunctionError) #{blame.message}"
+    # => (UndefinedFunctionError) function Size.List.empty?/1 is undefined or private, but the behaviour Size expects it to be present
+end
+
+# Not how it knows that the `Size` behaviour expects it.
+# Compare with the more generic error raised otherwise:
+Size.foo # => (UndefinedFunctionError) function Size.foo/0 is undefined or private
+```

data/lib/rubocop/cop/type_toolkit/prefer_not_nil.rb

@@ -4,12 +4,12 @@
 module RuboCop
   module Cop
     module TypeToolkit
-      # Replaces Sorbet's `T.must(value)` assertion with Type Toolkit's `value.not_nil!` assertion.
+      # Replaces Sorbet's `T.must` and `T.must_because` assertions with `.not_nil!`.
       class PreferNotNil < Base
         extend AutoCorrector
 
-        MSG = "Use `.not_nil!` instead of `T.must()`."
-        RESTRICT_ON_SEND = [:must].freeze
+        MSG = "Use `.not_nil!` instead of `T.%<method>s()`."
+        RESTRICT_ON_SEND = [:must, :must_because].freeze
 
         COMMA_BYTE = ",".ord
         private_constant :COMMA_BYTE
@@ -19,16 +19,21 @@ module RuboCop
 
         #: (RuboCop::AST::SendNode) -> void
         def on_send(node)
-          return unless (argument = extract_t_must_argument(node))
+          return unless (argument = extract_assertion_argument(node))
 
-          if nested_t_must?(node)
-            add_offense(node, message: MSG)
+          block = node.block_node if node.method?(:must_because)
+          target = block || node
+          message = format(MSG, method: node.method_name)
+
+          if nested_assertion?(node) || (block && contains_heredoc?(block))
+            add_offense(target, message:)
           else
             replacement = replacement_for(argument)
             correction = correction_for(node, argument, replacement)
+            correction = commented_correction(block, correction) if block
 
-            add_offense(node, message: MSG) do |corrector|
-              corrector.replace(node, correction)
+            add_offense(target, message:) do |corrector|
+              corrector.replace(target, correction)
             end
           end
         end
@@ -36,10 +41,10 @@ module RuboCop
         private
 
         #: (RuboCop::AST::SendNode) -> RuboCop::AST::Node?
-        def extract_t_must_argument(node)
+        def extract_assertion_argument(node)
           receiver = node.receiver
           return unless receiver.is_a?(RuboCop::AST::ConstNode)
-          return unless receiver.short_name == :T && node.method?(:must) && node.arguments.one?
+          return unless receiver.short_name == :T && RESTRICT_ON_SEND.include?(node.method_name) && node.arguments.one?
 
           namespace = receiver.namespace
           return unless namespace.nil? || namespace.cbase_type?
@@ -54,13 +59,16 @@ module RuboCop
         #: (RuboCop::AST::Node) -> String
         def replacement_for(argument)
           source = argument.source
+
           source = "(#{source})" if requires_parentheses?(argument)
+
           "#{source}.not_nil!"
         end
 
         #: (RuboCop::AST::SendNode, RuboCop::AST::Node, String) -> String
         def correction_for(node, argument, replacement)
-          return replacement unless node.multiline?
+          return replacement unless node.multiline? && node.parenthesized_call?
+          return replacement unless comments_inside_parentheses?(node) || contains_heredoc?(argument)
 
           grouped_range = node.source_range.with(begin_pos: node.loc.begin.begin_pos, end_pos: node.loc.end.end_pos)
           grouped_source = grouped_range.source
@@ -69,11 +77,51 @@ module RuboCop
           "#{grouped_source}.not_nil!"
         end
 
+        #: (RuboCop::AST::Node) -> bool
+        def contains_heredoc?(node)
+          return true if node.loc.is_a?(Parser::Source::Map::Heredoc)
+
+          node.each_descendant(:any_str).any? do |descendant|
+            descendant.loc.is_a?(Parser::Source::Map::Heredoc)
+          end
+        end
+
+        #: (RuboCop::AST::SendNode) -> bool
+        def comments_inside_parentheses?(node)
+          contents_begin = node.loc.begin.end_pos
+          contents_end = node.loc.end.begin_pos
+
+          processed_source.comments.any? do |comment|
+            comment_range = comment.loc.expression
+            contents_begin <= comment_range.begin_pos && comment_range.end_pos <= contents_end
+          end
+        end
+
         #: (RuboCop::AST::SendNode) -> bool
-        def nested_t_must?(node)
-          node.each_ancestor(:send).any? do |ancestor|
-            ancestor.is_a?(RuboCop::AST::SendNode) && extract_t_must_argument(ancestor)
+        def nested_assertion?(node)
+          node.each_ancestor(:send, :block, :numblock, :itblock).any? do |ancestor|
+            send_node = ancestor.is_a?(RuboCop::AST::SendNode) ? ancestor : ancestor.send_node
+            !send_node.equal?(node) && send_node.is_a?(RuboCop::AST::SendNode) && extract_assertion_argument(send_node)
+          end
+        end
+
+        #: (RuboCop::AST::BlockNode, String) -> String
+        def commented_correction(block, correction)
+          indentation = block.source_range.source_line[/\A\s*/]
+          reason_range = block.source_range.with(
+            begin_pos: block.loc.begin.end_pos,
+            end_pos: block.loc.end.begin_pos,
+          )
+          reason = reason_range.source
+          body = block.body
+          if body && (body.str_type? || body.dstr_type?) && ["\"", "'"].include?(body.loc.begin&.source)
+            reason.slice!(body.loc.end.begin_pos - reason_range.begin_pos)
+            reason.slice!(body.loc.begin.begin_pos - reason_range.begin_pos)
           end
+          comments = reason.strip.lines.map { |line| "#{indentation}  # #{line.strip}\n" }.join
+          return "(\n#{comments}#{correction.delete_prefix("(\n")}" if correction.start_with?("(\n")
+
+          "(\n#{comments}#{indentation}  #{correction}\n#{indentation})"
         end
 
         #: (RuboCop::AST::Node) -> bool
@@ -81,15 +129,21 @@ module RuboCop
           return false if argument.begin_type?
 
           if argument.is_a?(RuboCop::AST::SendNode)
+            return bracket_call_requires_parentheses?(argument) if argument.method?(:[])
             return true if argument.operator_method?
             return true if argument.arguments? && !argument.parenthesized_call?
           end
           return true if argument.range_type? || argument.operator_keyword?
           return true if argument.if_type? || argument.assignment?
-          return true if argument.any_block_type?
 
           KEYWORD_EXPRESSION_TYPES.include?(argument.type)
         end
+
+        # `foo[bar]` and `foo.[](bar)` can be chained directly, but command-style `foo.[] bar` cannot.
+        #: (RuboCop::AST::SendNode) -> bool
+        def bracket_call_requires_parentheses?(argument)
+          argument.dot? && !argument.parenthesized_call?
+        end
       end
     end
   end

data/lib/type_toolkit/dsl.rb

@@ -37,7 +37,9 @@ module TypeToolkit
       #     # is_singleton_method = true, owner is `Foo.singleton_class`
       #     abstract def self.foo; end
       #   end
-      method_owner = is_singleton_method ? singleton_class : self #: as Module[top] & HasAbstractMethods
+      method_owner = is_singleton_method ? raise(NotImplementedError, <<~MSG) : self
+        Abstract singleton methods are not supported yet.
+      MSG
 
       # Register the fact that this method is meant to be abstract,
       # used by APIs like `abstract_method_declared?` and `Method#abstract?`

data/lib/type_toolkit/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module TypeToolkit
-  VERSION = "0.0.6"
+  VERSION = "0.0.7"
 end

data/sorbet/rbi/shims/rubocop_minitest.rbi

@@ -4,14 +4,17 @@
 module RuboCop
   module Minitest
     module AssertOffense
-      sig { params(source: String).void }
-      def assert_offense(source); end
+      sig { params(source: String, file: T.nilable(String), replacements: String).void }
+      def assert_offense(source, file = nil, **replacements); end
 
       sig { params(source: String).void }
       def assert_no_offenses(source); end
 
       sig { params(source: String).void }
       def assert_correction(source); end
+
+      sig { void }
+      def assert_no_corrections; end
     end
   end
 end

data/spec/interface_spec.rb

@@ -401,5 +401,19 @@ module TypeToolkit
         end
       end
     end
+
+    describe "Abstract class methods" do
+      it "are not yet supported" do
+        test_context = self
+
+        Module.new do
+          interface!
+
+          test_context.assert_raises(NotImplementedError) do
+            abstract def self.abstract_class_method; end # rubocop:disable Style/ClassMethodsDefinitions
+          end
+        end
+      end
+    end
   end
 end

data/spec/misc/how_method_added_hooks_work_spec.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module TypeToolkit
+  module Misc
+    # This test just characterizes how `method_added` hooks work. It doesn't have anything to do with TypeToolkit itself,
+    # but it's useful for devs to confirm how this works across instance and class methods.
+    class HowMethodAddedHooksWorkSpec < Minitest::Spec
+      it "characterizes how method_added hooks work" do
+        test_context = self
+
+        Class.new do
+          class << self
+            attr_reader :__last_method_def
+
+            class << self
+              def __last_method_def
+                attached_object.__last_method_def
+              end
+            end
+
+            def method_added(m)
+              is_singleton_method = false
+              @__last_method_def = [m, is_singleton_method]
+
+              super
+            end
+
+            def singleton_method_added(m)
+              return super if m == :singleton_method_added
+
+              is_singleton_method = true
+              @__last_method_def = [m, is_singleton_method]
+
+              super
+            end
+          end
+
+          test_context.assert_nil __last_method_def
+
+          def instance_method; end
+
+          test_context.assert_equal [:instance_method, false], __last_method_def
+
+          def self.singleton_method_via_self_dot; end # rubocop:disable Style/ClassMethodsDefinitions
+
+          test_context.assert_equal [:singleton_method_via_self_dot, true], __last_method_def
+
+          r = class << self
+                def singleton_method_via_sclass; end
+
+                __last_method_def
+          end
+
+          test_context.assert_equal [:singleton_method_via_sclass, true], r
+
+          test_context.assert_equal [:singleton_method_via_sclass, true], __last_method_def
+        end
+      end
+    end
+  end
+end

data/spec/rubocop/cop/type_toolkit/prefer_not_nil_spec.rb

@@ -12,7 +12,8 @@ module RuboCop
       class PreferNotNilSpec < ::Minitest::Spec
         include RuboCop::Minitest::AssertOffense
 
-        MSG = "TypeToolkit/PreferNotNil: Use `.not_nil!` instead of `T.must()`."
+        MSG = "TypeToolkit/PreferNotNil: #{format(PreferNotNil::MSG, method: :must)}"
+        BECAUSE_MSG = "TypeToolkit/PreferNotNil: #{format(PreferNotNil::MSG, method: :must_because)}"
 
         before do
           @cop = PreferNotNil.new
@@ -77,6 +78,8 @@ module RuboCop
                          ^^^^^^^^^^^^^^^^^ #{MSG}
             block_value = T.must(foo { bar })
                           ^^^^^^^^^^^^^^^^^^^ #{MSG}
+            block_with_arguments = T.must(foo(arg) { |value| value })
+                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{MSG}
             defined_value = T.must(defined?(foo))
                             ^^^^^^^^^^^^^^^^^^^^^ #{MSG}
             def example
@@ -98,7 +101,8 @@ module RuboCop
             logical = (foo || bar).not_nil!
             grouped = (foo || bar).not_nil!
             assignment = (foo = bar).not_nil!
-            block_value = (foo { bar }).not_nil!
+            block_value = foo { bar }.not_nil!
+            block_with_arguments = foo(arg) { |value| value }.not_nil!
             defined_value = (defined?(foo)).not_nil!
             def example
               (yield foo).not_nil!
@@ -123,6 +127,19 @@ module RuboCop
           RUBY
         end
 
+        it "autocorrects multiline command calls" do
+          assert_offense(<<~RUBY)
+            T.must foo
+            ^^^^^^^^^^ #{MSG}
+              .bar
+          RUBY
+
+          assert_correction(<<~RUBY)
+            foo
+              .bar.not_nil!
+          RUBY
+        end
+
         it "does not add unnecessary parentheses to parenthesized calls" do
           assert_offense(<<~RUBY)
             value = T.must(fetch(value))
@@ -134,6 +151,51 @@ module RuboCop
           RUBY
         end
 
+        it "parenthesizes bracket method calls only when required" do
+          assert_offense(<<~RUBY)
+            bracketed = T.must(foo[bar]).foo
+                        ^^^^^^^^^^^^^^^^ #{MSG}
+            explicit = T.must(foo.[](bar)).foo
+                       ^^^^^^^^^^^^^^^^^^^ #{MSG}
+            command = T.must(foo.[] bar).foo
+                      ^^^^^^^^^^^^^^^^^^ #{MSG}
+          RUBY
+
+          assert_correction(<<~RUBY)
+            bracketed = foo[bar].not_nil!.foo
+            explicit = foo.[](bar).not_nil!.foo
+            command = (foo.[] bar).not_nil!.foo
+          RUBY
+        end
+
+        it "does not group an argument that makes the call multiline" do
+          assert_offense(<<~RUBY)
+            T.must(foo
+            ^^^^^^^^^^ #{MSG}
+              .bar)
+          RUBY
+
+          assert_correction(<<~RUBY)
+            foo
+              .bar.not_nil!
+          RUBY
+        end
+
+        it "preserves a multiline receiver without parentheses" do
+          assert_offense(<<~RUBY)
+            T.must(
+            ^^^^^^^ #{MSG}
+              foo.
+                bar
+            )
+          RUBY
+
+          assert_correction(<<~RUBY)
+            foo.
+                bar.not_nil!
+          RUBY
+        end
+
         it "preserves comments in multiline calls" do
           assert_offense(<<~RUBY)
             value = T.must(
@@ -151,7 +213,7 @@ module RuboCop
           RUBY
         end
 
-        it "autocorrects multiline calls with whitespace before the method" do
+        it "drops unnecessary grouping from multiline calls without comments" do
           assert_offense(<<~RUBY)
             first = T .must(
                     ^^^^^^^^ #{MSG}
@@ -165,12 +227,21 @@ module RuboCop
           RUBY
 
           assert_correction(<<~RUBY)
-            first = (
-              foo
-            ).not_nil!
-            second = (
-                bar
-              ).not_nil!
+            first = foo.not_nil!
+            second = bar.not_nil!
+          RUBY
+        end
+
+        it "preserves a multiline call chain without parentheses" do
+          assert_offense(<<~RUBY)
+            variant = T.must(
+                      ^^^^^^^ #{MSG}
+              InventoryItemVariant.preload(:variant).where(inventory_item_id: @inventory_item_id).first!.variant
+            )
+          RUBY
+
+          assert_correction(<<~RUBY)
+            variant = InventoryItemVariant.preload(:variant).where(inventory_item_id: @inventory_item_id).first!.variant.not_nil!
           RUBY
         end
 
@@ -189,6 +260,67 @@ module RuboCop
           RUBY
         end
 
+        it "preserves grouping around heredocs in multiline calls" do
+          assert_offense(<<~RUBY)
+            value = T.must(
+                    ^^^^^^^ #{MSG}
+              <<~TEXT
+                hello
+              TEXT
+            )
+          RUBY
+
+          assert_correction(<<~RUBY)
+            value = (
+              <<~TEXT
+                hello
+              TEXT
+            ).not_nil!
+          RUBY
+        end
+
+        it "preserves grouping around nested heredocs in multiline calls" do
+          assert_offense(<<~RUBY)
+            value = T.must(
+                    ^^^^^^^ #{MSG}
+              foo(<<~TEXT)
+                hello
+              TEXT
+            )
+          RUBY
+
+          assert_correction(<<~RUBY)
+            value = (
+              foo(<<~TEXT)
+                hello
+              TEXT
+            ).not_nil!
+          RUBY
+        end
+
+        it "preserves grouping around a heredoc T.must nested in another call" do
+          assert_offense(<<~RUBY)
+            value = foo(
+              T.must(
+              ^^^^^^^ #{MSG}
+                <<~TEXT
+                  hello
+                TEXT
+              )
+            )
+          RUBY
+
+          assert_correction(<<~RUBY)
+            value = foo(
+              (
+                <<~TEXT
+                  hello
+                TEXT
+              ).not_nil!
+            )
+          RUBY
+        end
+
         it "autocorrects nested T.must calls" do
           assert_offense(<<~RUBY)
             value = T.must(T.must(foo).bar)
@@ -214,6 +346,104 @@ module RuboCop
           RUBY
         end
 
+        it "reports heredoc reasons without leaving orphaned heredoc bodies" do
+          assert_offense(<<~RUBY)
+            value = T.must_because(foo) { <<~REASON }
+                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{BECAUSE_MSG}
+              Proven non-nil.
+            REASON
+          RUBY
+
+          assert_no_corrections
+        end
+
+        it "preserves the reason without attaching the block to the corrected call" do
+          assert_offense(<<~RUBY)
+            value = T.must_because(foo) { "reason" }.bar
+                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{BECAUSE_MSG}
+          RUBY
+
+          assert_correction(<<~RUBY)
+            value = (
+              # reason
+              foo.not_nil!
+            ).bar
+          RUBY
+        end
+
+        it "preserves multiline reasons and argument comments" do
+          assert_offense(<<~RUBY)
+            value = ::T.must_because(
+                    ^^^^^^^^^^^^^^^^^ #{BECAUSE_MSG}
+              # Validated earlier.
+              foo,
+            ) do
+              # Explain the invariant.
+              "validated for \#{user}"
+            end
+          RUBY
+
+          assert_correction(<<~RUBY)
+            value = (
+              # # Explain the invariant.
+              # validated for \#{user}
+              # Validated earlier.
+              foo
+            ).not_nil!
+          RUBY
+        end
+
+        it "keeps trailing arguments and string interpolation outside the reason comment" do
+          assert_offense(<<~'RUBY', message: BECAUSE_MSG)
+            values = [T.must_because(foo) { 'reason' }, bar]
+                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ %{message}
+            text = "#{T.must_because(foo) { "reason" }}"
+                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ %{message}
+          RUBY
+
+          assert_correction(<<~'RUBY')
+            values = [(
+              # reason
+              foo.not_nil!
+            ), bar]
+            text = "#{(
+              # reason
+              foo.not_nil!
+            )}"
+          RUBY
+        end
+
+        it "corrects mixed nested assertions without overlapping edits" do
+          assert_offense(<<~RUBY)
+            value = T.must(T.must_because(T.must(foo)) { "reason" })
+                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{MSG}
+                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{BECAUSE_MSG}
+                                          ^^^^^^^^^^^ #{MSG}
+          RUBY
+
+          assert_correction(<<~RUBY)
+            value = (
+              # reason
+              foo.not_nil!.not_nil!
+            ).not_nil!
+          RUBY
+        end
+
+        it "comments out assertions in the reason rather than correcting them" do
+          assert_offense(<<~RUBY)
+            value = T.must_because(foo) { T.must(bar) }
+                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #{BECAUSE_MSG}
+                                          ^^^^^^^^^^^ #{MSG}
+          RUBY
+
+          assert_correction(<<~RUBY)
+            value = (
+              # T.must(bar)
+              foo.not_nil!
+            )
+          RUBY
+        end
+
         it "ignores other receivers, methods, and argument counts" do
           assert_no_offenses(<<~RUBY)
             Other::T.must(foo)
@@ -221,6 +451,11 @@ module RuboCop
             T.let(foo, String)
             T.must(foo, bar)
             T.must(*values)
+            Other::T.must_because(foo) { "reason" }
+            object.must_because(foo) { "reason" }
+            T.must_because(foo, bar) { "reason" }
+            T.must_because(*values) { "reason" }
+            T.must_because(foo, &reason)
           RUBY
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: type_toolkit
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Alexander Momchilov
@@ -132,6 +132,7 @@ files:
 - sorbet/tapioca/require.rb
 - spec/.rubocop.yml
 - spec/interface_spec.rb
+- spec/misc/how_method_added_hooks_work_spec.rb
 - spec/nil_assertions_spec.rb
 - spec/rubocop/cop/type_toolkit/dont_expect_unexpected_nil_spec.rb
 - spec/rubocop/cop/type_toolkit/prefer_not_nil_spec.rb