remlint 0.1.0

data/lib/remlint/rules/unbalanced_blocks.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Block commands that never close, close the wrong thing, or close nothing.
+    #
+    # Remind has its own "Warning: Missing ENDIF" (src/err.h E_MISS_ENDIF), but
+    # only for the file it actually reaches the end of, and only once it has
+    # run everything above. A linter can say it before anything runs, name the
+    # line the block opened on, and cover the three context stacks Remind's own
+    # warning does not:
+    #
+    #   IF / IFTRIG ... ELSE ... ENDIF
+    #   PUSH-OMIT-CONTEXT ... POP-OMIT-CONTEXT
+    #   PUSH-VARS ... POP-VARS
+    #   PUSH-FUNCS ... POP-FUNCS
+    #
+    # `defs.rem` nests IF inside ELSE inside IF for its Yom Hazikaron
+    # calculation and brackets its US Tax Day block in PUSH/POP-OMIT-CONTEXT,
+    # so all of this is load-bearing in the shipped examples.
+    #
+    # Matching is by canonical keyword, so the abbreviations Remind allows --
+    # `PUSH` for PUSH-OMIT-CONTEXT, `POP` for POP-OMIT-CONTEXT -- are matched
+    # like the long forms rather than missed.
+    class UnbalancedBlocks < Rule
+      PAIRS = {
+        "IF"                => "ENDIF",
+        "IFTRIG"            => "ENDIF",
+        "PUSH-OMIT-CONTEXT" => "POP-OMIT-CONTEXT",
+        "PUSH-VARS"         => "POP-VARS",
+        "PUSH-FUNCS"        => "POP-FUNCS",
+      }.freeze
+
+      CLOSERS = PAIRS.values.uniq.freeze
+
+      # `IF_NEST` in src/ifelse.c. The 65th level is an error rather than a
+      # deeper nesting, and the linter can say so before the file runs -- though
+      # a script at that depth has larger problems than this rule.
+      MAX_IF_DEPTH = 64
+
+      # Which openers a given closer is allowed to close.
+      OPENERS_FOR = CLOSERS.to_h do |closer|
+        [closer, PAIRS.select { |_opener, close| close == closer }.keys]
+      end.freeze
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "IF/ENDIF, ELSE and the PUSH/POP context commands that do not pair up."
+      end
+
+      def check
+        @stack = []
+
+        document.code_commands.each do |command|
+          dispatch(command)
+        end
+
+        report_unclosed
+      end
+
+      private
+
+        def dispatch(command)
+          if PAIRS.key?(keyword_of(command))
+            @stack.push({ command: command, else_line: nil })
+            check_depth(command)
+          elsif CLOSERS.include?(keyword_of(command))
+            close(command)
+          elsif command.keyword?("ELSE")
+            handle_else(command)
+          end
+        end
+
+        def keyword_of(command)
+          command.keyword&.name
+        end
+
+        def check_depth(command)
+          depth = @stack.count { |frame| conditional?(frame) }
+
+          if depth == MAX_IF_DEPTH + 1 && conditional?(@stack.last)
+            offend(
+              command.line,
+              "`IF` blocks nest #{MAX_IF_DEPTH} deep at most; this is level #{depth}",
+              column: command.keyword_column,
+            )
+          end
+        end
+
+        def close(command)
+          closer = keyword_of(command)
+          frame = @stack.last
+
+          if frame.nil? || !OPENERS_FOR.fetch(closer).include?(keyword_of(frame[:command]))
+            report_stray(command, closer, frame)
+          else
+            @stack.pop
+          end
+        end
+
+        # A closer that matches nothing on the stack is one of two different
+        # mistakes, and the message says which: nothing is open at all, or
+        # something else is open and this closer crosses it.
+        def report_stray(command, closer, frame)
+          if frame.nil?
+            offend(
+              command.line,
+              "`#{closer}` with nothing open to close",
+              column: command.keyword_column,
+            )
+          else
+            opener = frame[:command]
+
+            offend(
+              command.line,
+              "`#{closer}` closes `#{keyword_of(opener)}` opened on line #{opener.line}",
+              column: command.keyword_column,
+            )
+          end
+        end
+
+        def handle_else(command)
+          frame = @stack.reverse.find { |candidate| conditional?(candidate) }
+
+          if frame.nil?
+            offend(command.line, "`ELSE` outside any `IF` block", column: command.keyword_column)
+          elsif frame[:else_line]
+            offend(
+              command.line,
+              "`ELSE` already given for this `IF` on line #{frame[:else_line]}",
+              column: command.keyword_column,
+            )
+          else
+            frame[:else_line] = command.line
+          end
+        end
+
+        def conditional?(frame)
+          PAIRS[keyword_of(frame[:command])] == "ENDIF"
+        end
+
+        def report_unclosed
+          @stack.each do |frame|
+            opener = frame[:command]
+            keyword = keyword_of(opener)
+
+            offend(
+              opener.line,
+              "`#{keyword}` is never closed by `#{PAIRS.fetch(keyword)}`",
+              column: opener.keyword_column,
+            )
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::UnbalancedBlocks" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::UnbalancedBlocks.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "balanced code" do
+    it "accepts a simple conditional" do
+      lint.("IF a\n   MSG yes\nENDIF\n").should.be.empty
+    end
+
+    it "accepts an ELSE" do
+      lint.("IF a\n   MSG yes\nELSE\n   MSG no\nENDIF\n").should.be.empty
+    end
+
+    it "accepts nesting, as defs.rem does" do
+      lint.("IF a\nIF b\nMSG x\nELSE\nMSG y\nENDIF\nELSE\nMSG z\nENDIF\n").should.be.empty
+    end
+
+    it "accepts IFTRIG" do
+      lint.("IFTRIG 1 Jan\n   MSG hi\nENDIF\n").should.be.empty
+    end
+
+    it "accepts the omit-context stack" do
+      lint.("PUSH-OMIT-CONTEXT\nOMIT 1 Jan\nPOP-OMIT-CONTEXT\n").should.be.empty
+    end
+
+    it "accepts the abbreviations Remind allows for it" do
+      lint.("PUSH\nOMIT 1 Jan\nPOP\n").should.be.empty
+    end
+
+    it "accepts the vars and funcs stacks" do
+      lint.("PUSH-VARS\nSET a 1\nPOP-VARS\n").should.be.empty
+      lint.("PUSH-FUNCS\nFSET f(x) x\nPOP-FUNCS\n").should.be.empty
+    end
+
+    it "is not confused by a comment or a blank line inside a block" do
+      lint.("IF a\n\n# note\nMSG x\nENDIF\n").should.be.empty
+    end
+  end
+
+  describe "an unclosed opener" do
+    it "is reported on the line it opened" do
+      offenses = lint.("IF $TerminalBackground == 0\n   MSG dark\n")
+
+      offenses.length.should == 1
+      offenses.first.line.should == 1
+      offenses.first.message.should.match(/never closed by `ENDIF`/)
+    end
+
+    it "is reported for each of several" do
+      messages.("IF a\nIF b\nMSG x\n").length.should == 2
+    end
+
+    it "names the right closer for a context stack" do
+      messages.("PUSH-VARS\nSET a 1\n").first.should.match(/never closed by `POP-VARS`/)
+    end
+
+    it "points at the keyword's column" do
+      lint.("   IF a\n").first.column.should == 4
+    end
+  end
+
+  describe "a closer with nothing open" do
+    it "is reported" do
+      messages.("MSG hi\nENDIF\n").should == ["`ENDIF` with nothing open to close"]
+    end
+
+    it "is reported for a stray POP too" do
+      messages.("POP-OMIT-CONTEXT\n").first.should.match(/nothing open/)
+    end
+  end
+
+  describe "a closer that crosses another block" do
+    it "names the block it crossed and where that opened" do
+      messages.("IF a\nPOP-OMIT-CONTEXT\nENDIF\n").first.should ==
+        "`POP-OMIT-CONTEXT` closes `IF` opened on line 1"
+    end
+  end
+
+  describe "ELSE" do
+    it "outside any IF is reported" do
+      messages.("MSG hi\nELSE\nMSG bye\n").should == ["`ELSE` outside any `IF` block"]
+    end
+
+    it "inside an omit-context block but no IF is reported" do
+      messages.("PUSH-OMIT-CONTEXT\nELSE\nPOP-OMIT-CONTEXT\n").should ==
+        ["`ELSE` outside any `IF` block"]
+    end
+
+    it "given twice for one IF is reported the second time" do
+      offenses = lint.("IF a\nMSG x\nELSE\nMSG y\nELSE\nMSG z\nENDIF\n")
+
+      offenses.length.should == 1
+      offenses.first.line.should == 5
+      offenses.first.message.should.match(/already given/)
+    end
+
+    it "is allowed once in each of two nested IFs" do
+      lint.("IF a\nIF b\nMSG x\nELSE\nMSG y\nENDIF\nELSE\nMSG z\nENDIF\n").should.be.empty
+    end
+  end
+
+  describe "nesting depth" do
+    it "accepts 64 levels" do
+      text = ("IF a\n" * 64) + "MSG hi\n" + ("ENDIF\n" * 64)
+
+      lint.(text).should.be.empty
+    end
+
+    it "reports the 65th" do
+      text = ("IF a\n" * 65) + "MSG hi\n" + ("ENDIF\n" * 65)
+      offenses = lint.(text)
+
+      offenses.length.should == 1
+      offenses.first.line.should == 65
+      offenses.first.message.should.match(/nest 64 deep at most; this is level 65/)
+    end
+
+    it "does not count the context stacks toward the IF limit" do
+      text = ("PUSH-OMIT-CONTEXT\n" * 70) + ("POP-OMIT-CONTEXT\n" * 70)
+
+      lint.(text).should.be.empty
+    end
+  end
+
+  it "reports at error severity" do
+    lint.("IF a\n").first.severity.should == "error"
+  end
+
+  it "reports lines of a heredoc at their position in the enclosing file" do
+    source = RemLint::Source.new(path: "astro", text: "IF a\nMSG x\n", line_offset: 12)
+
+    RemLint::Rules::UnbalancedBlocks.new.run(RemLint::Document.new(source)).first.line.should == 13
+  end
+end

