xbintsc 0.3.46 → 0.3.49

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

@@ -0,0 +1,139 @@
+# 扩展：Node 模块、GUI、C++/Rust 库
+
+编译器核心与平台无关。任何与平台相关的东西——Node 的 `fs`、一个 HTML/CSS 渲染器、
+你自己的 C++ 库——都以**扩展**的形式接入：它既贡献模块绑定，也贡献要一起编译/链接的
+C/C++ 源码或目标文件。
+
+## 最容易踩的规则
+
+**只要扩展没开启，import 它提供的模块就会失败。** xbintsc 知道该模块存在，并明确
+告诉你要传什么：
+
+```bash
+$ xbintsc run app.ts            # app.ts: import { readFileSync } from "fs";
+error TS6001: module 'fs' is provided by the 'node' extension; pass --ext node
+```
+
+```bash
+xbintsc run app.ts --ext node
+```
+
+多个扩展用逗号分隔一次开启：`--ext node,gui`。在项目里写进
+`xbintsc.config.json` 就不需要每次带参数：
+
+```json
+{ "entry": "src/app.ts", "outDir": "build", "extensions": ["node"] }
+```
+
+## 内置扩展
+
+### `node` —— Node 内置模块
+
+用 `--ext node` 开启。可以用裸名或 `node:` 前缀导入（`import { readFileSync } from
+"node:fs"`），两种写法解析到同一实现。
+
+| 模块 | 说明 |
+| --- | --- |
+| `fs` | **仅同步 API**（`readFileSync`、`writeFileSync` 等）；`fs/promises` 是独立模块 |
+| `fs/promises` | 基于 Promise 的文件 API |
+| `path` | 同时接入命名空间分发，`path.join(...)` 可用 |
+| `os` | |
+| `process` | `process.cwd()`、`argv`、`env` 等；也接入命名空间分发 |
+| `buffer` | |
+| `crypto` | |
+| `stream`、`stream/promises` | |
+| `events` | |
+| `net`、`dgram`、`http` | 跑在 xbintsc 事件循环上的套接字与服务端（注意下面的异步限制） |
+| `child_process` | |
+| `worker_threads` | |
+| `util`、`querystring`、`url`、`assert`、`test`、`zlib` | |
+
+各模块的具体覆盖（确切函数与选项）见
+[../../zh-CN/node-implemented.md](../../zh-CN/node-implemented.md)，缺失项见
+[../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md)。
+
+在 `net`/`http` 上搭东西之前，先记住运行时模型：事件循环在**程序主体之后**才运行，
+而 `async`/`await` 是同步微任务模型。见 [language-support.md](./language-support.md)。
+
+### `gui` —— HTML/CSS 窗口
+
+用 `--ext gui` 开启并导入 `gui` 模块：
+
+```ts
+import { createWindow, run } from "gui";
+```
+
+它是自带渲染引擎的 GPU 加速实现（自己的 HTML 解析器、CSS 级联、布局与合成器），不是
+系统 WebView。因为主体是 C++，它以各平台预编译的 `gui.a`/`gui.lib` 形式分发。如果该
+平台的归档不存在，构建会以明确的提示失败；设计与路线图见 [../../zh-CN/gui.md](../../zh-CN/gui.md)，
+脚本接口见 [../../zh-CN/gui-scripts.md](../../zh-CN/gui-scripts.md)。
+
+## 第三方 npm 包
+
+没有被已启用扩展认领的裸说明符，会在 `node_modules` 里查找并**作为源码**打包。不是
+纯 ESM TypeScript/JavaScript 的包——或依赖 CommonJS、`require`、`__dirname`、循环
+依赖的包——都不会工作。`require()` 会被拒绝并提示改用 `import`。
+
+实践结论：写 Node 程序时，正确做法通常就是开 `--ext node`；只有确实必要时才去依赖
+npm 包。
+
+## 原生扩展（C++ / Rust，无需改编译器）
+
+任何暴露了运行时 ABI 的 `extern "C"` 入口的代码都能被链接进来：
+
+```c
+xt_value my_fn(int32_t argc, xt_value *argv);
+```
+
+用**外部**工具链（clang++ 或 cargo）构建它，把产物写进一个 JSON 清单，然后传清单：
+
+```bash
+xbintsc build demo.ts --ext-native ./xbintsc.manifest.json
+xbintsc build demo.ts --ext-native a.json,b.json      # 多个
+```
+
+```jsonc
+{
+  "name": "mathx-cpp",                       // 必填，唯一
+  "objects": ["build/mathx.o"],              // .o / .a / .lib，相对本文件
+  "linkerFlagsByPlatform": {                 // C++/Rust 运行时
+    "linux":  ["-lstdc++", "-lm"],
+    "darwin": ["-lc++"],
+    "win32":  ["-lmsvcprt"]
+  },
+  "builtins": { "cppClamp": { "symbol": "mathx_clamp" } },   // 无需 import
+  "modules": {
+    "mathx": { "exports": { "add": { "symbol": "mathx_add" } } }
+  }
+}
+```
+
+之后 `import { add } from "mathx"` 会像 C 运行时绑定一样降级到原生符号；`builtins`
+无需导入即可全局调用。
+
+编写辅助头：`runtime/xt_ext.h`（C/C++）与 `runtime/xt_ext.rs`（Rust），它们封装了参数
+与值的辅助函数。关键 ABI 事实：值是 64 位 NaN-boxed 字；字符串**不**以 NUL 结尾，
+所以要把 `xt_string_data` 与 `xt_string_length_value` 配对使用；运行时交给你的内存
+不会被移动或释放。请使用与 xbintsc 解析到的同一个 clang/ABI 构建（`xbintsc doctor`
+会打印它）；在 Windows 上要在 **x64/ARM64 Native Tools 命令提示符**里构建。
+
+可直接照抄的工程：[`examples/extensions/cpp`](../../../examples/extensions/cpp) 与
+[`examples/extensions/rust`](../../../examples/extensions/rust)；完整指南见
+[../../../examples/extensions/README.md](../../../examples/extensions/README.md)。
+
+## 编程式注册
+
+```ts
+import { build, createDefaultRegistry, nativeExtensionFromManifest, nodeExtension } from "xbintsc";
+
+const extensions = createDefaultRegistry()
+  .register(nodeExtension)
+  .register(nativeExtensionFromManifest("./xbintsc.manifest.json"));
+
+build("demo.ts", { extensions });
+```
+
+注册表也是宿主工具提示"某扩展未开启"的机制，正是它把错误变成了可操作的
+"pass `--ext node`"，而不是下游令人困惑的报错
+（[../../../src/extensions/catalog.ts](../../../src/extensions/catalog.ts)）。内置扩展
+列表由 `bundledExtensions()` 提供。

