Document hooks; drop review tag from a comment

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt
This commit is contained in:
ariandClaude Sonnet 5.5 committed 2026-10-20 10:19:46 -04:00
1 parent 0bddfbb063
commit 9e4fb38993
2 files changed
+60 -1

No files matched your search

+59
View File
@@ -0,0 +1,59 @@
# 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/<mod>.rs` or `src/<mod>/**` | as `*.rs` | `cargo test --lib <mod>::` plus integration files: api, mcp, auth, sources, db, telemetry -> `integration`; tls -> `tls`; config -> `plain`; any `tests/<mod>*.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/<name>.rs` | as `*.rs` | `cargo test --test <name>` |
| `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.`
+1 -1
View File
@@ -1,7 +1,7 @@
//! Docker source over the unix socket via `bollard`.
//!
//! The client is built lazily on first use, so a missing or denied socket
//! never fails startup (review G9). Every call retries the connection until it
//! never fails startup (see ARCHITECTURE.md). Every call retries the connection until it
//! succeeds, and maps backend absence to `AppError::Unavailable`.
use std::io::ErrorKind;