Line-matching rewriter

lib/spoom/sorbet/metrics/code_metrics_visitor.rb

@@ -32,7 +32,7 @@ def collect_code_metrics(files)
       # On the other hand, the metrics file is a snapshot of the metrics at type checking time and knows about
       # is calls are typed, how many assertions are done, etc.
       class CodeMetricsVisitor < Spoom::Visitor
-        include RBS::ExtractRBSComments
+        include Spoom::RBS::ExtractRBSComments
 
         #: (Spoom::Counters) -> void
         def initialize(counters)

lib/spoom/sorbet/translate.rb

@@ -5,6 +5,7 @@
 
 require "spoom/source/rewriter"
 require "spoom/sorbet/translate/translator"
+require "spoom/sorbet/translate/validator"
 require "spoom/sorbet/translate/rbs_comments_to_sorbet_sigs"
 require "spoom/sorbet/translate/sorbet_assertions_to_rbs_comments"
 require "spoom/sorbet/translate/sorbet_sigs_to_rbs_comments"

lib/spoom/sorbet/translate/rbs_comments_to_sorbet_sigs.rb

@@ -55,3 +55,4 @@ def rewrite_if_needed(
 
 require "spoom/sorbet/translate/rbs_comments_to_sorbet_sigs/options"
 require "spoom/sorbet/translate/rbs_comments_to_sorbet_sigs/human_readable_translator"
+require "spoom/sorbet/translate/rbs_comments_to_sorbet_sigs/line_matching_translator"

lib/spoom/sorbet/translate/rbs_comments_to_sorbet_sigs/base_translator.rb

@@ -129,15 +129,15 @@ def visit_attr(node)
               @rewriter << Source::Replace.new(
                 signature.location.start_offset,
                 signature.location.end_offset,
-                sig.string(max_line_length: @max_line_length),
+                pad_out_line_count(of: sig.string(max_line_length: @max_line_length), to_height_of: signature),
               )
             rescue ::RBS::ParsingError, ::RBI::Error
               # Ignore signatures with errors
               next
             end
           end
 
-          #: (Prism::DefNode, RBS::Comments) -> void
+          #: (Prism::DefNode, Spoom::RBS::Comments) -> void
           def rewrite_def(def_node, comments)
             return if comments.empty?
             return if comments.signatures.empty?
@@ -180,40 +180,39 @@ def rewrite_def(def_node, comments)
               @rewriter << Source::Replace.new(
                 signature.location.start_offset,
                 signature.location.end_offset,
-                sig.string(max_line_length: @max_line_length),
+                pad_out_line_count(of: sig.string(max_line_length: @max_line_length), to_height_of: signature),
               )
             end
           end
 
-          #: (Array[RBS::Signature], method_name: String, location: String) -> Array[RBS::Signature]
+          #: (Array[Spoom::RBS::Signature], method_name: String, location: String) -> Array[Spoom::RBS::Signature]
           def apply_overloads_strategy(signatures, method_name:, location:)
             return signatures if signatures.size <= 1
 
             case @overloads_strategy
             when :translate_all
               signatures
             when :translate_last
-              kept = signatures.last #: as RBS::Signature
               others = signatures[0...-1] #: as !nil
+              others.each { |signature| rewrite_discarded_overload(signature) }
 
-              # Delete all the signatures we didn't keep
-              others.each do |signature|
-                from = adjust_to_line_start(signature.location.start_offset)
-                to = adjust_to_line_end(signature.location.end_offset)
-                @rewriter << Source::Delete.new(from, to)
-              end
+              kept = signatures.last #: as Spoom::RBS::Signature
               [kept]
             else # :raise
               raise Error, "Method `#{method_name}` at #{location} has multiple overloaded signatures"
             end
           end
 
+          # Called for every overloaded method sig that we discard because it wasn't the last one.
+          # @abstract
+          #: (Spoom::RBS::Signature) -> void
+          def rewrite_discarded_overload(signature) = raise
+
           #: (PrismTypes::anyScopeNode) -> void
           def apply_class_annotations(node)
             comments = node_rbs_comments(node)
             return if comments.empty?
 
-            indent = " " * (node.location.start_column + 2)
             insert_pos = case node
             when Prism::ClassNode
               (node.superclass || node.constant_path).location.end_offset
@@ -223,16 +222,14 @@ def apply_class_annotations(node)
               node.expression.location.end_offset
             end
 
-            class_annotations = comments.class_annotations
-            if class_annotations.any?
+            # Only translate (and `extend T::Helpers`) when there's at least one *known* class
+            # annotation. A node with only unknown annotations (e.g. `@private`) is left untouched.
+            if comments.class_annotations.any?
               unless already_extends?(node, /^(::)?T::Helpers$/)
-                @rewriter << Source::Insert.new(insert_pos, "\n#{indent}extend T::Helpers\n")
+                extend_with("T::Helpers", into: node, at: insert_pos)
               end
 
-              class_annotations.reverse_each do |annotation|
-                from = adjust_to_line_start(annotation.location.start_offset)
-                to = adjust_to_line_end(annotation.location.end_offset)
-
+              comments.annotations.reverse_each do |annotation|
                 content = case annotation.string
                 when "@abstract"
                   "abstract!"
@@ -247,15 +244,13 @@ def apply_class_annotations(node)
                   rbs_type = @type_translator.translate(srb_type)
                   "requires_ancestor { #{rbs_type} }"
                 else
+                  apply_class_annotation(annotation, parent_node: node, insert_pos:, sorbet_replacement: nil)
                   next
                 end
 
-                @rewriter << Source::Delete.new(from, to)
-
-                newline = node.body.nil? ? "" : "\n"
-                @rewriter << Source::Insert.new(insert_pos, "\n#{indent}#{content}#{newline}")
+                apply_class_annotation(annotation, parent_node: node, insert_pos:, sorbet_replacement: content)
               rescue ::RBS::ParsingError, ::RBI::Error
-                # Ignore annotations with errors
+                apply_class_annotation(annotation, parent_node: node, insert_pos:, sorbet_replacement: nil)
                 next
               end
             end
@@ -267,14 +262,11 @@ def apply_class_annotations(node)
                 next unless signature.string.start_with?("[")
 
                 type_params = ::RBS::Parser.parse_type_params(signature.string)
+                rewrite_type_params_signature(signature, type_params:)
                 next if type_params.empty?
 
-                from = adjust_to_line_start(signature.location.start_offset)
-                to = adjust_to_line_end(signature.location.end_offset)
-                @rewriter << Source::Delete.new(from, to)
-
                 unless already_extends?(node, /^(::)?T::Generic$/)
-                  @rewriter << Source::Insert.new(insert_pos, "\n#{indent}extend T::Generic\n")
+                  extend_with("T::Generic", into: node, at: insert_pos)
                 end
 
                 type_params.each do |type_param|
@@ -299,8 +291,7 @@ def apply_class_annotations(node)
                     end
                   end
 
-                  newline = node.body.nil? ? "" : "\n"
-                  @rewriter << Source::Insert.new(insert_pos, "\n#{indent}#{type_member}#{newline}")
+                  insert_type_member(type_member, parent_node: node, insert_pos:)
                 rescue ::RBS::ParsingError, ::RBI::Error
                   # Ignore signatures with errors
                   next
@@ -309,7 +300,28 @@ def apply_class_annotations(node)
             end
           end
 
-          #: (Array[RBS::Annotation], RBI::Sig) -> void
+          # @param is_known: true if this is an RBS annotation that we recognize
+          #                  false for some other `@`-prefixed thing, like a documentation `@param` tag.
+          # @abstract
+          #: (
+          #|   Spoom::RBS::Annotation,
+          #|   parent_node: PrismTypes::anyScopeNode,
+          #|   insert_pos: Integer,
+          #|   sorbet_replacement: String?
+          #| ) -> void
+          def apply_class_annotation(annotation, parent_node:, insert_pos:, sorbet_replacement:) = raise
+
+          # Rewrites the `#: [...]` type params comment (e.g. delete it, or mark it as translated).
+          # @abstract
+          #: (Spoom::RBS::Signature, type_params: Array[::RBS::AST::TypeParam]) -> void
+          def rewrite_type_params_signature(signature, type_params:) = raise
+
+          # Inserts a single `type_member` declaration into the class/module body.
+          # @abstract
+          #: (String type_member, parent_node: PrismTypes::anyScopeNode, insert_pos: Integer) -> void
+          def insert_type_member(type_member, parent_node:, insert_pos:) = raise
+
+          #: (Array[Spoom::RBS::Annotation], RBI::Sig) -> void
           def apply_member_annotations(annotations, sig)
             annotations.each do |annotation|
               case annotation.string
@@ -329,10 +341,25 @@ def apply_member_annotations(annotations, sig)
                 sig.is_overridable = true
               when "@without_runtime"
                 sig.without_runtime = true
+              else
+                rewrite_annotation(annotation, is_known: false)
+                next
               end
+
+              rewrite_annotation(annotation, is_known: true)
             end
           end
 
+          # @param is_known: true if this is an RBS annotation that we recognize
+          #                  false for some other `@`-prefixed thing, like a documentation `@param` tag.
+          # @overridable
+          #: (Spoom::RBS::Annotation, is_known: bool) -> void
+          def rewrite_annotation(annotation, is_known:) = nil # no-op
+
+          # @abstract
+          #: (String mixin_name, into: PrismTypes::anyScopeNode, at: Integer) -> void
+          def extend_with(mixin_name, into:, at:) = raise
+
           #: (PrismTypes::anyScopeNode, Regexp) -> bool
           def already_extends?(node, constant_regex)
             node.child_nodes.any? do |c|
@@ -349,9 +376,9 @@ def already_extends?(node, constant_regex)
             end
           end
 
-          #: (Array[Prism::Comment]) -> Array[RBS::TypeAlias]
+          #: (Array[Prism::Comment]) -> Array[Spoom::RBS::TypeAlias]
           def collect_type_aliases(comments)
-            type_aliases = [] #: Array[RBS::TypeAlias]
+            type_aliases = [] #: Array[Spoom::RBS::TypeAlias]
 
             return type_aliases if comments.empty?
 
@@ -414,12 +441,22 @@ def apply_type_aliases(comments)
 
               @rewriter << Source::Delete.new(from, to)
               content = "#{indent}#{alias_name} = T.type_alias { #{sorbet_type.to_rbi} }\n"
+              content = pad_out_line_count(of: content, to_height_of: type_alias)
               @rewriter << Source::Insert.new(insert_pos, content)
             rescue ::RBS::ParsingError, ::RBI::Error
               # Ignore type aliases with errors
               next
             end
           end
+
+          # @overridable
+          #: (of: String, to_height_of: Spoom::RBS::Comment) -> String
+          def pad_out_line_count(of:, to_height_of:)
+            replacement = of
+
+            # no-op implementation
+            replacement
+          end
         end
       end
     end

lib/spoom/sorbet/translate/rbs_comments_to_sorbet_sigs/human_readable_translator.rb

@@ -9,6 +9,66 @@ module Sorbet
     module Translate
       module RBSCommentsToSorbetSigs
         class HumanReadableTranslator < BaseTranslator
+          private
+
+          # Deletes the discarded overload from the source codes
+          # @override
+          #: (Spoom::RBS::Signature) -> void
+          def rewrite_discarded_overload(signature)
+            from = adjust_to_line_start(signature.location.start_offset)
+            to = adjust_to_line_end(signature.location.end_offset)
+            @rewriter << Source::Delete.new(from, to)
+          end
+
+          # @override
+          #: (
+          #|   Spoom::RBS::Annotation,
+          #|   parent_node: PrismTypes::anyScopeNode,
+          #|   insert_pos: Integer,
+          #|   sorbet_replacement: String?
+          #| ) -> void
+          def apply_class_annotation(annotation, parent_node:, insert_pos:, sorbet_replacement:)
+            return unless sorbet_replacement # unknown annotation.
+
+            from = adjust_to_line_start(annotation.location.start_offset)
+            to = adjust_to_line_end(annotation.location.end_offset)
+
+            @rewriter << Source::Delete.new(from, to)
+
+            indent = " " * (parent_node.location.start_column + 2)
+            content = sorbet_replacement
+            newline = parent_node.body.nil? ? "" : "\n"
+            @rewriter << Source::Insert.new(insert_pos, "\n#{indent}#{content}#{newline}")
+          end
+
+          # @override
+          #: (Spoom::RBS::Signature, type_params: Array[::RBS::AST::TypeParam]) -> void
+          def rewrite_type_params_signature(signature, type_params:)
+            from = adjust_to_line_start(signature.location.start_offset)
+            to = adjust_to_line_end(signature.location.end_offset)
+            @rewriter << Source::Delete.new(from, to)
+          end
+
+          # @override
+          #: (String type_member, parent_node: PrismTypes::anyScopeNode, insert_pos: Integer) -> void
+          def insert_type_member(type_member, parent_node:, insert_pos:)
+            indent = " " * (parent_node.location.start_column + 2)
+            newline = parent_node.body.nil? ? "" : "\n"
+            @rewriter << Source::Insert.new(insert_pos, "\n#{indent}#{type_member}#{newline}")
+          end
+
+          # @override
+          #: (String mixin_name, into: Prism::Node, at: Integer) -> void
+          def extend_with(mixin_name, into:, at:)
+            parent_node = into
+            insert_pos = at
+
+            indent = " " * (parent_node.location.start_column + 2)
+            # `extend` is always followed by an annotation or `type_member`, so it always needs a
+            # trailing newline to separate them. Since it's never the last inserted line, that
+            # trailing newline can't leave a blank line before `end` (unlike the lines that follow).
+            @rewriter << Source::Insert.new(insert_pos, "\n#{indent}extend #{mixin_name}\n")
+          end
         end
       end
     end