Vale GHA improvements (#4304)

* Integrate workaround for "head commit not ahead of base commit"

Workaround proposed here:
jitterbit/get-changed-files#11 (comment)

* Vale GHA: filter out files that aren't inside docs/ directory

- This helps avoid Vale running on non-content markdown files,
like our typography test page.
- A new select_docs_dir_files step is added. This step parses
and filters the JSON added_modified output from the
get_changed_files step. It then sets a new output for this
filtered file list that the Vale step later reads from.
- The jq command is used to filter the JSON list of files:
  https://stedolan.github.io/jq/
- This Stack Overflow served as inspiration:
  https://stackoverflow.com/questions/64482190/edit-the-value-inside-the-json-array-with-github-actions

* Only run the Vale step if list of files in docs/ is not empty

When the list of files was empty after the select_docs_dir_files
step ran, the action would hang at the Vale step:
https://github.com/linode/docs/pull/4304/checks?check_run_id=2546802169

* Vale GHA: add comments

.github/workflows/test.yaml

@@ -39,12 +39,35 @@ jobs:
     - name: Get Changed Files
       id: get_changed_files
       uses: jitterbit/get-changed-files@v1
+      # The continue-on-error parameter is set to true as a
+      # workaround for the `head commit is not ahead of base
+      # commit` error that can appear when the PR branch is
+      # out of date.
+      continue-on-error: true
       with:
         format: 'json'
+    - name: Install more-utils
+      run: sudo apt-get install moreutils
+    - name: Select Files in Docs Dir
+      # This action filters the list of added and modified
+      # files to only the files that are in the docs/ directory
+      id: select_docs_dir_files
+      run: |
+        docs_dir_files=$(echo $added_modified |  jq -c '[.[] | select(.|test("^docs/"))]')
+        echo "::set-output name=added_modified::$docs_dir_files"
+        echo "Added or modified files located within docs/ directory:"
+        echo $docs_dir_files | jq '.'
+      env:
+        added_modified: ${{ steps.get_changed_files.outputs.added_modified }}
     - name: Vale
       uses: errata-ai/[email protected]
+      # Only run the Vale step if the list of added and modified
+      # files inside the docs directory is not empty. If we don't
+      # add this conditional, the Vale step hangs and never
+      # completes when it is passed the empty array.
+      if: ${{ '[]' != steps.select_docs_dir_files.outputs.added_modified }}
       with:
-        files: '${{ steps.get_changed_files.outputs.added_modified }}'
+        files: '${{ steps.select_docs_dir_files.outputs.added_modified }}'
       env:
         GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}