Add PREK_MAX_CONCURRENCY environment variable (#1697)

## Summary

- Add `PREK_MAX_CONCURRENCY` environment variable to cap the maximum
number of concurrent hooks
- Value is floored at 1; values above CPU count are allowed (useful for
I/O-bound hooks)
- Invalid values show a user-visible warning and fall back to CPU count
- `PREK_NO_CONCURRENCY` takes precedence when both are set

## Motivation

When `ulimit -n` is low, concurrent hook execution can exhaust file
descriptors. This provides an environment variable to limit concurrency.

For #1696

## Test plan

- [x] `mise run lint` — no warnings
- [x] `mise run test` — all tests pass
- [x] Unit tests for `resolve_concurrency`: valid value, above CPU
count, zero floors to 1, invalid string, empty string, unset,
no_concurrency, no_concurrency overrides max

Co-authored-by: Claude <noreply@anthropic.com>

Author: drichardson

crates/prek-consts/src/env_vars.rs

@@ -22,6 +22,7 @@ impl EnvVars {
     pub const PREK_SKIP: &'static str = "PREK_SKIP";
     pub const PREK_ALLOW_NO_CONFIG: &'static str = "PREK_ALLOW_NO_CONFIG";
     pub const PREK_NO_CONCURRENCY: &'static str = "PREK_NO_CONCURRENCY";
+    pub const PREK_MAX_CONCURRENCY: &'static str = "PREK_MAX_CONCURRENCY";
     pub const PREK_NO_FAST_PATH: &'static str = "PREK_NO_FAST_PATH";
     pub const PREK_UV_SOURCE: &'static str = "PREK_UV_SOURCE";
     pub const PREK_NATIVE_TLS: &'static str = "PREK_NATIVE_TLS";

crates/prek/src/run.rs

@@ -10,6 +10,7 @@ use rustc_hash::FxHashMap;
 use tracing::trace;
 
 use crate::hook::Hook;
+use crate::warn_user;
 
 pub(crate) static USE_COLOR: LazyLock<bool> =
     LazyLock::new(|| match anstream::Stderr::choice(&std::io::stderr()) {
@@ -19,14 +20,34 @@ pub(crate) static USE_COLOR: LazyLock<bool> =
         ColorChoice::Auto => unreachable!(),
     });
 
-pub(crate) static CONCURRENCY: LazyLock<usize> = LazyLock::new(|| {
-    if EnvVars::is_set(EnvVars::PREK_NO_CONCURRENCY) {
-        1
-    } else {
-        std::thread::available_parallelism()
-            .map(std::num::NonZero::get)
-            .unwrap_or(1)
+fn resolve_concurrency(no_concurrency: bool, max_concurrency: Option<&str>, cpu: usize) -> usize {
+    if no_concurrency {
+        return 1;
+    }
+
+    if let Some(v) = max_concurrency {
+        if let Ok(cap) = v.parse::<usize>() {
+            return cap.max(1);
+        }
+        warn_user!(
+            "Invalid value for {}: {v:?}, using default ({cpu})",
+            EnvVars::PREK_MAX_CONCURRENCY,
+        );
     }
+
+    cpu
+}
+
+pub(crate) static CONCURRENCY: LazyLock<usize> = LazyLock::new(|| {
+    let cpu = std::thread::available_parallelism()
+        .map(std::num::NonZero::get)
+        .unwrap_or(1);
+
+    resolve_concurrency(
+        EnvVars::is_set(EnvVars::PREK_NO_CONCURRENCY),
+        EnvVars::var(EnvVars::PREK_MAX_CONCURRENCY).ok().as_deref(),
+        cpu,
+    )
 });
 
 fn target_concurrency(serial: bool) -> usize {
@@ -352,6 +373,46 @@ mod tests {
         assert_eq!(total_files, 100);
     }
 
+    #[test]
+    fn test_resolve_concurrency_defaults_to_cpu() {
+        assert_eq!(resolve_concurrency(false, None, 16), 16);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_caps_value() {
+        assert_eq!(resolve_concurrency(false, Some("4"), 16), 4);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_above_cpu() {
+        assert_eq!(resolve_concurrency(false, Some("32"), 8), 32);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_zero_floors_to_one() {
+        assert_eq!(resolve_concurrency(false, Some("0"), 16), 1);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_invalid_falls_back() {
+        assert_eq!(resolve_concurrency(false, Some("abc"), 16), 16);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_empty_falls_back() {
+        assert_eq!(resolve_concurrency(false, Some(""), 16), 16);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_no_concurrency() {
+        assert_eq!(resolve_concurrency(true, None, 16), 1);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_no_concurrency_overrides_max() {
+        assert_eq!(resolve_concurrency(true, Some("8"), 16), 1);
+    }
+
     #[test]
     fn test_partitions_respects_cli_length_limit() {
         // Create files that will exceed CLI length limit

docs/configuration.md

@@ -1332,6 +1332,8 @@ prek supports the following environment variables:
 
 - `PREK_NO_CONCURRENCY` — Disable parallelism for installs and runs (If set, force concurrency to 1).
 
+- `PREK_MAX_CONCURRENCY` — Set the maximum number of concurrent hooks (minimum 1). Defaults to the number of CPU cores when unset. Ignored when `PREK_NO_CONCURRENCY` is set. If you encounter "Too many open files" errors, lowering this value or raising the file descriptor limit with `ulimit -n` can help.
+
 - `PREK_NO_FAST_PATH` — Disable Rust-native built-in hooks; always use the original hook implementation. See [Built-in Fast Hooks](builtin.md) for details.
 
 - `PREK_UV_SOURCE` — Control how uv (Python package installer) is installed. Options: