remlint 0.1.0

data/lib/remlint/rules/info_clause.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `INFO` clauses a back-end will drop.
+    #
+    # `INFO` attaches a `"Header: value"` pair to a reminder, which the
+    # machine-readable back-ends carry through and `%<Header>` reads back. Two
+    # things go wrong, and a back-end's only recourse for either is to ignore
+    # the clause:
+    #
+    #   INFO with no quoted "Header: value" string
+    #   two INFO clauses on one command with the same header
+    #
+    # Headers are not case-sensitive, so `Url:` and `URL:` on one command are
+    # the same collision -- which is exactly the sort of duplicate that reads
+    # as two distinct pieces of information.
+    #
+    # The reminder still triggers either way. What goes missing is the location
+    # or the URL, silently, in the calendar app at the far end of the export.
+    class InfoClause < Rule
+      # `"Header: value"` -- the header runs to the first colon and cannot
+      # contain a quote.
+      WELL_FORMED = /\A(?<quote>["'])(?<header>[^:"']+):(?<value>.*)\k<quote>\z/m
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "An INFO clause that is malformed, or duplicates another's header."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          check_command(command)
+        end
+      end
+
+      private
+
+        def check_command(command)
+          seen = {}
+
+          document.trigger_for(command).clauses.each do |clause|
+            if clause.name == "INFO"
+              check_clause(command, clause, seen)
+            end
+          end
+        end
+
+        def check_clause(command, clause, seen)
+          argument = argument_of(command, clause)
+          match = argument&.match(WELL_FORMED)
+
+          if match.nil?
+            report_malformed(command, clause, argument)
+          else
+            check_duplicate(
+              command,
+              clause,
+              match[:header].strip,
+              seen,
+            )
+          end
+        end
+
+        # The whole quoted string after the keyword, if there is one.
+        def argument_of(command, clause)
+          tokens = document.tokens_for(command.logical_line)
+          token = tokens[clause.argument_index]
+
+          if token&.type == :string
+            token.value
+          end
+        end
+
+        def report_malformed(command, clause, argument)
+          offend_at(
+            command.logical_line,
+            clause.offset,
+            "`INFO` takes a quoted \"Header: value\" string; " \
+            "#{argument ? "`#{argument}`" : 'this'} is not one",
+          )
+        end
+
+        def check_duplicate(command, clause, header, seen)
+          key = header.downcase
+          first = seen[key]
+
+          if first
+            offend_at(
+              command.logical_line,
+              clause.offset,
+              "`#{header}:` repeats the header given on this command as `#{first}:`; " \
+              "headers are not case-sensitive and cannot be duplicated",
+            )
+          else
+            seen[key] = header
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::InfoClause" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::InfoClause.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "clauses that are fine" do
+    it "accepts a well-formed INFO" do
+      lint.(%(REM 1 Jan INFO "Location: The pub" MSG Meet up\n)).should.be.empty
+    end
+
+    it "accepts two INFO clauses with different headers" do
+      lint.(%(REM 1 Jan INFO "Location: pub" INFO "Url: x" MSG hi\n)).should.be.empty
+    end
+
+    it "accepts a value containing a colon" do
+      lint.(%(REM 1 Jan INFO "Url: https://example.com/x" MSG hi\n)).should.be.empty
+    end
+
+    it "accepts a reminder with no INFO at all" do
+      lint.("REM 1 Jan MSG hi\n").should.be.empty
+    end
+  end
+
+  describe "malformed clauses" do
+    it "reports an unquoted argument" do
+      messages.("REM 1 Jan INFO Location: pub MSG hi\n").first.should.match(
+        /takes a quoted "Header: value" string/,
+      )
+    end
+
+    it "reports a quoted string with no colon" do
+      messages.(%(REM 1 Jan INFO "Location" MSG hi\n)).length.should == 1
+    end
+
+    it "quotes what was written back" do
+      messages.(%(REM 1 Jan INFO "Location" MSG hi\n)).first.should.match(/`"Location"` is not one/)
+    end
+  end
+
+  describe "duplicate headers" do
+    it "reports the same header twice" do
+      messages.(%(REM 1 Jan INFO "Url: a" INFO "Url: b" MSG hi\n)).first.should ==
+        "`Url:` repeats the header given on this command as `Url:`; " \
+        "headers are not case-sensitive and cannot be duplicated"
+    end
+
+    it "reports a header that differs only in case" do
+      messages.(%(REM 1 Jan INFO "Url: a" INFO "URL: b" MSG hi\n)).first.should.match(
+        /`URL:` repeats the header given on this command as `Url:`/,
+      )
+    end
+
+    it "reports only the second of two" do
+      lint.(%(REM 1 Jan INFO "Url: a" INFO "Url: b" MSG hi\n)).length.should == 1
+    end
+
+    it "does not carry headers between commands" do
+      text = %(REM 1 Jan INFO "Url: a" MSG hi\nREM 2 Jan INFO "Url: b" MSG hi\n)
+
+      lint.(text).should.be.empty
+    end
+  end
+
+  it "says nothing about comments" do
+    lint.(%(# REM 1 Jan INFO "Url: a" INFO "Url: b" MSG hi\n)).should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.(%(REM 1 Jan INFO "Location" MSG hi\n)).first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/info_substitution_without_header.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `%<Header>` with no matching `INFO` on the same command.
+    #
+    # `FindTrigInfo` returns NULL and `dosubst.c` ships nothing at all, so the
+    # substitution expands to the empty string. The reminder then reads
+    # `Meeting at ` and looks like a truncation bug somewhere else entirely.
+    #
+    # `INFO` headers are per-command, so this is decidable from one line: the
+    # headers a command carries and the headers its body asks for are both
+    # right there. Matching is case-insensitive, because Remind's header
+    # lookup is.
+    class InfoSubstitutionWithoutHeader < Rule
+      # `INFO "Header: value"` -- the argument is a quoted string whose header
+      # runs up to the first colon.
+      INFO_HEADER = /\A["'](?<header>[^:"']+):/
+
+      REFERENCE = /%<(?<header>[^>]*)>/
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A %<Header> substitution with no INFO clause of that name on the command."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          check_command(command)
+        end
+      end
+
+      private
+
+        def check_command(command)
+          trigger = document.trigger_for(command)
+
+          if trigger.text_body?
+            report(command, headers(command, trigger))
+          end
+        end
+
+        # The headers this command declares, downcased for comparison.
+        def headers(command, trigger)
+          trigger.clauses.filter_map do |clause|
+            if clause.name == "INFO"
+              header_of(command, clause)
+            end
+          end
+        end
+
+        # The header name in the string that follows the INFO keyword.
+        def header_of(command, clause)
+          rest = command.text[clause.end_offset..].to_s
+          match = rest.sub(/\A\s+/, "").match(INFO_HEADER)
+
+          match && match[:header].strip.downcase
+        end
+
+        def report(command, declared)
+          trigger = document.trigger_for(command)
+          body = command.text[trigger.body_offset..].to_s
+
+          body.to_enum(:scan, REFERENCE).each do
+            match = Regexp.last_match
+
+            unless declared.include?(match[:header].strip.downcase)
+              offend_at(command.logical_line, trigger.body_offset + match.begin(0), message(match))
+            end
+          end
+        end
+
+        def message(match)
+          "`%<#{match[:header]}>` has no matching `INFO` clause on this command; " \
+          "it expands to nothing"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::InfoSubstitutionWithoutHeader" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::InfoSubstitutionWithoutHeader.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "references that match" do
+    it "accepts a header the command declares" do
+      lint.(%(REM 1 Jan INFO "Location: The pub" MSG Meet at %<Location>\n)).should.be.empty
+    end
+
+    it "matches case-insensitively, as Remind's lookup does" do
+      lint.(%(REM 1 Jan INFO "Location: pub" MSG Meet at %<LOCATION>\n)).should.be.empty
+      lint.(%(REM 1 Jan INFO "URL: x" MSG See %<Url>\n)).should.be.empty
+    end
+
+    it "accepts several headers on one command" do
+      text = %(REM 1 Jan INFO "Location: pub" INFO "Url: x" MSG %<Location> %<Url>\n)
+
+      lint.(text).should.be.empty
+    end
+
+    it "accepts a header declared after the reference is written" do
+      # Clause order does not matter; both are on the same command.
+      lint.(%(REM 1 Jan INFO "Location: pub" MSG at %<Location>\n)).should.be.empty
+    end
+  end
+
+  describe "references that do not match" do
+    it "reports a header the command never declares" do
+      messages.("REM 1 Jan MSG Meet at %<Location>\n").first.should ==
+        "`%<Location>` has no matching `INFO` clause on this command; it expands to nothing"
+    end
+
+    it "reports a misspelled header" do
+      messages.(%(REM 1 Jan INFO "Location: pub" MSG at %<Locaton>\n)).length.should == 1
+    end
+
+    it "reports each unmatched reference" do
+      messages.("REM 1 Jan MSG %<A> and %<B>\n").length.should == 2
+    end
+
+    it "does not confuse headers between two commands" do
+      text = %(REM 1 Jan INFO "Location: pub" MSG at %<Location>\nREM 2 Jan MSG at %<Location>\n)
+
+      lint.(text).map(&:line).should == [2]
+    end
+
+    it "points at the reference" do
+      text = "REM 1 Jan MSG Meet at %<Location>\n"
+
+      lint.(text).first.column.should == text.index("%<") + 1
+    end
+  end
+
+  describe "what it leaves alone" do
+    it "says nothing about a body with no reference" do
+      lint.(%(REM 1 Jan INFO "Location: pub" MSG Meet up\n)).should.be.empty
+    end
+
+    it "says nothing about a command with no body" do
+      lint.("SET a 1\n").should.be.empty
+    end
+
+    it "says nothing about comments" do
+      lint.("# uses %<Location> somewhere\n").should.be.empty
+    end
+  end
+
+  it "reports at warning severity" do
+    lint.("REM 1 Jan MSG %<Location>\n").first.severity.should == "warning"
+  end
+
+  it "reports the physical line inside a continuation" do
+    lint.("REM 1 Jan MSG a \\\n    %<Location>\n").first.line.should == 2
+  end
+end

data/lib/remlint/rules/invocation_mismatch.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Things a file does that its declared invocation will not deliver.
+    #
+    # Three checks want the command line rather than the file, and a file that
+    # declares one gets all three:
+    #
+    #     # remlint:invocation remind -pp -g /path/to/file
+    #
+    # SORT SPEC. `-g` takes up to four characters, each `a` or `d`. Anything
+    # else is silently ignored, so a sort somebody asked for never happens.
+    #
+    # INFO HEADERS. Plain `-p` does not carry `INFO` to the back-end at all;
+    # `-pp` does. A file full of correct `INFO` clauses and a `-p` invocation
+    # is a reminder that is fine and plumbing that is not, and nothing reports
+    # the gap.
+    #
+    # TODO IN A CALENDAR. `TODO`'s nagging and its overdue tail exist only in
+    # Agenda Mode. In a calendar a `TODO` is an ordinary event, which makes the
+    # keyword a lie about what the reminder does.
+    #
+    # A file with no declaration says nothing about how it is run, so this rule
+    # says nothing about it either.
+    class InvocationMismatch < Rule
+      SORT_CHARACTERS = %w[a d].freeze
+
+      MAX_SORT = 4
+
+      # Where a clause was found, for a message to point at.
+      Site = Struct.new(:line, :column)
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A file whose declared `# remlint:invocation` does not deliver what it uses."
+      end
+
+      def check
+        invocation = document.invocation
+
+        if invocation.declared?
+          check_sort(invocation)
+          check_info(invocation)
+          check_todo(invocation)
+        end
+      end
+
+      private
+
+        def check_sort(invocation)
+          spec = invocation.sort_spec
+
+          if spec && !valid_sort?(spec)
+            offend(declaration_line, sort_message(spec))
+          end
+        end
+
+        def valid_sort?(spec)
+          spec.length <= MAX_SORT &&
+            spec.each_char.all? { |character| SORT_CHARACTERS.include?(character.downcase) }
+        end
+
+        def check_info(invocation)
+          clause = first_clause("INFO")
+
+          if clause && invocation.simple_calendar? && !invocation.carries_info?
+            offend(clause.line, info_message, column: clause.column)
+          end
+        end
+
+        def check_todo(invocation)
+          clause = first_clause("TODO")
+
+          if clause && invocation.calendar?
+            offend(clause.line, todo_message, column: clause.column)
+          end
+        end
+
+        # The first command carrying a clause of that name, as a line and
+        # column to point at. `filter_map` rather than an `each` with a
+        # `break`, which yields the whole array when nothing matches.
+        def first_clause(name)
+          document.code_commands.filter_map { |command| site_of(command, name) }.first
+        end
+
+        def site_of(command, name)
+          found = document.trigger_for(command).find(name)
+
+          if found
+            Site.new(*command.logical_line.position_at(found.offset))
+          end
+        end
+
+        def declaration_line
+          index = document.raw_lines.find_index { |raw| raw.match?(Invocation::DIRECTIVE) }
+
+          document.line_number_at(index || 0)
+        end
+
+        def sort_message(spec)
+          "`-g#{spec}` is not a sort spec Remind reads -- up to #{MAX_SORT} characters, " \
+          "each `a` or `d` -- and the characters it cannot read are ignored, so the sort " \
+          "never happens"
+        end
+
+        def info_message
+          "this file uses `INFO`, but its declared invocation passes plain `-p`, which " \
+          "does not carry headers to the back-end at all; `-pp` does"
+        end
+
+        def todo_message
+          "`TODO`'s nagging and overdue tail exist only in Agenda Mode, and this file " \
+          "declares a calendar invocation -- in a calendar a `TODO` is an ordinary event"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::InvocationMismatch" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::InvocationMismatch.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  it "says nothing about a file that declares no invocation" do
+    lint.(%(REM 1 Jan INFO "Url: x" TODO MSG hi\n)).should.be.empty
+  end
+
+  describe "the sort spec" do
+    it "accepts a spec of a and d" do
+      lint.("# remlint:invocation remind -gaad\nMSG hi\n").should.be.empty
+    end
+
+    it "accepts a bare -g" do
+      lint.("# remlint:invocation remind -g\nMSG hi\n").should.be.empty
+    end
+
+    it "reports a character Remind does not read" do
+      messages.("# remlint:invocation remind -gxq\nMSG hi\n").first.should.match(
+        /is not a sort spec Remind reads/,
+      )
+    end
+
+    it "reports a spec longer than four characters" do
+      messages.("# remlint:invocation remind -gaaaaa\nMSG hi\n").length.should == 1
+    end
+
+    it "explains that the sort never happens" do
+      messages.("# remlint:invocation remind -gx\nMSG hi\n").first.should.match(
+        /the sort never happens/,
+      )
+    end
+  end
+
+  describe "INFO headers" do
+    it "reports INFO under a plain -p invocation" do
+      text = %(# remlint:invocation remind -p\nREM 1 Jan INFO "Url: x" MSG hi\n)
+
+      messages.(text).first.should.match(/passes plain `-p`, which does not carry headers/)
+    end
+
+    it "accepts INFO under -pp" do
+      text = %(# remlint:invocation remind -pp\nREM 1 Jan INFO "Url: x" MSG hi\n)
+
+      lint.(text).should.be.empty
+    end
+
+    it "says nothing about a file with no INFO" do
+      lint.("# remlint:invocation remind -p\nMSG hi\n").should.be.empty
+    end
+
+    it "says nothing under an agenda invocation" do
+      text = %(# remlint:invocation remind -q\nREM 1 Jan INFO "Url: x" MSG hi\n)
+
+      lint.(text).should.be.empty
+    end
+  end
+
+  describe "TODO in a calendar" do
+    it "reports it" do
+      text = "# remlint:invocation remind -c3\nREM 1 TODO MSG File\n"
+
+      messages.(text).first.should.match(/exist only in Agenda Mode/)
+    end
+
+    it "accepts TODO under an agenda invocation" do
+      lint.("# remlint:invocation remind -q\nREM 1 TODO MSG File\n").should.be.empty
+    end
+
+    it "says nothing about a file with no TODO" do
+      lint.("# remlint:invocation remind -c3\nMSG hi\n").should.be.empty
+    end
+
+    it "points at the TODO clause" do
+      text = "# remlint:invocation remind -c3\nREM 1 TODO MSG File\n"
+
+      lint.(text).first.line.should == 2
+    end
+  end
+
+  it "reports every mismatch a file has" do
+    text = %(# remlint:invocation remind -p -gx\nREM 1 INFO "Url: x" TODO MSG hi\n)
+
+    lint.(text).length.should == 3
+  end
+
+  it "reports at warning severity" do
+    lint.("# remlint:invocation remind -gx\nMSG hi\n").first.severity.should == "warning"
+  end
+end