sorbet-runtime 0.5.5841

data/lib/types/private/methods/decl_builder.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+# typed: true
+
+module T::Private::Methods
+  Declaration = Struct.new(:mod, :params, :returns, :bind, :mode, :checked, :finalized, :on_failure, :override_allow_incompatible, :type_parameters)
+
+  class DeclBuilder
+    attr_reader :decl
+
+    class BuilderError < StandardError; end
+
+    private def check_live!
+      if decl.finalized
+        raise BuilderError.new("You can't modify a signature declaration after it has been used.")
+      end
+    end
+
+    def initialize(mod)
+      # TODO RUBYPLAT-1278 - with ruby 2.5, use kwargs here
+      @decl = Declaration.new(
+        mod,
+        ARG_NOT_PROVIDED, # params
+        ARG_NOT_PROVIDED, # returns
+        ARG_NOT_PROVIDED, # bind
+        Modes.standard, # mode
+        ARG_NOT_PROVIDED, # checked
+        false, # finalized
+        ARG_NOT_PROVIDED, # on_failure
+        nil, # override_allow_incompatible
+        ARG_NOT_PROVIDED, # type_parameters
+      )
+    end
+
+    def params(params)
+      check_live!
+      if !decl.params.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .params twice")
+      end
+
+      decl.params = params
+
+      self
+    end
+
+    def returns(type)
+      check_live!
+      if decl.returns.is_a?(T::Private::Types::Void)
+        raise BuilderError.new("You can't call .returns after calling .void.")
+      end
+      if !decl.returns.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .returns multiple times in a signature.")
+      end
+
+      decl.returns = type
+
+      self
+    end
+
+    def void
+      check_live!
+      if !decl.returns.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .void after calling .returns.")
+      end
+
+      decl.returns = T::Private::Types::Void.new
+
+      self
+    end
+
+    def bind(type)
+      check_live!
+      if !decl.bind.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .bind multiple times in a signature.")
+      end
+
+      decl.bind = type
+
+      self
+    end
+
+    def checked(level)
+      check_live!
+
+      if !decl.checked.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .checked multiple times in a signature.")
+      end
+      if level == :never && !decl.on_failure.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't use .checked(:never) with .on_failure because .on_failure will have no effect.")
+      end
+      if !T::Private::RuntimeLevels::LEVELS.include?(level)
+        raise BuilderError.new("Invalid `checked` level '#{level}'. Use one of: #{T::Private::RuntimeLevels::LEVELS}.")
+      end
+
+      decl.checked = level
+
+      self
+    end
+
+    def on_failure(*args)
+      check_live!
+
+      if !decl.on_failure.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .on_failure multiple times in a signature.")
+      end
+      if decl.checked == :never
+        raise BuilderError.new("You can't use .on_failure with .checked(:never) because .on_failure will have no effect.")
+      end
+
+      decl.on_failure = args
+
+      self
+    end
+
+    def abstract
+      check_live!
+
+      case decl.mode
+      when Modes.standard
+        decl.mode = Modes.abstract
+      when Modes.abstract
+        raise BuilderError.new(".abstract cannot be repeated in a single signature")
+      else
+        raise BuilderError.new("`.abstract` cannot be combined with `.override` or `.overridable`.")
+      end
+
+      self
+    end
+
+    def final
+      check_live!
+      raise BuilderError.new("The syntax for declaring a method final is `sig(:final) {...}`, not `sig {final. ...}`")
+    end
+
+    def override(allow_incompatible: false)
+      check_live!
+
+      case decl.mode
+      when Modes.standard
+        decl.mode = Modes.override
+        decl.override_allow_incompatible = allow_incompatible
+      when Modes.override, Modes.overridable_override
+        raise BuilderError.new(".override cannot be repeated in a single signature")
+      when Modes.overridable
+        decl.mode = Modes.overridable_override
+      else
+        raise BuilderError.new("`.override` cannot be combined with `.abstract`.")
+      end
+
+      self
+    end
+
+    def overridable
+      check_live!
+
+      case decl.mode
+      when Modes.abstract
+        raise BuilderError.new("`.overridable` cannot be combined with `.#{decl.mode}`")
+      when Modes.override
+        decl.mode = Modes.overridable_override
+      when Modes.standard
+        decl.mode = Modes.overridable
+      when Modes.overridable, Modes.overridable_override
+        raise BuilderError.new(".overridable cannot be repeated in a single signature")
+      end
+
+      self
+    end
+
+    # Declares valid type paramaters which can be used with `T.type_parameter` in
+    # this `sig`.
+    #
+    # This is used for generic methods. Example usage:
+    #
+    #  sig do
+    #    type_parameters(:U)
+    #    .params(blk: T.proc.params(arg0: Elem).returns(T.type_parameter(:U)))
+    #    .returns(T::Array[T.type_parameter(:U)])
+    #  end
+    #  def map(&blk); end
+    def type_parameters(*names)
+      check_live!
+
+      names.each do |name|
+        raise BuilderError.new("not a symbol: #{name}") unless name.is_a?(Symbol)
+      end
+
+      if !decl.type_parameters.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .type_parameters multiple times in a signature.")
+      end
+
+      decl.type_parameters = names
+
+      self
+    end
+
+    def finalize!
+      check_live!
+
+      if decl.returns.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You must provide a return type; use the `.returns` or `.void` builder methods.")
+      end
+
+      if decl.bind.equal?(ARG_NOT_PROVIDED)
+        decl.bind = nil
+      end
+      if decl.checked.equal?(ARG_NOT_PROVIDED)
+        default_checked_level = T::Private::RuntimeLevels.default_checked_level
+        if default_checked_level == :never && !decl.on_failure.equal?(ARG_NOT_PROVIDED)
+          raise BuilderError.new("To use .on_failure you must additionally call .checked(:tests) or .checked(:always), otherwise, the .on_failure has no effect.")
+        end
+        decl.checked = default_checked_level
+      end
+      if decl.on_failure.equal?(ARG_NOT_PROVIDED)
+        decl.on_failure = nil
+      end
+      if decl.params.equal?(ARG_NOT_PROVIDED)
+        decl.params = {}
+      end
+      if decl.type_parameters.equal?(ARG_NOT_PROVIDED)
+        decl.type_parameters = {}
+      end
+
+      decl.finalized = true
+
+      self
+    end
+  end
+end

