Files
skyg-linux-tracker/docs/hooks.md
T

4.2 KiB

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.