remlint 0.1.0

data/lib/remlint/logical_line.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative "source"
+
+module RemLint
+  # One Remind command, after backslash continuations have been joined.
+  #
+  # `text` is byte-for-byte what Remind's own LineBuffer would hold: each
+  # continuing backslash replaced by a newline and the following line appended
+  # verbatim (src/files.c ReadLineFromFile). Keeping the newline rather than
+  # collapsing to a space costs nothing -- Remind's tokeniser treats it as
+  # whitespace either way -- and buys exact column arithmetic, because every
+  # character of every continued line still sits where it sat in the file.
+  #
+  # `line` is the physical line the command starts on, in the enclosing file;
+  # `physical_lines` lists every line it spans; `raw` keeps the untouched bytes,
+  # because the whitespace rules care about what the join threw away.
+  LogicalLine = Struct.new(
+    :text,
+    :line,
+    :physical_lines,
+    :raw,
+    keyword_init: true,
+  ) do
+    def continued?
+      physical_lines.length > 1
+    end
+
+    def last_line
+      physical_lines.last
+    end
+
+    # The command on one line, for a message or for a rule that would rather
+    # not think about continuations at all.
+    def squashed
+      text.tr("\n", " ")
+    end
+
+    # Map a character offset in `text` back to a physical [line, column] in the
+    # file. Column is 1-based, so `position_at(0)` is the first column of the
+    # line the command starts on.
+    def position_at(offset)
+      before = text[0, offset].to_s
+      crossed = before.count("\n")
+      last_break = before.rindex("\n")
+
+      if last_break
+        column = offset - last_break
+      else
+        column = offset + 1
+      end
+
+      [physical_lines.fetch(crossed, last_line), column]
+    end
+  end
+
+  # Joins backslash-continued physical lines into logical ones.
+  #
+  # This is where a whole bug class lives. Remind continues a line only on a
+  # backslash that is the very last character; a backslash followed by a space
+  # is just a backslash, and the long `IIF(...)` chains in `defs.rem` and
+  # `astro` are held together by nothing else. Joining here -- rather than
+  # letting each rule guess -- means every rule sees the command Remind sees,
+  # and "backslash that does not continue" becomes something DanglingContinuation
+  # can report rather than something that silently splits a command in half.
+  module Joiner
+    module_function
+
+    def call(source)
+      buffer = nil
+
+      [].tap do |logical|
+        source.lines.each_with_index do |raw, index|
+          line_no = index + 1 + source.line_offset
+          body = raw.chomp
+
+          if buffer
+            buffer.text << body
+            buffer.physical_lines << line_no
+            buffer.raw << raw
+          else
+            buffer = LogicalLine.new(
+              text:           +body,
+              line:           line_no,
+              physical_lines: [line_no],
+              raw:            +raw,
+            )
+          end
+
+          if buffer.text.end_with?("\\")
+            # Remind overwrites the backslash with the newline it just consumed.
+            buffer.text[-1] = "\n"
+          else
+            logical << buffer
+            buffer = nil
+          end
+        end
+
+        # A file whose last line ends in a backslash leaves a command open.
+        # Emit it anyway, so the rules can see -- and complain about -- it.
+        if buffer
+          logical << buffer
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "line joining" do
+  join = proc do |text, line_offset = 0|
+    RemLint::Joiner.call(RemLint::Source.new(path: "t.rem", text: text, line_offset: line_offset))
+  end
+
+  describe "RemLint::Joiner" do
+    it "leaves ordinary lines alone" do
+      lines = join.("REM 1 Jan MSG New Year\nREM 2 Jan MSG Day two\n")
+
+      lines.length.should == 2
+      lines.map(&:text).should == ["REM 1 Jan MSG New Year", "REM 2 Jan MSG Day two"]
+      lines.map(&:line).should == [1, 2]
+    end
+
+    it "joins a continued command the way Remind's LineBuffer does" do
+      lines = join.("SET x IIF(a, \\\n   b, \\\n   c)\n")
+
+      lines.length.should == 1
+      lines.first.text.should == "SET x IIF(a, \n   b, \n   c)"
+      lines.first.squashed.should == "SET x IIF(a,     b,     c)"
+    end
+
+    it "records every physical line a joined command spans" do
+      line = join.("SET x 1 + \\\n2 + \\\n3\n").first
+
+      line.line.should == 1
+      line.last_line.should == 3
+      line.physical_lines.should == [1, 2, 3]
+      line.should.be.continued
+    end
+
+    it "keeps the raw bytes of every joined line" do
+      join.("SET x 1 + \\\n  2\n").first.raw.should == "SET x 1 + \\\n  2\n"
+    end
+
+    it "does not join when the backslash is followed by whitespace" do
+      # Remind continues only on a backslash in the final column. This is the
+      # bug DanglingContinuation exists to report.
+      lines = join.("SET x 1 + \\ \nSET y 2\n")
+
+      lines.length.should == 2
+      lines.first.text.should == "SET x 1 + \\ "
+    end
+
+    it "emits a command left open at end of file" do
+      lines = join.("SET x 1 + \\\n")
+
+      lines.length.should == 1
+      lines.first.text.should == "SET x 1 + \n"
+      lines.first.raw.should.match(/\\\n\z/)
+    end
+
+    it "shifts every line number by the source's offset" do
+      join.("MSG one\nMSG two\n", 40).map(&:line).should == [41, 42]
+    end
+
+    it "handles an empty source" do
+      join.("").should.be.empty
+    end
+  end
+
+  describe "RemLint::LogicalLine#position_at" do
+    it "reports a 1-based column on an unjoined line" do
+      line = join.("SET x 12345\n").first
+
+      line.position_at(0).should == [1, 1]
+      line.position_at(4).should == [1, 5]
+    end
+
+    it "walks onto the physical line the offset actually landed on" do
+      line = join.("SET x 1 + \\\n    22 + \\\n    333\n").first
+
+      # The joined text is "SET x 1 + \n    22 + \n    333".
+      line.position_at(line.text.index("22")).should == [2, 5]
+      line.position_at(line.text.index("333")).should == [3, 5]
+    end
+
+    it "carries the source offset into reported positions" do
+      line = join.("SET x 1 + \\\n    22\n", 40).first
+
+      line.position_at(line.text.index("22")).should == [42, 5]
+    end
+  end
+end

