mt-lang 0.4.1 → 0.4.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e72d5a921ff9b83cef5fb60e89672e913daa367f7e64b7fd000664664c4bb22
-  data.tar.gz: 7876a95d45c0a11a801ea6ec3bef10adc448e69eacaccd5bc65df5c22e01786b
+  metadata.gz: 78cefa537b068c8eb6d28d4b9111448c60e837bcaaddc82400b3b7f00ca6bbb8
+  data.tar.gz: 3ceff08e45e74f22ef4fe2f3a7eee31dd11a7943e5f8596766e792741c366cdf
 SHA512:
-  metadata.gz: 641eb7f5a45dfd4b737342ccb89ef2e58036ff6e3a889032664b0136ba6a8c632d45180f9a18ce56061c9278e2bd7e68ad37374cf40dc6da2d626940f8457d95
-  data.tar.gz: 399e6943e1207afa3a14201e8a3f1984405810da46d245685b9b2a9b5fd74b92486f982377452f416caf5aa9d6878d6094ffb11c7382d35b37d11820c3df6a89
+  metadata.gz: 4b7fc7883e1fd86961012b35f7a91da1f996eaade75d2799863991d37acae57ab41360cc783ecbca5afc792b7a6455a25b638003ea0ffa9b456e7ece1a3395da
+  data.tar.gz: 259f4a718acace0f4c3ce07fcb01f458fc7bef4ea23798ac16458eb2ffc7b63688fa05fea53a553260d33bc9e031f768ada4b7f98effc803e5099f9c976a7d03

data/README.md

@@ -20,7 +20,7 @@ It is the preferred first entry point for getting to know the language.
 If this file conflicts with `docs/language-manual.md`, the manual wins.
 `docs/language-design.md` is for design direction and rationale, not the authoritative implementation spec.
 
-Package manifests, build workflow, and run workflow are documented separately in `docs/build-guide.md`.
+Package manifests, build workflow, and run workflow are documented separately in `docs/build-guide.md`. The `@[test]` attribute, assertion intrinsics, and `mtc test` runner are documented in `docs/testing.md`.
 
 ## 1. File Kinds And Layout
 
@@ -364,6 +364,8 @@ Method kinds:
 - `function` -> value receiver
 - `editable function` -> editable receiver
 - `static function` -> no receiver
+- `const function` -> value receiver, compile-time-evaluable
+- `static const function` -> no receiver, compile-time-evaluable
 
 Methods may appear inside a struct body (desugared to an `extending` block) or in a separate
 `extending` declaration:
@@ -424,6 +426,8 @@ const RESULT: int = square(5)   # folded to 25 at compile time
 
 `const function` also generates a normal runtime function, callable from ordinary runtime code.
 
