Fix issues scanning for aliases in markdown. (#690)

Aliases are not a list, but unparsed markdown.
Add some improved diagnostics for parsing yaml (more to do here)
Improve diagnostics for alias scanning in markdown.
Fix an issue in SyntaxItem parameter sorting to handle cases where a position may not be know (such as command help as generated by MAML).
Change yaml serialization for aliases to use yaml serializer.
Add copyright to exportyamlmodulefile tests.
Add a new get-childitem v2 help file for testing aliases.

Author: JamesWTruher

src/Command/Update-CommandHelp.cs

@@ -113,7 +113,13 @@ CommandHelp Merge(CommandHelp fromMarkdown, CommandHelp fromCmdlet)
             syntaxDiagnostics.ForEach(d => helpCopy.Diagnostics.TryAddDiagnostic(d));
 
             // Alias - there are no aliases to be found in the cmdlet, but we shouldn't add the boiler plate.
+            // If the boiler plate is found, we'll clear the aliases.
             helpCopy.AliasHeaderFound = true;
+            if (helpCopy.Aliases.Any(s => s.IndexOf(Constants.AliasMessage2, StringComparison.OrdinalIgnoreCase) >= 0))
+            {
+                helpCopy.Aliases?.Clear();
+            }
+
 
             // Parameters
             if (TryGetMergedParameters(helpCopy.Parameters, fromCmdlet.Parameters, out var mergedParametersList, out var paramDiagnostics))

src/Common/YamlUtils.cs

@@ -185,33 +185,55 @@ internal static CommandHelp ConvertDictionaryToCommandHelp(OrderedDictionary? di
             if (dictionary["metadata"] is IDictionary<object, object> metadata)
             {
                 help.Metadata = GetMetadataFromDictionary(metadata);
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.General, "Found Metadata", DiagnosticSeverity.Information, "yaml metadata", -1);
             }
 
             if (dictionary["synopsis"] is string synopsis)
             {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.Synopsis, $"Synopsis length: {synopsis.Length} ", DiagnosticSeverity.Information, "yaml synopsis", -1);
                 help.Synopsis = synopsis;
             }
+            else
+            {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.Synopsis, "No synopsis", DiagnosticSeverity.Warning, "yaml synopsis", -1);
+            }
 
             if (dictionary["title"] is string title)
             {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.General, $"Title length: {title.Length} ", DiagnosticSeverity.Information, "yaml title", -1);
                 help.Title = title;
             }
+            else
+            {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.General, "No title", DiagnosticSeverity.Warning, "yaml title", -1);
+            }
 
             if (dictionary["description"] is string description)
             {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.Description, $"Description length: {description.Length} ", DiagnosticSeverity.Information, "yaml description", -1);
                 help.Description = description;
             }
+            else
+            {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.Description, "No description", DiagnosticSeverity.Warning, "yaml description", -1);
+            }
 
             if (dictionary["notes"] is string notes)
             {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.Notes, $"notes length: {notes.Length} ", DiagnosticSeverity.Information, "yaml notes", -1);
                 help.Notes = notes;
             }
             else
             {
+                help.Diagnostics.TryAddDiagnostic(DiagnosticMessageSource.Notes, "No description", DiagnosticSeverity.Information, "yaml notes", -1);
                 help.Notes = string.Empty;
             }
 
             help.Syntax.AddRange(GetSyntaxFromDictionary(dictionary));
+            if (help.Aliases is not null)
+            {
+                help.Aliases.AddRange(GetAliasesFromDictionary(dictionary));
+            }
             help.Examples?.AddRange(GetExamplesFromDictionary(dictionary));
             help.Parameters.AddRange(GetParametersFromDictionary(dictionary));
             help.Inputs.AddRange(GetInputsFromDictionary(dictionary));
