remlint 0.1.0

data/lib/remlint/rules/tk_tag_namespace.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # A hand-written `TAG` in TkRemind's namespace.
+    #
+    # TkRemind finds the `REM` command it is about to edit or delete by its
+    # tag, and it names its own tags `TKTAG` followed by a number. A
+    # hand-written tag in that shape collides, and TkRemind then edits or
+    # deletes the wrong reminder.
+    #
+    # There is no error and no warning. The user clicks a reminder in the GUI,
+    # a different one changes, and nothing anywhere says why -- which makes it
+    # a data-loss bug with no diagnostic attached.
+    class TkTagNamespace < Rule
+      RESERVED = /\ATKTAG\d+\z/i
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A TAG in TkRemind's TKTAGn namespace, which makes the GUI edit the wrong reminder."
+      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 = tag_value(command, clause)
+
+          if value&.match?(RESERVED)
+            offend_at(
+              command.logical_line,
+              clause.offset,
+              "`#{value}` is in TkRemind's own `TKTAGn` namespace; it finds the command " \
+              "to edit by its tag, so a collision makes the GUI change a different " \
+              "reminder with no diagnostic",
+            )
+          end
+        end
+
+        def tag_value(command, clause)
+          token = document.tokens_for(command.logical_line)[clause.argument_index]
+
+          case token&.type
+          when :string then token.value[1..-2]
+          when :name then token.value
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::TkTagNamespace" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::TkTagNamespace.new.run(RemLint::Document.new(source))
+  end
+
+  it "reports a quoted tag in the reserved namespace" do
+    lint.(%(REM 1 Jan TAG "TKTAG1" MSG hi\n)).first.message.should.match(
+      /is in TkRemind's own `TKTAGn` namespace/,
+    )
+  end
+
+  it "reports an unquoted one" do
+    lint.("REM 1 Jan TAG TKTAG42 MSG hi\n").length.should == 1
+  end
+
+  it "matches the prefix case-insensitively" do
+    lint.("REM 1 Jan TAG tktag7 MSG hi\n").length.should == 1
+  end
+
+  it "accepts an ordinary tag" do
+    lint.(%(REM 1 Jan TAG "birthday" MSG hi\n)).should.be.empty
+  end
+
+  it "accepts a tag that merely starts with the prefix" do
+    # TkRemind's are the prefix plus digits and nothing else.
+    lint.(%(REM 1 Jan TAG "TKTAGGED" MSG hi\n)).should.be.empty
+  end
+
+  it "accepts a tag with no digits" do
+    lint.(%(REM 1 Jan TAG "TKTAG" MSG hi\n)).should.be.empty
+  end
+
+  it "says nothing about a reminder with no TAG" do
+    lint.("REM 1 Jan MSG hi\n").should.be.empty
+  end
+
+  it "explains why it matters" do
+    lint.("REM 1 Jan TAG TKTAG1 MSG hi\n").first.message.should.match(
+      /change a different reminder with no diagnostic/,
+    )
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM 1 Jan TAG TKTAG1 MSG hi\n").should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.("REM 1 Jan TAG TKTAG1 MSG hi\n").first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/todo_complete_through.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # A `TODO` with no `COMPLETE-THROUGH`.
+    #
+    # `COMPLETE-THROUGH` tells Remind the date up to which the task has been
+    # done, and it is the starting point of a TODO's entire trigger
+    # calculation. Without it the algorithm starts at Remind's epoch,
+    # 1990-01-01, so the task is decades overdue.
+    #
+    # On its own that is harmless -- the TODO simply fires. It turns into a
+    # defect the moment `MAX-OVERDUE` is added, because `MAX-OVERDUE` then
+    # suppresses a task that is thirty-odd years past due, and the reminder
+    # produces *nothing at all*:
+    #
+    #   REM TODO Mon MAX-OVERDUE 5 MSG x                      -> No reminders.
+    #   REM TODO Mon COMPLETE-THROUGH 2026-01-01 MAX-OVERDUE 5 MSG x  -> fires
+    #
+    # So this reports the pair, not the missing clause alone. The book
+    # described the failure as a reminder that arrives screaming; it is in fact
+    # a reminder that never arrives, which is harder to notice and was worth
+    # checking against the binary rather than taking on trust. Remind's own
+    # `tests/` has twenty-one TODOs with no `COMPLETE-THROUGH` and they are all
+    # fine, because none of them sets `MAX-OVERDUE`.
+    class TodoCompleteThrough < Rule
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A TODO with MAX-OVERDUE and no COMPLETE-THROUGH, which suppresses it entirely."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          trigger = document.trigger_for(command)
+
+          if trigger.include?("TODO") && trigger.include?("MAX-OVERDUE") &&
+             !trigger.include?("COMPLETE-THROUGH")
+            report(command, trigger)
+          end
+        end
+      end
+
+      private
+
+        def report(command, trigger)
+          offend_at(
+            command.logical_line,
+            trigger.find("TODO").offset,
+            "this `TODO` has no `COMPLETE-THROUGH`, so its calculation starts at " \
+            "Remind's epoch and the task is decades overdue -- and the `MAX-OVERDUE` " \
+            "on the same command then suppresses it, so the reminder never appears",
+          )
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::TodoCompleteThrough" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::TodoCompleteThrough.new.run(RemLint::Document.new(source))
+  end
+
+  it "reports a TODO with MAX-OVERDUE and no COMPLETE-THROUGH" do
+    lint.("REM Mon TODO MAX-OVERDUE 5 MSG File\n").first.message.should.match(
+      /suppresses it, so the reminder never appears/,
+    )
+  end
+
+  it "accepts one that has COMPLETE-THROUGH" do
+    text = "REM Mon TODO COMPLETE-THROUGH 2026-01-01 MAX-OVERDUE 5 MSG File\n"
+
+    lint.(text).should.be.empty
+  end
+
+  it "accepts the clauses in any order" do
+    text = "REM Mon MAX-OVERDUE 5 COMPLETE-THROUGH 2026-01-01 TODO MSG File\n"
+
+    lint.(text).should.be.empty
+  end
+
+  it "accepts a TODO with no MAX-OVERDUE, which simply fires" do
+    # Remind's own tests/ has twenty-one of these and they all work.
+    lint.("REM 1 TODO MSG File the accounts\n").should.be.empty
+  end
+
+  it "says nothing about MAX-OVERDUE without a TODO" do
+    lint.("REM 1 MAX-OVERDUE 5 MSG File\n").should.be.empty
+  end
+
+  it "says nothing about a reminder that is not a TODO" do
+    lint.("REM 1 MSG File the accounts\n").should.be.empty
+  end
+
+  it "points at the TODO clause" do
+    text = "REM Mon TODO MAX-OVERDUE 5 MSG File\n"
+
+    lint.(text).first.column.should == text.index("TODO") + 1
+  end
+
+  it "does not read the word todo out of a body" do
+    lint.("REM 1 MSG add this to the todo list\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM Mon TODO MAX-OVERDUE 5 MSG File\n").should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.("REM Mon TODO MAX-OVERDUE 5 MSG File\n").first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/trailing_whitespace.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Whitespace at the end of a line.
+    #
+    # Not bikeshedding in Remind. The shipped `examples/remind.vim` highlights
+    # it as an *error*, with the note "This will match trailing whitespaces
+    # that seem to break rem2ps". A linter that stayed quiet about it would
+    # disagree with the editor Remind ships.
+    #
+    # The pattern is vim's -- `\S\s\+$`, a non-space then whitespace -- so a
+    # line of nothing but spaces is left alone. Emptying such a line is a
+    # cosmetic change and flagging every one of them in a file that has a few
+    # is how a linter teaches people to ignore it.
+    #
+    # A trailing run that follows a backslash belongs to DanglingContinuation,
+    # which has something more useful to say about it, so it is skipped here
+    # rather than reported twice.
+    class TrailingWhitespace < Rule
+      OFFENDING = /\S[ \t]+\z/
+      AFTER_CONTINUATION = /\\[ \t]+\z/
+
+      MESSAGE = "Trailing whitespace (breaks rem2ps output)"
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "Whitespace at the end of a line, which breaks rem2ps output."
+      end
+
+      def check
+        document.each_raw_line do |raw, line|
+          body = raw.chomp
+
+          if offending?(body)
+            offend(line, MESSAGE, column: body.rstrip.length + 1)
+          end
+        end
+      end
+
+      private
+
+        def offending?(body)
+          body.match?(OFFENDING) && !body.match?(AFTER_CONTINUATION)
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::TrailingWhitespace" do
+  lint = proc do |text, config = {}|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::TrailingWhitespace.new(config).run(RemLint::Document.new(source))
+  end
+
+  it "flags a line that ends in a space" do
+    offenses = lint.("MSG hello \n")
+
+    offenses.length.should == 1
+    offenses.first.line.should == 1
+    offenses.first.message.should.match(/rem2ps/)
+  end
+
+  it "points at the first character of the trailing run" do
+    lint.("MSG hello   \n").first.column.should == 10
+  end
+
+  it "flags a trailing tab" do
+    lint.("MSG hello\t\n").length.should == 1
+  end
+
+  it "reports at error severity, as remind.vim does" do
+    lint.("MSG hello \n").first.severity.should == "error"
+  end
+
+  it "says nothing about a clean file" do
+    lint.("MSG hello\nMSG again\n").should.be.empty
+  end
+
+  it "says nothing about a line of nothing but whitespace" do
+    # remind.vim's pattern needs a non-space before the run, and so does this.
+    lint.("MSG hi\n   \nMSG bye\n").should.be.empty
+  end
+
+  it "leaves a dangling continuation to the rule that explains it" do
+    lint.("SET x 1 + \\ \n").should.be.empty
+  end
+
+  it "still flags a line whose backslash is not at the end" do
+    lint.("MSG a \\ b \n").length.should == 1
+  end
+
+  it "flags every offending line in a file" do
+    lint.("MSG a \nMSG b\nMSG c\t\n").map(&:line).should == [1, 3]
+  end
+
+  it "reports lines of a heredoc at their position in the enclosing file" do
+    source = RemLint::Source.new(path: "astro", text: "MSG a \n", line_offset: 40)
+
+    RemLint::Rules::TrailingWhitespace.new.run(RemLint::Document.new(source)).first.line.should == 41
+  end
+
+  it "takes its severity from configuration" do
+    lint.("MSG a \n", "Severity" => "warning").first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/translate_command.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `TRANSLATE` commands Remind will not accept, or will reject silently.
+    #
+    # `TRANSLATE` has five forms and nothing else parses:
+    #
+    #   TRANSLATE "original" "translated"
+    #   TRANSLATE "original"            (removes one)
+    #   TRANSLATE CLEAR
+    #   TRANSLATE DUMP
+    #   TRANSLATE LOAD "file"
+    #
+    # The bare-word forms are the ones that go wrong, because they are one
+    # forgotten pair of quotes away from being a translation *of* the literal
+    # string "CLEAR".
+    #
+    # The other half is the one that matters to a translator. A translated
+    # string has to carry the same `%` escapes as the original, in the same
+    # order -- Remind compares them and refuses the translation outright if
+    # they differ. The message then stays in English, which looks like a
+    # missing translation rather than a rejected one.
+    class TranslateCommand < Rule
+      BARE_WORDS = %w[CLEAR DUMP].freeze
+
+      LOAD = "LOAD"
+
+      # `%a`, `%*b`, `%<Header>` and the rest -- anything the substitution
+      # filter would replace, which both sides have to agree on.
+      ESCAPE = /%\*?(?:<[^>]*>|\{[^}]*\}|\([^)]*\)|.)/
+
+      STRING = /\A\s*"(?:[^"\\]|\\.)*"/
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A TRANSLATE that is not one of Remind's five forms, or whose escapes do not match."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          if command.keyword?("TRANSLATE")
+            check_command(command)
+          end
+        end
+      end
+
+      private
+
+        def check_command(command)
+          args = command.args.strip
+          word = args[/\A\S+/].to_s.upcase
+
+          if BARE_WORDS.include?(word) || word == LOAD
+            nil
+          else
+            check_strings(command, args)
+          end
+        end
+
+        def check_strings(command, args)
+          strings = quoted(args)
+
+          if strings.empty?
+            offend(command.line, form_message(args), column: command.keyword_column)
+          elsif strings.length >= 2
+            compare(command, strings[0], strings[1])
+          end
+        end
+
+        # The one or two quoted strings the command carries.
+        def quoted(args)
+          rest = args.dup
+          found = []
+
+          while (match = rest.match(STRING))
+            found << match[0].strip
+            rest = match.post_match
+          end
+
+          found
+        end
+
+        def compare(command, original, translated)
+          from = original.scan(ESCAPE)
+          to = translated.scan(ESCAPE)
+
+          if from != to
+            offend(command.line, escape_message(from, to), column: command.keyword_column)
+          end
+        end
+
+        def form_message(args)
+          "`TRANSLATE #{args.split(/\s+/).first}` is none of Remind's five forms; it takes " \
+          "a quoted string, two quoted strings, `CLEAR`, `DUMP`, or `LOAD \"file\"`"
+        end
+
+        def escape_message(from, to)
+          "the translation carries #{describe(to)} where the original has #{describe(from)}; " \
+          "Remind compares them and rejects a translation whose escapes differ, leaving " \
+          "the message in English"
+        end
+
+        def describe(escapes)
+          if escapes.empty?
+            "none"
+          else
+            escapes.map { |escape| "`#{escape}`" }.join(" ")
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::TranslateCommand" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::TranslateCommand.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "the five forms" do
+    it "accepts two quoted strings" do
+      lint.(%(TRANSLATE "Monday" "Montag"\n)).should.be.empty
+    end
+
+    it "accepts one quoted string" do
+      lint.(%(TRANSLATE "Monday"\n)).should.be.empty
+    end
+
+    it "accepts CLEAR and DUMP" do
+      lint.("TRANSLATE CLEAR\n").should.be.empty
+      lint.("TRANSLATE DUMP\n").should.be.empty
+    end
+
+    it "accepts LOAD with a filename" do
+      lint.(%(TRANSLATE LOAD "de.rem"\n)).should.be.empty
+    end
+
+    it "accepts the bare words in lower case" do
+      lint.("translate clear\n").should.be.empty
+    end
+
+    it "reports anything else" do
+      messages.("TRANSLATE Monday Montag\n").first.should.match(
+        /is none of Remind's five forms/,
+      )
+    end
+  end
+
+  describe "escapes that do not match" do
+    it "reports a missing escape" do
+      messages.(%(TRANSLATE "in %b" "in"\n)).first.should.match(
+        /carries none where the original has `%b`/,
+      )
+    end
+
+    it "reports an added escape" do
+      messages.(%(TRANSLATE "today" "heute %b"\n)).first.should.match(/carries `%b`/)
+    end
+
+    it "reports escapes in a different order" do
+      messages.(%(TRANSLATE "%a and %b" "%b und %a"\n)).first.should.match(
+        /carries `%b` `%a` where the original has `%a` `%b`/,
+      )
+    end
+
+    it "accepts matching escapes" do
+      lint.(%(TRANSLATE "%a and %b" "%a und %b"\n)).should.be.empty
+    end
+
+    it "accepts two strings with no escapes at all" do
+      lint.(%(TRANSLATE "Monday" "Montag"\n)).should.be.empty
+    end
+
+    it "explains what Remind does about it" do
+      messages.(%(TRANSLATE "in %b" "in"\n)).first.should.match(/leaving the message in English/)
+    end
+  end
+
+  it "says nothing about comments" do
+    lint.("# TRANSLATE Monday Montag\n").should.be.empty
+  end
+
+  it "points at the keyword" do
+    lint.("   TRANSLATE Monday Montag\n").first.column.should == 4
+  end
+
+  it "reports at warning severity" do
+    lint.("TRANSLATE Monday Montag\n").first.severity.should == "warning"
+  end
+end