remlint 0.1.0

data/lib/remlint/rules/keyword_case.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Command keywords written in a case the file does not otherwise use.
+    #
+    # Remind's keywords are case-insensitive -- `remind.vim` opens with
+    # `syn case ignore` for exactly this reason -- so this is a consistency
+    # rule and nothing more. It is off by default: `examples/alignment.rem`
+    # deliberately mixes `MSG` and `msg` to show the two are the same, and a
+    # linter that shouts at the shipped examples for their own subject matter
+    # is a linter people switch off.
+    #
+    # `EnforcedStyle: upper` (the default when the rule is on) matches every
+    # example Remind ships and the manual's own prose. `lower` is the mirror
+    # image. `consistent` picks whichever style the file already uses more and
+    # reports the rest, which is the setting for adopting the rule on a file
+    # you did not write.
+    class KeywordCase < Rule
+      STYLES = %w[upper lower consistent].freeze
+
+      def self.enabled_by_default?
+        false
+      end
+
+      def self.description
+        "Command keywords in a case other than the file's own."
+      end
+
+      def check
+        style = resolve_style
+
+        keyword_commands.each do |command|
+          if !conforms?(command.word, style)
+            offend(
+              command.line,
+              "Write `#{cased(command.word, style)}` rather than `#{command.word}`",
+              column: command.keyword_column,
+            )
+          end
+        end
+      end
+
+      private
+
+        def keyword_commands
+          document.code_commands.select { |command| command.kind == :keyword }
+        end
+
+        def resolve_style
+          configured = option("EnforcedStyle", "upper")
+
+          if configured == "consistent"
+            majority_style
+          else
+            configured
+          end
+        end
+
+        # Whichever style already accounts for more of the file's keywords, so
+        # turning the rule on reports the minority rather than half the file.
+        # A tie goes to upper, which is what Remind's own examples use.
+        def majority_style
+          words = keyword_commands.map(&:word)
+          lower = words.count { |word| word == word.downcase }
+          upper = words.count { |word| word == word.upcase }
+
+          if lower > upper
+            "lower"
+          else
+            "upper"
+          end
+        end
+
+        def conforms?(word, style)
+          word == cased(word, style)
+        end
+
+        def cased(word, style)
+          if style == "lower"
+            word.downcase
+          else
+            word.upcase
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::KeywordCase" do
+  lint = proc do |text, config = {}|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::KeywordCase.new(config).run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text, config = {}| lint.(text, config).map(&:message) }
+
+  it "is off unless the configuration asks for it" do
+    RemLint::Rules::KeywordCase.enabled_by_default?.should.be.false
+  end
+
+  describe "the default upper style" do
+    it "accepts upper-case keywords" do
+      lint.("SET a 1\nMSG hi\n").should.be.empty
+    end
+
+    it "reports a lower-case keyword" do
+      messages.("msg hi\n").should == ["Write `MSG` rather than `msg`"]
+    end
+
+    it "reports a mixed-case keyword" do
+      messages.("MsG hi\n").should == ["Write `MSG` rather than `MsG`"]
+    end
+
+    it "reports the abbreviation as written, not expanded" do
+      messages.("inc defs.rem\n").should == ["Write `INC` rather than `inc`"]
+    end
+
+    it "points at the keyword's column" do
+      lint.("   msg hi\n").first.column.should == 4
+    end
+  end
+
+  describe "the lower style" do
+    it "reports an upper-case keyword" do
+      messages.("MSG hi\n", "EnforcedStyle" => "lower").should ==
+        ["Write `msg` rather than `MSG`"]
+    end
+
+    it "accepts lower-case keywords" do
+      lint.("msg hi\n", "EnforcedStyle" => "lower").should.be.empty
+    end
+  end
+
+  describe "the consistent style" do
+    consistent = { "EnforcedStyle" => "consistent" }
+
+    it "reports the minority when the file is mostly upper" do
+      messages.("MSG a\nMSG b\nmsg c\n", consistent).should == ["Write `MSG` rather than `msg`"]
+    end
+
+    it "reports the minority when the file is mostly lower" do
+      messages.("msg a\nmsg b\nMSG c\n", consistent).should == ["Write `msg` rather than `MSG`"]
+    end
+
+    it "prefers upper on a tie, as Remind's own examples do" do
+      messages.("MSG a\nmsg b\n", consistent).should == ["Write `MSG` rather than `msg`"]
+    end
+  end
+
+  describe "what it stays quiet about" do
+    it "says nothing about a trigger with no keyword" do
+      lint.("1 Nov ++12 MSG get ready\n").should.be.empty
+    end
+
+    it "says nothing about clause keywords inside a trigger" do
+      # Only the command's own keyword is this rule's business.
+      lint.("REM 1 Jan until 3 Jan MSG hi\n").should.be.empty
+    end
+
+    it "says nothing about comments or blank lines" do
+      lint.("# msg\n\n").should.be.empty
+    end
+  end
+end

