Allow optional upgrade hints after semicolon in minimum_prek_version (#1536)

Closes #1490

Author: j178

crates/prek/src/config.rs

@@ -1126,25 +1126,38 @@ fn deserialize_and_validate_minimum_version<'de, D>(
 where
     D: Deserializer<'de>,
 {
-    let s = String::deserialize(deserializer)?;
-    if s.is_empty() {
+    let raw = String::deserialize(deserializer)?;
+    let (version_str, upgrade_hint) = match raw.split_once(';') {
+        Some((version, hint)) => {
+            let trimmed_hint = hint.trim();
+            if trimmed_hint.is_empty() {
+                (version, None)
+            } else {
+                (version, Some(trimmed_hint))
+            }
+        }
+        None => (raw.as_str(), None),
+    };
+    let version_str = version_str.trim();
+    if version_str.is_empty() {
         return Ok(None);
     }
 
-    let version = s
+    let version = version_str
         .parse::<semver::Version>()
         .map_err(serde::de::Error::custom)?;
     let cur_version = version::version()
         .version
         .parse::<semver::Version>()
         .expect("Invalid prek version");
     if version > cur_version {
+        let hint = upgrade_hint.unwrap_or("Please consider updating prek.");
         return Err(serde::de::Error::custom(format!(
-            "Required minimum prek version `{version}` is greater than current version `{cur_version}`. Please consider updating prek.",
+            "Required minimum prek version `{version}` is greater than current version `{cur_version}`. {hint}",
         )));
     }
 
-    Ok(Some(s))
+    Ok(Some(version_str.to_string()))
 }
 
 /// Deserializes a vector of strings and validates that each is a known file type tag.
@@ -1689,6 +1702,52 @@ mod tests {
         ");
     }
 
+    #[test]
+    fn test_upgrade_hint() {
+        // Test that hint is included in error message when version is too new
+        let yaml = indoc::indoc! {r"
+            repos:
+              - repo: local
+                hooks:
+                  - id: test-hook
+                    name: Test Hook
+                    entry: echo test
+                    language: system
+            minimum_prek_version: '10.0.0; Use `brew upgrade` to upgrade prek'
+        "};
+        let err = serde_saphyr::from_str::<Config>(yaml).unwrap_err();
+        insta::assert_snapshot!(err, @"
+        error: line 8 column 23: Required minimum prek version `10.0.0` is greater than current version `0.3.1`. Use `brew upgrade` to upgrade prek at line 8, column 23
+         --> <input>:8:23
+          |
+        6 |         entry: echo test
+        7 |         language: system
+        8 | minimum_prek_version: '10.0.0; Use `brew upgrade` to upgrade prek'
+          |                       ^ Required minimum prek version `10.0.0` is greater than current version `0.3.1`. Use `brew upgrade` to upgrade prek at line 8, column 23
+        ");
+
+        let yaml = indoc::indoc! {r"
+            repos:
+              - repo: local
+                hooks:
+                  - id: test-hook
+                    name: Test Hook
+                    entry: echo test
+                    language: system
+            minimum_prek_version: '10.0.0; '
+        "};
+        let err = serde_saphyr::from_str::<Config>(yaml).unwrap_err();
+        insta::assert_snapshot!(err, @"
+        error: line 8 column 23: Required minimum prek version `10.0.0` is greater than current version `0.3.1`. Please consider updating prek. at line 8, column 23
+         --> <input>:8:23
+          |
+        6 |         entry: echo test
+        7 |         language: system
+        8 | minimum_prek_version: '10.0.0; '
+          |                       ^ Required minimum prek version `10.0.0` is greater than current version `0.3.1`. Please consider updating prek. at line 8, column 23
+        ");
+    }
+
     #[test]
     fn test_validate_type_tags() {
         // Valid tags should parse successfully

docs/configuration.md

@@ -301,6 +301,15 @@ Example:
 minimum_prek_version: '0.2.0'
 ```
 
+You can append an optional upgrade hint after a semicolon. The hint is shown only
+when validation fails.
+
+Example:
+
+```yaml
+minimum_prek_version: '0.2.0; Use brew upgrade to upgrade prek'
+```
+
 #### `orphan`
 
 <a id="prek-only-orphan"></a>
@@ -821,6 +830,20 @@ Require a minimum `prek` version for this specific hook.
 - Type: string (version)
 - Default: unset
 
+You can append an optional upgrade hint after a semicolon. The hint is shown only
+when validation fails.
+
+Example:
+
+```yaml
+hooks:
+  - id: my-hook
+    name: My Hook
+    language: system
+    entry: echo hello
+    minimum_prek_version: '0.2.0; Use brew upgrade to upgrade prek'
+```
+
 ## Environment variables
 
 prek supports the following environment variables: