xbintsc 0.5.6 → 0.5.20

package/doc/zh-CN/implemented/driver.md

@@ -0,0 +1,19 @@
+# 驱动、增量编译与工具链
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/driver.md)
+
+实现位置：`src/driver/compiler.ts`（编排）、`src/driver/frontend.ts`、
+`src/driver/build-key.ts`、`src/driver/runtime-objects.ts`、
+`src/driver/app-artifacts.ts`、`src/driver/cache.ts`、`src/driver/toolchain.ts`、
+`src/driver/paths.ts`、`src/driver/version.ts`。
+
+- 编译流水线：读源 → 模块打包（`src/driver/modules.ts`，当入口含 `import`/`export` 时）→ 解析 → 绑定/检查 → IR → 目标文件 → 链接。
+- 增量缓存：以「编译器版本 + 源码哈希 + emit 类型 + 优化级别 + LTO/PGO 模式 + 平台 + 扩展指纹（名称、链接参数、原生对象内容）」为键，产物存在且新鲜则跳过构建。`--pgo-use` 总是重新构建，因为 profile 数据可能变化而源码不变。缓存键在 `src/driver/build-key.ts` 中组装。
+- C 运行时与扩展源按内容哈希缓存目标文件，只编译一次（缓存键包含 LTO/PGO 参数）。核心翻译单元列表 `RUNTIME_SOURCES` 位于 `src/driver/runtime-objects.ts`。
+- 工具链封装：查找 `clang`（可用 `xbintsc_CLANG` 覆盖）、编译 IR、编译 C、链接。
+- LTO（`--lto` / `"lto": true`）：程序与运行时都编译为 LLVM bitcode（`-flto`），并用 `-fuse-ld=lld` 链接；需要 lld。
+- PGO（先 `--pgo-generate[=dir]`，再 `--pgo-use[=dir]`，或配置 `"pgo"` / `"pgoDir"`）：生成 IR 与运行时 C 都用 `-fprofile-generate=<dir>` 插桩；运行插桩后的二进制，`--pgo-use` 会用 `llvm-profdata` 合并 `.profraw`（优先使用 clang 旁边的副本，可用 `xbintsc_LLVM_PROFDATA` 覆盖），再以 `-fprofile-use=<dir>` 重新构建。
+- 链接参数：非 Windows 自动加 `-lm`；扩展可追加链接参数。
+- 项目编译配置（`src/driver/config.ts`、`xbintsc.config.json`）：`entry`、`outDir`、`output`、`optimize`、`lto`、`pgo`、`pgoDir`、`extensions`、`extNative`、`force` 与 `app`（`name`、`icon`、`bundle`、`bundleId`）。从入口/当前目录向上查找，可用 `--config` 指定、`--no-config` 关闭；所有路径以配置文件所在目录为基准；CLI 参数优先于配置。
+- 应用图标（`src/driver/icon.ts`、`win-icon.ts`、`mac-bundle.ts`，`--icon`/`app.icon`）：PNG/ICO/ICNS 以 `xt_app_icon_*` 符号内嵌；Windows 上通过 `llvm-rc` 合成 PE 资源；macOS 上打包为 `Foo.app`（用 `sips`/`iconutil` 生成 `AppIcon.icns`）。`gui` 扩展用内嵌字节调用 `SDL_SetWindowIcon`；`xbintsc_RC` 可覆盖资源编译器。
+- 编译器版本：`COMPILER_VERSION` 位于 `src/driver/version.ts`，是缓存键的一部分。pre-commit 钩子只在 `main`/`master` 上（与 `package.json` 一起）提升它，因此功能分支不会改动版本文件。

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

@@ -0,0 +1,19 @@
+# 扩展机制（Extensions）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/extensions.md)
+
+实现位置：`src/extensions/registry.ts`、`src/extensions/node/`
+
+- 扩展是普通对象：`runtimeSources()`（额外 C 源）、`linkerFlags()`（额外链接参数）、`builtins()`（全局标识符 → 运行时符号，统一 `(argc, argv)` ABI）与 `modules()`（导入说明符 → 命名导出 / 命名空间）。
+- `ExtensionRegistry`：注册 / 注销 / 查询 / 汇总 builtins、modules、runtime 源、链接参数。
+- 内置核心扩展 `core`：暴露 `print`（映射 `xt_println`），始终注册。
+- Node 扩展 `node`：
+  - 模块化组织：`src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`
+  - 暴露可导入模块（`fs`、`fs/promises`、`path`、`os`、`process` 等），同时支持裸名称与 `node:` 前缀；`import { readFileSync } from "fs"` 解析到 `xt_node_read_text_file`，`path`/`os`/`process` 的导出映射到命名空间分发器。
+- 添加新模块只需新增目录 + C 实现，核心编译器无需改动。
+- 原生 C++/Rust 扩展（`src/extensions/native.ts`、`--ext-native`）：
+  - `nativeObjects()` 链接以 `(argc, argv)` ABI 暴露 `extern "C"` 符号的预编译对象/静态库；JSON manifest 把它们映射为 builtins/modules（`linkerFlags` / `linkerFlagsByPlatform` 用于 C++/Rust 运行时）。
+  - 编写辅助位于 `runtime/xt_ext.h`（C/C++）与 `runtime/xt_ext.rs`（Rust）；可运行工程在 `examples/extensions/`。
+  - 驱动原样链接这些产物，增量缓存会对其内容取指纹，因此重建库会使缓存二进制失效。
+  - CI 在 Linux、macOS、Windows 上都会构建两种语言的示例；Windows 下系统 clang 链接 MSVC ABI（C++ `-lmsvcprt`，Rust `*-pc-windows-msvc` 加 Windows 系统库）。
+- Node 模块覆盖情况见 [Node 扩展](./node.md)。

