mdl 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e82acf8008929f43d28c4be6a794f538d3745d1dd5acf37487ab061d0f968843
-  data.tar.gz: c4f5b4b055ceb67dd29a0b292fe4c9ecf974ae3724a7db9c359196dafe60efe0
+  metadata.gz: bb98b688ab9d9dc7bac3c169f20fefc7c0cb27ce5bf574bec52053d592b7a9c7
+  data.tar.gz: 873df51b4011d23617c1d73ab47a1928765fee0502b6f58853e2932bb3d5ec59
 SHA512:
-  metadata.gz: 6ed1202471b0bf2df640e0eaaacbfaf23593b3841ebc232ee630d15d4ae7817aedd6b455451612f0f4239762e0ddd6fe7acfa4efd9c61b72b14db87ab7dcce4a
-  data.tar.gz: 3a8b7a23579bc6345fdec2d79442b238c6e32e2836602827ed626d105f9495b2ad000ac799d130ebe97815dca67f29b4e5ba6c21c8f816c1cf60bca0cf4c501a
+  metadata.gz: fea533cf2d4a61c4da291a094e3f94080acee8837919935e789e1b39c98d8bcc416cb9fcb143a10a1f63738ee993d3fe5ce89ca3dc664a9a11712796db8dbc4d
+  data.tar.gz: 8dc7470f981b1267dddb1f668afc4f85c742d6c467ae9a31bcaf24618792d6d9c7792a328ff3258d8efd071d9592b4a84600a2825e787b26d1cb5f7e979989af

data/lib/mdl/cli.rb

@@ -107,6 +107,12 @@ module MarkdownLint
            :description => 'JSON output',
            :boolean => true
 
+    option :sarif,
+           :short => '-S',
+           :long => '--sarif',
+           :description => 'SARIF output',
+           :boolean => true
+
     def run(argv = ARGV)
       parse_options(argv)
 
@@ -145,10 +151,10 @@ module MarkdownLint
     end
 
     def self.toggle_list(parts, to_sym = false)
-      parts = parts.split(',') if parts.class == String
-      if parts.class == Array
+      parts = parts.split(',') if parts.instance_of?(String)
+      if parts.instance_of?(Array)
         inc = parts.reject { |p| p.start_with?('~') }
-        exc = parts.select { |p| p.start_with?('~') }.map { |p| p[1..-1] }
+        exc = parts.select { |p| p.start_with?('~') }.map { |p| p[1..] }
         if to_sym
           inc.map!(&:to_sym)
           exc.map!(&:to_sym)

data/lib/mdl/doc.rb

@@ -34,7 +34,9 @@ module MarkdownLint
       else
         @offset = 0
       end
-      @lines = text.split(/\R/)
+      # The -1 is to cause split to preserve an extra entry in the array so we
+      # can tell if there's a final newline in the file or not.
+      @lines = text.split(/\R/, -1)
       @parsed = Kramdown::Document.new(text, :input => 'MarkdownLint')
       @elements = @parsed.root.children
       add_annotations(@elements)
@@ -78,7 +80,7 @@ module MarkdownLint
 
     def find_type_elements(type, nested = true, elements = @elements)
       results = []
-      type = [type] if type.class == Symbol
+      type = [type] if type.instance_of?(Symbol)
       elements.each do |e|
         results.push(e) if type.include?(e.type)
         if nested && !e.children.empty?
@@ -102,8 +104,8 @@ module MarkdownLint
       type, nested_except = [], elements = @elements
     )
       results = []
-      type = [type] if type.class == Symbol
-      nested_except = [nested_except] if nested_except.class == Symbol
+      type = [type] if type.instance_of?(Symbol)
+      nested_except = [nested_except] if nested_except.instance_of?(Symbol)
       elements.each do |e|
         results.push(e) if type.include?(e.type)
         next if nested_except.include?(e.type) || e.children.empty?
@@ -230,7 +232,7 @@ module MarkdownLint
 
         lines = e.value.split("\n")
         lines.each_with_index do |l, i|
-          matches << first_line + i if regex.match(l)
+          matches << (first_line + i) if regex.match(l)
         end
       end
       matches
@@ -266,6 +268,30 @@ module MarkdownLint
       lines
     end
 
