✨ Reject incompatible type reassignment and widen on compatible assignment

The analyser now checks that reassignments are type-compatible.
Widening within a type family (e.g. Int → Number) is allowed and
updates the binding type, but changing to a completely different
type (e.g. () → (Int, Int)) is a static error.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: timfennis

manual/src/reference/variables-and-scopes.md

@@ -40,6 +40,31 @@ let x = {
 print(x); // 3
 ```
 
+## Reassignment
+
+The `=` operator can be used to reassign a value to an existing variable. However, the new value must be compatible with the variable's original type. Widening within a type family is allowed (for example, assigning a float to a variable that held an integer), but changing to a completely different type is not.
+
+```ndc
+let x = 1;
+x = 2;       // ok: same type
+x = 3.14;    // ok: Int widens to Number
+```
+
+```ndc
+let pos = ();
+pos = (1, 2); // error: cannot assign Tuple<Int, Int> to a variable of type ()
+```
+
+If you need a variable that will hold different types, initialize it with a value of the correct type or use `None` and `Some`:
+
+```ndc
+let pos = (0, 0);
+pos = (1, 2); // ok: same tuple arity
+
+let name = None;
+name = Some("Alice"); // ok: Option type
+```
+
 ## Destructuring
 
 Destructuring is more similar to how it works in python and cares mostly about where commas are and not so much about the delimiters (`[]`, `()`) used.

ndc_analyser/src/analyser.rs

@@ -78,8 +78,35 @@ impl Analyser {
                 Ok(StaticType::unit())
             }
             Expression::Assignment { l_value, r_value } => {
-                self.resolve_lvalue(l_value, *span)?;
-                self.analyse(r_value)?;
+                let old_type = self.resolve_lvalue(l_value, *span)?;
+                let new_type = self.analyse(r_value)?;
+
+                if let Lvalue::Identifier {
+                    resolved: Some(target),
+                    ..
+                } = l_value
+                {
+                    // Reject assignments that change the variable to an
+                    // incompatible type. Widening within a type family
+                    // (e.g. Int → Number) is allowed, but changing to a
+                    // completely different type (e.g. () → (Int, Int)) is not.
+                    let widened = old_type.lub(&new_type);
+                    if !matches!(old_type, StaticType::Any)
+                        && !matches!(new_type, StaticType::Any)
+                        && !old_type.same_kind(&widened)
+                    {
+                        return Err(AnalysisError::type_mismatch_in_assignment(
+                            &old_type, &new_type, *span,
+                        ));
+                    }
+
+                    // If the assignment widens the type, update the binding so
+                    // subsequent uses see the broader type.
+                    if widened != old_type {
+                        self.scope_tree.update_binding_type(*target, widened);
+                    }
+                }
+
                 Ok(StaticType::unit())
             }
             Expression::OpAssignment {
@@ -615,6 +642,13 @@ impl AnalysisError {
         }
     }
 
+    fn type_mismatch_in_assignment(expected: &StaticType, actual: &StaticType, span: Span) -> Self {
+        Self {
+            text: format!("Cannot assign {actual} to a variable of type {expected}"),
+            span,
+        }
+    }
+
     fn function_not_found(ident: &str, types: &[StaticType], span: Span) -> Self {
         Self {
             text: format!(

ndc_core/src/static_type.rs

@@ -121,6 +121,32 @@ impl StaticType {
     /// - Generic types are covariant in their type parameters
     /// - Function parameters are **contravariant**, returns are **covariant**
     ///
+    /// Returns true if two types share the same "kind" — i.e. the same
+    /// top-level type constructor (or both are numeric). This is used to
+    /// decide whether a reassignment is a compatible widening vs. a type
+    /// change that should be rejected.
+    pub fn same_kind(&self, other: &Self) -> bool {
+        use std::mem::discriminant;
+        match (self, other) {
+            // All numeric types are the same kind
+            (s, t)
+                if matches!(
+                    s,
+                    Self::Int | Self::Float | Self::Rational | Self::Complex | Self::Number
+                ) && matches!(
+                    t,
+                    Self::Int | Self::Float | Self::Rational | Self::Complex | Self::Number
+                ) =>
+            {
+                true
+            }
+            // Tuples must have the same arity to be the same kind
+            (Self::Tuple(a), Self::Tuple(b)) => a.len() == b.len(),
+            // Otherwise, same discriminant means same kind
+            _ => discriminant(self) == discriminant(other),
+        }
+    }
+
     /// Note: this function probably doesn't handle variadic functions correctly
     pub fn is_subtype(&self, other: &Self) -> bool {
         // Never is the bottom type: subtype of everything

tests/programs/900_bugs/bug0015_unpack_mismatched_tuple_arity.ndc

@@ -1,13 +1,7 @@
-// Destructuring let where the variable was declared as () but later
-// reassigned to a 2-tuple should not cause a false "not declared" error.
-// expect-output: 4
+// Reassigning a variable to an incompatible type is a static error.
+// Previously this caused a confusing "not declared" error at the
+// destructuring site instead of flagging the real problem.
+// expect-error: Cannot assign Tuple<Int, Int> to a variable of type ()
 
 let pos = ();
 pos = (1, 3);
-
-fn use_pos() {
-    let a, b = pos;
-    (a + b).print;
-}
-
-use_pos();