@ministryofjustice/hmpps-precommit-hooks 1.0.2 → 2.0.0-beta.1

package/README.md

@@ -1,12 +1,21 @@
 # @ministryofjustice/hmpps-precommit-hooks
 
-This package aims to automatically install and configure husky with gitleaks to help catch potential secrets before committing them to github.
+This package aims to automatically install and configure pre-commit hooks using [prek](https://github.com/pre-commit/pre-commit) to help catch potential secrets and code quality issues before committing them to github.
 
 ## Status
 
 **This library is currently: ready to adopt.**
 Teams are welcome to use this library. Please provide feedback via slack to the `#typescript` channel.
 
+## Migration from Husky
+
+This package has migrated from using Husky to using [prek](https://github.com/pre-commit/pre-commit) (pre-commit) for managing git hooks. The migration will happen automatically during `npm install`:
+
+- Husky will be uninstalled if present
+- Existing husky hooks will be removed
+- prek will be installed via Homebrew (if not already installed)
+- A `.pre-commit-config.yaml` file will be created with the default hooks configuration
+
 ## Migrating existing projects
 
 #### Automatically installing the library
@@ -19,35 +28,68 @@ Once the project has been initialised, other developers should be able to develo
 
 ### How this works
 
-Initialising will add new precommit scripts and a new prepare script in `package.json`:
+Initialising will add a new prepare script in `package.json`:
 
 ```json
 "scripts": {
      //...
-    "prepare": "hmpps-precommit-hooks",
-    "precommit:secrets": "gitleaks git --pre-commit --redact --staged --verbose",
-    "precommit:lint": "node_modules/.bin/lint-staged",
-    "precommit:verify": "npm run typecheck && npm test"
+    "prepare": "hmpps-precommit-hooks"
 }
 ```
 
-It will also configure a husky precommit hook using these scripts:
-
-```sh
-#!/bin/bash
-NODE_ENV=dev \
-npm run precommit:secrets \
-&& npm run precommit:lint \
-&& npm run precommit:verify
+The package will create a `.pre-commit-config.yaml` file in your project root that configures the hooks to run:
+
+```yaml
+HMPPS_HOOKS_VERSION: 1
+
+repos:
+  - repo: local
+    hooks:
+      - id: gitleaks
+        name: Scan commit for secrets
+        language: system
+        entry: gitleaks git --pre-commit --redact --staged --verbose --config .gitleaks/config.toml --gitleaks-ignore-path .gitleaks/.gitleaksignore
+      - id: lint
+        name: linting code
+        language: system
+        entry: npm run lint
+      - id: typecheck
+        name: verify types
+        language: system
+        entry: npm run typecheck
+      - id: test
+        name: running tests
+        language: system
+        entry: npm run test
+  - repo: builtin
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-json
+      - id: check-yaml
+      - id: check-merge-conflict
 ```
 
-The prepare script will trigger on any install and ensure that `gitleaks` is installed and `husky` is initiated.
+The prepare script will trigger on any install and ensure that `prek` (pre-commit) is installed via Homebrew.
+
+Note: `prek` is installed by `brew`. If `brew` is not available, `prepare` will display a message indicating you need to install prek manually.
 
-Note: `gitleaks` is installed by `brew`, if `brew` is not available then `prepare` will currently fail loudly and display a message.
+**Important:** The `.pre-commit-config.yaml` file will only be created if it doesn't exist. Once created, it will not be overwritten, allowing you to customize hooks for your project's needs. Legacy precommit scripts (`precommit:secrets`, `precommit:lint`, `precommit:verify`) will be automatically removed from `package.json` when the config file is created.
 
 ### Prevent precommit script initialising on prepare
 
-To disable the tool running on `npm install` and initialising husky and installing gitleaks, you can pass the `SKIP_PRECOMMIT_INIT=true` env var.
+To disable the tool running on `npm install` and initialising prek, you can pass the `SKIP_PRECOMMIT_INIT=true` env var.
+
+### Customizing hooks
+
+You can modify the `.pre-commit-config.yaml` file in your project to:
+
+- Add additional hooks
+- Remove hooks that don't apply to your project
+- Modify hook configurations
+- Add hooks from external repositories
+
+See the [pre-commit documentation](https://pre-commit.com/) for more details on hook configuration.
 
 ### Dealing with false positives
 
@@ -67,6 +109,21 @@ Repo specific rules can be added by teams in `.gitleaks/config.toml` in their in
 
 See the gitleaks documentation for how to create rules and [examples](https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml) or use the [online rule wizard](https://gitleaks.io/playground).
 
+### Running hooks manually
+
+You can run all hooks manually using:
+
+```bash
+prek run --all-files
+```
+
+Or run specific hooks:
+
+```bash
+prek run gitleaks
+prek run lint
+```
+
 ### Testing that hooks are configured correctly
 
 Secret protection can be tested using the following command:
@@ -92,7 +149,7 @@ Attempting to commit file containing secret
     ○ ░
     ░    gitleaks
 
-Finding:     fake_aws_key=REDACTED
+Finding:     fake__key=REDACTED
 Secret:      REDACTED
 RuleID:      aws-access-token
 Entropy:     3.546439

package/bin/init.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 #
-# Used to install husky with gitleaks
+# Used to install prek with gitleaks
 # 
 
 set -euo pipefail
@@ -44,22 +44,13 @@ else
   npm --silent  install
 fi
 
-startStage "  * Adding npm scripts"
-npm pkg --silent set scripts.precommit:secrets="gitleaks git --pre-commit --redact --staged --verbose --config .gitleaks/config.toml  --gitleaks-ignore-path .gitleaks/.gitleaksignore" 
-npm pkg --silent set scripts.precommit:lint="node_modules/.bin/lint-staged"
-npm pkg --silent set scripts.precommit:verify="npm run typecheck && npm test"
-endStage " ✅"
+# Copy default-hooks.yaml to target location
+SOURCE_HOOKS="./node_modules/@ministryofjustice/hmpps-precommit-hooks/default-hooks.yaml"
+TARGET_HOOKS=".pre-commit-config.yaml"
 
-startStage "  * Setting precommit hook"
-mkdir -p .husky
-printf "%s\n" \
-     "#!/bin/bash" \
-     "NODE_ENV=dev \\" \
-     "npm run precommit:secrets \\" \
-     "&& npm run precommit:lint \\" \
-     "&& npm run precommit:verify" \
-       > .husky/pre-commit
-endStage " ✅"
+startStage "Creating .pre-commit-config.yaml"
+cp "$SOURCE_HOOKS" "$TARGET_HOOKS"
+endStage " ✅ "
 
 startStage "  * Creating .gitleaksignore "
 mkdir -p .gitleaks

package/bin/prepare.sh

@@ -22,18 +22,58 @@ if [ "$CI" = "true" ] || [ "$SKIP_PRECOMMIT_INIT" = "true" ]; then
   exit 0
 fi 
 
-# Initialise husky
-node_modules/.bin/husky
+
+# Remove husky if installed
+if [ -f "node_modules/.bin/husky" ]; then
+  startStage "Removing husky"
+  npm uninstall husky
+  endStage " ✅ "
+
+  if [ -f ".husky/pre-commit" ]; then
+    startStage "Deleting existing husky pre-commit hook"
+    rm .husky/pre-commit
+    endStage " ✅ "
+  fi
+fi
 
 # Check brew exists
 if ! command -v brew > /dev/null 2> /dev/null; then
-  printError "Brew is not installed. You will need to install gitleaks separately and ensure it's on your PATH. exiting..."
+  printError "Brew is not installed. You will need to install prek separately and ensure it's on your PATH. exiting..."
   exit 0
 fi
 
-# Initialise gitleaks
+# Install gitleaks if not present - this will be used by prek for secret scanning until we move over to devsecops hooks
 if ! command -v gitleaks > /dev/null 2> /dev/null; then
   startStage "Installing gitleaks"
   brew install gitleaks
   endStage " ✅ "
 fi
+
+# Install prek
+if ! command -v prek > /dev/null 2> /dev/null; then
+  startStage "Installing prek"
+  brew install prek
+  endStage " ✅ "
+fi
+
+# Copy default-hooks.yaml to target location
+SOURCE_HOOKS="./node_modules/@ministryofjustice/hmpps-precommit-hooks/default-hooks.yaml"
+TARGET_HOOKS=".pre-commit-config.yaml"
+
+
+if [ ! -f "$TARGET_HOOKS" ]; then
+  startStage "Creating .pre-commit-config.yaml"
+  cp "$SOURCE_HOOKS" "$TARGET_HOOKS"
+  endStage " ✅ "
+  
+  startStage "Deleting existing precommit scripts"
+  npm pkg --silent delete scripts.precommit:secrets
+  npm pkg --silent delete scripts.precommit:lint
+  npm pkg --silent delete scripts.precommit:verify
+  endStage " ✅ "
+fi
+
+startStage "Initialising prek hooks on this repo"
+git config --unset-all --local core.hooksPath || true
+prek install
+endStage " ✅ "

package/bin/test.sh

@@ -3,11 +3,11 @@
 # Test that secret protection is set up correctly. 
 # This will create a separate file ./demo-password.txt which will need to be deleted separately. 
 
-RANDOM_NUMBER="$(LC_ALL=C tr -cd '[:digit:]' < /dev/urandom | fold -w 13 | head -n 1)"
-AWS_KEY="AKIA${RANDOM_NUMBER}ASD"
+RANDOM_NUMBER="$(LC_ALL=C tr -cd '[:digit:]' < /dev/urandom | fold -w 10 | head -n 1)"
+FAKE_KEY="sk-${RANDOM_NUMBER}abcdef"
 
-echo "Creating test file containing dummy AWS_KEY=${AWS_KEY}"
-echo "fake_aws_key=${AWS_KEY}" > ./demo-password.txt
+echo "Creating test file containing dummy key: 'fake_key=${FAKE_KEY}'"
+echo "fake_key=${FAKE_KEY}" > ./demo-password.txt
 
 echo "Attempting to commit file containing secret"
-git add ./demo-password.txt && git commit -m "This should fail due to detecting dummy AWS creds"
+git add ./demo-password.txt && git commit -m "This should fail due to detecting dummy creds"

package/default-hooks.yaml

@@ -0,0 +1,48 @@
+# Pre-commit hook configuration file
+#
+# This contains the list of hooks to be run before committing code.
+# The devsecops-hooks baseline hook is temporarily disabled while we investigate issues with it but will eventually become compulsory.
+# Other hooks maybe added or removed as needed to suit individual project requirements.
+
+repos:
+  #. Temporary disabled while we investigate issues with it
+  #  - repo: https://github.com/ministryofjustice/devsecops-hooks
+  #    rev: v1.1.0
+  #    hooks:
+  #      - id: baseline
+  - repo: local
+    hooks:
+      - id: gitleaks
+        name: Scan commit for secrets
+        language: system
+        entry: gitleaks git --pre-commit --redact --staged --verbose --config .gitleaks/config.toml --gitleaks-ignore-path .gitleaks/.gitleaksignore
+        require_serial: true
+        pass_filenames: false
+      - id: lint
+        name: linting code
+        language: system
+        entry: npm run lint
+        types: [ts]
+        require_serial: true
+        pass_filenames: false
+      - id: typecheck
+        name: verify types
+        language: system
+        entry: npm run typecheck
+        types: [ts]
+        require_serial: true
+        pass_filenames: false
+      - id: test
+        name: running tests
+        language: system
+        entry: npm run test
+        types: [ts]
+        require_serial: true
+        pass_filenames: false
+  - repo: builtin
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-json
+      - id: check-yaml
+      - id: check-merge-conflict

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ministryofjustice/hmpps-precommit-hooks",
-  "version": "1.0.2",
+  "version": "2.0.0-beta.1",
   "description": "Precommit hooks for HMPPS typescript projects",
   "keywords": [
     "precommit"
@@ -14,7 +14,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   },
   "bin": {
     "hmpps-precommit-hooks-prepare": "bin/prepare.sh",
@@ -27,7 +27,8 @@
   "files": [
     "*.md",
     "bin/*.sh",
-    "config.toml"
+    "config.toml",
+    "default-hooks.yaml"
   ],
   "engines": {
     "node": "20 || 22 || 24"