ENG-4687 pre-commit hook: cargo fmt --check + hygiene

.github/workflows/ci.yaml

@@ -125,3 +125,36 @@ jobs:
         with:
           shared-key: docs
       - run: cargo doc --no-deps --all-features
+
+  pre-commit:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      # Pin `pre-commit` so CI stays reproducible. The e2e tests assert
+      # on specific pre-commit diagnostic wording (e.g. "No hook with
+      # id ..."); an unpinned upstream release could change that
+      # wording and cause nondeterministic CI failures.
+      - run: pip install 'pre-commit==4.6.0'
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: pre-commit
+      # `cargo test --test pre_commit_e2e` exercises pre-commit
+      # end-to-end: AC2 (`ac2_pre_commit_run_all_files_passes_on_current_tree`)
+      # runs `pre-commit run --all-files` on the repo root and also
+      # asserts the tree stays drift-free; AC3 covers the fmt-bad
+      # commit path; AC4 covers the manual-stage clippy hook and its
+      # default-stage absence. AC2 supersedes a standalone
+      # `pre-commit run --all-files` step here — it does the same hook
+      # invocation plus the drift check, so running both would
+      # duplicate the hook suite and burn CI time. Without pre-commit
+      # on PATH, the e2e tests silently skip — installing it above is
+      # what makes AC2/AC3/AC4 actually machine-verified rather than
+      # self-attested.
+      - run: cargo test --test pre_commit_e2e

.pre-commit-config.yaml

@@ -0,0 +1,71 @@
+# ENG-4687: local pre-commit gate for rustyroute.
+#
+# Mirrors the framework patterns from spotship/backend's config
+# (top-level exclude, default_stages, rev: v5.0.0) and
+# spotship/swiftsure's non-Python hygiene baseline. Substitutes
+# `cargo fmt --check` for Python-specific linting. Clippy is opt-in
+# via --hook-stage manual because it is too slow for every commit. CI
+# (.github/workflows/ci.yaml) is the network-side enforcement; this
+# file is the laptop-side early signal.
+#
+# Locked by tests/pre_commit_config.rs — see that file for the
+# invariants asserted against silent drift.
+
+exclude: |
+  (?x)(
+    ^target/|
+    ^data/|
+    ^vendor/eurostat-marnet/.*\.gpkg$|
+    \.rkyv$
+  )
+default_stages: [pre-commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: check-json
+      - id: check-toml
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-added-large-files
+      - id: check-executables-have-shebangs
+      - id: check-vcs-permalinks
+      - id: forbid-new-submodules
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: detect-private-key
+
+  - repo: local
+    hooks:
+      - id: cargo-fmt-check
+        # Checks the root crate. A second hook
+        # (`cargo-fmt-check-downstream`) covers the nested
+        # `tests/downstream_consumer/` sub-package, which is its own
+        # `[package]` (not a workspace member) — so the root
+        # `cargo fmt --check` does NOT traverse into it. The two
+        # invocations live in separate hooks rather than chaining a
+        # single shell command, so neither entry depends on a shell
+        # being available — relevant on Windows CI runners.
+        name: cargo fmt --check (root)
+        entry: cargo fmt --check
+        language: system
+        pass_filenames: false
+        types: [rust]
+      - id: cargo-fmt-check-downstream
+        name: cargo fmt --check (downstream_consumer)
+        entry: cargo fmt --manifest-path tests/downstream_consumer/Cargo.toml --check
+        language: system
+        pass_filenames: false
+        types: [rust]
+      - id: cargo-clippy
+        name: cargo clippy --no-deps
+        entry: cargo clippy --no-deps -- -D warnings
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [manual]

CODE_OF_CONDUCT.md

@@ -81,4 +81,3 @@ For answers to common questions about this code of conduct, see the FAQ at [http
 [Mozilla CoC]: https://github.com/mozilla/diversity
 [FAQ]: https://www.contributor-covenant.org/faq
 [translations]: https://www.contributor-covenant.org/translations
-

CONTRIBUTING.md

@@ -69,7 +69,27 @@ See <https://developercertificate.org/> for the full text of the DCO.
 
 ## Local validation
 
-Before opening a pull request, run:
+First-time setup — install [pre-commit](https://pre-commit.com) itself
+(via pipx, pip, or Homebrew), then enable the git hook so format and
+file-hygiene checks run on every `git commit`:
+
+```sh
+pipx install pre-commit   # or: pip install pre-commit / brew install pre-commit
+pre-commit install
+```
+
+To run the managed hooks explicitly (e.g. before pushing):
+
+```sh
+pre-commit run --all-files
+pre-commit run --hook-stage manual  # runs cargo clippy --no-deps -- -D warnings
+```
+
+The pre-commit gate runs `cargo fmt --check` plus lightweight file
+hygiene (trailing whitespace, EOF newlines, YAML/TOML/JSON syntax,
+merge-conflict markers, private keys). Clippy and the rest of the
+full local validation suite remain manual. Before opening a pull
+request, run:
 
 ```sh
 cargo fmt --check

tests/downstream_consumer/src/lib.rs

@@ -12,8 +12,8 @@ pub fn exercise_public_api() -> (u32, u32, u32) {
     assert_eq!(loaded.resolution_km(), 50);
 
     // Path 2: Graph::from_bytes via the static BYTES_50KM const.
-    let static_g = Graph::from_bytes(rustyroute::data::BYTES_50KM)
-        .expect("Graph::from_bytes(BYTES_50KM)");
+    let static_g =
+        Graph::from_bytes(rustyroute::data::BYTES_50KM).expect("Graph::from_bytes(BYTES_50KM)");
 
     // Sanity: both observations agree on shape.
     assert_eq!(loaded.node_count(), static_g.node_count());