protostar 0.1.0.beta1

data/lib/protostar/diagnostics/formats.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Protostar
+  module Diagnostics
+    # Diagnostics for machines: one JSON object per diagnostic (JSON Lines),
+    # or GitHub Actions workflow commands, which annotate the lines of a pull
+    # request.
+    module Formats
+      # @param diagnostic [Compiler::Diagnostic]
+      # @param source [Source, nil] the file's text, to find where spans end
+      # @return [Hash] code, severity, message, file, path, line, column, spans,
+      #   help, notes, fix and rule; the message is the short title, `protoc` the
+      #   compiler's own wording when that differs
+      def self.record(diagnostic, source: nil)
+        d = diagnostic.annotated
+        spans = d.spans
+        spans = [Span.new(d.line, d.column)] if spans.empty? && d.line
+        spans = spans.map { |s| source.resolve(s) } if source
+        out = {code: d.code, severity: d.severity.to_s, message: d.title}
+        out[:protoc] = d.message if d.title != d.message
+        out.merge!(file: d.file, path: d.path, line: d.line, column: d.column, spans: spans.map(&:to_h),
+          help: d.help, notes: d.notes, fix: d.fix&.to_h, rule: d.rule)
+        out
+      end
+
+      # @return [String] one line of JSON
+      def self.json(diagnostic, source: nil)
+        ::JSON.generate(record(diagnostic, source: source))
+      end
+
+      # @return [String] an `::error` or `::warning` workflow command
+      def self.github(diagnostic, source: nil)
+        d = diagnostic.annotated
+        props = {"file" => d.path || d.file}
+        if d.line
+          span = d.spans.first || Span.new(d.line, d.column)
+          span = source.resolve(span) if source
+          props["line"] = span.line
+          props["col"] = span.column
+          if span.end_line
+            props["endLine"] = span.end_line
+            props["endColumn"] = span.end_column
+          end
+        end
+        props["title"] = d.code if d.code
+        text = [d.title, *d.help.map { |h| "help: #{h}" }, *d.notes.map { |n| "note: #{n}" }]
+        text << "fix: #{d.fix.description}" if d.fix
+        kind = d.error? ? "error" : "warning"
+        "::#{kind} #{props.map { |k, v| "#{k}=#{escape_property(v.to_s)}" }.join(",")}::#{escape_data(text.join("\n"))}"
+      end
+
+      def self.escape_data(text)
+        text.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+      end
+
+      def self.escape_property(text)
+        escape_data(text).gsub(":", "%3A").gsub(",", "%2C")
+      end
+      private_class_method :escape_data, :escape_property
+    end
+  end
+end

