protostar 0.1.0.beta1

data/lib/protostar/lint/command.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Protostar
+  module Lint
+    # `protostar lint`, the command line
+    #
+    #   protostar lint proto/                        # every *.proto under proto/, recursively
+    #   protostar lint acme/person.proto --format json
+    #   protostar lint proto/ --rules default,documentation --except FIELD_NOT_REQUIRED
+    #   protostar lint --explain FIELD_NOT_REQUIRED
+    #
+    # Exits 0 when clean, 1 with warnings (0 with --warnings-ok), 2 with
+    # errors, including mistakes on the command line.
+    class Command
+      USAGE = "Usage: protostar lint [OPTION] PROTO_FILES_OR_DIRS\n       protostar lint --explain CODE_OR_RULE"
+      FORMATS = %w[text json github].freeze
+      EXPLAIN_HINT = "For more about a code or rule, try `protostar lint --explain CODE`."
+
+      def initialize(out, err)
+        @out = out
+        @err = err
+      end
+
+      # @param argv [Array<String>]
+      # @return [Integer] the exit status
+      def run(argv)
+        opts = {}
+        inputs = parser(opts).parse(argv)
+        return explain(opts[:explain]) if opts[:explain]
+        return list_rules if opts[:list]
+        raise Error, "Missing input file or directory.\n#{USAGE}" if inputs.empty?
+        config = opts[:config] ? Config.load(opts[:config]) : Config.find(inputs)
+        rules = Lint.select(opts[:rules] || config.rules, except: (opts[:except] || []) + config.except)
+        except = ((opts[:except] || []) + config.except).map { |e| Lint.rule_id(e) }
+        format = opts.fetch(:format, "text")
+        raise Error, "Unknown format: #{format} (#{FORMATS.join(", ")})" unless FORMATS.include?(format)
+        include, names = targets(inputs, opts[:include], config)
+        raise Error, "No .proto files in #{inputs.join(", ")}." if names.empty?
+        lint = -> { Runner.new(include_paths: include, rules: rules, except: except, directives: config.allow_comment_directives?) }
+        runner = lint.call
+        result = runner.run(names)
+        changed = fix(result, runner, write: opts[:fix], show: opts[:fix] || opts[:diff],
+          diff_io: (format == "text") ? nil : @err)
+        # what is left is what the fixed files say now
+        if changed
+          runner = lint.call
+          result = runner.run(names)
+        end
+        remaining = result.diagnostics
+        show(remaining, runner, format, opts, result)
+        return 2 if remaining.any?(&:error?)
+        return 1 if remaining.any?(&:warning?) && !opts[:warnings_ok]
+        0
+      rescue Error, OptionParser::ParseError, Compiler::Error => e
+        @err.puts e.message
+        2
+      end
+
+      private
+
+      def parser(opts)
+        OptionParser.new do |o|
+          o.banner = USAGE
+          o.on("-I", "--proto_path=PATH", "Directory to resolve names and imports against; repeatable, or colon-separated") do |v|
+            (opts[:include] ||= []).concat(v.split(":"))
+          end
+          o.on("--rules=LIST", "Sets (minimal, default, strict), categories or rule ids; default: default") do |v|
+            (opts[:rules] ||= []).concat(v.split(","))
+          end
+          o.on("--except=LIST", "Rule ids or codes to leave out") { |v| (opts[:except] ||= []).concat(v.split(",")) }
+          o.on("--format=FORMAT", "text (default), json (one object per line) or github (workflow annotations)") do |v|
+            opts[:format] = v
+          end
+          o.on("--color=WHEN", %w[auto always never], "auto (default: when stdout is a terminal and NO_COLOR is unset), always, never") do |v|
+            opts[:color] = v
+          end
+          o.on("--warnings-ok", "Exit 0 when there are warnings but no errors") { opts[:warnings_ok] = true }
+          o.on("--fix", "Apply the safe fixes (renames, a missing syntax line) and print the diff") { opts[:fix] = true }
+          o.on("--diff", "Print the diff --fix would apply, change nothing") { opts[:diff] = true }
+          o.on("--config=FILE", "Read FILE instead of looking for .protostar.yml") { |v| opts[:config] = v }
+          o.on("--explain=CODE", "Explain a code (L0301) or rule (FIELD_NOT_REQUIRED, W0101)") { |v| opts[:explain] = v }
+          o.on("--list-rules", "List the rules, their codes and sets") { opts[:list] = true }
+        end
+      end
+
+      def explain(key)
+        if (entry = Diagnostics::Codes[key])
+          @out.puts "#{entry.code}: #{entry.summary}", "", entry.explanation
+          return 0
+        end
+        id = Lint.rule_id(key)
+        raise Error, "No code or rule #{key}." unless id
+        rule = Lint.rule_class(id)
+        @out.puts "#{rule.code}: #{id} (#{rule.tier} set, #{rule.category})", "", rule.reason, "", rule.explanation
+        0
+      end
+
+      def list_rules
+        RULES.each do |id, (code, tier, category)|
+          @out.puts format("%-6s %-30s %-8s %-14s %s", code, id, tier, category, Lint.rule_class(id).reason)
+        end
+        0
+      end
+
+      # Include paths and the names of the files to lint. With -I, a path on
+      # disk is named relative to the include path above it. Without, a file's
+      # directory is its include path, and a directory is the include path of
+      # the files under it.
+      def targets(inputs, include, config)
+        roots = []
+        names = []
+        inputs.each do |input|
+          raise Error, "#{input}: No such file or directory" unless ::File.exist?(input)
+          files = if ::File.directory?(input)
+            Dir.glob("**/*.proto", base: input).sort.map { |f| ::File.join(input, f) }.reject { |f| config.ignored?(f) }
+          else
+            [input]
+          end
+          files.each do |file|
+            if include
+              name = virtual(file, include)
+              raise Error, "#{file}: not under any include path (-I)" unless name
+            else
+              root = ::File.directory?(input) ? input : ::File.dirname(input)
+              roots << root
+              name = Compiler.canonical_path(::File.expand_path(file).delete_prefix("#{::File.expand_path(root)}/"))
+            end
+            names << name
+          end
+        end
+        paths = include || roots.uniq { |r| ::File.expand_path(r) }
+        [paths, names.uniq]
+      end
+
+      def virtual(file, include)
+        path = ::File.expand_path(file)
+        include.each do |dir|
+          root = ::File.expand_path(dir)
+          return path.delete_prefix("#{root}/") if path.start_with?("#{root}/")
+        end
+        nil
+      end
+
+      # The diff goes to stdout with text output, to stderr when stdout is JSON
+      # or annotations
+      def fix(result, runner, write:, show:, diff_io: nil)
+        return false unless show
+        changes = Fixer.plan(result.diagnostics, text: ->(n) { runner.text(n) },
+          path: ->(n) { result.contexts.find { |c| c.name == n }&.disk_path })
+        changes.each do |change|
+          (diff_io || @out).write(Fixer.diff(change))
+          ::File.binwrite(change.path, change.after) if write && change.path
+        end
+        write && !changes.empty?
+      end
+
+      def show(diagnostics, runner, format, opts, result)
+        sources = Hash.new { |h, name| h[name] = (text = runner.text(name)) && Diagnostics::Source.new(text) }
+        case format
+        when "json"
+          diagnostics.each { |d| @out.puts Diagnostics::Formats.json(d, source: sources[d.file]) }
+        when "github"
+          diagnostics.each { |d| @out.puts Diagnostics::Formats.github(d, source: sources[d.file]) }
+        else
+          renderer = Diagnostics::Renderer.new(color: color?(opts[:color]), source: ->(d) { runner.text(d.file) })
+          diagnostics.each { |d| @out.puts renderer.render(d) }
+          @out.puts summary(diagnostics, result)
+          @out.puts EXPLAIN_HINT unless diagnostics.empty?
+        end
+      end
+
+      def summary(diagnostics, result)
+        errors = diagnostics.count(&:error?)
+        warnings = diagnostics.count(&:warning?)
+        fixable = diagnostics.count(&:fix)
+        files = result.names.size
+        text = "#{files} #{(files == 1) ? "file" : "files"}: #{count(errors, "error")}, #{count(warnings, "warning")}"
+        text += " (#{fixable} fixable with --fix)" if fixable > 0
+        text
+      end
+
+      def count(n, word)
+        "#{n} #{word}#{"s" unless n == 1}"
+      end
+
+      def color?(setting)
+        case setting
+        when "always" then true
+        when "never" then false
+        else CLI.color?(@out)
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/config.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    # The `lint:` section of `.protostar.yml`:
+    #
+    #   lint:
+    #     rules: [default]                  # sets, categories or rule ids
+    #     except: [PACKAGE_VERSION_SUFFIX]
+    #     ignore: ["vendor/**"]             # relative to the file's directory
+    #     allow_comment_directives: true
+    class Config
+      FILE_NAME = ".protostar.yml"
+      KEYS = %w[rules except ignore allow_comment_directives].freeze
+
+      # @return [Array<String>]
+      attr_reader :rules
+      # @return [Array<String>]
+      attr_reader :except
+      # @return [Array<String>] globs
+      attr_reader :ignore
+      # @return [String] the directory `ignore` globs are relative to
+      attr_reader :root
+      # @return [String, nil] the file read, nil for the defaults
+      attr_reader :file
+
+      # The first `.protostar.yml` next to an input (a directory or a file's
+      # directory), else in the current directory, else the defaults
+      # @param inputs [Array<String>]
+      # @return [Config]
+      def self.find(inputs, cwd: Dir.pwd)
+        dirs = inputs.map { |i| ::File.directory?(i) ? i : ::File.dirname(i) } + [cwd]
+        dirs.each do |dir|
+          path = ::File.join(dir, FILE_NAME)
+          return load(path) if ::File.file?(path)
+        end
+        new({}, root: cwd)
+      end
+
+      # @param path [String]
+      # @return [Config]
+      # @raise [Error] when it is not YAML, or the `lint:` section has an unknown key
+      def self.load(path)
+        require "yaml"
+        data = YAML.safe_load_file(path) || {}
+        raise Error, "#{path}: expected a mapping" unless data.is_a?(Hash)
+        section = data.fetch("lint", {}) || {}
+        raise Error, "#{path}: `lint` must be a mapping" unless section.is_a?(Hash)
+        unknown = section.keys - KEYS
+        raise Error, "#{path}: unknown lint setting #{unknown.join(", ")} (known: #{KEYS.join(", ")})" unless unknown.empty?
+        new(section, root: ::File.dirname(::File.expand_path(path)), file: path)
+      rescue Psych::Exception => e
+        raise Error, "#{path}: #{e.message}"
+      end
+
+      def initialize(section, root:, file: nil)
+        @rules = list(section["rules"]) || ["default"]
+        @except = list(section["except"]) || []
+        @ignore = list(section["ignore"]) || []
+        @directives = section.fetch("allow_comment_directives", true) != false
+        @root = root
+        @file = file
+      end
+
+      def allow_comment_directives?
+        @directives
+      end
+
+      # @param path [String] a file found while walking a directory
+      # @return [Boolean] whether an `ignore` glob matches it or a directory above it
+      def ignored?(path)
+        return false if @ignore.empty?
+        rel = relative(::File.expand_path(path))
+        candidates = [rel]
+        dir = ::File.dirname(rel)
+        until dir == "." || dir == "/"
+          candidates << dir
+          dir = ::File.dirname(dir)
+        end
+        @ignore.any? do |glob|
+          candidates.any? { |c| ::File.fnmatch?(glob, c, ::File::FNM_PATHNAME | ::File::FNM_EXTGLOB) }
+        end
+      end
+
+      private
+
+      def list(value)
+        return nil if value.nil?
+        Array(value).flat_map { |v| v.to_s.split(",") }.map(&:strip).reject(&:empty?)
+      end
+
+      def relative(path)
+        root = ::File.expand_path(@root)
+        path.start_with?("#{root}/") ? path.delete_prefix("#{root}/") : path
+      end
+    end
+  end
+end