data/lib/remlint/rules/unbalanced_delimiters.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Brackets and parentheses that never close, or that close each other.
+    #
+    # Remind has `Missing ']'` and `Missing ')'` (src/err.h E_MISS_END,
+    # E_MISS_RIGHT_PAREN), so this reports something Remind agrees is wrong --
+    # it just reports it without running the file, and names the line the
+    # delimiter opened on rather than the line parsing gave up at.
+    #
+    # Two asymmetries matter, and both come from Remind treating unbracketed
+    # text as text:
+    #
+    # A CLOSER WITH NOTHING OPEN IS NOT AN ERROR. `MSG See note ]` prints a
+    # bracket. Reporting it would make the rule unusable on message bodies,
+    # which is most of what a reminder file is.
+    #
+    # PARENTHESES ONLY COUNT INSIDE AN EXPRESSION. `MSG Call (555) 1234` is
+    # text, not a call with a missing operand. So parentheses are tracked
+    # inside `[...]`, and in the arguments of the commands whose arguments are
+    # expressions -- `IF`, `SET`, `FSET` and friends -- and nowhere else.
+    #
+    # String literals are skipped, because the lexer already took them whole:
+    # the `]` in `MSG a "]" b` is inside a string and closes nothing.
+    class UnbalancedDelimiters < Rule
+      # Commands whose arguments Remind evaluates as an expression, so that
+      # parentheses in them are syntax rather than punctuation.
+      EXPRESSION_COMMANDS = %w[
+        IF IFTRIG SET FSET OMITFUNC EXPR MAX-OVERDUE
+      ].freeze
+
+      CLOSER_FOR = { lbracket: :rbracket, lparen: :rparen }.freeze
+      GLYPH = { lbracket: "[", rbracket: "]", lparen: "(", rparen: ")" }.freeze
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "Brackets and parentheses that are never closed, or that close each other."
+      end
+
+      def check
+        document.logical_lines.each_with_index do |logical_line, index|
+          command = document.commands[index]
+
+          if command.code?
+            check_line(logical_line, command)
+          end
+        end
+      end
+
+      private
+
+        def check_line(logical_line, command)
+          stack = []
+          expression = expression_command?(command)
+
+          document.tokens_for(logical_line).each do |token|
+            step(
+              stack,
+              token,
+              logical_line,
+              expression,
+            )
+          end
+
+          report_unclosed(stack, logical_line)
+        end
+
+        def step(stack, token, logical_line, expression)
+          if opener?(token, stack, expression)
+            stack.push(token)
+          elsif closer?(token, stack, expression)
+            match(stack, token, logical_line)
+          end
+        end
+
+        def opener?(token, stack, expression)
+          token.type == :lbracket ||
+            (token.type == :lparen && parens_count?(stack, expression))
+        end
+
+        def closer?(token, stack, expression)
+          token.type == :rbracket ||
+            (token.type == :rparen && parens_count?(stack, expression))
+        end
+
+        # Inside a bracketed expression, or in the arguments of a command whose
+        # arguments are one.
+        def parens_count?(stack, expression)
+          expression || stack.any? { |open| open.type == :lbracket }
+        end
+
+        def match(stack, token, logical_line)
+          top = stack.last
+
+          if top.nil?
+            nil # A closer with nothing open is literal text, not an error.
+          elsif CLOSER_FOR.fetch(top.type) == token.type
+            stack.pop
+          else
+            report_crossed(stack, token, logical_line)
+          end
+        end
+
+        def report_crossed(stack, token, logical_line)
+          top = stack.pop
+          line, _column = logical_line.position_at(top.offset)
+
+          offend_at(
+            logical_line,
+            token.offset,
+            "`#{GLYPH.fetch(token.type)}` closes `#{GLYPH.fetch(top.type)}` opened " \
+            "on line #{line}",
+          )
+        end
+
+        def report_unclosed(stack, logical_line)
+          stack.each do |token|
+            offend_at(
+              logical_line,
+              token.offset,
+              "`#{GLYPH.fetch(token.type)}` is never closed by " \
+              "`#{GLYPH.fetch(CLOSER_FOR.fetch(token.type))}`",
+            )
+          end
+        end
+
+        def expression_command?(command)
+          command.keyword?(*EXPRESSION_COMMANDS)
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::UnbalancedDelimiters" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::UnbalancedDelimiters.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "balanced code" do
+    it "accepts a bracketed substitution" do
+      lint.("MSG This is [center(\"hello\")]\n").should.be.empty
+    end
+
+    it "accepts the nested calls alignment.rem uses" do
+      lint.("MSG [ansicolor(255,255,0) + center(\"x \") + ansicolor(\"\")]\n").should.be.empty
+    end
+
+    it "accepts an expression command with parentheses and no brackets" do
+      lint.("IF version() < \"03.04.02\"\n").should.be.empty
+      lint.("FSET center(x) pad(\"\", \" \", (columns() - columns(x))/2) + x\n").should.be.empty
+    end
+
+    it "accepts a system-include path" do
+      lint.("INCLUDE [$SysInclude]/ansitext.rem\n").should.be.empty
+    end
+
+    it "accepts brackets spread over a continuation" do
+      lint.("SET x [IIF(a, \\\n   b, \\\n   c)]\n").should.be.empty
+    end
+  end
+
+  describe "text that only looks unbalanced" do
+    it "leaves a closer with nothing open alone" do
+      lint.("MSG See note ]\n").should.be.empty
+      lint.("MSG Call me )\n").should.be.empty
+    end
+
+    it "leaves parentheses in a message body alone" do
+      lint.("MSG Call (555 1234 tomorrow\n").should.be.empty
+    end
+
+    it "leaves parentheses in a RUN body alone" do
+      lint.("RUN echo $(date\n").should.be.empty
+    end
+
+    it "does not count a bracket inside a string literal" do
+      lint.(%(MSG a "]" b\n)).should.be.empty
+      lint.(%(MSG a "[" b\n)).should.be.empty
+    end
+  end
+
+  describe "an unclosed bracket" do
+    it "is reported" do
+      messages.("MSG value is [x\n").should == ["`[` is never closed by `]`"]
+    end
+
+    it "points at the bracket" do
+      lint.("MSG value is [x\n").first.column.should == 14
+    end
+
+    it "is reported once per unclosed bracket" do
+      messages.("MSG [a [b\n").length.should == 2
+    end
+
+    it "is reported on the physical line it opened on" do
+      lint.("SET x 1 + \\\n    [y\n").first.line.should == 2
+    end
+  end
+
+  describe "an unclosed parenthesis" do
+    it "is reported inside a bracketed expression" do
+      messages.("MSG [center(\"x\"\n").should ==
+        ["`[` is never closed by `]`", "`(` is never closed by `)`"]
+    end
+
+    it "is reported in an expression command" do
+      messages.("IF trigger(x\n").should == ["`(` is never closed by `)`"]
+    end
+  end
+
+  describe "delimiters that cross" do
+    it "reports a bracket closed by a parenthesis" do
+      messages.("SET x (a]\n").should == ["`]` closes `(` opened on line 1"]
+    end
+
+    it "reports a parenthesis closed by a bracket" do
+      # The `]` crosses the `(`, and the `[` it was meant to close is then
+      # left open -- both halves of the mistake get said.
+      messages.("MSG [foo(]\n").should ==
+        ["`]` closes `(` opened on line 1", "`[` is never closed by `]`"]
+    end
+  end
+
+  it "reports at error severity" do
+    lint.("MSG [x\n").first.severity.should == "error"
+  end
+
+  it "says nothing about comments" do
+    lint.("# a note with [ and (\n").should.be.empty
+  end
+
+  it "reports lines of a heredoc at their position in the enclosing file" do
+    source = RemLint::Source.new(path: "astro", text: "MSG [x\n", line_offset: 12)
+
+    RemLint::Rules::UnbalancedDelimiters.new.run(RemLint::Document.new(source)).first.line.should == 13
+  end
+end