data/lib/types/private/methods/modes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# typed: true
+
+module T::Private::Methods::Modes
+  def self.standard; 'standard'; end
+  def self.abstract; 'abstract'; end
+  def self.overridable; 'overridable'; end
+  def self.override; 'override'; end
+  def self.overridable_override; 'overridable_override'; end
+  def self.untyped; 'untyped'; end
+  MODES = [self.standard, self.abstract, self.overridable, self.override, self.overridable_override, self.untyped]
+
+  OVERRIDABLE_MODES = [self.override, self.overridable, self.overridable_override, self.untyped, self.abstract]
+  OVERRIDE_MODES = [self.override, self.overridable_override]
+  NON_OVERRIDE_MODES = MODES - OVERRIDE_MODES
+end

data/lib/types/private/methods/signature.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+# typed: true
+
+class T::Private::Methods::Signature
+  attr_reader :method, :method_name, :arg_types, :kwarg_types, :block_type, :block_name,
+              :rest_type, :rest_name, :keyrest_type, :keyrest_name, :bind,
+              :return_type, :mode, :req_arg_count, :req_kwarg_names, :has_rest, :has_keyrest,
+              :check_level, :parameters, :on_failure, :override_allow_incompatible
+
+  def self.new_untyped(method:, mode: T::Private::Methods::Modes.untyped, parameters: method.parameters)
+    # Using `Untyped` ensures we'll get an error if we ever try validation on these.
+    not_typed = T::Private::Types::NotTyped.new
+    raw_return_type = not_typed
+    raw_arg_types = parameters.map do |_param_kind, param_name|
+      [param_name, not_typed]
+    end.to_h
+
+    self.new(
+      method: method,
+      method_name: method.name,
+      raw_arg_types: raw_arg_types,
+      raw_return_type: raw_return_type,
+      bind: nil,
+      mode: mode,
+      check_level: :never,
+      parameters: parameters,
+      on_failure: nil,
+    )
+  end
+
+  def initialize(method:, method_name:, raw_arg_types:, raw_return_type:, bind:, mode:, check_level:, parameters: method.parameters, on_failure:, override_allow_incompatible: false)
+    @method = method
+    @method_name = method_name
+    @arg_types = []
+    @kwarg_types = {}
+    @block_type = nil
+    @block_name = nil
+    @rest_type = nil
+    @rest_name = nil
+    @keyrest_type = nil
+    @keyrest_name = nil
+    @return_type = T::Utils.coerce(raw_return_type)
+    @bind = bind ? T::Utils.coerce(bind) : bind
+    @mode = mode
+    @check_level = check_level
+    @req_arg_count = 0
+    @req_kwarg_names = []
+    @has_rest = false
+    @has_keyrest = false
+    @parameters = parameters
+    @on_failure = on_failure
+    @override_allow_incompatible = override_allow_incompatible
+
+    declared_param_names = raw_arg_types.keys
+    # If sig params are declared but there is a single parameter with a missing name
+    # **and** the method ends with a "=", assume it is a writer method generated
+    # by attr_writer or attr_accessor
+    writer_method = declared_param_names != [nil] && parameters == [[:req]] && method_name[-1] == "="
+    # For writer methods, map the single parameter to the method name without the "=" at the end
+    parameters = [[:req, method_name[0...-1].to_sym]] if writer_method
+    param_names = parameters.map {|_, name| name}
+    missing_names = param_names - declared_param_names
+    extra_names = declared_param_names - param_names
+    if !missing_names.empty?
+      raise "The declaration for `#{method.name}` is missing parameter(s): #{missing_names.join(', ')}"
+    end
+    if !extra_names.empty?
+      raise "The declaration for `#{method.name}` has extra parameter(s): #{extra_names.join(', ')}"
+    end
+
+    parameters.zip(raw_arg_types) do |(param_kind, param_name), (type_name, raw_type)|
+      if type_name != param_name
+        hint = ""
+        # Ruby reorders params so that required keyword arguments
+        # always precede optional keyword arguments. We can't tell
+        # whether the culprit is the Ruby reordering or user error, so
+        # we error but include a note
+        if param_kind == :keyreq && parameters.any? {|k, _| k == :key}
+          hint = "\n\nNote: Any required keyword arguments must precede any optional keyword " \
+                 "arguments. If your method declaration matches your `def`, try reordering any " \
+                 "optional keyword parameters to the end of the method list."
+        end
+
+        raise "Parameter `#{type_name}` is declared out of order (declared as arg number " \
+              "#{declared_param_names.index(type_name) + 1}, defined in the method as arg number " \
+              "#{param_names.index(type_name) + 1}).#{hint}\nMethod: #{method_desc}"
+      end
+
+      type = T::Utils.coerce(raw_type)
+
+      case param_kind
+      when :req
+        if @arg_types.length > @req_arg_count
+          # Note that this is actually is supported by Ruby, but it would add complexity to
+          # support it here, and I'm happy to discourage its use anyway.
+          raise "Required params after optional params are not supported in method declarations. Method: #{method_desc}"
+        end
+        @arg_types << [param_name, type]
+        @req_arg_count += 1
+      when :opt
+        @arg_types << [param_name, type]
+      when :key, :keyreq
+        @kwarg_types[param_name] = type
+        if param_kind == :keyreq
+          @req_kwarg_names << param_name
+        end
+      when :block
+        @block_name = param_name
+        @block_type = type
+      when :rest
+        @has_rest = true
+        @rest_name = param_name
+        @rest_type = type
+      when :keyrest
+        @has_keyrest = true
+        @keyrest_name = param_name
+        @keyrest_type = type
+      else
+        raise "Unexpected param_kind: `#{param_kind}`. Method: #{method_desc}"
+      end
+    end
+  end
+
+  def arg_count
+    @arg_types.length
+  end
+
+  def kwarg_names
+    @kwarg_types.keys
+  end
+
+  def owner
+    @method.owner
+  end
+
+  def dsl_method
+    "#{@mode}_method"
+  end
+
+  # @return [Hash] a mapping like {arg_name: [val, type], ...}, for only those args actually present.
+  def each_args_value_type(args)
+    # Manually split out args and kwargs based on ruby's behavior. Do not try to implement this by
+    # getting ruby to determine the kwargs for you (e.g., by defining this method to take *args and
+    # **kwargs). That won't work, because ruby's behavior for determining kwargs is dependent on the
+    # the other parameters in the method definition, and our method definition here doesn't (and
+    # can't) match the definition of the method we're validating. In addition, Ruby has a bug that
+    # causes forwarding **kwargs to do the wrong thing: see https://bugs.ruby-lang.org/issues/10708
+    # and https://bugs.ruby-lang.org/issues/11860.
+    if (args.length > @req_arg_count) && (!@kwarg_types.empty? || @has_keyrest) && args[-1].is_a?(Hash)
+      kwargs = args[-1]
+      args = args[0...-1]
+    else
+      kwargs = EMPTY_HASH
+    end
+
+    arg_types = @arg_types
+
+    if @has_rest
+      arg_types += [[@rest_name, @rest_type]] * (args.length - @arg_types.length)
+
+    elsif (args.length < @req_arg_count) || (args.length > @arg_types.length)
+      expected_str = @req_arg_count.to_s
+      if @arg_types.length != @req_arg_count
+        expected_str += "..#{@arg_types.length}"
+      end
+      raise ArgumentError.new("wrong number of arguments (given #{args.length}, expected #{expected_str})")
+    end
+
+    begin
+      it = 0
+      while it < args.length
+        yield arg_types[it][0], args[it], arg_types[it][1]
+        it += 1
+      end
+    end
+
+    kwargs.each do |name, val|
+      type = @kwarg_types[name]
+      if !type && @has_keyrest
+        type = @keyrest_type
+      end
+      yield name, val, type if type
+    end
+  end
+
+  def method_desc
+    if @method.source_location
+      loc = @method.source_location.join(':')
+    else
+      loc = "<unknown location>"
+    end
+    "#{@method} at #{loc}"
+  end
+
+  EMPTY_HASH = {}.freeze
+end