package/doc/ai/zh-CN/language-support.md

@@ -0,0 +1,147 @@
+# 语言支持范围：什么能编译，什么行为不同
+
+xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能写什么；要精确措辞请
+点开链接。
+
+权威细节（始终最新、篇幅长得多）：
+
+- [../../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 扩展
+
+## 图例
+
+| 标记 | 含义 |
+| --- | --- |
+| ✅ | 与 Node/TypeScript 一致 |
+| ⚠️ | 可用，但与标准行为有偏差 |
+| 🚫 | 被拒绝——语法错误或 `UnsupportedFeature` |
+| — | 被解析后擦除，运行时无任何作用 |
+
+## 语句与声明
+
+| 特性 | 状态 | 说明 |
+| --- | --- | --- |
+| `var`/`let`/`const`、块、`if`、`for`、`for...of`、`for...in`、`while`、`do...while` | ✅ | `for...in` 只枚举自有键（不含原型链） |
+| `switch`、`break`、`continue`、标签 | ✅ | 含带标签的 `break`/`continue` |
+| `try`/`catch`/`finally`、`throw` | ✅ | 提前 `return`/`break`/`continue` 时 `finally` 仍会执行 |
+| `function`、箭头函数、默认参数/剩余参数 | ✅ | |
+| `namespace`/`module` 声明 | 🚫 | 解析 ✓，代码生成 ✗ |
+| `with`、`debugger` | 🚫 | 不支持 |
+| 顶层 `await` | 🚫 | 请包进 `async` 函数 |
+
+## 表达式与运算符
+
+| 特性 | 状态 | 说明 |
+| --- | --- | --- |
+| 算术、位运算、逻辑、比较、赋值运算符 | ✅ | `+` 与 `ToPrimitive` 强转与 Node 一致 |
+| `===`/`!==`/`==`/`!=` | ✅ | 宽松相等与 Node 一致 |
+| 可选链 `?.`、空值合并 `??`、逻辑赋值 `??=` | ✅ | 整条链的短路都已实现 |
+| 模板字符串、标签模板 | ✅ | 标签模板提供 `raw` 与 `String.raw` |
+| 调用/数组/对象字面量中的展开与剩余 | ✅ | |
+| 解构（绑定、参数、嵌套） | ✅ | 支持默认值与剩余 |
+| `delete`、`in`、`instanceof`、`typeof` | ✅ | |
+| 逗号运算符、`void` | ✅ | |
+| `new.target` | 🚫 | 未实现 |
+| `import.meta` | 🚫 | 能解析，但没有值 |
+| `super` | ⚠️ | 单层继承正确；继承深度 > 1 可能不准 |
+
+## 函数、类与对象
+
+| 特性 | 状态 | 说明 |
+| --- | --- | --- |
+| 闭包（通过 box 按引用捕获） | ✅ | 直接调用与闭包调用共用一条 ABI |
+| `this`、方法调用、箭头函数词法 `this` | ✅ | 与 JS 不同：箭头函数有自己的 `arguments` |
+| `call`/`apply`/`bind`、`fn.name`/`fn.length` | ✅ | bind 出的闭包不跟踪部分应用后的 `length` |
+| 一等内置方法（把 `arr.map` 当值用） | ✅ | 暴露为*未绑定*方法值；脱离接收者调用时与 JS 一样抛错 |
+| `fn.toString()` | ⚠️ | 返回 `function name() { [native code] }`，不是源码 |
+| 类：字段、方法、静态成员、getter/setter、`extends`/`super`、`instanceof` | ✅ | |
+| 构造器参数属性 `constructor(public x: T)` | ✅ | |
+| `#private` 字段/方法/静态成员 | ⚠️ | 以字面量 `#x` 键存储；不做访问控制；父子类同名可能互相覆盖 |
+| `enum`/`const enum` | ✅ | 正向 + 反向映射 |
+| `private`/`protected`/`public`/`readonly`/`abstract`/`implements` | — | 被擦除，无访问控制 |
+| 生成器 `function*`、`yield`、`yield*` | ✅ | 不支持 `async` 生成器 |
+| `arguments` 对象 | ✅ | 隐式提供；箭头函数看到的是自己的参数 |
+| 参数个数校验 | 🚫 | 从不校验，虽然 `fn.length` 会报声明元数 |
+
+## 异步、Promise 与事件循环
+
+| 特性 | 状态 | 说明 |
+| --- | --- | --- |
+| `async`/`await`、`Promise`、`Promise.all` | ⚠️ | **同步微任务模型**——`await` 一个已敲定的 Promise 会同步继续 |
+| `setTimeout` 与回调 | ⚠️ | 事件循环在**程序主体之后**才运行，因此定时器里敲定的 Promise 无法被 await |
+| 套接字/服务端（`http`、`net`、`dgram`） | ⚠️ | 同一模型：回调在程序主体之后的循环里执行 |
+| 真正的异步事件循环、worker 线程 | 🚫 | 未实现 |
+
+## 类型：解析后擦除
+
+**不做任何类型检查。** 类型语法被解析进 AST，随后在绑定/代码生成阶段擦除：
+
+| 构造 | 状态 |
+| --- | --- |
+| 类型注解、返回类型、类型别名、接口 | — 解析后擦除，从不检查 |
+| 泛型参数与约束 | — 运行时无实例化 |
+| `as`、`satisfies`、非空断言 `!` | — 擦除，无断言语义 |
+| 可选链的类型收窄 | 🚫 |
+| 诊断码 `TS4001`–`TS4004`（`TypeMismatch`、`NotCallable`、`PropertyNotFound`、`ArgumentCountMismatch`） | 🚫 有定义但从不发出 |
+
+因此源码里的类型错误**不是**编译错误——只有运行时行为会被检查。你想跑出什么行为，
+就写什么代码。
+
+## 标准库
+
+已实现：`Math`、`JSON`、`Date`、`RegExp`、`Map`、`Set`、`WeakMap`/`WeakSet`、
+`Symbol`、`Error` 家族、`BigInt`、`Array`/`String`/`Number`/`Object` 方法、TypedArray、
+带捕获组的 `String.prototype.match`/`split`/`replace`、不可变数组方法
+（`toReversed`、`toSorted`、`toSpliced`、`with`）、全局 URI 函数。
+
+| 缺失或行为不同 | 状态 |
+| --- | --- |
+| `String.prototype.normalize`、`structuredClone` | 🚫 |
+| `Error.stack` 采集 | 🚫（不采集） |
+| `Object.getPrototypeOf({})` | ⚠️ 返回 `undefined`，而非 `Object.prototype` |
+| 全局 RegExp `lastIndex` | ⚠️ `/g`、`/y` 下 `test`/`exec` 忽略它 |
+| 稀疏数组空洞、数组越界 | ⚠️ 不区分空洞；越界读得 `undefined` |
+
+完整列表见 [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) 第 3 节。
+
+## 模块
+
+| 特性 | 状态 | 说明 |
+| --- | --- | --- |
+| ESM `import`/`export` | ✅ | |
+| 相对路径多文件打包 | ✅ | `./helper.js` 会解析到 `helper.ts` |
+| `import * as ns`、默认导入与具名导入 | ✅ | |
+| Node 内置模块 | ✅ | 仅在 `--ext node` 下——见 [extensions.md](./extensions.md) |
+| 裸第三方 npm 包 | 🚫 | 只有当没有扩展认领该说明符时，`node_modules` 的 ESM 包才会作为源码打包 |
+| `require()` / CommonJS | 🚫 | 被拒绝，并提示改用 `import` |
+| 循环依赖 | 🚫 | |
+| 实时绑定 | ⚠️ | 导入与命名空间成员都是快照 |
+| `import.meta`、`__dirname`、`__filename` | 🚫 | |
+
+## 字符串、数字与内存
+
+| 项目 | 行为 |
+| --- | --- |
+| `String.prototype.length` | ⚠️ 按 **UTF-8 字节**计，不是 UTF-16 码元：`"é".length === 1`，`"😀".length === 4`；`codePointAt` 相应不同 |
+| 数字格式化与强转 | ✅ 与 Node 一致（`toFixed`、`toPrecision`、十六/八/二进制解析） |
+| `BigInt` | ✅ 已实现 |
+| 垃圾回收 | ✅ 非移动标记清扫；显式根 + C 栈保守扫描；单线程、stop-the-world；无弱引用 |
+| 线程 | 🚫 单线程；`worker_threads` 只存在于 Node 扩展中 |
+
+## 平台
+
+构建目标覆盖 macOS、Linux、Windows 的 x64 与 arm64。Windows 上是 **MSVC ABI**，
+clang 需要 MSVC/SDK 环境——见 [../../zh-CN/requirements.md](../../zh-CN/requirements.md)。
+需要 clang **16 或更新**。
+
+## 写大程序之前
+
+1. 扫一眼你要用的特性所在的行；凡标 ⚠️ 或 🚫 的，打开
+   [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) 确认。
+2. 用 `xbintsc emit app.ts` 做原型验证——这是确认某构造是否被支持最便宜的方式，
+   不需要 clang。
+3. 用 `xbintsc run app.ts` 跑真实程序；构建失败就去
+   [troubleshooting.md](./troubleshooting.md)。
+4. 需要精确对齐 Node 行为时，把同一程序在 Node 下跑一遍对比输出；项目自带测试套件
+   就是这么做的差分验证。

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

@@ -0,0 +1,150 @@
+# 排错指南
+
+先跑这条命令，看 xbintsc 到底解析到了什么：
+
+```bash
+xbintsc doctor
+```
+
+它会打印平台、将要使用的工具链（以及来源）、编译器版本、运行时目录、运行时库目录
+与图标资源编译器。绝大多数"跑不起来"的答案都在这里。
+
+## 首先确认：clang 够新吗？
+
+**需要 clang/LLVM 16 或更新。** 更老的 clang 会以有类型指针（typed pointer）错误
+拒绝生成的 IR：
+
+```
+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)
+```
+
+编译器生成的 LLVM IR 依赖不透明指针（opaque pointers），而有类型指针在 LLVM 16
+中被移除（[LLVM 发布说明](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)）。
+用 `clang --version` 确认；如果机器上的系统 clang 太旧，装一个新版 LLVM 并让 xbintsc
+用它：
+
+```powershell
+$env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
+```
+
+```bash
+export xbintsc_CLANG=/usr/lib/llvm-18/bin/clang
+```
+
+注意：只做前端工作（`xbintsc emit`）完全不需要 clang，所以在旧工具链上它照常可用。
+
+## 报错信息对照
+
+### `module '…' is provided by the 'node' extension; pass --ext node`
+
+程序导入了 Node 模块但扩展没开。加上参数，或写进 `xbintsc.config.json` 让它始终生效：
+
+```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`
+
+一个没人认领、也链不进来的裸第三方导入。要么该包是 CommonJS（不支持），要么它是
+打包失败的 ESM 包。优先改用 `node` 扩展提供的 Node 内置模块；可打包的范围见
+[extensions.md](./extensions.md)。
+
+### ``CommonJS `require()` is not supported``
+
+改写为 ESM：`const fs = require("fs")` 变成 `import fs from "fs"`（并加
+`--ext node`）。`node_modules` 包内部的 `require` 由打包器处理；只有你自己的源码里
+会被拒绝。`require(<非常量表达式>)` 永远不支持。
+
+### `error TS4005: xbintsc does not yet support this <construct>`
+
+语法解析通过了，但代码生成没实现。查 [language-support.md](./language-support.md) 与
+[../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md)，然后改写该构造（或者
+贡献实现）。常见的是 `namespace` 声明与 `new.target`。
+
+### `error TS2xxx`（语法分析）或 `error TS1xxx`（词法分析）
+
+源码语法错误。诊断会打印文件、行、列、出错的那一行以及插入符。注意 xbintsc 的
+解析器接受绝大多数 TypeScript，所以语法错误通常意味着语法真的坏了，而不是"不支持"。
+
+### `error TS6001: Cannot resolve module './x' from '<file>'` / `Cannot find module`
+
+相对导入解析不到。`./helper.js` 说明符会映射到 `helper.ts`，所以要按你实际写的
+TypeScript 运行时路径导入。
+
+### `Cannot resolve module '…' required from '<file>'`
+
+被打包的 `node_modules` 包内部的 `require(...)` 无法解析。该包不能直接用；请优先
+使用内置模块或换一个依赖。
+
+### `xbintsc: <config path>: invalid JSON (…)` / `Unable to read …`
+
+项目配置或原生扩展清单格式错误或不存在。修好 JSON，或用 `--no-config` /
+`--config <path>` 绕开自动发现。
+
+### `error TS6003` / `Command failed (N): clang …`
+
+clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——请读 stderr，不要只看
+第一行。常见原因：
+
+- 工具链太旧（见上文）；
+- Windows 上 clang 因为环境没导入而找不到 MSVC/SDK 头文件或库。请在
+  **x64 Native Tools Command Prompt for VS 2022**（ARM64 机器上是 **ARM64 Native
+  Tools**）里运行，或先导入环境：
+  ```powershell
+  & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
+  ```
+- Linux 上链接器不对——设置 `xbintsc_CLANG`，并/或传
+  `xbintsc_LINKER_ARGS=-fuse-ld=lld`；
+- `No C compiler found. Set xbintsc_CLANG to a clang binary.` —— `PATH` 里完全没有
+  clang。
+
+### `GUI native library not found at …`
+
+`gui` 扩展需要各平台预编译的 `gui.a`/`gui.lib`，普通源码检出并没有构建它。去掉
+`--ext gui`，或按 [../../zh-CN/gui.md](../../zh-CN/gui.md) 构建该归档。
+
+### `Icon file not found` / 图标工具缺失
+
+`--icon`/`app.icon` 的路径相对配置文件目录解析。Windows 上嵌入 PE 图标需要
+`llvm-rc` 或 `windres`；`doctor` 会报告找到了哪个，只有在确实请求了图标时缺失才是
+致命错误。
+
+## 看起来不对、其实正常的构建行为
+
+### 构建打印了 `(cached)` 并什么都没做
+
+增量缓存命中了：源码哈希、编译器版本、选项、平台与扩展集合都没变，且所有产物都还在。
+这正是设计目标。要强制重建就用 `--force`。
+
+### 改了参数后产物是旧的
+
+对象缓存的键刻意不含编译参数，这正是那些会改参数的脚本（如运行时覆盖率）使用独立
+`xbintsc_CACHE_DIR` 的原因。如果怀疑产物过期，传 `--force` 或删掉 `.xbintsc/`。
+
+### `run` 返回非零但没有错误信息
+
+`run` 透传的是**被运行程序**的退出码，编译器本身成功了。直接跑 `./build/app` 看程序
+自己的输出。
+
+### `xbintsc: run requires --emit exe`
+
+`run` 只能执行可执行文件。要看 IR 请用 `build --emit ir` 或 `emit`。
+
+### 程序输出顺序出乎意料
+
+`async`/`await` 是同步微任务模型，且事件循环只在程序主体之后运行，所以定时器和套接字
+回调会晚触发；见 [language-support.md](./language-support.md)。
+
+## 该去源码哪里看
+
+| 症状 | 源码 |
+| --- | --- |
+| 某条诊断文本或代码 | [../../../src/diagnostics/diagnostic.ts](../../../src/diagnostics/diagnostic.ts)，以及 `src/` 下的发出点 |
+| 某个特性缺失 | [../../../src/codegen/](../../../src/codegen/) —— `UnsupportedFeature` 在那里抛出 |
+| 导入解析不了 | [../../../src/driver/bundler/](../../../src/driver/bundler/) |
+| clang 调用、链接参数 | [../../../src/driver/toolchain.ts](../../../src/driver/toolchain.ts)、[../../../src/driver/toolchain-provider.ts](../../../src/driver/toolchain-provider.ts) |
+| 缓存行为 | [../../../src/driver/cache.ts](../../../src/driver/cache.ts) |
+| 运行时崩溃、GC、值 | `runtime/*.c`、`runtime/rt.h` |
+
+如果你要改的是编译器本身而不是用它，接着读 [contributing.md](./contributing.md)。