package/doc/zh-CN/implemented/fetch.md

@@ -0,0 +1,12 @@
+# fetch
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/fetch.md)
+
+实现位置：`runtime/xt_fetch.c`。
+
+- 全局 `fetch(input, init)` 是阻塞式 HTTP/1.1 客户端，返回的 promise 已经 settle（交换同步完成，不经过 reactor 调度）。
+- 只接受 `http://` URL —— 由于未链接 TLS 后端，`https://` 会以 `TypeError` 拒绝。
+- 选项：`method`、`headers`（普通对象或 `Headers`）、`body` 与 `redirect`（`follow` / `manual` / `error`）；最多跟随 20 次重定向，并在 301/302/303 时将 POST 改为 GET。
+- 解析出的 `Response` 形状对象暴露 `ok` / `status` / `statusText` / `url` / `headers` 以及 `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`。
+- `Headers` 大小写不敏感，提供 `get` / `has` / `set` / `append` / `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`。
+- 非法 URL 与网络失败会以 `TypeError` 拒绝。

package/doc/zh-CN/implemented/lexer.md

@@ -0,0 +1,23 @@
+# 词法分析（Lexer）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/lexer.md)
+
+实现位置：`src/lexer/scanner.ts`、`src/lexer/token.ts`
+
+- 完整 Token 分类：标识符、关键字、私有标识符、数字、字符串、模板、正则（扫描）、所有标点与运算符。
+- 完整关键字表：`abstract any as asserts async await bigint boolean break case catch class const constructor continue debugger declare default delete do else enum export extends false finally for from function get if implements import in infer instanceof interface is keyof let module namespace never new null number object package private protected public readonly return satisfies set static string super switch symbol this throw true try type typeof undefined unique unknown var void while with yield`
+- 数字字面量：
+  - 十进制、`0x` 十六进制、`0o` 八进制、`0b` 二进制
+  - 下划线分隔 `1_000_000`
+  - 小数、指数 `1.5e3`
+  - BigInt 字面量（`10n`、`0xFFn`）求值为任意精度整数（算术、位运算、移位、比较、`toString(radix)`、`BigInt()` / `BigInt.asIntN` / `BigInt.asUintN`）
+  - BigInt 字面量的值在词法 / 语法阶段即精确解析为 `bigint`（不经过 `Number`），超过 2^53 的字面量在 token / AST 中也保持完整精度
+- 字符串字面量：
+  - 单引号 / 双引号
+  - 转义：`\n \t \r \b \f \0 \\ \' \"`、`\xHH`、`\uHHHH`、`\u{...}`
+- 模板字面量（词法层）：无替换模板、模板头 `TemplateHead`、模板中 `TemplateMiddle`、模板尾 `TemplateTail`，支持 `${}` 与转义。
+- 正则字面量扫描（`/pattern/flags`），并区分除法 `/`。
+- 私有标识符 `#name`。
+- 注释：单行 `//` 与块注释 `/* */`（含未闭合诊断）。
+- 换行与空白跟踪（用于 ASI），BOM / CRLF 规范化（`SourceFile`）。
+- 词法诊断：未终止字符串 / 模板 / 注释、非法字符、非法数字、非法转义。

package/doc/zh-CN/implemented/modules.md

@@ -0,0 +1,28 @@
+# 模块系统
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/modules.md)
+
+实现位置：`src/parser/parser.ts`（语法）、`src/driver/modules.ts`（打包）、
+`src/driver/frontend.ts`（`parseEntry`）。
+
+## 语法
+
+- `import default, { named } from "..."`、`import * as ns from "..."`（相对模块的命名空间导入会降级为合成对象字面量；扩展模块如 `path` 亦已支持）、`import "./side-effect"`、`import type`
+- `export default`、`export { a as b }`、`export *`、`export =`
+- import attributes（`with` / `assert`）
+
+## 运行时语义
+
+- `import` / `export` 的**运行时语义**由 `src/driver/modules.ts` 在驱动层完成：递归解析相对依赖**以及裸名称的 `node_modules` 包**（遵循 `exports` / `module` / `main` 与包子路径），按模块前缀重命名顶层符号、改写引用，合并为单文件后重新绑定。
+- 包可以是 ESM 或 CommonJS：`node_modules` 内的 CJS 文件会获得合成的 `module` / `exports`，`require` 调用被降级为依赖的导出对象，静态识别出的导出对 ESM 导入方可见；`node_modules` 之外的 `require()` 仍报错并提示改用 `import`。循环依赖报错。
+- `.js` 系列说明符解析到对应 `.ts` 源码；省略后缀时优先 TypeScript 后缀而非同名的 JavaScript 文件；纯 `.js` / `.jsx` / `.mjs` / `.cjs` 源码也可直接打包。
+- 导入绑定与命名空间成员是模块求值时的快照（无实时绑定）—— 见[未实现：模块系统](../unimplemented/modules.md)。
+- 纯类型导入与再导出（`import type { T } from "..."`、`import { type T } from "..."`、`export type { T } from "..."`）会被擦除，**不构成模块依赖边**：目标模块不会被加载或打包，模块之间的纯类型循环也不属于循环依赖。若需要仅求值一个模块而不绑定名字，请使用副作用导入（`import "./mod"`）。
+
+## import.meta
+
+- `import.meta.url` / `.dirname` / `.filename`，由正在运行的可执行文件路径解析。
+
+## 扩展模块
+
+- 扩展模块（如 `fs`）可通过裸名称或 `node:` 前缀的 `import` 引入，并解析到运行时入口；见[扩展机制](./extensions.md)。