data/lib/protostar/lint/context.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    # What a rule sees of one compiled file: the frozen {Schema::File}, the
+    # AST with its recorded positions, the source locations with their
+    # comments, the text, and the compiler's warnings for it.
+    class Context
+      # Source paths of `FileDescriptorProto` fields the rules point at
+      PATHS = {syntax: [12], edition: [14], package: [2]}.freeze
+
+      # @return [String] the file name as imported
+      attr_reader :name
+      # @return [String, nil] the file on disk, as diagnostics print it
+      attr_reader :path
+      # @return [String, nil] the file on disk, absolute
+      attr_reader :disk_path
+      # @return [Schema::File]
+      attr_reader :file
+      # @return [Compiler::AST::File]
+      attr_reader :ast
+      # @return [String] the file's bytes
+      attr_reader :text
+      # @return [Array<Compiler::Diagnostic>] the compiler's warnings for the file
+      attr_reader :warnings
+      # @return [Array<Context>] every file of the lint run, this one included
+      attr_reader :all
+
+      # @param linker [Compiler::Linker] the linker that built the file
+      def initialize(name:, path:, disk_path:, linker:, text:, warnings:, all:)
+        @name = name
+        @path = path
+        @disk_path = disk_path
+        @linker = linker
+        @file = linker.file
+        @ast = linker.ast
+        @text = text
+        @warnings = warnings
+        @all = all
+        @extents = {}
+        @ast.locations.each do |loc|
+          span = loc.span
+          next if span.size < 3
+          finish = (span.size == 4) ? [span[2], span[3]] : [span[0], span[2]]
+          key = [span[0], span[1]]
+          @extents[key] = finish if @extents[key].nil? || (finish <=> @extents[key]) < 0
+        end
+        @by_path = {}
+        @linker.locations.each { |loc| @by_path[loc.path] ||= loc }
+      end
+
+      # @return [Diagnostics::Source]
+      def source
+        @source ||= Diagnostics::Source.new(@text)
+      end
+
+      # Every element of a kind, as protoc visits them, without the map entry
+      # messages and synthetic oneofs the compiler made up
+      # @param kind [Symbol] :message, :field, :oneof, :enum, :enum_value, :service or :method
+      # @yieldparam node [Compiler::AST::Node]
+      # @yieldparam descriptor [Schema::Descriptor]
+      def each(kind)
+        @linker.each_element do |node, k|
+          next unless k == kind
+          descriptor = @linker.descriptor_of(node)
+          next if synthetic?(node, kind, descriptor)
+          yield node, descriptor
+        end
+      end
+
+      # @return [Schema::Descriptor] what the compiler built for a node
+      def descriptor(node)
+        @linker.descriptor_of(node)
+      end
+
+      # @param node [Compiler::AST::Node]
+      # @param kind [Symbol] a position kind the parser recorded: :name, :number, :type, ...
+      # @return [Diagnostics::Span, nil] from the position to the end of the element that starts there
+      def span(node, kind, label: nil, primary: true)
+        line, column = node.position(kind)
+        # oneofs record no position; every element's name is field 1 of its descriptor
+        return span_at(node.path + [1], label: label, primary: primary) if line.nil? && kind == :name && node.path
+        return nil unless line
+        end_line, end_column = @extents[[line, column]]
+        Diagnostics::Span.new(line + 1, column + 1, end_line && end_line + 1, end_column && end_column + 1,
+          label: label, primary: primary)
+      end
+
+      # @param path [Array<Integer>] a source path, e.g. [3, 0] for the first import
+      # @return [Diagnostics::Span, nil] the span of the first location with that path
+      def span_at(path, label: nil, primary: true)
+        loc = @by_path[path]
+        return nil unless loc
+        s = loc.span
+        end_line = (s.size == 4) ? s[2] : s[0]
+        Diagnostics::Span.new(s[0] + 1, s[1] + 1, end_line + 1, s.last + 1, label: label, primary: primary)
+      end
+
+      # @return [String, nil] the leading comment of an element, or its trailing
+      #   one, stripped; nil when it has none
+      def comment(node)
+        loc = node.path && @by_path[node.path]
+        return nil unless loc
+        [loc.leading_comments, loc.trailing_comments].compact.map(&:strip).find { |c| !c.empty? }
+      end
+
+      # Whether renaming `from` to `to` is safe to do mechanically: `from` is
+      # written once in the file, as the declaration, and `to` nowhere
+      def renamable?(from, to)
+        @words ||= @text.b.scan(/[A-Za-z_][A-Za-z0-9_]*/).tally
+        @words[from.b] == 1 && !@words.key?(to.b)
+      end
+
+      private
+
+      def synthetic?(node, kind, descriptor)
+        case kind
+        when :message then descriptor.map_entry?
+        when :oneof then descriptor.synthetic?
+        when :field then descriptor.containing_message&.map_entry? || false
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/directives.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    # Comments that switch rules off for part of a file:
+    #
+    #   // protostar-lint: disable-next-line FIELD_NOT_REQUIRED
+    #   required string id = 1;
+    #
+    #   // protostar-lint: disable COMMENT_FIELD, COMMENT_MESSAGE
+    #   ...
+    #   // protostar-lint: enable COMMENT_FIELD, COMMENT_MESSAGE
+    #
+    # A directive names rule ids or codes (a compiler warning's code works
+    # too), or none for every rule. `disable` without `enable` runs to the end
+    # of the file. Directives are read from the text line by line.
+    class Directives
+      PATTERN = %r{//\s*protostar-lint:\s*(disable-next-line|disable|enable)\b([^\n]*)}
+
+      # @param text [String] the file's bytes
+      def initialize(text)
+        @next_line = Hash.new { |h, k| h[k] = [] }
+        @ranges = []
+        open = {}
+        lines = text.b.split("\n", -1)
+        lines.each_with_index do |line, i|
+          match = PATTERN.match(line)
+          next unless match
+          names = match[2].split(/[\s,]+/).reject(&:empty?).map(&:upcase)
+          names = [:all] if names.empty?
+          number = i + 1
+          case match[1]
+          when "disable-next-line" then names.each { |n| @next_line[number + 1] << n }
+          when "disable" then names.each { |n| open[n] ||= number }
+          when "enable"
+            ((names == [:all]) ? open.keys : names).each do |n|
+              start = open.delete(n) || open.delete(:all)
+              @ranges << [n, start, number] if start
+            end
+          end
+        end
+        open.each { |n, start| @ranges << [n, start, lines.size + 1] }
+      end
+
+      # @param diagnostic [Compiler::Diagnostic]
+      # @return [Boolean] whether a directive switches it off where it starts
+      def suppressed?(diagnostic)
+        line = diagnostic.line
+        return false unless line
+        keys = [diagnostic.rule, diagnostic.code, :all].compact
+        return true if @next_line.key?(line) && @next_line[line].any? { |n| keys.include?(n) }
+        @ranges.any? { |n, from, to| keys.include?(n) && line > from && line < to }
+      end
+    end
+  end
+end

data/lib/protostar/lint/fixer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    # Applies the {Diagnostics::Fix}es lint findings carry, file by file. An
+    # edit that overlaps one already taken is left out (the finding stays
+    # unfixed), so the result never depends on two fixes agreeing.
+    class Fixer
+      CONTEXT = 3
+
+      # The fixes for one file
+      class Change
+        # @return [String] the file name as imported
+        attr_reader :name
+        # @return [String, nil] where it is on disk
+        attr_reader :path
+        # @return [String]
+        attr_reader :before
+        # @return [String]
+        attr_reader :after
+        # @return [Array<Compiler::Diagnostic>] the findings fixed
+        attr_reader :fixed
+
+        def initialize(name, path, before, after, fixed)
+          @name = name
+          @path = path
+          @before = before
+          @after = after
+          @fixed = fixed.freeze
+          freeze
+        end
+      end
+
+      # @param diagnostics [Array<Compiler::Diagnostic>]
+      # @param text [#call] the text of a file, by name
+      # @param path [#call] where a file is on disk, by name, or nil
+      # @return [Array<Change>] one per file with a fix
+      def self.plan(diagnostics, text:, path:)
+        diagnostics.select(&:fix).group_by(&:file).filter_map do |name, found|
+          before = text.call(name)
+          next unless before
+          taken = []
+          fixed = found.select do |d|
+            edits = d.fix.edits
+            next false if edits.any? { |e| taken.any? { |t| overlap?(e, t) } }
+            taken.concat(edits)
+            true
+          end
+          after = Diagnostics::Source.new(before).apply(before, taken)
+          Change.new(name, path.call(name), before, after, fixed)
+        end
+      end
+
+      def self.overlap?(a, b)
+        a_start = [a.line, a.column]
+        a_end = [a.end_line, a.end_column]
+        b_start = [b.line, b.column]
+        b_end = [b.end_line, b.end_column]
+        return a_start == b_start if a_start == a_end || b_start == b_end
+        (a_start <=> b_end) < 0 && (b_start <=> a_end) < 0
+      end
+      private_class_method :overlap?
+
+      # @param change [Change]
+      # @return [String] a unified diff, as `diff -u` prints it
+      def self.diff(change)
+        old_lines = change.before.split(/(?<=\n)/)
+        new_lines = change.after.split(/(?<=\n)/)
+        label = change.path || change.name
+        old_label, new_label = label.start_with?("/") ? [label, label] : ["a/#{label}", "b/#{label}"]
+        out = "--- #{old_label}\n+++ #{new_label}\n"
+        hunks(old_lines, new_lines).each do |os, oe, ns, ne|
+          out << "@@ -#{range(os, oe)} +#{range(ns, ne)} @@\n"
+          i = os
+          j = ns
+          while i < oe || j < ne
+            if i < oe && j < ne && old_lines[i] == new_lines[j]
+              out << " " << terminated(old_lines[i])
+              i += 1
+              j += 1
+            else
+              changed_old, changed_new = block(old_lines, new_lines, i, j, oe, ne)
+              changed_old.each { |l| out << "-" << terminated(l) }
+              changed_new.each { |l| out << "+" << terminated(l) }
+              i += changed_old.size
+              j += changed_new.size
+            end
+          end
+        end
+        out
+      end
+
+      # The lines that differ, as aligned runs: lint's edits change lines in
+      # place or insert whole lines, so a run ends where the two sides meet again
+      def self.block(old_lines, new_lines, i, j, oe, ne)
+        (0..[oe - i, ne - j].max).each do |skip|
+          (0..skip).each do |a|
+            b = skip - a
+            next if i + a > oe || j + b > ne
+            if (i + a == oe && j + b == ne) || (i + a < oe && j + b < ne && old_lines[i + a] == new_lines[j + b])
+              return [old_lines[i, a], new_lines[j, b]] if a + b > 0
+            end
+          end
+        end
+        [old_lines[i...oe], new_lines[j...ne]]
+      end
+      private_class_method :block
+
+      # Hunks as [old start, old end, new start, new end], 0-based, ends exclusive
+      def self.hunks(old_lines, new_lines)
+        prefix = 0
+        prefix += 1 while prefix < old_lines.size && prefix < new_lines.size && old_lines[prefix] == new_lines[prefix]
+        suffix = 0
+        while suffix < old_lines.size - prefix && suffix < new_lines.size - prefix &&
+            old_lines[-1 - suffix] == new_lines[-1 - suffix]
+          suffix += 1
+        end
+        return [] if prefix == old_lines.size && prefix == new_lines.size
+        changes = []
+        i = prefix
+        j = prefix
+        oe = old_lines.size - suffix
+        ne = new_lines.size - suffix
+        while i < oe || j < ne
+          if i < oe && j < ne && old_lines[i] == new_lines[j]
+            i += 1
+            j += 1
+            next
+          end
+          a, b = block(old_lines, new_lines, i, j, oe, ne)
+          changes << [i, i + a.size, j, j + b.size]
+          i += a.size
+          j += b.size
+        end
+        merged = []
+        changes.each do |os, oe2, ns, ne2|
+          if merged.any? && os - merged.last[1] <= 2 * CONTEXT
+            merged.last[1] = oe2
+            merged.last[3] = ne2
+          else
+            merged << [os, oe2, ns, ne2]
+          end
+        end
+        merged.map do |os, oe2, ns, ne2|
+          before = [CONTEXT, os].min
+          after = [CONTEXT, old_lines.size - oe2].min
+          [os - before, oe2 + after, ns - before, ne2 + after]
+        end
+      end
+      private_class_method :hunks
+
+      def self.range(start, finish)
+        count = finish - start
+        first = count.zero? ? start : start + 1
+        (count == 1) ? first.to_s : "#{first},#{count}"
+      end
+      private_class_method :range
+
+      def self.terminated(line)
+        line.end_with?("\n") ? line : "#{line}\n\\n"
+      end
+      private_class_method :terminated
+    end
+  end
+end