tapioca 0.16.9 → 0.17.7

data/lib/tapioca/repo_index.rb

@@ -4,17 +4,15 @@
 module Tapioca
   class RepoIndex
     extend T::Sig
-    extend T::Generic
-
     class << self
       extend T::Sig
 
-      sig { params(json: String).returns(RepoIndex) }
+      #: (String json) -> RepoIndex
       def from_json(json)
         RepoIndex.from_hash(JSON.parse(json))
       end
 
-      sig { params(hash: T::Hash[String, T::Hash[T.untyped, T.untyped]]).returns(RepoIndex) }
+      #: (Hash[String, Hash[untyped, untyped]] hash) -> RepoIndex
       def from_hash(hash)
         hash.each_with_object(RepoIndex.new) do |(name, _), index|
           index << name
@@ -22,22 +20,22 @@ module Tapioca
       end
     end
 
-    sig { void }
+    #: -> void
     def initialize
-      @entries = T.let(Set.new, T::Set[String])
+      @entries = Set.new #: Set[String]
     end
 
-    sig { params(gem_name: String).void }
+    #: (String gem_name) -> void
     def <<(gem_name)
       @entries.add(gem_name)
     end
 
-    sig { returns(T::Enumerable[String]) }
+    #: -> T::Enumerable[String]
     def gems
       @entries.sort
     end
 
-    sig { params(gem_name: String).returns(T::Boolean) }
+    #: (String gem_name) -> bool
     def has_gem?(gem_name)
       @entries.include?(gem_name)
     end

data/lib/tapioca/runtime/attached_class_of_32.rb

@@ -10,7 +10,7 @@ module Tapioca
     module AttachedClassOf
       extend T::Sig
 
-      sig { params(singleton_class: Class).returns(T.nilable(Module)) }
+      #: (Class singleton_class) -> Module?
       def attached_class_of(singleton_class)
         result = singleton_class.attached_object
         Module === result ? result : nil

data/lib/tapioca/runtime/attached_class_of_legacy.rb

@@ -7,13 +7,10 @@ module Tapioca
     # older than 3.2. Because the Class#attached_object method is not
     # available, it implements finding the attached class of a singleton
     # class by iterating through ObjectSpace.
+    # @requires_ancestor: Tapioca::Runtime::Reflection
     module AttachedClassOf
       extend T::Sig
-      extend T::Helpers
-
-      requires_ancestor { Tapioca::Runtime::Reflection }
-
-      sig { params(singleton_class: Class).returns(T.nilable(Module)) }
+      #: (Class singleton_class) -> Module?
       def attached_class_of(singleton_class)
         # https://stackoverflow.com/a/36622320/98634
         result = ObjectSpace.each_object(singleton_class).find do |klass|

data/lib/tapioca/runtime/dynamic_mixin_compiler.rb

@@ -7,26 +7,26 @@ module Tapioca
       extend T::Sig
       include Runtime::Reflection
 
-      sig { returns(T::Array[Module]) }
+      #: Array[Module]
       attr_reader :dynamic_extends, :dynamic_includes
 
-      sig { returns(T::Array[Symbol]) }
+      #: Array[Symbol]
       attr_reader :class_attribute_readers, :class_attribute_writers, :class_attribute_predicates
 
-      sig { returns(T::Array[Symbol]) }
+      #: Array[Symbol]
       attr_reader :instance_attribute_readers, :instance_attribute_writers, :instance_attribute_predicates
 
-      sig { params(constant: Module).void }
+      #: (Module constant) -> void
       def initialize(constant)
         @constant = constant
         mixins_from_modules = {}.compare_by_identity
-        class_attribute_readers = T.let([], T::Array[Symbol])
-        class_attribute_writers = T.let([], T::Array[Symbol])
-        class_attribute_predicates = T.let([], T::Array[Symbol])
+        class_attribute_readers = [] #: Array[Symbol]
+        class_attribute_writers = [] #: Array[Symbol]
+        class_attribute_predicates = [] #: Array[Symbol]
 
-        instance_attribute_readers = T.let([], T::Array[Symbol])
-        instance_attribute_writers = T.let([], T::Array[Symbol])
-        instance_attribute_predicates = T.let([], T::Array[Symbol])
+        instance_attribute_readers = [] #: Array[Symbol]
+        instance_attribute_writers = [] #: Array[Symbol]
+        instance_attribute_predicates = [] #: Array[Symbol]
 
         Class.new do
           # Override the `self.include` method
