From 9e4fb389937f68595292786d6ddeabdd660bfae5 Mon Sep 17 00:00:00 2001 From: ari Date: Mon, 19 Oct 2026 20:11:20 -0400 Subject: [PATCH] Document hooks; drop review tag from a comment Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt --- docs/hooks.md | 59 +++++++++++++++++++++++++++++++++++++++++++ src/sources/docker.rs | 2 +- 2 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 docs/hooks.md diff --git a/docs/hooks.md b/docs/hooks.md new file mode 100644 index 0000000..2a6adc0 --- /dev/null +++ b/docs/hooks.md @@ -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/.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.` diff --git a/src/sources/docker.rs b/src/sources/docker.rs index 60d29c9..a285636 100644 --- a/src/sources/docker.rs +++ b/src/sources/docker.rs @@ -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;