data/lib/protostar/diagnostics/renderer.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Diagnostics
+    # Prints a {Compiler::Diagnostic} the way rustc prints its own:
+    #
+    #   error[L0301]: field number 1 is already used in `p.A`
+    #    --> link.proto:5:15
+    #     |
+    #   4 |   Missing m = 1;
+    #     |               - first used by `m`
+    #   5 |   int32 dup = 1;
+    #     |               ^ reused here
+    #     |
+    #     = help: the next available field number is 2
+    #
+    # The primary span gets carets, related spans dashes, each with its label;
+    # a span over several lines is drawn down the left margin. Without the
+    # source, only the header, location and the `help:` and `note:` lines print.
+    class Renderer
+      COLORS = {
+        error: "\e[1;31m", warning: "\e[1;33m", secondary: "\e[1;34m", gutter: "\e[1;34m", bold: "\e[1m",
+        help: "\e[1;36m", reset: "\e[0m"
+      }.freeze
+      # Lines of a multi-line span shown between its first and last before `...`
+      INNER_LINES = 3
+
+      # @param color [Boolean] ANSI colours, for a terminal
+      # @param source [#call, nil] given the diagnostic, returns its file's text (or nil)
+      def initialize(color: false, source: nil)
+        @color = color
+        @source = source
+        @texts = {}
+      end
+
+      # @param diagnostic [Compiler::Diagnostic]
+      # @return [String] the rendered diagnostic, ending in a newline
+      def render(diagnostic)
+        d = diagnostic.annotated
+        out = +""
+        out << header(d) << "\n"
+        source = source_for(d)
+        spans = d.line ? spans_of(d, source) : []
+        width = [*spans.flat_map { |s| [s.line, s.end_line] }, d.line || 0].max.to_s.size
+        pad = " " * width
+        if d.line
+          out << "#{pad}#{paint("-->", :gutter)} #{d.path || d.file}:#{d.line}:#{d.column}\n"
+        elsif d.file
+          out << "#{pad}#{paint("-->", :gutter)} #{d.path || d.file}\n"
+        end
+        if source && !spans.empty?
+          out << "#{pad} #{paint("|", :gutter)}\n"
+          snippet(out, source, spans, d.severity, width)
+        end
+        footer = d.help.map { |h| ["help", h] } + d.notes.map { |n| ["note", n] }
+        footer << ["fix", d.fix.description] if d.fix
+        unless footer.empty?
+          out << "#{pad} #{paint("|", :gutter)}\n" if source && !spans.empty?
+          footer.each do |kind, text|
+            first, *rest = text.split("\n")
+            out << "#{pad} #{paint("=", :gutter)} #{paint("#{kind}:", (kind == "note") ? :bold : :help)} #{first}\n"
+            rest.each { |line| out << "#{pad}   #{" " * (kind.size + 2)}#{line}\n" }
+          end
+        end
+        out
+      end
+
+      # @param diagnostic [Compiler::Diagnostic]
+      # @return [Source, nil]
+      def source_for(diagnostic)
+        return nil unless @source && diagnostic.file
+        key = diagnostic.path || diagnostic.file
+        return @texts[key] if @texts.key?(key)
+        text = @source.call(diagnostic)
+        @texts[key] = text && Source.new(text)
+      end
+
+      private
+
+      def header(d)
+        label = d.error? ? "error" : "warning"
+        label += "[#{d.code}]" if d.code
+        "#{paint(label, d.severity)}#{paint(": #{d.title}", :bold)}"
+      end
+
+      def paint(text, kind)
+        return text unless @color
+        "#{COLORS.fetch(kind)}#{text}#{COLORS[:reset]}"
+      end
+
+      def spans_of(d, source)
+        spans = d.spans.empty? ? [Span.new(d.line, d.column)] : d.spans
+        return spans unless source
+        spans.map do |span|
+          span = source.resolve(span)
+          next span if span.end_line > span.line || span.end_column > span.column
+          Span.new(span.line, span.column, span.line, span.column + 1, label: span.label, primary: span.primary?)
+        end
+      end
+
+      # One underline on one line, in display columns
+      class Mark
+        attr_reader :start, :finish, :primary, :label
+
+        def initialize(start, finish, primary, label)
+          @start = start
+          @finish = finish
+          @primary = primary
+          @label = label
+        end
+      end
+
+      def snippet(out, source, spans, severity, width)
+        multi = spans.find { |s| s.end_line > s.line }
+        multi = nil if multi && multi.end_line > source.size + 1
+        marks = Hash.new { |h, k| h[k] = [] }
+        spans.each do |span|
+          next if span.equal?(multi)
+          finish = (span.end_line == span.line) ? span.end_column : source.end_column(span.line)
+          start = source.display_column(span.line, span.column)
+          stop = [source.display_column(span.line, finish), start + 1].max
+          marks[span.line] << Mark.new(start, stop, span.primary?, span.label)
+        end
+        shown = marks.keys
+        if multi
+          inner = ((multi.line + 1)...multi.end_line).to_a
+          inner = inner.first(INNER_LINES) + [nil] if inner.size > INNER_LINES + 1
+          shown += [multi.line, multi.end_line] + inner.compact
+        end
+        shown = shown.uniq.sort
+        margin = multi ? 2 : 0
+        prev = nil
+        shown.each do |line|
+          if prev && line > prev + 1
+            if line == prev + 2
+              source_line(out, source, prev + 1, width, gutter_margin(multi, prev + 1, source, severity), margin)
+            else
+              out << "#{paint("...", :gutter)}\n"
+            end
+          end
+          source_line(out, source, line, width, gutter_margin(multi, line, source, severity), margin)
+          if multi && line == multi.line && !slash_start?(multi, source)
+            col = source.display_column(line, multi.column)
+            row = " #{paint("_" * col + marker(multi), multi.primary? ? severity : :secondary)}"
+            out << "#{" " * width} #{paint("|", :gutter)} #{row}\n"
+          end
+          marks[line].empty? || annotate(out, marks[line], width, inside?(multi, line) ? :bar : :blank, severity, margin)
+          if multi && line == multi.end_line
+            last = [source.display_column(line, multi.end_column) - 1, 1].max
+            kind = multi.primary? ? severity : :secondary
+            row = paint("|#{"_" * last}#{marker(multi)}", kind)
+            row += " #{paint(multi.label, kind)}" if multi.label
+            out << "#{" " * width} #{paint("|", :gutter)} #{row}\n"
+          end
+          prev = line
+        end
+      end
+
+      def slash_start?(multi, source)
+        source.first_column(multi.line) == multi.column
+      end
+
+      def inside?(multi, line)
+        multi && line > multi.line && line <= multi.end_line
+      end
+
+      def gutter_margin(multi, line, source, severity)
+        return "" unless multi
+        kind = multi.primary? ? severity : :secondary
+        if line == multi.line
+          slash_start?(multi, source) ? paint("/", kind) + " " : "  "
+        elsif line > multi.line && line <= multi.end_line
+          paint("|", kind) + " "
+        else
+          "  "
+        end
+      end
+
+      def marker(span)
+        span.primary? ? "^" : "-"
+      end
+
+      def source_line(out, source, line, width, margin_text, margin)
+        text = source.display(line)
+        number = paint(line.to_s.rjust(width), :gutter)
+        body = margin.zero? ? text : margin_text + text
+        out << "#{number} #{paint("|", :gutter)}#{" #{body}" unless body.empty?}\n"
+      end
+
+      # The underline row, and below it the labels that do not fit at its end,
+      # each hanging from its span by a `|`
+      def annotate(out, marks, width, margin_kind, severity, margin)
+        marks = marks.sort_by { |m| [m.start, m.primary ? 1 : 0] }
+        prefix = "#{" " * width} #{paint("|", :gutter)} "
+        lead = if margin.zero?
+          ""
+        else
+          (margin_kind == :bar) ? paint("|", severity) + " " : "  "
+        end
+        cells = Array.new(marks.map(&:finish).max - 1, " ")
+        kinds = Array.new(cells.size)
+        marks.each do |m|
+          (m.start...m.finish).each do |c|
+            next if kinds[c - 1] && !m.primary
+            cells[c - 1] = m.primary ? "^" : "-"
+            kinds[c - 1] = m.primary ? severity : :secondary
+          end
+        end
+        labelled = marks.select(&:label)
+        last = labelled.max_by(&:start)
+        row = paint_cells(cells, kinds)
+        row += " #{paint(last.label, last.primary ? severity : :secondary)}" if last && last.start == marks.map(&:start).max
+        out << "#{prefix}#{lead}#{row.rstrip}\n"
+        hanging = labelled.reject { |m| m.equal?(last) && last.start == marks.map(&:start).max }.sort_by(&:start)
+        until hanging.empty?
+          connectors = Array.new(hanging.last.start, " ")
+          ckinds = Array.new(connectors.size)
+          hanging.each do |m|
+            connectors[m.start - 1] = "|"
+            ckinds[m.start - 1] = m.primary ? severity : :secondary
+          end
+          out << "#{prefix}#{lead}#{paint_cells(connectors, ckinds).rstrip}\n"
+          m = hanging.pop
+          labels = Array.new(m.start - 1, " ")
+          lkinds = Array.new(labels.size)
+          hanging.each do |h|
+            labels[h.start - 1] = "|"
+            lkinds[h.start - 1] = h.primary ? severity : :secondary
+          end
+          out << "#{prefix}#{lead}#{paint_cells(labels, lkinds)}#{paint(m.label, m.primary ? severity : :secondary)}\n"
+        end
+      end
+
+      def paint_cells(cells, kinds)
+        return cells.join unless @color
+        cells.each_with_index.map { |c, i| (kinds[i] && c != " ") ? paint(c, kinds[i]) : c }.join
+      end
+    end
+  end
+end