package/doc/zh-CN/implemented/node/assert.md

@@ -0,0 +1,17 @@
+# `assert` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/assert.md)
+
+实现位置：`src/extensions/node/assert/index.ts`、`runtime/ext_node/assert/assert.c`
+
+`assert.ok` / `fail` / `equal` / `notEqual` / `strictEqual` / `notStrictEqual` /
+`deepEqual` / `notDeepEqual` / `deepStrictEqual` / `notDeepStrictEqual` /
+`throws` / `doesNotThrow` / `rejects` / `doesNotReject` / `match` /
+`doesNotMatch` / `ifError`。
+
+具名导入与命名空间形式都分发到 `xt_assert_static`：
+
+```ts
+import assert from "node:assert";
+assert.strictEqual(1 + 1, 2);
+```

package/doc/zh-CN/implemented/node/buffer.md

@@ -0,0 +1,25 @@
+# `buffer` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/buffer.md)
+
+实现位置：`src/extensions/node/buffer/index.ts`、`runtime/ext_node/buffer/buffer.c`
+
+xbintsc 没有原生的二进制值类型，`Buffer` 以**普通对象**表示：每个字节是数字属性 `"0".."n-1"`，再加一个 `length` 属性，并共享 `xt_buffer_proto()` 原型提供实例方法。`xt_node_is_buffer` / `xt_node_buffer_bytes` 供其它模块跨模块访问字节。
+
+| 静态方法 | 说明 |
+| --- | --- |
+| `Buffer.from(value[, encoding])` | 从字符串（hex / base64 / utf8）、数组或 Buffer 构造 |
+| `Buffer.alloc(size[, fill])` | 分配并填充 |
+| `Buffer.allocUnsafe(size)` | 分配 |
+| `Buffer.isBuffer(value)` | 判定 |
+| `Buffer.byteLength(value[, encoding])` | 字节长度 |
+| `Buffer.concat(list[, totalLength])` | 拼接 |
+| `Buffer.compare(a, b)` | 比较 |
+
+实例方法：`toString([encoding])`、`toJSON()`、`slice(start, end)`、`subarray(...)`、`equals(other)`、`compare(other)`、`copy(target[, targetStart, sourceStart, sourceEnd])`、`write(string[, offset[, length[, encoding]]])`、`fill(value)`、`reverse()`、`indexOf(value)`、`lastIndexOf(value)`、`includes(value)`、`keys()`、`values()`，以及 `readUInt8/UInt16LE/UInt16BE/UInt32LE/UInt32BE`、`writeUInt8/UInt16LE/UInt16BE/UInt32LE/UInt32BE`。
+
+```ts
+const buf = Buffer.from("hello");
+console.log(buf.toString(), buf.length);      // hello 5
+console.log(Buffer.alloc(4, 65).toString());  // AAAA
+```

package/doc/zh-CN/implemented/node/child-process.md

@@ -0,0 +1,27 @@
+# `child_process` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/child-process.md)
+
+位置：`src/extensions/node/child_process/index.ts`、`runtime/ext_node/child_process/child_process.c`
+
+`spawnSync(command, args[, options])` 运行一个程序直到结束，返回
+`{ status, stdout, stderr }`。`options.cwd` 设置子进程工作目录；
+`options.stdio: "inherit"` 让子进程共用父进程的 stdout/stderr（`xbintsc run`
+用它把被编译程序的输出实时透传），否则 stdout/stderr 会作为 UTF-8 字符串捕获。
+
+| 选项 | 说明 |
+| --- | --- |
+| `cwd` | 子进程的工作目录 |
+| `stdio: "inherit"` | 共用父进程的 stdout/stderr，而不是捕获 |
+| `encoding` | 接受但忽略（输出始终按 UTF-8 解码） |
+
+Windows 上子进程通过 `CreateProcess` 启动，stdout/stderr 由读线程经匿名管道持续排空。
+不使用临时文件，因此受限的 `%TEMP%` 不会让 `spawnSync` 失败，输出超过管道缓冲区时
+也不会死锁。
+
+```ts
+import { spawnSync } from "child_process";
+
+const result = spawnSync("clang", ["--version"], { encoding: "utf8" });
+console.log(result.status, result.stdout.split("\n")[0]);
+```

