remlint 0.1.0

data/lib/remlint/rules/clause_value_range.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Numeric clause arguments outside the range Remind accepts.
+    #
+    # Four clauses take a bounded number and all four bounds are in the C:
+    #
+    #   AT hh:mm        0-23 and 0-59
+    #   DURATION hh:mm  minutes 0-59; the hour is unbounded
+    #   PRIORITY n      0-9999 (`ParsePriority`, src/dorem.c)
+    #   MAX-OVERDUE n   days past due, so a positive count
+    #
+    # Remind rejects each of them, but only when the line is reached. For a
+    # reminder that is the day it triggers, which for an annual one is up to a
+    # year after the typo was made.
+    #
+    # `DURATION` deliberately has no hour ceiling. A duration is a *length*,
+    # not a time of day: Remind's own `tests/test3.rem` writes
+    # `DURATION 24:45` and `DURATION 48:45` for events running over more than
+    # one day, and Remind accepts them. Only the minutes are bounded.
+    #
+    # `PRIORITY -1` is worth a word: `ParsePriority` starts with `isdigit`, so
+    # a minus sign is `Expecting number` rather than an out-of-range value, and
+    # the message says so rather than talking about the range.
+    class ClauseValueRange < Rule
+      MAX_HOUR = 23
+      MAX_MINUTE = 59
+      MAX_PRIORITY = 9999
+
+      # Only `AT` is a time of day, so only `AT` has an hour ceiling.
+      BOUNDED_HOUR = %w[AT].freeze
+
+      TIME_CLAUSES = %w[AT DURATION].freeze
+
+      # `15:00`, `15.00` -- Remind takes either separator.
+      TIME = /\A(?<hour>\d{1,2})[:.](?<minute>\d{1,2})\z/i
+
+      AM_PM = /\A(?<hour>\d{1,2})([:.](?<minute>\d{1,2}))?\s*(?<half>am|pm)\z/i
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "An AT, DURATION, PRIORITY or MAX-OVERDUE value outside its range."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          trigger = document.trigger_for(command)
+
+          TIME_CLAUSES.each { |name| check_time(command, trigger.find(name)) }
+          check_priority(command, trigger.find("PRIORITY"))
+          check_max_overdue(command, trigger.find("MAX-OVERDUE"))
+        end
+      end
+
+      private
+
+        # The literal word after a clause keyword, or nil when the argument is
+        # computed and so not this rule's to judge.
+        def argument(command, clause)
+          if clause
+            rest = command.text[clause.end_offset..].to_s
+
+            rest.strip[/\A\S+/]
+          end
+        end
+
+        def check_time(command, clause)
+          text = argument(command, clause)
+          match = text && (text.match(TIME) || text.match(AM_PM))
+
+          if match
+            report_time(command, clause, match)
+          end
+        end
+
+        def report_time(command, clause, match)
+          hour = match[:hour].to_i
+          minute = match[:minute].to_i
+          if am_pm?(match)
+            limit = 12
+          else
+            limit = MAX_HOUR
+          end
+
+          if BOUNDED_HOUR.include?(clause.name) && hour > limit
+            offend_at(command.logical_line, clause.offset, hour_message(clause, hour, limit))
+          elsif minute > MAX_MINUTE
+            offend_at(command.logical_line, clause.offset, minute_message(clause, minute))
+          end
+        end
+
+        def am_pm?(match)
+          match.names.include?("half") && !match[:half].nil?
+        end
+
+        def hour_message(clause, hour, limit)
+          "`#{clause.name} #{hour}:...` has an hour of #{hour}; Remind accepts 0 to #{limit}"
+        end
+
+        def minute_message(clause, minute)
+          "`#{clause.name}` has a minute of #{minute}; Remind accepts 0 to #{MAX_MINUTE}"
+        end
+
+        def check_priority(command, clause)
+          text = argument(command, clause)
+
+          if text&.match?(/\A-\d+\z/)
+            offend_at(
+              command.logical_line,
+              clause.offset,
+              "`PRIORITY #{text}` is rejected as `Expecting number`; " \
+              "ParsePriority reads digits only, so a minus never reaches the range check",
+            )
+          elsif text&.match?(/\A\d+\z/) && text.to_i > MAX_PRIORITY
+            offend_at(
+              command.logical_line,
+              clause.offset,
+              "`PRIORITY #{text}` is outside 0 to #{MAX_PRIORITY}",
+            )
+          end
+        end
+
+        def check_max_overdue(command, clause)
+          text = argument(command, clause)
+
+          if text&.match?(/\A-?\d+\z/) && text.to_i < 1
+            offend_at(
+              command.logical_line,
+              clause.offset,
+              "`MAX-OVERDUE #{text}` counts days past the due date, so it has to be " \
+              "positive; #{text} switches the nagging off rather than configuring it",
+            )
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::ClauseValueRange" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::ClauseValueRange.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "AT times" do
+    it "accepts a valid time" do
+      lint.("REM Tue AT 15:00 MSG hi\n").should.be.empty
+      lint.("REM Tue AT 0:00 MSG hi\n").should.be.empty
+      lint.("REM Tue AT 23:59 MSG hi\n").should.be.empty
+    end
+
+    it "accepts the dot separator" do
+      lint.("REM Tue AT 15.00 MSG hi\n").should.be.empty
+    end
+
+    it "reports an hour past 23" do
+      messages.("REM Tue AT 25:00 MSG hi\n").first.should.match(/an hour of 25; Remind accepts 0 to 23/)
+    end
+
+    it "reports a minute past 59" do
+      messages.("REM Tue AT 9:70 MSG hi\n").first.should.match(/a minute of 70/)
+    end
+
+    it "accepts an am/pm time" do
+      lint.("REM Tue AT 3:00PM MSG hi\n").should.be.empty
+      lint.("REM Tue AT 11:59am MSG hi\n").should.be.empty
+    end
+
+    it "reports an am/pm hour past 12" do
+      messages.("REM Tue AT 13:00PM MSG hi\n").first.should.match(/Remind accepts 0 to 12/)
+    end
+  end
+
+  describe "DURATION" do
+    it "accepts a valid duration" do
+      lint.("REM Tue AT 15:00 DURATION 1:30 MSG hi\n").should.be.empty
+    end
+
+    it "reports a minute past 59" do
+      messages.("REM Tue AT 15:00 DURATION 1:75 MSG hi\n").first.should.match(/`DURATION`/)
+    end
+
+    it "accepts an hour past 23, because a duration is a length" do
+      # tests/test3.rem writes DURATION 24:45 and DURATION 48:45; Remind
+      # accepts both -- the event simply runs over more than one day.
+      lint.("REM Tue AT 11:00 DURATION 24:45 MSG hi\n").should.be.empty
+      lint.("REM Tue AT 11:00 DURATION 48:45 MSG hi\n").should.be.empty
+    end
+  end
+
+  describe "PRIORITY" do
+    it "accepts the range" do
+      lint.("REM Tue PRIORITY 0 MSG hi\n").should.be.empty
+      lint.("REM Tue PRIORITY 9999 MSG hi\n").should.be.empty
+    end
+
+    it "reports a value past 9999" do
+      messages.("REM Tue PRIORITY 10000 MSG hi\n").first.should ==
+        "`PRIORITY 10000` is outside 0 to 9999"
+    end
+
+    it "explains that a negative is a parse error, not a range one" do
+      messages.("REM Tue PRIORITY -1 MSG hi\n").first.should.match(
+        /rejected as `Expecting number`/,
+      )
+    end
+  end
+
+  describe "MAX-OVERDUE" do
+    it "accepts a positive count" do
+      lint.("REM Tue MAX-OVERDUE 5 MSG hi\n").should.be.empty
+    end
+
+    it "reports zero" do
+      messages.("REM Tue MAX-OVERDUE 0 MSG hi\n").first.should.match(/has to be positive/)
+    end
+
+    it "reports a negative" do
+      messages.("REM Tue MAX-OVERDUE -3 MSG hi\n").length.should == 1
+    end
+  end
+
+  describe "arguments it cannot judge" do
+    it "says nothing about a computed time" do
+      lint.("REM Tue AT [sunset()] MSG hi\n").should.be.empty
+    end
+
+    it "says nothing about a computed priority" do
+      lint.("REM Tue PRIORITY [p] MSG hi\n").should.be.empty
+    end
+  end
+
+  it "does not read a time out of a message body" do
+    lint.("REM Tue MSG Meeting at 25:00 in the old money\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM Tue AT 25:00 MSG hi\n").should.be.empty
+  end
+
+  it "reports at error severity" do
+    lint.("REM Tue AT 25:00 MSG hi\n").first.severity.should == "error"
+  end
+end

