xbintsc 0.3.46 → 0.3.49

package/doc/ai/troubleshooting.md

@@ -0,0 +1,163 @@
+# Troubleshooting
+
+Start with the command that shows what xbintsc actually resolved:
+
+```bash
+xbintsc doctor
+```
+
+It prints the platform, the toolchain it will use (and where it came from), the
+compiler version, the runtime directory, the runtime library directory and the
+icon resource compiler. Most "it doesn't work" reports are answered here.
+
+## Before anything else: is clang new enough?
+
+**clang/LLVM 16 or newer is required.** Older clang rejects the emitted IR with a
+typed-pointer error:
+
+```
+D:\...\build\app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but expected 'i8*'
+  %r0 = call i64 @xt_string_new(i8* @.str.0, i64 5)
+```
+
+The compiler emits LLVM IR that relies on opaque pointers; typed pointers were
+removed in LLVM 16 ([LLVM release notes](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)).
+Confirm with `clang --version`; if the machine has an old system clang, install a
+newer LLVM and point xbintsc at it:
+
+```bash
+export xbintsc_CLANG=/usr/lib/llvm-18/bin/clang     # PowerShell: $env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
+```
+
+Note that front-end-only work (`xbintsc emit`) never needs clang, so it keeps
+working on an old toolchain.
+
+## Error messages and what they mean
+
+### `module '…' is provided by the 'node' extension; pass --ext node`
+
+The program imports a Node module but the extension is off. Add the flag, or put
+it in `xbintsc.config.json` so it is always on:
+
+```bash
+xbintsc run app.ts --ext node
+```
+
+### `module '<pkg>' is not supported: xbintsc can import built-in platform modules, relative '.ts' files and ESM packages under node_modules; CommonJS packages are not supported`
+
+A bare third-party import that nothing can link. Either the package is CommonJS
+(unsupported), or it is an ESM package that failed to bundle. Prefer a Node
+built-in from the `node` extension; see [extensions.md](./extensions.md) for
+what can actually be bundled.
+
+### ``CommonJS `require()` is not supported``
+
+Convert to ESM: `const fs = require("fs")` becomes `import fs from "fs"` (plus
+`--ext node`). `require` inside `node_modules` packages *is* handled by the
+bundler; it is only rejected in your own source. `require(<non-literal>)` is
+never supported.
+
+### `error TS4005: xbintsc does not yet support this <construct>`
+
+The syntax is parsed but codegen does not implement it. Check
+[language-support.md](./language-support.md) and
+[../unimplemented.md](../unimplemented.md), then rewrite the construct (or
+contribute support). `namespace` declarations and `new.target` are the common
+ones.
+
+### `error TS2xxx` (parser) or `error TS1xxx` (lexer)
+
+A syntax error in the source. The diagnostic prints the file, line, column, the
+offending line and a caret. Note that xbintsc's parser accepts most TypeScript,
+so a parse error usually means genuinely broken syntax rather than an
+unsupported feature.
+
+### `error TS6001: Cannot resolve module './x' from '<file>'` / `Cannot find module`
+
+A relative import that does not resolve. A `./helper.js` specifier maps to
+`helper.ts`, so import the runtime path you actually wrote in TypeScript.
+
+### `Cannot resolve module '…' required from '<file>'`
+
+A `require(...)` inside a bundled `node_modules` package that could not be
+resolved. The package is not usable as-is; prefer the built-in or a different
+dependency.
+
+### `xbintsc: <config path>: invalid JSON (…)` / `Unable to read …`
+
+The project config or a native extension manifest is malformed or missing. Fix
+the JSON, or bypass discovery with `--no-config` / `--config <path>`.
+
+### `error TS6003` / `Command failed (N): clang …`
+
+clang itself failed. The thrown message includes the full clang command and its
+stderr — read the stderr, not just the first line. Frequent causes:
+
+- the toolchain is too old (see above);
+- on Windows, clang cannot find the MSVC/SDK headers or libraries because the
+  environment was not imported. Run from an **x64 Native Tools Command Prompt
+  for VS 2022** (or **ARM64 Native Tools** on Windows on ARM), or import it
+  first:
+  ```powershell
+  & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
+  ```
+- the linker is wrong on Linux — set `xbintsc_CLANG` and/or pass
+  `xbintsc_LINKER_ARGS=-fuse-ld=lld`;
+- `No C compiler found. Set xbintsc_CLANG to a clang binary.` — no clang on
+  `PATH` at all.
+
+### `GUI native library not found at …`
+
+The `gui` extension needs its per-platform prebuilt `gui.a`/`gui.lib`, which is
+not built in a plain source checkout. Drop `--ext gui`, or build the archive as
+described in [../gui.md](../gui.md).
+
+### `Icon file not found` / icon tools missing
+
+`--icon`/`app.icon` paths resolve against the config file's directory. On
+Windows, embedding a PE icon needs `llvm-rc` or `windres`; `doctor` reports which
+one was found, and a missing one is only fatal when an icon was requested.
+
+## Build behaviour that looks wrong but is not
+
+### The build printed `(cached)` and did nothing
+
+The incremental cache matched: same source hash, compiler version, options,
+platform and extension set, with every output still present. That is the feature
+working. Force a rebuild with `--force`.
+
+### Stale output after changing a flag
+
+The object cache key deliberately excludes compiler flags, which is why scripts
+that change flags (such as runtime coverage) use a separate
+`xbintsc_CACHE_DIR`. If you suspect a stale artefact, pass `--force` or delete
+`.xbintsc/`.
+
+### `run` exits with a non-zero status but there is no error message
+
+`run` propagates the **program's** exit status; the compiler succeeded. Run it
+directly (`./build/app`) to see the program's own output.
+
+### `xbintsc: run requires --emit exe`
+
+`run` only executes executables. Use `build --emit ir` or `emit` to inspect IR.
+
+### Program output appears in an unexpected order
+
+`async`/`await` is a synchronous microtask model and the event loop only runs
+after the program body. Timer and socket callbacks therefore fire late; see
+[language-support.md](./language-support.md).
+
+## Where to look in the code
+
+| Symptom | Source |
+| --- | --- |
+| A diagnostic message or code | [../../src/diagnostics/diagnostic.ts](../../src/diagnostics/diagnostic.ts), emit sites under `src/` |
+| A missing feature | [../../src/codegen/](../../src/codegen/) — `UnsupportedFeature` is raised there |
+| An import that will not resolve | [../../src/driver/bundler/](../../src/driver/bundler/) |
+| clang invocation, linker flags | [../../src/driver/toolchain.ts](../../src/driver/toolchain.ts), [../../src/driver/toolchain-provider.ts](../../src/driver/toolchain-provider.ts) |
+| Cache behaviour | [../../src/driver/cache.ts](../../src/driver/cache.ts) |
+| Runtime crashes, GC, values | `runtime/*.c`, `runtime/rt.h` |
+
+If you are changing the compiler rather than using it, read
+[contributing.md](./contributing.md) next.

package/doc/ai/zh-CN/README.md

@@ -0,0 +1,56 @@
+# 面向 AI 的 xbintsc 使用指南
+
+**xbintsc 把 TypeScript 的一个子集直接编译成原生二进制。** 它自己解析
+TypeScript，把程序降级为 LLVM IR 文本，再调用 `clang` 链接一个小型 C 运行时
+（`runtime/`）产出独立可执行文件。产物里没有 Node.js，也没有 TypeScript 编译器。
+
+```
+source.ts --词法分析--> tokens --语法分析--> AST --绑定--> 绑定后的 AST
+          --代码生成--> module.ll --clang--> module.o --链接--> 可执行文件
+```
+
+本目录是**面向 AI、按任务组织**的文档层：刻意写得短，并指向更权威的文档。
+请只读你当前任务需要的那一篇，不要通读整个目录。
+
+| 页面 | 什么时候读 |
+| --- | --- |
+| [build-recipe.md](./build-recipe.md) | 要编译或运行一个程序，需要确切的命令形状 |
+| [cli.md](./cli.md) | 需要完整参数表、项目配置或编程 API |
+| [language-support.md](./language-support.md) | 必须确认某个语法/API 是否存在，或是否与 Node 一致 |
+| [extensions.md](./extensions.md) | 需要 `fs`/`http`/…、GUI，或 C++/Rust 库 |
+| [troubleshooting.md](./troubleshooting.md) | 报错了，要定位原因并修好 |
+
+如果你要改的是**这个仓库本身**（而不是用它编译程序），先读
+[../../AGENTS.md](../../../AGENTS.md)：那里讲了目录结构、构建门禁与改动规则。
+
+## 三个决定一切的事实
+
+1. **只有 TypeScript 的一个子集能编译。** 不支持的语法会被直接拒绝，而不是
+   近似实现。动手写大段代码之前先确认。
+2. **类型全部被擦除，从不做类型检查。** 类型注解、接口、泛型、`as`/`satisfies`、
+   非空断言 `!` 在运行时没有任何作用，也没有类型检查器会跑。只有真实的运行时
+   行为才算数。
+3. **Node 兼容是可选且不完整的。** Node 模块由 `node` 扩展提供（`--ext node`）；
+   不支持直接 import 第三方 npm 包。
+
+## 选一条命令
+
+```bash
+# 直接运行程序（先编译成临时二进制，再执行）
+xbintsc run app.ts
+
+# 产出独立二进制
+xbintsc build app.ts --out build          # -> build/app[.exe]
+
+# 查看会被编译的 LLVM IR
+xbintsc emit app.ts
+
+# 查看 xbintsc 解析到的工具链
+xbintsc doctor
+```
+
+在源码检出里，把 `xbintsc` 换成 `npx tsx src/cli/main.ts`（或
+`npm run xbintsc --`）。发布压缩包里的二进制不需要 Node.js。
+
+下一步：要命令就[build-recipe.md](./build-recipe.md)，要写正经程序就先看
+[language-support.md](./language-support.md)。

package/doc/ai/zh-CN/build-recipe.md

@@ -0,0 +1,132 @@
+# 构建配方
+
+常见任务的可直接复制命令，以及让构建成功的关键前提。完整参数见
+[cli.md](./cli.md)；命令报错见 [troubleshooting.md](./troubleshooting.md)。
+
+## 调用编译器
+
+| 场景 | 调用方式 |
+| --- | --- |
+| 已发布的独立压缩包 | `xbintsc …`（`bin/xbintsc[.exe]` 在 `PATH` 上） |
+| 源码检出，已编译 | `node dist/src/cli/main.js …` |
+| 源码检出，直接跑 TypeScript | `npx tsx src/cli/main.ts …` |
+| 源码检出，npm 脚本 | `npm run xbintsc -- …` |
+| 源码检出，bin 启动器 | `node bin/xbintsc.js …`（会自动回退到 `tsx`） |
+
+下文为简洁统一写作 `xbintsc`。
+
+## 运行程序
+
+```bash
+xbintsc run app.ts
+xbintsc run app.ts -- --flag value        # -- 之后的所有参数传给被运行的程序
+```
+
+`run` 先把程序编译成可执行文件，再以继承 stdio 的方式启动它。它要求
+`--emit exe`；`xbintsc run app.ts --emit ir` 是错误用法。`run` 的退出码就是被运行
+程序的退出码。
+
+## 构建独立二进制
+
+```bash
+xbintsc build app.ts                      # -> build/app（Windows 上是 build/app.exe）
+xbintsc build app.ts --out build/app      # 指定输出目录
+xbintsc build app.ts -o app.bin            # 或指定确切输出路径
+xbintsc build app.ts -O0                   # 优化级别：-O0 .. -O3（默认 -O2）
+xbintsc build app.ts --force               # 忽略增量缓存
+xbintsc build app.ts --verbose             # 输出进度
+```
+
+`build` 会打印产出的文件；如果增量缓存让本次构建无需干活，会额外打印
+`(cached)`：
+
+```
+xbintsc: wrote /abs/path/build/app
+```
+
+其他产出类型用于检查：
+
+```bash
+xbintsc build app.ts --emit ir   # 写出 app.ll
+xbintsc build app.ts --emit obj  # 写出 app.o
+```
+
+## 查看 LLVM IR
+
+```bash
+xbintsc emit app.ts > app.ll     # IR 输出到 stdout，不写任何文件
+```
+
+`emit` 不需要 clang，也不需要运行时库——它是确认"编译器到底理解了什么"最便宜
+的手段，也是不确定某个语法是否被支持时最快的反馈回路。
+
+## 能编译的程序形态
+
+```ts
+// app.ts —— ESM，不用 require()
+import { readFileSync } from "fs";          // 需要 `--ext node`
+
+function main(): void {
+  const text = readFileSync("package.json", "utf8");
+  console.log(text.length);
+}
+
+main();                                     // 顶层代码按顺序执行
+```
+
+- 使用 `import`/`export`；`require()` 会被拒绝。
+- 相对导入会被打包（`import { helper } from "./helper.js"` 会解析到
+  `helper.ts`）。
+- Node 内置模块用裸名（`fs`、`path`、`node:fs`），并且需要开启 `node` 扩展。
+
+## 项目配置：不带参数即可构建
+
+`xbintsc.config.json`（从入口文件所在目录向上查找，或用 `--config <path>` 指定，
+用 `--no-config` 关闭）承载构建选项，因此只敲 `xbintsc build` 就能工作。配置里的
+路径相对该配置文件解析，任何命令行参数都会覆盖对应字段。
+
+```json
+{
+  "entry": "src/app.ts",
+  "outDir": "build",
+  "optimize": "2",
+  "extensions": ["node"],
+  "app": { "name": "Demo", "icon": "assets/app.png" }
+}
+```
+
+机器可读的 schema 见 [../xbintsc.config.schema.json](../../xbintsc.config.schema.json)；
+完整字段表见 [cli.md](./cli.md)。
+
+## 带扩展编译
+
+只要 import 了 Node 模块，就必须开启对应扩展，否则编译失败。可一次开多个，用逗号
+分隔：
+
+```bash
+xbintsc run app.ts --ext node
+xbintsc run app.ts --ext node,gui
+```
+
+C++/Rust 库改用清单注册：
+
+```bash
+xbintsc run app.ts --ext-native ./mathx.manifest.json
+```
+
+两种扩展的编写方式都在 [extensions.md](./extensions.md)。
+
+## 编程 API
+
+写工具而不是写程序时：
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");   // IR 文本，不需要 clang
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+`build` 返回 `{ outputPath, irPath?, cached, diagnostics, bundlePath? }`，可恢复的
+问题通过 `diagnostics` 报告；但工具链失败会**抛异常**。子路径导出
+`xbintsc/driver` 暴露驱动内部能力。

package/doc/ai/zh-CN/cli.md

@@ -0,0 +1,127 @@
+# CLI 与配置参考
+
+权威的 `--help` 文本就是 [../../src/cli/main.ts](../../../src/cli/main.ts) 里的 `HELP`
+常量。本页补充帮助文本没有明说的语义。
+
+## 子命令
+
+| 命令 | 作用 | 需要 clang？ |
+| --- | --- | --- |
+| `xbintsc build <file.ts>` | 编译为 `exe`（默认）、`obj` 或 `ir` | 需要，`--emit ir` 除外 |
+| `xbintsc run <file.ts> [-- args]` | 编译成可执行文件并运行 | 需要（且只支持 `--emit exe`） |
+| `xbintsc emit <file.ts>` | 把 LLVM IR 打到 stdout，不写文件 | 不需要 |
+| `xbintsc doctor` | 报告解析到的工具链、运行时与图标工具 | 仅在探测时需要 |
+| `xbintsc version` | 打印版本 | 不需要 |
+| `xbintsc help` | 打印帮助文本 | 不需要 |
+
+任何命令加 `--help` 都会打印帮助并返回 0。未知命令会打印错误与帮助文本，返回 1。
+
+## 参数
+
+```
+-o, --output <path>   显式输出路径（覆盖 --out 与配置）
+    --out <dir>       输出目录（默认 build/）
+    --emit <kind>     exe | obj | ir（默认 exe）
+-O0 .. -O3            传给 clang 的优化级别（默认 -O2）
+    --ext <names>     开启内置扩展，逗号分隔（如 node,gui）
+    --ext-native <m>  通过 JSON 清单注册 C++/Rust 扩展（多个用逗号分隔）
+    --config <path>   使用指定项目配置，不做自动发现
+    --no-config       完全不读取项目配置
+    --icon <path>     嵌入应用图标（PNG/ICO/ICNS）
+    --bundle          macOS：额外产出 <name>.app
+    --app-name <name> Bundle / 显示名
+    --app-id <id>     macOS bundle 标识（如 com.example.demo）
+    --force           忽略增量缓存
+    --verbose         打印进度信息
+```
+
+少数容易踩的解析细节：
+
+- `--flag=value` 与 `--flag value` 都支持。
+- `-O`、`-O1`、`-O2`、`-O3` 都可以；裸 `-O` 等价于 `-O2`。
+- `--` 结束参数解析：其后的内容在 `run` 下属于被运行程序，在其他命令下是位置参数。
+- `-o` 会无条件吃掉下一个参数；其他带值参数在后一个参数以 `-` 开头时视为未给值。
+
+## 项目配置
+
+`xbintsc.config.json` 从**入口文件所在目录向上**查找（没有给入口文件时从当前目录
+开始）。文件里的每个路径相对该配置文件解析，命令行参数覆盖对应字段。`--no-config`
+完全跳过发现流程。
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `entry` | string | 入口 TypeScript 文件，使 `xbintsc build` 无需位置参数 |
+| `outDir` | string | 输出目录（默认 `build/`） |
+| `output` | string | 显式输出路径，覆盖 `outDir` |
+| `optimize` | `"0"｜"1"｜"2"｜"3"` | 优化级别 |
+| `extensions` | string[] | 开启的内置扩展，如 `["node"]` |
+| `extNative` | string[] | 原生扩展清单路径 |
+| `force` | boolean | 忽略增量缓存 |
+| `app.name` / `app.icon` / `app.bundle` / `app.bundleId` | | 应用元信息（[icon.md](../../zh-CN/icon.md)） |
+
+JSON schema：[xbintsc.config.schema.json](../../xbintsc.config.schema.json)。配置读不了
+或格式错误时，构建会以 `invalid JSON` 或 `Unable to read` 失败，而不会静默退回默认值。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `xbintsc_CLANG` | 指定 clang，替代从 `PATH` 解析 |
+| `xbintsc_LINKER_ARGS` | 额外链接参数（如 `-fuse-ld=lld`） |
+| `xbintsc_CACHE_DIR` | 对象缓存目录（默认 `.xbintsc`） |
+| `xbintsc_PREFER_PREBUILT` | `0` 强制从源码编译运行时 |
+| `xbintsc_BINARY` | `bin/` 启动器应运行的原生编译器二进制 |
+
+## 增量编译
+
+每次构建的键由入口源码哈希、编译器版本、构建选项、平台和已启用扩展集合共同决定
+（[../../src/driver/cache.ts](../../../src/driver/cache.ts)）。如果记录中的产物都还在，
+构建立即返回并打印 `(cached)`。C 运行时与扩展源码按同样机制缓存，对象文件放在
+`.xbintsc/`（或 `xbintsc_CACHE_DIR`）。
+
+`--force`（或配置 `force: true`）跳过新鲜度检查。如果构建结果疑似过期，这个键是
+第一个该看的东西——注意对象缓存的键刻意不含编译参数，这正是运行时覆盖率脚本使用
+独立缓存目录的原因。
+
+## 退出码
+
+- `0` —— 成功（对 `run` 而言是被运行程序退出 0）。
+- `1` —— 有诊断、用法错误，或编译器自身失败。
+- `run` 其他情况直接透传被运行程序的退出码。
+
+## 诊断信息
+
+错误渲染为 `file:line:col - error TS<code>: <message>`，并附带源码片段与插入符下划线。
+代码按阶段分段（[../../src/diagnostics/diagnostic.ts](../../../src/diagnostics/diagnostic.ts)）：
+
+| 区间 | 阶段 |
+| --- | --- |
+| TS1xxx | 词法分析 |
+| TS2xxx | 语法分析 |
+| TS3xxx | 名称绑定 |
+| TS4xxx | 检查器（`TS4005` 即 `UnsupportedFeature`） |
+| TS5xxx | 代码生成 |
+| TS6xxx | 驱动：`TS6001` 模块未找到、`TS6002` IO、`TS6003` 工具链、`TS6004` 缓存 |
+
+CLI 会在错误之后追加一行 `hint:`，指向对应文档（例如 `TS4005` 指向
+[language-support.md](./language-support.md)，`TS6001`/`TS6003` 指向
+[troubleshooting.md](./troubleshooting.md)）。工具链与 IO 失败是抛异常而非产生诊断，
+CLI 会以 `xbintsc: <message>` 加上同款提示来报告。
+
+## 编程 API
+
+```ts
+import { build, compileString } from "xbintsc";
+```
+
+- `compileString(source, fileName?, extensions?)` → `{ ir, diagnostics }`。纯 IR 生成：
+  不碰文件系统，不调用 clang。
+- `build(entryPath, options?)` → `BuildResult`。`options` 支持 `output`、`outDir`、
+  `emit`、`optimize`、`force`、`verbose`、`extensions`（注册表）、`app`、`clang`、
+  `preferPrebuilt`。
+- 返回值形状：`{ outputPath, irPath?, cached, diagnostics, ir?, bundlePath? }`。
+
+`build` 把源码级问题通过 `diagnostics` 报告——使用产物之前务必检查
+`diagnostics.some((d) => d.category === "error")`——但 clang 自身失败时会**抛出**
+`ToolchainError`（[../../src/driver/toolchain.ts](../../../src/driver/toolchain.ts)）。
+子路径 `xbintsc/driver` 另外导出缓存、工具链解析、配置加载、图标与 macOS bundle 助手。

