feat: add check-interval-hours to throttle hook update checks

- Default to checking at most once every 24 hours to avoid slowing commits
- Store last check timestamp in prek cache directory
- Change cooldown-days default from 0 to 7 for supply chain security
- Add --check-interval-hours=0 to force check every time (useful for CI)
- Update docs with new arguments and security rationale
- Add tests for check interval behavior

Addresses review feedback about hook running on every commit.

Author: Ismar Iljazovic

crates/prek/src/hooks/pre_commit_hooks/check_hook_updates.rs

@@ -1,14 +1,17 @@
 use std::io::Write;
 use std::path::Path;
+use std::time::{SystemTime, UNIX_EPOCH};
 
 use anyhow::Result;
 use clap::Parser;
+use tracing::debug;
 
 use crate::cli::auto_update::{
     find_eligible_tag, get_tag_timestamps, resolve_rev_to_commit_hash, setup_and_fetch_repo,
 };
 use crate::config;
 use crate::hook::Hook;
+use crate::store::{CacheBucket, Store};
 
 #[derive(Parser)]
 #[command(disable_help_subcommand = true)]
@@ -17,21 +20,40 @@ use crate::hook::Hook;
 struct Args {
     /// Minimum release age (in days) required for a version to be eligible.
     /// A value of `0` disables this check.
-    #[arg(long, value_name = "DAYS", default_value_t = 0)]
+    #[arg(long, value_name = "DAYS", default_value_t = 7)]
     cooldown_days: u8,
 
     /// Fail the hook if updates are available (default: warn only).
     #[arg(long, default_value_t = false)]
     fail_on_updates: bool,
+
+    /// Minimum hours between checks (default: 24). Set to 0 to check every time.
+    #[arg(long, value_name = "HOURS", default_value_t = 24)]
+    check_interval_hours: u64,
 }
 
+const LAST_CHECK_FILE: &str = "hook-updates-last-check";
+
 /// Check if configured hooks have newer versions available.
 pub(crate) async fn check_hook_updates(
     hook: &Hook,
     _filenames: &[&Path],
 ) -> Result<(i32, Vec<u8>)> {
     let args = Args::try_parse_from(hook.entry.resolve(None)?.iter().chain(&hook.args))?;
 
+    // Check if we should skip based on check interval
+    if args.check_interval_hours > 0 {
+        if let Ok(store) = Store::from_settings() {
+            if should_skip_check(&store, args.check_interval_hours) {
+                debug!(
+                    "Skipping hook update check (last check was within {} hours)",
+                    args.check_interval_hours
+                );
+                return Ok((0, Vec::new()));
+            }
+        }
+    }
+
     let project_config = hook.project().config();
 
     let mut code = 0;
@@ -65,9 +87,55 @@ pub(crate) async fn check_hook_updates(
         }
     }
 
+    // Mark check as complete (only if we actually ran the check)
+    if args.check_interval_hours > 0 {
+        if let Ok(store) = Store::from_settings() {
+            mark_check_complete(&store);
+        }
+    }
+
     Ok((code, output))
 }
 
+/// Check if we should skip the update check based on the last check time.
+fn should_skip_check(store: &Store, interval_hours: u64) -> bool {
+    let cache_file = store.cache_path(CacheBucket::Prek).join(LAST_CHECK_FILE);
+
+    let Ok(metadata) = std::fs::metadata(&cache_file) else {
+        return false;
+    };
+
+    let Ok(modified) = metadata.modified() else {
+        return false;
+    };
+
+    let Ok(age) = SystemTime::now().duration_since(modified) else {
+        return false;
+    };
+
+    let interval_secs = interval_hours * 3600;
+    age.as_secs() < interval_secs
+}
+
+/// Mark the check as complete by touching the cache file.
+fn mark_check_complete(store: &Store) {
+    let cache_dir = store.cache_path(CacheBucket::Prek);
+    if std::fs::create_dir_all(&cache_dir).is_err() {
+        return;
+    }
+
+    let cache_file = cache_dir.join(LAST_CHECK_FILE);
+    // Write current timestamp to the file
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0);
+
+    if let Err(e) = std::fs::write(&cache_file, now.to_string()) {
+        debug!("Failed to write last check timestamp: {}", e);
+    }
+}
+
 struct UpdateInfo {
     new_rev: String,
 }

