Add Vale pre-commit Git hook (#146)

## Description This change adds a Vale pre-commit Git hook to the repository template. Additionally, the following refactoring tasks were done: - Use Vale natively, if available, otherwise fall back to Docker. - Maintain a consistent naming convention for GitHub actions and pre-commit Git hooks. ## Context Vale is a command-line tool that functions as a syntax-aware linter for prose. It's designed to help writers adhere to a specific writing style or set of guidelines. We automatically check the English usage in our documentation. ## Type of changes - [x] Refactoring (non-breaking change) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would change existing functionality) - [ ] Bug fix (non-breaking change which fixes an issue) ## Checklist - [x] I am familiar with the [contributing guidelines](../docs/CONTRIBUTING.md) - [x] I have followed the code style of the project - [ ] I have added tests to cover my changes - [ ] I have updated the documentation accordingly - [ ] This PR is a result of pair or mob programming --- ## Sensitive Information Declaration To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including [PII (Personal Identifiable Information) / PID (Personal Identifiable Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter. - [x] I confirm that neither PII/PID nor sensitive data are included in this PR and the codebase changes.
nhs-england-tools · Dec 2, 2023 · 07ee679 · 07ee679
1 parent 894f8b6
commit 07ee679
Show file tree

Hide file tree

Showing 6 changed files with 62 additions and 22 deletions.
diff --git a/.github/actions/lint-prose/action.yaml → ...b/actions/check-english-usage/action.yaml b/.github/actions/lint-prose/action.yaml → ...b/actions/check-english-usage/action.yaml
@@ -6,4 +6,5 @@ runs:
     - name: "Check English usage"
       shell: bash
       run: |
+        export BRANCH_NAME=origin/${{ github.event.repository.default_branch }}
         check=branch ./scripts/githooks/check-english-usage.sh
diff --git a/.github/workflows/stage-1-commit.yaml b/.github/workflows/stage-1-commit.yaml
@@ -56,17 +56,17 @@ jobs:
       - name: "Check file format"
         uses: ./.github/actions/check-file-format
   check-markdown-format:
-    name: "Check markdown format"
+    name: "Check Markdown format"
     runs-on: ubuntu-latest
     timeout-minutes: 2
     steps:
       - name: "Checkout code"
         uses: actions/checkout@v4
         with:
           fetch-depth: 0 # Full history is needed to compare branches
-      - name: "Check markdown format"
+      - name: "Check Markdown format"
         uses: ./.github/actions/check-markdown-format
-  lint-prose:
+  check-english-usage:
     name: "Check English usage"
     runs-on: ubuntu-latest
     timeout-minutes: 2
@@ -76,7 +76,7 @@ jobs:
         with:
           fetch-depth: 0 # Full history is needed to compare branches
       - name: "Check English usage"
-        uses: ./.github/actions/lint-prose
+        uses: ./.github/actions/check-english-usage
   lint-terraform:
     name: "Lint Terraform"
     runs-on: ubuntu-latest

diff --git a/.tool-versions b/.tool-versions
@@ -15,6 +15,7 @@ pre-commit 3.4.0
 # docker/ghcr.io/nhs-england-tools/github-runner-image 20230909-321fd1e-rt@sha256:ce4fd6035dc450a50d3cbafb4986d60e77cb49a71ab60a053bb1b9518139a646 # SEE: https://github.com/nhs-england-tools/github-runner-image/pkgs/container/github-runner-image
 # docker/hadolint/hadolint 2.12.0-alpine@sha256:7dba9a9f1a0350f6d021fb2f6f88900998a4fb0aaf8e4330aa8c38544f04db42 # SEE: https://hub.docker.com/r/hadolint/hadolint/tags
 # docker/hashicorp/terraform 1.5.6@sha256:180a7efa983386a27b43657ed610e9deed9e6c3848d54f9ea9b6cb8a5c8c25f5 # SEE: https://hub.docker.com/r/hashicorp/terraform/tags
+# docker/jdkato/vale v2.29.7@sha256:5ccfac574231b006284513ac3e4e9f38833989d83f2a68db149932c09de85149 # SEE: https://hub.docker.com/r/jdkato/vale/tags
 # docker/koalaman/shellcheck latest@sha256:e40388688bae0fcffdddb7e4dea49b900c18933b452add0930654b2dea3e7d5c # SEE: https://hub.docker.com/r/koalaman/shellcheck/tags
 # docker/mstruebing/editorconfig-checker 2.7.1@sha256:dd3ca9ea50ef4518efe9be018d669ef9cf937f6bb5cfe2ef84ff2a620b5ddc24 # SEE: https://hub.docker.com/r/mstruebing/editorconfig-checker/tags
 # docker/sonarsource/sonar-scanner-cli 5.0.1@sha256:494ecc3b5b1ee1625bd377b3905c4284e4f0cc155cff397805a244dee1c7d575 # SEE: https://hub.docker.com/r/sonarsource/sonar-scanner-cli/tags
diff --git a/scripts/config/pre-commit.yaml b/scripts/config/pre-commit.yaml
@@ -2,31 +2,39 @@ repos:
 - repo: local
   hooks:
   - id: scan-secrets
-    name: Scan Secrets
+    name: Scan secrets
     entry: ./scripts/githooks/scan-secrets.sh
     args: ["check=staged-changes"]
     language: script
     pass_filenames: false
 - repo: local
   hooks:
   - id: check-file-format
-    name: Check File Format
+    name: Check file format
     entry: ./scripts/githooks/check-file-format.sh
     args: ["check=staged-changes"]
     language: script
     pass_filenames: false
 - repo: local
   hooks:
   - id: check-markdown-format
-    name: Check Markdown Format
+    name: Check Markdown format
     entry: ./scripts/githooks/check-markdown-format.sh
     args: ["check=staged-changes"]
     language: script
     pass_filenames: false
 - repo: local
   hooks:
-  - id: check-terraform-format
-    name: Check Terraform Format
+  - id: check-english-usage
+    name: Check English usage
+    entry: ./scripts/githooks/check-english-usage.sh
+    args: ["check=staged-changes"]
+    language: script
+    pass_filenames: false
+- repo: local
+  hooks:
+  - id: lint-terraform
+    name: Lint Terraform
     entry: ./scripts/githooks/check-terraform-format.sh
     language: script
     pass_filenames: false
diff --git a/scripts/githooks/check-english-usage.sh b/scripts/githooks/check-english-usage.sh
@@ -1,6 +1,8 @@
 #!/bin/bash
 
-set -e
+# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead.
+
+set -euo pipefail
 
 # Git hook to check prose style
 #
@@ -19,15 +21,12 @@ set -e
 #   check=staged-changes: check only files staged for commit.
 #   check=working-tree-changes: check modified, unstaged files. This is the default.
 #   check=branch: check for all changes since branching from $BRANCH_NAME
-# ==============================================================================
-
-image_version=v2.29.0@sha256:d4647754ea0d051d574bafe79edccaaa67f25a4c227b890a55dd83a117278590
 
 # ==============================================================================
 
 function main() {
 
-  cd $(git rev-parse --show-toplevel)
+  cd "$(git rev-parse --show-toplevel)"
 
   check=${check:-working-tree-changes}
   case $check in
@@ -48,18 +47,49 @@ function main() {
       ;;
   esac
 
+  if command -v vale > /dev/null 2>&1 && ! is-arg-true "${FORCE_USE_DOCKER:-false}"; then
+    filter="$filter" run-vale-natively
+  else
+    filter="$filter" run-vale-in-docker
+  fi
+}
+
+# Run Vale natively.
+# Arguments (provided as environment variables):
+#   filter=[git command to filter the files to check]
+function run-vale-natively() {
+
+  # shellcheck disable=SC2046
+  vale \
+    --config "$PWD/scripts/config/vale/vale.ini" \
+    $($filter)
+}
+
+# Run Vale in a Docker container.
+# Arguments (provided as environment variables):
+#   filter=[git command to filter the files to check]
+function run-vale-in-docker() {
+
+  # shellcheck disable=SC1091
+  source ./scripts/docker/docker.lib.sh
+
+  # shellcheck disable=SC2155
+  local image=$(name=jdkato/vale docker-get-image-version-and-pull)
   # We use /dev/null here to stop `vale` from complaining that it's
   # not been called correctly if the $filter happens to return an
-  # empty list.  As long as there's a filename, even if it's one that
+  # empty list. As long as there's a filename, even if it's one that
   # will be ignored, `vale` is happy.
+  # shellcheck disable=SC2046,SC2086
   docker run --rm --platform linux/amd64 \
-    --volume $PWD:/workdir \
+    --volume "$PWD:/workdir" \
     --workdir /workdir \
-    jdkato/vale:$image_version \
-      --config scripts/config/vale/vale.ini \
+    "$image" \
+      --config /workdir/scripts/config/vale/vale.ini \
       $($filter) /dev/null
 }
 
+# ==============================================================================
+
 function is-arg-true() {
 
   if [[ "$1" =~ ^(true|yes|y|on|1|TRUE|YES|Y|ON)$ ]]; then
@@ -71,8 +101,8 @@ function is-arg-true() {
 
 # ==============================================================================
 
-is-arg-true "$VERBOSE" && set -x
+is-arg-true "${VERBOSE:-false}" && set -x
 
-main $*
+main "$@"
 
 exit 0
diff --git a/scripts/githooks/check-file-format.sh b/scripts/githooks/check-file-format.sh
@@ -76,7 +76,7 @@ function main() {
 # Run editorconfig natively.
 # Arguments (provided as environment variables):
 #   dry_run_opt=[dry run option]
-#   filter=[filter for files to check]
+#   filter=[git command to filter the files to check]
 function run-editorconfig-natively() {
 
   # shellcheck disable=SC2046,SC2086
@@ -87,7 +87,7 @@ function run-editorconfig-natively() {
 # Run editorconfig in a Docker container.
 # Arguments (provided as environment variables):
 #   dry_run_opt=[dry run option]
-#   filter=[filter for files to check]
+#   filter=[git command to filter the files to check]
 function run-editorconfig-in-docker() {
 
   # shellcheck disable=SC1091