Add experimental frontmatter value to doc source generator

michael-hawker · michael-hawker · commit de5e0fb852a2 · 2023-08-30T11:34:00.000-07:00
Can be used for Labs to mark experimental components when we interleave things together.
diff --git a/CommunityToolkit.Tooling.SampleGen.Tests/ToolkitSampleMetadataTests.Documentation.cs b/CommunityToolkit.Tooling.SampleGen.Tests/ToolkitSampleMetadataTests.Documentation.cs
@@ -2,12 +2,9 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-using CommunityToolkit.Tooling.SampleGen.Attributes;
 using CommunityToolkit.Tooling.SampleGen.Diagnostics;
-using Microsoft.CodeAnalysis;
-using Microsoft.CodeAnalysis.CSharp;
-using Microsoft.VisualStudio.TestTools.UnitTesting;
 using CommunityToolkit.Tooling.SampleGen.Tests.Helpers;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
 
 namespace CommunityToolkit.Tooling.SampleGen.Tests;
 
@@ -184,12 +181,15 @@ public void DocumentationInvalidDiscussionId()
 icon: assets/icon.png
 ---
 # This is some test documentation...
-Without an invalid discussion id.";
+Without an invalid discussion-id.";
 
         var result = string.Empty.RunSourceGenerator<ToolkitSampleMetadataGenerator>(SAMPLE_ASM_NAME, markdown);
 
         result.AssertNoCompilationErrors();
         result.AssertDiagnosticsAre(DiagnosticDescriptors.MarkdownYAMLFrontMatterException, DiagnosticDescriptors.DocumentationHasNoSamples);
+
+        var diag = result.Diagnostics.First((d) => d.Descriptor == DiagnosticDescriptors.MarkdownYAMLFrontMatterException);
+        Assert.IsTrue(diag.GetMessage().Contains("discussion-id"));
     }
 
     [TestMethod]
@@ -209,12 +209,44 @@ public void DocumentationInvalidIssueId()
 icon: assets/icon.png
 ---
 # This is some test documentation...
-Without an invalid discussion id.";
+Without an invalid issue-id.";
+
+        var result = string.Empty.RunSourceGenerator<ToolkitSampleMetadataGenerator>(SAMPLE_ASM_NAME, markdown);
+
+        result.AssertNoCompilationErrors();
+        result.AssertDiagnosticsAre(DiagnosticDescriptors.MarkdownYAMLFrontMatterException, DiagnosticDescriptors.DocumentationHasNoSamples);
+
+        var diag = result.Diagnostics.First((d) => d.Descriptor == DiagnosticDescriptors.MarkdownYAMLFrontMatterException);
+        Assert.IsTrue(diag.GetMessage().Contains("issue-id"));
+    }
+
+    [TestMethod]
+    public void DocumentationInvalidIsExperimental()
+    {
+        string markdown = @"---
+title: Canvas Layout
+author: mhawker
+description: A canvas-like VirtualizingLayout for use in an ItemsRepeater
+keywords: CanvasLayout, ItemsRepeater, VirtualizingLayout, Canvas, Layout, Panel, Arrange
+dev_langs:
+    - csharp
+category: Controls
+subcategory: Layout
+discussion-id: 0
+issue-id: 0
+icon: assets/icon.png
+experimental: No
+---
+# This is some test documentation...
+Without an invalid experimental value.";
 
         var result = string.Empty.RunSourceGenerator<ToolkitSampleMetadataGenerator>(SAMPLE_ASM_NAME, markdown);
 
         result.AssertNoCompilationErrors();
         result.AssertDiagnosticsAre(DiagnosticDescriptors.MarkdownYAMLFrontMatterException, DiagnosticDescriptors.DocumentationHasNoSamples);
+
+        var diag = result.Diagnostics.First((d) => d.Descriptor == DiagnosticDescriptors.MarkdownYAMLFrontMatterException);
+        Assert.IsTrue(diag.GetMessage().Contains("experimental"));
     }
 
     [TestMethod]
@@ -232,6 +264,7 @@ public void DocumentationValidWithRegistry()
 discussion-id: 0
 issue-id: 0
 icon: assets/icon.png
+experimental: true
 ---
 # This is some test documentation...
 Which is valid.