crates/prek/tests/builtin_hooks.rs

@@ -2212,7 +2212,6 @@ fn check_json5() -> Result<()> {
     Ok(())
 }
 
-<<<<<<< HEAD
 /// Test that builtin hooks work correctly even when a system-wide binary with the
 /// same name exists on PATH (regression test for <https://github.com/j178/prek/issues/1412>).
 ///
@@ -2328,6 +2327,42 @@ fn check_hook_updates_hook_with_args() {
     ");
 }
 
+/// Tests that `check-hook-updates` hook with `--check-interval-hours=0` runs every time.
+#[test]
+fn check_hook_updates_check_interval_zero_runs_every_time() {
+    let context = TestContext::new();
+    context.init_project();
+
+    context.write_pre_commit_config(indoc::indoc! {r"
+        repos:
+          - repo: builtin
+            hooks:
+              - id: check-hook-updates
+                args: ['--check-interval-hours=0']
+    "});
+    context.git_add(".");
+
+    // First run
+    cmd_snapshot!(context.filters(), context.run(), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    check for hook updates...................................................Passed
+
+    ----- stderr -----
+    ");
+
+    // Second run should also execute (not skip)
+    cmd_snapshot!(context.filters(), context.run(), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    check for hook updates...................................................Passed
+
+    ----- stderr -----
+    ");
+}
+
 /// Tests that `check-hook-updates` hook detects available updates for remote repos.
 /// Without `--fail-on-updates`, the hook passes but outputs available updates.
 #[test]
@@ -2336,11 +2371,13 @@ fn check_hook_updates_detects_outdated_repo() {
     context.init_project();
 
     // Use an old version of pre-commit-hooks that has newer versions available
+    // Use --check-interval-hours=0 to ensure the check runs
     context.write_pre_commit_config(indoc::indoc! {r"
         repos:
           - repo: builtin
             hooks:
               - id: check-hook-updates
+                args: ['--check-interval-hours=0']
           - repo: https://github.com/pre-commit/pre-commit-hooks
             rev: v4.0.0
             hooks:
@@ -2367,12 +2404,13 @@ fn check_hook_updates_fails_on_updates() {
     context.init_project();
 
     // Use an old version with --fail-on-updates
+    // Use --check-interval-hours=0 to ensure the check runs
     context.write_pre_commit_config(indoc::indoc! {r"
         repos:
           - repo: builtin
             hooks:
               - id: check-hook-updates
-                args: ['--fail-on-updates']
+                args: ['--fail-on-updates', '--check-interval-hours=0']
           - repo: https://github.com/pre-commit/pre-commit-hooks
             rev: v4.0.0
             hooks:

docs/builtin.md

@@ -382,3 +382,24 @@ Checks that non-binary executables have a proper shebang.
 
 - The check is intentionally lightweight: it only verifies that the file starts with `#!`.
 - On systems where the executable bit is not tracked by the filesystem, `prek` consults git's staged mode bits.
+
+---
+
+#### `check-hook-updates`
+
+Checks if configured hooks have newer versions available.
+
+**Supported arguments**:
+
+- `--cooldown-days=<N>` (default: `7`)
+    - Minimum release age (in days) required for a version to be eligible. Helps prevent supply chain attacks by not immediately suggesting brand-new releases. A value of `0` disables this check.
+- `--fail-on-updates`
+    - Fail the hook if updates are available (default: warn only).
+- `--check-interval-hours=<N>` (default: `24`)
+    - Minimum hours between checks. Set to `0` to check every time.
+
+**Behavior / caveats**
+
+- By default, the hook only runs once every 24 hours to avoid slowing down commits. The last check time is stored in the prek cache directory.
+- Network errors are reported as warnings but do not fail the hook.
+- This hook is configured as `always_run: true` by default, and does not take filenames.