package/doc/zh-CN/implemented/node/crypto.md

@@ -0,0 +1,9 @@
+# `crypto` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/crypto.md)
+
+实现位置：`src/extensions/node/crypto/index.ts`、`runtime/ext_node/crypto/crypto.c`
+
+- `createHash(algorithm)` 返回带 `update(...)` 与 `digest([encoding])` 的哈希对象。
+- 支持流式形式（`setEncoding` / `write` / `end` / `read`）。
+- 提供 SHA-1 与 SHA-256。

package/doc/zh-CN/implemented/node/dgram.md

@@ -0,0 +1,15 @@
+# `dgram` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/dgram.md)
+
+实现位置：`src/extensions/node/dgram/index.ts`、`runtime/ext_node/dgram/dgram.c`
+
+UDP 套接字。`dgram.createSocket(type | options[, cb])` 返回 EventEmitter。
+
+| 方法 | 说明 |
+| --- | --- |
+| `bind([port][, address][, cb])` | 绑定（未绑定时 `send` 会自动绑定） |
+| `send(msg[, offset, length,] port[, address][, cb])` | 发送数据报 |
+| `close([cb])` / `address()` | 关闭 / 查询地址 |
+| `setBroadcast(b)` / `setTTL(n)` / `setMulticastTTL(n)` | 套接字选项 |
+| `on('message', (msg, rinfo) => ...)` | 收到数据报，`rinfo` 含 `address` / `port` / `family` / `size` |

package/doc/zh-CN/implemented/node/events.md

@@ -0,0 +1,36 @@
+# `events` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/events.md)
+
+位置：`src/extensions/node/events/index.ts`、`runtime/ext_node/events/events.c`
+
+提供独立的 `EventEmitter`，既可以作为**全局构造函数**使用
+（`new EventEmitter()`），也可以作为命名导出（`import { EventEmitter } from
+"events"`）。实例与 `stream` / `net` / `http` 共用运行时事件发射器（监听器存放
+在内部的 `__xt_events` 属性上），并在此基础上提供更完整的 `events` 接口：
+
+| 方法 | 说明 |
+| --- | --- |
+| `on(name, fn)` / `addListener(name, fn)` | 追加监听器 |
+| `once(name, fn)` | 最多触发一次，然后自行移除 |
+| `prependListener(name, fn)` / `prependOnceListener(name, fn)` | 插入到最前 |
+| `off(name, fn)` / `removeListener(name, fn)` | 移除监听器 |
+| `removeAllListeners([name])` | 清空某个（或全部）事件 |
+| `emit(name[, ...args])` | 触发监听器 |
+| `listeners(name)` / `rawListeners(name)` | 监听器数组 |
+| `listenerCount(name)` | 监听器数量 |
+| `eventNames()` | 当前有监听器的事件名 |
+| `setMaxListeners(n)` / `getMaxListeners()` | 记录（默认 10） |
+
+通过命名空间（`import ee from "events"`）可访问的静态方法：`listenerCount`、
+`getEventListeners`、`getMaxListeners`、`setMaxListeners`、`once`、
+`addAbortListener`。
+
+```ts
+import { EventEmitter } from "events";
+
+const em = new EventEmitter();
+em.once("ready", () => console.log("ready"));
+em.emit("ready"); // ready
+em.emit("ready"); // 无输出：监听器已执行过
+```

package/doc/zh-CN/implemented/node/fs-promises.md

@@ -0,0 +1,27 @@
+# `fs/promises` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/fs-promises.md)
+
+实现位置：`src/extensions/node/fs-promises/index.ts`、`runtime/ext_node/fs/promises.c`
+
+无异步 I/O 调度器，故每个函数把对应的同步 `fs` 实现包进**已 settle 的 Promise**。失败时会以同步形式抛出的同构 Node `Error`（含 `code` / `errno` / `syscall` / `path`）**reject**。`fs.promises` 也可从 `fs` 模块访问（`import { promises as fsp } from "fs"`），两个命名空间都暴露 `constants` 对象。
+
+Promise 导出：`readFile`、`writeFile`、`appendFile`、`mkdir`、`readdir`、`rm`、`unlink`、`rmdir`、`rename`、`copyFile`、`cp`、`realpath`、`stat`、`lstat`、`statfs`、`access`、`open`、`chmod`、`lchmod`、`chown`、`lchown`、`truncate`、`utimes`、`lutimes`、`link`、`symlink`、`readlink`、`mkdtemp`、`opendir`、`glob`、`watch`。
+
+`open(...)` 解析为 **`FileHandle`**，带有：`read`、`write`、`readFile`、`writeFile`、`appendFile`、`close`、`stat`、`truncate`、`chmod`、`chown`、`utimes`、`sync`、`datasync`。
+
+```ts
+import { readFile, writeFile, open } from "fs/promises";
+
+async function main(): Promise<void> {
+  await writeFile("/tmp/a.txt", "hi");
+  console.log(await readFile("/tmp/a.txt"));
+  const handle = await open("/tmp/a.txt", "r");
+  console.log(await handle.readFile("utf8"));
+  await handle.close();
+}
+main();
+```
+
+
+已知偏差见[未实现：`fs/promises`](../../unimplemented/node/fs-promises.md)。

