v0.4.1: Destructuring Params, Circular Import Diagnostics, Otherwise Lint

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 <!-- NTNT coding guide sections are sourced from docs/AI_AGENT_GUIDE.md -->
 <!-- To update NTNT coding instructions, edit AI_AGENT_GUIDE.md and copy to all agent files -->
-<!-- Last synced: 2026-03-11 -->
+<!-- Last synced: 2026-03-12 -->
 
 # NTNT Language - GitHub Copilot Instructions
 
@@ -577,7 +577,7 @@ let x = if true { 1 }  // ERROR: If-expressions require an else branch
 
 ### 11. Destructuring Assignment
 
-Map, array, and nested destructuring in `let` bindings, `match`, and `for` loops:
+Map, array, and nested destructuring in `let` bindings, `match`, `for` loops, and function parameters:
 
 ```ntnt
 // Map destructuring
@@ -615,6 +615,20 @@ match data {
     { name, age } => print("{name} is {age}"),
     _ => print("no match")
 }
+
+// Function parameter destructuring
+fn greet({ name, email }) {
+    print("Hello {name} ({email})")
+}
+
+fn first_two([a, b, ...rest]) {
+    print("{a}, {b}")
+}
+
+// With type annotation
+fn process({ name, email }: Map) {
+    print("{name}: {email}")
+}
 ```
 
 ### 12. Regex Capture Groups
@@ -1050,6 +1064,7 @@ The type checker tracks types through common operations:
 - **`parse_csv()`** — returns `Array<Array<String>>`
 - **Match arm narrowing** — `Ok(data)` on `Result<T, E>` binds `data` as `T`; `Some(x)` on `Option<T>` binds `x` as `T`; struct patterns bind field types
 - **Cross-file imports** — `import { foo } from "./lib/utils"` resolves function signatures from the imported `.tnt` file
+- **Circular import detection** — if files form an import cycle (e.g. `a.tnt → b.tnt → a.tnt`), a warning is emitted showing the exact chain
 
 ### What the Type Checker Catches
 

CLAUDE.md

@@ -1,6 +1,6 @@
 <!-- NTNT coding guide sections are sourced from docs/AI_AGENT_GUIDE.md -->
 <!-- To update NTNT coding instructions, edit AI_AGENT_GUIDE.md and copy to all agent files -->
-<!-- Last synced: 2026-03-11 -->
+<!-- Last synced: 2026-03-12 -->
 
 # NTNT Language - Claude Code Instructions
 
@@ -597,7 +597,7 @@ let x = if true { 1 }  // ERROR: If-expressions require an else branch
 
 ### 11. Destructuring Assignment
 
-Map, array, and nested destructuring in `let` bindings, `match`, and `for` loops:
+Map, array, and nested destructuring in `let` bindings, `match`, `for` loops, and function parameters:
 
 ```ntnt
 // Map destructuring
@@ -635,6 +635,20 @@ match data {
     { name, age } => print("{name} is {age}"),
     _ => print("no match")
 }
+
+// Function parameter destructuring
+fn greet({ name, email }) {
+    print("Hello {name} ({email})")
+}
+
+fn first_two([a, b, ...rest]) {
+    print("{a}, {b}")
+}
+
+// With type annotation
+fn process({ name, email }: Map) {
+    print("{name}: {email}")
+}
 ```
 
 ### 12. Regex Capture Groups
@@ -1070,6 +1084,7 @@ The type checker tracks types through common operations:
 - **`parse_csv()`** — returns `Array<Array<String>>`
 - **Match arm narrowing** — `Ok(data)` on `Result<T, E>` binds `data` as `T`; `Some(x)` on `Option<T>` binds `x` as `T`; struct patterns bind field types
 - **Cross-file imports** — `import { foo } from "./lib/utils"` resolves function signatures from the imported `.tnt` file
+- **Circular import detection** — if files form an import cycle (e.g. `a.tnt → b.tnt → a.tnt`), a warning is emitted showing the exact chain
 
 ### What the Type Checker Catches
 

