remlint 0.1.0

data/lib/remlint/rules/until_before_from.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+require_relative "../date_literal"
+
+module RemLint
+  module Rules
+    # A reminder whose window closes before it opens.
+    #
+    # `FROM` and `SCANFROM` set the date Remind starts scanning from; `UNTIL`
+    # (and its synonym `THROUGH`) sets the date the reminder expires. An
+    # `UNTIL` strictly before the start describes an empty window, and the
+    # reminder can never fire.
+    #
+    # Unusually for this linter, Remind is not silent here: it warns at parse
+    # time, with a different message for each start keyword --
+    #
+    #   Warning: UNTIL/THROUGH date earlier than FROM date
+    #   Warning: UNTIL/THROUGH date earlier than SCANFROM date
+    #
+    # -- so the value on offer is smaller than usual: saying it in the editor
+    # and in CI rather than only when someone runs the file and reads stderr.
+    # Remind's own `tests/test.rem` marks both forms "Diagnosed".
+    #
+    # Strictly before, not on or before. `FROM 1992-01-06 UNTIL 1992-01-06` is
+    # a legal one-day window and fires on the day; Remind's own warning says
+    # "earlier than" for the same reason.
+    #
+    # Both dates have to be fully spelled out for this to be decidable, which
+    # is no restriction: `GetFullDate` requires exactly that of both keywords.
+    class UntilBeforeFrom < Rule
+      # `UNTIL` and `THROUGH` are the same clause -- `ParseUntil` takes both
+      # and writes the same field.
+      EXPIRY = %w[UNTIL THROUGH].freeze
+
+      # `FROM` and `SCANFROM` are different clauses that both set where the
+      # scan begins, and Remind checks the expiry against either.
+      START = %w[FROM SCANFROM].freeze
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "An UNTIL or THROUGH date earlier than the reminder's FROM or SCANFROM."
+      end
+
+      def check
+        document.code_commands.each do |command|
+          check_window(command)
+        end
+      end
+
+      private
+
+        def check_window(command)
+          trigger = document.trigger_for(command)
+          start = first_clause(trigger, START)
+          expiry = first_clause(trigger, EXPIRY)
+          from = clause_date(command, start)
+          until_date = clause_date(command, expiry)
+
+          if from && until_date && until_date < from
+            report(
+              command,
+              start,
+              expiry,
+              from,
+              until_date,
+            )
+          end
+        end
+
+        def first_clause(trigger, names)
+          names.filter_map { |name| trigger.find(name) }.first
+        end
+
+        # The date written immediately after a clause keyword.
+        def clause_date(command, clause)
+          if clause
+            tokens = document.tokens_for(command.logical_line)
+
+            DateLiteral.at(tokens, clause.argument_index)
+          end
+        end
+
+        def report(command, start, expiry, from, until_date)
+          offend_at(
+            command.logical_line,
+            expiry.offset,
+            "`#{expiry.name} #{until_date}` is earlier than " \
+            "`#{start.name} #{from}`, so this reminder can never trigger",
+          )
+        end
+    end
+  end
+end
+
+__END__
+
+require_relative "../document"
+
+describe "RemLint::Rules::UntilBeforeFrom" do
+  lint = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+
+    RemLint::Rules::UntilBeforeFrom.new.run(RemLint::Document.new(source))
+  end
+
+  messages = proc { |text| lint.(text).map(&:message) }
+
+  describe "windows that can never open" do
+    it "reports an UNTIL before the FROM" do
+      messages.("REM Mon FROM 2027-03-01 UNTIL 2027-01-01 MSG hi\n").first.should ==
+        "`UNTIL 2027-01-01` is earlier than `FROM 2027-03-01`, so this reminder can never trigger"
+    end
+
+    it "reports an UNTIL earlier than a SCANFROM" do
+      # Remind warns about this one separately, and tests/test.rem marks it
+      # "Diagnosed" alongside the FROM form.
+      messages.("REM Mon SCANFROM 1992-01-01 UNTIL 1991-12-31 MSG hi\n").first.should.match(
+        /earlier than `SCANFROM 1992-01-01`/,
+      )
+    end
+
+    it "reports THROUGH, which is the same clause" do
+      messages.("REM Mon FROM 2027-03-01 THROUGH 2027-01-01 MSG hi\n").first.should.match(
+        /`THROUGH 2027-01-01` is earlier than/,
+      )
+    end
+
+    it "reads the spelled-out date form" do
+      messages.("REM Mon FROM 1 March 2027 UNTIL 1 Jan 2027 MSG hi\n").length.should == 1
+    end
+
+    it "reads the two forms mixed" do
+      messages.("REM Mon FROM 2027-03-01 UNTIL 1 Jan 2027 MSG hi\n").length.should == 1
+    end
+
+    it "points at the expiry clause" do
+      text = "REM Mon FROM 2027-03-01 UNTIL 2027-01-01 MSG hi\n"
+
+      lint.(text).first.column.should == text.index("UNTIL") + 1
+    end
+  end
+
+  describe "windows that are fine" do
+    it "accepts an UNTIL after the FROM" do
+      lint.("REM Mon FROM 2027-01-01 UNTIL 2027-03-01 MSG hi\n").should.be.empty
+    end
+
+    it "accepts an UNTIL one day after the FROM" do
+      lint.("REM Mon FROM 2027-01-01 UNTIL 2027-01-02 MSG hi\n").should.be.empty
+    end
+
+    it "accepts a one-day window, which is legal and fires" do
+      # `REM MON FROM 1992-01-06 UNTIL 1992-01-06` triggers on 1992-01-06.
+      lint.("REM Mon FROM 2027-03-01 UNTIL 2027-03-01 MSG hi\n").should.be.empty
+    end
+
+    it "accepts a reminder with only one of the two" do
+      lint.("REM Mon FROM 2027-01-01 MSG hi\n").should.be.empty
+      lint.("REM Mon UNTIL 2027-01-01 MSG hi\n").should.be.empty
+    end
+
+    it "accepts a reminder with neither" do
+      lint.("REM Mon MSG hi\n").should.be.empty
+    end
+
+    it "says nothing about a SCANFROM written as a delta" do
+      # `SCANFROM -7` has no date to compare against.
+      lint.("REM Mon SCANFROM -7 UNTIL 2027-01-01 MSG hi\n").should.be.empty
+    end
+
+    it "does not read the two clauses across different commands" do
+      text = "REM Mon FROM 2027-03-01 MSG a\nREM Tue UNTIL 2027-01-01 MSG b\n"
+
+      lint.(text).should.be.empty
+    end
+  end
+
+  describe "dates it cannot read" do
+    it "says nothing when a date is computed" do
+      lint.("REM Mon FROM [x] UNTIL 2027-01-01 MSG hi\n").should.be.empty
+    end
+
+    it "says nothing when a date is partial" do
+      # GetFullDate would reject it; that is a different rule's offence.
+      lint.("REM Mon FROM 1 Jan UNTIL 2027-01-01 MSG hi\n").should.be.empty
+    end
+  end
+
+  it "says nothing about comments" do
+    lint.("# FROM 2027-03-01 UNTIL 2027-01-01\n").should.be.empty
+  end
+
+  it "reports at error severity" do
+    lint.("REM Mon FROM 2027-03-01 UNTIL 2027-01-01 MSG hi\n").first.severity.should == "error"
+  end
+
+  it "reports the physical line inside a continuation" do
+    lint.("REM Mon FROM 2027-03-01 \\\n    UNTIL 2027-01-01 MSG hi\n").first.line.should == 2
+  end
+end

