@howells/husky 0.1.3 → 0.2.0

package/README.md

@@ -35,6 +35,25 @@ Runs `pnpm lint-staged` — formats staged files with the configured Howells for
 
 Runs `pnpm typecheck` and `pnpm lint`. Both must pass before code reaches the remote.
 
+Both run against the **working directory**, so their result only describes what is being pushed when the working directory is what is being pushed. Git names the refs on stdin, so the hook can tell:
+
+| What you are pushing | What happens |
+| --- | --- |
+| The commit you have checked out | Typecheck and lint run. A failure blocks the push. |
+| A ref that is not `HEAD` | Skipped, and said out loud. The checks would describe a different tree. |
+| A branch deletion | Ignored; nothing is being added to check. |
+| Nothing on stdin | Checked anyway. An unverified push is what this hook exists to stop. |
+
+**Why a non-`HEAD` push is skipped rather than failed.** It is neither a pass nor a failure - it is unverifiable, and reporting the wrong tree's result is worse than admitting the hook cannot see. The case this matters for is the rescue path: work that exists in one place, in a tree that does not typecheck, is exactly what most needs pushing. The old behaviour failed that push for a reason unrelated to what was being pushed, leaving `--no-verify` as the only route - which disables every gate at once.
+
+### The hooks are immutable, and now they say so
+
+`.husky/pre-commit` and `.husky/pre-push` are overwritten from this package on every install. That is deliberate: a repo cannot weaken its own gate to get something to pass.
+
+What changed is that it is no longer silent. If an install replaces a hook whose contents differ from the packaged one, it says so and names the file. Before, a customised hook vanished on the next `pnpm install` with nothing printed, so whoever wrote it believed it was in effect until it demonstrably was not.
+
+**To change a hook, change it here and publish.** There is no per-repo override, by design.
+
 ## Requirements
 
 Your `package.json` must have:

package/bin/howells-husky.mjs

@@ -78,11 +78,35 @@ if (!existsSync(huskyDir)) {
 const hooks = ["pre-commit", "pre-push"];
 const hooksDir = path.join(packageRoot, "hooks");
 
+// The overwrite is deliberate: the hooks are the package's, not the project's,
+// so a weakened gate cannot survive an install. What was missing is that it
+// happened in silence — a customised hook vanished on the next `pnpm install`
+// with nothing said, so the author believed their change was in effect until
+// it demonstrably was not. Replacing is still unconditional; it is now audible.
 for (const hook of hooks) {
   const source = path.join(hooksDir, hook);
   const dest = path.join(huskyDir, hook);
+
+  let replacedLocalEdit = false;
+  if (existsSync(dest)) {
+    replacedLocalEdit =
+      readFileSync(dest, "utf-8") !== readFileSync(source, "utf-8");
+  }
+
   copyFileSync(source, dest);
   chmodSync(dest, 0o755);
+
+  if (replacedLocalEdit) {
+    console.warn(
+      `[@howells/husky] Replaced .husky/${hook} with the packaged version; your local edits to it are gone.`
+    );
+    console.warn(
+      "  These hooks are intentionally immutable, so a repo cannot weaken its own gate."
+    );
+    console.warn(
+      "  Change them in @howells/husky and publish, or the next install reverts you again."
+    );
+  }
 }
 
 // Step 3: Validate lint-staged config

package/hooks/pre-push

@@ -1,2 +1,58 @@
+#!/usr/bin/env sh
+#
+# Pre-push gate: typecheck and lint before anything reaches a remote.
+#
+# Both checks run against the WORKING DIRECTORY, so their result only describes
+# what is being pushed when the working directory *is* what is being pushed.
+#
+# Git says what is actually being pushed on stdin, one line per ref:
+#
+#     <local ref> <local sha> <remote ref> <remote sha>
+#
+# When a pushed sha is not HEAD - archiving a salvage ref, pushing a branch that
+# is not checked out - the checks would be measuring a different tree. That is
+# neither a pass nor a failure. It is unverifiable, and it is reported as such
+# rather than folded into either, because a gate that reports the wrong tree's
+# result is worse than one that admits it cannot see.
+#
+# This matters most on the rescue path. Work that exists in one place, in a tree
+# that does not typecheck, is exactly what most needs pushing - and the old
+# behaviour failed that push for a reason unrelated to the thing being pushed,
+# leaving `--no-verify` as the only route and disabling every gate at once.
+
+ZERO=0000000000000000000000000000000000000000
+
+head_sha=$(git rev-parse HEAD 2>/dev/null)
+unverifiable=""
+saw_ref=0
+
+while read -r local_ref local_sha _remote_ref _remote_sha; do
+  [ -z "$local_sha" ] && continue
+  saw_ref=1
+
+  # A zero local sha is a branch deletion. Nothing is being added to check.
+  [ "$local_sha" = "$ZERO" ] && continue
+
+  # The common case: pushing the commit that is checked out. The working
+  # directory is the right tree and the checks below describe it.
+  [ "$local_sha" = "$head_sha" ] && continue
+
+  unverifiable="$unverifiable $local_ref"
+done
+
+if [ -n "$unverifiable" ]; then
+  echo "[@howells/husky] Not verified:$unverifiable"
+  echo "  These refs are not HEAD, so typecheck and lint would describe a"
+  echo "  different tree than the one being pushed. Skipped rather than"
+  echo "  reported as passing. Verify on the branch itself, or in CI."
+  exit 0
+fi
+
+# No refs on stdin means git did not tell us what it is pushing. Check anyway:
+# an unverified push is the thing this hook exists to prevent.
+if [ "$saw_ref" = "0" ]; then
+  echo "[@howells/husky] No refs on stdin; checking the working directory."
+fi
+
 pnpm typecheck || exit 1
 pnpm lint || exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/husky",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Standardised git hooks for Howells projects. Immutable pre-commit and pre-push configuration.",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     "lint": "howells-check --config=oxlint.config.ts package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
     "lint:fix": "howells-fix --config=oxlint.config.ts package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
     "format": "howells-oxfmt --write package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
-    "test": "node --test bin/detect.test.mjs"
+    "test": "node --test bin/detect.test.mjs bin/pre-push.test.mjs"
   },
   "dependencies": {
     "husky": "^9.1.7",