data/lib/remlint/rules/license_header.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Files missing a licence identifier near the top.
+    #
+    # Off by default, because it is a project policy rather than a Remind fact.
+    # It exists because it is a policy Remind itself keeps: every file under
+    # `examples/` carries `SPDX-License-Identifier: GPL-2.0-only` in its header
+    # comment, and a linter is the only thing that keeps that true as files are
+    # added.
+    #
+    # `Pattern` is a regular expression as a string, so a project with a
+    # different licence or a different marker configures it rather than
+    # forking the rule. Only the first `WithinLines` lines are searched, so a
+    # mention halfway down a long file does not count as a header.
+    class LicenseHeader < Rule
+      DEFAULT_PATTERN = "SPDX-License-Identifier:\\s*\\S+"
+      DEFAULT_WITHIN = 10
+
+      def self.enabled_by_default?
+        false
+      end
+
+      def self.description
+        "A licence identifier in the first few lines of the file."
+      end
+
+      def check
+        within = option("WithinLines", DEFAULT_WITHIN)
+        pattern = Regexp.new(option("Pattern", DEFAULT_PATTERN))
+
+        if !document.raw_lines.empty? && !header_matches?(pattern, within)
+          offend(document.line_number_at(0), "Missing a licence identifier in the first #{within} lines")
+        end
+      end
+
+      private
+
+        def header_matches?(pattern, within)
+          document.raw_lines.first(within).any? { |raw| raw.match?(pattern) }
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::LicenseHeader" do
+  lint = proc do |text, config = {}|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::LicenseHeader.new(config).run(RemLint::Document.new(source))
+  end
+
+  it "is off unless the configuration asks for it" do
+    RemLint::Rules::LicenseHeader.enabled_by_default?.should.be.false
+  end
+
+  it "accepts the header Remind's own examples carry" do
+    lint.("# Demo\n# SPDX-License-Identifier: GPL-2.0-only\nMSG hi\n").should.be.empty
+  end
+
+  it "reports a file with no identifier" do
+    offenses = lint.("# Demo\nMSG hi\n")
+
+    offenses.length.should == 1
+    offenses.first.line.should == 1
+    offenses.first.message.should.match(/licence identifier/)
+  end
+
+  it "does not count an identifier below the header" do
+    body = "MSG hi\n" * 12
+
+    lint.("#{body}# SPDX-License-Identifier: GPL-2.0-only\n").length.should == 1
+  end
+
+  it "honours a wider WithinLines" do
+    body = "MSG hi\n" * 12
+
+    lint.("#{body}# SPDX-License-Identifier: GPL-2.0-only\n", "WithinLines" => 20).should.be.empty
+  end
+
+  it "honours a project's own pattern" do
+    lint.("# Copyright 2026 Someone\n", "Pattern" => "Copyright \\d{4}").should.be.empty
+  end
+
+  it "says nothing about an empty file" do
+    lint.("").should.be.empty
+  end
+
+  it "reports a heredoc at its position in the enclosing file" do
+    source = RemLint::Source.new(path: "astro", text: "MSG hi\n", line_offset: 12)
+
+    RemLint::Rules::LicenseHeader.new.run(RemLint::Document.new(source)).first.line.should == 13
+  end
+end

