(maint) Add markdown lint checking to markdown tests

Previously the markdown generated by Puppet-Strings may contain errors which
markdown lint programs would flag.  This commit adds the ability to run markdown
lint on a per test basis and adds pending tests to show that the markdown output
does indeed need some work.

Note that this commit does not fix the errors.  That will come in later commits.

Author: glennsarti

Gemfile

@@ -20,6 +20,7 @@ group :test do
   gem 'simplecov-console'
   gem 'rspec', '~> 3.1'
   gem 'json_spec', '~> 1.1', '>= 1.1.5'
+  gem 'mdl', '~> 0.8.0' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.4.0')
 end
 
 group :acceptance do

spec/spec_helper.rb

@@ -47,3 +47,45 @@
     YARD::Registry.clear
   end
 end
+
+def mdl_available
+  @mdl_available ||= !Gem::Specification.select { |item| item.name.casecmp('mdl').zero? }.empty?
+end
+
+def lint_markdown(content)
+  return [] unless mdl_available
+  require 'mdl'
+
+  ruleset = MarkdownLint::RuleSet.new
+  ruleset.load_default
+
+  # All rules
+  style = MarkdownLint::Style.load('all', ruleset.rules)
+
+  # Create a document
+  doc = MarkdownLint::Doc.new(content, false)
+
+  # Run the rules
+  violations = []
+  ruleset.rules.each do |id, rule|
+    error_lines = rule.check.call(doc)
+    next if error_lines.nil? or error_lines.empty?
+    # record the error
+    error_lines.each do |line|
+      line += doc.offset # Correct line numbers for any yaml front matter
+      violations << "#{filename}:#{line}: #{id} #{rule.description}"
+    end
+  end
+  violations
+end
+
+RSpec::Matchers.define :have_no_markdown_lint_errors do
+  match do |actual|
+    @violations = lint_markdown(actual)
+    @violations.empty?
+  end
+
+  failure_message do |actual|
+    "expected that #{actual.length > 80 ? actual.slice(0,80).inspect + '...' : actual.inspect} would have no markdown lint errors but got #{@violations.join("\n")}"
+  end
+end

spec/unit/puppet-strings/markdown_spec.rb

@@ -325,6 +325,17 @@ def parse_data_type_content
   let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/markdown/#{filename}") }
   let(:baseline) { File.read(baseline_path) }
 
+  RSpec.shared_examples 'markdown lint checker' do |parameter|
+    it 'should not generate markdown lint errors from the rendered markdown', if: mdl_available do
+      pending('Failures are expected')
+      Tempfile.open('md') do |file|
+        PuppetStrings::Markdown.render(file.path)
+
+        expect(File.read(file.path)).to have_no_markdown_lint_errors
+      end
+    end
+  end
+
   describe 'rendering markdown to a file' do
     before(:each) do
       parse_shared_content
@@ -339,6 +350,8 @@ def parse_data_type_content
           expect(File.read(file.path)).to eq(baseline)
         end
       end
+
+      include_examples 'markdown lint checker'
     end
 
     describe 'with Puppet Plans', :if => TEST_PUPPET_PLANS do
@@ -354,6 +367,8 @@ def parse_data_type_content
           expect(File.read(file.path)).to eq(baseline)
         end
       end
+
+      include_examples 'markdown lint checker'
     end
 
     describe 'with Puppet Data Types', :if => TEST_PUPPET_DATATYPES do
@@ -369,6 +384,8 @@ def parse_data_type_content
           expect(File.read(file.path)).to eq(baseline)
         end
       end
+
+      include_examples 'markdown lint checker'
     end
   end
 end