@@ -112,28 +112,28 @@ module Tapioca
         # is the list of all dynamically extended modules because of that
         # constant. We grab that value by deleting the key for the original
         # constant.
-        @dynamic_extends = T.let(mixins_from_modules.delete(constant) || [], T::Array[Module])
+        @dynamic_extends = mixins_from_modules.delete(constant) || [] #: Array[Module]
 
         # Since we deleted the original constant from the list of keys, all
         # the keys that remain are the ones that are dynamically included modules
         # during the include of the original constant.
-        @dynamic_includes = T.let(mixins_from_modules.keys, T::Array[Module])
+        @dynamic_includes = mixins_from_modules.keys #: Array[Module]
 
-        @class_attribute_readers = T.let(class_attribute_readers, T::Array[Symbol])
-        @class_attribute_writers = T.let(class_attribute_writers, T::Array[Symbol])
-        @class_attribute_predicates = T.let(class_attribute_predicates, T::Array[Symbol])
+        @class_attribute_readers = class_attribute_readers #: Array[Symbol]
+        @class_attribute_writers = class_attribute_writers #: Array[Symbol]
+        @class_attribute_predicates = class_attribute_predicates #: Array[Symbol]
 
-        @instance_attribute_readers = T.let(instance_attribute_readers, T::Array[Symbol])
-        @instance_attribute_writers = T.let(instance_attribute_writers, T::Array[Symbol])
-        @instance_attribute_predicates = T.let(instance_attribute_predicates, T::Array[Symbol])
+        @instance_attribute_readers = instance_attribute_readers #: Array[Symbol]
+        @instance_attribute_writers = instance_attribute_writers #: Array[Symbol]
+        @instance_attribute_predicates = instance_attribute_predicates #: Array[Symbol]
       end
 
-      sig { returns(T::Boolean) }
+      #: -> bool
       def empty_attributes?
         @class_attribute_readers.empty? && @class_attribute_writers.empty?
       end
 
-      sig { params(tree: RBI::Tree).void }
+      #: (RBI::Tree tree) -> void
       def compile_class_attributes(tree)
         return if empty_attributes?
 
@@ -176,7 +176,7 @@ module Tapioca
         tree << RBI::Include.new("GeneratedInstanceMethods")
       end
 
-      sig { params(tree: RBI::Tree).returns([T::Array[Module], T::Array[Module]]) }
+      #: (RBI::Tree tree) -> [Array[Module], Array[Module]]
       def compile_mixes_in_class_methods(tree)
         includes = dynamic_includes.filter_map do |mod|
           qname = qualified_name_of(mod)
@@ -211,14 +211,14 @@ module Tapioca
         [[], []] # silence errors
       end
 
-      sig { params(mod: Module, dynamic_extends: T::Array[Module]).returns(T::Boolean) }
+      #: (Module mod, Array[Module] dynamic_extends) -> bool
       def module_included_by_another_dynamic_extend?(mod, dynamic_extends)
         dynamic_extends.any? do |dynamic_extend|
           mod != dynamic_extend && ancestors_of(dynamic_extend).include?(mod)
         end
       end
 
-      sig { params(qualified_mixin_name: String).returns(T::Boolean) }
+      #: (String qualified_mixin_name) -> bool
       def filtered_mixin?(qualified_mixin_name)
         # filter T:: namespace mixins that aren't T::Props
         # T::Props and subconstants have semantic value

data/lib/tapioca/runtime/generic_type_registry.rb

@@ -21,27 +21,22 @@ module Tapioca
     # variable to type variable serializers. This allows us to associate type variables
     # to the constant names that represent them, easily.
     module GenericTypeRegistry
-      @generic_instances = T.let(
-        {},
-        T::Hash[String, Module],
-      )
+      @generic_instances = {} #: Hash[String, Module]
 
-      @type_variables = T.let(
-        {}.compare_by_identity,
-        T::Hash[Module, T::Array[TypeVariableModule]],
-      )
+      @type_variables = {}.compare_by_identity #: Hash[Module, Array[TypeVariableModule]]
 
       class GenericType < T::Types::Simple
         extend T::Sig
 
-        sig { params(raw_type: Module, underlying_type: Module).void }
+        #: (Module raw_type, Module underlying_type) -> void
         def initialize(raw_type, underlying_type)
           super(raw_type)
 
-          @underlying_type = T.let(underlying_type, Module)
+          @underlying_type = underlying_type #: Module
         end
 
