Add Vale pre-commit Git hook (nhs-england-tools#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.

Author: stefaniuk

.github/actions/lint-prose/action.yaml …/actions/check-english-usage/action.yaml.github/actions/lint-prose/action.yaml renamed to .github/actions/check-english-usage/action.yaml .github/actions/lint-prose/action.yaml renamed to .github/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

.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

.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

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

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

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