+`const` applies to methods as well: `const function` (value receiver) and `static const function` (no receiver) methods fold when called from a compile-time context and also generate normal runtime functions. `editable const function`, `async const function`, and `const` on interface methods are rejected.
+
 External functions:
 
 ```mt
@@ -856,6 +860,10 @@ Generics:
 Special recognized callables:
 
 - `fatal(message)`
+- `assert(condition, message?)` — runtime check; aborts when the `bool` condition is false
+- `expect(condition, message?)` — same as `assert`, always-on test assertion
+- `expect_eq(actual, expected, message?)` — compares with the language `==` operator (primitives, `str`, structs, variants, arrays) and aborts when the values differ
+- `expect_ne(actual, expected, message?)` — compares with `!=` and aborts when the values are equal
 - `ref_of(x)`
 - `const_ptr_of(x)`
 - `read(r)`
@@ -873,6 +881,8 @@ Special recognized callables:
 - `get(coll, index)` — recoverable array/span indexing returning `ptr[T]?`; null on out‑of‑bounds instead of aborting
 - `adapt[I](value)` — constructs a `dyn[I]` runtime interface value; verifies `value`'s type implements interface `I` at compile time
 
+`assert`, `expect`, `expect_eq`, and `expect_ne` are recognized in bare call position (not reserved words) and take an optional `str`/`cstr` message. When omitted, the compiler synthesizes a message carrying the source location; the message is only evaluated on the failing path. A literal-false `assert(false, ...)` / `expect(false, ...)` is treated as terminating control flow, so it satisfies the `else:` block of a `let ... else:` guard.
+
 Reference and pointer notes:
 
 - `read(ref_value)` explicitly projects the referent value. Use `read(handle) = value` to write through a bare `ref[T]` value.

data/docs/index.html

@@ -556,6 +556,14 @@ function make_buffer[N: int]() -> str_buffer[N]:
     var buf: str_buffer[N]
     return buf
 
+## ── inline if with a compile-time type comparison ───────────────────
+function size_label[T]() -> str:
+    inline if T == int:
+        return "32-bit"
+    inline if T == float:
+        return "float"
+    return "other"
+
 ## ── Error handling with Result[T, E] ────────────────────────────────
 enum LoadError: ubyte
     not_found = 1
@@ -575,6 +583,12 @@ function load_pair() -> Result[bool, LoadError]:
     io.print_line(f"Loaded #{first.name} and #{second.name}")
     return Result[bool, LoadError].success(value = true)
 
+## ── Foreign FFI: raw external + foreign projection ──────────────────
+external function atoi(input: cstr) -> int
+
+## foreign function projects a raw ABI call into ordinary Milk Tea types
+foreign function parse_int_foreign(input: str as cstr) -> int = atoi
+
 ## ── Events (fixed-capacity pub/sub, zero heap during dispatch) ──────
 struct DamageEvent:
     target_id: EntityId
@@ -601,6 +615,19 @@ async function load_scores() -> int:
 ## ── Compile-time constants for inline if ─────────────────────────────
 const DEBUG: bool = false
 
+## ── when: compile-time conditional (only the chosen branch is emitted) ──
+enum Backend: ubyte
+    gl     = 1
+    vulkan = 2
+const TARGET_BACKEND: Backend = Backend.gl
+
+function backend_label() -> str:
+    when TARGET_BACKEND:
+        Backend.gl:
+            return "OpenGL"
+        Backend.vulkan:
+            return "Vulkan"
+
 ## ── Main entry point ────────────────────────────────────────────────
 function main() -> int:
     ## Local declarations: let (immutable), var (mutable)
@@ -727,12 +754,22 @@ function main() -> int:
         Action.idle:
             pass
 
+    ## is: variant arm membership test
+    if action is Action.attack:
+        io.print_line("action is an attack")
+
     ## match expression
     let label = match player.level:
         1: "beginner"
         2: "novice"
         _: "advanced"
 
+    ## Struct equality: field-wise ==/!=
+    let stats_a = Entity.Stats(attack = 10, defense = 5, speed = 1.0)
+    let stats_b = Entity.Stats(attack = 10, defense = 5, speed = 1.0)
+    if stats_a == stats_b:
+        io.print_line("stats equal")
+
     ## Explicit cast: T<-value
     let raw_kind = ubyte<-player.entity.kind
     let ratio = float<-score
@@ -795,6 +832,12 @@ function main() -> int:
     inline if DEBUG:
         io.print_line("debug mode")
 
+    ## Foreign FFI, when, and inline-if type dispatch
+    let parsed_int = parse_int_foreign("42")
+    io.print_line(f"FFI parsed: #{parsed_int}")
+    io.print_line(f"Backend: #{backend_label()}")
+    io.print_line(f"int label: #{size_label[int]()}")
+
     ## ── Concurrency ─────────────────────────────────────────────────────
     ## parallel for: data-parallel loop dispatched across CPU cores
     var positions = array[float, 4](0.0, 1.0, 2.0, 3.0)
@@ -829,7 +872,7 @@ function main() -> int:
 </div>
 
   <div class="callout tip">
-    <strong>Tip:</strong> This example covers imports, constants, <code>const function</code>, type aliases, enums, flags, structs (nested, attributed), variants, interfaces, <code>extending</code> methods, generics with constraints, value parameter generics, <code>Result</code> error handling with <code>?</code> and guard binding, events, closures (<code>proc</code>), <code>async</code>/<code>await</code>, concurrency (<code>parallel for</code>, <code>parallel:</code>, <code>detach</code> + <code>gather</code>, <code>atomic[T]</code>), native vector types, arrays, spans, collections, <code>for</code>/<code>while</code>/<code>match</code>/<code>if</code>, variant membership test (<code>is</code>), parallel <code>for</code>, <code>defer</code>, <code>unsafe</code>, <code>ref[T]</code>, <code>own[T]</code>, <code>dyn[Interface]</code>, format strings, heredocs, <code>str_buffer</code>, compile-time reflection, <code>inline for</code>/<code>inline if</code>, <code>static_assert</code>, and explicit casts. See the sections below for full details on each feature.
+    <strong>Tip:</strong> This example covers imports, constants, <code>const function</code>, type aliases, enums, flags, structs (nested, attributed), variants, interfaces, foreign functions (<code>external</code> / <code>foreign function</code>), <code>extending</code> methods, generics with constraints, value parameter generics, <code>Result</code> error handling with <code>?</code> and guard binding, events, closures (<code>proc</code>), <code>async</code>/<code>await</code>, concurrency (<code>parallel for</code>, <code>parallel:</code>, <code>detach</code> + <code>gather</code>, <code>atomic[T]</code>), native vector types, arrays, spans, collections, <code>for</code>/<code>while</code>/<code>match</code>/<code>if</code>, variant membership test (<code>is</code>), parallel <code>for</code>, <code>defer</code>, <code>unsafe</code>, <code>ref[T]</code>, <code>own[T]</code>, <code>dyn[Interface]</code>, format strings, heredocs, <code>str_buffer</code>, compile-time reflection, <code>when</code>, <code>inline for</code>/<code>inline if</code> (including type comparison), struct <code>==</code>/<code>!=</code>, <code>static_assert</code>, and explicit casts. See the sections below for full details on each feature.
   </div>
 </section>
 
@@ -1221,7 +1264,7 @@ struct NPC implements Damageable:
 </div>
 
   <h3>Methods (extending)</h3>
-  <p>Three kinds: <code>function</code> (value receiver), <code>editable function</code> (editable receiver), <code>static function</code> (no receiver).</p>
+  <p>Method kinds: <code>function</code> (value receiver), <code>editable function</code> (editable receiver), <code>static function</code> (no receiver), plus compile-time-evaluable <code>const function</code> and <code>static const function</code>. <code>editable const function</code>, <code>async const function</code>, and <code>const</code> on interface methods are rejected.</p>
 <div class="code-wrap">
 <button class="copy-btn" onclick="copyCode(this)">Copy</button>
 <pre><code>extending Counter:
@@ -1394,6 +1437,7 @@ function say_hello(name: str):
 
   <h3>const function</h3>
   <p>Evaluable at compile time. Generates both a compile-time constant-folding path and a normal runtime function. Recursive calls between <code>const</code> functions are supported. Use <code>const function</code> for reusable compile-time logic; use a block-bodied <code>const X -&gt; T: ...</code> for one-shot computed constants.</p>
+  <p><code>const</code> also applies to methods: <code>const function</code> (value receiver) and <code>static const function</code> (no receiver) fold when called from a compile-time context. <code>editable const function</code>, <code>async const function</code>, and <code>const</code> on interface methods are rejected.</p>
 <div class="code-wrap">
 <button class="copy-btn" onclick="copyCode(this)">Copy</button>
 <pre><code>const function square(x: int) -> int:
@@ -1656,6 +1700,31 @@ unsafe:
 <section id="compile-time">
   <h2>Compile-Time Control Flow</h2>
 
+  <h3>Block-bodied <code>const</code> and <code>const function</code></h3>
+  <p>Block-bodied <code>const</code> initializers and <code>const function</code> bodies are evaluated at compile time, and the result is folded into the emitted C. Supported surface: literals (character literals fold to their byte value), other <code>const</code> values, arithmetic, <code>str</code> concatenation, <code>if</code>/<code>while</code>/<code>for</code> with <code>break</code> and <code>continue</code>, <code>match</code> expressions, index and range access, struct member access, <code>let</code>/<code>var</code> with destructuring and <code>else:</code> / <code>else as error:</code> guards, assignment (including compound), numeric prefix casts, calls to other const functions and const methods, and the reflection builtins.</p>
+<div class="code-wrap">
+<button class="copy-btn" onclick="copyCode(this)">Copy</button>
+<pre><code>## str concatenation folds to a literal
+const GREET: str = "hello" + " " + "world"
+
+## match expressions fold
+const LABEL -&gt; str:
+    return match 2:
+        1: "one"
+        2: "two"
+        _: "other"
+
+## const methods fold too
+struct Rect:
+    w: int
+    h: int
+    const function area() -&gt; int:
+        return this.w * this.h
+
+const R: Rect = Rect(w = 10, h = 20)
+const AREA: int = R.area()   ## folded to 200 at compile time</code></pre>
+</div>
+
   <h3>when</h3>
   <p>Evaluates discriminant at compile time; only the chosen branch is type-checked and emitted. <code>when</code> may also appear at module level to conditionally include declarations, imports, or type definitions.</p>
 <div class="code-wrap">
@@ -1810,6 +1879,10 @@ let sized = name[32]</code></pre>
     <table class="attr-table">
       <tr><th>Callable</th><th>Description</th></tr>
       <tr><td><code>fatal(message)</code></td><td>Terminate with message</td></tr>
+      <tr><td><code>assert(condition, message?)</code></td><td>Runtime check; aborts when the <code>bool</code> condition is false</td></tr>
+      <tr><td><code>expect(condition, message?)</code></td><td>Always-on test assertion (same as <code>assert</code>)</td></tr>
+      <tr><td><code>expect_eq(actual, expected, message?)</code></td><td>Compares with the language <code>==</code> (primitives, <code>str</code>, structs, variants, arrays); aborts when the values differ</td></tr>
+      <tr><td><code>expect_ne(actual, expected, message?)</code></td><td>Compares with <code>!=</code>; aborts when the values are equal</td></tr>
       <tr><td><code>ref_of(x)</code></td><td>Writable safe reference to an addressable lvalue</td></tr>
       <tr><td><code>const_ptr_of(x)</code></td><td>Read-only raw pointer to an addressable lvalue</td></tr>
       <tr><td><code>ptr_of(x)</code></td><td>Writable raw pointer from a mutable addressable lvalue</td></tr>
@@ -2591,6 +2664,7 @@ const ATOMS = new Set(['true','false','null'])
 const BUILTINS = new Set([
   'ref_of','ptr_of','const_ptr_of','read','reinterpret','zero','default',
   'hash','equal','order','size_of','align_of','offset_of','get','adapt','fatal',
+  'assert','expect','expect_eq','expect_ne',
   'field_of','callable_of','attribute_of','has_attribute','attribute_arg',
   'fields_of','members_of','attributes_of',
 ])

data/docs/language-design.md

@@ -79,7 +79,7 @@ The intended reductions are deliberate:
 
 If a new feature introduces a second ordinary way to express the same concept, the language should delete one of them instead of documenting both.
 
-The compile-time evaluation surface is described in [Compile-Time Evaluation](compile-time.md).
+The compile-time evaluation surface is described in the [language manual](language-manual.md): block-bodied `const` and `const function` limits in §3.2 and §3.7a, and `when` plus the `inline` statements in §4.7–§4.11.
 
 ## Overall shape
 
@@ -716,7 +716,7 @@ type FileHandle = ptr[libc.FILE]
 
 ### Generics
 
-Generics are useful, but they must stay boring. The compile-time surface is documented in [Compile-Time Evaluation](compile-time.md); generic bodies participate in that surface by using `when`, `inline for`, `inline while`, `inline match`, `inline if`, `type`-returning functions, `const function`, and block-bodied `const` initializers (`const X -> T: ...`) at the lexical positions where the compile-time rules allow them.
+Generics are useful, but they must stay boring. The compile-time surface is documented in the [language manual](language-manual.md); generic bodies participate in that surface by using `when`, `inline for`, `inline while`, `inline match`, `inline if`, `type`-returning functions, `const function`, and block-bodied `const` initializers (`const X -> T: ...`) at the lexical positions where the compile-time rules allow them.
 
 Allowed in v1:
 

data/docs/language-manual.md

@@ -2,7 +2,7 @@
 
 This manual documents the Milk Tea language as implemented today in the lexer, parser, semantic checker, and compiler tests.
 
-Package manifests and build or run workflow are documented separately in `docs/build-guide.md`.
+Package manifests and build or run workflow are documented separately in `docs/build-guide.md`. The `@[test]` attribute, assertion intrinsics, and `mtc test` runner are documented in `docs/testing.md`.
 
 ## 1. Source Files And Modules
 
@@ -208,7 +208,7 @@ const NEXT_POW2 -> int:
     return n
 ```
 
