# Git hooks and flake checks One definition of every check lives in `dev/hooks/`: - `select.sh` maps changed paths to check names (the only place with path rules). - `run.sh` implements the checks and the `pre-commit`, `pre-push` and `lint-all` modes. - `test-select.sh` is the fixture test for the mapping and the secret, rules and hygiene checks. `devenv.hooks.nix` wires `run.sh` into devenv's git-hooks (imported from `devenv.nix`). `nix/checks.nix` exposes the same scripts as flake checks, so hooks and CI cannot drift. ## Stages - pre-commit: seconds. Staged files only; clippy runs only when Rust or Cargo files are staged. - pre-push: tests and slow checks, selected from the files changed since the upstream branch (or the merge base with `main`). ## Path mapping | Changed path | pre-commit | pre-push | | --- | --- | --- | | any file | hygiene (whitespace, EOF newline, conflict markers, files over 512 KiB), secrets | none | | `*.rs` | `cargo fmt --check`, rules, `cargo clippy --all-targets -D warnings` | see below | | `Cargo.toml`, `Cargo.lock` | clippy, `cargo tree -i openssl` must be empty | `cargo test` (all) | | `src/.rs` or `src//**` | as `*.rs` | `cargo test --lib ::` plus integration files: api, mcp, auth, sources, db, telemetry -> `integration`; tls -> `tls`; config -> `plain`; any `tests/*.rs` (for example `src/peers/**` -> `tests/peers*.rs`) | | `src/lib.rs`, `main.rs`, `state.rs`, `error.rs`, `server.rs`, `tests/common/**` | as `*.rs` | `cargo test` (all, includes `binary_smoke`) | | `tests/.rs` | as `*.rs` | `cargo test --test ` | | `migrations/**` | hygiene, secrets | `--lib db::` and `--test integration` | | `config.example.toml` | taplo | `--lib config::` (parses the example) and `--test plain` | | `*.toml` | taplo check | none | | `*.yaml`, `*.yml` | yamllint | none | | `*.md` | markdownlint (`.markdownlint.yaml`) | none | | `*.sh` | shellcheck | none | | `*.nu` | `nu-check` | none | | `*.nix` | `nix-instantiate --parse` | none | | `nix/**`, `flake.nix`, `flake.lock`, `devenv.hooks.nix` | parse | `nix flake check --no-build` (evaluation only; never the VM test) | | `dev/hooks/**` | shellcheck | `test-select.sh` | Docs-only changes (`docs/`, `*.md`) therefore run hygiene, secrets and markdownlint at commit and nothing at push. `src/mcp/**` runs `--lib mcp::`, which includes the tool-count snapshot test. Rules (`rules` check) enforce AGENTS.md: no `WS-x`, `G3` or `DEC-n` tags in `//` comments, and no axum `:name` routes. Secrets scans for private key headers, bearer tokens, common cloud token formats, and file types that hold secrets (`*.pem`, `*.key`, `.env*`, `.mcp.json`). A line containing `secret-scan: allow` is exempt, as are obviously fake runs of one repeated character. Skipped on purpose: the VM test and any nix build (slow, owned by the nix gate), nixfmt/statix (would reformat existing files), a README-versus-config sync check (no cheap reliable signal), and `cargo audit` (needs network). ## Activation Hooks install into `.git/hooks` when a devenv shell is entered (`devenv shell` or direnv). Because that dir is shared, every worktree gets them from then on. Missing optional tools are skipped with a warning outside devenv. Skip a stage once: `SKIP=slinuxm-pre-push git push` (native pre-commit variable; also `slinuxm-pre-commit`). Run by hand: `dev/hooks/run.sh pre-commit`, `dev/hooks/run.sh pre-push`, `dev/hooks/run.sh lint-all`, `dev/hooks/run.sh check NAME FILE...`. A later `dev-test` runner can replace the `cargo test` calls in the `chk_test-*` functions of `run.sh`; nothing depends on it today. ## Flake checks `nix flake check` also runs: `hooks-lint` (lint-all with every linter present), `hooks-selection` (the fixture test), `rust-fmt`, `rust-clippy` and `rust-no-openssl` (built from the package's vendored deps via `overrideAttrs`). Tests are covered by the package build's own `cargo test`. `nix flake check --no-build` evaluates all of them cheaply. ## Proposed pointers - AGENTS.md (Commands): `Git hooks run fmt, clippy, lint and a secret scan on commit and path-filtered tests on push; see docs/hooks.md.` - README.md (Development): `Contributors: enter devenv shell to install the git hooks; details in docs/hooks.md.`