-        sig { override.params(obj: T.untyped).returns(T::Boolean) }
+        # @override
+        #: (untyped obj) -> bool
         def valid?(obj)
           obj.is_a?(@underlying_type)
         end
@@ -61,7 +56,7 @@ module Tapioca
         # 2 hash lookups (for the other two `Foo[Integer]`s).
         #
         # This method returns the created or cached clone of the constant.
-        sig { params(constant: T.untyped, types: T.untyped).returns(Module) }
+        #: (untyped constant, untyped types) -> Module
         def register_type(constant, types)
           # Build the name of the instantiated generic type,
           # something like `"Foo[X, Y, Z]"`
@@ -76,12 +71,12 @@ module Tapioca
           @generic_instances[name] ||= create_generic_type(constant, name)
         end
 
-        sig { params(instance: Object).returns(T::Boolean) }
+        #: (Object instance) -> bool
         def generic_type_instance?(instance)
           @generic_instances.values.any? { |generic_type| generic_type === instance }
         end
 
-        sig { params(constant: Module).returns(T.nilable(T::Array[TypeVariableModule])) }
+        #: (Module constant) -> Array[TypeVariableModule]?
         def lookup_type_variables(constant)
           @type_variables[constant]
         end
@@ -95,12 +90,7 @@ module Tapioca
         #
         # Finally, the original `type_variable` is returned from this method, so that the caller
         # can return it from the original methods as well.
-        sig do
-          params(
-            constant: T.untyped,
-            type_variable: TypeVariableModule,
-          ).void
-        end
+        #: (untyped constant, TypeVariableModule type_variable) -> void
         def register_type_variable(constant, type_variable)
           type_variables = lookup_or_initialize_type_variables(constant)
 
@@ -109,7 +99,7 @@ module Tapioca
 
         private
 
-        sig { params(constant: Module, name: String).returns(Module) }
+        #: (Module constant, String name) -> Module
         def create_generic_type(constant, name)
           generic_type = case constant
           when Class
@@ -151,7 +141,7 @@ module Tapioca
           generic_type
         end
 
-        sig { params(constant: T::Class[T.anything]).returns(T::Class[T.anything]) }
+        #: (Class[top] constant) -> Class[top]
         def create_safe_subclass(constant)
           # Lookup the "inherited" class method
           inherited_method = constant.method(:inherited)
@@ -178,7 +168,7 @@ module Tapioca
           end
         end
 
-        sig { params(constant: Module).returns(T::Array[TypeVariableModule]) }
+        #: (Module constant) -> Array[TypeVariableModule]
         def lookup_or_initialize_type_variables(constant)
           @type_variables[constant] ||= []
         end

data/lib/tapioca/runtime/reflection.rb

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require "tapioca/runtime/source_location"
+
 # On Ruby 3.2 or newer, Class defines an attached_object method that returns the
 # attached class of a singleton class without iterating ObjectSpace. On older
 # versions of Ruby, we fall back to iterating ObjectSpace.
@@ -18,97 +20,93 @@ module Tapioca
       extend T::Sig
       extend self
 