-The block body is evaluated at compile time. Allowed inside the block: literals, names of other `const` values, arithmetic, control flow (`if`/`else if`/`else`, `while`, `for`), `let` and `var` declarations, calls to other compile-time functions, and calls to whitelisted builtins (`size_of`, `align_of`, `offset_of`, `fields_of`, `members_of`, `attributes_of`).
+The block body is evaluated at compile time. Allowed inside the block: literals (character literals fold to their byte value), names of other `const` values, arithmetic, `str` concatenation (`+`), control flow (`if`/`else if`/`else`, `while`, `for`, with `break` and `continue`), `match` expressions, index and range access (`arr[i]`, `s[i]`, `arr[start..stop]`, `s[start..stop]`), struct member access, `let` and `var` declarations (including tuple/struct destructuring and `else:` / `else as error:` guard forms), assignment (including compound assignment to block-local struct fields and array elements), numeric prefix casts (`T<-value`), calls to other compile-time functions and const methods, and calls to whitelisted builtins (`size_of`, `align_of`, `offset_of`, `fields_of`, `members_of`, `attributes_of`).
 
 Rules:
 
@@ -524,6 +524,8 @@ Kinds:
 - `function` (value receiver)
 - `editable function` (editable receiver)
 - `static function` (no receiver)
+- `const function` (value receiver, compile-time-evaluable)
+- `static const function` (no receiver, compile-time-evaluable)
 
 Names such as `init` and `default` are ordinary static functions. There is no constructor keyword or hidden initializer syntax.
 
