chore: enforce pre-PR validation (aggregate scripts, git hooks, PR checklist) (#1061)

brunoborges · Copilot · Copilot · web-flow · commit 623c707d77e9 · 2026-06-26T08:07:16.000+01:00
* chore: enforce pre-PR validation with aggregate scripts, git hooks, and PR checklist

Add tooling to help contributors run the same checks as CI before
submitting a pull request, reducing avoidable format/lint/build failures.

- Add aggregate npm scripts:
  - `npm run check` runs format-check + lint + build + test (mirrors CI)
  - `npm run fix` runs format + lint:fix + build
- Add husky + lint-staged git hooks (installed via `npm install`):
  - pre-commit formats and lints staged files
  - pre-push rebuilds dist/ and runs the test suite
- Add a checklist item to the PR template prompting contributors to run
  `npm run check` locally
- Document the aggregate scripts and hooks in docs/contributors.md

dist/ is intentionally not auto-committed by CI to avoid pwn-request
security risks; the existing `Check dist/` workflow continues to verify it.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;

* Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI &lt;175728472+Copilot@users.noreply.github.com&gt;

---------

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
Co-authored-by: Copilot Autofix powered by AI &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -5,5 +5,6 @@ Describe your changes.
 Add link to the related issue.
 
 **Check list:**
+- [ ] Ran `npm run check` locally (format, lint, build, test) and all checks pass.
 - [ ] Mark if documentation changes are required.
 - [ ] Mark if tests were added or updated to cover the changes.
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged
diff --git a/.husky/pre-push b/.husky/pre-push
@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run build && npm test
diff --git a/docs/contributors.md b/docs/contributors.md
@@ -63,6 +63,17 @@ Pull requests are the easiest way to contribute changes to git repos at GitHub.
 - To lint the code, **you need to run the `lint:fix` script**
 - To transpile source code to `javascript` we use [NCC](https://github.com/vercel/ncc). **It is very important to run the `build` script after making changes**, otherwise your changes will not get into the final `javascript` build
 
+> [!TIP]
+> Instead of running each script individually, you can run the aggregate scripts:
+>
+> - `npm run fix` — formats, lints (with autofix) and rebuilds the `dist/` bundle.
+> - `npm run check` — runs the same validation as CI: `format-check`, `lint`, `build` and `test`. **Run this before pushing a pull request** to make sure it will pass the required checks.
+>
+> Git hooks are installed automatically when you run `npm install` (via [husky](https://typicode.github.io/husky/)):
+>
+> - a **pre-commit** hook formats and lints staged files with [lint-staged](https://github.com/lint-staged/lint-staged);
+> - a **pre-push** hook rebuilds `dist/` and runs the test suite.
+
 **Learn more about how to implement tests:**
 
 Adding or changing tests is an integral part of making a change to the code. 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
