Use Check Runs API to report on status checks (success and failures) (#1129)

* First pass at code.

Prototype of generating checks

This has a prototype to create the proper JSON format for the status check.

Remaining task: Consume the output and POST the results.

* Add POST capability.

POST the check results back to GitHub

* Update YML and shell script

* Introduce error for check run

* Remove error introduced for testing

* remove warnings.

This way, the only annotations that are displayed actually matter for the tool being run

* Respond to feedback

Warnings shouldn't be treated as errors.

Author: BillWagner

.github/workflows/renumber-sections.yaml

@@ -14,8 +14,11 @@ on:
 jobs:
   renumber-sections:
     runs-on: ubuntu-latest
+    permissions:
+      checks: write
     env:
       DOTNET_NOLOGO: true
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
     steps:
     - name: Check out our repo
@@ -29,4 +32,4 @@ jobs:
     - name: Run section renumbering dry run
       run: |
         cd tools
-        ./run-section-renumber.sh --dryrun
+        ./run-section-renumber.sh ${{ github.event.pull_request.head.sha }}

tools/StandardAnchorTags/DiagnosticIDs.cs

@@ -0,0 +1,6 @@
+namespace StandardAnchorTags;
+internal class DiagnosticIDs
+{
+    public const string TOC001 = nameof(TOC001);
+    public const string TOC002 = nameof(TOC002);
+}

tools/StandardAnchorTags/GenerateGrammar.cs

@@ -2,13 +2,34 @@
 
 namespace StandardAnchorTags;
 
+/// <summary>
+/// The data storage for the headers of the grammar file
+/// </summary>
+/// <param name="LexicalHeader">The text for the lexical section header</param>
+/// <param name="SyntacticHeader">The text for the syntactic section header</param>
+/// <param name="UnsafeExtensionsHeader">The text for the unsafe extensions header</param>
+/// <param name="GrammarFooter">The footer</param>
 public record GrammarHeaders(string LexicalHeader, 
     string SyntacticHeader, 
     string UnsafeExtensionsHeader,
     string GrammarFooter);
 
+/// <summary>
+/// This class generates a grammar file from the ANTLR blocks in the standard
+/// </summary>
+/// <remarks>
+/// The full grammar is in small pieces in each clause of the standard. Then,
+/// its duplicated in an Annex. Rather than copy and paste by hand, generate that
+/// Annex from the other smaller parts.
+/// </remarks>
 public class GenerateGrammar : IDisposable
 {
+    /// <summary>
+    /// Read the existing headers from a grammar file
+    /// </summary>
+    /// <param name="pathToStandard">Path to the standard files (likely ../standard)</param>
+    /// <param name="grammarFile">The filename for the grammar annex</param>
+    /// <returns>The task that will return the headers when complete.</returns>
     public static async Task<GrammarHeaders> ReadExistingHeaders(string pathToStandard, string grammarFile)
     {
         GrammarHeaders headers = new GrammarHeaders("", "", "", "");
@@ -50,24 +71,53 @@ public static async Task<GrammarHeaders> ReadExistingHeaders(string pathToStanda
     private readonly string pathToStandardFiles;
     private readonly StreamWriter grammarStream;
 
+    /// <summary>
+    /// Construct a new grammar generator
+    /// </summary>
+    /// <param name="grammarPath">The path to the file</param>
+    /// <param name="pathToStandardFiles">The path to the files in the standard</param>
+    /// <param name="headers">The header text</param>
     public GenerateGrammar(string grammarPath, string pathToStandardFiles, GrammarHeaders headers)
     {
         grammarStream = new StreamWriter(Path.Combine(pathToStandardFiles, grammarPath), false);
         this.pathToStandardFiles = pathToStandardFiles;
         informativeTextBlocks = headers;
     }
 
+    /// <summary>
+    /// Write the header text that appears before the grammar output.
+    /// </summary>
+    /// <returns>The task</returns>
     public async Task WriteHeader() => await grammarStream.WriteAsync(informativeTextBlocks.LexicalHeader);
+
+    /// <summary>
+    /// Write the header text for the syntactic section
+    /// </summary>
+    /// <returns>The task</returns>
     public async Task WriteSyntaxHeader() => await grammarStream.WriteAsync(informativeTextBlocks.SyntacticHeader);
+
+    /// <summary>
+    /// Write the header text for the unsafe extensions section
+    /// </summary>
+    /// <returns>The task</returns>
     public async Task WriteUnsafeExtensionHeader() => await grammarStream.WriteAsync(informativeTextBlocks.UnsafeExtensionsHeader);
 
+    /// <summary>
+    /// Write the footer text that appears after the grammar output.
+    /// </summary>
+    /// <returns>The task</returns>
     public async Task WriteGrammarFooter()
     {
         await grammarStream.WriteAsync(informativeTextBlocks.GrammarFooter);
         await grammarStream.FlushAsync();
         grammarStream.Close();
     }
 
+    /// <summary>
+    /// Extract the grammar from one file in the standard
+    /// </summary>
+    /// <param name="inputFileName">The input file from the standard</param>
+    /// <returns>The task</returns>
     public async Task ExtractGrammarFrom(string inputFileName)
     {
         string inputFilePath = $"{pathToStandardFiles}/{inputFileName}";
@@ -106,5 +156,8 @@ public async Task ExtractGrammarFrom(string inputFileName)
         }
     }
 
+    /// <summary>
+    /// Dispose of the stream
+    /// </summary>
     public void Dispose() => grammarStream.Dispose();
 }