package/doc/zh-CN/implemented/node/fs.md

@@ -0,0 +1,105 @@
+# `fs` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/fs.md)
+
+实现位置：`src/extensions/node/fs/*.ts`、`runtime/ext_node/fs/*.c`
+
+## 可用函数（从 `fs` 导入）
+
+| 导入函数 | 运行时符号 | 说明 |
+| --- | --- | --- |
+| `readFileSync(path[, options])` | `xt_node_read_text_file` | 同步读取文件，返回字符串；支持编码选项 |
+| `readTextFile(path)` | `xt_node_read_text_file` | `readFileSync` 的别名（同一符号） |
+| `writeFileSync(path, data[, options])` | `xt_node_write_file` | 覆盖写入；接受字符串或 `Buffer` |
+| `appendFileSync(path, data[, options])` | `xt_node_append_file` | 追加写入；接受字符串或 `Buffer` |
+| `existsSync(path)` | `xt_node_exists` | 是否存在，返回布尔值 |
+| `readdirSync(path[, options])` | `xt_node_read_dir` | 目录项名称；`{ withFileTypes: true }` 返回 `Dirent`，`{ recursive: true }` 递归 |
+| `mkdirSync(path[, options])` | `xt_node_mkdir` | 创建目录，`{ recursive: true }` 递归创建，`{ mode }` 生效 |
+| `rmSync(path[, options])` | `xt_node_rm` | 删除文件/目录，`{ recursive: true }` 递归删除 |
+| `unlinkSync(path)` | `xt_node_unlink` | 删除文件 |
+| `rmdirSync(path)` | `xt_node_rmdir` | 删除空目录 |
+| `renameSync(oldPath, newPath)` | `xt_node_rename` | 重命名 / 移动 |
+| `copyFileSync(src, dest[, flags])` | `xt_node_copy_file` | 复制文件；支持 `COPYFILE_EXCL` |
+| `cpSync(src, dest[, options])` | `xt_node_cp` | 递归复制；`recursive` / `force` / `errorOnExist` / `dereference` / `preserveTimestamps` |
+| `realpathSync(path)` | `xt_node_realpath` | 解析为绝对路径 |
+| `statSync(path)` | `xt_node_stat` | 文件元信息对象（跟随符号链接） |
+| `lstatSync(path)` | `xt_node_lstat` | 文件元信息对象（不跟随符号链接） |
+| `statfsSync(path)` | `xt_node_statfs` | 文件系统统计（`bsize` / `blocks` / `bfree` …） |
+| `accessSync(path[, mode])` | `xt_node_access` | 检查可访问性 |
+| `chmodSync(path, mode)` | `xt_node_chmod` | 修改权限 |
+| `lchmodSync(path, mode)` | `xt_node_lchmod` | 修改符号链接权限 |
+| `chownSync(path, uid, gid)` | `xt_node_chown` | 修改属主 |
+| `lchownSync(path, uid, gid)` | `xt_node_lchown` | 修改符号链接属主 |
+| `truncateSync(path[, len])` | `xt_node_truncate` | 截断文件 |
+| `utimesSync(path, atime, mtime)` | `xt_node_utimes` | 设置访问/修改时间（秒数或 `Date`） |
+| `lutimesSync(path, atime, mtime)` | `xt_node_lutimes` | 设置符号链接时间 |
+| `mkdtempSync(prefix)` | `xt_node_mkdtemp` | 创建唯一临时目录 |
+| `linkSync(existing, newPath)` | `xt_node_link` | 硬链接 |
+| `symlinkSync(target, path[, type])` | `xt_node_symlink` | 符号链接 |
+| `readlinkSync(path)` | `xt_node_readlink` | 读取符号链接目标 |
+| `opendirSync(path[, options])` | `xt_node_opendir` | 返回 `Dir`（`readSync` / `closeSync` / `read` / `close`） |
+| `globSync(pattern[, options])` | `xt_node_glob` | glob 匹配（`*` / `?` / `[...]` / `**`），`{ cwd, withFileTypes }` |
+| `openSync(path[, flags[, mode]])` | `xt_node_open` | 打开文件描述符 |
+| `closeSync(fd)` | `xt_node_close` | 关闭描述符 |
+| `readSync(fd, buffer, offset, length, position)` | `xt_node_read` | 读入 `Buffer` |
+| `writeSync(fd, data[, offset[, length[, position]]])` | `xt_node_write` | 写入字符串 / `Buffer` |
+| `readvSync(fd, buffers[, position])` | `xt_node_readv` | 分散读 |
+| `writevSync(fd, buffers[, position])` | `xt_node_writev` | 聚集写 |
+| `fstatSync(fd)` | `xt_node_fstat` | 描述符的 `stat` |
+| `fsyncSync(fd)` / `fdatasyncSync(fd)` | `xt_node_fsync` / `xt_node_fdatasync` | 刷新描述符 |
+| `ftruncateSync(fd[, len])` | `xt_node_ftruncate` | 截断描述符 |
+| `fchmodSync(fd, mode)` | `xt_node_fchmod` | 描述符的 `chmod` |
+| `fchownSync(fd, uid, gid)` | `xt_node_fchown` | 描述符的 `chown` |
+| `futimesSync(fd, atime, mtime)` | `xt_node_futimes` | 描述符的 `utimes` |
+| `watch(filename[, options][, listener])` | `xt_node_watch` | 返回发射器形态的 watcher（不会触发，见[未实现：`fs`](../../unimplemented/node/fs.md)） |
+| `watchFile(filename[, options], listener)` | `xt_node_watch_file` | 轮询形态的 `StatWatcher`（不会触发） |
+| `unwatchFile(filename[, listener])` | `xt_node_unwatch_file` | 停止监听 |
+| `constants` | `xt_fs_constants` | `F_OK` / `R_OK` / `W_OK` / `X_OK`、`COPYFILE_*`、`O_*`、`S_IF*`（宿主值） |
+| `promises` | `xt_fs_promises` | `fs/promises` 门面（见 [`fs/promises`](./fs-promises.md)） |
+
+## 编码支持
+
+`readFileSync` / `writeFileSync` / `appendFileSync` 的 `options` 可以是编码字符串，也可以是 `{ encoding: "..." }`：
+
+| 编码 | 读取 | 写入 |
+| --- | --- | --- |
+| 默认 / `utf8` / `utf-8` / `ascii` / `latin1` / `binary` | 原始 UTF-8 文本 | 按文本字节写入 |
+| `hex` | 小写十六进制字符串 | 解析十六进制后写入 |
+| `base64` | Base64 字符串 | 解析 Base64 后写入 |
+| `base64url` | Base64url 字符串 | 解析 Base64url 后写入 |
+| `utf16le` / `ucs2` | 按文本直接读取原始字节（不做 UTF-16 解码） | 按 UTF-8 文本写入 |
+
+> `readFileSync` 默认仍返回**字符串**而不是 `Buffer`（即使 `Buffer` 类已存在），这样 `console.log(readFileSync(p))` 仍打印文本。
+
+## `statSync` 返回结构
+
+返回普通对象，数值属性：`size`、`mode`、`uid`、`gid`、`dev`、`ino`、`nlink`、`rdev`、`blksize`、`blocks`、`atimeMs`、`mtimeMs`、`ctimeMs`、`birthtimeMs`。
+方法（原生闭包，可调用）：`isFile()`、`isDirectory()`、`isSymbolicLink()`、`isFIFO()`、`isSocket()`、`isBlockDevice()`、`isCharacterDevice()`。
+
+## 调用方式
+
+`fs` 的导出通过 `import` 引入（也可用 `node:fs` 别名），不再以裸全局标识符暴露：
+
+```ts
+import { readFileSync, writeFileSync, existsSync } from "fs";
+
+const text = readFileSync("examples/data.txt");
+writeFileSync("/tmp/out.txt", text);
+console.log(existsSync("/tmp/out.txt"));
+```
+
+## 错误处理
+
+失败时函数会**抛出** Node 形态的 `Error` 对象，带有 `name`（`Error`）、`message`、`code`（如 `ENOENT`）、`errno`（数值 `errno`）、`syscall` 与 `path`。`existsSync` 仍返回布尔值，不会抛出。
+
+```ts
+import { readFileSync } from "fs";
+try {
+  readFileSync("/does/not/exist");
+} catch (error) {
+  console.log((error as any).code); // ENOENT
+}
+```
+
+
+已知偏差见[未实现：`fs`](../../unimplemented/node/fs.md)。