@@ -531,6 +533,9 @@ Method capabilities:
 
 - async methods are supported
 - generic methods are supported
+- `const function` and `static const function` methods follow the same compile-time body rules as a block-bodied `const` (§3.2). Called from a compile-time context, the call is constant-folded; they also generate normal runtime functions.
+- `editable const function` and `async const function` are rejected.
+- `const` is not allowed on interface methods.
 
 ### 3.7 Functions
 
@@ -591,10 +596,11 @@ const SQUARE_5: int = square(5)  # folded to 25 at compile time
 
 Rules:
 
-- The body must be evaluable at compile time (literals, `const` values, arithmetic, `if`/`else`, `while`, `for`, `let`/`var`, calls to other `const` functions, and whitelisted builtins).
+- The body follows the same compile-time rules as a block-bodied `const` (§3.2).
 - Generates a normal runtime function as well — callable from ordinary runtime code.
 - Called from `const` initializers, `when` discriminants, `inline for` bodies, and other compile-time contexts.
 - Recursive calls between `const` functions are supported.
+- `const` applies to methods as well: `const function` (value receiver) and `static const function` (no receiver) methods fold when called from compile-time contexts (§3.6).
 
 ### 3.8 External functions
 
@@ -1219,6 +1225,10 @@ The call site specializes with a literal: `int_with_bits[64]`.
 Special recognized callables:
 
 - `fatal(message)`