data/lib/remlint/offense.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RemLint
+  # Ordered worst-first, so a run that reports only the top N reports the N
+  # that matter.
+  #
+  # Defined out here rather than inside the Struct body below: a constant
+  # assigned inside a block belongs to the lexical scope around the block, not
+  # to the class the block configures, so `Offense::SEVERITIES` would not have
+  # existed.
+  SEVERITIES = %w[error warning info].freeze
+
+  # One thing a rule found, at one place in one file.
+  #
+  # The default rendering is `path:line:column: severity: [Rule] message`,
+  # which vim's default `errorformat` reads, which GitHub Actions' problem
+  # matchers read, and which `sort` orders correctly. The format is also
+  # configurable, following puppet-lint, because the one thing every CI system
+  # agrees on is that it wants a slightly different format.
+  Offense = Struct.new(
+    :path,
+    :line,
+    :column,
+    :severity,
+    :rule,
+    :message,
+    keyword_init: true,
+  ) do
+    def initialize(path:, line:, rule:, message:, column: 1, severity: "warning")
+      super
+    end
+
+    def severity_rank
+      SEVERITIES.index(severity) || SEVERITIES.length
+    end
+
+    def error?
+      severity == "error"
+    end
+
+    # At or above the given severity, where "above" means closer to error.
+    def at_least?(level)
+      severity_rank <= (SEVERITIES.index(level) || SEVERITIES.length)
+    end
+
+    def to_s
+      format_with("%{path}:%{line}:%{column}: %{severity}: [%{rule}] %{message}")
+    end
+
+    # `%{path}`, `%{line}`, `%{column}`, `%{severity}`, `%{rule}`, `%{message}`.
+    def format_with(template)
+      format(
+        template,
+        path:     path,
+        line:     line,
+        column:   column,
+        severity: severity,
+        rule:     rule,
+        message:  message,
+      )
+    end
+
+    # File, then position, then severity: the order someone reads them in.
+    def sort_key
+      [path, line, column, severity_rank, rule]
+    end
+  end
+end
+
+__END__
+
+describe "RemLint::Offense" do
+  offense = proc do |overrides = {}|
+    defaults = {
+      path:    "holidays.rem",
+      line:    12,
+      column:  4,
+      rule:    "TrailingWhitespace",
+      message: "Trailing whitespace",
+    }
+
+    RemLint::Offense.new(**defaults.merge(overrides))
+  end
+
+  it "renders in a format vim's errorformat reads" do
+    offense.().to_s.should == "holidays.rem:12:4: warning: [TrailingWhitespace] Trailing whitespace"
+  end
+
+  it "defaults to column 1 and warning severity" do
+    bare = RemLint::Offense.new(path: "a.rem", line: 1, rule: "R", message: "m")
+
+    bare.column.should == 1
+    bare.severity.should == "warning"
+  end
+
+  it "renders through a caller-supplied template" do
+    offense.().format_with("%{line}: %{message}").should == "12: Trailing whitespace"
+  end
+
+  it "knows whether it meets a severity threshold" do
+    offense.(severity: "error").should.be.error
+    offense.(severity: "error").at_least?("warning").should.be.true
+    offense.(severity: "warning").at_least?("error").should.be.false
+    offense.(severity: "info").at_least?("warning").should.be.false
+  end
+
+  it "sorts by file, then position, then severity" do
+    unsorted = [
+      offense.(line: 12, column: 9),
+      offense.(line: 3),
+      offense.(path: "a.rem", line: 99),
+    ]
+
+    unsorted.sort_by(&:sort_key).map { |o| [o.path, o.line, o.column] }.should ==
+      [["a.rem", 99, 4], ["holidays.rem", 3, 4], ["holidays.rem", 12, 9]]
+  end
+end

