diff --git a/.github/workflows/DocTagChecker.yml b/.github/workflows/DocTagChecker.yml new file mode 100644 index 0000000..b0e2a07 --- /dev/null +++ b/.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 diff --git a/badges/coverage.svg b/badges/coverage.svg index 846c4a6..63212d9 100644 --- a/badges/coverage.svg +++ b/badges/coverage.svg @@ -1 +1 @@ -Coverage: 95.16%Coverage95.16% \ No newline at end of file +Coverage: 96.19%Coverage96.19% \ No newline at end of file diff --git a/dist/index.js b/dist/index.js index cca14a7..dbd8f3b 100644 --- a/dist/index.js +++ b/dist/index.js @@ -29113,12 +29113,6 @@ async function deleteLastComment(ghToken, header) { * @return Message as string. */ function buildMessage(unchangedDoc, unknownTags, header) { - // 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) => { return tagList.map((tag) => { @@ -29126,33 +29120,41 @@ function buildMessage(unchangedDoc, unknownTags, header) { return `[${tag}](${(0, utils_1.getUrlToChanges)(filePath)})`; }); }; - // 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)}](${(0, utils_1.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)}](${(0, utils_1.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)}](${(0, utils_1.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)}](${(0, utils_1.getUrlToFile)(docfile)}) (changed: ${tagsToUrls(tags)})\n`; + } } } // Add footer with information about the bot. @@ -29275,16 +29277,13 @@ async function run() { // 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 diff --git a/src/main.ts b/src/main.ts index 59947dd..10ca6ba 100644 --- a/src/main.ts +++ b/src/main.ts @@ -240,14 +240,6 @@ function buildMessage( unknownTags: Map, 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 { // 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) {