-      CLASS_METHOD = T.let(Kernel.instance_method(:class), UnboundMethod)
-      CONSTANTS_METHOD = T.let(Module.instance_method(:constants), UnboundMethod)
-      NAME_METHOD = T.let(Module.instance_method(:name), UnboundMethod)
-      SINGLETON_CLASS_METHOD = T.let(Object.instance_method(:singleton_class), UnboundMethod)
-      ANCESTORS_METHOD = T.let(Module.instance_method(:ancestors), UnboundMethod)
-      SUPERCLASS_METHOD = T.let(Class.instance_method(:superclass), UnboundMethod)
-      OBJECT_ID_METHOD = T.let(BasicObject.instance_method(:__id__), UnboundMethod)
-      EQUAL_METHOD = T.let(BasicObject.instance_method(:equal?), UnboundMethod)
-      PUBLIC_INSTANCE_METHODS_METHOD = T.let(Module.instance_method(:public_instance_methods), UnboundMethod)
-      PROTECTED_INSTANCE_METHODS_METHOD = T.let(Module.instance_method(:protected_instance_methods), UnboundMethod)
-      PRIVATE_INSTANCE_METHODS_METHOD = T.let(Module.instance_method(:private_instance_methods), UnboundMethod)
-      METHOD_METHOD = T.let(Kernel.instance_method(:method), UnboundMethod)
-      UNDEFINED_CONSTANT = T.let(Module.new.freeze, Module)
-
-      REQUIRED_FROM_LABELS = T.let(["<top (required)>", "<main>"].freeze, T::Array[String])
-
-      T::Sig::WithoutRuntime.sig { params(constant: BasicObject).returns(T::Boolean) }
+      CLASS_METHOD = Kernel.instance_method(:class) #: UnboundMethod
+      CONSTANTS_METHOD = Module.instance_method(:constants) #: UnboundMethod
+      NAME_METHOD = Module.instance_method(:name) #: UnboundMethod
+      SINGLETON_CLASS_METHOD = Object.instance_method(:singleton_class) #: UnboundMethod
+      ANCESTORS_METHOD = Module.instance_method(:ancestors) #: UnboundMethod
+      SUPERCLASS_METHOD = Class.instance_method(:superclass) #: UnboundMethod
+      OBJECT_ID_METHOD = BasicObject.instance_method(:__id__) #: UnboundMethod
+      EQUAL_METHOD = BasicObject.instance_method(:equal?) #: UnboundMethod
+      PUBLIC_INSTANCE_METHODS_METHOD = Module.instance_method(:public_instance_methods) #: UnboundMethod
+      PROTECTED_INSTANCE_METHODS_METHOD = Module.instance_method(:protected_instance_methods) #: UnboundMethod
+      PRIVATE_INSTANCE_METHODS_METHOD = Module.instance_method(:private_instance_methods) #: UnboundMethod
+      METHOD_METHOD = Kernel.instance_method(:method) #: UnboundMethod
+      UNDEFINED_CONSTANT = Module.new.freeze #: Module
+
+      REQUIRED_FROM_LABELS = ["<top (required)>", "<main>", "<compiled>"].freeze #: Array[String]
+
+      # @without_runtime
+      #: (BasicObject constant) -> bool
       def constant_defined?(constant)
         !UNDEFINED_CONSTANT.eql?(constant)
       end
 
-      sig do
-        params(
-          symbol: String,
-          inherit: T::Boolean,
-          namespace: Module,
-        ).returns(BasicObject).checked(:never)
-      end
+      # @without_runtime
+      #: (String symbol, ?inherit: bool, ?namespace: Module) -> BasicObject
       def constantize(symbol, inherit: false, namespace: Object)
         namespace.const_get(symbol, inherit)
       rescue NameError, LoadError, RuntimeError, ArgumentError, TypeError
         UNDEFINED_CONSTANT
       end
 
-      sig { params(object: BasicObject).returns(T::Class[T.anything]).checked(:never) }
+      #: (BasicObject object) -> Class[top]
       def class_of(object)
         CLASS_METHOD.bind_call(object)
       end
 
-      sig { params(constant: Module).returns(T::Array[Symbol]) }
+      #: (Module constant) -> Array[Symbol]
       def constants_of(constant)
         CONSTANTS_METHOD.bind_call(constant, false)
       end
 
-      sig { params(constant: Module).returns(T.nilable(String)) }
+      #: (Module constant) -> String?
       def name_of(constant)
         name = NAME_METHOD.bind_call(constant)
         name&.start_with?("#<") ? nil : name
       end
 
-      sig { params(constant: Module).returns(T::Class[T.anything]) }
+      #: (Module constant) -> Class[top]
       def singleton_class_of(constant)
         SINGLETON_CLASS_METHOD.bind_call(constant)
       end
 
-      sig { params(constant: Module).returns(T::Array[Module]) }
+      #: (Module constant) -> Array[Module]
       def ancestors_of(constant)
         ANCESTORS_METHOD.bind_call(constant)
       end
 
-      sig { params(constant: T::Class[T.anything]).returns(T.nilable(T::Class[T.anything])) }
+      #: (Class[top] constant) -> Class[top]?
       def superclass_of(constant)
         SUPERCLASS_METHOD.bind_call(constant)
       end
 
-      sig { params(object: BasicObject).returns(Integer).checked(:never) }
+      #: (BasicObject object) -> Integer
       def object_id_of(object)
         OBJECT_ID_METHOD.bind_call(object)
       end
 
-      sig { params(object: BasicObject, other: BasicObject).returns(T::Boolean).checked(:never) }
+      #: (BasicObject object, BasicObject other) -> bool
       def are_equal?(object, other)
         EQUAL_METHOD.bind_call(object, other)
       end
 
