chore: warn devs when their feature branches may be too large (#1571)

## Description

Collectively, the Pepr team has reviewed some large PRs lately (e.g.,
#1262, #1543, #1539, #1396, #1402, #1407). We prefer several smaller PRs
to reduce the amount of time spent in code-review and to encourage
working in small chunks. This script is an example of a pre-push hook
using Husky that warns devs when their branch may be too large.

This PR does not fulfill a need in the backlog, and does not _need_ to
be merged. Rather, it's offered as an example to how a Pepr developer
might use a similar script for their local development.

## Related Issue

None.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Other (security config, docs update, etc)

## Checklist before merging
- [x] Unit,
[Journey](https://github.com/defenseunicorns/pepr/tree/main/journey),
[E2E Tests](https://github.com/defenseunicorns/pepr-excellent-examples),
[docs](https://github.com/defenseunicorns/pepr/tree/main/docs),
[adr](https://github.com/defenseunicorns/pepr/tree/main/adr) added or
updated as needed
- [x] [Contributor Guide
Steps](https://docs.pepr.dev/main/contribute/#submitting-a-pull-request)
followed

.husky/pre-commit

@@ -1 +1,2 @@
+#!/bin/bash
 npx lint-staged --verbose

.husky/pre-push

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Set PEPR_HOOK_OPT_IN=1 as an envar to use this optional pre-push hook
+
+[ "${PEPR_HOOK_OPT_IN}" != 1 ] && exit 0
+
+# Warn and exit if too many changes are about to be pushed
+MAX_CHANGES=340 #Avg commit size on main is 340 as of 12 Dec 2024
+
+# Get the local branch name
+current_branch=$(git rev-parse --abbrev-ref HEAD)
+
+# Get the remote and branch being pushed to
+remote_name="origin"
+remote_branch="main"
+
+# Get the list of commits being pushed
+# Only works if local tracking branch exists and is properly set
+commits=$(git rev-list --left-right --count ${remote_name}/${remote_branch}...HEAD 2>/dev/null || echo "0 0")
+
+# Extract commits ahead of remote
+commits_ahead=$(echo "$commits" | awk '{print $2}')
+if [[ "$commits_ahead" -eq 0 ]]; then
+    echo "No new commits to push. Exiting."
+    exit 0
+fi
+
+# Get the diff statistics for the range of commits
+stats=$(git diff --shortstat ${remote_name}/${remote_branch}...HEAD 2>/dev/null || echo "")
+
+# Extract the number of insertions and deletions
+insertions=$(echo "$stats" | awk -F',' '{gsub("[^0-9]", "", $2); print $2}')
+if [ -z "$insertions" ]; then
+  insertions="0"
+fi
+
+deletions=$(echo "$stats" | awk -F',' '{gsub("[^0-9]", "", $3); print $3}')
+if [ -z "$deletions" ]; then
+  deletions="0"
+fi
+
+total_changes=$((insertions + deletions))
+
+
+# Check if total changes exceed the maximum allowed
+if [[ "$total_changes" -gt "$MAX_CHANGES" ]]; then
+    echo "[WARNING] This push has $total_changes changes $insertions(+), $deletions(-), threshold is $MAX_CHANGES total changes."
+    echo "Consider breaking your changes into smaller, more manageable pull requests."
+    read -p "Do you want to proceed with the push? (y/n, default is n): " choice < /dev/tty
+    choice=${choice:-n} # Set default choice to 'n' if no input
+    if [[ "$choice" != "y" ]]; then
+        echo "Push aborted."
+        exit 1
+    fi
+fi
+
+# Proceed with the push
+echo "[INFO] This push contains $total_changes changes ($insertions insertions, $deletions deletions)."
+exit 0

docs/120_contribute/README.md

@@ -56,6 +56,14 @@ Please follow the coding conventions and style used in the project. Use ESLint a
 - Check formatting: `npm run format:check`
 - Fix formatting: `npm run format:fix`
 
+### Git Hooks
+
+- This project uses [husky](https://typicode.github.io/husky/) to manage git hooks for pre-commit and pre-push actions.
+- pre-commit will automatically run linters so that you don't need to remember to run `npm run format:*` commands
+- pre-push will warn you if you've changed lots of lines on a branch and encourage you to optionally present the changes as several smaller PRs to facilitate easier PR reviews.
+  - The pre-push hook is an opinionated way of working, and is therefore optional.
+  - You can opt-in to using the pre-push hook by setting `PEPR_HOOK_OPT_IN=1` as an environment variable.
+
 ## Running Tests
 
 ### Run Tests Locally