@@ -225,9 +247,6 @@ internal static CommandHelp ConvertDictionaryToCommandHelp(OrderedDictionary? di
             if (help.Metadata is not null)
             {
                 help.ModuleGuid = help.Metadata.Contains("ModuleGuid") ? new Guid(help.Metadata["ModuleGuid"].ToString()) : null;
-                // help.ExternalHelpFile = help.Metadata.Contains("external help file") ? help.Metadata["external help file"].ToString() : string.Empty;
-                // help.OnlineVersionUrl = help.Metadata.Contains("HelpUri") ? help.Metadata["HelpUri"].ToString() : string.Empty;
-                // help.SchemaVersion = help.Metadata.Contains("PlatyPS schema version") ? help.Metadata["PlatyPS schema version"].ToString() : string.Empty;
                 help.ModuleName = help.Metadata.Contains("Module Name") ? help.Metadata["Module Name"].ToString() : string.Empty;
             }
 
@@ -559,6 +578,19 @@ private static List<Links> GetRelatedLinksFromDictionary(OrderedDictionary dicti
             return links;
         }
 
+        private static List<string> GetAliasesFromDictionary(OrderedDictionary dictionary)
+        {
+            List<string> aliases = new();
+            if (dictionary["aliases"] is List<object> aliasList)
+            {
+                foreach(var alias in aliasList)
+                {
+                    aliases.Add(alias.ToString());
+                }
+            }
+            return aliases;
+        }
+
         private static List<Example> GetExamplesFromDictionary(OrderedDictionary dictionary)
         {
             List<Example> examples = new();

src/MarkdownReader/CommandHelpMarkdownReader.cs

@@ -746,8 +746,14 @@ internal static List<string> GetAliasesFromMarkdown(ParsedMarkdownContent markdo
                 return new List<string>();
             }
 
-            var aliasList = GetAliases(markdownContent.Ast, start + 1);
-            diagnostics.Add(new DiagnosticMessage(DiagnosticMessageSource.Alias, "ALIASES header found", DiagnosticSeverity.Information, $"{aliasList.Count} aliases found", markdownContent.GetTextLine(start)));
+            var end = markdownContent.FindHeader(2, string.Empty);
+
+            var aliasList = GetAliases(markdownContent, start + 1);
+            diagnostics.Add(new DiagnosticMessage(DiagnosticMessageSource.Alias, "ALIASES header found", DiagnosticSeverity.Information, $"{aliasList.Count} alias strings found", markdownContent.GetTextLine(start)));
+            int totalAliasLength = 0;
+            aliasList.ForEach(a => totalAliasLength += a.Length);
+            diagnostics.Add(new DiagnosticMessage(DiagnosticMessageSource.Alias, "Alias string length", DiagnosticSeverity.Information, $"alias string length: {totalAliasLength}", markdownContent.GetTextLine(start+1)));
+
             aliasHeaderFound = true;
             return aliasList;
         }
@@ -787,32 +793,15 @@ internal static string GetSynopsisFromMarkdown(ParsedMarkdownContent markdownCon
         }
 
         // Avoid turning boilerplate into an alias
-        internal static List<string> GetAliases(MarkdownDocument md, int startIndex)
+        internal static List<string> GetAliases(ParsedMarkdownContent md, int startIndex)
         {
             List<string> aliases = new List<string>();
 
-            while (md[startIndex] is not HeadingBlock)
+            var lines = GetLinesTillNextHeader(md, 2, startIndex);
+            // don't include the boilerplate
+            if (lines.IndexOf(Constants.AliasMessage2) == -1)
             {
-                if (md[startIndex] is ParagraphBlock pb)
-                {
-                    var item = pb?.Inline?.FirstChild;
-
-                    while (item != null)
-                    {
-                        if (item is LiteralInline line)
-                        {
-                            var alias = line.ToString();
-                            if (! ContainsAliasBoilerPlate(alias))
-                            {
-                                aliases.Add(alias);
-                            }
-                        }
-
-                        item = item.NextSibling;
-                    }
-                }
-
-                startIndex++;
+                aliases.Add(lines);
             }
 
             return aliases;

src/Model/SyntaxItem.cs

@@ -114,7 +114,7 @@ public void SortParameters()
 
             if (positionList.Count > 0)
             {
-                sortedList.AddRange(positionList.OrderBy(p => int.Parse(p.Position)));
+                sortedList.AddRange(positionList.OrderBy(p => int.TryParse(p.Position, out var pos) ? pos : int.MaxValue));
             }
 
             if (mandatoryList.Count > 0)

src/YamlWriter/CommandHelpYamlWriter.cs

@@ -117,8 +117,10 @@ internal override void WriteAliases(CommandHelp help)
         {
             if (help.Aliases?.Count > 0)
             {
-                string aliasString = string.Join(", ", help.Aliases);
-                sb.AppendLine($"{Constants.yamlAliasHeader} {aliasString}");
+                Hashtable aliasHash = new();
+                aliasHash.Add("aliases", help.Aliases);
+                string aliasString = YamlUtils.SerializeElement(aliasHash).Trim();
+                sb.AppendLine(aliasString);
             }
             else
             {

test/Pester/ExportYamlModuleFile.Tests.ps1

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
 Describe "Export-YamlModuleFile tests" {
     BeforeAll {
         $moduleFileNames = "Microsoft.PowerShell.Archive.md", "Microsoft.PowerShell.Core.md",
@@ -69,4 +72,4 @@ Describe "Export-YamlModuleFile tests" {
             $observed | Should -Be $expected
         }
     }
-}
+}

test/Pester/MeasurePlatyPSMarkdown.Tests.ps1

@@ -13,10 +13,10 @@ Describe "Export-MarkdownModuleFile" {
 
     It "Should identify all the '<fileType>' assets" -TestCases @(
         @{ fileType = "unknown"; expectedCount = 2 }
-        @{ fileType = "CommandHelp"; expectedCount = 32 }
+        @{ fileType = "CommandHelp"; expectedCount = 33 }
         @{ fileType = "ModuleFile"; expectedCount = 14 }
         @{ fileType = "V1Schema"; expectedCount = 45 }
-        @{ fileType = "V2Schema"; expectedCount = 1 }
+        @{ fileType = "V2Schema"; expectedCount = 2 }
     ) {
         param ($fileType, $expectedCount)
         $idents.Where({($_.FileType -band $fileType) -eq $fileType}).Count | Should -Be $expectedCount

test/Pester/Miscellaneous.Tests.ps1

@@ -0,0 +1,25 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+Describe "Miscellaneous tests" {
+    Context "Alias preservation" {
+        BeforeAll {
+            $cmdHelpPath = [io.path]::Combine($PSScriptRoot, "assets", "Get-ChildItem.V2.md")
+            $ch_md = Import-MarkdownCommandHelp $cmdHelpPath
+            $fPath = $ch_md | Export-YamlCommandHelp -output $TESTDRIVE -Force
+            $ch_yaml = Import-YamlCommandHelp $fPath
+        }
+
+        It "Should preserve the aliases" {
+            $ch_md.Aliases | Should -Not -BeNullOrEmpty
+            $ch_md.Aliases | Should -Be $ch_yaml.Aliases
+        }
+
+        It "Should have the correct diagnostic message from the markdown parse" {
+            $message = $ch_md.Diagnostics.Messages.Where({$_.source -eq "alias" -and $_.Identifier -match "length"})
+            $message | Should -Not -BeNullOrEmpty
+            $message.Identifier | Should -Match "118"
+        }
+
+    }
+}