remlint 0.1.0

data/lib/remlint/rules/system_variable_assignment.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+require_relative "../vocabulary"
+
+module RemLint
+  module Rules
+    # `SET` on a system variable that will not take it.
+    #
+    # Remind's table marks each variable modifiable or not and, for the integer
+    # ones, carries the range it will accept (src/var.c SysVarArr). Writing to a
+    # read-only variable is `E_CANT_MODIFY`; writing out of range is
+    # `E_2LOW`/`E_2HIGH`. Both are decidable from the line alone whenever the
+    # value is a literal, which is how these variables are almost always set:
+    #
+    #   SET $CalMode 1          $CalMode reports the mode, it does not set it
+    #   SET $FormWidth 10       Remind accepts 20 to 500
+    #
+    # A computed value (`SET $FormWidth columns()`) is left alone: the rule
+    # cannot know what it evaluates to, and guessing would be worse than
+    # silence.
+    class SystemVariableAssignment < Rule
+      # `SET $Name value` -- and `UNSET $Name`, which is the same permission
+      # question with no value attached.
+      ASSIGNMENT = /\A(?<sigil>\$)(?<name>\w+)\s*(?<value>.*)\z/m
+
+      INTEGER = /\A[+-]?\d+\z/
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "SET on a read-only system variable, or with a value outside its range."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          if command.keyword?("SET", "UNSET")
+            check_assignment(command)
+          end
+        end
+      end
+
+      private
+
+        def check_assignment(command)
+          match = command.args.match(ASSIGNMENT)
+          sysvar = match && Vocabulary.sysvar(match[:name])
+
+          if sysvar
+            check_permission(command, sysvar) || check_range(command, sysvar, match[:value])
+          end
+        end
+
+        # Returns truthy when it reported, so a variable that cannot be written
+        # at all is not also told its value is out of range.
+        def check_permission(command, sysvar)
+          unless sysvar.modifiable
+            offend(
+              command.line,
+              "`$#{sysvar.name}` is read-only and cannot be #{verb(command)}",
+              column: command.keyword_column,
+            )
+          end
+        end
+
+        def verb(command)
+          if command.keyword?("UNSET")
+            "unset"
+          else
+            "set"
+          end
+        end
+
+        def check_range(command, sysvar, value)
+          literal = integer_literal(value)
+
+          if sysvar.bounded? && !literal.nil? && !sysvar.in_range?(literal)
+            offend(
+              command.line,
+              "`$#{sysvar.name}` accepts #{sysvar.min} to #{sysvar.max}, given #{literal}",
+              column: command.keyword_column,
+            )
+          end
+        end
+
+        def integer_literal(value)
+          text = value.to_s.strip
+
+          if text.match?(INTEGER)
+            Integer(text)
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::SystemVariableAssignment" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::SystemVariableAssignment.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "assignments Remind accepts" do
+    it "accepts a writable variable" do
+      lint.("SET $AddBlankLines 0\n").should.be.empty
+    end
+
+    it "accepts a value at each end of the range" do
+      lint.("SET $FormWidth 20\nSET $FormWidth 500\n").should.be.empty
+    end
+
+    it "accepts a negative value inside a range that allows one" do
+      lint.("SET $MinsFromUTC -300\n").should.be.empty
+    end
+
+    it "accepts a string value for a string variable" do
+      lint.(%(SET $Ago "ago"\n)).should.be.empty
+    end
+
+    it "matches the variable name case-insensitively" do
+      lint.("SET $formwidth 100\n").should.be.empty
+    end
+  end
+
+  describe "read-only variables" do
+    it "reports a SET" do
+      messages.("SET $CalMode 1\n").should == ["`$CalMode` is read-only and cannot be set"]
+    end
+
+    it "reports an UNSET with the right verb" do
+      messages.("UNSET $CalMode\n").should == ["`$CalMode` is read-only and cannot be unset"]
+    end
+
+    it "does not also complain about the value" do
+      lint.("SET $CalMode 99999\n").length.should == 1
+    end
+
+    it "points at the keyword" do
+      lint.("   SET $CalMode 1\n").first.column.should == 4
+    end
+  end
+
+  describe "values outside a variable's range" do
+    it "reports one below the minimum" do
+      messages.("SET $FormWidth 10\n").should == ["`$FormWidth` accepts 20 to 500, given 10"]
+    end
+
+    it "reports one above the maximum" do
+      messages.("SET $FormWidth 900\n").should == ["`$FormWidth` accepts 20 to 500, given 900"]
+    end
+
+    it "reports a boolean variable given something other than 0 or 1" do
+      messages.("SET $AddBlankLines 2\n").should == ["`$AddBlankLines` accepts 0 to 1, given 2"]
+    end
+
+    it "reports at error severity" do
+      lint.("SET $FormWidth 10\n").first.severity.should == "error"
+    end
+  end
+
+  describe "what it stays quiet about" do
+    it "says nothing about a computed value it cannot evaluate" do
+      lint.("SET $FormWidth columns()\n").should.be.empty
+      lint.("SET $FormWidth [x]\n").should.be.empty
+    end
+
+    it "says nothing about a variable with no declared range" do
+      lint.("SET $MaxSatIter 999999\n").should.be.empty
+    end
+
+    it "says nothing about an ordinary variable" do
+      lint.("SET CalMode 1\n").should.be.empty
+    end
+
+    it "says nothing about a system variable it has never heard of" do
+      # UnknownSystemVariable owns that offence.
+      lint.("SET $Nope 1\n").should.be.empty
+    end
+
+    it "says nothing about a command that is not SET or UNSET" do
+      lint.("MSG $CalMode is [$CalMode]\n").should.be.empty
+    end
+  end
+
+  it "reports the line a continued assignment starts on" do
+    lint.("SET $FormWidth \\\n    10\n").first.line.should == 1
+  end
+end