-      sig { params(constant: Module).returns(T::Array[Symbol]) }
+      #: (Module constant) -> Array[Symbol]
       def public_instance_methods_of(constant)
         PUBLIC_INSTANCE_METHODS_METHOD.bind_call(constant)
       end
 
-      sig { params(constant: Module).returns(T::Array[Symbol]) }
+      #: (Module constant) -> Array[Symbol]
       def protected_instance_methods_of(constant)
         PROTECTED_INSTANCE_METHODS_METHOD.bind_call(constant)
       end
 
-      sig { params(constant: Module).returns(T::Array[Symbol]) }
+      #: (Module constant) -> Array[Symbol]
       def private_instance_methods_of(constant)
         PRIVATE_INSTANCE_METHODS_METHOD.bind_call(constant)
       end
 
-      sig { params(constant: Module).returns(T::Array[Module]) }
+      #: (Module constant) -> Array[Module]
       def inherited_ancestors_of(constant)
         if Class === constant
           ancestors_of(superclass_of(constant) || Object)
@@ -117,7 +115,7 @@ module Tapioca
         end
       end
 
-      sig { params(constant: Module).returns(T.nilable(String)) }
+      #: (Module constant) -> String?
       def qualified_name_of(constant)
         name = name_of(constant)
         return if name.nil?
@@ -129,24 +127,28 @@ module Tapioca
         end
       end
 
-      sig { params(method: T.any(UnboundMethod, Method)).returns(T.untyped) }
+      SignatureBlockError = Class.new(Tapioca::Error)
+
+      #: ((UnboundMethod | Method) method) -> untyped
       def signature_of!(method)
         T::Utils.signature_for_method(method)
+      rescue LoadError, StandardError
+        Kernel.raise SignatureBlockError
       end
 
-      sig { params(method: T.any(UnboundMethod, Method)).returns(T.untyped) }
+      #: ((UnboundMethod | Method) method) -> untyped
       def signature_of(method)
         signature_of!(method)
-      rescue LoadError, StandardError
+      rescue SignatureBlockError
         nil
       end
 
-      sig { params(type: T::Types::Base).returns(String) }
+      #: (T::Types::Base type) -> String
       def name_of_type(type)
         type.to_s
       end
 
-      sig { params(constant: Module, method: Symbol).returns(Method) }
+      #: (Module constant, Symbol method) -> Method
       def method_of(constant, method)
         METHOD_METHOD.bind_call(constant, method)
       end
@@ -164,11 +166,7 @@ module Tapioca
       #
       #   class D < C; end
       #   descendants_of(C) # => [B, A, D]
-      sig do
-        type_parameters(:U)
-          .params(klass: T.all(T::Class[T.anything], T.type_parameter(:U)))
-          .returns(T::Array[T.type_parameter(:U)])
-      end
+      #: [U] ((Class[top] & U) klass) -> Array[U]
       def descendants_of(klass)
         result = ObjectSpace.each_object(klass.singleton_class).reject do |k|
           k.singleton_class? || k == klass
@@ -177,51 +175,74 @@ module Tapioca
         T.unsafe(result)
       end
 
+      #: ((String | Symbol) constant_name) -> SourceLocation?
+      def const_source_location(constant_name)
+        return unless Object.respond_to?(:const_source_location)
+
+        file, line = Object.const_source_location(constant_name)
+
+        SourceLocation.from_loc([file, line]) if file && line
+      end
+
       # Examines the call stack to identify the closest location where a "require" is performed
       # by searching for the label "<top (required)>" or "block in <class:...>" in the
       # case of an ActiveSupport.on_load hook. If none is found, it returns the location
       # labeled "<main>", which is the original call site.
-      sig { params(locations: T.nilable(T::Array[Thread::Backtrace::Location])).returns(String) }
+      #: (Array[Thread::Backtrace::Location]? locations) -> SourceLocation?
       def resolve_loc(locations)
-        return "" unless locations
+        return unless locations
 
+        # Find the location of the closest file load, which should give us the location of the file that
+        # triggered the definition.
         resolved_loc = locations.find do |loc|
           label = loc.label
           next unless label
 
           REQUIRED_FROM_LABELS.include?(label) || label.start_with?("block in <class:")
         end
