mt-lang 0.2.0

data/lib/milk_tea/tooling/linter/doc_tags.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module MilkTea
+  class Linter
+    module LinterDocTags
+      private
+
+      def emit_doc_tag_warnings(source_file)
+        return if @source_lines.empty?
+  
+        each_doc_comment_definition(source_file) do |declaration, doc_lines|
+          parsed = parse_doc_tag_block(doc_lines)
+  
+          parsed[:errors].each do |error|
+            @warnings << Warning.new(
+              path: @path,
+              line: error[:line],
+              column: error[:column],
+              length: error[:length],
+              code: "doc-tag",
+              message: error[:message],
+              severity: :hint,
+            )
+          end
+  
+          validate_doc_tags_for_declaration(declaration, parsed[:tags])
+        end
+      end
+      def each_doc_comment_definition(source_file)
+        declarations = source_file.declarations.flat_map do |declaration|
+          case declaration
+          when AST::ExtendingBlock
+            declaration.methods
+          else
+            declaration
+          end
+        end
+  
+        declarations.each do |declaration|
+          docs = collect_doc_comment_block_for_line(declaration.line)
+          next if docs.nil? || docs.empty?
+  
+          yield declaration, docs
+        end
+      end
+  
+      def collect_doc_comment_block_for_line(line)
+        index = line.to_i - 2
+        return nil if index.negative?
+  
+        docs = []
+        while index >= 0
+          stripped = @source_lines[index].to_s.strip
+          break if stripped.empty?
+          break unless stripped.start_with?('##')
+  
+          docs << {
+            line: index + 1,
+            text: stripped.sub(/\A##\s?/, ''),
+          }
+          index -= 1
+        end
+  
+        return nil if docs.empty?
+  
+        docs.reverse
+      end
+      def parse_doc_tag_block(lines)
+        tags = {
+          params: [],
+          returns: nil,
+          throws: [],
+          see: [],
+        }
+        errors = []
+  
+        lines.each do |entry|
+          text = entry[:text].to_s
+          match = text.match(/\A\s*@([A-Za-z_][A-Za-z0-9_-]*)(?:\s+(.*))?\z/)
+          next unless match
+  
+          tag = match[1].to_s.downcase
+          payload = match[2].to_s.strip
+          column = doc_tag_column(entry[:line])
+  
+          case tag
+          when 'param'
+            if payload.empty?
+              errors << {
+                line: entry[:line],
+                column: column,
+                length: 6,
+                message: 'doc tag @param requires a parameter name',
+              }
+              next
+            end
+  
+            name_match = payload.match(/\A([A-Za-z_][A-Za-z0-9_]*)(?:\s+(.*))?\z/)
+            unless name_match
+              errors << {
+                line: entry[:line],
+                column: column,
+                length: 6,
+                message: 'doc tag @param has an invalid parameter name',
+              }
+              next
+            end
+  
+            tags[:params] << {
+              name: name_match[1],
+              text: name_match[2].to_s.strip,
+              line: entry[:line],
+              column: column,
+            }
+          when 'return', 'returns'
+            tags[:returns] = {
+              text: payload,
+              line: entry[:line],
+              column: column,
+            }
+          when 'throws', 'throw'
+            tags[:throws] << {
+              text: payload,
+              line: entry[:line],
+              column: column,
+            }
+          when 'see'
+            tags[:see] << {
+              text: payload,
+              line: entry[:line],
+              column: column,
+            }
+          else
+            errors << {
+              line: entry[:line],
+              column: column,
+              length: tag.length + 1,
+              message: "unknown doc tag @#{tag}",
+            }
+          end
+        end
+  
+        {
+          tags: tags,
+          errors: errors,
+        }
+      end
+      def validate_doc_tags_for_declaration(declaration, tags)
+        callable = declaration.respond_to?(:params) && declaration.respond_to?(:return_type)
+        param_tags = Array(tags[:params])
+        return_tag = tags[:returns]
+  
+        unless callable
+          ([*param_tags, return_tag].compact).each do |tag_entry|
+            @warnings << Warning.new(
+              path: @path,
+              line: tag_entry[:line],
+              column: tag_entry[:column],
+              length: 1,
+              code: 'doc-tag',
+              message: 'callable doc tags are only valid on function and method declarations',
+              severity: :hint,
+            )
+          end
+          return
+        end
+  
+        params = Array(declaration.params)
+        param_names = params.map(&:name)
+        param_name_set = param_names.to_set
+  
+        param_tags.each do |tag_entry|
+          next if param_name_set.include?(tag_entry[:name])
+  
+          @warnings << Warning.new(
+            path: @path,
+            line: tag_entry[:line],
+            column: tag_entry[:column],
+            length: tag_entry[:name].length,
+            code: 'doc-tag',
+            message: "doc tag @param '#{tag_entry[:name]}' does not match any parameter in '#{declaration.name}'",
+            severity: :hint,
+            symbol_name: tag_entry[:name],
+          )
+        end
+  
+        return unless return_tag
+  
+        return_type_text = declaration.return_type.to_s
+        return unless return_type_text == 'void'
+  
+        @warnings << Warning.new(
+          path: @path,
+          line: return_tag[:line],
+          column: return_tag[:column],
+          length: 7,
+          code: 'doc-tag',
+          message: "doc tag @return is stale for '#{declaration.name}' because it returns void",
+          severity: :hint,
+        )
+      end
+  
+      def doc_tag_column(line)
+        text = @source_lines[line.to_i - 1].to_s
+        at_index = text.index('@')
+        return 1 if at_index.nil?
+  
+        at_index + 1
+      end
+    end
+  end
+end

data/lib/milk_tea/tooling/linter/fix_engine.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module MilkTea
+  class Linter
+    FixEdit = Data.define(:start_line, :start_char, :end_line, :end_char, :new_text)
+
+    module FixEngine
+      module_function
+
+      def edits_for_rule(code, lines, warning)
+        case code
+        when "prefer-let"             then prefer_let_edits(lines, warning)
+        when "redundant-ignored-match-binding" then redundant_ignored_match_binding_edits(lines, warning)
+        when "prefer-let-else"        then prefer_let_else_edits(lines, warning)
+        when "prefer-var-else"        then prefer_var_else_edits(lines, warning)
+        when "redundant-bool-compare" then redundant_bool_compare_edits(lines, warning)
+        when "redundant-cast"        then redundant_cast_edits(lines, warning)
+        when "redundant-else"         then redundant_else_edits(lines, warning)
+        when "redundant-return"       then redundant_return_edits(lines, warning)
+        when "redundant-type-annotation" then redundant_type_annotation_edits(lines, warning)
+        when "unused-import"          then unused_import_edits(lines, warning)
+        when "trailing-list-comma"    then trailing_list_comma_edits(lines, warning)
+        else []
+        end
+      end
+
+      def apply_fix_edits(lines, edits)
+        edits.sort_by { |e| [-e.start_line, -e.start_char] }.reverse_each do |edit|
+          if edit.start_line == edit.end_line
+            line = lines[edit.start_line]
+            next unless line
+
+            lines[edit.start_line] = +"#{line[0...edit.start_char]}#{edit.new_text}#{line[edit.end_char..]}"
+          else
+            prefix = (l = lines[edit.start_line]) ? l[0...edit.start_char] : ""
+            suffix = (l = lines[edit.end_line]) ? l[edit.end_char..] : ""
+            lines[edit.start_line..edit.end_line] = ["#{prefix}#{edit.new_text}#{suffix}"]
+          end
+        end
+        lines
+      end
+
+      def edits_to_lsp_text_edits(edits, uri)
+        edits.map do |edit|
+          {
+            range: {
+              start: { line: edit.start_line, character: edit.start_char },
+              end:   { line: edit.end_line,   character: edit.end_char },
+            },
+            newText: edit.new_text,
+          }
+        end
+      end
+
+      # ── per-rule edit generators ──────────────────────────────────────────
+
+      def prefer_let_edits(lines, warning)
+        return [] unless warning.line
+
+        line_idx = warning.line - 1
+        original = lines[line_idx]
+        return [] unless original&.match?(/\bvar\b/)
+
+        new_line = original.sub(/\bvar\b/, "let")
+        [FixEdit.new(start_line: line_idx, start_char: 0, end_line: line_idx + 1, end_char: 0, new_text: new_line)]
+      end
+
+      def redundant_ignored_match_binding_edits(lines, warning)
+        return [] unless warning.line && warning.column
+
+        line_idx = warning.line - 1
+        line = lines[line_idx]
+        return [] unless line
+
+        span = Linter.redundant_ignored_match_binding_span(line, column: warning.column)
+        return [] unless span
+
+        [FixEdit.new(start_line: line_idx, start_char: span[:start_char], end_line: line_idx, end_char: span[:end_char], new_text: "")]
+      end
+
+      def prefer_let_else_edits(lines, warning)
+        return [] unless warning.line
+
+        fix = Linter.build_prefer_let_else_fix(lines, warning.line - 1, symbol_name: warning.symbol_name)
+        return [] unless fix
+
+        [FixEdit.new(start_line: fix[:start_line_idx], start_char: 0, end_line: fix[:end_line_idx] + 1, end_char: 0, new_text: fix[:new_text])]
+      end
+
+      def prefer_var_else_edits(lines, warning)
+        prefer_let_else_edits(lines, warning)
+      end
+
+      def redundant_bool_compare_edits(lines, warning)
+        return [] unless warning.line && warning.column && warning.length
+
+        line_idx = warning.line - 1
+        line = lines[line_idx]
+        return [] unless line
+
+        start_char = warning.column - 1
+        end_char = start_char + warning.length
+        return [] if start_char.negative? || end_char > line.length
+
+        expr_text = line[start_char...end_char]
+        replacement = Linter.redundant_bool_compare_replacement(expr_text)
+        return [] unless replacement
+
+        [FixEdit.new(start_line: line_idx, start_char:, end_line: line_idx, end_char:, new_text: replacement)]
+      end
+
+      def redundant_else_edits(lines, warning)
+        return [] unless warning.line
+
+        diag_idx = warning.line - 1
+        return [] if diag_idx.negative?
+
+        if lines[diag_idx]&.match?(/\A\s*else:\s*\z/)
+          else_idx = diag_idx
+          first_body_idx = else_idx + 1
+        else
+          first_body_idx = diag_idx
+          return [] if first_body_idx < 1
+
+          else_idx = (0...first_body_idx).to_a.reverse.find { |i| lines[i]&.match?(/\A\s*else:\s*\z/) }
+        end
+        return [] unless else_idx
+        return [] if first_body_idx >= lines.length
+
+        else_indent = lines[else_idx].match(/\A(\s*)/)[1]
+        body_indent = "#{else_indent}    "
+
+        body_end_idx = first_body_idx
+        (first_body_idx...lines.length).each do |i|
+          l = lines[i]
+          if l.chomp.empty? || l.start_with?(body_indent)
+            body_end_idx = i
+          else
+            break
+          end
+        end
+
+        new_body = lines[first_body_idx..body_end_idx].map { |l| l.sub(/\A    /, "") }.join
+        [FixEdit.new(start_line: else_idx, start_char: 0, end_line: body_end_idx + 1, end_char: 0, new_text: new_body)]
+      end
+
+      def redundant_return_edits(lines, warning)
+        return [] unless warning.line
+
+        line_idx = warning.line - 1
+        return [] unless lines[line_idx]&.match?(/\A\s*return\s*\z/)
+
+        [FixEdit.new(start_line: line_idx, start_char: 0, end_line: line_idx + 1, end_char: 0, new_text: "")]
+      end
+
+      def unused_import_edits(lines, warning)
+        return [] unless warning.line
+
+        line_idx = warning.line - 1
+        return [] unless lines[line_idx]&.match?(/\A\s*import\b/)
+
+        [FixEdit.new(start_line: line_idx, start_char: 0, end_line: line_idx + 1, end_char: 0, new_text: "")]
+      end
+
+      def trailing_list_comma_edits(lines, warning)
+        return [] unless warning.line && warning.column
+
+        line_idx = warning.line - 1
+        line = lines[line_idx]
+        return [] unless line
+
+        char_idx = warning.column - 1
+        return [] if char_idx.negative? || char_idx >= line.length
+        return [] unless line[char_idx] == ","
+
+        [FixEdit.new(start_line: line_idx, start_char: char_idx, end_line: line_idx, end_char: char_idx + 1, new_text: "")]
+      end
+
+      def redundant_type_annotation_edits(lines, warning)
+        return [] unless warning.line
+
+        line_idx = warning.line - 1
+        line = lines[line_idx]
+        return [] unless line
+
+        name_len = warning.length
+        col = warning.column - 1
+        return [] if col.negative? || col + name_len > line.length
+
+        after_name = col + name_len
+        rest = line[after_name..]
+        return [] unless rest
+
+        type_match = rest.match(/\s*:\s*\S+/)
+        return [] unless type_match
+
+        new_line = +"#{line[0...after_name]}#{rest[type_match.end(0)..]}"
+        [FixEdit.new(start_line: line_idx, start_char: 0, end_line: line_idx + 1, end_char: 0, new_text: new_line)]
+      end
+
+      def redundant_cast_edits(lines, warning)
+        return [] unless warning.line && warning.column
+
+        line_idx = warning.line - 1
+        line = lines[line_idx]
+        return [] unless line
+
+        start = warning.column - 1
+        return [] unless start >= 0 && start < line.length
+
+        # The warning column points at the cast target type. Delete the
+        # `TargetType<-` prefix, keeping the inner expression as-is. This
+        # covers both bare (`ulong<-x`) and parenthesized (`uint<-(a - b)`)
+        # forms; type refs never contain `<`, so the first `<-` at/after the
+        # column is the cast arrow.
+        arrow = line.index("<-", start)
+        return [] unless arrow
+
+        type_ref = line[start...arrow]
+        return [] unless type_ref.match?(/\A[A-Za-z_][A-Za-z0-9_\[\]\.,\s@]*\z/)
+
+        # When the cast is inside an `unsafe:` expression, also remove the
+        # `unsafe: ` wrapper. Look backward from the cast for `unsafe:`.
+        new_start = start
+        unsafe_keyword = line.rindex("unsafe:", new_start)
+        if unsafe_keyword
+          prefix = line[unsafe_keyword...new_start]
+          if prefix.match?(/\Aunsafe:\s*\z/)
+            new_start = unsafe_keyword
+          end
+        end
+
+        [FixEdit.new(start_line: line_idx, start_char: new_start, end_line: line_idx, end_char: arrow + 2, new_text: "")]
+      end
+    end
+  end
+end