data/lib/remlint/rules/tag_syntax.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `TAG` values that will not survive the trip to a back-end.
+    #
+    # Tags are handed to the machine-readable back-ends as a comma-separated
+    # list. A comma inside one tag therefore splits it into two tags nobody
+    # wrote, and whitespace inside one ends it early. Neither is an error --
+    # the reminder triggers, the tag is simply not the tag that was written,
+    # and the mistake surfaces in whatever consumes the export.
+    class TagSyntax < Rule
+      FORBIDDEN = {
+        ","  => "separates tags in the list back-ends receive",
+        " "  => "ends the tag",
+        "\t" => "ends the tag",
+      }.freeze
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A TAG value containing a comma or whitespace."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          document.trigger_for(command).clauses.each do |clause|
+            if clause.name == "TAG"
+              check_tag(command, clause)
+            end
+          end
+        end
+      end
+
+      private
+
+        def check_tag(command, clause)
+          value = quoted_value(command, clause)
+
+          if value
+            report(command, clause, value)
+          end
+        end
+
+        # Only a quoted tag can carry a comma or a space in the first place --
+        # an unquoted one is already ended by the whitespace, which the
+        # tokeniser settles before this rule sees it.
+        def quoted_value(command, clause)
+          tokens = document.tokens_for(command.logical_line)
+          token = tokens[clause.argument_index]
+
+          if token&.type == :string
+            token.value[1..-2]
+          end
+        end
+
+        def report(command, clause, value)
+          FORBIDDEN.each do |character, effect|
+            if value.include?(character)
+              offend_at(command.logical_line, clause.offset, message(value, character, effect))
+            end
+          end
+        end
+
+        def message(value, character, effect)
+          if character == "\t"
+            named = "a tab"
+          else
+            named = "`#{character}`"
+          end
+
+          "the tag `#{value}` contains #{named}, which #{effect}"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::TagSyntax" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::TagSyntax.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  it "accepts a plain tag" do
+    lint.(%(REM 1 Jan TAG "birthday" MSG hi\n)).should.be.empty
+  end
+
+  it "accepts an unquoted tag" do
+    lint.("REM 1 Jan TAG birthday MSG hi\n").should.be.empty
+  end
+
+  it "accepts a tag with a hyphen or an underscore" do
+    lint.(%(REM 1 Jan TAG "work-related_thing" MSG hi\n)).should.be.empty
+  end
+
+  it "reports a comma inside a tag" do
+    messages.(%(REM 1 Jan TAG "work,home" MSG hi\n)).first.should ==
+      "the tag `work,home` contains `,`, which separates tags in the list back-ends receive"
+  end
+
+  it "reports a space inside a tag" do
+    messages.(%(REM 1 Jan TAG "work stuff" MSG hi\n)).first.should.match(/contains `.`, which ends the tag/)
+  end
+
+  it "reports a tab inside a tag" do
+    messages.(%(REM 1 Jan TAG "work\tstuff" MSG hi\n)).first.should.match(/contains a tab/)
+  end
+
+  it "reports both faults in one tag" do
+    lint.(%(REM 1 Jan TAG "a, b" MSG hi\n)).length.should == 2
+  end
+
+  it "points at the clause" do
+    text = %(REM 1 Jan TAG "work,home" MSG hi\n)
+
+    lint.(text).first.column.should == text.index("TAG") + 1
+  end
+
+  it "says nothing about a reminder with no TAG" do
+    lint.("REM 1 Jan MSG hi\n").should.be.empty
+  end
+
+  it "does not read a tag out of a message body" do
+    lint.(%(REM 1 Jan MSG the tag "a,b" is wrong\n)).should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.(%(# REM 1 Jan TAG "a,b" MSG hi\n)).should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.(%(REM 1 Jan TAG "a,b" MSG hi\n)).first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/text_after_eof_marker.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Commands below a line reading `__EOF__`.
+    #
+    # Remind stops reading there and treats it as end of file
+    # (src/files.c: `if (!strcmp(CurLine, "__EOF__"))`). The match is exact --
+    # the whole line, no leading or trailing space -- so this is decidable by
+    # looking at it.
+    #
+    # The marker is a debugging convenience: drop it in, and everything below
+    # is temporarily switched off. The failure is leaving it in. What follows
+    # still looks like live configuration, still gets edited, and never runs
+    # again. Nothing in Remind's output distinguishes "this reminder did not
+    # trigger today" from "Remind never read this reminder at all".
+    class TextAfterEofMarker < Rule
+      MARKER = "__EOF__"
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "Commands below a __EOF__ marker, which Remind never reads."
+      end
+
+      def check
+        marker = marker_line
+
+        if marker
+          report(marker)
+        end
+      end
+
+      private
+
+        # The first marker wins; anything below it is unread, including a
+        # second marker. `find_index` rather than an `each` with a `break`,
+        # which yields the whole array when nothing matches.
+        def marker_line
+          document.raw_lines.find_index { |raw| raw.chomp == MARKER }
+        end
+
+        def report(index)
+          live = document.commands.count do |command|
+            command.code? && command.line > document.line_number_at(index)
+          end
+
+          if live.positive?
+            offend(
+              document.line_number_at(index),
+              "`#{MARKER}` ends the file here; the #{live} command#{live == 1 ? '' : 's'} " \
+              "below it are never read",
+            )
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::TextAfterEofMarker" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::TextAfterEofMarker.new.run(RemLint::Document.new(source))
+  end
+
+  it "reports commands below the marker" do
+    offenses = lint.("MSG live\n__EOF__\nMSG dead\n")
+
+    offenses.length.should == 1
+    offenses.first.line.should == 2
+    offenses.first.message.should.match(/never read/)
+  end
+
+  it "counts how many commands are stranded" do
+    lint.("__EOF__\nMSG a\nMSG b\nMSG c\n").first.message.should.match(/the 3 commands below/)
+  end
+
+  it "uses the singular for one" do
+    lint.("__EOF__\nMSG a\n").first.message.should.match(/the 1 command below/)
+  end
+
+  it "says nothing when the marker is the last line" do
+    lint.("MSG live\n__EOF__\n").should.be.empty
+  end
+
+  it "says nothing when only comments and blanks follow" do
+    # Dead comments are not a lie about configuration.
+    lint.("MSG live\n__EOF__\n# a note\n\n").should.be.empty
+  end
+
+  it "says nothing about a file with no marker" do
+    lint.("MSG a\nMSG b\n").should.be.empty
+  end
+
+  describe "the match is exact" do
+    it "ignores a marker with leading whitespace" do
+      lint.("MSG a\n  __EOF__\nMSG b\n").should.be.empty
+    end
+
+    it "ignores a marker with trailing whitespace" do
+      lint.("MSG a\n__EOF__ \nMSG b\n").should.be.empty
+    end
+
+    it "ignores a marker with anything else on the line" do
+      lint.("MSG a\n__EOF__ stop here\nMSG b\n").should.be.empty
+    end
+
+    it "ignores a lower-case spelling" do
+      lint.("MSG a\n__eof__\nMSG b\n").should.be.empty
+    end
+  end
+
+  it "takes the first marker when there are two" do
+    offenses = lint.("MSG a\n__EOF__\nMSG b\n__EOF__\nMSG c\n")
+
+    offenses.length.should == 1
+    offenses.first.line.should == 2
+  end
+
+  it "reports a heredoc's marker at its position in the enclosing file" do
+    source = RemLint::Source.new(path: "astro", text: "__EOF__\nMSG a\n", line_offset: 12)
+
+    RemLint::Rules::TextAfterEofMarker.new.run(RemLint::Document.new(source)).first.line.should == 13
+  end
+end

data/lib/remlint/rules/time_zone_name.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `TZ` given a zone name the system does not have.
+    #
+    # Remind hands the name to the C library, which is case-sensitive: on a
+    # system with a zone database, `america/toronto` is not `America/Toronto`.
+    # An unrecognised name does not error -- the conversion simply produces
+    # undefined results, which for a reminder means firing on the wrong day
+    # some months from now.
+    #
+    # This is the one rule that reads something outside the file: the zone
+    # database, at `TZDIR` or `/usr/share/zoneinfo`. Where there is no database
+    # to read, it reports nothing rather than guessing -- a linter that cannot
+    # run on a machine without tzdata is a linter that cannot run in CI.
+    #
+    # When a name matches a real zone except in case, the message names the
+    # zone that was probably meant. That is the whole difference between a
+    # rule that shrugs and one that can be acted on.
+    class TimeZoneName < Rule
+      DEFAULT_DIRECTORIES = ["/usr/share/zoneinfo", "/etc/zoneinfo"].freeze
+
+      # `TZ ""` restores the local zone and is not a name to look up.
+      LOCAL = ['""', "''"].freeze
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A TZ name the zone database does not have, or one that differs only in case."
+      end
+
+      def check
+        zones = database
+
+        unless zones.fetch(:exact).empty?
+          check_commands(zones)
+        end
+      end
+
+      private
+
+        def check_commands(zones)
+          document.code_commands.each do |command|
+            document.trigger_for(command).clauses.each do |clause|
+              if clause.name == "TZ"
+                check_clause(command, clause, zones)
+              end
+            end
+          end
+        end
+
+        def check_clause(command, clause, zones)
+          name = written_name(command, clause)
+
+          if name && !zones.fetch(:exact).include?(name)
+            report(
+              command,
+              clause,
+              name,
+              zones,
+            )
+          end
+        end
+
+        def written_name(command, clause)
+          text = command.text[clause.end_offset..].to_s.strip[/\A\S+/]
+
+          if text.nil? || LOCAL.include?(text) || text.include?("[")
+            nil
+          else
+            text.delete('"').delete("'")
+          end
+        end
+
+        def report(command, clause, name, zones)
+          intended = zones.fetch(:folded)[name.downcase]
+
+          offend_at(command.logical_line, clause.offset, message(name, intended))
+        end
+
+        def message(name, intended)
+          if intended
+            "`TZ #{name}` differs only in case from `#{intended}`; zone names are " \
+            "case-sensitive, and an unrecognised one gives undefined results rather " \
+            "than an error"
+          else
+            "`TZ #{name}` is not in the zone database; an unrecognised name gives " \
+            "undefined results rather than an error"
+          end
+        end
+
+        # Two indexes, not one. `exact` decides whether a name is real;
+        # `folded` says what a wrong-case name was probably meant to be. Using
+        # a single hash for both makes `america/toronto` look valid, which is
+        # precisely the case this rule exists to catch.
+        def database
+          @database ||= build(option("Directory", nil))
+        end
+
+        def build(configured)
+          root = configured || DEFAULT_DIRECTORIES.find { |path| Dir.exist?(path) }
+
+          if root.nil?
+            { exact: [], folded: {} }
+          else
+            index(root)
+          end
+        end
+
+        def index(root)
+          exact = []
+          folded = {}
+
+          Dir.glob("**/*", base: root).each do |entry|
+            unless entry.include?(".") || !File.file?(File.join(root, entry))
+              exact << entry
+              folded[entry.downcase] ||= entry
+            end
+          end
+
+          { exact: exact.to_set, folded: folded }
+        end
+    end
+  end
+end
+
+__END__
+
+require "fileutils"
+require "tmpdir"
+
+require_relative "../document"
+
+describe "RemLint::Rules::TimeZoneName" do
+  # A database of its own, so the specs do not depend on what the machine
+  # running them happens to have installed.
+  root = Dir.mktmpdir("remlint-zones")
+  ["America/Toronto", "Europe/Amsterdam", "UTC"].each do |zone|
+    path = File.join(root, zone)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, "")
+  end
+
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::TimeZoneName.new("Directory" => root).run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  it "accepts a zone the database has" do
+    lint.("REM Fri AT 23:30 TZ America/Toronto MSG hi\n").should.be.empty
+    lint.("REM Fri AT 23:30 TZ UTC MSG hi\n").should.be.empty
+  end
+
+  it "accepts a quoted zone name" do
+    lint.(%(REM Fri AT 23:30 TZ "America/Toronto" MSG hi\n)).should.be.empty
+  end
+
+  it "accepts the empty TZ that restores the local zone" do
+    lint.(%(REM Fri AT 23:30 TZ "" MSG hi\n)).should.be.empty
+  end
+
+  it "reports a zone the database does not have" do
+    messages.("REM Fri AT 23:30 TZ Mars/Olympus MSG hi\n").first.should ==
+      "`TZ Mars/Olympus` is not in the zone database; an unrecognised name gives " \
+      "undefined results rather than an error"
+  end
+
+  it "names the zone that was probably meant when only the case differs" do
+    messages.("REM Fri AT 23:30 TZ america/toronto MSG hi\n").first.should.match(
+      /differs only in case from `America\/Toronto`/,
+    )
+  end
+
+  it "says nothing about a computed zone" do
+    lint.("REM Fri AT 23:30 TZ [zone()] MSG hi\n").should.be.empty
+  end
+
+  it "says nothing about a reminder with no TZ" do
+    lint.("REM Fri AT 23:30 MSG hi\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM Fri AT 23:30 TZ Mars/Olympus MSG hi\n").should.be.empty
+  end
+
+  it "reports nothing at all when there is no database to read" do
+    source = RemLint::Source.new(path: "t.rem", text: "REM Fri AT 1:00 TZ Nope MSG hi\n")
+    rule = RemLint::Rules::TimeZoneName.new("Directory" => "/nonexistent/zoneinfo")
+
+    rule.run(RemLint::Document.new(source)).should.be.empty
+  end
+
+  it "points at the clause" do
+    text = "REM Fri AT 23:30 TZ Mars/Olympus MSG hi\n"
+
+    lint.(text).first.column.should == text.index("TZ ") + 1
+  end
+
+  it "reports at warning severity" do
+    lint.("REM Fri AT 23:30 TZ Mars/Olympus MSG hi\n").first.severity.should == "warning"
+  end
+end