mt-lang 0.4.24 → 0.4.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95423784419c8060f10277cb7abbb1fe1cd955fe648008781d1184976968e2d8
-  data.tar.gz: 6e1b33f4c2a17226dc34ba00618b89be6f329841c5badc7a53ccd022daa3c54d
+  metadata.gz: 8f75e56a0679c161c076efb3dd694afe256154c512e7ffae171e13c2d98d181d
+  data.tar.gz: ff00b0459c88d4fd31d12b0fc25e953d339fe7d8f7ed10964b5d8e2b70065a6f
 SHA512:
-  metadata.gz: aec1e36ac602ad755b89252058932df48abd25c0e645e212fa404afd25b23679e86d6cf45a970a36d566b08c9be774231496cf59766f64efa366da382e559963
-  data.tar.gz: 85af5d83647fd5cb635bec77a3ae8846be1b6f8f62638b5c82a2f99b9f76f2de6fb08455b6660e0cace75669e9281456a3d7336043ef3009988e50fc3efb4c0c
+  metadata.gz: 72e4cfb94f691ace787f420cbd2b6481c0b189282d21dbe42b47ebd795844f5e42a59a95fc64f1e75f56c6ec7119723231fef4601c8d856f6d7ada5ed107d26f
+  data.tar.gz: 01ba76cc9a0aeb3ab65fbd5dea21a9995ace49a3328003352fa13b0c54c9cc42e8b3e1bb6423d703913439ca4de91b4f70348d128a6c813a835c28e9345ff88b

data/.ruby-version

@@ -1 +1 @@
-4.0.3
+4.0.6

data/Gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-ruby "4.0.3"
+ruby "4.0.6"
 
 gem "rake", "~> 13.4"
 gem "rexml", "~> 3.4"

data/Gemfile.lock

@@ -5,7 +5,7 @@ GEM
     drb (2.2.3)
     fiddle (1.1.8)
     logger (1.7.0)
-    minitest (6.0.4)
+    minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
     minitest-coverage (1.0.0.b3)
@@ -15,7 +15,7 @@ GEM
     puma (6.6.1)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.6)
+    rack (3.2.7)
     rack-protection (4.2.1)
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
@@ -34,7 +34,7 @@ GEM
       rack-protection (= 4.2.1)
       rack-session (>= 2.0.0, < 3)
       tilt (~> 2.0)
-    tilt (2.7.0)
+    tilt (2.9.0)
     tomlrb (2.0.4)
 
 PLATFORMS
@@ -58,25 +58,25 @@ CHECKSUMS
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   fiddle (1.1.8) sha256=7fa8ee3627271497f3add5503acdbc3f40b32f610fc1cf49634f083ef3f32eee
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
-  minitest (6.0.4) sha256=df1304664589d40f46089247fdc451f866b0ce0d7cae1457a15fc1eb7d48dca1
+  minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
   minitest-coverage (1.0.0.b3) sha256=27c8b6b8df1259325dd206baa2b143c594f8a88b7dfd97fd8d3389a0e8a6ad26
   mustermann (3.1.1) sha256=4c6170c7234d5499c345562ba7c7dfe73e1754286dcc1abb053064d66a127198
   nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   puma (6.6.1) sha256=b9b56e4a4ea75d1bfa6d9e1972ee2c9f43d0883f011826d914e8e37b3694ea1e
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
-  rack (3.2.6) sha256=5ed78e1f73b2e25679bec7d45ee2d4483cc4146eb1be0264fc4d94cb5ef212c2
+  rack (3.2.7) sha256=93e13e1c24f93556671d85d2d79fa228c3485815c50d7e2f265b5330c6528fb7
   rack-protection (4.2.1) sha256=cf6e2842df8c55f5e4d1a4be015e603e19e9bc3a7178bae58949ccbb58558bac
   rack-session (2.1.2) sha256=595434f8c0c3473ae7d7ac56ecda6cc6dfd9d37c0b2b5255330aa1576967ffe8
   rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
   sinatra (4.2.1) sha256=b7aeb9b11d046b552972ade834f1f9be98b185fa8444480688e3627625377080
-  tilt (2.7.0) sha256=0d5b9ba69f6a36490c64b0eee9f6e9aad517e20dcc848800a06eb116f08c6ab3
+  tilt (2.9.0) sha256=da5735d0280bba96e9a91041bb14aee435ccad5c17b0fa519249ae543d9aa3a5
   tomlrb (2.0.4) sha256=262f77947ac3ac9b3366a0a5940ecd238300c553e2e14f22009e2afcd2181b99
 
 RUBY VERSION
-  ruby 4.0.3
+  ruby 4.0.6
 
 BUNDLED WITH
-  4.0.3
+  4.0.16

data/README.md

@@ -840,6 +840,8 @@ Nullability:
 - For non-pointer value bases (`int`, `bool`, `float`, structs, ...), `T?` is stored inline by value as a tagged optional (a presence flag plus the value). It copies by value with no hidden heap allocation or pointer aliasing.
 - Use `null` for absence in any nullable context.
 - In nullable pointer-like contexts, prefer `null` over `zero[ptr[T]]`.
+- `null` is only a value of nullable types. Comparing a non-nullable pointer against `null` is a type error: either declare the value `T?` when null is possible, or compare against `zero[ptr[T]]` (also `zero[cstr]`, `zero[own[T]]`) when testing the raw C zero pointer at the raw ABI level. Nullable types must use `null`, not `zero[...]`.
+- Null checks narrow flow: inside the `!= null` branch (and after an `== null` branch exits), the binding is treated as non-null. A further null check on a narrowed binding is still legal; the linter reports it as `redundant-null-check`.
 - `ref[T]` is non-null and cannot be nullable.
 - At an FFI boundary (`external` / `foreign function` parameters and returns), only pointer-like `T?` is allowed. A non-pointer value nullable such as `int?` is rejected — use `ptr[T]?` or pass an explicit struct.
 
@@ -911,6 +913,8 @@ A `field_handle`'s `.type` is usable directly **in type position** within a comp
 
 ### Standard library
 
+The authoritative module catalog is `mtc std list [--json]`; it discovers every hand-written module shipped in `std/` with its category, description, and path. Generated binding modules (`std/c/*` and imported-binding wrappers such as `raylib` or `zstd`) are excluded from `list` but stay viewable with `mtc std show`.
+
 Core modules in `std/`:
 
 - `std.linear_algebra` — extends native vector/matrix/quaternion types with `dot`, `cross`, `length`, `normalized`, `lerp`, `identity`, `transpose`, `conjugate` (pure Mt, no C dependency beyond `std.math` for `sqrt`)
@@ -922,7 +926,7 @@ Core modules in `std/`:
 - `std.encoding` — UTF-8 validation (`is_valid_utf8`, `utf8_codepoint_count`, `decode_utf8_codepoint`, `utf8_overlong_check`)
 - `std.string.String` — growable owned UTF-8 text
 - `std.mem.heap`, `std.mem.arena`, `std.mem.pool`, `std.mem.stack`, `std.mem.tracking`, `std.mem.endian` — allocators and memory utilities
-- `std.async` — task runtime (`sleep`, `work`, `completed`, `result`, `wait`, `run`)
+- `std.async` — task runtime (`sleep`, `work`, `completed`, `result`, `wait`, `run`, plus explicit-runtime variants `wait_on`, `work_on`, `sleep_on`, `run_on`, `pump`, `with_runtime`)
 - `std.option.Option[T]` — optional value with `is_some`, `is_none`, `unwrap`, `expect`, `unwrap_or`, `unwrap_or_else` (auto-imported via prelude)
 - `std.result.Result[T, E]` — fallible computation with `is_success`, `is_failure`, `unwrap`, `unwrap_error`, `unwrap_or`, `unwrap_or_else`, `ok`, `error`, `map_error` (auto-imported via prelude)
 
@@ -1241,6 +1245,13 @@ Resolve a module by name, build it, and run it:
 mtc run-module <module>       # Resolve, build, and run a module by name (e.g. std.http.server)
 ```
 
+Standard library inspection:
+
+```
+mtc std list [--json]         # List hand-written std modules grouped by category
+mtc std show MODULE           # Print a module's source (dotted or slashed names)
+```
+
 Toolchain maintenance:
 
 ```
@@ -1259,6 +1270,28 @@ mtc dap                       # Start the Debug Adapter Protocol server
 mtc docs [--open] [--port P]  # Serve the local documentation site
 ```
 
+`mtc bindgen` nullable policy:
+
+C headers usually do not state which functions can return NULL. A nullable policy file lists those symbols so generated raw bindings expose them as `T?` and null checks work downstream. The policy feeds the same override machinery as the checked-in `std.c.*` registries and shows up in `--nullable-report`.
+
+```sh
+mtc bindgen mylib.mt mylib.h --nullable-policy nullable_policy.json --nullable-report report.json
+```
+
+```json
+{
+    "return_types": {
+        "mylib_load": "ptr[ubyte]?",
+        "mylib_get_error": "cstr?"
+    },
+    "parameters": {
+        "mylib_read": { "out_size": "ptr[uint]?" }
+    }
+}
+```
+
+Types must match what bindgen would otherwise emit for the symbol (minus the `?`). Bindgen rejects policy entries for unknown symbols, so a stale policy fails loudly instead of silently drifting.
+
 Build and run commands support `--profile`, `--platform`, `--cc`, `--keep-c`, `--locked`, `--frozen`, and `-I` include paths. Dependency-locked flows support `--locked` (use package.lock) and `--frozen` (require current package.lock).
 
 Global options work with any command (before or after the subcommand, up to a `--` separator): `-h`/`--help` (also `mtc help <command>` for command-specific help), `-V`/`--version`, `-q`/`--quiet` (suppress informational output), `-v`/`--verbose` (per-file progress), and `--color auto|always|never`. Generate shell completions with `mtc completions bash|zsh|fish`. Timing breakdowns use `--timings` (on `format` and `lint`); `lint` reports warnings with per-file progress.
@@ -1266,14 +1299,13 @@ Global options work with any command (before or after the subcommand, up to a `-
 Diagnostic output uses standard compiler format (file:line:column with source context, error codes, and caret highlighting):
 
 ```
-[E0001] error: unknown type floa
-  --> file.mt:1:16
+error[sema/error]: unknown type floa -- /tmp/diag_probe.mt:2:12
    |
-   1 | type Seconds = floa
-     |                ^~~~
-  note: did you mean 'float'?
+    2 |     let x: floa = 1
+      |            ^~~~
+  = help: did you mean 'float'?
 
-error: could not check due to 1 previous error
+1 error found
 ```
 
 `mtc check` surfaces both errors and linter warnings:

data/docs/build-guide.md

@@ -351,6 +351,11 @@ Common options:
 - `--bundle` for native package builds when you want a distributable app directory instead of a bare executable
 - `--archive` for native package builds when you also want a `.tar.gz` archive of the bundle; this implies `--bundle`
 
+Debug profile builds enable runtime debug guards:
+
+- Loops get an iteration-limit guard that calls `mt_fatal` when a synchronous loop exceeds 50,000,000 iterations (a hang detector).
+- Every unconditionally-evaluated raw pointer dereference — pointer field access, pointer indexing, and `read(ptr)` in `unsafe` — is preceded by a null trap that calls `mt_fatal("null pointer dereferenced in <function>")` instead of segfaulting. This catches a NULL that crossed a non-nullable FFI declaration at the source line. Derefs guarded only by flow (inside `and`/`or` right sides or `?:` branches) and `ref[T]` receivers are not trapped: conditional derefs may never execute, and refs are non-null by the type system.
+
 The wasm platform also accepts the aliases `web`, `html5`, and `browser`.
 
 For editor tooling, the Milk Tea VS Code extension also accepts `milkTea.lsp.platform = auto|linux|windows|wasm`.

data/docs/index.html

@@ -254,7 +254,7 @@ p + p{margin-top:-.25rem}
     </button>
     <span style="font-size:.75rem">
       <a href="https://github.com/teefan/mt-lang" style="color:inherit;text-decoration:none" title="Source code on GitHub">&#9757; GitHub</a>
-      &nbsp;&middot;&nbsp; v1
+      &nbsp;&middot;&nbsp; v0.4
     </span>
   </div>
 </aside>
@@ -2101,7 +2101,7 @@ async function main() -> int:
 </div>
 
   <h3>Task Helpers</h3>
-  <p>Import <code>std.async</code> for runtime control:</p>
+  <p>Import <code>std.async</code> for runtime control (<code>sleep</code>, <code>work</code>, <code>completed</code>, <code>result</code>, <code>wait</code>, <code>run</code>, plus explicit-runtime variants such as <code>wait_on</code>, <code>work_on</code>, and <code>with_runtime</code>):</p>
 <div class="code-wrap">
 <button class="copy-btn" onclick="copyCode(this)">Copy</button>
 <pre><code>import std.async as aio
@@ -2306,7 +2306,7 @@ function attach(window: ref[Window]) -> Result[void, EventError]:
       <tr><td><code>std.mem.arena</code></td><td>Frame/level/scratch arena allocator</td></tr>
       <tr><td><code>std.mem.pool</code></td><td>Fixed-size object pool</td></tr>
       <tr><td><code>std.mem.stack</code></td><td>Explicit temporary allocator</td></tr>
-      <tr><td><code>std.async</code></td><td>Async runtime: <code>sleep</code>, <code>work</code>, <code>completed</code>, <code>result</code>, <code>wait</code>, <code>run</code></td></tr>
+      <tr><td><code>std.async</code></td><td>Async runtime: <code>sleep</code>, <code>work</code>, <code>completed</code>, <code>result</code>, <code>wait</code>, <code>run</code>, plus explicit-runtime variants (<code>wait_on</code>, <code>work_on</code>, <code>with_runtime</code>)</td></tr>
       <tr><td><code>std.option</code></td><td><code>Option[T]</code> — optional value (prelude type; methods always available without import). Methods: <code>is_some</code>, <code>is_none</code>, <code>unwrap</code>, <code>expect</code>, <code>unwrap_or</code>, <code>unwrap_or_else</code></td></tr>
       <tr><td><code>std.result</code></td><td><code>Result[T, E]</code> — fallible computation (prelude type; methods always available without import). Methods: <code>is_success</code>, <code>is_failure</code>, <code>unwrap</code>, <code>unwrap_error</code>, <code>unwrap_or</code>, <code>unwrap_or_else</code>, <code>ok</code>, <code>error</code>, <code>map_error</code></td></tr>
     </table>
@@ -2356,6 +2356,8 @@ function attach(window: ref[Window]) -> Result[void, EventError]:
       <tr><td><code>mtc test &lt;path&gt;</code></td><td>Discover and run <code>@[test]</code> functions</td></tr>
       <tr><td><code>mtc new &lt;name&gt;</code></td><td>Scaffold a new package (<code>package.toml</code> + <code>src/main.mt</code>)</td></tr>
       <tr><td><code>mtc run-module &lt;module&gt;</code></td><td>Resolve a module by name, build it, and run it</td></tr>
+      <tr><td><code>mtc std list [--json]</code></td><td>List hand-written standard library modules grouped by category (<code>--json</code> for machine-readable output)</td></tr>
+      <tr><td><code>mtc std show &lt;module&gt;</code></td><td>Print a standard library module's source (dotted or slashed names; platform variants resolve to the active platform)</td></tr>
       <tr><td><code>mtc completions &lt;shell&gt;</code></td><td>Print a bash/zsh/fish completion script</td></tr>
     </table>
   </div>
@@ -2430,46 +2432,76 @@ mtc lint path/to/file.mt --ignore line-too-long  # skip selected rules</code></p
 </div>
 
   <h3>Inline Suppression</h3>
