remlint 0.1.0

data/lib/remlint/cli.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "config"
+require_relative "formatter"
+require_relative "rules"
+require_relative "runner"
+require_relative "version"
+
+module RemLint
+  # The `remlint` command.
+  #
+  # Streams are injected rather than assumed, so the whole command is testable
+  # without shelling out or capturing `$stdout`.
+  class CLI
+    EXIT_SUCCESS = 0
+    EXIT_OFFENSES = 1
+    EXIT_USAGE = 2
+
+    DEFAULT_PATHS = ["."].freeze
+
+    Options = Struct.new(
+      :paths,
+      :config_path,
+      :only,
+      :format,
+      :fail_level,
+      keyword_init: true,
+    )
+
+    attr_reader :out, :err
+
+    def initialize(out: $stdout, err: $stderr)
+      @out = out
+      @err = err
+    end
+
+    def call(argv)
+      options = Options.new(
+        paths:       [],
+        config_path: nil,
+        only:        nil,
+        format:      Formatter::DEFAULT_TEMPLATE,
+        fail_level:  "warning",
+      )
+
+      dispatch(parse(argv, options), options)
+    rescue OptionParser::ParseError => error
+      err.puts(error.message)
+      EXIT_USAGE
+    end
+
+    private
+
+      # `parse` returns a symbol for the flags that do something instead of
+      # linting, and nil for an ordinary run.
+      def dispatch(action, options)
+        case action
+        when :version     then print_version
+        when :help        then EXIT_SUCCESS
+        when :show_rules  then print_rules
+        when :show_config then print_config(options)
+        else lint(options)
+        end
+      end
+
+      def parse(argv, options)
+        action = nil
+
+        parser(options) { |chosen| action = chosen }.parse!(argv)
+        options.paths = paths_from(argv)
+
+        action
+      end
+
+      # No paths means the working directory, the way every other linter reads
+      # a bare invocation.
+      def paths_from(argv)
+        if argv.empty?
+          DEFAULT_PATHS.dup
+        else
+          argv
+        end
+      end
+
+      def parser(options)
+        OptionParser.new do |parser|
+          parser.banner = "Usage: remlint [options] [path...]"
+
+          parser.on("-c", "--config PATH", "Configuration file (default: nearest .remlint.yml)") do |path|
+            options.config_path = path
+          end
+
+          parser.on(
+            "-o",
+            "--only RULES",
+            Array,
+            "Run only these rules",
+          ) do |rules|
+            options.only = rules
+          end
+
+          parser.on("-f", "--format TEMPLATE", "Output template with %{path} %{line} %{column} %{severity} %{rule} %{message}") do |template|
+            options.format = template
+          end
+
+          parser.on("--fail-level LEVEL", SEVERITIES, "Exit non-zero at this severity or worse (default: warning)") do |level|
+            options.fail_level = level
+          end
+
+          parser.on("--show-rules", "List the rules and whether they are on") { yield :show_rules }
+          parser.on("--show-config", "Print the configuration in effect") { yield :show_config }
+          parser.on("-v", "--version", "Print the version") { yield :version }
+
+          parser.on("-h", "--help", "Print this message") do
+            out.puts(parser.help)
+            yield :help
+          end
+        end
+      end
+
+      def lint(options)
+        runner = Runner.new(resolve_config(options))
+        offenses = runner.run(options.paths)
+
+        out.print(Formatter.new(template: options.format).render(offenses))
+        runner.warnings.each { |warning| err.puts("remlint: #{warning}") }
+
+        exit_code(offenses, options.fail_level)
+      end
+
+      def resolve_config(options)
+        base = base_config(options)
+
+        if options.only
+          base.only(options.only)
+        else
+          base
+        end
+      end
+
+      def base_config(options)
+        if options.config_path
+          Config.load_file(options.config_path)
+        else
+          Config.discover
+        end
+      end
+
+      # Offences below the threshold are reported and do not fail the run, so a
+      # project can adopt the informational rules without turning its build red.
+      def exit_code(offenses, fail_level)
+        if offenses.any? { |offense| offense.at_least?(fail_level) }
+          EXIT_OFFENSES
+        else
+          EXIT_SUCCESS
+        end
+      end
+
+      def print_version
+        out.puts("remlint #{VERSION}")
+        EXIT_SUCCESS
+      end
+
+      def print_rules
+        config = Config.discover
+
+        Rule.all.sort_by(&:rule_name).each do |rule|
+          if config.enabled?(rule)
+            state = "on "
+          else
+            state = "off"
+          end
+
+          out.puts("#{state}  #{rule.rule_name.ljust(26)} #{rule.description}")
+        end
+
+        EXIT_SUCCESS
+      end
+
+      def print_config(options)
+        out.puts(YAML.dump(resolve_config(options).settings))
+        EXIT_SUCCESS
+      end
+  end
+end
+
+__END__
+
+require "stringio"
+require "tempfile"
+
+describe "RemLint::CLI" do
+  run = proc do |argv|
+    out = StringIO.new
+    err = StringIO.new
+    status = RemLint::CLI.new(out: out, err: err).call(argv)
+
+    { status: status, out: out.string, err: err.string }
+  end
+
+  # The Tempfile objects are kept, not just their paths: an unreferenced
+  # Tempfile is garbage, and its finalizer unlinks the file. In a short run
+  # nothing collects and the specs pass; in a long one the file vanishes
+  # between being written and being linted.
+  fixtures = []
+
+  fixture = proc do |text|
+    file = Tempfile.new(["remlint-cli", ".rem"])
+    file.write(text)
+    file.close
+    fixtures << file
+    file.path
+  end
+
+  describe "linting" do
+    it "prints nothing and exits zero for a clean file" do
+      result = run.([fixture.("MSG hi\n")])
+
+      result[:status].should == 0
+      result[:out].should == ""
+    end
+
+    it "prints each offence and exits non-zero" do
+      result = run.(["--only", "TrailingWhitespace", fixture.("MSG hi \n")])
+
+      result[:status].should == 1
+      result[:out].should.match(/: error: \[TrailingWhitespace\] Trailing whitespace/)
+    end
+
+    it "runs only the rules --only names" do
+      result = run.(["--only", "LineLength", fixture.("MSG hi \n")])
+
+      result[:status].should == 0
+    end
+
+    it "honours a custom output format" do
+      result = run.(["--only", "TrailingWhitespace", "--format", "%{line}|%{rule}", fixture.("MSG hi \n")])
+
+      result[:out].should.match(/\A1\|TrailingWhitespace\n/)
+    end
+  end
+
+  describe "--fail-level" do
+    it "fails on an offence at the threshold" do
+      result = run.(["--only", "TrailingWhitespace", "--fail-level", "error", fixture.("MSG hi \n")])
+
+      result[:status].should == 1
+    end
+
+    it "reports an offence below the threshold without failing on it" do
+      path = fixture.("#{'x' * 200}\n")
+      result = run.(["--only", "LineLength", "--fail-level", "error", path])
+
+      result[:status].should == 0
+      result[:out].should.match(/\[LineLength\]/)
+    end
+  end
+
+  describe "informational flags" do
+    it "prints the version" do
+      result = run.(["--version"])
+
+      result[:status].should == 0
+      result[:out].should == "remlint #{RemLint::VERSION}\n"
+    end
+
+    it "lists the rules and whether each is on" do
+      result = run.(["--show-rules"])
+
+      result[:status].should == 0
+      result[:out].should.match(/^on   TrailingWhitespace/)
+    end
+
+    it "prints the configuration in effect" do
+      run.(["--show-config"])[:out].should.match(/TrailingWhitespace/)
+    end
+
+    it "prints usage for --help and exits zero" do
+      result = run.(["--help"])
+
+      result[:status].should == 0
+      result[:out].should.match(/Usage: remlint/)
+    end
+  end
+
+  describe "bad usage" do
+    it "reports an unknown flag on stderr and exits two" do
+      result = run.(["--nonsense"])
+
+      result[:status].should == 2
+      result[:err].should.match(/invalid option/)
+    end
+
+    it "reports an unknown --fail-level" do
+      run.(["--fail-level", "catastrophic"])[:status].should == 2
+    end
+  end
+end

