More Consistent Message Building

.github/workflows/DocTagChecker.yml

@@ -0,0 +1,30 @@
+name: DocTagChecker
+
+on:
+  pull_request
+
+jobs:
+  DocTagCheck:
+    runs-on: ubuntu-latest
+    env:
+        BRANCH_NAME: ${{ github.head_ref || github.ref_name }} 
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Check for missing userdoc updates
+        # Use the DocTagChecker version from the branch that triggered the workflow
+        # This is the repo relative path to actions.yml
+        uses: ./
+        with: 
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          # multiple paths are separated by whitespace or ','
+          userDocsDirs: __tests__/testData/
+          # Optional inputs with defaults:
+          # DON'T use '/other stuff/i' as it contains intentional fakes
+          # dirTagSectionRegex: 
+          # Check userDocsDirs recursively.
+          recurseUserDocDirs: true
+          # File extensions for files to be considered documentation.
+          docFileExtensions: md
+          # File extensions for files to be considered source code.
+          srcFileExtensions: ts

src/main.ts

@@ -240,14 +240,6 @@ function buildMessage(
   unknownTags: Map<string, string[]>,
   header: string
 ): string {
-  // If there is nothing to report on, the message stays empty
-  if (unchangedDoc.size === 0 && unknownTags.size === 0) {
-    return ''
-  }
-
-  // Message starts with the header.
-  let message = header
-
   // Local helper function turning a list of tags into named urls to changes.
   const tagsToUrls = (tagList: string[]): string[] => {
     return tagList.map((tag: string): string => {
@@ -256,39 +248,47 @@ function buildMessage(
     })
   }
 
-  // Add content for unknown tags.
-  if (unknownTags.size !== 0) {
-    message += `## Unknown Tags
+  // Message starts with the header.
+  let message = header
+
+  // If there is nothing to report on, only create s stub.
+  if (unchangedDoc.size === 0 && unknownTags.size === 0) {
+    message = `Looks good to me! :shipit:`
+  } else {
+    // Add content for unknown tags.
+    if (unknownTags.size !== 0) {
+      message += `## Unknown Tags
 The following tags could not be found in the latest revision:
 | DocFile | Unknown Tags |
 |:--------|:------------:|\n`
 
-    // Create one table row for each doc file.
-    for (const [docfile, tags] of unknownTags) {
-      // Turn filenames to links.
-      const docfileLink = `[${path.basename(docfile)}](${getUrlToFile(
-        docfile
-      )})`
-      // Wrap tags in '`' and add space for readability.
-      const tagsDecorated = tags.map(tag => {
-        return ` \`${tag}\``
-      })
-      // These tags are unknown so don't try to create links for them.
-      message += `| ${docfileLink} | ${tagsDecorated} |\n`
+      // Create one table row for each doc file.
+      for (const [docfile, tags] of unknownTags) {
+        // Turn filenames to links.
+        const docfileLink = `[${path.basename(docfile)}](${getUrlToFile(
+          docfile
+        )})`
+        // Wrap tags in '`' and add space for readability.
+        const tagsDecorated = tags.map(tag => {
+          return ` \`${tag}\``
+        })
+        // These tags are unknown so don't try to create links for them.
+        message += `| ${docfileLink} | ${tagsDecorated} |\n`
+      }
+      message += '\n'
     }
-    message += '\n'
-  }
 
-  // Add content for unchanged documentation.
-  if (unchangedDoc.size !== 0) {
-    message += `## Unchanged Documentation
+    // Add content for unchanged documentation.
+    if (unchangedDoc.size !== 0) {
+      message += `## Unchanged Documentation
 The following doc files are unchanged, but some related sources were changed. Make sure the documentation is up to date!\n\n`
-    // Create one task for each doc file.
-    for (const [docfile, tags] of unchangedDoc) {
-      // Add links to all filenames.
-      message += `- [ ] [${path.basename(docfile)}](${getUrlToFile(
-        docfile
-      )}) (changed: ${tagsToUrls(tags)})\n`
+      // Create one task for each doc file.
+      for (const [docfile, tags] of unchangedDoc) {
+        // Add links to all filenames.
+        message += `- [ ] [${path.basename(docfile)}](${getUrlToFile(
+          docfile
+        )}) (changed: ${tagsToUrls(tags)})\n`
+      }
     }
   }
 
@@ -454,15 +454,12 @@ export async function run(): Promise<void> {
     // Set outputs for other workflow steps to use.
     if (unchangedDoc.size === 0 && unknownTags.size === 0) {
       core.setOutput('warnings', 'NO WARNINGS')
-      // Message to signal that the checking actually happened.
-      const message = `${header}Looks good to me! :shipit:`
-      await postMessage(ghToken, message)
     } else {
       core.setOutput('warnings', 'DOC MIGHT NEED UPDATE OR TAGS ARE INVALID')
-      // Add a new comment with the warnings to the PR.
-      const message = buildMessage(unchangedDoc, unknownTags, header)
-      await postMessage(ghToken, message)
     }
+    // Add a new comment with either the warnings or an all-ok to the PR.
+    const message = buildMessage(unchangedDoc, unknownTags, header)
+    await postMessage(ghToken, message)
   } catch (error) {
     // Fail the workflow run if an error occurs
     if (error instanceof Error) {