feat(alef-docs-fresh): support custom alef command via hook args

Repos that build an extension-aware alef binary (e.g. spikard's spikard-alef,
which registers an HTTP-domain IR extension) must verify with that binary; the
generic alef on PATH computes a different inputs-hash and reports every
generated file as stale. The hook now invokes a command supplied via args with
'verify --exit-code' appended, falling back to alef on PATH when no args are
given so existing consumers are unaffected.

Author: Goldziher

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-06-20
+
+### Added
+
+- `alef-docs-fresh`: support a custom alef command via hook `args`. Repos that
+  build an extension-aware alef binary (e.g. spikard's `spikard-alef`, which
+  registers an HTTP-domain IR extension) must verify with that binary — the
+  generic `alef` on PATH computes a different inputs-hash and reports every
+  generated file as stale. Pass the override as args (e.g.
+  `args: ["cargo", "run", "--quiet", "--release", "-p", "spikard-alef", "--"]`);
+  `verify --exit-code` is appended. With no args the hook still uses `alef` on
+  PATH, so existing consumers are unaffected.
+
 ## [2.2.0] - 2026-06-18
 
 ### Fixed

hooks/alef-docs-fresh/run.sh

@@ -2,13 +2,29 @@
 # alef-docs-fresh — Verify that Alef-generated documentation is fresh.
 # Runs `alef verify --exit-code` to check that generated content is up-to-date
 # against the IR. If alef.toml is absent, exits 0 (no-op for non-polyglot repos).
+#
+# Repos that build a custom alef binary with extensions must verify with THAT
+# binary, not the generic `alef` on PATH — otherwise the inputs-hash differs and
+# every generated file is reported stale. Supply the override command as hook
+# args; `verify --exit-code` is appended to it. Example (.pre-commit-config.yaml):
+#
+#   - id: alef-docs-fresh
+#     args: ["cargo", "run", "--quiet", "--release", "-p", "spikard-alef", "--"]
+#
+# With no args, the hook falls back to the `alef` binary on PATH.
 set -euo pipefail
 
 # Quick check: if no alef.toml exists, skip silently.
 if [[ ! -f alef.toml ]]; then
   exit 0
 fi
 
+# A custom alef command supplied via hook args takes precedence over the `alef`
+# binary on PATH (e.g. an extension-aware build such as spikard's spikard-alef).
+if [[ "$#" -gt 0 ]]; then
+  exec "$@" verify --exit-code
+fi
+
 if ! command -v alef >/dev/null 2>&1; then
   printf 'kreuzberg-pre-commit-hooks: skipping alef-docs-fresh — `alef` not found on PATH.\n' >&2
   printf '  install alef: https://github.com/kreuzberg-dev/alef\n' >&2

tests/test_alef_docs_fresh.py

@@ -25,3 +25,30 @@ def test_hook_skips_when_alef_missing(tmp_path: Path) -> None:
     """
     result = run_hook(HOOK, path_override=empty_path(tmp_path), cwd=tmp_path)
     assert result.returncode == 0
+
+
+def test_hook_uses_custom_command_from_args(tmp_path: Path) -> None:
+    """A custom alef command passed via args is invoked with `verify --exit-code`.
+
+    Repos with an extension-aware build (e.g. spikard's spikard-alef) must verify
+    with that binary. The override is used even when no `alef` is on PATH.
+    """
+    (tmp_path / "alef.toml").write_text("[workspace]\n")
+    marker = tmp_path / "invoked-with"
+    stub = tmp_path / "fake-alef"
+    stub.write_text(f'#!/usr/bin/env bash\nprintf "%s" "$*" > "{marker}"\nexit 0\n')
+    stub.chmod(0o755)
+
+    result = run_hook(HOOK, str(stub), cwd=tmp_path)
+
+    assert result.returncode == 0
+    assert marker.read_text() == "verify --exit-code"
+
+
+def test_hook_propagates_custom_command_failure(tmp_path: Path) -> None:
+    """A non-zero exit from the custom alef command must fail the hook."""
+    (tmp_path / "alef.toml").write_text("[workspace]\n")
+
+    result = run_hook(HOOK, "false", cwd=tmp_path)
+
+    assert result.returncode != 0