remlint 0.1.0

data/lib/remlint/rules/shell_use_while_run_disabled.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # A function that shells out, defined while `RUN` is off.
+    #
+    # Remind binds the `RUN` permission when a function is *defined*, not when
+    # it is called. `userfns.c` stores the flag on the function
+    # (`if (RunDisabled) func->run_disabled = 1`) and `expr.c` puts it back on
+    # every call (`if (f->run_disabled) RunDisabled |= RUN_UF`). So:
+    #
+    #   RUN OFF
+    #   FSET listing() shell("ls")
+    #   RUN ON
+    #   MSG [listing()]           # RUN disabled
+    #
+    # The function is defined in the sandbox and stays in it for good. Nothing
+    # about the definition looks wrong, the `RUN ON` above the call looks like
+    # it should be enough, and the error arrives from the call site -- which is
+    # the one place the mistake is not.
+    #
+    # `shell()` is the only builtin that needs the permission (`funcs.c:2545`);
+    # `INCLUDECMD` needs it too but is a command, not something a function can
+    # contain.
+    class ShellUseWhileRunDisabled < Rule
+      SHELL = "shell"
+
+      ON = "ON"
+      OFF = "OFF"
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "A function calling shell(), defined between RUN OFF and RUN ON."
+      end
+
+      def check
+        disabled = false
+
+        document.code_commands.each do |command|
+          directive = run_directive(command)
+
+          if directive
+            disabled = directive == OFF
+          elsif disabled
+            check_definition(command)
+          end
+        end
+      end
+
+      private
+
+        # `RUN ON` / `RUN OFF` is a directive; any other `RUN` is a reminder
+        # that shells out. `DoRun` accepts exactly these two words, in any case.
+        def run_directive(command)
+          word = command.args.strip.upcase
+
+          if command.keyword?("RUN") && (word == ON || word == OFF)
+            word
+          end
+        end
+
+        def check_definition(command)
+          if command.keyword?("FSET")
+            shell_calls(command).each do |token|
+              offend_at(command.logical_line, token.offset, message)
+            end
+          end
+        end
+
+        def shell_calls(command)
+          document.tokens_for(command.logical_line).select do |token|
+            token.type == :function && token.value.casecmp?(SHELL)
+          end
+        end
+
+        def message
+          "`shell()` in a function defined while `RUN` is off: the permission " \
+          "is bound here, not at the call, so this fails even after `RUN ON`"
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::ShellUseWhileRunDisabled" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::ShellUseWhileRunDisabled.new.run(RemLint::Document.new(source))
+  end
+
+  it "reports a shell() function defined after RUN OFF" do
+    offenses = lint.(%(RUN OFF\nFSET listing() shell("ls")\nRUN ON\n))
+
+    offenses.length.should == 1
+    offenses.first.line.should == 2
+    offenses.first.message.should.match(/bound here, not at the call/)
+  end
+
+  it "accepts the same definition before RUN OFF" do
+    lint.(%(FSET listing() shell("ls")\nRUN OFF\n)).should.be.empty
+  end
+
+  it "accepts the same definition after RUN is turned back on" do
+    lint.(%(RUN OFF\nRUN ON\nFSET listing() shell("ls")\n)).should.be.empty
+  end
+
+  it "accepts a file that never turns RUN off" do
+    lint.(%(FSET listing() shell("ls")\n)).should.be.empty
+  end
+
+  it "reports every offending definition in the disabled span" do
+    text = %(RUN OFF\nFSET a() shell("ls")\nFSET b() shell("date")\nRUN ON\n)
+
+    lint.(text).map(&:line).should == [2, 3]
+  end
+
+  it "reports two calls in one definition" do
+    lint.(%(RUN OFF\nFSET a() shell("ls") + shell("date")\n)).length.should == 2
+  end
+
+  it "matches RUN OFF whatever its case" do
+    lint.(%(run off\nFSET a() shell("ls")\n)).length.should == 1
+  end
+
+  it "matches shell whatever its case" do
+    lint.(%(RUN OFF\nFSET a() SHELL("ls")\n)).length.should == 1
+  end
+
+  it "points at the call" do
+    text = %(RUN OFF\nFSET listing() shell("ls")\n)
+
+    lint.(text).first.column.should == %(FSET listing() shell("ls")).index("shell") + 1
+  end
+
+  describe "what it leaves alone" do
+    it "says nothing about a function that does not shell out" do
+      lint.("RUN OFF\nFSET double(x) x * 2\n").should.be.empty
+    end
+
+    it "says nothing about a RUN reminder, which is not a directive" do
+      # `RUN OFF` is the directive; `RUN echo off` is a reminder that runs a
+      # command, and it does not disable anything.
+      lint.(%(REM 1 Jan RUN echo off\nFSET a() shell("ls")\n)).should.be.empty
+    end
+
+    it "does not read a bare RUN reminder as a directive" do
+      lint.(%(RUN echo hello\nFSET a() shell("ls")\n)).should.be.empty
+    end
+
+    it "says nothing about a shell() call outside a definition" do
+      # That one fails visibly, at the point it is written.
+      lint.(%(RUN OFF\nSET x shell("ls")\n)).should.be.empty
+    end
+
+    it "says nothing about comments" do
+      lint.(%(RUN OFF\n# FSET a() shell("ls")\n)).should.be.empty
+    end
+  end
+
+  it "reports at error severity" do
+    lint.(%(RUN OFF\nFSET a() shell("ls")\n)).first.severity.should == "error"
+  end
+end

data/lib/remlint/rules/string_escape.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Backslash escapes in a string that are not escapes.
+    #
+    # Remind's escape set is `\a \b \f \n \r \t \v` and `\xHH`. Anything else
+    # reaches a `default:` branch in src/expr.c that emits the character and
+    # drops the backslash -- so `\q` is `q`, silently, with no way to tell it
+    # from a `q` somebody meant to type.
+    #
+    # `\\` and `\"` go through that same default branch, which is exactly how
+    # they work, so neither is reported: writing them is the fix, not the
+    # fault.
+    #
+    # `\x00` is different, and is the one case Remind refuses outright: a NUL
+    # cannot appear inside a Remind string, and the parser says so.
+    class StringEscape < Rule
+      # From the `switch(**in)` over escapes in src/expr.c.
+      DEFINED = %w[a b f n r t v x].freeze
+
+      # Handled by the default branch, and correct.
+      LITERAL = ['\\', '"', "'"].freeze
+
+      ESCAPE = /\\(?<body>x[0-9a-fA-F]{1,2}|.)/
+
+      NUL = /\Ax0+\z/
+
+      def self.default_severity
+        "warning"
+      end
+
+      def self.description
+        "A backslash escape Remind does not define, or the prohibited \\x00."
+      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)
+          document.tokens_for(logical_line).each do |token|
+            if token.type == :string && token.value.start_with?('"')
+              check_string(logical_line, token)
+            end
+          end
+        end
+
+        def check_string(logical_line, token)
+          token.value.to_enum(:scan, ESCAPE).each do
+            match = Regexp.last_match
+            complaint = fault(match[:body])
+
+            if complaint
+              offend_at(logical_line, token.offset + match.begin(0), complaint)
+            end
+          end
+        end
+
+        def fault(body)
+          if body.match?(NUL)
+            "`\\#{body}` is prohibited outright -- a NUL cannot appear inside a Remind string"
+          elsif !DEFINED.include?(body[0]) && !LITERAL.include?(body[0])
+            "`\\#{body}` is not an escape Remind defines; it drops the backslash " \
+            "and prints `#{body}`"
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::StringEscape" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::StringEscape.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "escapes Remind defines" do
+    it "accepts the control escapes" do
+      lint.(%(SET a "one\\ttwo\\nthree"\n)).should.be.empty
+      lint.(%(SET a "\\a\\b\\f\\r\\v"\n)).should.be.empty
+    end
+
+    it "accepts a hex escape" do
+      lint.(%(SET a "\\x41\\x7f"\n)).should.be.empty
+    end
+
+    it "accepts an escaped backslash and quote" do
+      # Both go through the same default branch, which is how they work.
+      lint.(%(SET a "a \\\\ b \\" c"\n)).should.be.empty
+    end
+  end
+
+  describe "escapes Remind does not define" do
+    it "reports an unknown letter" do
+      messages.(%(SET a "\\q"\n)).first.should ==
+        "`\\q` is not an escape Remind defines; it drops the backslash and prints `q`"
+    end
+
+    it "reports each one" do
+      messages.(%(SET a "\\q and \\z"\n)).length.should == 2
+    end
+
+    it "points at the backslash" do
+      text = %(SET a "x\\qy"\n)
+
+      lint.(text).first.column.should == text.index("\\q") + 1
+    end
+  end
+
+  describe "the prohibited NUL" do
+    it "reports \\x00" do
+      messages.(%(SET a "\\x00"\n)).first.should.match(/prohibited outright/)
+    end
+
+    it "reports \\x0 as well" do
+      messages.(%(SET a "\\x0"\n)).first.should.match(/prohibited outright/)
+    end
+
+    it "accepts a hex escape that is not zero" do
+      lint.(%(SET a "\\x01"\n)).should.be.empty
+    end
+  end
+
+  describe "where it does not look" do
+    it "says nothing about a single-quoted date constant" do
+      lint.("SET a '2027-01-01'\n").should.be.empty
+    end
+
+    it "says nothing about a backslash outside a string" do
+      # A trailing backslash is a line continuation, not an escape.
+      lint.("SET a 1 + \\\n    2\n").should.be.empty
+    end
+
+    it "says nothing about comments" do
+      lint.(%(# SET a "\\q"\n)).should.be.empty
+    end
+  end
+
+  it "reports at warning severity" do
+    lint.(%(SET a "\\q"\n)).first.severity.should == "warning"
+  end
+end

data/lib/remlint/rules/syntax.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tempfile"
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # Remind's own diagnostics, folded into the linter's output.
+    #
+    # puppet-lint draws the line here and it is the right line: a linter
+    # validates style, and for "is this even valid" you run the real parser.
+    # Remind has no parse-only mode, so the real parser is Remind, and running
+    # it means running the file.
+    #
+    # THIS RULE IS OFF BY DEFAULT, and stays off unless someone turns it on,
+    # because of what running the file means:
+    #
+    #   INCLUDE and INCLUDECMD read -- and INCLUDECMD executes -- other things
+    #   RUN reminders shell out
+    #
+    # `-r` is passed to disable RUN directives, `-q` to keep timed reminders
+    # out of the queue, and `-n` to ask only for next occurrences. That covers
+    # the RUN half. It does not cover INCLUDECMD, so turn this on for files you
+    # trust and leave it off for files you do not.
+    #
+    # When `remind` is not on PATH the rule reports nothing rather than
+    # failing: a linter that cannot run on a machine without Remind installed
+    # is a linter that cannot run in CI. It does say so once, through
+    # `Runner`, because silently not syntax-checking is worse than not
+    # syntax-checking -- a build can otherwise believe it is covered when it
+    # is not.
+    class Syntax < Rule
+      DEFAULT_COMMAND = "remind"
+
+      # `file(12): Some message` and `file(12:14): Some message`, the two forms
+      # src/main.c prints depending on whether the command spanned lines.
+      DIAGNOSTIC = /\A(?<file>[^(]+)\((?<line>\d+)(?::(?<end_line>\d+))?\):\s*(?<message>.*)\z/
+
+      # Remind labels its own non-fatal diagnostics -- "Warning: Missing ENDIF"
+      # and friends -- so they are relayed as warnings rather than promoted to
+      # errors by this rule's configured severity.
+      WARNING = /\Awarning\b/i
+
+      def self.enabled_by_default?
+        false
+      end
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "Diagnostics from running the file through Remind itself (off by default)."
+      end
+
+      # Set once per run when the configured command is missing, so `Runner`
+      # can say so a single time rather than per file.
+      attr_reader :unavailable
+
+      def check
+        command = option("Command", DEFAULT_COMMAND)
+        @unavailable = nil
+
+        if executable?(command)
+          run_remind(command)
+        else
+          @unavailable = command
+        end
+      end
+
+      private
+
+        def executable?(command)
+          ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |directory|
+            File.executable?(File.join(directory, command))
+          end
+        end
+
+        # The source is written out rather than piped, because a heredoc's
+        # Remind is only part of its file and Remind must not see the shell
+        # around it. Line numbers come back relative to the temporary file and
+        # are shifted onto the real one.
+        def run_remind(command)
+          Tempfile.create(["remlint", ".rem"]) do |file|
+            file.write(document.source.text)
+            file.flush
+
+            report(capture(command, file.path))
+          end
+        end
+
+        def capture(command, path)
+          output, _status = Open3.capture2e(
+            command,
+            "-n",
+            "-r",
+            "-q",
+            path,
+          )
+
+          output
+        rescue SystemCallError => error
+          "#{path}(1): could not run #{command}: #{error.message}"
+        end
+
+        def report(output)
+          output.each_line do |raw|
+            match = raw.chomp.match(DIAGNOSTIC)
+
+            if match
+              relay(match)
+            end
+          end
+        end
+
+        def relay(match)
+          message = match[:message].strip
+
+          offend(shifted(match[:line]), message, severity: graded(message))
+        end
+
+        # nil means "use whatever the configuration says", which is what an
+        # unlabelled diagnostic gets.
+        def graded(message)
+          if message.match?(WARNING)
+            "warning"
+          end
+        end
+
+        def shifted(line)
+          Integer(line) + document.line_offset
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::Syntax" do
+  lint = proc do |text, config = {}|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::Syntax.new(config).run(RemLint::Document.new(source))
+  end
+
+  it "is off unless the configuration asks for it" do
+    RemLint::Rules::Syntax.enabled_by_default?.should.be.false
+  end
+
+  it "reports nothing when the configured command is not on PATH" do
+    lint.("this is not valid remind at all\n", "Command" => "definitely-not-installed").should.be.empty
+  end
+
+  it "records which command was missing, so the runner can say so once" do
+    rule = RemLint::Rules::Syntax.new("Command" => "definitely-not-installed")
+    source = RemLint::Source.new(path: "t.rem", text: "MSG hi\n")
+
+    rule.run(RemLint::Document.new(source))
+    rule.unavailable.should == "definitely-not-installed"
+  end
+
+  describe "parsing Remind's diagnostics" do
+    # A stub that prints what Remind prints, so the parsing is tested without
+    # requiring Remind to be installed wherever the suite runs.
+    stub = proc do |output|
+      directory = Dir.mktmpdir("remlint-spec")
+      path = File.join(directory, "fake-remind")
+
+      File.write(path, "#!/bin/sh\ncat <<'DIAGNOSTICS'\n#{output}\nDIAGNOSTICS\n")
+      File.chmod(0o755, path)
+      ENV["PATH"] = "#{directory}#{File::PATH_SEPARATOR}#{ENV.fetch('PATH')}"
+
+      "fake-remind"
+    end
+
+    it "turns a single-line diagnostic into an offence" do
+      command = stub.("/tmp/x.rem(3): Missing ']'")
+      offenses = lint.("MSG [x\n", "Command" => command)
+
+      offenses.length.should == 1
+      offenses.first.line.should == 3
+      offenses.first.message.should == "Missing ']'"
+    end
+
+    it "takes the first line of a diagnostic that names a line range" do
+      command = stub.("/tmp/x.rem(3:5): Missing ')'")
+
+      lint.("MSG hi\n", "Command" => command).first.line.should == 3
+    end
+
+    it "reports every diagnostic Remind prints" do
+      command = stub.("/tmp/x.rem(1): First\n/tmp/x.rem(2): Second")
+
+      lint.("MSG hi\n", "Command" => command).map(&:line).should == [1, 2]
+    end
+
+    it "ignores output that is not a diagnostic" do
+      command = stub.("MSG hi\nsomething else entirely")
+
+      lint.("MSG hi\n", "Command" => command).should.be.empty
+    end
+
+    it "shifts a heredoc's diagnostics onto the enclosing file" do
+      command = stub.("/tmp/x.rem(2): Missing ']'")
+      source = RemLint::Source.new(path: "astro", text: "MSG hi\nMSG [x\n", line_offset: 12)
+      rule = RemLint::Rules::Syntax.new("Command" => command)
+
+      rule.run(RemLint::Document.new(source)).first.line.should == 14
+    end
+
+    it "reports at error severity" do
+      command = stub.("/tmp/x.rem(1): Missing ']'")
+
+      lint.("MSG [x\n", "Command" => command).first.severity.should == "error"
+    end
+
+    it "relays a diagnostic Remind labelled a warning as a warning" do
+      command = stub.("/tmp/x.rem(1): Warning: Missing ENDIF")
+      offense = lint.("IF a\n", "Command" => command).first
+
+      offense.severity.should == "warning"
+      offense.message.should == "Warning: Missing ENDIF"
+    end
+  end
+end