data/lib/types/private/methods/signature_validation.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+# typed: true
+
+module T::Private::Methods::SignatureValidation
+  Methods = T::Private::Methods
+  Modes = Methods::Modes
+
+  def self.validate(signature)
+    if signature.method_name == :initialize && signature.method.owner.is_a?(Class)
+      # Constructors are special. They look like overrides in terms of a super_method existing,
+      # but in practice, you never call them polymorphically. Conceptually, they're standard
+      # methods (this is consistent with how they're treated in other languages, e.g. Java)
+      if signature.mode != Modes.standard
+        raise "`initialize` should not use `.abstract` or `.implementation` or any other inheritance modifiers."
+      end
+      return
+    end
+
+    super_method = signature.method.super_method
+
+    if super_method && super_method.owner != signature.method.owner
+      Methods.maybe_run_sig_block_for_method(super_method)
+      super_signature = Methods.signature_for_method(super_method)
+
+      # If the super_method has any kwargs we can't build a
+      # Signature for it, so we'll just skip validation in that case.
+      if !super_signature && !super_method.parameters.select {|kind, _| kind == :rest || kind == :kwrest}.empty?
+        nil
+      else
+        # super_signature can be nil when we're overriding a method (perhaps a builtin) that didn't use
+        # one of the method signature helpers. Use an untyped signature so we can still validate
+        # everything but types.
+        #
+        # We treat these signatures as overridable, that way people can use `.override` with
+        # overrides of builtins. In the future we could try to distinguish when the method is a
+        # builtin and treat non-builtins as non-overridable (so you'd be forced to declare them with
+        # `.overridable`).
+        #
+        super_signature ||= Methods::Signature.new_untyped(method: super_method)
+
+        validate_override_mode(signature, super_signature)
+        validate_override_shape(signature, super_signature)
+        validate_override_types(signature, super_signature)
+      end
+    else
+      validate_non_override_mode(signature)
+    end
+  end
+
+  private_class_method def self.pretty_mode(signature)
+    if signature.mode == Modes.overridable_override
+      '.overridable.override'
+    else
+      ".#{signature.mode}"
+    end
+  end
+
+  def self.validate_override_mode(signature, super_signature)
+    case signature.mode
+    when *Modes::OVERRIDE_MODES
+      # Peaceful
+    when *Modes::NON_OVERRIDE_MODES
+      if super_signature.mode == Modes.standard
+        # Peaceful
+      elsif super_signature.mode == Modes.abstract
+        raise "You must use `.override` when overriding the abstract method `#{signature.method_name}`.\n" \
+              "  Abstract definition: #{method_loc_str(super_signature.method)}\n" \
+              "  Implementation definition: #{method_loc_str(signature.method)}\n"
+      elsif super_signature.mode != Modes.untyped
+        raise "You must use `.override` when overriding the existing method `#{signature.method_name}`.\n" \
+              "  Parent definition: #{method_loc_str(super_signature.method)}\n" \
+              "  Child definition:  #{method_loc_str(signature.method)}\n"
+      end
+    else
+      raise "Unexpected mode: #{signature.mode}. Please report to #dev-productivity."
+    end
+  end
+
+  def self.validate_non_override_mode(signature)
+    case signature.mode
+    when Modes.override
+      if signature.method_name == :each && signature.method.owner < Enumerable
+        # Enumerable#each is the only method in Sorbet's RBI payload that defines an abstract method.
+        # Enumerable#each does not actually exist at runtime, but it is required to be implemented by
+        # any class which includes Enumerable. We want to declare Enumerable#each as abstract so that
+        # people can call it anything which implements the Enumerable interface, and so that it's a
+        # static error to forget to implement it.
+        #
+        # This is a one-off hack, and we should think carefully before adding more methods here.
+        nil
+      else
+        raise "You marked `#{signature.method_name}` as #{pretty_mode(signature)}, but that method doesn't already exist in this class/module to be overriden.\n" \
+          "  Either check for typos and for missing includes or super classes to make the parent method shows up\n" \
+          "  ... or remove #{pretty_mode(signature)} here: #{method_loc_str(signature.method)}\n"
+      end
+    when Modes.standard, *Modes::NON_OVERRIDE_MODES
+      # Peaceful
+      nil
+    else
+      raise "Unexpected mode: #{signature.mode}. Please report to #dev-productivity."
+    end
+
+    owner = signature.method.owner
+    if (signature.mode == Modes.abstract || Modes::OVERRIDABLE_MODES.include?(signature.mode)) &&
+        owner.singleton_class?
+      # Given a singleton class, we can check if it belongs to a
+      # module by looking at its superclass; given `module M`,
+      # `M.singleton_class.superclass == Module`, which is not true
+      # for any class.
+      if owner.superclass == Module
+        raise "Defining an overridable class method (via #{pretty_mode(signature)}) " \
+              "on a module is not allowed. Class methods on " \
+              "modules do not get inherited and thus cannot be overridden. For help, ask in " \
+              "#dev-productivity."
+      end
+    end
+  end
+
+  def self.validate_override_shape(signature, super_signature)
+    return if signature.override_allow_incompatible
+    return if super_signature.mode == Modes.untyped
+
+    method_name = signature.method_name
+    mode_verb = super_signature.mode == Modes.abstract ? 'implements' : 'overrides'
+
+    if !signature.has_rest && signature.arg_count < super_signature.arg_count
+      raise "Your definition of `#{method_name}` must accept at least #{super_signature.arg_count} " \
+            "positional arguments to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if !signature.has_rest && super_signature.has_rest
+      raise "Your definition of `#{method_name}` must have `*#{super_signature.rest_name}` " \
+            "to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if signature.req_arg_count > super_signature.req_arg_count
+      raise "Your definition of `#{method_name}` must have no more than #{super_signature.req_arg_count} " \
+            "required argument(s) to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if !signature.has_keyrest
+      # O(nm), but n and m are tiny here
+      missing_kwargs = super_signature.kwarg_names - signature.kwarg_names
+      if !missing_kwargs.empty?
+        raise "Your definition of `#{method_name}` is missing these keyword arg(s): #{missing_kwargs} " \
+              "which are defined in the method it #{mode_verb}: " \
+              "#{base_override_loc_str(signature, super_signature)}"
+      end
+    end
+
+    if !signature.has_keyrest && super_signature.has_keyrest
+      raise "Your definition of `#{method_name}` must have `**#{super_signature.keyrest_name}` " \
+            "to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+
+    # O(nm), but n and m are tiny here
+    extra_req_kwargs = signature.req_kwarg_names - super_signature.req_kwarg_names
+    if !extra_req_kwargs.empty?
+      raise "Your definition of `#{method_name}` has extra required keyword arg(s) " \
+            "#{extra_req_kwargs} relative to the method it #{mode_verb}, making it incompatible: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if super_signature.block_name && !signature.block_name
+      raise "Your definition of `#{method_name}` must accept a block parameter to be compatible " \
+            "with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+  end
+
+  def self.validate_override_types(signature, super_signature)
+    return if signature.override_allow_incompatible
+    return if super_signature.mode == Modes.untyped
+    return unless [signature, super_signature].all? do |sig|
+      sig.check_level == :always || (sig.check_level == :tests && T::Private::RuntimeLevels.check_tests?)
+    end
+    mode_noun = super_signature.mode == Modes.abstract ? 'implementation' : 'override'
+
+    # arg types must be contravariant
+    super_signature.arg_types.zip(signature.arg_types).each_with_index do |((_super_name, super_type), (name, type)), index|
+      if !super_type.subtype_of?(type)
+        raise "Incompatible type for arg ##{index + 1} (`#{name}`) in #{mode_noun} of method " \
+              "`#{signature.method_name}`:\n" \
+              "* Base: `#{super_type}` (in #{method_loc_str(super_signature.method)})\n" \
+              "* #{mode_noun.capitalize}: `#{type}` (in #{method_loc_str(signature.method)})\n" \
+              "(The types must be contravariant.)"
+      end
+    end
+
+    # kwarg types must be contravariant
+    super_signature.kwarg_types.each do |name, super_type|
+      type = signature.kwarg_types[name]
+      if !super_type.subtype_of?(type)
+        raise "Incompatible type for arg `#{name}` in #{mode_noun} of method `#{signature.method_name}`:\n" \
+              "* Base: `#{super_type}` (in #{method_loc_str(super_signature.method)})\n" \
+              "* #{mode_noun.capitalize}: `#{type}` (in #{method_loc_str(signature.method)})\n" \
+              "(The types must be contravariant.)"
+      end
+    end
+
+    # return types must be covariant
+    if !signature.return_type.subtype_of?(super_signature.return_type)
+      raise "Incompatible return type in #{mode_noun} of method `#{signature.method_name}`:\n" \
+            "* Base: `#{super_signature.return_type}` (in #{method_loc_str(super_signature.method)})\n" \
+            "* #{mode_noun.capitalize}: `#{signature.return_type}` (in #{method_loc_str(signature.method)})\n" \
+            "(The types must be covariant.)"
+    end
+  end
+
+  private_class_method def self.base_override_loc_str(signature, super_signature)
+    mode_noun = super_signature.mode == Modes.abstract ? 'Implementation' : 'Override'
+    "\n * Base definition: in #{method_loc_str(super_signature.method)}" \
+    "\n * #{mode_noun}: in #{method_loc_str(signature.method)}"
+  end
+
+  private_class_method def self.method_loc_str(method)
+    if method.source_location
+      loc = method.source_location.join(':')
+    else
+      loc = "<unknown location>"
+    end
+    "#{method.owner} at #{loc}"
+  end
+end