From 37498554687771cebbc7538abe33bc269b210c02 Mon Sep 17 00:00:00 2001
From: Glenn Sarti <glennsarti@users.noreply.github.com>
Date: Wed, 19 Feb 2020 09:26:58 +0800
Subject: [PATCH] (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.
---
 Gemfile                                   |  1 +
 spec/spec_helper.rb                       | 42 +++++++++++++++++++++++
 spec/unit/puppet-strings/markdown_spec.rb | 17 +++++++++
 3 files changed, 60 insertions(+)

diff --git a/Gemfile b/Gemfile
index 435b9e997..565a0edfb 100644
--- a/Gemfile
+++ b/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
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb
index 56a151d34..ce06a04a0 100644
--- a/spec/spec_helper.rb
+++ b/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
diff --git a/spec/unit/puppet-strings/markdown_spec.rb b/spec/unit/puppet-strings/markdown_spec.rb
index 04f16db1b..1abe3410e 100644
--- a/spec/unit/puppet-strings/markdown_spec.rb
+++ b/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