data/lib/remlint/rule.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "offense"
+
+module RemLint
+  # Base class for rules. Subclassing registers.
+  #
+  # A rule implements `check` and calls `offend` for each thing it finds. It
+  # gets one {Document} and its own slice of configuration, and it is
+  # instantiated fresh per document, so a rule accumulating state across a file
+  # (block stacks, FSET definitions) does not have to clean up after itself.
+  #
+  # Registry-by-inheritance rather than an explicit list, following haml-lint:
+  # a new file under `rules/` that is required is a rule that runs, with
+  # nothing else to remember to edit.
+  class Rule
+    # Guarded, not plain: `scampi` runs each file's co-located specs by
+    # `load`ing the file, which re-executes its top level. An unguarded
+    # `REGISTRY = []` would empty the registry halfway through a run and take
+    # every already-registered rule with it -- the subclasses are not
+    # re-registered, because reopening a class does not call `inherited` again.
+    unless defined?(REGISTRY)
+      REGISTRY = []
+    end
+
+    class << self
+      def inherited(subclass)
+        super
+        REGISTRY << subclass
+      end
+
+      # `RemLint::Rules::TrailingWhitespace` configures and reports as
+      # `TrailingWhitespace`. Anonymous subclasses -- which specs make, and
+      # which land in the registry like any other -- get a placeholder rather
+      # than blowing up every caller that walks the registry.
+      def rule_name
+        if name
+          name.split("::").last
+        else
+          "(anonymous)"
+        end
+      end
+
+      # Overridden by a rule that should be off unless asked for. Rules that
+      # enforce a house preference rather than report a defect default to off,
+      # because a linter whose first run is a wall of style noise gets turned
+      # off entirely.
+      def enabled_by_default?
+        true
+      end
+
+      def default_severity
+        "warning"
+      end
+
+      # One line, shown by `remlint --show-rules` and used as the doc comment
+      # in the generated default config.
+      def description
+        ""
+      end
+
+      # Only named subclasses. A rule with no name cannot be configured, named
+      # in a `remlint:disable` comment, or reported usefully, so it is not one
+      # the runner can run -- which is also what keeps the anonymous classes a
+      # spec makes from turning up in someone else's lint run.
+      def all
+        REGISTRY.reject { |rule| rule.name.nil? }
+      end
+
+      def find(rule_name)
+        all.find { |rule| rule.rule_name == rule_name }
+      end
+    end
+
+    attr_reader :config, :document, :offenses
+
+    def initialize(config = {})
+      @config = config
+      @offenses = []
+    end
+
+    def run(document)
+      @document = document
+      @offenses = []
+      check
+      offenses
+    end
+
+    def rule_name
+      self.class.rule_name
+    end
+
+    # Subclasses implement this.
+    def check
+      raise NotImplementedError, "#{self.class} must implement #check"
+    end
+
+    private
+
+      # `severity:` overrides the configured level for one offence. Only one
+      # rule needs it: Syntax, which relays diagnostics Remind has already
+      # graded for itself and should not promote a warning to an error.
+      def offend(line, message, column: 1, severity: nil)
+        @offenses << Offense.new(
+          path:     document.path,
+          line:     line,
+          column:   column,
+          severity: severity || configured_severity,
+          rule:     rule_name,
+          message:  message,
+        )
+      end
+
+      # Report at a character offset into a logical line, letting the line work
+      # out which physical line and column that lands on. This is what a rule
+      # working from the token stream wants: it keeps offences inside a
+      # continued command pointing at the continuation they are actually on.
+      def offend_at(logical_line, offset, message)
+        line, column = logical_line.position_at(offset)
+
+        offend(line, message, column: column)
+      end
+
+      def configured_severity
+        config.fetch("Severity", self.class.default_severity)
+      end
+
+      def option(key, default)
+        config.fetch(key, default)
+      end
+  end
+end
+
+__END__
+
+require_relative "document"
+require_relative "rules/trailing_whitespace"
+
+describe "RemLint::Rule" do
+  # Defined inside the spec so the registry assertions have something of their
+  # own to find, rather than depending on which real rules happen to be loaded.
+  example = Class.new(RemLint::Rule) do
+    def self.rule_name = "ExampleRule"
+
+    def check
+      document.code_commands.each do |command|
+        offend(command.line, "saw #{command.keyword&.name}", column: command.keyword_column)
+      end
+    end
+  end
+
+  document = proc do |text|
+    RemLint::Document.new(RemLint::Source.new(path: "t.rem", text: text))
+  end
+
+  it "registers every subclass" do
+    RemLint::Rule::REGISTRY.should.include example
+  end
+
+  it "keeps anonymous subclasses out of the runnable set" do
+    # A rule with no name cannot be configured or reported by name, and the
+    # ones a spec makes must not leak into anyone else's run.
+    RemLint::Rule.all.should.not.include example
+  end
+
+  it "collects the offences a check reports" do
+    offenses = example.new.run(document.("# note\nMSG hi\n"))
+
+    offenses.length.should == 1
+    offenses.first.line.should == 2
+    offenses.first.message.should == "saw MSG"
+    offenses.first.rule.should == "ExampleRule"
+  end
+
+  it "starts empty on each run rather than accumulating" do
+    rule = example.new
+    rule.run(document.("MSG hi\n"))
+    rule.run(document.("MSG hi\n"))
+
+    rule.offenses.length.should == 1
+  end
+
+  it "takes severity from configuration, falling back to the rule's default" do
+    example.new.run(document.("MSG hi\n")).first.severity.should == "warning"
+    example.new("Severity" => "error").run(document.("MSG hi\n")).first.severity.should == "error"
+  end
+
+  it "insists a subclass implements check" do
+    incomplete = Class.new(RemLint::Rule)
+
+    lambda { incomplete.new.run(document.("MSG hi\n")) }.should.raise NotImplementedError
+  end
+
+  it "finds a named rule and nothing else" do
+    RemLint::Rule.find("TrailingWhitespace").rule_name.should == "TrailingWhitespace"
+    RemLint::Rule.find("ExampleRule").should.be.nil
+    RemLint::Rule.find("NoSuchRule").should.be.nil
+  end
+
+  it "reports an offset inside a continued command on the right physical line" do
+    positional = Class.new(RemLint::Rule) do
+      def self.rule_name = "Positional"
+
+      def check
+        line = document.logical_lines.first
+
+        offend_at(line, line.text.index("boom"), "found it")
+      end
+    end
+
+    offense = positional.new.run(document.("SET x 1 + \\\n    boom\n")).first
+
+    offense.line.should == 2
+    offense.column.should == 5
+  end
+end