remlint 0.1.0

data/lib/remlint/rules/repeat_trigger.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+require_relative "../date_literal"
+
+module RemLint
+  module Rules
+    # Repeats that do not repeat what the author meant.
+    #
+    # A repeat is `*n`: the reminder triggers on its start date and every *n*
+    # days after. Two things go wrong with it, and neither is an error.
+    #
+    # NO START DATE. A repeat counts days from somewhere, and without a fully
+    # specified start date there is nothing to count from.
+    #
+    # A WEEKDAY IN THE TRIGGER. The weekday picks the start date and nothing
+    # else -- the recurrence then ignores weekdays entirely. `REM Fri 15 Sep
+    # 2025 *10` starts on Friday 19 September and fires every ten days after,
+    # on days that are mostly not Fridays. Whatever the `Fri` was for, it was
+    # almost certainly not that.
+    class RepeatTrigger < Rule
+      WEEKDAY_TYPE = "T_WkDay"
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A *n repeat with no start date, or with a weekday that does not affect it."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          repeat = repeat_token(command)
+
+          if repeat
+            check_repeat(command, repeat)
+          end
+        end
+      end
+
+      private
+
+        # `*10` reaches the lexer as `*` then `10`. Only a command that carries
+        # a trigger can carry a repeat -- `SET a 3*14` is multiplication.
+        def repeat_token(command)
+          trigger = document.trigger_for(command)
+          limit = trigger.body_offset || command.text.length
+          tokens = document.tokens_for(command.logical_line)
+
+          if trigger.triggered?
+            tokens.each_index.filter_map { |index| star(tokens, index, limit) }.first
+          end
+        end
+
+        def star(tokens, index, limit)
+          token = tokens[index]
+          following = tokens[index + 1]
+
+          if token.type == :other && token.value == "*" &&
+             following&.type == :number && token.offset < limit
+            token
+          end
+        end
+
+        def check_repeat(command, repeat)
+          tokens = document.tokens_for(command.logical_line)
+
+          unless start_date(tokens)
+            offend_at(command.logical_line, repeat.offset, no_start_message)
+          end
+
+          weekday = weekday_clause(command)
+
+          if weekday
+            offend_at(command.logical_line, weekday.offset, weekday_message(weekday))
+          end
+        end
+
+        # A fully specified date anywhere in the trigger.
+        def start_date(tokens)
+          tokens.each_index.any? { |index| DateLiteral.at(tokens, index) }
+        end
+
+        def weekday_clause(command)
+          document.trigger_for(command).clauses.find do |clause|
+            clause.keyword.type == WEEKDAY_TYPE
+          end
+        end
+
+        def no_start_message
+          "a `*n` repeat counts days from a start date, and this trigger has no " \
+          "fully specified one to count from"
+        end
+
+        def weekday_message(clause)
+          "`#{clause.name}` only picks the start date; the `*n` repeat that follows " \
+          "counts days and ignores weekdays entirely"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::RepeatTrigger" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::RepeatTrigger.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "repeats that are fine" do
+    it "accepts a repeat with an ISO start date" do
+      lint.("REM 2012-11-07 *14 MSG Garbage\n").should.be.empty
+    end
+
+    it "accepts a repeat with a spelled-out start date" do
+      lint.("REM 31 October 2012 *14 MSG Paper recycling\n").should.be.empty
+    end
+
+    it "accepts a reminder with no repeat at all" do
+      lint.("REM Fri MSG hi\n").should.be.empty
+      lint.("REM 1 Jan MSG hi\n").should.be.empty
+    end
+  end
+
+  describe "a repeat with no start date" do
+    it "is reported" do
+      messages.("REM Mon *14 MSG hi\n").first.should.match(/no fully specified one to count from/)
+    end
+
+    it "is reported for a partial date" do
+      messages.("REM 1 Jan *14 MSG hi\n").first.should.match(/no fully specified one/)
+    end
+
+    it "points at the repeat" do
+      text = "REM Mon *14 MSG hi\n"
+
+      lint.(text).map(&:column).should.include(text.index("*14") + 1)
+    end
+  end
+
+  describe "a weekday with a repeat" do
+    it "is reported" do
+      # Straight from chapter 4: starts on 19 Sep, then every ten days.
+      messages.("REM Fri 15 Sep 2025 *10 MSG Test\n").first.should ==
+        "`FRIDAY` only picks the start date; the `*n` repeat that follows counts days " \
+        "and ignores weekdays entirely"
+    end
+
+    it "points at the weekday" do
+      text = "REM Fri 15 Sep 2025 *10 MSG Test\n"
+
+      lint.(text).first.column.should == text.index("Fri") + 1
+    end
+
+    it "is not reported without a repeat" do
+      lint.("REM Fri 15 Sep 2025 MSG Test\n").should.be.empty
+    end
+
+    it "reports both faults when a weekday repeat has no start date" do
+      lint.("REM Fri *10 MSG Test\n").length.should == 2
+    end
+  end
+
+  describe "what it leaves alone" do
+    it "does not read a star out of a message body" do
+      lint.("REM 2012-11-07 MSG rating *5 stars\n").should.be.empty
+    end
+
+    it "does not read a multiplication as a repeat" do
+      lint.("SET a 3*14\n").should.be.empty
+    end
+
+    it "says nothing about comments" do
+      lint.("# REM Mon *14 MSG hi\n").should.be.empty
+    end
+  end
+
+  it "reports at warning severity" do
+    lint.("REM Mon *14 MSG hi\n").first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/satisfy_constraint.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `SATISFY` expressions that belong in the trigger.
+    #
+    # `SATISFY` works by trial: Remind proposes a date, evaluates the
+    # expression, and moves on a day if it comes back false. Anything the
+    # trigger could have pinned down instead is therefore paid for once per
+    # candidate date rather than once.
+    #
+    # Chapter 7 measures it. Over 100,000 runs the all-SATISFY form evaluates
+    # the expression 13,214,377 times and takes 2.30s; moving the day into the
+    # trigger drops that to 482,026 evaluations and 0.58s. Same reminder, four
+    # times the speed, and the edit is mechanical:
+    #
+    #   REM SATISFY [$Td == 13 && $Tw == 5]     ->  REM 13 SATISFY [$Tw == 5]
+    #
+    # Three trigger components can be hoisted, and each is reported only when
+    # it is compared with `==` against a literal, which is the form that
+    # translates directly into the trigger:
+    #
+    #   $Td  the day of the month
+    #   $Tm  the month
+    #   $Ty  the year
+    #
+    # Two further faults share the same walk. A constraint no date can satisfy
+    # -- `$Td == 100` -- costs `$MaxSatIter` iterations and then prints
+    # `Can't compute trigger`. And a `$Ty <` term is an `UNTIL` written the
+    # expensive way, which the book calls bad practice for the same reason.
+    class SatisfyConstraint < Rule
+      # The trigger components a trigger can express directly, and the clause
+      # each becomes.
+      HOISTABLE = {
+        "Td" => "a day",
+        "Tm" => "a month",
+        "Ty" => "a year",
+      }.freeze
+
+      RANGES = {
+        "Td" => (1..31),
+        "Tm" => (1..12),
+        "Ty" => (1990..5990),
+      }.freeze
+
+      # `$Td == 13` and `$Ty < 2029`, as they arrive from the lexer.
+      COMPARISON = /\$(?<name>T[dmy])\s*(?<operator><=|>=|==|!=|<|>)\s*(?<value>\d+)/
+
+      def self.enabled_by_default?
+        false
+      end
+
+      def self.default_severity
+        "info"
+      end
+
+      def self.description
+        "A SATISFY constraint the trigger could express, or that no date satisfies."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          trigger = document.trigger_for(command)
+
+          if trigger.body&.name == "SATISFY"
+            check_satisfy(command, trigger)
+          end
+        end
+      end
+
+      private
+
+        def check_satisfy(command, trigger)
+          body = command.text[trigger.body_offset..].to_s
+          already = pinned(command, trigger)
+
+          body.to_enum(:scan, COMPARISON).each do
+            match = Regexp.last_match
+
+            report(
+              command,
+              trigger,
+              match,
+              already,
+            )
+          end
+        end
+
+        # A component the trigger already names is not one to hoist.
+        def pinned(command, trigger)
+          tokens = document.tokens_for(command.logical_line)
+          limit = trigger.body.offset
+
+          tokens.select { |token| token.offset < limit }.map(&:type)
+        end
+
+        def report(command, trigger, match, already)
+          name = match[:name]
+          value = match[:value].to_i
+          offset = trigger.body_offset + match.begin(0)
+
+          if !RANGES.fetch(name).cover?(value)
+            offend_at(command.logical_line, offset, unsatisfiable(name, match))
+          elsif match[:operator] == "==" && !already.include?(:number)
+            offend_at(command.logical_line, offset, hoistable(name, match))
+          elsif name == "Ty" && ["<", "<="].include?(match[:operator])
+            offend_at(command.logical_line, offset, bounded(match))
+          end
+        end
+
+        def unsatisfiable(name, match)
+          "`$#{name} #{match[:operator]} #{match[:value]}` can never hold -- " \
+          "#{name} runs #{RANGES.fetch(name).first} to #{RANGES.fetch(name).last} -- so " \
+          "this costs $MaxSatIter iterations and then prints `Can't compute trigger`"
+        end
+
+        def hoistable(name, match)
+          "`$#{name} == #{match[:value]}` is #{HOISTABLE.fetch(name)} the trigger could " \
+          "name directly; hoisting it stops the expression being evaluated once per " \
+          "candidate date"
+        end
+
+        def bounded(match)
+          "`$Ty #{match[:operator]} #{match[:value]}` is an `UNTIL` written as a " \
+          "constraint; `UNTIL #{match[:value].to_i - 1}-12-31` says the same thing " \
+          "without a search"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::SatisfyConstraint" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::SatisfyConstraint.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  it "is off unless the configuration asks for it" do
+    RemLint::Rules::SatisfyConstraint.enabled_by_default?.should.be.false
+  end
+
+  describe "constraints the trigger could express" do
+    it "reports a day" do
+      messages.("REM SATISFY [$Td == 13]\n").first.should.match(
+        /is a day the trigger could name directly/,
+      )
+    end
+
+    it "reports a month and a year" do
+      messages.("REM SATISFY [$Tm == 6]\n").first.should.match(/is a month the trigger could/)
+      messages.("REM SATISFY [$Ty == 2027]\n").first.should.match(/is a year the trigger could/)
+    end
+
+    it "explains the cost" do
+      messages.("REM SATISFY [$Td == 13]\n").first.should.match(
+        /once per candidate date/,
+      )
+    end
+
+    it "accepts a constraint the trigger already pins down" do
+      # `REM 13 SATISFY [$Tw == 5]` is the fixed form from chapter 7.
+      lint.("REM 13 SATISFY [$Tw == 5]\n").should.be.empty
+    end
+
+    it "says nothing about a weekday, which a trigger cannot pin this way" do
+      lint.("REM SATISFY [$Tw == 5]\n").should.be.empty
+    end
+  end
+
+  describe "constraints no date satisfies" do
+    it "reports a day out of range" do
+      messages.("REM SATISFY [$Td == 100]\n").first.should.match(
+        /can never hold -- Td runs 1 to 31/,
+      )
+    end
+
+    it "names the cost" do
+      messages.("REM SATISFY [$Td == 100]\n").first.should.match(
+        /costs \$MaxSatIter iterations and then prints `Can't compute trigger`/,
+      )
+    end
+
+    it "reports a month out of range" do
+      messages.("REM SATISFY [$Tm == 13]\n").first.should.match(/Tm runs 1 to 12/)
+    end
+
+    it "reports a year out of range" do
+      messages.("REM SATISFY [$Ty == 1970]\n").first.should.match(/Ty runs 1990 to 5990/)
+    end
+  end
+
+  describe "a year bound written as a constraint" do
+    it "is reported as an UNTIL" do
+      messages.("REM 13 SATISFY [$Ty < 2029]\n").first.should ==
+        "`$Ty < 2029` is an `UNTIL` written as a constraint; `UNTIL 2028-12-31` says " \
+        "the same thing without a search"
+    end
+
+    it "is reported for <= too" do
+      messages.("REM 13 SATISFY [$Ty <= 2029]\n").length.should == 1
+    end
+  end
+
+  it "says nothing about a REM with no SATISFY" do
+    lint.("REM 13 MSG hi\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM SATISFY [$Td == 13]\n").should.be.empty
+  end
+
+  it "points at the constraint" do
+    text = "REM SATISFY [$Td == 13]\n"
+
+    lint.(text).first.column.should == text.index("$Td") + 1
+  end
+
+  it "reports at info severity" do
+    lint.("REM SATISFY [$Td == 13]\n").first.severity.should == "info"
+  end
+end