data/lib/protostar/diagnostics/source.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Diagnostics
+    # The text of one `.proto` file, read the way protoc counts positions:
+    # 1-based lines, columns in bytes with a tab advancing to the next
+    # multiple of 8. Maps those columns to what a terminal shows, finds the
+    # token at a position, and applies {Edit}s.
+    class Source
+      TAB_WIDTH = 8
+      TOKEN = /\A(?:[A-Za-z_][A-Za-z0-9_]*|0[xX][0-9A-Fa-f]+|[0-9]+(?:\.[0-9]*)?(?:[eE][+-]?[0-9]+)?[A-Za-z]?|
+        \.[0-9]+(?:[eE][+-]?[0-9]+)?|"(?:[^"\\]|\\.)*"?|'(?:[^'\\]|\\.)*'?)/x
+
+      # @return [Array<String>] the lines, without their line ends, as UTF-8
+      attr_reader :lines
+
+      # @param text [String] the file's bytes
+      def initialize(text)
+        utf8 = text.dup.force_encoding(Encoding::UTF_8)
+        utf8 = utf8.scrub("?") unless utf8.valid_encoding?
+        @lines = utf8.split("\n", -1).map { |l| l.delete_suffix("\r") }
+        @lines.pop if @lines.size > 1 && @lines.last.empty?
+      end
+
+      # @param number [Integer] 1-based; past the end is an empty line, where
+      #   protoc reports errors at the end of input
+      # @return [String]
+      def line(number)
+        @lines.fetch(number - 1, "")
+      end
+
+      # @return [Integer] the number of lines
+      def size
+        @lines.size
+      end
+
+      # @return [String] the line as shown: tabs expanded to the columns protoc counts
+      def display(number)
+        out = +""
+        each_char(number) { |char, _, width, _| out << ((char == "\t") ? " " * width : char) }
+        out
+      end
+
+      # @param number [Integer] 1-based line
+      # @param column [Integer] 1-based protoc column
+      # @return [Integer] the 1-based column a terminal shows it at
+      def display_column(number, column)
+        target = column - 1
+        last_protoc = 0
+        last_display = 0
+        each_char(number) do |char, protoc, width, display|
+          if target < protoc + ((char == "\t") ? width : char.bytesize)
+            return display + 1 + ((char == "\t") ? target - protoc : 0)
+          end
+          last_protoc = protoc + ((char == "\t") ? width : char.bytesize)
+          last_display = display + ((char == "\t") ? width : 1)
+        end
+        last_display + (target - last_protoc) + 1
+      end
+
+      # @return [Integer] the 1-based protoc column just past the token starting at
+      #   the position (one character when no token starts there)
+      def token_end(number, column)
+        text = line(number)
+        index = char_index(number, column)
+        return column + 1 if index.nil? || index >= text.size
+        rest = text[index..]
+        token = rest[TOKEN] || rest[0]
+        column + token.bytesize
+      end
+
+      # @return [Integer, nil] the 1-based column of the first character that is not
+      #   whitespace, nil on a blank line
+      def first_column(number)
+        each_char(number) { |char, protoc, _, _| return protoc + 1 unless char.match?(/\s/) }
+        nil
+      end
+
+      # @return [Integer] the 1-based column just past the last character
+      def end_column(number)
+        protoc = 0
+        each_char(number) { |char, at, width, _| protoc = at + ((char == "\t") ? width : char.bytesize) }
+        protoc + 1
+      end
+
+      # @return [Span] with its end filled in: the token at its start when unknown
+      def resolve(span)
+        return span if span.end_line
+        Span.new(span.line, span.column, span.line, token_end(span.line, span.column), label: span.label,
+          primary: span.primary?)
+      end
+
+      # @param edits [Array<Edit>] on this text, not overlapping
+      # @return [String] the text with the edits made, line ends as they were
+      def apply(text, edits)
+        out = text.dup.force_encoding(Encoding::UTF_8)
+        starts = line_starts(out)
+        edits.sort_by { |e| [e.line, e.column] }.reverse_each do |edit|
+          from = offset(out, starts, edit.line, edit.column)
+          to = offset(out, starts, edit.end_line, edit.end_column)
+          out = out.byteslice(0, from) + edit.text + out.byteslice(to..)
+        end
+        out
+      end
+
+      private
+
+      def each_char(number)
+        protoc = 0
+        display = 0
+        line(number).each_char do |char|
+          width = (char == "\t") ? TAB_WIDTH - protoc % TAB_WIDTH : 1
+          yield char, protoc, width, display
+          protoc += (char == "\t") ? width : char.bytesize
+          display += width
+        end
+      end
+
+      def char_index(number, column)
+        target = column - 1
+        index = 0
+        each_char(number) do |char, protoc, width, _|
+          return index if target < protoc + ((char == "\t") ? width : char.bytesize)
+          index += 1
+        end
+        index
+      end
+
+      def line_starts(text)
+        bytes = text.b
+        starts = [0]
+        while (nl = bytes.index("\n", starts.last))
+          starts << nl + 1
+        end
+        starts
+      end
+
+      # The byte offset of a protoc position in the text
+      def offset(text, starts, number, column)
+        start = starts.fetch(number - 1) { return text.bytesize }
+        target = column - 1
+        protoc = 0
+        bytes = 0
+        line(number).each_char do |char|
+          return start + bytes if protoc >= target
+          protoc += (char == "\t") ? TAB_WIDTH - protoc % TAB_WIDTH : char.bytesize
+          bytes += char.bytesize
+        end
+        start + bytes
+      end
+    end
+  end
+end

