Skip to content

feat(repo): A commit with unformatted Rust is refused before it leaves the machine - #38

Merged
sodre merged 4 commits into
mainfrom
t3/foresight-implement-31
Nov 20, 2026
Merged

sodre merged 4 commits into
mainfrom
t3/foresight-implement-31

Conversation

@sodre

@sodre sodre commented Nov 20, 2026

Copy link
Copy Markdown
Member

Closes #31

Summary

A commit whose staged Rust is not formatted, or whose staged package JavaScript fails ESLint, is now refused before it leaves the machine, with the command that fixes it. A Claude session installs the hook when it starts, and scripts/install-git-hooks.sh installs it without Claude. Nothing changes for anyone using the product.

SessionStart (.claude/settings.json)
  scripts/install-git-hooks.sh
    core.hooksPath already .githooks       -> nothing, prints nothing
    another core.hooksPath, or hooks in .git/hooks -> changes nothing, says why
    otherwise                              -> git config core.hooksPath .githooks

git commit
  .githooks/pre-commit
    staged *.rs   -> the staged blob through the pinned rustfmt (rustup which, never installs)
    staged JS that pnpm lint covers -> node_modules/.bin/eslint, or "ESLint skipped" with no node_modules

Choices the ticket left open:

  • Install: core.hooksPath=.githooks, a relative path in the clone's shared config. One run covers every worktree, and each worktree runs its own tracked copy of the hook.
  • Checks beyond cargo fmt: ESLint on the paths the packages' lint scripts give it. It takes 0.2–0.4 s. Other tracked JavaScript has 28 ESLint errors today that pnpm lint never checks, so the hook leaves those files alone too. No Markdown check exists to run.
  • The staged copy, not the working tree: each file is checked from the index, so a partly staged file is judged by what will be committed.
  • The installer never takes over: it leaves another core.hooksPath alone, and it leaves hooks already in .git/hooks alone, symlinks included, because the setting would silently stop them running.
  • A missing tool: without node_modules (a fresh worktree) the hook skips ESLint and says so, since CI runs pnpm lint. A missing pinned Rust toolchain refuses the commit and names rustup show.

Not asked for and here: a CI step runs the hook's tests on Linux, so they do not rot.

Evidence