data/lib/remlint/command.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative "logical_line"
+require_relative "vocabulary"
+
+module RemLint
+  # A classified logical line: which keyword opens it, and what follows.
+  #
+  # `keyword` is nil for three different things, and rules must not confuse
+  # them, so ask rather than test for nil:
+  #
+  #   blank?    nothing but whitespace
+  #   comment?  opens with `#` or `;`
+  #   implicit? a trigger with the `REM` left off -- `1 Nov ++12 MSG ...`,
+  #             which the manual explicitly allows and which is the ordinary
+  #             way to write a reminder
+  Command = Struct.new(
+    :keyword,
+    :word,
+    :args,
+    :logical_line,
+    :kind,
+    keyword_init: true,
+  ) do
+    # Where `args` begins in `text`. `args` is always a suffix of `text`, so a
+    # rule that found something at offset N in `args` can hand
+    # `args_offset + N` to LogicalLine#position_at and get a real file position.
+    def args_offset
+      text.length - args.length
+    end
+
+    def line
+      logical_line.line
+    end
+
+    def last_line
+      logical_line.last_line
+    end
+
+    def text
+      logical_line.text
+    end
+
+    def blank?
+      kind == :blank
+    end
+
+    def comment?
+      kind == :comment
+    end
+
+    # A command line that opens with no recognisable keyword. Remind reads it
+    # as a bare trigger with an implicit `REM`.
+    def implicit?
+      kind == :implicit
+    end
+
+    # Blank lines and comments are not commands at all.
+    def code?
+      kind == :keyword || kind == :implicit
+    end
+
+    def keyword?(*names)
+      !keyword.nil? && names.map(&:upcase).include?(keyword.name)
+    end
+
+    # The column, 1-based, where the keyword itself starts.
+    def keyword_column
+      (text.index(/\S/) || 0) + 1
+    end
+  end
+
+  # Splits a logical line into its opening keyword and the rest.
+  #
+  # Deliberately shallow: Remind's grammar is loose enough that a full parse
+  # would be a second implementation of Remind, and wrong in different places
+  # than the first. Rules that need to look inside `args` reach for
+  # {ExprLexer}; rules that only care which command this is stop here.
+  module Classifier
+    COMMENT = /\A\s*[#;]/
+    BLANK   = /\A\s*\z/m
+    WORD    = /\A\s*(\S+)/
+
+    module_function
+
+    def call(logical_line)
+      text = logical_line.text
+
+      if text.match?(BLANK)
+        bare(logical_line, :blank)
+      elsif text.match?(COMMENT)
+        bare(logical_line, :comment)
+      else
+        classify_code(logical_line, text)
+      end
+    end
+
+    def all(logical_lines)
+      logical_lines.map { |logical_line| call(logical_line) }
+    end
+
+    # A line opening with a clause keyword -- a month, a weekday, an ordinal --
+    # is a trigger with the `REM` left off, not a command named `JANUARY`. It
+    # gets `kind: :implicit` like a line opening with a bare day number, and
+    # keeps its whole text as `args`, because the clause is part of the trigger
+    # rather than something the command takes.
+    def classify_code(logical_line, text)
+      match = text.match(WORD)
+      word = match[1]
+      keyword = Vocabulary.keyword(word)
+      commands = !keyword.nil? && !keyword.clause?
+
+      Command.new(
+        keyword:      keyword,
+        word:         word,
+        args:         commands ? match.post_match.sub(/\A[ \t]+/, "") : text.sub(/\A\s*/, ""),
+        logical_line: logical_line,
+        kind:         commands ? :keyword : :implicit,
+      )
+    end
+
+    def bare(logical_line, kind)
+      Command.new(
+        keyword:      nil,
+        word:         nil,
+        args:         logical_line.text,
+        logical_line: logical_line,
+        kind:         kind,
+      )
+    end
+  end
+end
+
+__END__
+
+describe "RemLint::Classifier" do
+  classify = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Classifier.all(RemLint::Joiner.call(source))
+  end
+
+  one = proc { |text| classify.(text).first }
+
+  it "recognises a keyword and splits off its arguments" do
+    command = one.("REM 1 Jan MSG New Year")
+
+    command.keyword.name.should == "REM"
+    command.args.should == "1 Jan MSG New Year"
+    command.should.be.code
+  end
+
+  it "recognises a keyword whatever its case" do
+    one.("msg hello").keyword.name.should == "MSG"
+    one.("MsG hello").keyword.name.should == "MSG"
+  end
+
+  it "recognises an abbreviated keyword" do
+    one.("INC defs.rem").keyword.name.should == "INCLUDE"
+  end
+
+  it "treats a bare trigger as an implicit REM" do
+    command = one.("1 Nov ++12 MSG Get ready")
+
+    command.keyword.should.be.nil
+    command.should.be.implicit
+    command.should.be.code
+    command.args.should == "1 Nov ++12 MSG Get ready"
+  end
+
+  it "treats a trigger opening with a clause keyword as an implicit REM too" do
+    command = one.("Nov 1 MSG All Saints")
+
+    command.should.be.implicit
+    command.keyword.name.should == "NOVEMBER"
+    command.args.should == "Nov 1 MSG All Saints"
+  end
+
+  it "marks comments, in both of Remind's comment characters" do
+    one.("# a note").should.be.comment
+    one.("; also a note").should.be.comment
+    one.("   # indented").should.be.comment
+    one.("# a note").code?.should.be.false
+  end
+
+  it "marks blank lines" do
+    one.("\n").should.be.blank
+    one.("   \t \n").should.be.blank
+    one.("\n").code?.should.be.false
+  end
+
+  it "can map an offset in args back to a file position" do
+    command = one.("   SET x 12345")
+
+    command.args.should == "x 12345"
+    command.logical_line.position_at(command.args_offset).should == [1, 8]
+  end
+
+  it "does not mistake a trailing # for a comment" do
+    one.("MSG see issue #42").should.be.code
+  end
+
+  it "keeps the logical line, so continued commands classify once" do
+    commands = classify.("IF a > 1 && \\\n   b < 2\nENDIF\n")
+
+    commands.length.should == 2
+    commands.first.keyword.name.should == "IF"
+    commands.first.line.should == 1
+    commands.first.last_line.should == 2
+  end
+
+  it "answers keyword? by canonical name, whatever was written" do
+    one.("inc defs.rem").keyword?("INCLUDE").should.be.true
+    one.("inc defs.rem").keyword?("MSG", "INCLUDE").should.be.true
+    one.("inc defs.rem").keyword?("MSG").should.be.false
+    one.("# note").keyword?("MSG").should.be.false
+  end
+
+  it "reports the column the keyword starts in" do
+    one.("MSG hi").keyword_column.should == 1
+    one.("    MSG hi").keyword_column.should == 5
+  end
+
+  it "classifies a whole file in order" do
+    commands = classify.("# header\n\nSET a 1\n1 Jan MSG hi\n")
+
+    commands.map(&:kind).should == %i[comment blank keyword implicit]
+  end
+end