remlint 0.1.0

data/lib/remlint/rules/generated_file_edited.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Hand-written commands in a file a tool owns.
+    #
+    # TkRemind appends to its own file; `ics2rem` and `radicale-remind`
+    # regenerate theirs from the other side of a sync. A command written into
+    # one of those by hand survives until the next write and then does not, and
+    # in the meantime the file mixes authored and generated state in something
+    # no human is expected to read.
+    #
+    # Which files a tool owns is not something the linter can work out, so it is
+    # configured -- `GeneratedFiles` takes shell globs. With none configured the
+    # rule has nothing to say, which is the honest default rather than a guess
+    # about anybody's layout.
+    #
+    # Comments are not reported: a note at the top of a generated file is how
+    # people mark it as generated in the first place.
+    class GeneratedFileEdited < Rule
+      # What the tools write, and so what is *not* a hand edit. TkRemind tags
+      # everything it appends.
+      GENERATED_TAG = /\bTAG\s+"?TKTAG\d+/i
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "Hand-written commands in a file listed under GeneratedFiles."
+      end
+
+      def check
+        patterns = option("GeneratedFiles", [])
+
+        if !patterns.empty? && generated?(patterns)
+          report
+        end
+      end
+
+      private
+
+        def generated?(patterns)
+          patterns.any? do |pattern|
+            File.fnmatch?(pattern, document.path.to_s, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+        end
+
+        def report
+          hand_written.each do |command|
+            offend(
+              command.line,
+              "this file is generated, and a hand-written command in it survives only " \
+              "until the tool next writes the file",
+              column: command.keyword_column,
+            )
+          end
+        end
+
+        # Anything the tool did not put there itself.
+        def hand_written
+          document.code_commands.reject { |command| command.text.match?(GENERATED_TAG) }
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::GeneratedFileEdited" do
+  lint = proc do |text, path = "calendar.rem", config = {}|
+    source = RemLint::Source.new(path: path, text: text)
+
+    RemLint::Rules::GeneratedFileEdited.new(config).run(RemLint::Document.new(source))
+  end
+
+  owned = { "GeneratedFiles" => ["*.generated.rem", "tkremind/*.rem"] }
+
+  it "says nothing when no files are declared generated" do
+    lint.("REM 1 Jan MSG hi\n").should.be.empty
+  end
+
+  it "says nothing about a file outside the patterns" do
+    lint.("REM 1 Jan MSG hi\n", "mine.rem", owned).should.be.empty
+  end
+
+  it "reports a hand-written command in a generated file" do
+    offenses = lint.("REM 1 Jan MSG hi\n", "notes.generated.rem", owned)
+
+    offenses.length.should == 1
+    offenses.first.message.should.match(/survives only until the tool next writes the file/)
+  end
+
+  it "matches a pattern with a directory" do
+    lint.("REM 1 Jan MSG hi\n", "tkremind/appts.rem", owned).length.should == 1
+  end
+
+  it "does not report what TkRemind wrote itself" do
+    text = %(REM 1 Jan TAG "TKTAG1" MSG Appointment\n)
+
+    lint.(text, "tkremind/appts.rem", owned).should.be.empty
+  end
+
+  it "reports only the hand-written commands among generated ones" do
+    text = %(REM 1 Jan TAG "TKTAG1" MSG Generated\nREM 2 Jan MSG By hand\n)
+
+    lint.(text, "tkremind/appts.rem", owned).map(&:line).should == [2]
+  end
+
+  it "says nothing about comments, which is how files are marked generated" do
+    lint.("# Generated by TkRemind -- do not edit\n", "tkremind/a.rem", owned).should.be.empty
+  end
+
+  it "points at the keyword" do
+    lint.("   REM 1 Jan MSG hi\n", "a.generated.rem", owned).first.column.should == 4
+  end
+
+  it "reports at warning severity" do
+    lint.("REM 1 Jan MSG hi\n", "a.generated.rem", owned).first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/hebrew_date.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Hebrew dates that cannot exist.
+    #
+    # `hebdate(day, month, year)` returns `Invalid Hebrew date` for a month
+    # Remind does not know and for a day past that month's length. Both are
+    # decidable from literals, and both fail on the day the reminder would
+    # otherwise have fired.
+    #
+    # The lengths are `MaxMonLen[]` from src/hbcal.c, and they are *not* the
+    # textbook fixed ones: Heshvan and Kislev are recomputed from each year's
+    # length -- a Hebrew year runs 353, 354 or 355 days -- so this reports the
+    # maximum any year allows. Confirmed against the binary across seven
+    # consecutive years.
+    #
+    # The names are all three of Remind's tables: `HebMonthNames`,
+    # `IvritMonthNames` in Hebrew script, and `AltMonthSpellings`, which is why
+    # `Tishri`, `Cheshvan`, `Shevat`, `Tammuz`, `Iyyar`, `Adar I` and their
+    # Hebrew equivalents are all accepted. Missing that third table reports 31
+    # offences against Remind's own tests/test.rem.
+    #
+    # `hebmon()` returns the canonical transliteration, so a comparison against
+    # an accepted-but-non-canonical spelling is never true even where `hebdate`
+    # takes it -- which the message says.
+    class HebrewDate < Rule
+      # `MaxMonLen[]` from src/hbcal.c, in the order its month constants
+      # define: Tishrey, Heshvan, Kislev, Tevet, Shvat, Adar A, Adar B,
+      # Nisan, Iyar, Sivan, Tamuz, Av, Elul, Adar.
+      MAX_LENGTHS = [30, 30, 30, 29, 30, 30, 29, 30, 29, 30, 29, 30, 29, 29].freeze
+
+      CANONICAL = [
+        "Tishrey", "Heshvan", "Kislev", "Tevet", "Shvat", "Adar A", "Adar B",
+        "Nisan", "Iyar", "Sivan", "Tamuz", "Av", "Elul", "Adar"
+      ].freeze
+
+      # `IvritMonthNames` -- the same months in Hebrew script.
+      IVRIT = [
+        "\u05EA\u05E9\u05E8\u05D9", "\u05D7\u05E9\u05D5\u05D5\u05DF",
+        "\u05DB\u05E1\u05DC\u05D5", "\u05D8\u05D1\u05EA",
+        "\u05E9\u05D1\u05D8", "\u05D0\u05D3\u05E8 \u05D0'",
+        "\u05D0\u05D3\u05E8 \u05D1'", "\u05E0\u05D9\u05E1\u05DF",
+        "\u05D0\u05D9\u05D9\u05E8", "\u05E1\u05D9\u05D5\u05DF",
+        "\u05EA\u05DE\u05D5\u05D6", "\u05D0\u05D1",
+        "\u05D0\u05DC\u05D5\u05DC", "\u05D0\u05D3\u05E8"
+      ].freeze
+
+      # `AltMonthSpellings` -- name => the month index it resolves to.
+      ALTERNATES = {
+        "Tishri"                    => 0,
+        "Tishrei"                   => 0,
+        "Cheshvan"                  => 1,
+        "Kheshvan"                  => 1,
+        "Shevat"                    => 4,
+        "Tammuz"                    => 10,
+        "Adar 1"                    => 5,
+        "Adar I"                    => 5,
+        "\u05D0\u05D3\u05E8 \u05D0" => 5,
+        "\u05D0\u05D3\u05E8 1"      => 5,
+        "\u05D0\u05D3\u05E8 I"      => 5,
+        "Adar 2"                    => 6,
+        "Adar II"                   => 6,
+        "\u05D0\u05D3\u05E8 \u05D1" => 6,
+        "\u05D0\u05D3\u05E8 2"      => 6,
+        "\u05D0\u05D3\u05E8 II"     => 6,
+        "Iyyar"                     => 8,
+      }.freeze
+
+      MONTHS = (
+        CANONICAL.each_with_index.to_h { |name, index| [name.downcase, MAX_LENGTHS[index]] }
+          .merge(IVRIT.each_with_index.to_h { |name, index| [name, MAX_LENGTHS[index]] })
+          .merge(ALTERNATES.transform_keys(&:downcase)
+                           .transform_values { |index| MAX_LENGTHS[index] })
+      ).freeze
+
+      # `hebdate(30, "Elul", 5790)` and the two-argument form.
+      CALL = /\bhebdate\s*\(\s*(?<day>\d+)\s*,\s*"(?<month>[^"]+)"/i
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "A Hebrew month Remind does not know, or a day past that month's length."
+      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)
+          logical_line.text.to_enum(:scan, CALL).each do
+            match = Regexp.last_match
+
+            report(logical_line, match)
+          end
+        end
+
+        def report(logical_line, match)
+          month = match[:month].strip
+          longest = MONTHS[month.downcase]
+
+          if longest.nil?
+            offend_at(logical_line, match.begin(0), unknown_message(month))
+          elsif match[:day].to_i < 1 || match[:day].to_i > longest
+            offend_at(logical_line, match.begin(0), length_message(match[:day], month, longest))
+          end
+        end
+
+        def unknown_message(month)
+          "`#{month}` is not a Hebrew month Remind knows; `hebdate` returns " \
+          "`Invalid Hebrew date`, and `hebmon()` returns the canonical spelling, " \
+          "so a comparison against this is never true either"
+        end
+
+        def length_message(day, month, longest)
+          "`#{month}` never has #{day} days -- #{longest} at most -- so `hebdate` " \
+          "returns `Invalid Hebrew date`"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::HebrewDate" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::HebrewDate.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "dates that exist" do
+    it "accepts a 30-day month at 30" do
+      lint.(%(MSG [hebdate(30, "Nisan", 5790)]\n)).should.be.empty
+      lint.(%(MSG [hebdate(30, "Tishrey", 5790)]\n)).should.be.empty
+    end
+
+    it "accepts the months whose length varies by year at 30" do
+      # Heshvan and Kislev are 29 or 30 depending on the year's length.
+      lint.(%(MSG [hebdate(30, "Heshvan", 5790)]\n)).should.be.empty
+      lint.(%(MSG [hebdate(30, "Kislev", 5790)]\n)).should.be.empty
+    end
+
+    it "accepts a 29-day month at 29" do
+      lint.(%(MSG [hebdate(29, "Elul", 5790)]\n)).should.be.empty
+    end
+
+    it "accepts the leap-month spellings" do
+      lint.(%(MSG [hebdate(29, "Adar A", 5790)]\n)).should.be.empty
+      lint.(%(MSG [hebdate(29, "Adar B", 5790)]\n)).should.be.empty
+    end
+
+    it "accepts the alternate spellings Remind lists" do
+      # tests/test.rem exercises every one of these.
+      %w[Tishri Tishrei Cheshvan Kheshvan Shevat Tammuz Iyyar].each do |name|
+        lint.(%(MSG [hebdate(1, "#{name}", 5790)]\n)).should.be.empty
+      end
+    end
+
+    it "accepts the Adar variants" do
+      ["Adar 1", "Adar I", "Adar 2", "Adar II"].each do |name|
+        lint.(%(MSG [hebdate(1, "#{name}", 5790)]\n)).should.be.empty
+      end
+    end
+
+    it "accepts the Hebrew-script names" do
+      lint.(%(MSG [hebdate(1, "\u05EA\u05E9\u05E8\u05D9", 5790)]\n)).should.be.empty
+      lint.(%(MSG [hebdate(1, "\u05D0\u05DC\u05D5\u05DC", 5790)]\n)).should.be.empty
+    end
+
+    it "applies the right length to an alternate spelling" do
+      # Cheshvan is Heshvan, which reaches 30; Tammuz is Tamuz, which does not.
+      lint.(%(MSG [hebdate(30, "Cheshvan", 5790)]\n)).should.be.empty
+      lint.(%(MSG [hebdate(30, "Tammuz", 5790)]\n)).length.should == 1
+    end
+
+    it "matches the month name case-insensitively" do
+      lint.(%(MSG [hebdate(29, "elul", 5790)]\n)).should.be.empty
+    end
+  end
+
+  describe "dates that cannot exist" do
+    it "reports a day past a 29-day month" do
+      # The book's example, confirmed against Remind.
+      messages.(%(MSG [hebdate(30, "Elul", 5790)]\n)).first.should ==
+        "`Elul` never has 30 days -- 29 at most -- so `hebdate` returns `Invalid Hebrew date`"
+    end
+
+    it "reports Tevet at 30" do
+      messages.(%(MSG [hebdate(30, "Tevet", 5790)]\n)).length.should == 1
+    end
+
+    it "reports a day past every month" do
+      messages.(%(MSG [hebdate(31, "Nisan", 5790)]\n)).length.should == 1
+    end
+
+    it "reports a day of zero" do
+      messages.(%(MSG [hebdate(0, "Nisan", 5790)]\n)).length.should == 1
+    end
+
+    it "reports a month Remind does not know" do
+      messages.(%(MSG [hebdate(1, "Nosuch", 5790)]\n)).first.should.match(
+        /is not a Hebrew month Remind knows/,
+      )
+    end
+
+    it "mentions that hebmon returns the canonical spelling" do
+      messages.(%(MSG [hebdate(1, "Nosuch", 5790)]\n)).first.should.match(
+        /`hebmon\(\)` returns the canonical spelling/,
+      )
+    end
+
+    it "points at the call" do
+      text = %(MSG [hebdate(30, "Elul", 5790)]\n)
+
+      lint.(text).first.column.should == text.index("hebdate") + 1
+    end
+  end
+
+  it "says nothing about a computed day" do
+    lint.(%(MSG [hebdate(d, "Elul", 5790)]\n)).should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.(%(# MSG [hebdate(30, "Elul", 5790)]\n)).should.be.empty
+  end
+
+  it "reports at error severity" do
+    lint.(%(MSG [hebdate(30, "Elul", 5790)]\n)).first.severity.should == "error"
+  end
+end

data/lib/remlint/rules/iftrig_with_satisfy.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `SATISFY` inside an `IFTRIG`.
+    #
+    # `IFTRIG` accepts any trigger a `REM` would, with exactly one exception:
+    # `SATISFY`. The exclusion is trivial to trip over, because the natural way
+    # to write an `IFTRIG` is to copy a working `REM` and change the keyword --
+    # and every other clause survives that edit.
+    class IftrigWithSatisfy < Rule
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "SATISFY inside an IFTRIG, which is the one clause IFTRIG does not take."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          if command.keyword?("IFTRIG")
+            check_iftrig(command)
+          end
+        end
+      end
+
+      private
+
+        def check_iftrig(command)
+          satisfy = document.trigger_for(command).body
+
+          if satisfy&.name == "SATISFY"
+            offend_at(
+              command.logical_line,
+              satisfy.offset,
+              "`IFTRIG` takes every clause `REM` does except `SATISFY`",
+            )
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::IftrigWithSatisfy" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::IftrigWithSatisfy.new.run(RemLint::Document.new(source))
+  end
+
+  it "reports SATISFY in an IFTRIG" do
+    offenses = lint.("IFTRIG 13 SATISFY [$Tw == 5]\nMSG Friday the 13th\nENDIF\n")
+
+    offenses.length.should == 1
+    offenses.first.line.should == 1
+    offenses.first.message.should.match(/except `SATISFY`/)
+  end
+
+  it "points at the SATISFY" do
+    text = "IFTRIG 13 SATISFY [$Tw == 5]\n"
+
+    lint.(text).first.column.should == text.index("SATISFY") + 1
+  end
+
+  it "accepts an IFTRIG with any other clause" do
+    lint.("IFTRIG 1 Jan UNTIL 2027-01-01 AT 15:00\n").should.be.empty
+    lint.("IFTRIG Tue SCANFROM -7\n").should.be.empty
+  end
+
+  it "accepts SATISFY on a REM, where it is legal" do
+    lint.("REM 13 SATISFY [$Tw == 5] MSG Boo!\n").should.be.empty
+  end
+
+  it "matches an abbreviated IFTRIG" do
+    # IFTRIG's minimum abbreviation length is 6, so IFTRIG is the short form.
+    lint.("IFTRIG 13 SATISFY [1]\n").length.should == 1
+  end
+
+  it "is case-insensitive" do
+    lint.("iftrig 13 satisfy [1]\n").length.should == 1
+  end
+
+  it "says nothing about the word satisfy in a comment" do
+    lint.("# IFTRIG and SATISFY do not mix\n").should.be.empty
+  end
+
+  it "reports at error severity" do
+    lint.("IFTRIG 13 SATISFY [1]\n").first.severity.should == "error"
+  end
+
+  it "reports the physical line inside a continuation" do
+    lint.("IFTRIG 13 \\\n    SATISFY [1]\n").first.line.should == 2
+  end
+end

data/lib/remlint/rules/include_path.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `INCLUDE` and `SYSINCLUDE` paths that do not mean what they look like.
+    #
+    # TWO KEYWORDS, TWO BASE DIRECTORIES. `INCLUDE` resolves a relative path
+    # against the *working directory*, not against the directory of the file
+    # doing the including. The manual calls this a mistake kept for
+    # compatibility, and `DO` is the keyword that resolves relative to the
+    # file. So `INCLUDE defs.rem` works when you run Remind from the directory
+    # the script lives in and fails from anywhere else -- from cron, most
+    # memorably.
+    #
+    # `SYSINCLUDE` with an absolute path is the mirror image: for an absolute
+    # path it is simply `INCLUDE`, so the keyword reads as though it pointed
+    # into the system include directory when it does not.
+    #
+    # A path built from an expression -- `[$SysInclude]/ansitext.rem`, which is
+    # how `examples/ansitext` does it -- is left alone, because what it
+    # resolves to is not decidable here.
+    class IncludePath < Rule
+      ABSOLUTE = %r{\A/}
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "INCLUDE with a relative path, where DO resolves relative to the file, " \
+        "or SYSINCLUDE with an absolute one."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          path = literal_path(command)
+
+          if path
+            report(command, path)
+          end
+        end
+      end
+
+      private
+
+        # The argument, when it is a plain path rather than something computed.
+        def literal_path(command)
+          if command.keyword?("INCLUDE", "SYSINCLUDE")
+            text = command.args.strip
+
+            unless text.empty? || text.include?("[") || text.include?("$")
+              text
+            end
+          end
+        end
+
+        def report(command, path)
+          if command.keyword?("INCLUDE") && !path.match?(ABSOLUTE)
+            offend(command.line, relative_message(path), column: command.keyword_column)
+          elsif command.keyword?("SYSINCLUDE") && path.match?(ABSOLUTE)
+            offend(command.line, absolute_message(path), column: command.keyword_column)
+          end
+        end
+
+        def relative_message(path)
+          "`INCLUDE #{path}` resolves against the working directory, not this file's " \
+          "directory; `DO #{path}` resolves relative to the file"
+        end
+
+        def absolute_message(path)
+          "`SYSINCLUDE #{path}` is just `INCLUDE` for an absolute path, so the keyword " \
+          "reads as though it pointed into the system include directory"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::IncludePath" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::IncludePath.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "INCLUDE" do
+    it "reports a relative path" do
+      messages.("INCLUDE defs.rem\n").first.should ==
+        "`INCLUDE defs.rem` resolves against the working directory, not this file's " \
+        "directory; `DO defs.rem` resolves relative to the file"
+    end
+
+    it "reports a path with a directory component" do
+      messages.("INCLUDE holidays/us.rem\n").length.should == 1
+    end
+
+    it "reports a path that starts with a dot" do
+      messages.("INCLUDE ./defs.rem\n").length.should == 1
+    end
+
+    it "accepts an absolute path" do
+      lint.("INCLUDE /etc/remind/defs.rem\n").should.be.empty
+    end
+
+    it "accepts DO, which resolves relative to the file" do
+      lint.("DO defs.rem\n").should.be.empty
+    end
+
+    it "matches the abbreviated keyword" do
+      messages.("INC defs.rem\n").length.should == 1
+    end
+  end
+
+  describe "SYSINCLUDE" do
+    it "reports an absolute path" do
+      messages.("SYSINCLUDE /etc/remind/defs.rem\n").first.should.match(
+        /is just `INCLUDE` for an absolute path/,
+      )
+    end
+
+    it "accepts a relative path, which is what it is for" do
+      lint.("SYSINCLUDE ansitext.rem\n").should.be.empty
+    end
+  end
+
+  describe "paths it cannot resolve" do
+    it "says nothing about a bracketed expression" do
+      # How examples/ansitext writes it.
+      lint.("INCLUDE [$SysInclude]/ansitext.rem\n").should.be.empty
+    end
+
+    it "says nothing about a path built from a variable" do
+      lint.("INCLUDE $SomeDir/defs.rem\n").should.be.empty
+    end
+  end
+
+  it "says nothing about comments" do
+    lint.("# INCLUDE defs.rem\n").should.be.empty
+  end
+
+  it "points at the keyword" do
+    lint.("   INCLUDE defs.rem\n").first.column.should == 4
+  end
+
+  it "reports at warning severity" do
+    lint.("INCLUDE defs.rem\n").first.severity.should == "warning"
+  end
+end