data/lib/remlint/rules/world_writable_script.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module RemLint
+  module Rules
+    # A reminder file anyone can write to.
+    #
+    # Remind refuses a world-writable script outright, and disables `RUN` for
+    # one it does not own -- because a reminder file is a program, and a
+    # program anybody can edit will eventually run something somebody else
+    # wrote. The check is in src/files.c (`CheckSafety`).
+    #
+    # This is the only rule that looks at a file rather than at its contents,
+    # and the only one that can fail on a file that is textually perfect. It
+    # earns its place because the failure mode is a cron job that stops
+    # working, or worse does not, and the mode is invisible in every editor.
+    #
+    # Group-writable is reported separately and more quietly: Remind allows it,
+    # but it means the file's safety rests on the group's membership.
+    class WorldWritableScript < Rule
+      WORLD_WRITABLE = 0o002
+      GROUP_WRITABLE = 0o020
+
+      def self.default_severity
+        "error"
+      end
+
+      def self.description
+        "A reminder file that is world-writable, which Remind refuses to read."
+      end
+
+      def check
+        mode = mode_of(document.path)
+
+        if mode
+          report(mode)
+        end
+      end
+
+      private
+
+        # Only a real file on disk has a mode; text linted from a string has
+        # nothing to check.
+        def mode_of(path)
+          if File.file?(path)
+            File.stat(path).mode
+          end
+        rescue SystemCallError
+          nil
+        end
+
+        def report(mode)
+          if (mode & WORLD_WRITABLE).positive?
+            offend(
+              document.line_number_at(0),
+              "this file is world-writable (mode #{format('%<mode>04o', mode: mode & 0o7777)}); " \
+              "Remind refuses to read a script anyone can edit",
+            )
+          elsif (mode & GROUP_WRITABLE).positive?
+            offend(
+              document.line_number_at(0),
+              "this file is group-writable (mode #{format('%<mode>04o', mode: mode & 0o7777)}); " \
+              "Remind allows it, but the script's safety then rests on the group's membership",
+            )
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require "fileutils"
+require "tmpdir"
+
+require_relative "../document"
+
+describe "RemLint::Rules::WorldWritableScript" do
+  root = Dir.mktmpdir("remlint-modes")
+
+  written = proc do |mode|
+    path = File.join(root, "mode-#{format('%o', mode)}.rem")
+    File.write(path, "MSG hi\n")
+    File.chmod(mode, path)
+
+    RemLint::Rules::WorldWritableScript.new.run(
+      RemLint::Document.new(RemLint::Source.new(path: path, text: "MSG hi\n")),
+    )
+  end
+
+  it "accepts a file only its owner can write" do
+    written.(0o644).should.be.empty
+    written.(0o600).should.be.empty
+  end
+
+  it "reports a world-writable file" do
+    written.(0o666).first.message.should.match(
+      /world-writable \(mode 0666\); Remind refuses to read a script anyone can edit/,
+    )
+  end
+
+  it "reports a world-writable file whatever else it allows" do
+    written.(0o777).length.should == 1
+  end
+
+  it "reports a group-writable file more quietly" do
+    written.(0o664).first.message.should.match(/group-writable \(mode 0664\)/)
+  end
+
+  it "prefers the world-writable message when both apply" do
+    written.(0o666).first.message.should.match(/world-writable/)
+  end
+
+  it "says nothing when there is no file on disk to stat" do
+    source = RemLint::Source.new(path: "not-a-real-path.rem", text: "MSG hi\n")
+
+    RemLint::Rules::WorldWritableScript.new.run(RemLint::Document.new(source)).should.be.empty
+  end
+
+  it "reports on the first line of the source" do
+    written.(0o666).first.line.should == 1
+  end
+
+  it "reports at error severity" do
+    written.(0o666).first.severity.should == "error"
+  end
+end

