Restore markdownlint tests (#12549)

Co-authored-by: Travis Plunk <travis.plunk@microsoft.com>

test/common/markdown/gulpfile.js

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+function runTest() {
+    "use strict";
+    var gulp = require("gulp");
+    var concat = require("gulp-concat");
+    var through2 = require("through2");
+    var markdownlint = require("markdownlint");
+
+    gulp.task("test-mdsyntax", function task() {
+        var paths = [];
+        var rootpath;
+
+        // assign --repoRoot <rootpath> into rootpath
+        var j = process.argv.indexOf("--rootpath");
+        if (j > -1) {
+            rootpath = process.argv[j + 1];
+        }
+
+        if (rootpath === null) {
+            throw "--rootpath <repoRoot> must be specified before all other parameters";
+        }
+
+        // parse --filter into paths.  --rootpath must be specified first.
+        j = process.argv.indexOf("--filter");
+        if (j > -1) {
+            var filters = process.argv[j + 1].split(",");
+            filters.forEach(function(filter) {
+                paths.push(rootpath + "/" + filter);
+            }, this);
+        }
+
+        if (paths.length === 0) {
+            throw "--filter <filter relative to repoRoot> must be specified";
+        }
+
+        var rootJsonFile = rootpath + "/.markdownlint.json";
+        var fs = require("fs");
+        fs.appendFileSync("markdownissues.txt", "--EMPTY--\r\n");
+        return gulp.src(paths, { "read": false })
+            .pipe(through2.obj(function obj(file, enc, next) {
+                markdownlint({
+                        "files": [file.path],
+                        "config": require(rootJsonFile)
+                    },
+                    function callback(err, result) {
+                        var resultString = (result || "").toString();
+                        if (resultString) {
+                            file.contents = Buffer.from(resultString);
+                        }
+                        next(err, file);
+                    });
+            }))
+            .pipe(concat("markdownissues.txt", { newLine: "\r\n" }))
+            .pipe(gulp.dest("."));
+    });
+}
+
+runTest();

test/common/markdown/markdown-link.tests.ps1

@@ -105,7 +105,7 @@ Describe "Verify Markdown Links" {
                         $prefix = $url.Substring(0,7)
 
                         # Logging for diagnosability.  Azure DevOps sometimes redacts the full url.
-                        Write-Verbose "prefix: '$prefix'" -Verbose
+                        Write-Verbose "prefix: '$prefix'"
                         if($url -match '^http(s)?:')
                         {
                             # If invoke-WebRequest can handle the URL, re-verify, with 6 retries

test/common/markdown/markdown.tests.ps1

@@ -0,0 +1,100 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+Import-Module HelpersCommon
+$moduleRootFilePath = Split-Path -Path $PSScriptRoot -Parent
+
+# Identify the repository root path of the resource module
+$repoRootPath = (Resolve-Path -LiteralPath (Join-Path $moduleRootFilePath "../..")).ProviderPath
+$repoRootPathFound = $false
+
+Describe 'Common Tests - Validate Markdown Files' -Tag 'CI' {
+    BeforeAll {
+        Push-Location $psscriptroot
+        $skip = $false
+        $NpmInstalled = "not installed"
+        if (Get-Command -Name 'yarn' -ErrorAction SilentlyContinue)
+        {
+            $NpmInstalled = "Installed"
+            Write-Verbose -Message "Checking if Gulp is installed. This may take a few moments." -Verbose
+            start-nativeExecution { yarn }
+            if(!(Get-Command -Name 'gulp' -ErrorAction SilentlyContinue))
+            {
+                start-nativeExecution {
+                    sudo yarn global add 'gulp@4.0.2'
+                }
+            }
+            if(!(Get-Command -Name 'node' -ErrorAction SilentlyContinue))
+            {
+                throw "node not found"
+            }
+        }
+        if(!(Get-Command -Name 'node' -ErrorAction SilentlyContinue))
+        {
+            <#
+                On Windows, pre-requisites are missing
+                For now we will skip, and write a warning.  Work to resolve this is tracked in:
+                https://github.com/PowerShell/PowerShell/issues/3429
+            #>
+            Write-Warning "Node and yarn are required to run this test"
+            $skip = $true
+        }
+
+        $mdIssuesPath = Join-Path -Path $PSScriptRoot -ChildPath "markdownissues.txt"
+        Remove-Item -Path $mdIssuesPath -Force -ErrorAction SilentlyContinue
+    }
+
+    AfterAll {
+        Pop-Location
+    }
+
+    It "Should not have errors in any markdown files" -Skip:$skip {
+        $NpmInstalled | Should -BeExactly "Installed"
+        $mdErrors = 0
+        Push-Location -Path $PSScriptRoot
+        try
+        {
+            $docsToTest = @(
+                './.github/*.md'
+                './README.md'
+                './demos/python/*.md'
+                './docker/*.md'
+                './docs/building/*.md'
+                './docs/community/*.md'
+                './docs/host-powershell/*.md'
+                './docs/cmdlet-example/*.md'
+                './docs/maintainers/*.md'
+                './test/powershell/README.md'
+                './tools/*.md'
+                './.github/ISSUE_TEMPLATE/*.md'
+            )
+            $filter = ($docsToTest -join ',')
+
+            # Gulp 4 beta is returning non-zero exit code even when there is not an error
+            Start-NativeExecution {
+                    &"gulp" test-mdsyntax --silent `
+                        --rootpath $repoRootPath `
+                        --filter $filter
+                } -VerboseOutputOnError -IgnoreExitcode
+
+        }
+        finally
+        {
+            Pop-Location
+        }
+
+        $mdIssuesPath | Should -Exist
+
+        [string[]] $markdownErrors = Get-Content -Path $mdIssuesPath
+        Remove-Item -Path $mdIssuesPath -Force -ErrorAction SilentlyContinue
+
+        if ($markdownErrors -ne "--EMPTY--")
+        {
+            $markdownErrors += ' (See https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md for an explanation of the error codes)'
+        }
+
+        $markdownErrors | Write-Host
+
+        $markdownErrors -join "`n" | Should -BeExactly "--EMPTY--"
+    }
+}

test/common/markdown/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "powershell.common.markdown.tests",
+    "private": true,
+    "version": "1.0.0",
+    "description": "The PowerShell Common Markdown Tests.",
+    "main": "gulpfile.js",
+    "dependencies": {
+        "gulp": "^4.0.2",
+        "markdownlint": "^0.20.2",
+        "through2": "^3.0.1"
+    },
+    "devDependencies": {
+        "gulp-concat": "^2.6.1",
+        "gulp-debug": "^4.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/PowerShell/PowerShell.git"
+    },
+    "author": "Microsoft Corporation",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/PowerShell/PowerShell/issues"
+    },
+    "homepage": "https://github.com/PowerShell/PowerShell#readme"
+}