-  <p>Suppress a rule for the next line with <code># lint: ignore &lt;rule-code&gt;</code>:</p>
+  <p>Suppress all rules on a line with <code># lint: ignore</code>, or specific rules with <code># lint: ignore(rule1, rule2)</code>:</p>
 <div class="code-wrap">
 <button class="copy-btn" onclick="copyCode(this)">Copy</button>
-<pre><code># lint: ignore unused-import
-import std.math  # intentionally available for downstream</code></pre>
+<pre><code>var count = 0  # lint: ignore
+var total = 0  # lint: ignore(prefer-let, dead-assignment)</code></pre>
 </div>
 
   <h3>Configuration</h3>
-  <p>Place a <code>.mt-lint.yml</code> file in your package root to customize rule severity:</p>
+  <p>Create a default config with <code>mtc lint --init</code>, or place a <code>.mt-lint.yml</code> file in the project root (or any ancestor directory):</p>
 <div class="code-wrap">
 <button class="copy-btn" onclick="copyCode(this)">Copy</button>
-<pre><code>rules:
-  prefer-let-else: warn
-  unused-import: error
-  line-too-long: off</code></pre>
+<pre><code>max_line_length: 120
+select:
+    - line-too-long
+    - prefer-let
+    - missing-return
+ignore:
+  - shadow
+  - useless-expression</code></pre>
 </div>
+  <p><code>max_line_length</code> defaults to <code>120</code> when omitted. When both <code>select</code> and <code>ignore</code> are present, <code>select</code> takes precedence.</p>
 
   <h3>Rule Reference</h3>
   <div class="table-wrap">
     <table class="attr-table">