data/lib/protostar/diagnostics.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Protostar
+  # Diagnostics the way `rustc` prints them: the source line with the span
+  # underlined, related spans with their own labels, `help:` and `note:`
+  # lines, a code that `protostar lint --explain` looks up, and fixes. Both
+  # the compiler's errors ({Compiler::Diagnostic}) and lint findings render
+  # through here.
+  #
+  #   renderer = Protostar::Diagnostics::Renderer.new(source: ->(name) { File.read(name) })
+  #   puts renderer.render(diagnostic)
+  #
+  # Lines and columns are 1-based and count as protoc counts them: bytes, a
+  # tab advancing to the next multiple of 8.
+  module Diagnostics
+    autoload :Codes, ::File.expand_path("diagnostics/codes", __dir__)
+    autoload :Source, ::File.expand_path("diagnostics/source", __dir__)
+    autoload :Renderer, ::File.expand_path("diagnostics/renderer", __dir__)
+    autoload :Formats, ::File.expand_path("diagnostics/formats", __dir__)
+
+    # A stretch of source a diagnostic points at
+    class Span
+      # @return [Integer] 1-based
+      attr_reader :line
+      # @return [Integer] 1-based
+      attr_reader :column
+      # @return [Integer, nil] 1-based; nil when only the start is known, which
+      #   renders as the token at the start
+      attr_reader :end_line
+      # @return [Integer, nil] 1-based, just past the last character
+      attr_reader :end_column
+      # @return [String, nil] printed next to the underline
+      attr_reader :label
+
+      def initialize(line, column, end_line = nil, end_column = nil, label: nil, primary: true)
+        @line = line
+        @column = column
+        @end_line = end_line
+        @end_column = end_column
+        @label = label
+        @primary = primary
+        freeze
+      end
+
+      # The primary span gets the carets, the others dashes
+      def primary?
+        @primary
+      end
+
+      # @return [Span] the same span with another label
+      def with_label(label)
+        Span.new(@line, @column, @end_line, @end_column, label: label, primary: @primary)
+      end
+
+      # @return [Hash]
+      def to_h
+        {line: @line, column: @column, end_line: @end_line, end_column: @end_column, label: @label, primary: @primary}
+      end
+
+      def ==(other)
+        other.is_a?(Span) && other.to_h == to_h
+      end
+      alias_method :eql?, :==
+
+      def hash
+        to_h.hash
+      end
+    end
+
+    # One replacement in a file
+    class Edit
+      # @return [Integer] 1-based
+      attr_reader :line
+      # @return [Integer] 1-based
+      attr_reader :column
+      # @return [Integer]
+      attr_reader :end_line
+      # @return [Integer] 1-based, just past the replaced text; equal to {#column} to insert
+      attr_reader :end_column
+      # @return [String]
+      attr_reader :text
+
+      def initialize(line, column, end_line, end_column, text)
+        @line = line
+        @column = column
+        @end_line = end_line
+        @end_column = end_column
+        @text = text.frozen? ? text : text.dup.freeze
+        freeze
+      end
+
+      # @return [Hash]
+      def to_h
+        {line: @line, column: @column, end_line: @end_line, end_column: @end_column, text: @text}
+      end
+    end
+
+    # A mechanical fix: what it does, in words, and the edits that do it
+    class Fix
+      # @return [String] e.g. "rename `colorRed` to `color_red`"
+      attr_reader :description
+      # @return [Array<Edit>]
+      attr_reader :edits
+
+      def initialize(description, edits)
+        @description = description
+        @edits = edits.freeze
+        freeze
+      end
+
+      # @return [Hash]
+      def to_h
+        {description: @description, edits: @edits.map(&:to_h)}
+      end
+    end
+  end
+end