package/doc/zh-CN/implemented/node/http.md

@@ -0,0 +1,17 @@
+# `http` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/http.md)
+
+实现位置：`src/extensions/node/http/index.ts`、`runtime/ext_node/http/http.c`
+
+服务端包裹一个 `net` 服务端：每个连接累积字节直到完整请求（请求行 + 头 + `Content-Length` body）可用，再以 `req`/`res` 调用 `request` 监听器。客户端包裹一个 `net` 套接字，写出 HTTP/1.1 请求并在连接关闭后解析响应。
+
+| API | 说明 |
+| --- | --- |
+| `http.createServer([requestListener])` | 创建 HTTP 服务端 |
+| `http.request(options[, cb])` | 创建 `ClientRequest`（`write` / `end` / `setHeader`） |
+| `http.get(url[, cb])` | 发起 GET |
+
+`IncomingMessage`（`req` / 响应）：`method`、`url`、`httpVersion`、`headers`、`statusCode`、`data` / `end` 事件、`setEncoding`。
+
+`ServerResponse`（`res`）：`writeHead(status[, message][, headers])`、`setHeader` / `getHeader` / `removeHeader` / `getHeaders`、`write(chunk)`、`end([chunk])`，事件 `finish` / `close`。响应固定带 `Connection: close`（不做 keep-alive）。

package/doc/zh-CN/implemented/node/net.md