-      <tr><th>Category</th><th>Code</th><th>Description</th></tr>
-      <tr><td>Correctness</td><td><code>constant-condition</code></td><td>Always-true or always-false conditions</td></tr>
-      <tr><td>Correctness</td><td><code>dead-assignment</code></td><td>Variable assigned but never read</td></tr>
-      <tr><td>Correctness</td><td><code>unreachable-code</code></td><td>Code after a terminating statement</td></tr>
-      <tr><td>Correctness</td><td><code>redundant-null-check</code></td><td>Null check on already-proven non-null</td></tr>
-      <tr><td>Correctness</td><td><code>loop-single-iteration</code></td><td>Loop with known single iteration</td></tr>
-      <tr><td>Style</td><td><code>prefer-let-else</code></td><td>Var followed by null check; suggest let...else</td></tr>
-      <tr><td>Style</td><td><code>prefer-var-else</code></td><td>Same as above for mutable bindings</td></tr>
-      <tr><td>Style</td><td><code>redundant-cast</code></td><td>Explicit cast where implicit widening already works</td></tr>
-      <tr><td>Style</td><td><code>redundant-return</code></td><td>Unnecessary return at end of void function</td></tr>
-      <tr><td>Style</td><td><code>trailing-list-comma</code></td><td>Multiline lists should end with trailing comma</td></tr>
-      <tr><td>Style</td><td><code>line-too-long</code></td><td>Line exceeds recommended width</td></tr>
-      <tr><td>Style</td><td><code>doc-tag</code></td><td>Documentation comment formatting</td></tr>
-      <tr><td>Convention</td><td><code>unused-import</code></td><td>Imported module never referenced</td></tr>
-      <tr><td>Convention</td><td><code>unused-var</code></td><td>Variable declared but never read</td></tr>
-      <tr><td>Convention</td><td><code>reserved-names</code></td><td>Binding shadows a primitive type or built-in name</td></tr>
-      <tr><td>Convention</td><td><code>event-capacity</code></td><td>Event capacity too large or unbounded</td></tr>
+      <tr><th>Code</th><th>Severity</th><th>Auto-fix</th><th>Description</th></tr>
+      <tr><td><code>borrow-and-mutate</code></td><td>warning</td><td>&mdash;</td><td>Local is borrowed with <code>ref_of</code>/<code>ptr_of</code> and also mutated in the same scope</td></tr>
+      <tr><td><code>constant-condition</code></td><td>warning</td><td>&mdash;</td><td>Branch or loop condition is provably always true or false</td></tr>
+      <tr><td><code>dead-assignment</code></td><td>warning</td><td>&mdash;</td><td>Assigned value is overwritten before any read</td></tr>
+      <tr><td><code>duplicate-if-condition</code></td><td>warning</td><td>&mdash;</td><td><code>if</code>/<code>else if</code> branch repeats a previous condition and is unreachable</td></tr>
+      <tr><td><code>directional-ffi-arg</code></td><td>hint</td><td>&mdash;</td><td>Legacy <code>ptr_of</code>/<code>ref_of</code>/<code>out</code> call-site wrapper is redundant for directional FFI parameters</td></tr>
+      <tr><td><code>doc-tag</code></td><td>hint</td><td>&mdash;</td><td><code>##</code> doc comment tag (<code>@param</code>, <code>@return</code>, <code>@throws</code>, <code>@see</code>) is invalid or inconsistent</td></tr>
+      <tr><td><code>event-capacity</code></td><td>warning</td><td>&mdash;</td><td>Event capacity may copy too many listeners to stack on emit</td></tr>
+      <tr><td><code>line-too-long</code></td><td>warning</td><td>&mdash;</td><td>Source line exceeds configured maximum length</td></tr>
+      <tr><td><code>loop-single-iteration</code></td><td>warning</td><td>&mdash;</td><td>Loop body always exits on the first iteration</td></tr>
+      <tr><td><code>missing-return</code></td><td>error</td><td>&mdash;</td><td>Non-void function lacks a guaranteed return on all paths</td></tr>
+      <tr><td><code>noop-compound-assignment</code></td><td>hint</td><td>&mdash;</td><td>Compound assignment uses an identity value and has no effect</td></tr>
+      <tr><td><code>owning-release-double</code></td><td>warning</td><td>&mdash;</td><td>Owning binding may be released more than once</td></tr>
+      <tr><td><code>owning-release-leak</code></td><td>warning</td><td>&mdash;</td><td>Owning binding is never released</td></tr>
+      <tr><td><code>platform-api-drift</code></td><td>warning</td><td>&mdash;</td><td>Public API differs across platform-specific variants of the same module</td></tr>
+      <tr><td><code>prefer-let</code></td><td>hint</td><td>yes</td><td><code>var</code> binding is never mutated; use <code>let</code></td></tr>
+      <tr><td><code>prefer-let-else</code></td><td>hint</td><td>yes</td><td>Nullable guard can be rewritten as <code>let ... else:</code></td></tr>
+      <tr><td><code>prefer-inline-methods</code></td><td>hint</td><td>yes</td><td>Methods on a struct can be written inline inside the struct declaration</td></tr>
+      <tr><td><code>prefer-is-variant</code></td><td>hint</td><td>&mdash;</td><td>A match that maps one variant arm to a boolean can be <code>expr is Arm</code></td></tr>
+      <tr><td><code>prefer-own-ptr</code></td><td>hint</td><td>&mdash;</td><td>Pointer binding used only inside <code>unsafe</code> could be <code>own[T]</code> for auto-deref</td></tr>
+      <tr><td><code>prefer-or-pattern</code></td><td>hint</td><td>&mdash;</td><td>Adjacent match arms with identical bodies can merge with <code>|</code></td></tr>
+      <tr><td><code>prefer-struct-with</code></td><td>hint</td><td>&mdash;</td><td>Field copies from another value can use <code>.with(...)</code></td></tr>
+      <tr><td><code>prefer-try</code></td><td>hint</td><td>&mdash;</td><td>A match that only propagates the failure branch can use <code>expr?</code></td></tr>
+      <tr><td><code>prefer-var-else</code></td><td>hint</td><td>yes</td><td>Nullable guard can be rewritten as <code>var ... else:</code></td></tr>
+      <tr><td><code>redundant-bool-compare</code></td><td>hint</td><td>yes</td><td>Comparing a boolean expression to <code>true</code>/<code>false</code> is redundant</td></tr>
+      <tr><td><code>redundant-cast</code></td><td>hint</td><td>yes</td><td>Explicit cast where implicit widening already works</td></tr>
+      <tr><td><code>redundant-else</code></td><td>warning</td><td>yes</td><td><code>else</code> block is unnecessary because all prior branches return</td></tr>
+      <tr><td><code>redundant-ignored-match-binding</code></td><td>hint</td><td>yes</td><td>Ignored <code>as _</code> match binding is redundant</td></tr>
+      <tr><td><code>redundant-null-check</code></td><td>hint</td><td>&mdash;</td><td>Null check on a value already known non-null by flow analysis</td></tr>
+      <tr><td><code>redundant-return</code></td><td>hint</td><td>yes</td><td>Final bare <code>return</code> in a void function is unnecessary</td></tr>
+      <tr><td><code>redundant-type-annotation</code></td><td>hint</td><td>yes</td><td>Type annotation is redundant; the type is inferred from the initializer</td></tr>
+      <tr><td><code>redundant-unsafe</code></td><td>hint</td><td>yes</td><td><code>unsafe</code> block contains no unsafe operations and can be removed</td></tr>
+      <tr><td><code>reserved-primitive-name</code></td><td>warning</td><td>yes</td><td>Binding uses a reserved built-in type name in its active namespace</td></tr>
+      <tr><td><code>self-assignment</code></td><td>warning</td><td>&mdash;</td><td>Variable is assigned to itself</td></tr>
+      <tr><td><code>self-comparison</code></td><td>warning</td><td>&mdash;</td><td>Value is compared to itself, making the condition constant</td></tr>
+      <tr><td><code>shadow</code></td><td>warning</td><td>&mdash;</td><td>Local binding shadows an outer binding with the same name</td></tr>
+      <tr><td><code>trailing-list-comma</code></td><td>hint</td><td>yes</td><td>Trailing comma in call argument list is redundant</td></tr>
+      <tr><td><code>unreachable-code</code></td><td>warning</td><td>&mdash;</td><td>Code after a guaranteed terminator cannot execute</td></tr>
+      <tr><td><code>unused-import</code></td><td>warning</td><td>&mdash;</td><td>Import alias is never referenced (intentionally not auto-fixable: removals can drop extension methods or canonical hooks)</td></tr>
+      <tr><td><code>unused-local</code></td><td>warning</td><td>&mdash;</td><td>Local binding is never referenced</td></tr>
+      <tr><td><code>unused-param</code></td><td>warning</td><td>&mdash;</td><td>Parameter is never referenced</td></tr>
+      <tr><td><code>useless-expression</code></td><td>warning</td><td>&mdash;</td><td>Expression statement has no side effects and its result is unused</td></tr>
     </table>
   </div>