+    ##
+    # Returns the element as plaintext
+
+    def extract_as_text(element)
+      quotes = {
+        :rdquo => '"',
+        :ldquo => '"',
+        :lsquo => "'",
+        :rsquo => "'",
+      }
+      # If anything goes amiss here, e.g. unknown type, then nil will be
+      # returned and we'll just not catch that part of the text, which seems
+      # like a sensible failure mode.
+      element.children.map do |e|
+        if e.type == :text || e.type == :codespan
+          e.value
+        elsif %i{strong em p a}.include?(e.type)
+          extract_as_text(e).join("\n")
+        elsif e.type == :smart_quote
+          quotes[e.value]
+        end
+      end.join.split("\n")
+    end
+
     private
 
     ##

data/lib/mdl/formatters/sarif.rb

@@ -0,0 +1,89 @@
+require 'json'
+
+module MarkdownLint
+  # SARIF formatter
+  #
+  # @see https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+  class SarifFormatter
+    class << self
+      def generate(rules, results)
+        matched_rules_id = results.map { |result| result['rule'] }.uniq
+        matched_rules = rules.select { |id, _| matched_rules_id.include?(id) }
+        JSON.generate(generate_sarif(matched_rules, results))
+      end
+
+      def generate_sarif(rules, results)
+        {
+          :'$schema' => 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+          :version => '2.1.0',
+          :runs => [
+            {
+              :tool => {
+                :driver => {
+                  :name => 'Markdown lint',
+                  :version => MarkdownLint::VERSION,
+                  :informationUri => 'https://github.com/markdownlint/markdownlint',
+                  :rules => generate_sarif_rules(rules),
+                },
+              },
+              :results => generate_sarif_results(rules, results),
+            }
+          ],
+        }
+      end
+
+      def generate_sarif_rules(rules)
+        rules.map do |id, rule|
+          {
+            :id => id,
+            :name => rule.aliases.first.split('-').map(&:capitalize).join,
+            :defaultConfiguration => {
+              :level => 'note',
+            },
+            :properties => {
+              :description => rule.description,
+              :tags => rule.tags,
+              :queryURI => rule.docs_url,
+            },
+            :shortDescription => {
+              :text => rule.description,
+            },
+            :fullDescription => {
+              :text => rule.description,
+            },
+            :helpUri => rule.docs_url,
+            :help => {
+              :text => "More info: #{rule.docs_url}",
+              :markdown => "[More info](#{rule.docs_url})",
+            },
+          }
+        end
+      end
+
+      def generate_sarif_results(rules, results)
+        results.map do |result|
+          {
+            :ruleId => result['rule'],
+            :ruleIndex => rules.find_index { |id, _| id == result['rule'] },
+            :message => {
+              :text => "#{result['rule']} - #{result['description']}",
+            },
+            :locations => [
+              {
+                :physicalLocation => {
+                  :artifactLocation => {
+                    :uri => result['filename'],
+                    :uriBaseId => '%SRCROOT%',
+                  },
+                  :region => {
+                    :startLine => result['line'],
+                  },
+                },
+              }
+            ],
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mdl/rules.rb

@@ -1,3 +1,9 @@
+docs do |id, description|
+  url_hash = [id.downcase,
+              description.downcase.gsub(/[^a-z]+/, '-')].join('---')
+  "https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md##{url_hash}"
+end
+
 rule 'MD001', 'Header levels should only increment by one level at a time' do
   tags :headers
   aliases 'header-increment'
@@ -27,7 +33,7 @@ end
 
 rule 'MD003', 'Header style' do
   # Header styles are things like ### and adding underscores
-  # See http://daringfireball.net/projects/markdown/syntax#header
+  # See https://daringfireball.net/projects/markdown/syntax#header
   tags :headers
   aliases 'header-style'
   # :style can be one of :consistent, :atx, :atx_closed, :setext
@@ -62,7 +68,7 @@ end
 rule 'MD004', 'Unordered list style' do
   tags :bullet, :ul
   aliases 'ul-style'
-  # :style can be one of :consistent, :asterisk, :plus, :dash
+  # :style can be one of :consistent, :asterisk, :plus, :dash, :sublist
   params :style => :consistent
   check do |doc|
     bullets = doc.find_type_elements(:ul).map do |l|
@@ -71,15 +77,30 @@ rule 'MD004', 'Unordered list style' do
     if bullets.empty?
       nil
     else
-      doc_style = if @params[:style] == :consistent
+      doc_style = case @params[:style]
+                  when :consistent
                     doc.list_style(bullets.first)
+                  when :sublist
+                    {}
                   else
                     @params[:style]
                   end
-      bullets.map do |b|
-        doc.element_linenumber(b) \
-                    if doc.list_style(b) != doc_style
-      end.compact
+      results = []
+      bullets.each do |b|
+        if @params[:style] == :sublist
+          level = b.options[:element_level]
+          if doc_style[level]
+            if doc_style[level] != doc.list_style(b)
+              results << doc.element_linenumber(b)
+            end
+          else
+            doc_style[level] = doc.list_style(b)
+          end
+        elsif doc.list_style(b) != doc_style
+          results << doc.element_linenumber(b)
+        end
+      end
+      results.compact
     end
   end
 end
@@ -105,7 +126,7 @@ rule 'MD005', 'Inconsistent indentation for list items at the same level' do
 end
 
 rule 'MD006', 'Consider starting bulleted lists at the beginning of the line' do
-  # Starting at the beginning of the line means that indendation for each
+  # Starting at the beginning of the line means that indentation for each
   # bullet level can be identical.
   tags :bullet, :ul, :indentation
   aliases 'ul-start-left'
@@ -119,7 +140,8 @@ end
 rule 'MD007', 'Unordered list indentation' do
   tags :bullet, :ul, :indentation
   aliases 'ul-indent'
-  params :indent => 2
+  # Do not default to < 3, see PR#373 or the comments in RULES.md
+  params :indent => 3
   check do |doc|
     errors = []
     indents = doc.find_type(:ul).map do |e|
@@ -139,7 +161,7 @@ end
 rule 'MD009', 'Trailing spaces' do
   tags :whitespace
   aliases 'no-trailing-spaces'
-  params :br_spaces => 0
+  params :br_spaces => 2
   check do |doc|
     errors = doc.matching_lines(/\s$/)
     if params[:br_spaces] > 1
@@ -152,8 +174,20 @@ end
 rule 'MD010', 'Hard tabs' do
   tags :whitespace, :hard_tab
   aliases 'no-hard-tabs'
+  params :ignore_code_blocks => false
   check do |doc|
-    doc.matching_lines(/\t/)
+    # Every line in the document that is part of a code block. Blank lines
+    # inside of a code block are acceptable.
+    codeblock_lines = doc.find_type_elements(:codeblock).map do |e|
+      (doc.element_linenumber(e)..
+               doc.element_linenumber(e) + e.value.lines.count).to_a
+    end.flatten
+
+    # Check for lines with hard tab
+    hard_tab_lines = doc.matching_lines(/\t/)
+    # Remove lines with hard tabs, if they stem from codeblock
+    hard_tab_lines -= codeblock_lines if params[:ignore_code_blocks]
+    hard_tab_lines
   end
 end
 
@@ -186,7 +220,9 @@ end
 rule 'MD013', 'Line length' do
   tags :line_length
   aliases 'line-length'
-  params :line_length => 80, :code_blocks => true, :tables => true
+  params :line_length => 80, :ignore_code_blocks => false, :code_blocks => true,
+         :tables => true
+
   check do |doc|
     # Every line in the document that is part of a code block.
     codeblock_lines = doc.find_type_elements(:codeblock).map do |e|
@@ -207,7 +243,14 @@ rule 'MD013', 'Line length' do
       end
     end.flatten
     overlines = doc.matching_lines(/^.{#{@params[:line_length]}}.*\s/)
-    overlines -= codeblock_lines unless params[:code_blocks]
+    if !params[:code_blocks] || params[:ignore_code_blocks]
+      overlines -= codeblock_lines
+      unless params[:code_blocks]
+        warn 'MD013 warning: Parameter :code_blocks is deprecated.'
+        warn '  Please replace \":code_blocks => false\" by '\
+             '\":ignore_code_blocks => true\" in your configuration.'
+      end
+    end
     overlines -= table_lines unless params[:tables]
     overlines
   end
@@ -218,7 +261,7 @@ rule 'MD014', 'Dollar signs used before commands without showing output' do
   aliases 'commands-show-output'
   check do |doc|
     doc.find_type_elements(:codeblock).select do |e|
-      !e.value.empty? and
+      !e.value.empty? &&
         !e.value.split(/\n+/).map { |l| l.match(/^\$\s/) }.include?(nil)
     end.map { |e| doc.element_linenumber(e) }
   end
@@ -229,7 +272,7 @@ rule 'MD018', 'No space after hash on atx style header' do
   aliases 'no-missing-space-atx'
   check do |doc|
     doc.find_type_elements(:header).select do |h|
-      doc.header_style(h) == :atx and doc.element_line(h).match(/^#+[^#\s]/)
+      doc.header_style(h) == :atx && doc.element_line(h).match(/^#+[^#\s]/)
     end.map { |h| doc.element_linenumber(h) }
   end
 end
@@ -239,7 +282,7 @@ rule 'MD019', 'Multiple spaces after hash on atx style header' do
   aliases 'no-multiple-space-atx'
   check do |doc|
     doc.find_type_elements(:header).select do |h|
-      doc.header_style(h) == :atx and doc.element_line(h).match(/^#+\s\s/)
+      doc.header_style(h) == :atx && doc.element_line(h).match(/^#+\s\s/)
     end.map { |h| doc.element_linenumber(h) }
   end
 end
@@ -250,8 +293,8 @@ rule 'MD020', 'No space inside hashes on closed atx style header' do
   check do |doc|
     doc.find_type_elements(:header).select do |h|
       doc.header_style(h) == :atx_closed \
-        and (doc.element_line(h).match(/^#+[^#\s]/) \
-             or doc.element_line(h).match(/[^#\s\\]#+$/))
+        && (doc.element_line(h).match(/^#+[^#\s]/) \
+             || doc.element_line(h).match(/[^#\s\\]#+$/))
     end.map { |h| doc.element_linenumber(h) }
   end
 end
@@ -262,8 +305,8 @@ rule 'MD021', 'Multiple spaces inside hashes on closed atx style header' do
   check do |doc|
     doc.find_type_elements(:header).select do |h|
       doc.header_style(h) == :atx_closed \
-        and (doc.element_line(h).match(/^#+\s\s/) \
-             or doc.element_line(h).match(/\s\s#+$/))
+        && (doc.element_line(h).match(/^#+\s\s/) \
+             || doc.element_line(h).match(/\s\s#+$/))
     end.map { |h| doc.element_linenumber(h) }
   end
 end
@@ -297,7 +340,7 @@ rule 'MD022', 'Headers should be surrounded by blank lines' do
         errors << linenum if line.match(/^\#{1,6}/) && !prev_lines[1].empty?
         # Next, look for setext style
         if line.match(/^(-+|=+)\s*$/) && !prev_lines[0].empty?
-          errors << linenum - 1
+          errors << (linenum - 1)
         end
         linenum += 1
         prev_lines << line
@@ -329,7 +372,7 @@ rule 'MD023', 'Headers must start at the beginning of the line' do
         errors << linenum if line.match(/^\s+\#{1,6}/)
         # Next, look for setext style
         if line.match(/^\s+(-+|=+)\s*$/) && !prev_line.empty?
-          errors << linenum - 1
+          errors << (linenum - 1)
         end
         linenum += 1
         prev_line = line
@@ -390,7 +433,7 @@ rule 'MD025', 'Multiple top level headers in the same document' do
       h[:level] == params[:level]
     end
     if !headers.empty? && (doc.element_linenumber(headers[0]) == 1)
-      headers[1..-1].map { |h| doc.element_linenumber(h) }
+      headers[1..].map { |h| doc.element_linenumber(h) }
     end
   end
 end
@@ -415,7 +458,10 @@ rule 'MD027', 'Multiple spaces after blockquote symbol' do
     errors = []
     doc.find_type_elements(:blockquote).each do |e|
       linenum = doc.element_linenumber(e)
-      lines = doc.extract_text(e, /^\s*> /)
+      lines = doc.extract_as_text(e)
+      # Handle first line specially as whitespace is stripped from the text
+      # element
+      errors << linenum if doc.element_line(e).match(/^\s*>  /)
       lines.each do |line|
         errors << linenum if line.start_with?(' ')
         linenum += 1
@@ -438,7 +484,7 @@ rule 'MD028', 'Blank line inside blockquote' do
           # The current location is the start of the second blockquote, so the
           # line before will be a blank line in between the two, or at least the
           # lowest blank line if there are more than one.
-          errors << e.options[:location] - 1
+          errors << (e.options[:location] - 1)
         end
         check_blockquote(errors, e.children)
       end
@@ -490,8 +536,13 @@ rule 'MD030', 'Spaces after list markers' do
       # the items in it have multiple paragraphs/other block items.
       srule = items.map { |i| i.children.length }.max > 1 ? 'multi' : 'single'
       items.each do |i|
-        actual_spaces = doc.element_line(i).gsub(/^> /, '')
-                           .match(/^\s*\S+(\s+)/)[1].length
+        line = doc.element_line(i)
+        # See #278 - sometimes we think non-printable characters are list
+        # items even if they are not, so this ignore those and prevents
+        # us from crashing
+        next if line.empty?
+
+        actual_spaces = line.gsub(/^> /, '').match(/^\s*\S+(\s+)/)[1].length
         required_spaces = params["#{list_type}_#{srule}".to_sym]
         errors << doc.element_linenumber(i) if required_spaces != actual_spaces
       end
@@ -548,7 +599,7 @@ rule 'MD032', 'Lists should be surrounded by blank lines' do
       unless in_code
         list_marker = line.strip.match(/^([*+\-]|(\d+\.))\s/)
         if list_marker && !in_list && !prev_line.match(/^($|\s)/)
-          errors << linenum + 1
+          errors << (linenum + 1)
         elsif !list_marker && in_list && !line.match(/^($|\s)/)
           errors << linenum
         end
@@ -571,8 +622,14 @@ end
 rule 'MD033', 'Inline HTML' do
   tags :html
   aliases 'no-inline-html'
+  params :allowed_elements => ''
   check do |doc|
     doc.element_linenumbers(doc.find_type(:html_element))
+    allowed = params[:allowed_elements].delete(" \t\r\n").downcase.split(',')
+    errors = doc.find_type_elements(:html_element).reject do |e|
+      allowed.include?(e.value)
+    end
+    doc.element_linenumbers(errors)
   end
 end
 
@@ -648,7 +705,7 @@ rule 'MD038', 'Spaces inside code span elements' do
     # block that happen to be parsed as code spans.
     doc.element_linenumbers(
       doc.find_type_elements(:codespan).select do |i|
-        i.value.match(/(^\s|\s$)/) and !i.value.include?("\n")
+        i.value.match(/(^\s|\s$)/) && !i.value.include?("\n")
       end,
     )
   end
@@ -660,8 +717,8 @@ rule 'MD039', 'Spaces inside link text' do
   check do |doc|
     doc.element_linenumbers(
       doc.find_type_elements(:a).reject { |e| e.children.empty? }.select do |e|
-        e.children.first.type == :text && e.children.last.type == :text and (
-          e.children.first.value.start_with?(' ') or
+        e.children.first.type == :text && e.children.last.type == :text && (
+          e.children.first.value.start_with?(' ') ||
           e.children.last.value.end_with?(' '))
       end,
     )
@@ -675,7 +732,7 @@ rule 'MD040', 'Fenced code blocks should have a language specified' do
     # Kramdown parses code blocks with language settings as code blocks with
     # the class attribute set to language-languagename.
     doc.element_linenumbers(doc.find_type_elements(:codeblock).select do |i|
-                              !i.attr['class'].to_s.start_with?('language-') and
+                              !i.attr['class'].to_s.start_with?('language-') &&
                                 !doc.element_line(i).start_with?('    ')
                             end)
   end
@@ -731,3 +788,103 @@ rule 'MD046', 'Code block style' do
     )
   end
 end
+
+rule 'MD047', 'File should end with a single newline character' do
+  tags :blank_lines
+  aliases 'single-trailing-newline'
+  check do |doc|
+    error_lines = []
+    last_line = doc.lines[-1]
+    error_lines.push(doc.lines.length) unless last_line.nil? || last_line.empty?
+    error_lines
+  end
+end
+
+rule 'MD055', 'Table row doesn\'t begin/end with pipes' do
+  tags :tables
+  aliases 'table-rows-start-and-end-with-pipes'
+  check do |doc|
+    error_lines = []
+    tables = doc.find_type_elements(:table)
+    lines = doc.lines
+
+    tables.each do |table|
+      table_pos = table.options[:location] - 1
+      table_rows = get_table_rows(lines, table_pos)
+
+      table_rows.each_with_index do |line, index|
+        if line.length < 2 || line[0] != '|' || line[-1] != '|'
+          error_lines << (table_pos + index + 1)
+        end
+      end
+    end
+
+    error_lines
+  end
+end
+
+rule 'MD056', 'Table has inconsistent number of columns' do
+  tags :tables
+  aliases 'inconsistent-columns-in-table'
+  check do |doc|
+    error_lines = []
+    tables = doc.find_type_elements(:table)
+    lines = doc.lines
+
+    tables.each do |table|
+      table_pos = table.options[:location] - 1
+      table_rows = get_table_rows(lines, table_pos)
+
+      num_headings = number_of_columns_in_a_table_row(lines[table_pos])
+
+      table_rows.each_with_index do |line, index|
+        if number_of_columns_in_a_table_row(line) != num_headings
+          error_lines << (table_pos + index + 1)
+        end
+      end
+    end
+
+    error_lines
+  end
+end
+
+rule 'MD057', 'Table has missing or invalid header separation (second row)' do
+  tags :tables
+  aliases 'table-invalid-second-row'
+  check do |doc|
+    error_lines = []
+    tables = doc.find_type_elements(:table)
+    lines = doc.lines
+
+    tables.each do |table|
+      second_row = ''
+
+      # line number of table start (1-indexed)
+      # which is equal to second row's index (0-indexed)
+      line_num = table.options[:location]
+      second_row = lines[line_num] if line_num < lines.length
+
+      # This pattern matches if
+      #   1) The row starts and stops with | characters
+      #   2) Only consists of characters '|', '-', ':' and whitespace
+      #   3) Each section between the separators (i.e. '|')
+      #      a) has at least three consecutive dashes
+      #      b) can have whitespace at the beginning or the end
+      #      c) can have colon before and/or after dashes (for alignment)
+      #   Some examples:
+      #       |-----|----|-------|      --> matches
+      #       |:---:|:---|-------|      --> matches
+      #       |  :------:  | ----|      --> matches
+      #       | - - - | - - - |         --> does NOT match
+      #       |::---|                   --> does NOT match
+      #       |----:|:--|----|          --> does NOT match
+      pattern = /^(\|\s*:?-{3,}:?\s*)+\|$/
+      unless second_row.match(pattern)
+        # Second row is not in the form described by the pattern
+        error_lines << (line_num + 1)
+      end
+    end
+
+    error_lines
+  end
+end

data/lib/mdl/ruleset.rb

@@ -3,9 +3,11 @@ module MarkdownLint
   class Rule
     attr_accessor :id, :description
 
-    def initialize(id, description, block)
+    def initialize(id, description, fallback_docs: nil, &block)
       @id = id
       @description = description
+      @generate_docs = fallback_docs
+      @docs_overridden = false
       @aliases = []
       @tags = []
       @params = {}
@@ -31,6 +33,82 @@ module MarkdownLint
       @params.update(params) unless params.nil?
       @params
     end
+
+    def docs(url = nil, &block)
+      if block_given? != url.nil?
+        raise ArgumentError, 'Give either a URL or a block, not both'
+      end
+
+      raise 'A docs url is already set within this rule' if @docs_overridden
+
+      @generate_docs = block_given? ? block : lambda { |_, _| url }
+      @docs_overridden = true
+    end
+
+    def docs_url
+      @generate_docs&.call(id, description)
+    end
+
+    # This method calculates the number of columns in a table row
+    #
+    # @param [String] table_row A row of the table in question.
+    # @return [Numeric] Number of columns in the row
+    def number_of_columns_in_a_table_row(table_row)
+      columns = table_row.strip.split('|')
+
+      if columns.empty?
+        # The stripped line consists of zero or more pipe characters
+        # and nothing more.
+        #
+        # Examples of stripped rows:
+        #   '||' --> one column
+        #   '|||' --> two columns
+        #   '|' --> zero columns
+        [0, table_row.count('|') - 1].max
+      else
+        # Number of columns is the number of splited
+        # segments with pipe separator. The first segment
+        # is ignored when it's empty string because
+        # someting like '|1|2|' is split into ['', '1', '2']
+        # when using split('|') function.
+        #
+        # Some examples:
+        #   '|foo|bar|' --> two columns
+        #   '  |foo|bar|' --> two columns
+        #   '|foo|bar' --> two columns
+        #   'foo|bar' --> two columns
+        columns.size - (columns[0].empty? ? 1 : 0)
+      end
+    end
+
+    # This method returns all the rows of a table
+    #
+    # @param [Array<String>] lines Lines of a doc as an array
+    # @param [Numeric] pos Position/index of the table in the array
+    # @return [Array<String>] Rows of the table in an array
+    def get_table_rows(lines, pos)
+      table_rows = []
+      while pos < lines.length
+        line = lines[pos]
+
+        # If the previous line is a table and the current line
+        #   1) includes pipe character
+        #   2) does not start with code block identifiers
+        #     a) >= 4 spaces
+        #     b) < 4 spaces and ``` right after
+        #
+        # it is possibly a table row
+        unless line.include?('|') && !line.start_with?('    ') &&
+               !line.strip.start_with?('```')
+          break
+        end
+
+        table_rows << line
+        pos += 1
+      end
+
+      table_rows
+    end
   end
 
   # defines a ruleset
@@ -42,7 +120,8 @@ module MarkdownLint
     end
 
     def rule(id, description, &block)
-      @rules[id] = Rule.new(id, description, block)
+      @rules[id] =
+        Rule.new(id, description, :fallback_docs => @fallback_docs, &block)
     end
 
     def load(rules_file)
@@ -50,6 +129,14 @@ module MarkdownLint
       @rules
     end
 
+    def docs(url = nil, &block)
+      if block_given? != url.nil?
+        raise ArgumentError, 'Give either a URL or a block, not both'
+      end
+
+      @fallback_docs = block_given? ? block : lambda { |_, _| url }
+    end
+
     def load_default
       load(File.expand_path('rules.rb', __dir__))
     end

data/lib/mdl/style.rb

@@ -58,7 +58,7 @@ module MarkdownLint
           warn "#{style_file} does not appear to be a built-in style." +
                ' If you meant to pass in your own style file, it must contain' +
                " a '/' or end in '.rb'. See https://github.com/markdownlint/" +
-               'markdownlint/blob/master/docs/configuration.md'
+               'markdownlint/blob/main/docs/configuration.md'
           exit(1)
         end
         style_file = tmp

data/lib/mdl/styles/cirosantilli.rb

@@ -9,3 +9,7 @@ rule 'MD035', :style => '---'
 # Inline HTML - this isn't forbidden by the style guide, and raw HTML use is
 # explicitly mentioned in the 'email automatic links' section.
 exclude_rule 'MD033'
+
+# File should end with a single newline character
+# this isn't forbidden by the style guide
+exclude_rule 'MD047'

data/lib/mdl/styles/relaxed.rb

@@ -8,3 +8,4 @@ exclude_rule 'MD033' # Inline HTML
 exclude_rule 'MD034' # Bare URL used
 exclude_rule 'MD040' # Fenced code blocks should have a language specified
 exclude_rule 'MD041' # First line in file should be a top level header
+exclude_rule 'MD047' # File should end with a single newline character

data/lib/mdl/version.rb

@@ -1,3 +1,3 @@
 module MarkdownLint
-  VERSION = '0.11.0'.freeze
+  VERSION = '0.13.0'.freeze
 end

data/lib/mdl.rb

@@ -1,3 +1,4 @@
+require_relative 'mdl/formatters/sarif'
 require_relative 'mdl/cli'
 require_relative 'mdl/config'
 require_relative 'mdl/doc'
@@ -66,7 +67,8 @@ module MarkdownLint
           Dir.chdir(filename) do
             cli.cli_arguments[i] =
               Mixlib::ShellOut.new("git ls-files '*.md' '*.markdown'")
-                              .run_command.stdout.lines.map(&:strip)
+                              .run_command.stdout.lines
+                              .map { |m| File.join(filename, m.strip) }
           end
         else
           cli.cli_arguments[i] = Dir["#{filename}/**/*.{md,markdown}"]
@@ -77,8 +79,15 @@ module MarkdownLint
 
     status = 0
     results = []
+    docs_to_print = []
     cli.cli_arguments.each do |filename|
       puts "Checking #{filename}..." if Config[:verbose]
+      unless filename == '-' || File.exist?(filename)
+        warn(
+          "#{Errno::ENOENT}: No such file or directory - #{filename}",
+        )
+        exit 3
+      end
       doc = Doc.new_from_file(filename, Config[:ignore_front_matter])
       filename = '(stdin)' if filename == '-'
       if Config[:show_kramdown_warnings]
@@ -95,31 +104,57 @@ module MarkdownLint
         status = 1
         error_lines.each do |line|
           line += doc.offset # Correct line numbers for any yaml front matter
-          if Config[:json]
+          if Config[:json] || Config[:sarif]
             results << {
               'filename' => filename,
               'line' => line,
               'rule' => id,
               'aliases' => rule.aliases,
               'description' => rule.description,
+              'docs' => rule.docs_url,
             }
-          elsif Config[:show_aliases]
-            puts "#{filename}:#{line}: #{rule.aliases.first || id} " +
-                 rule.description.to_s
           else
-            puts "#{filename}:#{line}: #{id} #{rule.description}"
+            linked_id = linkify(printable_id(rule), rule.docs_url)
+            puts "#{filename}:#{line}: #{linked_id} " + rule.description.to_s
           end
         end
+
+        # If we're not in JSON or SARIF mode (URLs are in the object), and we
+        # cannot make real links (checking if we have a TTY is an OK heuristic
+        # for that) then, instead of making the output ugly with long URLs, we
+        # print them at the end. And of course we only want to print each URL
+        # once.
+        if !Config[:json] && !Config[:sarif] &&
+           !$stdout.tty? && !docs_to_print.include?(rule)
+          docs_to_print << rule
+        end
       end
     end
 
     if Config[:json]
       require 'json'
       puts JSON.generate(results)
-    elsif status != 0
-      puts "\nA detailed description of the rules is available at " +
-           'https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md'
+    elsif Config[:sarif]
+      puts SarifFormatter.generate(rules, results)
+    elsif docs_to_print.any?
+      puts "\nFurther documentation is available for these failures:"
+      docs_to_print.each do |rule|
+        puts " - #{printable_id(rule)}: #{rule.docs_url}"
+      end
     end
     exit status
   end
+
+  def self.printable_id(rule)
+    return rule.aliases.first if Config[:show_aliases] && rule.aliases.any?
+
+    rule.id
+  end
+
+  # Creates hyperlinks in terminal emulators, if available: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+  def self.linkify(text, url)
+    return text unless $stdout.tty? && url
+
+    "\e]8;;#{url}\e\\#{text}\e]8;;\e\\"
+  end
 end

data/mdl.gemspec

@@ -9,8 +9,9 @@ Gem::Specification.new do |spec|
   spec.email = ['mark@mivok.net']
   spec.summary = 'Markdown lint tool'
   spec.description = 'Style checker/lint tool for markdown files'
-  spec.homepage = 'http://github.com/markdownlint/markdownlint'
+  spec.homepage = 'https://github.com/markdownlint/markdownlint'
   spec.license = 'MIT'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = %w{LICENSE.txt Gemfile} + Dir.glob('*.gemspec') +
                Dir.glob('lib/**/*')
@@ -18,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.executables = %w{mdl}
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.4'
+  spec.required_ruby_version = '>= 2.7'
 
   spec.add_dependency 'kramdown', '~> 2.3'
   spec.add_dependency 'kramdown-parser-gfm', '~> 1.1'
@@ -30,5 +31,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'minitest', '~> 5.9'
   spec.add_development_dependency 'pry', '~> 0.10'
   spec.add_development_dependency 'rake', '>= 11.2', '< 14'
-  spec.add_development_dependency 'rubocop', '>= 0.49.0'
+  spec.add_development_dependency 'rubocop', '~> 1.28.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mdl
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Mark Harrison
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-23 00:00:00.000000000 Z
+date: 2023-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown
@@ -164,16 +164,16 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.49.0
+        version: 1.28.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.49.0
+        version: 1.28.1
 description: Style checker/lint tool for markdown files
 email:
 - mark@mivok.net
@@ -189,6 +189,7 @@ files:
 - lib/mdl/cli.rb
 - lib/mdl/config.rb
 - lib/mdl/doc.rb
+- lib/mdl/formatters/sarif.rb
 - lib/mdl/kramdown_parser.rb
 - lib/mdl/rules.rb
 - lib/mdl/ruleset.rb
@@ -199,11 +200,12 @@ files:
 - lib/mdl/styles/relaxed.rb
 - lib/mdl/version.rb
 - mdl.gemspec
-homepage: http://github.com/markdownlint/markdownlint
+homepage: https://github.com/markdownlint/markdownlint
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -211,15 +213,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.3.15
+signing_key:
 specification_version: 4
 summary: Markdown lint tool
 test_files: []