@@ -0,0 +1,17 @@
+# `net` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/net.md)
+
+实现位置：`src/extensions/node/net/index.ts`、`runtime/ext_node/net/net.c`
+
+TCP 服务端与客户端，基于核心事件循环。
+
+| API | 说明 |
+| --- | --- |
+| `net.createServer([connectionListener])` | 创建 TCP 服务端（`Server` 构造函数等价） |
+| `net.connect(...)` / `net.createConnection(...)` | 连接（阻塞式 connect，之后注册事件循环） |
+| `net.isIP(s)` / `net.isIPv4(s)` / `net.isIPv6(s)` | 地址判定 |
+
+`Server`：`listen(port[, host][, cb])`、`close([cb])`、`address()`、`getConnections(cb)`，事件 `listening` / `connection` / `close`。
+
+`Socket`：`write(data[, cb])`、`end([data])`、`destroy()`、`address()`、`setEncoding(enc)`、`pause()` / `resume()`，事件 `data` / `end` / `close` / `connect` / `error`。

package/doc/zh-CN/implemented/node/os.md

@@ -0,0 +1,21 @@
+# `os` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/os.md)
+
+实现位置：`src/extensions/node/os/index.ts`、`runtime/ext_node/os/os.c`
+
+采用 `os.<name>(...)` 命名空间调用，降为 `xt_os_static(<name>, argc, argv)`。
+以命名空间方式导入（`import os from "os"`），或单独导入函数（`import { platform } from "os"`）。
+
+| 方法 | 说明 |
+| --- | --- |
+| `os.platform()` | `darwin` / `linux` / `win32` / ... |
+| `os.arch()` | `x64` / `arm64` / `ia32` / `arm` |
+| `os.type()` | `Darwin` / `Linux` / `Windows_NT` / ... |
+| `os.release()` | 内核版本 |
+| `os.endianness()` | `LE` / `BE` |
+| `os.homedir()` | 用户主目录 |
+| `os.tmpdir()` | 临时目录 |
+| `os.hostname()` | 主机名 |
+| `os.totalmem()` / `os.freemem()` | 总内存 / 可用内存（字节） |
+| `os.cpus()` | CPU 条目数组（`model` / `speed` 占位） |

package/doc/zh-CN/implemented/node/path.md