data/lib/remlint/rules.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+
+# Requiring a rule file registers the rule, so this list is the only place a
+# new rule has to be mentioned. Sorted by name to make an addition a one-line
+# diff rather than an argument about ordering.
+require_relative "rules/addomit_without_scanfrom"
+require_relative "rules/advance_warning_body"
+require_relative "rules/banner_placement"
+require_relative "rules/calendar_text_limited"
+require_relative "rules/callback_signature"
+require_relative "rules/clause_needs_full_date"
+require_relative "rules/clause_requires_at"
+require_relative "rules/clause_value_range"
+require_relative "rules/color_component_range"
+require_relative "rules/coordinate_not_string"
+require_relative "rules/dangling_continuation"
+require_relative "rules/date_out_of_range"
+require_relative "rules/debug_command"
+require_relative "rules/easterdate_from_today"
+require_relative "rules/function_arity"
+require_relative "rules/function_redefinition"
+require_relative "rules/generated_file_edited"
+require_relative "rules/hebrew_date"
+require_relative "rules/iftrig_with_satisfy"
+require_relative "rules/include_path"
+require_relative "rules/info_clause"
+require_relative "rules/info_substitution_without_header"
+require_relative "rules/invocation_mismatch"
+require_relative "rules/keyword_case"
+require_relative "rules/license_header"
+require_relative "rules/line_length"
+require_relative "rules/literal_type_mismatch"
+require_relative "rules/localization_pack"
+require_relative "rules/moon_phase_argument"
+require_relative "rules/omit_aware_delta"
+require_relative "rules/push_vars_missing_name"
+require_relative "rules/repeat_trigger"
+require_relative "rules/satisfy_constraint"
+require_relative "rules/shell_maxlen"
+require_relative "rules/shell_use_while_run_disabled"
+require_relative "rules/string_escape"
+require_relative "rules/syntax"
+require_relative "rules/system_variable_assignment"
+require_relative "rules/tag_syntax"
+require_relative "rules/text_after_eof_marker"
+require_relative "rules/time_zone_name"
+require_relative "rules/tk_tag_namespace"
+require_relative "rules/todo_complete_through"
+require_relative "rules/trailing_whitespace"
+require_relative "rules/translate_command"
+require_relative "rules/unbalanced_blocks"
+require_relative "rules/unbalanced_delimiters"
+require_relative "rules/unknown_special_type"
+require_relative "rules/unknown_substitution_sequence"
+require_relative "rules/unknown_system_variable"
+require_relative "rules/unquoted_shell_substitution"
+require_relative "rules/until_before_from"
+require_relative "rules/world_writable_script"