data/lib/remlint/rules/color_component_range.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Colour components outside 0-255.
+    #
+    # Remind rejects them -- `if (r > 255 || g > 255 || b > 255) return E_2HIGH`
+    # in src/funcs.c for `ansicolor`, and the same bound in src/var.c for
+    # `$DefaultColor` -- but only when the line runs, and `rem2ps` silently
+    # clamps instead (src/rem2ps.c). A component typed as `2555` therefore
+    # renders as something plausible in one output mode and fails in another,
+    # which is the worst way for a mistake to behave.
+    #
+    # Three places carry components, and all three are hand-typed integers in
+    # practice, which is exactly when a linter can help:
+    #
+    #   SPECIAL COLOR r g b <text>     examples/astro has sixteen of these
+    #   SPECIAL SHADE r g b            tests/shade.rem has one per weekday
+    #   [ansicolor(r, g, b)]           examples/ansitext, examples/alignment
+    #
+    # `ansicolor` also takes a one-argument form (`ansicolor("")`, the reset)
+    # and an optional fourth background flag; only the three components are
+    # range-checked, and only when they are literal integers.
+    class ColorComponentRange < Rule
+      MINIMUM = 0
+      MAXIMUM = 255
+
+      # `COLOR`, and the spelling Remind also accepts.
+      SPECIAL_KINDS = %w[COLOR COLOUR SHADE].freeze
+
+      # `SPECIAL COLOR 255 128 0 rest...` -- three integers after the keyword.
+      SPECIAL = /\A(?<kind>[A-Za-z]+)\s+(?<r>-?\d+)\s+(?<g>-?\d+)\s+(?<b>-?\d+)\b/
+
+      CHANNELS = %w[red green blue].freeze
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "Colour components outside the 0-255 Remind accepts."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          check_special(command)
+          check_ansicolor(command)
+        end
+      end
+
+      private
+
+        def check_special(command)
+          match = special_components(command)
+
+          if match
+            report_components(command, match[:kind].upcase, [match[:r], match[:g], match[:b]])
+          end
+        end
+
+        # The components sit after `SPECIAL`, which may itself be preceded by a
+        # whole trigger (`REM [moondatetime(0)] +60 SPECIAL COLOR ...`), so the
+        # keyword is found in the text rather than assumed to open the line.
+        def special_components(command)
+          rest = command.text[/\bSPECIAL\s+(.*)\z/mi, 1]
+          match = rest&.match(SPECIAL)
+
+          if match && SPECIAL_KINDS.include?(match[:kind].upcase)
+            match
+          end
+        end
+
+        def check_ansicolor(command)
+          logical_line = command.logical_line
+          tokens = document.tokens_for(logical_line)
+
+          tokens.each_with_index do |token, index|
+            if token.type == :function && token.value.casecmp?("ansicolor")
+              report_components(command, "ansicolor", literal_arguments(tokens, index))
+            end
+          end
+        end
+
+        # The first three arguments, and only when each is an integer literal.
+        # `ansicolor("")` and `ansicolor(r, g, b)` with computed components
+        # both yield nothing to check.
+        #
+        # The arguments are split on top-level commas rather than picked out by
+        # position, because the lexer emits a minus sign as its own token:
+        # `ansicolor(-1, 0, 0)` reads as `-`, `1`, `,`, ... and taking the
+        # numbers alone would see a perfectly in-range 1.
+        def literal_arguments(tokens, index)
+          split_arguments(tokens, index + 1).first(3).filter_map { |group| integer(group) }
+        end
+
+        def split_arguments(tokens, open_index)
+          groups = [[]]
+          depth = 0
+          cursor = open_index
+
+          if tokens[cursor]&.type != :lparen
+            groups = []
+          else
+            depth, cursor = 1, cursor + 1
+
+            while cursor < tokens.length && depth.positive?
+              depth = collect(tokens[cursor], groups, depth)
+              cursor += 1
+            end
+          end
+
+          groups
+        end
+
+        # Returns the depth after this token, having filed the token under the
+        # argument it belongs to. The call's own closing paren is the one thing
+        # not filed anywhere -- it ends the walk instead.
+        def collect(token, groups, depth)
+          case token.type
+          when :lparen, :lbracket then descend(groups, token, depth)
+          when :rparen, :rbracket then ascend(groups, token, depth)
+          when :comma             then comma(groups, token, depth)
+          else
+            groups.last << token
+            depth
+          end
+        end
+
+        def descend(groups, token, depth)
+          groups.last << token
+
+          depth + 1
+        end
+
+        def ascend(groups, token, depth)
+          if depth > 1
+            groups.last << token
+          end
+
+          depth - 1
+        end
+
+        def comma(groups, token, depth)
+          if depth == 1
+            groups << []
+          else
+            groups.last << token
+          end
+
+          depth
+        end
+
+        # A group is a literal only if it is a bare number, optionally signed.
+        def integer(group)
+          text = group.map(&:value).join
+
+          if text.match?(/\A[+-]?\d+\z/)
+            text
+          end
+        end
+
+        def report_components(command, kind, components)
+          components.each_with_index do |component, index|
+            value = Integer(component, exception: false)
+
+            if !value.nil? && !(MINIMUM..MAXIMUM).cover?(value)
+              offend(
+                command.line,
+                "#{kind} #{CHANNELS.fetch(index)} component #{value} is outside " \
+                "#{MINIMUM}-#{MAXIMUM}",
+                column: command.keyword_column,
+              )
+            end
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::ColorComponentRange" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::ColorComponentRange.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "SPECIAL COLOR" do
+    it "accepts components in range" do
+      lint.("REM Mon SPECIAL COLOR 255 128 0 Sunset\n").should.be.empty
+    end
+
+    it "accepts the boundary values" do
+      lint.("SPECIAL COLOR 0 0 0 x\nSPECIAL COLOR 255 255 255 y\n").should.be.empty
+    end
+
+    it "reports a component above 255" do
+      messages.("SPECIAL COLOR 2555 128 0 x\n").should ==
+        ["COLOR red component 2555 is outside 0-255"]
+    end
+
+    it "reports a negative component" do
+      messages.("SPECIAL COLOR 255 -1 0 x\n").should ==
+        ["COLOR green component -1 is outside 0-255"]
+    end
+
+    it "names the blue channel" do
+      messages.("SPECIAL COLOR 0 0 999 x\n").should ==
+        ["COLOR blue component 999 is outside 0-255"]
+    end
+
+    it "reports every bad component on the line" do
+      messages.("SPECIAL COLOR 300 400 500 x\n").length.should == 3
+    end
+
+    it "accepts the COLOUR spelling" do
+      messages.("SPECIAL COLOUR 300 0 0 x\n").should ==
+        ["COLOUR red component 300 is outside 0-255"]
+    end
+
+    it "finds the components after a full trigger, as astro writes them" do
+      messages.("REM [moondatetime(0)] +60 SPECIAL COLOR 300 0 0 New moon\n").length.should == 1
+    end
+  end
+
+  describe "SPECIAL SHADE" do
+    it "accepts components in range" do
+      lint.("REM Mon SPECIAL SHADE 255 255 204\n").should.be.empty
+    end
+
+    it "reports one out of range" do
+      messages.("REM Mon SPECIAL SHADE 256 255 204\n").should ==
+        ["SHADE red component 256 is outside 0-255"]
+    end
+  end
+
+  describe "ansicolor" do
+    it "accepts components in range" do
+      lint.("MSG [ansicolor(0, 255, 0)]red[ansicolor(\"\")]\n").should.be.empty
+    end
+
+    it "reports one out of range" do
+      messages.("MSG [ansicolor(0, 300, 0)]x\n").should ==
+        ["ansicolor green component 300 is outside 0-255"]
+    end
+
+    it "accepts the four-argument background form" do
+      lint.("MSG [ansicolor(255, 255, 255)][ansicolor(0, 0, 0, 1)]x\n").should.be.empty
+    end
+
+    it "says nothing about the reset form" do
+      lint.(%(MSG [ansicolor("")]\n)).should.be.empty
+    end
+
+    it "reports a negative component" do
+      # The lexer emits the minus as its own token, so this only works because
+      # the arguments are reassembled rather than picked out by position.
+      messages.("MSG [ansicolor(-1, 0, 0)]\n").should ==
+        ["ansicolor red component -1 is outside 0-255"]
+    end
+
+    it "says nothing when the components are computed" do
+      lint.("MSG [ansicolor(r, g, b)]\n").should.be.empty
+    end
+
+    it "matches the function name case-insensitively" do
+      messages.("MSG [ANSICOLOR(300, 0, 0)]\n").length.should == 1
+    end
+  end
+
+  describe "what it stays quiet about" do
+    it "says nothing about a SPECIAL it does not know" do
+      lint.("SPECIAL HTMLCLASS 999 999 999\n").should.be.empty
+    end
+
+    it "says nothing about ordinary numbers on a line" do
+      lint.("MSG 300 400 500 items\n").should.be.empty
+    end
+
+    it "says nothing about comments" do
+      lint.("# SPECIAL COLOR 999 0 0 example\n").should.be.empty
+    end
+  end
+
+  it "reports at error severity" do
+    lint.("SPECIAL COLOR 300 0 0 x\n").first.severity.should == "error"
+  end
+end