-  <p>Severity levels: <code>error</code> (fail build), <code>warn</code> (report only), <code>off</code> (disabled). Rules default to <code>warn</code> unless noted in the manual.</p>
+  <p>Severity levels: <code>error</code> (fail build), <code>warning</code>, and <code>hint</code>.</p>
 </section>
 
 <!-- ────────────────────────────────────────────────────────────────────────── -->

data/docs/language-design.md

@@ -473,12 +473,12 @@ Current implemented shape:
 
 - `async function` lifts its return type to `Task[T]`
 - `await` is only valid inside async functions
-- async entrypoint bootstrapping is compiler-owned, but async helpers stay explicit library surface; import `std.async as aio` when user code needs `sleep`, `work`, `completed`, `result`, `wait`, `run`, or runtime control
+- async entrypoint bootstrapping is compiler-owned, but async helpers stay explicit library surface; import `std.async as aio` when user code needs `sleep`, `work`, `completed`, `result`, `wait`, `run`, `wait_on`, `with_runtime`, or runtime control
 - `aio.wait(...)` and `aio.run(...)` accept direct task expressions as well as zero-arg task roots; the compiler rewrites the direct-task form into the deferred root shape automatically
 - async bodies support ordinary local declarations, including `let ... else:`, assignments, returns, `if`, `while`, single-form and parallel `for`, `match`, `defer`, `unsafe`, and deferred cleanup bodies that `await`
 - await placement is handled by the normalization pass which hoists nested awaits into `let` bindings, so `await` is supported in all expression contexts (call arguments, binary operations, if-expr, match-expr, member access, index access, format strings)
 
-The default async model is a language-integrated entry boundary. `std.async` remains the explicit high-level helper surface for operations such as `sleep`, `work`, `completed`, `result`, `wait`, `wait_on`, and `with_runtime`, while the normal runtime model stays the single integrated libuv-backed runtime.
+The default async model is a language-integrated entry boundary. `std.async` remains the explicit high-level helper surface for operations such as `sleep`, `work`, `completed`, `result`, `wait`, `run`, `wait_on`, and `with_runtime`, while the normal runtime model stays the single integrated libuv-backed runtime.
 
 #### Concurrency: `parallel for` and `parallel:` blocks
 

data/docs/language-manual.md

@@ -1172,7 +1172,9 @@ let q = quat(x = 0.0, y = 0.0, z = 0.0, w = 1.0)
 - for pointer-like bases (`ptr[T]`, `const_ptr[T]`, `own[T]`, `cstr`, `fn(...)`, `proc(...)`, opaque), `T?` is a nullable pointer with `null` as the absent value
 - for non-pointer value bases (`int`, `bool`, `float`, structs, ...), `T?` is stored inline by value as a tagged optional (a presence flag plus the value); it copies by value with no hidden heap allocation or pointer aliasing
 - `null` expresses absence in any nullable context; the explicit typed `null[...]` form's target must be pointer-like
+- `null` is only a value of nullable types. Comparing a non-nullable pointer, `cstr`, or opaque handle against `null` is a type error: declare the value `T?` when null is possible, or compare against `zero[ptr[T]]` (also `zero[cstr]`, `zero[own[T]]`) to test the raw C zero pointer at the raw ABI level. Nullable types must use `null`, not `zero[...]`
 - in nullable pointer-like contexts, `zero[ptr[T]]` is rejected; use `null` instead
+- null checks narrow flow: inside the `!= null` branch (and after an `== null` branch exits), the binding is treated as non-null. A further null check on a narrowed binding is still legal; the linter reports it as `redundant-null-check`
 - at an FFI boundary (`external` / `foreign function` parameters and returns), only pointer-like `T?` is allowed; a non-pointer value nullable such as `int?` is rejected — use `ptr[T]?` or pass an explicit struct
 
 ### 6.4 Generics
@@ -1523,7 +1525,7 @@ mtc lint --ignore shadow file.mt
 
 ### 12.2 Rules
 
-The auto-fix column corresponds to `mtc lint --fix`.
+The auto-fix column corresponds to `mtc lint --fix`. `unused-import` is intentionally not auto-fixable: removing an import has non-local effects (extension methods and canonical hooks) the per-file linter cannot see.
 
 | Code | Severity | Auto-fix | Description |
 |---|---|---|---|
@@ -1538,23 +1540,33 @@ The auto-fix column corresponds to `mtc lint --fix`.
 | `loop-single-iteration` | warning | — | Loop body always exits on the first iteration |
 | `missing-return` | error | — | Function with a non-void return type lacks a guaranteed return on all paths |
 | `noop-compound-assignment` | hint | — | Compound assignment uses an identity value and has no effect |
+| `owning-release-double` | warning | — | Owning binding may be released more than once |
+| `owning-release-leak` | warning | — | Owning binding is never released |
 | `platform-api-drift` | warning | — | Public API differs across sibling platform-specific variants of the same module |
 | `prefer-let` | hint | yes | `var` binding is never mutated; use `let` instead |
 | `prefer-let-else` | hint | yes | Nullable guard can be rewritten as `let ... else:` |