+- `assert(condition, message?)` — runtime check; aborts with `message` when the `bool` condition is false
+- `expect(condition, message?)` — same as `assert`, always-on test assertion
+- `expect_eq(actual, expected, message?)` — compares with the language `==` operator (works for primitives, `str`, structs, variants, arrays) and aborts when the values differ
+- `expect_ne(actual, expected, message?)` — compares with `!=` and aborts when the values are equal
 - `ref_of(x)`
 - `const_ptr_of(x)`
 - `read(r)`
@@ -1236,6 +1246,8 @@ Special recognized callables:
 - `get(coll, index)` — recoverable array/span indexing returning `ptr[T]?`; null on out‑of‑bounds instead of aborting
 - `adapt[I](value)` — constructs a `dyn[I]` runtime interface value; verifies `value`'s type implements `I` at compile time
 
+`assert`, `expect`, `expect_eq`, and `expect_ne` are special recognized callables, not reserved words: they are recognized in bare call position and may be shadowed by user declarations like any ordinary name. Their message argument (when given) must be `str` or `cstr`; when omitted, the compiler synthesizes a message carrying the source location. The message is only evaluated on the failing path. A literal-false `assert(false, ...)` or `expect(false, ...)` is treated as terminating control flow (like `static_assert(false, ...)`), so it may be used where the checker requires guaranteed exit, such as the `else:` block of a `let ... else:` guard.
+
 `default[T]` requires an accessible zero-argument associated function `T.default()` that returns `T`.
 
 `hash[T](value)` lowers to `T.hash(value: const_ptr[T]) -> uint`, `equal[T](left, right)` lowers to `T.equal(left: const_ptr[T], right: const_ptr[T]) -> bool`, and `order[T](left, right)` lowers to `T.order(left: const_ptr[T], right: const_ptr[T]) -> int`. Each argument must already be a `ref[T]`, `ptr[T]`, or `const_ptr[T]`, or be a safe stored `T` lvalue that can be borrowed implicitly.

data/docs/testing.md