data/lib/remlint/rules/line_length.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Physical lines past a configured width.
+    #
+    # Off by default, and measured on physical lines rather than joined ones,
+    # because the whole point of a backslash continuation is to keep a long
+    # command inside the margin -- reporting the joined length would report the
+    # very files that did the right thing.
+    #
+    # Remind has its own limit, `$MaxLineLength`, but that is a runtime guard
+    # against a runaway `INCLUDECMD`, not a style setting; this is the style
+    # setting.
+    class LineLength < Rule
+      DEFAULT_MAXIMUM = 100
+
+      def self.enabled_by_default?
+        false
+      end
+
+      def self.default_severity
+        "info"
+      end
+
+      def self.description
+        "Physical lines longer than Max characters."
+      end
+
+      def check
+        maximum = option("Max", DEFAULT_MAXIMUM)
+
+        document.each_raw_line do |raw, line|
+          length = raw.chomp.length
+
+          if length > maximum
+            offend(line, "Line is #{length} characters, over the #{maximum} allowed", column: maximum + 1)
+          end
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::LineLength" do
+  lint = proc do |text, config = {}|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::LineLength.new(config).run(RemLint::Document.new(source))
+  end
+
+  short = { "Max" => 10 }
+
+  it "is off unless the configuration asks for it" do
+    RemLint::Rules::LineLength.enabled_by_default?.should.be.false
+  end
+
+  it "accepts a line at the limit" do
+    lint.("MSG 123456\n", short).should.be.empty
+  end
+
+  it "reports a line over the limit" do
+    offenses = lint.("MSG 1234567\n", short)
+
+    offenses.length.should == 1
+    offenses.first.message.should == "Line is 11 characters, over the 10 allowed"
+  end
+
+  it "points at the first column past the limit" do
+    lint.("MSG 1234567\n", short).first.column.should == 11
+  end
+
+  it "measures physical lines, so a continuation is not penalised for the join" do
+    lint.("MSG 12345\\\n    67890\n", short).should.be.empty
+  end
+
+  it "does not count the newline" do
+    lint.("MSG 123456\n", short).should.be.empty
+  end
+
+  it "reports at info severity by default" do
+    lint.("MSG 1234567\n", short).first.severity.should == "info"
+  end
+
+  it "defaults to a hundred characters" do
+    lint.("#{'x' * 101}\n").length.should == 1
+    lint.("#{'x' * 100}\n").should.be.empty
+  end
+
+  it "reports lines of a heredoc at their position in the enclosing file" do
+    source = RemLint::Source.new(path: "astro", text: "MSG 1234567\n", line_offset: 12)
+
+    RemLint::Rules::LineLength.new(short).run(RemLint::Document.new(source)).first.line.should == 13
+  end
+end