@@ -258,7 +291,7 @@ public static class ToolkitDocumentRegistry
         {
             public static System.Collections.Generic.IEnumerable<CommunityToolkit.Tooling.SampleGen.Metadata.ToolkitFrontMatter> Execute()
             {
-                yield return new CommunityToolkit.Tooling.SampleGen.Metadata.ToolkitFrontMatter() { Title = "Canvas Layout", Author = "mhawker", Description = "A canvas-like VirtualizingLayout for use in an ItemsRepeater", Keywords = "CanvasLayout, ItemsRepeater, VirtualizingLayout, Canvas, Layout, Panel, Arrange", Category = ToolkitSampleCategory.Controls, Subcategory = ToolkitSampleSubcategory.Layout, DiscussionId = 0, IssueId = 0, Icon = @"experiment/samples/assets/icon.png", FilePath = @"experiment\samples\documentation.md", SampleIdReferences = new string[] { "Sample" } };
+                yield return new CommunityToolkit.Tooling.SampleGen.Metadata.ToolkitFrontMatter() { Title = "Canvas Layout", Author = "mhawker", Description = "A canvas-like VirtualizingLayout for use in an ItemsRepeater", Keywords = "CanvasLayout, ItemsRepeater, VirtualizingLayout, Canvas, Layout, Panel, Arrange", Category = ToolkitSampleCategory.Controls, Subcategory = ToolkitSampleSubcategory.Layout, DiscussionId = 0, IssueId = 0, Icon = @"experiment/samples/assets/icon.png", FilePath = @"experiment\samples\documentation.md", SampleIdReferences = new string[] { "Sample" }, IsExperimental = true };
             }
         }
         """, "Unexpected code generated");
diff --git a/CommunityToolkit.Tooling.SampleGen/Metadata/ToolkitFrontMatter.cs b/CommunityToolkit.Tooling.SampleGen/Metadata/ToolkitFrontMatter.cs
@@ -19,6 +19,7 @@ public sealed class ToolkitFrontMatter : DocsFrontMatter
     public ToolkitSampleSubcategory Subcategory { get; set; }
     public int DiscussionId { get; set; }
     public int IssueId { get; set; }
+    public bool? IsExperimental { get; set; }
 
     //// Extra Metadata needed for Sample App
     public string? FilePath { get; set; }
diff --git a/CommunityToolkit.Tooling.SampleGen/ToolkitSampleMetadataGenerator.Documentation.cs b/CommunityToolkit.Tooling.SampleGen/ToolkitSampleMetadataGenerator.Documentation.cs
@@ -46,6 +46,9 @@ public partial class ToolkitSampleMetadataGenerator
     private const string MarkdownRegexSampleTagExpression = @"^>\s*\[!SAMPLE\s*(?<sampleid>.*)\s*\]\s*$";
     private static readonly Regex MarkdownRegexSampleTag = new Regex(MarkdownRegexSampleTagExpression, RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.Multiline);
 
+    private const string FrontMatterRegexIsExperimentalExpression = @"^experimental:\s*(?<experimental>.*)$";
+    private static readonly Regex FrontMatterRegexIsExperimental = new Regex(FrontMatterRegexIsExperimentalExpression, RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.Multiline);
+
     private static void ReportDocumentDiagnostics(SourceProductionContext ctx, Dictionary<string, ToolkitSampleRecord> sampleMetadata, IEnumerable<AdditionalText> markdownFileData, IEnumerable<(ToolkitSampleAttribute Attribute, string AttachedQualifiedTypeName, ISymbol Symbol)> toolkitSampleAttributeData, ImmutableArray<ToolkitFrontMatter> docFrontMatter)
     {
         // Keep track of all sample ids and remove them as we reference them so we know if we have any unreferenced samples.
@@ -126,6 +129,8 @@ private ImmutableArray<ToolkitFrontMatter> GatherDocumentFrontMatter(SourceProdu
                 var discussion = ParseYamlField(ref ctx, file.Path, ref frontmatter, FrontMatterRegexDiscussionId, "discussionid")?.Trim();
                 var issue = ParseYamlField(ref ctx, file.Path, ref frontmatter, FrontMatterRegexIssueId, "issueid")?.Trim();
 
+                var experimental = ParseYamlField(ref ctx, file.Path, ref frontmatter, FrontMatterRegexIsExperimental, "experimental", true)?.Trim();
+
                 // Check we have all the fields we expect to continue (errors will have been spit out otherwise already from the ParseYamlField method)
                 if (title == null || description == null || keywords == null ||
                         category == null || subcategory == null || discussion == null || issue == null || icon == null)
@@ -204,6 +209,18 @@ private ImmutableArray<ToolkitFrontMatter> GatherDocumentFrontMatter(SourceProdu
                     return null;
                 }
 
+                bool isExperimental = false;
+                if (experimental != null && !bool.TryParse(experimental, out isExperimental))
+                {
+                    ctx.ReportDiagnostic(
+                        Diagnostic.Create(
+                            DiagnosticDescriptors.MarkdownYAMLFrontMatterException,
+                            Location.Create(file.Path, TextSpan.FromBounds(0, 1), new LinePositionSpan(LinePosition.Zero, LinePosition.Zero)),
+                            file.Path,
+                            "Can't parse optional experimental field, must be a boolean value like 'true' or 'false' or remove it."));
+                    return null;
+                }
+
                 // Finally, construct the complete object.
                 return new ToolkitFrontMatter()
                 {
@@ -218,16 +235,17 @@ private ImmutableArray<ToolkitFrontMatter> GatherDocumentFrontMatter(SourceProdu
                     DiscussionId = discussionId,
                     IssueId = issueId,
                     Icon = iconpath,
+                    IsExperimental = isExperimental,
                 };
             }
         }).OfType<ToolkitFrontMatter>().ToImmutableArray();
     }
 
-    private string? ParseYamlField(ref SourceProductionContext ctx, string filepath, ref string content, Regex pattern, string captureGroupName)
+    private string? ParseYamlField(ref SourceProductionContext ctx, string filepath, ref string content, Regex pattern, string captureGroupName, bool optional = false)
     {
         var match = pattern.Match(content);
 
-        if (!match.Success)
+        if (!optional && !match.Success)
         {
             ctx.ReportDiagnostic(
                 Diagnostic.Create(
@@ -237,6 +255,10 @@ private ImmutableArray<ToolkitFrontMatter> GatherDocumentFrontMatter(SourceProdu
                     captureGroupName));
             return null;
         }
+        else if (optional && !match.Success)
+        {
+            return null;
+        }
 
         return match.Groups[captureGroupName].Value.Trim();
     }
@@ -270,6 +292,6 @@ private static string FrontMatterToRegistryCall(ToolkitFrontMatter metadata)
         var categoryParam = $"{nameof(ToolkitSampleCategory)}.{metadata.Category}";
         var subcategoryParam = $"{nameof(ToolkitSampleSubcategory)}.{metadata.Subcategory}";
 
-        return @$"yield return new {typeof(ToolkitFrontMatter).FullName}() {{ Title = ""{metadata.Title}"", Author = ""{metadata.Author}"", Description = ""{metadata.Description}"", Keywords = ""{metadata.Keywords}"", Category = {categoryParam}, Subcategory = {subcategoryParam}, DiscussionId = {metadata.DiscussionId}, IssueId = {metadata.IssueId}, Icon = @""{metadata.Icon}"", FilePath = @""{metadata.FilePath}"", SampleIdReferences = new string[] {{ ""{string.Join("\",\"", metadata.SampleIdReferences)}"" }} }};"; // TODO: Add list of sample ids in document
+        return @$"yield return new {typeof(ToolkitFrontMatter).FullName}() {{ Title = ""{metadata.Title}"", Author = ""{metadata.Author}"", Description = ""{metadata.Description}"", Keywords = ""{metadata.Keywords}"", Category = {categoryParam}, Subcategory = {subcategoryParam}, DiscussionId = {metadata.DiscussionId}, IssueId = {metadata.IssueId}, Icon = @""{metadata.Icon}"", FilePath = @""{metadata.FilePath}"", SampleIdReferences = new string[] {{ ""{string.Join("\",\"", metadata.SampleIdReferences)}"" }}, IsExperimental = {metadata.IsExperimental.ToString().ToLowerInvariant()} }};"; // TODO: Add list of sample ids in document
     }
 }