-        return "" unless resolved_loc
+        return unless resolved_loc
+
+        resolved_loc_path = resolved_loc.absolute_path || resolved_loc.path
+
+        # Find the location of the last frame in this file to get the most accurate line number.
+        resolved_loc = locations.find { |loc| loc.absolute_path == resolved_loc_path }
+        return unless resolved_loc
+
+        # If the last operation was a `require`, and we have no more frames,
+        # we are probably dealing with a C-method.
+        return if locations.first&.label == "require"
+
+        file = resolved_loc.absolute_path || resolved_loc.path || ""
 
-        resolved_loc.absolute_path || ""
+        SourceLocation.from_loc([file, resolved_loc.lineno])
       end
 
-      sig { params(constant: Module).returns(T::Set[String]) }
+      #: (Module constant) -> Set[String]
       def file_candidates_for(constant)
         relevant_methods_for(constant).filter_map do |method|
           method.source_location&.first
         end.to_set
       end
 
-      sig { params(constant: Module).returns(T.untyped) }
+      #: (Module constant) -> untyped
       def abstract_type_of(constant)
         T::Private::Abstract::Data.get(constant, :abstract_type) ||
           T::Private::Abstract::Data.get(singleton_class_of(constant), :abstract_type)
       end
 
-      sig { params(constant: Module).returns(T::Boolean) }
+      #: (Module constant) -> bool
       def final_module?(constant)
         T::Private::Final.final_module?(constant)
       end
 
-      sig { params(constant: Module).returns(T::Boolean) }
+      #: (Module constant) -> bool
       def sealed_module?(constant)
         T::Private::Sealed.sealed_module?(constant)
       end
 
       private
 
-      sig { params(constant: Module).returns(T::Array[UnboundMethod]) }
+      #: (Module constant) -> Array[UnboundMethod]
       def relevant_methods_for(constant)
         methods = methods_for(constant).select(&:source_location)
           .reject { |x| method_defined_by_forwardable_module?(x) }
@@ -237,7 +258,7 @@ module Tapioca
         end
       end
 
-      sig { params(constant: Module).returns(T::Array[UnboundMethod]) }
+      #: (Module constant) -> Array[UnboundMethod]
       def methods_for(constant)
         modules = [constant, singleton_class_of(constant)]
         method_list_methods = [
@@ -251,7 +272,7 @@ module Tapioca
         end
       end
 
-      sig { params(parent: Module, name: String).returns(T.nilable(Module)) }
+      #: (Module parent, String name) -> Module?
       def child_module_for_parent_with_name(parent, name)
         return if parent.autoload?(name)
 
@@ -262,12 +283,12 @@ module Tapioca
         child
       end
 
-      sig { params(method: UnboundMethod).returns(T::Boolean) }
+      #: (UnboundMethod method) -> bool
       def method_defined_by_forwardable_module?(method)
         method.source_location&.first == Object.const_source_location(:Forwardable)&.first
       end
 
-      sig { params(name: String).returns(T::Boolean) }
+      #: (String name) -> bool
       def has_aliased_namespace?(name)
         name_parts = name.split("::")
         name_parts.pop # drop the constant name, leaving just the namespace

data/lib/tapioca/runtime/source_location.rb

@@ -0,0 +1,44 @@
+# typed: true
+# frozen_string_literal: true
+
+module Tapioca
+  module Runtime
+    class SourceLocation
+      # this looks something like:
+      # "(eval at /path/to/file.rb:123)"
+      # and we are interested in the "/path/to/file.rb" and "123" parts
+      EVAL_SOURCE_FILE_PATTERN = /^\(eval at (?<file>.+):(?<line>\d+)\)/ #: Regexp
+
+      #: String
+      attr_reader :file
+
+      #: Integer
+      attr_reader :line
+
+      def initialize(file:, line:)
+        # Ruby 3.3 adds automatic definition of source location for evals if
+        # `file` and `line` arguments are not provided. This results in the source
+        # file being something like `(eval at /path/to/file.rb:123)`. We try to parse
+        # this string to get the actual source file.
+        eval_pattern_match = EVAL_SOURCE_FILE_PATTERN.match(file)
+        if eval_pattern_match
+          file = eval_pattern_match[:file]
+          line = eval_pattern_match[:line].to_i
+        end
+
+        @file = file
+        @line = line
+      end
+
+      # force all callers to use the from_loc method
+      private_class_method :new
+
+      class << self
+        #: ([String?, Integer?]? loc) -> SourceLocation?
+        def from_loc(loc)
+          new(file: loc.first, line: loc.last) if loc&.first && loc.last
+        end
+      end
+    end
+  end
+end