package/doc/ai/zh-CN/contributing.md

@@ -0,0 +1,173 @@
+# 参与编译器开发
+
+本页接在 [../../AGENTS.md](../../../AGENTS.md) 之后读：那里讲了目录结构、构建门禁与规则，
+这里讲容易搞错的工作流细节。
+
+## 准备环境
+
+```bash
+npm install
+npm run typecheck        # tsc --noEmit
+npm run lint             # eslint + 600 行文件预算
+npm test                 # 单元测试 + 端到端测试
+```
+
+从源码运行编译器需要 Node.js ≥ 22；任何会链接二进制的操作都需要 **clang 16+** 工具链
+（见 [troubleshooting.md](./troubleshooting.md)）。`xbintsc emit` 既不需要 clang 也不需要
+运行时库，因此它是最快的内循环。
+
+可选但推荐——安装仓库钩子：
+
+```bash
+git config core.hooksPath .githooks
+```
+
+`.githooks/pre-commit` **会在每次提交时把补丁版本号 +1**，并把 `package.json` 与
+`package-lock.json` 一起折进该提交（`npm version patch --no-git-tag-version`）。请预期
+你的提交里会带版本号变更，不要对抗它。发布标签由 `release.yml` 创建，钩子从不打标签。
+
+## 测试套件
+
+| 命令 | 范围 |
+| --- | --- |
+| `npm test` | 全部：按模块的单元测试 + `tests/e2e` |
+| `npm run test:e2e` | 只跑"编译并运行"的测试 |
+| `npm run test:watch` | vitest 监听模式 |
+| `npm run coverage` | TypeScript 编译器（`src/`）的 V8 覆盖率 |
+| `npm run coverage:runtime` | C 运行时（`runtime/`）的 LLVM 覆盖率 |
+
+单元测试在 `tests/` 下按模块一个目录（`lexer`、`parser`、`binder`、`codegen`、
+`driver`、`extensions`、`cli`、`e2e`），与源码树镜像对应。边界用例放在它覆盖的模块
+旁边。
+
+`tests/e2e/` 会编译真实程序并运行产出的二进制，其中包含一个**差分测试框架**
+（`tests/e2e/differential-*.test.ts`）：把同一份源码分别交给 xbintsc 和 Node 执行，
+逐字节比较输出。这是仓库里最强的工具：只要动到语义，就往那里加用例，而不是断言一个
+手写的期望字符串。需要 clang 的测试在 clang 缺失时会自动跳过
+（[tests/helpers.ts](../../../tests/helpers.ts) 里的 `hasClang()`）——不要把这种跳过
+变成静默通过。
+
+## 两条不能破坏的不变量
+
+### 1. 自举不动点
+
+CI（[.github/workflows/ci.yml](../../../.github/workflows/ci.yml) 的 `self-host` 任务）
+用编译器编译自身，并要求各代生成的 IR 完全一致：
+
+```
+源码 --emit--> ref.ll
+源码 --build--> gen1 二进制
+gen1 --emit--> gen2.ll      # 必须等于 ref.ll
+gen1 --build--> gen2 二进制
+gen2 --emit--> gen3.ll      # 必须等于 ref.ll
+```
+
+由此推论：**任何改变生成 IR 的修改，都必须能被正在被修改的编译器自己复现**，并且 IR
+必须逐字节确定——包括迭代顺序、生成的符号名与编号。绝不要把不确定性（未受控的
+`Map`/`Set` 迭代顺序、时间戳、依赖文件系统顺序的东西）引入代码生成。
+
+第二个推论是字符串模型：编译器自身源码文本在各代中必须含义一致。编译后的字符串是
+UTF-8 字节，所以自举后的 `readFileSync`（`--ext node`）交给扫描器的是文件字节，而
+Node 交给它的是同一个文件已解码后的文本——读取源码文件一律走 `decodeUtf8`
+（[src/diagnostics/utf8.ts](../../../src/diagnostics/utf8.ts)），不要假设一个码元就是
+一个字节或一个字符。弄错的表现是：`gen2.ll` 里非 ASCII 字面量（比如提示语里的 `—`）
+被重新编码，这也正是这里逐字节比较 IR 而不是逐行比较的原因。
+
+本地验证：
+
+```bash
+npx tsx src/cli/main.ts emit src/cli/main.ts --ext node > scratch/ref.ll
+npx tsx src/cli/main.ts build src/cli/main.ts --ext node --out scratch/self --force
+./scratch/self/main emit src/cli/main.ts --ext node > scratch/gen2.ll   # Windows 上是 .exe
+diff scratch/ref.ll scratch/gen2.ll
+```
+
+### 2. 运行时 ABI 与值模型
+
+- 每个编译后的函数都用同一条 ABI：
+  `xt_value fn(xt_value env, int32_t argc, xt_value *argv)` —— 直接调用与闭包调用共用
+  这一条路径，`env` 通过 box 传递被捕获的变量。
+- 每个值都是一个 64 位字：double 不装箱，其余都是带标签指针（16 位标签 + 48 位载荷）。
+  该表示只定义一次：[../../../src/codegen/values.ts](../../../src/codegen/values.ts) 与
+  [../../../runtime/rt.h](../../../runtime/rt.h)；要改就一起改，否则别动。
+- 别扭的 JS 语义（`+` 强转、关系比较、属性访问、打印）委托给 `@xt_*` 运行时调用，而
+  不是内联。
+- GC 是非移动标记清扫：新堆对象走 `xt_alloc`；值存活期间必须能从显式根槽、已注册的
+  根提供者（事件循环、微任务队列）或 C 栈保守扫描到达。只存在于未被扫描的 C 局部
+  变量里的值就是 bug。
+
+## 修改运行时
+
+`runtime/` 是 C，按函数拆到多个编译单元（`xt_alloc.c`、`xt_values.c`、
+`xt_containers.c`、`xt_stdlib.c`、`xt_stdlib2.c` 等），共享 `runtime/rt_internal.h`。
+C 改动必须重建运行时才会生效：
+
+```bash
+npm run runtime            # tsx scripts/build-runtime.ts -> runtime/lib/<os>-<arch>/
+npm run runtime:clean      # 删除 build/runtime-obj 与 runtime/lib
+```
+
+新增 C 文件时必须同时更新列出运行时源文件的地方（[../../../src/driver/compiler.ts](../../../src/driver/compiler.ts)
+里的 `RUNTIME_SOURCES`），因为那份列表决定什么会被编译和链接。扩展的 C 源由扩展自己声明。
+
+## 新增或扩展一个扩展
+
+扩展就是一个普通对象（[../../../src/extensions/registry.ts](../../../src/extensions/registry.ts)），
+贡献 `runtimeSources()`、`modules()` / `builtins()`，可选贡献 `nativeObjects()` 或
+`assetLoaders()`。Node 扩展是"每个模块一个目录"，把 TypeScript 导出与实现它的 C 源
+配成对：
+
+```
+src/extensions/node/fs/index.ts        runtime/ext_node/fs/read_file.c
+```
+
+因此新增一个 Node 模块就是在两处各放一个目录，并在模块列表里注册；核心编译器不改。
+如果你的特性是可选的或与平台相关，它属于某个扩展，而不是 `src/codegen`。内置扩展
+列在 [../../../src/extensions/catalog.ts](../../../src/extensions/catalog.ts) —— 列在那里
+但未开启的扩展会产生可操作的 `pass --ext <name>` 提示，所以即使默认关闭也要把模块
+加进列表。
+
+不改编译器、纯用 C++/Rust 编写扩展的做法见
+[../../../examples/extensions/README.md](../../../examples/extensions/README.md)。
+
+## 新增一条诊断
+
+1. 在 [../../../src/diagnostics/diagnostic.ts](../../../src/diagnostics/diagnostic.ts)
+   的枚举里按阶段加入稳定代码（1xxx 词法、2xxx 语法、3xxx 绑定、4xxx 检查、5xxx 代码
+   生成、6xxx 驱动）。诊断码是公开接口——绝不要重新编号。
+2. 用你手上最精确的范围发出它；`formatDiagnostic` 会据此渲染文件、行、列、片段与
+   插入符。
+3. 让消息可操作，风格与现有消息一致：既说清哪里错了，也说清该做什么（`pass --ext
+   node`、`use an ESM import` 等）。如果读者还需要更多信息，CLI 的提示层会把诊断码
+   映射到文档——新增诊断码时同步扩展
+   [../../../src/cli/main.ts](../../../src/cli/main.ts) 里的映射。
+4. 在 `tests/diagnostics` 或该模块自己的测试里覆盖它。
+
+## 文档是改动的一部分
+
+文档没同步，功能就不算完成：
+
+| 文档 | 何时更新 |
+| --- | --- |
+| [../../zh-CN/implemented.md](../../zh-CN/implemented.md) | 某特性开始可用 |
+| [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) | 出现或解除了某个限制 |
+| [../../zh-CN/node-implemented.md](../../zh-CN/node-implemented.md) / [../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md) | Node 模块覆盖变化 |
+| [language-support.md](./language-support.md) | 上述内容的 AI 摘要变化 |
+| [../../zh-CN/requirements.md](../../zh-CN/requirements.md) | 工具链或平台要求变化 |
+| [cli.md](./cli.md) | 参数、配置字段或环境变量变化 |
+
+中文翻译（`doc/zh-CN/`、`doc/ai/zh-CN/`）要与英文源同步；半翻译的页面比没有更糟，因为
+它会静默过期。
+
+## 仓库卫生
+
+- **每个代码文件 600 行**：TS/JS 由 ESLint（`max-lines`）强制，C、C++、Rust、`.inc`
+  与 shell 由 [scripts/check-file-length.ts](../../../scripts/check-file-length.ts) 强制。
+  请按职责拆分而不是把文件撑大；vendored 源码豁免。
+- **禁止 `any`**；`prefer-const` 与 `eqeqeq` 是错误。解析器/生成器里的声明合并模式是
+  有意放行的。
+- **公开 API 变更**走 [../../../src/index.ts](../../../src/index.ts)，并且必须保持
+  [../../../package.json](../../../package.json) 里 `xbintsc` / `xbintsc/driver` 的导出
+  映射有效。
+- `npm run package-release` 会把各平台压缩包组装到 `dist/release/`；发布工作流负责打
+  标签，所以永远不要手工推标签。