data/lib/remlint/rules/unknown_special_type.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # `SPECIAL` types no shipped back-end understands.
+    #
+    # Remind passes a `SPECIAL` through untouched and the back-end is required
+    # to ignore anything it cannot parse. That contract is what makes `SPECIAL`
+    # extensible, and it is also why a typo is invisible: `SPECIAL SHDE 255 255
+    # 204` produces no error, no warning and no shading. The reminder triggers,
+    # the back-end shrugs, and the day is simply not coloured in.
+    #
+    # The shipped set is what the back-ends actually test `passthru` against --
+    # including `PostScript` and `PSFile`, which rem2ps reads and which are
+    # easy to forget because they look like reminder types rather than SPECIAL
+    # ones. A project with its own back-end adds to the set with
+    # `AllowedTypes`, which is the whole point of the passthrough.
+    class UnknownSpecialType < Rule
+      # Every value the shipped back-ends compare `passthru` against: the
+      # calendar ones from src/calendar.c and src/rem2ps.c, and the HTML and
+      # Pango ones from rem2html and Remind::PDF.
+      KNOWN = %w[
+        SHADE MOON WEEK COLOR COLOUR
+        POSTSCRIPT PSFILE PS
+        PANGO HTML HTMLCLASS
+      ].freeze
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A SPECIAL type no shipped back-end parses."
+      end
+
+      def check
+        allowed = KNOWN + option("AllowedTypes", []).map(&:upcase)
+
+        document.code_commands.each do |command|
+          check_special(command, allowed)
+        end
+      end
+
+      private
+
+        def check_special(command, allowed)
+          trigger = document.trigger_for(command)
+
+          if trigger.body&.name == "SPECIAL"
+            report(command, trigger, allowed)
+          end
+        end
+
+        def report(command, trigger, allowed)
+          tokens = document.tokens_for(command.logical_line)
+          token = tokens[trigger.body.argument_index]
+
+          if token&.type == :name && !allowed.include?(token.value.upcase)
+            offend_at(command.logical_line, token.offset, message(token, allowed))
+          end
+        end
+
+        def message(token, allowed)
+          "`SPECIAL #{token.value}` is a type no shipped back-end parses, so it " \
+          "produces no output and no error; the shipped set is #{allowed.join(', ')}"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::UnknownSpecialType" do
+  lint = proc do |text, config = {}|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::UnknownSpecialType.new(config).run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text, config = {}| lint.(text, config).map(&:message) }
+
+  describe "types the back-ends parse" do
+    it "accepts SHADE and MOON" do
+      lint.("REM Mon SPECIAL SHADE 255 255 204\n").should.be.empty
+      lint.("REM Mon SPECIAL MOON 0\n").should.be.empty
+    end
+
+    it "accepts COLOR and its other spelling" do
+      lint.("REM Mon SPECIAL COLOR 255 0 0 Sunset\n").should.be.empty
+      lint.("REM Mon SPECIAL COLOUR 255 0 0 Sunset\n").should.be.empty
+    end
+
+    it "accepts the PostScript passthroughs rem2ps reads" do
+      # tests/test2.rem writes this one, and rem2ps.c compares against it.
+      lint.("REM 21 AUG AT 1:55 SPECIAL PostScript (wookie) show\n").should.be.empty
+      lint.("REM Mon SPECIAL PSFile /tmp/x.ps\n").should.be.empty
+    end
+
+    it "accepts WEEK, PANGO and HTML" do
+      lint.("REM Mon SPECIAL WEEK 5\n").should.be.empty
+      lint.("REM Mon SPECIAL PANGO <b>bold</b>\n").should.be.empty
+      lint.("REM Mon SPECIAL HTML <b>bold</b>\n").should.be.empty
+    end
+
+    it "is case-insensitive" do
+      lint.("REM Mon SPECIAL shade 255 255 204\n").should.be.empty
+    end
+  end
+
+  describe "types nothing parses" do
+    it "reports a typo" do
+      messages.("REM Mon SPECIAL SHDE 255 255 204\n").first.should.match(
+        /`SPECIAL SHDE` is a type no shipped back-end parses/,
+      )
+    end
+
+    it "explains the silence" do
+      messages.("REM Mon SPECIAL SHDE 1\n").first.should.match(
+        /produces no output and no error/,
+      )
+    end
+
+    it "points at the type" do
+      text = "REM Mon SPECIAL SHDE 1\n"
+
+      lint.(text).first.column.should == text.index("SHDE") + 1
+    end
+  end
+
+  describe "AllowedTypes" do
+    it "accepts a type the configuration adds" do
+      lint.("REM Mon SPECIAL MYTHING 1\n", "AllowedTypes" => ["MYTHING"]).should.be.empty
+    end
+
+    it "matches an added type case-insensitively" do
+      lint.("REM Mon SPECIAL mything 1\n", "AllowedTypes" => ["MyThing"]).should.be.empty
+    end
+  end
+
+  it "says nothing about a reminder that is not a SPECIAL" do
+    lint.("REM Mon MSG SPECIAL SHDE\n").should.be.empty
+  end
+
+  it "says nothing about comments" do
+    lint.("# REM Mon SPECIAL SHDE 1\n").should.be.empty
+  end
+
+  it "reports at warning severity" do
+    lint.("REM Mon SPECIAL SHDE 1\n").first.severity.should == "warning"
+  end
+end