type_toolkit 0.0.5 → 0.0.7

data/docs/design/inherited_implementation_problem.md

@@ -0,0 +1,258 @@
+# The inherited implementation problem
+
+Take this example:
+
+```ruby
+class Parent
+  def m = "Parent#m"
+end
+
+module I
+  interface!
+
+  abstract def m = raise "Abstract method `#m` not implemented"
+end
+
+class Child < Parent
+  include I
+end
+
+Child.new.m
+# => Vanilla Ruby:   raises (from `I#m`)
+# => With this gem: `Parent#m`
+```
+
+There are two challenges here:
+
+  1. We need to not let the `I#m` stub implementation "get in the way", so that we can find real implementation that get inherited from further ancestors (like `Parent#m`).
+  2. *but* we still want something to raise an error if you attempt to call an unimplemented abstract method.
+
+If you lookup `m` on an instance of `Child`, you would usually hit the empty stub `I#m` instead of the inherited implementation `Parent#m`:
+
+```ruby
+Child.ancestors
+
+# => [Child, Interface, Parent, Object, Kernel, BasicObject]
+#     ^      ^          ^
+#     |      |          Provides the implementation for Child to inherit
+#     |      Its stub abstract method "gets in the way" and needs to be side-stepped
+#     We want Child to inherit the implementation from Parent
+
+
+Child.instance_method(:m).owner
+# => Vanilla Ruby:  `I`
+# => With this gem: `Parent`
+```
+
+# Solution
+
+Solve the inheritance problem by just yoinking the abstract method stub out of the ancestor chain, by just using `remove_method()`.
+
+Now if you send `#m` to a child, there's no `I#m` implementation to hit, so it just jumps over to `Parent#m`. This is a direct method call with absolutely no runtime overhead.
+
+This introduces a new problem, that now calling unimplemented abstract methods just raises `NoMethodError`, as if the name never existed. For a better developer experience, we'd like to give a more helpful message.
+
+To do this, we implement `#method_missing` and check if the missing method name is one of the abstract methods (based on a list we append to every time you call `abstract`). If it is, we can raise our nicer error, otherwise we just delegate up the rest of the `#method_missing` chain (ultimately triggering a `NoMethodError`, like normal). This part isn't strictly necessary, but it's a nice-to-have. We can make it configurable.
+
+Syntax:
+
+```ruby
+module I
+  interface!
+
+  abstract def m; end
+end
+```
+
+That's it. That simple!
+
+Pros:
+  - Good DX when calling an abstract method that you forgot to implement
+  - Really nice syntax
+
+Cons:
+  - Some implementation complexity (but all tucked into this gem, with less than 130 lines of implementation code)
+  - Calls to implemented abstract methods are faster, at the expense of unimplemented ones
+    - 1.9x slower than the hand-written alternative
+    - 1.1x slower than sorbet-runtime alternative
+    - but that's totally acceptable, because this should never happen in a completed program. The performance of calls to actually implemented methods is what matters, since that's what the real code will be doing at a huge volume.
+
+# Alternative 1: Hand-written delegation
+
+You duplicate this delegation logic in every abstract method:
+
+```ruby
+module I
+  interface!
+
+  # @abstract
+  def m = defined?(super) ? super : raise("Abstract method `#m` not implemented")
+end
+```
+
+Pros:
+  - There's no magic, no runtime needed.
+
+Cons:
+  - Repetitive
+  - Can be forgotten
+  - There's more overhead on every method call (but only to abstract methods with an inherited implementation):
+    - Checking `defined?(super)`
+    - Making the `super` call
+  - It adds an extra frame to your backtrace which will be seen in debuggers and exception backtraces (unless you configure them to filter it out)
+
+
+# Alternative 2: Sorbet runtime's solution
+
+Here's a Sorbet version of the example: [Sorbet.run](https://sorbet.run/#%23%20typed%3A%20true%0A%0Aclass%20Parent%0A%20%20extend%20T%3A%3ASig%0A%0A%20%20sig%20%7B%20returns%28String%29%20%7D%0A%20%20def%20m%20%3D%20%22Parent%23m%22%0Aend%0A%20%20%0Amodule%20I%0A%20%20extend%20T%3A%3ASig%0A%20%20extend%20T%3A%3AHelpers%0A%0A%20%20interface!%0A%0A%20%20sig%20%7B%20abstract.returns%28String%29%20%7D%0A%20%20def%20m%3B%20end%0Aend%0A%0Aclass%20Child%20%3C%20Parent%3B%20end).
+
+Sorbet runtime basically automates the hand-written solution above, by wrapping abstract methods:
+
+https://github.com/sorbet/sorbet/blob/703498a0dcddbe7ec4b87ec6cc5d7d55cfa9b270/gems/sorbet-runtime/lib/types/private/methods/call_validation.rb#L48-L68
+
+Pros:
+  - "just works"
+
+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/docs/design/self_dot_methods.md

@@ -0,0 +1,79 @@
+# The `def self.` problem
+
+Ruby method definitions evaluate to the name of the method that was defined. This fact is used by the `public`/`protected`/`private` methods:
+
+```ruby
+class
+  puts def demo; end
+  # Equivalent to `puts(:demo)`
+end
+```
+
+However, there's no way to distinguish whether the method was an instance method, or a singleton method:
+
+```ruby
+class C
+  puts def      demo; end # prints ":demo"
+  puts def self.demo; end # *also* prints ":demo"
+end
+```
+
+# Solution
+
+Track into whether the last method call was an instance method or a singleton method, by hooking into `method_added` and `singleton_method_added`. See the `MethodDefRecorder` for details.
+
+This way, both of these "just work"
+
+```rb
+class C
+  # Correctly defines an abstract instance method
+  abstract def      demo; end
+
+  # Correctly defines an abstract "class method"
+  abstract def self.demo; end
+end
+```
+
+# Alternative 1: Do nothing
+
+This is already a problem for access level modifiers, which don't do anything to handle it:
+
+```ruby
+class C
+  private def self.demo; end
+  # => ❌ undefined method 'demo' for class 'C' (NameError)
+end
+```
+
+We can just follow suit. However, there's a risk that if an instance method called `demo` _actually_ existed, we inadvertently make it abstract without intending. Again, the access level modifier methods already have this issue, but it's a sharp edge that we don't need to have.
+
+If we choose to do nothing, we could encourage users to enable the [`Style/ClassMethodsDefinitions`](https://docs.rubocop.org/rubocop/cops_style.html#styleclassmethodsdefinitions) on the `EnforcedStyle: self_class` mode, so that their code bases don't contain `def self.foo` methods at all.
+
+Pros:
+  - Simpler implementation (none!)
+
+Cons:
+  - Sharp edge
+  - More complex mental model for users of RBS
+
+# Alternative 2: separate macro
+
+E.g.
+
+```rb
+class C
+  # Correctly defines an abstract instance method
+  abstract_instance_method def demo; end
+
+  # Correctly defines an abstract "class method"
+  abstract_class_method def self.demo; end
+end
+```
+
+Pros:
+  - Simple implementation
+
+Cons:
+  - Correct usage can't be enforced at runtime.
+    - Rubocop cop could enforce it, but that would need to be written
+  - Still a sharp edge, has the same cognitive complexity as alternative 1.

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

@@ -13,7 +13,7 @@ module RuboCop
             name: "rubocop-type_toolkit",
             version: ::TypeToolkit::VERSION,
             homepage: "https://github.com/Shopify/type_toolkit",
-            description: "Detects misuse of UnexpectedNilError.",
+            description: "RuboCop rules for Type Toolkit.",
           )
         end
 

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

@@ -0,0 +1,150 @@
+# typed: true
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module TypeToolkit
+      # 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.%<method>s()`."
+        RESTRICT_ON_SEND = [:must, :must_because].freeze
+
+        COMMA_BYTE = ",".ord
+        private_constant :COMMA_BYTE
+
+        KEYWORD_EXPRESSION_TYPES = [:defined?, :super, :yield, :zsuper].freeze
+        private_constant :KEYWORD_EXPRESSION_TYPES
+
+        #: (RuboCop::AST::SendNode) -> void
+        def on_send(node)
+          return unless (argument = extract_assertion_argument(node))
+
+          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(target, message:) do |corrector|
+              corrector.replace(target, correction)
+            end
+          end
+        end
+
+        private
+
+        #: (RuboCop::AST::SendNode) -> RuboCop::AST::Node?
+        def extract_assertion_argument(node)
+          receiver = node.receiver
+          return unless receiver.is_a?(RuboCop::AST::ConstNode)
+          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?
+
+          argument = node.first_argument
+          return unless argument
+          return if argument.splat_type? || argument.kwsplat_type?
+
+          argument
+        end
+
+        #: (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? && 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
+          comma_offset = argument.source_range.end_pos - grouped_range.begin_pos
+          grouped_source.slice!(comma_offset) if grouped_source.getbyte(comma_offset) == COMMA_BYTE
+          "#{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_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
+        def requires_parentheses?(argument)
+          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?
+
+          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
+end