ROADMAP.md

@@ -519,7 +519,7 @@ fn divide(a: Int, b: Int) -> Int
 - [x] Union type soundness: union VALUES require ALL members compatible with target, union TARGETS require ANY member match
 - [x] Union type flattening and deduplication in `union_type()` computation
 - [x] Block divergence analysis (`block_diverges`) for otherwise/lambda validation
-- [x] `otherwise` block divergence warning (must end with return/break/continue)
+- [x] `otherwise` block divergence enforcement (lint error, not just warning — must end with return/break/continue)
 - [x] Lambda return type inference via `collected_returns` (early returns included in union)
 - [x] Flow-sensitive type narrowing after guards (`if x == None { return }` narrows `x` to inner type)
 - [x] Narrowing patterns: `x == None`, `x != None`, `is_some(x)`, `is_none(x)`, `is_ok(x)`, `is_err(x)`, `!cond`
@@ -531,6 +531,7 @@ fn divide(a: Int, b: Int) -> Int
 - [x] Variadic functions check minimum argument count
 - [x] Cross-file Pass 2 inference: unannotated exported functions get inferred return types
 - [x] Circular import safety: shared module cache prevents infinite recursion during cross-file analysis
+- [x] Circular import diagnostics: cycle chain shown in warnings (e.g. `a.tnt → b.tnt → a.tnt`)
 - [x] Strict mode: string interpolation warning for complex types (Array, Map, Function)
 - [x] Strict mode: Float→Int precision loss warning
 - [ ] Cross-file struct/enum propagation (extend import type resolution to include struct and enum definitions)
@@ -639,7 +640,7 @@ for line in lines {
 - [x] Works with `Option<T>` — unwrap Some or run otherwise on None
 - [x] Verify otherwise block diverges (return/break/continue)
 - [x] Type checker unwraps `Result<T, E>` → `T` and `Option<T>` → `T` for let with otherwise
-- [ ] Lint integration: warn if otherwise block doesn't diverge
+- [x] Lint integration: error if otherwise block doesn't diverge
 
 ### 7.3 Anonymous Functions / Closures ✅
 
@@ -865,7 +866,7 @@ fn create_user({ name, email }: Map) -> User {
 - [x] Rest patterns: `let [head, ...tail] = arr`, `let { name, ...other } = map`
 - [x] Nested destructuring: `let { user: { name } } = data`
 - [ ] Destructuring with type annotations
-- [ ] Destructuring in function parameters
+- [x] Destructuring in function parameters
 - [x] Destructuring in `for` loops: `for { name, email } in users { ... }`
 - [x] Type checking: destructured fields are type-inferred from the source expression
 - [x] Map destructuring with rename: `let { name: n } = data`

docs/AI_AGENT_GUIDE.md

@@ -570,7 +570,7 @@ let x = if true { 1 }  // ERROR: If-expressions require an else branch
 
 ### 11. Destructuring Assignment
 
-Map, array, and nested destructuring in `let` bindings, `match`, and `for` loops:
+Map, array, and nested destructuring in `let` bindings, `match`, `for` loops, and function parameters:
 
 ```ntnt
 // Map destructuring
@@ -608,6 +608,20 @@ match data {
     { name, age } => print("{name} is {age}"),
     _ => print("no match")
 }
+
+// Function parameter destructuring
+fn greet({ name, email }) {
+    print("Hello {name} ({email})")
+}
+
+fn first_two([a, b, ...rest]) {
+    print("{a}, {b}")
+}
+
+// With type annotation
+fn process({ name, email }: Map) {
+    print("{name}: {email}")
+}
 ```
 
 ### 12. Regex Capture Groups
@@ -1043,6 +1057,7 @@ The type checker tracks types through common operations:
 - **`parse_csv()`** — returns `Array<Array<String>>`
 - **Match arm narrowing** — `Ok(data)` on `Result<T, E>` binds `data` as `T`; `Some(x)` on `Option<T>` binds `x` as `T`; struct patterns bind field types
 - **Cross-file imports** — `import { foo } from "./lib/utils"` resolves function signatures from the imported `.tnt` file
+- **Circular import detection** — if files form an import cycle (e.g. `a.tnt → b.tnt → a.tnt`), a warning is emitted showing the exact chain
 
 ### What the Type Checker Catches
 

src/ast.rs

@@ -377,6 +377,8 @@ pub struct Parameter {
     pub name: String,
     pub type_annotation: Option<TypeExpr>,
     pub default: Option<Expression>,
+    #[serde(default)]
+    pub pattern: Option<Pattern>,
 }
 
 /// Import item for selective imports: `import { foo as bar } from "module"`

src/interpreter.rs

@@ -6339,7 +6339,12 @@ impl Interpreter {
                 // Should not reach here due to arity check above
                 Value::Unit
             };
-            func_env.borrow_mut().define(param.name.clone(), value);
+            if let Some(ref pat) = param.pattern {
+                // Destructured param: only bind pattern variables, not the synthetic name
+                self.bind_pattern(pat, &value)?;
+            } else {
+                func_env.borrow_mut().define(param.name.clone(), value);
+            }
         }
 
         // Environment is already set to func_env for contract checking and body execution
@@ -12017,4 +12022,69 @@ page
             other => panic!("expected String('ab'), got {:?}", other),
         }
     }
