From 7427d87e9a9106ad7c8d261d00439accb334356f Mon Sep 17 00:00:00 2001
From: Ragnor Comerford <hello@ragnor.co>
Date: Fri, 17 Apr 2026 16:19:08 +0200
Subject: [PATCH] Add opt-in git hook for openapi.json drift
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Track a project pre-commit hook under scripts/hooks/ that regenerates
openapi.json when server source is staged, and auto-stages the updated
spec into the commit. Zero external dependencies — plain bash + cargo.

Enable via `git config core.hooksPath scripts/hooks`. The CI drift
test remains the authoritative check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CONTRIBUTING.md          | 17 +++++++++++++++++
 scripts/hooks/pre-commit | 15 +++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100755 scripts/hooks/pre-commit

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65d1e24..45d2f1f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,23 @@ cargo test --workspace
 If you touch S3-backed flows, the CI model uses a local RustFS instance for
 integration tests.
 
+### OpenAPI spec
+
+`openapi.json` is a committed artifact generated from the Utoipa annotations in
+`crates/omnigraph-server`. CI fails if it drifts from the source. To regenerate
+manually:
+
+```bash
+OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date
+```
+
+Optional: enable the project's git hook to regenerate automatically when you
+commit server changes:
+
+```bash
+git config core.hooksPath scripts/hooks
+```
+
 ## Pull Requests
 
 - keep changes focused
diff --git a/scripts/hooks/pre-commit b/scripts/hooks/pre-commit
new file mode 100755
index 0000000..6fe8d8f
--- /dev/null
+++ b/scripts/hooks/pre-commit
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Regenerate openapi.json when the server API surface changes.
+set -euo pipefail
+
+staged=$(git diff --cached --name-only --diff-filter=ACMR)
+
+echo "$staged" | grep -qE '^(crates/omnigraph-server/src/.*\.rs|crates/omnigraph-server/Cargo\.toml)$' || exit 0
+
+echo "[pre-commit] regenerating openapi.json..."
+OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date --quiet
+
+if ! git diff --quiet -- openapi.json; then
+  git add openapi.json
+  echo "[pre-commit] openapi.json updated and staged"
+fi