remlint 0.1.0

data/lib/remlint/rules/addomit_without_scanfrom.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `ADDOMIT` with no `SCANFROM`, which adds the wrong year's holiday.
+    #
+    # `ADDOMIT` puts a movable holiday's computed date into the omit context.
+    # But Remind computes a reminder's trigger by scanning forward from today,
+    # so the day *after* the holiday the trigger has already moved to next
+    # year's occurrence -- and it is next year's date that gets added.
+    # Reminders that `SKIP`, `BEFORE` or `AFTER` around the holiday then work
+    # perfectly until the day after it, and are quietly wrong from then on.
+    #
+    # `SCANFROM` fixes it by making the scan start far enough back that the
+    # current year's date stays the trigger. Remind warns about a missing one
+    # itself, and names the same figure:
+    #
+    #   Warning: Consider using SCANFROM -28 with recurring ADDOMIT
+    #
+    # This rule says it before the file is ever run, and keeps to Remind's
+    # scope: a trigger built from a bracketed expression is opaque to both of
+    # us, so neither reports it. `include/holidays/cl.rem` has one
+    # (`REM [datepart(soleq(1, $U-28))] ADDOMIT ...`) and Remind is quiet
+    # about it, so this is too.
+    #
+    # The *width* of the window is a judgement rather than a fact, and so is
+    # off by default. Chapter 4 works through 28 days, and
+    # `include/holidays/us.rem` uses exactly that -- but `examples/defs.rem`
+    # uses `SCANFROM -7` twenty-seven times, and that is not a bug: it is a
+    # smaller guarantee, adequate for holidays whose dependent reminders are
+    # all within a week. Set `MinimumWindow` to 28 to ask for the wider one.
+    class AddomitWithoutScanfrom < Rule
+      # The figure chapter 4 works through, used only in the message and as
+      # the suggestion for a missing SCANFROM.
+      RECOMMENDED = 28
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "ADDOMIT with no SCANFROM, which adds next year's date the day after the holiday."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          trigger = document.trigger_for(command)
+
+          if trigger.include?("ADDOMIT") && !computed?(command, trigger)
+            check_scanfrom(command, trigger)
+          end
+        end
+      end
+
+      private
+
+        # A trigger whose date comes out of an expression. Remind's own
+        # warning does not fire on these and neither does this rule.
+        def computed?(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 check_scanfrom(command, trigger)
+          scanfrom = trigger.find("SCANFROM")
+
+          if scanfrom.nil?
+            offend_at(command.logical_line, trigger.find("ADDOMIT").offset, missing_message)
+          else
+            check_window(command, scanfrom)
+          end
+        end
+
+        # Zero -- the default -- means "any window will do", which is the
+        # honest position: a narrower one is a smaller guarantee, not a fault.
+        def check_window(command, scanfrom)
+          minimum = option("MinimumWindow", 0)
+          days = window(command, scanfrom)
+
+          if minimum.positive? && days && days < minimum
+            offend_at(command.logical_line, scanfrom.offset, narrow_message(days, minimum))
+          end
+        end
+
+        # `SCANFROM -28` -- the delta form, which is the one that matters here.
+        def window(command, scanfrom)
+          text = command.text[scanfrom.end_offset..].to_s.strip[/\A-\d+/]
+
+          text&.delete("-")&.to_i
+        end
+
+        def missing_message
+          "`ADDOMIT` with no `SCANFROM` adds *next* year's date once the day itself has " \
+          "passed, so anything skipping around this holiday is wrong from the day after " \
+          "it; `SCANFROM -#{RECOMMENDED}` keeps the addition stable"
+        end
+
+        def narrow_message(days, minimum)
+          "`SCANFROM -#{days}` is narrower than the #{minimum} days this project asks " \
+          "for, so a reminder more than #{days} days from the holiday can still see the " \
+          "wrong year's date"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::AddomitWithoutScanfrom" do
+  lint = proc do |text, config = {}|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::AddomitWithoutScanfrom.new(config).run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text, config = {}| lint.(text, config).map(&:message) }
+
+  wide = { "MinimumWindow" => 28 }
+
+  it "reports ADDOMIT with no SCANFROM" do
+    messages.("REM Mon 1 Apr ADDOMIT MSG Holiday\n").first.should.match(
+      /adds \*next\* year's date once the day itself has passed/,
+    )
+  end
+
+  it "suggests the window" do
+    messages.("REM Mon 1 Apr ADDOMIT MSG Holiday\n").first.should.match(/`SCANFROM -28`/)
+  end
+
+  it "accepts ADDOMIT with a wide enough SCANFROM" do
+    lint.("REM Thu Nov 22 SCANFROM -28 ADDOMIT MSG Thanksgiving\n").should.be.empty
+  end
+
+  it "accepts a wider window still" do
+    lint.("REM Thu Nov 22 SCANFROM -60 ADDOMIT MSG Thanksgiving\n").should.be.empty
+  end
+
+  it "accepts any window by default" do
+    # examples/defs.rem writes SCANFROM -7 twenty-seven times, and that is a
+    # smaller guarantee rather than a mistake.
+    lint.("REM Thu Nov 22 SCANFROM -7 ADDOMIT MSG Thanksgiving\n").should.be.empty
+  end
+
+  it "reports a narrow window when the project asks for a wider one" do
+    messages.("REM Thu Nov 22 SCANFROM -7 ADDOMIT MSG x\n", wide).first.should.match(
+      /`SCANFROM -7` is narrower than the 28 days this project asks for/,
+    )
+  end
+
+  it "accepts exactly the configured minimum" do
+    lint.("REM Thu Nov 22 SCANFROM -28 ADDOMIT MSG x\n", wide).should.be.empty
+  end
+
+  it "says nothing about a reminder with no ADDOMIT" do
+    lint.("REM Thu Nov 22 SCANFROM -7 MSG Thanksgiving\n").should.be.empty
+  end
+
+  it "says nothing when SCANFROM takes a date rather than a delta" do
+    # A fixed scan date is a different thing and not this rule's to judge.
+    lint.("REM Thu Nov 22 SCANFROM 2026-01-01 ADDOMIT MSG x\n", wide).should.be.empty
+  end
+
+  it "points at the ADDOMIT when there is no SCANFROM" do
+    text = "REM Mon 1 Apr ADDOMIT MSG Holiday\n"
+
+    lint.(text).first.column.should == text.index("ADDOMIT") + 1
+  end
+
+  it "says nothing about a trigger built from an expression" do
+    # include/holidays/cl.rem has one of these and Remind does not warn about
+    # it either -- the trigger is opaque to both of us.
+    lint.("REM [datepart(soleq(1, $U-28))] ADDOMIT MSG Solstice\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM Mon 1 Apr ADDOMIT MSG Holiday\n").should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.("REM Mon 1 Apr ADDOMIT MSG x\n").first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/advance_warning_body.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Reminders that arrive early without saying so.
+    #
+    # A delta makes a reminder start appearing before the day it is about, and
+    # a time makes it arrive before the hour. Neither changes the body. So
+    #
+    #   REM 16 July ++10 MSG Jane's birthday.
+    #
+    # prints `Jane's birthday.` on the 8th of July, with nothing to say the
+    # birthday is eight days off, and reads exactly like a birthday today.
+    # `%b` is the idiomatic fix -- "in 8 days' time" -- and `%2` or `%3` is its
+    # equivalent for a time.
+    #
+    # Off by default, and it will fire on plenty of correct files: an advance
+    # warning whose body already reads naturally in both places is fine, and
+    # only the author can say. Turning it on is worth it for a file being
+    # written rather than one being inherited.
+    #
+    # The paired rule is `CalendarTextLimited`, which asks you to fence the
+    # relative phrase in `%"…%"` so it does not follow the reminder into a
+    # calendar box.
+    class AdvanceWarningBody < Rule
+      # `%a` to `%l` and friends all say something about *when*; these are the
+      # ones that say how far away it is.
+      RELATIVE = /%\*?[abcefghijkluv]/i
+
+      TIME_SUBSTITUTION = /%\*?[0-9@#]/
+
+      DELTA = /(?<!\S)[+-]{1,2}\d+(?!\S)/
+
+      def self.enabled_by_default?
+        false
+      end
+
+      def self.default_severity
+        "info"
+      end
+
+      def self.description
+        "A reminder with a delta or a time whose body never says when the event is."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          trigger = document.trigger_for(command)
+
+          if trigger.text_body?
+            check_body(command, trigger)
+          end
+        end
+      end
+
+      private
+
+        def check_body(command, trigger)
+          body = command.text[trigger.body_offset..].to_s
+
+          check_delta(command, trigger, body)
+          check_time(command, trigger, body)
+        end
+
+        def check_delta(command, trigger, body)
+          if delta?(command, trigger) && !body.match?(RELATIVE)
+            offend_at(
+              command.logical_line,
+              trigger.body.offset,
+              "this reminder has a delta, so it appears days before the event, but the " \
+              "body never says how far off it is; `%b` reads as \"in 8 days' time\"",
+            )
+          end
+        end
+
+        def check_time(command, trigger, body)
+          if trigger.include?("AT") && !body.match?(TIME_SUBSTITUTION) && !body.match?(RELATIVE)
+            offend_at(
+              command.logical_line,
+              trigger.body.offset,
+              "this reminder has an `AT`, so the queued copy arrives before the event, " \
+              "but the body never mentions the time; `%2` or `%3` says when",
+            )
+          end
+        end
+
+        # A delta is written in the trigger, before the body.
+        def delta?(command, trigger)
+          head = command.text[0...trigger.body.offset].to_s
+
+          head.match?(DELTA)
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::AdvanceWarningBody" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::AdvanceWarningBody.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::AdvanceWarningBody.enabled_by_default?.should.be.false
+  end
+
+  describe "deltas" do
+    it "reports a body that never says how far off the event is" do
+      messages.("REM 16 July ++10 MSG Jane's birthday.\n").first.should.match(
+        /the body never says how far off it is/,
+      )
+    end
+
+    it "accepts a body that uses %b" do
+      lint.("REM 16 July ++10 MSG Jane's birthday %b.\n").should.be.empty
+    end
+
+    it "accepts a body that uses another relative substitution" do
+      lint.("REM 16 July ++10 MSG Jane's birthday %c.\n").should.be.empty
+    end
+
+    it "accepts a single-sign delta with a relative substitution" do
+      lint.("REM 16 July +10 MSG Jane's birthday %b.\n").should.be.empty
+    end
+
+    it "says nothing about a reminder with no delta" do
+      lint.("REM 16 July MSG Jane's birthday.\n").should.be.empty
+    end
+
+    it "does not read a delta out of the body" do
+      lint.("REM 16 July MSG the score was +10 points\n").should.be.empty
+    end
+  end
+
+  describe "times" do
+    it "reports an AT reminder whose body never mentions the time" do
+      messages.("REM Tue AT 15:00 MSG Staff meeting\n").first.should.match(
+        /the body never mentions the time/,
+      )
+    end
+
+    it "accepts a body that uses %2" do
+      lint.("REM Tue AT 15:00 MSG Staff meeting at %2\n").should.be.empty
+    end
+
+    it "accepts a body that uses %3 or %@" do
+      lint.("REM Tue AT 15:00 MSG Meeting %3\n").should.be.empty
+      lint.("REM Tue AT 15:00 MSG Meeting %@\n").should.be.empty
+    end
+
+    it "says nothing about a reminder with no AT" do
+      lint.("REM Tue MSG Staff meeting\n").should.be.empty
+    end
+  end
+
+  it "says nothing about a SATISFY body, which is an expression" do
+    lint.("REM 16 July ++10 SATISFY [1]\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM 16 July ++10 MSG Jane's birthday.\n").should.be.empty
+  end
+
+  it "reports at info severity" do
+    lint.("REM 16 July ++10 MSG hi\n").first.severity.should == "info"
+  end
+end

data/lib/remlint/rules/banner_placement.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `BANNER` written more than once, or below the reminders it appears above.
+    #
+    # `BANNER` sets the line Remind prints before the day's reminders, and
+    # there is one of them. A second `BANNER` silently replaces the first, and
+    # one written below a `REM` reads as though it applied to the reminders
+    # above it when it applies to all of them equally.
+    #
+    # Neither is an error. The first is a line of configuration that does
+    # nothing; the second is a line that does something other than where it
+    # sits suggests.
+    class BannerPlacement < Rule
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A second BANNER, or a BANNER written below the first reminder."
+      end
+
+      def check
+        banners = document.code_commands.select { |command| command.keyword?("BANNER") }
+
+        report_duplicates(banners)
+        report_late(banners.first)
+      end
+
+      private
+
+        def report_duplicates(banners)
+          banners.drop(1).each do |banner|
+            offend(
+              banner.line,
+              "a second `BANNER` silently replaces the one on line #{banners.first.line}",
+              column: banner.keyword_column,
+            )
+          end
+        end
+
+        def report_late(banner)
+          first = first_reminder
+
+          if banner && first && banner.line > first.line
+            offend(
+              banner.line,
+              "`BANNER` applies to the whole run, so writing it below the reminder on " \
+              "line #{first.line} reads as though it applied only to what follows",
+              column: banner.keyword_column,
+            )
+          end
+        end
+
+        def first_reminder
+          document.code_commands.find do |command|
+            command.implicit? || command.keyword?("REM")
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::BannerPlacement" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::BannerPlacement.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  it "accepts one BANNER above the reminders" do
+    lint.("BANNER %\nREM 1 Jan MSG hi\n").should.be.empty
+  end
+
+  it "accepts a file with no BANNER" do
+    lint.("REM 1 Jan MSG hi\n").should.be.empty
+  end
+
+  it "reports a second BANNER" do
+    messages.("BANNER one\nBANNER two\n").first.should ==
+      "a second `BANNER` silently replaces the one on line 1"
+  end
+
+  it "reports each BANNER after the first" do
+    lint.("BANNER a\nBANNER b\nBANNER c\n").length.should == 2
+  end
+
+  it "reports a BANNER written below a reminder" do
+    messages.("REM 1 Jan MSG hi\nBANNER %\n").first.should.match(
+      /reads as though it applied only to what follows/,
+    )
+  end
+
+  it "reports a BANNER below an implicit trigger" do
+    messages.("1 Jan MSG hi\nBANNER %\n").length.should == 1
+  end
+
+  it "does not count a SET or an INCLUDE as a reminder" do
+    lint.("SET a 1\nINCLUDE defs.rem\nBANNER %\n").should.be.empty
+  end
+
+  it "points at the keyword" do
+    lint.("BANNER a\n   BANNER b\n").first.column.should == 4
+  end
+
+  it "says nothing about the word banner in a body" do
+    lint.("REM 1 Jan MSG hang the banner\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# BANNER a\n# BANNER b\n").should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.("BANNER a\nBANNER b\n").first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/calendar_text_limited.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # A relative phrase that follows the reminder into a calendar box.
+    #
+    # `%"…%"` marks the part of a body that belongs in a calendar. Outside the
+    # marks, text appears in Agenda Mode only. The distinction matters most for
+    # exactly the substitutions `AdvanceWarningBody` asks you to add:
+    #
+    #   REM 16 July ++10 MSG %"Jane's birthday%" %b.
+    #
+    # In Agenda Mode that reads "Jane's birthday in 8 days' time". In a
+    # calendar it is printed in the box for 16 July, where "in 8 days' time" is
+    # not merely redundant but wrong -- the box already says which day it is.
+    #
+    # So this is the second half of a pair: one rule asks for `%b`, this one
+    # asks you to fence it. Off by default, like its sibling, and for the same
+    # reason: a file that is never rendered as a calendar does not need it.
+    class CalendarTextLimited < Rule
+      RELATIVE = /%\*?[abcefghijkluv]/i
+
+      MARKER = '%"'
+
+      def self.enabled_by_default?
+        false
+      end
+
+      def self.default_severity
+        "info"
+      end
+
+      def self.description
+        "A relative-date substitution in a body with no %\" ... %\" calendar limit."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          trigger = document.trigger_for(command)
+
+          if trigger.text_body?
+            check_body(command, trigger)
+          end
+        end
+      end
+
+      private
+
+        def check_body(command, trigger)
+          body = command.text[trigger.body_offset..].to_s
+          match = body.match(RELATIVE)
+
+          if match && !body.include?(MARKER)
+            offend_at(
+              command.logical_line,
+              trigger.body_offset + match.begin(0),
+              "`#{match[0]}` says how far off the event is, which is right in Agenda " \
+              "Mode and wrong in a calendar box; fence the name in `%\"…%\"` so only " \
+              "that reaches the calendar",
+            )
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::CalendarTextLimited" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::CalendarTextLimited.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::CalendarTextLimited.enabled_by_default?.should.be.false
+  end
+
+  it "reports a relative substitution with no calendar limit" do
+    messages.("REM 16 July ++10 MSG Jane's birthday %b.\n").first.should.match(
+      /wrong in a calendar box/,
+    )
+  end
+
+  it "names the substitution it found" do
+    messages.("REM 16 July ++10 MSG Jane's birthday %b.\n").first.should.match(/`%b` says/)
+  end
+
+  it "accepts a body that fences the name" do
+    lint.(%(REM 16 July ++10 MSG %"Jane's birthday%" %b.\n)).should.be.empty
+  end
+
+  it "accepts a body with no relative substitution at all" do
+    lint.("REM 16 July MSG Jane's birthday.\n").should.be.empty
+  end
+
+  it "reports only once per body" do
+    lint.("REM 16 July ++10 MSG %b and %c\n").length.should == 1
+  end
+
+  it "points at the substitution" do
+    text = "REM 16 July ++10 MSG Jane %b.\n"
+
+    lint.(text).first.column.should == text.index("%b") + 1
+  end
+
+  it "says nothing about a SATISFY body" do
+    lint.("REM 16 July SATISFY [1]\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM 16 July ++10 MSG Jane %b.\n").should.be.empty
+  end
+
+  it "reports at info severity" do
+    lint.("REM 16 July ++10 MSG Jane %b.\n").first.severity.should == "info"
+  end
+end