+
+    #[test]
+    fn test_destructured_map_param() {
+        let result = eval(
+            r#"
+            fn greet({ name, email }) {
+                return name + " <" + email + ">"
+            }
+            greet(map { "name": "Alice", "email": "a@b.com" })
+        "#,
+        )
+        .unwrap();
+        match result {
+            Value::String(s) => assert_eq!(s, "Alice <a@b.com>"),
+            other => panic!("expected String, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn test_destructured_map_param_with_type() {
+        let result = eval(
+            r#"
+            fn greet({ name, email }: Map) -> String {
+                return name + " <" + email + ">"
+            }
+            greet(map { "name": "Bob", "email": "b@b.com" })
+        "#,
+        )
+        .unwrap();
+        match result {
+            Value::String(s) => assert_eq!(s, "Bob <b@b.com>"),
+            other => panic!("expected String, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn test_destructured_array_param() {
+        let result = eval(
+            r#"
+            fn first_two([a, b, ...rest]) {
+                return a + b
+            }
+            first_two([10, 20, 30])
+        "#,
+        )
+        .unwrap();
+        assert!(matches!(result, Value::Int(30)));
+    }
+
+    #[test]
+    fn test_destructured_param_with_regular_params() {
+        let result = eval(
+            r#"
+            fn process(id, { name }) {
+                return str(id) + ": " + name
+            }
+            process(42, map { "name": "Alice" })
+        "#,
+        )
+        .unwrap();
+        match result {
+            Value::String(s) => assert_eq!(s, "42: Alice"),
+            other => panic!("expected String, got {:?}", other),
+        }
+    }
 }

src/parser.rs

@@ -307,7 +307,15 @@ impl Parser {
 
         if !self.check(&TokenKind::RightParen) {
             loop {
-                let name = self.consume_identifier("Expected parameter name")?;
+                let (name, pattern) =
+                    if self.check(&TokenKind::LeftBrace) || self.check(&TokenKind::LeftBracket) {
+                        let pat = self.parse_pattern()?;
+                        let synth_name = format!("_destructure_{}", params.len());
+                        (synth_name, Some(pat))
+                    } else {
+                        let name = self.consume_identifier("Expected parameter name")?;
+                        (name, None)
+                    };
 
                 let type_annotation = if self.match_token(&[TokenKind::Colon]) {
                     Some(self.parse_type()?)
@@ -325,6 +333,7 @@ impl Parser {
                     name,
                     type_annotation,
                     default,
+                    pattern,
                 });
 
                 if !self.match_token(&[TokenKind::Comma]) {
@@ -522,6 +531,7 @@ impl Parser {
                         name: param_name,
                         type_annotation,
                         default: None,
+                        pattern: None,
                     });
                 }