mdl 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e82acf8008929f43d28c4be6a794f538d3745d1dd5acf37487ab061d0f968843
-  data.tar.gz: c4f5b4b055ceb67dd29a0b292fe4c9ecf974ae3724a7db9c359196dafe60efe0
+  metadata.gz: 240bbb771676be213b572426ae6aa48dd810cb11769263a30ee1e2b98b6751d5
+  data.tar.gz: 0c474a99242d291a202b958294ba749977230b43b24a38342a00bc6675857d6b
 SHA512:
-  metadata.gz: 6ed1202471b0bf2df640e0eaaacbfaf23593b3841ebc232ee630d15d4ae7817aedd6b455451612f0f4239762e0ddd6fe7acfa4efd9c61b72b14db87ab7dcce4a
-  data.tar.gz: 3a8b7a23579bc6345fdec2d79442b238c6e32e2836602827ed626d105f9495b2ad000ac799d130ebe97815dca67f29b4e5ba6c21c8f816c1cf60bca0cf4c501a
+  metadata.gz: 538a08a57be028038bc8e1fe72c241e81e57261b84a0b58efb6875b515c8b0dfb01715826959778c6d88a9c6bb2b799b668a1662ac09e1a9d1c8a8a67817addd
+  data.tar.gz: 3104fb8e6bd66686b6268a5a5cb31f4bbdcef9fa7f7190f31b60a99c5acc489c47f19998c5bf40f9eff064c0f71cbeb73a8cb164a04899bb57666d041e85c125

data/lib/mdl/cli.rb

@@ -145,10 +145,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

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/master/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'
@@ -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
@@ -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|
@@ -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
@@ -438,7 +481,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 +533,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 +596,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
@@ -648,7 +696,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 +708,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 +723,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 +779,14 @@ 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

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,21 @@ 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
   end
 
   # defines a ruleset
@@ -42,7 +59,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 +68,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/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.12.0'.freeze
 end

data/lib/mdl.rb

@@ -66,7 +66,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 +78,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]
@@ -102,24 +110,47 @@ module MarkdownLint
               '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 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] && !$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 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

@@ -11,6 +11,7 @@ Gem::Specification.new do |spec|
   spec.description = 'Style checker/lint tool for markdown files'
   spec.homepage = 'http://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.12.0
 platform: ruby
 authors:
 - Mark Harrison
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-23 00:00:00.000000000 Z
+date: 2022-10-18 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
@@ -202,8 +202,9 @@ files:
 homepage: http://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 +212,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.7
+signing_key:
 specification_version: 4
 summary: Markdown lint tool
 test_files: []