data/lib/rubocop-type_toolkit.rb

@@ -3,3 +3,4 @@
 require "rubocop"
 require_relative "rubocop/cop/type_toolkit/plugin"
 require_relative "rubocop/cop/type_toolkit/dont_expect_unexpected_nil"
+require_relative "rubocop/cop/type_toolkit/prefer_not_nil"

data/lib/type_toolkit/abstract_method_receiver.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+
+module TypeToolkit
+  # Raised when a call is made to an abstract method that never had a real implementation.
+  class AbstractMethodNotImplementedError < Exception # rubocop:disable Lint/InheritException
+    def initialize(method_name:)
+      # Do not rely on this message content! Its content is subject to change.
+      super("Abstract method `##{method_name}` was never implemented.")
+    end
+  end
+
+  # This module is included on a class whose instances can be receivers of calls to abstract methods.
+  #
+  # Since abstract methods are removed at runtime (see `TypeToolkit::DSL#abstract`), attempting to call
+  # an unimplemented abstract method would usually raise a `NoMethodError`.
+  # This module uses `method_missing` to raise `AbstractMethodNotImplementedError` instead.
+  # @requires_ancestor: Kernel
+  module AbstractInstanceMethodReceiver
+    # This `#method_missing` is hit when calling a potentially abstract method on an instance
+    # E.g. TheClass.new.maybe_abstract_method
+    #
+    # (Symbol, ...) -> untyped
+    def method_missing(method_name, ...)
+      c = self.class #: as Class[top] & HasAbstractMethods
+
+      if c.abstract_method_declared?(method_name)
+        raise AbstractMethodNotImplementedError.new(method_name:)
+      end
+
+      super
+    end
+
+    #: (Symbol, ?bool) -> bool
+    def respond_to_missing?(method_name, include_private = false)
+      self.class.abstract_method_declared?(method_name) || super
+    end
+  end
+end