@@ -0,0 +1,91 @@
+# Milk Tea Testing Guide
+
+This guide documents the in-language testing surface: the `assert`/`expect`/`expect_eq`/`expect_ne` intrinsics, the `@[test]` attribute, and the `mtc test` runner. The assertion intrinsics are part of the built-in callable surface (see `language-manual.md` §7); there is no standard-library testing module to import.
+
+## 1. Assertions
+
+Four abort-based assertion intrinsics are available in every module, in both tests and ordinary code:
+
+```mt
+assert(condition, message?)            # runtime check
+expect(condition, message?)            # always-on test assertion
+expect_eq(actual, expected, message?)  # compares with the language `==`
+expect_ne(actual, expected, message?)  # compares with `!=`
+```
+
+Rules:
+
+- `condition` must be `bool`. `expect_eq`/`expect_ne` compare with the language `==`/`!=` operators, so they work for primitives, `str`, structs, variants, and arrays.
+- `message` (when given) must be `str` or `cstr`; a `f"..."` format string flows straight in. When omitted, the compiler synthesizes a message carrying the source location.
+- On failure the program aborts through the same path as `fatal`. The message is only evaluated on the failing path, so a `f"..."` message costs nothing while the assertion holds.
+- `assert` defaults to always-on. `expect` is the test-flavored form and is always on.
+- A literal-false `assert(false, ...)` or `expect(false, ...)` is treated as terminating control flow (like `static_assert(false, ...)`), so it satisfies contexts that require guaranteed exit, such as the `else:` block of a `let ... else:` guard.
+
+## 2. Tests
+
+Tests are ordinary functions annotated with `@[test]`. They take no parameters and return `void`; a failing assertion aborts the test.
+
+```mt
+function square(x: int) -> int:
+    return x * x
+
+@[test]
+function test_square() -> void:
+    expect_eq(square(3), 9)
+    expect(square(4) > 0, "square must be positive")
+```
+
+Rules:
+
+- A test file must not define `main`; `mtc test` synthesizes the entry point.
+- A function annotated with `@[test] @[expect_fatal]` is a death test: it must abort (via `fatal`, a failed assertion, or a failed safety check) to pass.
+
+## 3. Running Tests
+
+```sh
+mtc test PATH            # run @[test] functions in one file
+mtc test DIR             # recursively run every test file under a directory
+```
+
+`mtc test` builds one runner binary per test file and runs each test in its own process, so an aborting assertion is isolated to its own test and cannot suppress the results of its siblings. Passing tests print `ok   - name`; failures print `FAIL - name: message`. The run is sandboxed with a wall-clock timeout (default 30s) and an address-space memory cap (default 1024 MB).
+
+Options:
+
+- `--timeout SECONDS` — per-test wall-clock timeout
+- `--mem MB` — per-test address-space memory cap
+- `--jobs N` — build and run N files in parallel (output stays in file order)
+- `-n SUBSTRING` — run only tests whose name contains SUBSTRING
+- `--format tap|junit` — machine-readable results for CI
+- `--sanitize` — build with AddressSanitizer/UBSan; any sanitizer error fails the run
+- `--profile debug|release`, `--platform linux|windows|wasm`, `--cc COMPILER` — build controls, same as `mtc build`
+
+A file containing `# expect-error: <text>` is a compile-fail fixture: `mtc test` requires the compiler to reject it with a diagnostic containing that text, instead of running it.
+
+## 4. Example
+
+```mt
+# tests/vec_test.mt
+import std.vec as vec
+
+@[test]
+function test_vec_push_and_len() -> void:
+    var values = vec.Vec[int].create()
+    defer: values.release()
+    values.push(1)
+    values.push(2)
+    expect_eq(values.len(), 2)
+
+@[test]
+@[expect_fatal]
+function test_vec_oob_aborts() -> void:
+    var values = vec.Vec[int].create()
+    defer: values.release()
+    values.push(1)
+    values.at(5)
+```
+
+```sh
+mtc test tests
+```
+
+See the `mtc test --help` text for the current full option list.

data/lib/milk_tea/base.rb

@@ -3,7 +3,7 @@
 require "pathname"
 
 module MilkTea
-  VERSION = "0.4.1"
+  VERSION = "0.4.21"
 
   def self.root
     @root ||= Pathname.new(File.expand_path("../..", __dir__))

data/lib/milk_tea/core/control_flow/builder.rb

@@ -254,7 +254,16 @@ module MilkTea
       end
 
       def fatal_expression?(expression)
-        expression.is_a?(AST::Call) && expression.callee.is_a?(AST::Identifier) && expression.callee.name == "fatal"
+        return true if expression.is_a?(AST::Call) && expression.callee.is_a?(AST::Identifier) && expression.callee.name == "fatal"
+
+        # A literal-false `assert`/`expect` always aborts, so it terminates the
+        # current control flow like a `fatal` call (matching static_assert(false)).
+        expression.is_a?(AST::Call) &&
+          expression.callee.is_a?(AST::Identifier) &&
+          %w[assert expect].include?(expression.callee.name) &&
+          (first_arg = expression.arguments.first) &&
+          first_arg.value.is_a?(AST::BooleanLiteral) &&
+          first_arg.value.value == false
       end
 
       def assignment_target_reads(target, operator)