Criterion Ticked Shown by
A tracked pre-commit hook refuses a commit whose staged Rust files fail cargo fmt --check, and says how to fix it yes A fresh worktree refuses unformatted Rust after session start; the hook checks the staged copy; the live session start below
The hook finishes in under five seconds on a commit of one Rust and one Markdown file, measured and quoted here yes One Rust and one Markdown file commit in under five seconds; the timings below: 0.03 s for the hook, 0.037 s for the whole git commit
The hook runs no build, no test suite and no network call yes The hook runs no build, no test and no network
A session-start hook in .claude/settings.json installs the hook, and is a no-op when already installed yes Session start is a no-op when already installed; the live session start below
A commit in a fresh worktree, after a session start and nothing else, goes through the hook yes A fresh worktree refuses unformatted Rust after session start; the live session start below
docs/develop.md says what the hook checks, how to install it without Claude, and that CI runs the slow checks yes The grep of docs/develop.md below
Test Red Green
A fresh worktree refuses unformatted Rust after session start rustfmt output never compared: AssertionError: 0 == 0; SessionStart command replaced by true: 0 == 0 ok
The hook checks the staged copy, not the working tree working copy formatted instead of the staged blob: 0 == 0 ok
ESLint refuses package JavaScript that fails it ESLint failures ignored: 0 == 0 ok
The hook lints only what pnpm lint lints before the fix: the hook refused distribution/npm/launch.cjs, scripts/tool.mjs, crates/x/tests/addon.cjs ok
Without node_modules the hook skips ESLint and says so note reworded: 'ESLint skipped' not found ok
A pinned toolchain that is not installed is named before the fix: the commit failed with rustup's error and no rustup show ok
One Rust and one Markdown file commit in under five seconds sleep 5 in the hook: 5.038 not less than 5.0 ok
Session start is a no-op when already installed installer always rewrites: 'again\n' != '' ok
Session start leaves another hooks path alone installer overwrites it: '.githooks' != '/elsewhere' ok
Session start leaves hooks in the hooks folder alone, a file and a symlink before the fix: core.hooksPath set over a pre-push hook; with -type f, the symlink subtest failed ok
Session start installs when the hooks folder is a symlink before the fix: refused, naming a hook called hooks ok
The hook runs no build, no test and no network hook calls cargo --version: cargo --version logged; hook opens /dev/tcp/127.0.0.1/9: connect(3, {sa_family=AF_INET ... ok

python3 -m unittest discover -s scripts -p test_git_hooks.py on d57cbef: 12 tests, 12 passed, 0 skipped, 0 failed. Each test copies the hook's files into a throwaway repository and a fresh git worktree of it.

Live session start: a git clone --no-local of this branch into a scratch folder, then git worktree add --detach fresh. core.hooksPath before: empty. claude -p "Reply with the single word OK." in fresh printed OK. core.hooksPath after: .githooks. In fresh, an unformatted crates/countersign-protocol/src/zz.rs was refused with exit 1:

pre-commit: these staged Rust files are not formatted:
  crates/countersign-protocol/src/zz.rs
Run 'cargo fmt --all', then 'git add' them again.
pre-commit: commit refused. 'git commit --no-verify' skips this hook.

The formatted zz.rs plus README.md committed with exit 0 in real 0m0.037s.

Timing of the hook alone (/usr/bin/time .githooks/pre-commit, staged crates/countersign-gateway/src/worker_sandbox.rs, 363 lines, and docs/develop.md): 0.03 s, 0.03 s, 0.03 s. With packages/widget/src/widget.js added, which runs ESLint: 0.44 s. With 61 Rust files: 0.93 s.

grep of docs/develop.md: line 30 "It refuses a commit when a staged Rust file is not formatted as cargo fmt would format it, and when a staged JavaScript file that pnpm lint covers fails ESLint"; line 32 "Without Claude, install it once per clone from the checkout root:" followed by scripts/install-git-hooks.sh; line 30 "Clippy, the test suites and the Gateway's runtime test run in the [CI workflow]".

Not run: the hook on macOS and Windows (its tests run on Linux only; it is written for macOS's bash 3.2 but nothing runs it there); the new CI step, which runs on this pull request; a review round on d57cbef, the fix to round 3's finding (the owner chose to open the pull request after three rounds).

Merge Danger

Door: two-way. A revert removes the hook and the SessionStart entry. A clone where a session already set core.hooksPath=.githooks then points at a folder that no longer exists, so git runs no hooks there. git config --unset core.hooksPath restores .git/hooks.

Blast Radius: tooling only.

No image, infrastructure or flag. After the merge, every Claude session in a clone of this repository sets core.hooksPath the first time it starts, unless the clone already has one or holds hooks in .git/hooks. Worktrees on branches without .githooks/ then run no pre-commit hook until they rebase.

Reviews

Correctness, Standards, Spec and Security, three rounds: 18 findings, each with its outcome

Correctness, round 1

  1. ESLint ran on every staged JavaScript file, but pnpm lint covers only the packages and the demo Integrator, and the rest has 28 errors today. Fixed: the hook lints only those paths.
  2. Linked worktrees have no node_modules, so ESLint is skipped there. Pushed back: eslint.config.mjs imports @eslint/js from the worktree, so another checkout's ESLint cannot load it. CI runs pnpm lint, and the hook says ESLint was skipped.
  3. Setting core.hooksPath silently stops hooks in .git/hooks. Fixed: the installer changes nothing and names them.
  4. ./.githooks or an absolute path is reported as another hooks path. Pushed back: the message is true (the value differs from the one the script writes) and harmless, and the hook still runs.
  5. The pinned toolchain was parsed and resolved once per staged file. Fixed: rustfmt is found once (61 files: 1.32 s, then 0.93 s).
  6. A missing pinned toolchain refuses every Rust commit with only rustup's error. Fixed: the hook names the toolchain and rustup show.
  7. --diff-filter=ACMR skips a path whose type changed. Pushed back: no tracked file is a symlink, and CI's cargo fmt --all -- --check still catches it.
  8. The five-second timing test could flake on a loaded runner. Pushed back: the commit takes 0.04 s, a hundredth of the bound.
  9. Nothing tests the bash 3.2 claim on macOS. Pushed back: macOS runners put Homebrew's bash first on PATH, so a macOS job would not run 3.2 either. The comment guides editors.
  10. The no-network test copied the commit helper's staging loop. Fixed: a stage helper and a command prefix.

Standards, round 1

  1. The docs said CI runs the checks "as listed above", and the list says nothing about CI. Fixed: the docs name the CI workflow and the end-to-end workflow, and so does the hook's comment.
  2. "Well under a second" is not backed by the five-second test. Pushed back: the Evidence measures 0.03–0.44 s.
  3. "Its tests" pointed at the script. Fixed: "The tests for the hook and the script".
  4. Duplicated staging code in the tests. Fixed: as in 10.
  5. whole, partial and lint were vague names. Fixed: js_whole, js_partial, eslint_failed.

Spec, round 1

  1. The CI step is not asked for. Pushed back: the hook's tests must run somewhere or they rot, and the step adds one Linux step.

Correctness, round 2

  1. The installer's check missed a hook in .git/hooks that is a symlink. Fixed: it counts anything that is not a folder.

Spec, round 3

  1. That fix made the installer refuse a clone whose .git/hooks is itself a symlink. Fixed: find lists the folder's contents through a trailing slash (d57cbef, which no round has read).

Tracking

Epic: none
Spec: none
Ticket: #31 A fast pre-commit hook installs itself when a Claude session starts
Flag: none

🤖 Generated with Claude Code

sodre and others added 4 commits November 20, 2026 02:20
…s the machine

A tracked pre-commit hook in .githooks/ checks the staged copy of each
Rust file with rustfmt and each staged JavaScript file with ESLint. It
runs no build, no test and no network call; CI keeps those. A Claude
session installs it at start by setting core.hooksPath, which covers
every worktree of the clone. docs/develop.md says how to install it
without Claude.

Refs #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…des no existing hook

ESLint in the hook now takes the paths the packages' lint scripts give
it, so a commit touching tracked JavaScript that pnpm lint never checks
is not refused for lint debt CI accepts. The installer leaves
core.hooksPath unset when the clone's hooks folder holds hooks of its
own, which the setting would stop running. The hook finds the pinned
rustfmt once, and names the toolchain to install when it is missing.

Refs #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ks folder running

Hook managers often install a hook in .git/hooks as a symlink. The
installer's check looked only for regular files, so it set
core.hooksPath and stopped such a hook running.

Refs #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…is a symlink

find does not follow a symlink given as its starting point, so a
symlinked .git/hooks was itself reported as a hook and the installer
refused. A trailing slash makes find list the folder's contents.

Refs #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sodre
sodre marked this pull request as ready for review November 20, 2026 07:59
@sodre
sodre merged commit e8c5a9f into main Nov 20, 2026
34 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A fast pre-commit hook installs itself when a Claude session starts

1 participant