data/lib/remlint/runner.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "config"
+require_relative "document"
+require_relative "extractors"
+
+module RemLint
+  # Walks paths, extracts Remind out of them, runs the enabled rules, and drops
+  # whatever the file itself asked to be quiet about.
+  class Runner
+    # `# remlint:disable UnbalancedBlocks, TrailingWhitespace`, or `all`.
+    # Recognised after either comment character, and mid-line, so it can sit at
+    # the end of the line it applies to.
+    DISABLE = /[#;]\s*remlint:disable\s+(?<rules>[\w\s,-]+)/
+
+    ALL = "all"
+
+    # Extensions worth opening when walking a directory. A file with no
+    # extension is opened too, because `examples/astro` and `examples/ansitext`
+    # have none and are where most of the Remind in that directory lives.
+    CANDIDATE = /\.(rem|sh|bash)\z|\A[^.]+\z/
+
+    attr_reader :config, :warnings
+
+    def initialize(config = Config.default)
+      @config = config
+      @warnings = []
+    end
+
+    # Returns the offences, worst-placed first in reading order.
+    def run(paths)
+      files(paths).flat_map { |path| lint_file(path) }.sort_by(&:sort_key)
+    end
+
+    # The files a set of paths expands to: a named file is taken as given, a
+    # named directory is walked.
+    def files(paths)
+      Array(paths).flat_map { |path| expand(path) }.uniq.reject { |path| config.excluded?(path) }
+    end
+
+    def lint_file(path)
+      text = read(path)
+
+      if text.nil?
+        []
+      else
+        lint_text(path, text)
+      end
+    end
+
+    def lint_text(path, text)
+      rules = config.rules
+
+      Extractors.extract(path, text).flat_map do |source|
+        lint_source(Document.new(source), rules)
+      end
+    end
+
+    private
+
+      def expand(path)
+        pathname = Pathname.new(path)
+
+        if pathname.directory?
+          walk(pathname)
+        else
+          [path.to_s]
+        end
+      end
+
+      def walk(directory)
+        directory.find.filter_map do |entry|
+          if entry.file? && entry.basename.to_s.match?(CANDIDATE)
+            entry.to_s
+          end
+        end
+      end
+
+      # A file Remind can read is a file of bytes; one that is not valid UTF-8
+      # is not Remind's problem or ours, and neither is one we cannot open.
+      def read(path)
+        text = File.read(path, encoding: "UTF-8")
+
+        if text.valid_encoding?
+          text
+        end
+      rescue SystemCallError
+        nil
+      end
+
+      def lint_source(document, rules)
+        found = rules.flat_map { |rule| rule.run(document) }
+
+        note_unavailable(rules)
+
+        found.reject { |offense| disabled?(document, offense) }
+      end
+
+      # A rule that could not do its job says so once for the whole run, not
+      # once per file and not silently. `Syntax` is the only one: skipping
+      # quietly would let a build believe it is syntax-checking when the
+      # `remind` it needs is not installed.
+      def note_unavailable(rules)
+        rules.each do |rule|
+          missing = rule.respond_to?(:unavailable) && rule.unavailable
+
+          if missing
+            record(
+              "the Syntax rule is enabled but `#{missing}` is not on PATH, " \
+                                 "so no file was syntax-checked",
+            )
+          end
+        end
+      end
+
+      def record(warning)
+        unless @warnings.include?(warning)
+          @warnings << warning
+        end
+      end
+
+      # A directive applies to the line it is on and to the line below it, so
+      # it can be written after the offending line or above it -- puppet-lint's
+      # two forms, which cover the case where the line has no room left.
+      def disabled?(document, offense)
+        index = offense.line - document.line_offset - 1
+
+        [index, index - 1].any? do |candidate|
+          directive_covers?(document.raw_lines[candidate], offense.rule, candidate)
+        end
+      end
+
+      def directive_covers?(raw, rule_name, index)
+        match = index >= 0 && raw&.match(DISABLE)
+
+        if match
+          named = match[:rules].split(/[,\s]+/).reject(&:empty?)
+
+          named.include?(ALL) || named.include?(rule_name)
+        end
+      end
+  end
+end
+
+__END__
+
+require "tempfile"
+
+require_relative "rules/trailing_whitespace"
+require_relative "rules/unbalanced_blocks"
+
+describe "RemLint::Runner" do
+  # Just the two rules, so the assertions do not shift when a rule is added.
+  config = RemLint::Config.default.only(%w[TrailingWhitespace UnbalancedBlocks])
+  runner = RemLint::Runner.new(config)
+
+  lint = proc { |text, path = "t.rem"| runner.lint_text(path, text) }
+  rules_of = proc { |text| lint.(text).map(&:rule) }
+
+  describe "linting text" do
+    it "runs every enabled rule" do
+      rules_of.("IF a\nMSG hi \n").sort.should == %w[TrailingWhitespace UnbalancedBlocks]
+    end
+
+    it "returns nothing for a clean file" do
+      lint.("IF a\n   MSG hi\nENDIF\n").should.be.empty
+    end
+
+    it "runs only the rules the config leaves on" do
+      only_blocks = RemLint::Runner.new(RemLint::Config.default.only(%w[UnbalancedBlocks]))
+
+      only_blocks.lint_text("t.rem", "IF a\nMSG hi \n").map(&:rule).should == ["UnbalancedBlocks"]
+    end
+
+    it "sorts offences into reading order when running over real paths" do
+      Tempfile.create(["spec", ".rem"]) do |file|
+        file.write("MSG trailing \nIF a\nMSG also trailing \n")
+        file.flush
+
+        runner.run([file.path]).map { |offense| [offense.line, offense.rule] }.should ==
+          [[1, "TrailingWhitespace"], [2, "UnbalancedBlocks"], [3, "TrailingWhitespace"]]
+      end
+    end
+  end
+
+  describe "extraction" do
+    it "lints a .rem file whole" do
+      lint.("MSG hi \n").length.should == 1
+    end
+
+    it "lints a heredoc and reports positions in the enclosing file" do
+      script = "#!/bin/sh\n# note\nremind - <<'EOF'\nMSG hi \nEOF\n"
+
+      offenses = lint.(script, "ansitext")
+      offenses.length.should == 1
+      offenses.first.line.should == 4
+    end
+
+    it "ignores a file that holds no Remind at all" do
+      lint.("#!/bin/sh\necho hello \n", "build.sh").should.be.empty
+    end
+  end
+
+  describe "disable comments" do
+    it "drops an offence named on the same line" do
+      lint.("MSG hi  # remlint:disable TrailingWhitespace\n").should.be.empty
+    end
+
+    it "drops an offence named on the line above" do
+      lint.("# remlint:disable TrailingWhitespace\nMSG hi \n").should.be.empty
+    end
+
+    it "accepts the semicolon comment character too" do
+      lint.("; remlint:disable TrailingWhitespace\nMSG hi \n").should.be.empty
+    end
+
+    it "drops several rules named together" do
+      text = "# remlint:disable TrailingWhitespace, UnbalancedBlocks\nIF a\nMSG hi \n"
+
+      lint.(text).map(&:rule).should == ["TrailingWhitespace"]
+    end
+
+    it "drops everything when told all" do
+      lint.("# remlint:disable all\nMSG hi \n").should.be.empty
+    end
+
+    it "leaves an offence a directive does not name" do
+      lint.("# remlint:disable UnbalancedBlocks\nMSG hi \n").map(&:rule).should ==
+        ["TrailingWhitespace"]
+    end
+
+    it "does not reach a line further than one below the directive" do
+      lint.("# remlint:disable TrailingWhitespace\nMSG ok\nMSG hi \n").length.should == 1
+    end
+  end
+
+  describe "run warnings" do
+    it "says once when the Syntax rule cannot find its command" do
+      only_syntax = RemLint::Config.default
+        .only(%w[Syntax])
+        .merge("Syntax" => { "Command" => "definitely-not-installed" })
+      runner = RemLint::Runner.new(only_syntax)
+
+      runner.lint_text("a.rem", "MSG hi\n")
+      runner.lint_text("b.rem", "MSG hi\n")
+
+      runner.warnings.length.should == 1
+      runner.warnings.first.should.match(/is not on PATH, so no file was syntax-checked/)
+    end
+
+    it "says nothing when no rule is short of anything" do
+      RemLint::Runner.new(config).tap { |r| r.lint_text("a.rem", "MSG hi\n") }
+        .warnings.should.be.empty
+    end
+  end
+
+  describe "walking paths" do
+    it "keeps a named file as given" do
+      runner.files(["examples/holidays.rem"]).should == ["examples/holidays.rem"]
+    end
+
+    it "drops a path the config excludes" do
+      excluding = RemLint::Runner.new(RemLint::Config.new("Exclude" => ["vendor/**/*"]))
+
+      excluding.files(["vendor/a.rem", "b.rem"]).should == ["b.rem"]
+    end
+
+    it "returns nothing for a file it cannot read" do
+      runner.lint_file("/nonexistent/nowhere.rem").should.be.empty
+    end
+  end
+end

data/lib/remlint/source.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RemLint
+  # A run of Remind code carved out of a file, together with where it sat.
+  #
+  # `line_offset` is the number of physical lines that preceded this run in the
+  # file on disk -- zero for a plain `.rem` file, and the line number of the
+  # heredoc's opener for Remind embedded in a shell script. Every line number
+  # the linter reports is computed through this offset, so an offence inside
+  # the third heredoc of a shell script points at the real line of that script
+  # rather than at line 4 of an anonymous fragment.
+  Source = Struct.new(
+    :path,
+    :text,
+    :line_offset,
+    :description,
+    keyword_init: true,
+  ) do
+    def initialize(path:, text:, line_offset: 0, description: nil)
+      super
+    end
+
+    def lines
+      text.lines
+    end
+
+    # How to name this source in a message when a file yields more than one.
+    def label
+      if description
+        "#{path} (#{description})"
+      else
+        path
+      end
+    end
+  end
+end