parser: reject let rec with a helpful hint

Pyfun has no `rec` keyword — a `let` function is already recursive in its
own body (like a Python `def`). The F#/ML reflex `let rec f x = …` previously
parsed as a function *named* `rec` with parameters `f x`, then failed
downstream with a baffling `unbound name f`. Detect the shape in
parse_let_binding and reject it with the caret on `rec` and a hint to drop it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: simontreanor

DESIGN.md

@@ -584,8 +584,10 @@ no enforced visibility. All four shaping decisions were taken deliberately:
 - **All public.** Every top-level binding is exported; no `pub` keyword — Python has no enforced private
   (`_underscore` is convention only). Visibility control is **deferred**.
 - **Implicit recursion** (landed — slice 0, independent of the rest): a *function* binding (`let f x =
-  …`) is in scope in its own body, like Python's `def` — no `rec` keyword. A plain value binding still cannot
-  self-refer (`let x = x` stays an error, as `x = x` is a module-level `NameError` in Python). Mechanism:
+  …`) is in scope in its own body, like Python's `def` — no `rec` keyword (an F#/ML `let rec f x = …` is
+  rejected with a hint to drop `rec`, rather than silently binding a function named `rec`). A plain value
+  binding still cannot self-refer (`let x = x` stays an error, as `x = x` is a module-level `NameError` in
+  Python). Mechanism:
   pre-bind `f : α` (fresh) before inferring the body, unify, then generalize (standard monomorphic-
   recursion HM); lowering is unchanged (Python functions are already recursive). **Mutual recursion**
   (landed) extends this to *groups*: `run` builds the dependency graph among top-level `let` bindings

src/parser/mod.rs

@@ -673,6 +673,19 @@ impl Parser {
         while let Tok::Ident(_) = self.peek() {
             params.push(self.parse_param()?);
         }
+        // `let rec f x = …` is F#/ML muscle memory: Pyfun has no `rec` keyword — a
+        // function binding is already recursive in its own body (like a Python `def`,
+        // `DESIGN.md` §"Implicit recursion"). Left alone this would silently define a
+        // function *named* `rec` with parameters `f x`, then fail downstream with a
+        // baffling `unbound name f`. Catch the shape and say so.
+        if name == "rec" && !params.is_empty() {
+            return Err(ParseError {
+                message: "`rec` is not a keyword in Pyfun — a `let` function is already \
+                          recursive in its own body, so drop `rec` (write `let f x = …`)"
+                    .to_string(),
+                span: name_span.span(),
+            });
+        }
         if is_discard && !params.is_empty() {
             return Err(self.error("a discard binding `_` cannot take parameters"));
         }

tests/roundtrip.rs

@@ -620,6 +620,19 @@ fn reports_errors_for_malformed_input() {
     assert!(parse("(1 + 2").is_err()); // unbalanced paren
 }
 
+#[test]
+fn let_rec_is_rejected_with_a_helpful_hint() {
+    // Pyfun has no `rec` keyword (functions are implicitly recursive). The F#/ML
+    // `let rec f x = …` would otherwise silently define a function named `rec`; we
+    // catch it and point at the fix.
+    let err = parse("let rec f x = x").unwrap_err();
+    assert!(err.message().contains("`rec` is not a keyword"), "{}", err.message());
+    // A binding genuinely named `rec` with no params is still fine (a plain value).
+    assert!(parse("let rec = 1").is_ok());
+    // …and so is the corrected form.
+    assert!(parse("let f x = x").is_ok());
+}
+
 #[test]
 fn doc_comment_attaches_to_the_following_declaration() {
     // `## …` lines at column 0 join (with `\n`) onto the next top-level