data/lib/milk_tea/core/lowering/assertions.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module MilkTea
+  module Lowering
+    module Assertions
+      ASSERT_CALL_NAMES = %w[assert expect expect_eq expect_ne].freeze
+
+      # Lowers an `assert`/`expect`/`expect_eq`/`expect_ne` expression statement
+      # into an `IR::IfStmt` whose then-branch aborts via `fatal`. The message is
+      # only evaluated on the failing path so unused messages cost nothing.
+      # Returns `nil` when the statement is not one of the assertion calls so the
+      # caller can fall through to ordinary expression-statement lowering.
+      def lower_assert_like_statement(statement, env:)
+        kind = assert_like_call_kind(statement.expression)
+        return nil unless kind
+
+        arguments = statement.expression.arguments
+        line = statement.expression.line
+        column = statement.expression.column
+        default_message = default_assert_message(kind, statement.line)
+
+        condition_ast = nil
+        message = nil
+        case kind
+        when "assert", "expect"
+          condition_ast = unary_expression("not", arguments.fetch(0).value, line:, column:)
+          message = arguments.length > 1 ? arguments.fetch(1).value : string_literal(default_message, line:, column:)
+        when "expect_eq"
+          condition_ast = binary_expression("!=", arguments.fetch(0).value, arguments.fetch(1).value, line:, column:)
+          message = arguments.length > 2 ? arguments.fetch(2).value : string_literal(default_message, line:, column:)
+        when "expect_ne"
+          condition_ast = binary_expression("==", arguments.fetch(0).value, arguments.fetch(1).value, line:, column:)
+          message = arguments.length > 2 ? arguments.fetch(2).value : string_literal(default_message, line:, column:)
+        end
+
+        # Hoist inline-proc/foreign-temporary setup out of the condition so the
+        # failure check itself stays a plain `if (!cond)` in C.
+        setup, prepared_condition, cleanups = prepare_expression_with_cleanups(
+          condition_ast,
+          env:,
+          expected_type: @ctx.types.fetch("bool"),
+        )
+
+        [
+          *setup,
+          IR::IfStmt.new(
+            condition: lower_expression(prepared_condition, env:, expected_type: @ctx.types.fetch("bool")),
+            then_body: [lower_fatal_expression_statement(message, line:, column:, env:)],
+            else_body: [],
+          ),
+          *cleanups.flat_map(&:itself),
+        ]
+      end
+
+      def assert_like_call_kind(expression)
+        return nil unless expression.is_a?(AST::Call)
+        return nil unless expression.callee.is_a?(AST::Identifier)
+        return nil unless ASSERT_CALL_NAMES.include?(expression.callee.name)
+
+        expression.callee.name
+      end
+
+      def default_assert_message(kind, line)
+        path = @ctx.current_analysis_path.to_s
+        case kind
+        when "assert" then "assertion failed at #{path}:#{line}"
+        when "expect" then "expectation failed at #{path}:#{line}"
+        when "expect_eq" then "expect_eq failed: values are not equal at #{path}:#{line}"
+        when "expect_ne" then "expect_ne failed: values are equal at #{path}:#{line}"
+        end
+      end
+
+      def lower_fatal_expression_statement(message, line:, column:, env:)
+        fatal_call = AST::Call.new(
+          callee: AST::Identifier.new(name: "fatal", line:, column:),
+          arguments: [AST::Argument.new(name: nil, value: message, line:, column:)],
+          line:,
+          column:,
+        )
+        IR::ExpressionStmt.new(
+          expression: lower_expression(fatal_call, env:, expected_type: @ctx.types.fetch("void")),
+          line:,
+          path: @ctx.current_analysis_path,
+        )
+      end
+
+      def unary_expression(operator, operand, line:, column:)
+        AST::UnaryOp.new(operator:, operand:, line:, column:)
+      end
+
+      def binary_expression(operator, left, right, line:, column:)
+        AST::BinaryOp.new(operator:, left:, right:, line:, column:)
+      end
+
+      def string_literal(value, line:, column:)
+        AST::StringLiteral.new(lexeme: value.inspect, value:, cstring: false, line:, column:)
+      end
+    end
+  end
+end

data/lib/milk_tea/core/lowering/block.rb

@@ -422,6 +422,11 @@ module MilkTea
       end
 
       def lower_expression_stmt(statement, lowered:, local_defers:, local_env:)
+        if (assert_statements = lower_assert_like_statement(statement, env: local_env))
+          lowered.concat(assert_statements)
+          return
+        end
+
         if (format_sink_statements = lower_explicit_format_sink_expression_statement(statement.expression, env: local_env, line: statement.line))
           lowered.concat(format_sink_statements)
           return

data/lib/milk_tea/core/lowering/calls.rb

@@ -271,6 +271,8 @@ module MilkTea
           )
         when :zero
           IR::ZeroInit.new(type:)
+        when :assert, :expect, :expect_eq, :expect_ne
+          raise LoweringError.new("#{kind} must be used as a statement", line: 0, column: 0, path: @ctx.current_analysis_path)
         when :fatal
           argument = expression.arguments.fetch(0)
           message_type = infer_expression_type(argument.value, env:)

data/lib/milk_tea/core/lowering/resolve.rb