@@ -0,0 +1,26 @@
+# `path` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/path.md)
+
+实现位置：`src/extensions/node/path/index.ts`、`runtime/ext_node/path/path.c`
+
+采用 `path.<name>(...)` 命名空间调用，编译器将其降为 `xt_path_static(<name>, argc, argv)`。结果在所有平台上都以 POSIX `/` 分隔符输出（Windows 也接受 `/`），但输入可以使用 Windows 原生分隔符：在 Windows 上 `/` 与 `\` 都被识别，并保留盘符前缀（`C:`），因此自举后的编译器能正确解析带盘符的路径。以命名空间方式导入（`import path from "path"` / `import * as path from "path"`），或单独导入方法（`import { join } from "path"`）。
+
+| 方法 | 说明 |
+| --- | --- |
+| `path.join(...parts)` | 拼接并规范化 |
+| `path.resolve(...parts)` | 解析为绝对路径 |
+| `path.normalize(path)` | 规范化 |
+| `path.dirname(path)` | 目录名 |
+| `path.basename(path[, ext])` | 文件名，可去掉扩展名 |
+| `path.extname(path)` | 扩展名 |
+| `path.isAbsolute(path)` | 是否绝对路径 |
+| `path.relative(from, to)` | 相对路径 |
+
+```ts
+import path from "path";
+import { basename } from "path";
+
+console.log(path.join("a", "b", "..", "c")); // a/c
+console.log(basename("/x/y/z.txt"));          // z.txt
+```

package/doc/zh-CN/implemented/node/process.md

@@ -0,0 +1,23 @@
+# `process` 对象
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/process.md)
+
+实现位置：`src/extensions/node/process/index.ts`、`runtime/ext_node/process/process.c`
+
+方法调用降为 `xt_process_call(<name>, argc, argv)`，属性访问降为 `xt_process_get(<name>)`。
+通过 `import process from "process"` 导入后使用。
+
+| 方法 / 属性 | 说明 |
+| --- | --- |
+| `process.cwd()` | 当前工作目录 |
+| `process.exit([code])` | 退出进程 |
+| `process.uptime()` | 进程运行时间（秒） |
+| `process.hrtime()` | `[秒, 纳秒]` 数组 |
+| `process.getuid()` | 用户 ID（Windows 返回 0） |
+| `process.platform` / `process.arch` | 平台 / 架构 |
+| `process.pid` / `process.ppid` | 进程 ID / 父进程 ID |
+| `process.argv` | 参数数组（`argv[0]` 为可执行文件） |
+| `process.env` | 环境变量对象 |
+| `process.version` / `process.title` | 占位字符串 |
+
+> `argv` 由生成的 `main` 通过 `xt_set_program_args` 捕获后提供给运行时。

package/doc/zh-CN/implemented/node/querystring.md

@@ -0,0 +1,20 @@
+# `querystring` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/querystring.md)
+
+位置：`src/extensions/node/querystring/index.ts`、`runtime/ext_node/querystring/querystring.c`
+
+| 函数 | 说明 |
+| --- | --- |
+| `parse(str[, sep[, eq]])` / `decode` | 解析为对象；重复的键会变成数组 |
+| `stringify(obj[, sep[, eq]])` / `encode` | 序列化；空格变成 `+`，数组会重复键 |
+| `escape(str)` / `unescape(str)` | 百分号编码 / 解码（`+` 解码为空格） |
+
+默认值：`sep = "&"`，`eq = "="`。
+
+```ts
+import { parse, stringify } from "querystring";
+
+const q = parse("a=1&b=2&b=3");      // { a: "1", b: ["2", "3"] }
+console.log(stringify({ x: "a b" })); // x=a+b
+```

package/doc/zh-CN/implemented/node/stream-promises.md

@@ -0,0 +1,8 @@
+# `stream/promises` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/stream-promises.md)
+
+实现位置：`src/extensions/node/stream-promises/index.ts`、`runtime/ext_node/stream/pipeline.c`
+
+- `pipeline(...)` 同步排空给定流，并返回一个已 resolve 的 Promise，因此 `await pipeline(...)` 可用。
+- 支持的转换阶段为 `zlib.createGzip()`，见 [`zlib`](./zlib.md)。

package/doc/zh-CN/implemented/node/stream.md

@@ -0,0 +1,15 @@
+# `stream` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/stream.md)
+
+实现位置：`src/extensions/node/stream/index.ts`、`runtime/ext_node/stream/stream.c`
+
+`Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough` 作为**全局构造函数**使用（`new Readable()` 等）；`stream.Readable.from(...)` 等静态方法通过 `stream` 命名空间解析。流是 EventEmitter，采用**同步事件模型**：`on('data')` 时冲刷 `push` 缓冲，`write` 即时投递。
+
+| 方法 | 说明 |
+| --- | --- |
+| `push(chunk)` / `read([n])` | Readable 端 |
+| `write(chunk)` / `end([chunk])` | Writable 端 |
+| `pipe(destination)` | 数据转发 |
+| `on('data' / 'end' / 'finish')` | 事件 |
+| `pause()` / `resume()` / `setEncoding(enc)` / `destroy()` | 流控制 |

package/doc/zh-CN/implemented/node/test.md

@@ -0,0 +1,10 @@
+# `test` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/test.md)
+
+实现位置：`src/extensions/node/test/index.ts`、`runtime/ext_node/test/test.c`
+
+- `test(name, fn)` 立即执行 `fn`，捕获断言失败并输出 TAP。
+- `it` / `describe` / `skip` / `todo` / `only` 以及 `before` / `after` / `beforeEach` / `afterEach` 钩子。
+- 失败时进程以非零码退出。
+- 默认导出可调用，因此 `import test from "node:test"` 可用。

package/doc/zh-CN/implemented/node/url.md

@@ -0,0 +1,8 @@
+# `url` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/url.md)
+
+实现位置：`src/extensions/node/url/index.ts`、`runtime/ext_node/url/url.c`
+
+- `pathToFileURL(path)` 与 `fileURLToPath(url)`。
+- 这两个助手用于在 `import.meta.url`、`process.argv[1]` 与文件系统路径之间转换。

package/doc/zh-CN/implemented/node/util.md

@@ -0,0 +1,25 @@
+# `util` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/util.md)
+
+位置：`src/extensions/node/util/index.ts`、`runtime/ext_node/util/util.c`
+
+同时支持命名导入（`import { format } from "util"`）与命名空间调用
+（`import util from "util"` / `import * as util from "util"`）。
+
+| 函数 | 说明 |
+| --- | --- |
+| `format(fmt, ...args)` | 支持 `%s` `%d` `%i` `%f` `%j` `%o` `%O` `%c` `%%` 占位符 |
+| `formatWithOptions(opts, fmt, ...args)` | 接受选项但忽略 |
+| `inspect(value)` | 递归打印（限制深度，字符串带引号） |
+| `isDeepStrictEqual(a, b)` | 结构比较（`NaN` 等于 `NaN`） |
+| `inherits(ctor, superCtor)` | 连接原型链 |
+| `deprecate(fn, msg)` | 原样返回 `fn`（没有告警通道） |
+| `promisify(fn)` | 把「回调在末尾」的函数包装为 `Promise` |
+| `isString` `isNumber` `isBoolean` `isUndefined` `isNull` `isFunction` `isArray` `isObject` `isBuffer` `isDate` `isRegExp` `isPromise` `isError` | 类型判断 |
+
+```ts
+import { format, promisify } from "util";
+
+console.log(format("%s=%d", "n", 3)); // n=3
+```

package/doc/zh-CN/implemented/node/worker-threads.md

@@ -0,0 +1,9 @@
+# `worker_threads` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/worker-threads.md)
+
+实现位置：`src/extensions/node/worker_threads/index.ts`、`runtime/ext_node/worker_threads/worker_threads.c`
+
+- `Worker`、`isMainThread`、`workerData`、`parentPort`。
+- xbintsc 通过把当前可执行文件作为子进程重新运行来模拟 worker；`isMainThread` /
+  `workerData` / `parentPort` 是值绑定（无参运行时 getter），`Worker` 是构造器。

package/doc/zh-CN/implemented/node/zlib.md

@@ -0,0 +1,8 @@
+# `zlib` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/zlib.md)
+
+实现位置：`src/extensions/node/zlib/index.ts`、`runtime/ext_node/zlib/zlib.c`
+
+- 仅实现 `createGzip()`。它返回 gzip 转换流，供
+  [`stream/promises`](./stream-promises.md) 的 `pipeline` 使用。