data/lib/type_toolkit/dsl.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+module TypeToolkit
+  # @requires_ancestor: MethodDefRecorder
+  module DSL
+    # Mark `method_name` as abstract.
+    #
+    # A real implementation of the method must be provided somewhere in the ancestor chain.
+    # Calls to an unimplemented abstract method will raise `AbstractMethodNotImplementedError`.
+    #
+    #: (Symbol) -> Symbol
+    def abstract(method_name)
+      #: self as (Module[top] & HasAbstractMethods & MethodDefRecorder)
+
+      recorded_method_name, is_singleton_method = __last_method_def
+
+      if recorded_method_name != method_name
+        prefix = is_singleton_method ? "." : "#"
+
+        # Do not rely on this message content! Its content is subject to change.
+        raise <<~MSG.chomp
+          `abstract` expected to see `#{prefix}#{method_name}`, but the last recorded method was called `#{recorded_method_name}`.
+          This can happen when `abstract` is combined with other metaprogramming.
+          If you think this is a bug, please open an issue: https://github.com/Shopify/type_toolkit/issues
+        MSG
+      end
+
+      # The `method_owner` is the class whose method table stores the abstract method.
+      #
+      # Example:
+      #
+      #   class Foo
+      #     # is_singleton_method = false, owner is the `Foo` class
+      #     abstract def foo; end
+      #
+      #     # is_singleton_method = true, owner is `Foo.singleton_class`
+      #     abstract def self.foo; end
+      #   end
+      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?`
+      method_owner.__register_abstract_method(method_name)
+
+      # We never want the empty "stub" method to be called, so we remove it. This has one of 3 effects:
+      #
+      # 1. If the abstract method is implemented by a subclass, then there's no effect.
+      #    The subclass' implementation will always be invoked, so this removal does nothing.
+      #
+      # 2. If the abstract method was already implemented by a superclass,
+      #    Then this removal ensures that calls to the method will resolve to
+      #    the superclass' implementation, and never the empty stub.
+      #
+      # 3. If the abstract method was not implemented anywhere in the ancestor chain,
+      #    then this removal ensures we hit `method_missing`, which will then raise
+      #    the `AbstractMethodNotImplementedError`.
+      method_owner.remove_method(method_name)
+
+      # Return the method name, so `abstract` can be chained, e.g. `private abstract def foo; end`
+      method_name
+    end
+  end
+end

data/lib/type_toolkit/ext/method.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "type_toolkit/method_patch"
+
+class Method
+  prepend TypeToolkit::MethodPatch
+end
+
+class UnboundMethod
+  prepend TypeToolkit::MethodPatch
+end

data/lib/type_toolkit/ext/module.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Module
+  def interface!
+    TypeToolkit.make_interface!(self)
+  end
+end

data/lib/type_toolkit/ext/nil_assertions.rb

@@ -27,7 +27,9 @@ module TypeToolkit
   #
   # `UnexpectedNilError` should never occur in well-formed code, so it should never be rescued.
   # This is why it inherits from `Exception` instead of `StandardError`,
-  # so that bare rescues clauses (like `rescue => e`) don't rescue it.
+  # so that bare rescue clauses (like `rescue => e`) don't accidentally swallow it.
+  #
+  # Note: `rescue Exception` can still catch it, but that's intentionally harder to write accidentally.
   class UnexpectedNilError < Exception # rubocop:disable Lint/InheritException
     def initialize(message = "Called `not_nil!` on nil.")
       super