@@ -6,6 +6,10 @@ module MilkTea
       include CompileTime::MethodFolding
       PASS_THROUGH_BUILTINS = {
         "fatal"         => :fatal,
+        "assert"        => :assert,
+        "expect"        => :expect,
+        "expect_eq"     => :expect_eq,
+        "expect_ne"     => :expect_ne,
         "ref_of"        => :ref_of,
         "const_ptr_of"   => :const_ptr_of,
         "read"          => :read,

data/lib/milk_tea/core/lowering.rb

@@ -26,6 +26,7 @@
 
 require_relative "lowering/scans"
 require_relative "lowering/declarations"
+require_relative "lowering/assertions"
 require_relative "lowering/events"
 require_relative "lowering/functions"
 require_relative "lowering/async/analysis"
@@ -107,6 +108,7 @@ module MilkTea
     include Lowering::Functions
     include Lowering::Async
     include Lowering::Block
+    include Lowering::Assertions
     include Lowering::Proc
     include Lowering::Loops
     include Lowering::Expressions

data/lib/milk_tea/core/semantic_analyzer/calls.rb

@@ -834,6 +834,37 @@ module MilkTea
 
         raise_sema_error("fatal expects str or cstr, got #{message_type}")
       end
+      def check_assert_call(kind, arguments, scopes:)
+        name = kind.to_s
+        raise_sema_error("#{name} does not support named arguments") if arguments.any?(&:name)
+        raise_sema_error("#{name} expects 1 or 2 arguments, got #{arguments.length}") unless arguments.length == 1 || arguments.length == 2
+
+        condition_type = infer_expression(arguments.fetch(0).value, scopes:, expected_type: @ctx.types.fetch("bool"))
+        ensure_assignable!(condition_type, @ctx.types.fetch("bool"), "#{name} condition must be bool, got #{condition_type}", expression: arguments.fetch(0).value)
+        check_assert_message(name, arguments[1]&.value, scopes:) if arguments.length == 2
+
+        @ctx.types.fetch("void")
+      end
+      def check_expect_eq_call(kind, arguments, scopes:)
+        name = kind.to_s
+        raise_sema_error("#{name} does not support named arguments") if arguments.any?(&:name)
+        raise_sema_error("#{name} expects 2 or 3 arguments, got #{arguments.length}") unless arguments.length == 2 || arguments.length == 3
+
+        left = arguments.fetch(0).value
+        right = arguments.fetch(1).value
+        operator = kind == :expect_ne ? "!=" : "=="
+        comparison = AST::BinaryOp.new(operator:, left:, right:, line: nil, column: nil)
+        infer_binary(comparison, scopes:, expected_type: @ctx.types.fetch("bool"))
+        check_assert_message(name, arguments[2]&.value, scopes:) if arguments.length == 3
+
+        @ctx.types.fetch("void")
+      end
+      def check_assert_message(name, message, scopes:)
+        return unless message
+
+        message_type = infer_expression(message, scopes:, expected_type: @ctx.types.fetch("str"))
+        raise_sema_error("#{name} message must be str or cstr, got #{message_type}") unless string_like_type?(message_type)
+      end
       def check_get_call(arguments, scopes:)
         raise_sema_error("get does not support named arguments") if arguments.any?(&:name)
         raise_sema_error("get expects 2 arguments, got #{arguments.length}") unless arguments.length == 2

data/lib/milk_tea/core/semantic_analyzer/expressions.rb

@@ -1043,6 +1043,10 @@ module MilkTea
           check_order_call(callable, expression.arguments, scopes:)
         when :fatal
           check_fatal_call(expression.arguments, scopes:)
+        when :assert, :expect
+          check_assert_call(callable_kind, expression.arguments, scopes:)
+        when :expect_eq, :expect_ne
+          check_expect_eq_call(callable_kind, expression.arguments, scopes:)
         when :ref_of
           check_ref_of_call(expression.arguments, scopes:)
         when :const_ptr_of
@@ -1318,6 +1322,10 @@ module MilkTea
 
           return [:function, @ctx.top_level_functions.fetch(callee.name), nil] if @ctx.top_level_functions.key?(callee.name)
           return [:fatal, nil, nil] if callee.name == "fatal"
+          return [:assert, nil, nil] if callee.name == "assert"
+          return [:expect, nil, nil] if callee.name == "expect"
+          return [:expect_eq, nil, nil] if callee.name == "expect_eq"
+          return [:expect_ne, nil, nil] if callee.name == "expect_ne"
           return [:ref_of, nil, nil] if callee.name == "ref_of"
           return [:const_ptr_of, nil, nil] if callee.name == "const_ptr_of"
           return [:read, nil, nil] if callee.name == "read"