Skip to content

Commit cd0d33f

Browse files
wpfleger96Duncan
andauthored
fix(hooks): scope pre-push lanes to branch merge-base diff (#6423)
Lefthook selected pre-push lanes from the file set `git diff --name-only HEAD @{push}` returns, which is overinclusive two different ways: - **Rebase/merge poisoning.** `@{push}` is a two-dot diff against the branch's last-pushed tip. After a rebase onto newer main — or the `git merge origin/main` that `check-branch-skew.sh` itself instructs agents to run — that diff includes everything `main` changed since the last push, so `mobile-checks`, the `desktop-*` lanes, and `rust-tests` fire on branches that never touched those trees (a recent relay-only push discovered 266 files, 26 of them `mobile/`). - **Brand-new branch in a worktree.** When `@{push}` doesn't resolve, lefthook reads `$GIT_DIR/refs/remotes/origin/HEAD` — which doesn't exist in a linked worktree's git-dir — then falls back to the alphabetically-first `HEAD ->` remote. In a clone with a stale third-party remote sorted before `origin`, that diffs against a frozen tip and runs the full suite. All agent work happens in worktrees. ## Fix Add `files: git diff --name-only origin/main...HEAD` to the six globbed pre-push lanes (`rust-tests`, `desktop-check`, `desktop-typecheck`, `desktop-test`, `desktop-tauri-checks`, `mobile-checks`). The three-dot form is the branch's merge-base diff against `origin/main` — the same base resolution `scripts/check-file-sizes-core.mjs` (`resolveBaseRef`) and CI's dorny/paths-filter already use. A lane now fires only when this branch actually changed a file it covers; `main`-side changes never re-trigger it, and a new branch diffs against `origin/main` (empty diff → all globbed lanes skip) rather than a stale remote. `branch-skew` and `file-size-check` stay unfiltered by design. Also pin hook dispatch to the Hermit-managed lefthook. The generated `.git/hooks/*` dispatchers prefer `$LEFTHOOK_BIN`, then a `lefthook` on `PATH` — so a Homebrew lefthook shadowed the pinned 2.1.3. A `rc: bin/.lefthookrc` (a lefthook config key `lefthook install` bakes into every dispatcher) exports `LEFTHOOK_BIN` to `bin/lefthook`, so a push runs the pinned version regardless of `PATH`. `just hooks` already runs `lefthook install`, so re-running it picks up the `rc` line — no recipe change needed. `AGENTS.md` documents that lanes are scoped by merge-base diff and that agent shells should lead `PATH` with `./bin` so pinned tools win. ## Verification Reproduced both bugs in a scratch repo mirroring the worktree + stale-remote topology, with lanes stubbed to echo on selection: - **Bug 1:** relay-only branch, `git merge origin/main` (main carried `mobile/` + `desktop/` changes). Without the fix, `desktop-check` and `mobile-checks` fired; with it, three-dot diff = only the relay file, all globbed lanes skip. - **Bug 2:** brand-new branch, no upstream, in a linked worktree with an alphabetically-first stale remote. Confirmed `@{push}` is `fatal`, `refs/remotes/origin/HEAD` is absent from the worktree git-dir, and the stale remote's `HEAD ->` sorts first. Without the fix it fired lanes off the stale tip; with it, lanes scope to `origin/main` merge-base and skip. - **Positive controls:** a `mobile/**` commit still fires `mobile-checks`; a `crates/**` commit still fires `rust-tests` + `desktop-tauri-checks`. - **Dispatch:** with Homebrew lefthook 2.1.10 on `PATH`, running the real generated `.git/hooks/pre-push` under `LEFTHOOK_VERBOSE=1` shows it sourcing `bin/.lefthookrc`, exporting `LEFTHOOK_BIN`, and running `lefthook v2.1.3`. - This PR's own push (a brand-new branch in a linked worktree — the bug 2 case) ran only `branch-skew` and `file-size-check`; no mobile/desktop/rust lanes fired, since the branch touches only `lefthook.yml`, `AGENTS.md`, and `bin/.lefthookrc`. --------- Signed-off-by: Will Pfleger <[email protected]> Signed-off-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz> Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
1 parent 3ee465e commit cd0d33f

4 files changed

Lines changed: 117 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -125,9 +125,22 @@ clippy (workspace + Tauri), desktop TypeScript typechecking (`tsc --noEmit`),
125125
and fast unit tests in parallel (Rust, desktop JS, Tauri Rust, mobile Flutter)
126126
— no overlap with pre-commit. Builds are CI-only. Run `just fix-all` to auto-fix
127127
all formatting in one shot. Run `just ci` for the full local gate. Run `just
128-
hooks` to re-install hooks after env changes. Before agents run Git or hooks,
129-
activate the repo's Hermit environment (`. ./bin/activate-hermit`); do not
130-
rewrite hook commands to compensate for an unconfigured shell `PATH`.
128+
hooks` to re-install hooks after env changes. Each globbed pre-push lane is
129+
scoped to the branch's merge-base diff against `origin/main` (`git diff
130+
origin/main...HEAD`), matching CI's paths-filter — so a lane only fires when this
131+
branch actually changed a file it covers, never because `origin/main` moved.
132+
These lanes validate the checked-out HEAD; pushing a non-HEAD ref (explicit
133+
refspec, `--all`) gets a non-fatal `push-head-scope` warning and relies on CI for
134+
its path-scoped checks.
135+
Before agents run Git or hooks, activate the repo's Hermit environment
136+
(`. ./bin/activate-hermit`) so `./bin` leads `PATH` and the pinned toolchain
137+
(flutter, dart, lefthook) wins over any Homebrew version; do not
138+
rewrite hook commands to compensate for an unconfigured shell `PATH`. The
139+
pre-push hook self-pins regardless: `bin/.lefthookrc` (sourced by the generated
140+
`.git/hooks/*`) prepends the Hermit `bin/` to `PATH` and pins `LEFTHOOK_BIN`, so
141+
lane subprocesses resolve the pinned flutter/dart/lefthook even when an
142+
unactivated shell has Homebrew first. Activating Hermit remains recommended for
143+
non-hook commands.
131144

132145
**Commit with `git commit -s`.** The required **DCO Check** fails any PR with a commit missing a `Signed-off-by` trailer, and `just hooks` installs a `commit-msg` hook that adds it to commits you create locally (`git rebase` and `git cherry-pick` still need `--signoff`) — if you build commit commands programmatically, include `-s` every time. To repair a branch that already has unsigned commits: `git rebase --signoff main`, then force-push.
133146

‎bin/.lefthookrc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Sourced by the generated .git/hooks/* dispatchers (see `rc:` in lefthook.yml)
2+
# before their $LEFTHOOK_BIN-first lookup. Two jobs, both anchored on the repo
3+
# root so they hold regardless of the hook's working dir:
4+
# 1. Pin dispatch to the Hermit-managed lefthook (bin/lefthook ->
5+
# .lefthook-2.1.3.pkg) so a push from any worktree runs the pinned version
6+
# even when a newer lefthook is on PATH (e.g. Homebrew).
7+
# 2. Prepend the Hermit bin/ to PATH so every lane subprocess (just mobile-check
8+
# -> flutter/dart, etc.) resolves the repo's pinned toolchain, not whatever
9+
# the invoking shell had first (e.g. Homebrew flutter). This is the safe
10+
# subset of `activate-hermit`: a plain PATH prepend, no interactive-shell
11+
# machinery. It makes the hook self-pinning regardless of shell setup.
12+
_lefthook_root="$(git rev-parse --show-toplevel 2>/dev/null)"
13+
if [ -n "$_lefthook_root" ] && [ -d "$_lefthook_root/bin" ]; then
14+
PATH="$_lefthook_root/bin:$PATH"
15+
export PATH
16+
if [ -x "$_lefthook_root/bin/lefthook" ]; then
17+
LEFTHOOK_BIN="$_lefthook_root/bin/lefthook"
18+
export LEFTHOOK_BIN
19+
fi
20+
fi
21+
unset _lefthook_root

‎lefthook.yml‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,18 @@
11
# Glob patterns below mirror the `changes` job's dorny/paths-filter groups in
2-
# .github/workflows/ci.yml — keep the two in sync. Deliberate deviations:
2+
# .github/workflows/ci.yml — keep the two in sync. Each globbed pre-push lane
3+
# also sets `files: git diff --name-only origin/main...HEAD` so its file set is
4+
# the branch's merge-base diff against origin/main — the same semantics as CI's
5+
# dorny/paths-filter and `scripts/check-file-sizes-core.mjs` `resolveBaseRef`.
6+
# Without it lefthook derives files from `git diff HEAD @{push}`, which after a
7+
# rebase or `git merge origin/main` includes everything main changed since the
8+
# branch's last push (firing mobile/desktop/rust lanes on unrelated pushes), and
9+
# on a brand-new branch falls back to a stale remote's tip (a full-suite run).
10+
# The three-dot diff scopes every lane to what this branch actually changed.
11+
# Both the three-dot diff and lefthook's stock discovery inspect the checked-out
12+
# HEAD, so pushing a non-HEAD ref (explicit refspec, `--all`) validates HEAD's
13+
# tree, not the pushed commit — the always-on `push-head-scope` lane warns when
14+
# they diverge and CI remains the authoritative gate for that ref.
15+
# Deliberate deviations:
316
# - The `.github/workflows/ci.yml` path CI adds to its `rust`/`mobile` filters
417
# is omitted; a CI-workflow-only edit doesn't need a local test run.
518
# - `desktop-check`/`desktop-typecheck`/`desktop-test` don't trigger on `rust`
@@ -16,6 +29,17 @@
1629
# - `commit-msg` has no glob: it rewrites the commit message, not files. Note
1730
# Git only runs it for `git commit` and `git merge` — other flows need their own
1831
# flag: `git rebase --signoff`, `git cherry-pick -s`.
32+
#
33+
# `rc` points `lefthook install` at `bin/.lefthookrc`, which the generated
34+
# `.git/hooks/*` dispatchers source before their `$LEFTHOOK_BIN`-first lookup. It
35+
# (1) sets `LEFTHOOK_BIN` to the Hermit-pinned `bin/lefthook` (2.1.3) so a push
36+
# from any worktree runs the pinned binary even when a different lefthook is on
37+
# PATH, and (2) prepends the repo's Hermit `bin/` to `PATH` so every lane
38+
# subprocess (`just mobile-check` -> flutter/dart, etc.) resolves the pinned
39+
# toolchain regardless of the invoking shell — the hook self-pins, so a Homebrew
40+
# flutter/dart ahead on PATH can no longer cause false lane failures.
41+
rc: bin/.lefthookrc
42+
1943
pre-commit:
2044
parallel: true
2145
commands:
@@ -56,33 +80,46 @@ pre-push:
5680
commands:
5781
branch-skew:
5882
run: ./scripts/check-branch-skew.sh
83+
push-head-scope:
84+
# Warn-only: the scoped lanes below validate the checked-out HEAD, so a
85+
# non-HEAD ref push (explicit refspec, --all) relies on CI for its
86+
# path-scoped checks. This lane reads the pushed refs from stdin and
87+
# warns when any pushed commit is not HEAD. It never fails the push.
88+
use_stdin: true
89+
run: ./scripts/check-push-head-scope.sh
5990
file-size-check:
6091
# The ratchet computes its own merge-base diff, so path filtering here
6192
# would only duplicate policy and create another place for coverage drift.
6293
run: just file-size-check
6394
rust-tests:
95+
files: git diff --name-only origin/main...HEAD
6496
glob: ["crates/**", "migrations/**", "schema/**", "Cargo.toml", "Cargo.lock", "rust-toolchain.toml", "deny.toml", "scripts/run-tests.sh", "Justfile"]
6597
run: just test-unit
6698
desktop-check:
99+
files: git diff --name-only origin/main...HEAD
67100
glob: ["desktop/**", "pnpm-lock.yaml"]
68101
exclude: ["desktop/src-tauri/**"]
69102
run: just desktop-check
70103
desktop-typecheck:
104+
files: git diff --name-only origin/main...HEAD
71105
glob: ["desktop/**", "pnpm-lock.yaml"]
72106
exclude: ["desktop/src-tauri/**"]
73107
run: just desktop-typecheck
74108
desktop-test:
109+
files: git diff --name-only origin/main...HEAD
75110
glob: ["desktop/**", "pnpm-lock.yaml"]
76111
exclude: ["desktop/src-tauri/**"]
77112
run: just desktop-test
78113
desktop-tauri-checks:
79114
# Keep local lint parity with Desktop Core CI for every path that can
80115
# affect the Tauri crate or its path dependencies. Run clippy and tests
81116
# serially so parallel pre-push hooks do not contend for Cargo's lock.
117+
files: git diff --name-only origin/main...HEAD
82118
glob: ["desktop/src-tauri/**", "crates/**", "migrations/**", "schema/**", "Cargo.toml", "Cargo.lock", "rust-toolchain.toml", "deny.toml", "scripts/run-tests.sh", "Justfile"]
83119
run: just desktop-tauri-clippy && just desktop-tauri-test
84120
mobile-checks:
85121
# Run analysis and tests serially so parallel pre-push hooks do not
86122
# contend for shared Flutter state (.dart_tool, shader bundle).
123+
files: git diff --name-only origin/main...HEAD
87124
glob: ["mobile/**"]
88125
run: just mobile-check && just mobile-test

‎scripts/check-push-head-scope.sh‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/usr/bin/env bash
2+
# Pre-push scope signal (warn-only, never fails the push).
3+
#
4+
# The scoped pre-push lanes derive their file set from `git diff origin/main...HEAD`,
5+
# and lefthook's own stock discovery is `git diff HEAD @{push}` — both inspect the
6+
# checked-out HEAD, not the SHAs actually being pushed. Pushing a non-checked-out
7+
# ref (e.g. `git push origin other-branch`, an explicit refspec, or `--all`) can
8+
# therefore run the scoped lanes against HEAD while pushing a different commit, so
9+
# the pushed ref's path-scoped checks are only exercised by CI.
10+
#
11+
# This lane reads the pre-push stdin refspecs and prints a loud, non-fatal warning
12+
# naming each pushed ref whose commit is not the checked-out HEAD. It never blocks
13+
# the push; CI remains the authoritative gate for a non-HEAD ref.
14+
#
15+
# Stdin format (one line per ref, git-provided):
16+
# <local_ref> <local_sha> <remote_ref> <remote_sha>
17+
set -euo pipefail
18+
19+
head_sha=$(git rev-parse HEAD 2>/dev/null) || exit 0
20+
21+
divergent=""
22+
while read -r local_ref local_sha remote_ref remote_sha; do
23+
# Empty stdin (up-to-date push with no refs) or malformed line: skip.
24+
[ -n "${local_sha:-}" ] || continue
25+
# Deletion push (local sha is all-zeros): nothing built locally to validate.
26+
case "$local_sha" in *[!0]*) : ;; *) continue ;; esac
27+
# Pushed commit equals the checked-out HEAD: scoped lanes validated it.
28+
[ "$local_sha" = "$head_sha" ] && continue
29+
divergent="${divergent} ${local_ref:-?} -> ${remote_ref:-?} ($(git rev-parse --short "$local_sha" 2>/dev/null || echo "$local_sha"))
30+
"
31+
done
32+
33+
if [ -n "$divergent" ]; then
34+
{
35+
echo "Pushing commits that are not the checked-out HEAD:"
36+
printf '%s' "$divergent"
37+
echo "Local scoped lanes validated HEAD only; these refs rely on CI for"
38+
echo "path-scoped checks. This is a warning, not a failure."
39+
} >&2
40+
fi
41+
42+
exit 0

0 commit comments

Comments
 (0)