data/lib/remlint/rules/literal_type_mismatch.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Comparisons between literals of different types.
+    #
+    # `compare()` in src/expr.c settles both halves of this exactly:
+    #
+    #   if (v1.type != v2.type) {
+    #       if (how == EQ)      ans->v.val = 0;
+    #       else if (how == NE) ans->v.val = 1;
+    #       else                return E_BAD_TYPE;
+    #   }
+    #
+    # So `"foo" == 14:33` is not a comparison that happens to be false today.
+    # It is the constant 0, on every date, for ever -- and Remind reports
+    # nothing, because as far as it is concerned the answer is simply no. An
+    # ordering operator across types at least errors, but only on the day the
+    # line is reached.
+    #
+    # Both operands must be literals for the type to be knowable without
+    # running anything, which is the usual case for the mistake: comparing a
+    # variable against a constant of the wrong shape.
+    class LiteralTypeMismatch < Rule
+      CONSTANT = { "==" => "0", "!=" => "1" }.freeze
+      ORDERING = %w[< > <= >=].freeze
+
+      OPERATORS = (CONSTANT.keys + ORDERING).freeze
+
+      # E_BAD_TYPE's text, from src/err.h.
+      BAD_TYPE = "Type mismatch"
+
+      # `'2027-01-01'`, `'14:33'`, `'2027-01-01@14:33'` -- src/expr.c reads a
+      # single-quoted literal as a DATE, a TIME or a DATETIME by its shape.
+      DATETIME = /\A'.*@.*'\z/
+      DATE = %r{\A'\d{4}[-/]\d{1,2}[-/]\d{1,2}'\z}
+      TIME = /\A'\d{1,2}[:.]\d{2}'\z/
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "A comparison between literals of different types."
+      end
+
+      def check
+        document.logical_lines.each_with_index do |logical_line, index|
+          if document.commands[index].code?
+            check_line(logical_line)
+          end
+        end
+      end
+
+      private
+
+        def check_line(logical_line)
+          tokens = document.tokens_for(logical_line)
+
+          operators(tokens).each do |position, operator, width|
+            compare(
+              logical_line,
+              tokens,
+              position,
+              operator,
+              width,
+            )
+          end
+        end
+
+        # The lexer emits each punctuation character separately, so `<=` is two
+        # tokens and `==` is two more.
+        def operators(tokens)
+          tokens.each_index.filter_map do |index|
+            two = glyph(tokens, index, 2)
+            one = glyph(tokens, index, 1)
+
+            if OPERATORS.include?(two)
+              [index, two, 2]
+            elsif OPERATORS.include?(one) && !continues?(tokens, index)
+              [index, one, 1]
+            end
+          end
+        end
+
+        def glyph(tokens, index, width)
+          window = tokens[index, width]
+
+          if window&.length == width && window.all? { |token| token.type == :other }
+            window.map(&:value).join
+          end
+        end
+
+        # `<` is an operator; the `<` of `<=` is half of one.
+        def continues?(tokens, index)
+          tokens[index + 1]&.type == :other && tokens[index + 1].value == "="
+        end
+
+        def compare(logical_line, tokens, position, operator, width)
+          left = operand_before(tokens, position)
+          right = operand_after(tokens, position + width)
+
+          if left && right && left.fetch(:type) != right.fetch(:type)
+            offend_at(logical_line, left.fetch(:offset), message(operator, left, right))
+          end
+        end
+
+        def message(operator, left, right)
+          constant = CONSTANT[operator]
+
+          if constant
+            "`#{left.fetch(:text)} #{operator} #{right.fetch(:text)}` compares " \
+            "#{left.fetch(:type)} with #{right.fetch(:type)}; different types are " \
+            "never equal, so this is always #{constant}"
+          else
+            "`#{left.fetch(:text)} #{operator} #{right.fetch(:text)}` orders " \
+            "#{left.fetch(:type)} against #{right.fetch(:type)}, which Remind " \
+            "rejects with `#{BAD_TYPE}`"
+          end
+        end
+
+        # A literal ending at `index - 1`, provided what precedes it is a
+        # boundary rather than more expression.
+        def operand_before(tokens, index)
+          literal = time_before(tokens, index - 1) || single(tokens, index - 1)
+
+          if literal && boundary?(tokens[literal.fetch(:first) - 1])
+            literal
+          end
+        end
+
+        def operand_after(tokens, index)
+          literal = time_after(tokens, index) || single(tokens, index)
+
+          if literal && boundary?(tokens[literal.fetch(:last) + 1])
+            literal
+          end
+        end
+
+        # `14:33` arrives as three tokens, and is a TIME rather than two INTs.
+        def time_before(tokens, index)
+          time(tokens, index - 2)
+        end
+
+        def time_after(tokens, index)
+          time(tokens, index)
+        end
+
+        def time(tokens, first)
+          window = tokens[first, 3]
+
+          if first >= 0 && window&.length == 3 && time_shape?(window)
+            {
+              type:   "TIME",
+              text:   window.map(&:value).join,
+              offset: window.first.offset,
+              first:  first,
+              last:   first + 2,
+            }
+          end
+        end
+
+        def time_shape?(window)
+          window[0].type == :number && window[2].type == :number &&
+            window[1].type == :other && [":", "."].include?(window[1].value) &&
+            window[2].value.length == 2
+        end
+
+        def single(tokens, index)
+          token = tokens[index]
+          type = index >= 0 && token && literal_type(token)
+
+          if type
+            { type: type, text: token.value, offset: token.offset, first: index, last: index }
+          end
+        end
+
+        def literal_type(token)
+          case token.type
+          when :number then "INT"
+          when :string then quoted_type(token.value)
+          end
+        end
+
+        def quoted_type(value)
+          if value.start_with?('"')
+            "STRING"
+          else
+            dated_type(value)
+          end
+        end
+
+        def dated_type(value)
+          if value.match?(DATETIME)
+            "DATETIME"
+          elsif value.match?(DATE)
+            "DATE"
+          elsif value.match?(TIME)
+            "TIME"
+          end
+        end
+
+        # An operand stands alone only if what sits beside it opens, closes,
+        # separates or compares. Arithmetic is deliberately absent: in
+        # `1 + 1 == "foo"` the left side of the comparison is the expression
+        # `1 + 1`, not the literal `1`, and its type is not this rule's to
+        # guess. The same reasoning excludes a unary minus.
+        BOUNDARIES = ["&", "|", "!", "=", "<", ">"].freeze
+
+        def boundary?(token)
+          token.nil? ||
+            token.type == :lbracket || token.type == :rbracket ||
+            token.type == :lparen || token.type == :rparen ||
+            token.type == :comma ||
+            (token.type == :other && BOUNDARIES.include?(token.value))
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::LiteralTypeMismatch" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::LiteralTypeMismatch.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "equality across types" do
+    it "reports a STRING compared with an INT" do
+      messages.(%(IF ["foo" == 14]\n)).first.should.match(
+        /compares STRING with INT; different types are never equal, so this is always 0/,
+      )
+    end
+
+    it "reports a STRING compared with a TIME" do
+      messages.(%(IF ["foo" == 14:33]\n)).first.should.match(/compares STRING with TIME/)
+    end
+
+    it "reports != as always 1" do
+      messages.(%(IF ["foo" != 14]\n)).first.should.match(/always 1/)
+    end
+
+    it "reports a DATE compared with a STRING" do
+      messages.(%(IF ['2027-01-01' == "2027-01-01"]\n)).first.should.match(
+        /compares DATE with STRING/,
+      )
+    end
+
+    it "reports a DATETIME compared with a DATE" do
+      messages.(%(IF ['2027-01-01@14:33' == '2027-01-01']\n)).first.should.match(
+        /compares DATETIME with DATE/,
+      )
+    end
+  end
+
+  describe "ordering across types" do
+    it "reports it as the error Remind raises" do
+      messages.(%(IF ["foo" < 14]\n)).first.should.match(/orders STRING against INT/)
+    end
+
+    it "reports the two-character operators" do
+      messages.(%(IF ["foo" <= 14]\n)).length.should == 1
+      messages.(%(IF ["foo" >= 14]\n)).length.should == 1
+    end
+  end
+
+  describe "comparisons that are fine" do
+    it "accepts two literals of the same type" do
+      lint.(%(IF ["foo" == "bar"]\n)).should.be.empty
+      lint.("IF [1 == 2]\n").should.be.empty
+      lint.("IF [14:33 == 15:00]\n").should.be.empty
+      lint.(%(IF ['2027-01-01' == '2027-01-02']\n)).should.be.empty
+    end
+
+    it "accepts an ordering between two of the same type" do
+      lint.("IF [1 < 2]\n").should.be.empty
+      lint.(%(IF ["a" < "b"]\n)).should.be.empty
+    end
+  end
+
+  describe "operands it cannot type" do
+    it "says nothing when one side is a variable" do
+      lint.(%(IF [x == "foo"]\n)).should.be.empty
+      lint.(%(IF [$Tw == 5]\n)).should.be.empty
+    end
+
+    it "says nothing when one side is a call" do
+      lint.(%(IF [version() == "06.02.10"]\n)).should.be.empty
+    end
+
+    it "says nothing when one side is an arithmetic expression" do
+      # `1 + 1` is not a literal, so its type is not knowable here.
+      lint.(%(IF [1 + 1 == "foo"]\n)).should.be.empty
+    end
+
+    it "says nothing about a single-quoted literal it cannot classify" do
+      lint.(%(IF ['nonsense' == 14]\n)).should.be.empty
+    end
+  end
+
+  it "checks a SATISFY expression too" do
+    messages.(%(REM 13 SATISFY ["foo" == 14]\n)).length.should == 1
+  end
+
+  it "says nothing about comments" do
+    lint.(%(# IF ["foo" == 14]\n)).should.be.empty
+  end
+
+  it "reports at error severity" do
+    lint.(%(IF ["foo" == 14]\n)).first.severity.should == "error"
+  end
+
+  it "reports the physical line inside a continuation" do
+    lint.(%(IF ["foo" \\\n    == 14]\n)).first.line.should == 1
+  end
+end