Additional updates for OPS release (#664)

Fix issue with module parsing when schema was not present.
Fix up tests for same and add exchange module file (for tests against multiple command groups.
Refactor a number of files.
Change metadata dictionary to be <string,object> rather than <string,string>.
Add handling of HelpUri and HelpInfoUri to new-markdowncommandhelp (transform settings does not preserve these).
Update metadata serializer to handle arrays in flow format.
Add a reasonable implementation of ToString for DiagnosticMessages to improve formatting.
Be sure to include aliases in commandhelp.
Add support for metadata as a paragraph in addition to normal handling.
Add a number of diagnostic messages throughout.
Change alias boilerplate to appear only if the ALIAS header was missing. This means that the first conversion from V1 -> V2 will include boilerplate, but V2 -> V2 will not.
Don't add empty lines for the description of ModuleCommands, only if description is present.
Add a number of format entries for DiagnosticMessage, Iditify, Diagnostics (now a custom format).
Add Update-MarkdownModuleFile, Measure-PlatyPSMarkdown (identify what kind of markdown we have).
* Add metadata during import of MAML file.
* Change parameter name to from OutputDirectory to OutputFolder for Export-MamlCommandHelp.
Be sure to save command help notes as AlertSet.
Be sure to create metadata when importing MAML file.
* fix issue in Measure-PlatyPSMarkdown.
It was not identifying a V2 module file. Add a test for same.
* Set diagnostics and ParameterNames as skipped property names for Compare-CommandHelp.
* updates to helpinfouri and helpuri. Be sure that they go in the right file.
* use CurrentCulture rather than CurrentUICulture
* Be sure to default metadata Locale to en-US.
* Skip implicit loading of module in Windows PowerShell.
* When testing, be sure to execute the right powershell.
* Fixes to build script to ensure testing on Windows PowerShell.
* Rewrite of tests to support running on Windows PowerShell.

Author: JamesWTruher

.vscode/settings.json

@@ -3,5 +3,6 @@
      "files.exclude": {
         "out/**": true
     },
-    "dotnet.defaultSolution": "platyPS.sln"
+    "dotnet.defaultSolution": "platyPS.sln",
+    "sarif-viewer.connectToGithubCodeScanning": "off"
 }

build.ps1

@@ -71,7 +71,13 @@ if ($PSCmdlet.ParameterSetName -eq 'Build') {
             $moduleFiles += $expectedPdbPath
         }
 
-        Copy-Item -Path "$expectedBuildPath/Markdig.Signed.dll", "$expectedBuildPath/YamlDotNet.dll" -Destination $depsFolder -Verbose
+        $neededAssemblies = "System.Buffers.dll", "System.Memory.dll",
+            "System.Numerics.Vectors.dll", "System.Runtime.CompilerServices.Unsafe.dll",
+            "Markdig.Signed.dll","YamlDotNet.dll"
+        
+        $neededAssemblyLocations = $neededAssemblies | ForEach-Object { "${expectedBuildPath}/${_}" }
+
+        Copy-Item -Path $neededAssemblyLocations -Destination $depsFolder -Verbose
         Copy-Item -Path $moduleFiles -Destination $moduleRoot -Verbose
     }
     finally {
@@ -91,7 +97,10 @@ elseif ($PSCmdlet.ParameterSetName -eq 'Test') {
 
     write-verbose -verbose -message "$sb"
 
-    pwsh -noprofile -c "$sb"
+    # we need to run on both pwsh and powershell
+    $PSEXE = (Get-Process -Id $PID).MainModule.FileName
+    Write-Verbose -Verbose -Message ("Running tests on PowerShell Version: " + $PSVersionTable.PSVersion)
+    & $PSEXE -noprofile -c "$sb"
 
     $results = [xml](Get-Content $PesterLogPath)
     if ($results."test-results".failures -ne 0) {
@@ -114,4 +123,4 @@ if ($Package) {
         Unregister-PSRepository -Name $localRepoName -ErrorAction SilentlyContinue
     }
     Get-ChildItem -Path $PSScriptRoot/*.nupkg
-}
+}

src/Command/CompareCommandHelpCommand.cs

@@ -10,6 +10,7 @@
 using System.Management.Automation;
 using Microsoft.PowerShell.PlatyPS.Model;
 using System.Linq;
+using System.Runtime.InteropServices;
 
 namespace Microsoft.PowerShell.PlatyPS
 {
@@ -31,7 +32,7 @@ public class CompareCommandHelpCommand : PSCmdlet
         public CommandHelp? Difference { get; set; }
 
         [Parameter]
-        public string[] PropertyNamesToExclude { get; set; } = new string[0];
+        public string[] PropertyNamesToExclude { get; set; } = new string[] { "Diagnostics", "ParameterNames" };
 
         List<String> DiagnosticMessages = new();
 

src/Command/ExportMamlCommandHelp.cs

@@ -36,7 +36,7 @@ public sealed class ExportMamlCommandHelpCommand : PSCmdlet
         public SwitchParameter Force { get; set; }
 
         [Parameter(Mandatory = true, Position = 1)]
-        public string OutputDirectory { get; set; } = string.Empty;
+        public string OutputFolder { get; set; } = string.Empty;
 
         private List<CommandHelp> _commandHelps = new List<CommandHelp>();
         #endregion
@@ -57,9 +57,9 @@ protected override void ProcessRecord()
 
         protected override void EndProcessing()
         {
-            if (ShouldProcess(OutputDirectory))
+            if (ShouldProcess(OutputFolder))
             {
-                outputDirectory = PathUtils.CreateOrGetOutputDirectory(this, OutputDirectory, Force);
+                outputDirectory = PathUtils.CreateOrGetOutputDirectory(this, OutputFolder, Force);
             }
             else
             {
@@ -69,7 +69,7 @@ protected override void EndProcessing()
 
             if (outputDirectory is null)
             {
-                ThrowTerminatingError(new ErrorRecord(new InvalidOperationException("file is null"), "fileInfo is null", ErrorCategory.InvalidOperation, OutputDirectory));
+                ThrowTerminatingError(new ErrorRecord(new InvalidOperationException("file is null"), "fileInfo is null", ErrorCategory.InvalidOperation, OutputFolder));
                 throw new InvalidOperationException("fileInfo is null"); // not reached
             }
 

src/Command/ExportMarkdownModuleFileCommand.cs

@@ -92,7 +92,7 @@ protected override void ProcessRecord()
                             }
                             else
                             {
-                                moduleFile.Metadata[key] = (string)kv.Value;
+                                moduleFile.Metadata[key] = kv.Value;
                             }
                         }
                     }

src/Command/ExportYamlModuleFileCommand.cs

@@ -3,8 +3,6 @@
 
 using System;
 using System.Collections;
-using System.Collections.ObjectModel;
-using System.Globalization;
 using System.IO;
 using System.Management.Automation;
 using Microsoft.PowerShell.PlatyPS.Model;
@@ -59,7 +57,7 @@ protected override void ProcessRecord()
 
             foreach (ModuleFileInfo moduleFile in ModuleFile)
             {
-                if (moduleFile.Metadata.ContainsKey("Module Name"))
+                if (moduleFile.Metadata.Contains("Module Name"))
                 {
                     moduleName = moduleFile.Metadata["Module Name"].ToString();
                 }

src/Command/Measure-PlatyPSMarkdown.cs

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using System.Management.Automation;
+using Microsoft.PowerShell.PlatyPS.Model;
+
+namespace Microsoft.PowerShell.PlatyPS
+{
+    /// <summary>
+    /// Cmdlet to determine the type of markdown file.
+    /// </summary>
+    [Cmdlet(VerbsDiagnostic.Measure, "PlatyPSMarkdown", DefaultParameterSetName = "Path", HelpUri = "")]
+    [OutputType(typeof(CommandHelp))]
+    public sealed class MeasurePlatyPSMarkdown : PSCmdlet
+    {
+#region cmdlet parameters
+
+        [Parameter(Mandatory=true, Position=0, ValueFromPipeline=true, ParameterSetName= "Path")]
+        [ValidateNotNullOrEmpty]
+        [SupportsWildcards]
+        public string[] Path { get; set; } = Array.Empty<string>();
+
+        [Parameter(Mandatory=true, ValueFromPipeline=true, ParameterSetName= "LiteralPath")]
+        [ValidateNotNullOrEmpty]
+        public string[] LiteralPath { get; set; } = Array.Empty<string>();
+
+#endregion
+
+        protected override void ProcessRecord()
+        {
+            List<string> resolvedPaths;
+            try
+            {
+                // This is a list because the resolution process can result in multiple paths (in the case of non-literal path).
+                resolvedPaths = PathUtils.ResolvePath(this, ParameterSetName == "LiteralPath" ? LiteralPath : Path, ParameterSetName == "LiteralPath" ? true : false);
+            }
+            catch (Exception e)
+            {
+                WriteError(new ErrorRecord(e, "Could not resolve Path", ErrorCategory.InvalidOperation, ParameterSetName == "LiteralPath" ? LiteralPath : Path));
+                return;
+            }
+
+            // These should be resolved paths, whether -LiteralPath was used or not.
+            foreach (string path in resolvedPaths)
+            {
+                try
+                {
+                    var markdownInfo = MarkdownProbe.Identify(path);
+                    WriteObject(markdownInfo);
+                }
+                catch (Exception e)
+                {
+                    WriteError(new ErrorRecord(e, "FailedToImportMarkdown", ErrorCategory.InvalidOperation, path));
+                }
+            }
+        }
+    }
+}

src/Command/NewMarkdownHelpCommand.cs

@@ -10,7 +10,7 @@
 using System.Linq;
 using System.Management.Automation;
 using System.Management.Automation.Runspaces;
-
+using Microsoft.PowerShell.Commands;
 using Microsoft.PowerShell.PlatyPS.MarkdownWriter;
 using Microsoft.PowerShell.PlatyPS.Model;
 
@@ -118,6 +118,10 @@ protected override void EndProcessing()
 
             List<CommandHelp> cmdHelpObjs = new List<CommandHelp>();
             Dictionary<string, PSModuleInfo> moduleTable = new();
+            foreach (var providedModule in Module)
+            {
+                moduleTable[providedModule.Name] = providedModule;
+            }
 
             if (cmdCollection.Count > 0)
             {
@@ -126,7 +130,6 @@ protected override void EndProcessing()
                 {
                     if (cmd.Module is not null && ! string.IsNullOrEmpty(cmd.Module.Name) && ! moduleTable.ContainsKey(cmd.Module.Name))
                     {
-                        moduleTable[cmd.Module.Name] = cmd.Module;
                         if (HelpInfoUri == string.Empty && ! string.IsNullOrEmpty(cmd.Module.HelpInfoUri))
                         {
                             HelpInfoUri = cmd.Module.HelpInfoUri;
@@ -141,7 +144,7 @@ protected override void EndProcessing()
                         ExcludeDontShow = false,
                         FwLink = HelpInfoUri,
                         HelpVersion = HelpVersion.ToString(),
-                        Locale = Locale is null ? CultureInfo.CurrentUICulture : new CultureInfo(Locale),
+                        Locale = Locale is null ? CultureInfo.CurrentCulture : new CultureInfo(Locale),
                         ModuleName = cmd.ModuleName is null ? string.Empty : cmd.ModuleName,
                         ModuleGuid = cmd.Module?.Guid is null ? Guid.Empty : cmd.Module.Guid,
                         OnlineVersionUrl = HelpUri,
@@ -154,7 +157,25 @@ protected override void EndProcessing()
                         var pr = new ProgressRecord(0, "Transforming cmdlet", $"{cmd.ModuleName}\\{cmd.Name}");
                         pr.PercentComplete = (int)Math.Round(((double)currentOffset++ / (double)(cmdCollection.Count)) * 100);
                         WriteProgress(pr);
-                        cmdHelpObjs.Add(new TransformCommand(transformSettings).Transform(cmd));
+                        var transformedCommand = new TransformCommand(transformSettings).Transform(cmd);
+
+                        if (transformedCommand is null)
+                        {
+                            throw new InvalidDataException("Command transformation failed");
+                        }
+
+                        if (transformedCommand.Metadata is null)
+                        {
+                            transformedCommand.Metadata = new();
+                        }
+
+                        // update the HelpUri if the parameter was used.
+                        if (! string.IsNullOrEmpty(HelpUri))
+                        {
+                            transformedCommand.Metadata["HelpUri"] = HelpUri;
+                        }
+
+                        cmdHelpObjs.Add(transformedCommand);
                     }
                     catch (Exception e)
                     {
@@ -199,6 +220,11 @@ protected override void EndProcessing()
                     }
                 }
 
+                if (! string.IsNullOrEmpty(HelpInfoUri))
+                {
+                    moduleFileInfo.Metadata["HelpInfoUri"] = HelpInfoUri;
+                }
+
                 List<ModuleCommandInfo> mciList = new();
                 foreach(var cmdHelp in group)
                 {