diff --git a/.claude/settings.json b/.claude/settings.json index 696cea6..6b85023 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -3,5 +3,17 @@ "foresight@foresight-vendored": true, "superpowers@foresight-vendored": false, "mattpocock-skills@foresight-vendored": false + }, + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/install-git-hooks.sh" + } + ] + } + ] } } diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000..7a66487 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,105 @@ +#!/usr/bin/env bash +# Fast checks on the staged change only: rustfmt on staged Rust files and +# ESLint on the staged JavaScript that `pnpm lint` covers. No build, no test +# suite and no network call: the CI workflow (.github/workflows/ci.yml) runs +# those. +# Written for bash 3.2, the bash macOS ships. +set -uo pipefail + +cd "$(git rev-parse --show-toplevel)" || exit 1 +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT +status=0 + +staged() { + git diff --cached --name-only -z --diff-filter=ACMR -- "$@" +} + +# The rustfmt of the toolchain rust-toolchain.toml pins, found once. `rustup +# which` fails on a toolchain that is not installed, where the rustfmt proxy +# would download it. +find_rustfmt() { + if command -v rustup >/dev/null 2>&1; then + local channel + channel=$(sed -n 's/^channel *= *"\(.*\)"/\1/p' rust-toolchain.toml) + if ! rustup which --toolchain "$channel" rustfmt 2>/dev/null; then + echo "pre-commit: rustfmt of the pinned toolchain $channel is not installed. Run 'rustup show' in the checkout, which installs it, then commit again." >&2 + return 1 + fi + else + command -v rustfmt || { echo "pre-commit: rustfmt is not installed." >&2; return 1; } + fi +} + +# rustfmt reads each staged blob on stdin, so a file whose working copy differs +# from what is staged is judged by what will be committed. +rust_files=() +while IFS= read -r -d '' file; do + rust_files+=("$file") +done < <(staged '*.rs') + +if [ ${#rust_files[@]} -gt 0 ]; then + if ! rustfmt=$(find_rustfmt); then + status=1 + else + edition=$(sed -n 's/^edition *= *"\(.*\)"/\1/p' Cargo.toml | head -n 1) + unformatted=() + for file in "${rust_files[@]}"; do + git show ":$file" >"$tmp/in" + if ! "$rustfmt" --edition "$edition" --emit stdout <"$tmp/in" >"$tmp/out" 2>"$tmp/err"; then + echo "pre-commit: rustfmt could not check $file:" >&2 + cat "$tmp/err" >&2 + status=1 + elif ! cmp -s "$tmp/in" "$tmp/out"; then + unformatted+=("$file") + fi + done + if [ ${#unformatted[@]} -gt 0 ]; then + echo "pre-commit: these staged Rust files are not formatted:" >&2 + printf ' %s\n' "${unformatted[@]}" >&2 + echo "Run 'cargo fmt --all', then 'git add' them again." >&2 + status=1 + fi + fi +fi + +# The paths the packages' lint scripts give ESLint, which `pnpm lint` runs. +# Other tracked JavaScript is not lint-clean, so the hook leaves it alone too. +# A file whose working copy matches the index is linted in one run; a partly +# staged file is linted from its staged blob on stdin. +js_whole=() +js_partial=() +while IFS= read -r -d '' file; do + if git diff --quiet -- "$file"; then + js_whole+=("$file") + else + js_partial+=("$file") + fi +done < <(staged \ + ':(glob)packages/*/src/**/*.js' ':(glob)packages/*/src/**/*.mjs' ':(glob)packages/*/src/**/*.cjs' \ + ':(glob)packages/*/test/**/*.js' ':(glob)packages/*/test/**/*.mjs' ':(glob)packages/*/test/**/*.cjs' \ + ':(glob)examples/demo-integrator/*.js' ':(glob)examples/demo-integrator/site/*.js') + +if [ $((${#js_whole[@]} + ${#js_partial[@]})) -gt 0 ]; then + eslint=node_modules/.bin/eslint + if [ ! -x "$eslint" ]; then + echo "pre-commit: ESLint skipped, no node_modules here; run 'pnpm install' to lint staged JavaScript. CI runs 'pnpm lint'." >&2 + else + eslint_failed=0 + if [ ${#js_whole[@]} -gt 0 ]; then + "$eslint" --no-warn-ignored -- "${js_whole[@]}" >&2 || eslint_failed=1 + fi + for file in ${js_partial[@]+"${js_partial[@]}"}; do + git show ":$file" | "$eslint" --no-warn-ignored --stdin --stdin-filename "$file" >&2 || eslint_failed=1 + done + if [ $eslint_failed -ne 0 ]; then + status=1 + echo "Fix what ESLint reports ('pnpm lint' lints the same files), then 'git add' them again." >&2 + fi + fi +fi + +if [ $status -ne 0 ]; then + echo "pre-commit: commit refused. 'git commit --no-verify' skips this hook." >&2 +fi +exit $status diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b00851c..c9090fe 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,6 +27,9 @@ jobs: - run: pnpm lint - run: pnpm test - run: rustup show + - name: Pre-commit hook tests + if: runner.os == 'Linux' + run: python3 -m unittest discover -s scripts -p 'test_git_hooks.py' - if: runner.os == 'Linux' run: sudo apt-get update && sudo apt-get install -y bubblewrap - run: cargo fmt --all -- --check diff --git a/docs/develop.md b/docs/develop.md index 439455a..324f8a8 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -25,6 +25,22 @@ pnpm lint pnpm test ``` +### The pre-commit hook + +A tracked pre-commit hook, `.githooks/pre-commit`, runs fast checks on what you stage. 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: the packages' `src` and `test` folders and the demo Integrator. It checks the staged copy of each file, not the one in your working tree. When `node_modules` is missing it skips ESLint and says so. It finishes in well under a second. It runs no build, no test suite and no network call. Clippy, the test suites and the Gateway's runtime test run in the [CI workflow](https://github.com/zeroae/countersign/blob/main/.github/workflows/ci.yml) and the end-to-end workflow. + +A Claude session installs the hook when it starts, through the `SessionStart` hook in `.claude/settings.json`. Without Claude, install it once per clone from the checkout root: + +```sh +scripts/install-git-hooks.sh +``` + +The script sets `core.hooksPath` to `.githooks`. That setting covers every worktree of the clone, and each worktree runs its own tracked copy of the hook. If `core.hooksPath` already points elsewhere, or the clone's `.git/hooks` folder holds hooks of its own, which `core.hooksPath` would stop running, the script changes nothing and says so. To skip the hook for one commit, run `git commit --no-verify`. The tests for the hook and the script are in `scripts/test_git_hooks.py`: + +```sh +python3 -m unittest discover -s scripts -p 'test_git_hooks.py' +``` + To run the Gateway's tests under the filter sandbox on a host that refuses namespaces, run `scripts/filter-sandbox-container.sh`, which needs Docker. It runs the containment test and the runtime test in a container under Docker's default security profile, as the end-to-end workflow's `gateway-filter-sandbox` job does. Its two last steps use a profile with one quirk each: where the host refuses the allow-list, the filter sandbox has to fail at startup by name, and where the kernel has no `close_range`, a grant worker still has to start with no descriptor of the supervisor's. That container has the CI runner's kernel. To run the same two tests on real ECS Fargate 1.4.0, x86-64 and arm64, use the qualification harness, `qualification/fargate/run.sh`. It needs our AWS account, and its [README](https://github.com/zeroae/countersign/blob/main/qualification/fargate/README.md) says how to deploy, run and tear it down. Run it for every release that touches the grant worker. diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh new file mode 100755 index 0000000..489be7a --- /dev/null +++ b/scripts/install-git-hooks.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# Points this clone at the tracked hooks in .githooks/. core.hooksPath lives in +# the clone's shared config, so one run covers every worktree, and a relative +# path makes each worktree run its own tracked copy of the hooks. +# A Claude session runs this at start (.claude/settings.json). It prints nothing +# when the hooks are already installed. It never replaces another hooks path, +# and never hides hooks already in the clone's hooks folder, which core.hooksPath +# would stop running. +set -euo pipefail + +cd "$(dirname "$0")/.." +git rev-parse --git-dir >/dev/null 2>&1 || exit 0 + +current=$(git config --get core.hooksPath || true) +case "$current" in + .githooks) ;; + "") + hooks=$(git rev-parse --path-format=absolute --git-common-dir)/hooks + existing=$(find "$hooks/" -maxdepth 1 ! -type d ! -name '*.sample' -exec basename {} \; 2>/dev/null | sort | tr '\n' ' ') + if [ -n "$existing" ]; then + echo "$hooks holds hooks (${existing% }) that core.hooksPath would stop running, so the pre-commit hook in .githooks/ is not installed. Move them into .githooks/ or elsewhere, then run scripts/install-git-hooks.sh." >&2 + exit 0 + fi + git config core.hooksPath .githooks + echo "Installed the pre-commit hook: core.hooksPath is now .githooks." + ;; + *) + echo "core.hooksPath is already '$current', so the pre-commit hook in .githooks/ is not installed. To use it: git config core.hooksPath .githooks" >&2 + ;; +esac diff --git a/scripts/test_git_hooks.py b/scripts/test_git_hooks.py new file mode 100644 index 0000000..19b0c09 --- /dev/null +++ b/scripts/test_git_hooks.py @@ -0,0 +1,238 @@ +"""The tracked pre-commit hook and the session-start command that installs it. + +Each test copies the hook's files into a throwaway repository, so nothing here +touches the checkout's own Git configuration. +""" + +import json +import os +import shutil +import subprocess +import tempfile +import time +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +FILES = [ + ".githooks/pre-commit", + "scripts/install-git-hooks.sh", + ".claude/settings.json", + "rust-toolchain.toml", + "Cargo.toml", + "eslint.config.mjs", +] +UNFORMATTED = "fn main(){let x=1;}\n" +FORMATTED = "fn main() {\n let x = 1;\n}\n" + + +def git_env(extra=None): + env = dict(os.environ) + for key in list(env): + if key.startswith("GIT_"): + del env[key] + env.update( + GIT_CONFIG_GLOBAL=os.devnull, + GIT_CONFIG_NOSYSTEM="1", + GIT_AUTHOR_NAME="Test", + GIT_AUTHOR_EMAIL="test@example.invalid", + GIT_COMMITTER_NAME="Test", + GIT_COMMITTER_EMAIL="test@example.invalid", + ) + env.update(extra or {}) + return env + + +def run(args, cwd, env=None, check=True): + result = subprocess.run( + args, cwd=cwd, env=env or git_env(), capture_output=True, text=True, timeout=60 + ) + if check and result.returncode != 0: + raise AssertionError(f"{args} failed:\n{result.stdout}\n{result.stderr}") + return result + + +def session_start_commands(): + settings = json.loads((ROOT / ".claude/settings.json").read_text()) + return [ + hook["command"] + for entry in settings["hooks"]["SessionStart"] + for hook in entry["hooks"] + if hook["type"] == "command" + ] + + +class GitHooksTests(unittest.TestCase): + def setUp(self): + self.tmp = Path(tempfile.mkdtemp()) + self.addCleanup(shutil.rmtree, self.tmp, ignore_errors=True) + self.main = self.tmp / "main" + self.main.mkdir() + run(["git", "init", "-q", "-b", "main"], self.main) + for name in FILES: + target = self.main / name + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(ROOT / name, target) + run(["git", "add", "-A"], self.main) + run(["git", "commit", "-q", "-m", "init"], self.main) + self.worktree = self.tmp / "fresh" + run(["git", "worktree", "add", "-q", "--detach", str(self.worktree)], self.main) + + def start_session(self, directory): + outputs = [] + for command in session_start_commands(): + result = run( + ["bash", "-c", command], + directory, + env=git_env({"CLAUDE_PROJECT_DIR": str(directory)}), + ) + outputs.append(result.stdout + result.stderr) + return "".join(outputs) + + def stage(self, files): + for name, text in files.items(): + path = self.worktree / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + run(["git", "add", "--", *files], self.worktree) + + def commit(self, files, env=None, prefix=()): + self.stage(files) + args = [*prefix, "git", "commit", "-q", "-m", "change"] + return run(args, self.worktree, env=env, check=False) + + def test_fresh_worktree_refuses_unformatted_rust_after_session_start(self): + self.start_session(self.worktree) + result = self.commit({"src/lib.rs": UNFORMATTED}) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("src/lib.rs", result.stderr) + self.assertIn("cargo fmt", result.stderr) + + def test_hook_checks_the_staged_copy_not_the_working_tree(self): + self.start_session(self.worktree) + (self.worktree / "src").mkdir() + (self.worktree / "src/lib.rs").write_text(UNFORMATTED) + run(["git", "add", "src/lib.rs"], self.worktree) + (self.worktree / "src/lib.rs").write_text(FORMATTED) + result = run(["git", "commit", "-q", "-m", "change"], self.worktree, check=False) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + + def link_node_modules(self): + node_modules = ROOT / "node_modules" + if not (node_modules / ".bin/eslint").exists(): + common = run(["git", "rev-parse", "--path-format=absolute", "--git-common-dir"], ROOT) + node_modules = Path(common.stdout.strip()).parent / "node_modules" + if not (node_modules / ".bin/eslint").exists(): + self.fail("ESLint is not installed: run 'pnpm install' in this checkout") + (self.worktree / "node_modules").symlink_to(node_modules) + + def test_hook_refuses_javascript_that_fails_eslint(self): + self.start_session(self.worktree) + self.link_node_modules() + result = self.commit({"packages/widget/src/bad.js": "undefinedName();\n"}) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("no-undef", result.stderr) + run(["git", "rm", "-q", "--cached", "packages/widget/src/bad.js"], self.worktree) + good = self.commit({"packages/widget/src/good.js": "export const x = 1;\n"}) + self.assertEqual(good.returncode, 0, good.stdout + good.stderr) + + def test_hook_lints_only_what_pnpm_lint_lints(self): + self.start_session(self.worktree) + self.link_node_modules() + for name in ["distribution/npm/launch.cjs", "scripts/tool.mjs", "crates/x/tests/addon.cjs"]: + with self.subTest(name=name): + result = self.commit({name: "undefinedName();\n"}) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + + def test_hook_without_node_modules_skips_eslint_and_says_so(self): + self.start_session(self.worktree) + result = self.commit({"packages/widget/src/bad.js": "undefinedName();\n"}) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("ESLint skipped", result.stderr) + + def test_hook_names_a_pinned_toolchain_that_is_not_installed(self): + toolchain = self.worktree / "rust-toolchain.toml" + toolchain.write_text(toolchain.read_text().replace("1.99.0", "0.0.1")) + run(["git", "commit", "-q", "-am", "pin a missing toolchain"], self.worktree) + self.start_session(self.worktree) + result = self.commit({"src/lib.rs": FORMATTED}) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("0.0.1", result.stderr) + self.assertIn("rustup show", result.stderr) + + def test_one_rust_and_one_markdown_file_commit_in_under_five_seconds(self): + self.start_session(self.worktree) + started = time.monotonic() + result = self.commit({"src/lib.rs": FORMATTED, "NOTES.md": "# Notes\n\nText.\n"}) + elapsed = time.monotonic() - started + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + print(f"\npre-commit: one .rs and one .md file committed in {elapsed:.2f} s") + self.assertLess(elapsed, 5.0) + + def test_session_start_is_a_no_op_when_already_installed(self): + self.start_session(self.worktree) + config = (self.main / ".git/config").read_text() + self.assertEqual(self.start_session(self.worktree), "") + self.assertEqual((self.main / ".git/config").read_text(), config) + + def test_session_start_leaves_another_hooks_path_alone(self): + run(["git", "config", "core.hooksPath", "/elsewhere"], self.main) + output = self.start_session(self.worktree) + self.assertIn("/elsewhere", output) + hooks_path = run(["git", "config", "core.hooksPath"], self.main).stdout.strip() + self.assertEqual(hooks_path, "/elsewhere") + + def test_session_start_leaves_hooks_in_the_hooks_folder_alone(self): + target = self.tmp / "managed-hook" + target.write_text("#!/bin/sh\nexit 0\n") + target.chmod(0o755) + for kind in ["file", "symlink"]: + with self.subTest(kind=kind): + hook = self.main / ".git/hooks/pre-push" + hook.unlink(missing_ok=True) + if kind == "file": + shutil.copy2(target, hook) + else: + hook.symlink_to(target) + output = self.start_session(self.worktree) + self.assertIn("pre-push", output) + unset = run(["git", "config", "core.hooksPath"], self.main, check=False) + self.assertEqual(unset.stdout, "") + + def test_session_start_installs_when_the_hooks_folder_is_a_symlink(self): + hooks = self.main / ".git/hooks" + moved = self.tmp / "hooks-folder" + shutil.move(hooks, moved) + hooks.symlink_to(moved) + self.start_session(self.worktree) + hooks_path = run(["git", "config", "core.hooksPath"], self.main).stdout.strip() + self.assertEqual(hooks_path, ".githooks") + + def test_hook_runs_no_build_no_test_and_no_network(self): + self.start_session(self.worktree) + shims = self.tmp / "shims" + shims.mkdir() + log = self.tmp / "forbidden.log" + for name in ["cargo", "pnpm", "npm", "npx", "curl", "wget", "python3"]: + shim = shims / name + shim.write_text(f'#!/bin/sh\necho "{name} $*" >> "{log}"\nexit 1\n') + shim.chmod(0o755) + env = git_env({"PATH": f"{shims}{os.pathsep}{os.environ['PATH']}"}) + trace = self.tmp / "trace" + prefix = () + if shutil.which("strace"): + prefix = ("strace", "-f", "-qq", "-e", "trace=connect", "-o", str(trace)) + files = {"src/lib.rs": FORMATTED, "NOTES.md": "# Notes\n"} + result = self.commit(files, env=env, prefix=prefix) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertFalse(log.exists(), log.read_text() if log.exists() else "") + if trace.exists(): + network = [ + line for line in trace.read_text().splitlines() + if "AF_INET" in line + ] + self.assertEqual(network, []) + + +if __name__ == "__main__": + unittest.main()