remlint 0.1.0

data/lib/remlint/rules/callback_signature.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Callback functions defined with the wrong number of arguments.
+    #
+    # Remind calls a dozen or so functions by name and by shape. It does not
+    # look them up and adapt -- it checks the arity and, if it does not match,
+    # walks away:
+    #
+    #   UserFuncExists("msgprefix") == 1     src/dorem.c
+    #   check_subst_args(func, 3)            src/dosubst.c
+    #
+    # So a `msgprefix(p, q)` is never called. Not called with an error, not
+    # called with a warning: the prefix simply does not appear, and the
+    # obvious conclusion is that the callback mechanism is broken rather than
+    # that the signature is.
+    #
+    # This is `FunctionArity` turned around. That rule checks calls against the
+    # functions they name; this one checks *definitions* against the shape
+    # Remind will call them with.
+    class CallbackSignature < Rule
+      # name => arity Remind insists on.
+      #
+      # One argument: the prefix and suffix callbacks (given the priority) and
+      # the two ordinal helpers. Three: the substitution-filter family, called
+      # as `name(altmode, date, time)`.
+      ONE_ARGUMENT = %w[msgprefix msgsuffix calprefix calsuffix ordx subst_ampm subst_ordinal].freeze
+
+      THREE_ARGUMENTS = %w[
+        subst_at subst_atx subst_bang subst_bangx subst_colon subst_colonx
+        subst_hash subst_hashx subst_question subst_questionx
+      ].freeze
+
+      ARITIES = (
+        ONE_ARGUMENT.to_h { |name| [name, 1] }
+          .merge(THREE_ARGUMENTS.to_h { |name| [name, 3] })
+      ).freeze
+
+      # `get_function_override` builds `subst_<c>` and `subst_<c>x` for a
+      # *single* alphanumeric or underscore character (src/dosubst.c). So
+      # `subst_a` and `subst_ax` are callbacks and `subst_a_alt` is not -- it
+      # is an ordinary helper, and Remind's own language packs are full of
+      # them. Getting this wrong reports 45 offences against `include/lang`.
+      OVERRIDE = /\Asubst_[a-z0-9_]x?\z/
+
+      # A `%{name}` in the file makes `subst_name` a callback, called with the
+      # same three arguments.
+      NAMED = /%\{(?<name>[^}]*)\}/
+
+      DEFINITION = /\A(?:-\s*)?(?<name>[A-Za-z_]\w*)\s*\((?<params>[^)]*)\)/
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A Remind callback function defined with the wrong number of arguments."
+      end
+
+      def check
+        @named = named_substitutions
+
+        document.code_commands.each do |command|
+          if command.keyword?("FSET")
+            check_definition(command)
+          end
+        end
+      end
+
+      private
+
+        def check_definition(command)
+          match = command.args.match(DEFINITION)
+          expected = match && arity_for(match[:name].downcase)
+
+          if expected
+            compare(command, match, expected)
+          end
+        end
+
+        def arity_for(name)
+          if ARITIES.key?(name)
+            ARITIES.fetch(name)
+          elsif name.match?(OVERRIDE) || @named.include?(name)
+            3
+          end
+        end
+
+        # `subst_` names this file actually asks Remind to call.
+        def named_substitutions
+          document.code_commands.flat_map do |command|
+            command.text.scan(NAMED).flatten.map { |name| "subst_#{name.downcase}" }
+          end
+        end
+
+        def compare(command, match, expected)
+          actual = count(match[:params])
+
+          if actual != expected
+            offend(command.line, message(match[:name], expected, actual), column: command.keyword_column)
+          end
+        end
+
+        def count(params)
+          if params.strip.empty?
+            0
+          else
+            params.split(",").length
+          end
+        end
+
+        def message(name, expected, actual)
+          "`#{name}` is a Remind callback and is called with #{expected} " \
+          "argument#{expected == 1 ? '' : 's'}, not #{actual}; defined this way it is " \
+          "never called at all, and nothing says so"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::CallbackSignature" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::CallbackSignature.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "the one-argument callbacks" do
+    it "accepts the right shape" do
+      lint.(%(FSET msgprefix(p) "[" + p + "] "\n)).should.be.empty
+      lint.(%(FSET msgsuffix(p) char(8)\n)).should.be.empty
+      lint.(%(FSET calprefix(p) ""\n)).should.be.empty
+      lint.(%(FSET ordx(n) "th"\n)).should.be.empty
+    end
+
+    it "reports two arguments" do
+      messages.(%(FSET msgprefix(p, q) ""\n)).first.should ==
+        "`msgprefix` is a Remind callback and is called with 1 argument, not 2; " \
+        "defined this way it is never called at all, and nothing says so"
+    end
+
+    it "reports none" do
+      messages.(%(FSET msgprefix() ""\n)).length.should == 1
+    end
+
+    it "accepts subst_ampm and subst_ordinal, which take one" do
+      lint.(%(FSET subst_ampm(x) "am"\n)).should.be.empty
+      lint.(%(FSET subst_ordinal(x) "st"\n)).should.be.empty
+    end
+  end
+
+  describe "the three-argument substitution family" do
+    it "accepts the right shape" do
+      lint.(%(FSET subst_at(a, d, t) "at"\n)).should.be.empty
+      lint.(%(FSET subst_bangx(a, d, t) "is"\n)).should.be.empty
+    end
+
+    it "reports the wrong shape" do
+      messages.(%(FSET subst_at(a, d) "at"\n)).first.should.match(
+        /called with 3 arguments, not 2/,
+      )
+    end
+
+    it "applies to the single-character overrides Remind builds" do
+      messages.(%(FSET subst_a(x) "y"\n)).first.should.match(/called with 3 arguments, not 1/)
+      messages.(%(FSET subst_ax(x) "y"\n)).first.should.match(/called with 3 arguments, not 1/)
+      lint.(%(FSET subst_a(a, d, t) "y"\n)).should.be.empty
+    end
+
+    it "applies to a subst_ name the file reaches through %{name}" do
+      text = %(FSET subst_myown(a) "x"\nREM 1 Jan MSG %{myown}\n)
+
+      messages.(text).first.should.match(/called with 3 arguments, not 1/)
+    end
+
+    it "leaves an ordinary subst_ helper alone" do
+      # include/lang/*.rem define dozens of these, and Remind never calls them
+      # -- they are helpers the pack calls itself.
+      lint.(%(FSET subst_a_alt(x) "y"\n)).should.be.empty
+      lint.(%(FSET subst_hours(x) "y"\n)).should.be.empty
+      lint.(%(FSET subst_tdiff(a, b) "y"\n)).should.be.empty
+    end
+  end
+
+  describe "what it leaves alone" do
+    it "says nothing about an ordinary function" do
+      lint.("FSET double(x) x * 2\n").should.be.empty
+      lint.("FSET greet(a, b, c, d) a\n").should.be.empty
+    end
+
+    it "matches the callback name case-insensitively" do
+      messages.(%(FSET MsgPrefix(p, q) ""\n)).length.should == 1
+    end
+
+    it "accepts the FSET - form and still checks the shape" do
+      lint.(%(FSET - msgprefix(p) ""\n)).should.be.empty
+      messages.(%(FSET - msgprefix(p, q) ""\n)).length.should == 1
+    end
+
+    it "says nothing about comments" do
+      lint.(%(# FSET msgprefix(p, q) ""\n)).should.be.empty
+    end
+  end
+
+  it "points at the keyword" do
+    lint.(%(   FSET msgprefix(p, q) ""\n)).first.column.should == 4
+  end
+
+  it "reports at warning severity" do
+    lint.(%(FSET msgprefix(p, q) ""\n)).first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/clause_needs_full_date.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+require_relative "../date_literal"
+
+module RemLint
+  module Rules
+    # Clauses given a partial date where a full one is required.
+    #
+    # `FROM`, `UNTIL`, `THROUGH` and `COMPLETE-THROUGH` all read their argument
+    # with `GetFullDate`, which insists on a year, a month and a day. A partial
+    # date is `E_PARSE_ERR`.
+    #
+    # `COMPLETE-THROUGH` is the one that costs most. It is the starting point
+    # of a TODO's whole trigger calculation, so a partial date does not merely
+    # fail -- when the clause is missing or unusable the algorithm starts at
+    # 1990-01-01 and the TODO is overdue by decades on its first run.
+    #
+    # Only reported when the argument is written out. A computed `[expr]` may
+    # yield a perfectly good DATE and is not this rule's business.
+    #
+    # `OMIT` is excluded entirely. `OMIT ... THROUGH ...` is the omit-range
+    # syntax rather than a reminder's expiry, and it takes partial dates on
+    # purpose: Remind's own `tests/test.rem` writes `OMIT Jun THROUGH July 15`
+    # and `OMIT Apr 2022 through July`.
+    class ClauseNeedsFullDate < Rule
+      CLAUSES = %w[FROM UNTIL THROUGH COMPLETE-THROUGH].freeze
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "FROM, UNTIL, THROUGH or COMPLETE-THROUGH given a date that is not fully specified."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          unless command.keyword?("OMIT")
+            check_command(command)
+          end
+        end
+      end
+
+      private
+
+        def check_command(command)
+          trigger = document.trigger_for(command)
+
+          CLAUSES.each do |name|
+            check_clause(command, trigger.find(name))
+          end
+        end
+
+        def check_clause(command, clause)
+          if clause && !computed?(command, clause) && missing(command, clause)
+            offend_at(command.logical_line, clause.offset, message(clause, command))
+          end
+        end
+
+        # A bracketed expression right after the keyword supplies the date at
+        # run time.
+        def computed?(command, clause)
+          tokens = document.tokens_for(command.logical_line)
+
+          tokens[clause.argument_index]&.type == :lbracket
+        end
+
+        # The components `GetFullDate` did not get.
+        def missing(command, clause)
+          tokens = document.tokens_for(command.logical_line)
+          date = DateLiteral.at(tokens, clause.argument_index)
+
+          date.nil?
+        end
+
+        def message(clause, command)
+          "`#{clause.name}` needs a full date -- a year, a month and a day -- " \
+          "and #{written(command, clause)} is not one"
+        end
+
+        def written(command, clause)
+          rest = command.text[clause.end_offset..].to_s
+          words = rest.strip.split(/\s+/).first(3).join(" ")
+
+          "`#{words}`"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::ClauseNeedsFullDate" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::ClauseNeedsFullDate.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "dates that are complete" do
+    it "accepts the ISO form" do
+      lint.("REM Mon UNTIL 2027-01-01 MSG hi\n").should.be.empty
+    end
+
+    it "accepts the spelled-out form" do
+      lint.("REM Mon UNTIL 1 Jan 2027 MSG hi\n").should.be.empty
+      lint.("REM Mon FROM Jan 1 2027 MSG hi\n").should.be.empty
+    end
+
+    it "accepts COMPLETE-THROUGH with a full date" do
+      lint.("REM Mon COMPLETE-THROUGH 2027-01-01 TODO MSG hi\n").should.be.empty
+    end
+  end
+
+  describe "dates that are partial" do
+    it "reports a missing year" do
+      messages.("REM Mon UNTIL 1 Jan MSG hi\n").first.should ==
+        "`UNTIL` needs a full date -- a year, a month and a day -- and `1 Jan MSG` is not one"
+    end
+
+    it "reports a missing day" do
+      messages.("REM Mon FROM Jan 2027 MSG hi\n").length.should == 1
+    end
+
+    it "reports a bare year" do
+      messages.("REM Mon UNTIL 2027 MSG hi\n").length.should == 1
+    end
+
+    it "reports each clause that is short" do
+      messages.("REM Mon FROM 1 Jan UNTIL 2 Feb MSG hi\n").length.should == 2
+    end
+
+    it "reports THROUGH" do
+      messages.("REM Mon THROUGH 1 Jan MSG hi\n").first.should.match(/`THROUGH` needs a full date/)
+    end
+
+    it "points at the clause" do
+      text = "REM Mon UNTIL 1 Jan MSG hi\n"
+
+      lint.(text).first.column.should == text.index("UNTIL") + 1
+    end
+  end
+
+  describe "arguments it cannot judge" do
+    it "says nothing about a computed date" do
+      lint.("REM Mon UNTIL [expiry()] MSG hi\n").should.be.empty
+    end
+  end
+
+  it "says nothing about a reminder with none of these clauses" do
+    lint.("REM Mon MSG hi\n").should.be.empty
+  end
+
+  it "says nothing about SCANFROM, which also takes a delta" do
+    lint.("REM Mon SCANFROM -7 MSG hi\n").should.be.empty
+  end
+
+  it "says nothing about THROUGH inside an OMIT, which takes partial dates" do
+    # Both forms are in Remind's own tests/test.rem and both work.
+    lint.("OMIT Jun THROUGH July 15\n").should.be.empty
+    lint.("OMIT Apr 2022 through July\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM Mon UNTIL 1 Jan MSG hi\n").should.be.empty
+  end
+
+  it "reports at error severity" do
+    lint.("REM Mon UNTIL 1 Jan MSG hi\n").first.severity.should == "error"
+  end
+end

data/lib/remlint/rules/clause_requires_at.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Clauses that need a time, on a reminder that has none.
+    #
+    # `AT` is what gives a reminder a time of day. Two other clauses are only
+    # meaningful once it does:
+    #
+    #   DURATION   a duration with no start time has nothing to be a duration
+    #              of, and the back-ends have nowhere to place it
+    #   TZ         a bare date cannot be converted between zones -- there is no
+    #              instant to convert
+    #
+    # Both fail in the worst way: the reminder parses, runs, and quietly does
+    # something other than what the clause says. `TZ` without `AT` is the one
+    # that bites months later, when a reminder fires on a day the author never
+    # intended.
+    #
+    # `AT` is not the only way to get a time, though, and Remind's own
+    # `include/lunar-eclipses.rem` is 142 lines of the other way:
+    #
+    #   REM NOQUEUE [utctolocal('2097-04-26@10:37')] DURATION 196 MSG ...
+    #
+    # A pasted expression that evaluates to a DATETIME supplies the date *and*
+    # the time, so `DURATION` there is correct. Whether `utctolocal(...)`
+    # returns a DATETIME is not decidable without running it -- so a trigger
+    # containing any bracketed expression is left alone. Same principle as
+    # FunctionArity staying quiet about functions it has not seen defined:
+    # where the linter cannot know, it says nothing.
+    class ClauseRequiresAt < Rule
+      REASONS = {
+        "DURATION" => "a duration needs a start time",
+        "TZ"       => "a bare date has no instant to convert between zones",
+      }.freeze
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "DURATION or TZ on a reminder with no AT clause."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          check_command(command)
+        end
+      end
+
+      private
+
+        def check_command(command)
+          trigger = document.trigger_for(command)
+
+          unless trigger.include?("AT") || computed_time?(command, trigger)
+            report_orphans(command, trigger)
+          end
+        end
+
+        # Any bracketed expression before the body could be the DATETIME that
+        # supplies the time.
+        def computed_time?(command, trigger)
+          limit = trigger.body_offset || command.text.length
+
+          document.tokens_for(command.logical_line).any? do |token|
+            token.type == :lbracket && token.offset < limit
+          end
+        end
+
+        def report_orphans(command, trigger)
+          REASONS.each do |name, reason|
+            clause = trigger.find(name)
+
+            if clause
+              offend_at(
+                command.logical_line,
+                clause.offset,
+                "`#{name}` without an `AT` clause: #{reason}",
+              )
+            end
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::ClauseRequiresAt" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::ClauseRequiresAt.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "DURATION" do
+    it "is reported without AT" do
+      messages.("REM 1 Jan DURATION 1:00 MSG Meeting\n").first.should.match(/`DURATION` without an `AT`/)
+    end
+
+    it "is accepted with AT" do
+      lint.("REM 1 Jan AT 15:00 DURATION 1:00 MSG Meeting\n").should.be.empty
+    end
+
+    it "is accepted with AT written after it" do
+      lint.("REM 1 Jan DURATION 1:00 AT 15:00 MSG Meeting\n").should.be.empty
+    end
+  end
+
+  describe "TZ" do
+    it "is reported without AT" do
+      messages.("REM 1 Jan TZ America/Toronto MSG hi\n").first.should.match(/`TZ` without an `AT`/)
+    end
+
+    it "is accepted with AT" do
+      lint.("REM 1 Jan AT 15:00 TZ America/Toronto MSG hi\n").should.be.empty
+    end
+  end
+
+  it "reports both clauses on one reminder" do
+    messages.("REM 1 Jan DURATION 1:00 TZ UTC MSG hi\n").length.should == 2
+  end
+
+  it "points at the offending clause" do
+    text = "REM 1 Jan DURATION 1:00 MSG Meeting\n"
+
+    lint.(text).first.column.should == text.index("DURATION") + 1
+  end
+
+  describe "what it leaves alone" do
+    it "says nothing about a reminder with neither clause" do
+      lint.("REM 1 Jan MSG hi\n").should.be.empty
+    end
+
+    it "says nothing when the time could come from a pasted expression" do
+      # Straight out of include/lunar-eclipses.rem: the DATETIME the expression
+      # returns carries the time, so DURATION is correct here.
+      text = "REM NOQUEUE [utctolocal('2097-04-26@10:37')] DURATION 196 MSG Eclipse\n"
+
+      lint.(text).should.be.empty
+    end
+
+    it "still reports when the bracket is only in the body" do
+      # A body expression cannot supply the trigger's time.
+      lint.("REM 1 Jan DURATION 1:00 MSG at [place]\n").length.should == 1
+    end
+
+    it "does not read the words out of a message body" do
+      # `duration` and the zone name are English here, not clauses.
+      lint.("REM 1 Jan MSG Confirm the duration with the TZ America/Toronto team\n").should.be.empty
+    end
+
+    it "says nothing about comments" do
+      lint.("# REM 1 Jan TZ UTC MSG hi\n").should.be.empty
+    end
+  end
+
+  it "matches abbreviated clause keywords" do
+    # DURATION's minimum length is 8, TZ's is 2, AT's is 2.
+    lint.("REM 1 Jan AT 15:00 DURATION 1:00 MSG hi\n").should.be.empty
+    messages.("REM 1 Jan TZ UTC MSG hi\n").length.should == 1
+  end
+
+  it "reports at error severity" do
+    lint.("REM 1 Jan TZ UTC MSG hi\n").first.severity.should == "error"
+  end
+
+  it "reports the physical line inside a continuation" do
+    lint.("REM 1 Jan \\\n    TZ UTC MSG hi\n").first.line.should == 2
+  end
+end