data/lib/remlint/rules/shell_maxlen.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `shell()` given a maximum length that returns nothing.
+    #
+    # `shell(cmd)` reads up to 511 characters of the command's output;
+    # `shell(cmd, n)` reads up to *n*. A zero returns the empty string, and a
+    # command that produced no output returns the empty string too -- so
+    # `shell(cmd, 0)` is indistinguishable from a command that did not work,
+    # and debugging starts in the wrong place entirely.
+    #
+    # A negative *n* is the documented sentinel for "no limit", so only zero is
+    # reported.
+    class ShellMaxlen < Rule
+      SHELL = "shell"
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "shell() given a maximum length of zero, which always returns nothing."
+      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)
+          tokens = document.tokens_for(logical_line)
+
+          tokens.each_index do |index|
+            if call?(tokens, index)
+              check_call(logical_line, tokens, index)
+            end
+          end
+        end
+
+        def call?(tokens, index)
+          tokens[index].type == :function &&
+            tokens[index].value.casecmp?(SHELL) &&
+            tokens[index + 1]&.type == :lparen
+        end
+
+        # The second argument, when it is written out as a literal zero. The
+        # walk stops at the first top-level comma's operand, so a nested call
+        # in the first argument does not confuse it.
+        def check_call(logical_line, tokens, index)
+          zero = second_argument(tokens, index + 1)
+
+          if zero
+            offend_at(
+              logical_line,
+              zero.offset,
+              "`shell(..., 0)` returns the empty string whatever the command prints, " \
+              "which looks exactly like a command that produced nothing",
+            )
+          end
+        end
+
+        def second_argument(tokens, open_index)
+          comma = top_level_comma(tokens, open_index)
+          argument = comma && tokens[comma + 1]
+
+          if argument&.type == :number && argument.value.to_i.zero? &&
+             tokens[comma + 2]&.type == :rparen
+            argument
+          end
+        end
+
+        def top_level_comma(tokens, open_index)
+          depth = 0
+          cursor = open_index
+
+          while cursor < tokens.length
+            depth = depth_after(tokens[cursor], depth)
+
+            if depth.zero?
+              break
+            end
+
+            if depth == 1 && tokens[cursor].type == :comma
+              break
+            end
+
+            cursor += 1
+          end
+
+          if tokens[cursor]&.type == :comma
+            cursor
+          end
+        end
+
+        def depth_after(token, depth)
+          case token.type
+          when :lparen, :lbracket then depth + 1
+          when :rparen, :rbracket then depth - 1
+          else depth
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::ShellMaxlen" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::ShellMaxlen.new.run(RemLint::Document.new(source))
+  end
+
+  it "reports a zero maximum length" do
+    lint.(%(SET a shell("ls", 0)\n)).first.message.should.match(/returns the empty string/)
+  end
+
+  it "accepts the one-argument form" do
+    lint.(%(SET a shell("ls")\n)).should.be.empty
+  end
+
+  it "accepts a positive maximum length" do
+    lint.(%(SET a shell("ls", 1024)\n)).should.be.empty
+  end
+
+  it "accepts the negative sentinel" do
+    lint.(%(SET a shell("ls", -1)\n)).should.be.empty
+  end
+
+  it "is not confused by a comma inside the command" do
+    lint.(%(SET a shell("echo a,b")\n)).should.be.empty
+  end
+
+  it "is not confused by a nested call in the first argument" do
+    lint.(%(SET a shell(join("ls", "-l"), 1024)\n)).should.be.empty
+  end
+
+  it "matches the function name case-insensitively" do
+    lint.(%(SET a SHELL("ls", 0)\n)).length.should == 1
+  end
+
+  it "points at the zero" do
+    text = %(SET a shell("ls", 0)\n)
+
+    lint.(text).first.column.should == text.rindex("0") + 1
+  end
+
+  it "says nothing about another function with a zero argument" do
+    lint.("SET a max(1, 0)\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.(%(# SET a shell("ls", 0)\n)).should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.(%(SET a shell("ls", 0)\n)).first.severity.should == "warning"
+  end
+end