+| `prefer-inline-methods` | hint | yes | Methods on a struct can be written inline inside the struct declaration |
+| `prefer-is-variant` | hint | — | A match that maps one variant arm to a boolean can be `expr is Arm` |
+| `prefer-own-ptr` | hint | — | Pointer binding used only inside `unsafe` could be `own[T]` for auto-deref |
+| `prefer-or-pattern` | hint | — | Adjacent match arms with identical bodies can merge with `\|` |
+| `prefer-struct-with` | hint | — | Field copies from another value can use `.with(...)` |
+| `prefer-try` | hint | — | A match that only propagates the failure branch can use `expr?` |
 | `prefer-var-else` | hint | yes | Nullable guard can be rewritten as `var ... else:` |
 | `redundant-bool-compare` | hint | yes | Comparing a boolean expression to `true`/`false` is redundant |
+| `redundant-cast` | hint | yes | Explicit cast where implicit widening already works |
 | `redundant-else` | warning | yes | `else` block is unnecessary because all prior branches return |
 | `redundant-ignored-match-binding` | hint | yes | Ignored `as _` match binding is redundant |
 | `redundant-null-check` | hint | — | Null check on a value already known to be non-null by flow analysis |
 | `redundant-return` | hint | yes | Final bare `return` in a `void` function is unnecessary |
+| `redundant-type-annotation` | hint | yes | Type annotation is redundant; the type is inferred from the initializer |
+| `redundant-unsafe` | hint | yes | `unsafe` block contains no unsafe operations and can be removed |
 | `reserved-primitive-name` | warning | yes | Binding uses a reserved built-in type name in its active namespace |
 | `self-assignment` | warning | — | Variable is assigned to itself |
 | `self-comparison` | warning | — | Value is compared to itself, making the condition constant |
 | `shadow` | warning | — | Local binding shadows an outer binding with the same name |
 | `trailing-list-comma` | hint | yes | Trailing comma in call argument list is redundant |
 | `unreachable-code` | warning | — | Code after a guaranteed terminator cannot execute |
-| `redundant-unsafe` | hint | — | `unsafe` block contains no unsafe operations and can be removed |
-| `unused-import` | warning | yes | Import alias is never referenced |
+| `unused-import` | warning | — | Import alias is never referenced |
 | `unused-local` | warning | — | Local binding is never referenced |
 | `unused-param` | warning | — | Parameter is never referenced |
 | `useless-expression` | warning | — | Expression statement has no side effects and its result is unused |

data/lib/milk_tea/base.rb

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

data/lib/milk_tea/bindings/raw_bindings/defaults.rb

@@ -141,6 +141,27 @@ module MilkTea
         "GuiLoadIcons" => "ptr[ptr[char]]?",
       ).freeze
 
