remlint 0.1.0

data/lib/remlint/config.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+require_relative "rule"
+
+module RemLint
+  # Per-rule settings, merged from the shipped defaults and a `.remlint.yml`.
+  #
+  # Shaped like RuboCop's: a top-level key per rule, `Enabled` and `Severity`
+  # understood for every rule, anything else passed through to the rule that
+  # asked for it. `Exclude` at the top level drops paths from the run.
+  #
+  # Merging is per rule rather than per file: a project that sets
+  # `TrailingWhitespace: {Severity: error}` keeps every other rule's defaults
+  # instead of silently switching them all off.
+  class Config
+    DEFAULT_PATH = Pathname.new(__dir__).join("../../config/default.yml").cleanpath
+
+    FILENAME = ".remlint.yml"
+
+    attr_reader :settings
+
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    class << self
+      def default
+        new(load_yaml(DEFAULT_PATH))
+      end
+
+      # The defaults with a project file merged over them.
+      def load_file(path)
+        default.merge(load_yaml(Pathname.new(path)))
+      end
+
+      # Walk up from `directory` looking for a `.remlint.yml`, the way every
+      # other linter finds its config, so `remlint` works from a subdirectory.
+      def discover(directory = Dir.pwd)
+        found = ascend(Pathname.new(directory).expand_path)
+
+        if found
+          load_file(found)
+        else
+          default
+        end
+      end
+
+      def ascend(directory)
+        directory.ascend do |candidate|
+          path = candidate.join(FILENAME)
+
+          if path.file?
+            break path
+          end
+        end
+      end
+
+      def load_yaml(path)
+        if path.file?
+          YAML.safe_load(path.read, permitted_classes: [], aliases: true) || {}
+        else
+          {}
+        end
+      end
+    end
+
+    def merge(overrides)
+      merged = settings.dup
+
+      overrides.each do |key, value|
+        merged[key] = merge_section(settings[key], value)
+      end
+
+      Config.new(merged)
+    end
+
+    def for_rule(rule_name)
+      settings.fetch(rule_name, {})
+    end
+
+    # A rule runs unless it is switched off, or unless it is one of the
+    # opt-in rules and nothing switched it on.
+    def enabled?(rule_class)
+      section = for_rule(rule_class.rule_name)
+
+      section.fetch("Enabled", rule_class.enabled_by_default?)
+    end
+
+    def excluded?(path)
+      exclude_patterns.any? do |pattern|
+        File.fnmatch?(pattern, path.to_s, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      end
+    end
+
+    def exclude_patterns
+      Array(settings["Exclude"])
+    end
+
+    # Rules the config leaves running, instantiated with their own section.
+    def rules
+      Rule.all.select { |rule_class| enabled?(rule_class) }.map do |rule_class|
+        rule_class.new(for_rule(rule_class.rule_name))
+      end
+    end
+
+    # `--only` on the command line: run these and nothing else, regardless of
+    # what the file says, but keep each rule's configured options.
+    def only(rule_names)
+      wanted = Array(rule_names)
+      merged = settings.dup
+
+      Rule.all.each do |rule_class|
+        section = merged.fetch(rule_class.rule_name, {}).dup
+        section["Enabled"] = wanted.include?(rule_class.rule_name)
+        merged[rule_class.rule_name] = section
+      end
+
+      Config.new(merged)
+    end
+
+    private
+
+      # A rule's section merges key by key; anything else -- Exclude, scalars --
+      # is replaced outright, because a project listing its own excludes means
+      # those and not those plus ours.
+      def merge_section(existing, override)
+        if existing.is_a?(Hash) && override.is_a?(Hash)
+          existing.merge(override)
+        else
+          override
+        end
+      end
+  end
+end
+
+__END__
+
+require_relative "document"
+require_relative "rules/line_length"
+require_relative "rules/trailing_whitespace"
+
+describe "RemLint::Config" do
+  # A pair of registered rules to configure, so the assertions do not depend on
+  # which real rules happen to be loaded.
+  on_by_default = Class.new(RemLint::Rule) do
+    def self.rule_name = "SpecOnByDefault"
+
+    def check = nil
+  end
+
+  off_by_default = Class.new(RemLint::Rule) do
+    def self.rule_name = "SpecOffByDefault"
+    def self.enabled_by_default? = false
+
+    def check = nil
+  end
+
+  describe "defaults" do
+    it "ships a config for every rule that is on by default" do
+      RemLint::Config.default.enabled?(on_by_default).should.be.true
+    end
+
+    it "leaves an opt-in rule off until something asks for it" do
+      RemLint::Config.default.enabled?(off_by_default).should.be.false
+    end
+  end
+
+  describe "merging" do
+    config = RemLint::Config.new(
+      "SpecOnByDefault" => { "Enabled" => true, "Severity" => "warning" },
+    )
+
+    it "keeps the keys an override does not mention" do
+      merged = config.merge("SpecOnByDefault" => { "Severity" => "error" })
+
+      merged.for_rule("SpecOnByDefault").should == { "Enabled" => true, "Severity" => "error" }
+    end
+
+    it "leaves other rules alone" do
+      merged = config.merge("SpecOffByDefault" => { "Enabled" => true })
+
+      merged.enabled?(on_by_default).should.be.true
+      merged.enabled?(off_by_default).should.be.true
+    end
+
+    it "replaces a list outright rather than appending to it" do
+      merged = config.merge("Exclude" => ["vendor/**/*"])
+
+      merged.exclude_patterns.should == ["vendor/**/*"]
+    end
+
+    it "does not mutate the config it was merged from" do
+      config.merge("SpecOnByDefault" => { "Severity" => "error" })
+
+      config.for_rule("SpecOnByDefault").fetch("Severity").should == "warning"
+    end
+  end
+
+  describe "enabling and disabling" do
+    it "honours an explicit Enabled: false" do
+      config = RemLint::Config.new("SpecOnByDefault" => { "Enabled" => false })
+
+      config.enabled?(on_by_default).should.be.false
+    end
+
+    it "honours an explicit Enabled: true on an opt-in rule" do
+      config = RemLint::Config.new("SpecOffByDefault" => { "Enabled" => true })
+
+      config.enabled?(off_by_default).should.be.true
+    end
+
+    it "instantiates each enabled rule with its own section" do
+      config = RemLint::Config.new("TrailingWhitespace" => { "Severity" => "warning" })
+      rule = config.rules.find { |candidate| candidate.rule_name == "TrailingWhitespace" }
+
+      rule.config.should == { "Severity" => "warning" }
+    end
+  end
+
+  describe "only" do
+    it "runs the named rules and nothing else" do
+      config = RemLint::Config.default.only(["LineLength"])
+
+      # LineLength is off by default and TrailingWhitespace is on; --only
+      # inverts both, which is the whole point of it.
+      config.enabled?(RemLint::Rules::LineLength).should.be.true
+      config.enabled?(RemLint::Rules::TrailingWhitespace).should.be.false
+    end
+
+    it "keeps the options of the rules it leaves running" do
+      config = RemLint::Config
+        .new("SpecOffByDefault" => { "Severity" => "error" })
+        .only(["SpecOffByDefault"])
+
+      config.for_rule("SpecOffByDefault").fetch("Severity").should == "error"
+    end
+  end
+
+  describe "excludes" do
+    config = RemLint::Config.new("Exclude" => ["examples/*.rem", "vendor/**/*"])
+
+    it "matches a shell pattern against the path" do
+      config.excluded?("examples/tflag.rem").should.be.true
+      config.excluded?("vendor/a/b/c.rem").should.be.true
+      config.excluded?("holidays.rem").should.be.false
+    end
+
+    it "does not let a single-star pattern cross a directory boundary" do
+      config.excluded?("examples/nested/a.rem").should.be.false
+    end
+  end
+end

data/lib/remlint/date_literal.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require_relative "vocabulary"
+
+module RemLint
+  # A fully-specified date written out in a trigger.
+  #
+  # Remind accepts the three components in any order -- `1 Jan 2027`,
+  # `Jan 1 2027` and `2027 Jan 1` are the same date to `GetFullDate` -- so this
+  # collects components rather than matching a shape.
+  CalendarDate = Struct.new(:year, :month, :day) do
+    # Days from 1990-01-01, the same epoch Remind counts from (`BASE` in
+    # src/custom.h.in). Only ever compared against another one of these, so it
+    # needs to be monotonic rather than meaningful.
+    def to_i
+      (year * 10_000) + (month * 100) + day
+    end
+
+    def to_s
+      format(
+        "%04d-%02d-%02d",
+        year,
+        month,
+        day,
+      )
+    end
+
+    def <=>(other)
+      to_i <=> other.to_i
+    end
+
+    include Comparable
+  end
+
+  # Reads a date out of a run of tokens, the way `GetFullDate` does.
+  #
+  # The classification is `FindNumericToken`'s (src/token.c): a number from
+  # 1990 to 5990 is a year, a number from 1 to 31 is a day, and `YYYY-MM-DD`
+  # is a date all by itself. There is no overlap to resolve -- years start
+  # above the largest day -- so the components can arrive in any order.
+  #
+  # Returns nil unless all three components turn up, because a partial date is
+  # a different question from a wrong one, and the rules that care about
+  # partial dates want to ask it separately.
+  module DateLiteral
+    EPOCH_YEAR = 1990
+
+    # `BASE` + `YR_RANGE` from src/custom.h.in.
+    LAST_YEAR = EPOCH_YEAR + 4000
+
+    MAX_DAY = 31
+
+    SEPARATORS = %w[- /].freeze
+
+    module_function
+
+    # Scans forward from `index` and returns [date, tokens consumed]. Consumed
+    # is zero when nothing date-shaped was there at all.
+    def scan(tokens, index)
+      state = { year: nil, month: nil, day: nil }
+      cursor = index
+
+      while cursor < tokens.length
+        taken = absorb(tokens, cursor, state)
+
+        if taken.zero?
+          break
+        end
+
+        cursor += taken
+      end
+
+      [complete(state), cursor - index]
+    end
+
+    # The date at `index`, or nil.
+    def at(tokens, index)
+      scan(tokens, index).first
+    end
+
+    def absorb(tokens, cursor, state)
+      iso = iso_date(tokens, cursor)
+
+      if iso
+        merge(state, iso)
+        5
+      else
+        component(tokens[cursor], state)
+      end
+    end
+
+    # `2027-01-01` reaches the lexer as five tokens, because a hyphen is an
+    # operator everywhere else.
+    def iso_date(tokens, cursor)
+      window = tokens[cursor, 5]
+
+      if window&.length == 5 && iso_shape?(window)
+        { year: window[0].value.to_i, month: window[2].value.to_i, day: window[4].value.to_i }
+      end
+    end
+
+    def iso_shape?(window)
+      window[0].type == :number && window[2].type == :number && window[4].type == :number &&
+        SEPARATORS.include?(window[1].value) && window[1].value == window[3].value &&
+        window[0].value.length == 4
+    end
+
+    def component(token, state)
+      value = classify(token)
+
+      if value.nil? || !state[value.first].nil?
+        0
+      else
+        state[value.first] = value.last
+        1
+      end
+    end
+
+    def classify(token)
+      case token.type
+      when :number then number(token.value)
+      when :name   then month(token.value)
+      end
+    end
+
+    def number(text)
+      value = Integer(text, exception: false)
+
+      if value.nil?
+        nil
+      elsif value >= EPOCH_YEAR && value <= LAST_YEAR
+        [:year, value]
+      elsif value >= 1 && value <= MAX_DAY
+        [:day, value]
+      end
+    end
+
+    # Month names abbreviate like every other keyword: `Jan` is `JANUARY`
+    # because its minimum length is 3.
+    def month(word)
+      keyword = Vocabulary.keyword(word)
+
+      if keyword&.type == "T_Month"
+        [:month, MONTHS.index(keyword.name) + 1]
+      end
+    end
+
+    MONTHS = %w[
+      JANUARY FEBRUARY MARCH APRIL MAY JUNE
+      JULY AUGUST SEPTEMBER OCTOBER NOVEMBER DECEMBER
+    ].freeze
+
+    def merge(state, components)
+      components.each do |key, value|
+        state[key] ||= value
+      end
+    end
+
+    def complete(state)
+      if state.values.none?(&:nil?)
+        CalendarDate.new(state[:year], state[:month], state[:day])
+      end
+    end
+  end
+end
+
+__END__
+
+require_relative "document"
+
+describe "RemLint::DateLiteral" do
+  tokens = proc do |text|
+    source = RemLint::Source.new(path: "t.rem", text: text)
+    document = RemLint::Document.new(source)
+
+    document.tokens_for(document.logical_lines.first)
+  end
+
+  date = proc { |text| RemLint::DateLiteral.at(tokens.(text), 0) }
+
+  describe "the spelled-out form" do
+    it "reads day, month, year" do
+      date.("1 Jan 2027").to_s.should == "2027-01-01"
+    end
+
+    it "reads month, day, year" do
+      date.("Jan 1 2027").to_s.should == "2027-01-01"
+    end
+
+    it "reads them in any other order, as GetFullDate does" do
+      date.("2027 Jan 1").to_s.should == "2027-01-01"
+      date.("2027 1 Jan").to_s.should == "2027-01-01"
+    end
+
+    it "reads a full month name" do
+      date.("15 September 2026").to_s.should == "2026-09-15"
+    end
+
+    it "reads an abbreviated month name" do
+      date.("15 Sep 2026").to_s.should == "2026-09-15"
+      date.("15 sept 2026").to_s.should == "2026-09-15"
+    end
+
+    it "reads December, the last month" do
+      date.("31 Dec 2026").to_s.should == "2026-12-31"
+    end
+  end
+
+  describe "the ISO form" do
+    it "reads a hyphenated date" do
+      date.("2027-01-01").to_s.should == "2027-01-01"
+    end
+
+    it "reads a slashed date" do
+      date.("2027/03/15").to_s.should == "2027-03-15"
+    end
+
+    it "does not read a mixed separator" do
+      date.("2027-03/15").should.be.nil
+    end
+
+    it "does not read a subtraction as a date" do
+      date.("2027 - 3").should.be.nil
+    end
+  end
+
+  describe "dates it will not complete" do
+    it "returns nil for a partial date" do
+      date.("1 Jan").should.be.nil
+      date.("Jan 2027").should.be.nil
+      date.("2027").should.be.nil
+    end
+
+    it "returns nil for nothing date-shaped at all" do
+      date.("MSG hello").should.be.nil
+    end
+
+    it "returns nil for a number outside both ranges" do
+      # 1900 is neither a year Remind represents nor a day.
+      date.("32 Jan 1900").should.be.nil
+    end
+  end
+
+  describe "component classification" do
+    it "treats 1990 as the first year, not a day" do
+      date.("1 Jan 1990").to_s.should == "1990-01-01"
+    end
+
+    it "treats 5990 as the last year" do
+      date.("1 Jan 5990").to_s.should == "5990-01-01"
+    end
+
+    it "treats 31 as a day" do
+      date.("31 Jan 2027").to_s.should == "2027-01-31"
+    end
+
+    it "stops at a component it already has" do
+      # The second month name is not part of this date.
+      RemLint::DateLiteral.scan(tokens.("1 Jan 2027 Feb"), 0).last.should == 3
+    end
+  end
+
+  describe "scanning from an offset" do
+    it "starts where it is told to" do
+      stream = tokens.("REM 1 Jan 2027 MSG hi")
+
+      RemLint::DateLiteral.at(stream, 1).to_s.should == "2027-01-01"
+    end
+
+    it "reports how many tokens it took" do
+      RemLint::DateLiteral.scan(tokens.("1 Jan 2027"), 0).last.should == 3
+      RemLint::DateLiteral.scan(tokens.("2027-01-01"), 0).last.should == 5
+    end
+  end
+
+  describe "comparison" do
+    it "orders dates" do
+      (date.("1 Jan 2027") < date.("2 Jan 2027")).should.be.true
+      (date.("31 Dec 2026") < date.("1 Jan 2027")).should.be.true
+      (date.("1 Jan 2027") == date.("2027-01-01")).should.be.true
+    end
+  end
+end

data/lib/remlint/document.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "source"
+require_relative "logical_line"
+require_relative "command"
+require_relative "expr_lexer"
+require_relative "invocation"
+require_relative "trigger"
+
+module RemLint
+  # Everything a rule may look at, built once per source and shared by all of
+  # them.
+  #
+  # The four views answer four different questions and rules should take the
+  # narrowest one that works:
+  #
+  #   raw_lines      the bytes, per physical line -- for whitespace rules
+  #   logical_lines  continuations joined -- for anything spanning lines
+  #   commands       classified -- for anything keyed on which command it is
+  #   tokens_for     lexed -- for anything looking inside a command
+  #   trigger_for    clauses located -- for anything keyed on AT, UNTIL, TZ ...
+  #
+  # Building all of it eagerly except the token streams keeps rules cheap
+  # without lexing files no rule looks inside; the token streams are memoised
+  # per logical line, so several rules asking cost one lex.
+  class Document
+    attr_reader :source, :logical_lines, :commands
+
+    def initialize(source)
+      @source = source
+      @logical_lines = Joiner.call(source)
+      @commands = Classifier.all(@logical_lines)
+      @token_cache = {}
+      @trigger_cache = {}
+    end
+
+    def path
+      source.path
+    end
+
+    def line_offset
+      source.line_offset
+    end
+
+    def label
+      source.label
+    end
+
+    # The physical lines, exactly as they are in the file, newline and all.
+    def raw_lines
+      @raw_lines ||= source.lines
+    end
+
+    # The file line number of `raw_lines[index]`.
+    def line_number_at(index)
+      index + 1 + line_offset
+    end
+
+    def each_raw_line
+      raw_lines.each_with_index do |raw, index|
+        yield raw, line_number_at(index)
+      end
+    end
+
+    # Significant tokens of one logical line, lexed at most once.
+    def tokens_for(logical_line)
+      @token_cache[logical_line.line] ||= ExprLexer.significant(logical_line.text)
+    end
+
+    # How the file says it is meant to be run, from a
+    # `# remlint:invocation` comment. Undeclared for a file that says nothing,
+    # which is the honest default.
+    def invocation
+      @invocation ||= Invocation.of(self)
+    end
+
+    # The clauses of one command's trigger, parsed at most once. Rules ask this
+    # rather than scanning tokens themselves, because the trigger/body boundary
+    # is easy to get wrong and expensive to get wrong twice.
+    def trigger_for(command)
+      @trigger_cache[command.line] ||= Trigger.of(
+        tokens_for(command.logical_line),
+        triggered: Trigger.triggered?(command),
+      )
+    end
+
+    def code_commands
+      @code_commands ||= commands.select(&:code?)
+    end
+  end
+end
+
+__END__
+
+describe "RemLint::Document" do
+  document = proc do |text, line_offset = 0|
+    RemLint::Document.new(RemLint::Source.new(path: "t.rem", text: text, line_offset: line_offset))
+  end
+
+  sample = "# header\nIF a\n   MSG [x] \\\n       [y]\nENDIF\n"
+
+  it "exposes the physical lines untouched" do
+    document.(sample).raw_lines.length.should == 5
+    document.(sample).raw_lines.first.should == "# header\n"
+  end
+
+  it "exposes logical lines with continuations joined" do
+    document.(sample).logical_lines.length.should == 4
+  end
+
+  it "exposes classified commands" do
+    document.(sample).commands.map(&:kind).should == %i[comment keyword keyword keyword]
+  end
+
+  it "filters out comments and blanks for rules that only want code" do
+    document.("# note\n\nMSG hi\n").code_commands.map(&:line).should == [3]
+  end
+
+  it "numbers physical lines through the source offset" do
+    doc = document.("MSG one\nMSG two\n", 40)
+
+    doc.line_number_at(0).should == 41
+    doc.logical_lines.map(&:line).should == [41, 42]
+  end
+
+  it "yields each raw line with its file line number" do
+    seen = []
+    document.("MSG one\nMSG two\n", 40).each_raw_line { |raw, line| seen << [raw.chomp, line] }
+
+    seen.should == [["MSG one", 41], ["MSG two", 42]]
+  end
+
+  it "lexes a logical line once and reuses the result" do
+    doc = document.("MSG [ansicolor(1,2,3)]\n")
+    line = doc.logical_lines.first
+
+    doc.tokens_for(line).map(&:type).should.include :function
+    doc.tokens_for(line).should.be.identical_to doc.tokens_for(line)
+  end
+
+  it "parses a command's trigger once and reuses the result" do
+    doc = document.("REM Tue AT 15:00 MSG Meet Bob at the pub\n")
+    command = doc.code_commands.first
+
+    doc.trigger_for(command).include?("AT").should.be.true
+    doc.trigger_for(command).should.be.identical_to doc.trigger_for(command)
+  end
+
+  it "reads the file's declared invocation" do
+    doc = document.("# remlint:invocation remind -pp\nMSG hi\n")
+
+    doc.invocation.should.be.carries_info
+    doc.invocation.should.be.identical_to doc.invocation
+  end
+
+  it "carries the source's label for messages" do
+    source = RemLint::Source.new(path: "astro", text: "MSG hi\n", description: "heredoc at line 3")
+
+    RemLint::Document.new(source).label.should == "astro (heredoc at line 3)"
+  end
+end