feat: type annotations 📚 (#131)

This PR adds support for type annotations in a few positions.

```
let a: Int = 3;
fn bar(b: Int) -> Int { b + 1 }
```

It notably does not support:
* Generic type annotations
* Type annotations in for loops

```
for a, b: (Int, Int) in test {

}
```

---------

Co-authored-by: Claude <[email protected]>

Author: timfennis

benches/programs/fibonacci_typed.ndc

@@ -0,0 +1,5 @@
+fn fib(n: Int) -> Int { 
+    if n <= 1 { 1 } else { fib(n - 2) + fib(n - 1) }
+}
+
+fib(26);

manual/src/reference/types.md

@@ -1,30 +1,42 @@
 # Types
 
-Andy C++ is currently a dynamically typed language, that means that type checks are performed at runtime. Although
-you currently can't annotate your variables using type names they do have types at runtime.
-
-The type system is hierarchical with the root type being `Any`:
-
-* Any
-  * [Option](./types/option.md)
-  * [Boolean](./types/boolean.md)
-  * [Number](./types/number.md)
-    * Integer
-      * Int64 (64bit signed)
-      * Bigint (unlimited size)
-    * Float
-    * Complex
-    * Rational
-  * Sequence
-    * [String](./types/string.md): A mutable list of characters
-    * [List](./types/list.md): A mutable list
-    * [Tuple](./types/tuple.md): An immutable list
-      * [Unit](./types/unit.md)
-    * [Map](./types/map-and-set.md): A hashmap that associates keys with values
-    * [Deque](./types/deque.md): A double ended queue
-    * [MinHeap & MaxHeap](./types/min-max-heap.md): Min/max Heap
-    * Iterator: A type that can be consumed and produces values (Currently only used for range expressions like `5..100`)
-  * [Function](./types/function.md)
-
-> **Note:** `Any` is the base type for all other types. When you declare a function, its arguments default to type `Any`.
-> Currently, the `Any` type is implicit and does not appear explicitly in the language.
+Andy C++ runs as a dynamically typed language — values carry their types at runtime and most checking happens then. You can also attach type annotations to variables, function parameters, and return values, and the analyser will use them to flag obvious mismatches before the program runs.
+
+The type system is hierarchical with `Any` at the root:
+
+* `Any`
+  * [`Option<T>`](./types/option.md)
+  * [`Bool`](./types/boolean.md)
+  * [`Number`](./types/number.md)
+    * `Int` — machine `i64` or arbitrary-precision `BigInt`, picked automatically
+    * `Float`
+    * `Complex`
+    * `Rational`
+  * `Sequence<T>`
+    * [`String`](./types/string.md): a mutable list of characters
+    * [`List<T>`](./types/list.md): a mutable list
+    * [`Tuple<T, ...>`](./types/tuple.md): an immutable list
+      * [`()`](./types/unit.md): unit, the empty tuple
+    * [`Map<K, V>`](./types/map-and-set.md): a hashmap that associates keys with values
+    * [`Deque<T>`](./types/deque.md): a double-ended queue
+    * [`MinHeap<T>` / `MaxHeap<T>`](./types/min-max-heap.md): min/max heap
+    * `Iterator<T>`: produces values when consumed (currently only from range expressions like `5..100`)
+  * [`Function`](./types/function.md)
+
+These are also the names you write in annotations. Generic types take their parameters in angle brackets:
+
+```ndc
+let xs: List<Int> = [1, 2, 3];
+let table: Map<String, Int> = %{"a": 1, "b": 2};
+let maybe: Option<Any> = Some("hi");
+let pair: Tuple<Int, String> = (1, "hi");
+let pair2: (Int, String) = (1, "hi");  // tuple shorthand
+```
+
+Nested generics work too — the parser handles the `>>` ambiguity for you:
+
+```ndc
+let grid: List<List<Int>> = [[1, 2], [3, 4]];
+```
+
+> **Note:** `Any` is the base type for every other type, so an `Any`-annotated binding will accept anything. When a parameter or value has no annotation and the analyser can't infer a type, it falls back to `Any`. There is also a `Never` type used internally for things like `break` that don't produce a value — you'll rarely need to write it by hand.

manual/src/reference/types/function.md

@@ -89,6 +89,33 @@ let x = fn(y) => y, 3;
 let x = fn(y) => (y, 3);
 ```
 
+## Type annotations
+
+Parameters and return values can carry type annotations, just like `let` bindings:
+
+```ndc
+fn greet(name: String) -> String => "hello " <> name;
+
+fn add(x: Int, y: Int) -> Int {
+    x + y
+}
+```
+
+Annotations are optional — leave them off and the parameter is treated as `Any`. Mix and match as you like:
+
+```ndc
+fn first(xs: List<Int>) => xs[0];   // params annotated, return inferred
+fn count(xs) -> Int => len(xs);      // return annotated, params inferred
+```
+
+If the body produces a value that doesn't fit the declared return type, the analyser flags it:
+
+```ndc
+fn bad() -> Int { "hello" }   // ERROR: mismatched types
+```
+
+A return-type annotation also helps the analyser understand recursive calls — without it, a recursive call resolves against an unknown return type and you can lose precision.
+
 ## Function overloading
 
 You can overload functions by declaring multiple `fn` definitions with the same name and different parameter counts.
@@ -108,7 +135,7 @@ fn foo(a) { a + 1 }
 fn foo(a) { a + 2 } // ERROR: redefinition of 'foo' with 1 parameter
 ```
 
-> **Note:** The engine can also overload functions by argument type, and the standard library uses that support in a few places. You cannot write those overloads in user code yet because the language does not let you declare argument types in function signatures.
+> **Note:** The engine can also dispatch by argument type, and the standard library uses that to register specialised overloads (for example, an `Int`-only fast path for `+`). User code can't declare two overloads with the same name and arity yet, even when the parameter types differ — the resolver only distinguishes overloads by parameter count.
 
 ## Function shadowing
 

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

@@ -58,6 +58,43 @@ pos = ("a", "b");    // type is still Sequence<Any>
 
 > **Tip:** For the best type inference, initialize variables with a value that matches the intended type. For example, use `let pos = (0, 0);` instead of `let pos = ();` if you intend to store a 2-tuple of numbers.
 
+## Type annotations
+
+You can pin a variable's type by adding `: Type` after the name. The initialiser still has to fit, the analyser just checks it for you up front.
+
+```ndc
+let count: Int = 0;
+let name: String = "world";
+let xs: List<Int> = [1, 2, 3];
+```
+
+A subtype is fine — `Int` fits where `Number` is asked for, and so on:
+
+```ndc
+let n: Number = 3;        // OK: Int is a Number
+let x: Any = "anything";  // OK: everything is Any
+```
+
+A mismatch is rejected with a `mismatched types` error:
+
+```ndc
+let x: Int = "hello";   // ERROR: mismatched types: found String but expected Int
+```
+
+Once a binding has an annotation, it stays locked to that type. Reassignment and augmented assignment can't widen it the way they widen an inferred binding:
+
+```ndc
+let x: Int = 5;
+x = "test";   // ERROR: mismatched types
+x /= 2;       // ERROR: division can produce a Rational, which doesn't fit in Int
+```
+
+If you want a binding that widens freely, just leave the annotation off. Annotations are opt-in.
+
+The same syntax shows up on function parameters and return types — see the [Function](./types/function.md) page.
+
+See [Types](./types.md) for the full list of names you can use, including generics like `List<T>`, `Map<K, V>`, and tuple shorthand `(Int, String)`.
+
 ## Destructuring
 
 Destructuring works more like Python than Rust. Commas matter more than the delimiters, so `[]` and `()` both work.