+      # stb_image.h documents these as returning NULL on failure (and
+      # stbi_failure_reason as returning NULL before the first failure), so
+      # the raw binding must expose them as nullable for null checks to work.
+      stb_image_function_return_overrides = {
+        "stbi_failure_reason" => "cstr?",
+        "stbi_load" => "ptr[stbi_uc]?",
+        "stbi_load_16" => "ptr[stbi_us]?",
+        "stbi_load_16_from_callbacks" => "ptr[stbi_us]?",
+        "stbi_load_16_from_memory" => "ptr[stbi_us]?",
+        "stbi_load_from_callbacks" => "ptr[stbi_uc]?",
+        "stbi_load_from_memory" => "ptr[stbi_uc]?",
+        "stbi_load_gif_from_memory" => "ptr[stbi_uc]?",
+        "stbi_loadf" => "ptr[float]?",
+        "stbi_loadf_from_callbacks" => "ptr[float]?",
+        "stbi_loadf_from_memory" => "ptr[float]?",
+        "stbi_zlib_decode_malloc" => "ptr[char]?",
+        "stbi_zlib_decode_malloc_guesssize" => "ptr[char]?",
+        "stbi_zlib_decode_malloc_guesssize_headerflag" => "ptr[char]?",
+        "stbi_zlib_decode_noheader_malloc" => "ptr[char]?",
+      }.freeze
+
       sdl3_documented_function_param_overrides = {
         "SDL_AcquireGPUSwapchainTexture" => {
           "swapchain_texture_width" => "ptr[uint]?",
@@ -1269,6 +1290,7 @@ module MilkTea
           binding_path: root.join("std/c/stb_image.mt"),
           include_directives: ["stb_image.h"],
           declaration_name_prefixes: ["stbi_", "STBI_"],
+          function_return_type_overrides: stb_image_function_return_overrides,
           header_candidates: [
             MilkTea.data_root.join("third_party/stb-upstream/stb_image.h").to_s,
           ],

data/lib/milk_tea/core/c_backend/statements.rb

@@ -31,8 +31,10 @@ module MilkTea
         else
           []
         end
+        debug_guard_receivers = collect_debug_null_guards_for_statement(statement)
         statement_lines = with_checked_index_aliases(aliases) do
-          case statement
+          debug_guard_lines = emit_debug_null_guard_lines(debug_guard_receivers, indent, function)
+          debug_guard_lines + case statement
           when IR::LocalDecl
             if array_type?(statement.type) && statement.value.is_a?(IR::Call)
               lines = ["#{indent}#{c_declaration(statement.type, statement.linkage_name)};"]
@@ -524,6 +526,121 @@ module MilkTea
         nil
       end
 
+      # ── debug null traps ────────────────────────────────────────────────────
+      # Debug builds insert `if (ptr == NULL) mt_fatal(...)` before every
+      # unconditionally-evaluated raw pointer dereference (pointer field
+      # access, pointer indexing, read(ptr)) so a NULL that crosses the type
+      # system's non-null contract — typically from an FFI boundary — fatales
+      # with a function name instead of segfaulting. Receivers are duplicated
+      # into the guard, so only side-effect-free receivers qualify, and
+      # conditional subtrees (and/or right sides, ?: branches) are skipped so
+      # derefs that would never execute are not reported. ref[T] receivers are
+      # excluded: refs are non-null by the type system, so a trap there would
+      # be pure noise.
+
+      def collect_debug_null_guards_for_statement(statement)
+        return [] unless @debug_guards
+
+        expressions = case statement
+        when IR::LocalDecl
+          [statement.value]
+        when IR::Assignment
+          [statement.target, statement.value]
+        when IR::ExpressionStmt
+          [statement.expression]
+        when IR::ReturnStmt
+          statement.value ? [statement.value] : []
+        when IR::IfStmt
+          [statement.condition]
+        when IR::WhileStmt
+          [statement.condition]
+        when IR::ForStmt
+          [statement.init, statement.condition, statement.post].compact
+        when IR::SwitchStmt
+          [statement.expression]
+        else
+          []
+        end
+
+        receivers = []
+        expressions.compact.each do |expression|
+          collect_debug_null_guard_receivers(expression, receivers)
+        end
+        receivers
+      end
+
+      def collect_debug_null_guard_receivers(expression, receivers)
+        case expression
+        when IR::Member
+          collect_debug_null_guard_receivers(expression.receiver, receivers)
+          add_debug_null_guard_receiver(receivers, expression.receiver)
+        when IR::Index
+          collect_debug_null_guard_receivers(expression.receiver, receivers)
+          collect_debug_null_guard_receivers(expression.index, receivers)
+          add_debug_null_guard_receiver(receivers, expression.receiver)
+        when IR::Unary
+          collect_debug_null_guard_receivers(expression.operand, receivers)
+          add_debug_null_guard_receiver(receivers, expression.operand) if expression.operator == "*"
+        when IR::Call
+          collect_debug_null_guard_receivers(expression.callee, receivers) unless expression.callee.is_a?(String)
+          expression.arguments.each { |argument| collect_debug_null_guard_receivers(argument, receivers) }
+        when IR::Binary
+          collect_debug_null_guard_receivers(expression.left, receivers)
+          return if expression.operator == "and" || expression.operator == "or"
+
+          collect_debug_null_guard_receivers(expression.right, receivers)
+        when IR::Conditional
+          collect_debug_null_guard_receivers(expression.condition, receivers)
+        when IR::AddressOf, IR::Cast, IR::ReinterpretExpr
+          collect_debug_null_guard_receivers(expression.expression, receivers)
+        when IR::CheckedIndex, IR::CheckedSpanIndex, IR::NullableIndex, IR::NullableSpanIndex
+          collect_debug_null_guard_receivers(expression.receiver, receivers)
+          collect_debug_null_guard_receivers(expression.index, receivers)
+        when IR::AggregateLiteral
+          expression.fields.each { |field| collect_debug_null_guard_receivers(field.value, receivers) }
+        when IR::ArrayLiteral
+          expression.elements.each { |element| collect_debug_null_guard_receivers(element, receivers) }
+        when IR::VariantLiteral
+          expression.fields.each { |field| collect_debug_null_guard_receivers(field.value, receivers) }
+        when IR::SimdLaneWith
+          collect_debug_null_guard_receivers(expression.src, receivers)
+          collect_debug_null_guard_receivers(expression.value, receivers)
+        when IR::Assignment, IR::LocalDecl
+          collect_debug_null_guard_receivers(expression.target, receivers) if expression.is_a?(IR::Assignment)
+          collect_debug_null_guard_receivers(expression.value, receivers) if expression.value
+        end
+      end
+
+      def add_debug_null_guard_receiver(receivers, receiver_expression)
+        return unless debug_null_guardable_receiver?(receiver_expression)
+        return if receivers.any? { |existing| existing.equal?(receiver_expression) }
+
+        receivers << receiver_expression
+      end
+
+      def debug_null_guardable_receiver?(expression)
+        type = expression.respond_to?(:type) ? expression.type : nil
+        return false if ref_type?(type)
+
+        raw_pointer_type?(type) || nullable_pointer_like_type?(type)
+      end
+
+      def emit_debug_null_guard_lines(receivers, indent, function)
+        return [] if receivers.empty?
+
+        message = "null pointer dereferenced in #{function.linkage_name}"
+        lines = []
+        emitted = Set.new
+        receivers.each do |receiver|
+          receiver_text = emit_expression(receiver)
+          next if emitted.include?(receiver_text)
+
+          emitted << receiver_text
+          lines << "#{indent}if (#{receiver_text} == NULL) mt_fatal(\"#{message}\");"
+        end
+        lines
+      end
+
       def statements_require_scope?(statements)
         statements.any? { |statement| statement.is_a?(IR::LocalDecl) }
       end